svg-tools/docs/ARCHITECTURE.md

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.

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.