@vgai/engine 0.5.13 → 0.5.14

package/dist/adapter/constraint.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constraint.d.ts","sourceRoot":"","sources":["../../src/adapter/constraint.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AAGpC,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,UAAU,GAAG,YAAY,GAAG,OAAO,CAAC;AAE7E,MAAM,WAAW,gBAAgB;IAC/B,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,aAAa,GAAG,QAAQ,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IACxD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,iEAAiE;IACjE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,SAAS,KAAK,CAAC,QAAQ,EAAE,CAAC;IAC1C,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,GAAG,IAAI,CAAC;IACvC,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC,QAAQ,GAAG,IAAI,CAAC;IACrC,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,WAAW,IAAI,kBAAkB,CAAC;CACnC;AAED,wBAAgB,aAAa,CAC3B,MAAM,EAAE,KAAK,CAAC,QAAQ,GAAG,IAAI,GAAG,SAAS,GACxC,SAAS,cAAc,EAAE,CAU3B;AAED,iFAAiF;AACjF,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,EAAE,IAAI,EAAE,cAAc,GAAG,IAAI,CAGpF;AAED,4EAA4E;AAC5E,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAQ7E"}
+{"version":3,"file":"constraint.d.ts","sourceRoot":"","sources":["../../src/adapter/constraint.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AAGpC,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,UAAU,GAAG,YAAY,GAAG,OAAO,CAAC;AAE7E,MAAM,WAAW,gBAAgB;IAC/B,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,aAAa,GAAG,QAAQ,GAAG,KAAK,GAAG,UAAU,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IAC7E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,iEAAiE;IACjE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,SAAS,CAAC;CACrC;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,SAAS,KAAK,CAAC,QAAQ,EAAE,CAAC;IAC1C,kEAAkE;IAClE,QAAQ,CAAC,WAAW,EAAE,KAAK,CAAC,QAAQ,GAAG,IAAI,CAAC;IAC5C,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,GAAG,IAAI,CAAC;IACvC,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC,QAAQ,GAAG,IAAI,CAAC;IACrC,wEAAwE;IACxE,QAAQ,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAAC;CACxC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,WAAW,IAAI,kBAAkB,CAAC;CACnC;AAED,wBAAgB,aAAa,CAC3B,MAAM,EAAE,KAAK,CAAC,QAAQ,GAAG,IAAI,GAAG,SAAS,GACxC,SAAS,cAAc,EAAE,CAU3B;AAED,iFAAiF;AACjF,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,EAAE,IAAI,EAAE,cAAc,GAAG,IAAI,CAGpF;AAED,4EAA4E;AAC5E,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAQ7E"}

package/dist/adapter/finders/finder-result.d.ts

@@ -0,0 +1,28 @@
+/**
+ * What every finder answers with.
+ *
+ * A finder is a PURE function over project source/files with explicit inputs
+ * and outputs — it never reads a filesystem, never fetches, and never consults
+ * ambient state. What it cannot answer it says so in {@link FinderResult.notes}
+ * rather than degrading silently: "has none" and "nobody could look" are
+ * different facts, and only the second is a defect.
+ */
+import type { SceneEntry } from '../adapter-module';
+export interface FinderResult {
+    /** Scene-table entries this finder produced, in discovery order. */
+    readonly entries: readonly SceneEntry[];
+    /**
+     * The entry this finder's own answer makes the default, when its answer
+     * settles it UNAMBIGUOUSLY (one candidate). A finder never picks between
+     * candidates — that is the adapter author's declaration to make, and an
+     * absent default stays the honest fact that none was declared.
+     */
+    readonly default?: string;
+    /**
+     * Loud, non-fatal diagnostics: a selection identifier that is not in the
+     * source, an entrypoint whose bytes could not be read. Every note names the
+     * file it is about. The host surfaces these; it never swallows them.
+     */
+    readonly notes: readonly string[];
+}
+//# sourceMappingURL=finder-result.d.ts.map

package/dist/adapter/finders/finder-result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"finder-result.d.ts","sourceRoot":"","sources":["../../../src/adapter/finders/finder-result.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,MAAM,WAAW,YAAY;IAC3B,oEAAoE;IACpE,QAAQ,CAAC,OAAO,EAAE,SAAS,UAAU,EAAE,CAAC;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC"}

package/dist/adapter/finders/finder-result.js

@@ -0,0 +1,10 @@
+/**
+ * What every finder answers with.
+ *
+ * A finder is a PURE function over project source/files with explicit inputs
+ * and outputs — it never reads a filesystem, never fetches, and never consults
+ * ambient state. What it cannot answer it says so in {@link FinderResult.notes}
+ * rather than degrading silently: "has none" and "nobody could look" are
+ * different facts, and only the second is a defect.
+ */
+export {};

package/dist/adapter/finders/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * THE FINDER NAMESPACE — host-owned discovery algorithms an adapter SELECTS.
+ *
+ * ARCHITECTURE-CORE §The editor protocol, "Zero inference": what zero
+ * inference forbids is the ENGINE running a finder nobody selected. A
+ * convention (`src/scenes/`, a story registration) is legitimate exactly when
+ * it is an adapter's declared finder parameter, and illegitimate as implicit
+ * engine behavior.
+ *
+ * That is enforced MECHANICALLY, not by policy: everything under this
+ * directory has exactly ONE sanctioned importer — the editor's adapter loader
+ * (`packages/editor/src/project-adapter.ts`) — and
+ * `packages/engine/test/finder-import-boundary.test.ts` fails by name when any
+ * other engine/editor file imports it. Do not add a second importer; make the
+ * loader answer instead.
+ *
+ * Dependency direction is one-way: finders import their parameter types from
+ * `../adapter-module`, and `adapter-module.ts` imports nothing from here. That
+ * is what keeps a game's `vgai.adapter.ts` free of finder implementations.
+ */
+import type { FinderSelection } from '../adapter-module';
+import type { FinderResult } from './finder-result';
+import { type PrefabsFromStoriesInput } from './prefabs-from-stories';
+import { type ScenesFromEntrypointSelectionInput } from './scenes-from-entrypoint-selection';
+export type { FinderResult } from './finder-result';
+export type { PrefabsFromStoriesInput, ProjectComponentRef, StoryRegistration, } from './prefabs-from-stories';
+export { prefabsFromStories } from './prefabs-from-stories';
+export type { EntrypointSource, ScenesFromEntrypointSelectionInput, } from './scenes-from-entrypoint-selection';
+export { scenesFromEntrypointSelection } from './scenes-from-entrypoint-selection';
+/** Everything any shipped finder can be handed, gathered once by the loader. */
+export type FinderInput = ScenesFromEntrypointSelectionInput & PrefabsFromStoriesInput;
+/**
+ * Run one adapter-declared selection. The switch is exhaustive over
+ * {@link FinderSelection}: a new finder that forgets a case fails to COMPILE
+ * here rather than silently contributing nothing.
+ */
+export declare function runFinderSelection(selection: FinderSelection, input: FinderInput): FinderResult;
+//# sourceMappingURL=index.d.ts.map

package/dist/adapter/finders/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/adapter/finders/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,KAAK,uBAAuB,EAAsB,MAAM,wBAAwB,CAAC;AAC1F,OAAO,EACL,KAAK,kCAAkC,EAExC,MAAM,oCAAoC,CAAC;AAE5C,YAAY,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,YAAY,EACV,uBAAuB,EACvB,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,YAAY,EACV,gBAAgB,EAChB,kCAAkC,GACnC,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,6BAA6B,EAAE,MAAM,oCAAoC,CAAC;AAEnF,gFAAgF;AAChF,MAAM,MAAM,WAAW,GAAG,kCAAkC,GAAG,uBAAuB,CAAC;AAEvF;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,eAAe,EAAE,KAAK,EAAE,WAAW,GAAG,YAAY,CAW/F"}

package/dist/adapter/finders/index.js

@@ -0,0 +1,41 @@
+/**
+ * THE FINDER NAMESPACE — host-owned discovery algorithms an adapter SELECTS.
+ *
+ * ARCHITECTURE-CORE §The editor protocol, "Zero inference": what zero
+ * inference forbids is the ENGINE running a finder nobody selected. A
+ * convention (`src/scenes/`, a story registration) is legitimate exactly when
+ * it is an adapter's declared finder parameter, and illegitimate as implicit
+ * engine behavior.
+ *
+ * That is enforced MECHANICALLY, not by policy: everything under this
+ * directory has exactly ONE sanctioned importer — the editor's adapter loader
+ * (`packages/editor/src/project-adapter.ts`) — and
+ * `packages/engine/test/finder-import-boundary.test.ts` fails by name when any
+ * other engine/editor file imports it. Do not add a second importer; make the
+ * loader answer instead.
+ *
+ * Dependency direction is one-way: finders import their parameter types from
+ * `../adapter-module`, and `adapter-module.ts` imports nothing from here. That
+ * is what keeps a game's `vgai.adapter.ts` free of finder implementations.
+ */
+import { prefabsFromStories } from './prefabs-from-stories';
+import { scenesFromEntrypointSelection, } from './scenes-from-entrypoint-selection';
+export { prefabsFromStories } from './prefabs-from-stories';
+export { scenesFromEntrypointSelection } from './scenes-from-entrypoint-selection';
+/**
+ * Run one adapter-declared selection. The switch is exhaustive over
+ * {@link FinderSelection}: a new finder that forgets a case fails to COMPILE
+ * here rather than silently contributing nothing.
+ */
+export function runFinderSelection(selection, input) {
+    switch (selection.finder) {
+        case 'scenesFromEntrypointSelection':
+            return scenesFromEntrypointSelection(selection, input);
+        case 'prefabsFromStories':
+            return prefabsFromStories(selection, input);
+        default: {
+            const unreachable = selection;
+            throw new Error(`Unknown finder selection: ${JSON.stringify(unreachable)}`);
+        }
+    }
+}

package/dist/adapter/finders/prefabs-from-stories.d.ts

@@ -0,0 +1,64 @@
+/**
+ * FINDER — prefabs from colocated portable-CSF story registrations.
+ *
+ * ARCHITECTURE-CORE §Roots: "A prefab is an ordinary source component that a
+ * designer independently places, duplicates, or reuses, explicitly registered
+ * for Content by a colocated portable story whose `meta.component` names it."
+ * The registration is the load-bearing reference — delete the story and the
+ * declaration is gone — which is why source SHAPE alone never admits a prefab.
+ *
+ * EXTRACTION, not a new rule. The join implemented here is the one the editor
+ * already runs:
+ *   - the match + same-source-directory tiebreak:
+ *     `packages/editor/src/stories/story-registry.ts:162-186`
+ *     (`componentPreviewStories`) and `:148-159` (`pickComponentPreviewStory`);
+ *   - the default-story preference: `story-registry.ts:118-123`
+ *     (`isDeclaredDefaultStory`);
+ *   - the admission rule "a component with no story is not a Content entry at
+ *     all": `packages/editor/src/components/AssetBrowser.tsx`, the
+ *     `browserEntries` content scope (`if (!previewStory) return []`).
+ * `meta.component`'s identity NAME is read live by
+ * `packages/editor/src/stories/compose-project-stories.ts:130` /
+ * `:185` (`componentIdentityName`) — this finder consumes that answer rather
+ * than re-deriving it, so both sides of the join agree by construction.
+ *
+ * Pure over its inputs: the host hands in the registrations the story registry
+ * already produced and the component index it already has.
+ */
+import type { PrefabsFromStoriesParams } from '../adapter-module';
+import type { FinderResult } from './finder-result';
+/** One composed portable-CSF story, as the host's story registry reports it. */
+export interface StoryRegistration {
+    /** Project-relative path of the CSF module (`src/prefabs/HeroBox.stories.tsx`). */
+    readonly modulePath: string;
+    /** The composed story's stable id. */
+    readonly storyId: string;
+    /** Human label for the story. */
+    readonly label: string;
+    /**
+     * `meta.component`'s identity name. Absent ⇒ this story is joined to nothing
+     * and declares no prefab — an ordinary story document, not a defect.
+     */
+    readonly componentName?: string;
+    /** Whether the module declares this story as its component's default. */
+    readonly isDefault?: boolean;
+}
+/** One entry of the host's project component index. */
+export interface ProjectComponentRef {
+    readonly name: string;
+    /** Project-relative source path of the component's own module. */
+    readonly path: string;
+    /** Region this component's surface belongs to, when the host knows it. */
+    readonly region?: string | null;
+}
+export interface PrefabsFromStoriesInput {
+    readonly stories: readonly StoryRegistration[];
+    /**
+     * The project's component index. Supplies each prefab's own source path and
+     * region; absent, entries still exist (the story IS the declaration) and
+     * simply carry no `source`.
+     */
+    readonly components?: readonly ProjectComponentRef[];
+}
+export declare function prefabsFromStories(_params: PrefabsFromStoriesParams, input: PrefabsFromStoriesInput): FinderResult;
+//# sourceMappingURL=prefabs-from-stories.d.ts.map

package/dist/adapter/finders/prefabs-from-stories.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prefabs-from-stories.d.ts","sourceRoot":"","sources":["../../../src/adapter/finders/prefabs-from-stories.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,wBAAwB,EAAc,MAAM,mBAAmB,CAAC;AAC9E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEpD,gFAAgF;AAChF,MAAM,WAAW,iBAAiB;IAChC,mFAAmF;IACnF,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,sCAAsC;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,iCAAiC;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,yEAAyE;IACzE,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,uDAAuD;AACvD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,OAAO,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC/C;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;CACtD;AA6CD,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,wBAAwB,EACjC,KAAK,EAAE,uBAAuB,GAC7B,YAAY,CA4Bd"}

package/dist/adapter/finders/prefabs-from-stories.js

@@ -0,0 +1,92 @@
+/**
+ * FINDER — prefabs from colocated portable-CSF story registrations.
+ *
+ * ARCHITECTURE-CORE §Roots: "A prefab is an ordinary source component that a
+ * designer independently places, duplicates, or reuses, explicitly registered
+ * for Content by a colocated portable story whose `meta.component` names it."
+ * The registration is the load-bearing reference — delete the story and the
+ * declaration is gone — which is why source SHAPE alone never admits a prefab.
+ *
+ * EXTRACTION, not a new rule. The join implemented here is the one the editor
+ * already runs:
+ *   - the match + same-source-directory tiebreak:
+ *     `packages/editor/src/stories/story-registry.ts:162-186`
+ *     (`componentPreviewStories`) and `:148-159` (`pickComponentPreviewStory`);
+ *   - the default-story preference: `story-registry.ts:118-123`
+ *     (`isDeclaredDefaultStory`);
+ *   - the admission rule "a component with no story is not a Content entry at
+ *     all": `packages/editor/src/components/AssetBrowser.tsx`, the
+ *     `browserEntries` content scope (`if (!previewStory) return []`).
+ * `meta.component`'s identity NAME is read live by
+ * `packages/editor/src/stories/compose-project-stories.ts:130` /
+ * `:185` (`componentIdentityName`) — this finder consumes that answer rather
+ * than re-deriving it, so both sides of the join agree by construction.
+ *
+ * Pure over its inputs: the host hands in the registrations the story registry
+ * already produced and the component index it already has.
+ */
+/** Directory portion of a project-relative path — `story-registry.ts:126`'s `sourceDir`. */
+function sourceDir(path) {
+    const normalized = path.replaceAll('\\', '/').replace(/^\.\//, '');
+    const slash = normalized.lastIndexOf('/');
+    return slash >= 0 ? normalized.slice(0, slash) : '';
+}
+/** Group the registrations by the component their meta NAMES. A story naming
+ *  none is joined to nothing and declares no prefab. */
+function storiesByComponent(stories) {
+    const byComponent = new Map();
+    for (const story of stories) {
+        const name = story.componentName;
+        if (name === undefined || name === '')
+            continue;
+        const bucket = byComponent.get(name);
+        if (bucket)
+            bucket.push(story);
+        else
+            byComponent.set(name, [story]);
+    }
+    return byComponent;
+}
+/**
+ * The story that speaks for a component: colocated beats distant
+ * (story-registry.ts:177-180 — two files can export a same-named component),
+ * and within that set the module's own declared default wins
+ * (story-registry.ts:118-123).
+ */
+function chooseStory(stories, component) {
+    const sameDir = component
+        ? stories.filter((story) => sourceDir(story.modulePath) === sourceDir(component.path))
+        : [];
+    const pool = sameDir.length > 0 ? sameDir : stories;
+    return {
+        chosen: pool.find((story) => story.isDefault === true) ?? pool[0],
+        colocated: sameDir.length > 0,
+    };
+}
+export function prefabsFromStories(_params, input) {
+    const entries = [];
+    const notes = [];
+    for (const [componentName, stories] of storiesByComponent(input.stories)) {
+        const component = input.components?.find((candidate) => candidate.name === componentName);
+        const { chosen, colocated } = chooseStory(stories, component);
+        if (!chosen)
+            continue;
+        if (component && !colocated) {
+            notes.push(`prefabsFromStories: "${componentName}" is declared by ${chosen.modulePath}, which is not ` +
+                `colocated with ${component.path}. The join is by name; confirm it names this component.`);
+        }
+        entries.push({
+            id: componentName,
+            label: componentName,
+            kind: 'prefab',
+            region: component?.region ?? null,
+            authorable: true,
+            reach: { kind: 'story', storyId: chosen.storyId },
+            ...(component ? { source: { path: component.path, export: component.name } } : {}),
+            finder: 'prefabsFromStories',
+        });
+    }
+    // Prefabs are sibling documents, never the default scene — a finder that
+    // cannot settle a default says nothing rather than nominating one.
+    return { entries, notes };
+}

package/dist/adapter/finders/scenes-from-entrypoint-selection.d.ts

@@ -0,0 +1,67 @@
+/**
+ * FINDER — scenes from the entrypoint's active-scene selection.
+ *
+ * ARCHITECTURE-CORE §The editor protocol, "Zero inference": discovery may be a
+ * LIBRARY, and this is one. It only ever runs because an adapter SELECTED it
+ * (`{ finder: 'scenesFromEntrypointSelection', … }`); the engine never runs a
+ * finder nobody selected, which `packages/engine/test/finder-import-boundary.test.ts`
+ * enforces mechanically rather than by policy.
+ *
+ * Why the ENTRYPOINT and not a folder: it is a LOAD-BEARING source — a
+ * reference the game itself executes. The review test is "would the game break
+ * if this fact lied?", and here it would: change the entrypoint's selection
+ * table and the game changes with it. A `src/scenes/` convention can drift
+ * silently; this cannot.
+ *
+ * Two answers, and the difference is declared rather than sniffed:
+ *   - the adapter names a `selection` identifier ⇒ read that module-level
+ *     table and answer one entry per key, each reachable through it;
+ *   - the adapter names none ⇒ the entrypoint mounts ONE composition, and the
+ *     answer is the single-scene DEGENERATE table: the region's own
+ *     composition, opened by mounting the region.
+ *
+ * ON `typescript`: this module parses the entrypoint's own TSX with the
+ * TypeScript compiler API — the same parser `packages/editor/src/ui-source/
+ * oid-transform.ts` and `packages/editor/src/asset-workflow/project-content.ts`
+ * already use for exactly this kind of question (vgai has `typescript`; it does
+ * NOT have @babel/*). It is a HOST-SIDE-ONLY dependency: finders are importable
+ * only by the adapter loader, `adapter-module.ts` imports nothing from this
+ * directory, and a game's `vgai.adapter.ts` therefore never pulls a parser into
+ * its own bundle.
+ */
+import type { ScenesFromEntrypointSelectionParams } from '../adapter-module';
+import type { FinderResult } from './finder-result';
+/** One region's entrypoint, as the host reads it off the manifest + disk. */
+export interface EntrypointSource {
+    /** The region (== manifest root) id. */
+    readonly regionId: string;
+    /** Project-relative path of the root's `entry` module. */
+    readonly path: string;
+    /** The module's bytes; `null` when they could not be read. */
+    readonly source: string | null;
+    /** The root's declared `dev` flag — a dev layer is the game's own dev GUI. */
+    readonly dev: boolean;
+}
+export interface ScenesFromEntrypointSelectionInput {
+    /**
+     * Every region the host mounts from an exported composition (a root with an
+     * `entry`), in manifest order.
+     */
+    readonly entrypoints: readonly EntrypointSource[];
+    /**
+     * Resolve one of the entrypoint's own import specifiers to a project-relative
+     * path. Supplied by the host because extension/index resolution is a
+     * filesystem question and this function is pure. Absent, or answering `null`,
+     * means the produced entry carries no `source` — an honest omission rather
+     * than a guessed path.
+     */
+    readonly resolveModule?: (specifier: string, fromPath: string) => string | null;
+}
+/**
+ * Answer the scene table this finder's selection describes.
+ *
+ * Pure: every input is passed in, nothing is read from disk, and an
+ * unanswerable question becomes a NOTE rather than a fabricated entry.
+ */
+export declare function scenesFromEntrypointSelection(params: ScenesFromEntrypointSelectionParams, input: ScenesFromEntrypointSelectionInput): FinderResult;
+//# sourceMappingURL=scenes-from-entrypoint-selection.d.ts.map

package/dist/adapter/finders/scenes-from-entrypoint-selection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scenes-from-entrypoint-selection.d.ts","sourceRoot":"","sources":["../../../src/adapter/finders/scenes-from-entrypoint-selection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAGH,OAAO,KAAK,EAGV,mCAAmC,EACpC,MAAM,mBAAmB,CAAC;AAE3B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEpD,6EAA6E;AAC7E,MAAM,WAAW,gBAAgB;IAC/B,wCAAwC;IACxC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,0DAA0D;IAC1D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,8EAA8E;IAC9E,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,kCAAkC;IACjD;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAClD;;;;;;OAMG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;CACjF;AA2MD;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,mCAAmC,EAC3C,KAAK,EAAE,kCAAkC,GACxC,YAAY,CAwBd"}

package/dist/adapter/finders/scenes-from-entrypoint-selection.js

@@ -0,0 +1,226 @@
+/**
+ * FINDER — scenes from the entrypoint's active-scene selection.
+ *
+ * ARCHITECTURE-CORE §The editor protocol, "Zero inference": discovery may be a
+ * LIBRARY, and this is one. It only ever runs because an adapter SELECTED it
+ * (`{ finder: 'scenesFromEntrypointSelection', … }`); the engine never runs a
+ * finder nobody selected, which `packages/engine/test/finder-import-boundary.test.ts`
+ * enforces mechanically rather than by policy.
+ *
+ * Why the ENTRYPOINT and not a folder: it is a LOAD-BEARING source — a
+ * reference the game itself executes. The review test is "would the game break
+ * if this fact lied?", and here it would: change the entrypoint's selection
+ * table and the game changes with it. A `src/scenes/` convention can drift
+ * silently; this cannot.
+ *
+ * Two answers, and the difference is declared rather than sniffed:
+ *   - the adapter names a `selection` identifier ⇒ read that module-level
+ *     table and answer one entry per key, each reachable through it;
+ *   - the adapter names none ⇒ the entrypoint mounts ONE composition, and the
+ *     answer is the single-scene DEGENERATE table: the region's own
+ *     composition, opened by mounting the region.
+ *
+ * ON `typescript`: this module parses the entrypoint's own TSX with the
+ * TypeScript compiler API — the same parser `packages/editor/src/ui-source/
+ * oid-transform.ts` and `packages/editor/src/asset-workflow/project-content.ts`
+ * already use for exactly this kind of question (vgai has `typescript`; it does
+ * NOT have @babel/*). It is a HOST-SIDE-ONLY dependency: finders are importable
+ * only by the adapter loader, `adapter-module.ts` imports nothing from this
+ * directory, and a game's `vgai.adapter.ts` therefore never pulls a parser into
+ * its own bundle.
+ */
+import ts from 'typescript';
+import { EXPORTED_COMPOSITION_REGIONS } from '../adapter-module';
+/** Strip the directory and extension from a project-relative path. */
+function basename(path) {
+    const file = path.replaceAll('\\', '/').split('/').pop() ?? path;
+    return file.replace(/\.[jt]sx?$/, '');
+}
+function parse(path, source) {
+    return ts.createSourceFile(path, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+}
+/**
+ * The name the module's own default export carries — the game's own word for
+ * this composition, so the editor's tab reads `World`, not `world.tsx`.
+ * `undefined` when the default export is anonymous or absent.
+ */
+function defaultExportName(sf) {
+    for (const statement of sf.statements) {
+        if (ts.isExportAssignment(statement) && !statement.isExportEquals) {
+            const expression = statement.expression;
+            if (ts.isIdentifier(expression))
+                return expression.text;
+            continue;
+        }
+        const modifiers = ts.canHaveModifiers(statement) ? ts.getModifiers(statement) : undefined;
+        const isDefault = modifiers?.some((m) => m.kind === ts.SyntaxKind.DefaultKeyword);
+        if (!isDefault)
+            continue;
+        if (ts.isFunctionDeclaration(statement) || ts.isClassDeclaration(statement)) {
+            return statement.name?.text;
+        }
+    }
+    return undefined;
+}
+function recordClauseBindings(clause, specifier, bindings) {
+    if (clause.name)
+        bindings.set(clause.name.text, { specifier });
+    const named = clause.namedBindings;
+    if (!named || !ts.isNamedImports(named))
+        return;
+    for (const element of named.elements) {
+        bindings.set(element.name.text, {
+            specifier,
+            exported: (element.propertyName ?? element.name).text,
+        });
+    }
+}
+function importedBindings(sf) {
+    const bindings = new Map();
+    for (const statement of sf.statements) {
+        if (!ts.isImportDeclaration(statement) || !statement.importClause)
+            continue;
+        if (!ts.isStringLiteral(statement.moduleSpecifier))
+            continue;
+        recordClauseBindings(statement.importClause, statement.moduleSpecifier.text, bindings);
+    }
+    return bindings;
+}
+/** The module-level `const <name> = { … }` initializer, if there is one. */
+function selectionTable(sf, name) {
+    for (const statement of sf.statements) {
+        if (!ts.isVariableStatement(statement))
+            continue;
+        for (const declaration of statement.declarationList.declarations) {
+            if (!ts.isIdentifier(declaration.name) || declaration.name.text !== name)
+                continue;
+            const initializer = declaration.initializer;
+            if (initializer && ts.isObjectLiteralExpression(initializer))
+                return initializer;
+        }
+    }
+    return undefined;
+}
+function propertyKey(property) {
+    const name = property.name;
+    if (!name)
+        return undefined;
+    if (ts.isIdentifier(name) || ts.isStringLiteral(name))
+        return name.text;
+    return undefined;
+}
+/** The identifier a selection entry's value names, if it names one at all. */
+function propertyIdentifier(property) {
+    if (ts.isShorthandPropertyAssignment(property))
+        return property.name.text;
+    if (ts.isPropertyAssignment(property) && ts.isIdentifier(property.initializer)) {
+        return property.initializer.text;
+    }
+    return undefined;
+}
+function sourceFor(binding, fromPath, resolveModule) {
+    if (!binding || !resolveModule)
+        return undefined;
+    const path = resolveModule(binding.specifier, fromPath);
+    if (!path)
+        return undefined;
+    return binding.exported === undefined ? { path } : { path, export: binding.exported };
+}
+/**
+ * Which entrypoints this selection targets.
+ *
+ * The RULE form is every exported-composition region that is not a declared
+ * DEV layer. Reading `dev` is reading the manifest's own declaration — the dev
+ * GUI is edit-time chrome, not authorable game content — never a name
+ * heuristic. A named region with no matching entrypoint becomes a note, not a
+ * silent omission.
+ */
+function targetedEntrypoints(params, entrypoints, notes) {
+    if (params.regions === EXPORTED_COMPOSITION_REGIONS) {
+        return entrypoints.filter((entrypoint) => !entrypoint.dev);
+    }
+    const found = [];
+    for (const regionId of params.regions) {
+        const match = entrypoints.find((entry) => entry.regionId === regionId);
+        if (match)
+            found.push(match);
+        else {
+            notes.push(`scenesFromEntrypointSelection: region "${regionId}" is selected but the project ` +
+                'declares no root with that id and an entry.');
+        }
+    }
+    return found;
+}
+/** 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, sf) {
+    return {
+        id: entrypoint.regionId,
+        label: defaultExportName(sf) ?? basename(entrypoint.path),
+        kind: 'scene',
+        region: entrypoint.regionId,
+        authorable: true,
+        reach: { kind: 'root-mount' },
+        source: { path: entrypoint.path },
+        finder: 'scenesFromEntrypointSelection',
+    };
+}
+/** One entry per key of the entrypoint's own selection table. */
+function selectionEntries(entrypoint, sf, selection, resolveModule, notes) {
+    const table = selectionTable(sf, selection);
+    if (!table) {
+        notes.push(`scenesFromEntrypointSelection: ${entrypoint.path} declares no module-level ` +
+            `\`const ${selection} = { … }\` selection table. Nothing is assumed in its ` +
+            'place — fix the adapter’s `selection` or the entrypoint.');
+        return [];
+    }
+    const bindings = importedBindings(sf);
+    const entries = [];
+    for (const property of table.properties) {
+        const key = propertyKey(property);
+        if (key === undefined) {
+            notes.push(`scenesFromEntrypointSelection: ${entrypoint.path}'s \`${selection}\` has an ` +
+                'entry whose key is computed, so it cannot be named statically.');
+            continue;
+        }
+        const identifier = propertyIdentifier(property);
+        const source = sourceFor(identifier ? bindings.get(identifier) : undefined, entrypoint.path, resolveModule);
+        entries.push({
+            id: key,
+            label: identifier ?? key,
+            kind: 'scene',
+            region: entrypoint.regionId,
+            authorable: true,
+            reach: { kind: 'entrypoint-selection', selection, key },
+            ...(source ? { source } : {}),
+            finder: 'scenesFromEntrypointSelection',
+        });
+    }
+    return entries;
+}
+/**
+ * Answer the scene table this finder's selection describes.
+ *
+ * Pure: every input is passed in, nothing is read from disk, and an
+ * unanswerable question becomes a NOTE rather than a fabricated entry.
+ */
+export function scenesFromEntrypointSelection(params, input) {
+    const notes = [];
+    const entries = [];
+    for (const entrypoint of targetedEntrypoints(params, input.entrypoints, notes)) {
+        if (entrypoint.source === null) {
+            notes.push(`scenesFromEntrypointSelection: could not read ${entrypoint.path} (region ` +
+                `"${entrypoint.regionId}"), so its scenes are unknown — not empty.`);
+            continue;
+        }
+        const sf = parse(entrypoint.path, entrypoint.source);
+        entries.push(...(params.selection === undefined
+            ? [degenerateEntry(entrypoint, sf)]
+            : selectionEntries(entrypoint, sf, params.selection, input.resolveModule, notes)));
+    }
+    // One candidate settles the default; two or more is a choice, and a choice
+    // belongs to the adapter author.
+    const only = entries.length === 1 ? entries[0] : undefined;
+    return only ? { entries, default: only.id, notes } : { entries, notes };
+}

package/dist/adapter/first-party-systems.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"first-party-systems.d.ts","sourceRoot":"","sources":["../../src/adapter/first-party-systems.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAE,YAAY,IAAI,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtE,OAAO,KAAK,EACV,YAAY,EAIZ,iBAAiB,EAElB,MAAM,kBAAkB,CAAC;AAmC1B,+EAA+E;AAC/E,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI,CAI9D;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,SAAS,GAAG,YAAY,CAoIvE;AAED;;gEAEgE;AAChE,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,cAAc,GAAG,iBAAiB,CAS9E"}
+{"version":3,"file":"first-party-systems.d.ts","sourceRoot":"","sources":["../../src/adapter/first-party-systems.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAE,YAAY,IAAI,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtE,OAAO,KAAK,EACV,YAAY,EAKZ,iBAAiB,EAElB,MAAM,kBAAkB,CAAC;AAmC1B,+EAA+E;AAC/E,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI,CAI9D;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,SAAS,GAAG,YAAY,CAiKvE;AAED;;gEAEgE;AAChE,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,cAAc,GAAG,iBAAiB,CAS9E"}

package/dist/adapter/first-party-systems.js

@@ -177,6 +177,35 @@ export function createAudioSystemAdapter(audio) {
             liveMeterHandles.add(handle);
             return handle;
         },
+        /** Native Web Audio tap used by the editor's gameplay recorder. It is a
+         * sink beside the speakers, never an insert, so recording cannot change
+         * what the player hears. */
+        acquireRecordingStream() {
+            const recordingContext = nativeAudioContext(audio);
+            if (!recordingContext ||
+                typeof recordingContext.createMediaStreamDestination !== 'function') {
+                return null;
+            }
+            const destination = recordingContext.createMediaStreamDestination();
+            audio.masterGain.connect(destination);
+            let disposed = false;
+            return {
+                stream: destination.stream,
+                dispose() {
+                    if (disposed)
+                        return;
+                    disposed = true;
+                    try {
+                        audio.masterGain.disconnect(destination);
+                    }
+                    catch {
+                        // The world/context may already have been torn down.
+                    }
+                    for (const track of destination.stream.getTracks())
+                        track.stop();
+                },
+            };
+        },
     };
     meterHandlesByAdapter.set(adapter, liveMeterHandles);
     return adapter;