@vgai/engine 0.5.42 → 0.5.44

package/src/adapter/adapter-module.ts

@@ -491,42 +491,22 @@ export interface PrefabsFromStoriesParams {
   readonly finder: 'prefabsFromStories';
 }
 
-/** Every finder this engine ships, as the adapter's concrete SELECTION. */
-export type FinderSelection = ScenesFromEntrypointSelectionParams | PrefabsFromStoriesParams;
-
-/** The finder names, as a value — what the loader's dispatcher switches on. */
-export const FINDER_NAMES = ['scenesFromEntrypointSelection', 'prefabsFromStories'] as const;
-export type FinderName = (typeof FINDER_NAMES)[number];
-
-const ScenesFromEntrypointSelectionSchema = z
-  .object({
-    finder: z.literal('scenesFromEntrypointSelection'),
-    regions: z
-      .union([z.array(z.string().min(1)).min(1), z.literal(EXPORTED_COMPOSITION_REGIONS)])
-      .describe('Region ids whose entrypoints carry the selection, or the rule form'),
-    selection: z
-      .string()
-      .min(1)
-      .optional()
-      .describe(
-        "Identifier of the entrypoint's module-level scene selection table; omit for a " +
-          'single-composition entrypoint',
-      ),
-  })
-  .strict()
-  .refine((value) => value.selection === undefined || Array.isArray(value.regions), {
-    message:
-      'scenesFromEntrypointSelection: `selection` names an identifier in ONE entrypoint’s ' +
-      `source, so it cannot be paired with the \`${EXPORTED_COMPOSITION_REGIONS}\` rule — ` +
-      'name the region explicitly (`regions: ["<rootId>"]`).',
-  });
-
-const PrefabsFromStoriesSchema = z.object({ finder: z.literal('prefabsFromStories') }).strict();
+/**
+ * A finder selection: the finder's registered NAME plus its own parameters.
+ * The set of finders is OPEN (ARCHITECTURE-CORE §The editor protocol,
+ * "Documents, not scenes"): the engine's own register in
+ * `adapter/finders/registry.ts`, a contribution registers more, and this
+ * module validates only the envelope — each finder's parameters are checked
+ * against ITS schema the moment the loader runs it, loudly and by name.
+ */
+export type FinderSelection = {
+  readonly finder: string;
+  readonly [param: string]: unknown;
+};
 
-const FinderSelectionSchema = z.union([
-  ScenesFromEntrypointSelectionSchema,
-  PrefabsFromStoriesSchema,
-]);
+const FinderSelectionSchema = z
+  .object({ finder: z.string().min(1).describe('Registered finder name') })
+  .passthrough();
 
 // ---------------------------------------------------------------------------
 // The scene table
@@ -614,11 +594,13 @@ const SceneSourceSchema = z
  * verb, differing only in instance site (ARCHITECTURE-CORE §Roots: "A scene is
  * a ROLE, not a kind … the same kind of thing as a prefab").
  */
-export interface SceneEntry {
+export interface DocumentEntry {
   readonly id: string;
   readonly label: string;
   /** `scene` (swaps at the entrypoint's slot) or `prefab` (placed by a designer). */
-  readonly kind: 'scene' | 'prefab';
+  /** OPEN: `scene` and `prefab` are the first two kinds; a page, a component,
+   *  a model, a bake are kinds the same way. */
+  readonly kind: string;
   /** Owning region id; `null` for a project-scoped entry bound to no one root. */
   readonly region: string | null;
   /**
@@ -633,20 +615,20 @@ export interface SceneEntry {
    *  infers setup from neighboring filenames or game globals. */
   readonly isolationSetup?: SceneSource;
   /** Which finder produced it; absent = the adapter stated it outright. */
-  readonly finder?: FinderName;
+  readonly finder?: string;
 }
 
-const SceneEntrySchema = z
+const DocumentEntrySchema = z
   .object({
     id: z.string().min(1),
     label: z.string().min(1),
-    kind: z.enum(['scene', 'prefab']),
+    kind: z.string().min(1),
     region: z.string().min(1).nullable(),
     authorable: z.boolean(),
     reach: SceneReachSchema,
     source: SceneSourceSchema.optional(),
     isolationSetup: SceneSourceSchema.optional(),
-    finder: z.enum(FINDER_NAMES).optional(),
+    finder: z.string().min(1).optional(),
   })
   .strict();
 
@@ -654,8 +636,8 @@ const SceneEntrySchema = z
  * The adapter's scene table: entries stated outright, finder selections the
  * host runs to produce the rest, and the entry open by default.
  */
-export interface AdapterSceneTable {
-  readonly entries?: readonly SceneEntry[];
+export interface AdapterDocumentTable {
+  readonly entries?: readonly DocumentEntry[];
   readonly find?: readonly FinderSelection[];
   /**
    * Id of the entry open by default. Omit to let the finder's own answer
@@ -665,9 +647,9 @@ export interface AdapterSceneTable {
   readonly default?: string;
 }
 
-const AdapterSceneTableSchema = z
+const AdapterDocumentTableSchema = z
   .object({
-    entries: z.array(SceneEntrySchema).optional(),
+    entries: z.array(DocumentEntrySchema).optional(),
     find: z.array(FinderSelectionSchema).optional(),
     default: z.string().min(1).optional(),
   })
@@ -815,7 +797,7 @@ export interface AdapterDefinition {
    * an explicit `regions` LIST carries its own and rejects these by name.
    */
   readonly regionIncludes: Readonly<Record<string, AdapterRegionOverlay>>;
-  readonly scenes: AdapterSceneTable;
+  readonly documents: AdapterDocumentTable;
   readonly observation: readonly ObservationDeclaration[];
   readonly input?: AdapterInputBinding | undefined;
 }
@@ -826,7 +808,7 @@ export interface AdapterDefinition {
 export interface AdapterDefinitionInput {
   readonly regions?: RegionBinding;
   readonly regionIncludes?: Readonly<Record<string, AdapterRegionOverlay>>;
-  readonly scenes?: AdapterSceneTable;
+  readonly documents?: AdapterDocumentTable;
   readonly observation?: readonly ObservationDeclaration[];
   readonly input?: AdapterInputBinding | undefined;
 }
@@ -847,7 +829,7 @@ export const AdapterDefinitionSchema = z
   .object({
     regions: RegionBindingSchema.optional(),
     regionIncludes: RegionIncludesSchema.optional(),
-    scenes: AdapterSceneTableSchema.optional(),
+    documents: AdapterDocumentTableSchema.optional(),
     observation: z.array(ObservationDeclarationSchema).optional(),
     input: AdapterInputBindingSchema.optional(),
   })
@@ -885,7 +867,7 @@ export function defineAdapter(input: AdapterDefinitionInput = {}): AdapterDefini
   return Object.freeze({
     regions: input.regions ?? 'manifest-roots',
     regionIncludes: Object.freeze({ ...(input.regionIncludes ?? {}) }),
-    scenes: Object.freeze({ ...(input.scenes ?? {}) }),
+    documents: Object.freeze({ ...(input.documents ?? {}) }),
     observation: Object.freeze([...(input.observation ?? [])]),
     ...(input.input ? { input: input.input } : {}),
   });
@@ -894,7 +876,7 @@ export function defineAdapter(input: AdapterDefinitionInput = {}): AdapterDefini
 /** Extra bindings a near-native game adds without restating the native ones. */
 export interface NativeAdapterOptions {
   /** Scene-table entries this game states outright, beside what the finders find. */
-  readonly scenes?: readonly SceneEntry[];
+  readonly scenes?: readonly DocumentEntry[];
   /** Per-region `include`/`mounts` parameters for the derivation — see
    *  {@link AdapterDefinition.regionIncludes}. */
   readonly regionIncludes?: Readonly<Record<string, AdapterRegionOverlay>>;
@@ -911,7 +893,7 @@ export function nativeAdapter(options: NativeAdapterOptions = {}): AdapterDefini
   return defineAdapter({
     regions: 'manifest-roots',
     ...(options.regionIncludes ? { regionIncludes: options.regionIncludes } : {}),
-    scenes: {
+    documents: {
       ...(options.scenes ? { entries: options.scenes } : {}),
       find: [
         { finder: 'scenesFromEntrypointSelection', regions: EXPORTED_COMPOSITION_REGIONS },

package/src/adapter/authoring-seam-contract.ts

@@ -83,6 +83,7 @@ export const INSPECTOR_PROVIDER_SHAPE = defineSeamShape<InspectorProvider>()({
   properties: { optional: false, kind: 'function', required: 'operation' },
   get: { optional: false, kind: 'function', required: 'operation' },
   set: { optional: false, kind: 'function', required: 'effect' },
+  preview: { optional: true, kind: 'function', required: 'effect' },
   editability: { optional: true, kind: 'function', required: 'operation' },
   remove: { optional: true, kind: 'function', required: 'round-trip' },
 });

package/src/adapter/authoring.ts

@@ -346,6 +346,22 @@ export interface InspectorProvider {
    * performed by this provider, and the shell reports the live-only floor.
    */
   set(id: string, path: string, value: unknown): void | WriteAck | Promise<void | WriteAck>;
+  /**
+   * Optional — SHOW a value without writing it, for a control the user drags.
+   *
+   * The gizmo already has this pair ({@link TransformProvider.writeTransform}
+   * live, {@link TransformProvider.endEdit} persisting), and a colour picker
+   * needs the same shape: it streams values continuously while the pointer
+   * moves, and persisting each one is a write burst the absorb cycle cannot
+   * follow. So the control previews here on every change and calls
+   * {@link set} ONCE when the gesture ends.
+   *
+   * A preview NEVER persists and is never the truth: whatever the adapter
+   * mutates is discarded by the next remount unless a `set` follows. An
+   * adapter that cannot show a value without writing it simply omits this,
+   * and the control's preview is a no-op — the value still lands on commit.
+   */
+  preview?(id: string, path: string, value: unknown): void;
   /** Optional per-subject write preflight for shell affordances outside the
    * Inspector field grid (notably hierarchy eye/lock controls). The property
    * descriptor remains the Inspector's source of `readonly`; this gives other

package/src/adapter/finders/finder-result.ts

@@ -8,11 +8,11 @@
  * different facts, and only the second is a defect.
  */
 
-import type { SceneEntry } from '../adapter-module';
+import type { DocumentEntry } from '../adapter-module';
 
 export interface FinderResult {
   /** Scene-table entries this finder produced, in discovery order. */
-  readonly entries: readonly SceneEntry[];
+  readonly entries: readonly DocumentEntry[];
   /**
    * The entry this finder's own answer makes the default, when its answer
    * settles it UNAMBIGUOUSLY (one candidate). A finder never picks between

package/src/adapter/finders/index.ts

@@ -19,9 +19,16 @@
  * is what keeps a game's `vgai.adapter.ts` free of finder implementations.
  */
 
-import type { FinderSelection } from '../adapter-module';
+import { type ZodType, z } from 'zod';
+import {
+  EXPORTED_COMPOSITION_REGIONS,
+  type FinderSelection,
+  type PrefabsFromStoriesParams,
+  type ScenesFromEntrypointSelectionParams,
+} from '../adapter-module';
 import type { FinderResult } from './finder-result';
 import { type PrefabsFromStoriesInput, prefabsFromStories } from './prefabs-from-stories';
+import { registerFinder, runRegisteredFinder } from './registry';
 import {
   type ScenesFromEntrypointSelectionInput,
   scenesFromEntrypointSelection,
@@ -34,6 +41,13 @@ export type {
   StoryRegistration,
 } from './prefabs-from-stories';
 export { prefabsFromStories } from './prefabs-from-stories';
+export type { FinderContribution, FinderRegistration } from './registry';
+export {
+  registerContributedFinder,
+  registeredFinderNames,
+  registerFinder,
+  runRegisteredFinder,
+} from './registry';
 export type {
   EntrypointSource,
   ScenesFromEntrypointSelectionInput,
@@ -41,7 +55,20 @@ export type {
 export { scenesFromEntrypointSelection } from './scenes-from-entrypoint-selection';
 
 /** Everything any shipped finder can be handed, gathered once by the loader. */
-export type FinderInput = ScenesFromEntrypointSelectionInput & PrefabsFromStoriesInput;
+/** A project source the host read for a selection's `include` globs. */
+export interface ProjectSourceFile {
+  /** Project-relative path. */
+  readonly path: string;
+  readonly source: string;
+}
+
+export type FinderInput = ScenesFromEntrypointSelectionInput &
+  PrefabsFromStoriesInput & {
+    /** The sources matching every selection's `include` globs — empty when
+     *  no selection declares any. A contributed finder reads the project
+     *  through this and nothing else. */
+    readonly sources?: readonly ProjectSourceFile[];
+  };
 
 /**
  * Run one adapter-declared selection. The switch is exhaustive over
@@ -49,14 +76,43 @@ export type FinderInput = ScenesFromEntrypointSelectionInput & PrefabsFromStorie
  * here rather than silently contributing nothing.
  */
 export function runFinderSelection(selection: FinderSelection, input: FinderInput): FinderResult {
-  switch (selection.finder) {
-    case 'scenesFromEntrypointSelection':
-      return scenesFromEntrypointSelection(selection, input);
-    case 'prefabsFromStories':
-      return prefabsFromStories(selection, input);
-    default: {
-      const unreachable: never = selection;
-      throw new Error(`Unknown finder selection: ${JSON.stringify(unreachable)}`);
-    }
-  }
+  return runRegisteredFinder(selection, input);
 }
+
+// The engine's own finders register here, schemas beside them: what an
+// adapter may select by name is exactly what this registry holds.
+const ScenesFromEntrypointSelectionSchema = z
+  .object({
+    finder: z.literal('scenesFromEntrypointSelection'),
+    regions: z
+      .union([z.array(z.string().min(1)).min(1), z.literal(EXPORTED_COMPOSITION_REGIONS)])
+      .describe('Region ids whose entrypoints carry the selection, or the rule form'),
+    selection: z
+      .string()
+      .min(1)
+      .optional()
+      .describe(
+        "Identifier of the entrypoint's module-level scene selection table; omit for a " +
+          'single-composition entrypoint',
+      ),
+  })
+  .strict()
+  .refine((value) => value.selection === undefined || Array.isArray(value.regions), {
+    message:
+      'scenesFromEntrypointSelection: `selection` names an identifier in ONE entrypoint’s ' +
+      `source, so it cannot be paired with the \`${EXPORTED_COMPOSITION_REGIONS}\` rule — ` +
+      'name the region explicitly (`regions: ["<rootId>"]`).',
+  });
+registerFinder<ScenesFromEntrypointSelectionParams, FinderInput>({
+  name: 'scenesFromEntrypointSelection',
+  schema:
+    ScenesFromEntrypointSelectionSchema as unknown as ZodType<ScenesFromEntrypointSelectionParams>,
+  run: scenesFromEntrypointSelection,
+});
+registerFinder<PrefabsFromStoriesParams, FinderInput>({
+  name: 'prefabsFromStories',
+  schema: z
+    .object({ finder: z.literal('prefabsFromStories') })
+    .strict() as unknown as ZodType<PrefabsFromStoriesParams>,
+  run: prefabsFromStories,
+});

package/src/adapter/finders/prefabs-from-stories.ts

@@ -26,7 +26,7 @@
  * already produced and the component index it already has.
  */
 
-import type { PrefabsFromStoriesParams, SceneEntry } from '../adapter-module';
+import type { DocumentEntry, PrefabsFromStoriesParams } from '../adapter-module';
 import type { FinderResult } from './finder-result';
 
 /** One composed portable-CSF story, as the host's story registry reports it. */
@@ -112,7 +112,7 @@ export function prefabsFromStories(
   _params: PrefabsFromStoriesParams,
   input: PrefabsFromStoriesInput,
 ): FinderResult {
-  const entries: SceneEntry[] = [];
+  const entries: DocumentEntry[] = [];
   const notes: string[] = [];
   for (const [componentName, stories] of storiesByComponent(input.stories)) {
     const component = input.components?.find((candidate) => candidate.name === componentName);

package/src/adapter/finders/registry.ts

@@ -0,0 +1,95 @@
+/**
+ * THE FINDER REGISTRY — the open set of finders an adapter may SELECT by
+ * name (ARCHITECTURE-CORE §The editor protocol, "Documents, not scenes").
+ *
+ * A finder is a pure function from the project's gathered source to document
+ * entries, plus the Zod schema of its own parameters. The engine registers
+ * its two here (`./index.ts`); a contribution registers more through the
+ * same door. `adapter-module.ts` validates only the selection ENVELOPE; the
+ * parameters are checked against the finder's schema when the loader runs
+ * it — an unregistered name or a bad parameter refuses loudly, naming both.
+ */
+
+import type { ZodType } from 'zod';
+import type { FinderSelection } from '../adapter-module';
+import type { FinderResult } from './finder-result';
+
+/** What a registration's selection type must carry: the name. A finder's own
+ *  params interface satisfies this without an index signature. */
+export type FinderSelectionEnvelope = { readonly finder: string };
+
+export interface FinderRegistration<
+  S extends FinderSelectionEnvelope = FinderSelection,
+  I = unknown,
+> {
+  readonly name: S['finder'];
+  /** The selection's full shape, `finder` included; `.strict()` by the
+   *  same rule as every other adapter table. */
+  readonly schema: ZodType<S>;
+  readonly run: (selection: S, input: I) => FinderResult;
+}
+
+const registry = new Map<string, FinderRegistration>();
+
+/** Register a finder. A second registration under one name replaces the
+ *  first (a module re-evaluated on save), never throws. */
+export function registerFinder<S extends FinderSelectionEnvelope, I>(
+  registration: FinderRegistration<S, I>,
+): () => void {
+  const entry = registration as unknown as FinderRegistration;
+  registry.set(registration.name, entry);
+  return () => {
+    if (registry.get(registration.name) === entry) registry.delete(registration.name);
+  };
+}
+
+/**
+ * What a CONTRIBUTION exports to register a finder (ARCHITECTURE-CORE §The
+ * project model): a plain object a project module `src/contributions/<name>.finder.ts`
+ * exports as `finder`, handed by the HOST to {@link registerContributedFinder}.
+ * A selection may carry `include` globs; the host then supplies the matching
+ * project sources on `input.sources`, which is how a finder reads the
+ * project without a file system.
+ */
+export type FinderContribution = FinderRegistration<FinderSelection, unknown>;
+
+/** Register a contribution's finder after checking its shape by name. */
+export function registerContributedFinder(value: unknown, source: string): () => void {
+  const record = (value ?? {}) as Partial<FinderContribution>;
+  const problems: string[] = [];
+  if (typeof record.name !== 'string' || record.name.length === 0)
+    problems.push('`name` must be a non-empty string');
+  const schema = record.schema as { safeParse?: unknown } | undefined;
+  if (!schema || typeof schema.safeParse !== 'function')
+    problems.push('`schema` must be a Zod schema');
+  if (typeof record.run !== 'function') problems.push('`run(selection, input)` must be a function');
+  if (problems.length > 0) throw new Error(`${source}: not a finder — ${problems.join('; ')}`);
+  return registerFinder(record as FinderContribution);
+}
+
+/** Every registered finder name, in registration order. */
+export function registeredFinderNames(): readonly string[] {
+  return [...registry.keys()];
+}
+
+/** Validate a selection against its finder's schema and run it. */
+export function runRegisteredFinder<I>(selection: FinderSelection, input: I): FinderResult {
+  const registration = registry.get(selection.finder);
+  if (!registration) {
+    const known = registeredFinderNames();
+    throw new Error(
+      `Unknown finder ${JSON.stringify(selection.finder)} — registered: ${
+        known.length > 0 ? known.map((n) => `"${n}"`).join(', ') : 'none'
+      }`,
+    );
+  }
+  const parsed = registration.schema.safeParse(selection);
+  if (!parsed.success) {
+    throw new Error(
+      `Finder ${JSON.stringify(selection.finder)}: ${parsed.error.issues
+        .map((issue) => `${issue.path.join('.') || '(selection)'}: ${issue.message}`)
+        .join('; ')}`,
+    );
+  }
+  return registration.run(parsed.data, input);
+}

package/src/adapter/finders/scenes-from-entrypoint-selection.ts

@@ -38,7 +38,7 @@
 
 import ts from 'typescript';
 import type {
-  SceneEntry,
+  DocumentEntry,
   SceneSource,
   ScenesFromEntrypointSelectionParams,
 } from '../adapter-module';
@@ -263,7 +263,7 @@ function targetedEntrypoints(
 /** DEGENERATE: the entrypoint mounts one composition, and mounting the region
  *  IS opening it. Labelled by the module's own default export — the game's own
  *  word for this composition. */
-function degenerateEntry(entrypoint: EntrypointSource, sf: ts.SourceFile): SceneEntry {
+function degenerateEntry(entrypoint: EntrypointSource, sf: ts.SourceFile): DocumentEntry {
   return {
     id: entrypoint.regionId,
     label: defaultExportName(sf) ?? basename(entrypoint.path),
@@ -286,7 +286,7 @@ function selectionEntries(
   selection: string,
   resolveModule: ScenesFromEntrypointSelectionInput['resolveModule'],
   notes: string[],
-): { entries: SceneEntry[]; active: string | undefined } {
+): { entries: DocumentEntry[]; active: string | undefined } {
   const table = selectionTable(sf, selection);
   if (!table) {
     notes.push(
@@ -352,7 +352,7 @@ export function scenesFromEntrypointSelection(
   input: ScenesFromEntrypointSelectionInput,
 ): FinderResult {
   const notes: string[] = [];
-  const entries: SceneEntry[] = [];
+  const entries: DocumentEntry[] = [];
   const active: string[] = [];
 
   for (const entrypoint of targetedEntrypoints(params, input.entrypoints, notes)) {

package/src/adapter/ingest/scene-capture.ts

@@ -649,30 +649,59 @@ export function installSceneCapture(
     recordLoop: recordAnimationLoop,
   });
 
-  // DOM-backed Three renderers (CSS3DRenderer is the first) use a normal
-  // prototype method rather than WebGLRenderer's constructor assignment. Trap
-  // only classes explicitly supplied by the host, and restore each byte-for-byte.
+  // DOM-backed Three renderers (CSS3DRenderer is the first): trap only classes
+  // explicitly supplied by the host, and restore each byte-for-byte. Two
+  // shapes exist across three revisions and both are met: an ordinary
+  // prototype `render` is wrapped in place; a CONSTRUCTOR-ASSIGNED `render`
+  // (r180's CSS3DRenderer does `this.render = function …` exactly like
+  // WebGLRenderer, so the prototype carries none) gets the same
+  // getter/setter trap the WebGLRenderer path uses — the constructor's
+  // assignment hits the setter, the getter hands back the observing wrapper.
+  // Skipping that shape silently was measured as "the game never rendered"
+  // on css3d_periodictable while 118 of its elements sat in the DOM.
   const additionalRendererRestores: Array<() => void> = [];
   for (const candidate of opts?.additionalRendererCtors ?? []) {
     const ctor = candidate as PrototypeRendererCtorLike;
     const rendererProto = ctor?.prototype;
-    const priorRender = rendererProto?.render;
-    if (!rendererProto || typeof priorRender !== 'function' || rendererProto === proto) continue;
-    rendererProto.render = function (this: unknown, ...args: unknown[]) {
-      observeRendererRender(this, args[0], args[1]);
-      const hooks = renderPassHooks;
-      if (hooks === null || !captured || this !== captured.renderer) {
-        return priorRender.apply(this, args);
-      }
-      hooks.before();
-      try {
-        return priorRender.apply(this, args);
-      } finally {
-        hooks.after();
-      }
-    };
+    if (!rendererProto || rendererProto === proto) continue;
+    const priorRender = rendererProto.render;
+    if (typeof priorRender === 'function') {
+      rendererProto.render = function (this: unknown, ...args: unknown[]) {
+        observeRendererRender(this, args[0], args[1]);
+        const hooks = renderPassHooks;
+        if (hooks === null || !captured || this !== captured.renderer) {
+          return priorRender.apply(this, args);
+        }
+        hooks.before();
+        try {
+          return priorRender.apply(this, args);
+        } finally {
+          hooks.after();
+        }
+      };
+      additionalRendererRestores.push(() => {
+        rendererProto.render = priorRender;
+      });
+      continue;
+    }
+    const priorAddonDescriptor = Object.getOwnPropertyDescriptor(rendererProto, 'render');
+    Object.defineProperty(rendererProto, 'render', {
+      configurable: true,
+      set(this: Record<symbol, unknown>, fn: unknown) {
+        this[REAL] = fn;
+      },
+      get(this: Record<symbol, unknown>) {
+        const self = this;
+        return function render(this: unknown, ...args: unknown[]) {
+          observeRendererRender(self, args[0], args[1]);
+          return forwardRender(self, args);
+        };
+      },
+    });
     additionalRendererRestores.push(() => {
-      rendererProto.render = priorRender;
+      if (priorAddonDescriptor)
+        Object.defineProperty(rendererProto, 'render', priorAddonDescriptor);
+      else delete (rendererProto as { render?: unknown }).render;
     });
   }
 

package/src/adapter/system-adapter.ts

@@ -168,7 +168,9 @@ export interface NetPeer {
  *  running. `null` from `getServerConfig` means no server is declared. */
 export interface NetServerConfig {
   endpoint: string;
-  roomName: string;
+  /** Known once the game's own networking adapter reports it; in edit mode
+   *  the declared `process` gives only the endpoint. */
+  roomName?: string;
 }
 
 /** The signed-in player's authored identity, used as the connect default. */

package/src/canvas-react/pixi-react-root-factory.tsx

@@ -150,19 +150,19 @@ function canvasWorldAdapter(id: string, component: ComponentType): RootAdapter<'
       const unmounted = new Promise<void>((resolve) => {
         resolveUnmounted = resolve;
       });
+      let resolveEffectsUnmounted!: () => void;
+      const effectsUnmounted = new Promise<void>((resolve) => {
+        resolveEffectsUnmounted = resolve;
+      });
       /**
-       * Signals the tree's FIRST COMMIT and its LAST. A layout effect,
-       * deliberately, and rendered as the LAST child, deliberately:
+       * Signals the tree's FIRST COMMIT and both unmount cleanup phases. Rendered as the LAST
+       * child deliberately:
        *
        *  - mount: layout effects run synchronously inside the commit, before
        *    any passive effect and before any tick can be scheduled;
-       *  - unmount: React commits deletion effects in tree order, each node
-       *    before its own children, so the LAST sibling's cleanup is the last
-       *    to run. That is what makes this a reliable "every component has
-       *    finished tearing down" signal — and it is load-bearing, because
-       *    `useTick`'s own cleanup calls `ticker.remove()`. Destroying the
-       *    Application before that cleanup lands throws inside React's commit
-       *    on every teardown of any world with a tick hook.
+       *  - unmount: the layout cleanup fences `useTick` and the passive cleanup fences ordinary
+       *    project effects. Native destruction waits for BOTH; resolving only from layout left
+       *    passive listener/resource cleanup racing an Application whose renderer was null.
        */
       function Lifecycle(): null {
         useLayoutEffect(() => {
@@ -172,7 +172,10 @@ function canvasWorldAdapter(id: string, component: ComponentType): RootAdapter<'
         // This component is the last sibling. Reaching its passive effect
         // means the initial tree's provider/command effects have registered,
         // so mount() can truthfully back Play's ack.
-        useEffect(resolveEffectsReady, []);
+        useEffect(() => {
+          resolveEffectsReady();
+          return resolveEffectsUnmounted;
+        }, []);
         return null;
       }
 
@@ -282,7 +285,14 @@ function canvasWorldAdapter(id: string, component: ComponentType): RootAdapter<'
       // Adapter surface: the host's shared debug registry. The game's own
       // capabilities arrive as the entry module's declared `systems`.
       const systemAdapters: SystemAdapters = registry ? { debug: registry.adapter } : {};
-      const disposeComplete = unmounted.then(() => {
+      const disposeComplete = Promise.all([unmounted, effectsUnmounted]).then(() => {
+        // React can tear the root down itself after a fatal layout/effect error. In that path the
+        // host has not called dispose() yet, but Application.destroy() still clears Pixi's ticker
+        // and renderer. Wait for both layout and passive cleanup first: project effects may own
+        // window/document listeners and can still read the Pixi Application while React drains
+        // passive deletion effects. Fence the mounted root before clearing the native slots so
+        // subsequent host frames and the eventual host teardown cannot re-enter them.
+        disposed = true;
         mountedApp.destroy(false, { children: true });
       });
 

package/src/data/vite-plugin-data.ts

@@ -27,7 +27,7 @@
  *    target file" hole, closed for declared refs — see
  *    `collectDeclaredRefFields`/`findMissingRefTargets` in `data-check-core.ts`).
  * 3. **Tools never ship** (`generateBundle`): no emitted chunk may contain a
- *    module from `src/tools/` or a `*.tool.*` file (§4: tester serves and
+ *    module from `src/contributions/`, `src/tools/` or a `*.tool.*` file (§4: tester serves and
  *    standalone builds strip tools entirely; W4 made this true by
  *    construction — nothing imports tools — and this check PINS it against
  *    the day some game module imports a tool "just for a helper").
@@ -268,7 +268,9 @@ export async function collectDataCheckProblems(options: VgaiDataCheckOptions): P
 /** True iff a bundled module id is tool code that must never ship (§4). Pure, unit-tested. */
 export function isToolModuleId(id: string): boolean {
   const normalized = id.split('\\').join('/');
-  return /\/src\/tools\//.test(normalized) || /\.tool\.[tj]sx?(\?|$)/.test(normalized);
+  return (
+    /\/src\/(?:tools|contributions)\//.test(normalized) || /\.tool\.[tj]sx?(\?|$)/.test(normalized)
+  );
 }
 
 /**