@vgai/engine 0.5.4 → 0.5.6

package/dist/manifest/schema.js

@@ -0,0 +1,633 @@
+// T3.1 slice 1 — the game manifest schema (`vgai.project.json`).
+//
+// This is the serialized form of the Game's root list for the adjudicated
+// field list this file implements exactly. `load.ts` is this schema's runtime
+// reader (T4.1 policy): it parses via this schema, then layers the
+// cross-field checks and default resolution §3/§5 describe. Every field below
+// has a `.describe()` (repo policy — powers `scripts/generate-schema.ts` and
+// the T4.1 schema-walk coverage test).
+//
+// Naming: this file follows the repo's `XxxSchema` (Zod schema) / `Xxx`
+// (inferred type) convention used throughout `scene/schema/` — the design
+// doc's §3 sketch names the bare consts (`Tier`, `IngestStrategy`,
+// `AdapterRoot`) without the `Schema` suffix; that sketch is explicitly a
+// "Zod sketch" the doc tells implementers to adapt to real code style
+// ("mirror the style in scene/schema/scene-file.ts" per CLAUDE.md), so the
+// schema consts here are suffixed and the bare names are reserved for the
+// inferred types, matching every other schema file in the repo.
+//
+// Adapter surface values mirror `AdapterSurface` in
+// `packages/engine/src/runtime/game.ts` (`'three' | 'canvas' | 'dom'`)
+// by value, not by import. The adapter remains the sole root discriminator.
+import { z } from 'zod';
+/**
+ * Current on-disk `vgai.project.json` format. Exported so editor/server
+ * compatibility checks do not duplicate the schema's literal value.
+ */
+export const GAME_MANIFEST_VERSION = 2;
+// ---------------------------------------------------------------------------
+// Ingest capture strategy (the general vocabulary D6/§4 names)
+// ---------------------------------------------------------------------------
+export const IngestStrategySchema = z.enum([
+    'shared', // game imports host-served ESM three — full in-realm capture
+    'deduped', // game source built by OUR pipeline, bundler dedupe — full capture
+    'iframe-reachable', // prebuilt bundle in iframe, three reachable — cross-realm capture
+    'opaque-embed', // prebuilt bundle, nothing reachable — host lifecycle only
+]);
+// ---------------------------------------------------------------------------
+// Capability tier — one ordered enum, declared per delivery context (§4)
+// ---------------------------------------------------------------------------
+export const TierSchema = z.enum([
+    'first-party', // vgai-native root: full editor, full loop control
+    'shared', // = IngestStrategy 'shared' rung
+    'deduped', // = IngestStrategy 'deduped' rung
+    'iframe-reachable', // = IngestStrategy 'iframe-reachable' rung
+    'opaque-embed', // = IngestStrategy 'opaque-embed' rung
+    'unsupported', // this root does not function in this delivery context
+]);
+// ---------------------------------------------------------------------------
+// Root adapter identity. The adapter is the sole discriminator: a root never
+// repeats its rendering substrate in a sibling `kind` field. Module and ingest
+// adapters carry the surface their adapter contract exposes because the host
+// must allocate a layer before the module has mounted.
+//
+// The surface vocabulary is `three | canvas | dom` — what the HOST HANDS the
+// root, not which library it uses. `canvas` and `dom` are platform primitives:
+// a canvas root may be Pixi, Phaser, Babylon, raw WebGL/WebGPU or a 2D context,
+// and a dom root may be React, Vue, Svelte or plain HTML, all through the
+// identical host. The former `canvas`/`react` named two libraries in a seam
+// that has nothing to do with either, which foreclosed the rest by
+// construction.
+//
+// All three surfaces are legal as a BARE adapter string: each names a root the
+// engine itself mounts from an `entry` module — `three` through the R3F lane
+// (`@engine/world3d-react`), `canvas` through the Pixi lane
+// (`@engine/canvas-react`), `dom` through the React lane. In every case the
+// entry's document is its own TSX source. A root the engine does NOT mount
+// arrives as an `{ ingest }` root or a `{ module }` adapter the project
+// supplies, both of which name their `surface` explicitly.
+//
+// `three` earns a kind of its own because the host must provide something the
+// platform cannot: the ONE shared `three` instance (identity matters — ingest
+// games bring their own, and r3f depends on dedupe). React needs no equivalent,
+// which is exactly why react is a `dom` root rather than its own kind.
+//
+// The pre-rename spellings `threejs`/`pixijs`/`react` are REMOVED, not
+// normalized (WO-LR1 item 2, the legacy-removal doctrine at
+// ARCHITECTURE-CORE §Vocabulary). Normalization was a second way to say the
+// same thing: two spellings both parsed, so both kept being written, and
+// SECOND readers grew (the dev server's surface probe, the hosted-editor
+// bundler's alias sets) each re-implementing the same map. A manifest naming
+// an old spelling now fails to parse with an issue that names the canonical
+// value and the exact one-line edit.
+// ---------------------------------------------------------------------------
+/** Removed spellings → the canonical value each one must be rewritten to. */
+const REMOVED_SURFACE_SPELLING = {
+    threejs: 'three',
+    pixijs: 'canvas',
+    react: 'dom',
+};
+/** Removed spellings legal as a BARE adapter (a root the engine itself mounts). */
+const REMOVED_BARE_ADAPTER_SPELLING = {
+    threejs: 'three',
+    pixijs: 'canvas',
+    react: 'dom',
+};
+function removedSpellingMessage(bad, where) {
+    const canonical = where === 'adapter' ? REMOVED_BARE_ADAPTER_SPELLING[bad] : REMOVED_SURFACE_SPELLING[bad];
+    return (`Game manifest: \`${where}\`: "${bad}" — that spelling was REMOVED (WO-LR1; ` +
+        'ARCHITECTURE-CORE §Vocabulary). The surface vocabulary is ' +
+        "'three' | 'canvas' | 'dom' — what the HOST HANDS the root, never which " +
+        `library it uses.\nFix: change \`${where}\` to "${canonical}".`);
+}
+/** Reject a removed surface spelling wherever one may appear — the bare
+ *  shorthand, or the `surface` field of a module/ingest adapter — with an issue
+ *  naming the canonical value. Runs as a Zod preprocess so the message wins
+ *  over the union's generic discriminant error. */
+function rejectRemovedRootAdapterSpelling(value, ctx) {
+    if (typeof value === 'string' && REMOVED_BARE_ADAPTER_SPELLING[value]) {
+        ctx.addIssue({ code: 'custom', message: removedSpellingMessage(value, 'adapter') });
+        return z.NEVER;
+    }
+    if (value && typeof value === 'object' && 'surface' in value) {
+        const surface = value.surface;
+        if (typeof surface === 'string' && REMOVED_SURFACE_SPELLING[surface]) {
+            ctx.addIssue({
+                code: 'custom',
+                message: removedSpellingMessage(surface, 'adapter.surface'),
+            });
+            return z.NEVER;
+        }
+    }
+    return value;
+}
+export const RootAdapterSchema = z
+    .preprocess(rejectRemovedRootAdapterSpelling, z.union([
+    z.enum(['three', 'canvas', 'dom']),
+    z
+        .object({
+        module: z
+            .string()
+            .describe('Game-folder-relative path to a custom adapter module (trust boundary)'),
+        surface: z
+            .enum(['three', 'canvas', 'dom'])
+            .describe('Native surface exposed by this custom adapter contract'),
+    })
+        .strict(),
+    z
+        .object({
+        surface: z
+            .enum(['three', 'canvas', 'dom'])
+            .describe('Native surface captured from the unmodified game'),
+        ingest: z
+            .object({
+            strategy: IngestStrategySchema.describe('Capture mechanics rung this ingested root uses (§4) — also the root`s natural local capability tier'),
+            entryHtml: z
+                .string()
+                .optional()
+                .describe('Entry HTML path, project-relative. WIRED for opaque-embed (D-W2): ' +
+                'the file`s bytes are read verbatim through ' +
+                'the project-static route and hosted in a sandboxed iframe (embed-only, no scene ' +
+                'introspection), for both canvas and three roots. Legal but NOT wired to a ' +
+                'mount for iframe-reachable (a named error at resolve names this — use `bundleUrl` ' +
+                'instead, the wired reachable route).'),
+            assets: z
+                .record(z.string(), z.string())
+                .optional()
+                .describe('Path-substring -> served-URL rewrites for this ingested game (IngestGame.assets today)'),
+            domStubs: z
+                .array(z.string())
+                .optional()
+                .describe('DOM API stub ids this ingested game requires to run headlessly/in-realm'),
+            captureTimeoutMs: z
+                .number()
+                .optional()
+                .describe('How long to wait for capture before REPORTING the degrade loudly — not how ' +
+                'long to keep listening. On the self-hosted-three route the devtools ' +
+                'subscription is permanent, so a renderer appearing later still upgrades a ' +
+                'reported-embed-only mount in place; the host clamps this value so a long ' +
+                'one cannot block the editor on a question the upgrade path answers anyway.'),
+            // The six iframe-reachable-multi mount fields
+            // (`ingest-iframe-2d.ts`'s `IframeReachableMultiOpts`), legal
+            // ONLY when `strategy` is 'iframe-reachable' (enforced by the
+            // `.superRefine` below).
+            bundleUrl: z
+                .string()
+                .optional()
+                .describe('Absolute URL of the externalized built game bundle — the WIRED iframe-reachable ' +
+                'mount route (iframe-reachable only), for BOTH canvas (Track P, ' +
+                "ingest-iframe-2d.ts's mountIngestGame2DIframeReachableMulti) and three (D-W1, " +
+                "ingest-iframe-reachable-adapter.ts's mountIngestGameIframeReachableBundle). " +
+                'PRECONDITION: the bundle must externalize its root`s own runtime as a bare, ' +
+                'un-rewritten import (`pixi.js` for canvas, `three` for three — `vgai bundle` ' +
+                'does this for you) so it resolves through the iframe importmap to the HOST ' +
+                'instance the capture trap is installed on; a bundle with an inlined runtime is ' +
+                'unreachable and degrades to the embed-only floor. Exactly one of bundleUrl/' +
+                'entryHtml is required when strategy is iframe-reachable.'),
+            baseHref: z
+                .string()
+                .optional()
+                .describe("Iframe <base href> so the game's relative asset URLs resolve (iframe-reachable only)."),
+            assetBaseUrl: z
+                .string()
+                .optional()
+                .describe("Host-side basePath forced onto the trapped runtime's own asset resolution — " +
+                "pixi's `Assets.init` for a canvas root, three's " +
+                '`DefaultLoadingManager.setURLModifier` for a three root (D-W1) — absolute, or ' +
+                "root-relative (resolved against the editor page's own origin at mount time, " +
+                'ingest-mode.ts, so a static manifest never has to know the dev-server port) ' +
+                '(iframe-reachable only — a document.write iframe keeps the parent window.location).'),
+            extraDeps: z
+                .array(z.string())
+                .optional()
+                .describe("Bare specifiers of this root's externalized deps beyond its own runtime " +
+                "(pixi.js/three — e.g. '@pixi/sound', 'gsap'). Resolved by the editor's " +
+                'host-namespace registry into module namespaces when known (D-P1 — the manifest ' +
+                'carries data, not code); an unregistered specifier falls back to the open ' +
+                "project's own node_modules (D-Z3), served " +
+                'as a verbatim iframe importmap URL. Throws a named error if neither resolves it ' +
+                '(iframe-reachable only).'),
+            pixiModuleUrl: z
+                .string()
+                .optional()
+                .describe('PIXI-ONLY: standalone matching-major pixi ESM URL to trap instead of the host ' +
+                "pixi, for version-skewed games (e.g. a v6 game on a v8 host); this field's " +
+                'PRESENCE is how the skew is expressed (D-P2 — no separate strategy/tier for ' +
+                'version skew) (iframe-reachable only). Declaring this on a `kind: "three"` ' +
+                'root is schema-legal (this field is kind-agnostic here) but throws a NAMED ' +
+                'not-supported error at resolve — three has no version-skew mount this wave ' +
+                '(D-W7: a hypothetical `threeModuleUrl` is explicitly parked, no consumer ' +
+                'exists).'),
+            bodyHtml: z
+                .string()
+                .optional()
+                .describe('HTML injected into the iframe body before the game script boots (e.g. a ' +
+                '`<div id="game-root">` the game expects to find) (iframe-reachable only).'),
+        })
+            .describe('Ingest adapter configuration for an unmodified game (a repo-vendored game or your ' +
+            'own external folder)')
+            .superRefine((ingest, ctx) => {
+            // The six iframe-reachable-multi fields only make sense for the
+            // iframe-reachable-multi mount — reject them under any other
+            // strategy (mirrors ui.ts's dead-field-under-wrong-variant pattern).
+            const iframeOnlyFields = [
+                ['bundleUrl', ingest.bundleUrl !== undefined],
+                ['baseHref', ingest.baseHref !== undefined],
+                ['assetBaseUrl', ingest.assetBaseUrl !== undefined],
+                ['extraDeps', ingest.extraDeps !== undefined],
+                ['pixiModuleUrl', ingest.pixiModuleUrl !== undefined],
+                ['bodyHtml', ingest.bodyHtml !== undefined],
+            ];
+            if (ingest.strategy !== 'iframe-reachable') {
+                for (const [key, present] of iframeOnlyFields) {
+                    if (present) {
+                        ctx.addIssue({
+                            code: z.ZodIssueCode.custom,
+                            message: `\`${key}\` is only legal when strategy is 'iframe-reachable' (got ` +
+                                `"${ingest.strategy}") — bundleUrl/baseHref/assetBaseUrl/extraDeps/` +
+                                "pixiModuleUrl/bodyHtml are the iframe-reachable-multi mount's options " +
+                                '(canvas: ingest-iframe-2d.ts IframeReachableMultiOpts; three, D-W1: ' +
+                                'ingest-iframe-reachable-adapter.ts IframeReachableBundleOpts) and have no ' +
+                                'meaning under any other strategy.',
+                            path: [key],
+                        });
+                    }
+                }
+                return;
+            }
+            const hasBundleUrl = ingest.bundleUrl !== undefined;
+            const hasEntryHtml = ingest.entryHtml !== undefined;
+            if (hasBundleUrl === hasEntryHtml) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    message: "strategy 'iframe-reachable' requires EXACTLY ONE of `bundleUrl` (externalized " +
+                        'multi-file bundle, the iframe-reachable-multi mount) or `entryHtml` (single-' +
+                        `file/legacy iframe entry) — ${hasBundleUrl ? 'both are present' : 'neither is present'}.`,
+                    path: hasBundleUrl ? ['bundleUrl'] : ['entryHtml'],
+                });
+            }
+        }),
+    })
+        .strict(),
+]))
+    .describe("Root adapter identity: built-in 'three'/'canvas'/'dom' (what the host hands " +
+    "the root — 'canvas' covers Pixi/Phaser/Babylon/raw WebGL, 'dom' covers " +
+    'React/Vue/plain HTML), a custom { module, surface } adapter, or an ' +
+    '{ ingest, surface } adapter for an unmodified game.');
+// ---------------------------------------------------------------------------
+// Root entry
+// ---------------------------------------------------------------------------
+export const AdapterRootSchema = z
+    .object({
+    id: z
+        .string()
+        .describe('Unique id for this root within the manifest (enforced-unique, D-V6 — GameManifestSchema.roots rejects duplicates)'),
+    description: z
+        .string()
+        .optional()
+        .describe("Optional one-line description of this root's game/content (e.g. an ingested game's " +
+        "blurb — the manifest-native replacement for a registry entry's description field)"),
+    adapter: RootAdapterSchema.describe("This root's adapter and sole rendering/lifecycle discriminator"),
+    entry: z
+        .string()
+        .optional()
+        .describe('Module exporting a world root — a TSX/R3F component or a setup()/adapter (three), or a ' +
+        'React component (dom). Required for every built-in adapter root.'),
+    zOrder: z
+        .number()
+        .int()
+        .default(0)
+        .describe('Canvas stacking order; ties broken by array order'),
+    pausable: z
+        .boolean()
+        .default(true)
+        .describe('Whether play-mode pause/step applies to this root'),
+    dev: z
+        .boolean()
+        .default(false)
+        .describe("Marks this root as a DEV LAYER: the game's own dev GUI, not shipped game content. " +
+        'Four readers act on it. `mountManifestRoots` mounts it only when dev layers are ' +
+        'enabled (`devLayersEnabled`, runtime/dev-layers.ts), so a production build carries ' +
+        'no dev GUI; the host stacks every dev root ABOVE every non-dev root (a dev layer ' +
+        'sits topmost, and as a DOM layer it steals no input from the game while closed); ' +
+        'the play compositor EXCLUDES dev layers from a capture unless the capture asks for ' +
+        'them; and the editor mounts a dev root as edit-time CHROME rather than authorable ' +
+        'content (no hierarchy entry, no OID stamping, no JSX write-back, not selectable).'),
+    loop: z
+        .enum(['gated', 'self-driven'])
+        .default('gated')
+        .describe('gated: host-driven loop (default). self-driven: this root drives its own loop ' +
+        '(the "composited, unsynchronized" tier) — an axis independent of capability tier'),
+    capabilities: z
+        .object({
+        local: TierSchema.optional().describe('Declared capability tier when served via the local CLI (Vite pipeline); omitted -> derived (§4)'),
+        hosted: TierSchema.optional().describe('Declared capability tier when served hosted (no bundler: esbuild-wasm + externals only); omitted -> derived (§4)'),
+    })
+        .optional()
+        .describe("Per-delivery-context capability tier declarations (§4). Declaring above the adapter's " +
+        'ceiling for that context is an error; declaring at or below it (including `unsupported`) is legal.'),
+})
+    .strict();
+/**
+ * The MEDIUM a root occupies — its surface, i.e. what the host hands it. A
+ * bare adapter string names its own surface; `{ module, surface }` and
+ * `{ ingest, surface }` name it explicitly. Bucketing by surface is what makes
+ * a first-party `@pixi/react` world, an ingested canvas game and a custom
+ * canvas module ONE medium: they all compete for the same canvas surface, and
+ * which library draws on it is not what the rule below is about.
+ */
+function rootMedium(root) {
+    return typeof root.adapter === 'string' ? root.adapter : root.adapter.surface;
+}
+// ---------------------------------------------------------------------------
+// Learn metadata (FT-5)
+// ---------------------------------------------------------------------------
+export const LearnKindSchema = z
+    .enum(['starter', 'feature', 'sample-game', 'lesson-companion'])
+    .describe('Content kind in the FTUE taxonomy (§3): starter (minimal per-genre starting point), ' +
+    'feature (demonstrates a subsystem), sample-game (complete game as an architectural ' +
+    'reference), lesson-companion (exists to back a Learn-site lesson)');
+export const LearnDifficultySchema = z
+    .enum(['beginner', 'intermediate', 'advanced'])
+    .describe('Learner-facing difficulty rating');
+export const LearnMetadataSchema = z
+    .object({
+    kind: LearnKindSchema,
+    title: z.string().min(1).describe('Learner-facing display title (gallery card headline)'),
+    summary: z.string().min(1).describe('One-sentence learner-facing summary (gallery card body)'),
+    difficulty: LearnDifficultySchema,
+    features: z
+        .array(z.string().regex(/^[a-z0-9]+(-[a-z0-9]+)*$/, 'features tags must be kebab-case'))
+        .describe('Short kebab-case feature tags used as gallery/catalog filter facets'),
+    thumbnail: z
+        .string()
+        .optional()
+        .describe('Optional thumbnail image reference, PROJECT-relative (canonical path: ' +
+        'learn/thumbnail.png — the §3 schema path). Generated per FT-11 by the deterministic ' +
+        'render tooling (scripts/generate-learn-thumbnails.ts), never hand-made'),
+    preview: z
+        .string()
+        .optional()
+        .describe('Optional short preview video/loop reference, PROJECT-relative (canonical path: ' +
+        'learn/preview.mp4; generated per FT-11)'),
+    lesson: z
+        .string()
+        .optional()
+        .describe('Optional Learn-site lesson URL that teaches this project 1:1 ' +
+        '(e.g. https://vgai-learn.pages.dev/quick-starts/joints/)'),
+})
+    .strict()
+    .describe('Learner-facing metadata (FT-5) — powers the example ' +
+    'gallery, New Project wizard, and Learn-site catalog. Registries are generated from this ' +
+    'block; there is no parallel hand-edited catalog.');
+// ---------------------------------------------------------------------------
+// Game manifest (vgai.project.json)
+// ---------------------------------------------------------------------------
+export const GameManifestSchema = z
+    .object({
+    $schema: z
+        .string()
+        .optional()
+        .describe('Optional JSON Schema URI for editor autocomplete and validation'),
+    manifestVersion: z
+        .literal(GAME_MANIFEST_VERSION)
+        .describe('Manifest file format version (v2 clean roots)'),
+    name: z.string().describe('Game display name'),
+    appId: z
+        .string()
+        .optional()
+        .describe('Stable reverse-domain application id used by packaged targets'),
+    version: z.string().describe("The game's own version (used for orphan detection)"),
+    engine: z
+        .object({
+        version: z
+            .string()
+            .describe('Exact @vgai/engine semver this game was scaffolded/last upgraded against — an ' +
+            'identity pin, not a range'),
+    })
+        .describe('Engine version pin'),
+    roots: z
+        .array(AdapterRootSchema)
+        .min(1)
+        .superRefine((roots, ctx) => {
+        // D-V6 (debt): root ids are described as unique above but that was
+        // describe-only at the SCHEMA level — only load.ts's loader-level
+        // cross-field check caught a collision, so any OTHER consumer of this
+        // schema (the generated JSON Schema, editor tooling) saw duplicate
+        // ids as legal. Enforced HERE instead, naming every colliding id (not
+        // just the first found) — a root id is the key every per-world editor
+        // surface is addressed by, so a silently-permitted duplicate would
+        // have two roots silently collide.
+        const counts = new Map();
+        for (const root of roots)
+            counts.set(root.id, (counts.get(root.id) ?? 0) + 1);
+        const duplicates = [...counts.entries()].filter(([, n]) => n > 1).map(([id]) => id);
+        if (duplicates.length > 0) {
+            const idsText = duplicates.map((id) => `"${id}"`).join(', ');
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: duplicates.length === 1
+                    ? `Game manifest: duplicate root id ${idsText} — root ids must be unique across the manifest (enforced-unique).`
+                    : `Game manifest: duplicate root ids: ${idsText} — root ids must be unique across the manifest (enforced-unique).`,
+            });
+        }
+        // A project has at most ONE world root per MEDIUM (owner-ratified).
+        // The medium is the surface (see `rootMedium`), so `three`, `dom` and
+        // the canvas surface are the three buckets — a first-party canvas
+        // world, a canvas ingest and a canvas module are the SAME medium.
+        //
+        // Enforced here rather than left to the reader because the editor
+        // mounts exactly one root per medium (`resolveFocusedThreejsRootId`
+        // is a `find`, and the design-time layer stack hosts the one dom
+        // root): a second root of the same medium parsed cleanly and was then
+        // silently never mounted, which is the failure mode this rejects.
+        //
+        // DEV LAYERS ARE COUNTED SEPARATELY. A `dev: true` root is not content
+        // competing for the medium — it is the game's dev GUI stacked above
+        // everything (`create-runtime.ts`'s stacking pass), and the editor
+        // mounts it as chrome, not as the one dom document. Counting it with
+        // the content roots would make the ratified shape — a game with a HUD
+        // and a dev panel, both `dom` — unrepresentable. The one-per-medium
+        // rule still applies WITHIN the dev band, for the same
+        // silently-never-mounted reason.
+        const idsByMedium = new Map();
+        for (const root of roots) {
+            const medium = `${root.dev ? 'dev ' : ''}${rootMedium(root)}`;
+            const ids = idsByMedium.get(medium);
+            if (ids)
+                ids.push(root.id);
+            else
+                idsByMedium.set(medium, [root.id]);
+        }
+        for (const [medium, ids] of idsByMedium) {
+            if (ids.length < 2)
+                continue;
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `Game manifest: a project has at most one ${medium} world root — ` +
+                    `${ids.map((id) => `"${id}"`).join(', ')} all occupy the ${medium} surface. ` +
+                    'Keep one and remove the rest, or move a root to a different medium ' +
+                    "(three / canvas / dom); only one root per medium is ever mounted, so a second one's " +
+                    'content would never appear.',
+            });
+        }
+    })
+        .describe("The Game's explicit, non-empty adapter-root composition. There is no implicit root. " +
+        'Root ids are unique, and a project declares at most ONE world root per medium — ' +
+        'one `three`, one `dom`, one canvas-surface root (first-party canvas, canvas ingest ' +
+        'and canvas module are the same medium). A `dev: true` root is counted in its own ' +
+        'band: a dev layer is chrome stacked above the game, not content competing for the ' +
+        'medium, so a game may declare a `dom` HUD and a `dom` dev layer — but not two of either.'),
+    authoring: z
+        .object({
+        hierarchy: z
+            .object({
+            rootLabels: z
+                .record(z.string(), z.string())
+                .optional()
+                .describe('Optional editor labels keyed by adapter-root id'),
+            groups: z
+                .array(z.object({
+                id: z.string().describe('Unique editor-only group id'),
+                label: z.string().describe('Editor-only group label'),
+                roots: z
+                    .array(z.string())
+                    .min(1)
+                    .describe('Adapter-root ids shown under this editor-only group'),
+            }))
+                .optional()
+                .describe('Optional editor-only hierarchy groups'),
+        })
+            .optional()
+            .describe('Editor projection for native adapter roots'),
+    })
+        .optional()
+        .describe('Editor-only authoring metadata; never runtime ownership'),
+    server: z
+        .object({
+        room: z.string().describe('Colyseus room name'),
+        module: z
+            .string()
+            .optional()
+            .describe('Module path for the Colyseus room bootstrap; defaults to the scaffolded server bootstrap'),
+        relay: z
+            .object({
+            signalingUrl: z
+                .string()
+                .optional()
+                .describe('Managed relay signaling URL to prefer over the client default; omitted when the deploy did not pin one'),
+            accessToken: z
+                .string()
+                .describe('Room-scoped managed-relay access token minted at `vgai deploy` and read by the standalone client (main.ts)'),
+            expiresAt: z
+                .number()
+                .describe('Token expiry as epoch milliseconds; the client falls back to a tokenless join once elapsed'),
+        })
+            .strict()
+            .optional()
+            .describe('Deploy-baked managed-relay credentials. NEVER hand-authored in source — written only into the staged manifest by `vgai deploy` and fetched at runtime by the standalone client'),
+    })
+        .optional()
+        .describe('Multiplayer server config (Colyseus), if this game registers a room'),
+    resolution: z
+        .object({
+        width: z.number().describe('Canvas width in pixels'),
+        height: z.number().describe('Canvas height in pixels'),
+    })
+        .optional()
+        .describe('Canvas resolution'),
+    debug: z
+        .object({
+        allowInProduction: z
+            .boolean()
+            .describe('Allow the ?vgai-debug=1 introspection bridge and debug-command invocation in ' +
+            'production builds. Default false: the bridge only installs in dev builds. The ' +
+            'runtime reader is the debug-bridge installer (D18).'),
+    })
+        .optional()
+        .describe('Debug-bridge production gating (D18) — governs whether ?vgai-debug=1 installs ' +
+        'window.__vgai outside dev builds.'),
+    determinism: z
+        .object({
+        seededRandom: z
+            .boolean()
+            .describe('Declares that ALL gameplay RNG in this project flows through ctx.random (the ' +
+            'named-stream seeded PRNG) rather than raw ' +
+            'Math.random/Date.now/performance.now. Three runtime enforcers key off this flag: ' +
+            'the boot-time seeding reader (mount-manifest.ts seeds ctx.random from ' +
+            'defaultSeed/?vgai-seed=/explicit config, in that precedence, only when true), the ' +
+            'gameplay-rng-ban burn-down scan (test/gameplay-rng-ban.test.ts — lints this ' +
+            "project's src/ for raw RNG/wall-clock calls), and the dev-mode Math.random phase " +
+            'trap (runtime/gameplay-rng-trap.ts — warns once per call site during a gameplay ' +
+            'frame, never throws). Default false: an undeclared project gets no determinism ' +
+            'contract at all (that IS the opt-out — no dead field).'),
+        defaultSeed: z
+            .number()
+            .int()
+            .optional()
+            .describe('The seed ctx.random boots from when seededRandom is true, unless overridden by ' +
+            '?vgai-seed=<int> (the query param always wins over this manifest default) or an ' +
+            'even higher-precedence explicit config value a host passes directly. Optional — ' +
+            "omit to fall back to the runtime's own fixed default seed."),
+    })
+        .optional()
+        .describe('Seeded-RNG determinism contract (D15) — governs ' +
+        'whether ctx.random is boot-seeded from a reproducible seed and whether the ' +
+        'gameplay-rng-ban scan / dev-mode Math.random phase trap are active for this project.'),
+    budget: z
+        .object({
+        frameCpuMsP95: z
+            .number()
+            .positive()
+            .optional()
+            .describe('Maximum allowed p95 of per-frame CPU time (ms) across the measured frames of a ' +
+            '`vgai perf` seeded headless run. CPU-side only: headless runs rasterize under ' +
+            'SwiftShader, so this is main-thread frame cost, NOT real GPU frame time. ' +
+            'Machine-dependent — prefer the baseline-diff tolerance band for regression ' +
+            'gating and use this as a coarse absolute ceiling.'),
+        physicsMsP95: z
+            .number()
+            .positive()
+            .optional()
+            .describe("Maximum allowed p95 of the profiler's `physics` phase time (ms) per fixed-step " +
+            'frame in a `vgai perf` run. Same CPU-timing caveats as frameCpuMsP95.'),
+        maxEntities: z
+            .number()
+            .int()
+            .nonnegative()
+            .optional()
+            .describe('Maximum allowed entity-tagged scene-graph nodes (nodes carrying ' +
+            "userData.entityId) summed across the game's three/canvas worlds at the end " +
+            'of a `vgai perf` run. Exact and deterministic under a seed — no tolerance band.'),
+        maxDrawCalls: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe('Maximum allowed renderer draw calls in any measured frame of a `vgai perf` run ' +
+            "(the profiler's per-frame render.drawCalls, from renderer.info). Exact and " +
+            'deterministic under a seed.'),
+        maxTriangles: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe('Maximum allowed rendered triangles in any measured frame of a `vgai perf` run ' +
+            "(the profiler's per-frame render.triangles, from renderer.info). Exact and " +
+            'deterministic under a seed.'),
+    })
+        .refine((budget) => Object.values(budget).some((value) => value !== undefined), {
+        message: 'Game manifest: `budget` must set at least one metric (frameCpuMsP95, physicsMsP95, ' +
+            'maxEntities, maxDrawCalls, maxTriangles) — an empty budget block gates nothing ' +
+            '(the no-dead-fields policy).',
+    })
+        .optional()
+        .describe('Performance budget (W3d, F11 perf regression gates) asserted by ' +
+        '`vgai perf --assert-budget`: a seeded, fixed-step headless run samples the engine ' +
+        'profiler and fails (nonzero exit) when any metric here is exceeded. Only ' +
+        'headlessly-measurable metrics are budgetable; real GPU frame time is not (SwiftShader).'),
+    learn: LearnMetadataSchema.optional().describe('Optional learner-facing metadata (FT-5) — set on shipped example projects so the ' +
+        'gallery/wizard/Learn-catalog registries can be generated from the manifest itself'),
+})
+    .strict()
+    .describe('Game manifest (vgai.project.json) — the complete v2 project configuration');