# 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.