Compiler 指南
0.2 release 边界与分别验证的私有 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 架构理解当前执行路径。
0.2 实际交付的内容
Section titled “0.2 实际交付的内容”| 层 | 当前职责 |
|---|---|
@proto.ui/core | Prototype definition、setup/render syntax、template structure、module declaration、Rule authoring type |
@proto.ui/runtime | 物化 Prototype、运行 Module、拥有 lifecycle/update flow、把 commit 交给 host |
| 官方 Adapter | 为 Web Component、React 与 Vue profile 翻译 Runtime output 和 semantic host capability |
@proto.ui/cli | 初始化项目并生成 theme、token、style 与 component preset material;它不是 Prototype compiler |
当前 production route 是:
Prototype TypeScript → Runtime execution → official Adapter → Web host0.2 没有交付 Compiler 路径:
portable analyzable input → [future Compiler] → host artifacts0.2 不承诺第二条路径接受什么 source language、如何优化、生成哪些文件、是否包含 runtime 或采用什么 compatibility policy。
已经适用的约束
Section titled “已经适用的约束”即使没有 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 遇到PrototypeReftemplate node 时必须拒绝,不能私自发明 composition。C-RULE-0003:Rule declaration 生成 serializableRuleIR,其中不保留 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。
Static intent 与任意 function
Section titled “Static intent 与任意 function”有些作者形式比 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。
0.2 没有受支持的 Compiler input/output
Section titled “0.2 没有受支持的 Compiler input/output”| 问题 | 0.2 回答 |
|---|---|
.proto.ts 能否脱离 Runtime 编译? | 没有受支持流程 |
TemplateChildren 是稳定 compiler IR 吗? | 不是;它是当前 Core/Runtime template data |
RuleIR 是完整 Prototype IR 吗? | 不是;它只覆盖 Rule |
| CLI 能否从 Prototype 生成 React/Vue/Custom Element component? | 不能 |
| 是否支持 zero-runtime delivery? | 不支持,仍属未来方向 |
| 是否有 Compiler conformance matrix? | 没有 Compiler entity/profile |
如果未来 proposal 要改变这些回答,必须显式新增 catalog 与 API 工作,不能从文档推断。
仓库内的私有 Compiler 实验
Section titled “仓库内的私有 Compiler 实验”packages/compiler 是已实现的私有实验,不是 official Compiler distribution。Manifest 保持 private: true 与 protoUi.release.scan: false。私有 Compiler CLI 与已发布的 proto-ui CLI 分开;publication、catalog admission 和长期 compatibility 需要各自的批准。
当前 main 的浏览器边界与网站 inventory
Section titled “当前 main 的浏览器边界与网站 inventory”在当前 main 7181a93a5ec5cad43936a72e31d5477d5488733a 中,与 PR #829 相关的 browser-host prototype 不存在:compiler package 没有当前 browser export、VM host、memory entry、browser build 或 WASM regression。PR #829 的源码进入的是 feature branch,不是这一 main revision;其 browser code 和 dependencies 属于历史证据,不是当前交付。
Issue #817 仍保持 open。网站 demo inventory 只做 source-AST discovery 与 canonical private Node compileFile admission。它记录已挂载页面、静态 registration、source-located rejection 和 unresolved binding;它不会执行 WASM、运行 compiler preview、迁移页面,也不证明 browser isolation、security、performance、full parity 或 public Compiler。历史 #829 inventory 的各行(包括 rejection)继续作为带日期的 evidence 与 reconciliation obligation 保留,绝不是新的 pass。
使用 node --import tsx scripts/compiler/website-demo-inventory.mjs 重新生成 inventory。Generator 在 scripts/compiler/website-demo-migrations-829.json 保留完整 immutable historical input,核对其 SHA-256,并输出 internal/compiler/website-demo-migrations.json。当前 input membership(包括范围内隐藏 source file)、bytes、已安装 parser dependency closure、HEAD/index provenance 与 dirty worktree binding 分别记录。修改、缺失或新增 input 会使原 binding 失效;unresolved 或 dynamic source address 继续显式保留,不会变成成功 admission。
已实现 profile 与 compatibility
Section titled “已实现 profile 与 compatibility”| 私有 profile | 实际运行的 target | Output dependency 边界 |
|---|---|---|
react-runtime-v1 | React / React DOM 19.2.6 | 保留 Proto UI Core、Hooks 与 React Adapter;不独立于 Runtime |
react-dom-source-v1 | React / React DOM 19.2.6 | Target framework 加生成的 native helper;不依赖 Proto UI Runtime/Adapter |
vue-source-v1 | Vue 3.5.31 | Target framework 加生成的 native helper;不依赖 Proto UI Runtime/Adapter |
vue2-source-v1 | Vue 2.6.14 | Target framework 加生成的 native helper;不依赖 Proto UI Runtime/Adapter |
web-component-source-v1 | Custom Elements v1 | 生成的 native helper;不依赖 framework 或 Proto UI Runtime/Adapter |
gpui-source-v1 | 固定 Git revision 62e5991dd0f0c8a3af8d5e7e9c4652490d468db8 的 GPUI | GPUI 加生成的共享 Rust support crate;不依赖 Proto UI Runtime/Adapter |
Qt、Flutter 与四个 SSR profile identity 尚未实现,通过 registry 选择它们会拒绝编译。现有 direct emitter 的 ssr: true 入口仍是私有实验;执行这些入口不激活 SSR profile,也不建立 SSR/hydration conformance。GPUI 仍是私有 source profile,不是已编目的 official Adapter,也不代表完整 native conformance。实际测试的 target version 不构成对其他版本的 compatibility 承诺。Restricted source admission、semantic IR version 7、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。
公开 atomic hook 的 import 校验与 operation lowering 复用同一 admission table。每个导出的 asHook 都有明确分类,改名 import 与本地 re-export 使用相同规则。asControlLabel 已准入,并在四个已实现的 Web client source profile 中完成 lowering;GPUI、direct Qt/Flutter 与默认 SSR 入口继续给出明确的 unsupported diagnostic。私有 Web Component hydration 实验另须显式选择 controlLabelHydration: 'client-only'。asAxisInput、asContextMenuInput、asNativeLink 仍不支持,diagnostic 在作者 import 处说明缺少哪项 capability lowering。其他 hook 获得准入,也不表示其每个 method 或每个 target 都已支持:不支持的 capability call 会带上实际 callee 与 source range。这些 diagnostic 不构成缺失 capability 的实现或 conformance 证据。
Static helper 参数可使用已支持的 local record alias,包括 optional field 与有限 literal union。直接传入 { entry: 'manual' } 这类字面量时,会保留其具体值来核对参数类型;不兼容的 literal value 与伪造 IR 仍会被拒绝。Source frontend 与 IR validator 复用同一 data compatibility 规则,不执行作者代码。
私有 scalar let 保留普通词法 lifetime 与 assignment semantics。Closure 共享其 storage,const alias 则保存读取当时的 scalar snapshot;写入不会请求 render,也不发送 State notification。JavaScript target 使用原生 let;GPUI 以 native reference ownership 保留被捕获的 cell,并在调用作者代码前结束每一次 borrow。纯 scalar module initializer 与实际到达的具名 source helper 保留跨 component instance 的 module lifetime。Helper 的 capture 来自定义它的 module,不能由 caller-local 同名变量补足。Module cell 属于单个 generated artifact(GPUI 中还限定 UI thread);单独编译的 artifact 不会自动获得共享 source-module registry。Source graph、export 与 top-level execution 继续受闭图检查约束,编译不会执行 initializer 或未调用的 function body。
私有同步 try/catch/finally 与 throw 保留原始的已准入 thrown data,包括 undefined、null、false、零、空字符串,以及 record/array identity。Catch binding 始终 opaque:TypeScript assertion 不授予 public data、State 或 execution authority。作者的 finalizer 按 source order 执行,其 return 或 throw 替换先前的 authored completion。GPUI 对生成的 source exception 要求 panic=unwind,且仅识别自身的 thrown-value marker;无关 native failure 在 cleanup 后保留原始 payload。可读取 caught data field 与 scalar/list member;JavaScript prototype property name 仍不在这项有界 GPUI access surface 内。
Context failure delivery 保留已提交的每次 update,完成其余仍有效的 callback、重置 dispatch state,再抛出 primary authored value;即使该值为 falsy,也不会被当作成功。Required Context 断连 read/update 与 strict Anatomy 缺少 domain 的失败保留可区分的 error code,供作者 catch 判别。这些 source-lowering 边界不构成新的 native acceptance,也不替代未改动的真实公共 GPUI composition consumer。
生成的 Web Context helper 为每个排队 transition 记录 provider identity,并在 delivery 前重新检查接收者的当前 ancestry。前一个 callback 导致 rebind 后,旧 provider 的排队 transition 不会送入新 binding。错误是否发生与 thrown value 分开记录,因此 throw undefined 和 throw null 仍是失败,后续 callback 的错误也不会替换第一个值。
这项词法 lowering 保留普通 defineHook facade 的准入缺口。D-AS-HOOK-DEFINE-HOOK-0001 将其 capture、store 与 configurable authoring surface 留在核心 authored-asHook 契约之外;旧 parameterized-asHook note 仍为 proposal。现有普通 facade 及其公共 consumer 是有效 implementation evidence。Compiler 支持仍需独立治理的边界与真实 consumer evidence;仅添加 import whitelist,或替换为 atomic/authored asHook,不能建立这项支持。
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。
私有 Vue 2 client profile 的普通 framework repaint 保留上次 authored commit,同时让 native slot 保持实时。已声明的 Text Control 在首次 mount 后拥有原生 editor value:非受控编辑不会被 framework repaint 或后续 defaultValue 变化重置;受控编辑仍只是 proposal,无关更新保留正在进行的 composition。重新创建 view 时,新的物理 editor 绑定到保留的 logical value。这些边界不代表浏览器 IME fidelity、内部 SSR/hydration 迁移、所有准入程序的完整生成类型、完整 reached-support 或 production cost 已通过验收;这些工作仍在 #1055 分别追踪。
私有 Vue 2 emitter 仅在 client 分支生成 client render-call 注释。SSR 输出保留独立的 renderer 路径;有界的注释回归检查保留其余全部 SSR diagnostic,不代表完整 SSR typing 或 hydration 已通过验收。
完整生成的 Vue 2 pointer consumer 及其 supporting module graph 现已通过原有 strict TypeScript 检查,保留 checkJs: true 与 skipLibCheck: false。Emitter 将精确的 owned/observed State handle 注册到对应 external view,并在使用 interactive Root 前验证它确为 HTML element。这份证据限定于实际执行的 client 程序;下文历史 consumer measurement 仍未检查 JavaScript body,其他程序与 SSR 的完整类型验收仍需独立完成。
多入口 native Web 产物
Section titled “多入口 native Web 产物”共享同一个 source Context declaration 的 component 需要使用同一个生成模块图。私有 project API 可以从同一 source root 编译所有 entry,并一起发布组件 source 与共享 supporting module:
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));选择未使用的 output directory,并为每个 entry 指定唯一、平铺的 source filename。React 使用 .tsx,Vue 3 与 Web Component 使用 .ts,Vue 2 使用 .js。Planner 只合并 path、kind 和字节完全一致的 supporting file;helper 冲突、source snapshot 不一致、路径歧义或 entry 映射不完整都在发布前拒绝。每个 entry 保留 source map 与 provenance manifest,provenance.json 记录整个 project artifact set。projectCompilationArtifacts 返回相同的产物规划,diffProjectCompilation 只读比较 consumer-owned output。
普通 React consumer 可以从 Provider.tsx 导入 CompiledComponent as Provider,从 Consumer.tsx 导入 CompiledComponent as Consumer。二者由此 import 同一组物理 Context key、scope 与 React transport module,通过 native composition 保留 source declaration 的引用身份。独立发布的目录仍是独立模块图,即使 source 字节与 debug name 相同。这条路径不引入共享 source-module registry、不桥接 Runtime/Adapter instance,也不改变单入口 CLI。React consumer 回归覆盖 alias、nearest provider、显式 update 与 terminal cleanup;artifact planner 同时覆盖其余三个 Web source profile。
本地命令与 consumer ownership
Section titled “本地命令与 consumer ownership”在安装了 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-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 输出 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。
已执行证据与成本测量
Section titled “已执行证据与成本测量”私有验证在四个 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 至少说明:
- portable source subset,以及 unsupported construct 如何失败;
- output host 与 generated artifact ownership;
- 如何与现有 Contract criteria 保持 semantic parity;
- lifecycle、capability 与 component composition 如何处理;
- versioned identity 与 executable conformance model;
- 如何迁移并与 Runtime/Adapter path 共存。
不要把 packages/modules/rule/src/compile.ts、CLI style generation 或 bundler transform 当成缺失的 Compiler architecture 并直接发起实现 PR;它们是由其他层拥有的局部实现。
验证当前边界
Section titled “验证当前边界”以下检查覆盖今天已经存在的 portable template 与 analyzable Rule 约束:
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:types希望现在就能交付的工作,请继续阅读 Runtime 架构、模块与扩展架构或边界明确的 Adapter 指南;未来顺序见里程碑。