@vgai/engine 0.5.13 → 0.5.15

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (192) hide show
  1. package/dist/adapter/adapter-module.d.ts +447 -0
  2. package/dist/adapter/adapter-module.d.ts.map +1 -0
  3. package/dist/adapter/adapter-module.js +308 -0
  4. package/dist/adapter/authoring.d.ts +357 -10
  5. package/dist/adapter/authoring.d.ts.map +1 -1
  6. package/dist/adapter/authoring.js +87 -1
  7. package/dist/adapter/constraint.d.ts +9 -3
  8. package/dist/adapter/constraint.d.ts.map +1 -1
  9. package/dist/adapter/finders/finder-result.d.ts +28 -0
  10. package/dist/adapter/finders/finder-result.d.ts.map +1 -0
  11. package/dist/adapter/finders/finder-result.js +10 -0
  12. package/dist/adapter/finders/index.d.ts +38 -0
  13. package/dist/adapter/finders/index.d.ts.map +1 -0
  14. package/dist/adapter/finders/index.js +41 -0
  15. package/dist/adapter/finders/prefabs-from-stories.d.ts +64 -0
  16. package/dist/adapter/finders/prefabs-from-stories.d.ts.map +1 -0
  17. package/dist/adapter/finders/prefabs-from-stories.js +92 -0
  18. package/dist/adapter/finders/scenes-from-entrypoint-selection.d.ts +67 -0
  19. package/dist/adapter/finders/scenes-from-entrypoint-selection.d.ts.map +1 -0
  20. package/dist/adapter/finders/scenes-from-entrypoint-selection.js +226 -0
  21. package/dist/adapter/first-party-systems.d.ts.map +1 -1
  22. package/dist/adapter/first-party-systems.js +29 -0
  23. package/dist/adapter/index.d.ts +7 -3
  24. package/dist/adapter/index.d.ts.map +1 -1
  25. package/dist/adapter/index.js +5 -2
  26. package/dist/adapter/ingest/contract-system-adapters.d.ts +24 -1
  27. package/dist/adapter/ingest/contract-system-adapters.d.ts.map +1 -1
  28. package/dist/adapter/ingest/contract-system-adapters.js +100 -34
  29. package/dist/adapter/ingest/game-contract.d.ts +188 -2
  30. package/dist/adapter/ingest/game-contract.d.ts.map +1 -1
  31. package/dist/adapter/ingest/game-contract.js +107 -0
  32. package/dist/adapter/ingest/mount-readiness.d.ts +84 -0
  33. package/dist/adapter/ingest/mount-readiness.d.ts.map +1 -0
  34. package/dist/adapter/ingest/mount-readiness.js +81 -0
  35. package/dist/adapter/ingest/scene-capture.d.ts +91 -2
  36. package/dist/adapter/ingest/scene-capture.d.ts.map +1 -1
  37. package/dist/adapter/ingest/scene-capture.js +110 -18
  38. package/dist/adapter/ingest/structural-ids.d.ts +11 -5
  39. package/dist/adapter/ingest/structural-ids.d.ts.map +1 -1
  40. package/dist/adapter/ingest/structural-ids.js +18 -9
  41. package/dist/adapter/ingest/upstream-pin.d.ts +4 -2
  42. package/dist/adapter/ingest/upstream-pin.d.ts.map +1 -1
  43. package/dist/adapter/ingest/upstream-pin.js +4 -2
  44. package/dist/adapter/ingest/visible-capture-window.d.ts +116 -0
  45. package/dist/adapter/ingest/visible-capture-window.d.ts.map +1 -0
  46. package/dist/adapter/ingest/visible-capture-window.js +141 -0
  47. package/dist/adapter/loop-gate-report.d.ts +3 -4
  48. package/dist/adapter/loop-gate-report.d.ts.map +1 -1
  49. package/dist/adapter/loop-gate-report.js +3 -4
  50. package/dist/adapter/root-adapter.d.ts +22 -2
  51. package/dist/adapter/root-adapter.d.ts.map +1 -1
  52. package/dist/adapter/setup-three-root-adapter.d.ts.map +1 -1
  53. package/dist/adapter/setup-three-root-adapter.js +15 -0
  54. package/dist/adapter/system-adapter.d.ts +161 -2
  55. package/dist/adapter/system-adapter.d.ts.map +1 -1
  56. package/dist/adapter/system-adapter.js +18 -1
  57. package/dist/animation/camera-ownership.d.ts +4 -2
  58. package/dist/animation/camera-ownership.d.ts.map +1 -1
  59. package/dist/animation/camera-ownership.js +58 -1
  60. package/dist/animation/runtime-inspection.d.ts +70 -0
  61. package/dist/animation/runtime-inspection.d.ts.map +1 -0
  62. package/dist/animation/runtime-inspection.js +25 -0
  63. package/dist/animation/xstate-animation-binding.d.ts +9 -1
  64. package/dist/animation/xstate-animation-binding.d.ts.map +1 -1
  65. package/dist/animation/xstate-animation-binding.js +48 -1
  66. package/dist/asset-formats/material.d.ts +1 -1
  67. package/dist/asset-formats/mesh.d.ts +1 -1
  68. package/dist/asset-formats/particles.d.ts +13 -0
  69. package/dist/asset-formats/particles.d.ts.map +1 -1
  70. package/dist/asset-formats/particles.js +28 -0
  71. package/dist/behavior/xstate-inspection.d.ts +24 -0
  72. package/dist/behavior/xstate-inspection.d.ts.map +1 -0
  73. package/dist/behavior/xstate-inspection.js +25 -0
  74. package/dist/core/game-loop.d.ts +7 -5
  75. package/dist/core/game-loop.d.ts.map +1 -1
  76. package/dist/core/game-loop.js +39 -18
  77. package/dist/core/types.d.ts +11 -12
  78. package/dist/core/types.d.ts.map +1 -1
  79. package/dist/data/data-asset.js +1 -1
  80. package/dist/dev/instruments.d.ts.map +1 -1
  81. package/dist/dev/instruments.js +5 -1
  82. package/dist/dev/render-debug-adapter.d.ts +19 -2
  83. package/dist/dev/render-debug-adapter.d.ts.map +1 -1
  84. package/dist/dev/render-debug-adapter.js +10 -0
  85. package/dist/ecs/user-data.d.ts +10 -2
  86. package/dist/ecs/user-data.d.ts.map +1 -1
  87. package/dist/ecs/user-data.js +6 -2
  88. package/dist/input/binding-identity.d.ts +10 -0
  89. package/dist/input/binding-identity.d.ts.map +1 -0
  90. package/dist/input/binding-identity.js +36 -0
  91. package/dist/input/input-manager.d.ts +18 -185
  92. package/dist/input/input-manager.d.ts.map +1 -1
  93. package/dist/input/input-manager.js +78 -68
  94. package/dist/manifest/load.d.ts +14 -0
  95. package/dist/manifest/load.d.ts.map +1 -1
  96. package/dist/manifest/load.js +6 -1
  97. package/dist/manifest/schema.d.ts +18 -0
  98. package/dist/manifest/schema.d.ts.map +1 -1
  99. package/dist/manifest/schema.js +65 -8
  100. package/dist/pixi/authoring.d.ts +27 -0
  101. package/dist/pixi/authoring.d.ts.map +1 -1
  102. package/dist/pixi/authoring.js +10 -3
  103. package/dist/pixi/index.d.ts +1 -1
  104. package/dist/pixi/index.d.ts.map +1 -1
  105. package/dist/pixi/index.js +1 -1
  106. package/dist/pixi/ingest.d.ts +8 -0
  107. package/dist/pixi/ingest.d.ts.map +1 -1
  108. package/dist/pixi/ingest.js +10 -1
  109. package/dist/pixi/render-pass-bracket.d.ts +56 -0
  110. package/dist/pixi/render-pass-bracket.d.ts.map +1 -0
  111. package/dist/pixi/render-pass-bracket.js +98 -0
  112. package/dist/pixi/scene-capture.d.ts +32 -1
  113. package/dist/pixi/scene-capture.d.ts.map +1 -1
  114. package/dist/pixi/scene-capture.js +21 -9
  115. package/dist/pixi/system-adapters.d.ts +29 -0
  116. package/dist/pixi/system-adapters.d.ts.map +1 -1
  117. package/dist/pixi/system-adapters.js +27 -0
  118. package/dist/render/particles-factory.d.ts +16 -2
  119. package/dist/render/particles-factory.d.ts.map +1 -1
  120. package/dist/render/particles-factory.js +88 -5
  121. package/dist/render/soft-particle-depth.d.ts +149 -0
  122. package/dist/render/soft-particle-depth.d.ts.map +1 -0
  123. package/dist/render/soft-particle-depth.js +305 -0
  124. package/dist/render/voxel-surface.d.ts +117 -0
  125. package/dist/render/voxel-surface.d.ts.map +1 -0
  126. package/dist/render/voxel-surface.js +263 -0
  127. package/dist/runtime/create-runtime.js +7 -0
  128. package/dist/runtime/debug-bridge.d.ts +15 -15
  129. package/dist/runtime/debug-bridge.d.ts.map +1 -1
  130. package/dist/runtime/debug-bridge.js +27 -26
  131. package/dist/runtime/game.d.ts.map +1 -1
  132. package/dist/runtime/game.js +1 -2
  133. package/dist/setup/setup-particles.d.ts.map +1 -1
  134. package/dist/setup/setup-particles.js +9 -0
  135. package/dist/world3d-react/r3f-adapter.d.ts.map +1 -1
  136. package/dist/world3d-react/r3f-adapter.js +42 -3
  137. package/dist/world3d-react/rapier-physics-bridge.d.ts.map +1 -1
  138. package/dist/world3d-react/rapier-physics-bridge.js +201 -11
  139. package/dist-config/config.js.map +1 -1
  140. package/package.json +4 -2
  141. package/schemas/engine-capabilities.json +12 -12
  142. package/schemas/vgai-project.schema.json +42 -3
  143. package/src/adapter/adapter-module.ts +607 -0
  144. package/src/adapter/authoring.ts +440 -10
  145. package/src/adapter/constraint.ts +10 -3
  146. package/src/adapter/finders/finder-result.ts +29 -0
  147. package/src/adapter/finders/index.ts +62 -0
  148. package/src/adapter/finders/prefabs-from-stories.ts +142 -0
  149. package/src/adapter/finders/scenes-from-entrypoint-selection.ts +304 -0
  150. package/src/adapter/first-party-systems.ts +30 -0
  151. package/src/adapter/index.ts +32 -1
  152. package/src/adapter/ingest/contract-system-adapters.ts +116 -32
  153. package/src/adapter/ingest/game-contract.ts +265 -2
  154. package/src/adapter/ingest/mount-readiness.ts +140 -0
  155. package/src/adapter/ingest/scene-capture.ts +199 -22
  156. package/src/adapter/ingest/structural-ids.ts +21 -9
  157. package/src/adapter/ingest/upstream-pin.ts +4 -2
  158. package/src/adapter/ingest/visible-capture-window.ts +213 -0
  159. package/src/adapter/loop-gate-report.ts +3 -4
  160. package/src/adapter/root-adapter.ts +22 -2
  161. package/src/adapter/setup-three-root-adapter.ts +16 -0
  162. package/src/adapter/system-adapter.ts +188 -2
  163. package/src/animation/camera-ownership.ts +68 -3
  164. package/src/animation/runtime-inspection.ts +104 -0
  165. package/src/animation/xstate-animation-binding.ts +53 -1
  166. package/src/asset-formats/particles.ts +31 -0
  167. package/src/behavior/xstate-inspection.ts +51 -0
  168. package/src/core/game-loop.ts +39 -17
  169. package/src/core/types.ts +11 -12
  170. package/src/data/data-asset.ts +1 -1
  171. package/src/dev/instruments.ts +5 -1
  172. package/src/dev/render-debug-adapter.ts +22 -2
  173. package/src/ecs/user-data.ts +10 -2
  174. package/src/input/binding-identity.ts +37 -0
  175. package/src/input/input-manager.ts +93 -68
  176. package/src/manifest/load.ts +23 -2
  177. package/src/manifest/schema.ts +77 -8
  178. package/src/pixi/authoring.ts +37 -5
  179. package/src/pixi/index.ts +2 -0
  180. package/src/pixi/ingest.ts +15 -2
  181. package/src/pixi/render-pass-bracket.ts +117 -0
  182. package/src/pixi/scene-capture.ts +63 -13
  183. package/src/pixi/system-adapters.ts +41 -0
  184. package/src/render/particles-factory.ts +89 -6
  185. package/src/render/soft-particle-depth.ts +336 -0
  186. package/src/render/voxel-surface.ts +358 -0
  187. package/src/runtime/create-runtime.ts +7 -0
  188. package/src/runtime/debug-bridge.ts +32 -31
  189. package/src/runtime/game.ts +1 -2
  190. package/src/setup/setup-particles.ts +9 -0
  191. package/src/world3d-react/r3f-adapter.tsx +48 -2
  192. package/src/world3d-react/rapier-physics-bridge.tsx +249 -11
@@ -0,0 +1,447 @@
1
+ /**
2
+ * `vgai.adapter.ts` — THE ADAPTER MODULE CONTRACT.
3
+ *
4
+ * ARCHITECTURE-CORE §The editor protocol, "The adapter is the game's own
5
+ * module": the editor is a universal CLIENT of a fixed protocol and every game
6
+ * supplies a SERVER — its adapter. That adapter is the game's OWN module,
7
+ * `vgai.adapter.ts`, sitting beside `vgai.project.json`, default-exporting
8
+ * {@link defineAdapter}'s result.
9
+ *
10
+ * It is CODE (bindings are expressions — a scene entry may carry a closure the
11
+ * host evaluates against the mounted game) with a CONFIG's discipline: the top
12
+ * level is a STATICALLY EVALUABLE BINDING TABLE, readable without booting the
13
+ * game. Concretely, that is the split this module enforces:
14
+ *
15
+ * - the TABLE SHAPE — regions, the scene table, observation declarations —
16
+ * is plain data, validated by {@link AdapterDefinitionSchema} the moment
17
+ * the module is evaluated. `.strict()` throughout: an unrecognized key is
18
+ * an error naming the key, never a silent pass-through (CLAUDE.md,
19
+ * "Unknown input must REJECT LOUDLY").
20
+ * - individual FIELDS may be closures, evaluated lazily against the mounted
21
+ * game (`ObservationDeclaration.answer`). A closure is never required to
22
+ * read the table.
23
+ *
24
+ * **Zero inference.** A binding is a DECLARATION or a finder SELECTION the
25
+ * adapter makes — never something the host sniffs out. Finder algorithms
26
+ * (scenes from an entrypoint selection, prefabs from story registrations, …)
27
+ * ship host-side under `adapter/finders/`, and this module names them by
28
+ * SELECTION only ({@link FinderSelection}). That is deliberate and load-bearing
29
+ * twice over:
30
+ * 1. the engine never runs a finder nobody selected — enforced mechanically
31
+ * by `packages/engine/test/finder-import-boundary.test.ts`, whose only
32
+ * sanctioned importer of the finder namespace is the editor's adapter
33
+ * loader;
34
+ * 2. this module therefore imports NOTHING from `adapter/finders/`, so a
35
+ * game's `vgai.adapter.ts` pulls no finder implementation (and no source
36
+ * parser) into its own bundle. The dependency runs one way: finders
37
+ * import their parameter types from HERE.
38
+ *
39
+ * The manifest keeps only what must be readable without evaluating any module
40
+ * — identity, roots, boot mode, `server.room`. Everything that binds behavior
41
+ * is the adapter's. This wave adds NO manifest field.
42
+ */
43
+ import { z } from 'zod';
44
+ import type { ResolvedAdapterRoot } from '../manifest/load';
45
+ import type { AdapterSurface } from './adapter-surface';
46
+ import { type WriteAnchorKind } from './authoring';
47
+ /**
48
+ * The projector serving a surface — one per surface, host-owned
49
+ * (ARCHITECTURE-CORE: "Projection — nodes, stable identity, bounds, picking …
50
+ * one projector per surface"). Named, never imported: the adapter states WHICH
51
+ * library serves the region; the host binds the implementation.
52
+ */
53
+ export declare const PROJECTOR_NAMES: readonly ["three", "pixi", "dom"];
54
+ export type ProjectorName = (typeof PROJECTOR_NAMES)[number];
55
+ /**
56
+ * A region's WORLD BASIS — which axis points up, and where its ground sits.
57
+ *
58
+ * The editor needs a ground plane to place a dropped asset or a probe point on.
59
+ * That plane used to be the constant `y = 0` compiled into `editor-viewport.ts`,
60
+ * which is a guess about the GAME's convention: a Z-up world (the CAD/Blender
61
+ * idiom foreign R3F games routinely carry) got its drops silently projected onto
62
+ * the wrong plane. It is exactly the shape "zero inference" names — a fact the
63
+ * game's author can state, so the fix is a declaration slot rather than a
64
+ * smarter sniff (ARCHITECTURE-CORE §The editor protocol).
65
+ */
66
+ export interface AdapterRegionBasis {
67
+ /** World axis pointing away from the ground. */
68
+ readonly up: 'y' | 'z';
69
+ /** Ground offset along {@link up}, in world units. */
70
+ readonly groundHeight: number;
71
+ }
72
+ /**
73
+ * The NATIVE basis — what {@link regionsFromManifestRoots} emits and what a
74
+ * region that declares none is read as. +Y up, ground at 0: three.js' own
75
+ * convention, which every first-party root is authored in. Stated as a value so
76
+ * "the default" has one home instead of a copy at each reader.
77
+ */
78
+ export declare const NATIVE_REGION_BASIS: AdapterRegionBasis;
79
+ /**
80
+ * One matrix REGION: a root, its surface, and the library selections that
81
+ * serve it. Universality lives at region granularity — which libraries serve a
82
+ * surface is a per-surface ENGINE fact, so a new surface root in an existing
83
+ * game is one manifest line and one derived region, never new adapter code
84
+ * (that is exactly what {@link regionsFromManifestRoots} does).
85
+ */
86
+ export interface AdapterRegion {
87
+ /** The manifest root this region grades. */
88
+ readonly id: string;
89
+ /** What the host hands this root. */
90
+ readonly surface: AdapterSurface;
91
+ /**
92
+ * `true` = this region grades the game's own DEV LAYER (the manifest root's
93
+ * `dev: true`), not shipped game content.
94
+ *
95
+ * Carried here because a dev root occupies the same MEDIUM as the content
96
+ * root beside it — a dev GUI is a `dom` root next to the HUD's `dom` root —
97
+ * and anything that maps a subject to "the region on this surface" would
98
+ * otherwise be choosing between them by array order. A region consumer that
99
+ * means shipped content says so by skipping `dev` regions (the loader's
100
+ * `regionForSurface` does), rather than by guessing which one matched.
101
+ */
102
+ readonly dev: boolean;
103
+ /** Projection library, by name. */
104
+ readonly projector: ProjectorName;
105
+ /**
106
+ * Dialect writer, by name (`r3f`, `jsx`, `pixi-react`, …) — the truth
107
+ * family's source writer for this region. `null` states outright that the
108
+ * host writes no source here: the region's truth is the game's own code,
109
+ * which the host does not author (a module or ingest root).
110
+ */
111
+ readonly dialect: string | null;
112
+ /**
113
+ * Anchor kinds this region's writer serves, drawn from the compile-pinned
114
+ * {@link WRITE_ANCHOR_KINDS} vocabulary. A kind absent here is a red cell in
115
+ * the matrix, which is a work order — never a silently unsupported edit.
116
+ */
117
+ readonly anchors: readonly WriteAnchorKind[];
118
+ /**
119
+ * This region's world basis. Omitted = {@link NATIVE_REGION_BASIS}, which is
120
+ * a DECLARED default (the native adapter emits it outright), not a silent
121
+ * fallback — same shape as an absent `vgai.adapter.ts` meaning
122
+ * `nativeAdapter()`.
123
+ */
124
+ readonly basis?: AdapterRegionBasis;
125
+ /**
126
+ * Project-relative globs naming source files this region OWNS, for the
127
+ * ambiguous remainder that import reach cannot place.
128
+ *
129
+ * A file's surface/dialect is derived from WHICH REGION'S IMPORT CLOSURE
130
+ * reaches it — a load-bearing fact, because the region's manifest entry is
131
+ * what the host actually executes at mount (the game would break first if it
132
+ * lied). Reach through several regions of the SAME surface is unambiguous;
133
+ * reach through regions of DIFFERING surfaces, or through none at all, is
134
+ * genuinely undecidable from outside, and this is where the game's author
135
+ * states the answer instead of the host guessing it from the file's bytes.
136
+ *
137
+ * READER: `packages/editor/src/ui-source/file-region-resolver.ts`'s
138
+ * `resolveFileRegion`, consulted BEFORE reach — a declared include wins,
139
+ * because it is a first-party statement about this exact file. Every OID
140
+ * stamping tier, the HMR classifier, the R3F authoring diagnostics and
141
+ * Content's component grouping read that one resolver.
142
+ *
143
+ * {@link regionsFromManifestRoots} emits none: the native default is PURE
144
+ * reach, and a first-party project that needs an include has a module its
145
+ * roots do not reach, which is a fact worth stating rather than absorbing.
146
+ *
147
+ * Glob vocabulary is deliberately the small one every reader already knows:
148
+ * `**` (any depth, including none), `*` (one segment, no `/`), `?` (one
149
+ * character). No brace expansion, no negation — a second syntax to learn is
150
+ * how a declaration slot turns back into a language.
151
+ */
152
+ readonly include?: readonly string[];
153
+ }
154
+ /**
155
+ * How a definition supplies its regions: the RULE `'manifest-roots'` (the
156
+ * native default — a declaration may be a rule rather than a list, the way
157
+ * `roots[]` never enumerates a world's contents), or an explicit list a game
158
+ * with novel bindings states outright.
159
+ */
160
+ export type RegionBinding = 'manifest-roots' | readonly AdapterRegion[];
161
+ /**
162
+ * The MECHANICAL derivation behind the `'manifest-roots'` rule: one region per
163
+ * declared root, its surface and adapter identity read straight off the
164
+ * RESOLVED manifest (`@engine/manifest/load` already decided both — this never
165
+ * re-derives them).
166
+ *
167
+ * The per-surface library table below is an ENGINE fact, stated once:
168
+ *
169
+ * | root `adapter` | projector | dialect | anchors |
170
+ * |-----------------------|-----------|---------------|------------------------------------|
171
+ * | `three` | `three` | `r3f` | source-prop, construction-literal |
172
+ * | `canvas` | `pixi` | `pixi-react` | source-prop, construction-literal |
173
+ * | `dom` | `dom` | `jsx` | source-prop |
174
+ * | `{module,surface}` | (surface) | `null` | live-only |
175
+ * | `{ingest,surface}` | (surface) | `null` | live-only |
176
+ *
177
+ * A module/ingest root's truth is the game's own source, which no first-party
178
+ * dialect writer authors — so it declares `live-only` rather than implying a
179
+ * write path it does not have. That is a red cell and therefore a work order,
180
+ * which is the point of stating it.
181
+ *
182
+ * Every derived region carries {@link NATIVE_REGION_BASIS} outright, so the
183
+ * editor's ground plane READS a declaration on the native path too — the
184
+ * default is published, never assumed at the read site.
185
+ */
186
+ export declare function regionsFromManifestRoots(roots: readonly ResolvedAdapterRoot[]): AdapterRegion[];
187
+ /**
188
+ * The rule form of a finder's region targeting: every region the host mounts
189
+ * from an exported composition (a root with an `entry`) that is not a declared
190
+ * DEV layer. A dev root is the game's own dev GUI — the manifest already says
191
+ * so (`dev: true`), so skipping it reads a declaration rather than guessing.
192
+ */
193
+ export declare const EXPORTED_COMPOSITION_REGIONS = "exported-composition-regions";
194
+ /**
195
+ * `scenesFromEntrypointSelection` — read the entrypoint's ACTIVE-SCENE
196
+ * SELECTION, the load-bearing reference (the game itself executes it, so it
197
+ * cannot drift: the game would break first).
198
+ */
199
+ export interface ScenesFromEntrypointSelectionParams {
200
+ readonly finder: 'scenesFromEntrypointSelection';
201
+ /**
202
+ * Which regions' entrypoints to read: named region ids, or the rule
203
+ * {@link EXPORTED_COMPOSITION_REGIONS}.
204
+ */
205
+ readonly regions: readonly string[] | typeof EXPORTED_COMPOSITION_REGIONS;
206
+ /**
207
+ * Identifier of the entrypoint's module-level selection table — the
208
+ * `const <selection> = { <sceneId>: <Component>, … }` binding the entrypoint
209
+ * renders at its swap slot.
210
+ *
211
+ * OMIT for an entrypoint that mounts ONE composition: the finder then answers
212
+ * with the single-scene degenerate table (the root's own composition, opened
213
+ * by mounting the region). Only legal alongside exactly one named region —
214
+ * a selection identifier is a fact about ONE entrypoint's source, so pairing
215
+ * it with the rule form is rejected by name rather than applied to whichever
216
+ * region happened to match.
217
+ */
218
+ readonly selection?: string;
219
+ }
220
+ /**
221
+ * `prefabsFromStories` — read the colocated portable-CSF story registrations.
222
+ * A prefab is an ordinary source component a designer independently places,
223
+ * declared by a story whose `meta.component` names it; the story registration
224
+ * is the load-bearing reference here (removing it removes the declaration).
225
+ * Zero parameters: the selection IS the whole configuration.
226
+ */
227
+ export interface PrefabsFromStoriesParams {
228
+ readonly finder: 'prefabsFromStories';
229
+ }
230
+ /** Every finder this engine ships, as the adapter's concrete SELECTION. */
231
+ export type FinderSelection = ScenesFromEntrypointSelectionParams | PrefabsFromStoriesParams;
232
+ /** The finder names, as a value — what the loader's dispatcher switches on. */
233
+ export declare const FINDER_NAMES: readonly ["scenesFromEntrypointSelection", "prefabsFromStories"];
234
+ export type FinderName = (typeof FINDER_NAMES)[number];
235
+ /**
236
+ * How the RUNNING game is navigated to an entry — the `reachable` honesty
237
+ * clause, stated rather than assumed. An entry whose reach is `none` is a
238
+ * declared-but-unreachable scene: a red cell carrying its own reason.
239
+ */
240
+ export type SceneReach =
241
+ /** Mounting the region IS opening it — the single-composition degenerate case. */
242
+ {
243
+ readonly kind: 'root-mount';
244
+ }
245
+ /** The entrypoint's own selection table reaches it under `key`. */
246
+ | {
247
+ readonly kind: 'entrypoint-selection';
248
+ readonly selection: string;
249
+ readonly key: string;
250
+ }
251
+ /** A portable story mounts it in isolation. */
252
+ | {
253
+ readonly kind: 'story';
254
+ readonly storyId: string;
255
+ }
256
+ /** Declared, with no code path that opens it. */
257
+ | {
258
+ readonly kind: 'none';
259
+ readonly reason: string;
260
+ };
261
+ /** Where an entry's composition lives in the game's own source. */
262
+ export interface SceneSource {
263
+ /** Project-relative path. */
264
+ readonly path: string;
265
+ /** Named export; omit when the module default-exports it. */
266
+ readonly export?: string;
267
+ }
268
+ /**
269
+ * One entry of the scene table. Scenes and prefabs are SIBLINGS here — both
270
+ * are registered compositions the editor opens in isolation through the same
271
+ * verb, differing only in instance site (ARCHITECTURE-CORE §Roots: "A scene is
272
+ * a ROLE, not a kind … the same kind of thing as a prefab").
273
+ */
274
+ export interface SceneEntry {
275
+ readonly id: string;
276
+ readonly label: string;
277
+ /** `scene` (swaps at the entrypoint's slot) or `prefab` (placed by a designer). */
278
+ readonly kind: 'scene' | 'prefab';
279
+ /** Owning region id; `null` for a project-scoped entry bound to no one root. */
280
+ readonly region: string | null;
281
+ /**
282
+ * `true` = a composition a designer authors (it earns a matrix column).
283
+ * `false` = TRAVERSAL: boot/loading choreography, which gets no column.
284
+ */
285
+ readonly authorable: boolean;
286
+ readonly reach: SceneReach;
287
+ readonly source?: SceneSource;
288
+ /** Which finder produced it; absent = the adapter stated it outright. */
289
+ readonly finder?: FinderName;
290
+ }
291
+ /**
292
+ * The adapter's scene table: entries stated outright, finder selections the
293
+ * host runs to produce the rest, and the entry open by default.
294
+ */
295
+ export interface AdapterSceneTable {
296
+ readonly entries?: readonly SceneEntry[];
297
+ readonly find?: readonly FinderSelection[];
298
+ /**
299
+ * Id of the entry open by default. Omit to let the finder's own answer
300
+ * stand — the host never picks one on its own, so "no default" stays a fact
301
+ * rather than becoming whichever entry sorted first.
302
+ */
303
+ readonly default?: string;
304
+ }
305
+ /**
306
+ * One statically declared observation slot. Declaring a slot and ANSWERING it
307
+ * live are separate facts (the two-state rule): a slot declared here whose
308
+ * `answer` throws or whose game never booted reads as broken, never as
309
+ * "the game has none".
310
+ */
311
+ export interface ObservationDeclaration {
312
+ readonly id: string;
313
+ readonly kind: 'system' | 'command' | 'state';
314
+ /**
315
+ * Lazily evaluated against the mounted game. The field may be a closure; the
316
+ * TABLE around it stays statically readable, which is the whole discipline.
317
+ */
318
+ readonly answer?: (game: unknown) => unknown;
319
+ }
320
+ /** The adapter module's default export, after {@link defineAdapter}. */
321
+ export interface AdapterDefinition {
322
+ readonly regions: RegionBinding;
323
+ readonly scenes: AdapterSceneTable;
324
+ readonly observation: readonly ObservationDeclaration[];
325
+ }
326
+ /** What a game writes. Every field optional — the near-empty adapter is the
327
+ * first-party case, and an adapter's SIZE measures the game's distance from
328
+ * native. */
329
+ export interface AdapterDefinitionInput {
330
+ readonly regions?: RegionBinding;
331
+ readonly scenes?: AdapterSceneTable;
332
+ readonly observation?: readonly ObservationDeclaration[];
333
+ }
334
+ export declare const AdapterDefinitionSchema: z.ZodObject<{
335
+ regions: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<"manifest-roots">, z.ZodArray<z.ZodObject<{
336
+ id: z.ZodString;
337
+ surface: z.ZodEnum<{
338
+ canvas: "canvas";
339
+ three: "three";
340
+ dom: "dom";
341
+ }>;
342
+ dev: z.ZodBoolean;
343
+ projector: z.ZodEnum<{
344
+ three: "three";
345
+ dom: "dom";
346
+ pixi: "pixi";
347
+ }>;
348
+ dialect: z.ZodNullable<z.ZodString>;
349
+ anchors: z.ZodArray<z.ZodEnum<{
350
+ "source-prop": "source-prop";
351
+ "construction-literal": "construction-literal";
352
+ "physics-binding": "physics-binding";
353
+ "data-record": "data-record";
354
+ "live-only": "live-only";
355
+ }>>;
356
+ basis: z.ZodOptional<z.ZodObject<{
357
+ up: z.ZodEnum<{
358
+ y: "y";
359
+ z: "z";
360
+ }>;
361
+ groundHeight: z.ZodNumber;
362
+ }, z.core.$strict>>;
363
+ include: z.ZodOptional<z.ZodArray<z.ZodString>>;
364
+ }, z.core.$strict>>]>>;
365
+ scenes: z.ZodOptional<z.ZodObject<{
366
+ entries: z.ZodOptional<z.ZodArray<z.ZodObject<{
367
+ id: z.ZodString;
368
+ label: z.ZodString;
369
+ kind: z.ZodEnum<{
370
+ scene: "scene";
371
+ prefab: "prefab";
372
+ }>;
373
+ region: z.ZodNullable<z.ZodString>;
374
+ authorable: z.ZodBoolean;
375
+ reach: z.ZodUnion<readonly [z.ZodObject<{
376
+ kind: z.ZodLiteral<"root-mount">;
377
+ }, z.core.$strict>, z.ZodObject<{
378
+ kind: z.ZodLiteral<"entrypoint-selection">;
379
+ selection: z.ZodString;
380
+ key: z.ZodString;
381
+ }, z.core.$strict>, z.ZodObject<{
382
+ kind: z.ZodLiteral<"story">;
383
+ storyId: z.ZodString;
384
+ }, z.core.$strict>, z.ZodObject<{
385
+ kind: z.ZodLiteral<"none">;
386
+ reason: z.ZodString;
387
+ }, z.core.$strict>]>;
388
+ source: z.ZodOptional<z.ZodObject<{
389
+ path: z.ZodString;
390
+ export: z.ZodOptional<z.ZodString>;
391
+ }, z.core.$strict>>;
392
+ finder: z.ZodOptional<z.ZodEnum<{
393
+ scenesFromEntrypointSelection: "scenesFromEntrypointSelection";
394
+ prefabsFromStories: "prefabsFromStories";
395
+ }>>;
396
+ }, z.core.$strict>>>;
397
+ find: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
398
+ finder: z.ZodLiteral<"scenesFromEntrypointSelection">;
399
+ regions: z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodLiteral<"exported-composition-regions">]>;
400
+ selection: z.ZodOptional<z.ZodString>;
401
+ }, z.core.$strict>, z.ZodObject<{
402
+ finder: z.ZodLiteral<"prefabsFromStories">;
403
+ }, z.core.$strict>]>>>;
404
+ default: z.ZodOptional<z.ZodString>;
405
+ }, z.core.$strict>>;
406
+ observation: z.ZodOptional<z.ZodArray<z.ZodObject<{
407
+ id: z.ZodString;
408
+ kind: z.ZodEnum<{
409
+ command: "command";
410
+ state: "state";
411
+ system: "system";
412
+ }>;
413
+ answer: z.ZodOptional<z.ZodCustom<(game: unknown) => unknown, (game: unknown) => unknown>>;
414
+ }, z.core.$strict>>>;
415
+ }, z.core.$strict>;
416
+ /**
417
+ * Validate and freeze a game's binding table.
418
+ *
419
+ * Called TWICE by design and with one schema: once here, in the game's own
420
+ * module, so a malformed table fails at the author's own file with the key
421
+ * named; and once in the host's loader, because the loaded default export is
422
+ * untrusted input crossing a module boundary. Two call sites, one rule — not
423
+ * two ways to say the same thing.
424
+ */
425
+ export declare function defineAdapter(input?: AdapterDefinitionInput): AdapterDefinition;
426
+ /** Extra bindings a near-native game adds without restating the native ones. */
427
+ export interface NativeAdapterOptions {
428
+ /** Scene-table entries this game states outright, beside what the finders find. */
429
+ readonly scenes?: readonly SceneEntry[];
430
+ /** Observation slots this game declares. */
431
+ readonly observation?: readonly ObservationDeclaration[];
432
+ }
433
+ /**
434
+ * THE NATIVE DEFAULT — regions derived mechanically from the manifest's
435
+ * `roots[]`, and a scene table produced by the two shipped finders. This is
436
+ * what a first-party project ships (`export default nativeAdapter()`), and it
437
+ * is also what a project with NO `vgai.adapter.ts` gets: that absence is the
438
+ * declared native default, not a silent fallback.
439
+ */
440
+ export declare function nativeAdapter(options?: NativeAdapterOptions): AdapterDefinition;
441
+ /**
442
+ * Parse an untrusted default export (the loaded `vgai.adapter.ts`) into a
443
+ * definition. Rejects loudly — an unknown key, a bad finder name, a
444
+ * `selection` paired with the rule form all fail by name.
445
+ */
446
+ export declare function parseAdapterDefinition(value: unknown): AdapterDefinition;
447
+ //# sourceMappingURL=adapter-module.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"adapter-module.d.ts","sourceRoot":"","sources":["../../src/adapter/adapter-module.ts"],"names":[],"mappings":"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"}