102 lines
4.3 KiB
Markdown
102 lines
4.3 KiB
Markdown
# OneNote Tools
|
|
|
|
OneNote Tools is a standalone, local-first browser reader for a tested subset
|
|
of Microsoft OneNote `.one` sections and CAB-based `.onepkg` packages. The
|
|
parser is native TypeScript, runs in a dedicated module worker, and never
|
|
uploads or persists the selected notebook.
|
|
|
|
It is also an independent application in the add·ideas Toolbox contract: the
|
|
source uses the Toolbox SDK shell and manifest, builds with Vite `base: './'`,
|
|
and is delivered to Toolbox Portal as an already-built, checksummed static ZIP.
|
|
|
|
## What version 0.1.0 can open
|
|
|
|
- Desktop revision-store `.one` sections from the tested OneNote family. The
|
|
reader exposes section/page names, stable page IDs, created and updated
|
|
timestamps when present, page level, and readable plain text.
|
|
- Unfragmented FSSHTTPB-packaged `.one` sections matching the tested Joplin
|
|
family. Package cells, revision chains, object groups, and resolved object
|
|
and page-space references feed the same bounded content reader.
|
|
- Single-cabinet `.onepkg` files whose CAB folders are uncompressed, MSZIP,
|
|
Quantum, or LZX compressed. Each contained supported `.one` section is
|
|
parsed independently, so one unsupported section does not hide sections that
|
|
did parse.
|
|
- Package entries, safe normalized paths, uncompressed sizes, compression
|
|
metadata, section/page navigation, and structured diagnostics.
|
|
|
|
The golden tests parse a real Joplin desktop `.one` file with three pages, an
|
|
unfragmented 17,197-byte Joplin FSSHTTPB `.one` file with one page, and a real
|
|
Joplin `.onepkg` with seven entries, five sections, and seven pages. LZX
|
|
`0x1203` and `0x1303`, uncompressed CAB, one- and two-block MSZIP data, and
|
|
single- and multi-frame Quantum data are covered by fixtures. The MSZIP and
|
|
Quantum fixtures are CAB-level evidence, not a claim about a particular
|
|
OneNote `.onepkg` producer.
|
|
|
|
This is a structural reader, not a full-fidelity OneNote renderer. Images,
|
|
tables, ink, embedded files, layout, formatting, links, and exports are not
|
|
rendered. Fragmented FSSHTTPB data elements and some producer variants remain
|
|
unsupported. See
|
|
[format support](docs/FORMAT_SUPPORT.md) for the precise matrix.
|
|
|
|
There is no Rust/Wasm runtime, server, proxy, upload, telemetry, or notebook
|
|
storage. All parsing and CAB/LZX/MSZIP/Quantum decompression is ordinary
|
|
browser JavaScript produced from the TypeScript source.
|
|
|
|
## Use
|
|
|
|
Run the static build or open it through Toolbox Portal, then drop or choose one
|
|
local `.one` or `.onepkg` file. Use **Clear file** to terminate the current
|
|
worker and release application references. Browser garbage collection does not
|
|
provide a secure-erasure guarantee.
|
|
|
|
## Development
|
|
|
|
Node.js 22 or newer is required. The checked-in `.npmrc` contains only the
|
|
public package registry mapping and no credential.
|
|
|
|
```sh
|
|
npm ci
|
|
npm run dev
|
|
npm run check
|
|
```
|
|
|
|
`npm run check` validates manifest synchronization, TypeScript, ESLint,
|
|
Prettier, fixture-backed Vitest tests, the production build, and
|
|
`toolbox-check dist`.
|
|
|
|
The application works standalone. A same-origin Toolbox catalogue can be
|
|
supplied through the SDK's `?toolbox=` context mechanism. The app uses the SDK
|
|
`AppShell` and does not add a second suite-level switcher.
|
|
|
|
## Release artifact
|
|
|
|
```sh
|
|
npm run release:artifact
|
|
(cd release && sha256sum -c onenote-tools-0.1.0.sha256)
|
|
```
|
|
|
|
The ZIP root contains the built static app and manifest plus the changelog,
|
|
corresponding-source information, security/support/provenance documents, and
|
|
the required project and third-party licence texts. File order and ZIP
|
|
timestamps are fixed. Existing artifacts are not overwritten unless `--force`
|
|
is passed after `--`.
|
|
|
|
Toolbox Portal expands the reviewed ZIP below an `apps/<target>/` path and
|
|
locks its exact SHA-256. It does not build this repository or import this app
|
|
into the portal React tree.
|
|
|
|
## Design and provenance
|
|
|
|
- [Format support](docs/FORMAT_SUPPORT.md)
|
|
- [Security model and active limits](docs/SECURITY.md)
|
|
- [Pinned references and normative specifications](docs/REFERENCE_IMPLEMENTATIONS.md)
|
|
- [Port provenance](docs/PORTING.md)
|
|
- [Fixture provenance](tests/fixtures/README.md)
|
|
|
|
## Licence
|
|
|
|
OneNote Tools is licensed under MPL-2.0. The complete licence is in
|
|
[`LICENSES/MPL-2.0.txt`](LICENSES/MPL-2.0.txt). Adapted and third-party material
|
|
remains under the terms recorded in
|
|
[`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md).
|