@llui/compiler-introspection 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Franco Ponticelli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/binding-descriptors.d.ts

@@ -0,0 +1,5 @@
+import { BINDING_DESCRIPTORS_SLOT } from '@llui/compiler';
+import type { CompilerModule } from '@llui/compiler';
+export { BINDING_DESCRIPTORS_SLOT };
+export declare const bindingDescriptorsModule: CompilerModule;
+//# sourceMappingURL=binding-descriptors.d.ts.map

package/dist/binding-descriptors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"binding-descriptors.d.ts","sourceRoot":"","sources":["../src/binding-descriptors.ts"],"names":[],"mappings":"AAyBA,OAAO,EAGL,wBAAwB,EAEzB,MAAM,gBAAgB,CAAA;AACvB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAEpD,OAAO,EAAE,wBAAwB,EAAE,CAAA;AAEnC,eAAO,MAAM,wBAAwB,EAAE,cAuBtC,CAAA"}

package/dist/binding-descriptors.js

@@ -0,0 +1,48 @@
+// `binding-descriptors` — agent-runtime hook tagging. Pre-transform
+// CompilerModule wrapping `tagDispatchHandlers` + `injectScopeVariantRegistrations`.
+//
+// Both functions mutate the AST in ways the visitor model can't
+// cleanly express:
+//   - `tagDispatchHandlers`: walks every arrow/fn expression, wraps
+//     those whose body contains `send({type:'X'})` with
+//     `Object.assign(arrow, {__lluiVariants: ['X']})`. The visitor
+//     pattern records findings but doesn't rewrite; rewriting is what
+//     this pass does.
+//   - `injectScopeVariantRegistrations`: walks for `*.connect(get,
+//     send, ...)` call sites and inserts `__registerScopeVariants([...])`
+//     adjacent statements. The visitor pattern can't insert siblings
+//     into the source file at arbitrary positions.
+//
+// Both are pre-passes — they produce a rewritten SourceFile that the
+// main visitor walks. v2c §2.1's "walker runs once per file" invariant
+// is preserved: the VISITOR walk runs once. preTransform passes are
+// additional but typically cheap and targeted.
+//
+// The `injected` flag from `injectScopeVariantRegistrations` is
+// surfaced via a shared analysis slot — the umbrella's
+// `cleanupImports` reads it to know whether to add the
+// `__registerScopeVariants` runtime helper to the @llui/dom imports.
+import { tagDispatchHandlers, injectScopeVariantRegistrations, BINDING_DESCRIPTORS_SLOT, } from '@llui/compiler';
+export { BINDING_DESCRIPTORS_SLOT };
+export const bindingDescriptorsModule = {
+    name: 'binding-descriptors',
+    compilerVersion: '^0.3.0',
+    diagnostics: [],
+    visitors: {},
+    preTransform(ctx, sf) {
+        // injectScopeVariantRegistrations runs FIRST so its
+        // `collectLocalFns` resolver still sees raw arrow initializers in
+        // const declarations (the universal tagger below replaces those
+        // initializers with `Object.assign(...)` wrappers).
+        const injection = injectScopeVariantRegistrations(sf, ctx.factory);
+        const tagged = tagDispatchHandlers(injection.sf, ctx.factory);
+        // Surface the injected flag for the umbrella's cleanupImports
+        // pass. The umbrella reads this from `analysis.perModule` after
+        // `registry.run()` returns.
+        ctx.analysis.perModule.set(BINDING_DESCRIPTORS_SLOT, {
+            scopeRegistrationsInjected: injection.injected,
+        });
+        return tagged;
+    },
+};
+//# sourceMappingURL=binding-descriptors.js.map

package/dist/binding-descriptors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"binding-descriptors.js","sourceRoot":"","sources":["../src/binding-descriptors.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,qFAAqF;AACrF,EAAE;AACF,gEAAgE;AAChE,mBAAmB;AACnB,oEAAoE;AACpE,wDAAwD;AACxD,mEAAmE;AACnE,sEAAsE;AACtE,sBAAsB;AACtB,mEAAmE;AACnE,0EAA0E;AAC1E,qEAAqE;AACrE,mDAAmD;AACnD,EAAE;AACF,qEAAqE;AACrE,uEAAuE;AACvE,oEAAoE;AACpE,+CAA+C;AAC/C,EAAE;AACF,gEAAgE;AAChE,uDAAuD;AACvD,uDAAuD;AACvD,qEAAqE;AAErE,OAAO,EACL,mBAAmB,EACnB,+BAA+B,EAC/B,wBAAwB,GAEzB,MAAM,gBAAgB,CAAA;AAGvB,OAAO,EAAE,wBAAwB,EAAE,CAAA;AAEnC,MAAM,CAAC,MAAM,wBAAwB,GAAmB;IACtD,IAAI,EAAE,qBAAqB;IAC3B,eAAe,EAAE,QAAQ;IACzB,WAAW,EAAE,EAAE;IACf,QAAQ,EAAE,EAAE;IAEZ,YAAY,CAAC,GAAG,EAAE,EAAE;QAClB,oDAAoD;QACpD,kEAAkE;QAClE,gEAAgE;QAChE,oDAAoD;QACpD,MAAM,SAAS,GAAG,+BAA+B,CAAC,EAAE,EAAE,GAAG,CAAC,OAAO,CAAC,CAAA;QAClE,MAAM,MAAM,GAAG,mBAAmB,CAAC,SAAS,CAAC,EAAE,EAAE,GAAG,CAAC,OAAO,CAAC,CAAA;QAE7D,8DAA8D;QAC9D,gEAAgE;QAChE,4BAA4B;QAC5B,GAAG,CAAC,QAAQ,CAAC,SAAS,CAAC,GAAG,CAAC,wBAAwB,EAAE;YACnD,0BAA0B,EAAE,SAAS,CAAC,QAAQ;SACrB,CAAC,CAAA;QAE5B,OAAO,MAAM,CAAA;IACf,CAAC;CACF,CAAA","sourcesContent":["// `binding-descriptors` — agent-runtime hook tagging. Pre-transform\n// CompilerModule wrapping `tagDispatchHandlers` + `injectScopeVariantRegistrations`.\n//\n// Both functions mutate the AST in ways the visitor model can't\n// cleanly express:\n//   - `tagDispatchHandlers`: walks every arrow/fn expression, wraps\n//     those whose body contains `send({type:'X'})` with\n//     `Object.assign(arrow, {__lluiVariants: ['X']})`. The visitor\n//     pattern records findings but doesn't rewrite; rewriting is what\n//     this pass does.\n//   - `injectScopeVariantRegistrations`: walks for `*.connect(get,\n//     send, ...)` call sites and inserts `__registerScopeVariants([...])`\n//     adjacent statements. The visitor pattern can't insert siblings\n//     into the source file at arbitrary positions.\n//\n// Both are pre-passes — they produce a rewritten SourceFile that the\n// main visitor walks. v2c §2.1's \"walker runs once per file\" invariant\n// is preserved: the VISITOR walk runs once. preTransform passes are\n// additional but typically cheap and targeted.\n//\n// The `injected` flag from `injectScopeVariantRegistrations` is\n// surfaced via a shared analysis slot — the umbrella's\n// `cleanupImports` reads it to know whether to add the\n// `__registerScopeVariants` runtime helper to the @llui/dom imports.\n\nimport {\n  tagDispatchHandlers,\n  injectScopeVariantRegistrations,\n  BINDING_DESCRIPTORS_SLOT,\n  type BindingDescriptorsSlot,\n} from '@llui/compiler'\nimport type { CompilerModule } from '@llui/compiler'\n\nexport { BINDING_DESCRIPTORS_SLOT }\n\nexport const bindingDescriptorsModule: CompilerModule = {\n  name: 'binding-descriptors',\n  compilerVersion: '^0.3.0',\n  diagnostics: [],\n  visitors: {},\n\n  preTransform(ctx, sf) {\n    // injectScopeVariantRegistrations runs FIRST so its\n    // `collectLocalFns` resolver still sees raw arrow initializers in\n    // const declarations (the universal tagger below replaces those\n    // initializers with `Object.assign(...)` wrappers).\n    const injection = injectScopeVariantRegistrations(sf, ctx.factory)\n    const tagged = tagDispatchHandlers(injection.sf, ctx.factory)\n\n    // Surface the injected flag for the umbrella's cleanupImports\n    // pass. The umbrella reads this from `analysis.perModule` after\n    // `registry.run()` returns.\n    ctx.analysis.perModule.set(BINDING_DESCRIPTORS_SLOT, {\n      scopeRegistrationsInjected: injection.injected,\n    } as BindingDescriptorsSlot)\n\n    return tagged\n  },\n}\n"]}

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+import { type IntrospectionFactory } from '@llui/compiler';
+import { msgSchemaModule, type MsgSchemaModuleOptions } from './msg-schema.js';
+import { stateSchemaModule, type StateSchemaModuleOptions } from './state-schema.js';
+import { msgAnnotationsModule, type MsgAnnotationsModuleOptions } from './msg-annotations.js';
+import { schemaHashModule, SCHEMA_HASH_INPUTS_SLOT, type SchemaHashInputs } from './schema-hash.js';
+import { bindingDescriptorsModule, BINDING_DESCRIPTORS_SLOT } from './binding-descriptors.js';
+export { msgSchemaModule, type MsgSchemaModuleOptions, stateSchemaModule, type StateSchemaModuleOptions, msgAnnotationsModule, type MsgAnnotationsModuleOptions, schemaHashModule, SCHEMA_HASH_INPUTS_SLOT, type SchemaHashInputs, bindingDescriptorsModule, BINDING_DESCRIPTORS_SLOT, };
+/**
+ * Builds the introspection module set for a single source file.
+ * Activation order matches the v2c/decomp-7 design:
+ *   1. `bindingDescriptorsModule`  — preTransform fires first so the
+ *      universal handler-tagger + scope-variant-registration runs
+ *      before any visitor or emit phase sees the file.
+ *   2. `msgSchemaModule`, `stateSchemaModule`, `msgAnnotationsModule`
+ *      — producer modules populate the schema-hash inputs slot.
+ *   3. `schemaHashModule` — emit reads the populated slot.
+ *
+ * Per-module activation gates mirror what `transformLlui` did inline
+ * before decomp-26:
+ *   - `msgSchemaModule`     when at least one of Msg / Effect schemas extracted
+ *   - `stateSchemaModule`   when State schema extracted
+ *   - `msgAnnotationsModule` when annotation map non-null (includes empty)
+ *   - `schemaHashModule`    always (well-defined hash over null inputs)
+ *   - `bindingDescriptorsModule` always when introspection is on
+ *
+ * The "always-on schemaHash" comes from spec §7.4: the hash ships in
+ * prod too, used by HMR re-send gating regardless of agent mode.
+ */
+export declare const introspectionFactory: IntrospectionFactory;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,KAAK,oBAAoB,EAAuC,MAAM,gBAAgB,CAAA;AAC/F,OAAO,EAAE,eAAe,EAAE,KAAK,sBAAsB,EAAE,MAAM,iBAAiB,CAAA;AAC9E,OAAO,EAAE,iBAAiB,EAAE,KAAK,wBAAwB,EAAE,MAAM,mBAAmB,CAAA;AACpF,OAAO,EAAE,oBAAoB,EAAE,KAAK,2BAA2B,EAAE,MAAM,sBAAsB,CAAA;AAC7F,OAAO,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AACnG,OAAO,EAAE,wBAAwB,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAA;AAK7F,OAAO,EACL,eAAe,EACf,KAAK,sBAAsB,EAC3B,iBAAiB,EACjB,KAAK,wBAAwB,EAC7B,oBAAoB,EACpB,KAAK,2BAA2B,EAChC,gBAAgB,EAChB,uBAAuB,EACvB,KAAK,gBAAgB,EACrB,wBAAwB,EACxB,wBAAwB,GACzB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,oBAAoB,EAAE,oBAqClC,CAAA"}

package/dist/index.js

@@ -0,0 +1,86 @@
+// @llui/compiler-introspection — runtime introspection metadata (opt-in).
+//
+// Emits the compile-time metadata that downstream runtime
+// introspectors consume: the end-user-facing `@llui/agent-bridge`
+// (in-app agent) and the dev-facing `@llui/mcp` (dev LLM tooling).
+// Both reads the same compiled output; this package owns the
+// emission side, the runtime packages own the consumption side.
+//
+// Modules:
+//   - msg-schema             __msgSchema + __effectSchema
+//   - msg-annotations        __msgAnnotations
+//   - state-schema           __stateSchema
+//   - schema-hash            __schemaHash (HMR re-send gating)
+//   - binding-descriptors    preTransform pass tagging handler
+//                            arrows with __lluiVariants
+//
+// Activation: opt-in. The package registers a factory with
+// `@llui/compiler` via `registerIntrospectionFactory`. The host
+// (test setup, Vite plugin, MCP) imports this package and calls
+// `registerIntrospectionFactory(introspectionFactory)` once at
+// process start. transformLlui then activates the modules when
+// `shouldEmitAgentMetadata` is true.
+import {} from '@llui/compiler';
+import { msgSchemaModule } from './msg-schema.js';
+import { stateSchemaModule } from './state-schema.js';
+import { msgAnnotationsModule } from './msg-annotations.js';
+import { schemaHashModule, SCHEMA_HASH_INPUTS_SLOT } from './schema-hash.js';
+import { bindingDescriptorsModule, BINDING_DESCRIPTORS_SLOT } from './binding-descriptors.js';
+// Re-export individual modules + slots so adapters that want fine-
+// grained control (e.g. a test that wants only schemaHash) can still
+// reach them. The default consumption path is the factory below.
+export { msgSchemaModule, stateSchemaModule, msgAnnotationsModule, schemaHashModule, SCHEMA_HASH_INPUTS_SLOT, bindingDescriptorsModule, BINDING_DESCRIPTORS_SLOT, };
+/**
+ * Builds the introspection module set for a single source file.
+ * Activation order matches the v2c/decomp-7 design:
+ *   1. `bindingDescriptorsModule`  — preTransform fires first so the
+ *      universal handler-tagger + scope-variant-registration runs
+ *      before any visitor or emit phase sees the file.
+ *   2. `msgSchemaModule`, `stateSchemaModule`, `msgAnnotationsModule`
+ *      — producer modules populate the schema-hash inputs slot.
+ *   3. `schemaHashModule` — emit reads the populated slot.
+ *
+ * Per-module activation gates mirror what `transformLlui` did inline
+ * before decomp-26:
+ *   - `msgSchemaModule`     when at least one of Msg / Effect schemas extracted
+ *   - `stateSchemaModule`   when State schema extracted
+ *   - `msgAnnotationsModule` when annotation map non-null (includes empty)
+ *   - `schemaHashModule`    always (well-defined hash over null inputs)
+ *   - `bindingDescriptorsModule` always when introspection is on
+ *
+ * The "always-on schemaHash" comes from spec §7.4: the hash ships in
+ * prod too, used by HMR re-send gating regardless of agent mode.
+ */
+export const introspectionFactory = (input) => {
+    const modules = [];
+    // Agent-gated modules — only fire when shouldEmitAgentMetadata is true.
+    // binding-descriptors and the schema producers all emit metadata the
+    // end-user agent / dev MCP reads; out of agent mode they're dead weight.
+    if (input.shouldEmitAgentMetadata) {
+        // binding-descriptors fires FIRST (preTransform pass) so subsequent
+        // module visitors see the post-mutation source file.
+        modules.push(bindingDescriptorsModule);
+        // Producer modules — order matters: they populate the schema-hash
+        // inputs slot before schemaHashModule's emit consumes it.
+        const msgSchema = input.msgSchema;
+        const effectSchema = input.effectSchema;
+        if (msgSchema || effectSchema) {
+            modules.push(msgSchemaModule({ msgSchema, effectSchema }));
+        }
+        const stateSchema = input.stateSchema;
+        if (stateSchema) {
+            modules.push(stateSchemaModule({ stateSchema }));
+        }
+        const msgAnnotations = input.msgAnnotations;
+        if (msgAnnotations !== null) {
+            modules.push(msgAnnotationsModule({ msgAnnotations }));
+        }
+    }
+    // schemaHashModule registers UNCONDITIONALLY — hash is well-defined
+    // for null inputs (deterministic). HMR re-send gating consumes the
+    // hash in prod builds (spec §7.4) even when no other introspection
+    // metadata is emitted.
+    modules.push(schemaHashModule);
+    return modules;
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,EAAE;AACF,0DAA0D;AAC1D,kEAAkE;AAClE,mEAAmE;AACnE,6DAA6D;AAC7D,gEAAgE;AAChE,EAAE;AACF,WAAW;AACX,0DAA0D;AAC1D,8CAA8C;AAC9C,2CAA2C;AAC3C,+DAA+D;AAC/D,+DAA+D;AAC/D,wDAAwD;AACxD,EAAE;AACF,2DAA2D;AAC3D,gEAAgE;AAChE,gEAAgE;AAChE,+DAA+D;AAC/D,+DAA+D;AAC/D,qCAAqC;AAErC,OAAO,EAAkE,MAAM,gBAAgB,CAAA;AAC/F,OAAO,EAAE,eAAe,EAA+B,MAAM,iBAAiB,CAAA;AAC9E,OAAO,EAAE,iBAAiB,EAAiC,MAAM,mBAAmB,CAAA;AACpF,OAAO,EAAE,oBAAoB,EAAoC,MAAM,sBAAsB,CAAA;AAC7F,OAAO,EAAE,gBAAgB,EAAE,uBAAuB,EAAyB,MAAM,kBAAkB,CAAA;AACnG,OAAO,EAAE,wBAAwB,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAA;AAE7F,mEAAmE;AACnE,qEAAqE;AACrE,iEAAiE;AACjE,OAAO,EACL,eAAe,EAEf,iBAAiB,EAEjB,oBAAoB,EAEpB,gBAAgB,EAChB,uBAAuB,EAEvB,wBAAwB,EACxB,wBAAwB,GACzB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAyB,CAAC,KAAK,EAAE,EAAE;IAClE,MAAM,OAAO,GAAqB,EAAE,CAAA;IAEpC,wEAAwE;IACxE,qEAAqE;IACrE,yEAAyE;IACzE,IAAI,KAAK,CAAC,uBAAuB,EAAE,CAAC;QAClC,oEAAoE;QACpE,qDAAqD;QACrD,OAAO,CAAC,IAAI,CAAC,wBAAwB,CAAC,CAAA;QAEtC,kEAAkE;QAClE,0DAA0D;QAC1D,MAAM,SAAS,GAAG,KAAK,CAAC,SAA6B,CAAA;QACrD,MAAM,YAAY,GAAG,KAAK,CAAC,YAAgC,CAAA;QAC3D,IAAI,SAAS,IAAI,YAAY,EAAE,CAAC;YAC9B,OAAO,CAAC,IAAI,CAAC,eAAe,CAAC,EAAE,SAAS,EAAE,YAAY,EAAE,CAAC,CAAC,CAAA;QAC5D,CAAC;QACD,MAAM,WAAW,GAAG,KAAK,CAAC,WAAqE,CAAA;QAC/F,IAAI,WAAW,EAAE,CAAC;YAChB,OAAO,CAAC,IAAI,CAAC,iBAAiB,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,CAAA;QAClD,CAAC;QACD,MAAM,cAAc,GAAG,KAAK,CAAC,cAEP,CAAA;QACtB,IAAI,cAAc,KAAK,IAAI,EAAE,CAAC;YAC5B,OAAO,CAAC,IAAI,CAAC,oBAAoB,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC,CAAA;QACxD,CAAC;IACH,CAAC;IAED,oEAAoE;IACpE,mEAAmE;IACnE,mEAAmE;IACnE,uBAAuB;IACvB,OAAO,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAA;IAE9B,OAAO,OAAO,CAAA;AAChB,CAAC,CAAA","sourcesContent":["// @llui/compiler-introspection — runtime introspection metadata (opt-in).\n//\n// Emits the compile-time metadata that downstream runtime\n// introspectors consume: the end-user-facing `@llui/agent-bridge`\n// (in-app agent) and the dev-facing `@llui/mcp` (dev LLM tooling).\n// Both reads the same compiled output; this package owns the\n// emission side, the runtime packages own the consumption side.\n//\n// Modules:\n//   - msg-schema             __msgSchema + __effectSchema\n//   - msg-annotations        __msgAnnotations\n//   - state-schema           __stateSchema\n//   - schema-hash            __schemaHash (HMR re-send gating)\n//   - binding-descriptors    preTransform pass tagging handler\n//                            arrows with __lluiVariants\n//\n// Activation: opt-in. The package registers a factory with\n// `@llui/compiler` via `registerIntrospectionFactory`. The host\n// (test setup, Vite plugin, MCP) imports this package and calls\n// `registerIntrospectionFactory(introspectionFactory)` once at\n// process start. transformLlui then activates the modules when\n// `shouldEmitAgentMetadata` is true.\n\nimport { type IntrospectionFactory, type CompilerModule, type MsgSchema } from '@llui/compiler'\nimport { msgSchemaModule, type MsgSchemaModuleOptions } from './msg-schema.js'\nimport { stateSchemaModule, type StateSchemaModuleOptions } from './state-schema.js'\nimport { msgAnnotationsModule, type MsgAnnotationsModuleOptions } from './msg-annotations.js'\nimport { schemaHashModule, SCHEMA_HASH_INPUTS_SLOT, type SchemaHashInputs } from './schema-hash.js'\nimport { bindingDescriptorsModule, BINDING_DESCRIPTORS_SLOT } from './binding-descriptors.js'\n\n// Re-export individual modules + slots so adapters that want fine-\n// grained control (e.g. a test that wants only schemaHash) can still\n// reach them. The default consumption path is the factory below.\nexport {\n  msgSchemaModule,\n  type MsgSchemaModuleOptions,\n  stateSchemaModule,\n  type StateSchemaModuleOptions,\n  msgAnnotationsModule,\n  type MsgAnnotationsModuleOptions,\n  schemaHashModule,\n  SCHEMA_HASH_INPUTS_SLOT,\n  type SchemaHashInputs,\n  bindingDescriptorsModule,\n  BINDING_DESCRIPTORS_SLOT,\n}\n\n/**\n * Builds the introspection module set for a single source file.\n * Activation order matches the v2c/decomp-7 design:\n *   1. `bindingDescriptorsModule`  — preTransform fires first so the\n *      universal handler-tagger + scope-variant-registration runs\n *      before any visitor or emit phase sees the file.\n *   2. `msgSchemaModule`, `stateSchemaModule`, `msgAnnotationsModule`\n *      — producer modules populate the schema-hash inputs slot.\n *   3. `schemaHashModule` — emit reads the populated slot.\n *\n * Per-module activation gates mirror what `transformLlui` did inline\n * before decomp-26:\n *   - `msgSchemaModule`     when at least one of Msg / Effect schemas extracted\n *   - `stateSchemaModule`   when State schema extracted\n *   - `msgAnnotationsModule` when annotation map non-null (includes empty)\n *   - `schemaHashModule`    always (well-defined hash over null inputs)\n *   - `bindingDescriptorsModule` always when introspection is on\n *\n * The \"always-on schemaHash\" comes from spec §7.4: the hash ships in\n * prod too, used by HMR re-send gating regardless of agent mode.\n */\nexport const introspectionFactory: IntrospectionFactory = (input) => {\n  const modules: CompilerModule[] = []\n\n  // Agent-gated modules — only fire when shouldEmitAgentMetadata is true.\n  // binding-descriptors and the schema producers all emit metadata the\n  // end-user agent / dev MCP reads; out of agent mode they're dead weight.\n  if (input.shouldEmitAgentMetadata) {\n    // binding-descriptors fires FIRST (preTransform pass) so subsequent\n    // module visitors see the post-mutation source file.\n    modules.push(bindingDescriptorsModule)\n\n    // Producer modules — order matters: they populate the schema-hash\n    // inputs slot before schemaHashModule's emit consumes it.\n    const msgSchema = input.msgSchema as MsgSchema | null\n    const effectSchema = input.effectSchema as MsgSchema | null\n    if (msgSchema || effectSchema) {\n      modules.push(msgSchemaModule({ msgSchema, effectSchema }))\n    }\n    const stateSchema = input.stateSchema as Parameters<typeof stateSchemaModule>[0]['stateSchema']\n    if (stateSchema) {\n      modules.push(stateSchemaModule({ stateSchema }))\n    }\n    const msgAnnotations = input.msgAnnotations as Parameters<\n      typeof msgAnnotationsModule\n    >[0]['msgAnnotations']\n    if (msgAnnotations !== null) {\n      modules.push(msgAnnotationsModule({ msgAnnotations }))\n    }\n  }\n\n  // schemaHashModule registers UNCONDITIONALLY — hash is well-defined\n  // for null inputs (deterministic). HMR re-send gating consumes the\n  // hash in prod builds (spec §7.4) even when no other introspection\n  // metadata is emitted.\n  modules.push(schemaHashModule)\n\n  return modules\n}\n"]}

package/dist/msg-annotations.d.ts

@@ -0,0 +1,9 @@
+import type { CompilerModule } from '@llui/compiler';
+import { type MessageAnnotations } from '@llui/compiler';
+export interface MsgAnnotationsModuleOptions {
+    /** Pre-computed annotation map. Null when extraction failed; empty
+     * record when there are no Msg variants at all. */
+    msgAnnotations: Record<string, MessageAnnotations> | null;
+}
+export declare function msgAnnotationsModule(opts: MsgAnnotationsModuleOptions): CompilerModule;
+//# sourceMappingURL=msg-annotations.d.ts.map

package/dist/msg-annotations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"msg-annotations.d.ts","sourceRoot":"","sources":["../src/msg-annotations.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,cAAc,EAAwB,MAAM,gBAAgB,CAAA;AAC1E,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,gBAAgB,CAAA;AAIvB,MAAM,WAAW,2BAA2B;IAC1C;uDACmD;IACnD,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,GAAG,IAAI,CAAA;CAC1D;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,2BAA2B,GAAG,cAAc,CAsCtF"}

package/dist/msg-annotations.js

@@ -0,0 +1,54 @@
+// `msg-annotations` — emits `__msgAnnotations` per `component()` call
+// when the annotation map has any non-default field, and populates the
+// schema-hash inputs slot. Factory module taking the pre-computed
+// annotation map (from `extractMsgAnnotations` / cross-file resolver
+// upstream).
+//
+// Migrated from inline `injectMsgAnnotations` in transform.ts (v2c/
+// decomp-4). The "gate on hasNonDefaultAnnotation" rule preserves: when
+// every variant carries default intent/alwaysAffordable/etc., the
+// emission is suppressed (runtime treats absence as defaults). This is
+// a real win for un-annotated Msg unions, which dominate.
+import { annotationsToObjectLiteral, hasNonDefaultAnnotation, } from '@llui/compiler';
+import { SCHEMA_HASH_INPUTS_SLOT } from './schema-hash.js';
+import { findComponentCalls } from '@llui/compiler';
+export function msgAnnotationsModule(opts) {
+    return {
+        name: 'msg-annotations',
+        compilerVersion: '^0.3.0',
+        diagnostics: [],
+        // Targets captured in `emit` — see `_shared.ts`.
+        visitors: {},
+        emit(_ctx, analysis) {
+            const annotations = opts.msgAnnotations;
+            // Populate schema-hash inputs regardless of `hasNonDefault` — the
+            // hash is over the full annotation map (defaults included), so it
+            // must reflect the resolver's output verbatim.
+            if (annotations !== null) {
+                const hashInputs = analysis.perModule.get(SCHEMA_HASH_INPUTS_SLOT);
+                if (hashInputs) {
+                    hashInputs.msgAnnotations = annotations;
+                }
+                else {
+                    analysis.perModule.set(SCHEMA_HASH_INPUTS_SLOT, {
+                        msgSchema: null,
+                        stateSchema: null,
+                        msgAnnotations: annotations,
+                    });
+                }
+            }
+            if (!annotations || !hasNonDefaultAnnotation(annotations))
+                return [];
+            const calls = findComponentCalls(analysis.sourceFile);
+            if (calls.length === 0)
+                return [];
+            return calls.map((call) => ({
+                module: 'msg-annotations',
+                field: '__msgAnnotations',
+                value: annotationsToObjectLiteral(annotations),
+                target: call,
+            }));
+        },
+    };
+}
+//# sourceMappingURL=msg-annotations.js.map

package/dist/msg-annotations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"msg-annotations.js","sourceRoot":"","sources":["../src/msg-annotations.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,uEAAuE;AACvE,kEAAkE;AAClE,qEAAqE;AACrE,aAAa;AACb,EAAE;AACF,oEAAoE;AACpE,wEAAwE;AACxE,kEAAkE;AAClE,uEAAuE;AACvE,0DAA0D;AAG1D,OAAO,EACL,0BAA0B,EAC1B,uBAAuB,GAExB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,uBAAuB,EAAyB,MAAM,kBAAkB,CAAA;AACjF,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AAQnD,MAAM,UAAU,oBAAoB,CAAC,IAAiC;IACpE,OAAO;QACL,IAAI,EAAE,iBAAiB;QACvB,eAAe,EAAE,QAAQ;QACzB,WAAW,EAAE,EAAE;QACf,iDAAiD;QACjD,QAAQ,EAAE,EAAE;QAEZ,IAAI,CAAC,IAAI,EAAE,QAAQ;YACjB,MAAM,WAAW,GAAG,IAAI,CAAC,cAAc,CAAA;YACvC,kEAAkE;YAClE,kEAAkE;YAClE,+CAA+C;YAC/C,IAAI,WAAW,KAAK,IAAI,EAAE,CAAC;gBACzB,MAAM,UAAU,GAAG,QAAQ,CAAC,SAAS,CAAC,GAAG,CAAC,uBAAuB,CAEpD,CAAA;gBACb,IAAI,UAAU,EAAE,CAAC;oBACf,UAAU,CAAC,cAAc,GAAG,WAAW,CAAA;gBACzC,CAAC;qBAAM,CAAC;oBACN,QAAQ,CAAC,SAAS,CAAC,GAAG,CAAC,uBAAuB,EAAE;wBAC9C,SAAS,EAAE,IAAI;wBACf,WAAW,EAAE,IAAI;wBACjB,cAAc,EAAE,WAAW;qBACR,CAAC,CAAA;gBACxB,CAAC;YACH,CAAC;YACD,IAAI,CAAC,WAAW,IAAI,CAAC,uBAAuB,CAAC,WAAW,CAAC;gBAAE,OAAO,EAAE,CAAA;YACpE,MAAM,KAAK,GAAG,kBAAkB,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAA;YACrD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO,EAAE,CAAA;YACjC,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;gBAC1B,MAAM,EAAE,iBAAiB;gBACzB,KAAK,EAAE,kBAAkB;gBACzB,KAAK,EAAE,0BAA0B,CAAC,WAAW,CAAC;gBAC9C,MAAM,EAAE,IAAI;aACb,CAAC,CAAC,CAAA;QACL,CAAC;KACF,CAAA;AACH,CAAC","sourcesContent":["// `msg-annotations` — emits `__msgAnnotations` per `component()` call\n// when the annotation map has any non-default field, and populates the\n// schema-hash inputs slot. Factory module taking the pre-computed\n// annotation map (from `extractMsgAnnotations` / cross-file resolver\n// upstream).\n//\n// Migrated from inline `injectMsgAnnotations` in transform.ts (v2c/\n// decomp-4). The \"gate on hasNonDefaultAnnotation\" rule preserves: when\n// every variant carries default intent/alwaysAffordable/etc., the\n// emission is suppressed (runtime treats absence as defaults). This is\n// a real win for un-annotated Msg unions, which dominate.\n\nimport type { CompilerModule, EmissionContribution } from '@llui/compiler'\nimport {\n  annotationsToObjectLiteral,\n  hasNonDefaultAnnotation,\n  type MessageAnnotations,\n} from '@llui/compiler'\nimport { SCHEMA_HASH_INPUTS_SLOT, type SchemaHashInputs } from './schema-hash.js'\nimport { findComponentCalls } from '@llui/compiler'\n\nexport interface MsgAnnotationsModuleOptions {\n  /** Pre-computed annotation map. Null when extraction failed; empty\n   * record when there are no Msg variants at all. */\n  msgAnnotations: Record<string, MessageAnnotations> | null\n}\n\nexport function msgAnnotationsModule(opts: MsgAnnotationsModuleOptions): CompilerModule {\n  return {\n    name: 'msg-annotations',\n    compilerVersion: '^0.3.0',\n    diagnostics: [],\n    // Targets captured in `emit` — see `_shared.ts`.\n    visitors: {},\n\n    emit(_ctx, analysis): EmissionContribution[] {\n      const annotations = opts.msgAnnotations\n      // Populate schema-hash inputs regardless of `hasNonDefault` — the\n      // hash is over the full annotation map (defaults included), so it\n      // must reflect the resolver's output verbatim.\n      if (annotations !== null) {\n        const hashInputs = analysis.perModule.get(SCHEMA_HASH_INPUTS_SLOT) as\n          | SchemaHashInputs\n          | undefined\n        if (hashInputs) {\n          hashInputs.msgAnnotations = annotations\n        } else {\n          analysis.perModule.set(SCHEMA_HASH_INPUTS_SLOT, {\n            msgSchema: null,\n            stateSchema: null,\n            msgAnnotations: annotations,\n          } as SchemaHashInputs)\n        }\n      }\n      if (!annotations || !hasNonDefaultAnnotation(annotations)) return []\n      const calls = findComponentCalls(analysis.sourceFile)\n      if (calls.length === 0) return []\n      return calls.map((call) => ({\n        module: 'msg-annotations',\n        field: '__msgAnnotations',\n        value: annotationsToObjectLiteral(annotations),\n        target: call,\n      }))\n    },\n  }\n}\n"]}

package/dist/msg-schema.d.ts

@@ -0,0 +1,10 @@
+import type { CompilerModule } from '@llui/compiler';
+import { type MsgSchema } from '@llui/compiler';
+export interface MsgSchemaModuleOptions {
+    /** Pre-computed Msg schema; null when extraction failed. */
+    msgSchema: MsgSchema | null;
+    /** Pre-computed Effect schema; null when not present in source. */
+    effectSchema: MsgSchema | null;
+}
+export declare function msgSchemaModule(opts: MsgSchemaModuleOptions): CompilerModule;
+//# sourceMappingURL=msg-schema.d.ts.map

package/dist/msg-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"msg-schema.d.ts","sourceRoot":"","sources":["../src/msg-schema.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,cAAc,EAAwB,MAAM,gBAAgB,CAAA;AAC1E,OAAO,EAAsB,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAInE,MAAM,WAAW,sBAAsB;IACrC,4DAA4D;IAC5D,SAAS,EAAE,SAAS,GAAG,IAAI,CAAA;IAC3B,mEAAmE;IACnE,YAAY,EAAE,SAAS,GAAG,IAAI,CAAA;CAC/B;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,sBAAsB,GAAG,cAAc,CAkD5E"}

package/dist/msg-schema.js

@@ -0,0 +1,70 @@
+// `msg-schema` — emits `__msgSchema` + `__effectSchema` per
+// `component()` call and populates the schema-hash inputs slot.
+// Factory module taking the pre-computed MsgSchema for Msg and Effect.
+//
+// Migrated from inline `injectMsgSchema` + `injectEffectSchema` in
+// transform.ts (v2c/decomp-5). The literal builder
+// `msgSchemaToLiteral` (from `msg-schema.ts`) is shared between the
+// two emissions — Msg and Effect use the same discriminated-union
+// shape on the wire.
+//
+// When this module is in the active list alongside `state-schema`
+// and `msg-annotations`, the schema-hash inputs slot is fully
+// populated and `schemaHashModule` produces the authoritative
+// `__schemaHash` emission. At that point the inline
+// `injectSchemaHash` in transform.ts also deletes — see
+// v2c/decomp-5's migration.
+import { msgSchemaToLiteral } from '@llui/compiler';
+import { SCHEMA_HASH_INPUTS_SLOT } from './schema-hash.js';
+import { findComponentCalls } from '@llui/compiler';
+export function msgSchemaModule(opts) {
+    return {
+        name: 'msg-schema',
+        compilerVersion: '^0.3.0',
+        diagnostics: [],
+        // Targets captured in `emit` — see `_shared.ts`.
+        visitors: {},
+        emit(ctx, analysis) {
+            // Populate schema-hash inputs slot with our msgSchema input — the
+            // schemaHashModule will pick it up alongside whatever
+            // stateSchemaModule and msgAnnotationsModule wrote.
+            if (opts.msgSchema !== null) {
+                const hashInputs = analysis.perModule.get(SCHEMA_HASH_INPUTS_SLOT);
+                if (hashInputs) {
+                    hashInputs.msgSchema = opts.msgSchema;
+                }
+                else {
+                    analysis.perModule.set(SCHEMA_HASH_INPUTS_SLOT, {
+                        msgSchema: opts.msgSchema,
+                        stateSchema: null,
+                        msgAnnotations: null,
+                    });
+                }
+            }
+            const calls = findComponentCalls(analysis.sourceFile);
+            if (calls.length === 0)
+                return [];
+            const out = [];
+            for (const call of calls) {
+                if (opts.msgSchema !== null) {
+                    out.push({
+                        module: 'msg-schema',
+                        field: '__msgSchema',
+                        value: msgSchemaToLiteral(opts.msgSchema, ctx.factory),
+                        target: call,
+                    });
+                }
+                if (opts.effectSchema !== null) {
+                    out.push({
+                        module: 'msg-schema',
+                        field: '__effectSchema',
+                        value: msgSchemaToLiteral(opts.effectSchema, ctx.factory),
+                        target: call,
+                    });
+                }
+            }
+            return out;
+        },
+    };
+}
+//# sourceMappingURL=msg-schema.js.map

package/dist/msg-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"msg-schema.js","sourceRoot":"","sources":["../src/msg-schema.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAC5D,gEAAgE;AAChE,uEAAuE;AACvE,EAAE;AACF,mEAAmE;AACnE,mDAAmD;AACnD,oEAAoE;AACpE,kEAAkE;AAClE,qBAAqB;AACrB,EAAE;AACF,kEAAkE;AAClE,8DAA8D;AAC9D,8DAA8D;AAC9D,oDAAoD;AACpD,wDAAwD;AACxD,4BAA4B;AAG5B,OAAO,EAAE,kBAAkB,EAAkB,MAAM,gBAAgB,CAAA;AACnE,OAAO,EAAE,uBAAuB,EAAyB,MAAM,kBAAkB,CAAA;AACjF,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AASnD,MAAM,UAAU,eAAe,CAAC,IAA4B;IAC1D,OAAO;QACL,IAAI,EAAE,YAAY;QAClB,eAAe,EAAE,QAAQ;QACzB,WAAW,EAAE,EAAE;QACf,iDAAiD;QACjD,QAAQ,EAAE,EAAE;QAEZ,IAAI,CAAC,GAAG,EAAE,QAAQ;YAChB,kEAAkE;YAClE,sDAAsD;YACtD,oDAAoD;YACpD,IAAI,IAAI,CAAC,SAAS,KAAK,IAAI,EAAE,CAAC;gBAC5B,MAAM,UAAU,GAAG,QAAQ,CAAC,SAAS,CAAC,GAAG,CAAC,uBAAuB,CAEpD,CAAA;gBACb,IAAI,UAAU,EAAE,CAAC;oBACf,UAAU,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAA;gBACvC,CAAC;qBAAM,CAAC;oBACN,QAAQ,CAAC,SAAS,CAAC,GAAG,CAAC,uBAAuB,EAAE;wBAC9C,SAAS,EAAE,IAAI,CAAC,SAAS;wBACzB,WAAW,EAAE,IAAI;wBACjB,cAAc,EAAE,IAAI;qBACD,CAAC,CAAA;gBACxB,CAAC;YACH,CAAC;YACD,MAAM,KAAK,GAAG,kBAAkB,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAA;YACrD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO,EAAE,CAAA;YACjC,MAAM,GAAG,GAA2B,EAAE,CAAA;YACtC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACzB,IAAI,IAAI,CAAC,SAAS,KAAK,IAAI,EAAE,CAAC;oBAC5B,GAAG,CAAC,IAAI,CAAC;wBACP,MAAM,EAAE,YAAY;wBACpB,KAAK,EAAE,aAAa;wBACpB,KAAK,EAAE,kBAAkB,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,CAAC,OAAO,CAAC;wBACtD,MAAM,EAAE,IAAI;qBACb,CAAC,CAAA;gBACJ,CAAC;gBACD,IAAI,IAAI,CAAC,YAAY,KAAK,IAAI,EAAE,CAAC;oBAC/B,GAAG,CAAC,IAAI,CAAC;wBACP,MAAM,EAAE,YAAY;wBACpB,KAAK,EAAE,gBAAgB;wBACvB,KAAK,EAAE,kBAAkB,CAAC,IAAI,CAAC,YAAY,EAAE,GAAG,CAAC,OAAO,CAAC;wBACzD,MAAM,EAAE,IAAI;qBACb,CAAC,CAAA;gBACJ,CAAC;YACH,CAAC;YACD,OAAO,GAAG,CAAA;QACZ,CAAC;KACF,CAAA;AACH,CAAC","sourcesContent":["// `msg-schema` — emits `__msgSchema` + `__effectSchema` per\n// `component()` call and populates the schema-hash inputs slot.\n// Factory module taking the pre-computed MsgSchema for Msg and Effect.\n//\n// Migrated from inline `injectMsgSchema` + `injectEffectSchema` in\n// transform.ts (v2c/decomp-5). The literal builder\n// `msgSchemaToLiteral` (from `msg-schema.ts`) is shared between the\n// two emissions — Msg and Effect use the same discriminated-union\n// shape on the wire.\n//\n// When this module is in the active list alongside `state-schema`\n// and `msg-annotations`, the schema-hash inputs slot is fully\n// populated and `schemaHashModule` produces the authoritative\n// `__schemaHash` emission. At that point the inline\n// `injectSchemaHash` in transform.ts also deletes — see\n// v2c/decomp-5's migration.\n\nimport type { CompilerModule, EmissionContribution } from '@llui/compiler'\nimport { msgSchemaToLiteral, type MsgSchema } from '@llui/compiler'\nimport { SCHEMA_HASH_INPUTS_SLOT, type SchemaHashInputs } from './schema-hash.js'\nimport { findComponentCalls } from '@llui/compiler'\n\nexport interface MsgSchemaModuleOptions {\n  /** Pre-computed Msg schema; null when extraction failed. */\n  msgSchema: MsgSchema | null\n  /** Pre-computed Effect schema; null when not present in source. */\n  effectSchema: MsgSchema | null\n}\n\nexport function msgSchemaModule(opts: MsgSchemaModuleOptions): CompilerModule {\n  return {\n    name: 'msg-schema',\n    compilerVersion: '^0.3.0',\n    diagnostics: [],\n    // Targets captured in `emit` — see `_shared.ts`.\n    visitors: {},\n\n    emit(ctx, analysis): EmissionContribution[] {\n      // Populate schema-hash inputs slot with our msgSchema input — the\n      // schemaHashModule will pick it up alongside whatever\n      // stateSchemaModule and msgAnnotationsModule wrote.\n      if (opts.msgSchema !== null) {\n        const hashInputs = analysis.perModule.get(SCHEMA_HASH_INPUTS_SLOT) as\n          | SchemaHashInputs\n          | undefined\n        if (hashInputs) {\n          hashInputs.msgSchema = opts.msgSchema\n        } else {\n          analysis.perModule.set(SCHEMA_HASH_INPUTS_SLOT, {\n            msgSchema: opts.msgSchema,\n            stateSchema: null,\n            msgAnnotations: null,\n          } as SchemaHashInputs)\n        }\n      }\n      const calls = findComponentCalls(analysis.sourceFile)\n      if (calls.length === 0) return []\n      const out: EmissionContribution[] = []\n      for (const call of calls) {\n        if (opts.msgSchema !== null) {\n          out.push({\n            module: 'msg-schema',\n            field: '__msgSchema',\n            value: msgSchemaToLiteral(opts.msgSchema, ctx.factory),\n            target: call,\n          })\n        }\n        if (opts.effectSchema !== null) {\n          out.push({\n            module: 'msg-schema',\n            field: '__effectSchema',\n            value: msgSchemaToLiteral(opts.effectSchema, ctx.factory),\n            target: call,\n          })\n        }\n      }\n      return out\n    },\n  }\n}\n"]}

package/dist/schema-hash.d.ts

@@ -0,0 +1,14 @@
+import { type MessageAnnotations, type CompilerModule } from '@llui/compiler';
+/**
+ * Slot shape modules write to populate this module's inputs. Sibling
+ * agent modules (msg-schema, state-schema, msg-annotations) write their
+ * outputs here under the same conventional slot name.
+ */
+export interface SchemaHashInputs {
+    msgSchema: unknown;
+    stateSchema: unknown;
+    msgAnnotations: Record<string, MessageAnnotations> | null;
+}
+export declare const SCHEMA_HASH_INPUTS_SLOT = "schema-hash:inputs";
+export declare const schemaHashModule: CompilerModule;
+//# sourceMappingURL=schema-hash.d.ts.map

package/dist/schema-hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-hash.d.ts","sourceRoot":"","sources":["../src/schema-hash.ts"],"names":[],"mappings":"AA2BA,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,cAAc,EAGpB,MAAM,gBAAgB,CAAA;AAEvB;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,OAAO,CAAA;IAClB,WAAW,EAAE,OAAO,CAAA;IACpB,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,GAAG,IAAI,CAAA;CAC1D;AAED,eAAO,MAAM,uBAAuB,uBAAuB,CAAA;AAE3D,eAAO,MAAM,gBAAgB,EAAE,cAyC9B,CAAA"}

package/dist/schema-hash.js

@@ -0,0 +1,69 @@
+// `schema-hash` — CompilerModule wrapper around `computeSchemaHash`.
+//
+// Per `MODULE-MAPPING.md`, this is an **agent** concern: the hash signals
+// schema drift across HMR cycles, and only matters when the agent
+// runtime cares about Msg/State schema stability. When the agent module
+// is disabled, this module is excluded from the registry — bundles
+// don't carry `__schemaHash` and the HMR re-send heuristic falls back
+// to "always re-send".
+//
+// The module reads its inputs from sibling-module slots:
+//   - `msg-schema`'s slot for the MsgSchema object
+//   - `state-schema`'s slot for the StateSchema object
+//   - `msg-annotations`'s slot for the annotation map
+//
+// Today none of those sibling modules exist yet — the monolith's
+// `transform.ts` still owns the schema extraction. So this module's
+// `emit` falls back to "no contribution" when the slots are empty.
+// The agent-pipeline decomposition push fills the sibling slots and
+// flips this module from no-op to authoritative.
+//
+// Test fixture: `test/poc-module-schema-hash.test.ts` constructs a
+// fake AnalysisContext with populated slots and asserts the emitted
+// __schemaHash matches `computeSchemaHash`'s direct output. This proves
+// the registry+module path produces a byte-identical hash without
+// requiring the full sibling-module pipeline.
+import ts from 'typescript';
+import { computeSchemaHash, findComponentCalls, } from '@llui/compiler';
+export const SCHEMA_HASH_INPUTS_SLOT = 'schema-hash:inputs';
+export const schemaHashModule = {
+    name: 'schema-hash',
+    compilerVersion: '^0.3.0',
+    dependsOn: [],
+    diagnostics: [],
+    // No visitor pass — this module is a pure emit consumer. Sibling
+    // modules populate the inputs slot during their own visitor pass.
+    visitors: {},
+    emit(ctx, analysis) {
+        const slot = analysis.perModule.get(SCHEMA_HASH_INPUTS_SLOT);
+        // The monolith emits `__schemaHash` unconditionally for every
+        // compiled `component()` — `computeSchemaHash({null, null, null})`
+        // is a well-defined deterministic digest. Match that behavior: an
+        // absent slot means "no agent-side producers ran", which produces
+        // a hash over null inputs. Producer modules populating the slot
+        // change the hash; their absence is itself a stable input.
+        const inputs = slot ?? {
+            msgSchema: null,
+            stateSchema: null,
+            msgAnnotations: null,
+        };
+        const hash = computeSchemaHash({
+            msgSchema: inputs.msgSchema,
+            stateSchema: inputs.stateSchema,
+            msgAnnotations: inputs.msgAnnotations,
+        });
+        // Emit per-component-call so the bridge can splice the same hash
+        // into every `component()` call's config-arg. File-global emission
+        // would also work (every component in a file shares the same
+        // hash), but per-target matches the per-call splice the monolith
+        // performed via injectSchemaHash and avoids changing the bridge's
+        // existing field-distribution semantics for this migration.
+        return findComponentCalls(ctx.sourceFile).map((call) => ({
+            module: 'schema-hash',
+            field: '__schemaHash',
+            value: ts.factory.createStringLiteral(hash),
+            target: call,
+        }));
+    },
+};
+//# sourceMappingURL=schema-hash.js.map

package/dist/schema-hash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-hash.js","sourceRoot":"","sources":["../src/schema-hash.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,EAAE;AACF,0EAA0E;AAC1E,kEAAkE;AAClE,wEAAwE;AACxE,mEAAmE;AACnE,sEAAsE;AACtE,uBAAuB;AACvB,EAAE;AACF,yDAAyD;AACzD,mDAAmD;AACnD,uDAAuD;AACvD,sDAAsD;AACtD,EAAE;AACF,iEAAiE;AACjE,oEAAoE;AACpE,mEAAmE;AACnE,oEAAoE;AACpE,iDAAiD;AACjD,EAAE;AACF,mEAAmE;AACnE,oEAAoE;AACpE,wEAAwE;AACxE,kEAAkE;AAClE,8CAA8C;AAE9C,OAAO,EAAE,MAAM,YAAY,CAAA;AAC3B,OAAO,EACL,iBAAiB,EAIjB,kBAAkB,GACnB,MAAM,gBAAgB,CAAA;AAavB,MAAM,CAAC,MAAM,uBAAuB,GAAG,oBAAoB,CAAA;AAE3D,MAAM,CAAC,MAAM,gBAAgB,GAAmB;IAC9C,IAAI,EAAE,aAAa;IACnB,eAAe,EAAE,QAAQ;IACzB,SAAS,EAAE,EAAE;IACb,WAAW,EAAE,EAAE;IAEf,iEAAiE;IACjE,kEAAkE;IAClE,QAAQ,EAAE,EAAE;IAEZ,IAAI,CAAC,GAAG,EAAE,QAAQ;QAChB,MAAM,IAAI,GAAG,QAAQ,CAAC,SAAS,CAAC,GAAG,CAAC,uBAAuB,CAAiC,CAAA;QAC5F,8DAA8D;QAC9D,mEAAmE;QACnE,kEAAkE;QAClE,kEAAkE;QAClE,gEAAgE;QAChE,2DAA2D;QAC3D,MAAM,MAAM,GAAqB,IAAI,IAAI;YACvC,SAAS,EAAE,IAAI;YACf,WAAW,EAAE,IAAI;YACjB,cAAc,EAAE,IAAI;SACrB,CAAA;QACD,MAAM,IAAI,GAAG,iBAAiB,CAAC;YAC7B,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,WAAW,EAAE,MAAM,CAAC,WAAW;YAC/B,cAAc,EAAE,MAAM,CAAC,cAAc;SACtC,CAAC,CAAA;QACF,iEAAiE;QACjE,mEAAmE;QACnE,6DAA6D;QAC7D,iEAAiE;QACjE,kEAAkE;QAClE,4DAA4D;QAC5D,OAAO,kBAAkB,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YACvD,MAAM,EAAE,aAAa;YACrB,KAAK,EAAE,cAAc;YACrB,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,mBAAmB,CAAC,IAAI,CAAC;YAC3C,MAAM,EAAE,IAAI;SACb,CAAC,CAAC,CAAA;IACL,CAAC;CACF,CAAA","sourcesContent":["// `schema-hash` — CompilerModule wrapper around `computeSchemaHash`.\n//\n// Per `MODULE-MAPPING.md`, this is an **agent** concern: the hash signals\n// schema drift across HMR cycles, and only matters when the agent\n// runtime cares about Msg/State schema stability. When the agent module\n// is disabled, this module is excluded from the registry — bundles\n// don't carry `__schemaHash` and the HMR re-send heuristic falls back\n// to \"always re-send\".\n//\n// The module reads its inputs from sibling-module slots:\n//   - `msg-schema`'s slot for the MsgSchema object\n//   - `state-schema`'s slot for the StateSchema object\n//   - `msg-annotations`'s slot for the annotation map\n//\n// Today none of those sibling modules exist yet — the monolith's\n// `transform.ts` still owns the schema extraction. So this module's\n// `emit` falls back to \"no contribution\" when the slots are empty.\n// The agent-pipeline decomposition push fills the sibling slots and\n// flips this module from no-op to authoritative.\n//\n// Test fixture: `test/poc-module-schema-hash.test.ts` constructs a\n// fake AnalysisContext with populated slots and asserts the emitted\n// __schemaHash matches `computeSchemaHash`'s direct output. This proves\n// the registry+module path produces a byte-identical hash without\n// requiring the full sibling-module pipeline.\n\nimport ts from 'typescript'\nimport {\n  computeSchemaHash,\n  type MessageAnnotations,\n  type CompilerModule,\n  type EmissionContribution,\n  findComponentCalls,\n} from '@llui/compiler'\n\n/**\n * Slot shape modules write to populate this module's inputs. Sibling\n * agent modules (msg-schema, state-schema, msg-annotations) write their\n * outputs here under the same conventional slot name.\n */\nexport interface SchemaHashInputs {\n  msgSchema: unknown\n  stateSchema: unknown\n  msgAnnotations: Record<string, MessageAnnotations> | null\n}\n\nexport const SCHEMA_HASH_INPUTS_SLOT = 'schema-hash:inputs'\n\nexport const schemaHashModule: CompilerModule = {\n  name: 'schema-hash',\n  compilerVersion: '^0.3.0',\n  dependsOn: [],\n  diagnostics: [],\n\n  // No visitor pass — this module is a pure emit consumer. Sibling\n  // modules populate the inputs slot during their own visitor pass.\n  visitors: {},\n\n  emit(ctx, analysis): EmissionContribution[] {\n    const slot = analysis.perModule.get(SCHEMA_HASH_INPUTS_SLOT) as SchemaHashInputs | undefined\n    // The monolith emits `__schemaHash` unconditionally for every\n    // compiled `component()` — `computeSchemaHash({null, null, null})`\n    // is a well-defined deterministic digest. Match that behavior: an\n    // absent slot means \"no agent-side producers ran\", which produces\n    // a hash over null inputs. Producer modules populating the slot\n    // change the hash; their absence is itself a stable input.\n    const inputs: SchemaHashInputs = slot ?? {\n      msgSchema: null,\n      stateSchema: null,\n      msgAnnotations: null,\n    }\n    const hash = computeSchemaHash({\n      msgSchema: inputs.msgSchema,\n      stateSchema: inputs.stateSchema,\n      msgAnnotations: inputs.msgAnnotations,\n    })\n    // Emit per-component-call so the bridge can splice the same hash\n    // into every `component()` call's config-arg. File-global emission\n    // would also work (every component in a file shares the same\n    // hash), but per-target matches the per-call splice the monolith\n    // performed via injectSchemaHash and avoids changing the bridge's\n    // existing field-distribution semantics for this migration.\n    return findComponentCalls(ctx.sourceFile).map((call) => ({\n      module: 'schema-hash',\n      field: '__schemaHash',\n      value: ts.factory.createStringLiteral(hash),\n      target: call,\n    }))\n  },\n}\n"]}

package/dist/state-schema.d.ts

@@ -0,0 +1,8 @@
+import type { CompilerModule } from '@llui/compiler';
+import { type StateSchema } from '@llui/compiler';
+export interface StateSchemaModuleOptions {
+    /** Pre-computed schema (cross-file aware) — null when extraction failed. */
+    stateSchema: StateSchema | null;
+}
+export declare function stateSchemaModule(opts: StateSchemaModuleOptions): CompilerModule;
+//# sourceMappingURL=state-schema.d.ts.map

package/dist/state-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-schema.d.ts","sourceRoot":"","sources":["../src/state-schema.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,cAAc,EAAwB,MAAM,gBAAgB,CAAA;AAC1E,OAAO,EAAsB,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAIrE,MAAM,WAAW,wBAAwB;IACvC,4EAA4E;IAC5E,WAAW,EAAE,WAAW,GAAG,IAAI,CAAA;CAChC;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,wBAAwB,GAAG,cAAc,CA0ChF"}

package/dist/state-schema.js

@@ -0,0 +1,55 @@
+// `state-schema` — emits `__stateSchema` per `component()` call and
+// populates the schema-hash inputs slot. Factory module: takes the
+// pre-computed StateSchema (from `extractStateSchema` upstream, with
+// cross-file resolution if available) and emits its literal form
+// targeted at each component() call site.
+//
+// Migrated from the inline `injectStateSchema` in transform.ts. The
+// monolith's `extractStateSchema(...)` call lives in transformLlui's
+// setup section and gets passed into the factory; the module consumes
+// it without re-running the extractor. This keeps the extraction
+// authoritative at the umbrella level (where pre-extracted cross-file
+// data + type-source overrides are already wired) and frees the module
+// from re-implementing input resolution.
+import { stateTypeToLiteral } from '@llui/compiler';
+import { SCHEMA_HASH_INPUTS_SLOT } from './schema-hash.js';
+import { findComponentCalls } from '@llui/compiler';
+export function stateSchemaModule(opts) {
+    return {
+        name: 'state-schema',
+        compilerVersion: '^0.3.0',
+        diagnostics: [],
+        // Targets captured in `emit` — see `_shared.ts`.
+        visitors: {},
+        emit(ctx, analysis) {
+            if (!opts.stateSchema)
+                return [];
+            const calls = findComponentCalls(analysis.sourceFile);
+            if (calls.length === 0)
+                return [];
+            // Populate the schema-hash inputs slot. The schema-hash module
+            // reads this on its own emit pass and computes the hash. Module
+            // ordering is observable per v2c §2.1: when `stateSchemaModule`
+            // appears in the active module list before `schemaHashModule`,
+            // the inputs slot is populated when schema-hash's emit runs.
+            const hashInputs = analysis.perModule.get(SCHEMA_HASH_INPUTS_SLOT);
+            if (hashInputs) {
+                hashInputs.stateSchema = opts.stateSchema;
+            }
+            else {
+                analysis.perModule.set(SCHEMA_HASH_INPUTS_SLOT, {
+                    msgSchema: null,
+                    stateSchema: opts.stateSchema,
+                    msgAnnotations: null,
+                });
+            }
+            return calls.map((call) => ({
+                module: 'state-schema',
+                field: '__stateSchema',
+                value: stateTypeToLiteral({ kind: 'object', fields: opts.stateSchema.fields }, ctx.factory),
+                target: call,
+            }));
+        },
+    };
+}
+//# sourceMappingURL=state-schema.js.map

package/dist/state-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-schema.js","sourceRoot":"","sources":["../src/state-schema.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,mEAAmE;AACnE,qEAAqE;AACrE,iEAAiE;AACjE,0CAA0C;AAC1C,EAAE;AACF,oEAAoE;AACpE,qEAAqE;AACrE,sEAAsE;AACtE,iEAAiE;AACjE,sEAAsE;AACtE,uEAAuE;AACvE,yCAAyC;AAGzC,OAAO,EAAE,kBAAkB,EAAoB,MAAM,gBAAgB,CAAA;AACrE,OAAO,EAAE,uBAAuB,EAAyB,MAAM,kBAAkB,CAAA;AACjF,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AAOnD,MAAM,UAAU,iBAAiB,CAAC,IAA8B;IAC9D,OAAO;QACL,IAAI,EAAE,cAAc;QACpB,eAAe,EAAE,QAAQ;QACzB,WAAW,EAAE,EAAE;QACf,iDAAiD;QACjD,QAAQ,EAAE,EAAE;QAEZ,IAAI,CAAC,GAAG,EAAE,QAAQ;YAChB,IAAI,CAAC,IAAI,CAAC,WAAW;gBAAE,OAAO,EAAE,CAAA;YAChC,MAAM,KAAK,GAAG,kBAAkB,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAA;YACrD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO,EAAE,CAAA;YAEjC,+DAA+D;YAC/D,gEAAgE;YAChE,gEAAgE;YAChE,+DAA+D;YAC/D,6DAA6D;YAC7D,MAAM,UAAU,GAAG,QAAQ,CAAC,SAAS,CAAC,GAAG,CAAC,uBAAuB,CAEpD,CAAA;YACb,IAAI,UAAU,EAAE,CAAC;gBACf,UAAU,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAA;YAC3C,CAAC;iBAAM,CAAC;gBACN,QAAQ,CAAC,SAAS,CAAC,GAAG,CAAC,uBAAuB,EAAE;oBAC9C,SAAS,EAAE,IAAI;oBACf,WAAW,EAAE,IAAI,CAAC,WAAW;oBAC7B,cAAc,EAAE,IAAI;iBACD,CAAC,CAAA;YACxB,CAAC;YAED,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;gBAC1B,MAAM,EAAE,cAAc;gBACtB,KAAK,EAAE,eAAe;gBACtB,KAAK,EAAE,kBAAkB,CACvB,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,WAAY,CAAC,MAAM,EAAE,EACpD,GAAG,CAAC,OAAO,CACZ;gBACD,MAAM,EAAE,IAAI;aACb,CAAC,CAAC,CAAA;QACL,CAAC;KACF,CAAA;AACH,CAAC","sourcesContent":["// `state-schema` — emits `__stateSchema` per `component()` call and\n// populates the schema-hash inputs slot. Factory module: takes the\n// pre-computed StateSchema (from `extractStateSchema` upstream, with\n// cross-file resolution if available) and emits its literal form\n// targeted at each component() call site.\n//\n// Migrated from the inline `injectStateSchema` in transform.ts. The\n// monolith's `extractStateSchema(...)` call lives in transformLlui's\n// setup section and gets passed into the factory; the module consumes\n// it without re-running the extractor. This keeps the extraction\n// authoritative at the umbrella level (where pre-extracted cross-file\n// data + type-source overrides are already wired) and frees the module\n// from re-implementing input resolution.\n\nimport type { CompilerModule, EmissionContribution } from '@llui/compiler'\nimport { stateTypeToLiteral, type StateSchema } from '@llui/compiler'\nimport { SCHEMA_HASH_INPUTS_SLOT, type SchemaHashInputs } from './schema-hash.js'\nimport { findComponentCalls } from '@llui/compiler'\n\nexport interface StateSchemaModuleOptions {\n  /** Pre-computed schema (cross-file aware) — null when extraction failed. */\n  stateSchema: StateSchema | null\n}\n\nexport function stateSchemaModule(opts: StateSchemaModuleOptions): CompilerModule {\n  return {\n    name: 'state-schema',\n    compilerVersion: '^0.3.0',\n    diagnostics: [],\n    // Targets captured in `emit` — see `_shared.ts`.\n    visitors: {},\n\n    emit(ctx, analysis): EmissionContribution[] {\n      if (!opts.stateSchema) return []\n      const calls = findComponentCalls(analysis.sourceFile)\n      if (calls.length === 0) return []\n\n      // Populate the schema-hash inputs slot. The schema-hash module\n      // reads this on its own emit pass and computes the hash. Module\n      // ordering is observable per v2c §2.1: when `stateSchemaModule`\n      // appears in the active module list before `schemaHashModule`,\n      // the inputs slot is populated when schema-hash's emit runs.\n      const hashInputs = analysis.perModule.get(SCHEMA_HASH_INPUTS_SLOT) as\n        | SchemaHashInputs\n        | undefined\n      if (hashInputs) {\n        hashInputs.stateSchema = opts.stateSchema\n      } else {\n        analysis.perModule.set(SCHEMA_HASH_INPUTS_SLOT, {\n          msgSchema: null,\n          stateSchema: opts.stateSchema,\n          msgAnnotations: null,\n        } as SchemaHashInputs)\n      }\n\n      return calls.map((call) => ({\n        module: 'state-schema',\n        field: '__stateSchema',\n        value: stateTypeToLiteral(\n          { kind: 'object', fields: opts.stateSchema!.fields },\n          ctx.factory,\n        ),\n        target: call,\n      }))\n    },\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@llui/compiler-introspection",
+  "version": "0.3.0",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "typescript": "^6.0.2",
+    "@llui/compiler": "0.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0"
+  },
+  "description": "LLui compiler — runtime introspection metadata (opt-in). Schema/annotation/hash emission consumed by @llui/agent-bridge (end-user agent) and @llui/mcp (dev MCP).",
+  "keywords": [
+    "llui",
+    "compiler",
+    "introspection",
+    "schema"
+  ],
+  "author": "Franco Ponticelli <franco.ponticelli@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fponticelli/llui.git",
+    "directory": "packages/compiler-introspection"
+  },
+  "bugs": {
+    "url": "https://github.com/fponticelli/llui/issues"
+  },
+  "homepage": "https://github.com/fponticelli/llui/tree/main/packages/compiler-introspection#readme",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "check": "tsc --noEmit",
+    "lint": "eslint src",
+    "test": "vitest run"
+  }
+}