@volter/editor-core 0.5.57

package/vite-plugin-module-doorways.ts

@@ -0,0 +1,336 @@
+/**
+ * The editor's MODULE DOORWAYS: synthetic ES modules that statically re-export
+ * a fixed set of members, so the editor SHELL reaches a package through the
+ * OPENED PROJECT's Vite graph instead of through its own prebuilt bundle.
+ *
+ * One plugin, one declarative table per doorway. Everything below is the same
+ * two-line mechanism — `resolveId` maps `/__vgai-<name>` to a `\0`-prefixed
+ * virtual id, `load` answers with a literal string of `export … from '<bare
+ * specifier>'` lines — and the ONLY thing that ever differed between the five
+ * was the specifier table, so the tables are the module's data and the plugin
+ * machinery is written once.
+ *
+ * ## Why a doorway exists at all
+ *
+ * Under the PACKAGED runtime (`server/packaged.ts` — a `@vgai/editor` npm
+ * package with no monorepo checkout) the editor shell is a prebuilt production
+ * bundle with its own React, three, `@react-three/fiber`, `pixi.js`,
+ * `@pixi/react` and `@storybook/react` inlined, while the opened project's
+ * source is served by a SEPARATE, project-rooted Vite instance that resolves
+ * those same bare specifiers from the PROJECT's `node_modules`. A bare static
+ * `import` in shell code therefore holds a DIFFERENT module instance than the
+ * objects it is pointed at. A doorway is how the shell asks the project's graph
+ * for the same identity the project itself resolved: the synthetic body's
+ * specifiers go through that instance's own transform-time resolver and its own
+ * `optimizeDeps` prebundle cache, exactly the way a project entry module's own
+ * `import … from 'react'` does.
+ *
+ * `dev.ts` has no such split — one Vite
+ * instance, and the repo-root `vite.config.ts`'s `resolve.dedupe` already
+ * collapses `react`/`three`/`pixi.js`/`@pixi/react`/`@react-three/fiber` onto
+ * one instance — so this plugin is registered ONLY on the packaged runtime's
+ * project-rooted instance, plus the root `vitest.config.ts` (two doorways
+ * there, so the branch is exercisable headlessly).
+ *
+ * ## Why the doorways stay SEPARATE modules
+ *
+ * The plugin merges; the MODULES deliberately do not. Each doorway is fetched
+ * only when the lane that needs it actually mounts, so its packages are only
+ * ever demanded of a project that has them:
+ *
+ *  - a DOM/canvas-only project must not resolve `@react-three/fiber` merely to
+ *    mount an ordinary React root (which is why the r3f rows are not on the
+ *    react-world doorway — keeping them there meant a valid 2D project could
+ *    not boot the packaged editor without installing an unrelated renderer
+ *    stack), nor a three-only project `@pixi/react`;
+ *  - an INGEST root's whole premise is a game that brought its OWN stack, so
+ *    the three-ingest doorway does not borrow `/__vgai-r3f-runtime` even though
+ *    that module already publishes `projectThree` and reusing it would be one
+ *    line: a vendored plain-three game has no Fiber installed, and demanding it
+ *    would break the exact case the doorway closes;
+ *  - `@storybook/react` is a devDependency a project may drop, so a project
+ *    with no stories must never pay for it and a project missing it must lose
+ *    only the story lane (with an error naming the missing package, surfaced by
+ *    `src/story-dom-runtime.ts`), never react-world mounting.
+ *
+ * ## The measured defects, per doorway
+ *
+ * These are the failures each row set was bought with. None of them reproduce
+ * from a checkout — every one needs a real packaged build.
+ *
+ * ### `/__vgai-react-world-runtime` (`REACT_WORLD_DOORWAY`)
+ *
+ * Mounting a react world with `createRoot` from the editor's own bundle while
+ * the entry component's hooks ran against the project's `react` produced two
+ * React module instances: `useContext`/`useState` read and wrote different
+ * internal singletons, and `useContext` threw on a `null` dispatcher (confirmed
+ * live; see `server/packaged.ts`'s header, "React-world OID authoring parity",
+ * and `src/react-mount-runtime.ts`'s `resolveReactRootMountRuntime`).
+ *
+ * A real-browser run then caught a SECOND bug the wiring tests could not see:
+ * `flushSync` must come from bare `react-dom`, and this instance's
+ * `optimizeDeps` uses a project-entry-scoped crawl, so an injected bare
+ * specifier the crawl cannot see is served RAW — `react-dom`'s package entry
+ * re-exports its implementation through a `NODE_ENV`-conditional `require(...)`
+ * the raw-serve path cannot see through. Because a doorway is ONE ES module
+ * with several `export … from` statements, that single broken re-export sinks
+ * the whole dynamic import, breaking even Play mode's `ReactRootAdapter.mount()`
+ * which never touches `flushSync`:
+ *
+ *   SyntaxError: The requested module '/node_modules/react-dom/index.js'
+ *     does not provide an export named 'flushSync'
+ *
+ * — gone once bare `react-dom` was in `optimizeDeps.include`, in the same run.
+ * That is what `EDITOR_RUNTIME_MODULE_SPECIFIERS` (below, read by
+ * `server/project-optimize-deps-entries.ts`) exists to keep true.
+ *
+ * WHICH react the graph then points at is not this module's business and has
+ * changed: `packaged.ts` redirects every React specifier in this graph to the
+ * editor SHELL's own built React chunks (`vite-plugin-shared-react.ts`), so the
+ * page has exactly one React the way `dev.ts` always did. The contract is
+ * unchanged and still load-bearing — the mount call and the entry component's
+ * hooks must resolve `react` through the SAME graph, whatever that graph points
+ * at.
+ *
+ * ### `/__vgai-canvas-runtime` (`CANVAS_DOORWAY`)
+ *
+ * `src/authoring/canvas-design-mount.ts` and `src/binding-resolver.ts` are
+ * SHELL modules. A bare `await import('@vgai/game-runtime/canvas-react')` there built the
+ * adapter — and thus called `createRoot` and `extend` — with the SHELL's
+ * copies, then rendered the PROJECT's world component inside it. Measured on a
+ * packaged build against `examples/retro-shooter`:
+ *
+ *   Invalid hook call … more than one copy of React in the same app   (×12)
+ *   TypeError: Cannot read properties of null (reading 'useSyncExternalStore')
+ *   [design-time-layers] world "world" (canvas) failed to mount:
+ *     canvas world "world": no first commit within 10s
+ *
+ * — the canvas world never design-mounted, and the Scene view was a Boundary
+ * node.
+ *
+ * `projectPixi` rides along because mounting is only half of what the editor
+ * does to a canvas world. Everything AFTERWARDS — the authoring adapter that
+ * duplicates a node, the drop that loads a texture, the capture trap an ingest
+ * root installs, the preview that photographs a selection — is SHELL code
+ * holding `pixi.js` VALUES, and those values came from a different module
+ * instance than the objects they point at. Four measured failures:
+ *
+ *  - `object.constructor === Container` is FALSE for every project node, so
+ *    `PixiAuthoringAdapter`'s duplicate gate refuses a plain project Container
+ *    with the sentence it reserves for a game's own subclass;
+ *  - `Assets.load` reads the SHELL's cache, so an image dropped on the world is
+ *    fetched and decoded a second time into a texture the project's own loader
+ *    has never heard of;
+ *  - `installSceneCapture2D` traps the SHELL's `Application.prototype`, which an
+ *    ingested game never calls — MEASURED on a packaged build of the
+ *    `bunnymark` ingest fixture, the mount died with the engine's own words:
+ *    "the game never rendered, or it bundles its own (un-shared) copy of
+ *    pixi.js" (8s of visible time, then the whole root failed by name);
+ *  - a selection preview clones a project subtree through a five-way
+ *    `instanceof` chain of SHELL classes, which every branch misses, and renders
+ *    the result on a SHELL `Application` against the project's GPU textures.
+ *
+ * So, stated once: A CANVAS SURFACE HOLDS ONE PIXI NAMESPACE, and it is the one
+ * the graph its objects came from resolved. The mount site chooses it
+ * (`resolveCanvasPixiForEditor`) and hands it to whatever it constructs;
+ * nothing downstream reaches for a static import. `CanvasHostContext` carries
+ * no renderer namespace (the mount calls `extend(PIXI)` with its OWN `pixi.js`
+ * import, which is the project's once this doorway resolves it), so the MOUNT
+ * needs nothing further.
+ *
+ * ### `/__vgai-three-ingest-runtime` (`THREE_INGEST_DOORWAY`)
+ *
+ * `src/authoring/ingest-root-adapter.ts` is SHELL code, and it installed the
+ * render accessor trap on the `three` it statically imported — while the
+ * ingested game's entry is served as `/@fs/<project>/…` by the project-rooted
+ * Vite and therefore resolves the PROJECT's `three`. The trap sat on a
+ * `WebGLRenderer.prototype` the game never constructs. The engine states the
+ * invariant in `adapter/ingest/scene-capture.ts`'s own header — "every trap
+ * must be installed on the SAME `three` module/addon instance the game uses" —
+ * and says exactly what a violation looks like. MEASURED on a packaged build
+ * (published `@vgai/editor@0.5.20`, real npm install) against a ~30-line
+ * unmodified three.js game declared as a `{ surface: 'three', ingest: {} }`
+ * root:
+ *
+ *   WARNING: Multiple instances of Three.js being imported.
+ *   Scene capture timed out after 15000ms of VISIBLE time (0ms
+ *     browser-suspended …) — the game never rendered, or it bundles its own
+ *     (un-shared) copy of three.
+ *
+ * — three.js's own duplicate-instance guard naming the cause, beside the mount
+ * failing by name 15 seconds later. The ADDONS ride along because they are the
+ * same identity question: `EffectComposer` and `CSS3DRenderer` are FILES inside
+ * the `three` package tree, so an unmodified game's `three/addons/…` import
+ * resolves to the copy beside its own `three`, and trapping the shell's would
+ * miss a composer-driven or CSS3D-driven game for precisely that reason.
+ *
+ * ### `/__vgai-story-runtime` (`STORY_DOORWAY`)
+ *
+ * A CSF module is dynamically imported through the project's Vite graph
+ * (`src/stories/story-discovery.ts`'s `/@fs/` import), so its components' hooks
+ * resolve against the PROJECT's own `react` — while `mountIsolatedStory`
+ * (`StoryPreviewMount.tsx`) rendered them with the editor SPA's statically
+ * bundled `react-dom`, and `compose-project-stories.ts` composed them with the
+ * editor's own bundled `@storybook/react`. Two React module instances: every
+ * story render died on "Invalid hook call" — confirmed live in a package-native
+ * project, where the Stories panel and the `vgai screenshot` story lane were
+ * both dead.
+ *
+ * ### `/__vgai-r3f-runtime` (`R3F_DOORWAY`)
+ *
+ * The three lane's original doorway, and the pattern the canvas and
+ * three-ingest ones were transcribed from: the R3F entry adjudicator, plus
+ * `projectThree` for the same reason `projectPixi` exists on the canvas
+ * doorway.
+ *
+ * ## Why the module BODY is exported (`doorwayModuleSource`)
+ *
+ * A synthesized module hangs off no file the `optimizeDeps` crawl can reach, so
+ * its specifiers were discovered only when a lane first mounted — mid-session —
+ * which re-optimizes and hard-reloads the controlling tab. Measured on a real
+ * canonical-Pixi project with a cold `node_modules/.vite`: the boot pass
+ * prebundled 19 deps; one request for the synthetic modules took it to 21,
+ * adding `three` and `@react-three/fiber` — two optimizer waves, two reloads.
+ * `server/project-optimize-deps-entries.ts` closes that by reading
+ * `EDITOR_RUNTIME_MODULE_SPECIFIERS` out of the SAME strings the browser is
+ * served, which is what stops the prebundle list from drifting from what the
+ * modules actually import.
+ */
+import { STORY_RUNTIME_PATH } from '@volter/editor-sdk/host';
+import type { Plugin } from 'vite';
+
+/** One `from '<specifier>'` line of a doorway's synthetic module body. */
+export interface ModuleDoorwayRow {
+  /** The bare (or aliased) specifier this row re-exports from. */
+  readonly from: string;
+  /**
+   * Named re-exports, verbatim and in order — `'createRoot as createR3FRoot'`
+   * is a single entry, because the rename IS the published name.
+   */
+  readonly names?: readonly string[];
+  /**
+   * Publish the specifier's whole namespace under this binding
+   * (`import * as projectThree from 'three'` + `export { projectThree }`).
+   * Namespace imports lead the module body and their re-export closes it, the
+   * way a hand-written module reads.
+   */
+  readonly namespace?: string;
+}
+
+/** A synthetic module the editor shell imports by URL to reach the project's graph. */
+export interface ModuleDoorway {
+  /** The URL shell code imports (`/__vgai-r3f-runtime`). Part of the public API. */
+  readonly path: string;
+  readonly rows: readonly ModuleDoorwayRow[];
+}
+
+/**
+ * The dynamic-import-facing URL `src/binding-resolver.ts`'s
+ * `resolveReactRootMountRuntime` imports.
+ */
+export const REACT_WORLD_RUNTIME_PATH = '/__vgai-react-world-runtime';
+export const R3F_RUNTIME_PATH = '/__vgai-r3f-runtime';
+export const CANVAS_RUNTIME_PATH = '/__vgai-canvas-runtime';
+export const THREE_INGEST_RUNTIME_PATH = '/__vgai-three-ingest-runtime';
+/** The dynamic-import-facing URL `stories/story-dom-runtime.ts` imports. Its
+ *  one spelling is `@volter/editor-sdk/host`, because a reader reaches a host
+ *  fact through the published door and never through this build tier; this
+ *  plugin still owns WHAT is served at that address, below. */
+export { STORY_RUNTIME_PATH };
+
+export const R3F_DOORWAY: ModuleDoorway = {
+  path: R3F_RUNTIME_PATH,
+  rows: [
+    { from: 'three', namespace: 'projectThree' },
+    { from: 'react', names: ['createElement'] },
+    {
+      from: '@react-three/fiber',
+      names: ['createRoot as createR3FRoot', 'extend as extendThree'],
+    },
+  ],
+};
+
+export const THREE_INGEST_DOORWAY: ModuleDoorway = {
+  path: THREE_INGEST_RUNTIME_PATH,
+  rows: [
+    { from: 'three', namespace: 'projectThree' },
+    {
+      from: 'three/examples/jsm/postprocessing/EffectComposer.js',
+      names: ['EffectComposer'],
+    },
+    {
+      from: 'three/examples/jsm/renderers/CSS3DRenderer.js',
+      names: ['CSS3DRenderer'],
+    },
+  ],
+};
+
+export const STORY_DOORWAY: ModuleDoorway = {
+  path: STORY_RUNTIME_PATH,
+  rows: [
+    { from: '@storybook/react', names: ['composeStories', 'setProjectAnnotations'] },
+    { from: 'react-dom', names: ['flushSync'] },
+    { from: 'react-dom/client', names: ['createRoot'] },
+  ],
+};
+
+/**
+ * Every doorway the PACKAGED runtime serves, in registration order.
+ *
+ * `vitest.config.ts` deliberately registers a SUBSET (react-world + story), and
+ * `dev.ts` registers none — see the header for why a doorway is only ever
+ * served to a lane that asked for it.
+ */
+export const PACKAGED_MODULE_DOORWAYS: readonly ModuleDoorway[] = [
+  R3F_DOORWAY,
+  THREE_INGEST_DOORWAY,
+  STORY_DOORWAY,
+];
+
+/**
+ * The exact module text a doorway is served as — a literal string of STATIC
+ * `import`/`export … from` lines and nothing else, so every specifier goes
+ * through the serving instance's own resolver.
+ */
+export function doorwayModuleSource(doorway: ModuleDoorway): string {
+  const lines: string[] = [];
+  for (const row of doorway.rows) {
+    if (row.namespace) lines.push(`import * as ${row.namespace} from '${row.from}';`);
+  }
+  for (const row of doorway.rows) {
+    if (!row.names || row.names.length === 0) continue;
+    lines.push(`export { ${row.names.join(', ')} } from '${row.from}';`);
+  }
+  for (const row of doorway.rows) {
+    if (row.namespace) lines.push(`export { ${row.namespace} };`);
+  }
+  return lines.join('\n');
+}
+
+/** A doorway's private virtual id — `\0`-prefixed so no other plugin claims it. */
+function virtualIdOf(doorway: ModuleDoorway): string {
+  return `\0vgai${doorway.path.replace(/^\/__vgai/, '')}`;
+}
+
+/**
+ * The ONE plugin serving every doorway handed to it.
+ *
+ * Registered per host with the doorways that host is meant to answer for, which
+ * is the whole conditional cost model: a doorway not in this list is not a
+ * module the graph can reach, so its packages are never demanded.
+ */
+export function moduleDoorwaysPlugin(doorways: readonly ModuleDoorway[]): Plugin {
+  const byPath = new Map(doorways.map((doorway) => [doorway.path, virtualIdOf(doorway)]));
+  const bodies = new Map(
+    doorways.map((doorway) => [virtualIdOf(doorway), doorwayModuleSource(doorway)]),
+  );
+  return {
+    name: 'vgai-module-doorways',
+    resolveId(id) {
+      return byPath.get(id);
+    },
+    load(id) {
+      return bodies.get(id);
+    },
+  };
+}

package/vite-plugin-product-contributions.ts

@@ -0,0 +1,197 @@
+/**
+ * `vgai:contributions/<package>` — a package's DECLARED contributions, read at
+ * build/serve time and served as a module of static `import()`s.
+ *
+ * A PRODUCT is code (ARCHITECTURE-CORE §The target shape, rule 8: "Compositions
+ * are code; the frame's and the loader's manifests are declarations and stay").
+ * `packages/game-editor/src/index.ts` and `packages/model-editor/src/index.ts`
+ * name the packages they mount, in TypeScript, and each name is spelled as an
+ * import of this virtual module:
+ *
+ *   import blender from 'vgai:contributions/@vgai/blender';
+ *
+ * whose body this plugin synthesizes from that package's own
+ * `package.json#vgai.contributions`:
+ *
+ *   export default [
+ *     { entryPath: '@vgai/blender/contributions/blender.command.ts',
+ *       load: () => import('@vgai/blender/contributions/blender.command') },
+ *     …
+ *   ];
+ *
+ * The declaration is the ONE source. Nothing is committed that a script
+ * generates, and a package that grows a contribution grows every product that
+ * names it with no second edit anywhere — which is the defect the generated
+ * table (`builds.generated.ts`, 529 committed lines derived from `builds/*.json`)
+ * existed to remove and then re-introduced from the other side: the table was
+ * committed, so it went stale, and a pre-commit check had to exist to notice.
+ *
+ * WHY A PLUGIN AND NOT `import.meta.glob`. A glob is a path pattern over THIS
+ * package's tree; what a product mounts is another package's own list, and a
+ * package's contributions live behind its export map, not at a path a consumer
+ * may guess. So the plugin reads the manifest the loader already reads
+ * (`server/project-tools.ts`'s `packageContributionModules` reads the same key
+ * for a PROJECT's declared packages) and emits the same `{ entryPath, load }`
+ * shape `tool-loader.ts` consumes. `vite-plugin-module-doorways.ts` is the
+ * precedent for the mechanism: `resolveId` maps a private id, `load` answers
+ * with a literal module body of static statements, and every specifier in it
+ * goes through the serving instance's own resolver.
+ *
+ * THE `entryPath` IS THE PACKAGE SPECIFIER, with its extension, because that is
+ * what the SESSION reports for the same module (`project-tools.ts` records a
+ * package's contribution by the manifest's own `./contributions/x.ts` spelling)
+ * and `tool-loader.ts` dedupes a package the product bundles against one the
+ * open project declares BY THAT STRING. The `load` import drops the extension
+ * for the same reason the old generator did: `@vgai/x/contributions/*` is an
+ * export-map wildcard, and the bundler resolves the extension.
+ *
+ * WHERE THE MANIFEST IS FOUND. From the IMPORTER — the product module doing the
+ * importing — through Node resolution of `<name>/package.json`, so the product
+ * reads the package its own install resolves. `resolveId` is the only hook with
+ * an importer, so it resolves the manifest and remembers it for `load`.
+ */
+
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, isAbsolute, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import type { Plugin } from 'vite';
+
+/** The specifier prefix a product writes. Part of the kit's public surface: a
+ *  product package's source contains this string and nothing else about how a
+ *  contribution is found. */
+export const PRODUCT_CONTRIBUTIONS_PREFIX = 'vgai:contributions/';
+
+/** One contribution a product bundles: the package specifier `tool-loader.ts`
+ *  records as the module's `file`, and the lazy import the bundler follows. */
+export interface BundledContribution {
+  readonly entryPath: string;
+  readonly load: () => Promise<unknown>;
+}
+
+/** The module text served for one package's declared contributions. Exported so
+ *  the closure meter can read the same list this serves without re-deriving the
+ *  rule (`scripts/validate-editor-closure.mjs`). */
+export function productContributionsModuleSource(
+  packageName: string,
+  declared: readonly string[],
+): string {
+  const rows = declared.map((entry) => {
+    const relative = entry.replace(/^\.\//, '');
+    const specifier = `${packageName}/${relative}`;
+    const importable = specifier.replace(/\.(tsx|ts|jsx|js)$/, '');
+    return (
+      `  { entryPath: ${JSON.stringify(specifier)}, ` +
+      `load: () => import(${JSON.stringify(importable)}) },`
+    );
+  });
+  return [
+    `// ${packageName}'s package.json#vgai.contributions, read at build time by`,
+    '// packages/editor/vite-plugin-product-contributions.ts.',
+    'export default [',
+    ...rows,
+    '];',
+    '',
+  ].join('\n');
+}
+
+/** A package's declared contribution modules, or a throw naming the package. */
+export function readDeclaredContributions(manifestPath: string, packageName: string): string[] {
+  let manifest: { vgai?: { contributions?: unknown } };
+  try {
+    manifest = JSON.parse(readFileSync(manifestPath, 'utf8')) as typeof manifest;
+  } catch (error) {
+    throw new Error(
+      `${manifestPath} is not readable (${error instanceof Error ? error.message : String(error)}), ` +
+        `so ${packageName}'s contributions cannot be composed into this product.`,
+    );
+  }
+  const declared = manifest.vgai?.contributions;
+  if (declared === undefined)
+    throw new Error(
+      `${packageName} declares no package.json#vgai.contributions, so there is nothing for a ` +
+        'product to mount from it. A package that contributes declares its modules there; a ' +
+        'package that only exports code is imported by name instead.',
+    );
+  if (!Array.isArray(declared) || declared.some((entry) => typeof entry !== 'string'))
+    throw new Error(
+      `${packageName}'s package.json#vgai.contributions must be an array of ./-relative modules.`,
+    );
+  return declared as string[];
+}
+
+/**
+ * Resolve `<name>/package.json` from the importing module's own directory.
+ *
+ * `createRequire` walks `node_modules` upward exactly as the runtime does, so a
+ * product resolves the package version its own install carries — and in this
+ * workspace that is the checkout's symlink, which is the same file the estate
+ * scan reads.
+ */
+function locateManifest(packageName: string, importer: string | undefined): string {
+  const from = importer && isAbsolute(importer) ? importer : join(process.cwd(), 'index.js');
+  const require = createRequire(pathToFileURL(from));
+  try {
+    return require.resolve(`${packageName}/package.json`);
+  } catch {
+    // An export map without a `./package.json` entry: fall back to the package
+    // directory Node resolves for the bare name's own files.
+    const resolvedFrom = createRequire(pathToFileURL(from));
+    const found = resolvedFrom.resolve(packageName);
+    let dir = dirname(found);
+    for (;;) {
+      const candidate = join(dir, 'package.json');
+      try {
+        if (JSON.parse(readFileSync(candidate, 'utf8')).name === packageName) return candidate;
+      } catch {
+        /* keep walking */
+      }
+      const parent = dirname(dir);
+      if (parent === dir)
+        throw new Error(
+          `${packageName} is not installed where ${from} can resolve it, so this product cannot ` +
+            'mount its contributions. Declare it as a dependency of the product package.',
+        );
+      dir = parent;
+    }
+  }
+}
+
+/**
+ * The ONE plugin serving every `vgai:contributions/<package>` a product names.
+ *
+ * Registered on the repo-root `vite.config.ts` — which is both the product
+ * BUILD's config and the dev session's `configFile`
+ * (`packages/editor/server/dev.ts`), so one registration answers both hosts.
+ * The PACKAGED host's project-rooted instance never sees a product module (the
+ * product is a built chunk there), so it registers nothing.
+ */
+export function productContributionsPlugin(): Plugin {
+  const manifests = new Map<string, string>();
+  return {
+    name: 'vgai-product-contributions',
+    resolveId(id, importer) {
+      if (!id.startsWith(PRODUCT_CONTRIBUTIONS_PREFIX)) return null;
+      const packageName = id.slice(PRODUCT_CONTRIBUTIONS_PREFIX.length);
+      if (packageName === '')
+        throw new Error(
+          `"${id}" names no package — the form is \`${PRODUCT_CONTRIBUTIONS_PREFIX}<package>\`.`,
+        );
+      const virtual = `\0${id}`;
+      manifests.set(virtual, locateManifest(packageName, importer));
+      return virtual;
+    },
+    load(id) {
+      const manifestPath = manifests.get(id);
+      if (manifestPath === undefined) return null;
+      const packageName = id.slice(`\0${PRODUCT_CONTRIBUTIONS_PREFIX}`.length);
+      // Watched, so a package that grows a contribution refreshes the product
+      // in a live session instead of waiting for a restart.
+      this.addWatchFile(manifestPath);
+      return productContributionsModuleSource(
+        packageName,
+        readDeclaredContributions(manifestPath, packageName),
+      );
+    },
+  };
+}

package/vite-plugin-project-game-static.ts

@@ -0,0 +1,125 @@
+/**
+ * vite-plugin-project-game-static — D-X2 (slice S1): the external-folder
+ * sibling of `vite-plugin-game-static.ts`. Serves the CURRENTLY OPEN
+ * project's own folder VERBATIM (no vite transform) at
+ * `/project-game-static/<path>` -> `<projectRoot>/<path>`, so a game's own
+ * data files reach it untransformed — an AssetPack `.json` spritesheet stays
+ * raw JSON instead of becoming an ESM module, the same R-X1 rationale
+ * `vite-plugin-game-static.ts`'s header records for the vendored route, just
+ * rooted at an arbitrary user folder.
+ *
+ * `getProjectRoot` is a THUNK, not a captured string: `open-project` can
+ * switch the current project live (`server/dev.ts`'s `onProjectOpened`
+ * callback), and this route must follow the CURRENT project root, not a
+ * boot-time snapshot — every request re-reads it. No project open (thunk
+ * returns `undefined`) -> `next()`, never a 5xx.
+ *
+ * `configureServer`-only: it exists to serve an OPENED project's files, which
+ * is a session's job and nothing else's.
+ */
+import { readFile } from 'node:fs/promises';
+import { extname, join, normalize, resolve, sep } from 'node:path';
+import type { Plugin } from 'vite';
+import { MIME } from './vite-plugin-game-static';
+
+/**
+ * Resolve `rel` against `projectRoot`, refusing anything that escapes it.
+ * Plain `startsWith(root)` would wrongly admit a sibling folder that merely
+ * shares `root` as a string prefix (e.g. root `/a/b` and filePath `/a/bc/evil`)
+ * — the boundary must fall on a real path separator (or be an exact match).
+ * Returns `null` for an escape attempt.
+ */
+function resolveInsideProjectRoot(projectRoot: string, rel: string): string | null {
+  const root = resolve(projectRoot);
+  const filePath = normalize(join(root, rel));
+  if (filePath === root || filePath.startsWith(root + sep)) return filePath;
+  return null;
+}
+
+/** `req.url`'s path portion (query stripped), project-root-relative (leading
+ *  slash removed). Empty for the bare mount path (`/project-game-static`
+ *  itself, with nothing after it). */
+function requestRelPath(url: string | undefined): string {
+  // `.split('?')` always yields at least one element — `noUncheckedIndexedAccess`
+  // types index access as possibly-undefined regardless, so fall back to ''.
+  const path = (url ?? '').split('?')[0] ?? '';
+  return path.startsWith('/') ? path.slice(1) : path;
+}
+
+/**
+ * One `Range: bytes=…` header against a known size. Returns the inclusive
+ * range to send, `null` for "send the whole file" (absent, malformed, or a
+ * form this route does not implement — a multi-range request is legal to
+ * answer with the full body), or `'unsatisfiable'` for a start past the end,
+ * which must be a 416 rather than a silently clamped success.
+ */
+export function parseByteRange(
+  header: string | string[] | undefined,
+  size: number,
+): { start: number; end: number } | 'unsatisfiable' | null {
+  if (typeof header !== 'string') return null;
+  const match = /^bytes=(\d*)-(\d*)$/.exec(header.trim());
+  if (!match) return null;
+  const [, rawStart, rawEnd] = match;
+  if (rawStart === '' && rawEnd === '') return null;
+  // A suffix range (`bytes=-500`) asks for the LAST n bytes.
+  const start = rawStart === '' ? Math.max(0, size - Number(rawEnd)) : Number(rawStart);
+  const end = rawStart === '' || rawEnd === '' ? size - 1 : Math.min(Number(rawEnd), size - 1);
+  if (!Number.isFinite(start) || !Number.isFinite(end)) return null;
+  if (size === 0 || start >= size || start > end) return 'unsatisfiable';
+  return { start, end };
+}
+
+export function projectGameStaticPlugin(getProjectRoot: () => string | undefined): Plugin {
+  return {
+    name: 'vgai-project-game-static',
+    configureServer(server) {
+      server.middlewares.use('/project-game-static', async (req, res, next) => {
+        const projectRoot = getProjectRoot();
+        if (!projectRoot) return next(); // no project open — nothing to serve
+
+        const rel = requestRelPath(req.url);
+        if (!rel) return next();
+
+        const filePath = resolveInsideProjectRoot(projectRoot, rel);
+        if (!filePath) {
+          res.statusCode = 403;
+          res.end('forbidden');
+          return;
+        }
+
+        try {
+          const buf = await readFile(filePath);
+          res.setHeader('Content-Type', MIME[extname(filePath)] ?? 'application/octet-stream');
+          res.setHeader('Cache-Control', 'no-cache');
+          // RANGE, and it is load-bearing for video. A `<video>` element seeks by
+          // asking for a byte range, and a route that answers every request with
+          // the whole file and no `Accept-Ranges` cannot be seeked at all: the
+          // clip's own first frame never paints (measured — a reference tile and
+          // its Asset Lab document both showed black over a bright opening
+          // frame), and the scrubber does nothing. Everything else is unaffected:
+          // a request with no `Range` still gets the ordinary 200 below.
+          res.setHeader('Accept-Ranges', 'bytes');
+          const range = parseByteRange(req.headers['range'], buf.byteLength);
+          if (range === 'unsatisfiable') {
+            res.statusCode = 416;
+            res.setHeader('Content-Range', `bytes */${buf.byteLength}`);
+            res.end();
+            return;
+          }
+          if (range) {
+            res.statusCode = 206;
+            res.setHeader('Content-Range', `bytes ${range.start}-${range.end}/${buf.byteLength}`);
+            res.setHeader('Content-Length', range.end - range.start + 1);
+            res.end(buf.subarray(range.start, range.end + 1));
+            return;
+          }
+          res.statusCode = 200;
+          res.end(buf);
+        } catch {
+          next();
+        }
+      });
+    },
+  };
+}