label-tools/docs/ARCHITECTURE.md

Architecture

The sheet engine keeps all physical geometry in millimetres and converts only at the editor boundary. Alongside the fixed address, badge and asset layouts, labels/template.ts validates a reusable v1 element model for draggable text, image, barcode and shape elements. Merge expressions are fixed {{field}} lookups; they never evaluate code. Bounds include an explicit bleed allowance, and barcode elements report format-specific quiet-zone and minimum-size risks.

SVG pages use physical dimensions and application-owned escaped markup. PDF export walks that generated markup into pdf-lib vector paths, rectangles and embedded standard-font text; local PNG/JPEG assets remain image objects. No page-wide rasterization is used. Unsupported WebP embedding remains visible in SVG and is omitted from PDF rather than fetched or executed.

Label Tools separates untrusted input from rendering:

1. labels/data.ts uses toolbox helpers for bounded CSV/JSON parsing and the browser cryptographic RNG for optional virtual fields.
2. labels/stocks.ts stores canonical millimetre geometry and validates every preset/custom grid before rendering.
3. labels/render.ts maps scalar fields into three fixed layouts or the validated designer model, escapes XML, embeds validated local raster data, and places reviewed bwip-js output.
4. labels/export.ts exports exact SVG pages, deterministic fflate ZIPs, or vector pdf-lib documents assembled from application-owned SVG markup.

The React workbench retains the last valid data model after parse errors and limits interactive preview to the first 12 pages. Complete SVG export remains available for all bounded rows. The shared toolbox shell owns theme and portal navigation; all app URLs are relative for nested deployment.