@llui/vite-plugin 0.0.31 → 0.0.34

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

package/dist/msg-schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"msg-schema.js","sourceRoot":"","sources":["../src/msg-schema.ts"],"names":[],"mappings":"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","sourcesContent":["import ts from 'typescript'\n\nexport interface MsgSchema {\n  discriminant: string\n  variants: Record<string, Record<string, string | { enum: string[] }>>\n}\n\nexport function extractMsgSchema(source: string): MsgSchema | null {\n  return extractDiscriminatedUnionSchema(source, 'Msg')\n}\n\nexport function extractEffectSchema(source: string): MsgSchema | null {\n  return extractDiscriminatedUnionSchema(source, 'Effect')\n}\n\nfunction extractDiscriminatedUnionSchema(source: string, typeName: string): MsgSchema | null {\n  const sf = ts.createSourceFile('input.ts', source, ts.ScriptTarget.Latest, true)\n\n  for (const stmt of sf.statements) {\n    if (!ts.isTypeAliasDeclaration(stmt)) continue\n    if (stmt.name.text !== typeName) continue\n\n    const variants: MsgSchema['variants'] = {}\n    collectVariants(stmt.type, variants)\n\n    if (Object.keys(variants).length === 0) return null\n\n    return { discriminant: 'type', variants }\n  }\n\n  return null\n}\n\nfunction collectVariants(type: ts.TypeNode, variants: MsgSchema['variants']): void {\n  if (ts.isUnionTypeNode(type)) {\n    for (const member of type.types) {\n      collectVariants(member, variants)\n    }\n    return\n  }\n\n  if (ts.isTypeLiteralNode(type)) {\n    let discriminantValue: string | null = null\n    const fields: Record<string, string | { enum: string[] }> = {}\n\n    for (const member of type.members) {\n      if (!ts.isPropertySignature(member) || !member.name || !ts.isIdentifier(member.name)) continue\n\n      const name = member.name.text\n      const memberType = member.type\n\n      if (name === 'type' && memberType) {\n        // Extract the discriminant value\n        if (ts.isLiteralTypeNode(memberType) && ts.isStringLiteral(memberType.literal)) {\n          discriminantValue = memberType.literal.text\n        }\n        continue\n      }\n\n      if (!memberType) {\n        fields[name] = 'unknown'\n        continue\n      }\n\n      fields[name] = resolveFieldType(memberType)\n    }\n\n    if (discriminantValue) {\n      variants[discriminantValue] = fields\n    }\n  }\n}\n\nfunction resolveFieldType(type: ts.TypeNode): string | { enum: string[] } {\n  // Primitive keywords\n  if (type.kind === ts.SyntaxKind.StringKeyword) return 'string'\n  if (type.kind === ts.SyntaxKind.NumberKeyword) return 'number'\n  if (type.kind === ts.SyntaxKind.BooleanKeyword) return 'boolean'\n\n  // String literal union: 'a' | 'b' | 'c'\n  if (ts.isUnionTypeNode(type)) {\n    const literals: string[] = []\n    let allLiterals = true\n    for (const member of type.types) {\n      if (ts.isLiteralTypeNode(member) && ts.isStringLiteral(member.literal)) {\n        literals.push(member.literal.text)\n      } else {\n        allLiterals = false\n        break\n      }\n    }\n    if (allLiterals && literals.length > 0) {\n      return { enum: literals }\n    }\n  }\n\n  return 'unknown'\n}\n"]}
+{"version":3,"file":"msg-schema.js","sourceRoot":"","sources":["../src/msg-schema.ts"],"names":[],"mappings":"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","sourcesContent":["import ts from 'typescript'\n\n/**\n * The \"bare type\" of a field. Covers four cases:\n *   - primitive keyword as a string: `'string'`, `'number'`, `'boolean'`, `'unknown'`\n *   - string-literal union: `{enum: ['a', 'b']}`\n *   - nested object shape: `{kind: 'object', shape: {...}}` — emitted when\n *     a field's type is a local interface/type alias the extractor could\n *     follow (depth-limited; cross-file references stay `'unknown'`).\n *   - array of element type: `{kind: 'array', element: <bare type>}`.\n *\n * The synthesizer in `@llui/agent`'s `list_actions` walks these to build\n * copy-paste-ready payload examples; the validator in `send_message`\n * walks them too (treating object/array as \"any\" since deep validation\n * is the reducer's job).\n */\nexport type MsgFieldType =\n  | string\n  | { enum: string[] }\n  | { kind: 'object'; shape: Record<string, MsgField> }\n  | { kind: 'array'; element: MsgFieldType }\n\n/**\n * Rich per-field descriptor. Emitted only when there's something\n * beyond the bare type to communicate — optionality, an explicit\n * priority hint, or a freeform agent hint. When everything but `type`\n * is unset, the producer emits the bare `MsgFieldType` instead so\n * variants without annotations stay byte-cheap in the bundle.\n */\nexport interface MsgFieldRich {\n  type: MsgFieldType\n  /** Mirrors TypeScript's `?:` optional marker. Required fields omit this. */\n  optional?: boolean\n  /**\n   * Strength signal for optional fields. Borrows RFC 2119's `SHOULD`:\n   * the LLM ought to fill it in unless it has a specific reason not\n   * to. Required fields don't carry a priority — TS already conveys\n   * \"must\" via the type system. Currently the only level; future\n   * extensions could add `'recommended'` or similar.\n   */\n  priority?: 'should'\n  /** Freeform consequence-shaped explanation. Surfaced verbatim to\n   *  the LLM at affordance time. */\n  hint?: string\n}\n\nexport type MsgField = MsgFieldType | MsgFieldRich\n\nexport interface MsgSchema {\n  discriminant: string\n  variants: Record<string, Record<string, MsgField>>\n}\n\n/** True when `f` is a rich descriptor (object with `type` key). */\nexport function isRichField(f: MsgField): f is MsgFieldRich {\n  return typeof f === 'object' && f !== null && !Array.isArray(f) && 'type' in f\n}\n\n/** Extracts the bare type from either descriptor form. */\nexport function fieldType(f: MsgField): MsgFieldType {\n  return isRichField(f) ? f.type : f\n}\n\nexport function extractMsgSchema(source: string, typeName: string = 'Msg'): MsgSchema | null {\n  return extractDiscriminatedUnionSchema(source, typeName)\n}\n\nexport function extractEffectSchema(source: string, typeName: string = 'Effect'): MsgSchema | null {\n  return extractDiscriminatedUnionSchema(source, typeName)\n}\n\nfunction extractDiscriminatedUnionSchema(source: string, typeName: string): MsgSchema | null {\n  const sf = ts.createSourceFile('input.ts', source, ts.ScriptTarget.Latest, true)\n  const typeIndex = buildTypeIndex(sf)\n\n  for (const stmt of sf.statements) {\n    if (!ts.isTypeAliasDeclaration(stmt)) continue\n    if (stmt.name.text !== typeName) continue\n\n    const variants: MsgSchema['variants'] = {}\n    collectVariants(stmt.type, variants, source, typeIndex)\n\n    if (Object.keys(variants).length === 0) return null\n\n    return { discriminant: 'type', variants }\n  }\n\n  return null\n}\n\n/**\n * Index of type aliases and interfaces visible from a source file,\n * keyed by name. Lets the field-type resolver follow `Criterion[]` →\n * `interface Criterion { … }` and emit a nested object shape rather\n * than `'unknown'`.\n *\n * The cross-file resolver pipeline (`cross-file-resolver.ts`) builds\n * an enriched index that includes types imported from sibling files —\n * follow `GridSorting` → `'rank' | 'crit-X' | 'crit-Y'` → `{enum: […]}`\n * even when the alias lives in `./state.ts` not the Msg-defining file.\n */\nexport type TypeIndex = Map<string, ts.TypeNode | ts.InterfaceDeclaration>\n\nfunction buildTypeIndex(sf: ts.SourceFile): TypeIndex {\n  const index: TypeIndex = new Map()\n  for (const stmt of sf.statements) {\n    if (ts.isTypeAliasDeclaration(stmt)) {\n      index.set(stmt.name.text, stmt.type)\n    } else if (ts.isInterfaceDeclaration(stmt)) {\n      index.set(stmt.name.text, stmt)\n    }\n  }\n  return index\n}\n\nfunction collectVariants(\n  type: ts.TypeNode,\n  variants: MsgSchema['variants'],\n  source: string,\n  typeIndex: TypeIndex,\n): void {\n  if (ts.isUnionTypeNode(type)) {\n    for (const member of type.types) {\n      collectVariants(member, variants, source, typeIndex)\n    }\n    return\n  }\n\n  if (ts.isTypeLiteralNode(type)) {\n    let discriminantValue: string | null = null\n    const fields: Record<string, MsgField> = {}\n\n    for (const member of type.members) {\n      if (!ts.isPropertySignature(member) || !member.name || !ts.isIdentifier(member.name)) continue\n\n      const name = member.name.text\n      const memberType = member.type\n\n      if (name === 'type' && memberType) {\n        // Extract the discriminant value\n        if (ts.isLiteralTypeNode(memberType) && ts.isStringLiteral(memberType.literal)) {\n          discriminantValue = memberType.literal.text\n        }\n        continue\n      }\n\n      fields[name] = buildFieldDescriptor(member, source, typeIndex)\n    }\n\n    if (discriminantValue) {\n      variants[discriminantValue] = fields\n    }\n  }\n}\n\n/**\n * Build a single field descriptor from a property signature: type,\n * optionality, and any `@should(\"…\")` JSDoc hint. Emits the compact\n * bare form when there's nothing extra to communicate; otherwise the\n * rich `{type, optional?, priority?, hint?}` shape.\n *\n * Exported so the cross-file resolver (which walks the same property\n * signatures when the Msg type lives in a different file from the\n * `component()` call) can produce identical descriptors. Without\n * sharing this helper, JSDoc hints would silently disappear whenever\n * a Msg union got resolved across module boundaries.\n */\nexport function buildFieldDescriptor(\n  member: ts.PropertySignature,\n  source: string,\n  typeIndex: TypeIndex = new Map(),\n): MsgField {\n  const baseType: MsgFieldType = member.type\n    ? resolveFieldType(member.type, typeIndex, MAX_FIELD_DEPTH)\n    : 'unknown'\n  const optional = member.questionToken !== undefined\n  const jsdoc = readMemberJSDoc(source, member)\n  const hint = readShouldHint(jsdoc)\n\n  if (!optional && hint === null) {\n    return baseType\n  }\n  const rich: MsgFieldRich = { type: baseType }\n  if (optional) rich.optional = true\n  if (hint !== null) {\n    rich.priority = 'should'\n    rich.hint = hint\n  }\n  return rich\n}\n\n/**\n * Recursion bound for nested type resolution. Stops the extractor\n * before it spirals on self-referential or mutually-recursive types\n * (`type Tree = { children: Tree[] }`). At depth 0 every reference\n * collapses to `'unknown'`; the synthesizer emits `null` and the\n * agent falls back to free-form filling.\n *\n * 3 covers the common cases (Msg payload → Criterion → ValueMeta),\n * keeps the bundle bounded, and is well under the Tarjan-style\n * depths needed for actual recursive types.\n */\nconst MAX_FIELD_DEPTH = 3\n\nexport function resolveFieldType(\n  type: ts.TypeNode,\n  typeIndex: TypeIndex = new Map(),\n  depth = MAX_FIELD_DEPTH,\n): MsgFieldType {\n  // Primitive keywords\n  if (type.kind === ts.SyntaxKind.StringKeyword) return 'string'\n  if (type.kind === ts.SyntaxKind.NumberKeyword) return 'number'\n  if (type.kind === ts.SyntaxKind.BooleanKeyword) return 'boolean'\n\n  // String literal union: 'a' | 'b' | 'c'\n  if (ts.isUnionTypeNode(type)) {\n    const literals: string[] = []\n    let allLiterals = true\n    for (const member of type.types) {\n      if (ts.isLiteralTypeNode(member) && ts.isStringLiteral(member.literal)) {\n        literals.push(member.literal.text)\n      } else {\n        allLiterals = false\n        break\n      }\n    }\n    if (allLiterals && literals.length > 0) {\n      return { enum: literals }\n    }\n  }\n\n  // Below this point, all branches need depth budget. Bail out cheaply.\n  if (depth <= 0) return 'unknown'\n\n  // Inline object literal — `{a: number; b: string}` directly.\n  if (ts.isTypeLiteralNode(type)) {\n    return { kind: 'object', shape: collectInlineShape(type, typeIndex, depth - 1) }\n  }\n\n  // Array type — `T[]` and `readonly T[]`.\n  if (ts.isArrayTypeNode(type)) {\n    return { kind: 'array', element: resolveFieldType(type.elementType, typeIndex, depth - 1) }\n  }\n  // Generic Array<T> (less common in app code but compiler may produce it).\n  if (\n    ts.isTypeReferenceNode(type) &&\n    ts.isIdentifier(type.typeName) &&\n    type.typeName.text === 'Array' &&\n    type.typeArguments?.length === 1 &&\n    type.typeArguments[0]\n  ) {\n    return {\n      kind: 'array',\n      element: resolveFieldType(type.typeArguments[0], typeIndex, depth - 1),\n    }\n  }\n  // ReadonlyArray<T> → same shape; the readonly modifier is purely a\n  // TypeScript-side concern that the agent never observes at runtime.\n  if (\n    ts.isTypeReferenceNode(type) &&\n    ts.isIdentifier(type.typeName) &&\n    type.typeName.text === 'ReadonlyArray' &&\n    type.typeArguments?.length === 1 &&\n    type.typeArguments[0]\n  ) {\n    return {\n      kind: 'array',\n      element: resolveFieldType(type.typeArguments[0], typeIndex, depth - 1),\n    }\n  }\n  // `readonly T[]` parses as TypeOperator(readonly) wrapping ArrayType.\n  if (ts.isTypeOperatorNode(type) && type.operator === ts.SyntaxKind.ReadonlyKeyword) {\n    return resolveFieldType(type.type, typeIndex, depth)\n  }\n\n  // Named type reference — chase it through the local index.\n  if (ts.isTypeReferenceNode(type) && ts.isIdentifier(type.typeName)) {\n    const target = typeIndex.get(type.typeName.text)\n    if (target) {\n      if (ts.isInterfaceDeclaration(target)) {\n        return {\n          kind: 'object',\n          shape: collectInterfaceShape(target, typeIndex, depth - 1),\n        }\n      }\n      // Type alias — recurse on its body. `type Foo = …` could resolve\n      // to anything (object literal, array, union, primitive); each\n      // already has its own branch above.\n      return resolveFieldType(target, typeIndex, depth - 1)\n    }\n    // Reference to a type the index doesn't know about — typically\n    // imported from another module. Cross-file resolution is the\n    // separate cross-file-resolver pipeline's job; leave this as\n    // unknown rather than fabricating a misleading shape.\n    return 'unknown'\n  }\n\n  return 'unknown'\n}\n\nfunction collectInlineShape(\n  lit: ts.TypeLiteralNode,\n  typeIndex: TypeIndex,\n  depth: number,\n): Record<string, MsgField> {\n  const shape: Record<string, MsgField> = {}\n  for (const member of lit.members) {\n    if (!ts.isPropertySignature(member) || !member.name || !ts.isIdentifier(member.name)) continue\n    const name = member.name.text\n    const baseType: MsgFieldType = member.type\n      ? resolveFieldType(member.type, typeIndex, depth)\n      : 'unknown'\n    const optional = member.questionToken !== undefined\n    if (!optional) {\n      shape[name] = baseType\n    } else {\n      shape[name] = { type: baseType, optional: true }\n    }\n  }\n  return shape\n}\n\nfunction collectInterfaceShape(\n  iface: ts.InterfaceDeclaration,\n  typeIndex: TypeIndex,\n  depth: number,\n): Record<string, MsgField> {\n  const shape: Record<string, MsgField> = {}\n  for (const member of iface.members) {\n    if (!ts.isPropertySignature(member) || !member.name || !ts.isIdentifier(member.name)) continue\n    const name = member.name.text\n    const baseType: MsgFieldType = member.type\n      ? resolveFieldType(member.type, typeIndex, depth)\n      : 'unknown'\n    const optional = member.questionToken !== undefined\n    if (!optional) {\n      shape[name] = baseType\n    } else {\n      shape[name] = { type: baseType, optional: true }\n    }\n  }\n  return shape\n}\n\n/**\n * Read the leading JSDoc block immediately above `member`. The\n * TypeScript parser doesn't attach JSDoc to interior property\n * signatures, so we re-scan the source between the previous member's\n * end (or the type-literal's `{`) and this member's start, and return\n * the last `/** … *\\/` block found there. Returns `''` when none.\n */\nfunction readMemberJSDoc(source: string, member: ts.PropertySignature): string {\n  const ranges = ts.getLeadingCommentRanges(source, member.pos) ?? []\n  // Walk in order, keeping only `/** */` blocks. Multiple back-to-back\n  // JSDocs concatenate (matches msg-annotations.ts's existing behavior).\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\n/**\n * Match `@should(\"…\")` (and curly-quote variant) anywhere in the\n * JSDoc. Mirrors msg-annotations.ts's `@intent` parser — same grammar,\n * same tolerance for either ASCII or curly quotes.\n *\n * Returns the unescaped string content, or null when the tag is\n * absent or malformed.\n */\nfunction readShouldHint(comment: string): string | null {\n  if (!comment) return null\n  const match = comment.match(/@should\\s*\\(\\s*[\"“]([^\"”]*)[\"”]\\s*\\)/)\n  return match?.[1] ?? null\n}\n"]}

package/dist/transform.d.ts

@@ -1,4 +1,7 @@
 import ts from 'typescript';
+import { extractMsgSchema, extractEffectSchema } from './msg-schema.js';
+import { extractMsgAnnotations } from './msg-annotations.js';
+import { extractStateSchema } from './state-schema.js';
 /**
  * Transform a source file containing @llui/dom imports.
  * Returns the transformed source or null if no transformation needed.
@@ -8,7 +11,50 @@ export interface TransformEdit {
     end: number;
     replacement: string;
 }
-export declare function transformLlui(source: string, _filename: string, devMode?: boolean, emitAgentMetadata?: boolean, mcpPort?: number | null, verbose?: boolean): {
+/**
+ * Pre-resolved external type sources from the cross-file resolver.
+ * When the plugin's vite hook detects that `State` / `Msg` / `Effect`
+ * for a `component<...>()` call are imported (not declared in the
+ * current file), it walks the imports and re-exports to find the
+ * declaring file, then passes the source + local name here. Each
+ * extractor below uses the resolved source instead of falling back to
+ * the file-local search (which would miss the type entirely).
+ */
+export interface ExternalTypeSources {
+    state?: {
+        source: string;
+        typeName: string;
+    };
+    msg?: {
+        source: string;
+        typeName: string;
+    };
+    effect?: {
+        source: string;
+        typeName: string;
+    };
+}
+/**
+ * Schemas already extracted by the plugin's async hook before invoking
+ * the sync transform. Used for cases the file-local sync extractors
+ * can't handle on their own:
+ *   - The Msg/Effect/State alias lives in another file (cross-file
+ *     resolution, see `cross-file-resolver.ts`).
+ *   - The Msg/Effect alias is a *composition* — a union mixing inline
+ *     `{ type: 'literal' }` members with TypeReferences pointing at
+ *     other (often imported) Msg unions.
+ *
+ * When provided, transformLlui uses these instead of running its own
+ * file-local extractors. When omitted (the test path that constructs
+ * a single-source string), the file-local extractors run as before.
+ */
+export interface PreExtractedSchemas {
+    msgSchema?: ReturnType<typeof extractMsgSchema>;
+    msgAnnotations?: ReturnType<typeof extractMsgAnnotations>;
+    stateSchema?: ReturnType<typeof extractStateSchema>;
+    effectSchema?: ReturnType<typeof extractEffectSchema>;
+}
+export declare function transformLlui(source: string, _filename: string, devMode?: boolean, emitAgentMetadata?: boolean, mcpPort?: number | null, verbose?: boolean, typeSources?: ExternalTypeSources, preExtracted?: PreExtractedSchemas): {
     output: string;
     edits: TransformEdit[];
 } | null;

package/dist/transform.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transform.d.ts","sourceRoot":"","sources":["../src/transform.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,YAAY,CAAA;AAiL3B;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAA;IACb,GAAG,EAAE,MAAM,CAAA;IACX,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,OAAO,UAAQ,EACf,iBAAiB,UAAQ,EACzB,OAAO,GAAE,MAAM,GAAG,IAAW,EAC7B,OAAO,UAAQ,GACd;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,aAAa,EAAE,CAAA;CAAE,GAAG,IAAI,CA8TnD;AAwoID,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,EAAE,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,GAChB,wBAAwB,GAAG,IAAI,CAoGjC;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CA4B7D;AAID;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAI3D;AAED;;;GAGG;AACH,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,EAAE,CAAC,cAAc,GAAG,MAAM,GAAG,IAAI,CAcrF;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CASzF;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,KAAK,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAAC,GAChE,MAAM,CAYR"}
+{"version":3,"file":"transform.d.ts","sourceRoot":"","sources":["../src/transform.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,YAAY,CAAA;AAE3B,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EAIpB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,qBAAqB,EAA2B,MAAM,sBAAsB,CAAA;AACrF,OAAO,EAAE,kBAAkB,EAAkB,MAAM,mBAAmB,CAAA;AA6KtE;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAA;IACb,GAAG,EAAE,MAAM,CAAA;IACX,WAAW,EAAE,MAAM,CAAA;CACpB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAA;IAC5C,GAAG,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAA;IAC1C,MAAM,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAA;CAC9C;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,mBAAmB;IAClC,SAAS,CAAC,EAAE,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAA;IAC/C,cAAc,CAAC,EAAE,UAAU,CAAC,OAAO,qBAAqB,CAAC,CAAA;IACzD,WAAW,CAAC,EAAE,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAA;IACnD,YAAY,CAAC,EAAE,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAA;CACtD;AAED,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,OAAO,UAAQ,EACf,iBAAiB,UAAQ,EACzB,OAAO,GAAE,MAAM,GAAG,IAAW,EAC7B,OAAO,UAAQ,EACf,WAAW,CAAC,EAAE,mBAAmB,EACjC,YAAY,CAAC,EAAE,mBAAmB,GACjC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,aAAa,EAAE,CAAA;CAAE,GAAG,IAAI,CAqYnD;AAgqID,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,EAAE,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,GAChB,wBAAwB,GAAG,IAAI,CAoGjC;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CA4B7D;AAID;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAI3D;AAED;;;GAGG;AACH,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,EAAE,CAAC,cAAc,GAAG,MAAM,GAAG,IAAI,CAcrF;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,MAAM,CASzF;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,KAAK,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAAC,GAChE,MAAM,CAYR"}