@vgai/engine 0.5.13 → 0.5.14

package/dist/adapter/adapter-module.js

@@ -0,0 +1,308 @@
+/**
+ * `vgai.adapter.ts` — THE ADAPTER MODULE CONTRACT.
+ *
+ * ARCHITECTURE-CORE §The editor protocol, "The adapter is the game's own
+ * module": the editor is a universal CLIENT of a fixed protocol and every game
+ * supplies a SERVER — its adapter. That adapter is the game's OWN module,
+ * `vgai.adapter.ts`, sitting beside `vgai.project.json`, default-exporting
+ * {@link defineAdapter}'s result.
+ *
+ * It is CODE (bindings are expressions — a scene entry may carry a closure the
+ * host evaluates against the mounted game) with a CONFIG's discipline: the top
+ * level is a STATICALLY EVALUABLE BINDING TABLE, readable without booting the
+ * game. Concretely, that is the split this module enforces:
+ *
+ *   - the TABLE SHAPE — regions, the scene table, observation declarations —
+ *     is plain data, validated by {@link AdapterDefinitionSchema} the moment
+ *     the module is evaluated. `.strict()` throughout: an unrecognized key is
+ *     an error naming the key, never a silent pass-through (CLAUDE.md,
+ *     "Unknown input must REJECT LOUDLY").
+ *   - individual FIELDS may be closures, evaluated lazily against the mounted
+ *     game (`ObservationDeclaration.answer`). A closure is never required to
+ *     read the table.
+ *
+ * **Zero inference.** A binding is a DECLARATION or a finder SELECTION the
+ * adapter makes — never something the host sniffs out. Finder algorithms
+ * (scenes from an entrypoint selection, prefabs from story registrations, …)
+ * ship host-side under `adapter/finders/`, and this module names them by
+ * SELECTION only ({@link FinderSelection}). That is deliberate and load-bearing
+ * twice over:
+ *   1. the engine never runs a finder nobody selected — enforced mechanically
+ *      by `packages/engine/test/finder-import-boundary.test.ts`, whose only
+ *      sanctioned importer of the finder namespace is the editor's adapter
+ *      loader;
+ *   2. this module therefore imports NOTHING from `adapter/finders/`, so a
+ *      game's `vgai.adapter.ts` pulls no finder implementation (and no source
+ *      parser) into its own bundle. The dependency runs one way: finders
+ *      import their parameter types from HERE.
+ *
+ * The manifest keeps only what must be readable without evaluating any module
+ * — identity, roots, boot mode, `server.room`. Everything that binds behavior
+ * is the adapter's. This wave adds NO manifest field.
+ */
+import { z } from 'zod';
+import { WRITE_ANCHOR_KINDS } from './authoring';
+// ---------------------------------------------------------------------------
+// Regions
+// ---------------------------------------------------------------------------
+/**
+ * The projector serving a surface — one per surface, host-owned
+ * (ARCHITECTURE-CORE: "Projection — nodes, stable identity, bounds, picking …
+ * one projector per surface"). Named, never imported: the adapter states WHICH
+ * library serves the region; the host binds the implementation.
+ */
+export const PROJECTOR_NAMES = ['three', 'pixi', 'dom'];
+/**
+ * The NATIVE basis — what {@link regionsFromManifestRoots} emits and what a
+ * region that declares none is read as. +Y up, ground at 0: three.js' own
+ * convention, which every first-party root is authored in. Stated as a value so
+ * "the default" has one home instead of a copy at each reader.
+ */
+export const NATIVE_REGION_BASIS = Object.freeze({
+    up: 'y',
+    groundHeight: 0,
+});
+const AdapterRegionBasisSchema = z
+    .object({
+    up: z.enum(['y', 'z']).describe('World axis pointing away from the ground'),
+    groundHeight: z.number().describe('Ground offset along `up`, in world units'),
+})
+    .strict();
+const AdapterRegionSchema = z
+    .object({
+    id: z.string().min(1).describe('Manifest root id this region grades'),
+    surface: z.enum(['three', 'canvas', 'dom']).describe('Render surface the host hands this root'),
+    dev: z
+        .boolean()
+        .describe("true = this region grades the game's own dev layer, not shipped content (the " +
+        "manifest root's `dev: true`)"),
+    projector: z.enum(PROJECTOR_NAMES).describe('Projection library serving this surface, by name'),
+    dialect: z
+        .string()
+        .min(1)
+        .nullable()
+        .describe('Dialect writer serving this region, by name; null states outright that the host writes ' +
+        "no source here (the region's truth is the game's own code)"),
+    anchors: z
+        .array(z.enum(WRITE_ANCHOR_KINDS))
+        .describe('Anchor kinds this region’s writer serves'),
+    basis: AdapterRegionBasisSchema.optional().describe('World basis (up axis + ground height); omit for the native +Y / 0 default'),
+    include: z
+        .array(z.string().min(1))
+        .min(1)
+        .optional()
+        .describe('Project-relative globs (`**`, `*`, `?`) naming source files this region owns, for files ' +
+        'no root entry’s import closure reaches; a declared include wins over reach'),
+})
+    .strict();
+const RegionBindingSchema = z.union([
+    z.literal('manifest-roots'),
+    z.array(AdapterRegionSchema).min(1),
+]);
+/**
+ * The MECHANICAL derivation behind the `'manifest-roots'` rule: one region per
+ * declared root, its surface and adapter identity read straight off the
+ * RESOLVED manifest (`@engine/manifest/load` already decided both — this never
+ * re-derives them).
+ *
+ * The per-surface library table below is an ENGINE fact, stated once:
+ *
+ * | root `adapter`        | projector | dialect       | anchors                            |
+ * |-----------------------|-----------|---------------|------------------------------------|
+ * | `three`               | `three`   | `r3f`         | source-prop, construction-literal   |
+ * | `canvas`              | `pixi`    | `pixi-react`  | source-prop, construction-literal   |
+ * | `dom`                 | `dom`     | `jsx`         | source-prop                        |
+ * | `{module,surface}`    | (surface) | `null`        | live-only                          |
+ * | `{ingest,surface}`    | (surface) | `null`        | live-only                          |
+ *
+ * A module/ingest root's truth is the game's own source, which no first-party
+ * dialect writer authors — so it declares `live-only` rather than implying a
+ * write path it does not have. That is a red cell and therefore a work order,
+ * which is the point of stating it.
+ *
+ * Every derived region carries {@link NATIVE_REGION_BASIS} outright, so the
+ * editor's ground plane READS a declaration on the native path too — the
+ * default is published, never assumed at the read site.
+ */
+export function regionsFromManifestRoots(roots) {
+    return roots.map((root) => {
+        const surface = root.surface;
+        const dev = root.dev;
+        const firstParty = root.adapter.type === 'builtin';
+        const projector = surface === 'canvas' ? 'pixi' : surface;
+        const basis = NATIVE_REGION_BASIS;
+        if (!firstParty) {
+            return {
+                id: root.id,
+                surface,
+                dev,
+                projector,
+                dialect: null,
+                anchors: ['live-only'],
+                basis,
+            };
+        }
+        if (surface === 'dom') {
+            return {
+                id: root.id,
+                surface,
+                dev,
+                projector,
+                dialect: 'jsx',
+                anchors: ['source-prop'],
+                basis,
+            };
+        }
+        return {
+            id: root.id,
+            surface,
+            dev,
+            projector,
+            dialect: surface === 'three' ? 'r3f' : 'pixi-react',
+            anchors: ['source-prop', 'construction-literal'],
+            basis,
+        };
+    });
+}
+// ---------------------------------------------------------------------------
+// Finder selections
+// ---------------------------------------------------------------------------
+/**
+ * The rule form of a finder's region targeting: every region the host mounts
+ * from an exported composition (a root with an `entry`) that is not a declared
+ * DEV layer. A dev root is the game's own dev GUI — the manifest already says
+ * so (`dev: true`), so skipping it reads a declaration rather than guessing.
+ */
+export const EXPORTED_COMPOSITION_REGIONS = 'exported-composition-regions';
+/** The finder names, as a value — what the loader's dispatcher switches on. */
+export const FINDER_NAMES = ['scenesFromEntrypointSelection', 'prefabsFromStories'];
+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();
+const FinderSelectionSchema = z.union([
+    ScenesFromEntrypointSelectionSchema,
+    PrefabsFromStoriesSchema,
+]);
+const SceneReachSchema = z.union([
+    z.object({ kind: z.literal('root-mount') }).strict(),
+    z
+        .object({
+        kind: z.literal('entrypoint-selection'),
+        selection: z.string().min(1),
+        key: z.string().min(1),
+    })
+        .strict(),
+    z.object({ kind: z.literal('story'), storyId: z.string().min(1) }).strict(),
+    z.object({ kind: z.literal('none'), reason: z.string().min(1) }).strict(),
+]);
+const SceneSourceSchema = z
+    .object({ path: z.string().min(1), export: z.string().min(1).optional() })
+    .strict();
+const SceneEntrySchema = z
+    .object({
+    id: z.string().min(1),
+    label: z.string().min(1),
+    kind: z.enum(['scene', 'prefab']),
+    region: z.string().min(1).nullable(),
+    authorable: z.boolean(),
+    reach: SceneReachSchema,
+    source: SceneSourceSchema.optional(),
+    finder: z.enum(FINDER_NAMES).optional(),
+})
+    .strict();
+const AdapterSceneTableSchema = z
+    .object({
+    entries: z.array(SceneEntrySchema).optional(),
+    find: z.array(FinderSelectionSchema).optional(),
+    default: z.string().min(1).optional(),
+})
+    .strict();
+const ObservationDeclarationSchema = z
+    .object({
+    id: z.string().min(1),
+    kind: z.enum(['system', 'command', 'state']),
+    answer: z
+        .custom((value) => typeof value === 'function', {
+        message: 'observation.answer must be a function evaluated against the mounted game',
+    })
+        .optional(),
+})
+    .strict();
+export const AdapterDefinitionSchema = z
+    .object({
+    regions: RegionBindingSchema.optional(),
+    scenes: AdapterSceneTableSchema.optional(),
+    observation: z.array(ObservationDeclarationSchema).optional(),
+})
+    .strict();
+/**
+ * Validate and freeze a game's binding table.
+ *
+ * Called TWICE by design and with one schema: once here, in the game's own
+ * module, so a malformed table fails at the author's own file with the key
+ * named; and once in the host's loader, because the loaded default export is
+ * untrusted input crossing a module boundary. Two call sites, one rule — not
+ * two ways to say the same thing.
+ */
+export function defineAdapter(input = {}) {
+    const parsed = AdapterDefinitionSchema.safeParse(input);
+    if (!parsed.success) {
+        throw new Error(`vgai.adapter.ts: invalid adapter definition — ${parsed.error.issues
+            .map((issue) => `${issue.path.join('.') || '(root)'}: ${issue.message}`)
+            .join('; ')}`);
+    }
+    return Object.freeze({
+        regions: input.regions ?? 'manifest-roots',
+        scenes: Object.freeze({ ...(input.scenes ?? {}) }),
+        observation: Object.freeze([...(input.observation ?? [])]),
+    });
+}
+/**
+ * THE NATIVE DEFAULT — regions derived mechanically from the manifest's
+ * `roots[]`, and a scene table produced by the two shipped finders. This is
+ * what a first-party project ships (`export default nativeAdapter()`), and it
+ * is also what a project with NO `vgai.adapter.ts` gets: that absence is the
+ * declared native default, not a silent fallback.
+ */
+export function nativeAdapter(options = {}) {
+    return defineAdapter({
+        regions: 'manifest-roots',
+        scenes: {
+            ...(options.scenes ? { entries: options.scenes } : {}),
+            find: [
+                { finder: 'scenesFromEntrypointSelection', regions: EXPORTED_COMPOSITION_REGIONS },
+                { finder: 'prefabsFromStories' },
+            ],
+        },
+        ...(options.observation ? { observation: options.observation } : {}),
+    });
+}
+/**
+ * Parse an untrusted default export (the loaded `vgai.adapter.ts`) into a
+ * definition. Rejects loudly — an unknown key, a bad finder name, a
+ * `selection` paired with the rule form all fail by name.
+ */
+export function parseAdapterDefinition(value) {
+    if (value === null || typeof value !== 'object') {
+        throw new Error('vgai.adapter.ts must default-export defineAdapter({…}) / nativeAdapter() — ' +
+            `got ${value === null ? 'null' : typeof value}`);
+    }
+    return defineAdapter(value);
+}