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