@defold-typescript/transpiler 0.23.0 → 0.25.0

package/dist/input-action-index.d.ts

@@ -0,0 +1 @@
+export declare function buildInputActionIndex(documents: ReadonlyMap<string, string>): ReadonlySet<string>;

package/dist/output-paths.d.ts

@@ -0,0 +1,11 @@
+export type ScriptKind = "script" | "gui-script" | "render-script" | "editor-script";
+export type SourceOutputKind = ScriptKind | "module";
+export interface BuildConfig {
+    readonly outDir: string | undefined;
+    readonly include: string[];
+}
+export declare const DEFAULT_INCLUDE: string[];
+export declare const SCRIPT_SUFFIX_BY_KIND: Record<ScriptKind, string>;
+export declare function parseBuildConfig(raw: string): BuildConfig;
+export declare function stripIncludeBase(pattern: string): string;
+export declare function computeOutputRel(rel: string, config: BuildConfig, kind: SourceOutputKind): string;

package/dist/project-resources.d.ts

@@ -0,0 +1,2 @@
+export declare const SCAFFOLDED_DEFIGNORE_LINES: string[];
+export declare function isDefignoredPath(displayPath: string): boolean;

package/dist/scene-component-index.d.ts

@@ -0,0 +1,5 @@
+export interface SceneComponentIndex {
+    readonly ids: ReadonlySet<string>;
+    readonly incomplete: readonly string[];
+}
+export declare function buildSceneComponentIndex(documents: ReadonlyMap<string, string>): SceneComponentIndex;

package/dist/scene-object-path-index.d.ts

@@ -0,0 +1,6 @@
+export interface SceneObjectPathIndex {
+    readonly paths: ReadonlySet<string>;
+    readonly declaredIn: ReadonlyMap<string, readonly string[]>;
+    readonly incomplete: readonly string[];
+}
+export declare function buildSceneObjectPathIndex(documents: ReadonlyMap<string, string>): SceneObjectPathIndex;

package/dist/scene-text-format.d.ts

@@ -0,0 +1,9 @@
+export interface SceneMessage {
+    readonly fields: ReadonlyMap<string, readonly string[]>;
+    readonly messages: ReadonlyMap<string, readonly SceneMessage[]>;
+}
+export declare class SceneTextFormatError extends Error {
+    readonly line: number;
+    constructor(message: string, line: number);
+}
+export declare function parseSceneTextFormat(text: string): SceneMessage;

package/dist/sprite-animation-index.d.ts

@@ -0,0 +1,10 @@
+export interface SpriteAnimationIndex {
+    readonly byScriptResource: ReadonlyMap<string, ReadonlyMap<string, ReadonlySet<string>>>;
+    readonly tileSetByScriptResource: ReadonlyMap<string, ReadonlyMap<string, string>>;
+    readonly unresolved: readonly string[];
+}
+export declare function buildSpriteAnimationIndex(input: {
+    scenes: ReadonlyMap<string, string>;
+    assets: ReadonlyMap<string, string>;
+}): SpriteAnimationIndex;
+export declare function componentIdOfSameObjectAddress(address: string): string | undefined;

package/dist/url-address-slots.d.ts

@@ -0,0 +1,19 @@
+import type { UrlParameterClass, UrlParameterTable } from "@defold-typescript/types";
+import * as ts from "typescript";
+export interface ClassifiedSlot {
+    readonly class: UrlParameterClass;
+    readonly text: string;
+    readonly textStart: number;
+    readonly fragmentStart: number;
+    readonly addressText?: string;
+    readonly resourceExtensions?: readonly string[];
+}
+export declare function isAddressClass(parameterClass: UrlParameterClass): boolean;
+export declare function isFragmentCaret(slot: ClassifiedSlot, position: number): boolean;
+export declare function addressClassOfArgument(checker: ts.TypeChecker, table: UrlParameterTable, argument: ts.Expression): UrlParameterClass;
+export declare function resolveClassifiedSlotAtPosition(input: {
+    program: ts.Program;
+    table: UrlParameterTable;
+    fileName: string;
+    position: number;
+}): ClassifiedSlot | undefined;

package/dist/url-fragment-reachability.d.ts

@@ -0,0 +1,23 @@
+import type { UrlParameterTable } from "@defold-typescript/types";
+import * as ts from "typescript";
+import type { SceneComponentIndex } from "./scene-component-index";
+export interface UrlFragmentFinding {
+    readonly fileName: string;
+    readonly start: number;
+    readonly length: number;
+    readonly fragment: string;
+    readonly message: string;
+}
+export type UrlFragmentReport = {
+    readonly kind: "suppressed";
+    readonly reasons: readonly string[];
+} | {
+    readonly kind: "checked";
+    readonly findings: readonly UrlFragmentFinding[];
+};
+export declare function checkUrlFragmentReachability(input: {
+    program: ts.Program;
+    table: UrlParameterTable;
+    index: SceneComponentIndex;
+    sourceFiles?: readonly ts.SourceFile[];
+}): UrlFragmentReport;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@defold-typescript/transpiler",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "TypeScript-to-Lua build pipeline tuned for Defold's runtime.",
   "license": "MIT",
   "repository": {
@@ -35,7 +35,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@defold-typescript/types": "0.23.0",
+    "@defold-typescript/types": "0.25.0",
     "@typescript-to-lua/language-extensions": "1.19.0",
     "typescript-to-lua": "^1.36.0"
   }

package/src/config-key-index.ts

@@ -0,0 +1,34 @@
+// The `<section>.<key>` ids the project's `game.project` declares — the whole
+// universe `sys.get_config_string` can resolve, since a key the file never
+// writes answers the reader's default instead.
+//
+// Deliberately a line reader rather than a parse of the scene text format:
+// `game.project` is a flat INI the editor writes, the same shape
+// `readExtensionDependencies` already walks. A key may carry a `#`
+// (`dependencies#0`), which is part of its name here and never a fragment.
+
+function sectionNameOf(line: string): string | undefined {
+  const match = line.trim().match(/^\[(.+)\]$/);
+  return match?.[1];
+}
+
+export function buildConfigKeyIndex(gameProjectText: string): ReadonlySet<string> {
+  const keys = new Set<string>();
+  let section: string | undefined;
+  for (const line of gameProjectText.split("\n")) {
+    const header = sectionNameOf(line);
+    if (header !== undefined) {
+      section = header;
+      continue;
+    }
+    // A line before the first header belongs to no section, so it names nothing
+    // a reader could ask for.
+    if (section === undefined) continue;
+    const separator = line.indexOf("=");
+    if (separator === -1) continue;
+    const key = line.slice(0, separator).trim();
+    if (key === "") continue;
+    keys.add(`${section}.${key}`);
+  }
+  return keys;
+}

package/src/editor-script-erasure.ts

@@ -1,33 +1,46 @@
 import * as ts from "typescript";
 import {
   createReturnStatement,
+  type Expression,
   type Plugin,
   type Statement,
   type TransformationContext,
 } from "typescript-to-lua";
 
 export const EDITOR_FACTORY_MODULE = "@defold-typescript/types";
-export const EDITOR_FACTORY_NAME = "defineEditorScript";
-// Only the bare main entry for now; the walled `@defold-typescript/types/editor-script`
-// subpath import arrives with the per-kind editor wall (a deferred slice).
-const EDITOR_FACTORY_SPECIFIERS = new Set([EDITOR_FACTORY_MODULE]);
+export const EDITOR_SCRIPT_FACTORY_NAME = "defineEditorScript";
+export const EDITOR_COMMAND_FACTORY_NAME = "defineEditorCommand";
+const EDITOR_FACTORY_NAMES: ReadonlySet<string> = new Set([
+  EDITOR_SCRIPT_FACTORY_NAME,
+  EDITOR_COMMAND_FACTORY_NAME,
+]);
+// The bare main entry and the walled per-kind subpath the guide teaches; the
+// other kinds' subpaths export their own factories, never these.
+const EDITOR_FACTORY_SPECIFIERS = new Set([
+  EDITOR_FACTORY_MODULE,
+  `${EDITOR_FACTORY_MODULE}/editor-script`,
+]);
 
-function resolvesToEditorFactoryExport(callee: ts.Expression, checker: ts.TypeChecker): boolean {
+function resolveEditorFactoryExport(
+  callee: ts.Expression,
+  checker: ts.TypeChecker,
+): string | undefined {
   let symbol = checker.getSymbolAtLocation(callee);
   if (symbol === undefined) {
-    return false;
+    return undefined;
   }
   if (symbol.flags & ts.SymbolFlags.Alias) {
     symbol = checker.getAliasedSymbol(symbol);
   }
-  if (symbol.getName() !== EDITOR_FACTORY_NAME) {
-    return false;
+  const name = symbol.getName();
+  if (!EDITOR_FACTORY_NAMES.has(name)) {
+    return undefined;
   }
   const declaration = symbol.valueDeclaration ?? symbol.declarations?.[0];
   if (declaration === undefined) {
-    return false;
+    return undefined;
   }
-  return declaration.getSourceFile().fileName.includes(EDITOR_FACTORY_MODULE);
+  return declaration.getSourceFile().fileName.includes(EDITOR_FACTORY_MODULE) ? name : undefined;
 }
 
 // Unlike the runtime kinds (lowered to flat top-level lifecycle globals), the
@@ -41,7 +54,12 @@ function lowerEditorFactoryCall(
   if (!ts.isCallExpression(expression)) {
     return undefined;
   }
-  if (!resolvesToEditorFactoryExport(expression.expression, context.checker)) {
+  // Only the module factory owns the chunk-level return; a command factory call
+  // is unwrapped in place by the `CallExpression` visitor below.
+  if (
+    resolveEditorFactoryExport(expression.expression, context.checker) !==
+    EDITOR_SCRIPT_FACTORY_NAME
+  ) {
     return undefined;
   }
   const module = expression.arguments[0];
@@ -77,8 +95,8 @@ export function isEditorFactoryOnlyImport(node: ts.ImportDeclaration): boolean {
   if (runtime.length === 0) {
     return false;
   }
-  return runtime.every(
-    (element) => (element.propertyName ?? element.name).text === EDITOR_FACTORY_NAME,
+  return runtime.every((element) =>
+    EDITOR_FACTORY_NAMES.has((element.propertyName ?? element.name).text),
   );
 }
 
@@ -96,6 +114,19 @@ export const editorScriptErasurePlugin: Plugin = {
       }
       return context.superTransformStatements(node);
     },
+    // `defineEditorCommand` is a compile-time identity with no runtime
+    // counterpart once its import is erased, so the call must collapse to the
+    // command table it wraps rather than survive as a nil-global call.
+    [ts.SyntaxKind.CallExpression]: (node, context): Expression => {
+      const command = node.arguments[0];
+      if (
+        command !== undefined &&
+        resolveEditorFactoryExport(node.expression, context.checker) === EDITOR_COMMAND_FACTORY_NAME
+      ) {
+        return context.transformExpression(command);
+      }
+      return context.superTransformExpression(node);
+    },
     [ts.SyntaxKind.ImportDeclaration]: (node, context) =>
       isEditorFactoryOnlyImport(node) ? [] : context.superTransformStatements(node),
   },

package/src/gui-node-index.ts

@@ -0,0 +1,71 @@
+import { parseSceneTextFormat, SceneTextFormatError } from "./scene-text-format";
+
+// The node ids each script may address, keyed by the project-relative resource
+// path of the `.gui_script` that owns them, plus an honest record of every scene
+// whose ownership could not be settled. A key's absence is not an empty scene:
+// it means no single `.gui` owns that resource, so nothing may be offered for
+// it.
+export interface GuiNodeIndex {
+  readonly byScriptResource: ReadonlyMap<string, ReadonlySet<string>>;
+  readonly unresolved: readonly string[];
+}
+
+// A `.gui` names its script as a project-absolute resource path, and the key is
+// that path with the leading `/` removed — never a guess at the source it came
+// from. An output path cannot say which include base was stripped to produce it,
+// so the only well-defined direction is forward: a caller maps the file it holds
+// through the build's own output-path math and looks the result up here. A
+// hand-written Lua `.gui_script` keys itself, which no computed name (always
+// `.ts.gui_script`) can equal, so it needs no separate check.
+const SCRIPT_SUFFIX = ".gui_script";
+
+function scriptKeyOf(script: string): string | undefined {
+  if (!script.endsWith(SCRIPT_SUFFIX)) return undefined;
+  const key = script.startsWith("/") ? script.slice(1) : script;
+  return key === SCRIPT_SUFFIX ? undefined : key;
+}
+
+export function buildGuiNodeIndex(documents: ReadonlyMap<string, string>): GuiNodeIndex {
+  const byScriptResource = new Map<string, ReadonlySet<string>>();
+  const claimedBy = new Map<string, string>();
+  const unresolved: string[] = [];
+
+  for (const [displayPath, text] of documents) {
+    let document: ReturnType<typeof parseSceneTextFormat>;
+    try {
+      document = parseSceneTextFormat(text);
+    } catch (error) {
+      if (!(error instanceof SceneTextFormatError)) throw error;
+      unresolved.push(`${displayPath}: could not be parsed (${error.message})`);
+      continue;
+    }
+
+    const [script] = document.fields.get("script") ?? [];
+    if (script === undefined) continue;
+    const key = scriptKeyOf(script);
+    if (key === undefined) continue;
+
+    const owner = claimedBy.get(key);
+    if (owner !== undefined) {
+      byScriptResource.delete(key);
+      unresolved.push(
+        `${key}: claimed by both ${owner} and ${displayPath}, so its node ids are ambiguous`,
+      );
+      continue;
+    }
+    claimedBy.set(key, displayPath);
+
+    // Top-level `nodes` only. A `layouts` or `templates` block repeats a node
+    // under an override, and walking into them would offer the same id twice
+    // while inventing ids from scenes this script does not drive.
+    const ids = new Set<string>();
+    for (const message of document.messages.get("nodes") ?? []) {
+      for (const id of message.fields.get("id") ?? []) {
+        if (id !== "") ids.add(id);
+      }
+    }
+    byScriptResource.set(key, ids);
+  }
+
+  return { byScriptResource, unresolved };
+}

package/src/index.ts

@@ -1,7 +1,31 @@
+export { buildConfigKeyIndex } from "./config-key-index";
+export type { GuiNodeIndex } from "./gui-node-index";
+export { buildGuiNodeIndex } from "./gui-node-index";
+export { buildInputActionIndex } from "./input-action-index";
 export { findMainEntryFactoryImports } from "./main-entry-factory-imports";
+export type { BuildConfig, ScriptKind, SourceOutputKind } from "./output-paths";
+export {
+  computeOutputRel,
+  DEFAULT_INCLUDE,
+  parseBuildConfig,
+  SCRIPT_SUFFIX_BY_KIND,
+  stripIncludeBase,
+} from "./output-paths";
 export { getProgramDiagnostics } from "./program-diagnostics";
+export { isDefignoredPath, SCAFFOLDED_DEFIGNORE_LINES } from "./project-resources";
+export type { SceneComponentIndex } from "./scene-component-index";
+export { buildSceneComponentIndex } from "./scene-component-index";
+export type { SceneObjectPathIndex } from "./scene-object-path-index";
+export { buildSceneObjectPathIndex } from "./scene-object-path-index";
+export type { SceneMessage } from "./scene-text-format";
+export { parseSceneTextFormat, SceneTextFormatError } from "./scene-text-format";
 export type { TranspileSession } from "./session";
 export { createTranspileSession } from "./session";
+export type { SpriteAnimationIndex } from "./sprite-animation-index";
+export {
+  buildSpriteAnimationIndex,
+  componentIdOfSameObjectAddress,
+} from "./sprite-animation-index";
 export type {
   TranspileDiagnostic,
   TranspileProjectInput,
@@ -9,3 +33,12 @@ export type {
   TranspileResult,
 } from "./transpile";
 export { transpile, transpileProject } from "./transpile";
+export type { ClassifiedSlot } from "./url-address-slots";
+export {
+  addressClassOfArgument,
+  isAddressClass,
+  isFragmentCaret,
+  resolveClassifiedSlotAtPosition,
+} from "./url-address-slots";
+export type { UrlFragmentFinding, UrlFragmentReport } from "./url-fragment-reachability";
+export { checkUrlFragmentReachability } from "./url-fragment-reachability";

package/src/input-action-index.ts

@@ -0,0 +1,41 @@
+import { parseSceneTextFormat, SceneTextFormatError } from "./scene-text-format";
+
+// The action names the project's `.input_binding` files declare — the whole
+// universe an `on_input` handler can compare against, since an action no binding
+// produces never fires. A project-wide union, deliberately: which binding is
+// live is a `game.project` `[input] game_binding` setting, and a suggestion
+// claims nothing about what is absent.
+//
+// Every top-level sub-message contributes, not a list of the trigger kinds
+// Defold ships today: `key_trigger`, `mouse_trigger`, `gamepad_trigger` and
+// `text_trigger` all carry the same `action` field, and a kind added upstream
+// would otherwise drop out of the universe silently. The `input` half names an
+// engine constant rather than anything the project declares, so it is never
+// offered.
+//
+// A document that will not parse is skipped and its siblings still contribute —
+// the same honest-hole convention `buildGuiNodeIndex` uses, with no `unresolved`
+// channel because nothing here reports.
+export function buildInputActionIndex(documents: ReadonlyMap<string, string>): ReadonlySet<string> {
+  const actions = new Set<string>();
+
+  for (const text of documents.values()) {
+    let document: ReturnType<typeof parseSceneTextFormat>;
+    try {
+      document = parseSceneTextFormat(text);
+    } catch (error) {
+      if (!(error instanceof SceneTextFormatError)) throw error;
+      continue;
+    }
+
+    for (const triggers of document.messages.values()) {
+      for (const trigger of triggers) {
+        for (const action of trigger.fields.get("action") ?? []) {
+          if (action !== "") actions.add(action);
+        }
+      }
+    }
+  }
+
+  return actions;
+}

package/src/lifecycle-erasure.ts

@@ -312,13 +312,22 @@ export function isFactoryOnlyImport(node: ts.ImportDeclaration): boolean {
   if (clause === undefined || clause.name !== undefined) {
     return false;
   }
+  // A whole-clause `import type { ... }` binds nothing at runtime; leave it for
+  // the normal transform, which elides it.
+  if (clause.isTypeOnly) {
+    return false;
+  }
   const bindings = clause.namedBindings;
   if (bindings === undefined || !ts.isNamedImports(bindings)) {
     return false;
   }
-  return bindings.elements.every((element) =>
-    FACTORY_NAMES.has((element.propertyName ?? element.name).text),
-  );
+  // Type-only specifiers ride along and drop with the erased statement; erase
+  // only when every runtime specifier is a lifecycle factory.
+  const runtime = bindings.elements.filter((element) => !element.isTypeOnly);
+  if (runtime.length === 0) {
+    return false;
+  }
+  return runtime.every((element) => FACTORY_NAMES.has((element.propertyName ?? element.name).text));
 }
 
 export const lifecycleErasurePlugin: Plugin = {

package/src/output-paths.ts

@@ -0,0 +1,69 @@
+import * as path from "node:path";
+
+export type ScriptKind = "script" | "gui-script" | "render-script" | "editor-script";
+
+export type SourceOutputKind = ScriptKind | "module";
+
+export interface BuildConfig {
+  readonly outDir: string | undefined;
+  readonly include: string[];
+}
+
+interface TsConfig {
+  compilerOptions?: {
+    outDir?: string;
+  };
+  include?: string[];
+}
+
+export const DEFAULT_INCLUDE = ["src/**/*.ts"];
+
+export const SCRIPT_SUFFIX_BY_KIND: Record<ScriptKind, string> = {
+  script: ".ts.script",
+  "gui-script": ".ts.gui_script",
+  "render-script": ".ts.render_script",
+  "editor-script": ".ts.editor_script",
+};
+
+// The `tsconfig.json` reading the output-path math depends on, separated from
+// how the text was obtained: the CLI reads it off disk, the editor plugin gets
+// it from the language-service host, and both must derive the same names from
+// the same text or the plugin predicts a resource the build never writes.
+export function parseBuildConfig(raw: string): BuildConfig {
+  const tsconfig = JSON.parse(raw) as TsConfig;
+  const outDir = tsconfig.compilerOptions?.outDir;
+  const include = tsconfig.include?.length ? tsconfig.include : DEFAULT_INCLUDE;
+  return { outDir, include };
+}
+
+export function stripIncludeBase(pattern: string): string {
+  const firstWildcard = pattern.search(/[*?[]/);
+  if (firstWildcard === -1) {
+    return pattern.endsWith("/") ? pattern : `${path.posix.dirname(pattern)}/`;
+  }
+  const upToWildcard = pattern.slice(0, firstWildcard);
+  const lastSlash = upToWildcard.lastIndexOf("/");
+  return lastSlash === -1 ? "" : upToWildcard.slice(0, lastSlash + 1);
+}
+
+function relUnderOutDir(rel: string, config: BuildConfig): string {
+  const { outDir, include } = config;
+  if (outDir === undefined || outDir === "" || outDir === ".") {
+    return rel;
+  }
+  const includeBase =
+    include
+      .map(stripIncludeBase)
+      .filter((base) => rel.startsWith(base))
+      .sort((a, b) => b.length - a.length)[0] ?? "";
+  const relUnderBase = rel.slice(includeBase.length);
+  return path.posix.join(outDir, relUnderBase);
+}
+
+export function computeOutputRel(rel: string, config: BuildConfig, kind: SourceOutputKind): string {
+  const baseRel = relUnderOutDir(rel, config);
+  if (kind === "module") {
+    return baseRel.replace(/\.ts$/, ".lua");
+  }
+  return baseRel.replace(/\.ts$/, SCRIPT_SUFFIX_BY_KIND[kind]);
+}

package/src/project-resources.ts

@@ -0,0 +1,20 @@
+// The Defold editor and bob read neither `.gitignore` nor `.vscode`; they scan
+// the whole project tree for resources. `.defignore` (one root-relative path per
+// line) is how a project tells them to skip a folder. These three carry files
+// the editor would otherwise misread as project resources: `node_modules`
+// dependency trees, the resolver-generated `.defold-types` LuaLS surface, and
+// `.vscode` config plus the multi-MB debug engine binary. `src/` is never
+// listed — its emitted `.ts.script`/`.gui_script`/`.lua` components are exactly
+// what Defold must load. Committed config (not in `GITIGNORE_LINES`, like
+// `.vscode`).
+export const SCAFFOLDED_DEFIGNORE_LINES = ["/node_modules", "/.defold-types", "/.vscode"];
+
+// Whether a project-relative display path lies under one of the lines `init`
+// scaffolds. Root-anchored, because a `.defignore` line is a root-relative
+// path: `assets/node_modules/tiles.atlas` is a resource Defold loads.
+export function isDefignoredPath(displayPath: string): boolean {
+  const rooted = `/${displayPath.replace(/^\/+/, "")}`;
+  return SCAFFOLDED_DEFIGNORE_LINES.some(
+    (line) => rooted === line || rooted.startsWith(`${line}/`),
+  );
+}

package/src/scene-component-index.ts

@@ -0,0 +1,80 @@
+import { parseSceneTextFormat, type SceneMessage, SceneTextFormatError } from "./scene-text-format";
+
+// Every component id the project declares, plus an honest record of everything
+// the walk could not read. A non-empty `incomplete` means the universe is not
+// provably whole, so no consumer may conclude that a missing id is absent.
+export interface SceneComponentIndex {
+  readonly ids: ReadonlySet<string>;
+  readonly incomplete: readonly string[];
+}
+
+// `id` under these names is a component id. `instances`,
+// `collection_instances` and `embedded_instances` carry game-object ids, which
+// name a *path* — and a path can never be proven wrong, because `factory.create`
+// invents them at runtime.
+const COMPONENT_BLOCKS = new Set(["components", "embedded_components"]);
+
+// The only two places Defold embeds a whole escaped document in `data:`. Every
+// other `data:` is a plain scalar — `embedded_collision_shape` stores sphere
+// radii there — so re-parsing all of them would report the repo's own example
+// projects as unreadable and suppress the check for good.
+const EMBEDDING_BLOCKS = new Set(["embedded_instances", "embedded_components"]);
+
+function collect(
+  message: SceneMessage,
+  blockName: string,
+  depth: number,
+  displayPath: string,
+  ids: Set<string>,
+  incomplete: string[],
+): void {
+  if (COMPONENT_BLOCKS.has(blockName)) {
+    for (const id of message.fields.get("id") ?? []) {
+      ids.add(id);
+    }
+  }
+  if (EMBEDDING_BLOCKS.has(blockName)) {
+    for (const payload of message.fields.get("data") ?? []) {
+      try {
+        collect(parseSceneTextFormat(payload), "", depth + 1, displayPath, ids, incomplete);
+      } catch (error) {
+        if (!(error instanceof SceneTextFormatError)) throw error;
+        incomplete.push(
+          `${displayPath}: embedded payload at depth ${depth + 1} could not be parsed (${error.message})`,
+        );
+      }
+    }
+  }
+  for (const [name, nested] of message.messages) {
+    for (const child of nested) {
+      collect(child, name, depth, displayPath, ids, incomplete);
+    }
+  }
+}
+
+// Build the component-id universe from already-read scene sources: keys are
+// display paths, values are file text. Pure — the filesystem walk belongs to the
+// caller, so a test can drive this from inline strings and a build can drive it
+// from a real scan.
+export function buildSceneComponentIndex(
+  documents: ReadonlyMap<string, string>,
+): SceneComponentIndex {
+  const ids = new Set<string>();
+  const incomplete: string[] = [];
+
+  if (documents.size === 0) {
+    incomplete.push("no scene sources were read, so no component id can be proven absent");
+    return { ids, incomplete };
+  }
+
+  for (const [displayPath, text] of documents) {
+    try {
+      collect(parseSceneTextFormat(text), "", 0, displayPath, ids, incomplete);
+    } catch (error) {
+      if (!(error instanceof SceneTextFormatError)) throw error;
+      incomplete.push(`${displayPath}: could not be parsed (${error.message})`);
+    }
+  }
+
+  return { ids, incomplete };
+}