@lingfan-engine/stories-build 0.1.5 → 0.3.0

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

@@ -1,5 +1,6 @@
 import * as ts from "typescript";
 import { compareOrdinal } from "@lingfan-engine/core";
+import type { SceneType } from "@lingfan-engine/core";
 import { script } from "@lingfan-engine/editor";
 
 export interface CompileDiag {
@@ -49,7 +50,23 @@ export type Binding =
       name: string;
       members: ReadonlyMap<string, ConstValue>;
     }
-  | { kind: "story"; file: string; name: string };
+  | { kind: "story"; file: string; name: string }
+  | { kind: "ui"; name: string };
+
+/**
+ * 一次 UI 导入在模块记录里留下的痕迹：只有一个名字与一条相对路径。
+ *
+ * 装配期靠 `name` 写列级 `uis` 声明，`relPath` 只用于生成/审计定位；UI 文件本身
+ * 从不进图谱、不读内容——句柄是纯静态事实，运行期怎么挂载不归编译期管。
+ */
+export interface UiRecord {
+  /** UI 名（= 目录名 = 绑定名 = 文件名去扩展名） */
+  name: string;
+  /** UI 文件相对 `src/` 的 posix 路径（如 `ui/hub/hub.vue`） */
+  relPath: string;
+  /** 触发这次登记的导入声明（诊断定位用） */
+  node: ts.Node;
+}
 
 export interface ModuleRecord {
   rel: string;
@@ -66,6 +83,10 @@ export interface ModuleRecord {
   evaluated?: Readonly<Record<string, unknown>>;
   /** 列级字体声明（`export const columnFont = "<名>"`；仅故事文件合法，null = 未声明） */
   columnFont: { value: string; node: ts.Node } | null;
+  /** 列类型声明（`export const columnType = "ui"`；仅故事文件合法，null = 未声明） */
+  columnType: { value: SceneType; node: ts.Node } | null;
+  /** UI 导入登记：UI 名 → 记录。UI 文件不进图谱，这里只留名字与路径 */
+  uis: Map<string, UiRecord>;
 }
 
 export interface StoryConfig {
@@ -84,11 +105,54 @@ export interface Graph {
 }
 
 export const ROOT_TS_FILES_ALLOWED = new Set(["config.ts"]);
-export const GEN_PREFIX = "gen/";
+/** 生成物目录前缀：权威声明在 `shared/generated-dir.ts`（编译器只是消费方之一） */
+export { GEN_PREFIX } from "../../../shared/index.ts";
 
 /** 列级字体声明的保留导出名（`export const columnFont = "<名>"`，仅故事文件顶层） */
 export const COLUMN_FONT_DECL = "columnFont";
 
+/** 列类型声明的保留导出名（`export const columnType = "ui"`，仅故事文件顶层） */
+export const COLUMN_TYPE_DECL = "columnType";
+
+/**
+ * UI 导入可用的文件扩展名（小写比对）。
+ *
+ * 只出现在 `src/ui/<名>/<名>.<扩展名>` 这一种形态里；扩展名本身不决定「这是不是 UI」——
+ * 相对位置同时要落在 UI 目录下。`.ts` 是特例：故事源自己的 `.ts` 也是这个扩展名，
+ * 所以 `.ts` 只有路径合上 `ui/<名>/<名>.ts` 且不在故事源树内时才当 UI，其余照常走模块图。
+ */
+export const UI_EXTENSIONS = [".vue", ".tsx", ".html", ".ts"] as const;
+
+/** 说明符的 UI 扩展名（小写）；不是 UI 扩展名 ⇒ `undefined` */
+export function uiExtensionOf(specifier: string): string | undefined {
+  const lower = specifier.toLowerCase();
+  return UI_EXTENSIONS.find((ext) => lower.endsWith(ext));
+}
+
+/** UI 根目录名（源根的兄弟目录，与故事源平级） */
+export const UI_DIR_NAME = "ui";
+
+/**
+ * UI 注册表生成物的基名（不带扩展名）：生成物是 `<生成物目录>/<基名>.ts`，
+ * 故事源以**命名导入**从 `../../gen/ui_register.g` 取句柄（形如 `{ hub }`）。
+ *
+ * 它没有 UI 扩展名，因此不走 `uiExtensionOf` 那条判定——由 UI 通道单独认这一条形状。
+ */
+export const UI_REGISTER_BASENAME = "ui_register.g";
+
+/**
+ * UI 注册表条目：一个 UI 的名字与它的实现文件名。
+ *
+ * 声明在这里而不是 UI 注册表实现里，是因为图谱层（UI 通道）也要消费它，而
+ * 注册表实现反过来依赖本文件的 `UI_EXTENSIONS`——放实现里会成环。
+ */
+export interface UiRegistryEntry {
+  /** UI 名（= 目录名 = 文件名去扩展名） */
+  readonly name: string;
+  /** 实现文件名（含扩展名，如 `hub.vue`） */
+  readonly file: string;
+}
+
 export const WORD_NAMES: ReadonlySet<string> = new Set(
   Object.keys(script).filter(
     (k) => typeof (script as Record<string, unknown>)[k] === "function",

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

@@ -76,6 +76,9 @@ export function foldConst(
   }
   if (ts.isIdentifier(expr)) {
     const b = lookup(expr.text);
+    // UI 句柄在编译期就是一个名字：`export const picked = hub` 折成 `"hub"`，
+    // 于是 `mount(picked, true)` 与 `mount(hub, true)` 的产物完全一致。
+    if (b?.kind === "ui") return b.name;
     return b?.kind === "const" ? b.value : undefined;
   }
   if (ts.isPropertyAccessExpression(expr) && ts.isIdentifier(expr.expression)) {

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

@@ -11,7 +11,18 @@ export type {
   Graph,
   ModuleRecord,
   StoryConfig,
+  UiRecord,
+  UiRegistryEntry,
+} from "./core.ts";
+export {
+  DiagBag,
+  toPosix,
+  UI_DIR_NAME,
+  UI_EXTENSIONS,
+  UI_REGISTER_BASENAME,
+  uiExtensionOf,
 } from "./core.ts";
-export { DiagBag, toPosix } from "./core.ts";
 export { foldConst } from "./fold.ts";
 export { buildGraph, resolveStart } from "./build.ts";
+export { createUiChannel } from "./scan/ui-specifier.ts";
+export type { UiChannel, UiOutcome } from "./scan/ui-specifier.ts";

package/src/compiler/story-compiler/graph/scan/alias.ts

@@ -0,0 +1,100 @@
+import { posix, relative } from "node:path";
+import * as ts from "typescript";
+import type { PathsConfig } from "../../../../pipeline/tsconfig-paths.ts";
+import { expandAlias } from "../../../../pipeline/tsconfig-paths.ts";
+
+/**
+ * 别名说明符解析：把工程 `tsconfig.json` 的 `paths` 展开成源根内的模块键。
+ *
+ * 只服务作者手写的那一行 import——产物里一律写相对路径，宿主零配置也能跑。判定结果分五种：
+ * - `module`：命中且是源根内的 `.ts`，`rel` 是相对源根的 posix 模块键，交给图谱层当普通模块连边；
+ * - `other`：命中且在源根内，但不是 `.ts`（如 `.vue`）。调用方据此给出「不是 .ts 模块」诊断；
+ * - `outside`：命中但文件在源根之外。创作导入只接受源根内的模块，越界 fail-closed，
+ *   不静默丢弃；`target` 是绝对路径，调用方若按更宽的沙箱复判（例如宿主源码）不必重新展开；
+ * - `missing`：有模式命中但展开出的候选都不存在——作者写错路径；
+ * - `unmatched`：没有任何模式命中——说明符根本不是别名，调用方按既有的外部包判定继续。
+ *
+ * `missing` 与 `unmatched` 必须分开：混成一个「未命中」会让普通的 npm 导入也背上一句
+ * 「别名没命中」的误导诊断，而真正的别名笔误又会被当成「不支持外部包」。
+ *
+ * 存在性探测走 `ts.sys.fileExists`（自带平台语义），候选按 tsc 的补全习惯依次试
+ * 「原样 / `.ts` / `.d.ts` / 目录索引」，命中即止。
+ */
+export interface AliasResolver {
+  /** 展开一条非相对说明符；`undefined` = 工程没配 `paths`（调用方退回既有判定） */
+  resolveSpecifier(specifier: string): AliasOutcome;
+  /**
+   * 只定位文件、不判沙箱：返回命中的绝对路径，未命中 ⇒ `undefined`。
+   *
+   * 用途是沙箱根与源根不同的调用方（UI 文件在 `src/ui/` 而不在 `src/Stories.src/`）：
+   * 它们拿到绝对路径后按自己的根折算并判越界，不必让别名解析器猜第二套沙箱。
+   */
+  locateFile(specifier: string): string | undefined;
+  /**
+   * 只展开不探测：返回第一个候选的绝对路径，文件存不存在都不影响。
+   *
+   * 生成物在编译期还没落盘（它是这次构建的产物），但引用它的那条 import 仍然合法；
+   * 用存在性探测就会把「第一次构建」判成路径写错。
+   */
+  expandTarget(specifier: string): string | undefined;
+}
+
+export type AliasOutcome =
+  | { readonly kind: "module"; readonly target: string; readonly rel: string }
+  | { readonly kind: "other"; readonly target: string; readonly rel: string }
+  | { readonly kind: "outside"; readonly target: string }
+  | { readonly kind: "missing" }
+  | { readonly kind: "unmatched" };
+
+/** 候选路径的补全形态（tsc 的模块解析习惯：原样 → .ts → .d.ts → 目录索引） */
+const PROBES = ["", ".ts", ".d.ts", "/index.ts"] as const;
+
+/**
+ * 按工程配置造解析器。`config` 为 `null`（无 tsconfig 或无 paths）⇒ 返回 `undefined`，
+ * 让调用方保持「只认相对路径」的既有行为。
+ */
+export function createAliasResolver(
+  config: PathsConfig | null,
+  sourcesDir: string,
+): AliasResolver | undefined {
+  if (config === null) return undefined;
+  return {
+    resolveSpecifier(specifier): AliasOutcome {
+      const candidates = expandAlias(config, specifier);
+      if (candidates.length === 0) return { kind: "unmatched" };
+      const target = locateIn(candidates);
+      if (target === undefined) return { kind: "missing" };
+      const rel = insideSources(sourcesDir, target);
+      if (rel === null) return { kind: "outside", target };
+      return rel.endsWith(".ts")
+        ? { kind: "module", target, rel }
+        : { kind: "other", target, rel };
+    },
+    locateFile(specifier): string | undefined {
+      return locateIn(expandAlias(config, specifier));
+    },
+    expandTarget(specifier): string | undefined {
+      return expandAlias(config, specifier)[0];
+    },
+  };
+}
+
+/** 按 tsc 的补全习惯逐个候选探测存在性，命中即止 */
+function locateIn(candidates: readonly string[]): string | undefined {
+  for (const candidate of candidates) {
+    for (const probe of PROBES) {
+      const target = `${candidate}${probe}`;
+      if (ts.sys.fileExists(target)) return target;
+    }
+  }
+  return undefined;
+}
+
+/** 绝对路径 → 相对源根的 posix 路径；越出源根 ⇒ `null` */
+function insideSources(sourcesDir: string, absolute: string): string | null {
+  const rel = posix.normalize(
+    relative(sourcesDir, absolute).split("\\").join("/"),
+  );
+  if (rel === "" || rel.startsWith("..") || posix.isAbsolute(rel)) return null;
+  return rel;
+}

package/src/compiler/story-compiler/graph/scan/imports.ts

@@ -1,6 +1,8 @@
 import * as ts from "typescript";
 import { WORD_NAMES, GEN_PREFIX, toPosix } from "../core.ts";
 import type { ModuleRecord, DiagBag } from "../core.ts";
+import type { AliasResolver } from "./alias.ts";
+import type { UiChannel } from "./ui-specifier.ts";
 
 function resolveModuleFile(rel: string, spec: string): string | null {
   const dirParts = toPosix(rel).split("/").slice(0, -1);
@@ -39,6 +41,8 @@ export function resolveImports(
   records: Map<string, ModuleRecord>,
   diags: DiagBag,
   editorPass: boolean,
+  alias?: AliasResolver,
+  uiChannel?: UiChannel,
 ): void {
   const { sf, rel } = record;
   for (const imp of record.imports) {
@@ -96,21 +100,64 @@ export function resolveImports(
       diags.add(rel, sf, imp, "引擎包不参与创作导入：请使用词汇层词函数");
       continue;
     }
+    // UI 说明符已由 UI 通道处置（登记或诊断），这里只负责不再按模块解析它——
+    // 否则 `.vue`/`.tsx`/`.html` 会落到「不支持外部包」或「必须解析到相对 .ts 文件」。
+    if (
+      uiChannel !== undefined &&
+      uiChannel.classify(rel, spec).kind !== "not-ui"
+    )
+      continue;
+    let targetRel: string | null;
     if (!spec.startsWith(".")) {
-      if (record.evaluated === undefined) {
+      // 非相对说明符先问工程别名：引擎包（editor/core）已在上面的分支判定完毕，
+      // 这里只剩作者自己在 tsconfig.json 里定义的 paths。
+      const outcome = alias?.resolveSpecifier(spec);
+      if (outcome?.kind === "missing") {
         diags.add(
           rel,
           sf,
           imp,
-          `导入仅限相对路径与词汇层既有出口，不支持外部包 \`${spec}\``,
+          `已读 tsconfig.json 的 paths，未命中 \`${spec}\``,
         );
         continue;
       }
-      // 经编译期求值的文件允许 node_modules 值导入——值经求值结果内联，
-      // 引用域仅限模块层 const 初始化链（buildGraph 末尾 assertNpmNamesConstOnly 兜底）。
-      continue;
+      if (outcome?.kind === "other") {
+        diags.add(
+          rel,
+          sf,
+          imp,
+          `别名 \`${spec}\` 解析到 ${outcome.rel}：创作导入只接受 .ts 模块`,
+        );
+        continue;
+      }
+      if (outcome?.kind === "outside") {
+        // 越界的别名一律 fail-closed：静默丢弃会让作者以为引用生效了。
+        diags.add(
+          rel,
+          sf,
+          imp,
+          `别名 \`${spec}\` 解析到源根之外（${outcome.target}）：创作导入只接受源根内的文件`,
+        );
+        continue;
+      }
+      if (outcome?.kind !== "module") {
+        if (record.evaluated === undefined) {
+          diags.add(
+            rel,
+            sf,
+            imp,
+            `导入仅限相对路径与词汇层既有出口，不支持外部包 \`${spec}\``,
+          );
+          continue;
+        }
+        // 经编译期求值的文件允许 node_modules 值导入——值经求值结果内联，
+        // 引用域仅限模块层 const 初始化链（buildGraph 末尾 assertNpmNamesConstOnly 兜底）。
+        continue;
+      }
+      targetRel = outcome.rel;
+    } else {
+      targetRel = resolveModuleImportPath(rel, spec);
     }
-    const targetRel = resolveModuleImportPath(rel, spec);
     if (targetRel === null) {
       diags.add(rel, sf, imp, `模块说明符 \`${spec}\` 必须解析到相对 .ts 文件`);
       continue;

package/src/compiler/story-compiler/graph/scan/module-scan.ts

@@ -1,5 +1,6 @@
 import * as ts from "typescript";
 import { scanEnum } from "../fold.ts";
+import { uiExtensionOf } from "../core.ts";
 import type { Binding, DiagBag, ModuleRecord } from "../core.ts";
 
 /**
@@ -26,6 +27,10 @@ function collectNpmNames(
     spec === "@lingfan-engine/core"
   )
     return;
+  // UI 说明符带 `.vue`/`.tsx`/`.html` 这类扩展名（`.ts` 也只在 `ui/<名>/<名>.ts`
+  // 这一种形状上算 UI），它们由 UI 通道处置，不是 npm 包名——登记进来会让
+  // 「npm 值导入只能出现在模块层 const」的检查误报。
+  if (uiExtensionOf(spec) !== undefined) return;
   const clause = imp.importClause;
   if (clause === undefined || clause.isTypeOnly) return;
   if (clause.name !== undefined) record.npmNames.add(clause.name.text);

package/src/compiler/story-compiler/graph/scan/ui-import.ts

@@ -0,0 +1,136 @@
+import * as ts from "typescript";
+import { posix } from "node:path";
+import type { StoriesBuildTexts } from "../../../../shared/index.ts";
+import { UI_DIR_NAME, type DiagBag, type ModuleRecord } from "../core.ts";
+import type { UiChannel } from "./ui-specifier.ts";
+
+/**
+ * UI 导入通道的落账一段：把模块里每条 UI 说明符登记成「一个 UI + 一个句柄绑定」。
+ *
+ * 这一遍必须**先于模块层常量扫描**跑：`export const picked = hub` 要在扫描时就能把
+ * `hub` 折成 `"hub"`，否则折叠看不到 UI 绑定。它也独立于模块图的两遍导入解析——
+ * UI 文件从不进 `records`（那里是会参与连边与常量求值的 TS 模块，`.vue` 进去会被当
+ * TS 解析），句柄是纯静态事实。
+ *
+ * 两种写法：default 导入 UI 文件，或命名导入 UI 注册表。前者三件必须同时成立——
+ * 落在源根的兄弟目录 `ui/<名>/` 内、default 导入、绑定名等于目录名——任一不成立都
+ * fail-closed：UI 名字是全工程的键（列声明、生成物、运行期挂载都用它），静默接受一个
+ * 歪名字会让后面每一步都拿着不同的名字。后者见 `bindRegisterImport`。
+ */
+export function resolveUiImports(
+  record: ModuleRecord,
+  diags: DiagBag,
+  channel: UiChannel,
+  texts: StoriesBuildTexts,
+): void {
+  for (const imp of record.imports) {
+    const spec = ts.isStringLiteral(imp.moduleSpecifier)
+      ? imp.moduleSpecifier.text
+      : "";
+    bindUiImport(record, imp, spec, diags, channel, texts);
+  }
+}
+
+/** 单条说明符的判定与登记；不归 UI 管时什么都不做（交回模块图）。 */
+function bindUiImport(
+  record: ModuleRecord,
+  imp: ts.ImportDeclaration,
+  spec: string,
+  diags: DiagBag,
+  channel: UiChannel,
+  texts: StoriesBuildTexts,
+): void {
+  const outcome = channel.classify(record.rel, spec);
+  if (outcome.kind === "not-ui") return;
+  const { sf, rel } = record;
+  if (outcome.kind === "outside") {
+    diags.add(rel, sf, imp, texts.uiOutside(spec, channel.sourceRootName));
+    return;
+  }
+  if (outcome.kind === "file-name") {
+    diags.add(
+      rel,
+      sf,
+      imp,
+      texts.uiFileName(outcome.name, posix.basename(outcome.relPath)),
+    );
+    return;
+  }
+  if (outcome.kind === "register") {
+    bindRegisterImport(record, imp, diags, channel, texts);
+    return;
+  }
+  const clause = imp.importClause;
+  // 类型导入不产生运行期绑定，也没有句柄可用；`import type` 交给 tsc 自己判。
+  if (clause?.isTypeOnly === true) return;
+  if (clause?.name === undefined || clause.namedBindings !== undefined) {
+    diags.add(rel, sf, clause ?? imp, texts.uiDefaultImport(outcome.name));
+    return;
+  }
+  if (clause.name.text !== outcome.name) {
+    diags.add(
+      rel,
+      sf,
+      clause.name,
+      texts.uiBindingName(outcome.name, clause.name.text),
+    );
+    return;
+  }
+  record.uis.set(outcome.name, {
+    name: outcome.name,
+    relPath: outcome.relPath,
+    node: imp,
+  });
+  record.bindings.set(clause.name.text, { kind: "ui", name: outcome.name });
+}
+
+/**
+ * UI 注册表的命名导入：从注册表说明符取句柄（形如 `{ hub }`）。
+ *
+ * 名字来自注册表键，而不是说明符本身——一条注册表说明符能同时供出所有 UI 句柄，
+ * 所以必须逐个导入名去注册表里查。查不到就是笔误，报错而不是静默跳过。
+ *
+ * 与 default 导入的差异只有一处：这里**不要求**绑定名等于 UI 名（`import { hub as h }`
+ * 合法）。绑定名只是本地别名，折叠用的是 UI 名，落账时两者分开记。
+ */
+function bindRegisterImport(
+  record: ModuleRecord,
+  imp: ts.ImportDeclaration,
+  diags: DiagBag,
+  channel: UiChannel,
+  texts: StoriesBuildTexts,
+): void {
+  const { sf, rel } = record;
+  const clause = imp.importClause;
+  // 副作用导入不取任何句柄，写在这里只可能是笔误。
+  if (clause === undefined) {
+    diags.add(rel, sf, imp, texts.uiRegisterSideEffect());
+    return;
+  }
+  // 类型导入不产生运行期绑定，也没有句柄可用。
+  if (clause.isTypeOnly) return;
+  const named = clause.namedBindings;
+  // 注册表只有具名导出：default 与命名空间导入都取不到句柄。
+  if (clause.name !== undefined || named === undefined) {
+    diags.add(rel, sf, clause, texts.uiRegisterNoDefault());
+    return;
+  }
+  if (ts.isNamespaceImport(named)) {
+    diags.add(rel, sf, named, texts.uiRegisterNoDefault());
+    return;
+  }
+  for (const element of named.elements) {
+    const imported = element.propertyName?.text ?? element.name.text;
+    const entry = channel.registry.find((item) => item.name === imported);
+    if (entry === undefined) {
+      diags.add(rel, sf, element, texts.uiRegisterMissing(imported));
+      continue;
+    }
+    record.uis.set(entry.name, {
+      name: entry.name,
+      relPath: posix.join(UI_DIR_NAME, entry.name, entry.file),
+      node: imp,
+    });
+    record.bindings.set(element.name.text, { kind: "ui", name: entry.name });
+  }
+}

package/src/compiler/story-compiler/graph/scan/ui-specifier.ts

@@ -0,0 +1,202 @@
+import { posix } from "node:path";
+import {
+  GEN_PREFIX,
+  toPosix,
+  uiExtensionOf,
+  UI_REGISTER_BASENAME,
+  type UiRegistryEntry,
+} from "../core.ts";
+import type { AliasResolver } from "./alias.ts";
+
+/**
+ * UI 导入通道：把一条 import 说明符判成「指向某个 UI」还是「不归 UI 管」。
+ *
+ * UI 文件与故事源是同一棵树上的兄弟目录——故事源在 `src/Stories.src/`，UI 在
+ * `src/ui/<名>/<名>.<扩展名>`。因此这里的沙箱根是 `src/`（源根的上一级），比模块导入
+ * 的沙箱更宽：模块导入只认源根内，UI 恰好必须落在源根外。
+ *
+ * 一个说明符要同时满足三件事才算 UI：
+ * - 落在 `src/ui/` 下（越过 `src/` 或落在别处一律 fail-closed，不静默丢弃）；
+ * - 相对 `src/ui/` 恰两层：`<目录>/<文件>`；
+ * - 文件名去扩展名 = 目录名（名字 = 目录名，同一条规则决定绑定名与文件位置）。
+ *
+ * `.ts` 额外收紧：故事源自己也是 `.ts`，所以只有位置完全合上 `ui/<名>/<名>.ts` 才当 UI；
+ * 其余 `.ts` 说明符一律交回模块图，免得把源树里的列文件当成 UI。
+ */
+export interface UiChannel {
+  /** 源根目录名（如 `Stories.src`），诊断文案里用来指认「UI 是它的兄弟目录」 */
+  readonly sourceRootName: string;
+  /** UI 注册表（扫描期产物）：命名导入注册表时按名字查条目 */
+  readonly registry: readonly UiRegistryEntry[];
+  /**
+   * 判定一条说明符。`fromRel` 是发起导入的文件相对**源根**的路径（如
+   * `title/title_main.ts`），`spec` 是原样的说明符文本。
+   */
+  classify(fromRel: string, spec: string): UiOutcome;
+}
+
+export type UiOutcome =
+  /** 合上 `ui/<名>/<名>.<扩展名>`：`relPath` 相对 `src/`，`name` 即目录名 */
+  | { readonly kind: "ui"; readonly name: string; readonly relPath: string }
+  /** 在 `src/ui/` 之外（越出 `src/`、层级不对、或被引到别处）——fail-closed */
+  | { readonly kind: "outside"; readonly target: string }
+  /** 落位合规但文件名与目录名不一致——fail-closed */
+  | {
+      readonly kind: "file-name";
+      readonly name: string;
+      readonly relPath: string;
+    }
+  /**
+   * UI 注册表生成物（`<生成物目录>/ui_register.g`）：句柄经**命名导入**取，
+   * 名字来自注册表键而不是目录名，故与上面四支分开处置。
+   */
+  | { readonly kind: "register" }
+  /** 不归 UI 管：不是 UI 扩展名，或 `.ts` 位置不合规，交回模块图判定 */
+  | { readonly kind: "not-ui" };
+
+const UI_DIR = "ui";
+
+/**
+ * 造通道。`sourcesDir` 是源根绝对路径（`<工程>/src/Stories.src`），沙箱根由它推出
+ * `<工程>/src`——调用方不必额外传一个「UI 根」，两处目录天生是父子。
+ *
+ * `registry` 是 UI 名注册表（`scanUiRegistry` 的产物）：注册表说明符本身不带名字，
+ * 具名句柄要拿导入名去这张表里查，才知它对不对得上一个真实 UI 文件。
+ */
+export function createUiChannel(
+  sourcesDir: string,
+  alias?: AliasResolver,
+  registry: readonly UiRegistryEntry[] = [],
+): UiChannel {
+  const sourceRootName = posix.basename(toPosix(sourcesDir));
+  const srcRoot = posix.dirname(toPosix(sourcesDir));
+  return {
+    sourceRootName,
+    registry,
+    classify(fromRel, spec): UiOutcome {
+      // 注册表形状先判：它可能带 `.ts` 后缀，而 `.ts` 同时也是故事源自己的扩展名，
+      // 走扩展名判定会被当成普通模块交回模块图。两者的区别不在扩展名，在位置——
+      // 只有生成物目录下那一个文件才算注册表，别处的同名文件仍交回模块图。
+      if (isRegisterSpecifier(spec)) {
+        const located = locate(
+          srcRoot,
+          sourceRootName,
+          fromRel,
+          spec,
+          alias,
+          true,
+        );
+        if (located === undefined) return { kind: "not-ui" };
+        return judgeRegister(located, sourceRootName);
+      }
+      const extension = uiExtensionOf(spec);
+      if (extension === undefined) return { kind: "not-ui" };
+      const located = locate(srcRoot, sourceRootName, fromRel, spec, alias);
+      if (located === undefined) return { kind: "not-ui" };
+      return judge(located, sourceRootName, extension);
+    },
+  };
+}
+
+/**
+ * 说明符的文件名（去 `.ts`）是否就是注册表生成物的基名。
+ *
+ * 生成物在故事源里既可能写成不带扩展名的 `<基名>`（工程配置把 `.g` 映到生成物），
+ * 也可能显式带 `.ts`；两者指同一个文件，判定必须一视同仁。
+ */
+function isRegisterSpecifier(spec: string): boolean {
+  const base = posix.basename(toPosix(spec));
+  return base.replace(/\.ts$/, "") === UI_REGISTER_BASENAME;
+}
+
+/**
+ * 注册表说明符的形状判定：只认生成物目录下那一个位置（`src/<生成物目录>/ui_register.g`）。
+ *
+ * 越出 `src/` 是越界（与 UI 说明符同样 fail-closed）；落在别处则只是「恰好同名」，
+ * 交回模块图——别的目录下的同名文件不归 UI 通道管。
+ *
+ * 落在**源根之内**同理交回模块图：生成物是源根的兄弟目录，源树里那份 `gen/` 归模块
+ * 图管（那里有「生成物不参与创作导入」的既有判定），两者不能混为一谈。
+ *
+ * `locate` 对相对写法与别名写法都会折成「相对 `src/`」的路径，但别名展开会带 `.ts`、
+ * 相对写法不带，故判定时再去一次扩展名。
+ */
+function judgeRegister(located: string, sourceRootName: string): UiOutcome {
+  if (located.startsWith("..") || posix.isAbsolute(located)) {
+    return { kind: "outside", target: located };
+  }
+  if (located === sourceRootName || located.startsWith(`${sourceRootName}/`)) {
+    return { kind: "not-ui" };
+  }
+  const expected = `${GEN_PREFIX}${UI_REGISTER_BASENAME}`;
+  return located.replace(/\.ts$/, "") === expected
+    ? { kind: "register" }
+    : { kind: "not-ui" };
+}
+
+/**
+ * 折成「相对 `src/` 的 posix 路径」：相对说明符从发起文件的目录起算（此时要补回
+ * 源根那一段前缀，因为 `fromRel` 不含它）；非相对说明符先问别名表拿绝对路径，再折算。
+ *
+ * 返回 `undefined` 表示这里判不了（别名未配/未命中），交回模块图按原路径报错。
+ *
+ * `existenceFree` 关掉别名解析里的存在性探测：注册表生成物是本次构建的产物，编译时
+ * 它还没落盘，用探测会把「第一次构建」误判成路径写错。此时只取别名展开的第一个候选，
+ * 是否真有这个文件交给写入阶段决定。
+ */
+function locate(
+  srcRoot: string,
+  sourceRootName: string,
+  fromRel: string,
+  spec: string,
+  alias?: AliasResolver,
+  existenceFree = false,
+): string | undefined {
+  if (spec.startsWith(".")) {
+    return posix.join(sourceRootName, posix.dirname(toPosix(fromRel)), spec);
+  }
+  const target =
+    alias?.locateFile(spec) ??
+    (existenceFree ? alias?.expandTarget(spec) : undefined);
+  if (target === undefined) return undefined;
+  return posix.relative(srcRoot, toPosix(target));
+}
+
+/**
+ * 形状判定：先看沙箱与层级，再看文件名是否等于目录名。
+ *
+ * `.ts` 与其余扩展名分开收口——`.ts` 同时也是故事源自己的扩展名，位置不合规时它只是
+ * 一个普通模块说明符，必须原样交回模块图（那里有源根沙箱与更准确的诊断）；其余扩展名
+ * 在本设计里只可能是 UI，位置不合规就是越界，fail-closed。
+ */
+function judge(
+  located: string,
+  sourceRootName: string,
+  extension: string,
+): UiOutcome {
+  if (located.startsWith("..") || posix.isAbsolute(located)) {
+    return { kind: "outside", target: located };
+  }
+  // 源根自己可能就叫 `ui`（sourcesDir 配成 `src/ui`）——那样 `ui/` 前缀指的是源树内部，
+  // 不是 UI 目录，必须交回模块图。
+  if (located === sourceRootName || located.startsWith(`${sourceRootName}/`)) {
+    return extension === ".ts"
+      ? { kind: "not-ui" }
+      : { kind: "outside", target: located };
+  }
+  const parts = located.split("/");
+  const shapeOk = parts.length === 3 && parts[0] === UI_DIR;
+  if (!shapeOk) {
+    return extension === ".ts"
+      ? { kind: "not-ui" }
+      : { kind: "outside", target: located };
+  }
+  const [, name, fileName] = parts as [string, string, string];
+  const base = fileName.slice(0, -extension.length);
+  if (base !== name) {
+    return extension === ".ts"
+      ? { kind: "not-ui" }
+      : { kind: "file-name", name, relPath: located };
+  }
+  return { kind: "ui", name, relPath: located };
+}