@volter/sdk 0.0.0-stage → 0.5.203

package/src/kit/project-module-split.ts

@@ -0,0 +1,270 @@
+/**
+ * PD-3's runtime backstop: DETECT a cross-root module split and report it
+ * LOUDLY, so the next one can never be silent the way the measured one was
+ * ("HUD rendered defaults forever while `game.state()` moved; no error, no
+ * warning").
+ *
+ * `project-module-url.ts` removes the deterministic CAUSE (one mount epoch
+ * shared by every root's entry url). This module is the tripwire for whatever
+ * that guarantee does not cover — a future root resolver that hand-builds a
+ * url, a `/@fs//doubled-slash` form reappearing, a symlink-uncanonical root,
+ * or a source edit landing between two roots' transforms inside one mount.
+ *
+ * HOW IT MEASURES, and why this observable and not another
+ * --------------------------------------------------------
+ * Browser ES-module identity is per-URL and a module is EVALUATED exactly
+ * once per url, so "two live instances of one file" is exactly "two distinct
+ * urls for one file were fetched as modules". Resource Timing already records
+ * every one of those fetches with a timestamp, which makes the whole check a
+ * pure function over `performance.getEntriesByType('resource')` — no
+ * instrumentation injected into project code, no per-module cost, and
+ * trivially unit-testable against a synthetic entry list.
+ *
+ * The window matters, and is what keeps this SOUND rather than noisy:
+ *
+ *  - Counting over the whole session would fire on every healthy remount —
+ *    an edited module legitimately gets a new `?t=` url each mount, and the
+ *    superseded instance's fetch stays in the timeline forever.
+ *  - Counting only fetches made DURING one mount cannot false-positive: a
+ *    single mount has no legitimate reason to evaluate one file twice. A file
+ *    reused from the browser's module registry is not re-fetched, so it never
+ *    inflates the count.
+ *
+ * The cost of that soundness is the honest gap recorded here: the ONE case
+ * this cannot see is a root that reuses a cached module while a sibling
+ * evaluates a fresh one (the original PD-3 shape) — the cached side performs
+ * no fetch at all. That case is closed by construction upstream, in
+ * `project-module-url.ts`; this module is deliberately the second line, not
+ * the first.
+ */
+
+/** The Resource Timing fields this module reads — declared structurally so a
+ *  test can hand over a plain array and so nothing here depends on the DOM
+ *  lib's `PerformanceResourceTiming`. */
+export interface ResourceTimingLike {
+  readonly name: string;
+  readonly startTime: number;
+}
+
+/** One file that was evaluated more than once inside a single mount. */
+export interface ProjectModuleSplit {
+  /** The file's path (query stripped) — the `/@fs/…` pathname as fetched, so
+   *  it names the module the way every other editor/dev-server message does. */
+  readonly path: string;
+  /** Every distinct url the file was fetched under during the window, in
+   *  fetch order. Always length >= 2. */
+  readonly urls: readonly string[];
+}
+
+/** Module-graph extensions vite serves for a NON-module purpose — the same
+ *  file legitimately produces a different module for each of these, so two
+ *  urls differing only by one of them is not a split. */
+const NON_MODULE_QUERY_KEYS = new Set(['raw', 'url', 'worker', 'sharedworker', 'inline', 'init']);
+
+import { PROJECT_MOUNT_QUERY } from '@volter/sdk/session/project-module-url';
+
+const MODULE_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'];
+const STORY_MODULE_PATTERN = /\.stories\.[cm]?[jt]sx?$/i;
+
+function pathAndQuery(name: string): { path: string; query: string } | null {
+  // Resource Timing `name` is an absolute url. Parsing against a fixed base
+  // keeps this pure (no `window.location` read) and works for both forms.
+  let parsed: URL;
+  try {
+    parsed = new URL(name, 'http://volter.invalid');
+  } catch {
+    return null;
+  }
+  return { path: parsed.pathname, query: parsed.search };
+}
+
+function isNonModuleQuery(query: string): boolean {
+  const params = new URLSearchParams(query);
+  for (const key of params.keys()) {
+    if (NON_MODULE_QUERY_KEYS.has(key)) return true;
+  }
+  return false;
+}
+
+/**
+ * The pure half: given the Resource Timing entries of one mount window and
+ * the project's absolute root, return every project file fetched under more
+ * than one url.
+ *
+ * `projectRoot` is matched against the `/@fs/`-mounted pathname, which is how
+ * every project module the editor imports is served in dev. A project served
+ * some other way simply yields no candidates — an empty result, never a
+ * fabricated one.
+ */
+/** The one candidate test: is this fetch a MODULE of the project under test?
+ *  Split out so the grouping loop stays one thing. */
+function projectModuleFetch(
+  entry: ResourceTimingLike,
+  root: string,
+  since: number,
+): { group: string; path: string; url: string } | null {
+  if (entry.startTime < since) return null;
+  const parts = pathAndQuery(entry.name);
+  if (!parts) return null;
+  const { path, query } = parts;
+  if (!path.includes(root)) return null;
+  if (!MODULE_EXTENSIONS.some((ext) => path.endsWith(ext))) return null;
+  // Portable CSF is a design-time document, not part of a mounted root's
+  // runtime module graph. Story discovery deliberately gives every refresh a
+  // fresh `?t=` URL (`stories/story-discovery.ts`), and a board refresh may
+  // overlap this Play mount window. Counting that intentional reload as a
+  // cross-root split makes a healthy multi-root game report an error even
+  // though every root entry still shares the one `volter-mount` epoch.
+  if (STORY_MODULE_PATTERN.test(path)) return null;
+  // The project's adapter is the same shape: a binding table the editor reads
+  // WITHOUT booting the game (`project-adapter.ts`'s `importAdapterModule`), fresh
+  // `?t=` on every read, and imported by no root.
+  if (path.endsWith('/volter.adapter.ts')) return null;
+  if (isNonModuleQuery(query)) return null;
+  // The mount id is not a variant of a module — it names WHICH INSTANCE's copy
+  // this is, and per-instance module graphs are the isolation working (see
+  // ARCHITECTURE-CORE §Multiplayer authoring). Two instances fetch every
+  // project module under different urls BY DESIGN, so comparing across them
+  // would report the entire project as split the moment a second one mounts —
+  // every module, every time, on the loudest diagnostic in the play path.
+  // Group per instance instead: the question this watch asks ("did the roots
+  // of one mount fail to share a module?") is a per-instance question. With
+  // one instance — every mount today — there is one group and nothing changes.
+  const params = new URLSearchParams(query);
+  const mount = params.get(PROJECT_MOUNT_QUERY) ?? '';
+  params.delete(PROJECT_MOUNT_QUERY);
+  const rest = params.toString();
+  return {
+    group: `${mount}\u0000${path}`,
+    path,
+    url: `${path}${rest ? `?${rest}` : ''}`,
+  };
+}
+
+export function findProjectModuleSplits(
+  resources: readonly ResourceTimingLike[],
+  opts: { readonly projectRoot: string; readonly since: number },
+): ProjectModuleSplit[] {
+  const root = opts.projectRoot.endsWith('/') ? opts.projectRoot.slice(0, -1) : opts.projectRoot;
+  if (root.length === 0) return [];
+  const byGroup = new Map<string, { path: string; urls: string[] }>();
+
+  for (const entry of resources) {
+    const fetched = projectModuleFetch(entry, root, opts.since);
+    if (!fetched) continue;
+    const seen = byGroup.get(fetched.group);
+    if (seen === undefined) byGroup.set(fetched.group, { path: fetched.path, urls: [fetched.url] });
+    else if (!seen.urls.includes(fetched.url)) seen.urls.push(fetched.url);
+  }
+
+  const splits: ProjectModuleSplit[] = [];
+  for (const { path, urls } of byGroup.values()) {
+    if (urls.length > 1) splits.push({ path, urls });
+  }
+  return splits;
+}
+
+/**
+ * The message a split is reported with. Pure (and exported) so the wording is
+ * a testable contract rather than an inline string: a silent split is the
+ * entire defect, so the report has to NAME the module and show the two urls
+ * that prove it.
+ */
+export function formatProjectModuleSplitMessage(split: ProjectModuleSplit): string {
+  return (
+    `Cross-root module split: ${split.path} was loaded ${split.urls.length} times in one mount, ` +
+    'so each root holds its OWN copy of its module-level state (a `let` written by one root is ' +
+    'invisible to the other). Urls: ' +
+    split.urls.join('  |  ')
+  );
+}
+
+// ---------------------------------------------------------------------------
+// The stateful half — one mount window, and the reports it produced
+// ---------------------------------------------------------------------------
+
+interface PerformanceLike {
+  now(): number;
+  getEntriesByType(type: string): ResourceTimingLike[];
+}
+
+function performanceHost(): PerformanceLike | null {
+  const candidate = (globalThis as { performance?: unknown }).performance;
+  if (!candidate || typeof candidate !== 'object') return null;
+  const perf = candidate as Partial<PerformanceLike>;
+  if (typeof perf.now !== 'function' || typeof perf.getEntriesByType !== 'function') return null;
+  return perf as PerformanceLike;
+}
+
+// Capture this diagnostic window independently of the browser's bounded
+// Resource Timing history. Module lookup is owned by the game realm.
+let resourceObserver: PerformanceObserver | null = null;
+let windowResources: ResourceTimingLike[] = [];
+
+let windowStart: number | null = null;
+let reports: ProjectModuleSplit[] = [];
+
+/** Open the mount window. Called immediately before a composition's roots are
+ *  resolved/imported; clears the previous mount's reports so the diagnostic
+ *  can always go back to healthy (the PD-1 lesson — a report that cannot
+ *  clear itself is worse than none). */
+export function beginProjectModuleSplitWatch(): void {
+  reports = [];
+  resourceObserver?.disconnect();
+  resourceObserver = null;
+  windowResources = [];
+  const perf = performanceHost();
+  if (!perf) {
+    windowStart = null;
+    return;
+  }
+  windowStart = perf.now();
+  if (typeof PerformanceObserver !== 'undefined') {
+    resourceObserver = new PerformanceObserver((list) => {
+      windowResources.push(...list.getEntries());
+    });
+    resourceObserver.observe({ type: 'resource' });
+  }
+}
+
+/**
+ * Close the mount window and record what it found. Called after every root
+ * has mounted (not merely resolved) so a root that imports its entry lazily
+ * inside `mount()` is inside the window too. Returns the reports so the
+ * caller can log them; a no-op window (no `performance`, or no `begin`) is an
+ * empty result, never a guess.
+ */
+export function endProjectModuleSplitWatch(projectRoot: string): readonly ProjectModuleSplit[] {
+  const perf = performanceHost();
+  if (!perf || windowStart === null) {
+    windowStart = null;
+    return reports;
+  }
+  const entries = resourceObserver
+    ? [...windowResources, ...resourceObserver.takeRecords()]
+    : perf.getEntriesByType('resource');
+  resourceObserver?.disconnect();
+  resourceObserver = null;
+  windowResources = [];
+  reports = findProjectModuleSplits(entries, {
+    projectRoot,
+    since: windowStart,
+  });
+  windowStart = null;
+  return reports;
+}
+
+/** What the last closed mount window found — `[]` on a healthy mount. Read by
+ *  `command-listener.ts`'s `collectState` so the editor's `status` command carries it. */
+export function getProjectModuleSplitReports(): readonly ProjectModuleSplit[] {
+  return reports;
+}
+
+/** Drop every recorded split — what a torn-down play session calls. */
+export function clearProjectModuleSplitReports(): void {
+  resourceObserver?.disconnect();
+  resourceObserver = null;
+  windowResources = [];
+  reports = [];
+  windowStart = null;
+}

package/src/kit/project-play-layers.ts

@@ -0,0 +1,25 @@
+/** A UI tool offers project roots to any playing stage. The caller lends a
+ * container and one mount epoch shared with its world/script; Stop disposes it.
+ * Neither the game context nor a product needs an overlay field. */
+import type { ProjectMountEpoch } from '../session/project-module-url';
+export interface MountedProjectPlayLayers {
+  /** Entries whose dependency graph belongs to these layers. */
+  readonly entries: readonly string[];
+  dispose(): void;
+}
+export type ProjectPlayLayers = (options: {
+  readonly projectRoot: string;
+  readonly epoch: ProjectMountEpoch;
+  readonly container: HTMLElement;
+  /** Report all declared entries before importing or mounting them, so a failed
+   * first mount can be retried when an entry or its dependency is saved. */
+  readonly onEntries: (entries: readonly string[]) => void;
+}) => Promise<MountedProjectPlayLayers>;
+const key = Symbol.for('volter.project-play-layers');
+const page = globalThis as typeof globalThis & { [key]?: ProjectPlayLayers };
+export function projectPlayLayers(): ProjectPlayLayers | null { return page[key] ?? null; }
+export function registerProjectPlayLayers(provider: ProjectPlayLayers): () => void {
+  if (page[key]) throw new Error('A UI tool already offers project Play layers.');
+  page[key] = provider;
+  return () => { if (page[key] === provider) delete page[key]; };
+}

package/src/kit/project-provenance.ts

@@ -0,0 +1,115 @@
+const PROVENANCE_PATH = '.volter/provenance.json';
+
+export interface ProjectOutputProvenance {
+  readonly operationId: string;
+  readonly createdAt: string;
+  readonly operationName: string;
+  readonly operationSource?: string;
+  readonly input?: unknown;
+  readonly output: {
+    readonly path: string;
+    readonly bytes: number;
+    readonly sha256: string;
+    readonly mediaType?: string;
+    readonly role?: string;
+  };
+}
+
+/** The project-root-relative FILE behind a served asset path — the served path
+ *  with `public/` put back, which is where a writer's bytes have to land. */
+export function projectOutputPath(assetPath: string): string {
+  const clean = assetPath.split(/[?#]/, 1)[0]!.replace(/^\/+/, '');
+  return clean.startsWith('public/') ? clean : `public/${clean}`;
+}
+
+async function readProjectProvenance(): Promise<unknown> {
+  // NOT read through `editor-server-response.ts`: this route's GET half serves
+  // raw file bytes as `text/plain` (routes/project-source.ts), and that reader
+  // asserts `application/json` — it would reject the success case.
+  const response = await fetch(
+    `/__editor/volter-file?${new URLSearchParams({ path: PROVENANCE_PATH })}`,
+  );
+  if (!response.ok) return null;
+  return JSON.parse(await response.text());
+}
+
+function record(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+function parsedOutput(
+  value: unknown,
+  expectedPath: string,
+): ProjectOutputProvenance['output'] | null {
+  const output = record(value);
+  if (
+    output?.['path'] !== expectedPath ||
+    typeof output['bytes'] !== 'number' ||
+    typeof output['sha256'] !== 'string'
+  )
+    return null;
+  const mediaType = output['mediaType'];
+  const role = output['role'];
+  return {
+    path: expectedPath,
+    bytes: output['bytes'],
+    sha256: output['sha256'],
+    ...(typeof mediaType === 'string' ? { mediaType } : {}),
+    ...(typeof role === 'string' ? { role } : {}),
+  };
+}
+
+function operationMatches(
+  operationId: string,
+  value: unknown,
+  expectedPath: string,
+): ProjectOutputProvenance[] {
+  const operation = record(value);
+  const identity = record(operation?.['operation']);
+  const outputs = operation?.['outputs'];
+  const createdAt = operation?.['createdAt'];
+  const operationName = identity?.['name'];
+  if (
+    !operation ||
+    !identity ||
+    typeof createdAt !== 'string' ||
+    typeof operationName !== 'string' ||
+    !Array.isArray(outputs)
+  )
+    return [];
+  const operationSource = identity['source'];
+  return outputs.flatMap((value) => {
+    const output = parsedOutput(value, expectedPath);
+    if (!output) return [];
+    return [
+      {
+        operationId,
+        createdAt,
+        operationName,
+        ...(typeof operationSource === 'string' ? { operationSource } : {}),
+        ...(operation['input'] !== undefined ? { input: operation['input'] } : {}),
+        output,
+      },
+    ];
+  });
+}
+
+/** Resolve the newest central provenance operation that produced this asset path. */
+export async function provenanceForProjectAsset(
+  assetPath: string,
+): Promise<ProjectOutputProvenance | null> {
+  const document = record(await readProjectProvenance());
+  const operations = record(document?.['operations']);
+  if (!operations) return null;
+  const expectedPath = projectOutputPath(assetPath);
+  const matches = Object.entries(operations).flatMap(([operationId, operation]) =>
+    operationMatches(operationId, operation, expectedPath),
+  );
+  return matches.sort((left, right) => right.createdAt.localeCompare(left.createdAt))[0] ?? null;
+}
+
+export function __projectOutputPathForTest(assetPath: string): string {
+  return projectOutputPath(assetPath);
+}

package/src/kit/project-ready.ts

@@ -0,0 +1,42 @@
+/**
+ * THE PROJECT-READY HOOK — the host's side of `host.project.onReady`: the
+ * moment both bootstraps (`the world root's stage`'s boot chain, after the scene
+ * loads and the composite installs; `NonThreeAuthoringBootstrap`'s, after
+ * its composite installs) reach when a lane may auto-launch what the
+ * manifest declares. Listeners run in registration order, each awaited, so
+ * a later one may read what an earlier one mounted.
+ *
+ * LATCHED, per project, for the same reason `hosted-example.ts`'s auto-play
+ * decision is: this hook's registrants are PACKAGE SERVICES, and a
+ * contribution pass is asynchronous — it can finish on either side of the
+ * boot chain. Unlatched, a service that registered one tick late simply
+ * never ran, and the lane it starts (the ingest auto-launch) silently
+ * did nothing for the whole session; measured 2026-09-17 on a staged
+ * vendored game, which mounted nothing at all. The latch is keyed to the
+ * project that reached ready, so opening a second project does not fire its
+ * services against the first project's boot.
+ */
+import { getCurrentProject } from '@volter/sdk/kit/project-manager';
+
+const listeners = new Set<() => void | Promise<void>>();
+
+/** The `rootPath` of the project whose boot chain last reached ready. */
+let readyFor: string | null = null;
+
+function currentProjectKey(): string | null {
+  return getCurrentProject()?.rootPath ?? null;
+}
+
+export function onProjectReady(fn: () => void | Promise<void>): () => void {
+  listeners.add(fn);
+  const key = currentProjectKey();
+  if (key !== null && readyFor === key) void fn();
+  return () => {
+    listeners.delete(fn);
+  };
+}
+
+export async function runProjectReady(): Promise<void> {
+  readyFor = currentProjectKey();
+  for (const fn of [...listeners]) await fn();
+}

package/src/kit/project-shape.ts

@@ -0,0 +1,68 @@
+/**
+ * What the active project DECLARES, as the chrome reads it (ARCHITECTURE-CORE
+ * §Roots: "a project's shape is derived from what it declares, never
+ * assumed"). Nothing here names a kind of project; the questions are the
+ * ones chrome actually has — does anything mount? — answered from the
+ * manifest's own `roots`.
+ */
+
+import { useSyncExternalStore } from 'react';
+import { getCurrentProject, onProjectChange } from '@volter/sdk/kit/active-project';
+
+/** True when the active project declares at least one root — something the
+ *  host mounts, plays and instances. A project config from before
+ *  `rootCount` existed answers true, which is what every project was. */
+export function projectMounts(): boolean {
+  const count = getCurrentProject()?.config.rootCount;
+  return count === undefined ? true : count > 0;
+}
+
+/** {@link projectMounts} as a React subscription. */
+export function useProjectMounts(): boolean {
+  return useSyncExternalStore(onProjectChange, projectMounts, projectMounts);
+}
+
+const shapeListeners = new Set<() => void>();
+
+/** The adapter host resolved (or re-resolved) the document table: what the
+ *  project declares may have changed without the project itself changing. */
+export function notifyProjectShapeChanged(): void {
+  for (const fn of shapeListeners) fn();
+}
+
+/** Fires on {@link notifyProjectShapeChanged} and on a project change. */
+export function subscribeProjectShape(fn: () => void): () => void {
+  shapeListeners.add(fn);
+  const stopProject = onProjectChange(fn);
+  return () => {
+    shapeListeners.delete(fn);
+    stopProject();
+  };
+}
+
+/** The document kinds the active project's resolved table holds, supplied by
+ *  the adapter host (`project-adapter.ts` registers it) so this module —
+ *  which a bounded host's closure carries — imports no adapter machinery. `null`
+ *  until an adapter has resolved. */
+let documentKindsSupplier: (() => readonly string[] | null) | null = null;
+export function registerDocumentKindsSupplier(supplier: () => readonly string[] | null): void {
+  documentKindsSupplier = supplier;
+}
+
+/** True when the active project's resolved document table holds an entry
+ *  of `kind` — what a workspace built around one kind of document requires
+ *  (Model, Sculpt and Texture require a `model`). Before the adapter has
+ *  resolved, the answer is true, so a workspace never vanishes mid-boot. */
+export function projectDeclaresDocumentKind(kind: string): boolean {
+  const kinds = documentKindsSupplier?.() ?? null;
+  if (kinds === null) return true;
+  return kinds.includes(kind);
+}
+
+/** The same answer as a LIST, for a message that has to name the vocabulary
+ *  rather than test one value against it (`present-view`'s refusal on an
+ *  unknown document kind). `null` before the adapter has resolved — a refusal
+ *  that cannot read the table says less, never something invented. */
+export function projectDocumentKinds(): readonly string[] | null {
+  return documentKindsSupplier?.() ?? null;
+}

package/src/kit/project-tools.ts

@@ -0,0 +1,107 @@
+import type { ProjectToolCatalog } from '@volter/sdk/project-tool-catalog';
+import { connectToolFileEvents } from './asset-events';
+import { editorServerJson } from '@volter/sdk/kit/editor-server-response';
+import { onProjectChange } from './project-manager';
+
+export type {
+  ProjectToolCatalog,
+  ProjectToolCatalogEntry,
+  ProjectToolContribution,
+  ToolContributionPoint,
+} from '@volter/sdk/project-tool-catalog';
+
+export type ProjectToolOutcome =
+  | {
+      ok: true;
+      data: unknown;
+      generation?: import('@volter/sdk/generations').GenerationJob;
+      generationWarning?: string;
+    }
+  | { ok: false; error: { code: string; message: string; data?: unknown; issues?: unknown[] } };
+
+const EMPTY_CATALOG: ProjectToolCatalog = { tools: [], contributions: [], loadErrors: [] };
+let catalog = EMPTY_CATALOG;
+let version = 0;
+const listeners = new Set<() => void>();
+
+function publish(next: ProjectToolCatalog): void {
+  catalog = next;
+  version++;
+  for (const listener of listeners) listener();
+}
+
+export function getProjectTools(): ProjectToolCatalog {
+  return catalog;
+}
+
+export function projectToolsVersion(): number {
+  return version;
+}
+
+export function subscribeProjectTools(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export async function refreshProjectTools(): Promise<ProjectToolCatalog> {
+  try {
+    const response = await fetch('/__editor/project-tools');
+    const next = await editorServerJson<ProjectToolCatalog>(response, 'Catalog request failed');
+    publish(next);
+    return next;
+  } catch (error) {
+    const next = {
+      tools: [],
+      contributions: [],
+      loadErrors: [
+        {
+          sourcePath: 'package.json#volter.tools',
+          message: error instanceof Error ? error.message : String(error),
+        },
+      ],
+    };
+    publish(next);
+    return next;
+  }
+}
+
+export async function runProjectTool(
+  name: string,
+  input: unknown,
+  options: { confirm?: boolean } = {},
+): Promise<ProjectToolOutcome> {
+  const response = await fetch('/__editor/project-tools/run', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ name, input, confirm: options.confirm === true }),
+  });
+  // Named BEFORE parsing. A host with no editor server answers this POST with
+  // its page fallback, and `res.json()` on HTML throws `Unexpected token '<'` —
+  // an error that names neither the tool nor the reason, surfacing to the user
+  // as a broken tool rather than a host that never ran one.
+  const outcome = await editorServerJson<ProjectToolOutcome>(
+    response,
+    `Running the project tool ${JSON.stringify(name)} failed`,
+  );
+  if (!outcome || typeof outcome !== 'object' || typeof outcome.ok !== 'boolean') {
+    throw new Error(`Tool request returned an invalid response (${response.status}).`);
+  }
+  return outcome;
+}
+
+/** Editor-init lifecycle for the Node-side registered tool catalog. */
+export function startProjectToolCatalog(): () => void {
+  void refreshProjectTools();
+  const stopProjectWatch = onProjectChange(() => void refreshProjectTools());
+  const stopFileWatch = connectToolFileEvents(() => void refreshProjectTools());
+  return () => {
+    stopProjectWatch();
+    stopFileWatch();
+  };
+}
+
+export function __resetProjectToolsForTest(): void {
+  catalog = EMPTY_CATALOG;
+  version = 0;
+  listeners.clear();
+}

package/src/kit/projection-types.ts

@@ -0,0 +1,44 @@
+/**
+ * The PROJECTION family's surface-neutral shapes (ARCHITECTURE-CORE §The editor
+ * protocol).
+ *
+ * A projection answers "what nodes are in this world, what are their stable
+ * ids, and how do they nest" over the RUNTIME objects a mounted world is made
+ * of — the live `Object3D`/`Container`/DOM element, never an AST node. A walk
+ * always answers: an empty projection over a mounted world is a defect, never a
+ * fact.
+ *
+ * Only the shapes live here. The projectors themselves are per surface
+ * (`./three.ts`, `./pixi.ts`, `./dom.ts`), because what an
+ * object IS, how identity is minted and what an editor-owned object looks like
+ * are all surface facts.
+ */
+
+/**
+ * One projected authoring node.
+ *
+ * `parentId` is the nearest ADMITTED ancestor — not the runtime parent — so a
+ * projection that folds a library's internals into their owner reports the
+ * owner. `null` means this node is a root of the projection.
+ */
+export interface ProjectedNode<TObject> {
+  readonly object: TObject;
+  readonly id: string;
+  readonly parentId: string | null;
+  readonly childIds: string[];
+}
+
+/**
+ * One walk's product: every node by id, the roots in walk order, and whatever
+ * the surface counts about itself.
+ *
+ * `nodes` is keyed by the id the rest of the editor addresses the node by, so
+ * the id the gizmo binds to, the id the hierarchy row shows and the id
+ * `EditorShellStore.objectMap` indexes can never disagree — they are all this
+ * one map.
+ */
+export interface Projection<TObject, TStats> {
+  readonly nodes: Map<string, ProjectedNode<TObject>>;
+  readonly rootIds: string[];
+  readonly stats: TStats;
+}