@vgai/cli 0.5.10 → 0.5.12

package/README.md

@@ -74,7 +74,7 @@ vgai upgrade [--report]         report engine drift vs. the project's engine pin
                                 present reports "not a scaffolded project" instead of
                                 dumping the whole template — see `vgai validate` instead)
 vgai validate [folder]          in-process: validate vgai.project.json, check every declared
-                                entry/scene/entryHtml/bundleUrl file exists, print the engine
+                                entry/contractShim file exists, print the engine
                                 pin (default: cwd) — no monorepo Vite/editor stack required
                                 Exit codes: 0 valid, 1 invalid manifest or missing file, 2 usage
 npm run vgai -- add deploy-vercel      add project-owned Vercel scripts/config

package/dist/index.js

@@ -413,6 +413,51 @@ var init_client = __esm({
         const data = await this.command({ type: "inspect" });
         return data.subject;
       }
+      /**
+       * The HIERARCHY PANEL's actual rendered row tree, as data.
+       *
+       * The same rows a human is looking at: the adapter's tree after the component
+       * marks fold implementation subtrees, after the internals reveal, after the
+       * document promotion, the child cap, the collapse state, the search filter
+       * and the selection scope. Works in play mode and edit mode alike — the
+       * answer reports which (`playState`, `activeViewportTab`), because a
+       * play-mode tree and an edit-mode tree come from different adapters.
+       *
+       * Deliberately NOT `status().entities`, which walks the raw adapter tree and
+       * therefore answers a different question: a panel defect is invisible in it.
+       *
+       * Each row carries `childCount` (what its caret opens), `internalChildCount`
+       * (what is folded behind "Reveal Internals") and `expandable` (whether the
+       * panel draws a caret at all) — so "this subtree exists but the UI offers no
+       * way to open it" is a readable fact rather than something only a human
+       * squinting at the panel can notice.
+       *
+       * Rejects, naming the panel, when no hierarchy panel is mounted: an empty
+       * tree would be a fabricated answer about a surface nobody is being shown.
+       */
+      async hierarchy() {
+        const data = await this.command({ type: "hierarchy" });
+        return data.hierarchy;
+      }
+      /** Write one editable path through the active Inspector's own IO. */
+      async setInspectionField(path, value) {
+        const data = await this.command({
+          type: "set-inspection-field",
+          path,
+          value
+        });
+        return data.subject;
+      }
+      /**
+       * Undo / redo one project transaction — the same queue the keyboard shortcut
+       * drives. `moved` is false when there was nothing left in that direction.
+       */
+      async undo() {
+        return this.command({ type: "undo" });
+      }
+      async redo() {
+        return this.command({ type: "redo" });
+      }
       /** Read the editor's actual current durable projection. */
       async currentView() {
         const data = await this.command({ type: "current-view" });
@@ -425,7 +470,30 @@ var init_client = __esm({
           ...size === void 0 ? {} : { size }
         });
       }
+      /**
+       * Read or drive the ACTIVE center document's own DOM — the scoped
+       * editor-chrome door, and the read/gesture half of the same subject
+       * {@link captureActiveDocument} photographs. NOT play-mode gated, and NOT
+       * page automation: a target outside the active document's container is
+       * refused by name. Design and scope contract:
+       * `packages/editor/src/editor-document-probe.ts`.
+       */
+      async documentProbe(step) {
+        return this.command({ type: "document-probe", step });
+      }
       // --- Display (set semantics) ---
+      /**
+       * The Game document's "Persist to game source" consent, over the relay —
+       * the same session-scoped switch the checkbox flips, refused for the same
+       * reasons (it answers with the server's own words when the base cannot be
+       * written). `recorder` names who accounts for the diff a write produces.
+       */
+      async setSourcePersistConsent(enabled) {
+        return this.command({
+          type: "set-source-persist-consent",
+          enabled
+        });
+      }
       async setGrid(enabled) {
         await this.command({ type: "set-grid", enabled });
       }
@@ -18296,6 +18364,9 @@ var init_inspection_operations = __esm({
       id: external_exports.string(),
       title: external_exports.string(),
       kindLabel: external_exports.string().optional(),
+      note: external_exports.string().optional().describe(
+        "The identity row\u2019s own line \u2014 for an ingest mount, where the object was CONSTRUCTED (`Source \xB7 game.js:271`), or the reason it has no such line."
+      ),
       hint: external_exports.string().optional().describe("The quiet line a subject with nothing to edit carries."),
       presentation: external_exports.object({
         preferred: external_exports.string().describe("The surface\u2019s presentation affinity: card|column."),
@@ -18311,6 +18382,7 @@ var init_inspection_operations = __esm({
           disabled: external_exports.boolean().optional()
         })
       ),
+      related: external_exports.array(external_exports.object({ id: external_exports.string(), title: external_exports.string() })).describe("Agent-visible counterparts of the inspector\u2019s related-document buttons."),
       sections: external_exports.array(InspectedSectionSchema)
     });
     NothingInspectedSchema = external_exports.object({ none: external_exports.literal(true).describe("There is no inspector showing.") }).describe("Nothing is being inspected.");
@@ -39603,36 +39675,12 @@ function rejectRemovedRootAdapterSpelling(value, ctx) {
 function rootMedium(root) {
   return typeof root.adapter === "string" ? root.adapter : root.adapter.surface;
 }
-var GAME_MANIFEST_VERSION, IngestStrategySchema, TierSchema, REMOVED_SURFACE_SPELLING, REMOVED_BARE_ADAPTER_SPELLING, RootAdapterSchema, AdapterRootSchema, LearnKindSchema, LearnDifficultySchema, LearnMetadataSchema, GameManifestSchema;
+var GAME_MANIFEST_VERSION, REMOVED_SURFACE_SPELLING, REMOVED_BARE_ADAPTER_SPELLING, RootAdapterSchema, AdapterRootSchema, LearnKindSchema, LearnDifficultySchema, LearnMetadataSchema, GameManifestSchema;
 var init_schema = __esm({
   "../engine/src/manifest/schema.ts"() {
     "use strict";
     init_zod();
     GAME_MANIFEST_VERSION = 2;
-    IngestStrategySchema = external_exports.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
-    ]);
-    TierSchema = external_exports.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
-    ]);
     REMOVED_SURFACE_SPELLING = {
       threejs: "three",
       pixijs: "canvas",
@@ -39654,11 +39702,11 @@ var init_schema = __esm({
         external_exports.object({
           surface: external_exports.enum(["three", "canvas", "dom"]).describe("Native surface captured from the unmodified game"),
           ingest: external_exports.object({
-            strategy: IngestStrategySchema.describe(
-              "Capture mechanics rung this ingested root uses (\xA74) \u2014 also the root`s natural local capability tier"
+            contractShim: external_exports.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 \u2014 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. 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. 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 \u2014 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."
             ),
-            entryHtml: external_exports.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 \u2014 use `bundleUrl` instead, the wired reachable route)."
+            dataWriter: external_exports.string().optional().describe(
+              "Project-relative path to a HOST-ADDED ES module that writes this game's own DATA file back \u2014 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 \u2014 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` \u2014 the game declares that identity itself (a recorded patch or a shim); the host never infers one."
             ),
             assets: external_exports.record(external_exports.string(), external_exports.string()).optional().describe(
               "Path-substring -> served-URL rewrites for this ingested game (IngestGame.assets today)"
@@ -39667,63 +39715,11 @@ var init_schema = __esm({
               "DOM API stub ids this ingested game requires to run headlessly/in-realm"
             ),
             captureTimeoutMs: external_exports.number().optional().describe(
-              "How long to wait for capture before REPORTING the degrade loudly \u2014 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: external_exports.string().optional().describe(
-              "Absolute URL of the externalized built game bundle \u2014 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 \u2014 `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: external_exports.string().optional().describe(
-              "Iframe <base href> so the game's relative asset URLs resolve (iframe-reachable only)."
-            ),
-            assetBaseUrl: external_exports.string().optional().describe(
-              "Host-side basePath forced onto the trapped runtime's own asset resolution \u2014 pixi's `Assets.init` for a canvas root, three's `DefaultLoadingManager.setURLModifier` for a three root (D-W1) \u2014 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 \u2014 a document.write iframe keeps the parent window.location)."
-            ),
-            extraDeps: external_exports.array(external_exports.string()).optional().describe(
-              "Bare specifiers of this root's externalized deps beyond its own runtime (pixi.js/three \u2014 e.g. '@pixi/sound', 'gsap'). Resolved by the editor's host-namespace registry into module namespaces when known (D-P1 \u2014 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: external_exports.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 \u2014 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 \u2014 three has no version-skew mount this wave (D-W7: a hypothetical `threeModuleUrl` is explicitly parked, no consumer exists).'
-            ),
-            bodyHtml: external_exports.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."
             )
-          }).describe(
+          }).strict().describe(
             "Ingest adapter configuration for an unmodified game (a repo-vendored game or your own external folder)"
-          ).superRefine((ingest, ctx) => {
-            const iframeOnlyFields = [
-              ["bundleUrl", ingest.bundleUrl !== void 0],
-              ["baseHref", ingest.baseHref !== void 0],
-              ["assetBaseUrl", ingest.assetBaseUrl !== void 0],
-              ["extraDeps", ingest.extraDeps !== void 0],
-              ["pixiModuleUrl", ingest.pixiModuleUrl !== void 0],
-              ["bodyHtml", ingest.bodyHtml !== void 0]
-            ];
-            if (ingest.strategy !== "iframe-reachable") {
-              for (const [key, present] of iframeOnlyFields) {
-                if (present) {
-                  ctx.addIssue({
-                    code: external_exports.ZodIssueCode.custom,
-                    message: `\`${key}\` is only legal when strategy is 'iframe-reachable' (got "${ingest.strategy}") \u2014 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 !== void 0;
-            const hasEntryHtml = ingest.entryHtml !== void 0;
-            if (hasBundleUrl === hasEntryHtml) {
-              ctx.addIssue({
-                code: external_exports.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) \u2014 ${hasBundleUrl ? "both are present" : "neither is present"}.`,
-                path: hasBundleUrl ? ["bundleUrl"] : ["entryHtml"]
-              });
-            }
-          })
+          )
         }).strict()
       ])
     ).describe(
@@ -39748,17 +39744,7 @@ var init_schema = __esm({
         "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: external_exports.enum(["gated", "self-driven"]).default("gated").describe(
-        'gated: host-driven loop (default). self-driven: this root drives its own loop (the "composited, unsynchronized" tier) \u2014 an axis independent of capability tier'
-      ),
-      capabilities: external_exports.object({
-        local: TierSchema.optional().describe(
-          "Declared capability tier when served via the local CLI (Vite pipeline); omitted -> derived (\xA74)"
-        ),
-        hosted: TierSchema.optional().describe(
-          "Declared capability tier when served hosted (no bundler: esbuild-wasm + externals only); omitted -> derived (\xA74)"
-        )
-      }).optional().describe(
-        "Per-delivery-context capability tier declarations (\xA74). Declaring above the adapter's ceiling for that context is an error; declaring at or below it (including `unsupported`) is legal."
+        "gated: host-driven loop (default). self-driven: this root drives its own loop (composited, unsynchronized)"
       )
     }).strict();
     LearnKindSchema = external_exports.enum(["starter", "feature", "sample-game", "lesson-companion"]).describe(
@@ -39857,6 +39843,13 @@ var init_schema = __esm({
         width: external_exports.number().describe("Canvas width in pixels"),
         height: external_exports.number().describe("Canvas height in pixels")
       }).optional().describe("Canvas resolution"),
+      rendering: external_exports.object({
+        antialias: external_exports.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 \u2014 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: external_exports.object({
         allowInProduction: external_exports.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)."
@@ -39913,6 +39906,11 @@ function checkAdapterEntryRules(root) {
       `Game manifest: root "${root.id}" uses the '${adapter}' adapter but declares no \`entry\` \u2014 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\` \u2014 the game's own entry module is what the host imports.`
+    );
+  }
 }
 function resolveAdapter(root) {
   const { adapter } = root;
@@ -39933,51 +39931,13 @@ function resolveAdapter(root) {
     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
+    captureTimeoutMs: ingest.captureTimeoutMs
   };
 }
-function ceilingFor(adapter, context) {
-  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) {
-  const contexts = ["local", "hosted"];
-  const result = {};
-  for (const context of contexts) {
-    const declared = root.capabilities?.[context];
-    if (declared !== void 0) {
-      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 (\xA74). Under-claiming (including \`unsupported\`) is legal; over-claiming is not.`
-        );
-      }
-      result[context] = declared;
-      continue;
-    }
-    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 \u2014 a custom adapter's reach is not derivable (\xA74).`
-      );
-    } else {
-      result[context] = CAPABILITY_CEILINGS.ingest[root.adapter.ingest.strategy][context];
-    }
-  }
-  return result;
-}
 function checkEngineVersionPin(version2) {
   if (!SEMVER_RE.test(version2)) {
     throw new Error(
@@ -39997,8 +39957,7 @@ function resolveRoot2(root) {
     zOrder: root.zOrder,
     pausable: root.pausable,
     dev: root.dev,
-    loop: root.loop,
-    capabilities: resolveCapabilities(root)
+    loop: root.loop
   };
 }
 function loadGameManifest(raw) {
@@ -40031,6 +39990,7 @@ function loadGameManifest(raw) {
     roots,
     server: server2,
     resolution: manifest.resolution,
+    rendering: manifest.rendering,
     authoring: manifest.authoring,
     debug: manifest.debug,
     determinism: manifest.determinism,
@@ -40038,29 +39998,11 @@ function loadGameManifest(raw) {
     learn: manifest.learn
   };
 }
-var CAPABILITY_CEILINGS, TIER_RANK, DEFAULT_SERVER_MODULE, SEMVER_RE;
+var DEFAULT_SERVER_MODULE, SEMVER_RE;
 var init_load = __esm({
   "../engine/src/manifest/load.ts"() {
     "use strict";
     init_schema();
-    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" }
-    };
-    TIER_RANK = {
-      "first-party": 5,
-      shared: 4,
-      deduped: 4,
-      "iframe-reachable": 3,
-      "opaque-embed": 2,
-      unsupported: 1
-    };
     DEFAULT_SERVER_MODULE = "server/colyseus-setup.ts";
     SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-.]+)?(?:\+[0-9A-Za-z-.]+)?$/;
   }
@@ -42651,7 +42593,7 @@ function createIngestManifest(inspection, options) {
     roots: [
       {
         id: "game",
-        adapter: { surface, ingest: { strategy: "deduped" } },
+        adapter: { surface, ingest: {} },
         entry
       }
     ]
@@ -304437,12 +304379,54 @@ var require_lib = __commonJS({
   }
 });
 
+// ../vgai-live/dist/editor-document.js
+var LiveEditorDocument;
+var init_editor_document = __esm({
+  "../vgai-live/dist/editor-document.js"() {
+    "use strict";
+    LiveEditorDocument = class {
+      #client;
+      constructor(client) {
+        this.#client = client;
+      }
+      /** Read matching elements inside the active document: tag, text, attributes,
+       *  value/checked/disabled and rect. `matched` is the total before `limit`. */
+      async query(selector, options) {
+        return this.#probe({
+          action: "query",
+          selector,
+          ...options?.limit === void 0 ? {} : { limit: options.limit }
+        });
+      }
+      /** A REAL pointer gesture (pointerdown/mousedown/focus/pointerup/mouseup/click)
+       *  — not `element.click()`, which a `pointerdown` listener never sees. */
+      async click(selector, options) {
+        return this.#probe({
+          action: "click",
+          selector,
+          ...options?.index === void 0 ? {} : { index: options.index }
+        });
+      }
+      /** A real keydown/keyup on the target, or on whatever inside the document has focus. */
+      async key(key, options) {
+        return this.#probe({ action: "key", key, ...options ?? {} });
+      }
+      /** A real `ClipboardEvent` carrying `text/plain` — the gesture nothing else
+       *  in the product can produce. */
+      async paste(text, options) {
+        return this.#probe({ action: "paste", text, ...options ?? {} });
+      }
+      #probe(step) {
+        return this.#client.documentProbe(step);
+      }
+    };
+  }
+});
+
 // ../vgai-live/dist/editor.js
 function inferAssetKind(path) {
   if (path.endsWith(".prefab.json"))
     return "prefab";
-  if (path.endsWith(".mat.json"))
-    return "material";
   const dot = path.lastIndexOf(".");
   const ext = dot >= 0 ? path.slice(dot).toLowerCase() : "";
   return EXTENSION_KIND[ext] ?? "json";
@@ -304451,6 +304435,7 @@ var EXTENSION_KIND, LiveEditor;
 var init_editor2 = __esm({
   "../vgai-live/dist/editor.js"() {
     "use strict";
+    init_editor_document();
     EXTENSION_KIND = {
       ".glb": "model",
       ".gltf": "model",
@@ -304460,10 +304445,15 @@ var init_editor2 = __esm({
       ".webp": "image",
       ".gif": "image",
       ".svg": "image",
+      ".hdr": "image",
+      ".exr": "image",
       ".mp3": "audio",
       ".ogg": "audio",
       ".wav": "audio",
-      ".flac": "audio"
+      ".flac": "audio",
+      ".glsl": "source",
+      ".vert": "source",
+      ".frag": "source"
     };
     LiveEditor = class {
       /** `#`-private, not `private`: `vgai eval --list` enumerates this object's
@@ -304471,8 +304461,18 @@ var init_editor2 = __esm({
        *  raw `EditorClient` advertised beside them. See `./game-client/`'s
        *  `client.ts` (GameClient's field block) for the full reasoning. */
       #client;
+      /**
+       * The ACTIVE center document's own DOM: read it, click it, key it, paste
+       * into it. The one door onto editor chrome that is not play-mode gated, and
+       * deliberately scoped to that document alone —
+       * `packages/editor/src/editor-document-probe.ts` carries the design and the
+       * refusal contract. Screenshotting the same subject is
+       * {@link LiveEditor.captureActiveDocument}, not a fifth verb here.
+       */
+      document;
       constructor(client) {
         this.#client = client;
+        this.document = new LiveEditorDocument(client);
       }
       /**
        * The active authoring adapter's persistence destination — where a save would
@@ -304624,6 +304624,23 @@ var init_editor2 = __esm({
       async shading(mode) {
         await this.#client.setShadingMode(mode);
       }
+      /**
+       * CONSENT to edits being written into the game's own source files, for this
+       * session — the Game document's "Persist to game source" checkbox, reachable
+       * from a script.
+       *
+       * Off by default every session, on purpose: it is a statement about what you
+       * are doing right now, never a property of the game. With it off, an edit
+       * lives on the running object and says so; with it on, an edit that can be
+       * honestly anchored to the line that CREATED the object is written there,
+       * and one that cannot still says so. Answers with the server's own phrase for
+       * who records the resulting diff — your version control, or a vendored
+       * game's own lock — and refuses, with the reason, where the checkbox is
+       * disabled.
+       */
+      async persistToGameSource(on) {
+        return this.#client.setSourcePersistConsent(on);
+      }
       /**
        * READ the inspector, as data — the serialized inspection subject
        * (`editor.inspect()`; design: `docs/ARCHITECTURE-CORE.md` §Editor chrome,
@@ -304654,6 +304671,51 @@ var init_editor2 = __esm({
       async inspect() {
         return this.#client.inspect();
       }
+      /**
+       * READ the hierarchy panel, as data — the rows a human is looking at right
+       * now, nested exactly as the panel nests them.
+       *
+       * The companion to {@link inspect}: that one answers "what IS the selected
+       * thing", this one answers "what does the tree LOOK LIKE". It is the panel's
+       * own output, not a fresh walk of the scene — the adapter's tree after the
+       * component marks fold implementation subtrees (bones, particle renderers,
+       * instanced pools), after the internals reveal, the document promotion, the
+       * child cap, the collapse state, the search filter and the selection scope.
+       *
+       * Works in play mode and edit mode; the answer says which (`playState`,
+       * `activeViewportTab`), because the two are different adapters and a tree
+       * that looks wrong is very often the wrong adapter's tree.
+       *
+       * Prefer this over `status().entities`, which is deliberately a different
+       * question — the RAW adapter tree, unprojected. A panel that renders the
+       * wrong rows looks perfectly healthy in that facet.
+       *
+       * Each row carries `childCount` (what its caret opens), `internalChildCount`
+       * (what is folded behind "Reveal Internals") and `expandable` (whether the
+       * panel draws a caret at all), so "this subtree exists but nothing in the UI
+       * opens it" is a fact you can read rather than one you have to notice.
+       *
+       * Rejects, naming the panel, when no hierarchy panel is mounted — an empty
+       * tree would be a fabricated answer about a surface nobody is being shown.
+       */
+      async hierarchy() {
+        return this.#client.hierarchy();
+      }
+      /**
+       * Write one editable field from `inspect()` by its stable path, through the
+       * same Inspector IO and persistence boundary the human control uses.
+       */
+      async setField(path, value) {
+        return this.#client.setInspectionField(path, value);
+      }
+      /** Undo / redo one project transaction, through the session's own history
+       *  queue — the same one the keyboard shortcut drives. */
+      async undo() {
+        return this.#client.undo();
+      }
+      async redo() {
+        return this.#client.redo();
+      }
       /** Mirrors `vgai status` — the full live editor state as JSON. */
       async status() {
         return this.#client.getState();
@@ -306322,6 +306384,7 @@ __export(dist_exports, {
   HIDDEN_RECOVERY_STALL_POLLS: () => HIDDEN_RECOVERY_STALL_POLLS,
   HiddenRecoveryDriver: () => HiddenRecoveryDriver,
   LiveEditor: () => LiveEditor,
+  LiveEditorDocument: () => LiveEditorDocument,
   LiveTools: () => LiveTools,
   PageTransport: () => PageTransport,
   RelayTransport: () => RelayTransport,
@@ -306395,6 +306458,7 @@ var init_dist = __esm({
     init_singleton();
     init_tools();
     init_editor2();
+    init_editor_document();
     init_game();
     init_game_client();
     init_session();
@@ -307538,7 +307602,6 @@ function rewritePackageJson(targetDir, slug, engineDir, monoRoot) {
 function resolvePackageRoots() {
   return {
     engineRelPath: "node_modules/@vgai/engine",
-    p2pRelPath: "node_modules/@vgai/p2p-colyseus/",
     editorRelPath: "node_modules/@vgai/editor",
     liveRelPath: "node_modules/@vgai/live",
     sdkRelPath: "node_modules/@vgai/sdk",
@@ -307599,6 +307662,32 @@ function rewriteGameManifest(targetDir, name, slug, template, monoRoot) {
   writeJson(manifestPath, manifest);
   return manifest;
 }
+function repinEngineAfterInstall(targetDir) {
+  const installed = readInstalledVersion(targetDir, "@vgai/engine");
+  if (!installed) return null;
+  const manifestPath = resolveManifestPath(targetDir);
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync12(manifestPath, "utf-8"));
+  } catch {
+    return null;
+  }
+  const engine = manifest["engine"] ?? {};
+  const from = typeof engine["version"] === "string" ? engine["version"] : "";
+  if (from === installed) return null;
+  manifest["engine"] = { ...engine, version: installed };
+  writeJson(manifestPath, manifest);
+  const baselinePath = join14(targetDir, SCAFFOLD_BASELINE_RELATIVE_PATH);
+  try {
+    const baseline = JSON.parse(readFileSync12(baselinePath, "utf-8"));
+    baseline.engineVersion = installed;
+    baseline.files["vgai.project.json"] = hashFile(manifestPath);
+    writeFileSync4(baselinePath, `${JSON.stringify(baseline, null, 2)}
+`, "utf-8");
+  } catch {
+  }
+  return { from, to: installed };
+}
 var REACT_ONLY_PAGE_SOURCE = `export interface ReactGamePageProps {
   readonly lastInput: string;
   readonly title?: string;
@@ -307745,26 +307834,13 @@ function rewriteTsconfig(targetDir, engineRelPath, editorRelPath) {
   }
   writeJson(tsconfigPath, tsconfig);
 }
-function rewriteViteConfig(targetDir, engineRelPath, p2pRelPath) {
+function rewriteViteConfig(targetDir) {
   const vitePath = join14(targetDir, "vite.config.ts");
   if (!existsSync11(vitePath)) return;
-  writeFileSync4(
-    vitePath,
-    rewriteViteConfigContent(readFileSync12(vitePath, "utf-8"), engineRelPath, p2pRelPath),
-    "utf-8"
-  );
+  writeFileSync4(vitePath, rewriteViteConfigContent(readFileSync12(vitePath, "utf-8")), "utf-8");
 }
-function rewriteViteConfigContent(content, engineRelPath, p2pRelPath) {
-  const enginePluginRoot = engineRelPath.startsWith(".") ? engineRelPath : `./${engineRelPath}`;
-  return ensureReactDedupe(
-    content.replace(
-      /'@engine':\s*path\.resolve\(__dirname,\s*['"][^'"]+['"]\)/,
-      `'@engine': path.resolve(__dirname, '${engineRelPath}/src')`
-    ).replace(/\.\.\/\.\.\/(?:packages\/)?p2p-colyseus\//g, p2pRelPath).replace(
-      /(['"])\.\.\/\.\.\/(?:packages\/)?engine\/src\/data\/vite-plugin-data\1/g,
-      `$1${enginePluginRoot}/src/data/vite-plugin-data$1`
-    )
-  );
+function rewriteViteConfigContent(content) {
+  return ensureReactDedupe(content);
 }
 function ensureReactDedupe(content) {
   const REQUIRED = ["react", "react-dom"];
@@ -307784,32 +307860,6 @@ function ensureReactDedupe(content) {
     "resolve: {\n    // react/react-dom dedupe (GH #123): see packages/editor/template/vite.config.ts's\n    // matching comment for the dual-React-instance root cause this avoids.\n    dedupe: ['react', 'react-dom'],"
   );
 }
-function rewriteDataRefModule(targetDir, engineRelPath) {
-  const dataRefPath = join14(targetDir, "src", "data", "data-ref.ts");
-  if (!existsSync11(dataRefPath)) return;
-  writeFileSync4(
-    dataRefPath,
-    rewriteDataRefModuleContent(readFileSync12(dataRefPath, "utf-8"), engineRelPath),
-    "utf-8"
-  );
-}
-function rewriteDataRefModuleContent(content, engineRelPath) {
-  return content.replace(
-    // Match BOTH in-repo spellings, exactly like the sibling p2p-colyseus and
-    // vite-plugin-data rewrites above (`(?:packages\/)?`): the STARTER template
-    // (packages/editor/template/) spells this `../../../../engine/src/data/…`
-    // (already inside `packages/`), but an `examples/<id>/` project spells the
-    // identical on-disk target `../../../../packages/engine/src/data/…` (WITH
-    // the `packages/` segment). Without the optional `packages/` here a bare
-    // literal match no-oped on every data-trio EXAMPLE scaffold, leaving its
-    // data-ref.ts pointed at the in-checkout depth — which fails `tsc`/`vite
-    // build` the moment it's scaffolded into any external directory (E4
-    // AC-TPL-002; no prior CI externally-scaffolds a data-trio example, so it
-    // stayed latent). The p2p/vite-plugin rewrites already carried this guard.
-    /(['"])(?:\.\.\/)+(?:packages\/)?engine\/src\/data\/data-ref\1/,
-    `$1../../${engineRelPath}/src/data/data-ref$1`
-  );
-}
 function rewriteIndexHtml(targetDir, name) {
   const htmlPath = join14(targetDir, "index.html");
   if (!existsSync11(htmlPath)) return;
@@ -307846,13 +307896,12 @@ function scaffoldProject(opts) {
     writeExampleReadme(targetDir, name, opts.exampleId);
   }
   if (opts.presentation) applyPresentation(targetDir, opts.presentation);
-  const { engineRelPath, p2pRelPath, editorRelPath } = resolvePackageRoots();
+  const { engineRelPath, editorRelPath } = resolvePackageRoots();
   rewritePackageJson(targetDir, slug, engineDir, monoRoot);
   const manifest = rewriteGameManifest(targetDir, name, slug, template, monoRoot);
   rewriteTemplateVariantFiles(targetDir, template);
   rewriteTsconfig(targetDir, engineRelPath, editorRelPath);
-  rewriteViteConfig(targetDir, engineRelPath, p2pRelPath);
-  rewriteDataRefModule(targetDir, engineRelPath);
+  rewriteViteConfig(targetDir);
   rewriteIndexHtml(targetDir, name);
   rewriteRoadmap(targetDir, name);
   if (hasCapabilityDistribution) initializeProjectCatalog(targetDir, catalogDir);
@@ -308045,15 +308094,6 @@ function checkAdapterWall(manifest) {
     }
   }
 }
-function checkHostedTierWall(manifest) {
-  for (const world of manifest.roots) {
-    if (world.capabilities.hosted !== "first-party") {
-      throw new DeployError(
-        `vgai deploy: world "${world.id}" declares capabilities.hosted = "${world.capabilities.hosted}", below the required "first-party" tier \u2014 a static host IS a hosted delivery context (\xA71.B), and only first-party roots can ship there.`
-      );
-    }
-  }
-}
 function runProjectBuild(projectDir, extraViteArgs) {
   const cmd = extraViteArgs ? `npm run build -- ${extraViteArgs}` : "npm run build";
   try {
@@ -308141,7 +308181,6 @@ async function deployProject(opts) {
   const { projectDir, reportOnly = false, wrangler } = opts;
   const manifest = loadManifestOrThrow(projectDir);
   checkAdapterWall(manifest);
-  checkHostedTierWall(manifest);
   const projectName = opts.projectName ?? defaultProjectName(manifest.name);
   const targetUrlShape = `${projectName}.pages.dev`;
   if (!reportOnly) {
@@ -309225,7 +309264,6 @@ async function packageItchZip(opts) {
   const { projectDir, reportOnly = false } = opts;
   const manifest = loadManifestOrThrow(projectDir);
   checkAdapterWall(manifest);
-  checkHostedTierWall(manifest);
   runProjectBuild(projectDir, "--base ./");
   const manifestPath = resolveManifestPath(projectDir);
   const staging = stageBuildOutput(projectDir, manifestPath);
@@ -309676,7 +309714,7 @@ function projectHasThreeRoot(projectDir) {
 }
 function reapplyScaffoldRewrites(scratchDir, projectDir, monoRoot, name, currentEngineVersion, targetPackageVersions) {
   const engineDir = resolveScaffoldPackageDir(monoRoot, join18("packages", "engine"), "@vgai/engine");
-  const { engineRelPath, p2pRelPath, editorRelPath, liveRelPath, sdkRelPath, editorSdkRelPath } = resolvePackageRoots();
+  const { engineRelPath, editorRelPath, liveRelPath, sdkRelPath, editorSdkRelPath } = resolvePackageRoots();
   const targetEditorVersion = targetPackageVersions["@vgai/editor"] ?? readInstalledVersion(monoRoot, "@vgai/editor");
   const satelliteRelPaths = {
     "@vgai/live": liveRelPath,
@@ -309761,21 +309799,9 @@ function reapplyScaffoldRewrites(scratchDir, projectDir, monoRoot, name, current
   }
   const vitePath = join18(scratchDir, "vite.config.ts");
   if (existsSync14(vitePath)) {
-    const content = rewriteViteConfigContent(
-      readFileSync16(vitePath, "utf-8"),
-      engineRelPath,
-      p2pRelPath
-    );
+    const content = rewriteViteConfigContent(readFileSync16(vitePath, "utf-8"));
     writeFileSync7(vitePath, content, "utf-8");
   }
-  const dataRefPath = join18(scratchDir, "src", "data", "data-ref.ts");
-  if (existsSync14(dataRefPath)) {
-    writeFileSync7(
-      dataRefPath,
-      rewriteDataRefModuleContent(readFileSync16(dataRefPath, "utf-8"), engineRelPath),
-      "utf-8"
-    );
-  }
   const htmlPath = join18(scratchDir, "index.html");
   if (existsSync14(htmlPath)) {
     const html = readFileSync16(htmlPath, "utf-8").replace(
@@ -310334,6 +310360,7 @@ function formatTabCensus(census) {
     census.heapUsedMB === null ? "heap n/a" : `heap ${census.heapUsedMB}MB${census.heapLimitMB === null ? "" : `/${census.heapLimitMB}MB`}`,
     `canvas ${census.canvasMB}MB in ${census.canvases}`
   ];
+  if (census.mountEpochs !== void 0) parts.splice(1, 0, `mount epochs ${census.mountEpochs}`);
   if (census.textures !== void 0) parts.push(`tex ${census.textures}`);
   if (census.geometries !== void 0) parts.push(`geo ${census.geometries}`);
   if (census.programs !== void 0) parts.push(`prog ${census.programs}`);
@@ -321165,7 +321192,14 @@ function shipRoutesLine(projectRoot) {
   }
   return text.includes(STARTER_SENTINEL) ? "ship routes: not yet implemented (fine while the game is forming \u2014 see AGENTS.md)" : "ship routes: implemented";
 }
-var GAMEPLAY_PATHS = ["src/components", "src/lib", "src/world.tsx", "src/hooks"];
+var GAMEPLAY_PATHS = [
+  "src/components",
+  "src/scenes",
+  "src/prefabs",
+  "src/lib",
+  "src/world.tsx",
+  "src/hooks"
+];
 var STALE_AUTOPLAY_COMMIT_THRESHOLD = 5;
 function git2(cwd2, args2) {
   const result = spawnSync8("git", args2, { cwd: cwd2, encoding: "utf-8" });
@@ -321199,13 +321233,7 @@ function livePlaneLine(shape) {
 }
 
 // src/integrations.ts
-import {
-  existsSync as existsSync22,
-  mkdirSync as mkdirSync11,
-  readFileSync as readFileSync25,
-  renameSync as renameSync3,
-  writeFileSync as writeFileSync9
-} from "node:fs";
+import { existsSync as existsSync22, mkdirSync as mkdirSync11, readFileSync as readFileSync25, renameSync as renameSync3, writeFileSync as writeFileSync9 } from "node:fs";
 import { homedir as homedir6 } from "node:os";
 import { dirname as dirname13, join as join29 } from "node:path";
 
@@ -321272,9 +321300,7 @@ function parseHookStdin(raw) {
   return {};
 }
 function buildCallerSessionContext(opts) {
-  const lines = [
-    "vgai caller-session bridge (advisory, not a gate):"
-  ];
+  const lines = ["vgai caller-session bridge (advisory, not a gate):"];
   if (opts.projectRoot) {
     lines.push(`  project root: ${opts.projectRoot}`);
   } else {
@@ -321291,19 +321317,13 @@ function buildCallerSessionContext(opts) {
     }
     if (opts.projectRoot) {
       const canon = canonicalPath(opts.projectRoot);
-      const match = editors.find(
-        (s) => s.project !== null && canonicalPath(s.project) === canon
-      );
+      const match = editors.find((s) => s.project !== null && canonicalPath(s.project) === canon);
       if (match) {
-        lines.push(
-          `  prefer this session for control commands: http://127.0.0.1:${match.port}`
-        );
+        lines.push(`  prefer this session for control commands: http://127.0.0.1:${match.port}`);
       }
     }
   }
-  lines.push(
-    "  drive the game with `vgai eval`, never synthetic keys / wall-clock sleeps."
-  );
+  lines.push("  drive the game with `vgai eval`, never synthetic keys / wall-clock sleeps.");
   return lines.join("\n");
 }
 function gatherLiveSessionNotes() {
@@ -321428,9 +321448,7 @@ function readIntegrationStatus(paths) {
   if (codex) {
     const hooks = codex["hooks"];
     if (typeof hooks === "object" && hooks !== null) {
-      codexSessionStartInstalled = hasVgaiCommandInHookList(
-        hooks["SessionStart"]
-      );
+      codexSessionStartInstalled = hasVgaiCommandInHookList(hooks["SessionStart"]);
       legacyCodexPreToolUseBashGate = hasLegacyCodexPreToolUseBashGate(codex);
     }
   } else if (existsSync22(paths.codexHooksJson)) {
@@ -321440,14 +321458,10 @@ function readIntegrationStatus(paths) {
   if (claude) {
     const hooks = claude["hooks"];
     if (typeof hooks === "object" && hooks !== null) {
-      claudeSessionStartInstalled = hasVgaiCommandInHookList(
-        hooks["SessionStart"]
-      );
+      claudeSessionStartInstalled = hasVgaiCommandInHookList(hooks["SessionStart"]);
     }
   } else if (existsSync22(paths.claudeSettingsJson)) {
-    notes.push(
-      `claude settings file exists but is not valid JSON: ${paths.claudeSettingsJson}`
-    );
+    notes.push(`claude settings file exists but is not valid JSON: ${paths.claudeSettingsJson}`);
   }
   if (legacyCodexPreToolUseBashGate) {
     notes.push(
@@ -324149,9 +324163,6 @@ function detectUnmanagedReactRoots(source, file2) {
 }
 
 // src/validate.ts
-function isServedRouteOrAbsoluteUrl(value) {
-  return /^[a-z][a-z0-9+.-]*:\/\//i.test(value) || value.startsWith("//") || value.startsWith("/project-game-static/");
-}
 function checkFile(worldId, field, declaredPath, resolvedPath) {
   return { worldId, field, declaredPath, resolvedPath, exists: existsSync25(resolvedPath) };
 }
@@ -324162,16 +324173,9 @@ function collectFileChecks(folder, manifest) {
       checks.push(checkFile(world.id, "entry", world.entry, join35(folder, world.entry)));
     }
     if (world.adapter.type === "ingest") {
-      const { entryHtml, bundleUrl } = world.adapter;
-      if (entryHtml !== void 0) {
-        checks.push(
-          checkFile(world.id, "adapter.ingest.entryHtml", entryHtml, join35(folder, entryHtml))
-        );
-      }
-      if (bundleUrl !== void 0 && !isServedRouteOrAbsoluteUrl(bundleUrl)) {
-        checks.push(
-          checkFile(world.id, "adapter.ingest.bundleUrl", bundleUrl, join35(folder, bundleUrl))
-        );
+      const shim = world.adapter.contractShim;
+      if (shim !== void 0) {
+        checks.push(checkFile(world.id, "adapter.ingest.contractShim", shim, join35(folder, shim)));
       }
     }
   }
@@ -324685,8 +324689,8 @@ function catalogDistributionDir() {
   );
 }
 function cliVersion() {
-  if ("0.5.10") {
-    return "0.5.10";
+  if ("0.5.12") {
+    return "0.5.12";
   }
   try {
     const pkg = JSON.parse(readFileSync32(join39(__dirname4, "..", "package.json"), "utf8"));
@@ -324705,7 +324709,7 @@ function bakedTargetVersions() {
   if (false)
     return void 0;
   try {
-    return JSON.parse('{"@vgai/engine":"0.5.10","@vgai/editor":"0.5.10","@vgai/p2p-colyseus":"0.5.10","@vgai/live":"0.5.10","@vgai/sdk":"0.5.10","@vgai/editor-sdk":"0.5.10","@vgai/cli":"0.5.10"}');
+    return JSON.parse('{"@vgai/engine":"0.5.12","@vgai/editor":"0.5.12","@vgai/p2p-colyseus":"0.5.12","@vgai/live":"0.5.12","@vgai/sdk":"0.5.12","@vgai/editor-sdk":"0.5.12","@vgai/cli":"0.5.12"}');
   } catch {
     return void 0;
   }
@@ -324808,7 +324812,6 @@ Verify it:
 Ship it:
   npm run deploy       The project's provider-native deployment script
   deploy [folder]      Legacy Cloudflare/itch compatibility for existing projects
-  bundle <folder>      Sidecar ESM bundle for an external pixi game
   render-cinematic     Deterministic frame-addressed video export
 
 Bring in an existing web game:
@@ -324974,7 +324977,7 @@ Project:
                               --to (that package, if named) > this CLI build's baked-in version
                               > (in-repo only) this checkout's installed version.
   validate [folder]           In-process: validate vgai.project.json, check every declared
-                              entry/scene/entryHtml/bundleUrl file exists, print the engine pin
+                              entry/contractShim file exists, print the engine pin
                               (default: cwd) \u2014 no monorepo/editor/Vite needed beyond this checkout
                               Exit codes: 0 valid, 1 invalid manifest/files/React roots/design states, 2 usage
   Deployment is project-owned: add deploy-vercel or deploy-cloudflare, then
@@ -324983,15 +324986,6 @@ Project:
     --json                    Print a single machine-readable JSON report instead of text
                               Exit codes: 0 pass, 1 conformance failure, 2 usage/environment error
                               Requires a monorepo checkout (same precondition as \`edit\`)
-  bundle <folder>             Build an external pixi game's iframe-reachable world as a sidecar
-                              ESM bundle (pixi.js + declared extraDeps externalized), never
-                              touching game source. Prints the vgai.project.json fields to add.
-    --write                   Patch vgai.project.json's bundleUrl in place instead of printing it
-    --entry <path>            Build entry, folder-relative (default: probed from package.json)
-    --world <id>              Which world to build (default: the manifest's one iframe-reachable
-                              canvas world \u2014 an error if there are zero or several)
-                              Exit codes: 0 built, 1 build failure, 2 usage error
-                              Requires a monorepo checkout (same precondition as \`edit\`)
   doctor <folder>             Headless mount of every declared world: static validation
                               (manifest + declared files + engine pin), then a REAL headless
                               editor session. Exactly one verdict per world \u2014
@@ -326029,11 +326023,7 @@ function renderValidateReport(report) {
     `${manifestPath}: OK \u2014 "${manifest.name}" v${manifest.version} (engine ${manifest.engine.version})`
   );
   for (const world of manifest.roots) {
-    const { adapter } = world;
-    const adapterLabel = adapter.type === "ingest" ? `${adapter.identity} (${adapter.strategy})` : adapter.identity;
-    lines.push(
-      `  root "${world.id}" surface=${world.surface} adapter=${adapterLabel} tiers={local: ${world.capabilities.local}, hosted: ${world.capabilities.hosted}}`
-    );
+    lines.push(`  root "${world.id}" surface=${world.surface} adapter=${world.adapter.identity}`);
   }
   lines.push("");
   const missing = fileChecks.filter((f) => !f.exists);
@@ -326435,6 +326425,24 @@ function describeEditorProvenance(packagedEntry, engineRoot) {
   }
   return `Editor: packaged @vgai/editor@${version2} (${editorPkgDir})`;
 }
+function assertEditorProjectInstalled(absProject, engineRoot = ENGINE_ROOT) {
+  let realEngineRoot;
+  try {
+    realEngineRoot = realpathSync8(engineRoot);
+  } catch {
+    realEngineRoot = engineRoot;
+  }
+  const engineRootIsCheckout = existsSync28(
+    join39(realEngineRoot, "packages", "editor", "package.json")
+  );
+  const projectIsInCheckout = absProject === realEngineRoot || absProject.startsWith(realEngineRoot + sep6);
+  if (engineRootIsCheckout && projectIsInCheckout) return;
+  if (existsSync28(join39(absProject, "node_modules"))) return;
+  throw new Error(
+    `Project dependencies are not installed in ${absProject}.
+Run \`npm install\` in that project, then run \`vgai edit\` again. vgai will not borrow React or editor packages from another checkout.`
+  );
+}
 async function launchEditor(projectPath, opts = {}) {
   if (opts.noOpen === void 0 && process.env["VGAI_NO_OPEN"]) {
     opts = { ...opts, noOpen: true };
@@ -326444,6 +326452,7 @@ async function launchEditor(projectPath, opts = {}) {
   }
   const absProject = canonicalPath(resolve20(projectPath));
   discoverProject(absProject);
+  assertEditorProjectInstalled(absProject);
   const portRequest = resolveEditorPortRequest(
     absProject,
     opts.portOverride,
@@ -326782,50 +326791,6 @@ No vgai.project.json in ${absFolder}`
   });
   process.exit(code);
 }
-async function runBundle(folderArg, opts) {
-  const absFolder = resolve20(folderArg);
-  if (!existsSync28(absFolder) || !statSync12(absFolder).isDirectory()) {
-    console.error(
-      `Usage: vgai bundle <folder> [--write] [--entry <path>] [--world <id>]
-Folder not found: ${absFolder}`
-    );
-    process.exit(2);
-  }
-  if (!hasManifest(absFolder)) {
-    console.error(
-      `Usage: vgai bundle <folder> [--write] [--entry <path>] [--world <id>]
-No vgai.project.json in ${absFolder}`
-    );
-    process.exit(2);
-  }
-  const runnerScript = join39(ENGINE_ROOT, "packages/editor/scripts/run-bundle.ts");
-  if (!existsSync28(runnerScript)) {
-    throw new Error(`Bundle runner not found at ${runnerScript}. Is the engine installed?`);
-  }
-  const childArgs = [
-    "tsx",
-    runnerScript,
-    absFolder,
-    ...opts.write ? ["--write"] : [],
-    ...opts.entry !== void 0 ? ["--entry", opts.entry] : [],
-    ...opts.world !== void 0 ? ["--world", opts.world] : []
-  ];
-  const code = await new Promise((resolvePromise) => {
-    const child = spawn4("npx", childArgs, {
-      cwd: ENGINE_ROOT,
-      stdio: "inherit",
-      shell: true
-    });
-    child.on("error", (err2) => {
-      console.error(`Failed to start bundle runner: ${err2.message}`);
-      resolvePromise(1);
-    });
-    child.on("close", (exitCode) => {
-      resolvePromise(exitCode ?? 1);
-    });
-  });
-  process.exit(code);
-}
 var DOCTOR_USAGE = "Usage: vgai doctor <folder> [--json] [--port <n>] [--timeout <ms>]";
 async function runDoctor(folderArg, opts) {
   const absFolder = resolve20(folderArg);
@@ -327701,7 +327666,6 @@ var KNOWN_COMMANDS = /* @__PURE__ */ new Set([
   "screenshot",
   "eval",
   "conformance",
-  "bundle",
   "doctor",
   "render-cinematic",
   "perf",
@@ -328199,6 +328163,10 @@ Unrecognized option or invalid project name: ${name}`);
             throw new Error(`npm install exited with code ${exitCode ?? "unknown"}`);
           cacheDependencies(targetDir);
         }
+        const repin = repinEngineAfterInstall(targetDir);
+        if (repin) {
+          console.log(`Engine pin updated ${repin.from} -> ${repin.to} (the project's installed @vgai/engine).`);
+        }
       } catch {
         console.error("npm install failed. The editor was not started; fix the install and retry.");
         process.exitCode = 1;
@@ -328311,7 +328279,7 @@ ${subcommand === "list" ? `Unknown option: ${unknown2[0]}` : `Unknown subcommand
         console.log(`Usage: vgai validate [folder]
 
 In-process: validate vgai.project.json, check every declared
-entry/scene/entryHtml/bundleUrl file exists, print the engine pin (default: cwd)
+entry/contractShim file exists, print the engine pin (default: cwd)
 \u2014 no monorepo/editor/Vite needed beyond this checkout.
 
 Exit codes: 0 valid, 1 invalid manifest/files/React roots/design states, 2 usage`);
@@ -328898,33 +328866,6 @@ Choose exactly one target: project, --port/--url, --all, or --everywhere.`
       await runConformance(positional[0], jsonMode);
       break;
     }
-    case "bundle": {
-      if (hasHelpFlag(args)) {
-        console.log("Usage: vgai bundle <folder> [--write] [--entry <path>] [--world <id>]");
-        break;
-      }
-      const write = args.includes("--write");
-      const entryIdx = args.indexOf("--entry");
-      const entry = entryIdx >= 0 ? args[entryIdx + 1] : void 0;
-      const worldIdx = args.indexOf("--world");
-      const worldId = worldIdx >= 0 ? args[worldIdx + 1] : void 0;
-      const positional = [];
-      for (let i = 1; i < args.length; i++) {
-        const a = args[i];
-        if (a === "--write") continue;
-        if (a === "--entry" || a === "--world") {
-          i++;
-          continue;
-        }
-        positional.push(a);
-      }
-      if (!positional[0]) {
-        console.error("Usage: vgai bundle <folder> [--write] [--entry <path>] [--world <id>]");
-        process.exit(2);
-      }
-      await runBundle(positional[0], { write, entry, world: worldId });
-      break;
-    }
     case "doctor": {
       if (hasHelpFlag(args)) {
         console.log(DOCTOR_USAGE);
@@ -329422,6 +329363,7 @@ if (process.argv[1] && import.meta.url === pathToFileURL2(realpathOrSelf(process
 export {
   BRIDGE_SCREENSHOT_STALE,
   HIDDEN_FRAME_NOTICE,
+  assertEditorProjectInstalled,
   authoringWarningsWarning,
   autoAddCapabilityForTool,
   autoLaunchEditorAfterCreate,

package/package.json

@@ -2,7 +2,7 @@
   "name": "@vgai/cli",
   "author": "Volter AI, Inc.",
   "license": "Apache-2.0",
-  "version": "0.5.10",
+  "version": "0.5.12",
   "description": "Create, open, control, validate, and playtest VGAI game projects.",
   "keywords": [
     "game-engine",
@@ -39,12 +39,12 @@
   },
   "dependencies": {
     "@oclif/core": "^4.11.14",
-    "@vgai/editor": "0.5.10",
-    "@vgai/editor-sdk": "0.5.10",
-    "@vgai/engine": "0.5.10",
-    "@vgai/live": "0.5.10",
-    "@vgai/p2p-colyseus": "0.5.10",
-    "@vgai/sdk": "0.5.10",
+    "@vgai/editor": "0.5.12",
+    "@vgai/editor-sdk": "0.5.12",
+    "@vgai/engine": "0.5.12",
+    "@vgai/live": "0.5.12",
+    "@vgai/p2p-colyseus": "0.5.12",
+    "@vgai/sdk": "0.5.12",
     "ink": "^7.1.0",
     "playwright": "^1.58.2",
     "react": "^19.2.4",