@llui/compiler 0.3.0

package/dist/modules/view-bag-import.js

@@ -0,0 +1,80 @@
+// `view-bag-import` — errors when a file that defines a component
+// imports view-bag primitives (text, each, show, branch, memo,
+// selector) directly from @llui/dom. The view bag (`view: ({ text,
+// each, … }) => …`) is typed to the component's State; the direct
+// import is generic. Migrated from
+// `@llui/eslint-plugin/src/rules/view-bag-import.ts`.
+import ts from 'typescript';
+import { rangeFromOffsets } from '../diagnostic.js';
+import { findComponentCalls } from './_shared.js';
+const VIEW_BAG_NAMES = new Set(['text', 'each', 'show', 'branch', 'memo', 'selector']);
+export function viewBagImportModule() {
+    return {
+        name: 'view-bag-import',
+        compilerVersion: '^0.3.0',
+        diagnostics: [
+            {
+                id: 'llui/view-bag-import',
+                description: 'View bag primitive imported from @llui/dom in a file that defines a component — use the view bag instead.',
+            },
+        ],
+        visitors: {
+            [ts.SyntaxKind.SourceFile]: (ctx, node) => {
+                const visited = node;
+                const sf = ts.createSourceFile(visited.fileName, visited.text, ts.ScriptTarget.Latest, true);
+                const componentCalls = findComponentCalls(sf);
+                if (componentCalls.length === 0)
+                    return;
+                // At least one component() must have a `view:` property for the
+                // rule to be meaningful (matches the ESLint rule's semantics).
+                let definesView = false;
+                for (const call of componentCalls) {
+                    const arg = call.arguments[0];
+                    if (!arg || !ts.isObjectLiteralExpression(arg))
+                        continue;
+                    for (const prop of arg.properties) {
+                        if (ts.isPropertyAssignment(prop) &&
+                            ts.isIdentifier(prop.name) &&
+                            prop.name.text === 'view') {
+                            definesView = true;
+                            break;
+                        }
+                    }
+                    if (definesView)
+                        break;
+                }
+                if (!definesView)
+                    return;
+                for (const stmt of sf.statements) {
+                    if (!ts.isImportDeclaration(stmt))
+                        continue;
+                    if (!ts.isStringLiteral(stmt.moduleSpecifier))
+                        continue;
+                    if (stmt.moduleSpecifier.text !== '@llui/dom')
+                        continue;
+                    const clause = stmt.importClause;
+                    if (!clause || !clause.namedBindings || !ts.isNamedImports(clause.namedBindings))
+                        continue;
+                    for (const spec of clause.namedBindings.elements) {
+                        const importedName = (spec.propertyName ?? spec.name).text;
+                        if (VIEW_BAG_NAMES.has(importedName)) {
+                            ctx.reportDiagnostic({
+                                id: 'llui/view-bag-import',
+                                severity: 'error',
+                                category: 'style',
+                                message: `Don't import \`${importedName}\` from '@llui/dom' in a file that defines a ` +
+                                    `component. Use the view bag: \`view: ({ ${importedName}, … }) => [...]\`. ` +
+                                    `The view-bag version is typed to your component's State.`,
+                                location: {
+                                    file: sf.fileName,
+                                    range: rangeFromOffsets(sf.text, spec.getStart(sf), spec.getEnd()),
+                                },
+                            });
+                        }
+                    }
+                }
+            },
+        },
+    };
+}
+//# sourceMappingURL=view-bag-import.js.map

package/dist/modules/view-bag-import.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"view-bag-import.js","sourceRoot":"","sources":["../../src/modules/view-bag-import.ts"],"names":[],"mappings":"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","sourcesContent":["// `view-bag-import` — errors when a file that defines a component\n// imports view-bag primitives (text, each, show, branch, memo,\n// selector) directly from @llui/dom. The view bag (`view: ({ text,\n// each, … }) => …`) is typed to the component's State; the direct\n// import is generic. Migrated from\n// `@llui/eslint-plugin/src/rules/view-bag-import.ts`.\n\nimport ts from 'typescript'\nimport { rangeFromOffsets } from '../diagnostic.js'\nimport type { CompilerModule } from '../module.js'\nimport { findComponentCalls } from './_shared.js'\n\nconst VIEW_BAG_NAMES = new Set(['text', 'each', 'show', 'branch', 'memo', 'selector'])\n\nexport function viewBagImportModule(): CompilerModule {\n  return {\n    name: 'view-bag-import',\n    compilerVersion: '^0.3.0',\n    diagnostics: [\n      {\n        id: 'llui/view-bag-import',\n        description:\n          'View bag primitive imported from @llui/dom in a file that defines a component — use the view bag instead.',\n      },\n    ],\n    visitors: {\n      [ts.SyntaxKind.SourceFile]: (ctx, node) => {\n        const visited = node as ts.SourceFile\n        const sf = ts.createSourceFile(visited.fileName, visited.text, ts.ScriptTarget.Latest, true)\n        const componentCalls = findComponentCalls(sf)\n        if (componentCalls.length === 0) return\n        // At least one component() must have a `view:` property for the\n        // rule to be meaningful (matches the ESLint rule's semantics).\n        let definesView = false\n        for (const call of componentCalls) {\n          const arg = call.arguments[0]\n          if (!arg || !ts.isObjectLiteralExpression(arg)) continue\n          for (const prop of arg.properties) {\n            if (\n              ts.isPropertyAssignment(prop) &&\n              ts.isIdentifier(prop.name) &&\n              prop.name.text === 'view'\n            ) {\n              definesView = true\n              break\n            }\n          }\n          if (definesView) break\n        }\n        if (!definesView) return\n        for (const stmt of sf.statements) {\n          if (!ts.isImportDeclaration(stmt)) continue\n          if (!ts.isStringLiteral(stmt.moduleSpecifier)) continue\n          if (stmt.moduleSpecifier.text !== '@llui/dom') continue\n          const clause = stmt.importClause\n          if (!clause || !clause.namedBindings || !ts.isNamedImports(clause.namedBindings)) continue\n          for (const spec of clause.namedBindings.elements) {\n            const importedName = (spec.propertyName ?? spec.name).text\n            if (VIEW_BAG_NAMES.has(importedName)) {\n              ctx.reportDiagnostic({\n                id: 'llui/view-bag-import',\n                severity: 'error',\n                category: 'style',\n                message:\n                  `Don't import \\`${importedName}\\` from '@llui/dom' in a file that defines a ` +\n                  `component. Use the view bag: \\`view: ({ ${importedName}, … }) => [...]\\`. ` +\n                  `The view-bag version is typed to your component's State.`,\n                location: {\n                  file: sf.fileName,\n                  range: rangeFromOffsets(sf.text, spec.getStart(sf), spec.getEnd()),\n                },\n              })\n            }\n          }\n        }\n      },\n    },\n  }\n}\n"]}

package/dist/msg-annotations.d.ts

@@ -0,0 +1,104 @@
+import ts from 'typescript';
+export type DispatchMode = 'shared' | 'human-only' | 'agent-only';
+/**
+ * Whether the annotation map carries any non-default values. Used to
+ * gate `__msgAnnotations` emission — annotations whose every field is
+ * default are emission-redundant (the runtime treats absence as the
+ * same defaults). Saves ~50 bytes per component for un-annotated Msg
+ * unions, which dominates the corpus.
+ */
+export declare function hasNonDefaultAnnotation(a: Record<string, MessageAnnotations>): boolean;
+/**
+ * Build a TS object-literal expression for the annotation map. Used by
+ * `msgAnnotationsModule` for `__msgAnnotations` emission. Variant
+ * names are emitted as string literals (not identifiers) so
+ * discriminants containing `/`, `-`, reserved words, etc. produce
+ * valid JS.
+ */
+export declare function annotationsToObjectLiteral(a: Record<string, MessageAnnotations>): ts.ObjectLiteralExpression;
+export type MessageAnnotations = {
+    intent: string | null;
+    alwaysAffordable: boolean;
+    requiresConfirm: boolean;
+    dispatchMode: DispatchMode;
+    /**
+     * Concrete example dispatches the LLM can copy from. Populated by
+     * `@example("text")` JSDoc tags. Each tag becomes one entry, in
+     * source order, so authors can mix scenarios ("typical case",
+     * "edge case with auth", etc.) without nesting them in a single
+     * string.
+     */
+    examples: string[];
+    /**
+     * Non-blocking caution. Surfaced verbatim to the agent at affordance
+     * time so the LLM can weigh the consequence ("this overwrites the
+     * cloud version", "fires analytics that can't be retracted") before
+     * dispatching. Distinct from `requiresConfirm`, which is a runtime
+     * gate the user must acknowledge.
+     */
+    warning: string | null;
+    /**
+     * Effect kinds this variant emits when dispatched, declared by the
+     * author via `@emits("kind1", "kind2")`. Lets the agent reason
+     * about side effects ("this dispatch hits the cloud, so I should
+     * batch") without the compiler having to walk update.ts. Authored
+     * rather than auto-extracted because real apps emit effects
+     * through helpers (`track('foo')`, `saveDelta(d)`) — auto-detecting
+     * those would require helper-return-shape analysis with
+     * ergonomically-painful failure modes; the declarative form trades
+     * automatic discovery for accuracy and simplicity.
+     *
+     * Empty when no `@emits` tag is present.
+     */
+    emits: string[];
+    /**
+     * Boolean predicate gating whether the variant surfaces in
+     * `list_actions`. Authored as `@routeGated("expr")`; the compiler
+     * captures the predicate string verbatim and the runtime evaluates
+     * it with `state` bound to the current state. The variant only
+     * appears in the agent's affordance list when the predicate
+     * returns true.
+     *
+     * Compile-time alternative to `agentAffordances(state) => Msg[]`
+     * for the common case of "this Msg is reachable when state.X
+     * looks like Y." Co-located with the Msg definition rather than
+     * threaded through a separate hook.
+     *
+     * Examples:
+     *   @routeGated("state.matrixState.kind === 'loaded'")
+     *   @routeGated("state.route.kind === 'page' && state.route.slug === 'ranking'")
+     *   @routeGated("state.auth.status === 'authenticated'")
+     *
+     * Null when no `@routeGated` tag is present (variant defaults to
+     * its dispatchMode-driven affordance behavior).
+     */
+    routeGate: string | null;
+};
+/**
+ * Walk a Msg-like discriminated-union type alias and extract JSDoc
+ * annotations attached to each union member. Returns null if no
+ * recognizable union is found so callers can skip emission cleanly.
+ *
+ * Expected JSDoc grammar (order-independent):
+ *   @intent("human readable")
+ *   @alwaysAffordable
+ *   @requiresConfirm
+ *   @humanOnly       — sugar for dispatchMode: 'human-only'
+ *   @agentOnly       — sugar for dispatchMode: 'agent-only'
+ *
+ * Unknown tags are ignored; malformed @intent (no quoted string) is
+ * treated as "no intent". `@humanOnly` and `@agentOnly` are mutually
+ * exclusive — if both are present (which the ESLint rule
+ * `agent-exclusive-annotations` reports as an error), the parser
+ * falls back to `'shared'` so a misconfigured Msg variant doesn't
+ * silently lock out one audience.
+ */
+export declare function extractMsgAnnotations(source: string, 
+/**
+ * Name of the type alias to extract from. Defaults to `'Msg'` for
+ * convention. Passed by the cross-file resolver when the alias has
+ * been renamed through imports/re-exports — its local name in the
+ * declaring file may differ from `'Msg'`.
+ */
+typeName?: string): Record<string, MessageAnnotations> | null;
+//# 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":"AAAA,OAAO,EAAE,MAAM,YAAY,CAAA;AAE3B,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,YAAY,GAAG,YAAY,CAAA;AAEjE;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,GAAG,OAAO,CAStF;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACxC,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,GACpC,EAAE,CAAC,uBAAuB,CAmD5B;AAED,MAAM,MAAM,kBAAkB,GAAG;IAC/B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,gBAAgB,EAAE,OAAO,CAAA;IACzB,eAAe,EAAE,OAAO,CAAA;IACxB,YAAY,EAAE,YAAY,CAAA;IAC1B;;;;;;OAMG;IACH,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB;;;;;;OAMG;IACH,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB;;;;;;;;;;;;OAYG;IACH,KAAK,EAAE,MAAM,EAAE,CAAA;IACf;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CACzB,CAAA;AAaD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM;AACd;;;;;GAKG;AACH,QAAQ,GAAE,MAAc,GACvB,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,GAAG,IAAI,CAgC3C"}

package/dist/msg-annotations.js

@@ -0,0 +1,242 @@
+import ts from 'typescript';
+/**
+ * Whether the annotation map carries any non-default values. Used to
+ * gate `__msgAnnotations` emission — annotations whose every field is
+ * default are emission-redundant (the runtime treats absence as the
+ * same defaults). Saves ~50 bytes per component for un-annotated Msg
+ * unions, which dominates the corpus.
+ */
+export function hasNonDefaultAnnotation(a) {
+    for (const v of Object.values(a)) {
+        if (v.intent !== null)
+            return true;
+        if (v.alwaysAffordable)
+            return true;
+        if (v.requiresConfirm)
+            return true;
+        if (v.dispatchMode !== 'shared')
+            return true;
+        if (v.routeGate != null)
+            return true;
+    }
+    return false;
+}
+/**
+ * Build a TS object-literal expression for the annotation map. Used by
+ * `msgAnnotationsModule` for `__msgAnnotations` emission. Variant
+ * names are emitted as string literals (not identifiers) so
+ * discriminants containing `/`, `-`, reserved words, etc. produce
+ * valid JS.
+ */
+export function annotationsToObjectLiteral(a) {
+    const props = [];
+    for (const [variant, ann] of Object.entries(a)) {
+        props.push(ts.factory.createPropertyAssignment(
+        // Wrap with createStringLiteral — the printer treats bare strings
+        // as identifiers, which produces invalid JS for discriminants
+        // containing characters like '/' (e.g. 'Router/RouteChanged'),
+        // reserved words ('delete'), or hyphens.
+        ts.factory.createStringLiteral(variant), ts.factory.createObjectLiteralExpression([
+            ts.factory.createPropertyAssignment('intent', ann.intent === null
+                ? ts.factory.createNull()
+                : ts.factory.createStringLiteral(ann.intent)),
+            ts.factory.createPropertyAssignment('alwaysAffordable', ann.alwaysAffordable ? ts.factory.createTrue() : ts.factory.createFalse()),
+            ts.factory.createPropertyAssignment('requiresConfirm', ann.requiresConfirm ? ts.factory.createTrue() : ts.factory.createFalse()),
+            ts.factory.createPropertyAssignment('dispatchMode', ts.factory.createStringLiteral(ann.dispatchMode)),
+            // Only emit `routeGate` when non-null. The runtime treats
+            // missing as the no-gate default ("variant follows its
+            // dispatchMode-driven affordance behavior") — keeping the
+            // wire shape minimal for the common case of un-gated Msgs.
+            // Use loose `!= null` so test fixtures that omit the
+            // field entirely also fall through to the no-emit path.
+            ...(ann.routeGate != null
+                ? [
+                    ts.factory.createPropertyAssignment('routeGate', ts.factory.createStringLiteral(ann.routeGate)),
+                ]
+                : []),
+        ], true)));
+    }
+    return ts.factory.createObjectLiteralExpression(props, true);
+}
+const DEFAULT = {
+    intent: null,
+    alwaysAffordable: false,
+    requiresConfirm: false,
+    dispatchMode: 'shared',
+    examples: [],
+    warning: null,
+    emits: [],
+    routeGate: null,
+};
+/**
+ * Walk a Msg-like discriminated-union type alias and extract JSDoc
+ * annotations attached to each union member. Returns null if no
+ * recognizable union is found so callers can skip emission cleanly.
+ *
+ * Expected JSDoc grammar (order-independent):
+ *   @intent("human readable")
+ *   @alwaysAffordable
+ *   @requiresConfirm
+ *   @humanOnly       — sugar for dispatchMode: 'human-only'
+ *   @agentOnly       — sugar for dispatchMode: 'agent-only'
+ *
+ * Unknown tags are ignored; malformed @intent (no quoted string) is
+ * treated as "no intent". `@humanOnly` and `@agentOnly` are mutually
+ * exclusive — if both are present (which the ESLint rule
+ * `agent-exclusive-annotations` reports as an error), the parser
+ * falls back to `'shared'` so a misconfigured Msg variant doesn't
+ * silently lock out one audience.
+ */
+export function extractMsgAnnotations(source, 
+/**
+ * Name of the type alias to extract from. Defaults to `'Msg'` for
+ * convention. Passed by the cross-file resolver when the alias has
+ * been renamed through imports/re-exports — its local name in the
+ * declaring file may differ from `'Msg'`.
+ */
+typeName = 'Msg') {
+    const sf = ts.createSourceFile('msg.ts', source, ts.ScriptTarget.Latest, true);
+    const aliases = [];
+    sf.forEachChild((n) => {
+        if (ts.isTypeAliasDeclaration(n))
+            aliases.push(n);
+    });
+    const named = aliases.find((a) => a.name.text === typeName);
+    // Fallback: only when looking for the conventional 'Msg' name AND the
+    // file has no `type Msg = …`; pick any union type alias. With an
+    // explicit `typeName` from the resolver, we don't fall back — that
+    // would silently match the wrong alias.
+    const alias = named ?? (typeName === 'Msg' ? aliases.find((a) => ts.isUnionTypeNode(a.type)) : undefined);
+    if (!alias || !ts.isUnionTypeNode(alias.type))
+        return null;
+    const result = {};
+    const types = alias.type.types;
+    for (let i = 0; i < types.length; i++) {
+        const member = types[i];
+        if (member === undefined || !ts.isTypeLiteralNode(member))
+            continue;
+        const variant = readDiscriminantLiteral(member);
+        if (!variant)
+            continue;
+        // Leading JSDoc for union member i is scanned from the end of the
+        // previous element (or union.pos for the first member), because
+        // TypeScript's parser places comment ranges relative to the token
+        // that follows them — and the | bar is not part of the TypeLiteralNode.
+        const prev = types[i - 1];
+        const scanPos = i === 0 || prev === undefined ? alias.type.pos : prev.end;
+        const comment = readLeadingJSDoc(source, scanPos);
+        result[variant] = parseAnnotations(comment);
+    }
+    return Object.keys(result).length === 0 ? null : result;
+}
+function readDiscriminantLiteral(lit) {
+    for (const m of lit.members) {
+        if (!ts.isPropertySignature(m))
+            continue;
+        if (!m.name || !ts.isIdentifier(m.name) || m.name.text !== 'type')
+            continue;
+        if (!m.type || !ts.isLiteralTypeNode(m.type))
+            continue;
+        const literal = m.type.literal;
+        if (ts.isStringLiteral(literal))
+            return literal.text;
+    }
+    return null;
+}
+function readLeadingJSDoc(source, scanPos) {
+    const ranges = ts.getLeadingCommentRanges(source, scanPos) ?? [];
+    const docs = ranges
+        .filter((r) => r.kind === ts.SyntaxKind.MultiLineCommentTrivia)
+        .map((r) => source.slice(r.pos, r.end))
+        .filter((txt) => txt.startsWith('/**'));
+    return docs.join('\n');
+}
+function parseAnnotations(comment) {
+    if (!comment)
+        return { ...DEFAULT, examples: [] };
+    const intent = readIntent(comment);
+    const human = /@humanOnly\b/.test(comment);
+    const agent = /@agentOnly\b/.test(comment);
+    // Mutual-exclusion fallback: both tags present means a config bug;
+    // the ESLint rule reports it. At parse time, default to 'shared' so
+    // we don't silently lock out one audience based on tag order.
+    const dispatchMode = human && !agent ? 'human-only' : agent && !human ? 'agent-only' : 'shared';
+    return {
+        intent,
+        alwaysAffordable: /@alwaysAffordable\b/.test(comment),
+        requiresConfirm: /@requiresConfirm\b/.test(comment),
+        dispatchMode,
+        examples: readExamples(comment),
+        warning: readWarning(comment),
+        emits: readEmits(comment),
+        routeGate: readRouteGate(comment),
+    };
+}
+/**
+ * Match `@routeGated("predicate-expression")` (and curly-quote
+ * variant). Returns the verbatim predicate string — the runtime
+ * compiles it with `new Function('state', 'return (' + src + ')')`
+ * and evaluates against the current state to gate affordances.
+ *
+ * Mirrors `@validates`'s grammar but with `state` as the bound
+ * variable instead of `v` (since the predicate sees the whole app
+ * state, not a single field value).
+ */
+function readRouteGate(comment) {
+    const match = comment.match(/@routeGated\s*\(\s*["“]([^"”]*)["”]\s*\)/);
+    return match?.[1] ?? null;
+}
+/**
+ * Match `@emits("k1", "k2", ...)` — comma-separated list of effect
+ * kind strings. Each entry can use straight or curly quotes; the
+ * separator is `,` with arbitrary whitespace. Returns the kinds in
+ * source order (deduped). Empty when the tag is absent or has no
+ * quoted strings.
+ */
+function readEmits(comment) {
+    // Match the whole `@emits(...)` parenthesized group so we can
+    // re-parse the inner content for individual quoted strings. The
+    // outer match is non-greedy on the closing paren to avoid eating
+    // through later JSDoc.
+    const outer = comment.match(/@emits\s*\(([^)]*)\)/);
+    if (!outer || outer[1] === undefined)
+        return [];
+    const inner = outer[1];
+    const seen = new Set();
+    const out = [];
+    const re = /["“]([^"”]*)["”]/g;
+    let m;
+    while ((m = re.exec(inner)) !== null) {
+        const v = m[1];
+        if (v === undefined || seen.has(v))
+            continue;
+        seen.add(v);
+        out.push(v);
+    }
+    return out;
+}
+function readIntent(comment) {
+    const match = comment.match(/@intent\s*\(\s*["\u201c]([^"\u201d]*)["\u201d]\s*\)/);
+    return match?.[1] ?? null;
+}
+/**
+ * Match every `@example("\u2026")` (and curly-quote variant) in source
+ * order. Multiple tags on one variant are common \u2014 typical-case,
+ * edge-case-with-auth, etc. \u2014 so the parser collects all of them
+ * rather than picking the first.
+ */
+function readExamples(comment) {
+    const out = [];
+    const re = /@example\s*\(\s*["\u201c]([^"\u201d]*)["\u201d]\s*\)/g;
+    let m;
+    while ((m = re.exec(comment)) !== null) {
+        if (m[1] !== undefined)
+            out.push(m[1]);
+    }
+    return out;
+}
+function readWarning(comment) {
+    const match = comment.match(/@warning\s*\(\s*["\u201c]([^"\u201d]*)["\u201d]\s*\)/);
+    return match?.[1] ?? null;
+}
+//# 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,OAAO,EAAE,MAAM,YAAY,CAAA;AAI3B;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CAAC,CAAqC;IAC3E,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;QACjC,IAAI,CAAC,CAAC,MAAM,KAAK,IAAI;YAAE,OAAO,IAAI,CAAA;QAClC,IAAI,CAAC,CAAC,gBAAgB;YAAE,OAAO,IAAI,CAAA;QACnC,IAAI,CAAC,CAAC,eAAe;YAAE,OAAO,IAAI,CAAA;QAClC,IAAI,CAAC,CAAC,YAAY,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAA;QAC5C,IAAI,CAAC,CAAC,SAAS,IAAI,IAAI;YAAE,OAAO,IAAI,CAAA;IACtC,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,0BAA0B,CACxC,CAAqC;IAErC,MAAM,KAAK,GAA4B,EAAE,CAAA;IACzC,KAAK,MAAM,CAAC,OAAO,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/C,KAAK,CAAC,IAAI,CACR,EAAE,CAAC,OAAO,CAAC,wBAAwB;QACjC,kEAAkE;QAClE,8DAA8D;QAC9D,+DAA+D;QAC/D,yCAAyC;QACzC,EAAE,CAAC,OAAO,CAAC,mBAAmB,CAAC,OAAO,CAAC,EACvC,EAAE,CAAC,OAAO,CAAC,6BAA6B,CACtC;YACE,EAAE,CAAC,OAAO,CAAC,wBAAwB,CACjC,QAAQ,EACR,GAAG,CAAC,MAAM,KAAK,IAAI;gBACjB,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,UAAU,EAAE;gBACzB,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,mBAAmB,CAAC,GAAG,CAAC,MAAM,CAAC,CAC/C;YACD,EAAE,CAAC,OAAO,CAAC,wBAAwB,CACjC,kBAAkB,EAClB,GAAG,CAAC,gBAAgB,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,WAAW,EAAE,CAC1E;YACD,EAAE,CAAC,OAAO,CAAC,wBAAwB,CACjC,iBAAiB,EACjB,GAAG,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,WAAW,EAAE,CACzE;YACD,EAAE,CAAC,OAAO,CAAC,wBAAwB,CACjC,cAAc,EACd,EAAE,CAAC,OAAO,CAAC,mBAAmB,CAAC,GAAG,CAAC,YAAY,CAAC,CACjD;YACD,0DAA0D;YAC1D,uDAAuD;YACvD,0DAA0D;YAC1D,2DAA2D;YAC3D,qDAAqD;YACrD,wDAAwD;YACxD,GAAG,CAAC,GAAG,CAAC,SAAS,IAAI,IAAI;gBACvB,CAAC,CAAC;oBACE,EAAE,CAAC,OAAO,CAAC,wBAAwB,CACjC,WAAW,EACX,EAAE,CAAC,OAAO,CAAC,mBAAmB,CAAC,GAAG,CAAC,SAAS,CAAC,CAC9C;iBACF;gBACH,CAAC,CAAC,EAAE,CAAC;SACR,EACD,IAAI,CACL,CACF,CACF,CAAA;IACH,CAAC;IACD,OAAO,EAAE,CAAC,OAAO,CAAC,6BAA6B,CAAC,KAAK,EAAE,IAAI,CAAC,CAAA;AAC9D,CAAC;AA6DD,MAAM,OAAO,GAAuB;IAClC,MAAM,EAAE,IAAI;IACZ,gBAAgB,EAAE,KAAK;IACvB,eAAe,EAAE,KAAK;IACtB,YAAY,EAAE,QAAQ;IACtB,QAAQ,EAAE,EAAE;IACZ,OAAO,EAAE,IAAI;IACb,KAAK,EAAE,EAAE;IACT,SAAS,EAAE,IAAI;CAChB,CAAA;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,qBAAqB,CACnC,MAAc;AACd;;;;;GAKG;AACH,WAAmB,KAAK;IAExB,MAAM,EAAE,GAAG,EAAE,CAAC,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,CAAC,YAAY,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;IAC9E,MAAM,OAAO,GAA8B,EAAE,CAAA;IAC7C,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,EAAE;QACpB,IAAI,EAAE,CAAC,sBAAsB,CAAC,CAAC,CAAC;YAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;IACnD,CAAC,CAAC,CAAA;IACF,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAA;IAC3D,sEAAsE;IACtE,iEAAiE;IACjE,mEAAmE;IACnE,wCAAwC;IACxC,MAAM,KAAK,GACT,KAAK,IAAI,CAAC,QAAQ,KAAK,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,eAAe,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;IAC7F,IAAI,CAAC,KAAK,IAAI,CAAC,EAAE,CAAC,eAAe,CAAC,KAAK,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAA;IAE1D,MAAM,MAAM,GAAuC,EAAE,CAAA;IACrD,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,CAAA;IAC9B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,CAAA;QACvB,IAAI,MAAM,KAAK,SAAS,IAAI,CAAC,EAAE,CAAC,iBAAiB,CAAC,MAAM,CAAC;YAAE,SAAQ;QACnE,MAAM,OAAO,GAAG,uBAAuB,CAAC,MAAM,CAAC,CAAA;QAC/C,IAAI,CAAC,OAAO;YAAE,SAAQ;QACtB,kEAAkE;QAClE,gEAAgE;QAChE,kEAAkE;QAClE,wEAAwE;QACxE,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAA;QACzB,MAAM,OAAO,GAAG,CAAC,KAAK,CAAC,IAAI,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAA;QACzE,MAAM,OAAO,GAAG,gBAAgB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;QACjD,MAAM,CAAC,OAAO,CAAC,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAA;IAC7C,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAA;AACzD,CAAC;AAED,SAAS,uBAAuB,CAAC,GAAuB;IACtD,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;QAC5B,IAAI,CAAC,EAAE,CAAC,mBAAmB,CAAC,CAAC,CAAC;YAAE,SAAQ;QACxC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,KAAK,MAAM;YAAE,SAAQ;QAC3E,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,EAAE,CAAC,iBAAiB,CAAC,CAAC,CAAC,IAAI,CAAC;YAAE,SAAQ;QACtD,MAAM,OAAO,GAAG,CAAC,CAAC,IAAI,CAAC,OAAO,CAAA;QAC9B,IAAI,EAAE,CAAC,eAAe,CAAC,OAAO,CAAC;YAAE,OAAO,OAAO,CAAC,IAAI,CAAA;IACtD,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC;AAED,SAAS,gBAAgB,CAAC,MAAc,EAAE,OAAe;IACvD,MAAM,MAAM,GAAG,EAAE,CAAC,uBAAuB,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,EAAE,CAAA;IAChE,MAAM,IAAI,GAAG,MAAM;SAChB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,EAAE,CAAC,UAAU,CAAC,sBAAsB,CAAC;SAC9D,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;SACtC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAA;IACzC,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACxB,CAAC;AAED,SAAS,gBAAgB,CAAC,OAAe;IACvC,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,GAAG,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAA;IACjD,MAAM,MAAM,GAAG,UAAU,CAAC,OAAO,CAAC,CAAA;IAClC,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;IAC1C,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;IAC1C,mEAAmE;IACnE,oEAAoE;IACpE,8DAA8D;IAC9D,MAAM,YAAY,GAChB,KAAK,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,QAAQ,CAAA;IAC5E,OAAO;QACL,MAAM;QACN,gBAAgB,EAAE,qBAAqB,CAAC,IAAI,CAAC,OAAO,CAAC;QACrD,eAAe,EAAE,oBAAoB,CAAC,IAAI,CAAC,OAAO,CAAC;QACnD,YAAY;QACZ,QAAQ,EAAE,YAAY,CAAC,OAAO,CAAC;QAC/B,OAAO,EAAE,WAAW,CAAC,OAAO,CAAC;QAC7B,KAAK,EAAE,SAAS,CAAC,OAAO,CAAC;QACzB,SAAS,EAAE,aAAa,CAAC,OAAO,CAAC;KAClC,CAAA;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,SAAS,aAAa,CAAC,OAAe;IACpC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,0CAA0C,CAAC,CAAA;IACvE,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAA;AAC3B,CAAC;AAED;;;;;;GAMG;AACH,SAAS,SAAS,CAAC,OAAe;IAChC,8DAA8D;IAC9D,gEAAgE;IAChE,iEAAiE;IACjE,uBAAuB;IACvB,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,sBAAsB,CAAC,CAAA;IACnD,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,SAAS;QAAE,OAAO,EAAE,CAAA;IAC/C,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAA;IACtB,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAA;IAC9B,MAAM,GAAG,GAAa,EAAE,CAAA;IACxB,MAAM,EAAE,GAAG,mBAAmB,CAAA;IAC9B,IAAI,CAAyB,CAAA;IAC7B,OAAO,CAAC,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QACrC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAA;QACd,IAAI,CAAC,KAAK,SAAS,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;YAAE,SAAQ;QAC5C,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;QACX,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;IACb,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,SAAS,UAAU,CAAC,OAAe;IACjC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,qDAAqD,CAAC,CAAA;IAClF,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAA;AAC3B,CAAC;AAED;;;;;GAKG;AACH,SAAS,YAAY,CAAC,OAAe;IACnC,MAAM,GAAG,GAAa,EAAE,CAAA;IACxB,MAAM,EAAE,GAAG,uDAAuD,CAAA;IAClE,IAAI,CAAyB,CAAA;IAC7B,OAAO,CAAC,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QACvC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,SAAS;YAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IACxC,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,SAAS,WAAW,CAAC,OAAe;IAClC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,sDAAsD,CAAC,CAAA;IACnF,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAA;AAC3B,CAAC","sourcesContent":["import ts from 'typescript'\n\nexport type DispatchMode = 'shared' | 'human-only' | 'agent-only'\n\n/**\n * Whether the annotation map carries any non-default values. Used to\n * gate `__msgAnnotations` emission — annotations whose every field is\n * default are emission-redundant (the runtime treats absence as the\n * same defaults). Saves ~50 bytes per component for un-annotated Msg\n * unions, which dominates the corpus.\n */\nexport function hasNonDefaultAnnotation(a: Record<string, MessageAnnotations>): boolean {\n  for (const v of Object.values(a)) {\n    if (v.intent !== null) return true\n    if (v.alwaysAffordable) return true\n    if (v.requiresConfirm) return true\n    if (v.dispatchMode !== 'shared') return true\n    if (v.routeGate != null) return true\n  }\n  return false\n}\n\n/**\n * Build a TS object-literal expression for the annotation map. Used by\n * `msgAnnotationsModule` for `__msgAnnotations` emission. Variant\n * names are emitted as string literals (not identifiers) so\n * discriminants containing `/`, `-`, reserved words, etc. produce\n * valid JS.\n */\nexport function annotationsToObjectLiteral(\n  a: Record<string, MessageAnnotations>,\n): ts.ObjectLiteralExpression {\n  const props: ts.PropertyAssignment[] = []\n  for (const [variant, ann] of Object.entries(a)) {\n    props.push(\n      ts.factory.createPropertyAssignment(\n        // Wrap with createStringLiteral — the printer treats bare strings\n        // as identifiers, which produces invalid JS for discriminants\n        // containing characters like '/' (e.g. 'Router/RouteChanged'),\n        // reserved words ('delete'), or hyphens.\n        ts.factory.createStringLiteral(variant),\n        ts.factory.createObjectLiteralExpression(\n          [\n            ts.factory.createPropertyAssignment(\n              'intent',\n              ann.intent === null\n                ? ts.factory.createNull()\n                : ts.factory.createStringLiteral(ann.intent),\n            ),\n            ts.factory.createPropertyAssignment(\n              'alwaysAffordable',\n              ann.alwaysAffordable ? ts.factory.createTrue() : ts.factory.createFalse(),\n            ),\n            ts.factory.createPropertyAssignment(\n              'requiresConfirm',\n              ann.requiresConfirm ? ts.factory.createTrue() : ts.factory.createFalse(),\n            ),\n            ts.factory.createPropertyAssignment(\n              'dispatchMode',\n              ts.factory.createStringLiteral(ann.dispatchMode),\n            ),\n            // Only emit `routeGate` when non-null. The runtime treats\n            // missing as the no-gate default (\"variant follows its\n            // dispatchMode-driven affordance behavior\") — keeping the\n            // wire shape minimal for the common case of un-gated Msgs.\n            // Use loose `!= null` so test fixtures that omit the\n            // field entirely also fall through to the no-emit path.\n            ...(ann.routeGate != null\n              ? [\n                  ts.factory.createPropertyAssignment(\n                    'routeGate',\n                    ts.factory.createStringLiteral(ann.routeGate),\n                  ),\n                ]\n              : []),\n          ],\n          true,\n        ),\n      ),\n    )\n  }\n  return ts.factory.createObjectLiteralExpression(props, true)\n}\n\nexport type MessageAnnotations = {\n  intent: string | null\n  alwaysAffordable: boolean\n  requiresConfirm: boolean\n  dispatchMode: DispatchMode\n  /**\n   * Concrete example dispatches the LLM can copy from. Populated by\n   * `@example(\"text\")` JSDoc tags. Each tag becomes one entry, in\n   * source order, so authors can mix scenarios (\"typical case\",\n   * \"edge case with auth\", etc.) without nesting them in a single\n   * string.\n   */\n  examples: string[]\n  /**\n   * Non-blocking caution. Surfaced verbatim to the agent at affordance\n   * time so the LLM can weigh the consequence (\"this overwrites the\n   * cloud version\", \"fires analytics that can't be retracted\") before\n   * dispatching. Distinct from `requiresConfirm`, which is a runtime\n   * gate the user must acknowledge.\n   */\n  warning: string | null\n  /**\n   * Effect kinds this variant emits when dispatched, declared by the\n   * author via `@emits(\"kind1\", \"kind2\")`. Lets the agent reason\n   * about side effects (\"this dispatch hits the cloud, so I should\n   * batch\") without the compiler having to walk update.ts. Authored\n   * rather than auto-extracted because real apps emit effects\n   * through helpers (`track('foo')`, `saveDelta(d)`) — auto-detecting\n   * those would require helper-return-shape analysis with\n   * ergonomically-painful failure modes; the declarative form trades\n   * automatic discovery for accuracy and simplicity.\n   *\n   * Empty when no `@emits` tag is present.\n   */\n  emits: string[]\n  /**\n   * Boolean predicate gating whether the variant surfaces in\n   * `list_actions`. Authored as `@routeGated(\"expr\")`; the compiler\n   * captures the predicate string verbatim and the runtime evaluates\n   * it with `state` bound to the current state. The variant only\n   * appears in the agent's affordance list when the predicate\n   * returns true.\n   *\n   * Compile-time alternative to `agentAffordances(state) => Msg[]`\n   * for the common case of \"this Msg is reachable when state.X\n   * looks like Y.\" Co-located with the Msg definition rather than\n   * threaded through a separate hook.\n   *\n   * Examples:\n   *   @routeGated(\"state.matrixState.kind === 'loaded'\")\n   *   @routeGated(\"state.route.kind === 'page' && state.route.slug === 'ranking'\")\n   *   @routeGated(\"state.auth.status === 'authenticated'\")\n   *\n   * Null when no `@routeGated` tag is present (variant defaults to\n   * its dispatchMode-driven affordance behavior).\n   */\n  routeGate: string | null\n}\n\nconst DEFAULT: MessageAnnotations = {\n  intent: null,\n  alwaysAffordable: false,\n  requiresConfirm: false,\n  dispatchMode: 'shared',\n  examples: [],\n  warning: null,\n  emits: [],\n  routeGate: null,\n}\n\n/**\n * Walk a Msg-like discriminated-union type alias and extract JSDoc\n * annotations attached to each union member. Returns null if no\n * recognizable union is found so callers can skip emission cleanly.\n *\n * Expected JSDoc grammar (order-independent):\n *   @intent(\"human readable\")\n *   @alwaysAffordable\n *   @requiresConfirm\n *   @humanOnly       — sugar for dispatchMode: 'human-only'\n *   @agentOnly       — sugar for dispatchMode: 'agent-only'\n *\n * Unknown tags are ignored; malformed @intent (no quoted string) is\n * treated as \"no intent\". `@humanOnly` and `@agentOnly` are mutually\n * exclusive — if both are present (which the ESLint rule\n * `agent-exclusive-annotations` reports as an error), the parser\n * falls back to `'shared'` so a misconfigured Msg variant doesn't\n * silently lock out one audience.\n */\nexport function extractMsgAnnotations(\n  source: string,\n  /**\n   * Name of the type alias to extract from. Defaults to `'Msg'` for\n   * convention. Passed by the cross-file resolver when the alias has\n   * been renamed through imports/re-exports — its local name in the\n   * declaring file may differ from `'Msg'`.\n   */\n  typeName: string = 'Msg',\n): Record<string, MessageAnnotations> | null {\n  const sf = ts.createSourceFile('msg.ts', source, ts.ScriptTarget.Latest, true)\n  const aliases: ts.TypeAliasDeclaration[] = []\n  sf.forEachChild((n) => {\n    if (ts.isTypeAliasDeclaration(n)) aliases.push(n)\n  })\n  const named = aliases.find((a) => a.name.text === typeName)\n  // Fallback: only when looking for the conventional 'Msg' name AND the\n  // file has no `type Msg = …`; pick any union type alias. With an\n  // explicit `typeName` from the resolver, we don't fall back — that\n  // would silently match the wrong alias.\n  const alias =\n    named ?? (typeName === 'Msg' ? aliases.find((a) => ts.isUnionTypeNode(a.type)) : undefined)\n  if (!alias || !ts.isUnionTypeNode(alias.type)) return null\n\n  const result: Record<string, MessageAnnotations> = {}\n  const types = alias.type.types\n  for (let i = 0; i < types.length; i++) {\n    const member = types[i]\n    if (member === undefined || !ts.isTypeLiteralNode(member)) continue\n    const variant = readDiscriminantLiteral(member)\n    if (!variant) continue\n    // Leading JSDoc for union member i is scanned from the end of the\n    // previous element (or union.pos for the first member), because\n    // TypeScript's parser places comment ranges relative to the token\n    // that follows them — and the | bar is not part of the TypeLiteralNode.\n    const prev = types[i - 1]\n    const scanPos = i === 0 || prev === undefined ? alias.type.pos : prev.end\n    const comment = readLeadingJSDoc(source, scanPos)\n    result[variant] = parseAnnotations(comment)\n  }\n  return Object.keys(result).length === 0 ? null : result\n}\n\nfunction readDiscriminantLiteral(lit: ts.TypeLiteralNode): string | null {\n  for (const m of lit.members) {\n    if (!ts.isPropertySignature(m)) continue\n    if (!m.name || !ts.isIdentifier(m.name) || m.name.text !== 'type') continue\n    if (!m.type || !ts.isLiteralTypeNode(m.type)) continue\n    const literal = m.type.literal\n    if (ts.isStringLiteral(literal)) return literal.text\n  }\n  return null\n}\n\nfunction readLeadingJSDoc(source: string, scanPos: number): string {\n  const ranges = ts.getLeadingCommentRanges(source, scanPos) ?? []\n  const docs = ranges\n    .filter((r) => r.kind === ts.SyntaxKind.MultiLineCommentTrivia)\n    .map((r) => source.slice(r.pos, r.end))\n    .filter((txt) => txt.startsWith('/**'))\n  return docs.join('\\n')\n}\n\nfunction parseAnnotations(comment: string): MessageAnnotations {\n  if (!comment) return { ...DEFAULT, examples: [] }\n  const intent = readIntent(comment)\n  const human = /@humanOnly\\b/.test(comment)\n  const agent = /@agentOnly\\b/.test(comment)\n  // Mutual-exclusion fallback: both tags present means a config bug;\n  // the ESLint rule reports it. At parse time, default to 'shared' so\n  // we don't silently lock out one audience based on tag order.\n  const dispatchMode: DispatchMode =\n    human && !agent ? 'human-only' : agent && !human ? 'agent-only' : 'shared'\n  return {\n    intent,\n    alwaysAffordable: /@alwaysAffordable\\b/.test(comment),\n    requiresConfirm: /@requiresConfirm\\b/.test(comment),\n    dispatchMode,\n    examples: readExamples(comment),\n    warning: readWarning(comment),\n    emits: readEmits(comment),\n    routeGate: readRouteGate(comment),\n  }\n}\n\n/**\n * Match `@routeGated(\"predicate-expression\")` (and curly-quote\n * variant). Returns the verbatim predicate string — the runtime\n * compiles it with `new Function('state', 'return (' + src + ')')`\n * and evaluates against the current state to gate affordances.\n *\n * Mirrors `@validates`'s grammar but with `state` as the bound\n * variable instead of `v` (since the predicate sees the whole app\n * state, not a single field value).\n */\nfunction readRouteGate(comment: string): string | null {\n  const match = comment.match(/@routeGated\\s*\\(\\s*[\"“]([^\"”]*)[\"”]\\s*\\)/)\n  return match?.[1] ?? null\n}\n\n/**\n * Match `@emits(\"k1\", \"k2\", ...)` — comma-separated list of effect\n * kind strings. Each entry can use straight or curly quotes; the\n * separator is `,` with arbitrary whitespace. Returns the kinds in\n * source order (deduped). Empty when the tag is absent or has no\n * quoted strings.\n */\nfunction readEmits(comment: string): string[] {\n  // Match the whole `@emits(...)` parenthesized group so we can\n  // re-parse the inner content for individual quoted strings. The\n  // outer match is non-greedy on the closing paren to avoid eating\n  // through later JSDoc.\n  const outer = comment.match(/@emits\\s*\\(([^)]*)\\)/)\n  if (!outer || outer[1] === undefined) return []\n  const inner = outer[1]\n  const seen = new Set<string>()\n  const out: string[] = []\n  const re = /[\"“]([^\"”]*)[\"”]/g\n  let m: RegExpExecArray | null\n  while ((m = re.exec(inner)) !== null) {\n    const v = m[1]\n    if (v === undefined || seen.has(v)) continue\n    seen.add(v)\n    out.push(v)\n  }\n  return out\n}\n\nfunction readIntent(comment: string): string | null {\n  const match = comment.match(/@intent\\s*\\(\\s*[\"\\u201c]([^\"\\u201d]*)[\"\\u201d]\\s*\\)/)\n  return match?.[1] ?? null\n}\n\n/**\n * Match every `@example(\"\\u2026\")` (and curly-quote variant) in source\n * order. Multiple tags on one variant are common \\u2014 typical-case,\n * edge-case-with-auth, etc. \\u2014 so the parser collects all of them\n * rather than picking the first.\n */\nfunction readExamples(comment: string): string[] {\n  const out: string[] = []\n  const re = /@example\\s*\\(\\s*[\"\\u201c]([^\"\\u201d]*)[\"\\u201d]\\s*\\)/g\n  let m: RegExpExecArray | null\n  while ((m = re.exec(comment)) !== null) {\n    if (m[1] !== undefined) out.push(m[1])\n  }\n  return out\n}\n\nfunction readWarning(comment: string): string | null {\n  const match = comment.match(/@warning\\s*\\(\\s*[\"\\u201c]([^\"\\u201d]*)[\"\\u201d]\\s*\\)/)\n  return match?.[1] ?? null\n}\n"]}

package/dist/msg-schema.d.ts

@@ -0,0 +1,130 @@
+import ts from 'typescript';
+/**
+ * The "bare type" of a field. Covers five cases:
+ *   - primitive keyword as a string: `'string'`, `'number'`, `'boolean'`, `'unknown'`
+ *   - literal union: `{enum: ['a', 'b']}` for strings, `{enum: [1, 2, 3]}`
+ *     for numbers, `{enum: [true]}` for booleans. Mixed-type literal
+ *     unions stay `'unknown'`.
+ *   - nested object shape: `{kind: 'object', shape: {...}}` — emitted when
+ *     a field's type is a local interface/type alias the extractor could
+ *     follow (depth-limited; cross-file references stay `'unknown'`).
+ *   - array of element type: `{kind: 'array', element: <bare type>}`.
+ *   - discriminated union of objects: `{kind: 'discriminated-union',
+ *     discriminant: 'kind', variants: {a: {...}, b: {...}}}`. Emitted
+ *     when every member of a union is an object literal sharing one
+ *     literal-string property name with distinct values. Symmetric with
+ *     how the top-level Msg union itself is encoded — same shape,
+ *     recursed.
+ *
+ * The synthesizer in `@llui/agent`'s `list_actions` walks these to build
+ * copy-paste-ready payload examples; the validator in `send_message`
+ * walks them too (treating object/array as "any" since deep validation
+ * is the reducer's job).
+ */
+export type MsgFieldType = string | {
+    enum: ReadonlyArray<string | number | boolean>;
+} | {
+    kind: 'object';
+    shape: Record<string, MsgField>;
+} | {
+    kind: 'array';
+    element: MsgFieldType;
+} | {
+    kind: 'discriminated-union';
+    discriminant: string;
+    variants: Record<string, Record<string, MsgField>>;
+};
+/**
+ * Rich per-field descriptor. Emitted only when there's something
+ * beyond the bare type to communicate — optionality, an explicit
+ * priority hint, a freeform agent hint, or a runtime validation
+ * predicate. When everything but `type` is unset, the producer emits
+ * the bare `MsgFieldType` instead so variants without annotations
+ * stay byte-cheap in the bundle.
+ */
+export interface MsgFieldRich {
+    type: MsgFieldType;
+    /** Mirrors TypeScript's `?:` optional marker. Required fields omit this. */
+    optional?: boolean;
+    /**
+     * Strength signal for optional fields. Borrows RFC 2119's `SHOULD`:
+     * the LLM ought to fill it in unless it has a specific reason not
+     * to. Required fields don't carry a priority — TS already conveys
+     * "must" via the type system. Currently the only level; future
+     * extensions could add `'recommended'` or similar.
+     */
+    priority?: 'should';
+    /** Freeform consequence-shaped explanation. Surfaced verbatim to
+     *  the LLM at affordance time. */
+    hint?: string;
+    /**
+     * Boolean JS expression that must hold for the field's value to be
+     * accepted. The expression has `v` bound to the field's runtime
+     * value; everything else is global (Math, JSON, RegExp, etc.).
+     * Authored as `@validates("expr")` JSDoc — the compiler captures
+     * the source string verbatim and the validator compiles it lazily
+     * with `new Function`, caching across calls.
+     *
+     * Examples:
+     *   @validates("v >= 0 && v <= 100")        // weight 0–100
+     *   @validates("v.length > 0")              // non-empty string
+     *   @validates("/^[a-z0-9-]+$/.test(v)")    // slug format
+     *
+     * The predicate runs ONLY at the agent boundary. Human-driven
+     * dispatches bypass it because TypeScript already validated the
+     * call site. Use for invariants the type system can't express
+     * (numeric ranges, format predicates, length bounds).
+     */
+    validates?: string;
+}
+export type MsgField = MsgFieldType | MsgFieldRich;
+export interface MsgSchema {
+    discriminant: string;
+    variants: Record<string, Record<string, MsgField>>;
+}
+/** True when `f` is a rich descriptor (object with `type` key). */
+export declare function isRichField(f: MsgField): f is MsgFieldRich;
+/**
+ * Build a TS expression for a single field descriptor in a MsgSchema's
+ * variant map. Used by `msgSchemaToLiteral` (this file) for the
+ * `__msgSchema` / `__effectSchema` emissions. Migrated from inline
+ * `buildFieldDescriptorExpr` in transform.ts (v2c/decomp-5).
+ */
+export declare function buildFieldDescriptorExpr(descriptor: MsgField, f: ts.NodeFactory): ts.Expression;
+/**
+ * Build the full `{ discriminant, variants }` object literal for a
+ * MsgSchema. Symmetric for `__msgSchema` and `__effectSchema` emission
+ * (both use the discriminated-union shape).
+ */
+export declare function msgSchemaToLiteral(schema: MsgSchema, f: ts.NodeFactory): ts.ObjectLiteralExpression;
+/** Extracts the bare type from either descriptor form. */
+export declare function fieldType(f: MsgField): MsgFieldType;
+export declare function extractMsgSchema(source: string, typeName?: string): MsgSchema | null;
+export declare function extractEffectSchema(source: string, typeName?: string): MsgSchema | null;
+/**
+ * Index of type aliases and interfaces visible from a source file,
+ * keyed by name. Lets the field-type resolver follow `Criterion[]` →
+ * `interface Criterion { … }` and emit a nested object shape rather
+ * than `'unknown'`.
+ *
+ * The cross-file resolver pipeline (`cross-file-resolver.ts`) builds
+ * an enriched index that includes types imported from sibling files —
+ * follow `GridSorting` → `'rank' | 'crit-X' | 'crit-Y'` → `{enum: […]}`
+ * even when the alias lives in `./state.ts` not the Msg-defining file.
+ */
+export type TypeIndex = Map<string, ts.TypeNode | ts.InterfaceDeclaration>;
+/**
+ * Build a single field descriptor from a property signature: type,
+ * optionality, and any `@should("…")` JSDoc hint. Emits the compact
+ * bare form when there's nothing extra to communicate; otherwise the
+ * rich `{type, optional?, priority?, hint?}` shape.
+ *
+ * Exported so the cross-file resolver (which walks the same property
+ * signatures when the Msg type lives in a different file from the
+ * `component()` call) can produce identical descriptors. Without
+ * sharing this helper, JSDoc hints would silently disappear whenever
+ * a Msg union got resolved across module boundaries.
+ */
+export declare function buildFieldDescriptor(member: ts.PropertySignature, source: string, typeIndex?: TypeIndex): MsgField;
+export declare function resolveFieldType(type: ts.TypeNode, typeIndex?: TypeIndex, depth?: number): MsgFieldType;
+//# 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":"AAAA,OAAO,EAAE,MAAM,YAAY,CAAA;AAE3B;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,YAAY,GACpB,MAAM,GACN;IAAE,IAAI,EAAE,aAAa,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAA;CAAE,GAClD;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAA;CAAE,GACnD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,YAAY,CAAA;CAAE,GACxC;IACE,IAAI,EAAE,qBAAqB,CAAA;IAC3B,YAAY,EAAE,MAAM,CAAA;IACpB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAA;CACnD,CAAA;AAEL;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,YAAY,CAAA;IAClB,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB;sCACkC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;;;;;;;;;;;;;;OAiBG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,MAAM,QAAQ,GAAG,YAAY,GAAG,YAAY,CAAA;AAElD,MAAM,WAAW,SAAS;IACxB,YAAY,EAAE,MAAM,CAAA;IACpB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAA;CACnD;AAED,mEAAmE;AACnE,wBAAgB,WAAW,CAAC,CAAC,EAAE,QAAQ,GAAG,CAAC,IAAI,YAAY,CAE1D;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,QAAQ,EAAE,CAAC,EAAE,EAAE,CAAC,WAAW,GAAG,EAAE,CAAC,UAAU,CAqE/F;AAQD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,SAAS,EACjB,CAAC,EAAE,EAAE,CAAC,WAAW,GAChB,EAAE,CAAC,uBAAuB,CA0B5B;AAED,0DAA0D;AAC1D,wBAAgB,SAAS,CAAC,CAAC,EAAE,QAAQ,GAAG,YAAY,CAEnD;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAc,GAAG,SAAS,GAAG,IAAI,CAE3F;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAiB,GAAG,SAAS,GAAG,IAAI,CAEjG;AAqBD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,SAAS,GAAG,GAAG,CAAC,MAAM,EAAE,EAAE,CAAC,QAAQ,GAAG,EAAE,CAAC,oBAAoB,CAAC,CAAA;AAsD1E;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,EAAE,CAAC,iBAAiB,EAC5B,MAAM,EAAE,MAAM,EACd,SAAS,GAAE,SAAqB,GAC/B,QAAQ,CAwBV;AAmVD,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,EAAE,CAAC,QAAQ,EACjB,SAAS,GAAE,SAAqB,EAChC,KAAK,SAAkB,GACtB,YAAY,CA8Hd"}