@forgeax/engine-devkit 0.1.4 → 0.1.7

package/dist/cli.mjs

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 import { deflateRawSync } from 'zlib';
-import { createHash } from 'crypto';
-import { readFile, mkdtemp, rm, readdir, mkdir, cp, rename, writeFile, copyFile, stat, symlink, unlink, realpath, readlink, lstat, rmdir, access } from 'fs/promises';
+import { createHash, randomUUID } from 'crypto';
+import { readFile, mkdtemp, rm, readdir, mkdir, cp, rename, writeFile, realpath, copyFile, stat, symlink, unlink, access, readlink, lstat, rmdir } from 'fs/promises';
 import { resolve, extname, dirname, basename, relative, isAbsolute, sep } from 'path';
+import { GameProjectSchema } from '@forgeax/engine-project';
 import { readFileSync, existsSync } from 'fs';
 import { createRequire } from 'module';
 import { pathToFileURL, fileURLToPath } from 'url';
@@ -19,15 +20,19 @@ import { createStandaloneRuntimeAssetBinding, ok, err } from '@forgeax/engine-ty
 import { createParticleCodeNativeCookerFromRoots } from '@forgeax/engine-vfx-compiler';
 import { pluginPack, reloadAssetHost } from '@forgeax/engine-vite-plugin-pack';
 import { forgeaxShader } from '@forgeax/engine-vite-plugin-shader';
-import { GameProjectSchema } from '@forgeax/engine-project';
 import { runCliGltf } from '@forgeax/engine-gltf/cli-gltf';
 import { scanEntries } from '@forgeax/engine-pack/cli-asset';
 import { AssetGuid } from '@forgeax/engine-pack/guid';
-import { execFile } from 'child_process';
+import { spawn, execFile } from 'child_process';
 import { tmpdir } from 'os';
 import { promisify } from 'util';
-import { decodeTape, openReplay, buildFrameModel, createRhiDebugError } from '@forgeax/engine-rhi-debug';
-import { build, createServer, preview } from 'vite';
+import { decodeTape, openReplay, buildFrameModel, replayDeviceRequest, createRhiDebugError } from '@forgeax/engine-rhi-debug';
+import { rhi, createShaderModule } from '@forgeax/engine-rhi-webgpu';
+import { build, preview, createServer as createServer$1 } from 'vite';
+import { createServer } from 'net';
+import { FORGEAX_FRAME_SUBMITTED_DATASET } from '@forgeax/engine-app';
+import { parseImage } from '@forgeax/engine-image/parse-image';
+import { chromium } from 'playwright';
 import { startVitest } from 'vitest/node';
 import materialPreviewPlugin from '@forgeax/engine-preview/material';
 import meshPreviewPlugin from '@forgeax/engine-preview/mesh';
@@ -299,17 +304,546 @@ var init_dist = __esm({
   "src/dist.ts"() {
   }
 });
-function ignoreDevKitCatalogPath(path) {
-  const normalized = path.replace(/\\/g, "/");
-  if (normalized.split("/").includes("shaders")) return true;
-  if (!normalized.endsWith(".meta.json")) return false;
+function projectError(code, expected, hint, detail) {
+  return { ok: false, error: { code, expected, hint, detail } };
+}
+async function readJson(path) {
+  return JSON.parse(await readFile(path, "utf8"));
+}
+function firstUnsupportedStandaloneRealm(entries2, inheritedRealm = "engine") {
+  for (const entry of entries2) {
+    const realm = entry.realm ?? inheritedRealm ?? "engine";
+    if (realm !== "engine") return { id: entry.id, realm };
+    if (entry.group === true) {
+      const unsupported = firstUnsupportedStandaloneRealm(
+        entry.config,
+        realm
+      );
+      if (unsupported !== void 0) return unsupported;
+    }
+  }
+  return void 0;
+}
+function pluginModuleNames(entries2) {
+  return entries2.flatMap(
+    (entry) => entry.group === true ? pluginModuleNames(entry.config) : [entry.name]
+  );
+}
+async function readProjectFacts(rootInput = process.cwd()) {
+  const root = resolve(rootInput);
+  let forgeValue;
+  let packageValue;
+  try {
+    [forgeValue, packageValue] = await Promise.all([
+      readJson(resolve(root, "forge.json")),
+      readJson(resolve(root, "package.json"))
+    ]);
+  } catch (cause) {
+    return projectError(
+      "project-manifest-unreadable",
+      "readable forge.json and package.json files",
+      "Run the command from a ForgeaX game root or pass its directory.",
+      { root, reason: cause instanceof Error ? cause.message : String(cause) }
+    );
+  }
+  if (forgeValue === null || typeof forgeValue !== "object") {
+    return projectError(
+      "project-manifest-invalid",
+      "forge.json to contain an object",
+      "Repair forge.json before running DevKit.",
+      { root }
+    );
+  }
+  if (packageValue === null || typeof packageValue !== "object") {
+    return projectError(
+      "package-manifest-invalid",
+      "package.json to contain an object",
+      "Repair package.json before running DevKit.",
+      { root }
+    );
+  }
+  const parsedForge = GameProjectSchema.safeParse(forgeValue);
+  if (!parsedForge.success) {
+    return projectError(
+      "project-manifest-invalid",
+      "forge.json to satisfy @forgeax/engine-project GameProjectSchema",
+      "Repair the fields reported by the authoritative project schema.",
+      { root, issues: parsedForge.error.issues }
+    );
+  }
+  const forge = parsedForge.data;
+  if (forge.id.length === 0 || forge.name.length === 0 || forge.entry === void 0 || forge.entry.length === 0) {
+    return projectError(
+      "project-manifest-invalid",
+      "forge.json to declare id, name, and entry",
+      "Restore the project entry; plugin Entries remain optional additions.",
+      { root }
+    );
+  }
+  const plugins = forge.plugins ?? [];
+  const unsupportedRealm = firstUnsupportedStandaloneRealm(plugins);
+  if (unsupportedRealm !== void 0) {
+    return projectError(
+      "project-plugin-realm-unsupported",
+      "the standalone Devkit host to contain only engine-realm plugin Entries",
+      "Move Host or build plugins to a host that owns that physical realm.",
+      { root, ...unsupportedRealm }
+    );
+  }
+  const entryPath = isAbsolute(forge.entry) ? forge.entry : resolve(root, forge.entry);
   try {
-    const meta = JSON.parse(readFileSync(path, "utf8"));
-    return meta.importer === "game-default-target-profile";
+    await readFile(entryPath);
+  } catch {
+    return projectError(
+      "project-entry-missing",
+      "forge.json#entry to resolve to a readable module",
+      "Restore the game entry or update forge.json#entry.",
+      { root, entry: forge.entry }
+    );
+  }
+  const packageJson = packageValue;
+  const forgeax = packageJson.forgeax;
+  const configuredRoots = forgeax !== null && typeof forgeax === "object" ? forgeax.assets?.roots : void 0;
+  const assetRoots = Array.isArray(configuredRoots) && configuredRoots.every((value) => typeof value === "string") ? configuredRoots : ["assets"];
+  const configuredImporters = forgeax !== null && typeof forgeax === "object" ? forgeax.assets?.importers : void 0;
+  const assetImporters = Array.isArray(configuredImporters) && configuredImporters.every((value) => typeof value === "string") ? configuredImporters : [];
+  const configuredPublicDir = forgeax !== null && typeof forgeax === "object" ? forgeax.assets?.publicDir : void 0;
+  const assetPublicDir = typeof configuredPublicDir === "string" ? configuredPublicDir : void 0;
+  const physics = forge.physics === "2d" || forge.physics === "3d" ? forge.physics : void 0;
+  const defaultScene = typeof forge.defaultScene === "string" && forge.defaultScene.length > 0 ? forge.defaultScene : void 0;
+  const normalizedEntry = forge.entry.startsWith("./") ? forge.entry : `./${forge.entry}`;
+  const bootstrapEntry = pluginModuleNames(plugins).map((name) => name.startsWith("./") ? name : `./${name}`).includes(normalizedEntry) ? void 0 : forge.entry;
+  return {
+    ok: true,
+    value: {
+      root,
+      id: forge.id,
+      name: forge.name,
+      entry: forge.entry,
+      ...bootstrapEntry === void 0 ? {} : { bootstrapEntry },
+      plugins,
+      ...physics === void 0 ? {} : { physics },
+      ...defaultScene === void 0 ? {} : { defaultScene },
+      assetRoots,
+      ...assetImporters.length === 0 ? {} : { assetImporters },
+      ...assetPublicDir === void 0 ? {} : { assetPublicDir },
+      packageJson
+    }
+  };
+}
+function commandError(cause, fallbackCode) {
+  if (cause !== null && typeof cause === "object" && "code" in cause && "expected" in cause && "hint" in cause && "detail" in cause) {
+    return cause;
+  }
+  return {
+    code: fallbackCode,
+    expected: "the ForgeaX command to complete",
+    hint: "Inspect the underlying diagnostic and repair the owning input.",
+    detail: { reason: cause instanceof Error ? cause.message : String(cause) }
+  };
+}
+var init_project = __esm({
+  "src/project.ts"() {
+  }
+});
+function bindingError(code, expected, hint, detail = {}) {
+  return { ok: false, error: { code, expected, hint, detail } };
+}
+function isMissing(cause) {
+  return cause !== null && typeof cause === "object" && "code" in cause && cause.code === "ENOENT";
+}
+async function pathExists(path) {
+  try {
+    await access(path);
+    return true;
   } catch {
     return false;
   }
 }
+function parseBinding(value, path) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return bindingError(
+      "engine-binding-invalid",
+      "engine-binding.json to contain one object",
+      "Run forgeax engine unlink, then select a binding again.",
+      { path }
+    );
+  }
+  const candidate = value;
+  if (candidate.schemaVersion !== ENGINE_BINDING_SCHEMA_VERSION) {
+    return bindingError(
+      "engine-binding-version-unsupported",
+      `engine-binding.json schemaVersion ${ENGINE_BINDING_SCHEMA_VERSION}`,
+      "Upgrade the SDK or remove the stale binding with forgeax engine unlink.",
+      { path, schemaVersion: candidate.schemaVersion ?? null }
+    );
+  }
+  if (typeof candidate.path !== "string" || candidate.path.length === 0) {
+    return bindingError(
+      "engine-binding-path-missing",
+      "engine-binding.json to contain one non-empty local Engine path",
+      "Run forgeax engine use-local <engine-directory>.",
+      { path }
+    );
+  }
+  return {
+    ok: true,
+    value: {
+      schemaVersion: ENGINE_BINDING_SCHEMA_VERSION,
+      path: resolve(candidate.path)
+    }
+  };
+}
+async function readEngineBinding(rootInput = process.cwd()) {
+  const root = resolve(rootInput);
+  const path = bindingFile(root);
+  try {
+    const value = JSON.parse(await readFile(path, "utf8"));
+    return parseBinding(value, path);
+  } catch (cause) {
+    if (isMissing(cause)) return { ok: true, value: null };
+    return bindingError(
+      "engine-binding-unreadable",
+      "engine-binding.json to be readable JSON",
+      "Repair or remove .forgeax/engine-binding.json, then select a binding again.",
+      { path, reason: cause instanceof Error ? cause.message : String(cause) }
+    );
+  }
+}
+async function writeEngineBinding(root, binding) {
+  const path = bindingFile(root);
+  const partial = `${path}.partial-${process.pid}`;
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(partial, `${JSON.stringify(binding, null, 2)}
+`, "utf8");
+  await rename(partial, path);
+}
+function conditionalExport(value) {
+  if (typeof value === "string") return value;
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return void 0;
+  const record = value;
+  for (const key of ["import", "browser", "node", "default", "require", "types"]) {
+    const candidate = record[key];
+    const selected = conditionalExport(candidate);
+    if (selected !== void 0) return selected;
+  }
+  return void 0;
+}
+function packageEntry(manifest) {
+  const exportsValue = manifest.exports;
+  if (exportsValue !== void 0) {
+    if (typeof exportsValue === "object" && exportsValue !== null && !Array.isArray(exportsValue)) {
+      const root = exportsValue["."];
+      const selected2 = conditionalExport(root ?? exportsValue);
+      if (selected2 !== void 0) return selected2;
+    }
+    const selected = conditionalExport(exportsValue);
+    if (selected !== void 0) return selected;
+  }
+  return typeof manifest.module === "string" ? manifest.module : typeof manifest.main === "string" ? manifest.main : void 0;
+}
+async function readManifest(path) {
+  const value = JSON.parse(await readFile(path, "utf8"));
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`engine-package-manifest-invalid: ${path}`);
+  }
+  return value;
+}
+async function inspectEngineWorkspace(workspaceInput) {
+  const root = resolve(workspaceInput);
+  const packageRoot = resolve(root, "packages");
+  try {
+    await access(resolve(root, "pnpm-workspace.yaml"));
+    const entries2 = await readdir(packageRoot, { withFileTypes: true });
+    const packages = [];
+    for (const entry of entries2) {
+      if (!entry.isDirectory()) continue;
+      const packagePath = resolve(packageRoot, entry.name);
+      let manifest;
+      try {
+        manifest = await readManifest(resolve(packagePath, "package.json"));
+      } catch {
+        continue;
+      }
+      if (typeof manifest.name !== "string" || !manifest.name.startsWith("@forgeax/engine"))
+        continue;
+      if (typeof manifest.version !== "string") {
+        return bindingError(
+          "engine-package-version-missing",
+          "every local Engine package to declare a version",
+          "Restore the package manifest version before selecting a local Engine.",
+          { package: manifest.name, root: packagePath }
+        );
+      }
+      const target = packageEntry(manifest);
+      const entryPath = target === void 0 ? void 0 : resolve(packagePath, target);
+      let entryDigest = null;
+      let builtAt2 = null;
+      if (entryPath !== void 0 && await pathExists(entryPath)) {
+        const [bytes, metadata] = await Promise.all([readFile(entryPath), stat(entryPath)]);
+        entryDigest = `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+        builtAt2 = metadata.mtime.toISOString();
+      }
+      packages.push({
+        name: manifest.name,
+        root: packagePath,
+        version: manifest.version,
+        entry: entryPath ?? null,
+        built: entryDigest !== null,
+        entryDigest,
+        builtAt: builtAt2
+      });
+    }
+    packages.sort((a, b) => a.name.localeCompare(b.name));
+    if (packages.length === 0) {
+      return bindingError(
+        "engine-workspace-empty",
+        "the local Engine workspace to contain @forgeax/engine packages",
+        "Pass the Engine repository or its source/engine SDK directory.",
+        { root, packageRoot }
+      );
+    }
+    const versions = [...new Set(packages.map((item) => item.version))].sort();
+    const missingBuilds = packages.filter((item) => !item.built).map((item) => item.name);
+    const builtAt = packages.flatMap((item) => item.builtAt === null ? [] : [item.builtAt]).sort().at(-1) ?? null;
+    const digest = `sha256:${createHash("sha256").update(
+      packages.map((item) => `${item.name}\0${item.version}\0${item.entryDigest ?? "unbuilt"}`).join("\n")
+    ).digest("hex")}`;
+    return {
+      ok: true,
+      value: {
+        root,
+        packageCount: packages.length,
+        builtPackages: packages.length - missingBuilds.length,
+        missingBuilds,
+        versions,
+        packages,
+        digest,
+        builtAt
+      }
+    };
+  } catch (cause) {
+    return bindingError(
+      isMissing(cause) ? "engine-workspace-missing" : "engine-workspace-unreadable",
+      "a readable Engine workspace with pnpm-workspace.yaml and packages/",
+      "Pass the Engine repository root, not its packages/ directory.",
+      { root, packageRoot, reason: cause instanceof Error ? cause.message : String(cause) }
+    );
+  }
+}
+function projectDependencyMode(packageJson) {
+  let workspace = false;
+  let registry = false;
+  for (const section of [
+    "dependencies",
+    "devDependencies",
+    "optionalDependencies",
+    "peerDependencies"
+  ]) {
+    const value = packageJson[section];
+    if (value === null || typeof value !== "object" || Array.isArray(value)) continue;
+    for (const version of Object.values(value)) {
+      if (typeof version !== "string") continue;
+      if (version.startsWith("workspace:") || version.startsWith("file:")) workspace = true;
+      else registry = true;
+    }
+  }
+  return workspace ? registry ? "mixed" : "workspace" : registry ? "registry" : "none";
+}
+async function sdkResolution(root) {
+  const packageJson = resolve(root, "node_modules", "@forgeax", "engine", "package.json");
+  try {
+    const manifest = await readManifest(packageJson);
+    const target = packageEntry(manifest);
+    const entry = target === void 0 ? null : resolve(dirname(packageJson), target);
+    return {
+      root: dirname(packageJson),
+      version: typeof manifest.version === "string" ? manifest.version : null,
+      entry,
+      built: entry !== null && await pathExists(entry),
+      source: "sdk"
+    };
+  } catch {
+    return { root: null, version: null, entry: null, built: false, source: "unresolved" };
+  }
+}
+async function engineStatusCommand(options = {}) {
+  const facts = await readProjectFacts(options.root);
+  if (!facts.ok) return facts;
+  const bindingResult = await readEngineBinding(facts.value.root);
+  if (!bindingResult.ok) return bindingResult;
+  const binding = bindingResult.value;
+  const mode = binding === null ? "sdk" : "local";
+  const projectDependencies = projectDependencyMode(facts.value.packageJson);
+  if (binding !== null) {
+    const localPath = binding.path;
+    const localBinding = {
+      schemaVersion: ENGINE_BINDING_SCHEMA_VERSION,
+      path: localPath
+    };
+    const workspaceResult = await inspectEngineWorkspace(localPath);
+    if (!workspaceResult.ok) {
+      const resolved3 = {
+        root: localPath,
+        version: null,
+        entry: null,
+        built: false,
+        source: "local"
+      };
+      return {
+        ok: true,
+        value: {
+          schemaVersion: ENGINE_BINDING_SCHEMA_VERSION,
+          root: facts.value.root,
+          binding: localBinding,
+          mode,
+          resolved: resolved3,
+          workspace: null,
+          projectDependencies,
+          npmCompatible: projectDependencies === "registry" || projectDependencies === "none",
+          healthy: false,
+          next: ["forgeax engine unlink", "forgeax engine use-local <engine-directory>"],
+          diagnostic: workspaceResult.error
+        }
+      };
+    }
+    const workspace = workspaceResult.value;
+    const version = workspace.versions.length === 1 ? workspace.versions[0] ?? null : null;
+    const umbrella = workspace.packages.find((item) => item.name === "@forgeax/engine");
+    const resolved2 = {
+      root: localPath,
+      version,
+      entry: umbrella?.entry ?? null,
+      built: umbrella?.built ?? false,
+      source: "local"
+    };
+    const healthy = workspace.versions.length === 1 && workspace.missingBuilds.length === 0;
+    return {
+      ok: true,
+      value: {
+        schemaVersion: ENGINE_BINDING_SCHEMA_VERSION,
+        root: facts.value.root,
+        binding: localBinding,
+        mode,
+        resolved: resolved2,
+        workspace,
+        projectDependencies,
+        npmCompatible: projectDependencies === "registry" || projectDependencies === "none",
+        healthy,
+        next: healthy ? ["forgeax build", "forgeax capture --backend auto --require-ui"] : ["pnpm build:engine", "forgeax engine doctor"]
+      }
+    };
+  }
+  const resolved = await sdkResolution(facts.value.root);
+  return {
+    ok: true,
+    value: {
+      schemaVersion: ENGINE_BINDING_SCHEMA_VERSION,
+      root: facts.value.root,
+      binding,
+      mode,
+      resolved,
+      workspace: null,
+      projectDependencies,
+      npmCompatible: projectDependencies === "registry" || projectDependencies === "none",
+      healthy: resolved.source === "sdk" && resolved.built,
+      next: resolved.source === "sdk" && resolved.built ? ["forgeax build", "forgeax capture --backend auto --require-ui"] : ["pnpm install", "forgeax doctor"]
+    }
+  };
+}
+async function engineUseLocalCommand(options) {
+  const root = resolve(options.root ?? process.cwd());
+  if (options.path === void 0 || options.path.trim().length === 0) {
+    return bindingError(
+      "engine-binding-path-missing",
+      "forgeax engine use-local <engine-directory>",
+      "Pass the local Engine repository or SDK source directory."
+    );
+  }
+  let localPath;
+  try {
+    localPath = await realpath(resolve(root, options.path));
+  } catch (cause) {
+    return bindingError(
+      "engine-workspace-missing",
+      "the local Engine directory to exist",
+      "Pass an existing Engine repository or SDK source directory.",
+      {
+        path: resolve(root, options.path),
+        reason: cause instanceof Error ? cause.message : String(cause)
+      }
+    );
+  }
+  const workspace = await inspectEngineWorkspace(localPath);
+  if (!workspace.ok) return workspace;
+  const binding = {
+    schemaVersion: ENGINE_BINDING_SCHEMA_VERSION,
+    path: localPath
+  };
+  if (options.dryRun !== true) await writeEngineBinding(root, binding);
+  const status = await engineStatusCommand({ root });
+  if (!status.ok) return status;
+  return {
+    ok: true,
+    value: {
+      ...status.value,
+      next: workspace.value.missingBuilds.length === 0 ? ["forgeax build", "forgeax capture --backend auto --require-ui"] : ["pnpm build:engine", "forgeax engine doctor"]
+    }
+  };
+}
+async function engineUnlinkCommand(options = {}) {
+  const root = resolve(options.root ?? process.cwd());
+  if (options.dryRun !== true) await rm(bindingFile(root), { force: true });
+  return engineStatusCommand({ root });
+}
+async function engineDoctorCommand(options = {}) {
+  const status = await engineStatusCommand(options);
+  if (!status.ok) return status;
+  if (status.value.projectDependencies === "workspace" || status.value.projectDependencies === "mixed") {
+    return {
+      ok: false,
+      error: {
+        code: "engine-project-workspace-dependency",
+        expected: "the game project to use registry or SDK-resolved dependencies for npm consumers",
+        hint: "This project is a pnpm workspace; use pnpm here, or create a clean SDK game project for npm install.",
+        detail: { root: status.value.root, projectDependencies: status.value.projectDependencies }
+      }
+    };
+  }
+  if (status.value.diagnostic !== void 0) return { ok: false, error: status.value.diagnostic };
+  if (!status.value.healthy) {
+    return {
+      ok: false,
+      error: {
+        code: status.value.mode === "local" ? "engine-local-build-missing" : "engine-sdk-unresolved",
+        expected: "the selected Engine binding to resolve to built packages",
+        hint: status.value.mode === "local" ? "Run pnpm build:engine in the selected Engine checkout, then rerun forgeax engine doctor." : "Run pnpm install in the game project or select a valid local Engine checkout.",
+        detail: { status: status.value }
+      }
+    };
+  }
+  return status;
+}
+var ENGINE_BINDING_SCHEMA_VERSION, bindingFile;
+var init_engine_binding = __esm({
+  "src/engine-binding.ts"() {
+    init_project();
+    ENGINE_BINDING_SCHEMA_VERSION = "1.0.0";
+    bindingFile = (root) => resolve(root, ".forgeax", "engine-binding.json");
+  }
+});
+
+// src/host.ts
+var host_exports = {};
+__export(host_exports, {
+  createViteConfig: () => createViteConfig,
+  devKitDdcRoots: () => devKitDdcRoots,
+  ignoreDevKitCatalogPath: () => ignoreDevKitCatalogPath
+});
+function ignoreDevKitCatalogPath(path) {
+  const normalized = path.replace(/\\/g, "/");
+  return normalized.split("/").includes("shaders");
+}
 function devKitDdcRoots(projectRoot2) {
   return {
     buildCacheRoot: resolve(projectRoot2, ".forgeax", "ddc", "build-cache"),
@@ -367,40 +901,33 @@ function findEngineWorkspaceRoot() {
     cursor = parent;
   }
 }
-async function engineWorkspacePackages() {
-  if (engineWorkspacePackagesPromise !== void 0) return engineWorkspacePackagesPromise;
-  engineWorkspacePackagesPromise = (async () => {
-    const workspaceRoot = findEngineWorkspaceRoot();
-    if (workspaceRoot === void 0) return /* @__PURE__ */ new Map();
-    const packageRoot = resolve(workspaceRoot, "packages");
-    if (!existsSync(packageRoot)) return /* @__PURE__ */ new Map();
-    const packages = /* @__PURE__ */ new Map();
-    for (const entry of await readdir(packageRoot, { withFileTypes: true })) {
-      if (!entry.isDirectory()) continue;
-      const root = resolve(packageRoot, entry.name);
-      try {
-        const manifest = JSON.parse(
-          await readFile(resolve(root, "package.json"), "utf8")
-        );
-        if (manifest === null || typeof manifest !== "object") continue;
-        const name = manifest.name;
-        if (typeof name === "string" && name.startsWith("@forgeax/engine-")) {
-          packages.set(name, { root, manifest });
-        }
-      } catch {
+async function engineWorkspacePackages(workspaceRoot = findEngineWorkspaceRoot()) {
+  if (workspaceRoot === void 0) return /* @__PURE__ */ new Map();
+  const packageRoot = resolve(workspaceRoot, "packages");
+  if (!existsSync(packageRoot)) return /* @__PURE__ */ new Map();
+  const packages = /* @__PURE__ */ new Map();
+  for (const entry of await readdir(packageRoot, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const root = resolve(packageRoot, entry.name);
+    try {
+      const manifest = JSON.parse(await readFile(resolve(root, "package.json"), "utf8"));
+      if (manifest === null || typeof manifest !== "object") continue;
+      const name = manifest.name;
+      if (typeof name === "string" && name.startsWith("@forgeax/engine")) {
+        packages.set(name, { root, manifest });
       }
+    } catch {
     }
-    return packages;
-  })();
-  return engineWorkspacePackagesPromise;
+  }
+  return packages;
 }
-function conditionalExport(value) {
+function conditionalExport2(value) {
   if (typeof value === "string") return value;
   if (value === null || Array.isArray(value)) return void 0;
   for (const condition of ["browser", "import", "node", "default"]) {
     const candidate = value[condition];
     if (candidate === void 0) continue;
-    const selected = conditionalExport(candidate);
+    const selected = conditionalExport2(candidate);
     if (selected !== void 0) return selected;
   }
   return void 0;
@@ -413,14 +940,14 @@ function packageExportTarget(manifest, subpath) {
     return typeof main === "string" ? main : void 0;
   }
   if (typeof exportsValue === "string" || exportsValue === null) {
-    return subpath.length === 0 ? conditionalExport(exportsValue) : void 0;
+    return subpath.length === 0 ? conditionalExport2(exportsValue) : void 0;
   }
   const keys = Object.keys(exportsValue);
   const subpathMap = keys.some((key) => key === "." || key.startsWith("./"));
-  if (!subpathMap) return subpath.length === 0 ? conditionalExport(exportsValue) : void 0;
+  if (!subpathMap) return subpath.length === 0 ? conditionalExport2(exportsValue) : void 0;
   const requested = subpath.length === 0 ? "." : `./${subpath}`;
   const exact = exportsValue[requested];
-  if (exact !== void 0) return conditionalExport(exact);
+  if (exact !== void 0) return conditionalExport2(exact);
   for (const key of keys) {
     const marker = key.indexOf("*");
     if (marker < 0) continue;
@@ -430,14 +957,14 @@ function packageExportTarget(manifest, subpath) {
     const replacement = requested.slice(prefix.length, requested.length - suffix.length);
     const exportTarget = exportsValue[key];
     if (exportTarget === void 0) continue;
-    const selected = conditionalExport(exportTarget);
+    const selected = conditionalExport2(exportTarget);
     return selected?.replaceAll("*", replacement);
   }
   return void 0;
 }
 function engineWorkspaceImport(source, packages) {
-  if (!source.startsWith("@forgeax/engine-")) return void 0;
-  const separator = source.indexOf("/", "@forgeax/engine-".length);
+  if (!source.startsWith("@forgeax/engine")) return void 0;
+  const separator = source.indexOf("/", "@forgeax/engine".length);
   const packageName = separator < 0 ? source : source.slice(0, separator);
   const subpath = separator < 0 ? "" : source.slice(separator + 1);
   const packageInfo = packages.get(packageName);
@@ -451,14 +978,25 @@ function engineWorkspaceImport(source, packages) {
   }
   return absolute;
 }
-async function createEngineWorkspaceResolver() {
-  const packages = await engineWorkspacePackages();
+async function createEngineWorkspaceResolver(projectRoot2) {
+  const binding = await readEngineBinding(projectRoot2);
+  if (!binding.ok) {
+    throw new Error(`${binding.error.code}: ${binding.error.hint}`);
+  }
+  const localRoot = binding.value?.path;
+  if (localRoot !== void 0) {
+    const inspected = await inspectEngineWorkspace(localRoot);
+    if (!inspected.ok) throw new Error(`${inspected.error.code}: ${inspected.error.hint}`);
+  }
+  const packages = await engineWorkspacePackages(localRoot);
   if (packages.size === 0) return void 0;
   return {
     name: "forgeax:devkit-engine-workspace-resolver",
+    enforce: "pre",
     async resolveId(source, importer) {
       const bareSource = source.split("?", 1)[0] ?? source;
-      if (!bareSource.startsWith("@forgeax/engine-")) return null;
+      if (!bareSource.startsWith("@forgeax/engine")) return null;
+      if (localRoot !== void 0) return engineWorkspaceImport(bareSource, packages);
       try {
         const resolved = await this.resolve(source, importer, { skipSelf: true });
         if (resolved !== null) return resolved;
@@ -574,17 +1112,20 @@ await app.pluginContext.plugin({
   return `import { forgeaxBundlerAdapter } from 'virtual:forgeax/bundler';
 import { createApp, createToolPreviewHost, createToolPreviewRecipe, fitToolPreviewCameraToAabb, gameHostPlugin, replayToolPreviewCapture } from '@forgeax/engine/app';
 import { createCatalogSource } from '@forgeax/engine/assets-runtime';
+import {
+  createRuntimeAssetImportTransport,
+  runtimeBinding,
+} from 'virtual:forgeax/pack-runtime';
 import { installCatalogLoader, projectPluginEntries } from '@forgeax/engine/plugin/loader';
 import { audioPlugin } from '@forgeax/engine/audio';
 import { webAudioPlugin } from '@forgeax/engine/audio-webaudio';
 import { physicsPlugin } from '@forgeax/engine/physics';
 import { skinningPlugin } from '@forgeax/engine/skinning';
 import { createPrimitiveMesh } from '@forgeax/engine/geometry';
-import { createDevImportTransport } from '@forgeax/engine/runtime';
 import { mat4 } from '@forgeax/engine/math';
 import { CAMERA_PROJECTION_ORTHOGRAPHIC, Camera, DirectionalLight, Materials, MeshFilter, MeshRenderer, Skylight, SkyboxBackground, TONEMAP_NONE, TONEMAP_REINHARD_EXTENDED } from '@forgeax/engine/render';
-import { projectSceneAsset, Transform, worldInstantiateScene } from '@forgeax/engine/scene';
-import { createStandaloneRuntimeAssetBinding } from '@forgeax/engine/types';
+import { Transform } from '@forgeax/engine/scene';
+import { type SceneAsset } from '@forgeax/engine/types';
 import { ParticleEffectPlayer, vfxGpuEffectContribution } from '@forgeax/engine/vfx';
 import { createVfxRuntimeHost } from '@forgeax/engine/vfx-render';
 
@@ -685,17 +1226,43 @@ const resizeCanvas = () => {
 const resizeObserver = new ResizeObserver(resizeCanvas);
 resizeObserver.observe(canvas);
 resizeCanvas();
-const runtimeScopeBinding = createStandaloneRuntimeAssetBinding(${JSON.stringify(facts.id)});
+const runtimeScopeBinding = runtimeBinding;
+if (runtimeScopeBinding === undefined) {
+  throw new Error('forgeax: Vite Pack runtime binding is required in the generated host');
+}
 const assetCatalog = createCatalogSource({
   url: import.meta.env.DEV
     ? runtimeScopeBinding.catalogUrl
     : new URL('pack-index.json', document.baseURI).href,
-  expectedScope: runtimeScopeBinding,
+  ...(import.meta.env.DEV ? { expectedScope: runtimeScopeBinding } : {}),
 });
 const bundler = {
   ...forgeaxBundlerAdapter(),
-  ...(import.meta.env.DEV ? { importTransport: createDevImportTransport(runtimeScopeBinding) } : {}),
+  ...(import.meta.env.DEV
+    ? { importTransport: createRuntimeAssetImportTransport(runtimeScopeBinding) }
+    : {}),
 };
+const assetPreparation = new WeakMap();
+
+function prepareAssetRegistry(assets) {
+  const existing = assetPreparation.get(assets);
+  if (existing !== undefined) return existing;
+  const pending = (async () => {
+    if (import.meta.env.DEV) {
+      assets.configureRuntimeBinding(runtimeScopeBinding);
+    } else {
+      assets.configurePackIndex(new URL('pack-index.json', document.baseURI).href);
+    }
+    assets.setCatalogSource(assetCatalog);
+    if (vfxRuntimeHost !== undefined) {
+      assets.installDecoder(vfxGpuEffectContribution.kind, vfxGpuEffectContribution.decoder);
+    }
+    const catalog = await assets.enumerateCatalog();
+    if (!catalog.ok) throw catalog.error;
+  })();
+  assetPreparation.set(assets, pending);
+  return pending;
+}
 
 function previewStable(value) {
   if (value instanceof ArrayBuffer) return 'ArrayBuffer:' + JSON.stringify(Array.from(new Uint8Array(value)));
@@ -756,13 +1323,14 @@ async function previewOwnerFacts(assets, resource, payload) {
 }
 
 async function prepareProject(app) {
+await prepareAssetRegistry(app.assets);
 previewWorld = app.world;
 const assets = app.assets;
 let canonicalEnvironment;
 if (resource !== undefined) {
   if (resource.kind !== 'texture') {
     if (canonicalEnvironmentGuid === null) throw new Error('canonical preview environment is unavailable');
-    const environment = await assets.load(canonicalEnvironmentGuid, 'equirect');
+    const environment = await assets.loadByGuid(assets.parseGuid(canonicalEnvironmentGuid));
     if (!environment.ok) throw environment.error;
     if (environment.value.kind !== 'equirect') {
       throw new Error(\`canonical preview environment expected equirect, received \${environment.value.kind}\`);
@@ -777,7 +1345,7 @@ if (resource !== undefined) {
     const attached = await vfxRuntimeHost.attachWorld({ world: app.world, assets });
     if (!attached.ok) throw attached.error;
   }
-  const loaded = await assets.load(resource.guid, resource.kind === 'vfx' ? 'particle-effect' : resource.kind);
+  const loaded = await assets.loadByGuid(assets.parseGuid(resource.guid));
   if (!loaded.ok) throw loaded.error;
   const payload = loaded.value;
   if (resource.kind === 'vfx' && payload.kind !== 'particle-effect') {
@@ -790,7 +1358,7 @@ if (resource !== undefined) {
   const meshMaterialHandles = resource.kind === 'mesh' && payload.kind === 'mesh'
     ? await Promise.all(payload.materialSlots.map(async (slot) => {
         if (slot.defaultMaterial === undefined) return 0;
-        const material = await assets.load(slot.defaultMaterial, 'material');
+        const material = await assets.loadByGuid(assets.parseGuid(slot.defaultMaterial));
         if (!material.ok) throw material.error;
         if (material.value.kind !== 'material') {
           throw new Error('mesh material slot resolved to a non-material asset');
@@ -920,15 +1488,13 @@ let defaultScene;
 let defaultSceneRoot;
 const defaultSceneGuid = ${JSON.stringify(facts.defaultScene)};
 if (defaultSceneGuid !== undefined) {
-  const loaded = await assets.load(defaultSceneGuid, 'scene');
+  const loaded = await assets.loadByGuid<SceneAsset>(assets.parseGuid(defaultSceneGuid));
   if (!loaded.ok) throw loaded.error;
-  const projected = await projectSceneAsset(app.world, loaded.value, (guid, kind) => assets.load(guid, kind));
-  if (!projected.ok) throw projected.error;
-  defaultScene = projected.value;
-  const handle = app.world.allocSharedRef('SceneAsset', projected.value);
-  const instantiated = worldInstantiateScene(app.world, handle);
+  defaultScene = loaded.value;
+  const handle = app.world.allocSharedRef('SceneAsset', loaded.value);
+  const instantiated = assets.instantiate<SceneAsset>(handle, app.world);
   if (!instantiated.ok) throw instantiated.error;
-  defaultSceneRoot = instantiated.value.root;
+  defaultSceneRoot = instantiated.value;
 }
 const uiRoot = document.querySelector('#game-ui');
 await app.pluginContext.plugin(gameHostPlugin({
@@ -967,8 +1533,6 @@ if (query.has('forgeax-tool-replay')) {
     ...(resource === undefined ? {} : { resource }),
     canvas,
     app: {
-      ...(assetCatalog === undefined ? {} : { assetCatalog }),
-      ...(vfxRuntimeHost === undefined ? {} : { assetDecoders: [vfxGpuEffectContribution] }),
       plugins: [${plugins.join(", ")}],
       ...(vfxRuntimeHost === undefined ? {} : { features: [vfxRuntimeHost.feature] }),
     },
@@ -1081,8 +1645,6 @@ if (query.has('forgeax-tool-replay')) {
   const result = await createApp(
     canvas,
     {
-      ...(assetCatalog === undefined ? {} : { assetCatalog }),
-      ...(vfxRuntimeHost === undefined ? {} : { assetDecoders: [vfxGpuEffectContribution] }),
       plugins: [${plugins.join(", ")}],
       ...(pointerLockAllowed === undefined ? {} : { pointerLockAllowed }),
     },
@@ -1143,32 +1705,62 @@ function htmlSource(title) {
     <div id="app-shell"><canvas id="app"></canvas><div id="game-ui"></div></div><div id="forgeax-fatal" role="alert"></div>
     <script>
       (() => {
+        const appendStructuredFailure = (value, prefix, depth, seen, lines) => {
+          if (value === null || typeof value !== 'object' || depth > 3) return;
+          if (seen.has(value)) {
+            lines.push((prefix || 'cause') + ': [circular]');
+            return;
+          }
+          seen.add(value);
+          const record = value;
+          const name = typeof record.name === 'string' && record.name.length > 0
+            ? record.name
+            : undefined;
+          const code = typeof record.code === 'string' && record.code.length > 0
+            ? record.code
+            : undefined;
+          const message = typeof record.message === 'string' && record.message.length > 0
+            ? record.message
+            : undefined;
+          if (name !== undefined || code !== undefined || message !== undefined) {
+            const identity = [name || 'Error', code].filter(Boolean).join(' ');
+            lines.push((prefix ? prefix + ': ' : '') + identity + (message ? ': ' + message : ''));
+          }
+          for (const key of ['expected', 'hint', 'reason']) {
+            if (typeof record[key] === 'string' && record[key].length > 0) {
+              lines.push((prefix ? prefix + '.' : '') + key + ': ' + record[key]);
+            }
+          }
+          for (const key of ['cause', 'detail', 'webgpuError', 'wgpuError', 'error']) {
+            const nested = record[key];
+            const nestedPrefix = (prefix ? prefix + '.' : '') + key;
+            if (nested !== null && typeof nested === 'object') {
+              appendStructuredFailure(nested, nestedPrefix, depth + 1, seen, lines);
+            } else if (typeof nested === 'string' && nested.length > 0) {
+              lines.push(nestedPrefix + ': ' + nested);
+            }
+          }
+        };
         const formatStartupFailure = (reason) => {
-          if (reason instanceof Error) return reason.message;
           if (reason !== null && typeof reason === 'object') {
-            const record = reason;
             const lines = [];
-            for (const key of ['code', 'expected', 'hint']) {
-              if (typeof record[key] === 'string' && record[key].length > 0) {
-                lines.push(key + ': ' + record[key]);
-              }
-            }
-            const detail = record.detail;
-            if (detail !== null && typeof detail === 'object') {
-              for (const key of ['reason', 'guid']) {
-                if (typeof detail[key] === 'string' && detail[key].length > 0) {
-                  lines.push('detail.' + key + ': ' + detail[key]);
-                }
-              }
-            }
+            appendStructuredFailure(reason, '', 0, new Set(), lines);
             if (lines.length > 0) return lines.join('\\n');
+            try {
+              return JSON.stringify(reason) || 'Unknown structured startup failure';
+            } catch {
+              return 'Unserializable structured startup failure';
+            }
           }
           return String(reason ?? 'Unknown startup failure');
         };
         const show = (reason) => {
           const notice = document.querySelector('#forgeax-fatal');
           if (!(notice instanceof HTMLElement)) return;
-          const message = formatStartupFailure(reason);
+          let message = formatStartupFailure(reason);
+          if (/webgpu|adapter-unavailable|no usable (rendering )?backend/i.test(message)) {
+            message += '\\n\\nRenderer diagnosis: ForgeaX supports browser WebGPU and a wgpu/WebGL2 fallback. This failure alone does not prove that WebGPU is unsupported; use the structured code, hint, and nested backend causes above.';
+          }
           notice.textContent = 'ForgeaX game failed to start.\\n' + message;
           notice.style.display = 'grid';
         };
@@ -1194,215 +1786,88 @@ async function createViteConfig(facts, command2, base = "/", options = {}) {
     writeFile(resolve(generated, "main.ts"), hostSource(facts, bootstrapRoot, canonicalKit?.guid))
   ]);
   const roots = [
-    ...projectRoots,
-    ...builtinPack === void 0 ? [] : [builtinPack],
-    ...canonicalKit === void 0 ? [] : [canonicalKit.root]
-  ];
-  const importers = [...projectImporters(facts)];
-  const runtimeBinding = createStandaloneRuntimeAssetBinding(facts.id);
-  const engineWorkspaceResolver = await createEngineWorkspaceResolver();
-  const consumerAliases = await consumerEngineAliases(facts.root);
-  const plugins = [
-    ...engineWorkspaceResolver === void 0 ? [] : [engineWorkspaceResolver],
-    forgeaxShader(),
-    pluginPack({
-      roots,
-      runtimeBinding,
-      ddc: devKitDdcRoots(facts.root),
-      refresh: command2 === "serve" ? reloadAssetHost() : void 0,
-      importers: [
-        audioImporter,
-        imageImporter,
-        fbxImporter,
-        gltfImporter,
-        fontImporter,
-        ...importers
-      ],
-      cookers: [createMaterialPackCooker(roots), createParticleCodeNativeCookerFromRoots(roots)],
-      ignorePath
-    })
-  ];
-  return {
-    root: generated,
-    base,
-    configFile: false,
-    publicDir: facts.assetPublicDir === void 0 ? false : resolve(facts.root, facts.assetPublicDir),
-    plugins,
-    resolve: {
-      alias: consumerAliases,
-      dedupe: ["@forgeax/engine-app", "@forgeax/engine-ecs", "@forgeax/engine-runtime"]
-    },
-    server: { fs: { allow: [facts.root, ...roots] } },
-    build: {
-      target: "esnext",
-      outDir: options.outDir ?? resolve(facts.root, "dist"),
-      emptyOutDir: true,
-      rollupOptions: { input: resolve(generated, "index.html") }
-    }
-  };
-}
-var hostRequire, engineWorkspacePackagesPromise;
-var init_host = __esm({
-  "src/host.ts"() {
-    hostRequire = createRequire(import.meta.url);
-  }
-});
-function projectError(code, expected, hint, detail) {
-  return { ok: false, error: { code, expected, hint, detail } };
-}
-async function readJson(path) {
-  return JSON.parse(await readFile(path, "utf8"));
-}
-function firstUnsupportedStandaloneRealm(entries2, inheritedRealm = "engine") {
-  for (const entry of entries2) {
-    const realm = entry.realm ?? inheritedRealm ?? "engine";
-    if (realm === "host") return { id: entry.id, realm };
-    if (entry.group === true) {
-      const unsupported = firstUnsupportedStandaloneRealm(
-        entry.config,
-        realm
-      );
-      if (unsupported !== void 0) return unsupported;
-    }
-  }
-  return void 0;
-}
-function pluginModuleNames(entries2) {
-  return entries2.flatMap(
-    (entry) => entry.group === true ? pluginModuleNames(entry.config) : [entry.name]
-  );
-}
-async function readProjectFacts(rootInput = process.cwd()) {
-  const root = resolve(rootInput);
-  let forgeValue;
-  let packageValue;
-  try {
-    [forgeValue, packageValue] = await Promise.all([
-      readJson(resolve(root, "forge.json")),
-      readJson(resolve(root, "package.json"))
-    ]);
-  } catch (cause) {
-    return projectError(
-      "project-manifest-unreadable",
-      "readable forge.json and package.json files",
-      "Run the command from a ForgeaX game root or pass its directory.",
-      { root, reason: cause instanceof Error ? cause.message : String(cause) }
-    );
-  }
-  if (forgeValue === null || typeof forgeValue !== "object") {
-    return projectError(
-      "project-manifest-invalid",
-      "forge.json to contain an object",
-      "Repair forge.json before running DevKit.",
-      { root }
-    );
-  }
-  if (packageValue === null || typeof packageValue !== "object") {
-    return projectError(
-      "package-manifest-invalid",
-      "package.json to contain an object",
-      "Repair package.json before running DevKit.",
-      { root }
-    );
-  }
-  const parsedForge = GameProjectSchema.safeParse(forgeValue);
-  if (!parsedForge.success) {
-    return projectError(
-      "project-manifest-invalid",
-      "forge.json to satisfy @forgeax/engine-project GameProjectSchema",
-      "Repair the fields reported by the authoritative project schema.",
-      { root, issues: parsedForge.error.issues }
-    );
-  }
-  const forge = parsedForge.data;
-  if (forge.id.length === 0 || forge.name.length === 0 || forge.entry === void 0 || forge.entry.length === 0) {
-    return projectError(
-      "project-manifest-invalid",
-      "forge.json to declare id, name, and entry",
-      "Restore the project entry; plugin Entries remain optional additions.",
-      { root }
-    );
-  }
-  const plugins = forge.plugins ?? [];
-  const unsupportedRealm = firstUnsupportedStandaloneRealm(plugins);
-  if (unsupportedRealm !== void 0) {
-    return projectError(
-      "project-plugin-realm-unsupported",
-      "the standalone Devkit host to contain only engine-realm plugin Entries",
-      "Move Host or build plugins to a host that owns that physical realm.",
-      { root, ...unsupportedRealm }
-    );
-  }
-  const entryPath = isAbsolute(forge.entry) ? forge.entry : resolve(root, forge.entry);
-  try {
-    await readFile(entryPath);
-  } catch {
-    return projectError(
-      "project-entry-missing",
-      "forge.json#entry to resolve to a readable module",
-      "Restore the game entry or update forge.json#entry.",
-      { root, entry: forge.entry }
-    );
-  }
-  const packageJson = packageValue;
-  const forgeax = packageJson.forgeax;
-  const configuredRoots = forgeax !== null && typeof forgeax === "object" ? forgeax.assets?.roots : void 0;
-  const assetRoots = Array.isArray(configuredRoots) && configuredRoots.every((value) => typeof value === "string") ? configuredRoots : ["assets"];
-  const configuredImporters = forgeax !== null && typeof forgeax === "object" ? forgeax.assets?.importers : void 0;
-  const assetImporters = Array.isArray(configuredImporters) && configuredImporters.every((value) => typeof value === "string") ? configuredImporters : [];
-  const configuredPublicDir = forgeax !== null && typeof forgeax === "object" ? forgeax.assets?.publicDir : void 0;
-  const assetPublicDir = typeof configuredPublicDir === "string" ? configuredPublicDir : void 0;
-  const physics = forge.physics === "2d" || forge.physics === "3d" ? forge.physics : void 0;
-  const defaultScene = typeof forge.defaultScene === "string" && forge.defaultScene.length > 0 ? forge.defaultScene : void 0;
-  const normalizedEntry = forge.entry.startsWith("./") ? forge.entry : `./${forge.entry}`;
-  const bootstrapEntry = pluginModuleNames(plugins).map((name) => name.startsWith("./") ? name : `./${name}`).includes(normalizedEntry) ? void 0 : forge.entry;
+    ...projectRoots,
+    ...builtinPack === void 0 ? [] : [builtinPack],
+    ...canonicalKit === void 0 ? [] : [canonicalKit.root]
+  ];
+  const importers = [...projectImporters(facts)];
+  const runtimeBinding = createStandaloneRuntimeAssetBinding(facts.id);
+  const engineWorkspaceResolver = await createEngineWorkspaceResolver(facts.root);
+  const consumerAliases = await consumerEngineAliases(facts.root);
+  const plugins = [
+    ...engineWorkspaceResolver === void 0 ? [] : [engineWorkspaceResolver],
+    forgeaxShader(),
+    pluginPack({
+      roots,
+      runtimeBinding,
+      ddc: devKitDdcRoots(facts.root),
+      refresh: command2 === "serve" ? reloadAssetHost() : void 0,
+      importers: [
+        audioImporter,
+        imageImporter,
+        fbxImporter,
+        gltfImporter,
+        fontImporter,
+        ...importers
+      ],
+      cookers: [createMaterialPackCooker(roots), createParticleCodeNativeCookerFromRoots(roots)],
+      ignorePath
+    })
+  ];
   return {
-    ok: true,
-    value: {
-      root,
-      id: forge.id,
-      name: forge.name,
-      entry: forge.entry,
-      ...bootstrapEntry === void 0 ? {} : { bootstrapEntry },
-      plugins,
-      ...physics === void 0 ? {} : { physics },
-      ...defaultScene === void 0 ? {} : { defaultScene },
-      assetRoots,
-      ...assetImporters.length === 0 ? {} : { assetImporters },
-      ...assetPublicDir === void 0 ? {} : { assetPublicDir },
-      packageJson
+    root: generated,
+    base,
+    configFile: false,
+    publicDir: facts.assetPublicDir === void 0 ? false : resolve(facts.root, facts.assetPublicDir),
+    plugins,
+    resolve: {
+      alias: consumerAliases,
+      dedupe: ["@forgeax/engine"]
+    },
+    server: { ...options.server, fs: { allow: [facts.root, ...roots] } },
+    build: {
+      target: "esnext",
+      outDir: options.outDir ?? resolve(facts.root, "dist"),
+      emptyOutDir: true,
+      rollupOptions: { input: resolve(generated, "index.html") }
     }
   };
 }
-function isCommandError(value) {
-  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
-  const candidate = value;
-  return typeof candidate.code === "string" && typeof candidate.expected === "string" && typeof candidate.hint === "string" && candidate.detail !== null && typeof candidate.detail === "object" && !Array.isArray(candidate.detail);
-}
-function commandError(cause, fallbackCode) {
-  if (isCommandError(cause)) return cause;
+var hostRequire;
+var init_host = __esm({
+  "src/host.ts"() {
+    init_engine_binding();
+    hostRequire = createRequire(import.meta.url);
+  }
+});
+
+// src/types.ts
+function parseProjectPortOption(value, provided) {
+  if (!provided) return { ok: true, value: void 0 };
+  if (value !== void 0 && /^(0|[1-9]\d*)$/.test(value)) {
+    const port = Number(value);
+    if (Number.isSafeInteger(port) && port <= 65535) return { ok: true, value: port };
+  }
   return {
-    code: fallbackCode,
-    expected: "the ForgeaX command to complete",
-    hint: "Inspect the underlying diagnostic and repair the owning input.",
-    detail: { reason: cause instanceof Error ? cause.message : String(cause) }
+    ok: false,
+    error: {
+      code: "cli-parse-error",
+      expected: "--port to be 0 or an integer from 1 to 65535",
+      hint: "Omit --port for strict 5173, pass a positive port for a strict binding, or pass 0 for an OS-assigned port.",
+      detail: { option: "--port", received: value ?? null }
+    }
   };
 }
-var init_project = __esm({
-  "src/project.ts"() {
+function resolveProjectPort(port) {
+  return { port: port ?? 5173, strictPort: port !== 0 };
+}
+var init_types = __esm({
+  "src/types.ts"() {
   }
 });
 function failure(error) {
   return { ok: false, error };
 }
-function producerFailure(stderr, fallback, detail) {
-  try {
-    const parsed = JSON.parse(stderr.at(-1) ?? "");
-    if (isCommandError(parsed)) return failure(parsed);
-  } catch {
-  }
-  return failure({ ...fallback, detail: { ...detail, diagnostic: stderr.join("\n") } });
-}
 async function sourcesAt(path) {
   const info = await stat(path);
   if (info.isFile()) return [path];
@@ -1486,15 +1951,16 @@ async function addGltf(sourcePath, dryRun2) {
     stderrWrite: (line) => stderr.push(line)
   });
   if (exitCode !== 0) {
-    return producerFailure(
-      stderr,
-      {
+    try {
+      return failure(JSON.parse(stderr.at(-1) ?? ""));
+    } catch {
+      return failure({
         code: "asset-add-failed",
         expected: "the glTF producer to create or reuse a valid sidecar",
-        hint: "Inspect the glTF source and its external references."
-      },
-      { source: sourcePath }
-    );
+        hint: "Inspect the glTF source and its external references.",
+        detail: { source: sourcePath, diagnostic: stderr.join("\n") }
+      });
+    }
   }
   return { ok: true, value: { source: sourcePath, metaPath: `${sourcePath}.meta.json` } };
 }
@@ -1537,15 +2003,16 @@ async function entries(options) {
     { stdoutWrite: (line) => stdout.push(line), stderrWrite: (line) => stderr.push(line) }
   );
   if (!result.ok) {
-    return producerFailure(
-      stderr,
-      {
+    try {
+      return failure(JSON.parse(stderr.at(-1) ?? ""));
+    } catch {
+      return failure({
         code: "asset-authority-invalid",
         expected: "all asset roots and sidecars to pass the pack scanner",
-        hint: "Repair the first invalid asset authority reported by the scanner."
-      },
-      {}
-    );
+        hint: "Repair the first invalid asset authority reported by the scanner.",
+        detail: { diagnostic: stderr.join("\n") }
+      });
+    }
   }
   return { ok: true, value: { facts: facts.value, entries: result.value } };
 }
@@ -1630,7 +2097,6 @@ var init_package = __esm({
         "@forgeax/engine-audio-webaudio": "workspace:*",
         "@forgeax/engine-fbx": "workspace:*",
         "@forgeax/engine-font": "workspace:*",
-        "@forgeax/engine-geometry": "workspace:*",
         "@forgeax/engine-gltf": "workspace:*",
         "@forgeax/engine-image": "workspace:*",
         "@forgeax/engine-input": "workspace:*",
@@ -1640,6 +2106,8 @@ var init_package = __esm({
         "@forgeax/engine-preview": "workspace:*",
         "@forgeax/engine-project": "workspace:*",
         "@forgeax/engine-rhi-debug": "workspace:*",
+        "@forgeax/engine-rhi-null": "workspace:*",
+        "@forgeax/engine-rhi-webgpu": "workspace:*",
         "@forgeax/engine-render": "workspace:*",
         "@forgeax/engine-render-graph": "workspace:*",
         "@forgeax/engine-runtime": "workspace:*",
@@ -1654,10 +2122,10 @@ var init_package = __esm({
         jiti: "1.21.7",
         playwright: "1.60.0",
         vite: "8.0.10",
-        vitest: "4.1.5"
+        vitest: "4.0.18",
+        webgpu: "^0.4.0"
       },
       devDependencies: {
-        "@forgeax/engine-rhi-null": "workspace:*",
         "@types/node": "^20.14.0"
       },
       forgeax: {
@@ -1829,7 +2297,7 @@ var init_init = __esm({
       "@webgpu/types": "0.1.71",
       tsx: "4.23.1",
       typescript: "6.0.3",
-      vitest: "4.1.5"
+      vitest: "4.0.18"
     };
   }
 });
@@ -1871,6 +2339,20 @@ var init_sdk = __esm({
   "src/sdk.ts"() {
   }
 });
+function agentOnboarding(sdk, projectRoot2) {
+  const root = projectRoot2 ?? sdk.root;
+  return {
+    read: [
+      resolve(root, "AGENTS.md"),
+      resolve(root, "skills", "forgeax-engine-sdk", "SKILL.md"),
+      resolve(root, "skills", "forgeax-engine-sdk", "references", "feature-catalog.md")
+    ],
+    next: projectRoot2 === void 0 ? {
+      cwd: root,
+      argv: ["node", "./bin/forgeax.mjs", "new", "../my-game"]
+    } : { cwd: root, argv: ["pnpm", "exec", "forgeax", "list", "--json"] }
+  };
+}
 function sdkInitPath(sdk) {
   return resolve(sdk.root, ...SDK_INIT_PATH);
 }
@@ -1882,19 +2364,21 @@ function sdkProjectInstallArgs(store) {
     "install",
     "--frozen-lockfile",
     "--ignore-scripts",
+    "--config.pm-on-fail=ignore",
     "--side-effects-cache=true",
     "--child-concurrency=1"
   ];
-  return store === void 0 ? common : [...common, "--offline", "--trust-lockfile", "--store-dir", store];
+  return store === void 0 ? common : [...common, "--offline", "--config.trust-lockfile=true", "--store-dir", store];
 }
 function sdkBootstrapInstallArgs(store) {
   const common = [
     "install",
     "--frozen-lockfile",
+    "--config.pm-on-fail=ignore",
     "--child-concurrency=1",
     "--side-effects-cache=true"
   ];
-  return store === void 0 ? common : [...common, "--offline", "--trust-lockfile", "--store-dir", store];
+  return store === void 0 ? common : [...common, "--offline", "--config.trust-lockfile=true", "--store-dir", store];
 }
 function supportedPnpm(version) {
   const [major = 0, minor = 0] = version.split(".").map(Number);
@@ -1984,7 +2468,8 @@ async function sdkInitCommand(sdk, options = {}) {
   const report = {
     ...state,
     root: sdk.root,
-    store: sdk.store === void 0 ? "registry" : "offline"
+    store: sdk.store === void 0 ? "registry" : "offline",
+    onboarding: agentOnboarding(sdk)
   };
   if (options.dryRun === true || options.install === false) return { ok: true, value: report };
   let staging;
@@ -2019,6 +2504,107 @@ var init_sdk_bootstrap = __esm({
     SDK_INIT_SCHEMA_VERSION = "1.0.0";
   }
 });
+
+// src/sdk-update.ts
+function parseVersion(version) {
+  const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(
+    version
+  );
+  if (match === null) return void 0;
+  const major = match[1];
+  const minor = match[2];
+  const patch = match[3];
+  if (major === void 0 || minor === void 0 || patch === void 0) return void 0;
+  const prerelease = match[4]?.split(".");
+  if (prerelease?.some(
+    (identifier) => identifier.length === 0 || /^\d+$/.test(identifier) && /^0\d+/.test(identifier)
+  )) {
+    return void 0;
+  }
+  return {
+    core: [major, minor, patch],
+    ...prerelease === void 0 ? {} : { prerelease }
+  };
+}
+function compareNumericIdentifier(current, latest) {
+  if (current.length !== latest.length) return latest.length > current.length ? 1 : -1;
+  if (current === latest) return 0;
+  return latest > current ? 1 : -1;
+}
+function comparePrerelease(current, latest) {
+  const length = Math.max(current.length, latest.length);
+  for (let index = 0; index < length; index += 1) {
+    const currentIdentifier = current[index];
+    const latestIdentifier = latest[index];
+    if (currentIdentifier === void 0) return 1;
+    if (latestIdentifier === void 0) return -1;
+    if (currentIdentifier === latestIdentifier) continue;
+    const currentNumeric = /^\d+$/.test(currentIdentifier);
+    const latestNumeric = /^\d+$/.test(latestIdentifier);
+    if (currentNumeric && latestNumeric) {
+      return compareNumericIdentifier(currentIdentifier, latestIdentifier);
+    }
+    if (currentNumeric !== latestNumeric) return latestNumeric ? -1 : 1;
+    return latestIdentifier > currentIdentifier ? 1 : -1;
+  }
+  return 0;
+}
+function newerSdkVersion(currentVersion, latestVersion) {
+  const current = parseVersion(currentVersion);
+  const latest = parseVersion(latestVersion);
+  if (current === void 0 || latest === void 0) return false;
+  for (let index = 0; index < current.core.length; index += 1) {
+    const precedence = compareNumericIdentifier(
+      current.core[index] ?? "0",
+      latest.core[index] ?? "0"
+    );
+    if (precedence !== 0) return precedence > 0;
+  }
+  if (current.prerelease !== void 0 && latest.prerelease === void 0) return true;
+  if (current.prerelease === void 0 || latest.prerelease === void 0) return false;
+  return comparePrerelease(current.prerelease, latest.prerelease) > 0;
+}
+function offline() {
+  return ["1", "true"].includes((process.env.npm_config_offline ?? "").toLowerCase());
+}
+async function checkSdkUpdate(currentVersion) {
+  if (process.env.FORGEAX_DISABLE_UPDATE_CHECK === "1") {
+    return { status: "skipped", currentVersion, reason: "disabled" };
+  }
+  if (offline()) return { status: "skipped", currentVersion, reason: "offline" };
+  try {
+    const registry = process.env.npm_config_registry ?? "https://registry.npmjs.org/";
+    const response = await fetch(
+      new URL("@forgeax%2Fengine-sdk", `${registry.replace(/\/$/, "")}/`),
+      {
+        headers: { accept: "application/vnd.npm.install-v1+json" },
+        signal: AbortSignal.timeout(2e3)
+      }
+    );
+    if (!response.ok) throw new Error(`registry-http-${response.status}`);
+    const metadata = await response.json();
+    const latestVersion = metadata["dist-tags"]?.latest;
+    if (typeof latestVersion !== "string") throw new Error("registry-latest-version-missing");
+    return newerSdkVersion(currentVersion, latestVersion) ? {
+      status: "available",
+      currentVersion,
+      latestVersion,
+      migrationRisk: UPDATE_MIGRATION_RISK
+    } : { status: "current", currentVersion, latestVersion };
+  } catch (cause) {
+    return {
+      status: "unavailable",
+      currentVersion,
+      reason: cause instanceof Error ? cause.message : String(cause)
+    };
+  }
+}
+var UPDATE_MIGRATION_RISK;
+var init_sdk_update = __esm({
+  "src/sdk-update.ts"() {
+    UPDATE_MIGRATION_RISK = "Install a newer SDK in a separate directory. Existing games remain pinned and are not migrated automatically; review release notes and migrate and test each game before changing its Engine version.";
+  }
+});
 function slash(path) {
   return path.split(sep).join("/");
 }
@@ -2646,9 +3232,16 @@ async function newCommand(options = {}) {
         env: { ...process.env, CI: "true" },
         maxBuffer: 16 * 1024 * 1024
       });
+      const sdkUpdate = await checkSdkUpdate(sdk.manifest.sdkVersion);
       return {
         ok: true,
-        value: { root, template: templateId, sdkVersion: sdk.manifest.sdkVersion }
+        value: {
+          root,
+          template: templateId,
+          sdkVersion: sdk.manifest.sdkVersion,
+          onboarding: agentOnboarding(sdk, root),
+          sdkUpdate
+        }
       };
     } catch (cause) {
       if (staging !== void 0) await rm(staging, { recursive: true, force: true });
@@ -2681,6 +3274,7 @@ var init_bootstrap_commands = __esm({
     init_project();
     init_sdk();
     init_sdk_bootstrap();
+    init_sdk_update();
     init_skill_install();
     execFileAsync2 = promisify(execFile);
   }
@@ -2692,7 +3286,7 @@ __export(plugin_authoring_exports, {
   pluginInstallCommand: () => pluginInstallCommand,
   pluginUninstallCommand: () => pluginUninstallCommand
 });
-async function readManifest(root) {
+async function readManifest2(root) {
   const path = resolve(root, "forge.json");
   try {
     const raw = await readFile(path, "utf8");
@@ -2745,7 +3339,7 @@ async function mutateDependency(root, action, dependency) {
 }
 async function pluginInstallCommand(options) {
   const root = resolve(options.root ?? process.cwd());
-  const manifest = await readManifest(root);
+  const manifest = await readManifest2(root);
   if (!manifest.ok) return manifest;
   const parsed = GameProjectSchema.safeParse(manifest.value.value);
   if (!parsed.success) {
@@ -2798,7 +3392,7 @@ async function pluginInstallCommand(options) {
 }
 async function pluginUninstallCommand(options) {
   const root = resolve(options.root ?? process.cwd());
-  const manifest = await readManifest(root);
+  const manifest = await readManifest2(root);
   if (!manifest.ok) return manifest;
   const parsed = GameProjectSchema.safeParse(manifest.value.value);
   if (!parsed.success) {
@@ -2849,491 +3443,12 @@ var init_plugin_authoring = __esm({
     execFileAsync3 = promisify(execFile);
   }
 });
-var RhiError;
-var init_dist2 = __esm({
-  "../rhi/dist/index.mjs"() {
-    RhiError = class extends Error {
-      code;
-      expected;
-      hint;
-      detail;
-      constructor(args2) {
-        super(`[RhiError ${args2.code}] expected: ${args2.expected}; hint: ${args2.hint}`);
-        this.name = "RhiError";
-        this.code = args2.code;
-        this.expected = args2.expected;
-        this.hint = args2.hint;
-        this.detail = args2.detail;
-      }
-    };
-  }
-});
-function readPassLabel(desc) {
-  if (desc && typeof desc.label === "string" && desc.label.length > 0) {
-    return desc.label;
-  }
-  return "<unnamed>";
-}
-function readRecord(handle) {
-  if (handle === null || typeof handle !== "object") return void 0;
-  const tagged = handle;
-  return tagged[BOOKKEEPING_KEY];
-}
-function isHandleDestroyed(handle) {
-  if (readRecord(handle)?.destroyed === true) {
-    return err(
-      new RhiError({
-        code: "destroy-after-destroy",
-        expected: "GPU buffer/texture handle has not been destroyed yet",
-        hint: "object already destroyed; track lifecycle in caller or check isDestroyed before re-destroy"
-      })
-    );
-  }
-  return ok(void 0);
-}
-function acquireCanvasContext(_canvas) {
-  return ok(new RhiNullCanvasContext());
-}
-function createShaderModule(_device, _desc) {
-  return Promise.resolve(ok({}));
-}
-function requestAdapter(_opts, _compatibleSurface) {
-  return Promise.resolve(ok(new RhiNullAdapter()));
-}
-var RhiNullRenderPassEncoder, RhiNullComputePassEncoder, DeviceCounter, RhiNullCommandEncoder, BOOKKEEPING_KEY, Bookkeeper, nextDeviceId, RhiNullDevice, EMPTY_FEATURES, EMPTY_LIMITS, NEVER, RhiNullQueue, RhiNullAdapter, RhiNullCanvasContext, rhi;
-var init_dist3 = __esm({
-  "../rhi-null/dist/index.mjs"() {
-    init_dist2();
-    RhiNullRenderPassEncoder = class {
-      /** Number of draw* calls issued on this pass (AC-06 readback). */
-      drawCount = 0;
-      bindGroupCount = 0;
-      /** Most recent setVertexBuffer / setBindGroup ownership validation; ok unless
-       *  a foreign handle was passed (AC-09 readback). */
-      lastValidation = ok(void 0);
-      bookkeeper;
-      counter;
-      passName;
-      constructor(bookkeeper, counter, passName) {
-        this.bookkeeper = bookkeeper;
-        this.counter = counter;
-        this.passName = passName;
-      }
-      setPipeline(_pipeline) {
-      }
-      setVertexBuffer(_slot, buffer, _offset, _size) {
-        this.lastValidation = this.bookkeeper.validateOwnership(buffer);
-      }
-      setIndexBuffer(_buffer, _format, _offset, _size) {
-      }
-      setBindGroup(_index, bindGroup, _dynamicOffsetsData, _dynamicOffsetsDataStart, _dynamicOffsetsDataLength) {
-        this.bindGroupCount++;
-        this.counter?.recordBindGroup();
-        this.lastValidation = this.bookkeeper.validateOwnership(bindGroup);
-      }
-      draw(_vertexCount, _instanceCount, _firstVertex, _firstInstance) {
-        this.drawCount++;
-        this.counter?.recordDraw();
-      }
-      drawIndexed(_indexCount, _instanceCount, _firstIndex, _baseVertex, _firstInstance) {
-        this.drawCount++;
-        this.counter?.recordDraw();
-      }
-      end() {
-        this.counter?.recordPassName(this.passName);
-      }
-      setViewport(_x, _y, _w, _h, _minDepth, _maxDepth) {
-      }
-      setScissorRect(_x, _y, _w, _h) {
-      }
-      setBlendConstant(_color) {
-      }
-      setStencilReference(_reference) {
-      }
-      drawIndirect(_indirectBuffer, _indirectOffset) {
-        this.drawCount++;
-        this.counter?.recordDraw();
-      }
-      drawIndexedIndirect(_indirectBuffer, _indirectOffset) {
-        this.drawCount++;
-        this.counter?.recordDraw();
-      }
-      pushDebugGroup(_groupLabel) {
-      }
-      popDebugGroup() {
-      }
-      insertDebugMarker(_markerLabel) {
-      }
-      executeBundles(_bundles) {
-        return ok(void 0);
-      }
-      beginOcclusionQuery(_queryIndex) {
-        return ok(void 0);
-      }
-      endOcclusionQuery() {
-        return ok(void 0);
-      }
-    };
-    RhiNullComputePassEncoder = class {
-      /** Number of dispatchWorkgroups calls issued on this pass (readback). */
-      dispatchCount = 0;
-      /** Most recent setBindGroup ownership validation (AC-09 readback). */
-      lastValidation = ok(void 0);
-      bookkeeper;
-      counter;
-      passName;
-      constructor(bookkeeper, counter, passName) {
-        this.bookkeeper = bookkeeper;
-        this.counter = counter;
-        this.passName = passName;
-      }
-      setPipeline(_pipeline) {
-      }
-      setBindGroup(_index, bindGroup, _dynamicOffsets) {
-        this.lastValidation = this.bookkeeper.validateOwnership(bindGroup);
-      }
-      dispatchWorkgroups(_x, _y, _z) {
-        this.dispatchCount++;
-        this.counter?.recordDispatch();
-      }
-      dispatchWorkgroupsIndirect(indirectBuffer, _indirectOffset) {
-        this.lastValidation = this.bookkeeper.validateOwnership(indirectBuffer);
-        this.dispatchCount++;
-        this.counter?.recordDispatch();
-      }
-      end() {
-        this.counter?.recordPassName(this.passName);
-      }
-    };
-    DeviceCounter = class {
-      constructor(device) {
-        this.device = device;
-      }
-      device;
-      recordDraw() {
-        this.device.totalDrawCount++;
-      }
-      recordDispatch() {
-        this.device.totalDispatchCount++;
-      }
-      recordBindGroup() {
-        this.device.totalBindGroupCount++;
-      }
-      recordPassName(name) {
-        this.device.framePassNames.push(name);
-      }
-    };
-    RhiNullCommandEncoder = class {
-      bookkeeper;
-      counter;
-      constructor(bookkeeper, device) {
-        this.bookkeeper = bookkeeper;
-        this.counter = new DeviceCounter(device);
-      }
-      beginRenderPass(desc) {
-        const label = readPassLabel(desc);
-        return new RhiNullRenderPassEncoder(this.bookkeeper, this.counter, label);
-      }
-      beginComputePass(desc) {
-        const label = readPassLabel(desc);
-        return new RhiNullComputePassEncoder(this.bookkeeper, this.counter, label);
-      }
-      copyBufferToBuffer(_source, _sourceOffsetOrDestination, _destinationOrSize, _destinationOffset, _size) {
-      }
-      copyBufferToTexture(_source, _destination, _copySize) {
-      }
-      copyTextureToBuffer(_source, _destination, _copySize) {
-      }
-      copyTextureToTexture(_source, _destination, _copySize) {
-      }
-      clearBuffer(_buffer, _offset, _size) {
-      }
-      resolveQuerySet(_querySet, _firstQuery, _queryCount, _destination, _destinationOffset) {
-        return ok(void 0);
-      }
-      writeTimestamp(_querySet, _queryIndex) {
-      }
-      pushDebugGroup(_groupLabel) {
-      }
-      popDebugGroup() {
-      }
-      insertDebugMarker(_markerLabel) {
-      }
-      finish() {
-        return ok(this.bookkeeper.register("CommandBuffer"));
-      }
-    };
-    BOOKKEEPING_KEY = /* @__PURE__ */ Symbol("forgeax-rhi-null-bookkeeping");
-    Bookkeeper = class {
-      deviceId;
-      nextHandleId = 0;
-      records = /* @__PURE__ */ new Map();
-      constructor(deviceId) {
-        this.deviceId = deviceId;
-      }
-      /**
-       * Register a freshly-minted handle of the given kind, returning a plain
-       * object that carries its ledger row. The caller casts the return value to
-       * the concrete brand (`as unknown as Buffer` etc.).
-       */
-      register(kind) {
-        const id = this.nextHandleId++;
-        const record = {
-          id,
-          kind,
-          destroyed: false,
-          sourceDeviceId: this.deviceId
-        };
-        this.records.set(id, record);
-        return { [BOOKKEEPING_KEY]: record };
-      }
-      /**
-       * Mark a handle destroyed. Fail-fasts on a second destroy
-       * ('destroy-after-destroy') or on a handle issued by a different device
-       * ('rhi-not-available'); otherwise flips the destroyed flag and returns ok.
-       */
-      destroy(handle) {
-        const ownership = this.validateOwnership(handle);
-        if (!ownership.ok) return ownership;
-        const destroyedCheck = isHandleDestroyed(handle);
-        if (!destroyedCheck.ok) return destroyedCheck;
-        ownership.value.destroyed = true;
-        return ok(void 0);
-      }
-      /**
-       * Report whether a handle has already been destroyed (true once destroy()
-       * has flipped its flag). Used by command-stream methods that must not
-       * consume a stale handle.
-       */
-      isDestroyed(handle) {
-        return readRecord(handle)?.destroyed === true;
-      }
-      /**
-       * Validate that a handle was issued by THIS device. Returns the ledger row on
-       * success so callers can mutate it (e.g. flip destroyed); returns
-       * 'rhi-not-available' for a foreign handle (AC-09 — no silent pass).
-       */
-      validateOwnership(handle) {
-        const record = readRecord(handle);
-        if (record === void 0 || record.sourceDeviceId !== this.deviceId) {
-          return err(
-            new RhiError({
-              code: "rhi-not-available",
-              expected: "handle was issued by this RhiNull device",
-              hint: "do not pass a handle created on a different RhiNull device into this device; create resources on the device they are used with"
-            })
-          );
-        }
-        return ok(record);
-      }
-      /**
-       * Return all ledger rows as a readonly array. M3 unit tests (w17) read this
-       * to assert create/destroy pairing, BGL/PSO shape counts, and resource
-       * lifecycle coverage (AC-05/06/07). Returns a snapshot of the current Map
-       * so callers can iterate without a stale reference after further mutations.
-       */
-      allRecords() {
-        return [...this.records.values()];
-      }
-      /** Report the total number of records in the ledger. */
-      recordCount() {
-        return this.records.size;
-      }
-    };
-    nextDeviceId = 0;
-    RhiNullDevice = class {
-      internalBookkeeper;
-      nullQueue;
-      encoderFactory;
-      /** Per-frame total draw count across all pass encoders executed this frame
-       *  (aggregated by the command encoder on finish, then reset). M3 unit tests
-       *  (w17) read this to assert draw count >= 1 (AC-06). */
-      totalDrawCount = 0;
-      /** Per-frame total direct and indirect compute dispatch count. */
-      totalDispatchCount = 0;
-      /** Per-frame total bind group set count (AC-06 / AC-05 readback). */
-      totalBindGroupCount = 0;
-      /** Per-frame pass names executed this frame, in schedule order (AC-04). */
-      framePassNames = [];
-      /** The per-device handle ledger — exposed so M3 tests can assert create/destroy
-       *  pairing and BGL/PSO shape counts (AC-05/06/07). */
-      get bookkeeper() {
-        return this.internalBookkeeper;
-      }
-      constructor(queue, encoderFactory) {
-        this.internalBookkeeper = new Bookkeeper(nextDeviceId++);
-        this.nullQueue = queue;
-        this.encoderFactory = encoderFactory;
-      }
-      get caps() {
-        return {
-          backendKind: "null",
-          compute: true,
-          timestampQuery: false,
-          timestampPeriodNanoseconds: null,
-          indirectDrawing: true,
-          textureCompressionBc: false,
-          textureCompressionEtc2: false,
-          textureCompressionAstc: false,
-          // 3 wgpu-native-only reserved flags stay false on non-native backends
-          // (D-5); the headless backend is not a native runtime.
-          multiDrawIndirect: false,
-          pushConstants: false,
-          textureBindingArray: false,
-          samplerAliasing: true,
-          firstInstanceIndirect: true,
-          storageBuffer: true,
-          storageTexture: true,
-          rgba16floatRenderable: true,
-          rg11b10ufloatRenderable: true,
-          float32Filterable: true,
-          maxColorAttachments: 8
-        };
-      }
-      get features() {
-        return EMPTY_FEATURES;
-      }
-      get limits() {
-        return EMPTY_LIMITS;
-      }
-      get queue() {
-        return this.nullQueue;
-      }
-      // forgeax-async-whitelist: dom-native — spec `GPUDevice.lost` Promise
-      // passthrough. The headless backend never loses a device (no GPU), so the
-      // Promise stays unsettled for the lifetime of the device, mirroring a live
-      // device that never transitions to the lost state.
-      get lost() {
-        return NEVER;
-      }
-      createBuffer(_desc) {
-        return ok(this.internalBookkeeper.register("Buffer"));
-      }
-      createTexture(_desc) {
-        return ok(this.internalBookkeeper.register("Texture"));
-      }
-      destroyBuffer(buf) {
-        return this.internalBookkeeper.destroy(buf);
-      }
-      destroyQuerySet(querySet) {
-        return this.internalBookkeeper.destroy(querySet);
-      }
-      destroyTexture(tex) {
-        return this.internalBookkeeper.destroy(tex);
-      }
-      createTextureView(_texture, _desc) {
-        return ok(this.internalBookkeeper.register("TextureView"));
-      }
-      createSampler(_desc) {
-        return ok(this.internalBookkeeper.register("Sampler"));
-      }
-      createBindGroupLayout(_desc) {
-        return ok(this.internalBookkeeper.register("BindGroupLayout"));
-      }
-      createBindGroup(_desc) {
-        return ok(this.internalBookkeeper.register("BindGroup"));
-      }
-      createPipelineLayout(_desc) {
-        return ok(this.internalBookkeeper.register("PipelineLayout"));
-      }
-      createRenderPipeline(_desc) {
-        return ok(this.makePipeline("RenderPipeline"));
-      }
-      createComputePipeline(_desc) {
-        return ok(this.makePipeline("ComputePipeline"));
-      }
-      createQuerySet(desc) {
-        if (desc.type === "timestamp") {
-          return err(
-            new RhiError({
-              code: "feature-not-enabled",
-              expected: "caps.timestampQuery === true (timestamp-query feature)",
-              hint: "RhiNull is structural-only and cannot produce GPU timestamp ticks"
-            })
-          );
-        }
-        return ok(this.internalBookkeeper.register("QuerySet"));
-      }
-      createCommandEncoder(_desc) {
-        return ok(this.encoderFactory(this.internalBookkeeper, this));
-      }
-      /**
-       * Mint a pipeline handle whose object also carries the no-op
-       * `getBindGroupLayout(index)` ops method (D-2). The prod auto-layout path
-       * (debug-draw.ts) and the existing mock unit tests both call
-       * `pipeline.getBindGroupLayout(n)`; returning a legal BindGroupLayout brand
-       * (recorded in the ledger) keeps those consumers from crashing on a missing
-       * method.
-       */
-      makePipeline(kind) {
-        const handle = this.internalBookkeeper.register(kind);
-        const getBindGroupLayout = (_index) => this.internalBookkeeper.register("BindGroupLayout");
-        return Object.assign(handle, { getBindGroupLayout });
-      }
-    };
-    EMPTY_FEATURES = /* @__PURE__ */ new Set();
-    EMPTY_LIMITS = {};
-    NEVER = new Promise(() => {
-    });
-    RhiNullQueue = class {
-      writeBuffer(_buffer, _bufferOffset, _data, _dataOffset, _size) {
-        return ok(void 0);
-      }
-      writeTexture(_destination, _data, _dataLayout, _size) {
-        return ok(void 0);
-      }
-      copyExternalImageToTexture(_source, _destination, _copySize) {
-        return ok(void 0);
-      }
-      submit(_commandBuffers) {
-        return ok(void 0);
-      }
-      // forgeax-async-whitelist: dom-native — spec `GPUQueue.onSubmittedWorkDone`
-      // never rejects. The headless backend has no pending GPU work, so it resolves
-      // immediately (AC-12: read-back idioms must not hang).
-      onSubmittedWorkDone() {
-        return Promise.resolve(void 0);
-      }
-    };
-    RhiNullAdapter = class {
-      features = /* @__PURE__ */ new Set();
-      limits = {};
-      // forgeax-async-whitelist is not needed: this returns Promise<Result<...>>
-      // per the spec contract; never rejects.
-      requestDevice(_opts) {
-        const device = new RhiNullDevice(
-          new RhiNullQueue(),
-          (bookkeeper, dev) => new RhiNullCommandEncoder(bookkeeper, dev)
-        );
-        return Promise.resolve(ok(device));
-      }
-    };
-    RhiNullCanvasContext = class {
-      configure(_desc) {
-        return ok(void 0);
-      }
-      unconfigure() {
-      }
-      getConfiguration() {
-        return void 0;
-      }
-      getCurrentTexture() {
-        return ok({});
-      }
-    };
-    rhi = {
-      requestAdapter,
-      acquireCanvasContext,
-      createShaderModule
-    };
-  }
-});
 function createCliRhiDebugOperationContext() {
   return {
     captureFrame: async () => err(
       createRhiDebugError("capture-unavailable", {
         stage: "capture",
-        cause: "the standalone CLI has no live App capture provider"
+        cause: "the standalone CLI has no live App capture provider; start a recorder-enabled live host and invoke its rhiCapture root"
       })
     ),
     async readArtifact(artifact) {
@@ -3358,33 +3473,69 @@ function createCliRhiDebugOperationContext() {
             expected: "the ArtifactRef path to be readable",
             hint: "Check the tape path and recapture if the artifact was removed.",
             detail: {
-              path: artifact.path,
-              reason: cause instanceof Error ? cause.message : String(cause)
+              path: artifact.path,
+              reason: cause instanceof Error ? cause.message : String(cause)
+            }
+          }
+        };
+      }
+    },
+    async createReplayBackend(tape) {
+      let createDawn;
+      let gpuGlobals;
+      try {
+        const dawn = await import('webgpu');
+        createDawn = dawn.create;
+        gpuGlobals = dawn.globals;
+      } catch (cause) {
+        return {
+          ok: false,
+          error: {
+            code: "replay-backend-unavailable",
+            expected: "the Dawn WebGPU provider to load",
+            hint: "Install the DevKit runtime closure and retry rhi.inspect.",
+            detail: {
+              stage: "provider",
+              cause: cause instanceof Error ? cause.message : String(cause)
             }
           }
         };
       }
-    },
-    async createReplayBackend() {
+      Object.assign(globalThis, gpuGlobals);
+      const gpu = createDawn([]);
+      if (!("navigator" in globalThis) || globalThis.navigator === void 0) {
+        Object.defineProperty(globalThis, "navigator", {
+          value: {},
+          configurable: true,
+          writable: true
+        });
+      }
+      Object.defineProperty(globalThis.navigator, "gpu", {
+        value: gpu,
+        configurable: true,
+        writable: true
+      });
       const adapter = await rhi.requestAdapter();
       if (!adapter.ok) {
         return {
           ok: false,
           error: {
             code: "replay-backend-unavailable",
-            expected: "a fresh rhi-null adapter",
+            expected: "a fresh Dawn WebGPU adapter",
             hint: adapter.error.hint,
             detail: { stage: "adapter", cause: adapter.error.hint }
           }
         };
       }
-      const device = await adapter.value.requestDevice();
+      const device = await adapter.value.requestDevice(
+        replayDeviceRequest(tape, adapter.value.features, adapter.value.limits)
+      );
       if (!device.ok) {
         return {
           ok: false,
           error: {
             code: "replay-backend-unavailable",
-            expected: "a fresh rhi-null device",
+            expected: "a fresh Dawn WebGPU device satisfying the recorded tape",
             hint: device.error.hint,
             detail: { stage: "device", cause: device.error.hint }
           }
@@ -3396,7 +3547,6 @@ function createCliRhiDebugOperationContext() {
 }
 var init_cli_context = __esm({
   "src/rhi-debug/cli-context.ts"() {
-    init_dist3();
   }
 });
 function createRhiDebugOperationContext(host) {
@@ -3423,6 +3573,9 @@ function renderRhiDebugHelp() {
   return [
     "forgeax run <operation>",
     ...discoverRhiDebugOperations().map((operation) => `  ${operation.name}: ${operation.summary}`),
+    "Usage:",
+    "  forgeax run rhi.summary --artifact PATH --digest SHA256 --json",
+    "  forgeax run rhi.inspect --artifact PATH --digest SHA256 --work-index N --fields pipeline,bindings,pixels --json",
     "ArtifactRef schema:",
     JSON.stringify(RHI_DEBUG_OPERATION_MANIFEST.artifactRefSchema)
   ].join("\n");
@@ -3550,7 +3703,7 @@ async function runRhiDebugOperation(name, input, context) {
           "Provide a fresh device and shader factory before running rhi.inspect."
         );
       }
-      const backend = await context.createReplayBackend();
+      const backend = await context.createReplayBackend(decoded.value);
       if (!backend.ok) return backend;
       const opened = await openReplay(decoded.value, backend.value);
       if (!opened.ok) return { ok: false, error: coreError(opened.error) };
@@ -3642,7 +3795,10 @@ var init_operations = __esm({
             properties: {
               artifact: artifactRefSchema,
               workIndex: { type: "integer", minimum: 0 },
-              fields: { type: "array", items: { type: "string" } }
+              fields: {
+                type: "array",
+                items: { type: "string", enum: ["bindings", "pipeline", "pixels"] }
+              }
             },
             required: ["artifact", "workIndex"],
             additionalProperties: false
@@ -3734,7 +3890,15 @@ async function sdkInstallCommand(options) {
         await rename(resolve(staging, name), resolve(root, name));
       }
     }
-    return { ok: true, value: { root, sdkVersion: version, source: "@forgeax/engine-sdk" } };
+    return {
+      ok: true,
+      value: {
+        root,
+        sdkVersion: version,
+        source: "@forgeax/engine-sdk",
+        next: { cwd: root, argv: ["node", "./bin/forgeax.mjs", "init"] }
+      }
+    };
   } catch (cause) {
     return { ok: false, error: commandError(cause, "sdk-install-failed") };
   } finally {
@@ -3783,6 +3947,630 @@ var init_shader_check = __esm({
     init_project();
   }
 });
+function fail(code, expected, hint, detail = {}) {
+  throw new SoftwareCaptureError(code, expected, hint, detail);
+}
+async function pathExists2(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function reservePort() {
+  const reservation = createServer();
+  await new Promise((resolveListen, rejectListen) => {
+    reservation.once("error", rejectListen);
+    reservation.listen(0, "127.0.0.1", resolveListen);
+  });
+  const address = reservation.address();
+  const port = typeof address === "object" && address !== null ? address.port : 0;
+  await new Promise((resolveClose, rejectClose) => {
+    reservation.close((error) => error === void 0 ? resolveClose() : rejectClose(error));
+  });
+  if (port === 0) throw new Error("OS did not assign an ephemeral capture port");
+  return port;
+}
+async function stopProcess(child) {
+  if (child.exitCode !== null || child.signalCode !== null) return;
+  await new Promise((resolveStop) => {
+    const timeout = setTimeout(() => {
+      child.kill("SIGKILL");
+      resolveStop();
+    }, 2e3);
+    child.once("exit", () => {
+      clearTimeout(timeout);
+      resolveStop();
+    });
+    child.kill("SIGTERM");
+  });
+}
+async function startVirtualDisplay(width, height) {
+  if (process.platform !== "linux" || process.env.DISPLAY !== void 0) {
+    return {
+      ...process.env.DISPLAY === void 0 ? {} : { value: process.env.DISPLAY },
+      async close() {
+      }
+    };
+  }
+  for (let offset = 0; offset < 100; offset += 1) {
+    const number = 90 + (process.pid + offset) % 100;
+    const socket = `/tmp/.X11-unix/X${number}`;
+    const lock = `/tmp/.X${number}-lock`;
+    if (await pathExists2(socket) || await pathExists2(lock)) continue;
+    const display = `:${number}`;
+    const child = spawn(
+      "Xvfb",
+      [display, "-screen", "0", `${width}x${height}x24`, "-nolisten", "tcp"],
+      { stdio: ["ignore", "ignore", "pipe"] }
+    );
+    let diagnostic = "";
+    child.stderr?.setEncoding("utf8");
+    child.stderr?.on("data", (chunk) => {
+      diagnostic += chunk;
+    });
+    try {
+      await new Promise((resolveReady, rejectReady) => {
+        const timeout = setTimeout(
+          () => rejectReady(new Error(`Xvfb did not create ${socket}: ${diagnostic.trim()}`)),
+          5e3
+        );
+        const poll = setInterval(() => {
+          void pathExists2(socket).then((exists) => {
+            if (!exists) return;
+            clearTimeout(timeout);
+            clearInterval(poll);
+            resolveReady();
+          });
+        }, 50);
+        child.once("error", (error) => {
+          clearTimeout(timeout);
+          clearInterval(poll);
+          rejectReady(error);
+        });
+        child.once("exit", (code, signal) => {
+          clearTimeout(timeout);
+          clearInterval(poll);
+          rejectReady(
+            new Error(`Xvfb exited before ready (${code ?? signal}): ${diagnostic.trim()}`)
+          );
+        });
+      });
+      return { value: display, close: () => stopProcess(child) };
+    } catch (cause) {
+      await stopProcess(child);
+      throw cause;
+    }
+  }
+  throw new Error("no free X11 display number was available for browser capture");
+}
+async function lavapipeIcd() {
+  for (const candidate of [
+    "/usr/share/vulkan/icd.d/lvp_icd.x86_64.json",
+    "/usr/share/vulkan/icd.d/lvp_icd.aarch64.json"
+  ]) {
+    if (await pathExists2(candidate)) return candidate;
+  }
+  return void 0;
+}
+function evidencePath(output) {
+  return output.toLowerCase().endsWith(".png") ? `${output.slice(0, -4)}.json` : `${output}.json`;
+}
+function newRunId() {
+  return `${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}-${randomUUID().slice(0, 8)}`;
+}
+function checkpointSlug(checkpoint) {
+  const value = (checkpoint ?? "capture").trim().toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 80);
+  return value.length === 0 ? "capture" : value;
+}
+function captureDigest(bytes) {
+  return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+}
+function observedBackend(runtime) {
+  if (runtime.adapter === null) return "unknown";
+  return isSoftwareAdapter(runtime) ? "software" : "hardware";
+}
+async function resolveBrowserExecutable(requested) {
+  const candidates = [
+    requested,
+    process.env.FORGEAX_BROWSER_EXECUTABLE,
+    "/opt/google/chrome-beta/chrome",
+    "/usr/bin/google-chrome",
+    "/usr/bin/google-chrome-stable",
+    "/usr/bin/chromium",
+    "/usr/bin/chromium-browser"
+  ].filter((candidate) => candidate !== void 0 && candidate.length > 0);
+  for (const candidate of candidates) {
+    if (await pathExists2(candidate)) return candidate;
+  }
+  return void 0;
+}
+function browserLaunchArgs(backend) {
+  const common = [
+    "--enable-unsafe-webgpu",
+    "--ignore-gpu-blocklist",
+    "--disable-gpu-driver-bug-workarounds",
+    "--force-color-profile=srgb",
+    "--force-device-scale-factor=1"
+  ];
+  if (backend !== "software") return common;
+  return [
+    ...common,
+    "--enable-features=Vulkan",
+    "--use-vulkan=swiftshader",
+    "--use-angle=swiftshader",
+    "--disable-vulkan-surface"
+  ];
+}
+function summarizeCapturePixels(rgba, width, height) {
+  const pixelCount = width * height;
+  const stride = Math.max(1, Math.floor(pixelCount / 4096));
+  const histogram = new Uint32Array(16);
+  let lumaMin = 255;
+  let lumaMax = 0;
+  let sampledPixels = 0;
+  for (let pixel = 0; pixel < pixelCount; pixel += stride) {
+    const offset = pixel * 4;
+    const red = rgba[offset];
+    const green = rgba[offset + 1];
+    const blue = rgba[offset + 2];
+    if (red === void 0 || green === void 0 || blue === void 0) break;
+    const luma = Math.round((54 * red + 183 * green + 19 * blue) / 256);
+    lumaMin = Math.min(lumaMin, luma);
+    lumaMax = Math.max(lumaMax, luma);
+    const bucket = Math.min(15, Math.floor(luma / 16));
+    histogram[bucket] = (histogram[bucket] ?? 0) + 1;
+    sampledPixels += 1;
+  }
+  const dominantPixels = histogram.reduce((largest, count) => Math.max(largest, count), 0);
+  const varyingPixels = sampledPixels - dominantPixels;
+  const lumaRange = lumaMax - lumaMin;
+  const requiredVariation = Math.min(sampledPixels, Math.max(8, Math.ceil(sampledPixels * 2e-3)));
+  return {
+    width,
+    height,
+    sampledPixels,
+    lumaMin,
+    lumaMax,
+    lumaRange,
+    varyingPixels,
+    rendered: lumaRange >= 8 && varyingPixels >= requiredVariation
+  };
+}
+function inspectCapturePng(png) {
+  const decoded = parseImage(png, "image/png", { mipmap: false });
+  if (!decoded.ok) throw decoded.error;
+  return summarizeCapturePixels(decoded.value.bytes, decoded.value.width, decoded.value.height);
+}
+async function screenshotWithWitness(page) {
+  const canvasPng = await page.locator("canvas").first().screenshot({
+    type: "png",
+    style: "* { visibility: hidden !important; } canvas { visibility: visible !important; }"
+  });
+  const png = await page.screenshot({ type: "png", caret: "hide" });
+  return { png, pixels: inspectCapturePng(canvasPng) };
+}
+async function waitForCompositor(page) {
+  await page.evaluate(async () => {
+    await document.fonts.ready;
+    await new Promise((resolveFrame) => requestAnimationFrame(() => resolveFrame()));
+    await new Promise((resolveFrame) => requestAnimationFrame(() => resolveFrame()));
+  });
+}
+async function runtimeWitness(page) {
+  return page.evaluate(async (datasetKey) => {
+    const canvas = document.querySelector("canvas");
+    const uiRoot = document.querySelector("#game-ui");
+    const shadowHosts = [...uiRoot?.querySelectorAll("*") ?? []].filter(
+      (element) => element.shadowRoot?.childElementCount !== 0
+    );
+    let adapter = null;
+    let adapterError = null;
+    try {
+      const gpuAdapter = await navigator.gpu?.requestAdapter();
+      if (gpuAdapter === null || gpuAdapter === void 0) {
+        adapterError = "navigator.gpu.requestAdapter() returned null";
+      } else {
+        const info = gpuAdapter.info;
+        adapter = {
+          vendor: info.vendor,
+          architecture: info.architecture,
+          device: info.device,
+          description: info.description
+        };
+      }
+    } catch (cause) {
+      adapterError = String(cause);
+    }
+    const frameId = Number(document.documentElement.dataset[datasetKey]);
+    return {
+      title: document.title,
+      canvas: canvas instanceof HTMLCanvasElement ? { width: canvas.width, height: canvas.height } : null,
+      domUi: {
+        rootChildren: uiRoot?.childElementCount ?? 0,
+        openShadowRoots: shadowHosts.length,
+        textWitness: shadowHosts.map((host) => host.shadowRoot?.textContent?.replace(/\s+/g, " ").trim() ?? "").filter((text) => text.length > 0).join(" | ").slice(0, 500)
+      },
+      adapter,
+      adapterError,
+      engineFrameId: Number.isSafeInteger(frameId) && frameId > 0 ? frameId : null,
+      captureReady: document.documentElement.dataset.forgeaxCaptureReady ?? null,
+      userAgent: navigator.userAgent
+    };
+  }, FORGEAX_FRAME_SUBMITTED_DATASET);
+}
+function isSoftwareAdapter(runtime) {
+  const witness = Object.values(runtime.adapter ?? {}).map((value) => String(value).toLowerCase()).join(" ");
+  return ["swiftshader", "llvmpipe", "lavapipe", "software"].some(
+    (token) => witness.includes(token)
+  );
+}
+async function writeRunReport(report) {
+  await mkdir(dirname(report.report), { recursive: true });
+  await writeFile(report.report, `${JSON.stringify(report, null, 2)}
+`, "utf8");
+}
+async function openBrowserCaptureSession(root, options) {
+  const backend = options.backend ?? (options.software === true ? "software" : "auto");
+  if (options.software === true && options.backend !== void 0 && options.backend !== "software") {
+    fail(
+      "browser-capture-option-conflict",
+      "software and backend options to describe the same capture lane",
+      "Use either software: true or backend: software; use backend: auto for a portable capture.",
+      { software: options.software, backend: options.backend }
+    );
+  }
+  const facts = await readProjectFacts(root);
+  if (!facts.ok) {
+    throw new SoftwareCaptureError(
+      facts.error.code,
+      facts.error.expected,
+      facts.error.hint,
+      facts.error.detail
+    );
+  }
+  const width = options.width ?? 1280;
+  const height = options.height ?? 720;
+  const browserPath = await resolveBrowserExecutable(options.browser);
+  if (options.browser !== void 0 && browserPath === void 0) {
+    fail(
+      "browser-capture-browser-missing",
+      `a runnable browser at ${options.browser}`,
+      "Install Chrome/Chromium or pass --browser with an executable path.",
+      { browser: options.browser }
+    );
+  }
+  const id = options.runId ?? newRunId();
+  const outputDirectory = resolve(
+    facts.value.root,
+    options.outputDir ?? `artifacts/playthrough/${id}`
+  );
+  const reportPath = resolve(
+    facts.value.root,
+    options.report ?? resolve(outputDirectory, "run.json")
+  );
+  const port = options.port === void 0 || options.port === 0 ? await reservePort() : options.port;
+  let server;
+  let browser;
+  let page;
+  let display;
+  try {
+    const { createServer: createServer2 } = await import('vite');
+    server = await createServer2(
+      await createViteConfig(facts.value, "serve", "/", {
+        server: { port, strictPort: true }
+      })
+    );
+    await server.listen(port);
+    display = await startVirtualDisplay(width, height);
+    const captureDisplay = display;
+    const icd = await lavapipeIcd();
+    const consoleErrors = [];
+    const pageErrors = [];
+    const hasDisplay = display.value !== void 0;
+    const headless = options.headless ?? (!hasDisplay && process.platform !== "linux");
+    const baseUrl = new URL(server.resolvedUrls?.local[0] ?? `http://127.0.0.1:${port}/`);
+    const openPage = async (launchBackend) => {
+      const browserEnvironment = {
+        ...Object.fromEntries(
+          Object.entries(process.env).filter(
+            (entry) => entry[1] !== void 0
+          )
+        ),
+        ...launchBackend === "software" ? { LIBGL_ALWAYS_SOFTWARE: "1" } : {},
+        ...captureDisplay.value === void 0 ? {} : { DISPLAY: captureDisplay.value }
+      };
+      const launchOptions = {
+        headless,
+        env: browserEnvironment,
+        args: browserLaunchArgs(launchBackend),
+        ...browserPath === void 0 ? {} : { executablePath: browserPath }
+      };
+      browser = await chromium.launch(launchOptions);
+      page = await browser.newPage({
+        viewport: { width, height },
+        screen: { width, height },
+        deviceScaleFactor: 1,
+        colorScheme: "light",
+        locale: "en-US",
+        timezoneId: "UTC",
+        serviceWorkers: "block"
+      });
+      page.on("console", (message) => {
+        if (message.type() === "error") consoleErrors.push(message.text());
+      });
+      page.on("pageerror", (error) => pageErrors.push(String(error)));
+      const captureUrl2 = new URL(baseUrl.href);
+      if (options.deterministic === true) captureUrl2.searchParams.set("forgeaxCapture", "1");
+      await page.goto(captureUrl2.href, { waitUntil: "domcontentloaded", timeout: 12e4 });
+      await page.waitForFunction(
+        (requireUi) => {
+          const canvas = document.querySelector("canvas");
+          if (!(canvas instanceof HTMLCanvasElement) || canvas.width <= 0 || canvas.height <= 0)
+            return false;
+          if (!requireUi) return true;
+          const uiRoot = document.querySelector("#game-ui");
+          return uiRoot !== null && uiRoot.childElementCount > 0;
+        },
+        options.requireUi === true,
+        { timeout: 12e4 }
+      );
+      return runtimeWitness(page);
+    };
+    const initialLaunchBackend = backend === "software" ? "software" : "hardware";
+    let runtime = await openPage(initialLaunchBackend);
+    let observed = observedBackend(runtime);
+    if (backend === "auto" && runtime.adapter === null) {
+      await browser?.close();
+      browser = void 0;
+      page = void 0;
+      consoleErrors.length = 0;
+      pageErrors.length = 0;
+      runtime = await openPage("software");
+      observed = observedBackend(runtime);
+    }
+    const captureUrl = new URL(baseUrl.href);
+    if (options.deterministic === true) captureUrl.searchParams.set("forgeaxCapture", "1");
+    if (page === void 0 || browser === void 0) {
+      fail(
+        "browser-capture-browser-unavailable",
+        "the browser capture session to open",
+        "Inspect the browser launch diagnostic and retry with --browser or --headless."
+      );
+    }
+    const captures = [];
+    let closed = false;
+    const report = {
+      schemaVersion: "2.0.0",
+      runId: id,
+      ok: false,
+      mode: "browser-compositor",
+      root: facts.value.root,
+      url: captureUrl.href,
+      report: reportPath,
+      backendRequested: backend,
+      backend: observed,
+      softwareRequested: backend === "software",
+      deterministicRequested: options.deterministic === true,
+      viewport: {
+        width,
+        height,
+        deviceScaleFactor: 1,
+        colorProfile: "srgb",
+        colorScheme: "light",
+        locale: "en-US",
+        timezone: "UTC"
+      },
+      browser: { version: browser.version(), executable: browserPath ?? "playwright-managed" },
+      display: display.value ?? null,
+      lavapipeIcd: icd ?? null,
+      captures,
+      consoleErrors,
+      pageErrors,
+      boundary: "Browser-compositor capture is visual iteration evidence, not physical-GPU performance, HDR-display output, or release acceptance."
+    };
+    await writeRunReport(report);
+    const updateReport = async () => {
+      Object.assign(report, {
+        ok: captures.length > 0 && captures.every((capture) => capture.ok) && consoleErrors.length === 0 && pageErrors.length === 0
+      });
+      await writeRunReport(report);
+    };
+    const close = async () => {
+      if (closed) return;
+      closed = true;
+      await Promise.allSettled([browser?.close(), display?.close(), server?.close()]);
+      Object.assign(report, { closedAt: (/* @__PURE__ */ new Date()).toISOString() });
+      await updateReport();
+    };
+    return {
+      page,
+      url: captureUrl.href,
+      reportPath,
+      async capture(checkpoint, captureOptions = {}) {
+        if (closed) {
+          fail(
+            "browser-capture-session-closed",
+            "capture to run inside an open browser session",
+            "Open one session, complete all checkpoints, then close it.",
+            { report: reportPath }
+          );
+        }
+        const activePage = page;
+        if (activePage === void 0) {
+          fail(
+            "browser-capture-browser-unavailable",
+            "an open Playwright page",
+            "Inspect the browser launch diagnostic and retry the capture."
+          );
+        }
+        const expectedReady = checkpoint ?? (options.deterministic === true ? "true" : void 0);
+        await activePage.waitForFunction(
+          ({ datasetKey }) => Number(document.documentElement.dataset[datasetKey]) > 0,
+          { datasetKey: FORGEAX_FRAME_SUBMITTED_DATASET },
+          { timeout: 12e4 }
+        );
+        if (expectedReady !== void 0) {
+          await activePage.waitForFunction(
+            (expected) => document.documentElement.dataset.forgeaxCaptureReady === expected,
+            expectedReady,
+            { timeout: 12e4 }
+          );
+        }
+        await waitForCompositor(activePage);
+        let captured = await screenshotWithWitness(activePage);
+        const deadline = Date.now() + 12e4;
+        while (!captured.pixels.rendered && Date.now() < deadline) {
+          await activePage.waitForTimeout(500);
+          await waitForCompositor(activePage);
+          captured = await screenshotWithWitness(activePage);
+        }
+        const waitMs = captureOptions.waitMs ?? 0;
+        if (waitMs > 0) {
+          await activePage.waitForTimeout(waitMs);
+          await waitForCompositor(activePage);
+          captured = await screenshotWithWitness(activePage);
+          while (!captured.pixels.rendered && Date.now() < deadline) {
+            await activePage.waitForTimeout(500);
+            await waitForCompositor(activePage);
+            captured = await screenshotWithWitness(activePage);
+          }
+        }
+        const runtime2 = await runtimeWitness(activePage);
+        const uiPresent = runtime2.domUi.rootChildren > 0;
+        const requireUi = captureOptions.requireUi ?? options.requireUi ?? false;
+        const captureBackend = observedBackend(runtime2);
+        if (captureBackend !== "unknown") Object.assign(report, { backend: captureBackend });
+        const backendMatches = backend === "auto" || captureBackend === backend;
+        const ok2 = runtime2.canvas !== null && captured.pixels.rendered && backendMatches && runtime2.engineFrameId !== null && consoleErrors.length === 0 && pageErrors.length === 0 && (expectedReady === void 0 || runtime2.captureReady === expectedReady) && (!requireUi || uiPresent);
+        const index = captures.length + 1;
+        const output = resolve(
+          facts.value.root,
+          captureOptions.output ?? resolve(
+            outputDirectory,
+            `${String(index).padStart(3, "0")}-${checkpointSlug(checkpoint)}.png`
+          )
+        );
+        await mkdir(dirname(output), { recursive: true });
+        await writeFile(output, captured.png);
+        const record = {
+          index,
+          checkpoint: checkpoint ?? null,
+          ok: ok2,
+          output,
+          digest: captureDigest(captured.png),
+          pixels: captured.pixels,
+          runtime: runtime2
+        };
+        captures.push(record);
+        await updateReport();
+        if (!ok2) {
+          fail(
+            `${backend === "software" ? "software" : "browser"}-capture-runtime-failed`,
+            "non-flat canvas pixels, the requested browser backend/checkpoint, and no browser errors",
+            "Inspect the run report and repair the first browser runtime failure.",
+            { checkpoint: checkpoint ?? null, output, report: reportPath }
+          );
+        }
+        return record;
+      },
+      report: () => report,
+      close
+    };
+  } catch (cause) {
+    await Promise.allSettled([browser?.close(), display?.close(), server?.close()]);
+    throw cause;
+  }
+}
+function createBrowserCapture(root) {
+  const sessions = /* @__PURE__ */ new Set();
+  return {
+    async open(options) {
+      const session = await openBrowserCaptureSession(root, options);
+      sessions.add(session);
+      return session;
+    },
+    async close() {
+      await Promise.allSettled([...sessions].map((session) => session.close()));
+      sessions.clear();
+    }
+  };
+}
+function captureCommandError(cause, legacySoftware = false) {
+  if (cause instanceof SoftwareCaptureError) {
+    const code = legacySoftware && cause.code.startsWith("browser-capture-") ? cause.code.replace(/^browser-capture-/, "software-capture-") : cause.code;
+    return {
+      code,
+      expected: cause.expected,
+      hint: cause.hint,
+      detail: cause.detail
+    };
+  }
+  return commandError(cause, legacySoftware ? "software-capture-failed" : "browser-capture-failed");
+}
+async function browserCaptureCommand(options) {
+  const root = options.root ?? process.cwd();
+  const output = resolve(root, options.output ?? "artifacts/capture/game-ui.png");
+  const browser = createBrowserCapture(root);
+  try {
+    const backend = options.backend ?? (options.software === true ? "software" : "auto");
+    const session = await browser.open({
+      backend,
+      ...backend === "software" ? { software: true } : {},
+      ...options.browser === void 0 ? {} : { browser: options.browser },
+      ...options.width === void 0 ? {} : { width: options.width },
+      ...options.height === void 0 ? {} : { height: options.height },
+      ...options.port === void 0 ? {} : { port: options.port },
+      ...options.headless === void 0 ? {} : { headless: options.headless },
+      requireUi: options.requireUi === true,
+      deterministic: options.deterministic === true,
+      outputDir: dirname(output),
+      report: evidencePath(output)
+    });
+    await session.capture(options.deterministic === true ? "true" : void 0, {
+      output,
+      waitMs: options.waitMs ?? 4e3,
+      requireUi: options.requireUi === true
+    });
+    await session.close();
+    return { ok: true, value: session.report() };
+  } catch (cause) {
+    return { ok: false, error: captureCommandError(cause) };
+  } finally {
+    await browser.close();
+  }
+}
+async function softwareCaptureCommand(options) {
+  const result = await browserCaptureCommand({ ...options, backend: "software", software: true });
+  if (result.ok) return result;
+  return { ok: false, error: captureCommandErrorFromResult(result.error) };
+}
+function captureCommandErrorFromResult(error, legacySoftware) {
+  if (!error.code.startsWith("browser-capture-")) return error;
+  return { ...error, code: error.code.replace(/^browser-capture-/, "software-capture-") };
+}
+var SoftwareCaptureError;
+var init_software_capture = __esm({
+  "src/software-capture.ts"() {
+    init_host();
+    init_project();
+    SoftwareCaptureError = class extends Error {
+      constructor(code, expected, hint, detail) {
+        super(`${code}: ${hint}`);
+        this.code = code;
+        this.expected = expected;
+        this.hint = hint;
+        this.detail = detail;
+        this.name = "SoftwareCaptureError";
+      }
+      code;
+      expected;
+      hint;
+      detail;
+    };
+  }
+});
 
 // src/commands.ts
 var commands_exports = {};
@@ -3792,12 +4580,17 @@ __export(commands_exports, {
   assetInspectCommand: () => assetInspectCommand,
   assetListCommand: () => assetListCommand,
   assetVerifyCommand: () => assetVerifyCommand,
+  browserCaptureCommand: () => browserCaptureCommand,
   buildCommand: () => buildCommand,
   createCliRhiDebugOperationContext: () => createCliRhiDebugOperationContext,
   createRhiDebugOperationContext: () => createRhiDebugOperationContext,
   devCommand: () => devCommand,
   discoverRhiDebugOperations: () => discoverRhiDebugOperations,
   doctorCommand: () => doctorCommand,
+  engineDoctorCommand: () => engineDoctorCommand,
+  engineStatusCommand: () => engineStatusCommand,
+  engineUnlinkCommand: () => engineUnlinkCommand,
+  engineUseLocalCommand: () => engineUseLocalCommand,
   initCommand: () => initCommand,
   newCommand: () => newCommand,
   packageCommand: () => packageCommand,
@@ -3812,11 +4605,27 @@ __export(commands_exports, {
   shaderCheckCommand: () => shaderCheckCommand,
   skillInstallCommand: () => skillInstallCommand,
   skillVerifyCommand: () => skillVerifyCommand,
+  softwareCaptureCommand: () => softwareCaptureCommand,
   testCommand: () => testCommand
 });
 function runRhiDebugCommand(name, input, context) {
   return runRhiDebugOperation(name, input, context);
 }
+async function materializeViteDevPort(port) {
+  if (port !== 0) return port;
+  const reservation = createServer();
+  await new Promise((resolveListen, rejectListen) => {
+    reservation.once("error", rejectListen);
+    reservation.listen(0, "127.0.0.1", resolveListen);
+  });
+  const address = reservation.address();
+  const assigned = typeof address === "object" && address !== null ? address.port : 0;
+  await new Promise((resolveClose, rejectClose) => {
+    reservation.close((error) => error === void 0 ? resolveClose() : rejectClose(error));
+  });
+  if (assigned === 0) throw new Error("OS did not assign an ephemeral preview port");
+  return assigned;
+}
 async function buildCommand(options = {}) {
   const facts = await readProjectFacts(options.root);
   if (!facts.ok) return facts;
@@ -3919,13 +4728,38 @@ async function devCommand(options = {}) {
   const facts = await readProjectFacts(options.root);
   if (!facts.ok) return facts;
   const previous = process.cwd();
+  let server;
   try {
+    const { createServer: createServer2 } = await import('vite');
+    const { createViteConfig: createViteConfig2 } = await Promise.resolve().then(() => (init_host(), host_exports));
+    const port = resolveProjectPort(options.port);
+    const vitePort = { ...port, port: await materializeViteDevPort(port.port) };
     process.chdir(facts.value.root);
-    const server = await createServer(await createViteConfig(facts.value, "serve"));
-    await server.listen();
+    server = await createServer2(
+      await createViteConfig2(facts.value, "serve", "/", {
+        server: vitePort
+      })
+    );
+    await server.listen(vitePort.port);
     if (options.json !== true) server.printUrls();
-    return { ok: true, value: { root: facts.value.root, urls: server.resolvedUrls } };
+    return {
+      ok: true,
+      value: {
+        root: facts.value.root,
+        urls: server.resolvedUrls,
+        mode: "dev",
+        serves: "source",
+        capabilities: {
+          "rhi.capture": {
+            available: false,
+            realm: "host",
+            reason: "standalone-dev-server-has-no-live-app-cli-attachment"
+          }
+        }
+      }
+    };
   } catch (cause) {
+    await server?.close();
     process.chdir(previous);
     return { ok: false, error: commandError(cause, "dev-server-failed") };
   }
@@ -3935,15 +4769,31 @@ async function previewCommand(options = {}) {
   const verified = await verifyDist(resolve(root, "dist"));
   if (!verified.ok) return verified;
   try {
+    const port = resolveProjectPort(options.port);
     const server = await preview({
       root,
       configFile: false,
       base: verified.value.base,
-      preview: { open: false, port: 0, strictPort: false },
+      preview: { open: false, ...port },
       build: { outDir: resolve(root, "dist") }
     });
     if (options.json !== true) server.printUrls();
-    return { ok: true, value: { root, urls: server.resolvedUrls } };
+    return {
+      ok: true,
+      value: {
+        root,
+        urls: server.resolvedUrls,
+        mode: "preview",
+        serves: "dist",
+        capabilities: {
+          "rhi.capture": {
+            available: false,
+            realm: "host",
+            reason: "static-dist-host-does-not-install-dev-capture"
+          }
+        }
+      }
+    };
   } catch (cause) {
     return { ok: false, error: commandError(cause, "preview-server-failed") };
   }
@@ -3993,14 +4843,17 @@ var init_commands = __esm({
     init_dist();
     init_host();
     init_project();
+    init_types();
     init_assets();
     init_bootstrap_commands();
+    init_engine_binding();
     init_plugin_authoring();
     init_cli_context();
     init_operations();
     init_sdk_install();
     init_shader_check();
     init_skill_install();
+    init_software_capture();
     init_operations();
   }
 });
@@ -4365,7 +5218,7 @@ function hasStaticToolDeclarations(entry) {
   return Array.isArray(Reflect.get(entry.config, "tools"));
 }
 async function createViteModuleLoader(root) {
-  const server = await createServer({
+  const server = await createServer$1({
     root,
     appType: "custom",
     configFile: false,
@@ -4622,9 +5475,42 @@ var init_runtime = __esm({
   }
 });
 
+// src/cli-output.ts
+function agentOnboardingLines(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return [];
+  const onboarding = value.onboarding;
+  if (onboarding === null || typeof onboarding !== "object" || Array.isArray(onboarding)) return [];
+  const candidate = onboarding;
+  const lines = Array.isArray(candidate.read) ? candidate.read.filter((path) => typeof path === "string").map((path) => `[forgeax] read: ${path}`) : [];
+  if (typeof candidate.next?.cwd === "string" && Array.isArray(candidate.next.argv) && candidate.next.argv.every((part) => typeof part === "string")) {
+    lines.push(`[forgeax] next cwd: ${candidate.next.cwd}`);
+    lines.push(`[forgeax] next: ${candidate.next.argv.join(" ")}`);
+  }
+  return lines;
+}
+function sdkUpdateLines(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return [];
+  const update = value.sdkUpdate;
+  if (update === null || typeof update !== "object" || Array.isArray(update)) return [];
+  const candidate = update;
+  if (candidate.status !== "available" || typeof candidate.currentVersion !== "string" || typeof candidate.latestVersion !== "string" || typeof candidate.migrationRisk !== "string") {
+    return [];
+  }
+  return [
+    `[forgeax] update available: @forgeax/engine-sdk ${candidate.currentVersion} -> ${candidate.latestVersion}`,
+    `[forgeax] update note: ${candidate.migrationRisk}`
+  ];
+}
+function renderForgeaxUsage() {
+  return "Usage: forgeax new [directory] [--template empty|game-3d]\n       forgeax <init|doctor|test|dev|build|package|serve|preview> [directory]\n       forgeax capture [directory] [--backend auto|software|hardware] [--require-ui] [--deterministic] [--headless] [--output PATH]\n       forgeax engine <status|doctor|unlink> [--root directory]\n       forgeax engine use-local <engine-directory> [--root directory]\n       forgeax package [directory] [--output release/game-web.zip]\n       forgeax run <rhi.capture|rhi.summary|rhi.inspect> [options]\n       forgeax run <operation-id> --input <request.json>\n       forgeax exec <program.mjs> [--json]\n       forgeax asset <add|verify|inspect|list> [subject]\n       forgeax shader check [path]\n       forgeax plugin <install|uninstall> <module-or-id> [options]\n       forgeax skill <install|verify> [--root directory]\n       forgeax sdk install <directory> [--version VERSION]\n";
+}
+
 // src/cli.ts
 init_commands();
 
+// src/tools/commands.ts
+init_software_capture();
+
 // src/tools/client.ts
 init_catalog();
 function decorateResourcePreviewTerminal(terminal) {
@@ -4795,6 +5681,7 @@ async function execCommand(options) {
     };
   }
   const root = options.root ?? process.cwd();
+  const browser = createBrowserCapture(root);
   try {
     const module = await import(pathToFileURL(resolve(root, options.program)).href);
     const program = module.default ?? module.run;
@@ -4802,7 +5689,8 @@ async function execCommand(options) {
       throw new TypeError("operation program must export a default function or named run function");
     }
     const client = await createToolClient({ projectRoot: root });
-    const value = await program(client);
+    const context = { ...client, browser };
+    const value = await program(context);
     if (!isSerializableValue(value)) {
       throw new TypeError("tool program returned a non-serializable live value");
     }
@@ -4817,17 +5705,22 @@ async function execCommand(options) {
         detail: { reason: cause instanceof Error ? cause.message : String(cause) }
       }
     };
+  } finally {
+    await browser.close();
   }
 }
 
 // src/cli.ts
-var args = process.argv.slice(2);
+init_types();
+var rawArgs = process.argv.slice(2);
+var args = [...rawArgs];
 var primary = args.shift();
-var nested = primary === "asset" || primary === "shader" || primary === "plugin" || primary === "skill" || primary === "sdk" ? args.shift() : void 0;
-var command = primary === "asset" || primary === "shader" || primary === "plugin" || primary === "skill" || primary === "sdk" ? `${primary}.${nested ?? ""}` : primary;
+var nested = primary === "asset" || primary === "shader" || primary === "plugin" || primary === "skill" || primary === "sdk" || primary === "engine" ? args.shift() : void 0;
+var command = primary === "asset" || primary === "shader" || primary === "plugin" || primary === "skill" || primary === "sdk" || primary === "engine" ? `${primary}.${nested ?? ""}` : primary;
 var json = args.includes("--json");
 var dryRun = args.includes("--dry-run");
 var noInstall = args.includes("--no-install");
+var help = rawArgs.includes("--help") || rawArgs.includes("-h");
 function option(name) {
   const index = args.indexOf(name);
   return index < 0 ? void 0 : args[index + 1];
@@ -4836,6 +5729,8 @@ var optionValueIndexes = new Set(
   [
     "--artifact",
     "--base",
+    "--backend",
+    "--browser",
     "--digest",
     "--id",
     "--realm",
@@ -4844,8 +5739,12 @@ var optionValueIndexes = new Set(
     "--input",
     "--output",
     "--root",
+    "--port",
     "--template",
+    "--height",
     "--version",
+    "--wait-ms",
+    "--width",
     "--work-index"
   ].flatMap((name) => {
     const index = args.indexOf(name);
@@ -4865,6 +5764,11 @@ var commands = [
   "dev",
   "build",
   "package",
+  "capture",
+  "engine.status",
+  "engine.use-local",
+  "engine.unlink",
+  "engine.doctor",
   "serve",
   "preview",
   "run",
@@ -4882,6 +5786,18 @@ var commands = [
   "describe",
   "exec"
 ];
+function projectServerOptions() {
+  const parsedPort = parseProjectPortOption(option("--port"), args.includes("--port"));
+  if (!parsedPort.ok) return parsedPort;
+  return {
+    ok: true,
+    value: {
+      root: projectRoot,
+      json,
+      ...parsedPort.value === void 0 ? {} : { port: parsedPort.value }
+    }
+  };
+}
 async function run(value) {
   switch (value) {
     case "new": {
@@ -4898,8 +5814,10 @@ async function run(value) {
       return doctorCommand({ root: projectRoot});
     case "test":
       return testCommand({ root: projectRoot});
-    case "dev":
-      return devCommand({ root: projectRoot, json });
+    case "dev": {
+      const options = projectServerOptions();
+      return options.ok ? devCommand(options.value) : options;
+    }
     case "build": {
       const base = option("--base");
       const outDir = option("--out-dir");
@@ -4917,10 +5835,100 @@ async function run(value) {
         ...output === void 0 ? {} : { output }
       });
     }
-    case "preview":
-      return previewCommand({ root: projectRoot, json });
-    case "serve":
-      return devCommand({ root: projectRoot, json });
+    case "capture": {
+      const parsedPort = parseProjectPortOption(option("--port"), args.includes("--port"));
+      if (!parsedPort.ok) return parsedPort;
+      const software = args.includes("--software");
+      const requestedBackend = option("--backend");
+      if (requestedBackend !== void 0 && requestedBackend !== "auto" && requestedBackend !== "software" && requestedBackend !== "hardware") {
+        return {
+          ok: false,
+          error: {
+            code: "cli-parse-error",
+            expected: "--backend to be auto, software, or hardware",
+            hint: "Use auto for a portable capture, or assert one browser rendering lane explicitly.",
+            detail: { option: "--backend", received: requestedBackend }
+          }
+        };
+      }
+      if (software && requestedBackend !== void 0 && requestedBackend !== "software") {
+        return {
+          ok: false,
+          error: {
+            code: "cli-parse-error",
+            expected: "--software and --backend to select the same capture lane",
+            hint: "Use --backend software (or only the legacy --software flag).",
+            detail: { software: true, backend: requestedBackend }
+          }
+        };
+      }
+      const parseInteger = (name, fallback, minimum, maximum) => {
+        const raw = option(name);
+        if (raw === void 0) return { ok: true, value: fallback };
+        const parsed = Number(raw);
+        return Number.isSafeInteger(parsed) && parsed >= minimum && parsed <= maximum ? { ok: true, value: parsed } : {
+          ok: false,
+          error: {
+            code: "cli-parse-error",
+            expected: `${name} to be an integer from ${minimum} to ${maximum}`,
+            hint: "Pass a bounded deterministic capture value.",
+            detail: { option: name, received: raw }
+          }
+        };
+      };
+      const width = parseInteger("--width", 1280, 64, 8192);
+      if (!width.ok) return width;
+      const height = parseInteger("--height", 720, 64, 8192);
+      if (!height.ok) return height;
+      const waitMs = parseInteger("--wait-ms", 4e3, 0, 12e4);
+      if (!waitMs.ok) return waitMs;
+      const output = option("--output");
+      const browser = option("--browser");
+      return browserCaptureCommand({
+        root: projectRoot,
+        json,
+        backend: requestedBackend ?? (software ? "software" : "auto"),
+        ...software ? { software: true } : {},
+        width: width.value,
+        height: height.value,
+        waitMs: waitMs.value,
+        requireUi: args.includes("--require-ui"),
+        deterministic: args.includes("--deterministic"),
+        ...args.includes("--headless") ? { headless: true } : {},
+        ...parsedPort.value === void 0 ? {} : { port: parsedPort.value },
+        ...output === void 0 ? {} : { output },
+        ...browser === void 0 ? {} : { browser }
+      });
+    }
+    case "engine.status":
+      return engineStatusCommand({ root: scopedRoot});
+    case "engine.use-local": {
+      const path = positionals[0];
+      if (path === void 0) {
+        return {
+          ok: false,
+          error: {
+            code: "cli-parse-error",
+            expected: "forgeax engine use-local <engine-directory>",
+            hint: "Pass the local Engine source checkout or SDK source directory.",
+            detail: {}
+          }
+        };
+      }
+      return engineUseLocalCommand({ root: scopedRoot, path, dryRun, json });
+    }
+    case "engine.unlink":
+      return engineUnlinkCommand({ root: scopedRoot, dryRun});
+    case "engine.doctor":
+      return engineDoctorCommand({ root: scopedRoot});
+    case "preview": {
+      const options = projectServerOptions();
+      return options.ok ? previewCommand(options.value) : options;
+    }
+    case "serve": {
+      const options = projectServerOptions();
+      return options.ok ? devCommand(options.value) : options;
+    }
     case "plugin.install": {
       const module = positionals[0];
       const id = option("--id");
@@ -5093,14 +6101,36 @@ async function run(value) {
           }
         };
       }
-      return runRhiDebugCommand(operation, { artifact, workIndex }, context);
+      const fieldsOption = option("--fields");
+      const fields = fieldsOption?.split(",").map((field) => field.trim()).filter((field) => field.length > 0);
+      const allowedFields = /* @__PURE__ */ new Set(["bindings", "pipeline", "pixels"]);
+      if (fields?.some((field) => !allowedFields.has(field))) {
+        return {
+          ok: false,
+          error: {
+            code: "cli-parse-error",
+            expected: "--fields to contain pipeline, bindings, and/or pixels",
+            hint: "Use a comma-separated subset such as --fields pipeline,bindings.",
+            detail: { fields: fieldsOption }
+          }
+        };
+      }
+      return runRhiDebugCommand(
+        operation,
+        {
+          artifact,
+          workIndex,
+          ...fields === void 0 ? {} : { fields }
+        },
+        context
+      );
     }
   }
 }
-if (command === void 0 || !commands.includes(command)) {
-  process.stderr.write(
-    "Usage: forgeax new [directory] [--template empty|game-default]\n       forgeax <init|doctor|test|dev|build|package|serve|preview> [directory]\n       forgeax package [directory] [--output release/game-web.zip]\n       forgeax run <rhi.capture|rhi.summary|rhi.inspect> [options]\n       forgeax run <operation-id> --input <request.json>\n       forgeax asset <add|verify|inspect|list> [subject]\n       forgeax shader check [path]\n       forgeax plugin <install|uninstall> <module-or-id> [options]\n       forgeax skill <install|verify> [--root directory]\n       forgeax sdk install <directory> [--version VERSION]\n"
-  );
+if (help && primary !== "run") {
+  process.stdout.write(renderForgeaxUsage());
+} else if (command === void 0 || !commands.includes(command)) {
+  process.stderr.write(renderForgeaxUsage());
   process.exitCode = 2;
 } else {
   const stdoutWrite = process.stdout.write;
@@ -5120,9 +6150,23 @@ if (command === void 0 || !commands.includes(command)) {
   const envelope = result.ok ? { schemaVersion: "1.0.0", command, ok: true, value: result.value } : { schemaVersion: "1.0.0", command, ok: false, error: result.error };
   if (json) stdoutWrite.call(process.stdout, `${JSON.stringify(envelope)}
 `);
-  else if (result.ok) process.stdout.write(`[forgeax] ${command} ready
+  else if (result.ok) {
+    process.stdout.write(`[forgeax] ${command} ready
+`);
+    for (const line of agentOnboardingLines(result.value)) process.stdout.write(`${line}
+`);
+    for (const line of sdkUpdateLines(result.value)) process.stdout.write(`${line}
 `);
-  else process.stderr.write(`[forgeax] ${result.error.code}: ${result.error.hint}
+    if (command === "sdk.install") {
+      const value = result.value;
+      if (typeof value.next?.cwd === "string" && Array.isArray(value.next.argv) && value.next.argv.every((part) => typeof part === "string")) {
+        process.stdout.write(`[forgeax] next cwd: ${value.next.cwd}
+`);
+        process.stdout.write(`[forgeax] next: ${value.next.argv.join(" ")}
+`);
+      }
+    }
+  } else process.stderr.write(`[forgeax] ${result.error.code}: ${result.error.hint}
 `);
   if (!result.ok) process.exitCode = result.error.code === "cli-parse-error" ? 2 : 1;
 }