feat: release Office Tools 0.1.0

public/docs/ARCHITECTURE.md

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