feat: introduce local-first SVG workbench

2026-08-02 16:31:49 +02:00
commit 39d9802daa
97 changed files with 20702 additions and 0 deletions
@@ -0,0 +1,53 @@
+# Architecture
+
+## Boundaries
+
+SVG Tools is a static Vite application. React owns controls and projections,
+not the document. Canonical SVG source is the only persistent document
+representation. Normal sessions stay in memory; explicit downloads are the
+only persistence boundary.
+
+```text
+canonical source
+  ├─ ranged XML scan + DOM parse → semantic document → tree/inspectors
+  ├─ security policy + DOMPurify → editing projection → opaque iframe
+  └─ source patches/transactions ← visual commands and explicit workflows
+```
+
+The last valid semantic document and projection remain available while current
+source is invalid. Revision checks reject stale visual, worker or dialog results.
+
+## Representations
+
+1. **Source document:** exact user text, including comments, quotes and
+   whitespace.
+2. **Semantic document:** SVG elements, attributes, source ranges, in-memory
+   keys, relationships, preferences, metrics and diagnostics.
+3. **Editing projection:** cloned, sanitized SVG with temporary mapping
+   attributes. It is never exported as current SVG.
+4. **Preview:** the projection in a sandboxed opaque-origin iframe, plus a
+   parent-owned overlay for bounds and path controls.
+
+Imported source is never rendered through React or inserted into the main DOM.
+The iframe controller is a fixed packaged asset, accepts only its parent and a
+random per-instance channel, and removes its script element after startup.
+
+## Commands and workers
+
+Every accepted edit is a transaction containing exact before/after source,
+patches, selection and revision. Undo validates the current source before
+restoring exact text. Fast consecutive source/key nudge edits may merge under a
+bounded merge key.
+
+SVGO executes in a dedicated module worker. Jobs have IDs, timeout,
+supersession, AbortSignal cancellation and immediate deterministic rejection.
+Parsing currently uses bounded synchronous browser XML facilities because its
+`XMLDocument` projection is not transferable; large inputs are throttled and
+hard-limited. Rasterization uses a sanitized Blob URL and Canvas 2D.
+
+## Release boundary
+
+`base: './'` keeps every asset relocatable. The independent ZIP is built and
+checked here. Toolbox Portal consumes the immutable ZIP and checksum through a
+release lock; it never compiles SVG Tools source. AppShell reads optional
+Toolbox context but standalone operation is the default fallback.