Compiler Guide
The 0.2 release boundary and the separately verified private compiler experiment
Proto UI 0.2 does not ship a Compiler implementation or a Compiler authoring workflow. There is no @proto.ui/compiler package, compiler entity type, official compiler profile, CLI compile command, or supported compiler input/output artifact in the 0.2 release.
Release support and repository experiments are separate. The private experiment described below does not change the 0.2 package, catalog, CLI, or official-support boundary.
Prerequisites
Section titled “Prerequisites”Read Chapter 5: Translation Layer for the conceptual distinction, Core for portable syntax, and Runtime Architecture for the current execution path.
What 0.2 actually ships
Section titled “What 0.2 actually ships”| Layer | Current responsibility |
|---|---|
@proto.ui/core | Prototype definition, setup/render syntax, template structures, module declarations, Rule authoring types |
@proto.ui/runtime | Materialize a Prototype, run Modules, own lifecycle/update flow, hand commits to a host |
| Official Adapters | Translate Runtime output and semantic host capabilities for Web Component, React, and Vue profiles |
@proto.ui/cli | Initialize projects and generate themes, tokens, styles, and component preset material; it is not a Prototype compiler |
The current production route is therefore:
Prototype TypeScript → Runtime execution → official Adapter → Web hostA Compiler route was not shipped in 0.2:
portable analyzable input → [future Compiler] → host artifactsNothing in 0.2 promises the second route’s accepted source language, optimization model, generated files, runtime footprint, or compatibility policy.
Constraints that already apply
Section titled “Constraints that already apply”Even without a Compiler package, cataloged protocol boundaries constrain any future official translation:
K-PROTOTYPE-COMPOSITION-0001: templates describe one Root Node; they do not embed another Prototype definition.C-TEMPLATE-0005: the v0 slot is anonymous, singular, and parameterless.C-TEMPLATE-0006: an official Adapter or Compiler encounteringPrototypeRefas a template node must reject it rather than inventing private composition.C-RULE-0003: Rule declarations produce serializableRuleIRwithout functions, host references, closures, or live handles.C-MODULE-DECLARATION-0001: static typed Module declarations are available before Module construction and potential host selection.
These are protocol constraints, not a Compiler SPI. They do not specify a parser, AST format, incremental build graph, code generator, or deployment artifact.
Static intent versus arbitrary functions
Section titled “Static intent versus arbitrary functions”Some authoring forms preserve more analyzable intent than callbacks. Rule is the clearest current example: it separates condition from semantic intent and compiles internally to RuleIR for Runtime evaluation. That does not mean the repository has a general Prototype compiler, nor that arbitrary callback bodies can be translated losslessly.
Use declarative forms when they accurately express behavior, but do not rewrite working 0.2 semantics around an imagined compiler. internal/contracts/integration/portability-and-integration.md discusses this longer-term direction as explanatory, non-normative material.
No supported Compiler inputs or outputs in 0.2
Section titled “No supported Compiler inputs or outputs in 0.2”| Question | 0.2 answer |
|---|---|
Can a .proto.ts file be compiled without Runtime? | No supported workflow |
Is TemplateChildren a stable compiler IR? | No; it is current Core/Runtime template data |
Is RuleIR a complete Prototype IR? | No; it covers Rule only |
| Can CLI emit React/Vue/Custom Element components from a Prototype? | No |
| Is zero-runtime delivery supported? | No; it remains future direction |
| Is there a Compiler conformance matrix? | No Compiler entity/profile exists |
If a future proposal needs one of these answers to change, it requires explicit catalog and API work rather than documentation inference.
Private repository compiler experiment
Section titled “Private repository compiler experiment”packages/compiler is an implemented private experiment, not an official Compiler distribution. Its manifest retains private: true and protoUi.release.scan: false. The private compiler CLI is separate from the published proto-ui CLI; publication, catalog admission and maintained compatibility require their own approval.
Current-main browser boundary and website inventory
Section titled “Current-main browser boundary and website inventory”At current main 7181a93a5ec5cad43936a72e31d5477d5488733a, the browser-host prototype associated with PR #829 is absent: there is no current browser export, VM host, memory entry, browser build or WASM regression in the compiler package. PR #829’s source landed on a feature branch, not this main revision; its browser code and dependencies are historical evidence, not current delivery.
Issue #817 remains open. The website demo inventory is source-AST discovery plus canonical private Node compileFile admission only. It records mounted pages, static registrations, source-located rejections and unresolved bindings; it does not execute WASM, run a compiler preview, migrate a page or establish browser isolation, security, performance, full parity or a public Compiler. Historical #829 inventory rows—including rejected rows—remain dated evidence and reconciliation obligations, never new passes.
Regenerate the inventory with node --import tsx scripts/compiler/website-demo-inventory.mjs. The generator retains the complete immutable historical input in scripts/compiler/website-demo-migrations-829.json, verifies its SHA-256, and writes internal/compiler/website-demo-migrations.json. Current input membership (including hidden scoped source files), bytes, installed parser dependency closure, HEAD/index provenance and dirty worktree bindings are recorded separately. Changed, missing or newly added inputs invalidate the binding; unresolved or dynamic source addresses remain visible rather than becoming successful admissions.
Implemented profiles and compatibility
Section titled “Implemented profiles and compatibility”| Private profile | Exercised target | Output dependency boundary |
|---|---|---|
react-runtime-v1 | React / React DOM 19.2.6 | Retains Proto UI Core, Hooks and React Adapter; not Runtime-independent |
react-dom-source-v1 | React / React DOM 19.2.6 | Target framework plus emitted native helpers; no Proto UI Runtime/Adapter |
vue-source-v1 | Vue 3.5.31 | Target framework plus emitted native helpers; no Proto UI Runtime/Adapter |
vue2-source-v1 | Vue 2.6.14 | Target framework plus emitted native helpers; no Proto UI Runtime/Adapter |
web-component-source-v1 | Custom Elements v1 | Emitted native helpers; no framework or Proto UI Runtime/Adapter dependency |
gpui-source-v1 | GPUI pinned to Git revision 62e5991dd0f0c8a3af8d5e7e9c4652490d468db8 | GPUI plus an emitted shared Rust support crate; no Proto UI Runtime/Adapter dependency |
Qt, Flutter and the four SSR profile identities are unimplemented and reject registry-based compilation. The existing direct emitter ssr: true entry points remain private experiments; exercising them does not activate an SSR profile or establish SSR/hydration conformance. GPUI remains a private source profile, not a cataloged official Adapter or a complete native conformance claim. A profile’s concrete tested target version is not a compatibility promise for other versions. Restricted source admission, semantic IR version 7, target profile identity and emitted Web helper ABI 1 are separate private compatibility dimensions; neither IR nor helper files are a public plugin SPI.
The GPUI source owner interprets void setup as the defined anonymous slot inside its host Root (C-CORE-SYNTAX-0004-C, C-TEMPLATE-0001). A pure author definition with State and a public increment method was compiled without Web globals and exercised in a real headless GPUI window. The same generated component admitted two native slot children in order, preserved their measured boxes across the method call, and exposed the State change from 0 to 1. This bounded evidence does not establish OS-visible rendering, assistive-technology fidelity or full compiler/Prototype equivalence. Missing native style declarations are diagnosed rather than replaced with Web behavior.
The frontend reads a closed, root-contained TypeScript source graph without importing or evaluating the author program. It admits checked data, primitive/control-flow callbacks, static helpers and authored hooks, explicit updates, named State and typed exposes, Props and Context reads/watchers, one-Root templates, serializable Rule conditions and style intent, and the declared native event/focus/accessibility slice. Unsupported syntax, phase/capture authority, operations, target versions and missing host capabilities are diagnostics, not silent bridges.
Public atomic hook imports and operation lowering use one admission table. Every exported asHook has an explicit disposition, including renamed imports and local re-exports. asControlLabel is admitted and lowered in the four implemented Web client source profiles. It retains explicit unsupported diagnostics for GPUI and the direct Qt/Flutter and default SSR entries; the private Web Component hydration experiment separately requires its explicit controlLabelHydration: 'client-only' option. asAxisInput, asContextMenuInput and asNativeLink remain unsupported, with a diagnostic naming the missing capability lowering at the author import. Admission of another hook does not admit every method or every target: an unsupported capability call names its actual callee and source range. These diagnostics do not establish implementation or conformance for an unsupported capability.
Static helper parameters may use supported local record aliases with optional fields and finite literal unions. A direct literal argument such as { entry: 'manual' } retains its value when checked against that parameter; incompatible literal values and forged IR are still rejected. The source frontend and IR validator apply the same data compatibility rule without evaluating author code.
Private scalar let bindings have ordinary lexical lifetime and assignment semantics. Closures share their storage, while a const alias snapshots the current scalar value. A write schedules no render and sends no State notification. JavaScript targets use native let; GPUI retains captured cells with native reference ownership and ends each borrow before calling authored code. Pure scalar module initializers and reached named source helpers preserve a separate module lifetime across component instances. Helpers resolve their defining module’s bindings; caller-local names cannot supply their captures. Module cells belong to one generated artifact (and the UI thread for GPUI); separately compiled artifacts do not acquire a shared source-module registry. Source graph, export and top-level execution checks remain closed, and compilation never executes an initializer or an uncalled function body.
Private synchronous try/catch/finally and throw retain the original admitted thrown data, including undefined, null, false, zero, empty strings and record/array identity. Catch bindings stay opaque: a TypeScript assertion grants no public data, State or execution authority. An authored finalizer runs in source order, and its return or throw replaces the earlier authored completion. GPUI requires panic=unwind for emitted source exceptions and recognizes only its own thrown-value marker; unrelated native failures retain their original payload after cleanup. Caught data fields and scalar/list members are available, while JavaScript prototype property names remain outside this bounded GPUI access surface.
Context failure delivery preserves each committed update, drains the remaining eligible callbacks, resets dispatch state, then rethrows the primary authored value even when it is falsy. Required disconnected Context reads/updates and strict missing Anatomy domains retain distinguishable error codes for authored catch discrimination. These source-lowering boundaries do not establish new native acceptance or replace the unchanged actual public GPUI composition consumer.
The generated Web Context helper records the provider identity for each queued transition and rechecks the recipient’s current ancestry before delivery. Rebinding during an earlier callback cannot deliver an old provider’s queued transition to the new binding. Error presence is tracked separately from the thrown value, so throw undefined and throw null remain failures and later callback errors cannot replace the first value.
This lexical lowering leaves the ordinary defineHook facade’s admission unresolved. D-AS-HOOK-DEFINE-HOOK-0001 places its capture, store and configurable authoring surface outside the core authored-asHook contract; the legacy parameterized-asHook note remains a proposal. The existing ordinary facade and its public consumers remain valid implementation evidence. Compiler support needs an independently governed boundary and real consumer evidence. An import whitelist or substitution with an atomic or authored asHook does not supply that support.
Native templates keep child style separate from Root feedback and support the singular anonymous slot. Arbitrary attributes, PrototypeRef, multiple/named slots, native interaction groups/portals and operations outside the admitted interaction vocabulary remain unsupported. Raw host events are opaque; raw Props snapshots are available, but arbitrary raw-member access is not treated as typed portable data. The setup style unUse and Rule declaration disposer stay setup-only; runtime changes use Rules and run.feedback.style.patch/suppress/clearPatch.
State writes and feedback projection do not themselves request a template render. Explicit authored update intent remains separate from host policy: React/Vue 3 consumers exercise authored updates; the default Vue 2 props policy and Custom Element setProps can explicitly request semantic updates. View detach retains instance state, exposed handles, Context and pending intent; terminal disposal closes them. Framework wrappers compose components through their native ownership mechanisms, not Prototype nodes embedded in templates.
In the private Vue 2 client profile, ordinary framework repaints retain the last authored commit while native slots stay live. A declared Text Control owns its native editor value after the initial mount. Uncontrolled edits survive framework repaints and later default-value changes; controlled edits remain proposals, and unrelated updates preserve active composition. Recreating the view binds a new physical editor to the retained logical value. These boundaries do not establish browser IME fidelity, internal SSR/hydration migration, complete generated typing for every admitted program, or full reached-support and production-cost acceptance; those remain separately tracked in #1055.
The private Vue 2 emitter keeps client render-call annotations inside the client branch. SSR output retains its separate renderer path; the bounded annotation regression checks preserve all other SSR diagnostics and do not establish complete SSR typing or hydration acceptance.
The complete generated Vue 2 pointer consumer and its supporting module graph now pass the existing strict TypeScript check with checkJs: true and skipLibCheck: false. The emitter registers exact owned/observed State handles with their external views and validates the interactive HTML Root before using it. This is bounded evidence for the exercised client program; the historical consumer measurement below still did not check JavaScript bodies, and complete typing for other programs and SSR remains separate work.
Multi-entry native Web output
Section titled “Multi-entry native Web output”Components that share a source Context declaration need one generated module graph. The private project API can compile all entries from one source root and publish their sources and shared supporting modules together:
import { compileProject, writeProjectCompilation } from './packages/compiler/src/index.ts';
const compiled = await compileProject({ root: '.', entries: ['src/provider.proto.ts', 'src/consumer.proto.ts'], profile: 'react-dom-source-v1',});if (!compiled.ok) throw new Error(JSON.stringify(compiled.diagnostics));
const written = await writeProjectCompilation(compiled.value, '.cache/context-assembly', { sourcePaths: { 'src/provider.proto.ts': 'Provider.tsx', 'src/consumer.proto.ts': 'Consumer.tsx', },});if (!written.ok) throw new Error(JSON.stringify(written.diagnostics));Choose a fresh output directory and a unique flat source filename for every entry. React uses .tsx, Vue 3 and Web Component use .ts, and Vue 2 uses .js. The planner coalesces supporting files only when their paths, kinds and bytes agree; conflicting helpers, mismatched source snapshots, ambiguous paths and incomplete entry mappings fail before publication. Each entry retains its source map and provenance manifest, and provenance.json records the complete project artifact set. projectCompilationArtifacts exposes the same plan and diffProjectCompilation compares it with consumer-owned output without writing.
An ordinary React consumer can import CompiledComponent as Provider from Provider.tsx and CompiledComponent as Consumer from Consumer.tsx. Both then import the same physical Context key, scope and React transport modules, retaining source declaration reference identity through native composition. Independently published directories remain separate graphs even when their source bytes and debug names match. This workflow does not introduce a shared source-module registry, bridge Runtime/Adapter instances, or change the single-entry CLI. The React consumer regression exercises aliases, nearest providers, explicit updates and terminal cleanup; the artifact planner is also exercised for the other three Web source profiles.
Local commands and consumer ownership
Section titled “Local commands and consumer ownership”Run from the repository root with its development dependencies installed. Choose a fresh output directory:
node --import tsx packages/compiler/src/cli-entry.ts check packages/prototypes/base/src/button/button.proto.ts --root . --profile react-dom-source-v1node --import tsx packages/compiler/src/cli-entry.ts compile packages/prototypes/base/src/button/button.proto.ts --root . --profile react-dom-source-v1 --output .cache/compiler-guide-buttonnode --import tsx packages/compiler/src/cli-entry.ts diff packages/prototypes/base/src/button/button.proto.ts --root . --profile react-dom-source-v1 --output .cache/compiler-guide-button --jsonnode --import tsx packages/compiler/src/cli-entry.ts watch packages/prototypes/base/src/button/button.proto.ts --root . --profile react-dom-source-v1 --output .cache/compiler-guide-watch --jsoninspect prints checked IR; explain reports the profile, requirements and dependencies. --config explicitly selects JSON with entry, root, export, output, profile and json; configuration paths are relative to that file, command-line paths to the working directory. Command-line values override configuration, and unknown/repeated flags or fields fail.
Compilation plans source, supporting helpers, standard source maps and hash/provenance manifests before create-only publication. Existing consumer files are never overwritten. diff is read-only and identifies consumer modifications against recorded hashes. watch publishes immutable <output>/<session UUID>/revision-<N> generations, retaining the last successful generation on rejected input; it does not maintain a mutable latest pointer. Consumer edits require a normal target rebuild. The original compiler map remains historical and can be stale after an edit; a rebuild supplies the current executable-to-edited-source map.
Executed evidence and measured costs
Section titled “Executed evidence and measured costs”The private verification runs compile and mount three-component/Context assemblies in physically isolated consumers for all four Web source profiles, type-check generated TypeScript and helpers, rebuild and execute a consumer-owned template edit, reject an introduced syntax error, and verify the physical dependency tree and artifact hashes. These Web consumer measurements do not exercise GPUI. Vue 2 JavaScript component bodies are not checkJs-validated. A separate offline private-package rehearsal executes the bundled compiler JavaScript API in plain Node and records tarball integrity, bundled compile-time inputs, dependencies, BOM and licenses; this is not an official package or public declaration-file release.
Real Chromium evidence independently checks the original React Adapter, runtime-backed output and native React output for explicit update/detach/reattach contracts and a finite Rule/style/AX/input program. Missing-update and duplicate-activation mutants fail those observations. Separate real failing generated callback stacks resolve through standard executable-to-generated and generated-to-author maps; automatic map composition is not claimed.
Replay the isolated native consumer measurement with:
node --import tsx scripts/compiler/native-consumer-smoke.mjsEach run retains summary.json, timing.json, costs.json, runtime traces, diagnostics and dependency integrity in its printed evidence directory. Measurements cover cold/hot/changed compilation, whole-process peak RSS and coarse memory snapshots, emitted/supporting source and dependency payload bytes, real framework initialization/update/teardown, retained handle identity and observed instance/view-epoch/Root counts. They do not measure exact allocation counts, garbage collection, native-browser layout latency or Adapter-relative speed. Happy DOM consumers are one-sided evidence; the finite Chromium program is not general equivalence, SSR/hydration support or a claim that compiled output is universally faster or smaller.
Contribution boundary
Section titled “Contribution boundary”A Compiler proposal begins as Agent-led governed research. Research, candidate entities, implementation probes, and executable evidence may proceed immediately; only product choices not decided by current authority become an attended decision. The proposal must identify at least:
- the portable source subset and how unsupported constructs fail;
- the output host and ownership of generated artifacts;
- semantic parity with existing Contract criteria;
- lifecycle, capability, and component-composition treatment;
- a versioned identity and executable conformance model; and
- migration and coexistence with the Runtime/Adapter path.
Do not open an implementation PR by treating packages/modules/rule/src/compile.ts, CLI style generation, or a bundler transform as the missing Compiler architecture. Those are bounded implementations with different owners.
Verification of the current boundary
Section titled “Verification of the current boundary”The following checks exercise the portable template and analyzable Rule constraints that exist today:
corepack pnpm@10.32.1 vitest run packages/core/test/contract/template.normalize.contract.test.tscorepack pnpm@10.32.1 vitest run packages/adapters/web-component/test/contract/template.no-prototype-composition.v0.contract.test.tscorepack pnpm@10.32.1 vitest run packages/runtime/test/contract/rule.props-style.smoke.v0.contract.test.tscorepack pnpm@10.32.1 check:typesFor work that can ship now, continue to Runtime Architecture, Module & Extension Architecture, or the bounded Adapter Guide. For future sequencing, see Roadmap.