feat: release Office Tools 0.1.0

2026-08-31 22:37:01 +02:00
commit a5524e27e3
90 changed files with 16328 additions and 0 deletions
@@ -0,0 +1,15 @@
+# Accessibility
+
+Office Tools uses semantic controls, visible focus, keyboard-operable file
+selection and the shared Toolbox light/dark/system preference. The main content
+width is `min(100%, 90rem)` and layouts collapse without horizontal page
+overflow on narrow screens.
+
+Viewer adapters should preserve meaningful headings, paragraphs, lists and table
+semantics where the source exposes them. Spreadsheet grids need labelled row and
+column headers plus a non-visual cell description. Presentation navigation needs
+an announced slide position and a linear text alternative for each slide.
+
+Colour alone must not communicate selection, errors or diagnostics. Animations
+respect `prefers-reduced-motion`. Imported images use source alternative text
+when available and an explicit fallback when it is absent.
@@ -0,0 +1,44 @@
+# Architecture
+
+Office Tools is a static React application with four deliberately separated
+layers:
+
+1. The Toolbox shell owns navigation, application identity, theme preferences,
+   help and source links.
+2. The ingestion boundary checks extension and source size; each parser then
+   validates package identity from its contents and enforces resource limits.
+3. Format adapters convert office packages into one application-owned,
+   read-only document model.
+4. Viewer components render that model as document pages, spreadsheet sheets or
+   presentation slides without trusting imported markup.
+
+The original file is immutable. Opening a new file cancels obsolete work and
+releases prior buffers and object URLs. Expensive parsing belongs in a module
+worker so the shell stays responsive and cancellation has a clear boundary.
+
+Office Open XML input uses the pinned `@silurus/ooxml` Rust/WebAssembly parser
+and Canvas renderer. OpenDocument input uses project-owned TypeScript adapters
+over `fflate` and `@xmldom/xmldom`; it is not routed through an online converter.
+The adapters share detection, size-policy and diagnostics contracts while
+retaining their intentionally different rendering paths.
+
+The OpenDocument module worker verifies central and local ZIP declarations,
+normalized paths, CRC and expansion limits before namespace-aware XML parsing.
+It rejects DTDs, entities, external resources and active XML, and returns only a
+typed, serializable model plus transferable packaged image buffers.
+
+## Deployment contract
+
+Vite emits relative URLs (`base: './'`). `toolbox-app.json` sits beside
+`index.html`, and the application works with or without a same-origin Toolbox
+catalogue. `toolbox-check dist` verifies manifest identity, files and nested-path
+operation. The service worker handles requests only inside its own scope.
+
+## Rendering contract
+
+The OpenDocument model records source kind, ordered blocks/sheets/slides, text
+runs, whitelisted style data, tables, local images, notes and diagnostics. ODS
+keeps source repeats compressed, trims office-suite full-grid tails and renders
+at most 200 rows per page and 256 columns. Adapters emit warnings for omitted
+embedded objects and other approximations. Source markup is never inserted as
+HTML, formulas are never evaluated, and document URLs are never fetched.
@@ -0,0 +1,47 @@
+# Format support
+
+Office Tools 0.1.0 targets read-only browser viewing, not editing or
+pixel-identical reproduction.
+
+| Family                       | Extensions | 0.1 viewing coverage                                                                                           |
+| ---------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------- |
+| Office Open XML document     | `.docx`    | Paginated sections, text, lists, tables, images, shapes, charts, headers/footers, comments, selection and find |
+| Office Open XML spreadsheet  | `.xlsx`    | Sheets, cached values/formulas, styles, merges, frozen panes, images, charts, comments, navigation and find    |
+| Office Open XML presentation | `.pptx`    | Slides/masters, text, shapes, images, tables, charts, notes, selection, navigation and find                    |
+| OpenDocument text            | `.odt`     | Semantic headings, paragraphs/runs, lists, tables, packaged images, metadata and foot/endnotes                 |
+| OpenDocument spreadsheet     | `.ods`     | Sheets, typed/cached values, formulas, repeats, merges, annotations, basic safe styling and paged rows         |
+| OpenDocument presentation    | `.odp`     | Slide order, positioned text/shapes, groups, tables, packaged images, notes and basic safe styling             |
+
+Legacy compound-binary `.doc`, `.xls` and `.ppt` formats are explicitly outside
+the first package-reader slice. They require a distinct, bounded parser and must
+not be misidentified as their XML successors.
+
+## Never executed
+
+Macros, VBA projects, embedded executables, OLE objects, scripts, remote
+templates and automatic external relationships remain inert. Unsupported
+content is reported in diagnostics where it can be identified.
+
+## Known boundaries
+
+- Spreadsheet formulas display their saved cached result; Office Tools does not
+  recalculate them or refresh pivots and external data.
+- Presentation animations and transitions are not reproduced. Embedded media
+  playback is disabled in the first release.
+- OLE, ActiveX, VBA and OpenDocument embedded objects remain inert. The ODF
+  semantic view reports and omits embedded objects such as chart subdocuments.
+- OpenDocument slide masters/layouts are identified but not fully reproduced;
+  uncommon drawing transforms and office-suite-specific layout can be
+  approximated.
+- Fonts are substituted locally. Remote fonts, templates, images and links are
+  never fetched.
+- ODS renders 200 rows at a time and up to 256 columns. Empty full-grid tails
+  emitted by office suites are deliberately trimmed.
+
+## Safety limits
+
+The source-file limit is 100 MiB. OOXML and ODF packages also enforce expanded
+entry, total expanded byte, entry-count and image limits. ODF additionally
+bounds compression ratio, XML depth/nodes, text, repeats, cells and assets.
+Files that exceed a boundary fail with a visible diagnostic instead of being
+partially trusted.
@@ -0,0 +1,36 @@
+# Privacy and security model
+
+## Local processing
+
+Selecting a file grants the current browser tab access to that file's bytes.
+Office Tools does not upload them, send telemetry or fetch a remote conversion
+service. Data remains in memory unless a future feature explicitly offers a
+user-triggered local download or browser-local save.
+
+## Threat model
+
+The input may be hostile: a ZIP bomb, path traversal, deeply nested XML,
+oversized text, misleading MIME information, malformed relationships or active
+content disguised as media. Readers therefore need limits for compressed and
+expanded bytes, entry count, XML depth, node count, repeated elements, image
+dimensions and rendered output.
+
+Package paths are normalized as OPC/ODF paths and may never escape the logical
+package root. External relationships and document links are not fetched or made
+active. Imported HTML is never trusted. Macros, scripts, OLE objects and
+embedded executables are never run. OpenDocument embedded objects are retained
+only as inert package bytes and reported as omitted from the semantic view.
+
+The ODF reader rejects ambiguous or traversing names, unsupported/encrypted ZIP
+features, inconsistent headers, overlap, CRC errors, unsafe expansion, DTDs,
+entities and active XML. It applies byte, entry, ratio, node, depth, repeat,
+text, cell and image limits inside a disposable worker. OOXML readers likewise
+run with explicit package/resource limits and external links and Google Fonts
+disabled.
+
+## Browser limits
+
+Local processing is not the same as zero risk: a large document can still cause
+memory pressure, and rendering depends on the browser's image and font engines.
+The application should remain cancellable, keep the previous stable UI until a
+new parse succeeds, and release resources promptly when a file closes.