@vgai/engine 0.5.14 → 0.5.16

package/dist/adapter/adapter-module.js

@@ -62,6 +62,18 @@ export const NATIVE_REGION_BASIS = Object.freeze({
     up: 'y',
     groundHeight: 0,
 });
+const AdapterRegionMountSchema = z
+    .object({
+    surface: z
+        .enum(['three', 'canvas', 'dom'])
+        .describe('An additional surface this root mounts, beside the manifest root’s own adapter'),
+    include: z
+        .array(z.string().min(1))
+        .min(1)
+        .describe('Project-relative globs (`**`, `*`, `?`) naming the source files that render on this ' +
+        'additional surface'),
+})
+    .strict();
 const AdapterRegionBasisSchema = z
     .object({
     up: z.enum(['y', 'z']).describe('World axis pointing away from the ground'),
@@ -93,12 +105,62 @@ const AdapterRegionSchema = z
         .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'),
+    mounts: z
+        .array(AdapterRegionMountSchema)
+        .min(1)
+        .optional()
+        .describe('Surfaces this root mounts BESIDE its own adapter, each with the files that render on ' +
+        'them; with `surface`, the root’s full mounted surface set'),
 })
     .strict();
 const RegionBindingSchema = z.union([
     z.literal('manifest-roots'),
     z.array(AdapterRegionSchema).min(1),
 ]);
+const AdapterRegionOverlaySchema = z
+    .object({
+    include: z
+        .array(z.string().min(1))
+        .min(1)
+        .optional()
+        .describe('Project-relative globs (`**`, `*`, `?`) naming source files this derived region owns, ' +
+        'for files no root entry’s import closure reaches; a declared include wins over reach'),
+    mounts: z
+        .array(AdapterRegionMountSchema)
+        .min(1)
+        .optional()
+        .describe('Surfaces this root mounts BESIDE its own adapter, each with the files that render on ' +
+        'them; with the derived region’s own surface, the root’s full mounted surface set'),
+})
+    .strict()
+    .refine((value) => value.include !== undefined || value.mounts !== undefined, {
+    message: 'regionIncludes entry declares neither `include` nor `mounts` — an empty overlay states ' +
+        'nothing the derivation did not already say. Remove it, or name the files it owns.',
+});
+/**
+ * PARAMETERS FOR THE RULE, keyed by manifest root id (decision, 2026-08-17;
+ * ARCHITECTURE-CORE §The editor protocol, "Declared includes LAYER onto the
+ * manifest-roots rule").
+ *
+ * The finder-selection shape, one level up: `regions: 'manifest-roots'` SELECTS
+ * the mechanical derivation, and this table DECLARES the per-region parameters
+ * it cannot derive. The two compose — {@link regionsFromManifestRoots} merges
+ * them — so a first-party project states one include without hand-writing its
+ * whole region table, and adding a root still grows the table for free.
+ *
+ * Illegal beside an explicit `regions` LIST, and rejected by name: that form is
+ * the full REPLACEMENT, and its entries carry `include`/`mounts` themselves.
+ * Two homes for one fact is how a declaration goes stale in one of them.
+ *
+ * MEASURED BASIS (PR #2281, verified twice): the region binding was
+ * replace-only, so no `nativeAdapter()` project could declare a single include
+ * without restating every region — which is what blocked the source-text R3F
+ * floor's retirement across the five shipped 3D projects.
+ */
+const RegionIncludesSchema = z
+    .record(z.string().min(1), AdapterRegionOverlaySchema)
+    .describe('Per-region parameters for the `manifest-roots` rule, keyed by manifest root id: the ' +
+    '`include` globs and `mounts` surfaces the mechanical derivation cannot produce');
 /**
  * The MECHANICAL derivation behind the `'manifest-roots'` rule: one region per
  * declared root, its surface and adapter identity read straight off the
@@ -107,13 +169,20 @@ const RegionBindingSchema = z.union([
  *
  * 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                          |
+ * | root `adapter`        | projector | dialect       | anchors                                              |
+ * |-----------------------|-----------|---------------|------------------------------------------------------|
+ * | `three`               | `three`   | `r3f`         | source-prop, source-structure, construction-literal  |
+ * | `canvas`              | `pixi`    | `pixi-react`  | source-prop, source-structure, construction-literal  |
+ * | `dom`                 | `dom`     | `jsx`         | source-prop, source-structure                        |
+ * | `{module,surface}`    | (surface) | `null`        | live-only                                            |
+ * | `{ingest,surface}`    | (surface) | `null`        | live-only                                            |
+ *
+ * `source-structure` rides with every first-party dialect because all three
+ * write through the SAME structural door (`/__ui-source/struct`) — a region
+ * that can rewrite a JSX attribute in a file can rewrite that file's element
+ * tree. It is listed separately rather than folded into `source-prop` because
+ * they are different doors: a lane could lose one and keep the other, and the
+ * matrix has to be able to say so.
  *
  * 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
@@ -123,46 +192,78 @@ const RegionBindingSchema = z.union([
  * 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.
+ *
+ * It DERIVES no {@link AdapterRegion.include} and no {@link AdapterRegion.mounts},
+ * and there is no derivation that could: the manifest states ONE adapter per
+ * root and names only its entry, so a root's extra owned files and its second
+ * mounted surface are facts only the game can state. It states them as
+ * `regionIncludes` PARAMETERS, which this function merges onto the region it
+ * derives for that root — the rule stays selected, the parameters are declared
+ * (ARCHITECTURE-CORE §The editor protocol, "Declared includes LAYER onto the
+ * manifest-roots rule"). A key naming no declared root merges onto nothing;
+ * the LOADER reports that, because only it can see both sides.
  */
-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,
-            };
-        }
+export function regionsFromManifestRoots(roots, regionIncludes = {}) {
+    return roots.map((root) => ({
+        ...derivedRegion(root),
+        ...overlayOf(regionIncludes[root.id]),
+    }));
+}
+/** The declared half of a merged region — omitted keys leave the derived
+ *  region untouched, so an overlay can only ADD what the rule cannot derive. */
+function overlayOf(overlay) {
+    if (!overlay)
+        return {};
+    return {
+        ...(overlay.include ? { include: overlay.include } : {}),
+        ...(overlay.mounts ? { mounts: overlay.mounts } : {}),
+    };
+}
+/** Region ids an overlay names that no declared root answers to. A typo here
+ *  would otherwise be a declaration that silently does nothing, which is the
+ *  failure class the whole declaration lane exists to end. */
+export function unmatchedRegionIncludeIds(roots, regionIncludes) {
+    const declared = new Set(roots.map((root) => root.id));
+    return Object.keys(regionIncludes).filter((id) => !declared.has(id));
+}
+/** One root's region, before any declared parameters are merged onto it. */
+function derivedRegion(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: surface === 'three' ? 'r3f' : 'pixi-react',
-            anchors: ['source-prop', 'construction-literal'],
+            dialect: null,
+            anchors: ['live-only'],
             basis,
         };
-    });
+    }
+    if (surface === 'dom') {
+        return {
+            id: root.id,
+            surface,
+            dev,
+            projector,
+            dialect: 'jsx',
+            anchors: ['source-prop', 'source-structure'],
+            basis,
+        };
+    }
+    return {
+        id: root.id,
+        surface,
+        dev,
+        projector,
+        dialect: surface === 'three' ? 'r3f' : 'pixi-react',
+        anchors: ['source-prop', 'source-structure', 'construction-literal'],
+        basis,
+    };
 }
 // ---------------------------------------------------------------------------
 // Finder selections
@@ -207,9 +308,11 @@ const SceneReachSchema = z.union([
         kind: z.literal('entrypoint-selection'),
         selection: z.string().min(1),
         key: z.string().min(1),
+        active: z.boolean().optional(),
     })
         .strict(),
     z.object({ kind: z.literal('story'), storyId: z.string().min(1) }).strict(),
+    z.object({ kind: z.literal('game-contract'), sceneId: z.string().min(1) }).strict(),
     z.object({ kind: z.literal('none'), reason: z.string().min(1) }).strict(),
 ]);
 const SceneSourceSchema = z
@@ -224,6 +327,7 @@ const SceneEntrySchema = z
     authorable: z.boolean(),
     reach: SceneReachSchema,
     source: SceneSourceSchema.optional(),
+    isolationSetup: SceneSourceSchema.optional(),
     finder: z.enum(FINDER_NAMES).optional(),
 })
     .strict();
@@ -234,24 +338,100 @@ const AdapterSceneTableSchema = z
     default: z.string().min(1).optional(),
 })
     .strict();
+// ---------------------------------------------------------------------------
+// Observation
+// ---------------------------------------------------------------------------
+/**
+ * The two faces a declaration projects onto. They are exactly the two
+ * `DebugAdapter` halves (`adapter/system-adapter.ts`): `state` becomes a
+ * provider (`providers()` / `state(name)`), `command` becomes a verb
+ * (`commands()` / `invoke(name, args)`). There is deliberately no third kind —
+ * see {@link OBSERVATION_KIND_REFUSAL}.
+ */
+export const OBSERVATION_KINDS = ['command', 'state'];
+/**
+ * Why a declaration may not name a `SystemAdapters` slot here.
+ *
+ * A game's system slots are already declared through the game contract's own
+ * `systemAdapters` carrier (`adapter/ingest/game-contract.ts`), which validates
+ * each slot per-surface and reports a malformed one BY NAME
+ * (`contract-system-adapters.ts`). A second door onto the same slots is exactly
+ * the two-declarations-one-slot problem `game-contract.ts` records for `debug`,
+ * where it says outright that a second door "would let a game declare two
+ * different debug planes with no rule for which wins".
+ */
+const OBSERVATION_KIND_REFUSAL = "observation.kind must be 'command' or 'state' — the two DebugAdapter faces a declaration " +
+    'projects onto. A SystemAdapters slot is declared through the game contract’s `systemAdapters` ' +
+    'carrier, which validates it per-surface; declaring one here would be a second door onto the ' +
+    'same slot with no rule for which wins.';
 const ObservationDeclarationSchema = z
     .object({
     id: z.string().min(1),
-    kind: z.enum(['system', 'command', 'state']),
+    kind: z.enum(OBSERVATION_KINDS, { error: () => OBSERVATION_KIND_REFUSAL }),
+    description: z.string().min(1).optional(),
+    locus: z.enum(['client', 'server']).optional(),
     answer: z
         .custom((value) => typeof value === 'function', {
         message: 'observation.answer must be a function evaluated against the mounted game',
     })
         .optional(),
+})
+    .strict()
+    .refine((value) => value.kind === 'command' || value.locus === undefined, {
+    path: ['locus'],
+    message: 'observation.locus is valid only for a command declaration',
+});
+// ---------------------------------------------------------------------------
+// Native input
+// ---------------------------------------------------------------------------
+/** The action value shapes the session input door already speaks. */
+export const ADAPTER_INPUT_VALUE_TYPES = [
+    'digital',
+    'scalar',
+    'vector2',
+    'pointerDelta',
+    'pointerPosition',
+];
+const AdapterInputBindingSchema = z
+    .object({
+    root: z.string().min(1),
+    actions: z.custom((value) => typeof value === 'function', {
+        message: 'input.actions must be a function returning the app-owned action vocabulary',
+    }),
+    set: z.custom((value) => typeof value === 'function', {
+        message: 'input.set must be a function writing the app-owned input store',
+    }),
+    clear: z.custom((value) => typeof value === 'function', {
+        message: 'input.clear must be a function releasing app-owned virtual actions',
+    }),
 })
     .strict();
+/**
+ * Why the two forms may not be combined, said in the error a game's author
+ * reads. An explicit region list REPLACES the derivation and its entries carry
+ * `include`/`mounts` themselves; layering a second table over it would put one
+ * fact in two homes, with no rule for which wins.
+ */
+const REGION_INCLUDES_WITH_LIST_REFUSAL = '`regionIncludes` states parameters for the `manifest-roots` RULE, so it cannot be paired ' +
+    'with an explicit `regions` list — that form is the full replacement, and each entry carries ' +
+    'its own `include`/`mounts`. Move these globs onto the matching `regions[]` entry, or drop the ' +
+    'list and let the derivation run.';
 export const AdapterDefinitionSchema = z
     .object({
     regions: RegionBindingSchema.optional(),
+    regionIncludes: RegionIncludesSchema.optional(),
     scenes: AdapterSceneTableSchema.optional(),
     observation: z.array(ObservationDeclarationSchema).optional(),
+    input: AdapterInputBindingSchema.optional(),
 })
-    .strict();
+    .strict()
+    // An EMPTY table beside a list is fine and must stay fine: `defineAdapter`
+    // publishes `regionIncludes: {}` on every definition, and its output is
+    // parsed a second time by the host's loader — a refusal on the key's mere
+    // presence would reject the module's own valid output on the round trip.
+    .refine((value) => value.regionIncludes === undefined ||
+    Object.keys(value.regionIncludes).length === 0 ||
+    !Array.isArray(value.regions), { message: REGION_INCLUDES_WITH_LIST_REFUSAL });
 /**
  * Validate and freeze a game's binding table.
  *
@@ -270,8 +450,10 @@ export function defineAdapter(input = {}) {
     }
     return Object.freeze({
         regions: input.regions ?? 'manifest-roots',
+        regionIncludes: Object.freeze({ ...(input.regionIncludes ?? {}) }),
         scenes: Object.freeze({ ...(input.scenes ?? {}) }),
         observation: Object.freeze([...(input.observation ?? [])]),
+        ...(input.input ? { input: input.input } : {}),
     });
 }
 /**
@@ -284,6 +466,7 @@ export function defineAdapter(input = {}) {
 export function nativeAdapter(options = {}) {
     return defineAdapter({
         regions: 'manifest-roots',
+        ...(options.regionIncludes ? { regionIncludes: options.regionIncludes } : {}),
         scenes: {
             ...(options.scenes ? { entries: options.scenes } : {}),
             find: [
@@ -291,7 +474,6 @@ export function nativeAdapter(options = {}) {
                 { finder: 'prefabsFromStories' },
             ],
         },
-        ...(options.observation ? { observation: options.observation } : {}),
     });
 }
 /**