@volter/sdk 0.0.0-stage → 0.5.203

package/src/kit/project-asset-refresh.ts

@@ -0,0 +1,23 @@
+/** Project asset BYTES changed on disk. A lane whose loaders cache parsed assets
+ * across mounts listens here, invalidates those paths, then reloads — so
+ * replacing a GLB updates every placement without editing source.
+ */
+const ASSET_RELOAD_EVENT = 'editor:asset-loaders-changed';
+
+export function announceAssetReload(paths: readonly string[]): void {
+  if (
+    typeof window === 'undefined' ||
+    !paths.some((path) => /\.(glb|gltf|png|jpe?g|webp|avif)$/i.test(path))
+  )
+    return;
+  window.dispatchEvent(new CustomEvent(ASSET_RELOAD_EVENT, { detail: { paths } }));
+}
+
+export function onAssetReload(listener: (paths: readonly string[]) => void): () => void {
+  if (typeof window === 'undefined') return () => {};
+  const handler = (event: Event): void => {
+    listener((event as CustomEvent<{ paths: readonly string[] }>).detail?.paths ?? []);
+  };
+  window.addEventListener(ASSET_RELOAD_EVENT, handler);
+  return () => window.removeEventListener(ASSET_RELOAD_EVENT, handler);
+}

package/src/kit/project-asset-roots.ts

@@ -0,0 +1,68 @@
+/**
+ * The asset ROOTS Content lists, and the one place a row's root plus its
+ * root-relative path becomes a project path or a URL.
+ *
+ * `public/` is the shipped game's assets; `references/` is reference material
+ * that lives in the project and is deliberately NOT shipped (see
+ * `@volter/sdk/project/output-roots` for the writer's half of the same rule). Both are
+ * ordinary directories of ordinary files — there is no reference database, no
+ * import step, and no copy into `public/` to make something appear.
+ *
+ * Why a reference is addressed through `/project-game-static/`: that middleware
+ * (`vite-plugin-project-game-static.ts`) already serves the CURRENTLY OPEN
+ * project's own folder verbatim, which is exactly what a reference needs and
+ * exactly what `public/`'s root-relative URLs are not — a public asset's URL is
+ * `/<publicRelativePath>` because a shipped game addresses it that way, and
+ * giving references the same spelling would collide with the game's own paths.
+ * Nothing new is served; a reference simply uses the project-file route that
+ * already exists.
+ *
+ * `projectPathForAssetUrl` is the inverse: a bytes reader takes the URL a
+ * document or a tile already holds and asks THIS module which project file it
+ * names.
+ */
+
+export const REFERENCE_ROOT = 'references';
+
+/** A listable asset root. `public` is the default and the shipped one. */
+export type AssetRootId = 'public' | typeof REFERENCE_ROOT;
+
+export const ASSET_ROOTS: readonly AssetRootId[] = ['public', REFERENCE_ROOT];
+
+/** The URL prefix a reference is served under on the local editor server. */
+export const REFERENCE_URL_PREFIX = `/project-game-static/${REFERENCE_ROOT}/`;
+
+/** Project-root-relative path for a root + root-relative path. */
+export function projectAssetPath(root: AssetRootId, rootRelativePath: string): string {
+  return `${root}/${rootRelativePath}`;
+}
+
+/**
+ * The URL editor chrome, asset documents and the Inspector address this asset
+ * by. Public keeps its exact existing spelling (`/textures/crate.png`).
+ */
+export function assetRootServingUrl(root: AssetRootId, rootRelativePath: string): string {
+  return root === REFERENCE_ROOT
+    ? `${REFERENCE_URL_PREFIX}${rootRelativePath}`
+    : `/${rootRelativePath}`;
+}
+
+/** Is this URL/document path a reference rather than a public asset? */
+export function isReferenceAssetUrl(url: string): boolean {
+  return url.startsWith(REFERENCE_URL_PREFIX);
+}
+
+/**
+ * Which project file a serving URL names — the inverse of
+ * {@link assetRootServingUrl}, and the one mapping every bytes reader uses.
+ * A plain `/x.png` is a public asset, so it answers `public/x.png`, which is
+ * the rule those readers used to hardcode.
+ */
+export function projectPathForAssetUrl(url: string): string {
+  const servingUrl = url.startsWith('/') ? url : `/${url}`;
+  if (isReferenceAssetUrl(servingUrl)) {
+    return projectAssetPath(REFERENCE_ROOT, servingUrl.slice(REFERENCE_URL_PREFIX.length));
+  }
+  const withoutSlash = url.startsWith('/') ? url.slice(1) : url;
+  return withoutSlash.startsWith('public/') ? withoutSlash : `public/${withoutSlash}`;
+}

package/src/kit/project-local-state.ts

@@ -0,0 +1,151 @@
+/**
+ * THE PROJECT-LOCAL SETTINGS LAYER — one in-memory document mirroring
+ * `.volter/editor-state.json`, the git-ignored file the scaffold already
+ * reserves for "editor autosaved UI state" (ARCHITECTURE-CORE §Editor chrome,
+ * "Settings have four layers with named homes").
+ *
+ * Every piece of per-user, per-checkout state — the workspace layouts, the
+ * active workspace, the open documents, the view state the shell store
+ * autosaves — is a SECTION of this one document, loaded ONCE when a project
+ * becomes active and written back debounced through `saveEditorState`, the
+ * editor server's own route. One document, one writer, so two sections can
+ * never clobber each other through the whole-file route.
+ *
+ * Keyed by the folder itself: a rename, another browser or another checkout
+ * of the same folder finds the same file. Browser storage keyed by an
+ * absolute path was the previous home, and it lost a layout to exactly those
+ * three moves (measured 2026-09-04).
+ *
+ * UNDER THE CODE-OSS FRAME THE DOCUMENT IS ONE KEY OF THE WORKBENCH'S WORKSPACE
+ * STORAGE (`kit/workspace-storage`): the frame hands that scope over at mount,
+ * and the web workbench keeps it in the same folder
+ * (`.volter/workbench-storage.json`), beside the workbench's own layout. A host
+ * without the frame keeps the file above.
+ */
+
+import { activeProjectKey, getCurrentProject, onProjectChange } from '@volter/sdk/kit/active-project';
+import { loadEditorState, saveEditorState } from '@volter/sdk/kit/editor-api';
+import { onWorkspaceStorageProvider, workspaceStorageProvider } from '@volter/sdk/kit/workspace-storage';
+import { preloadSettings } from '@volter/sdk/kit/settings-store';
+
+type Sections = Record<string, unknown>;
+
+const WRITE_DEBOUNCE_MS = 400;
+
+/** The workspace storage key the whole document lives under when the frame provides the scope. */
+const STORAGE_KEY = 'volter.projectLocalState';
+
+let loadedFor: string | null = null;
+let loading: Promise<void> | null = null;
+let doc: Sections = {};
+let dirty = false;
+let timer: ReturnType<typeof setTimeout> | null = null;
+
+function projectKey(): string {
+  return activeProjectKey();
+}
+
+/**
+ * Load the active project's local document, once per project. Idempotent and
+ * memoized: the second caller for the same project joins the first load, and
+ * a different project starts over. Callers that read synchronously through
+ * {@link projectLocalSection} await this first.
+ */
+export function preloadProjectLocalState(): Promise<void> {
+  const key = projectKey();
+  if (loadedFor === key) return Promise.resolve();
+  // A load in flight for ANOTHER project (the boot's unscoped one, or a
+  // project switched away from mid-load) settles for that project; this
+  // caller's project loads after it, never joins it.
+  if (loading) return loading.then(() => preloadProjectLocalState());
+  const storage = workspaceStorageProvider();
+  const load = storage ? Promise.resolve(parseStored(storage.get(STORAGE_KEY))) : loadEditorState();
+  loading = Promise.all([load, preloadSettings()])
+    .then(([state]) => {
+      doc = state && typeof state === 'object' ? { ...state } : {};
+      loadedFor = key;
+    })
+    .catch(() => {
+      doc = {};
+      loadedFor = key;
+    })
+    .finally(() => {
+      loading = null;
+    });
+  return loading;
+}
+
+/** True once the active project's document has loaded. */
+export function projectLocalStateReady(): boolean {
+  return loadedFor === projectKey();
+}
+
+/** One section of the loaded document, or `undefined` before load or when
+ *  the project has never written it. Synchronous by design: the boot awaits
+ *  {@link preloadProjectLocalState} before anything reads. */
+export function projectLocalSection<T>(name: string): T | undefined {
+  if (!projectLocalStateReady()) return undefined;
+  return doc[name] as T | undefined;
+}
+
+function flush(leaving = false): void {
+  if (timer !== null) {
+    clearTimeout(timer);
+    timer = null;
+  }
+  if (!dirty) return;
+  dirty = false;
+  const storage = workspaceStorageProvider();
+  if (storage) storage.store(STORAGE_KEY, JSON.stringify(doc));
+  else void saveEditorState(doc, { leaving });
+}
+
+function parseStored(raw: string | undefined): Sections {
+  if (!raw) return {};
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? (parsed as Sections) : {};
+  } catch {
+    return {};
+  }
+}
+
+/** Replace one section and schedule the write. A write before the load has
+ *  settled is applied on top of what loads, so a fast first edit is kept. */
+export function writeProjectLocalSection(name: string, value: unknown): void {
+  const apply = () => {
+    doc = { ...doc, [name]: value };
+    dirty = true;
+    if (timer !== null) clearTimeout(timer);
+    timer = setTimeout(flush, WRITE_DEBOUNCE_MS);
+  };
+  if (projectLocalStateReady()) apply();
+  else void preloadProjectLocalState().then(apply);
+}
+
+/** Write what is pending NOW — the page is leaving. */
+export function flushProjectLocalState(): void {
+  flush(true);
+}
+
+// The layer loads the moment a project becomes active, so the dock that
+// mounts next reads its layout from the folder, not defaults. This module is
+// imported by the shell's boot (`EditorContext`), which is what makes the
+// subscription exist before the first project activates; `active-project.ts`
+// imports nothing of it, so a bounded host's closure stays as it was.
+onProjectChange(() => {
+  if (getCurrentProject()) void preloadProjectLocalState();
+});
+
+// The frame's scope arriving (or leaving) changes where the document lives: what was loaded from
+// the other home is read again from this one, so one session never writes two homes.
+onWorkspaceStorageProvider(() => {
+  if (loadedFor === null) return;
+  flush();
+  loadedFor = null;
+  if (getCurrentProject()) void preloadProjectLocalState();
+});
+
+if (typeof window !== 'undefined') {
+  window.addEventListener('pagehide', flushProjectLocalState);
+}

package/src/kit/project-manager.ts

@@ -0,0 +1,243 @@
+/**
+ * Project manager — manages the active game project.
+ *
+ * How the editor learns which project is open depends on the surface, and the
+ * split is the whole point:
+ *
+ *  - LOCAL (server-backed) — it ASKS the server. The editor server holds
+ *    "which project is open" as session state, re-rooted live by
+ *    `POST /__editor/open-project` (the project browser, the editor's `edit <path>` command).
+ *    The URL carries no project identity at all, so a
+ *    refresh or a tab-heal navigation back to the bare origin lands in the
+ *    same project — a VS Code window, not a deep link. A `?project=` on a
+ *    local URL is a loud boot error (`assertNoRemovedBootParams`).
+ *
+ * Sibling deep-link param (the §6 contract):
+ * `?create-from=<templateOrExampleId>` — handled at AppRoot's routing layer,
+ * NOT here. When no explicit project target wins, it opens the
+ * hub's New Project wizard with that template/example preselected and the name
+ * field focused (invalid ids degrade to the default selection plus a
+ * non-blocking notice). An explicit project target always takes precedence.
+ *
+ * Boot precedence (§5/FT-7, unit G5) is decided by `boot-routing.ts`'s pure
+ * `resolveBootTarget` and merely EXECUTED here: explicit target → opted-in
+ * reopen-last → hub. `?hub=1` forces the hub, and a reopen-last project that
+ * fails to open falls back to the hub rather than trapping the user.
+ */
+
+import { assertProjectCompatibility } from '@volter/sdk/session/editor-compatibility';
+import { hasRootOnSurface } from '@volter/project/adapter/manifest-interpreter';
+import { loadGameManifest } from '@volter/project/manifest/load';
+import { type ActiveProject, assignActiveProject, type ProjectConfig } from '@volter/sdk/kit/active-project';
+import {
+  assertNoRemovedBootParams,
+  decideServerProjectBoot,
+  describeServerProjectFailure,
+  hubRequestedFromSearch,
+  resolveBootTarget,
+  ServerProjectDetectionError,
+} from './boot-routing';
+import {
+  getLauncherSettings,
+  listRecentProjects,
+  probeCurrentServerProject,
+  requireEditorCompatibility,
+} from '@volter/sdk/kit/editor-api';
+import { parseHierarchyProjection } from '@volter/sdk/kit/hierarchy-projection';
+
+function describeManifestError(error: unknown): string {
+  const issues =
+    error && typeof error === 'object' && Array.isArray((error as { issues?: unknown }).issues)
+      ? (error as { issues: unknown[] }).issues
+      : null;
+  if (!issues) return error instanceof Error ? error.message : String(error);
+
+  return issues
+    .map((issue) => {
+      if (!issue || typeof issue !== 'object') return String(issue);
+      const candidate = issue as { path?: unknown; message?: unknown };
+      const path = Array.isArray(candidate.path)
+        ? candidate.path.map(String).join('.') || '(root)'
+        : '(root)';
+      const message =
+        typeof candidate.message === 'string' ? candidate.message : 'Invalid manifest value';
+      return `${path}: ${message}`;
+    })
+    .join('\n');
+}
+
+/** Open a project by its root path. Fetches the sole v2 project manifest. */
+export async function openProject(rootPath: string): Promise<ActiveProject> {
+  const compatibility = await requireEditorCompatibility();
+  const res = await fetch('/volter.project.json');
+  if (!res.ok) {
+    throw new Error(
+      `Could not open project at ${rootPath}.\n` +
+        `Failed to load volter.project.json: ${res.status} ${res.statusText}`,
+    );
+  }
+  let rawManifest: unknown;
+  try {
+    rawManifest = await res.json();
+  } catch (error) {
+    throw new Error(
+      `Could not open project at ${rootPath}.\n` +
+        `volter.project.json is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+  assertProjectCompatibility(
+    rawManifest && typeof rawManifest === 'object'
+      ? (rawManifest as {
+          manifestVersion?: unknown;
+          engine?: { version?: unknown };
+          roots?: unknown;
+        })
+      : {},
+    compatibility,
+  );
+  let manifest: ReturnType<typeof loadGameManifest>;
+  try {
+    manifest = loadGameManifest(rawManifest, { configurationKinds: 'defer' });
+  } catch (error) {
+    throw new Error(
+      `Could not open project at ${rootPath}.\n` +
+        `volter.project.json does not match the current project format:\n${describeManifestError(error)}`,
+    );
+  }
+  const config: ProjectConfig = {
+    manifestVersion: manifest.manifestVersion,
+    name: manifest.name,
+    version: manifest.version,
+    engine: manifest.engine,
+    appId: manifest.appId,
+    resolution: manifest.resolution,
+    authoring: manifest.authoring
+      ? { hierarchy: parseHierarchyProjection(manifest.authoring.hierarchy) }
+      : undefined,
+    hasThreeRoot: hasRootOnSurface(manifest, 'three'),
+    rootCount: manifest.roots.length,
+    configurations: manifest.configurations,
+  };
+  return assignActiveProject({ rootPath, config });
+}
+
+/** How many times boot may re-ask a server that failed to answer at all, and
+ *  how long it waits between tries. Both small: `detectProject` runs inside
+ *  AppRoot's detection timeout, and a failing fetch fails fast. */
+export const SERVER_PROJECT_PROBE_ATTEMPTS = 3;
+export const SERVER_PROJECT_PROBE_RETRY_MS = 300;
+
+/**
+ * Detect and open whatever project the server currently has active.
+ * Used in production where __VOLTER_PROJECT_PATH__ isn't available at build time.
+ *
+ * Returns null ONLY when the server said it has no project open — that is the
+ * one answer the launcher is a truthful response to. A server that is serving
+ * a project it cannot describe, or that could not be asked at all, THROWS
+ * (after bounded retries for the transient shape), because rendering the
+ * launcher there tells the user their project does not exist when it does.
+ * The ladder itself is `boot-routing.ts`'s `decideServerProjectBoot`.
+ */
+export async function detectServerProject(): Promise<ActiveProject | null> {
+  const compatibility = await requireEditorCompatibility();
+  for (let attempt = 1; ; attempt++) {
+    const probe = await probeCurrentServerProject();
+    const action = decideServerProjectBoot({
+      status: probe.status,
+      attempt,
+      maxAttempts: SERVER_PROJECT_PROBE_ATTEMPTS,
+    });
+    if (action === 'continue-ladder') return null;
+    if (action === 'open' && probe.status === 'project') {
+      const info = probe.project;
+      assertProjectCompatibility(info.config, compatibility);
+      return assignActiveProject({ rootPath: info.path, config: info.config as ProjectConfig });
+    }
+    if (action === 'retry') {
+      await new Promise((resolve) => setTimeout(resolve, SERVER_PROJECT_PROBE_RETRY_MS));
+      continue;
+    }
+    // 'fail' is only reachable from the two failure shapes, and the surface
+    // that renders this must name the served path and the server's own error
+    // separately — a launcher with a banner is what this fix exists to stop.
+    throw new ServerProjectDetectionError(
+      describeServerProjectFailure(
+        probe.status === 'unreadable'
+          ? { status: 'unreadable', path: probe.path, error: probe.error }
+          : {
+              status: 'unknown',
+              error: probe.status === 'unknown' ? probe.error : 'no answer from the server',
+            },
+      ),
+    );
+  }
+}
+
+/**
+ * Detect which project is open, by ASKING the session. Returns the project if
+ * found, null if the project screen should be shown.
+ */
+export async function detectProject(): Promise<ActiveProject | null> {
+  // One gate before anything is resolved: a removed boot
+  // param errors loudly naming its replacement rather than falling through
+  // (boot-routing.ts) — including `?project=` itself: project identity is
+  // session-held.
+  assertNoRemovedBootParams(window.location.search);
+
+  // 1. ASK THE SESSION. This is the one explicit target —
+  //    the editor's `edit <path>` command, `VOLTER_PROJECT`, and the project browser all reach
+  //    the client the same way, because they all move the SERVER's project
+  //    and the client reads it from there. There is no URL param and no
+  //    boot-time Vite define snapshot in this path: the define is a
+  //    build-time value, and `POST /__editor/open-project` moves the session
+  //    live, so a snapshot could disagree with the server that serves the
+  //    files.
+  const serverProject = await detectServerProject();
+  if (serverProject) return serverProject;
+
+  // 2. Reopen-last (G5). Only reached when the server said it has no project
+  //    open: a live session project outranks the preference.
+  return reopenLastProjectIfEnabled();
+}
+
+/**
+ * The opted-in "Reopen last project on launch" rung of the §5 ladder.
+ *
+ * Returns the reopened project, or null to fall through to the hub — which is
+ * also what a FAILED reopen returns. That fallback is deliberate and is half
+ * the reason the escape hatch exists: a project that was deleted, moved, or
+ * broken since it was last opened must not be able to wedge the launcher in a
+ * boot loop the user cannot click their way out of. Unreal behaves the same
+ * way. The failure is reported to the console rather than thrown, because a
+ * thrown error here would render the startup-failure screen instead of the hub
+ * and hide the recents list the user needs in order to pick something else.
+ */
+async function reopenLastProjectIfEnabled(): Promise<ActiveProject | null> {
+  const [settings, recents] = await Promise.all([getLauncherSettings(), listRecentProjects()]);
+  const target = resolveBootTarget({
+    explicitTarget: null,
+    hubRequested: hubRequestedFromSearch(window.location.search),
+    reopenLastEnabled: settings.reopenLastProject,
+    recents,
+  });
+  if (target.kind !== 'reopen-last') return null;
+  try {
+    return await openProject(target.path);
+  } catch (err) {
+    // biome-ignore lint/suspicious/noConsole: a failed auto-reopen must be visible; the editor console isn't mounted yet at boot.
+    console.warn(
+      `[volter] "Reopen last project on launch" could not open ${target.path}; showing the project browser instead.`,
+      err,
+    );
+    return null;
+  }
+}
+
+export {
+  type ActiveProject,
+  getCurrentProject,
+  onProjectChange,
+  onProjectSessionEnd,
+  type ProjectConfig,
+  setActiveProject,
+} from '@volter/sdk/kit/active-project';

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

@@ -0,0 +1,201 @@
+/**
+ * "This project module was saved" — the ONE subscription for editor surfaces
+ * that hold a live, re-executable copy of a project source module.
+ *
+ * WHICH SIGNAL, AND WHY IT IS THE HMR CHANNEL AND NOT SSE
+ * -------------------------------------------------------
+ * The editor has two file-change channels and they answer different
+ * questions. `asset-events.ts` (SSE) reports FILE-SET changes — a tool or
+ * story file appeared/vanished, a `public/` asset changed — and it carries no
+ * event for "an arbitrary `src/**` module's bytes changed". Vite's HMR
+ * channel does, and it carries something the SSE channel cannot: the dev
+ * server has already stamped the changed file HMR-invalid across the
+ * project's own subgraph before it sends (`server/project-script-hmr.ts`'s
+ * `stampHmrInvalidation`, bounded at editor chrome). That stamp is what makes
+ * a cache-busted re-import re-evaluate the module's DEPENDENCIES too; without
+ * it a fresh leaf url re-runs against the browser's cached copies of
+ * everything it imports, which is the exact stale-restart defect that module's
+ * header documents. So the freshness guarantee is the server's, and this
+ * subscription is how a document learns the stamp has landed.
+ *
+ * THE THREE EVENTS are the complete set the server sends for a project source
+ * file (`handleProjectScriptHotUpdate`); a live module document takes all
+ * three because its subject can be any of those classifications:
+ *   - `volter:restart-required` — a plain `.ts`, or a `.tsx` that is not a Fast
+ *     Refresh boundary. THE COMMON CASE for a model module, whose export is a
+ *     lowercase builder function.
+ *   - `volter:script-update` — the file is in the editor's lane (`editor/contributions/`, `editor/tools/`).
+ *   - `volter:r3f-entry-update` — the file is R3F-dialect.
+ * A `.tsx` that IS a Fast Refresh boundary rides stock Vite HMR instead and
+ * sends none of these, so `vite:afterUpdate` is taken as well: Vite stamped
+ * the graph itself on that path, and the accepted path names the file.
+ *
+ * Nothing here re-imports anything. The subscriber owns what "changed" means
+ * for its own surface.
+ */
+
+/** Project-relative path of the module that changed, e.g. `src/prefabs/probe.ts`. */
+export type ProjectModuleChangeListener = (
+  relativePath: string,
+  affected?: readonly string[],
+  type?: 'create' | 'update' | 'delete',
+) => void;
+
+/**
+ * WHY THE TRANSFORM ERROR IS RECORDED SEPARATELY: a dynamic `import()` of a
+ * module the server could not transform rejects with the browser's own opaque
+ * `TypeError: Failed to fetch dynamically imported module: <url>` — the
+ * ACTUAL reason (`Unexpected ";"`, at line:col, with a source frame) never
+ * reaches the importer. Vite sends it on the HMR channel instead, as
+ * `vite:error`, and `editor-console.ts` already prints it. A document showing
+ * a build failure needs the same text: "failed to fetch" is not a modeling
+ * error message.
+ *
+ * Kept as a LAST-ERROR-PER-FILE map rather than a subscription because the
+ * consumer reads it at the moment its import rejects, which is after the
+ * event: the server sends `vite:error` while answering the very request that
+ * is about to reject.
+ */
+interface ViteErrorPayload {
+  readonly err?: {
+    readonly message?: unknown;
+    readonly id?: unknown;
+    readonly frame?: unknown;
+    readonly loc?: { readonly file?: unknown; readonly line?: unknown; readonly column?: unknown };
+  };
+}
+
+/** Keyed by the normalized absolute file path Vite reports. */
+const busKey = Symbol.for('volter.project-module-changes');
+interface ModuleChangesBus {
+  readonly listeners: Set<ProjectModuleChangeListener>;
+  readonly errors: Map<string, string>;
+  transformErrorsWired: boolean;
+  changesWired: boolean;
+}
+const page = globalThis as typeof globalThis & { [busKey]?: ModuleChangesBus };
+const bus = page[busKey] ??= {
+  listeners: new Set(), errors: new Map(), transformErrorsWired: false, changesWired: false,
+};
+const lastTransformError = bus.errors;
+
+/** Vite's HMR context when a dev server serves this module, typed here so the SDK carries no
+ *  bundler types. */
+const viteHot = (
+  import.meta as ImportMeta & {
+    hot?: {
+      on(event: string, listener: (payload: never) => void): void;
+      off(event: string, listener: (payload: never) => void): void;
+    };
+  }
+).hot;
+
+function wireTransformErrors(): void {
+  if (bus.transformErrorsWired) return;
+  const hot = viteHot;
+  if (!hot) return;
+  bus.transformErrorsWired = true;
+  hot.on('vite:error', (payload: ViteErrorPayload) => {
+    const err = payload?.err;
+    if (!err || typeof err.message !== 'string') return;
+    const file =
+      typeof err.loc?.file === 'string' ? err.loc.file : typeof err.id === 'string' ? err.id : null;
+    if (file === null) return;
+    const frame = typeof err.frame === 'string' && err.frame !== '' ? `\n${err.frame}` : '';
+    // Vite ids carry the transform query; the record is keyed by the file.
+    lastTransformError.set(normalize(file.split('?')[0] ?? file), `${err.message}${frame}`);
+  });
+}
+
+/**
+ * The server's own reason the module at `relativePath` did not transform, if
+ * it reported one — see {@link ViteErrorPayload}. `null` when the failure was
+ * something else (a throwing top level, a missing dependency at runtime),
+ * which is the caller's cue to report what its own `import()` said.
+ */
+export function projectModuleTransformError(relativePath: string): string | null {
+  for (const [file, message] of lastTransformError) {
+    if (projectModuleChangeMatches(file, relativePath)) return message;
+  }
+  return null;
+}
+
+/** Drop the recorded transform error for a module that has now built. */
+export function clearProjectModuleTransformError(relativePath: string): void {
+  for (const file of [...lastTransformError.keys()]) {
+    if (projectModuleChangeMatches(file, relativePath)) lastTransformError.delete(file);
+  }
+}
+
+/** Server-sent event payloads all carry `{ file }` as an ABSOLUTE path. */
+interface HotFilePayload {
+  readonly file?: unknown;
+  readonly affected?: unknown;
+  readonly type?: unknown;
+}
+
+/** Vite's own `vite:afterUpdate` payload, narrowed to what is read here. */
+interface ViteUpdatePayload {
+  readonly updates?: ReadonlyArray<{ readonly acceptedPath?: unknown; readonly path?: unknown }>;
+}
+
+function normalize(path: string): string {
+  return path.replaceAll('\\', '/');
+}
+
+/**
+ * Does `changedPath` (absolute, or already project-relative) name
+ * `relativePath` of the open project? Compared by SUFFIX because the two
+ * halves spell the same file differently: the dev server reports the absolute
+ * path it watched, and a document knows only its project-relative one. The
+ * leading separator makes the suffix a whole path segment, so
+ * `src/prefabs/probe.ts` never matches `.../not-src/prefabs/probe.ts`.
+ */
+export function projectModuleChangeMatches(changedPath: string, relativePath: string): boolean {
+  const changed = normalize(changedPath);
+  const relative = normalize(relativePath).replace(/^\.?\//, '');
+  return changed === relative || changed.endsWith(`/${relative}`);
+}
+
+/**
+ * Call `listener` whenever the dev server reports that a project source module
+ * was saved. A dev-served copy connects Vite to the page-wide bus, so bundled
+ * consumers hear the same channel. Outside a dev client no events arrive.
+ */
+export function subscribeProjectModuleChange(listener: ProjectModuleChangeListener): () => void {
+  bus.listeners.add(listener);
+  wireChanges();
+  return () => { bus.listeners.delete(listener); };
+}
+
+function wireChanges(): void {
+  const hot = viteHot;
+  if (!hot || bus.changesWired) return;
+  bus.changesWired = true;
+  wireTransformErrors();
+  const publish: ProjectModuleChangeListener = (path, affected, type) => {
+    for (const listener of [...bus.listeners]) listener(path, affected, type);
+  };
+  const onFileEvent = (payload: HotFilePayload): void => {
+    if (typeof payload?.file !== 'string') return;
+    const affected = Array.isArray(payload.affected)
+      ? payload.affected.filter((path): path is string => typeof path === 'string').map(normalize)
+      : undefined;
+    const type = payload.type === 'create' || payload.type === 'update' || payload.type === 'delete'
+      ? payload.type : undefined;
+    publish(normalize(payload.file), affected, type);
+  };
+  const onViteUpdate = (payload: ViteUpdatePayload): void => {
+    for (const update of payload?.updates ?? []) {
+      const path = update.acceptedPath ?? update.path;
+      // Vite's urls carry the transform query (`?t=…`); the path half is the file.
+      if (typeof path === 'string') publish(normalize(path.split('?')[0] ?? path));
+    }
+  };
+  hot.on('volter:restart-required', onFileEvent);
+  hot.on('volter:script-update', onFileEvent);
+  hot.on('volter:r3f-entry-update', onFileEvent);
+  hot.on('vite:afterUpdate', onViteUpdate);
+}
+
+wireChanges();