@lingfan-engine/stories-build 0.1.5 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lingfan-engine/stories-build",
-  "version": "0.1.5",
+  "version": "0.3.0",
   "type": "module",
   "description": "Stories 创作链编译包：把 Stories.src 的多目录原生 TS 源编译成 Resources/Stories/** + project.json，并产出 cell 注册生成物",
   "license": "Apache-2.0",
@@ -9,6 +9,7 @@
     "./authoring": "./src/authoring.d.ts",
     "./cell": "./src/cell/index.ts",
     "./cli": "./src/cli/cli.ts",
+    "./host-plugins": "./src/host-plugins/index.ts",
     "./watch": "./src/pipeline/watch.ts",
     "./watch-cli": "./src/cli/watch-cli.ts"
   },
@@ -23,8 +24,8 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@lingfan-engine/core": "^0.1.5",
-    "@lingfan-engine/editor": "^0.1.5",
+    "@lingfan-engine/core": "^0.3.0",
+    "@lingfan-engine/editor": "^0.3.0",
     "esbuild": "^0.28.2",
     "tsx": "^4.23.15",
     "typescript": "~6.0.3"

package/src/authoring.d.ts

@@ -13,8 +13,16 @@
  *   全局声明供 config.ts 书写与 tsc 通过。
  * - `StoriesConfig`：config.ts default 对象形态的类型（declare global，零 import 全局可用）；
  *   `satisfies StoriesConfig` 给 default 导出强校验与 IDE 键名补全。
+ * - `*.vue` / `*.tsx` / `*.html`：UI 单文件的模块形状。故事源用一行 import
+ *   （说明符指向 `ui/<名>/<名>.<扩展名>`）拿到句柄，编译器只记名字、不读文件；
+ *   tsc 侧则要有人告诉它「这类文件导出一个 UiHandle」，否则每个 UI 导入都是一条
+ *   TS2307。`.ts` UI 不需要这一段——它本来就是 TS 模块，类型由文件自己提供。
  */
 import type { StoryCommand } from "@lingfan-engine/core";
+import type { UiHandle } from "@lingfan-engine/editor";
+
+/** UI 句柄形状的转发出口：唯一声明处是 `@lingfan-engine/editor` 的词汇层，此处不重复声明。 */
+export type { UiHandle };
 
 export interface StateRoot {
   // 宽索引签名是未接 gen 桥工程的缺省回退：gen/state.gen.d.ts 已提供精确 StoryState，
@@ -48,4 +56,27 @@ declare global {
     /** 这个是你需要注册的状态，注意它对应的是你 `state` 的这个 state，你也可以define，都可以的 */
     readonly state?: Record<string, unknown>;
   }
+
+  /**
+   * UI 单文件通配模块：三种非 TS 扩展名各声明一次。
+   *
+   * 写成 `declare global { module "…" }` 而不是裸 `declare module "…"`：本文件是模块
+   *（有 import/export），裸 `declare module` 在模块文件里是「模块增强」，找不到可增强
+   * 的目标就静默失效 —— 表现为每个 UI 导入仍报 TS2307。放进 `declare global` 才是
+   * 真正的全局通配声明。
+   *
+   * `.ts` 有意不在这里：TS 文件的类型由它自己提供，通配拦过去只会盖掉真实类型。
+   */
+  module "*.vue" {
+    const handle: UiHandle;
+    export default handle;
+  }
+  module "*.tsx" {
+    const handle: UiHandle;
+    export default handle;
+  }
+  module "*.html" {
+    const handle: UiHandle;
+    export default handle;
+  }
 }

package/src/cell/imports.ts

@@ -53,13 +53,19 @@ export function lineOf(sf: ts.SourceFile, node: ts.Node): number {
 }
 
 /**
- * 相对说明符重写：源文件（相对 Stories.src 的目录 `fromDir`）→ 生成物（`gen/`，恰深一层）。
- * 解析到 Stories.src 内的规范相对路径后加 `../` 前缀；越出根 = null（调用方 fail-closed）；
+ * 相对说明符重写：源文件（相对源根的目录 `fromDir`）→ 生成物所在目录。
+ *
+ * `rootPrefix` = 从生成物目录回到源根的相对路径（默认布局下 `"../Stories.src"`：
+ * 生成物在 `src/gen/`，源根在 `src/Stories.src/`，两者同级）。缺省 `".."` = 生成物
+ * 就在源根内一层（旧布局）。调用方按工程布局算好传进来，本函数不猜目录。
+ *
+ * 解析到源根内的规范相对路径后拼前缀；越出根 = null（调用方 fail-closed）；
  * 裸说明符（包名）原样。
  */
 export function adjustSpecifier(
   specifier: string,
   fromDir: string,
+  rootPrefix = "..",
 ): string | null {
   if (!specifier.startsWith("./") && !specifier.startsWith("../"))
     return specifier;
@@ -67,22 +73,24 @@ export function adjustSpecifier(
   for (const part of `${fromDir}/${specifier}`.split("/")) {
     if (part === "" || part === ".") continue;
     if (part === "..") {
-      if (segments.pop() === undefined) return null; // 越出 Stories.src 根
+      if (segments.pop() === undefined) return null; // 越出源根
       continue;
     }
     segments.push(part);
   }
   if (segments.length === 0) return null;
-  return `../${segments.join("/")}`;
+  return `${rootPrefix}/${segments.join("/")}`;
 }
 
-/** 文件顶层 import 声明 → 绑定名集 + 「按 gen/ 位置重写过」的语句文本 */
+/** 文件顶层 import 声明 → 绑定名集 + 「按生成物位置重写过」的语句文本 */
 export function collectFileImports(
   sf: ts.SourceFile,
   text: string,
   fromDir: string,
   issues: CellIssue[],
   relPath: string,
+  rootPrefix = "..",
+  isForeignImport?: (fromRel: string, specifier: string) => boolean,
 ): FileImports {
   const statements: Array<{ adjustedText: string; bindings: string[] }> = [];
   const bindingNames = new Set<string>();
@@ -101,11 +109,17 @@ export function collectFileImports(
       }
     }
     for (const binding of bindings) bindingNames.add(binding);
-    // 说明符重写（生成物在 gen/，比源文件深一层）
+    // `import type` 只进类型面，运行期不存在 ⇒ 不搬运、也不受源根沙箱约束
+    // （与编译图的导入扫描同一口径：`clause.isTypeOnly` 先放行）
+    if (clause?.isTypeOnly === true) continue;
+    // 说明符重写（生成物在源根之外的同级目录，比源文件深一层）
     const raw = statement.moduleSpecifier;
     let adjustedText = text.slice(statement.getStart(sf), statement.getEnd());
     if (ts.isStringLiteralLike(raw)) {
-      const adjusted = adjustSpecifier(raw.text, fromDir);
+      // 由别的通道处置的导入（如 UI 句柄）不搬进生成物，也不受源根沙箱约束：
+      // 生成注册物只需要 cell 实现文本，句柄是构建期事实，运行期不再需要那条语句。
+      if (isForeignImport?.(relPath, raw.text) === true) continue;
+      const adjusted = adjustSpecifier(raw.text, fromDir, rootPrefix);
       if (adjusted === null) {
         issues.push({
           message: `cell 所在文件 import "${raw.text}" 越出 Stories.src——生成物无法搬运该导入`,

package/src/cell/index.ts

@@ -10,8 +10,9 @@
  * - 身份键 = (face, name)、指纹 = 实现文本 trim：**同键同纹去重、同键异纹冲突**
  *   （fail-closed 带两处定位，不隐式覆盖）；
  * - face v1 恒 `guards`；`cell` 只认裸标识符调用（house style 解构导入）；
- * - **导入搬运按生成物位置重写相对说明符**：生成物在 `Stories.src/gen/`（比源文件
- *   深一层），`"./x"`/`"../x"` 必须换算到同一目标——越出 `Stories.src` 根 fail-closed。
+ * - **导入搬运按生成物位置重写相对说明符**：生成物目录通常与源根同级（默认布局
+ *   `src/gen/` 对 `src/Stories.src/`），`"./x"`/`"../x"` 由调用方给出的 `rootPrefix`
+ *   换算到同一目标——越出源根 fail-closed。
  */
 
 /** cell 声明提取失败（带 `origin` 定位：`相对路径:行`）——由调用方决定是否中断构建 */

package/src/cell/scan-cells.ts

@@ -12,6 +12,8 @@ export function scanCells(
   options: ScanCellsOptions = {},
 ): { errors: CellIssue[]; scan: CellScan } {
   const globalWhitelist = options.globalWhitelist ?? DEFAULT_GLOBAL_WHITELIST;
+  const rootPrefix = options.rootPrefix ?? "..";
+  const isForeignImport = options.isForeignImport;
   const issues: CellIssue[] = [];
   const byName = new Map<
     string,
@@ -21,7 +23,14 @@ export function scanCells(
   const seenImports = new Set<string>();
 
   for (const [relPath, text] of files) {
-    for (const found of scanFile(relPath, text, globalWhitelist, issues)) {
+    for (const found of scanFile(
+      relPath,
+      text,
+      globalWhitelist,
+      issues,
+      rootPrefix,
+      isForeignImport,
+    )) {
       const existing = byName.get(found.name);
       if (existing === undefined) {
         byName.set(found.name, {

package/src/cell/scan-file.ts

@@ -23,6 +23,8 @@ export function scanFile(
   text: string,
   globalWhitelist: ReadonlySet<string>,
   issues: CellIssue[],
+  rootPrefix = "..",
+  isForeignImport?: (fromRel: string, specifier: string) => boolean,
 ): Array<{
   name: string;
   implText: string;
@@ -33,7 +35,15 @@ export function scanFile(
   const fromDir = relPath.includes("/")
     ? relPath.slice(0, relPath.lastIndexOf("/"))
     : "";
-  const fileImports = collectFileImports(sf, text, fromDir, issues, relPath);
+  const fileImports = collectFileImports(
+    sf,
+    text,
+    fromDir,
+    issues,
+    relPath,
+    rootPrefix,
+    isForeignImport,
+  );
   const found: Array<{
     name: string;
     implText: string;

package/src/cell/types.ts

@@ -24,4 +24,14 @@ export interface FileImports {
 export interface ScanCellsOptions {
   /** 允许在内联实现里直接引用的全局名（缺省 = 标准全局白名单 16 项） */
   readonly globalWhitelist?: ReadonlySet<string>;
+  /**
+   * 生成物目录回到源根的相对前缀（缺省 `".."` = 生成物在源根内恰深一层）。
+   * 生成物挪到源根之外的同级目录时传 `"../Stories.src"` 这类值。
+   */
+  readonly rootPrefix?: string;
+  /**
+   * 判断某条 import 是否由别的通道处置（家例：UI 句柄导入）。命中的语句既不搬进
+   * 生成物、也不算问题——它压根不是生成注册物的运行期依赖，越界与否由那条通道自己判。
+   */
+  readonly isForeignImport?: (fromRel: string, specifier: string) => boolean;
 }

package/src/cli/cli.ts

@@ -17,8 +17,10 @@
  * Node 类型擦除加载，垫片用 tsx 的 `tsImport` 装本文件再调同一个 `runBuildCli`，两条路
  * 因此共用一份呈现逻辑。
  *
- * 用法：`<工程根可省略>`；缺省工程根 = 进程工作目录（调用方脚本已 cd 到宿主工程根，
- * 或经 DSH_STORIES_ROOT 指明——包内没有「谁在调我、宿主工程在哪」这件事实）。
+ * 用法：`[工程根] [--sources-dir=<目录>] [--resources-dir=<目录>]`；缺省工程根 = 进程
+ * 工作目录（调用方脚本已 cd 到宿主工程根，或经 DSH_STORIES_ROOT 指明——包内没有
+ * 「谁在调我、宿主工程在哪」这件事实）。目录参数缺省 = `buildStories` 的默认常量，
+ * 自定义布局的工程用它们覆盖（拒绝在包内猜目录名）。
  * 测试不经这里——它们直接调 `buildStories`（纯编排，fs 全在参数 root 之下）。
  */
 import { resolve } from "node:path";
@@ -28,6 +30,7 @@ import {
   StoryBuildError,
   buildStories,
 } from "../index.ts";
+import type { StoryBuildOptions } from "../index.ts";
 
 export { StoryBuildError, buildStories, type BuildReport } from "../index.ts";
 
@@ -40,6 +43,48 @@ export function resolveBuildRoot(argv: readonly string[]): string {
   );
 }
 
+/** 目录名类参数：命令行可覆盖 `buildStories` 的默认目录名 */
+const DIR_FLAGS = [
+  ["--sources-dir", "sourcesDir"],
+  ["--resources-dir", "resourcesDir"],
+] as const;
+
+/**
+ * 拆命令行：目录参数进 `options`（缺省不下发，让 `buildStories` 用默认常量），
+ * 剩下的位置参数按原序留给 `resolveBuildRoot`。
+ *
+ * 写成 `<目录>=<绝对值>` 或 `<目录>=<相对路径>` 都行——值原样交给 `buildStories`，
+ * 它按工程根 join（与配置文件里的相对口径一致）。缺值时按空串下发会让构建落到工程根
+ * 本身，这类误用直接 fail-closed 报参数名。
+ */
+export function parseCliArgs(argv: readonly string[]): {
+  root: string;
+  options: StoryBuildOptions;
+} {
+  const positional: string[] = [];
+  const options: { sourcesDir?: string; resourcesDir?: string } = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index]!;
+    const match = DIR_FLAGS.find(
+      ([flag]) => arg === flag || arg.startsWith(`${flag}=`),
+    );
+    if (match === undefined) {
+      positional.push(arg);
+      continue;
+    }
+    const [flag, key] = match;
+    const inline = arg.startsWith(`${flag}=`) ? arg.slice(flag.length + 1) : "";
+    const value = inline !== "" ? inline : argv[++index];
+    if (value === undefined || value === "") {
+      throw new StoryBuildError(
+        `${flag} 需要一个目录值（如 ${flag}=src/Stories.src）`,
+      );
+    }
+    options[key] = value;
+  }
+  return { root: resolveBuildRoot(positional), options };
+}
+
 /**
  * 跑一次编译并把结果打到标准输出/标准错误，返回进程退出码。
  * 不调用 `process.exit`——谁来决定退出由调用方（主模块守卫或 bin 垫片）负责。
@@ -47,9 +92,9 @@ export function resolveBuildRoot(argv: readonly string[]): string {
 export async function runBuildCli(
   argv: readonly string[] = process.argv.slice(2),
 ): Promise<number> {
-  const root = resolveBuildRoot(argv);
   try {
-    const report = await buildStories(root);
+    const { root, options } = parseCliArgs(argv);
+    const report = await buildStories(root, options);
     console.log(
       `TS 故事源编译完成：${DEFAULT_SOURCES_DIR}/${report.source} → story "${report.storyId}"（${report.columns} 列）`,
     );

package/src/compiler/cell-scan.ts

@@ -2,20 +2,30 @@ import { scanCells, type CellScan } from "../cell/index.ts";
 import { StoryBuildError } from "../shared/index.ts";
 
 /**
- * cell 声明扫描（构建期 AST 扫描）：`Stories.src` 树（排除生成物目录，仅 `.ts`）。
+ * cell 声明扫描（构建期 AST 扫描）：源树（排除生成物目录，仅 `.ts`）。
  * 「名字在数据、实现在代码、build 做名字闭合」：实现住生成模块，故事 JSON 只留名字。
  * 任一条扫描问题都 fail-closed，一次报全部（每条带 `路径:行` 定位）。
+ *
+ * `generatedDir` 排除项是防手工把生成物放进源树林；`rootPrefix` 只在生成物住在源根
+ * 之外时给（见 `ScanCellsOptions`），决定搬运进来的 import 说明符怎么写。
+ * `isForeignImport` 交给调用方指认「这条导入由别的通道处置」（如 UI 句柄）——这类语句
+ * 既不搬进生成物，也不参与越界判定。
  */
 export function scanCellSources(
   sourcesTree: ReadonlyMap<string, string>,
   generatedDir: string,
+  rootPrefix = "..",
+  isForeignImport?: (fromRel: string, specifier: string) => boolean,
 ): CellScan {
   const cellSourceTree = new Map<string, string>();
   for (const [rel, text] of sourcesTree) {
     if (rel.startsWith(`${generatedDir}/`) || !rel.endsWith(".ts")) continue;
     cellSourceTree.set(rel, text);
   }
-  const cellScanResult = scanCells(cellSourceTree);
+  const cellScanResult = scanCells(cellSourceTree, {
+    rootPrefix,
+    ...(isForeignImport === undefined ? {} : { isForeignImport }),
+  });
   if (cellScanResult.errors.length > 0) {
     throw new StoryBuildError(
       `cell 声明扫描失败：\n${cellScanResult.errors

package/src/compiler/compiler-contract.ts

@@ -1,6 +1,8 @@
 import { StoryBuildError } from "../shared/index.ts";
 import type { StoriesBuildTexts } from "../shared/index.ts";
 import type { StorySourceConfig } from "../config/story-config.ts";
+import type { AliasResolver } from "./story-compiler/graph/scan/alias.ts";
+import type { UiRegistryEntry } from "./story-compiler/graph/core.ts";
 
 /**
  * story-compiler 契约（编译器下游的唯一对接面）：
@@ -59,6 +61,16 @@ export interface StoriesCompiler {
     >;
     /** 文案注入（Partial）；缺省 = 内建缺省文案（即构建层的既有文案） */
     readonly texts?: Partial<StoriesBuildTexts>;
+    /**
+     * 工程 `tsconfig.json` 的 `paths` 解析器；缺省 = 只认相对路径。
+     * 由编排层读工程配置后注入，编译器自己不读 tsconfig。
+     */
+    readonly alias?: AliasResolver;
+    /**
+     * UI 名注册表（扫描 `ui/` 目录的产物）；缺省 = 空表，此时命名导入注册表
+     * 会因查不到名字而 fail-closed。由编排层扫描后注入，编译器自己不读 UI 目录。
+     */
+    readonly uiRegistry?: readonly UiRegistryEntry[];
   }): CompiledStories | Promise<CompiledStories>;
 }
 

package/src/compiler/story-compiler/assemble/mount-uis.ts

@@ -0,0 +1,43 @@
+/**
+ * `mount` 命令与列级 `uis` 声明的互锁判定。
+ *
+ * 为什么要有这道判定：`uis` 是**静态声明**（本列引用了哪些 UI，宿主据此预加载），
+ * `mount(...)` 是**动态挂载**。两者指向同一个名字空间，但来源不同——静态那份来自
+ * 导入语句，动态那份来自列体代码。若代码 `mount` 了一个本列没导入的 UI，静态声明就漏了
+ * 一个名字：宿主不会预加载它，界面第一次挂载时才去取，表现为「点了才闪一下」。
+ * 这类缺陷在运行期只表现为时序抖动，很难归因，所以在编译期就判死。
+ *
+ * 判定只看名字是否在集合里，不判断 UI 是否存在（那是构建期的另一道闸门）。
+ */
+import { compareOrdinal, type StoryCommand } from "@lingfan-engine/core";
+import { walkCommandBodies } from "@lingfan-engine/editor";
+
+/**
+ * 找出「`mount` 了但未在 `uis` 里声明」的名字（去重 + 码点序，保证诊断顺序稳定）。
+ *
+ * 遍历含嵌套块体（`if.then` / `while.body` / `func.body` 等）：块体里的 `mount`
+ * 与列体顶层的 `mount` 在运行期一样会执行，静态声明漏了它同样是缺陷。
+ */
+export function undeclaredMountUis(
+  commands: readonly StoryCommand[],
+  uis: ReadonlySet<string>,
+): string[] {
+  const missing = new Set<string>();
+  const consider = (cmd: Record<string, unknown>): void => {
+    if (cmd.op !== "mount") return;
+    const name = cmd.name;
+    if (typeof name !== "string" || uis.has(name)) return;
+    missing.add(name);
+  };
+  for (const cmd of commands) {
+    consider(cmd as unknown as Record<string, unknown>);
+    walkCommandBodies(
+      cmd as unknown as Record<string, unknown>,
+      "",
+      (inner) => {
+        consider(inner);
+      },
+    );
+  }
+  return [...missing].sort(compareOrdinal);
+}

package/src/compiler/story-compiler/assemble/session.ts

@@ -1,5 +1,6 @@
 import {
   compareOrdinal,
+  normalizeUiNames,
   type CharacterDef,
   type Story,
   type StoryCommand,
@@ -10,6 +11,7 @@ import {
 } from "../../../shared/index.ts";
 import type { DiagBag, Graph } from "../graph.ts";
 import { compileFunction, partitionFunctions, tryFuncOp } from "./functions.ts";
+import { undeclaredMountUis } from "./mount-uis.ts";
 import {
   createBodyCtx,
   translateStatements,
@@ -66,6 +68,18 @@ export function compileStoryFile(
     }
   }
 
+  // —— 列类型：`export const columnType = "ui"` 与 JSON 形态的 `type` 字段同义。
+  // 显式写 `game` 与不写等价，一律不带该字段——「缺省 game 不写」是序列化口径，
+  // 产物要跟手写 JSON 编译出来的字节一致，否则同一份故事两条路径产出两种文件。 ——
+  const declaredType =
+    mod.columnType === null ? undefined : mod.columnType.value;
+  const columnType = declaredType === "game" ? undefined : declaredType;
+
+  // —— 列级 UI 声明：模块扫描期已把 `import hub from ".../ui/hub/hub.vue"` 登记进
+  // `mod.uis`，这里只取名字集合（不回头扫 import 语句——那会让同一件事有第二个判定点）。
+  // 定序与去重交给契约层的唯一实现，保证同源同产物 ——
+  const columnUis = normalizeUiNames([...mod.uis.keys()]);
+
   const registry: FuncRegistry = { refs: new Map(), names: new Map() };
   const shared = {
     mod,
@@ -178,6 +192,20 @@ export function compileStoryFile(
   }
   commands.push(...bodyCommands);
 
+  // —— 静态声明与动态挂载互锁：列体里 `mount` 的每个名字都必须在 `uis` 里 ——
+  // 静态那份来自导入语句，动态那份来自代码；不一致时宿主不会预加载，
+  // 界面要到第一次挂载才取，症状只是「闪一下」，所以在编译期判死。
+  const declared = new Set(columnUis);
+  for (const name of undeclaredMountUis(commands, declared)) {
+    diags.add(
+      rel,
+      sf,
+      storyName,
+      `mount("${name}") 引用了本列未导入的 UI——请在本列补一条默认导入，` +
+        `指向 \`../../ui/${name}/${name}.vue\`，否则产物缺这条静态声明`,
+    );
+  }
+
   const story: Story = {
     formatVersion: 1,
     id: columnId,
@@ -186,7 +214,9 @@ export function compileStoryFile(
       {
         id: columnId,
         kind: "flow",
+        ...(columnType !== undefined ? { type: columnType } : {}),
         ...(columnFont !== undefined ? { font: columnFont } : {}),
+        ...(columnUis.length > 0 ? { uis: columnUis } : {}),
         commands,
       },
     ],

package/src/compiler/story-compiler/graph/build.ts

@@ -1,5 +1,10 @@
 import * as ts from "typescript";
-import { walkFiles, type StoriesBuildTexts } from "../../../shared/index.ts";
+import { isSceneType } from "@lingfan-engine/core";
+import {
+  walkFiles,
+  defaultStoriesBuildTexts,
+  type StoriesBuildTexts,
+} from "../../../shared/index.ts";
 import type { StorySourceConfig } from "../../../config/story-config.ts";
 import type { CompilerConstValues } from "../../compiler-contract.ts";
 import {
@@ -7,9 +12,10 @@ import {
   ROOT_TS_FILES_ALLOWED,
   GEN_PREFIX,
   COLUMN_FONT_DECL,
+  COLUMN_TYPE_DECL,
   toPosix,
 } from "./core.ts";
-import type { Graph, ModuleRecord } from "./core.ts";
+import type { Graph, ModuleRecord, UiRegistryEntry } from "./core.ts";
 import { scanModule } from "./scan/module-scan.ts";
 import { discoverStateRoot } from "./state-root.ts";
 import {
@@ -17,10 +23,18 @@ import {
   assertNpmNamesConstOnly,
 } from "./scan/bindings.ts";
 import { resolveImports } from "./scan/imports.ts";
+import { createUiChannel } from "./scan/ui-specifier.ts";
+import { resolveUiImports } from "./scan/ui-import.ts";
+import type { AliasResolver } from "./scan/alias.ts";
 
 /**
  * 图谱构建：布局声明（config 求值产物）为必填入参——本层不再解析 config.ts
  *（读取/校验统一走 const-eval/config-eval），只消费 folders/start。
+ *
+ * `alias` 是工程 `tsconfig.json` 的 `paths` 解析器；缺省 = 只认相对路径。
+ *
+ * `uiRegistry` 是 UI 名注册表（扫描 `ui/` 目录的产物）；缺省 = 空表，此时命名导入
+ * 注册表会因查不到名字而报错——只有编排层知道 `ui/` 在哪，编译器自己不扫目录。
  */
 export function buildGraph(
   sourcesDir: string,
@@ -28,6 +42,8 @@ export function buildGraph(
   config: StorySourceConfig,
   constValues?: CompilerConstValues,
   texts?: StoriesBuildTexts,
+  alias?: AliasResolver,
+  uiRegistry?: readonly UiRegistryEntry[],
 ): Graph | null {
   const files = new Map<string, string>();
   for (const [rel, text] of walkFiles(sourcesDir)) {
@@ -91,19 +107,28 @@ export function buildGraph(
       npmNames: new Set(),
       evaluated: constValues?.[rel],
       columnFont: null,
+      columnType: null,
+      uis: new Map(),
     });
   }
 
+  // UI 沙箱根是源根的上一级（`src/`）：UI 目录与故事源树是兄弟，不是它的子目录。
+  // 这一遍必须早于模块层常量扫描——`export const picked = hub` 折叠时要看得到 UI 绑定。
+  const uiChannel = createUiChannel(sourcesDir, alias, uiRegistry);
+  const uiTexts = texts ?? defaultStoriesBuildTexts;
   for (const record of records.values()) scanModule(record, diags);
   for (const record of records.values())
-    resolveImports(record, records, diags, true);
+    resolveUiImports(record, diags, uiChannel, uiTexts);
+  for (const record of records.values())
+    resolveImports(record, records, diags, true, alias, uiChannel);
   for (const record of records.values()) {
     for (const stmt of record.consts)
       scanConstStatement(stmt, record, diags, texts);
   }
   collectColumnFonts(records, diags);
+  collectColumnTypes(records, diags);
   for (const record of records.values())
-    resolveImports(record, records, diags, false);
+    resolveImports(record, records, diags, false, alias, uiChannel);
   for (const record of records.values())
     assertNpmNamesConstOnly(record, diags, texts);
 
@@ -132,10 +157,28 @@ export function buildGraph(
   return { files, records, config, configSf, coveredStories, stateRoot };
 }
 
+/**
+ * 列级声明所在的语法节点（诊断定位用）。
+ *
+ * 找不到对应的 `const` 语句时退回整个源文件：报错仍能指出哪个文件，
+ * 比拿不到位置更好，也和 `columnFont` 既有行为一致。
+ */
+function declNodeOf(record: ModuleRecord, name: string): ts.Node {
+  const stmt = record.consts.find((s) => {
+    const decl = s.declarationList.declarations[0];
+    return (
+      decl !== undefined &&
+      ts.isIdentifier(decl.name) &&
+      decl.name.text === name
+    );
+  });
+  return stmt ?? record.sf;
+}
+
 /**
  * 列级字体声明拾取：`export const columnFont = "<名>"`。
  * 值走既有 const 绑定通道（字面量 / 常量运算 / 其他 const / 编译期求值内联同源），
- * 这里只做归属与形状裁定；字体名是否在注册表内由汇编段对照 fontNames 报（注册表
+ * 这里只做归属与形状判定；字体名是否在注册表内由汇编段对照 fontNames 报（注册表
  * 在会话上，图谱层不可见）。
  */
 function collectColumnFonts(
@@ -145,15 +188,7 @@ function collectColumnFonts(
   for (const record of records.values()) {
     const binding = record.exports.get(COLUMN_FONT_DECL);
     if (binding === undefined) continue;
-    const stmt = record.consts.find((s) => {
-      const decl = s.declarationList.declarations[0];
-      return (
-        decl !== undefined &&
-        ts.isIdentifier(decl.name) &&
-        decl.name.text === COLUMN_FONT_DECL
-      );
-    });
-    const node = stmt ?? record.sf;
+    const node = declNodeOf(record, COLUMN_FONT_DECL);
     if (record.story === null) {
       diags.add(
         record.rel,
@@ -180,6 +215,43 @@ function collectColumnFonts(
   }
 }
 
+/**
+ * 列类型声明拾取：`export const columnType = "ui"`。
+ *
+ * 与 JSON / 文本形态的 `type` 字段同义：不写 = `game`，写了必须是契约承认的两个取值之一。
+ * 为什么要这条通道：列类型是**列自身的语义**，而 TS 创作链里一列就是一个函数模块，
+ * 没有别的位置能放下它；让作者改生成物或手写 JSON 会把同一份事实劈成两处。
+ */
+function collectColumnTypes(
+  records: ReadonlyMap<string, ModuleRecord>,
+  diags: DiagBag,
+): void {
+  for (const record of records.values()) {
+    const binding = record.exports.get(COLUMN_TYPE_DECL);
+    if (binding === undefined) continue;
+    const node = declNodeOf(record, COLUMN_TYPE_DECL);
+    if (record.story === null) {
+      diags.add(
+        record.rel,
+        record.sf,
+        node,
+        "columnType 只能声明在故事文件（default 导出列）的模块顶层",
+      );
+      continue;
+    }
+    if (binding.kind !== "const" || !isSceneType(binding.value)) {
+      diags.add(
+        record.rel,
+        record.sf,
+        node,
+        'columnType 必须折叠为 "game" 或 "ui" 字面量（缺省即 game，不必声明）',
+      );
+      continue;
+    }
+    record.columnType = { value: binding.value, node };
+  }
+}
+
 export function resolveStart(graph: Graph, diags: DiagBag): string | undefined {
   const candidates = graph.coveredStories.filter((rel) => {
     const idx = rel.lastIndexOf("/");