@llui/vite-plugin 0.0.31 → 0.0.33

package/dist/msg-annotations.d.ts

@@ -1,8 +1,39 @@
+export type DispatchMode = 'shared' | 'human-only' | 'agent-only';
 export type MessageAnnotations = {
     intent: string | null;
     alwaysAffordable: boolean;
     requiresConfirm: boolean;
-    humanOnly: 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[];
 };
 /**
  * Walk a Msg-like discriminated-union type alias and extract JSDoc
@@ -13,11 +44,22 @@ export type MessageAnnotations = {
  *   @intent("human readable")
  *   @alwaysAffordable
  *   @requiresConfirm
- *   @humanOnly
+ *   @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". The four flags are booleans; any occurrence
- * of the tag sets it true.
+ * 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): Record<string, MessageAnnotations> | null;
+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

@@ -1 +1 @@
-{"version":3,"file":"msg-annotations.d.ts","sourceRoot":"","sources":["../src/msg-annotations.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,kBAAkB,GAAG;IAC/B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,gBAAgB,EAAE,OAAO,CAAA;IACzB,eAAe,EAAE,OAAO,CAAA;IACxB,SAAS,EAAE,OAAO,CAAA;CACnB,CAAA;AASD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,GAAG,IAAI,CA2B/F"}
+{"version":3,"file":"msg-annotations.d.ts","sourceRoot":"","sources":["../src/msg-annotations.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,YAAY,GAAG,YAAY,CAAA;AAEjE,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;CAChB,CAAA;AAYD;;;;;;;;;;;;;;;;;;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

@@ -3,7 +3,10 @@ const DEFAULT = {
     intent: null,
     alwaysAffordable: false,
     requiresConfirm: false,
-    humanOnly: false,
+    dispatchMode: 'shared',
+    examples: [],
+    warning: null,
+    emits: [],
 };
 /**
  * Walk a Msg-like discriminated-union type alias and extract JSDoc
@@ -14,21 +17,36 @@ const DEFAULT = {
  *   @intent("human readable")
  *   @alwaysAffordable
  *   @requiresConfirm
- *   @humanOnly
+ *   @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". The four flags are booleans; any occurrence
- * of the tag sets it true.
+ * 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) {
+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 === 'Msg');
-    const alias = named ?? aliases.find((a) => ts.isUnionTypeNode(a.type));
+    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 = {};
@@ -75,17 +93,75 @@ function readLeadingJSDoc(source, scanPos) {
 }
 function parseAnnotations(comment) {
     if (!comment)
-        return { ...DEFAULT };
+        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),
-        humanOnly: /@humanOnly\b/.test(comment),
+        dispatchMode,
+        examples: readExamples(comment),
+        warning: readWarning(comment),
+        emits: readEmits(comment),
     };
 }
+/**
+ * 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

@@ -1 +1 @@
-{"version":3,"file":"msg-annotations.js","sourceRoot":"","sources":["../src/msg-annotations.ts"],"names":[],"mappings":"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","sourcesContent":["import ts from 'typescript'\n\nexport type MessageAnnotations = {\n  intent: string | null\n  alwaysAffordable: boolean\n  requiresConfirm: boolean\n  humanOnly: boolean\n}\n\nconst DEFAULT: MessageAnnotations = {\n  intent: null,\n  alwaysAffordable: false,\n  requiresConfirm: false,\n  humanOnly: false,\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\n *\n * Unknown tags are ignored; malformed @intent (no quoted string) is\n * treated as \"no intent\". The four flags are booleans; any occurrence\n * of the tag sets it true.\n */\nexport function extractMsgAnnotations(source: string): 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 === 'Msg')\n  const alias = named ?? aliases.find((a) => ts.isUnionTypeNode(a.type))\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 }\n  const intent = readIntent(comment)\n  return {\n    intent,\n    alwaysAffordable: /@alwaysAffordable\\b/.test(comment),\n    requiresConfirm: /@requiresConfirm\\b/.test(comment),\n    humanOnly: /@humanOnly\\b/.test(comment),\n  }\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"]}
+{"version":3,"file":"msg-annotations.js","sourceRoot":"","sources":["../src/msg-annotations.ts"],"names":[],"mappings":"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","sourcesContent":["import ts from 'typescript'\n\nexport type DispatchMode = 'shared' | 'human-only' | 'agent-only'\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\nconst DEFAULT: MessageAnnotations = {\n  intent: null,\n  alwaysAffordable: false,\n  requiresConfirm: false,\n  dispatchMode: 'shared',\n  examples: [],\n  warning: null,\n  emits: [],\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  }\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

@@ -1,9 +1,85 @@
+import ts from 'typescript';
+/**
+ * The "bare type" of a field. Covers four cases:
+ *   - primitive keyword as a string: `'string'`, `'number'`, `'boolean'`, `'unknown'`
+ *   - string-literal union: `{enum: ['a', 'b']}`
+ *   - 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>}`.
+ *
+ * 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: string[];
+} | {
+    kind: 'object';
+    shape: Record<string, MsgField>;
+} | {
+    kind: 'array';
+    element: MsgFieldType;
+};
+/**
+ * Rich per-field descriptor. Emitted only when there's something
+ * beyond the bare type to communicate — optionality, an explicit
+ * priority hint, or a freeform agent hint. 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;
+}
+export type MsgField = MsgFieldType | MsgFieldRich;
 export interface MsgSchema {
     discriminant: string;
-    variants: Record<string, Record<string, string | {
-        enum: string[];
-    }>>;
+    variants: Record<string, Record<string, MsgField>>;
 }
-export declare function extractMsgSchema(source: string): MsgSchema | null;
-export declare function extractEffectSchema(source: string): MsgSchema | null;
+/** True when `f` is a rich descriptor (object with `type` key). */
+export declare function isRichField(f: MsgField): f is MsgFieldRich;
+/** 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

@@ -1 +1 @@
-{"version":3,"file":"msg-schema.d.ts","sourceRoot":"","sources":["../src/msg-schema.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,SAAS;IACxB,YAAY,EAAE,MAAM,CAAA;IACpB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC,CAAA;CACtE;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAEjE;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAEpE"}
+{"version":3,"file":"msg-schema.d.ts","sourceRoot":"","sources":["../src/msg-schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,YAAY,CAAA;AAE3B;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,YAAY,GACpB,MAAM,GACN;IAAE,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,GAClB;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,CAAA;AAE5C;;;;;;GAMG;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;CACd;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,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,CAkBV;AAeD,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,EAAE,CAAC,QAAQ,EACjB,SAAS,GAAE,SAAqB,EAChC,KAAK,SAAkB,GACtB,YAAY,CA0Fd"}

package/dist/msg-schema.js

@@ -1,29 +1,50 @@
 import ts from 'typescript';
-export function extractMsgSchema(source) {
-    return extractDiscriminatedUnionSchema(source, 'Msg');
+/** True when `f` is a rich descriptor (object with `type` key). */
+export function isRichField(f) {
+    return typeof f === 'object' && f !== null && !Array.isArray(f) && 'type' in f;
 }
-export function extractEffectSchema(source) {
-    return extractDiscriminatedUnionSchema(source, 'Effect');
+/** Extracts the bare type from either descriptor form. */
+export function fieldType(f) {
+    return isRichField(f) ? f.type : f;
+}
+export function extractMsgSchema(source, typeName = 'Msg') {
+    return extractDiscriminatedUnionSchema(source, typeName);
+}
+export function extractEffectSchema(source, typeName = 'Effect') {
+    return extractDiscriminatedUnionSchema(source, typeName);
 }
 function extractDiscriminatedUnionSchema(source, typeName) {
     const sf = ts.createSourceFile('input.ts', source, ts.ScriptTarget.Latest, true);
+    const typeIndex = buildTypeIndex(sf);
     for (const stmt of sf.statements) {
         if (!ts.isTypeAliasDeclaration(stmt))
             continue;
         if (stmt.name.text !== typeName)
             continue;
         const variants = {};
-        collectVariants(stmt.type, variants);
+        collectVariants(stmt.type, variants, source, typeIndex);
         if (Object.keys(variants).length === 0)
             return null;
         return { discriminant: 'type', variants };
     }
     return null;
 }
-function collectVariants(type, variants) {
+function buildTypeIndex(sf) {
+    const index = new Map();
+    for (const stmt of sf.statements) {
+        if (ts.isTypeAliasDeclaration(stmt)) {
+            index.set(stmt.name.text, stmt.type);
+        }
+        else if (ts.isInterfaceDeclaration(stmt)) {
+            index.set(stmt.name.text, stmt);
+        }
+    }
+    return index;
+}
+function collectVariants(type, variants, source, typeIndex) {
     if (ts.isUnionTypeNode(type)) {
         for (const member of type.types) {
-            collectVariants(member, variants);
+            collectVariants(member, variants, source, typeIndex);
         }
         return;
     }
@@ -42,18 +63,57 @@ function collectVariants(type, variants) {
                 }
                 continue;
             }
-            if (!memberType) {
-                fields[name] = 'unknown';
-                continue;
-            }
-            fields[name] = resolveFieldType(memberType);
+            fields[name] = buildFieldDescriptor(member, source, typeIndex);
         }
         if (discriminantValue) {
             variants[discriminantValue] = fields;
         }
     }
 }
-function resolveFieldType(type) {
+/**
+ * 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 function buildFieldDescriptor(member, source, typeIndex = new Map()) {
+    const baseType = member.type
+        ? resolveFieldType(member.type, typeIndex, MAX_FIELD_DEPTH)
+        : 'unknown';
+    const optional = member.questionToken !== undefined;
+    const jsdoc = readMemberJSDoc(source, member);
+    const hint = readShouldHint(jsdoc);
+    if (!optional && hint === null) {
+        return baseType;
+    }
+    const rich = { type: baseType };
+    if (optional)
+        rich.optional = true;
+    if (hint !== null) {
+        rich.priority = 'should';
+        rich.hint = hint;
+    }
+    return rich;
+}
+/**
+ * Recursion bound for nested type resolution. Stops the extractor
+ * before it spirals on self-referential or mutually-recursive types
+ * (`type Tree = { children: Tree[] }`). At depth 0 every reference
+ * collapses to `'unknown'`; the synthesizer emits `null` and the
+ * agent falls back to free-form filling.
+ *
+ * 3 covers the common cases (Msg payload → Criterion → ValueMeta),
+ * keeps the bundle bounded, and is well under the Tarjan-style
+ * depths needed for actual recursive types.
+ */
+const MAX_FIELD_DEPTH = 3;
+export function resolveFieldType(type, typeIndex = new Map(), depth = MAX_FIELD_DEPTH) {
     // Primitive keywords
     if (type.kind === ts.SyntaxKind.StringKeyword)
         return 'string';
@@ -78,6 +138,134 @@ function resolveFieldType(type) {
             return { enum: literals };
         }
     }
+    // Below this point, all branches need depth budget. Bail out cheaply.
+    if (depth <= 0)
+        return 'unknown';
+    // Inline object literal — `{a: number; b: string}` directly.
+    if (ts.isTypeLiteralNode(type)) {
+        return { kind: 'object', shape: collectInlineShape(type, typeIndex, depth - 1) };
+    }
+    // Array type — `T[]` and `readonly T[]`.
+    if (ts.isArrayTypeNode(type)) {
+        return { kind: 'array', element: resolveFieldType(type.elementType, typeIndex, depth - 1) };
+    }
+    // Generic Array<T> (less common in app code but compiler may produce it).
+    if (ts.isTypeReferenceNode(type) &&
+        ts.isIdentifier(type.typeName) &&
+        type.typeName.text === 'Array' &&
+        type.typeArguments?.length === 1 &&
+        type.typeArguments[0]) {
+        return {
+            kind: 'array',
+            element: resolveFieldType(type.typeArguments[0], typeIndex, depth - 1),
+        };
+    }
+    // ReadonlyArray<T> → same shape; the readonly modifier is purely a
+    // TypeScript-side concern that the agent never observes at runtime.
+    if (ts.isTypeReferenceNode(type) &&
+        ts.isIdentifier(type.typeName) &&
+        type.typeName.text === 'ReadonlyArray' &&
+        type.typeArguments?.length === 1 &&
+        type.typeArguments[0]) {
+        return {
+            kind: 'array',
+            element: resolveFieldType(type.typeArguments[0], typeIndex, depth - 1),
+        };
+    }
+    // `readonly T[]` parses as TypeOperator(readonly) wrapping ArrayType.
+    if (ts.isTypeOperatorNode(type) && type.operator === ts.SyntaxKind.ReadonlyKeyword) {
+        return resolveFieldType(type.type, typeIndex, depth);
+    }
+    // Named type reference — chase it through the local index.
+    if (ts.isTypeReferenceNode(type) && ts.isIdentifier(type.typeName)) {
+        const target = typeIndex.get(type.typeName.text);
+        if (target) {
+            if (ts.isInterfaceDeclaration(target)) {
+                return {
+                    kind: 'object',
+                    shape: collectInterfaceShape(target, typeIndex, depth - 1),
+                };
+            }
+            // Type alias — recurse on its body. `type Foo = …` could resolve
+            // to anything (object literal, array, union, primitive); each
+            // already has its own branch above.
+            return resolveFieldType(target, typeIndex, depth - 1);
+        }
+        // Reference to a type the index doesn't know about — typically
+        // imported from another module. Cross-file resolution is the
+        // separate cross-file-resolver pipeline's job; leave this as
+        // unknown rather than fabricating a misleading shape.
+        return 'unknown';
+    }
     return 'unknown';
 }
+function collectInlineShape(lit, typeIndex, depth) {
+    const shape = {};
+    for (const member of lit.members) {
+        if (!ts.isPropertySignature(member) || !member.name || !ts.isIdentifier(member.name))
+            continue;
+        const name = member.name.text;
+        const baseType = member.type
+            ? resolveFieldType(member.type, typeIndex, depth)
+            : 'unknown';
+        const optional = member.questionToken !== undefined;
+        if (!optional) {
+            shape[name] = baseType;
+        }
+        else {
+            shape[name] = { type: baseType, optional: true };
+        }
+    }
+    return shape;
+}
+function collectInterfaceShape(iface, typeIndex, depth) {
+    const shape = {};
+    for (const member of iface.members) {
+        if (!ts.isPropertySignature(member) || !member.name || !ts.isIdentifier(member.name))
+            continue;
+        const name = member.name.text;
+        const baseType = member.type
+            ? resolveFieldType(member.type, typeIndex, depth)
+            : 'unknown';
+        const optional = member.questionToken !== undefined;
+        if (!optional) {
+            shape[name] = baseType;
+        }
+        else {
+            shape[name] = { type: baseType, optional: true };
+        }
+    }
+    return shape;
+}
+/**
+ * Read the leading JSDoc block immediately above `member`. The
+ * TypeScript parser doesn't attach JSDoc to interior property
+ * signatures, so we re-scan the source between the previous member's
+ * end (or the type-literal's `{`) and this member's start, and return
+ * the last `/** … *\/` block found there. Returns `''` when none.
+ */
+function readMemberJSDoc(source, member) {
+    const ranges = ts.getLeadingCommentRanges(source, member.pos) ?? [];
+    // Walk in order, keeping only `/** */` blocks. Multiple back-to-back
+    // JSDocs concatenate (matches msg-annotations.ts's existing behavior).
+    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');
+}
+/**
+ * Match `@should("…")` (and curly-quote variant) anywhere in the
+ * JSDoc. Mirrors msg-annotations.ts's `@intent` parser — same grammar,
+ * same tolerance for either ASCII or curly quotes.
+ *
+ * Returns the unescaped string content, or null when the tag is
+ * absent or malformed.
+ */
+function readShouldHint(comment) {
+    if (!comment)
+        return null;
+    const match = comment.match(/@should\s*\(\s*["“]([^"”]*)["”]\s*\)/);
+    return match?.[1] ?? null;
+}
 //# sourceMappingURL=msg-schema.js.map