Architecture

Compiler 1.0.0 implements this pipeline in Python with a bundled browser runtime. See IMPLEMENTATION.md for backend constraints and SYNTAX.md for accepted notation.

Pipeline

Source text
    -> tokenizer and parser
    -> syntax tree
    -> imports, aliases, and symbol resolution
    -> type and component validation
    -> component expansion
    -> target-independent document model
    -> HTML, CSS, assets, and controlled runtime
    -> interactive web document or paged PDF rendering

Python modules

The package is currently organized by responsibility:

• parser.py, values.py — block/inline parsing, typed values, and bounded expressions.
• model.py, semantics.py — syntax/document nodes, names, imports, types, and expansion.
• components.py — component schemas and standard component definitions.
• styles.py, graphics.py — layout styles, SVG drawing, charts, diagrams, and molecular structures.
• renderer.py, compiler.py — semantic HTML, styles, controlled runtime configuration, and output bundles.
• export.py — local Chromium PDF rendering with external requests blocked.
• assets.py, packages.py — root-constrained resources and portable source bundles.
• diagnostics.py — errors, warnings, source locations, and hints.
• cli.py, lsp.py, formatter.py — commands, live preview, editor protocol, and conservative formatting.

Browser measurement, named flows, constraints, logical page numbers, and Paged.js orchestration live in static/runtime.js. Shared styling lives in static/base.css; pinned browser dependencies and fonts are in static/vendor/.

Rendering principle

Web and PDF should share the same generated HTML, CSS, fonts, assets, and layout rules wherever possible. PDF export should use the paged representation rather than an independent drawing implementation. Target-specific differences must be explicit and testable.

Determinism

Source bundles are deterministic and carry content checksums. HTML builds record source and asset hashes. Browser libraries and fonts are bundled locally. PDF visual reproducibility requires the same Chromium version, platform, fonts, and profile; byte-identical PDF output is not promised because the PDF backend may include changing metadata.

Testing strategy

The test suite includes:

• Parser, expression, type, component, and invalid-document cases.
• Custom-component, include, source-root, and source-bundle checks.
• Browser geometry, repeated furniture, page masters, footnotes, and numbering checks.
• Flow content preservation, overflow failures, and constraint placement.
• Mobile reflow, accessible control labels, interactions, and offline 3D rotation.
• PDF page dimensions, text, links, tags, and static media fallbacks.

PDF pages are also rendered to images and manually reviewed in output/playwright/. There is not yet an automated pixel-baseline comparison suite, exhaustive accessibility audit, or cross-engine compatibility matrix.