Compiler 指南

Proto UI 0.2 没有交付 Compiler 实现或 Compiler authoring workflow。0.2 release 中不存在 @proto.ui/compiler package、compiler entity type、official compiler profile、CLI compile command 或受支持的 compiler input/output artifact。

Release support 与仓库实验分开。下文的私有实验不改变 0.2 package、catalog、CLI 或 official-support 边界。

先读第五章：翻译层理解概念差异，读核心规范理解 portable syntax，再读 Runtime 架构理解当前执行路径。

当前 production route 是：

Prototype TypeScript → Runtime execution → official Adapter → Web host

0.2 没有交付 Compiler 路径：

portable analyzable input → [future Compiler] → host artifacts

0.2 不承诺第二条路径接受什么 source language、如何优化、生成哪些文件、是否包含 runtime 或采用什么 compatibility policy。

即使没有 Compiler package，已经编目的协议边界仍会约束任何未来 official translation：

• K-PROTOTYPE-COMPOSITION-0001：template 描述一个 Root Node，不嵌入另一个 Prototype definition。
• C-TEMPLATE-0005：v0 slot 是 anonymous、singular、parameterless。
• C-TEMPLATE-0006：official Adapter 或 Compiler 遇到 PrototypeRef template node 时必须拒绝，不能私自发明 composition。
• C-RULE-0003：Rule declaration 生成 serializable RuleIR，其中不保留 function、host reference、closure 或 live handle。
• C-MODULE-DECLARATION-0001：static typed Module declaration 在 Module construction 和潜在 host selection 之前可见。

这些是协议约束，不是 Compiler SPI；它们没有定义 parser、AST format、incremental build graph、code generator 或 deployment artifact。

有些作者形式比 callback 更能保留可分析 intent。Rule 是当前最清楚的例子：它把 condition 与 semantic intent 分开，并在内部编译为 RuleIR 供 Runtime evaluation。这不代表仓库已经有通用 Prototype compiler，也不意味着任意 callback body 都可以无损翻译。

当 declarative form 能准确表达行为时应优先使用，但不要围绕想象中的 Compiler 改写已经成立的 0.2 semantics。internal/contracts/integration/portability-and-integration.md 对长期方向有更多解释，但它属于 non-normative material。

如果未来 proposal 要改变这些回答，必须显式新增 catalog 与 API 工作，不能从文档推断。

packages/compiler 是已实现的私有实验，不是 official Compiler distribution。Manifest 保持 private: true 与 protoUi.release.scan: false。私有 Compiler CLI 与已发布的 proto-ui CLI 分开；publication、catalog admission 和长期 compatibility 需要各自的批准。

Qt、Flutter profile identity 尚未实现，选择它们会拒绝编译。GPUI 仍是私有 source profile，不是已编目的 official Adapter，也不代表完整 native conformance。实际测试的 target version 不构成对其他版本的 compatibility 承诺。Restricted source admission、semantic IR version 5、target profile identity 与生成 Web helper ABI 1 是不同的私有 compatibility 维度；IR 和 helper 文件都不是 public plugin SPI。

GPUI source owner 按定义将 void setup 解释为 host Root 内部的匿名 slot（C-CORE-SYNTAX-0004-C、C-TEMPLATE-0001）。包含 State 和公开 increment method 的纯作者定义在没有 Web global 的环境中完成编译，并在真实 headless GPUI window 中运行。同一生成组件按顺序接入两个 native slot child，method 调用前后保留实际测得的布局框，并通过公开 State 观察到 0 到 1 的变化。这份有界证据不代表 OS-visible rendering、assistive-technology fidelity 或完整 compiler/Prototype equivalence；缺失 native style declaration 会生成 diagnostic，而不会替换成 Web 行为。

Frontend 读取限定 root 内的完整 TypeScript source graph，不 import 或 evaluate 作者程序。准入范围包括 checked data、primitive/control-flow callback、static helper 和 authored hook、显式 update、named State 与 typed expose、Props/Context read/watch、单 Root template、serializable Rule condition/style intent，以及已声明的 native event/focus/accessibility 切片。Unsupported syntax、phase/capture authority、operation、target version 和缺失 host capability 会生成 diagnostic，不会静默 bridge。

Native template 将 child style 与 Root feedback 分开，并支持 singular anonymous slot。任意 attribute、PrototypeRef、multiple/named slot、native interaction group/portal，以及准入 vocabulary 之外的 interaction operation 仍不支持。Raw host event 是 opaque；可读取 raw Props snapshot，但任意 raw member 不会冒充 typed portable data。Setup style 的 unUse 与 Rule declaration disposer 仍是 setup-only；runtime 变化使用 Rule 和 run.feedback.style.patch/suppress/clearPatch。

State write 与 feedback projection 本身不会请求 template render。作者显式 update intent 与 host policy 分开：React/Vue 3 consumer 执行 authored update；Vue 2 的默认 props policy 与 Custom Element setProps 可以显式请求 semantic update。View detach 保留 instance state、exposed handle、Context 与 pending intent；terminal disposal 才关闭它们。Framework wrapper 使用 native ownership 组合 component，而不是在 template 内嵌入 Prototype node。

在安装了 development dependencies 的仓库 root 执行，并选择未使用的 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-v1
node --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-button
node --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 --json
node --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 --json

inspect 输出 checked IR；explain 输出 profile、requirements 与 dependencies。--config 显式选择 JSON，字段限于 entry、root、export、output、profile、json；配置路径相对配置文件，命令行路径相对 working directory。命令行覆盖配置；unknown/repeated flag 或 field 会失败。

Compilation 先规划 source、supporting helper、standard source map 与 hash/provenance manifest，再 create-only 发布。现有 consumer file 从不被覆盖。diff 只读，通过记录的 hash 识别 consumer modification。watch 发布 immutable <output>/<session UUID>/revision-<N>，输入被拒绝时保留最后成功 generation，不维护可变 latest pointer。Consumer edit 使用普通 target rebuild；原 compiler map 是历史证据，编辑后可能 stale，rebuild 才生成当前 executable-to-edited-source map。

私有验证在四个 Web source profile 的独立物理 consumer 中编译、挂载三 component/Context assembly，type-check 生成的 TypeScript/helper，重建并执行 consumer-owned template edit，拒绝引入的 syntax error，并验证物理 dependency tree 与 artifact hash；这些 Web consumer 测量不执行 GPUI。Vue 2 的 JavaScript component body 不执行 checkJs。另有 offline private-package rehearsal，在普通 Node 中执行打包 Compiler 的 JavaScript API，并记录 tarball integrity、实际 bundled compile-time input、dependency、BOM 和 license；这不等于 official package 或 public declaration-file release。

真实 Chromium 分别核对原 React Adapter、runtime-backed output 与 native React output 的 explicit update/detach/reattach，以及有限 Rule/style/AX/input 程序。Missing-update 与 duplicate-activation mutant 被实际观察拒绝。独立的生成 callback 真实错误堆栈通过 standard executable-to-generated、generated-to-author 两段 map 精确定位；不宣称自动 map composition。

重放独立 native consumer 测量：

node --import tsx scripts/compiler/native-consumer-smoke.mjs

每次执行在输出的 evidence directory 中保留 summary.json、timing.json、costs.json、runtime trace、diagnostic 与 dependency integrity。测量包括 cold/hot/changed compilation、whole-process peak RSS 与 coarse memory snapshot、生成/supporting source 和 dependency payload byte、真实 framework initialization/update/teardown、retained handle identity，以及观察到的 instance/view-epoch/Root count。没有测量 exact allocation、garbage collection、native-browser layout latency 或相对 Adapter 的速度。Happy DOM consumer 是单边证据；有限 Chromium 程序不构成普遍等价、SSR/hydration 支持或编译产物必然更快/更小的承诺。

Compiler proposal 从 Agent-led governed research 开始。research、candidate entity、实现探针与 executable evidence 可以立即推进；只有现有 authority 未决定的产品选择才形成 attended decision。proposal 至少说明：

1. portable source subset，以及 unsupported construct 如何失败；
2. output host 与 generated artifact ownership；
3. 如何与现有 Contract criteria 保持 semantic parity；
4. lifecycle、capability 与 component composition 如何处理；
5. versioned identity 与 executable conformance model；
6. 如何迁移并与 Runtime/Adapter path 共存。

不要把 packages/modules/rule/src/compile.ts、CLI style generation 或 bundler transform 当成缺失的 Compiler architecture 并直接发起实现 PR；它们是由其他层拥有的局部实现。

以下检查覆盖今天已经存在的 portable template 与 analyzable Rule 约束：

corepack pnpm@10.32.1 vitest run packages/core/test/contract/template.normalize.contract.test.ts
corepack pnpm@10.32.1 vitest run packages/adapters/web-component/test/contract/template.no-prototype-composition.v0.contract.test.ts
corepack pnpm@10.32.1 vitest run packages/runtime/test/contract/rule.props-style.smoke.v0.contract.test.ts
corepack pnpm@10.32.1 check:types

希望现在就能交付的工作，请继续阅读 Runtime 架构、模块与扩展架构或边界明确的 Adapter 指南；未来顺序见里程碑。