@volter/editor-core 0.5.57

package/src/project-module-split.ts

@@ -0,0 +1,266 @@
+/**
+ * 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/editor-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://vgai.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 `vgai-mount` epoch.
+  if (STORY_MODULE_PATTERN.test(path)) 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 `vgai status` 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/project-provenance.ts

@@ -0,0 +1,115 @@
+const PROVENANCE_PATH = '.vgai/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/vgai-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/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 './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/project-session-reset.ts

@@ -0,0 +1,67 @@
+import { resetAvailableWorkspaceDocuments } from './workspace-available-documents';
+/**
+ * What must NOT survive a project switch.
+ *
+ * Switching projects without a page reload is a real path — the project
+ * screen's own open sites call `setActiveProject`, and `AppRoot` remounts the
+ * editor layout under a fresh provider. React state goes with that remount;
+ * MODULE-LEVEL state does not. Every singleton below was written against "one
+ * project per page load", and each one carries the previous project's answers
+ * into the next: a running play session (RAF loop, WebGL context, Rapier
+ * world), a live ingest session nothing unmounted, an authoring override
+ * pointing at a game that is gone, System adapters still answering the gizmo
+ * and the CLI wire, and two measurement ledgers whose keys (document ids,
+ * surface ids) repeat across projects.
+ *
+ * ONE subscriber, listed in one place, because that is the only way this stays
+ * honest: a singleton with a session lifetime that is not named here is a
+ * singleton nobody will remember to reset. Add new ones HERE.
+ *
+ * WHICH SWITCHES ACTUALLY LAND HERE, measured rather than assumed: the
+ * browser/FSA project paths (`rootPath: 'browser' | 'fsa'`) never touch the
+ * editor server, so nothing reloads and this is the ONLY teardown they get.
+ * A local, server-backed open additionally POSTs `/__editor/open-project`,
+ * whose broadcast makes `command-listener.ts` reload the page — so there this
+ * runs during the window before that reload lands, not instead of it. A page
+ * reload reclaims everything by definition; the window before it does not, and
+ * it is long enough to hold a live WebGL context and RAF loop across a network
+ * round trip.
+ */
+
+import { clearSelectedAsset } from './asset-selection';
+import { setActiveAuthoring } from './authoring/active-adapter';
+import { resetActiveSystemsForNewProject } from './authoring/active-systems';
+import { resetSessionVitalsForNewProject } from './coverage/session-vitals';
+import { stopAllLiveSessions } from './live-session-registry';
+import { onProjectSessionEnd } from './project-manager';
+import { resetViewportActivationTimingsForNewProject } from './viewport-activation-timings';
+import { closeAllWorkspaceDocuments } from './workspace-document-registry';
+
+/**
+ * Register the project-session resets. Called once at editor init
+ * (`EditorContext.tsx`), the same lifecycle shape `startProjectAdapterLoad`
+ * uses; returns its own teardown.
+ */
+export function startProjectSessionReset(): () => void {
+  return onProjectSessionEnd(() => {
+    // TEARDOWN FIRST, and in the order a normal stop would run it: these two
+    // own mounted games (loop, renderer, realm, adapters, subscriptions) and
+    // each is idempotent + a no-op when nothing is running. Dropping a
+    // reference to either would leak the whole session, not just the handle.
+    stopAllLiveSessions();
+    // Both teardowns above clear the override themselves WHEN they had one;
+    // this covers the surfaces that install an override without owning a
+    // session (an open design/boundary adapter), which nothing else ends.
+    setActiveAuthoring(null);
+    resetActiveSystemsForNewProject();
+    resetSessionVitalsForNewProject();
+    resetViewportActivationTimingsForNewProject();
+    // The center's open documents and the Content selection are module
+    // state too: a project SWITCH is not a reload, so the previous project's
+    // model stayed open in the next project's center, and its restore saw
+    // "something is open" and never opened the new project's own default.
+    closeAllWorkspaceDocuments();
+    resetAvailableWorkspaceDocuments();
+    clearSelectedAsset();
+  });
+}

package/src/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 './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/project-tool-discovery.ts

@@ -0,0 +1,66 @@
+/**
+ * Project-tool discovery LIFECYCLE (W0 — "project tool discovery must move
+ * out of `BottomPanel` and into project/editor initialization").
+ *
+ * Until W0, `BottomPanel.tsx` anchored discovery in its own mount effects:
+ * the dock was both the DISCOVERER and one consumer of project tools, so
+ * inspector-placement tools only loaded because the bottom dock happened to
+ * be mounted. This module owns that lifecycle instead; the editor shell
+ * starts it once at editor initialization (`EditorContext.tsx`'s
+ * `EditorProvider`), and the placement hosts (center tool documents,
+ * workspace-utility registrations — `components/tool-documents.tsx`,
+ * tool-loader.ts's `getGlobalTools`/`subscribeGlobalTools`) are plain
+ * consumers of the already-discovered store — proven by
+ * `test/project-tool-discovery.test.ts`, which runs discovery with no
+ * component module imported at all.
+ *
+ * The pass itself still has editor-init ownership (`refreshProjectTools`,
+ * tool-loader.ts), but its generic startup inventory waits until the opening
+ * viewport has painted: discover after first presentation, re-discover when
+ * the open project changes, and
+ * re-discover on server-watched editor-lane add/unlink events (W6a).
+ * Edit-HMR stays where it was — tool-loader's own module-level
+ * `vgai:script-update` listener.
+ */
+
+import { connectToolFileEvents } from './asset-events';
+import { onProjectChange } from './project-manager';
+import { refreshProjectToolContributions } from './tool-loader';
+import { waitForFirstViewportFrame } from './viewport-activation-timings';
+
+async function refreshAfterOpeningViewport(): Promise<void> {
+  // Contribution modules are executable UI, not an index. A plain startup
+  // used to import every unopened tool here, putting the template's full Data
+  // Tables/react-data-grid graph into the same Vite queue as the Scene. Saved
+  // tool documents still take workspace-state-persistence's explicit awaited
+  // refresh path; this generic inventory can land after the authored frame.
+  // Non-navigation DOMs (unit hosts and embedded documents) have no opening
+  // page critical path to protect. In a real editor page the Navigation entry
+  // is always present, including reloads and history restoration.
+  const hasOpeningNavigation =
+    typeof performance !== 'undefined' && performance.getEntriesByType('navigation').length > 0;
+  if (hasOpeningNavigation) {
+    await Promise.race([
+      waitForFirstViewportFrame(),
+      new Promise<void>((resolve) => setTimeout(resolve, 5_000)),
+    ]);
+  }
+  await refreshProjectToolContributions();
+}
+
+/**
+ * Start the project-tool discovery lifecycle: one presentation-deferred
+ * inventory pass, plus immediate re-discovery on project change and on
+ * tool-file add/unlink events.
+ * Returns a stop function that disconnects both subscriptions (the pass in
+ * flight is left to finish — `refreshProjectTools` never throws).
+ */
+export function startProjectToolContributionDiscovery(): () => void {
+  void refreshAfterOpeningViewport();
+  const stopProjectWatch = onProjectChange(() => void refreshProjectToolContributions());
+  const stopToolFileWatch = connectToolFileEvents(() => void refreshProjectToolContributions());
+  return () => {
+    stopProjectWatch();
+    stopToolFileWatch();
+  };
+}