@vgai/engine 0.5.11 → 0.5.13

package/src/manifest/load.ts

@@ -17,10 +17,8 @@ import {
   type AdapterRoot,
   type GameManifest,
   GameManifestSchema,
-  type IngestStrategy,
   type LearnMetadata,
   type RootAdapter,
-  type Tier,
 } from './schema';
 
 // ---------------------------------------------------------------------------
@@ -42,40 +40,28 @@ export type ResolvedAdapter =
     }
   | {
       readonly type: 'ingest';
-      // 'ingest-react' (Track N, N1) is assigned here purely structurally (kind
-      // === 'dom'), same as 'ingest-three'/'ingest-pixi': this loader stays
-      // strategy-agnostic at resolve time, exactly like the other two ingest
-      // identities (`ceilingFor`/`resolveCapabilities` below already derive tiers
-      // per `strategy` regardless of `kind`). The v1 "deduped rung only" rule
-      // (D-N3) is enforced editor-side, at the resolver
-      // (`packages/editor/src/adapter-resolver.ts`'s `resolveIngestReactAdapter`)
-      // — not here — mirroring how THIS file never rejects
-      // `ingest-three`/`ingest-pixi`'s `iframe-reachable`/`opaque-embed`
-      // strategies either; `resolveIngestDescriptor`/`resolveIngest2DDescriptor`
-      // are where "not yet buildable" strategies throw.
+      // 'ingest-react' (Track N, N1) is assigned here purely structurally
+      // (surface === 'dom'), same as 'ingest-three'/'ingest-pixi'.
       readonly identity: 'ingest-three' | 'ingest-pixi' | 'ingest-react';
       readonly surface: 'three' | 'canvas' | 'dom';
-      readonly strategy: IngestStrategy;
-      readonly entryHtml: string | undefined;
       /**
        * Project-relative ES module declaring `window.vgaiGame` beside a
        * pristine copy. OPTIONAL rather than required-and-possibly-undefined
-       * (the shape its siblings above use) because it is read by exactly one
-       * mount route: every other construction site of this type — the ingest
-       * routes' own fixtures included — has nothing to say about it, and
-       * requiring the key would only make them all say `undefined`.
+       * (the shape its siblings above use) because most ingested games have
+       * nothing to say about it, and requiring the key would only make every
+       * construction site say `undefined`.
        */
       readonly contractShim?: string | undefined;
+      /**
+       * Project-relative ES module that writes this game'''s own DATA file back
+       * (see the field'''s schema description). Same OPTIONAL shape and same
+       * reason as {@link contractShim}: a game whose truth is entirely source
+       * declares nothing here.
+       */
+      readonly dataWriter?: string | undefined;
       readonly assets: Record<string, string> | undefined;
       readonly domStubs: string[] | undefined;
       readonly captureTimeoutMs: number | undefined;
-      /** Iframe-reachable-multi mount fields. */
-      readonly bundleUrl: string | undefined;
-      readonly baseHref: string | undefined;
-      readonly assetBaseUrl: string | undefined;
-      readonly extraDeps: string[] | undefined;
-      readonly pixiModuleUrl: string | undefined;
-      readonly bodyHtml: string | undefined;
     };
 
 export interface ResolvedAdapterRoot {
@@ -90,8 +76,6 @@ export interface ResolvedAdapterRoot {
    *  `manifest/schema.ts`'s `dev` field for the four readers. */
   readonly dev: boolean;
   readonly loop: 'gated' | 'self-driven';
-  /** Every optional resolved: both contexts always present (§4/§5). */
-  readonly capabilities: { readonly local: Tier; readonly hosted: Tier };
 }
 
 export interface ResolvedGameManifest {
@@ -104,6 +88,8 @@ export interface ResolvedGameManifest {
   readonly roots: readonly ResolvedAdapterRoot[];
   readonly server: { readonly room: string; readonly module: string } | undefined;
   readonly resolution: { readonly width: number; readonly height: number } | undefined;
+  /** Construction-time renderer properties no world can declare for itself — see the schema. */
+  readonly rendering: { readonly antialias: boolean } | undefined;
   readonly authoring:
     | {
         readonly hierarchy?:
@@ -149,55 +135,6 @@ export interface ResolvedGameManifest {
   readonly learn: LearnMetadata | undefined;
 }
 
-// ---------------------------------------------------------------------------
-// §4 — the per-context ceiling table (named + exported so the tier-table test
-// can pin its rows against this).
-// ---------------------------------------------------------------------------
-
-/**
- * Ceiling (maximum legal declared `Tier`) per adapter type and delivery
- * context. `default` roots are always first-party in both contexts (D6/§2 —
- * a first-party root is fully vgai-native everywhere). `ingest` roots are
- * ceilinged by their own capture `strategy`: locally the local CLI's Vite
- * pipeline gives bundler dedupe, so every strategy reaches its own natural
- * rung; hosted has no bundler (esbuild-wasm + externals only), and a
- * `deduped` root is DEFINED by being source built through our pipeline — no
- * prebuilt bundle exists to fall back to an iframe rung, and nothing
- * implements a hosted build for it, so hosted is `unsupported` (honesty over
- * optimism; if the hosted esbuild-wasm path ever proves capable, raising
- * this ceiling is a non-breaking widening). `shared`/`iframe-reachable`/
- * `opaque-embed` don't depend on a bundler either way, so they carry through
- * unchanged. `module` adapters have no derivable ceiling ("a custom
- * adapter's reach is not derivable", §4) — modeled here as `first-party`
- * (the top rank), i.e. no ceiling actually constrains a module adapter's
- * declared tier; the loader instead requires the tier to be declared
- * explicitly for module roots (see `resolveCapabilities`), since there is no
- * default to derive.
- */
-export const CAPABILITY_CEILINGS = {
-  builtin: { local: 'first-party', hosted: 'first-party' },
-  ingest: {
-    shared: { local: 'shared', hosted: 'shared' },
-    deduped: { local: 'deduped', hosted: 'unsupported' },
-    'iframe-reachable': { local: 'iframe-reachable', hosted: 'iframe-reachable' },
-    'opaque-embed': { local: 'opaque-embed', hosted: 'opaque-embed' },
-  },
-  module: { local: 'first-party', hosted: 'first-party' },
-} as const satisfies Record<
-  string,
-  { local: Tier; hosted: Tier } | Record<IngestStrategy, { local: Tier; hosted: Tier }>
->;
-
-/** Total order over `Tier` (§4: `first-party > shared ≈ deduped > iframe-reachable > opaque-embed > unsupported`). */
-const TIER_RANK: Record<Tier, number> = {
-  'first-party': 5,
-  shared: 4,
-  deduped: 4,
-  'iframe-reachable': 3,
-  'opaque-embed': 2,
-  unsupported: 1,
-};
-
 /** Default relative path for `server.module` when omitted (§3) — the scaffolded Colyseus bootstrap. */
 export const DEFAULT_SERVER_MODULE = 'server/colyseus-setup.ts';
 
@@ -235,18 +172,14 @@ function checkAdapterEntryRules(root: AdapterRoot): void {
         '`entry` — a built-in adapter root is authored as an entry module.',
     );
   }
+  if (typeof adapter === 'object' && 'ingest' in adapter && !root.entry) {
+    throw new Error(
+      `Game manifest: root "${root.id}" is an { ingest } root but declares no \`entry\` — the ` +
+        "game's own entry module is what the host imports.",
+    );
+  }
 }
 
-// Historical note (Track N, N1): this file used to reject EVERY `kind:
-// 'react'` + `{ ingest }` root outright here (`checkReactAdapterRestriction`,
-// citing "no react ingest program is un-parked"). Track N un-parks exactly
-// that program — react+ingest is now a structurally legal combination,
-// resolved to the `'ingest-react'` identity by `resolveAdapter` below like
-// any other ingest root. There is nothing left to reject at THIS layer: the
-// v1 "deduped strategy only" restriction is an editor-resolver concern (D-N3),
-// not a manifest-shape concern — see the `ResolvedAdapter` type's comment
-// above.
-
 // ---------------------------------------------------------------------------
 // Resolution (§5)
 // ---------------------------------------------------------------------------
@@ -268,8 +201,7 @@ function resolveAdapter(root: AdapterRoot): ResolvedAdapter {
   }
 
   // isIngestAdapter (Track N, N1: 'ingest-react' joins 'ingest-three'/
-  // 'ingest-pixi' — see the `ResolvedAdapter` type's comment above for why
-  // this stays strategy-agnostic here).
+  // 'ingest-pixi').
   const identity =
     adapter.surface === 'three'
       ? 'ingest-three'
@@ -281,62 +213,14 @@ function resolveAdapter(root: AdapterRoot): ResolvedAdapter {
     type: 'ingest',
     identity,
     surface: adapter.surface,
-    strategy: ingest.strategy,
-    entryHtml: ingest.entryHtml,
     contractShim: ingest.contractShim,
+    dataWriter: ingest.dataWriter,
     assets: ingest.assets,
     domStubs: ingest.domStubs,
     captureTimeoutMs: ingest.captureTimeoutMs,
-    bundleUrl: ingest.bundleUrl,
-    baseHref: ingest.baseHref,
-    assetBaseUrl: ingest.assetBaseUrl,
-    extraDeps: ingest.extraDeps,
-    pixiModuleUrl: ingest.pixiModuleUrl,
-    bodyHtml: ingest.bodyHtml,
   };
 }
 
-function ceilingFor(adapter: RootAdapter, context: 'local' | 'hosted'): Tier {
-  if (typeof adapter === 'string') return CAPABILITY_CEILINGS.builtin[context];
-  if (isModuleAdapter(adapter)) return CAPABILITY_CEILINGS.module[context];
-  return CAPABILITY_CEILINGS.ingest[adapter.ingest.strategy][context];
-}
-
-function resolveCapabilities(root: AdapterRoot): { local: Tier; hosted: Tier } {
-  const contexts = ['local', 'hosted'] as const;
-  const result = {} as { local: Tier; hosted: Tier };
-
-  for (const context of contexts) {
-    const declared = root.capabilities?.[context];
-    if (declared !== undefined) {
-      const ceiling = ceilingFor(root.adapter, context);
-      if (TIER_RANK[declared] > TIER_RANK[ceiling]) {
-        throw new Error(
-          `Game manifest: root "${root.id}": declared capabilities.${context} tier "${declared}" ` +
-            `exceeds the "${ceiling}" ceiling for this adapter in the ${context} context (§4). ` +
-            'Under-claiming (including `unsupported`) is legal; over-claiming is not.',
-        );
-      }
-      result[context] = declared;
-      continue;
-    }
-
-    // Omitted -> derive.
-    if (typeof root.adapter === 'string') {
-      result[context] = 'first-party';
-    } else if (isModuleAdapter(root.adapter)) {
-      throw new Error(
-        `Game manifest: root "${root.id}": { module } adapter requires an explicit ` +
-          `capabilities.${context} declaration — a custom adapter's reach is not derivable (§4).`,
-      );
-    } else {
-      result[context] = CAPABILITY_CEILINGS.ingest[root.adapter.ingest.strategy][context];
-    }
-  }
-
-  return result;
-}
-
 function checkEngineVersionPin(version: string): void {
   if (!SEMVER_RE.test(version)) {
     throw new Error(
@@ -348,17 +232,17 @@ function checkEngineVersionPin(version: string): void {
 
 /**
  * Resolve one already-Zod-validated root entry into its `ResolvedAdapterRoot`
- * (adapter identity, capabilities, and a pass-through of every other field).
+ * (adapter identity, and a pass-through of every other field).
  * Every `AdapterRoot` field participates here or in a check above:
  * `id` drives uniqueness; `adapter` (incl. its surface and
- * `module`/`ingest.*` sub-fields) drives identity + capability-ceiling
+ * `module`/`ingest.*` sub-fields) drives adapter identity
  * resolution; `entry` drives the entry cross-field rule and is
  * carried through; `zOrder` drives the final sort; `pausable`/`loop` are
  * carried through as-is (their consumers are the runtime/CLI, T3.2/T3.3);
  * `dev` is carried through for the four dev-layer readers (`mountManifestRoots`'s
  * ship gate, the host's topmost stacking pass, the play compositor's capture
  * exclusion, and the editor's chrome-not-content seam);
- * `capabilities.{local,hosted}` drive tier resolution; `description` (T3.3
+ * `description` (T3.3
  * slice 3) is carried through as-is — its consumer today is
  * `resolveIngestDescriptor` (packages/editor/src/adapter-resolver.ts), which
  * threads an ingest-three root's description into `IngestGame.description`.
@@ -377,7 +261,6 @@ function resolveRoot(root: AdapterRoot): ResolvedAdapterRoot {
     pausable: root.pausable,
     dev: root.dev,
     loop: root.loop,
-    capabilities: resolveCapabilities(root),
   };
 }
 
@@ -404,7 +287,7 @@ export function loadGameManifest(raw: unknown): ResolvedGameManifest {
     // raw multi-issue dump, because each one already reads as a finished
     // sentence naming the offending ids. Every other schema violation keeps
     // propagating as the raw `ZodError` it always has (unchanged behavior,
-    // e.g. the iframe-reachable field-exclusivity / manifestVersion checks).
+    // e.g. an unrecognized key or a bad `manifestVersion`).
     const compositionIssue = parsed.error.issues.find(
       (issue) =>
         issue.message.startsWith('Game manifest: duplicate root id') ||
@@ -441,6 +324,7 @@ export function loadGameManifest(raw: unknown): ResolvedGameManifest {
     roots,
     server,
     resolution: manifest.resolution,
+    rendering: manifest.rendering,
     authoring: manifest.authoring,
     debug: manifest.debug,
     determinism: manifest.determinism,

package/src/manifest/schema.ts

@@ -9,8 +9,8 @@
 //
 // 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
+// doc's §3 sketch names the bare consts (`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
@@ -28,32 +28,6 @@ import { z } from 'zod';
  */
 export const GAME_MANIFEST_VERSION = 2 as const;
 
-// ---------------------------------------------------------------------------
-// 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
-]);
-export type IngestStrategy = z.infer<typeof IngestStrategySchema>;
-
-// ---------------------------------------------------------------------------
-// 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
-]);
-export type Tier = z.infer<typeof TierSchema>;
-
 // ---------------------------------------------------------------------------
 // Root adapter identity. The adapter is the sole discriminator: a root never
 // repeats its rendering substrate in a sibling `kind` field. Module and ingest
@@ -160,39 +134,51 @@ export const RootAdapterSchema = z
             .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).',
-                ),
               contractShim: z
                 .string()
                 .optional()
                 .describe(
                   "Project-relative path to a HOST-ADDED ES module that declares this game's " +
                     '`window.vgaiGame` contract (adapter/ingest/game-contract.ts) WITHOUT editing a ' +
-                    'vendored byte — the pristine-copy door. The host injects it as a ' +
-                    '`<script type="module">` into the assembled iframe document AFTER the game`s own ' +
-                    'importmap (moving a module load ahead of an import map invalidates the map) and ' +
-                    'BEFORE the game`s entry module, so deferred module scripts run it first. ' +
+                    'vendored byte — the pristine-copy door. The host imports it immediately BEFORE ' +
+                    "the game's own entry module, in the editor's realm. " +
                     'TIMING CONTRACT, which a shim author must obey: because it runs before the ' +
-                    'game`s entry, it MUST assign `window.vgaiGame` SYNCHRONOUSLY at top level — the ' +
-                    'host waits for that assignment and fails the mount by name if it never arrives. ' +
+                    'game`s entry, it MUST assign `window.vgaiGame` SYNCHRONOUSLY at top level. ' +
                     'Anything that needs the game`s own modules must be LAZY: a dynamic `import()` ' +
                     'INSIDE each verb/provider closure, resolved at call time. Importing a game module ' +
                     'eagerly from the shim would evaluate it ahead of the game`s own entry and reorder ' +
-                    'its module side effects. Read by the vendored/self-hosted three route only ' +
-                    '(strategy `iframe-reachable` with `entryHtml`); declaring it elsewhere is a ' +
-                    'schema error rather than a silently dead field.',
+                    'its module side effects. ' +
+                    'Every such `import()` MUST take a STRING LITERAL, never a variable/table lookup. ' +
+                    'A variable specifier is not statically analyzable, so the dev server leaves it ' +
+                    'alone and it resolves at runtime against the shim`s own `/@fs/` url — while the ' +
+                    'game`s entry has had ITS relative imports rewritten to whatever url the server ' +
+                    'considers canonical for those files. Module identity is per-url, so the shim ' +
+                    'silently binds a SECOND, freshly-evaluated copy of the whole game and every ' +
+                    'provider reports a game that never started. Measured on three-descent: 285 ' +
+                    'segments through the game`s graph, 0 through the shim`s, and no error anywhere.',
+                ),
+              dataWriter: z
+                .string()
+                .optional()
+                .describe(
+                  "Project-relative path to a HOST-ADDED ES module that writes this game's own " +
+                    'DATA file back — the sibling of a source write for a game whose authorable ' +
+                    'truth is not source. Descent places its robots, powerups and hostages in ' +
+                    'binary records inside `descent.hog`, reaching no source literal, so an ' +
+                    'authored move of one is an edit to that file and nothing else can write it. ' +
+                    'The module declares two exports and the host knows nothing else about it: ' +
+                    '`dataFile` (a project-relative string — the ONE file this writer edits) and ' +
+                    '`planDataEdit(bytes, {record, property, baseline, next})`, which returns ' +
+                    '`{changed: true, bytes}` or `{changed: false, reason}` and may be async. ' +
+                    'It is loaded in the editor realm beside the game, so it may `import()` the ' +
+                    "game's own modules to resolve what only a running game knows (Descent's " +
+                    'writer asks the game`s own `find_point_seg` which segment a moved object ' +
+                    'landed in, and refuses "outside the mine" rather than writing data the game ' +
+                    'would read back wrong). It NEVER fabricates: a record it cannot address, or ' +
+                    'a property it does not model, is a named refusal. ' +
+                    'An object is anchored to a record by carrying `userData.vgaiRecordIndex` — ' +
+                    'the game declares that identity itself (a recorded patch or a shim); the ' +
+                    'host never infers one.',
                 ),
               assets: z
                 .record(z.string(), z.string())
@@ -210,168 +196,16 @@ export const RootAdapterSchema = 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).',
+                  "How long the host waits for this game's first captured frame before the mount " +
+                    'FAILS by name. A game that needs a long boot (streamed world assets, a menu ' +
+                    'the player must clear) raises it; the default is 10s.',
                 ),
             })
+            .strict()
             .describe(
               'Ingest adapter configuration for an unmodified game (a repo-vendored game or your ' +
                 'own external folder)',
-            )
-            // `contractShim` is injected into the assembled ENTRY DOCUMENT, so
-            // the ONLY route that can read it is the self-hosted one
-            // (`iframe-reachable` + `entryHtml`,
-            // ingest-self-hosted-three-adapter.ts). An `opaque-embed` entry
-            // document is hosted sandboxed with no host wiring, and a `bundleUrl`
-            // mount has no game document at all — under either, a declared shim
-            // would be a silently dead declaration, the exact failure the
-            // dead-field-under-wrong-variant checks below exist to prevent. Its
-            // own `.superRefine` rather than a branch inside the next one: they
-            // check unrelated invariants, and folding them together only made
-            // one function harder to read.
-            .superRefine((ingest, ctx) => {
-              if (
-                ingest.contractShim === undefined ||
-                (ingest.strategy === 'iframe-reachable' && ingest.entryHtml !== undefined)
-              ) {
-                return;
-              }
-              ctx.addIssue({
-                code: z.ZodIssueCode.custom,
-                message:
-                  '`contractShim` is read ONLY by the self-hosted entry-document route, so it ' +
-                  "requires strategy 'iframe-reachable' together with `entryHtml` (got strategy " +
-                  `"${ingest.strategy}"${ingest.entryHtml === undefined ? ' and no `entryHtml`' : ''}) — ` +
-                  "the host injects the shim module into the GAME'S OWN entry HTML " +
-                  '(ingest-self-hosted-three-adapter.ts), and no other mount has such a document.',
-                path: ['contractShim'],
-              });
-            })
-            .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: ReadonlyArray<
-                readonly [
-                  key:
-                    | 'bundleUrl'
-                    | 'baseHref'
-                    | 'assetBaseUrl'
-                    | 'extraDeps'
-                    | 'pixiModuleUrl'
-                    | 'bodyHtml',
-                  present: boolean,
-                ]
-              > = [
-                ['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(),
     ]),
@@ -439,21 +273,7 @@ export const AdapterRootSchema = z
       .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.',
+          '(composited, unsynchronized)',
       ),
   })
   .strict();
@@ -701,6 +521,28 @@ export const GameManifestSchema = z
       })
       .optional()
       .describe('Canvas resolution'),
+    rendering: z
+      .object({
+        antialias: z
+          .boolean()
+          .describe(
+            'Whether every three root is built with a multisampled drawing buffer. This is the ' +
+              'ONE render property a world cannot declare for itself (world3d-react/' +
+              'renderer-config.ts): a WebGL context fixes its sample count at CREATION from this ' +
+              'boolean, long before a world mounts, so it belongs to the PROJECT. The runtime ' +
+              'reader is mount-manifest.ts, which threads it into createHostRenderer for each ' +
+              'three root. WebGL exposes no sample COUNT — the implementation picks one (4x on ' +
+              'every desktop browser measured), so a source engine that authored 8x/16x gets ' +
+              'multisampling but not its exact count.',
+          ),
+      })
+      .strict()
+      .optional()
+      .describe(
+        'Construction-time renderer properties, which no world can declare after the fact. ' +
+          'Everything a world CAN declare (tone mapping, output colour space, clear colour, ' +
+          "shadow filter) lives on the world's own renderer config instead.",
+      ),
     debug: z
       .object({
         allowInProduction: z

package/src/pixi/index.ts

@@ -4,7 +4,7 @@
  * PixiJS is opt-in: the engine core never imports it, so a three-only bundle
  * never pays for it. What lives here is what the host needs to mount and
  * inspect a PixiJS game it did not write — the render-call capture trap, the
- * in-realm and iframe mounts, the live display-tree authoring adapter, and the
+ * in-realm mount, the live display-tree authoring adapter, and the
  * Rapier-2D handle registry the editor's transform coordination reads.
  */
 
@@ -16,20 +16,7 @@ export {
   type Property2D,
   type Transform2DValue,
 } from './authoring';
-export {
-  type ExtraDepsResolution2D,
-  type IngestGame2D,
-  type IngestMount2D,
-  mountIngestGame2D,
-} from './ingest';
-export {
-  type EmbedMount2D,
-  type IframeReachableMount2D,
-  type IframeReachableMultiOpts,
-  mountIngestGame2DEmbed,
-  mountIngestGame2DIframeReachable,
-  mountIngestGame2DIframeReachableMulti,
-} from './ingest-iframe';
+export { type IngestGame2D, type IngestMount2D, mountIngestGame2D } from './ingest';
 export {
   createPhysics2DRegistry,
   type Physics2DRefs,