@forgeax/engine-devkit 0.1.2

package/dist/cli.mjs

@@ -0,0 +1,4862 @@
+#!/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 { resolve, extname, dirname, basename, relative, isAbsolute, sep } from 'path';
+import { readFileSync, existsSync } from 'fs';
+import { createRequire } from 'module';
+import { pathToFileURL, fileURLToPath } from 'url';
+import { audioImporter } from '@forgeax/engine-audio-webaudio/audio-importer';
+import { fbxImporter } from '@forgeax/engine-fbx';
+import { fontImporter } from '@forgeax/engine-font/font-importer';
+import { gltfImporter } from '@forgeax/engine-gltf';
+import { imageImporter } from '@forgeax/engine-image/image-importer';
+import { describeResourcePreviewFailure, validateCanonicalKitReceipt, createMaterialPreviewContribution, createMeshPreviewContribution, createVfxPreviewContribution, createTexturePreviewContribution, validatePreviewArtifactManifest } from '@forgeax/engine-preview';
+import { createStandaloneRuntimeAssetBinding, ok, err } from '@forgeax/engine-types';
+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 { promisify } from 'util';
+import { decodeTape, openReplay, buildFrameModel, createRhiDebugError } from '@forgeax/engine-rhi-debug';
+import { tmpdir } from 'os';
+import { build, createServer, preview } from 'vite';
+import { startVitest } from 'vitest/node';
+import materialPreviewPlugin from '@forgeax/engine-preview/material';
+import meshPreviewPlugin from '@forgeax/engine-preview/mesh';
+import texturePreviewPlugin from '@forgeax/engine-preview/texture';
+import vfxPreviewPlugin from '@forgeax/engine-preview/vfx';
+import { isSerializableValue, domainFailureError, createToolRuntime, capabilityUnavailableError, defineTool, validateArtifactManifest } from '@forgeax/engine-tool-runtime';
+import { Context, isToolPlugin } from '@forgeax/engine-plugin';
+import { installCatalogLoader, projectPluginEntries } from '@forgeax/engine-plugin/loader';
+
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+function crc32(bytes) {
+  let value = 4294967295;
+  for (const byte of bytes) value = value >>> 8 ^ (CRC_TABLE[(value ^ byte) & 255] ?? 0);
+  return (value ^ 4294967295) >>> 0;
+}
+function assertArchivePath(path) {
+  if (path.length === 0 || path.startsWith("/") || path.includes("\\") || path.split("/").some((segment) => segment.length === 0 || segment === "." || segment === "..")) {
+    throw new TypeError(`invalid ZIP entry path: ${path}`);
+  }
+}
+function createZip(entriesInput) {
+  if (entriesInput.length > ZIP_ENTRY_LIMIT) throw new RangeError("ZIP32 entry limit exceeded");
+  const entries2 = [...entriesInput].sort((left, right) => left.path.localeCompare(right.path));
+  const seen = /* @__PURE__ */ new Set();
+  const localParts = [];
+  const centralParts = [];
+  let offset = 0;
+  for (const entry of entries2) {
+    assertArchivePath(entry.path);
+    if (seen.has(entry.path)) throw new TypeError(`duplicate ZIP entry path: ${entry.path}`);
+    seen.add(entry.path);
+    const name = Buffer.from(entry.path, "utf8");
+    const source = Buffer.from(entry.bytes);
+    const compressed = deflateRawSync(source, { level: 9 });
+    if (source.byteLength > ZIP32_LIMIT || compressed.byteLength > ZIP32_LIMIT) {
+      throw new RangeError(`ZIP32 file limit exceeded: ${entry.path}`);
+    }
+    const checksum = crc32(source);
+    const local = Buffer.alloc(30);
+    local.writeUInt32LE(67324752, 0);
+    local.writeUInt16LE(20, 4);
+    local.writeUInt16LE(UTF8_FLAG, 6);
+    local.writeUInt16LE(DEFLATE_METHOD, 8);
+    local.writeUInt16LE(0, 10);
+    local.writeUInt16LE(DOS_EPOCH_DATE, 12);
+    local.writeUInt32LE(checksum, 14);
+    local.writeUInt32LE(compressed.byteLength, 18);
+    local.writeUInt32LE(source.byteLength, 22);
+    local.writeUInt16LE(name.byteLength, 26);
+    local.writeUInt16LE(0, 28);
+    localParts.push(local, name, compressed);
+    const central = Buffer.alloc(46);
+    central.writeUInt32LE(33639248, 0);
+    central.writeUInt16LE(20, 4);
+    central.writeUInt16LE(20, 6);
+    central.writeUInt16LE(UTF8_FLAG, 8);
+    central.writeUInt16LE(DEFLATE_METHOD, 10);
+    central.writeUInt16LE(0, 12);
+    central.writeUInt16LE(DOS_EPOCH_DATE, 14);
+    central.writeUInt32LE(checksum, 16);
+    central.writeUInt32LE(compressed.byteLength, 20);
+    central.writeUInt32LE(source.byteLength, 24);
+    central.writeUInt16LE(name.byteLength, 28);
+    central.writeUInt16LE(0, 30);
+    central.writeUInt16LE(0, 32);
+    central.writeUInt16LE(0, 34);
+    central.writeUInt16LE(0, 36);
+    central.writeUInt32LE(0, 38);
+    central.writeUInt32LE(offset, 42);
+    centralParts.push(central, name);
+    offset += local.byteLength + name.byteLength + compressed.byteLength;
+    if (offset > ZIP32_LIMIT) throw new RangeError("ZIP32 archive limit exceeded");
+  }
+  const centralDirectory = Buffer.concat(centralParts);
+  if (centralDirectory.byteLength > ZIP32_LIMIT)
+    throw new RangeError("ZIP32 directory limit exceeded");
+  const end = Buffer.alloc(22);
+  end.writeUInt32LE(101010256, 0);
+  end.writeUInt16LE(entries2.length, 8);
+  end.writeUInt16LE(entries2.length, 10);
+  end.writeUInt32LE(centralDirectory.byteLength, 12);
+  end.writeUInt32LE(offset, 16);
+  return Buffer.concat([...localParts, centralDirectory, end]);
+}
+var ZIP32_LIMIT, ZIP_ENTRY_LIMIT, UTF8_FLAG, DEFLATE_METHOD, DOS_EPOCH_DATE, CRC_TABLE;
+var init_archive = __esm({
+  "src/archive.ts"() {
+    ZIP32_LIMIT = 4294967295;
+    ZIP_ENTRY_LIMIT = 65535;
+    UTF8_FLAG = 2048;
+    DEFLATE_METHOD = 8;
+    DOS_EPOCH_DATE = 33;
+    CRC_TABLE = new Uint32Array(256);
+    for (let index = 0; index < CRC_TABLE.length; index += 1) {
+      let value = index;
+      for (let bit = 0; bit < 8; bit += 1) value = value >>> 1 ^ 3988292384 & -(value & 1);
+      CRC_TABLE[index] = value >>> 0;
+    }
+  }
+});
+function mediaType(path) {
+  if (path.endsWith(".html")) return "text/html";
+  if (path.endsWith(".js") || path.endsWith(".mjs")) return "text/javascript";
+  if (path.endsWith(".json")) return "application/json";
+  if (path.endsWith(".wasm")) return "application/wasm";
+  if (path.endsWith(".png")) return "image/png";
+  if (path.endsWith(".jpg") || path.endsWith(".jpeg")) return "image/jpeg";
+  return "application/octet-stream";
+}
+async function filesUnder(root, directory = root) {
+  const result = [];
+  for (const name of (await readdir(directory)).sort()) {
+    const path = resolve(directory, name);
+    const info = await stat(path);
+    if (info.isDirectory()) result.push(...await filesUnder(root, path));
+    else if (info.isFile() && name !== "forgeax-dist.json") result.push(path);
+  }
+  return result;
+}
+async function writeDistManifest(facts, base, rootInput = resolve(facts.root, "dist")) {
+  const root = resolve(rootInput);
+  const artifacts = await Promise.all(
+    (await filesUnder(root)).map(async (path) => {
+      const bytes = await readFile(path);
+      return {
+        path: relative(root, path).split(sep).join("/"),
+        mediaType: mediaType(path),
+        bytes: bytes.byteLength,
+        sha256: createHash("sha256").update(bytes).digest("hex")
+      };
+    })
+  );
+  const manifest = {
+    schemaVersion: "1.0.0",
+    project: { id: facts.id, name: facts.name },
+    base,
+    runtime: {
+      packIndexUrl: "pack-index.json",
+      shaderManifestUrl: "shaders/manifest.json"
+    },
+    artifacts
+  };
+  await writeFile(resolve(root, "forgeax-dist.json"), `${JSON.stringify(manifest, null, 2)}
+`);
+  return manifest;
+}
+async function verifyDist(rootInput) {
+  const root = resolve(rootInput);
+  let manifest;
+  try {
+    manifest = JSON.parse(
+      await readFile(resolve(root, "forgeax-dist.json"), "utf8")
+    );
+  } catch (cause) {
+    return {
+      ok: false,
+      error: {
+        code: "dist-manifest-unreadable",
+        expected: "a readable dist/forgeax-dist.json",
+        hint: "Run forgeax build and do not edit its derived manifest.",
+        detail: { root, reason: cause instanceof Error ? cause.message : String(cause) }
+      }
+    };
+  }
+  if (manifest.schemaVersion !== "1.0.0" || !Array.isArray(manifest.artifacts)) {
+    return {
+      ok: false,
+      error: {
+        code: "dist-manifest-invalid",
+        expected: "forgeax-dist schema 1.0.0",
+        hint: "Rebuild the game with a compatible ForgeaX DevKit.",
+        detail: { root }
+      }
+    };
+  }
+  const declaredPaths = new Set(manifest.artifacts.map((artifact) => artifact.path));
+  if (declaredPaths.size !== manifest.artifacts.length) {
+    return {
+      ok: false,
+      error: {
+        code: "dist-artifact-duplicate",
+        expected: "every dist artifact path to be declared exactly once",
+        hint: "Rebuild the derived dist manifest.",
+        detail: { root }
+      }
+    };
+  }
+  for (const artifact of manifest.artifacts) {
+    const path = resolve(root, artifact.path);
+    if (relative(root, path).startsWith("..")) {
+      return {
+        ok: false,
+        error: {
+          code: "dist-path-escape",
+          expected: "every artifact path to remain inside dist",
+          hint: "Rebuild the derived dist manifest.",
+          detail: { path: artifact.path }
+        }
+      };
+    }
+    try {
+      const bytes = await readFile(path);
+      const digest = createHash("sha256").update(bytes).digest("hex");
+      if (bytes.byteLength !== artifact.bytes || digest !== artifact.sha256) {
+        return {
+          ok: false,
+          error: {
+            code: "dist-artifact-mismatch",
+            expected: "artifact bytes and SHA-256 to match forgeax-dist.json",
+            hint: "Restore the built artifact or rebuild the complete dist.",
+            detail: { path: artifact.path }
+          }
+        };
+      }
+    } catch {
+      return {
+        ok: false,
+        error: {
+          code: "dist-artifact-missing",
+          expected: "every declared dist artifact to exist",
+          hint: "Restore the built artifact or rebuild the complete dist.",
+          detail: { path: artifact.path }
+        }
+      };
+    }
+  }
+  for (const required of [
+    "index.html",
+    manifest.runtime.packIndexUrl,
+    manifest.runtime.shaderManifestUrl
+  ]) {
+    if (!manifest.artifacts.some((artifact) => artifact.path === required)) {
+      return {
+        ok: false,
+        error: {
+          code: "dist-required-artifact-missing",
+          expected: "HTML, Pack index, and Shader manifest in the dist closure",
+          hint: "Rebuild after repairing the owning producer.",
+          detail: { path: required }
+        }
+      };
+    }
+  }
+  for (const path of await filesUnder(root)) {
+    const artifactPath = relative(root, path).split(sep).join("/");
+    if (!declaredPaths.has(artifactPath)) {
+      return {
+        ok: false,
+        error: {
+          code: "dist-artifact-undeclared",
+          expected: "every file in dist to be covered by forgeax-dist.json",
+          hint: "Remove the foreign file or rebuild the complete dist.",
+          detail: { path: artifactPath }
+        }
+      };
+    }
+  }
+  return { ok: true, value: manifest };
+}
+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;
+  try {
+    const meta = JSON.parse(readFileSync(path, "utf8"));
+    return meta.importer === "game-default-target-profile";
+  } catch {
+    return false;
+  }
+}
+function devKitDdcRoots(projectRoot2) {
+  return {
+    buildCacheRoot: resolve(projectRoot2, ".forgeax", "ddc", "build-cache"),
+    projectDdcRoot: resolve(projectRoot2, ".forgeax", "ddc", "v2")
+  };
+}
+function isResourcePreviewIgnoredPath(path) {
+  return ignoreDevKitCatalogPath(path) || path.endsWith(".wgsl.meta.json") || path.endsWith("target-profile.json.meta.json");
+}
+function isProjectSourceIgnoredPath(path) {
+  return ignoreDevKitCatalogPath(path) || path.endsWith(".wgsl.meta.json");
+}
+function findEngineWorkspaceRoot() {
+  let cursor = dirname(fileURLToPath(import.meta.url));
+  for (; ; ) {
+    if (existsSync(resolve(cursor, "pnpm-workspace.yaml"))) return cursor;
+    const parent = dirname(cursor);
+    if (parent === cursor) return void 0;
+    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");
+    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;
+}
+function conditionalExport(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);
+    if (selected !== void 0) return selected;
+  }
+  return void 0;
+}
+function packageExportTarget(manifest, subpath) {
+  const exportsValue = manifest.exports;
+  if (exportsValue === void 0) {
+    if (subpath.length > 0) return void 0;
+    const main = manifest.module ?? manifest.main;
+    return typeof main === "string" ? main : void 0;
+  }
+  if (typeof exportsValue === "string" || exportsValue === null) {
+    return subpath.length === 0 ? conditionalExport(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;
+  const requested = subpath.length === 0 ? "." : `./${subpath}`;
+  const exact = exportsValue[requested];
+  if (exact !== void 0) return conditionalExport(exact);
+  for (const key of keys) {
+    const marker = key.indexOf("*");
+    if (marker < 0) continue;
+    const prefix = key.slice(0, marker);
+    const suffix = key.slice(marker + 1);
+    if (!requested.startsWith(prefix) || !requested.endsWith(suffix)) continue;
+    const replacement = requested.slice(prefix.length, requested.length - suffix.length);
+    const exportTarget = exportsValue[key];
+    if (exportTarget === void 0) continue;
+    const selected = conditionalExport(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);
+  const packageName = separator < 0 ? source : source.slice(0, separator);
+  const subpath = separator < 0 ? "" : source.slice(separator + 1);
+  const packageInfo = packages.get(packageName);
+  if (packageInfo === void 0) return void 0;
+  const target = packageExportTarget(packageInfo.manifest, subpath);
+  if (target === void 0) return void 0;
+  const absolute = resolve(packageInfo.root, target);
+  const inside = relative(packageInfo.root, absolute);
+  if (inside === ".." || inside.startsWith(`..${sep}`) || absolute === packageInfo.root) {
+    return void 0;
+  }
+  return absolute;
+}
+async function createEngineWorkspaceResolver() {
+  const packages = await engineWorkspacePackages();
+  if (packages.size === 0) return void 0;
+  return {
+    name: "forgeax:devkit-engine-workspace-resolver",
+    async resolveId(source, importer) {
+      const bareSource = source.split("?", 1)[0] ?? source;
+      if (!bareSource.startsWith("@forgeax/engine-")) return null;
+      try {
+        const resolved = await this.resolve(source, importer, { skipSelf: true });
+        if (resolved !== null) return resolved;
+      } catch {
+      }
+      return engineWorkspaceImport(bareSource, packages);
+    }
+  };
+}
+async function resolveCanonicalKit() {
+  const packageJson = hostRequire.resolve("@forgeax/engine-preview/package.json");
+  const root = resolve(packageJson, "..", "assets/canonical-kit");
+  if (!existsSync(root)) throw new Error(`canonical preview kit root is missing: ${root}`);
+  const receiptPath = resolve(root, "cook-receipt.json");
+  const receipt = validateCanonicalKitReceipt(JSON.parse(await readFile(receiptPath, "utf8")));
+  if (!receipt.ok) {
+    throw new Error(`${receipt.error.code}: ${receipt.error.detail.field}`);
+  }
+  const sourcePath = resolve(root, receipt.value.transport.source);
+  const metaPath = resolve(root, receipt.value.transport.meta);
+  if (!existsSync(sourcePath) || !existsSync(metaPath)) {
+    throw new Error("canonical preview kit source and Meta must be package-owned files");
+  }
+  return { root, guid: receipt.value.source.guid };
+}
+function moduleSpecifier(from, to) {
+  const value = relative(from, to).split(sep).join("/");
+  return value.startsWith(".") ? value : `./${value}`;
+}
+function catalogModules(facts) {
+  const modules = /* @__PURE__ */ new Map();
+  const visit = (entries2, inheritedRealm = "engine") => {
+    for (const entry of entries2) {
+      const realm = entry.realm ?? inheritedRealm;
+      if (entry.group === true) {
+        visit(entry.config, realm);
+        continue;
+      }
+      if (entry.name.startsWith("cordis:") || realm === "build") continue;
+      const current = modules.get(entry.name);
+      if (current !== void 0 && current.realm !== realm) {
+        throw new Error(`plugin module ${entry.name} is assigned to multiple realms`);
+      }
+      modules.set(entry.name, { name: entry.name, realm });
+    }
+  };
+  visit(facts.plugins);
+  return [...modules.values()];
+}
+function catalogImport(facts, generated, name) {
+  const specifier = name.startsWith(".") ? moduleSpecifier(generated, resolve(facts.root, name)) : name;
+  return `() => import(${JSON.stringify(specifier)})`;
+}
+function projectImporters(facts) {
+  const specs = facts.assetImporters ?? [];
+  if (specs.length === 0) return [];
+  const createJiti = hostRequire("jiti");
+  const load = createJiti(resolve(facts.root, "package.json"), { esmResolve: true });
+  return specs.map((spec) => {
+    const separator = spec.lastIndexOf("#");
+    const moduleSpecifier2 = separator < 0 ? spec : spec.slice(0, separator);
+    const exportName = separator < 0 ? "default" : spec.slice(separator + 1);
+    const modulePath = moduleSpecifier2.startsWith(".") ? resolve(facts.root, moduleSpecifier2) : moduleSpecifier2;
+    const namespace = load(modulePath);
+    if (namespace === null || typeof namespace !== "object") {
+      throw new Error(`project-asset-importer-module-invalid: ${spec}`);
+    }
+    const factory = namespace[exportName];
+    if (typeof factory !== "function") {
+      throw new Error(`project-asset-importer-export-missing: ${spec}`);
+    }
+    const importer = factory();
+    if (importer === null || typeof importer !== "object") {
+      throw new Error(`project-asset-importer-invalid: ${spec}`);
+    }
+    return importer;
+  });
+}
+function hostSource(facts, bootstrapRoot, canonicalEnvironmentGuid) {
+  const generated = resolve(facts.root, ".forgeax", "generated");
+  const plugins = bootstrapRoot === "resource-bootstrap" ? [] : [
+    `webAudioPlugin()`,
+    `audioPlugin()`,
+    ...facts.physics === void 0 ? [] : [`physicsPlugin('${facts.physics === "2d" ? "rapier-2d" : "rapier-3d"}')`]
+  ];
+  const bootstrapPlugin = facts.bootstrapEntry === void 0 ? "" : `const bootstrapModule = await import(${JSON.stringify(
+    moduleSpecifier(generated, resolve(facts.root, facts.bootstrapEntry))
+  )});
+if (typeof bootstrapModule.bootstrap !== 'function') {
+  throw new Error('forgeax: project entry must export bootstrap(world, context)');
+}
+await app.pluginContext.plugin({
+  name: 'project-entry-bootstrap',
+  inject: ['gameHost'],
+  async apply(ctx) {
+    if (ctx.gameHost === undefined) throw new Error('forgeax: gameHost unavailable');
+    await bootstrapModule.bootstrap(ctx.gameHost.app.world, ctx.gameHost);
+  },
+});`;
+  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 { 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 { 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 { ParticleEffectPlayer, vfxGpuEffectContribution } from '@forgeax/engine-vfx';
+import { createVfxRuntimeHost } from '@forgeax/engine-vfx-render';
+
+const pluginCatalog = new Map([
+${catalogModules(facts).map(
+    ({ name, realm }) => `  [${JSON.stringify(name)}, { realm: ${JSON.stringify(realm)}, load: ${catalogImport(facts, generated, name)} }],`
+  ).join("\n")}
+]);
+const pluginEntries = ${JSON.stringify(facts.plugins, null, 2)};
+const bootstrapRoot = ${JSON.stringify(bootstrapRoot)};
+const canonicalEnvironmentGuid = ${JSON.stringify(canonicalEnvironmentGuid ?? null)};
+const resourceValue = new URLSearchParams(location.search).get('forgeax-resource-preview');
+const resource = resourceValue === null ? undefined : JSON.parse(resourceValue);
+const previewCameraEntities = new WeakMap();
+const previewCameraTargets = new WeakMap();
+let previewWorld;
+const vfxRuntimeHost = resource?.kind === 'vfx'
+  ? createVfxRuntimeHost({
+      camera: {
+        read(world) {
+          const cameraEntity = previewCameraEntities.get(world);
+          if (cameraEntity === undefined) return undefined;
+          const transform = world.get(cameraEntity, Transform);
+          const camera = world.get(cameraEntity, Camera);
+          if (!transform.ok || !camera.ok) return undefined;
+          const position = new Float32Array(transform.value.pos);
+          const target = previewCameraTargets.get(world) ?? [0, 0, 0];
+          return {
+            position,
+            right: new Float32Array([1, 0, 0]),
+            up: new Float32Array([0, 1, 0]),
+            viewProjection: mat4.computeViewProj(
+              mat4.create(),
+              position,
+              target,
+              [0, 1, 0],
+              camera.value.fov,
+              camera.value.aspect,
+              camera.value.near,
+              camera.value.far,
+            ),
+          };
+        },
+      },
+    })
+  : undefined;
+
+function previewVfxBounds(payload) {
+  if (payload?.kind !== 'particle-effect' || payload.program?.emitters?.length === 0) return undefined;
+  let minX = Infinity;
+  let minY = Infinity;
+  let minZ = Infinity;
+  let maxX = -Infinity;
+  let maxY = -Infinity;
+  let maxZ = -Infinity;
+  for (const emitter of payload.program.emitters) {
+    const bounds = emitter.bounds;
+    if (bounds?.kind === 'sphere' && Array.isArray(bounds.center) && typeof bounds.radius === 'number') {
+      const [x, y, z] = bounds.center;
+      if (![x, y, z, bounds.radius].every((value) => typeof value === 'number' && Number.isFinite(value)) || bounds.radius < 0) return undefined;
+      minX = Math.min(minX, x - bounds.radius);
+      minY = Math.min(minY, y - bounds.radius);
+      minZ = Math.min(minZ, z - bounds.radius);
+      maxX = Math.max(maxX, x + bounds.radius);
+      maxY = Math.max(maxY, y + bounds.radius);
+      maxZ = Math.max(maxZ, z + bounds.radius);
+      continue;
+    }
+    if (bounds?.kind === 'aabb' && Array.isArray(bounds.min) && Array.isArray(bounds.max)) {
+      const [loX, loY, loZ] = bounds.min;
+      const [hiX, hiY, hiZ] = bounds.max;
+      if (![loX, loY, loZ, hiX, hiY, hiZ].every((value) => typeof value === 'number' && Number.isFinite(value))) return undefined;
+      minX = Math.min(minX, loX);
+      minY = Math.min(minY, loY);
+      minZ = Math.min(minZ, loZ);
+      maxX = Math.max(maxX, hiX);
+      maxY = Math.max(maxY, hiY);
+      maxZ = Math.max(maxZ, hiZ);
+      continue;
+    }
+    return undefined;
+  }
+  if (![minX, minY, minZ, maxX, maxY, maxZ].every(Number.isFinite)) return undefined;
+  const center = [(minX + maxX) / 2, (minY + maxY) / 2, (minZ + maxZ) / 2];
+  const radius = Math.max(1, Math.hypot(maxX - minX, maxY - minY, maxZ - minZ));
+  return { aabb: [minX, minY, minZ, maxX, maxY, maxZ], center, radius };
+}
+
+const canvas = document.querySelector('#app');
+if (!(canvas instanceof HTMLCanvasElement)) throw new Error('forgeax: missing canvas');
+const resizeCanvas = () => {
+  const dpr = Math.min(window.devicePixelRatio || 1, 2);
+  const width = Math.max(1, Math.round(canvas.clientWidth * dpr));
+  const height = Math.max(1, Math.round(canvas.clientHeight * dpr));
+  if (canvas.width !== width) canvas.width = width;
+  if (canvas.height !== height) canvas.height = height;
+};
+const resizeObserver = new ResizeObserver(resizeCanvas);
+resizeObserver.observe(canvas);
+resizeCanvas();
+const binding = import.meta.env.DEV
+  ? createStandaloneRuntimeAssetBinding(${JSON.stringify(facts.id)})
+  : undefined;
+const assetCatalog = binding === undefined
+  ? undefined
+  : createCatalogSource({ url: binding.catalogUrl, expectedScope: binding });
+const bundler = {
+  ...forgeaxBundlerAdapter(),
+  ...(binding === undefined ? {} : { importTransport: createDevImportTransport(binding) }),
+};
+
+function previewStable(value) {
+  if (value instanceof ArrayBuffer) return 'ArrayBuffer:' + JSON.stringify(Array.from(new Uint8Array(value)));
+  if (ArrayBuffer.isView(value)) return value.constructor.name + ':' + JSON.stringify(Array.from(new Uint8Array(value.buffer, value.byteOffset, value.byteLength)));
+  if (Array.isArray(value)) return '[' + value.map(previewStable).join(',') + ']';
+  if (value !== null && typeof value === 'object') {
+    const record = value;
+    return '{' + Object.keys(record).sort().map((key) => JSON.stringify(key) + ':' + previewStable(record[key])).join(',') + '}';
+  }
+  return JSON.stringify(value) ?? 'null';
+}
+
+async function previewDigest(value) {
+  const bytes = new TextEncoder().encode(previewStable(value));
+  const digest = await crypto.subtle.digest('SHA-256', bytes);
+  return 'sha256:' + Array.from(new Uint8Array(digest)).map((byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+
+async function previewOwnerFacts(assets, resource, payload) {
+  if (resource.kind === 'material') {
+    const primaryPass = Array.isArray(payload.passes) ? payload.passes[0] : undefined;
+    const program = primaryPass?.program?.module;
+    const pass = primaryPass?.name;
+    return {
+      subjectDigest: await previewDigest(payload),
+      bindingsDigest: await previewDigest(payload.passes),
+      closureDigest: await previewDigest(payload.values ?? payload.passes),
+      ...(typeof program === 'string' ? { program } : {}),
+      ...(typeof pass === 'string' ? { pass } : {}),
+    };
+  }
+  if (resource.kind === 'mesh') {
+    return {
+      subjectDigest: await previewDigest(payload),
+      vertexDigest: await previewDigest(payload.vertices),
+      indexDigest: await previewDigest(payload.indices ?? []),
+      submeshDigest: await previewDigest(payload.submeshes),
+      aabbDigest: await previewDigest(payload.aabb),
+    };
+  }
+  if (resource.kind === 'texture') {
+    const mipCount = typeof payload.mipLevelCount === 'number' ? payload.mipLevelCount : 1;
+    const filter = 'linear';
+    return {
+      subjectDigest: await previewDigest(payload),
+      boundDigest: await previewDigest({ width: payload.width, height: payload.height, format: payload.format }),
+      uvDigest: await previewDigest({ offset: [0, 0], scale: [1, 1], rotation: 0 }),
+      bindingDigest: await previewDigest({ format: payload.format, colorSpace: payload.colorSpace, filter, mipCount }),
+      format: payload.format,
+      colorSpace: payload.colorSpace,
+      filter,
+      mipCount,
+      dimensions: [payload.width, payload.height],
+      payloadClass: 'color',
+    };
+  }
+  return undefined;
+}
+
+async function prepareProject(app) {
+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');
+    if (!environment.ok) throw environment.error;
+    if (environment.value.kind !== 'equirect') {
+      throw new Error(\`canonical preview environment expected equirect, received \${environment.value.kind}\`);
+    }
+    if (environment.value.width <= 0 || environment.value.height <= 0 || environment.value.data.byteLength === 0) {
+      throw new Error('canonical preview environment must provide decoded equirect pixels');
+    }
+    canonicalEnvironment = app.world.allocSharedRef('EquirectAsset', environment.value);
+  }
+  if (resource.kind === 'vfx') {
+    if (vfxRuntimeHost === undefined) throw new Error('VFX preview host was not created');
+    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);
+  if (!loaded.ok) throw loaded.error;
+  const payload = loaded.value;
+  if (resource.kind === 'vfx' && payload.kind !== 'particle-effect') {
+    throw new Error(\`VFX preview expected ParticleEffectAsset, received \${payload.kind}\`);
+  }
+  const vfxBounds = resource.kind === 'vfx' ? previewVfxBounds(payload) : undefined;
+  if (resource.kind === 'vfx' && vfxBounds === undefined) {
+    throw new Error('VFX preview owner did not publish finite emitter bounds');
+  }
+  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');
+        if (!material.ok) throw material.error;
+        if (material.value.kind !== 'material') {
+          throw new Error('mesh material slot resolved to a non-material asset');
+        }
+        return app.world.allocSharedRef('MaterialAsset', material.value);
+      }))
+    : undefined;
+  const meshHandle = resource.kind === 'mesh' && payload.kind === 'mesh'
+    ? app.world.allocSharedRef('MeshAsset', payload)
+    : app.world.internSharedRef(
+        'MeshAsset',
+        createPrimitiveMesh(resource.kind === 'texture' ? 'quad' : 'sphere').unwrap(),
+      );
+  const textureHandle = resource.kind === 'texture' && payload.kind === 'texture'
+    ? app.world.allocSharedRef('TextureAsset', payload)
+    : undefined;
+  if (textureHandle !== undefined && payload.kind === 'texture') {
+    const bytes = payload.data instanceof Uint8ClampedArray
+      ? new Uint8Array(payload.data.buffer, payload.data.byteOffset, payload.data.byteLength)
+      : payload.data;
+    const uploaded = await app.renderer.store.uploadTexture(textureHandle, payload, {
+      bytes,
+      width: payload.width,
+      height: payload.height,
+      mime: 'image/png',
+      colorSpace: payload.colorSpace,
+      mipmap: payload.mipmap,
+    });
+    if (!uploaded.ok) throw uploaded.error;
+  }
+  const materialPayload = resource.kind === 'texture' && payload.kind === 'texture'
+    ? Materials.unlit([1, 1, 1, 1], { baseColorTexture: textureHandle })
+    : resource.kind === 'material' && payload.kind === 'material'
+      ? payload
+      : undefined;
+  const materialHandle = materialPayload === undefined
+    ? undefined
+    : app.world.allocSharedRef('MaterialAsset', materialPayload);
+  const materialBindings = resource.kind === 'mesh'
+    ? meshMaterialHandles
+    : materialHandle === undefined
+      ? undefined
+      : [materialHandle];
+  const rawAabb = payload.kind === 'mesh' ? payload.aabb : undefined;
+  const aabb = rawAabb !== undefined && (Array.isArray(rawAabb) || ArrayBuffer.isView(rawAabb)) && rawAabb.length === 6
+    ? Array.from(rawAabb)
+    : resource.kind === 'mesh' && payload.kind === 'mesh'
+      ? (() => { throw new Error('mesh owner did not publish a finite AABB'); })()
+      : [-1, -1, -1, 1, 1, 1];
+  const meshFrame = resource.kind === 'mesh'
+    ? fitToolPreviewCameraToAabb(aabb, { aspect: 1, fov: Math.PI / 4 })
+    : undefined;
+  const textureWidth = resource.kind === 'texture' && payload.kind === 'texture' && typeof payload.width === 'number'
+    ? Math.max(1, payload.width)
+    : 1;
+  const textureHeight = resource.kind === 'texture' && payload.kind === 'texture' && typeof payload.height === 'number'
+    ? Math.max(1, payload.height)
+    : 1;
+  const textureAspect = textureWidth / textureHeight;
+  const textureScale = textureAspect >= 1
+    ? [textureAspect, 1, 1]
+    : [1, 1 / textureAspect, 1];
+  const center = meshFrame?.center ?? vfxBounds?.center ?? [(aabb[0] + aabb[3]) / 2, (aabb[1] + aabb[4]) / 2, (aabb[2] + aabb[5]) / 2];
+  const radius = meshFrame?.radius ?? vfxBounds?.radius ?? Math.max(1, Math.hypot(aabb[3] - aabb[0], aabb[4] - aabb[1], aabb[5] - aabb[2]));
+  const texturePreview = resource.kind === 'texture';
+  if (resource.kind === 'vfx') {
+    const effect = app.world.allocSharedRef('ParticleEffectAsset', payload);
+    app.world.spawn(
+      { component: Transform, data: { pos: center } },
+      { component: ParticleEffectPlayer, data: { effect, playing: true, seed: 0, timeScale: 1 } },
+    );
+  } else {
+    app.world.spawn(
+      { component: Transform, data: { pos: center, ...(texturePreview ? { scale: textureScale } : {}) } },
+      { component: MeshFilter, data: { assetHandle: meshHandle } },
+      { component: MeshRenderer, data: materialBindings === undefined ? {} : { materials: materialBindings } },
+    );
+  }
+  const cameraData = texturePreview
+    ? {
+        fov: 0,
+        aspect: 1,
+        near: 0.01,
+        far: 100,
+        projection: CAMERA_PROJECTION_ORTHOGRAPHIC,
+        left: -textureScale[0] * 0.6,
+        right: textureScale[0] * 0.6,
+        bottom: -textureScale[1] * 0.6,
+        top: textureScale[1] * 0.6,
+        tonemap: TONEMAP_NONE,
+        antialias: 0,
+        bloom: 0,
+        clearColor: [0, 0, 0, 1],
+      }
+    : {
+        fov: Math.PI / 4,
+        aspect: 1,
+        near: meshFrame?.near ?? 0.01,
+        far: meshFrame?.far ?? radius * 8,
+        tonemap: TONEMAP_REINHARD_EXTENDED,
+      };
+  const cameraPosition = texturePreview
+    ? [0, 0, 5]
+    : [center[0], center[1], center[2] + (meshFrame?.distance ?? radius * 2.5)];
+  const cameraEntity = app.world.spawn({ component: Camera, data: cameraData }, { component: Transform, data: { pos: cameraPosition } }).unwrap();
+  previewCameraEntities.set(app.world, cameraEntity);
+  previewCameraTargets.set(app.world, center);
+  if (!texturePreview) {
+    app.world.spawn({ component: DirectionalLight, data: { direction: [-0.5, -1, -0.3], intensity: 2 } });
+    if (canonicalEnvironment === undefined) throw new Error('canonical preview environment was not loaded');
+    app.world.spawn({ component: Skylight, data: { equirect: canonicalEnvironment } });
+    app.world.spawn({ component: SkyboxBackground, data: { equirect: canonicalEnvironment } });
+  }
+  const ownerFacts = await previewOwnerFacts(assets, resource, payload);
+  const publishedAsset = resource.kind === 'mesh' && payload.kind === 'mesh' && payload.aabb !== undefined
+    ? { ...payload, aabb: Array.from(payload.aabb) }
+    : payload;
+  return {
+    kind: resource.kind,
+    guid: resource.guid,
+    asset: publishedAsset,
+    ...(ownerFacts === undefined ? {} : { ownerFacts }),
+  };
+}
+if (bootstrapRoot === 'resource-bootstrap') return;
+let defaultScene;
+let defaultSceneRoot;
+const defaultSceneGuid = ${JSON.stringify(facts.defaultScene)};
+if (defaultSceneGuid !== undefined) {
+  const loaded = await assets.load(defaultSceneGuid, 'scene');
+  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);
+  if (!instantiated.ok) throw instantiated.error;
+  defaultSceneRoot = instantiated.value.root;
+}
+const uiRoot = document.querySelector('#game-ui');
+await app.pluginContext.plugin(gameHostPlugin({
+  app,
+  assets,
+  canvas,
+  renderer: app.renderer,
+  ...(defaultScene === undefined ? {} : { defaultScene }),
+  ...(defaultSceneRoot === undefined ? {} : { defaultSceneRoot }),
+  uiRoot: uiRoot instanceof HTMLElement ? uiRoot : document.body,
+  setPointerLockAllowed: (allowed) => app.input?.setPointerLockAllowed?.(allowed),
+}));
+const { loader: pluginLoader } = await installCatalogLoader(app.pluginContext, pluginCatalog, 'engine');
+await pluginLoader.root.update(projectPluginEntries(pluginEntries, 'engine'));
+await pluginLoader.await();
+}
+
+const query = new URLSearchParams(location.search);
+const recipeValue = query.get('forgeax-tool-recipe');
+const snapshotValue = query.get('forgeax-tool-snapshot');
+const runIdValue = query.get('forgeax-tool-run-id');
+if (query.has('forgeax-tool-replay')) {
+  globalThis.__forgeaxToolReplayHost = {
+    ready: true,
+    async run(capture) {
+      const result = await replayToolPreviewCapture(capture);
+      return result.ok ? { ok: true, result: result.value } : { ok: false, error: result.error };
+    },
+  };
+} else if (recipeValue !== null) {
+  const previewRecipe = createToolPreviewRecipe(JSON.parse(recipeValue));
+  const host = await createToolPreviewHost({
+    ...(runIdValue === null ? {} : { runId: runIdValue }),
+    recipe: previewRecipe,
+    snapshot: JSON.parse(snapshotValue ?? 'null'),
+    ...(resource === undefined ? {} : { resource }),
+    canvas,
+    app: {
+      ...(assetCatalog === undefined ? {} : { assetCatalog }),
+      ...(vfxRuntimeHost === undefined ? {} : { assetDecoders: [vfxGpuEffectContribution] }),
+      plugins: [${plugins.join(", ")}],
+      ...(vfxRuntimeHost === undefined ? {} : { features: [vfxRuntimeHost.feature] }),
+    },
+    bundler,
+    prepare: prepareProject,
+    collectResourceFacts(app, current) {
+      if (current === undefined) return current;
+      if (resource?.kind !== 'vfx') {
+        if (resource?.kind === 'material' || resource?.kind === 'mesh' || resource?.kind === 'texture') {
+          if (app.renderer.drawCalls <= 0) return current;
+          if (resource.kind === 'mesh') {
+            const asset = current.asset;
+            const aabb = asset?.aabb;
+            const submeshes = asset?.submeshes;
+            const materialSlots = asset?.materialSlots;
+            if (!Array.isArray(aabb) || aabb.length !== 6 || !Array.isArray(submeshes) || !Array.isArray(materialSlots)) {
+              return current;
+            }
+            return {
+              ...current,
+              observation: {
+                ...current.ownerFacts,
+                aabb,
+                submeshCount: submeshes.length,
+                materialSlotCount: materialSlots.length,
+              },
+            };
+          }
+          return {
+            ...current,
+            observation: current.ownerFacts,
+          };
+        }
+        return current;
+      }
+      if (vfxRuntimeHost === undefined) return current;
+      const hostInspection = vfxRuntimeHost.inspect(app.world);
+      const player = hostInspection?.players[0];
+      const renderObservation = vfxRuntimeHost.feature.inspect();
+      if (player === undefined || renderObservation.frameNumber < 0) {
+        return current;
+      }
+      const bounds = previewVfxBounds(current.asset);
+      if (bounds === undefined) return current;
+      const emitterDigest = JSON.stringify(player.emitters.map(({ id, module, capacity }) => ({ id, module, capacity })));
+      const sampleDigest = JSON.stringify(player.emitters.map(({ id, schedule }) => ({ id, schedule })));
+      const boundsDigest = JSON.stringify(player.emitters.map(({ id, bounds: emitterBounds }) => ({ id, bounds: emitterBounds })));
+      const computeDigest = player.programFingerprint;
+      const indirectDigest = JSON.stringify(player.emitters.map(({ id, renderers }) => ({ id, renderers: renderers.map(({ kind, enabled }) => ({ kind, enabled })) })));
+      return {
+        ...current,
+        observation: {
+          subjectDigest: current.asset.programFingerprint,
+          programFingerprint: player.programFingerprint,
+          emitterDigest,
+          sampleDigest,
+          boundsDigest,
+          computeDigest,
+          indirectDigest,
+          authoredBounds: bounds.aabb,
+          seed: player.seed,
+          fixedDelta: player.fixedDelta,
+          timelineFrames: previewRecipe.frames,
+          dispatches: renderObservation.dispatches,
+          indirectDraws: renderObservation.indirectDraws,
+          subjectOutputs: renderObservation.subjectOutputs,
+        },
+      };
+    },
+    onDispose: async () => {
+      if (vfxRuntimeHost === undefined || previewWorld === undefined) return;
+      const detached = await vfxRuntimeHost.detachWorld({ world: previewWorld });
+      if (!detached.ok) throw detached.error;
+    },
+    executeAction(action) {
+      return !globalThis.dispatchEvent(new CustomEvent('forgeax-tool-action', {
+        detail: action,
+        cancelable: true,
+      }));
+    },
+  });
+  if (!host.ok) {
+    globalThis.__forgeaxToolHost = {
+      ready: true,
+      capture: async () => ({ ok: false, error: host.error }),
+      run: async () => ({ ok: false, error: host.error }),
+      dispose: async () => undefined,
+    };
+  } else {
+    globalThis.__forgeaxToolHost = {
+      ready: true,
+      async capture() {
+        const result = await host.value.capture();
+        return result.ok ? { ok: true, result: result.value } : { ok: false, error: result.error };
+      },
+      async run() {
+        const result = await host.value.run();
+        return result.ok ? { ok: true, result: result.value } : { ok: false, error: result.error };
+      },
+      dispose: () => host.value.dispose(),
+    };
+    window.addEventListener('pagehide', () => void host.value.dispose(), { once: true });
+  }
+} else {
+  const result = await createApp(
+    canvas,
+    {
+      ...(assetCatalog === undefined ? {} : { assetCatalog }),
+      ...(vfxRuntimeHost === undefined ? {} : { assetDecoders: [vfxGpuEffectContribution] }),
+      plugins: [${plugins.join(", ")}],
+    },
+    bundler,
+  );
+  if (!result.ok) throw result.error;
+  const app = result.value;
+  await prepareProject(app);
+${bootstrapPlugin}
+  app.start().unwrap();
+  let disposed = false;
+  const dispose = () => {
+    if (disposed) return;
+    disposed = true;
+    resizeObserver.disconnect();
+    void app.dispose();
+  };
+  window.addEventListener('pagehide', dispose);
+}
+`;
+}
+function escapeHtml(value) {
+  return value.replace(/[&<>"']/g, (character) => {
+    switch (character) {
+      case "&":
+        return "&amp;";
+      case "<":
+        return "&lt;";
+      case ">":
+        return "&gt;";
+      case '"':
+        return "&quot;";
+      case "'":
+        return "&#39;";
+    }
+    return character;
+  });
+}
+function htmlSource(title) {
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <link rel="icon" href="data:," />
+    <title>${escapeHtml(title)}</title>
+    <style>
+      html, body, #app-shell, #app { width: 100%; height: 100%; margin: 0; overflow: hidden; }
+      body { background: #05070b; }
+      #app { display: block; }
+      #app-shell { position: relative; }
+      #game-ui { position: absolute; inset: 0; overflow: hidden; pointer-events: none; }
+      #game-ui > * { pointer-events: auto; }
+      #forgeax-fatal { position: fixed; inset: 0; z-index: 2147483647; display: none; place-items: center; padding: 24px; background: #0b0d10; color: #e6e6e6; font: 15px/1.6 system-ui, sans-serif; text-align: center; white-space: pre-wrap; }
+    </style>
+  </head>
+  <body>
+    <div id="app-shell"><canvas id="app"></canvas><div id="game-ui"></div></div><div id="forgeax-fatal" role="alert"></div>
+    <script>
+      (() => {
+        const show = (reason) => {
+          const notice = document.querySelector('#forgeax-fatal');
+          if (!(notice instanceof HTMLElement)) return;
+          const message = reason instanceof Error ? reason.message : String(reason ?? 'Unknown startup failure');
+          notice.textContent = 'ForgeaX game failed to start.\\n' + message;
+          notice.style.display = 'grid';
+        };
+        window.addEventListener('error', (event) => show(event.error ?? event.message));
+        window.addEventListener('unhandledrejection', (event) => show(event.reason));
+      })();
+    </script>
+    <script type="module" src="./main.ts"></script>
+  </body>
+</html>
+`;
+}
+async function createViteConfig(facts, command2, base = "/", options = {}) {
+  const bootstrapRoot = options.bootstrapRoot ?? "project-bootstrap";
+  const canonicalKit = bootstrapRoot === "resource-bootstrap" ? await resolveCanonicalKit() : void 0;
+  const generated = resolve(facts.root, ".forgeax", "generated");
+  await mkdir(generated, { recursive: true });
+  await Promise.all([
+    writeFile(resolve(generated, "index.html"), htmlSource(facts.name)),
+    writeFile(resolve(generated, "main.ts"), hostSource(facts, bootstrapRoot, canonicalKit?.guid))
+  ]);
+  const roots = [
+    ...facts.assetRoots.map((root) => resolve(facts.root, root)),
+    ...canonicalKit === void 0 ? [] : [canonicalKit.root]
+  ];
+  const importers = [...projectImporters(facts)];
+  const runtimeBinding = createStandaloneRuntimeAssetBinding(facts.id);
+  const engineWorkspaceResolver = await createEngineWorkspaceResolver();
+  const plugins = [
+    ...engineWorkspaceResolver === void 0 ? [] : [engineWorkspaceResolver],
+    forgeaxShader(),
+    pluginPack({
+      roots,
+      base,
+      runtimeBinding,
+      ddc: devKitDdcRoots(facts.root),
+      scriptablePack: {},
+      refresh: command2 === "serve" ? reloadAssetHost() : void 0,
+      importers: [
+        audioImporter,
+        imageImporter,
+        fbxImporter,
+        gltfImporter,
+        fontImporter,
+        ...importers
+      ],
+      cookers: [createParticleCodeNativeCookerFromRoots(roots)],
+      ...bootstrapRoot === "resource-bootstrap" ? { ignorePath: isResourcePreviewIgnoredPath } : { ignorePath: isProjectSourceIgnoredPath }
+    })
+  ];
+  return {
+    root: generated,
+    base,
+    configFile: false,
+    publicDir: facts.assetPublicDir === void 0 ? false : resolve(facts.root, facts.assetPublicDir),
+    plugins,
+    resolve: { 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;
+  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 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;
+  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 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];
+  if (!info.isDirectory()) return [];
+  const output = [];
+  const entries2 = await readdir(path, { withFileTypes: true });
+  for (const entry of entries2.sort((a, b) => a.name.localeCompare(b.name))) {
+    if (entry.name.startsWith(".") || entry.name === "node_modules" || entry.name === "dist")
+      continue;
+    const child = resolve(path, entry.name);
+    if (entry.isDirectory()) output.push(...await sourcesAt(child));
+    else if (entry.isFile() && !entry.name.endsWith(".meta.json")) output.push(child);
+  }
+  return output;
+}
+async function addImage(sourcePath, dryRun2) {
+  const metaPath = `${sourcePath}.meta.json`;
+  const source = basename(sourcePath);
+  let existing;
+  try {
+    existing = JSON.parse(await readFile(metaPath, "utf8"));
+  } catch (cause) {
+    if (cause.code !== "ENOENT") {
+      return failure({
+        code: "asset-meta-unreadable",
+        expected: "an absent or readable JSON sidecar",
+        hint: "Repair the existing sidecar before adding the source again.",
+        detail: { source: sourcePath, metaPath }
+      });
+    }
+  }
+  if (existing !== void 0) {
+    const value = existing;
+    const row = value.subAssets?.[0];
+    if (value.importer !== "image" || value.source !== source || value.subAssets?.length !== 1 || typeof row?.guid !== "string" || row.kind !== "texture") {
+      return failure({
+        code: "asset-meta-conflict",
+        expected: "the existing sidecar to describe this image source and one texture identity",
+        hint: "Resolve the sidecar conflict explicitly; DevKit will not replace authored identity.",
+        detail: { source: sourcePath, metaPath }
+      });
+    }
+    return { ok: true, value: { source: sourcePath, metaPath, guid: row.guid, reused: true } };
+  }
+  const guid = AssetGuid.format(AssetGuid.random());
+  const linear = extname(sourcePath).toLowerCase() === ".hdr";
+  const meta = {
+    schemaVersion: "1.0.0",
+    kind: "external-asset-package",
+    importer: "image",
+    source,
+    importSettings: {
+      colorSpace: linear ? "linear" : "srgb",
+      mipmap: true,
+      addressMode: "repeat",
+      filterMode: "linear"
+    },
+    subAssets: [{ guid, sourceIndex: 0, kind: "texture", sourceKey: "texture" }]
+  };
+  if (!dryRun2) await writeFile(metaPath, `${JSON.stringify(meta, null, 2)}
+`, { flag: "wx" });
+  return { ok: true, value: { source: sourcePath, metaPath, guid, reused: false, dryRun: dryRun2 } };
+}
+async function addGltf(sourcePath, dryRun2) {
+  if (dryRun2) {
+    const exists = await stat(`${sourcePath}.meta.json`).then(() => true).catch(() => false);
+    return {
+      ok: true,
+      value: {
+        source: sourcePath,
+        metaPath: `${sourcePath}.meta.json`,
+        reused: exists,
+        dryRun: true
+      }
+    };
+  }
+  const stdout = [];
+  const stderr = [];
+  const exitCode = await runCliGltf(["import", sourcePath], {
+    stdoutWrite: (line) => stdout.push(line),
+    stderrWrite: (line) => stderr.push(line)
+  });
+  if (exitCode !== 0) {
+    return producerFailure(
+      stderr,
+      {
+        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 }
+    );
+  }
+  return { ok: true, value: { source: sourcePath, metaPath: `${sourcePath}.meta.json` } };
+}
+async function assetAddCommand(options) {
+  const facts = await readProjectFacts(options.root);
+  if (!facts.ok) return facts;
+  const target = resolve(facts.value.root, options.path);
+  try {
+    const sources = await sourcesAt(target);
+    const supported = sources.filter((source) => {
+      const extension = extname(source).toLowerCase();
+      return imageExtensions.has(extension) || gltfExtensions.has(extension);
+    });
+    if (supported.length === 0) {
+      return failure({
+        code: "source-package-importer-missing",
+        expected: "a .png, .jpg, .jpeg, .hdr, .gltf, or .glb source",
+        hint: "Use a supported built-in importer or add an explicit producer before adding this source.",
+        detail: { target }
+      });
+    }
+    const assets = [];
+    for (const source of supported) {
+      const result = imageExtensions.has(extname(source).toLowerCase()) ? await addImage(source, options.dryRun === true) : await addGltf(source, options.dryRun === true);
+      if (!result.ok) return result;
+      assets.push(result.value);
+    }
+    return { ok: true, value: { root: facts.value.root, assets, dryRun: options.dryRun === true } };
+  } catch (cause) {
+    return failure(commandError(cause, "asset-add-failed"));
+  }
+}
+async function entries(options) {
+  const facts = await readProjectFacts(options.root);
+  if (!facts.ok) return facts;
+  const stdout = [];
+  const stderr = [];
+  const result = await scanEntries(
+    facts.value.assetRoots.map((root) => resolve(facts.value.root, root)),
+    { stdoutWrite: (line) => stdout.push(line), stderrWrite: (line) => stderr.push(line) }
+  );
+  if (!result.ok) {
+    return producerFailure(
+      stderr,
+      {
+        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."
+      },
+      {}
+    );
+  }
+  return { ok: true, value: { facts: facts.value, entries: result.value } };
+}
+async function assetListCommand(options = {}) {
+  const result = await entries(options);
+  if (!result.ok) return result;
+  return { ok: true, value: result.value.entries };
+}
+async function assetVerifyCommand(options = {}) {
+  const result = await entries(options);
+  if (!result.ok) return result;
+  return {
+    ok: true,
+    value: { root: result.value.facts.root, assetCount: result.value.entries.length }
+  };
+}
+async function assetInspectCommand(options) {
+  const result = await entries(options);
+  if (!result.ok) return result;
+  const subject = options.subject.toLowerCase();
+  const matches = result.value.entries.filter(
+    (entry) => entry.guid.toLowerCase() === subject || entry.name?.toLowerCase() === subject
+  );
+  if (matches.length !== 1) {
+    return failure({
+      code: matches.length === 0 ? "asset-not-found" : "asset-subject-ambiguous",
+      expected: "the GUID or name to resolve to exactly one asset",
+      hint: matches.length === 0 ? "Run asset list and choose a known subject." : "Use the stable GUID.",
+      detail: { subject: options.subject, matches }
+    });
+  }
+  return { ok: true, value: matches[0] };
+}
+var imageExtensions, gltfExtensions;
+var init_assets = __esm({
+  "src/assets.ts"() {
+    init_project();
+    imageExtensions = /* @__PURE__ */ new Set([".png", ".jpg", ".jpeg", ".hdr"]);
+    gltfExtensions = /* @__PURE__ */ new Set([".gltf", ".glb"]);
+  }
+});
+
+// package.json
+var package_default;
+var init_package = __esm({
+  "package.json"() {
+    package_default = {
+      name: "@forgeax/engine-devkit",
+      version: "0.0.0",
+      private: false,
+      type: "module",
+      license: "Apache-2.0",
+      sideEffects: false,
+      description: "ForgeaX external game project CLI and build orchestration.",
+      bin: {
+        forgeax: "./dist/cli.mjs"
+      },
+      exports: {
+        ".": {
+          types: "./dist/index.d.ts",
+          import: "./dist/index.mjs"
+        },
+        "./cli": "./dist/cli.mjs",
+        "./package.json": "./package.json"
+      },
+      main: "./dist/index.mjs",
+      types: "./dist/index.d.ts",
+      files: [
+        "dist",
+        "README.md",
+        "LICENSE"
+      ],
+      scripts: {
+        build: "tsup",
+        test: "vitest run"
+      },
+      dependencies: {
+        "@forgeax/engine-animation": "workspace:*",
+        "@forgeax/engine-app": "workspace:*",
+        "@forgeax/engine-assets-runtime": "workspace:*",
+        "@forgeax/engine-audio": "workspace:*",
+        "@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:*",
+        "@forgeax/engine-pack": "workspace:*",
+        "@forgeax/engine-physics": "workspace:*",
+        "@forgeax/engine-plugin": "workspace:*",
+        "@forgeax/engine-preview": "workspace:*",
+        "@forgeax/engine-project": "workspace:*",
+        "@forgeax/engine-rhi-debug": "workspace:*",
+        "@forgeax/engine-render": "workspace:*",
+        "@forgeax/engine-render-graph": "workspace:*",
+        "@forgeax/engine-runtime": "workspace:*",
+        "@forgeax/engine-scene": "workspace:*",
+        "@forgeax/engine-shader-compiler": "workspace:*",
+        "@forgeax/engine-skinning": "workspace:*",
+        "@forgeax/engine-tool-runtime": "workspace:*",
+        "@forgeax/engine-types": "workspace:*",
+        "@forgeax/engine-vfx-compiler": "workspace:*",
+        "@forgeax/engine-vite-plugin-pack": "workspace:*",
+        "@forgeax/engine-vite-plugin-shader": "workspace:*",
+        jiti: "1.21.7",
+        playwright: "1.60.0",
+        vite: "8.0.10",
+        vitest: "4.1.5"
+      },
+      devDependencies: {
+        "@forgeax/engine-rhi-null": "workspace:*",
+        "@types/node": "^20.14.0"
+      },
+      forgeax: {
+        metrics: {
+          "bundle-size": {
+            enabled: true,
+            path: "dist/cli.mjs",
+            compression: "gzip"
+          },
+          fps: {
+            enabled: false,
+            reason: "Node-only build orchestration; runtime FPS belongs to consumer games"
+          },
+          bench: {
+            enabled: false,
+            reason: "CLI latency is not a runtime hot path"
+          },
+          gate: {
+            enabled: true,
+            command: "pnpm test",
+            cwd: "packages/devkit"
+          },
+          "spike-report": {
+            enabled: false,
+            reason: "production DevKit package"
+          }
+        }
+      }
+    };
+  }
+});
+function createInitPlan(facts, sdk) {
+  const manifest = structuredClone(facts.packageJson);
+  const packageVersions = new Map(sdk?.packages.map((entry) => [entry.name, entry.version]));
+  const devkitVersion = packageVersions.get("@forgeax/engine-devkit") ?? package_default.version;
+  const dependencyChanges = [];
+  if (sdk !== void 0) {
+    for (const section of ["dependencies", "devDependencies"]) {
+      const dependencies = manifest[section];
+      if (dependencies === null || typeof dependencies !== "object") continue;
+      const unsupported = Object.keys(dependencies).filter(
+        (name) => !name.startsWith("@forgeax/engine-") && !(name in SDK_DEV_DEPENDENCIES)
+      );
+      if (unsupported.length > 0) {
+        return {
+          ok: false,
+          error: {
+            code: "sdk-external-dependency-unsupported",
+            expected: "archive-backed init dependencies to belong to the SDK closure",
+            hint: "Remove the external dependency or use a network-backed package workflow explicitly.",
+            detail: { root: facts.root, dependencies: unsupported.sort() }
+          }
+        };
+      }
+    }
+  }
+  for (const section of ["dependencies", "devDependencies"]) {
+    const dependencies = manifest[section];
+    if (dependencies === null || typeof dependencies !== "object") continue;
+    for (const [name, value] of Object.entries(dependencies)) {
+      if (name.startsWith("@forgeax/engine-") && typeof value === "string" && value.startsWith("workspace:")) {
+        const version = packageVersions.get(name) ?? devkitVersion;
+        dependencyChanges.push({ section, name, from: value, to: version });
+      }
+    }
+  }
+  if (sdk !== void 0) {
+    const existingEngineNames = new Set(
+      ["dependencies", "devDependencies"].flatMap((section) => {
+        const value = manifest[section];
+        return value !== null && typeof value === "object" ? Object.keys(value).filter((name) => name.startsWith("@forgeax/engine-")) : [];
+      })
+    );
+    for (const entry of sdk.packages) {
+      if (entry.name === "@forgeax/engine-devkit" || existingEngineNames.has(entry.name)) continue;
+      dependencyChanges.push({
+        section: "dependencies",
+        name: entry.name,
+        to: entry.version
+      });
+    }
+    const devDependencies2 = manifest.devDependencies !== null && typeof manifest.devDependencies === "object" ? manifest.devDependencies : {};
+    for (const [name, version] of Object.entries(SDK_DEV_DEPENDENCIES)) {
+      if (devDependencies2[name] === version) continue;
+      dependencyChanges.push({
+        section: "devDependencies",
+        name,
+        ...typeof devDependencies2[name] === "string" ? { from: devDependencies2[name] } : {},
+        to: version
+      });
+    }
+  }
+  const scriptsValue = manifest.scripts;
+  const scripts = scriptsValue !== null && typeof scriptsValue === "object" ? scriptsValue : {};
+  const scriptChanges = [];
+  for (const [name, command2] of Object.entries(STANDARD_SCRIPTS)) {
+    const existing = scripts[name];
+    if (existing === void 0) scriptChanges.push({ name, to: command2 });
+    else if (existing !== command2) {
+      return {
+        ok: false,
+        error: {
+          code: "project-script-conflict",
+          expected: `package.json#scripts.${name} to be absent or ${JSON.stringify(command2)}`,
+          hint: `Rename the existing ${name} script, then rerun forgeax init.`,
+          detail: { root: facts.root, script: name, existing }
+        }
+      };
+    }
+  }
+  const devDependencies = manifest.devDependencies;
+  const existingDevkit = devDependencies !== null && typeof devDependencies === "object" ? devDependencies["@forgeax/engine-devkit"] : void 0;
+  if (existingDevkit !== devkitVersion) {
+    dependencyChanges.push({
+      section: "devDependencies",
+      name: "@forgeax/engine-devkit",
+      ...typeof existingDevkit === "string" ? { from: existingDevkit } : {},
+      to: devkitVersion
+    });
+  }
+  return {
+    ok: true,
+    value: {
+      root: facts.root,
+      version: sdk?.sdkVersion ?? devkitVersion,
+      archiveBacked: sdk !== void 0,
+      dependencyChanges,
+      scriptChanges
+    }
+  };
+}
+async function applyInitPlan(facts, plan, options) {
+  if (options.dryRun === true) return { ok: true, value: plan };
+  const manifest = structuredClone(facts.packageJson);
+  for (const change of plan.dependencyChanges) {
+    const sectionValue = manifest[change.section];
+    const section = sectionValue !== null && typeof sectionValue === "object" ? sectionValue : {};
+    section[change.name] = change.to;
+    manifest[change.section] = section;
+  }
+  const scriptsValue = manifest.scripts;
+  const scripts = scriptsValue !== null && typeof scriptsValue === "object" ? scriptsValue : {};
+  for (const change of plan.scriptChanges) scripts[change.name] = change.to;
+  manifest.scripts = scripts;
+  if (plan.archiveBacked) {
+    manifest.packageManager = "pnpm@10.33.2";
+    const pnpmValue = manifest.pnpm;
+    const pnpm = pnpmValue !== null && typeof pnpmValue === "object" ? pnpmValue : {};
+    manifest.pnpm = {
+      ...pnpm,
+      onlyBuiltDependencies: [
+        "@forgeax/engine-codec",
+        "@forgeax/engine-fbx",
+        "@forgeax/engine-wgpu-wasm",
+        "esbuild"
+      ],
+      supportedArchitectures: {
+        os: ["darwin", "linux", "win32"],
+        cpu: ["x64", "arm64"],
+        libc: ["glibc", "musl"]
+      }
+    };
+  }
+  await writeFile(resolve(facts.root, "package.json"), `${JSON.stringify(manifest, null, 2)}
+`);
+  return { ok: true, value: plan };
+}
+var STANDARD_SCRIPTS, SDK_DEV_DEPENDENCIES;
+var init_init = __esm({
+  "src/init.ts"() {
+    init_package();
+    STANDARD_SCRIPTS = {
+      dev: "forgeax dev",
+      build: "forgeax build",
+      package: "forgeax package",
+      serve: "forgeax serve",
+      preview: "forgeax preview",
+      doctor: "forgeax doctor",
+      test: "forgeax test"
+    };
+    SDK_DEV_DEPENDENCIES = {
+      "@types/node": "20.19.40",
+      "@webgpu/types": "0.1.71",
+      tsx: "4.23.1",
+      typescript: "6.0.3",
+      vitest: "4.1.5"
+    };
+  }
+});
+async function readable(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function findSdkContext() {
+  const configured = process.env.FORGEAX_SDK_ROOT;
+  let cursor = resolve(configured ?? dirname(fileURLToPath(import.meta.url)));
+  for (; ; ) {
+    const manifestPath = resolve(cursor, "sdk-manifest.json");
+    if (await readable(manifestPath)) {
+      const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+      const templates = new Map(
+        manifest.templates.map((template) => [template.id, resolve(cursor, template.root)])
+      );
+      const defaultTemplate = manifest.templates.find((template) => template.default);
+      if (defaultTemplate === void 0) throw new Error("sdk-default-template-missing");
+      return {
+        root: cursor,
+        manifest,
+        store: resolve(cursor, "store", "pnpm"),
+        templates,
+        defaultTemplate: defaultTemplate.id
+      };
+    }
+    const parent = dirname(cursor);
+    if (parent === cursor) return void 0;
+    cursor = parent;
+  }
+}
+var init_sdk = __esm({
+  "src/sdk.ts"() {
+  }
+});
+function slash(path) {
+  return path.split(sep).join("/");
+}
+function contained(parent, child) {
+  const path = relative(parent, child);
+  return path !== "" && path !== ".." && !path.startsWith(`..${sep}`) && !path.startsWith(sep);
+}
+async function pathKind(path) {
+  try {
+    const info = await lstat(path);
+    if (info.isSymbolicLink()) return "symlink";
+    if (info.isDirectory()) return "directory";
+    return "file";
+  } catch (cause) {
+    if (cause !== null && typeof cause === "object" && "code" in cause && cause.code === "ENOENT") {
+      return "missing";
+    }
+    throw cause;
+  }
+}
+async function filesUnder2(root, directory = root) {
+  const files = [];
+  for (const name of (await readdir(directory)).sort()) {
+    const path = resolve(directory, name);
+    const info = await lstat(path);
+    if (info.isSymbolicLink()) throw new Error(`skill-source-symlink: ${path}`);
+    if (info.isDirectory()) files.push(...await filesUnder2(root, path));
+    else if (info.isFile()) files.push(path);
+  }
+  return files;
+}
+async function skillRow(sourceRoot, id) {
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(id)) throw new Error(`skill-id-invalid: ${id}`);
+  const root = resolve(sourceRoot, id);
+  if (await pathKind(root) !== "directory") throw new Error(`skill-source-invalid: ${id}`);
+  if (await pathKind(resolve(root, "SKILL.md")) !== "file") {
+    throw new Error(`skill-entry-missing: ${id}/SKILL.md`);
+  }
+  const files = await filesUnder2(root);
+  return {
+    id,
+    root: `skills/${id}`,
+    fileCount: files.length,
+    byteCount: (await Promise.all(files.map(async (path) => (await readFile(path)).byteLength))).reduce((sum, bytes) => sum + bytes, 0)
+  };
+}
+async function discoverProjectSkills(root) {
+  const sourceRoot = resolve(root, "skills");
+  if (await pathKind(sourceRoot) !== "directory") throw new Error("project-skills-missing");
+  const entries2 = await readdir(sourceRoot, { withFileTypes: true });
+  const ids = entries2.filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
+  if (ids.length === 0) throw new Error("project-skills-empty");
+  return Promise.all(ids.map((id) => skillRow(sourceRoot, id)));
+}
+async function sameFiles(leftRoot, rightRoot) {
+  const left = await filesUnder2(leftRoot);
+  const right = await filesUnder2(rightRoot);
+  const leftNames = left.map((path) => slash(relative(leftRoot, path)));
+  const rightNames = right.map((path) => slash(relative(rightRoot, path)));
+  if (JSON.stringify(leftNames) !== JSON.stringify(rightNames)) return false;
+  for (let index = 0; index < left.length; index += 1) {
+    const leftPath = left[index];
+    const rightPath = right[index];
+    if (leftPath === void 0 || rightPath === void 0) return false;
+    if (!(await readFile(leftPath)).equals(await readFile(rightPath))) return false;
+  }
+  return true;
+}
+async function copySdkSkills(sdk, projectRoot2) {
+  const targetSourceRoot = resolve(projectRoot2, "skills");
+  const copies = [];
+  for (const skill of sdk.manifest.skills) {
+    const source = resolve(sdk.root, skill.root);
+    const destination = resolve(projectRoot2, skill.root);
+    if (!contained(sdk.root, source) || !contained(projectRoot2, destination)) {
+      throw new Error(`sdk-skill-path-invalid: ${skill.id}`);
+    }
+    const actual = await skillRow(resolve(sdk.root, "skills"), skill.id);
+    if (actual.root !== skill.root || actual.fileCount !== skill.fileCount || actual.byteCount !== skill.byteCount) {
+      throw new Error(`sdk-skill-manifest-drift: ${skill.id}`);
+    }
+    const kind = await pathKind(destination);
+    if (kind === "missing") {
+      copies.push({ source, destination });
+    } else if (kind !== "directory" || !await sameFiles(source, destination)) {
+      throw new Error(`project-skill-source-conflict: ${skill.id}`);
+    }
+  }
+  const created = [];
+  try {
+    await mkdir(targetSourceRoot, { recursive: true });
+    for (const { source, destination } of copies) {
+      await cp(source, destination, { recursive: true, errorOnExist: true, force: false });
+      created.push(destination);
+    }
+  } catch (cause) {
+    await Promise.all(created.map((path) => rm(path, { recursive: true, force: true })));
+    throw cause;
+  }
+}
+function expectedLinkTarget(projectRoot2, mountRoot, id) {
+  const mountParent = resolve(projectRoot2, mountRoot);
+  const target = resolve(projectRoot2, "skills", id);
+  return process.platform === "win32" ? target : relative(mountParent, target);
+}
+async function linkMatches(path, target) {
+  if (await pathKind(path) !== "symlink") return false;
+  const actual = await readlink(path);
+  return resolve(dirname(path), actual) === resolve(dirname(path), target);
+}
+function updateManagedGitignore(previous, skillIds) {
+  const block = `${GITIGNORE_BEGIN}
+${skillIds.map((id) => `/${id}`).join("\n")}
+${GITIGNORE_END}`;
+  const begin = previous.indexOf(GITIGNORE_BEGIN);
+  const end = previous.indexOf(GITIGNORE_END);
+  if (begin >= 0 && end >= begin) {
+    const after = end + GITIGNORE_END.length;
+    return `${previous.slice(0, begin)}${block}${previous.slice(after)}`.replace(/^\n+/, "");
+  }
+  return previous.length === 0 ? `${block}
+` : `${previous.replace(/\s*$/, "")}
+
+${block}
+`;
+}
+function removeManagedGitignore(previous) {
+  const begin = previous.indexOf(GITIGNORE_BEGIN);
+  const end = previous.indexOf(GITIGNORE_END);
+  if (begin < 0 || end < begin) return previous;
+  const before = previous.slice(0, begin).trimEnd();
+  const after = previous.slice(end + GITIGNORE_END.length).trimStart();
+  const retained = [before, after].filter((part) => part.length > 0).join("\n");
+  return retained.length === 0 ? "" : `${retained}
+`;
+}
+async function removeEmptyDirectory(path) {
+  try {
+    await rmdir(path);
+  } catch (cause) {
+    if (cause !== null && typeof cause === "object" && "code" in cause && (cause.code === "ENOENT" || cause.code === "ENOTEMPTY" || cause.code === "EEXIST")) {
+      return;
+    }
+    throw cause;
+  }
+}
+async function readOptional(path) {
+  try {
+    return await readFile(path, "utf8");
+  } catch (cause) {
+    if (cause !== null && typeof cause === "object" && "code" in cause && cause.code === "ENOENT") {
+      return void 0;
+    }
+    throw cause;
+  }
+}
+async function readInstallManifest(root) {
+  const value = await readOptional(resolve(root, MANIFEST_PATH));
+  return value === void 0 ? void 0 : JSON.parse(value);
+}
+async function installProjectSkills(root, provenance) {
+  const projectRoot2 = resolve(root);
+  const skills = await discoverProjectSkills(projectRoot2);
+  const ids = skills.map((skill) => skill.id);
+  const priorManifest = await readInstallManifest(projectRoot2);
+  const desiredLinks = PROJECT_SKILL_MOUNT_ROOTS.flatMap(
+    (mountRoot) => ids.map((id) => ({
+      path: resolve(projectRoot2, mountRoot, id),
+      target: expectedLinkTarget(projectRoot2, mountRoot, id)
+    }))
+  );
+  const desiredPaths = new Set(desiredLinks.map((entry) => entry.path));
+  const desiredMountRoots = new Set(PROJECT_SKILL_MOUNT_ROOTS);
+  const retiredMountRoots = (priorManifest?.mounts ?? []).map((mount) => mount.root).filter(
+    (mountRoot) => !desiredMountRoots.has(mountRoot) && RETIRED_PROJECT_SKILL_MOUNT_ROOTS.has(mountRoot)
+  );
+  const staleLinks = (priorManifest?.mounts ?? []).flatMap(
+    (mount) => mount.skills.map((id) => ({
+      path: resolve(projectRoot2, mount.root, id),
+      target: expectedLinkTarget(projectRoot2, mount.root, id)
+    }))
+  ).filter((entry) => !desiredPaths.has(entry.path));
+  for (const entry of desiredLinks) {
+    const kind = await pathKind(entry.path);
+    if (kind !== "missing" && !await linkMatches(entry.path, entry.target)) {
+      throw new Error(`skill-mount-conflict: ${slash(relative(projectRoot2, entry.path))}`);
+    }
+  }
+  for (const entry of staleLinks) {
+    const kind = await pathKind(entry.path);
+    if (kind !== "missing" && !await linkMatches(entry.path, entry.target)) {
+      throw new Error(`skill-stale-mount-conflict: ${slash(relative(projectRoot2, entry.path))}`);
+    }
+  }
+  const ignoreSnapshots = /* @__PURE__ */ new Map();
+  const createdLinks = [];
+  const removedLinks = [];
+  const manifestPath = resolve(projectRoot2, MANIFEST_PATH);
+  const priorManifestText = await readOptional(manifestPath);
+  try {
+    for (const entry of staleLinks) {
+      if (await pathKind(entry.path) === "symlink") {
+        await rm(entry.path);
+        removedLinks.push(entry);
+      }
+    }
+    for (const mountRoot of retiredMountRoots) {
+      const mountParent = resolve(projectRoot2, mountRoot);
+      const ignorePath = resolve(mountParent, ".gitignore");
+      const previous = await readOptional(ignorePath);
+      ignoreSnapshots.set(ignorePath, previous);
+      if (previous !== void 0) {
+        const retained = removeManagedGitignore(previous);
+        if (retained.length === 0) await rm(ignorePath);
+        else await writeFile(ignorePath, retained);
+      }
+      await removeEmptyDirectory(mountParent);
+      await removeEmptyDirectory(dirname(mountParent));
+    }
+    for (const mountRoot of PROJECT_SKILL_MOUNT_ROOTS) {
+      const mountParent = resolve(projectRoot2, mountRoot);
+      await mkdir(mountParent, { recursive: true });
+      const ignorePath = resolve(mountParent, ".gitignore");
+      const previous = await readOptional(ignorePath);
+      ignoreSnapshots.set(ignorePath, previous);
+      await writeFile(ignorePath, updateManagedGitignore(previous ?? "", ids));
+      for (const id of ids) {
+        const path = resolve(mountParent, id);
+        if (await pathKind(path) === "missing") {
+          const target = expectedLinkTarget(projectRoot2, mountRoot, id);
+          await symlink(target, path, process.platform === "win32" ? "junction" : "dir");
+          createdLinks.push(path);
+        }
+      }
+    }
+    const sdkVersion = provenance?.sdkVersion ?? priorManifest?.sdkVersion;
+    const engineCommit = provenance?.engineCommit ?? priorManifest?.engineCommit;
+    const manifest = {
+      schemaVersion: "1.0.0",
+      sourceRoot: "skills",
+      ...sdkVersion === void 0 ? {} : { sdkVersion },
+      ...engineCommit === void 0 ? {} : { engineCommit },
+      skills,
+      mounts: PROJECT_SKILL_MOUNT_ROOTS.map((mountRoot) => ({ root: mountRoot, skills: ids }))
+    };
+    await mkdir(dirname(manifestPath), { recursive: true });
+    await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}
+`);
+  } catch (cause) {
+    await Promise.all(createdLinks.map((path) => rm(path, { force: true })));
+    await Promise.all(
+      removedLinks.map(async ({ path, target }) => {
+        await mkdir(dirname(path), { recursive: true });
+        await symlink(target, path, process.platform === "win32" ? "junction" : "dir");
+      })
+    );
+    await Promise.all(
+      [...ignoreSnapshots].map(async ([path, value]) => {
+        if (value === void 0) await rm(path, { force: true });
+        else {
+          await mkdir(dirname(path), { recursive: true });
+          await writeFile(path, value);
+        }
+      })
+    );
+    if (priorManifestText === void 0) await rm(manifestPath, { force: true });
+    else await writeFile(manifestPath, priorManifestText);
+    throw cause;
+  }
+  return {
+    root: projectRoot2,
+    sourceRoot: resolve(projectRoot2, "skills"),
+    manifest: manifestPath,
+    skills: ids,
+    mountRoots: PROJECT_SKILL_MOUNT_ROOTS
+  };
+}
+async function verifyProjectSkills(root) {
+  const projectRoot2 = resolve(root);
+  const skills = await discoverProjectSkills(projectRoot2);
+  const ids = skills.map((skill) => skill.id);
+  const manifest = await readInstallManifest(projectRoot2);
+  if (manifest === void 0) throw new Error("skill-install-manifest-missing");
+  if (manifest.schemaVersion !== "1.0.0" || manifest.sourceRoot !== "skills" || JSON.stringify(manifest.skills) !== JSON.stringify(skills) || JSON.stringify(manifest.mounts.map((mount) => mount.root)) !== JSON.stringify(PROJECT_SKILL_MOUNT_ROOTS)) {
+    throw new Error("skill-install-manifest-drift");
+  }
+  for (const mountRoot of PROJECT_SKILL_MOUNT_ROOTS) {
+    const declared = manifest.mounts.find((mount) => mount.root === mountRoot);
+    if (declared === void 0 || JSON.stringify(declared.skills) !== JSON.stringify(ids)) {
+      throw new Error(`skill-install-manifest-mount-drift: ${mountRoot}`);
+    }
+    const ignore = await readOptional(resolve(projectRoot2, mountRoot, ".gitignore"));
+    if (ignore === void 0 || updateManagedGitignore(ignore, ids) !== ignore) {
+      throw new Error(`skill-mount-gitignore-drift: ${mountRoot}`);
+    }
+    for (const id of ids) {
+      const path = resolve(projectRoot2, mountRoot, id);
+      const target = expectedLinkTarget(projectRoot2, mountRoot, id);
+      if (!await linkMatches(path, target)) {
+        throw new Error(`skill-mount-drift: ${mountRoot}/${id}`);
+      }
+    }
+  }
+  return {
+    root: projectRoot2,
+    sourceRoot: resolve(projectRoot2, "skills"),
+    manifest: resolve(projectRoot2, MANIFEST_PATH),
+    skills: ids,
+    mountRoots: PROJECT_SKILL_MOUNT_ROOTS
+  };
+}
+async function skillInstallCommand(options = {}) {
+  const facts = await readProjectFacts(options.root);
+  if (!facts.ok) return facts;
+  try {
+    return { ok: true, value: await installProjectSkills(facts.value.root) };
+  } catch (cause) {
+    return { ok: false, error: commandError(cause, "skill-install-failed") };
+  }
+}
+async function skillVerifyCommand(options = {}) {
+  const facts = await readProjectFacts(options.root);
+  if (!facts.ok) return facts;
+  try {
+    return { ok: true, value: await verifyProjectSkills(facts.value.root) };
+  } catch (cause) {
+    return { ok: false, error: commandError(cause, "skill-verify-failed") };
+  }
+}
+var PROJECT_SKILL_MOUNT_ROOTS, RETIRED_PROJECT_SKILL_MOUNT_ROOTS, MANIFEST_PATH, GITIGNORE_BEGIN, GITIGNORE_END;
+var init_skill_install = __esm({
+  "src/skill-install.ts"() {
+    init_project();
+    PROJECT_SKILL_MOUNT_ROOTS = Object.freeze([
+      ".codebuddy/skills",
+      ".cursor/skills",
+      ".agents/skills",
+      ".claude/skills",
+      ".workbuddy/skills",
+      ".forgeax/skills"
+    ]);
+    RETIRED_PROJECT_SKILL_MOUNT_ROOTS = /* @__PURE__ */ new Set([".claude-internal/skills"]);
+    MANIFEST_PATH = ".forgeax/skill-install-manifest.json";
+    GITIGNORE_BEGIN = "# BEGIN FORGEAX MANAGED SKILLS";
+    GITIGNORE_END = "# END FORGEAX MANAGED SKILLS";
+  }
+});
+function isMissingPathError(cause) {
+  return cause !== null && typeof cause === "object" && "code" in cause && cause.code === "ENOENT";
+}
+async function canonicalProspectivePath(path) {
+  let cursor = resolve(path);
+  const suffix = [];
+  for (; ; ) {
+    try {
+      return resolve(await realpath(cursor), ...suffix.reverse());
+    } catch (cause) {
+      if (!isMissingPathError(cause)) throw cause;
+      const parent = dirname(cursor);
+      if (parent === cursor) throw cause;
+      suffix.push(basename(cursor));
+      cursor = parent;
+    }
+  }
+}
+function containsOrEquals(parent, child) {
+  const path = relative(parent, child);
+  return path === "" || path !== ".." && !path.startsWith(`..${sep}`) && !isAbsolute(path);
+}
+function nodeSupported() {
+  const [major = 0, minor = 0] = process.versions.node.split(".").map(Number);
+  return major > 22 || major === 22 && minor >= 13;
+}
+function pnpmSupported(version) {
+  const [major = 0, minor = 0] = version.split(".").map(Number);
+  return major === 10 && minor >= 33;
+}
+async function doctorCommand(options = {}) {
+  const facts = await readProjectFacts(options.root);
+  if (!facts.ok) return facts;
+  let pnpm;
+  try {
+    pnpm = (await execFileAsync("pnpm", ["--version"], { cwd: facts.value.root })).stdout.trim();
+  } catch (cause) {
+    return {
+      ok: false,
+      error: {
+        code: "pnpm-unavailable",
+        expected: "pnpm to be available on PATH",
+        hint: "Install the SDK-supported pnpm version and retry.",
+        detail: { reason: cause instanceof Error ? cause.message : String(cause) }
+      }
+    };
+  }
+  if (!nodeSupported()) {
+    return {
+      ok: false,
+      error: {
+        code: "node-version-unsupported",
+        expected: "Node.js >=22.13.0",
+        hint: "Select a supported Node.js installation and retry.",
+        detail: { actual: process.versions.node }
+      }
+    };
+  }
+  if (!pnpmSupported(pnpm)) {
+    return {
+      ok: false,
+      error: {
+        code: "pnpm-version-unsupported",
+        expected: "pnpm >=10.33.0 <11",
+        hint: "Enable the packageManager-declared pnpm version with Corepack and retry.",
+        detail: { actual: pnpm }
+      }
+    };
+  }
+  const workspaceDependencies = [];
+  for (const section of ["dependencies", "devDependencies"]) {
+    const value = facts.value.packageJson[section];
+    if (value === null || typeof value !== "object") continue;
+    for (const [name, version] of Object.entries(value)) {
+      if (typeof version === "string" && (version.startsWith("workspace:") || version.startsWith("file:"))) {
+        workspaceDependencies.push(name);
+      }
+    }
+  }
+  if (workspaceDependencies.length > 0) {
+    return {
+      ok: false,
+      error: {
+        code: "project-local-dependency",
+        expected: "all external project dependencies to use SDK-resolved exact versions",
+        hint: "Run forgeax init from the unpacked SDK and commit the resulting lockfile.",
+        detail: { dependencies: workspaceDependencies.sort() }
+      }
+    };
+  }
+  return {
+    ok: true,
+    value: {
+      root: facts.value.root,
+      projectId: facts.value.id,
+      node: process.versions.node,
+      pnpm,
+      workspaceDependencies
+    }
+  };
+}
+async function initCommand(options = {}) {
+  const facts = await readProjectFacts(options.root);
+  if (!facts.ok) return facts;
+  try {
+    const sdk = await findSdkContext();
+    const plan = createInitPlan(facts.value, sdk?.manifest);
+    if (!plan.ok) return plan;
+    const applied = await applyInitPlan(facts.value, plan.value, options);
+    if (!applied.ok || options.dryRun === true) return applied;
+    if (sdk !== void 0) {
+      const template = sdk.templates.get(sdk.defaultTemplate);
+      if (template === void 0) throw new Error("sdk-default-template-missing");
+      await copyFile(
+        resolve(template, "pnpm-lock.yaml"),
+        resolve(facts.value.root, "pnpm-lock.yaml")
+      );
+      await copySdkSkills(sdk, facts.value.root);
+      await installProjectSkills(facts.value.root, sdk.manifest);
+    }
+    if (options.install === false) return applied;
+    const installArgs = sdk === void 0 ? ["install", "--frozen-lockfile=false"] : [
+      "install",
+      "--offline",
+      "--frozen-lockfile",
+      "--side-effects-cache=false",
+      "--store-dir",
+      sdk.store
+    ];
+    await execFileAsync("pnpm", installArgs, {
+      cwd: facts.value.root,
+      env: { ...process.env, CI: "true" },
+      maxBuffer: 16 * 1024 * 1024
+    });
+    return applied;
+  } catch (cause) {
+    return { ok: false, error: commandError(cause, "project-init-failed") };
+  }
+}
+async function newCommand(options = {}) {
+  try {
+    const sdk = await findSdkContext();
+    if (sdk === void 0) {
+      return {
+        ok: false,
+        error: {
+          code: "sdk-context-missing",
+          expected: "forgeax new to run from an unpacked ForgeaX SDK",
+          hint: "Run the SDK archive bin/forgeax.mjs entry or set FORGEAX_SDK_ROOT.",
+          detail: {}
+        }
+      };
+    }
+    const root = resolve(options.root ?? process.cwd());
+    if (containsOrEquals(
+      await canonicalProspectivePath(sdk.root),
+      await canonicalProspectivePath(root)
+    )) {
+      return {
+        ok: false,
+        error: {
+          code: "project-target-inside-sdk",
+          expected: "forgeax new target to be outside the unpacked SDK root",
+          hint: "Choose a sibling directory or an absolute path outside the SDK.",
+          detail: { root, sdkRoot: sdk.root }
+        }
+      };
+    }
+    const templateId = options.template ?? sdk.defaultTemplate;
+    const template = sdk.templates.get(templateId);
+    if (template === void 0) {
+      return {
+        ok: false,
+        error: {
+          code: "sdk-template-not-found",
+          expected: "a template id declared by sdk-manifest.json",
+          hint: `Choose one of: ${[...sdk.templates.keys()].sort().join(", ")}.`,
+          detail: { template: templateId }
+        }
+      };
+    }
+    let targetExists = true;
+    let entries2;
+    try {
+      entries2 = await readdir(root);
+    } catch (cause) {
+      if (!isMissingPathError(cause)) throw cause;
+      targetExists = false;
+      entries2 = [];
+    }
+    if (entries2.length > 0) {
+      return {
+        ok: false,
+        error: {
+          code: "project-target-not-empty",
+          expected: "forgeax new target to be absent or empty",
+          hint: "Choose an empty directory so existing files cannot be overwritten.",
+          detail: { root }
+        }
+      };
+    }
+    if (options.dryRun === true) {
+      return {
+        ok: true,
+        value: { root, template: templateId, sdkVersion: sdk.manifest.sdkVersion }
+      };
+    }
+    const parent = dirname(root);
+    await mkdir(parent, { recursive: true });
+    let staging = await mkdtemp(
+      resolve(parent, `.${basename(root)}.forgeax-staging-`)
+    );
+    const committedNames = [];
+    try {
+      for (const name of await readdir(template)) {
+        await cp(resolve(template, name), resolve(staging, name), {
+          recursive: true,
+          errorOnExist: true,
+          force: false
+        });
+      }
+      await copySdkSkills(sdk, staging);
+      await installProjectSkills(staging, sdk.manifest);
+      await execFileAsync(
+        "pnpm",
+        [
+          "install",
+          "--offline",
+          "--frozen-lockfile",
+          "--side-effects-cache=false",
+          "--store-dir",
+          sdk.store
+        ],
+        {
+          cwd: staging,
+          env: { ...process.env, CI: "true" },
+          maxBuffer: 16 * 1024 * 1024
+        }
+      );
+      if (!targetExists) {
+        await rename(staging, root);
+        staging = void 0;
+      } else {
+        for (const name of await readdir(staging)) {
+          await rename(resolve(staging, name), resolve(root, name));
+          committedNames.push(name);
+        }
+        await rm(staging, { recursive: true, force: true });
+        staging = void 0;
+      }
+      return {
+        ok: true,
+        value: { root, template: templateId, sdkVersion: sdk.manifest.sdkVersion }
+      };
+    } catch (cause) {
+      if (staging !== void 0) await rm(staging, { recursive: true, force: true });
+      await Promise.all(
+        committedNames.map((name) => rm(resolve(root, name), { recursive: true, force: true }))
+      );
+      return { ok: false, error: commandError(cause, "project-create-failed") };
+    }
+  } catch (cause) {
+    return { ok: false, error: commandError(cause, "project-create-failed") };
+  }
+}
+var execFileAsync;
+var init_bootstrap_commands = __esm({
+  "src/bootstrap-commands.ts"() {
+    init_init();
+    init_project();
+    init_sdk();
+    init_skill_install();
+    execFileAsync = promisify(execFile);
+  }
+});
+
+// src/plugin-authoring.ts
+var plugin_authoring_exports = {};
+__export(plugin_authoring_exports, {
+  pluginInstallCommand: () => pluginInstallCommand,
+  pluginUninstallCommand: () => pluginUninstallCommand
+});
+async function readManifest(root) {
+  const path = resolve(root, "forge.json");
+  try {
+    const raw = await readFile(path, "utf8");
+    return { ok: true, value: { raw, value: JSON.parse(raw) } };
+  } catch (cause) {
+    return {
+      ok: false,
+      error: {
+        code: "plugin-manifest-unreadable",
+        expected: "a readable forge.json",
+        hint: "Repair the project manifest before changing plugin installation state.",
+        detail: { path, reason: cause instanceof Error ? cause.message : String(cause) }
+      }
+    };
+  }
+}
+async function writeManifest(root, value) {
+  const path = resolve(root, "forge.json");
+  const temporary = resolve(root, `.forgeax-plugin-${process.pid}.tmp`);
+  await writeFile(temporary, `${JSON.stringify(value, null, 2)}
+`);
+  try {
+    await rename(temporary, path);
+  } catch (cause) {
+    await unlink(temporary).catch(() => void 0);
+    throw cause;
+  }
+}
+function allEntries(entries2) {
+  return entries2.flatMap((entry) => [
+    entry,
+    ...entry.group === true ? allEntries(entry.config) : []
+  ]);
+}
+function withoutEntry(entries2, id) {
+  return entries2.flatMap((entry) => {
+    if (entry.id === id) return [];
+    if (entry.group !== true) return [entry];
+    return [
+      {
+        ...entry,
+        config: withoutEntry(entry.config, id)
+      }
+    ];
+  });
+}
+async function mutateDependency(root, action, dependency) {
+  if (dependency === void 0) return;
+  await execFileAsync2("pnpm", [action, dependency], { cwd: root, maxBuffer: 16 * 1024 * 1024 });
+}
+async function pluginInstallCommand(options) {
+  const root = resolve(options.root ?? process.cwd());
+  const manifest = await readManifest(root);
+  if (!manifest.ok) return manifest;
+  const parsed = GameProjectSchema.safeParse(manifest.value.value);
+  if (!parsed.success) {
+    return {
+      ok: false,
+      error: {
+        code: "plugin-manifest-invalid",
+        expected: "forge.json to satisfy GameProjectSchema",
+        hint: "Repair the manifest before installing a plugin.",
+        detail: { issues: parsed.error.issues }
+      }
+    };
+  }
+  const entries2 = parsed.data.plugins ?? [];
+  if (allEntries(entries2).some((entry) => entry.id === options.id)) {
+    return {
+      ok: false,
+      error: {
+        code: "plugin-entry-id-conflict",
+        expected: "a project-unique plugin Entry id",
+        hint: "Choose a stable id not already present in forge.json#plugins.",
+        detail: { id: options.id }
+      }
+    };
+  }
+  const next = {
+    ...parsed.data,
+    plugins: [
+      ...entries2,
+      { id: options.id, name: options.module, realm: options.realm ?? "engine" }
+    ]
+  };
+  if (options.dryRun === true) return { ok: true, value: { root, manifest: next } };
+  try {
+    await writeManifest(root, next);
+    await mutateDependency(root, "add", options.dependency);
+    return { ok: true, value: { root, id: options.id, module: options.module } };
+  } catch (cause) {
+    await writeFile(resolve(root, "forge.json"), manifest.value.raw);
+    return {
+      ok: false,
+      error: {
+        code: "plugin-install-failed",
+        expected: "dependency and forge.json Entry mutations to commit together",
+        hint: "Inspect the package-manager failure; the original forge.json was restored.",
+        detail: { reason: cause instanceof Error ? cause.message : String(cause) }
+      }
+    };
+  }
+}
+async function pluginUninstallCommand(options) {
+  const root = resolve(options.root ?? process.cwd());
+  const manifest = await readManifest(root);
+  if (!manifest.ok) return manifest;
+  const parsed = GameProjectSchema.safeParse(manifest.value.value);
+  if (!parsed.success) {
+    return {
+      ok: false,
+      error: {
+        code: "plugin-manifest-invalid",
+        expected: "forge.json to satisfy GameProjectSchema",
+        hint: "Repair the manifest before uninstalling a plugin.",
+        detail: { issues: parsed.error.issues }
+      }
+    };
+  }
+  const entries2 = parsed.data.plugins ?? [];
+  if (!allEntries(entries2).some((entry) => entry.id === options.id)) {
+    return {
+      ok: false,
+      error: {
+        code: "plugin-entry-missing",
+        expected: "the plugin Entry id to exist",
+        hint: "Inspect forge.json#plugins and pass an installed Entry id.",
+        detail: { id: options.id }
+      }
+    };
+  }
+  const next = { ...parsed.data, plugins: withoutEntry(entries2, options.id) };
+  if (options.dryRun === true) return { ok: true, value: { root, manifest: next } };
+  try {
+    await writeManifest(root, next);
+    await mutateDependency(root, "remove", options.dependency);
+    return { ok: true, value: { root, id: options.id } };
+  } catch (cause) {
+    await writeFile(resolve(root, "forge.json"), manifest.value.raw);
+    return {
+      ok: false,
+      error: {
+        code: "plugin-uninstall-failed",
+        expected: "Entry and dependency removal to commit together",
+        hint: "Inspect the package-manager failure; the original forge.json was restored.",
+        detail: { reason: cause instanceof Error ? cause.message : String(cause) }
+      }
+    };
+  }
+}
+var execFileAsync2;
+var init_plugin_authoring = __esm({
+  "src/plugin-authoring.ts"() {
+    execFileAsync2 = 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"
+      })
+    ),
+    async readArtifact(artifact) {
+      if (artifact.path === void 0) {
+        return {
+          ok: false,
+          error: {
+            code: "artifact-path-missing",
+            expected: "ArtifactRef.path to identify a readable .rhitape file",
+            hint: "Pass the path returned by the capture host together with its digest.",
+            detail: { digest: artifact.digest }
+          }
+        };
+      }
+      try {
+        return { ok: true, value: new Uint8Array(await readFile(artifact.path)) };
+      } catch (cause) {
+        return {
+          ok: false,
+          error: {
+            code: "artifact-read-failed",
+            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)
+            }
+          }
+        };
+      }
+    },
+    async createReplayBackend() {
+      const adapter = await rhi.requestAdapter();
+      if (!adapter.ok) {
+        return {
+          ok: false,
+          error: {
+            code: "replay-backend-unavailable",
+            expected: "a fresh rhi-null adapter",
+            hint: adapter.error.hint,
+            detail: { stage: "adapter", cause: adapter.error.hint }
+          }
+        };
+      }
+      const device = await adapter.value.requestDevice();
+      if (!device.ok) {
+        return {
+          ok: false,
+          error: {
+            code: "replay-backend-unavailable",
+            expected: "a fresh rhi-null device",
+            hint: device.error.hint,
+            detail: { stage: "device", cause: device.error.hint }
+          }
+        };
+      }
+      return { ok: true, value: { device: device.value, createShaderModule } };
+    }
+  };
+}
+var init_cli_context = __esm({
+  "src/rhi-debug/cli-context.ts"() {
+    init_dist3();
+  }
+});
+function createRhiDebugOperationContext(host) {
+  return {
+    async captureFrame(input) {
+      const captured = await host.captureFrame(input);
+      if (!captured.ok) return captured;
+      return ok({
+        kind: RHI_TAPE_ARTIFACT_KIND,
+        digest: captured.value.digest,
+        source: captured.value.source ?? "rhi.capture",
+        ...captured.value.path === void 0 ? {} : { path: captured.value.path },
+        bytes: captured.value.bytes
+      });
+    },
+    readArtifact: host.readArtifact,
+    ...host.createReplayBackend === void 0 ? {} : { createReplayBackend: host.createReplayBackend }
+  };
+}
+function discoverRhiDebugOperations() {
+  return RHI_DEBUG_OPERATION_MANIFEST.operations;
+}
+function renderRhiDebugHelp() {
+  return [
+    "forgeax run <operation>",
+    ...discoverRhiDebugOperations().map((operation) => `  ${operation.name}: ${operation.summary}`),
+    "ArtifactRef schema:",
+    JSON.stringify(RHI_DEBUG_OPERATION_MANIFEST.artifactRefSchema)
+  ].join("\n");
+}
+function recoverRhiDebugError(error) {
+  switch (error.code) {
+    case "capture-unavailable":
+    case "capture-busy":
+    case "capture-snapshot-failed":
+    case "capture-timeout":
+      return `${error.hint}: ${error.detail?.cause ?? "capture failed"}`;
+    case "tape-invalid":
+      return `${error.hint}: ${error.detail?.cause ?? "tape validation failed"}`;
+    case "tape-version-unsupported":
+      return `${error.hint}: found ${error.detail?.foundVersion}, expected ${error.detail?.expectedVersion}`;
+    case "replay-capability-mismatch":
+      return `${error.hint}: ${error.detail?.cause ?? "capability mismatch"}`;
+    case "replay-event-failed":
+      return `${error.hint}: event ${error.detail?.eventIndex} ${error.detail?.kind} at ${error.detail?.stage}`;
+    case "replay-position-invalid":
+      return `${error.hint}: requested ${error.detail?.requested}, available ${error.detail?.available}`;
+    case "readback-failed":
+      return `${error.hint}: ${error.detail?.cause ?? "readback failed"}`;
+    case "readback-unsupported":
+      return `${error.hint}: ${error.detail?.reason ?? "readback is unsupported"}`;
+  }
+}
+function coreError(error) {
+  return {
+    code: error.code,
+    expected: error.expected,
+    hint: recoverRhiDebugError(error),
+    detail: error.detail === void 0 ? {} : Object.fromEntries(Object.entries(error.detail))
+  };
+}
+function operationError(code, expected, hint, detail = {}) {
+  return { ok: false, error: { code, expected, hint, detail } };
+}
+function validateArtifactRef(value) {
+  if (value === null || typeof value !== "object") {
+    return operationError(
+      "artifact-ref-invalid",
+      "an ArtifactRef object",
+      "Pass the ArtifactRef returned by rhi.capture unchanged."
+    );
+  }
+  const candidate = value;
+  if (candidate.kind !== RHI_TAPE_ARTIFACT_KIND) {
+    return operationError(
+      "artifact-kind-invalid",
+      `ArtifactRef.kind to equal ${RHI_TAPE_ARTIFACT_KIND}`,
+      "Capture a new RHI tape and pass its ArtifactRef unchanged.",
+      { kind: candidate.kind ?? null }
+    );
+  }
+  if (typeof candidate.digest !== "string" || candidate.digest.length === 0) {
+    return operationError(
+      "artifact-digest-invalid",
+      "ArtifactRef.digest to be a non-empty digest",
+      "Use the digest returned with the captured tape."
+    );
+  }
+  if (typeof candidate.source !== "string" || candidate.source.length === 0) {
+    return operationError(
+      "artifact-source-invalid",
+      "ArtifactRef.source to identify the producing operation",
+      "Use the complete ArtifactRef returned by rhi.capture."
+    );
+  }
+  return {
+    ok: true,
+    value: {
+      kind: RHI_TAPE_ARTIFACT_KIND,
+      digest: candidate.digest,
+      source: candidate.source,
+      ...typeof candidate.path === "string" ? { path: candidate.path } : {}
+    }
+  };
+}
+async function readTape(artifact, context) {
+  const validated = validateArtifactRef(artifact);
+  if (!validated.ok) return validated;
+  return context.readArtifact(validated.value);
+}
+async function runRhiDebugOperation(name, input, context) {
+  switch (name) {
+    case "rhi.capture": {
+      const capture = await context.captureFrame(input);
+      if (!capture.ok) return { ok: false, error: coreError(capture.error) };
+      const artifact = validateArtifactRef(capture.value);
+      if (!artifact.ok) return artifact;
+      return { ok: true, value: artifact.value };
+    }
+    case "rhi.summary": {
+      const summaryInput = input;
+      const bytes = await readTape(summaryInput.artifact, context);
+      if (!bytes.ok) return bytes;
+      const decoded = decodeTape(bytes.value);
+      if (!decoded.ok) return { ok: false, error: coreError(decoded.error) };
+      const artifact = validateArtifactRef(summaryInput.artifact);
+      if (!artifact.ok) return artifact;
+      return {
+        ok: true,
+        value: { artifact: artifact.value, model: buildFrameModel(decoded.value) }
+      };
+    }
+    case "rhi.inspect": {
+      const inspectInput = input;
+      if (!Number.isInteger(inspectInput.workIndex) || inspectInput.workIndex < 0) {
+        return operationError(
+          "work-index-invalid",
+          "workIndex to be a non-negative integer",
+          "Choose workIndex from the FrameModel returned by rhi.summary.",
+          { workIndex: inspectInput.workIndex }
+        );
+      }
+      const bytes = await readTape(inspectInput.artifact, context);
+      if (!bytes.ok) return bytes;
+      const decoded = decodeTape(bytes.value);
+      if (!decoded.ok) return { ok: false, error: coreError(decoded.error) };
+      if (context.createReplayBackend === void 0) {
+        return operationError(
+          "replay-backend-unavailable",
+          "a fresh ReplayBackend factory",
+          "Provide a fresh device and shader factory before running rhi.inspect."
+        );
+      }
+      const backend = await context.createReplayBackend();
+      if (!backend.ok) return backend;
+      const opened = await openReplay(decoded.value, backend.value);
+      if (!opened.ok) return { ok: false, error: coreError(opened.error) };
+      try {
+        const inspection = await opened.value.inspectWork(
+          inspectInput.workIndex,
+          inspectInput.fields
+        );
+        if (!inspection.ok) return { ok: false, error: coreError(inspection.error) };
+        const artifact = validateArtifactRef(inspectInput.artifact);
+        if (!artifact.ok) return artifact;
+        return { ok: true, value: { artifact: artifact.value, inspection: inspection.value } };
+      } finally {
+        await opened.value.dispose();
+      }
+    }
+  }
+}
+var RHI_TAPE_ARTIFACT_KIND, artifactRefSchema, summaryOutputSchema, inspectOutputSchema, RHI_DEBUG_OPERATION_MANIFEST;
+var init_operations = __esm({
+  "src/rhi-debug/operations.ts"() {
+    RHI_TAPE_ARTIFACT_KIND = "rhi-tape";
+    artifactRefSchema = {
+      type: "object",
+      properties: {
+        kind: { type: "string", enum: [RHI_TAPE_ARTIFACT_KIND] },
+        digest: { type: "string" },
+        source: { type: "string" },
+        path: { type: "string" }
+      },
+      required: ["kind", "digest", "source"],
+      additionalProperties: false
+    };
+    summaryOutputSchema = {
+      type: "object",
+      properties: {
+        artifact: artifactRefSchema,
+        model: { type: "object", additionalProperties: true }
+      },
+      required: ["artifact", "model"],
+      additionalProperties: false
+    };
+    inspectOutputSchema = {
+      type: "object",
+      properties: {
+        artifact: artifactRefSchema,
+        inspection: { type: "object", additionalProperties: true }
+      },
+      required: ["artifact", "inspection"],
+      additionalProperties: false
+    };
+    RHI_DEBUG_OPERATION_MANIFEST = {
+      schemaVersion: "1.0.0",
+      artifactRefSchema,
+      operations: [
+        {
+          name: "rhi.capture",
+          summary: "Capture the next frame and return one rhi-tape ArtifactRef.",
+          inputSchema: {
+            type: "object",
+            properties: {},
+            additionalProperties: false
+          },
+          outputSchema: artifactRefSchema,
+          recoveryCodes: [
+            "capture-unavailable",
+            "capture-busy",
+            "capture-snapshot-failed",
+            "capture-timeout"
+          ]
+        },
+        {
+          name: "rhi.summary",
+          summary: "Strictly decode one ArtifactRef and return its CPU FrameModel.",
+          inputSchema: {
+            type: "object",
+            properties: { artifact: artifactRefSchema },
+            required: ["artifact"],
+            additionalProperties: false
+          },
+          outputSchema: summaryOutputSchema,
+          recoveryCodes: ["tape-invalid", "tape-version-unsupported"]
+        },
+        {
+          name: "rhi.inspect",
+          summary: "Replay one ArtifactRef on a fresh backend and inspect a workIndex.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              artifact: artifactRefSchema,
+              workIndex: { type: "integer", minimum: 0 },
+              fields: { type: "array", items: { type: "string" } }
+            },
+            required: ["artifact", "workIndex"],
+            additionalProperties: false
+          },
+          outputSchema: inspectOutputSchema,
+          recoveryCodes: [
+            "tape-invalid",
+            "tape-version-unsupported",
+            "replay-capability-mismatch",
+            "replay-event-failed",
+            "replay-position-invalid",
+            "readback-failed",
+            "readback-unsupported"
+          ]
+        }
+      ]
+    };
+  }
+});
+async function packageVersion() {
+  const manifest = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
+  if (typeof manifest.version !== "string" || manifest.version.length === 0) {
+    throw new Error("sdk-installer-version-missing");
+  }
+  return manifest.version;
+}
+async function sdkInstallCommand(options) {
+  const root = resolve(options.root);
+  let targetExists = true;
+  let entries2;
+  try {
+    entries2 = await readdir(root);
+  } catch (cause) {
+    if (cause === null || typeof cause !== "object" || !("code" in cause) || cause.code !== "ENOENT") {
+      return { ok: false, error: commandError(cause, "sdk-install-failed") };
+    }
+    targetExists = false;
+    entries2 = [];
+  }
+  if (entries2.length > 0) {
+    return {
+      ok: false,
+      error: {
+        code: "sdk-target-not-empty",
+        expected: "the SDK install target to be absent or empty",
+        hint: "Choose an empty versioned SDK directory so existing files cannot be overwritten.",
+        detail: { root }
+      }
+    };
+  }
+  const version = options.version ?? await packageVersion();
+  const parent = dirname(root);
+  await mkdir(parent, { recursive: true });
+  let staging;
+  let download;
+  try {
+    staging = await mkdtemp(resolve(parent, `.${basename(root)}.forgeax-sdk-staging-`));
+    download = await mkdtemp(resolve(parent, `.${basename(root)}.forgeax-sdk-download-`));
+    await execFileAsync3(
+      process.env.FORGEAX_NPM_CLIENT ?? "npm",
+      [
+        "install",
+        "--prefix",
+        download,
+        "--ignore-scripts",
+        "--no-package-lock",
+        "--no-save",
+        "--fund=false",
+        "--audit=false",
+        `@forgeax/engine-sdk@${version}`
+      ],
+      { env: { ...process.env, CI: "true" }, maxBuffer: 16 * 1024 * 1024 }
+    );
+    const carrier = resolve(download, "node_modules", "@forgeax", "engine-sdk", "sdk");
+    const manifest = JSON.parse(await readFile(resolve(carrier, "sdk-manifest.json"), "utf8"));
+    if (manifest.sdkVersion !== version) throw new Error("sdk-carrier-version-mismatch");
+    for (const name of await readdir(carrier)) {
+      await cp(resolve(carrier, name), resolve(staging, name), {
+        recursive: true,
+        errorOnExist: true,
+        force: false
+      });
+    }
+    if (!targetExists) {
+      await rename(staging, root);
+      staging = void 0;
+    } else {
+      for (const name of await readdir(staging)) {
+        await rename(resolve(staging, name), resolve(root, name));
+      }
+    }
+    return { ok: true, value: { root, sdkVersion: version, source: "@forgeax/engine-sdk" } };
+  } catch (cause) {
+    return { ok: false, error: commandError(cause, "sdk-install-failed") };
+  } finally {
+    if (staging !== void 0) await rm(staging, { recursive: true, force: true });
+    if (download !== void 0) await rm(download, { recursive: true, force: true });
+  }
+}
+var execFileAsync3;
+var init_sdk_install = __esm({
+  "src/sdk-install.ts"() {
+    init_project();
+    execFileAsync3 = promisify(execFile);
+  }
+});
+async function shaderCheckCommand(options = {}) {
+  const facts = await readProjectFacts(options.root);
+  if (!facts.ok) return facts;
+  const target = options.path === void 0 ? void 0 : resolve(facts.value.root, options.path);
+  if (target !== void 0) {
+    try {
+      await readFile(target);
+    } catch (cause) {
+      return { ok: false, error: commandError(cause, "shader-source-unreadable") };
+    }
+  }
+  const temporary = await mkdtemp(resolve(tmpdir(), "forgeax-shader-check-"));
+  const previous = process.cwd();
+  try {
+    process.chdir(facts.value.root);
+    const config = await createViteConfig(facts.value, "build");
+    await build({
+      ...config,
+      build: { ...config.build, outDir: temporary, emptyOutDir: true, write: true }
+    });
+    return { ok: true, value: { root: facts.value.root, path: target ?? null } };
+  } catch (cause) {
+    return { ok: false, error: commandError(cause, "shader-check-failed") };
+  } finally {
+    process.chdir(previous);
+    await rm(temporary, { recursive: true, force: true });
+  }
+}
+var init_shader_check = __esm({
+  "src/shader-check.ts"() {
+    init_host();
+    init_project();
+  }
+});
+
+// src/commands.ts
+var commands_exports = {};
+__export(commands_exports, {
+  RHI_DEBUG_OPERATION_MANIFEST: () => RHI_DEBUG_OPERATION_MANIFEST,
+  assetAddCommand: () => assetAddCommand,
+  assetInspectCommand: () => assetInspectCommand,
+  assetListCommand: () => assetListCommand,
+  assetVerifyCommand: () => assetVerifyCommand,
+  buildCommand: () => buildCommand,
+  createCliRhiDebugOperationContext: () => createCliRhiDebugOperationContext,
+  createRhiDebugOperationContext: () => createRhiDebugOperationContext,
+  devCommand: () => devCommand,
+  discoverRhiDebugOperations: () => discoverRhiDebugOperations,
+  doctorCommand: () => doctorCommand,
+  initCommand: () => initCommand,
+  newCommand: () => newCommand,
+  packageCommand: () => packageCommand,
+  pluginInstallCommand: () => pluginInstallCommand,
+  pluginUninstallCommand: () => pluginUninstallCommand,
+  previewCommand: () => previewCommand,
+  recoverRhiDebugError: () => recoverRhiDebugError,
+  renderRhiDebugHelp: () => renderRhiDebugHelp,
+  runRhiDebugCommand: () => runRhiDebugCommand,
+  runRhiDebugOperation: () => runRhiDebugOperation,
+  sdkInstallCommand: () => sdkInstallCommand,
+  shaderCheckCommand: () => shaderCheckCommand,
+  skillInstallCommand: () => skillInstallCommand,
+  skillVerifyCommand: () => skillVerifyCommand,
+  testCommand: () => testCommand
+});
+function runRhiDebugCommand(name, input, context) {
+  return runRhiDebugOperation(name, input, context);
+}
+async function buildCommand(options = {}) {
+  const facts = await readProjectFacts(options.root);
+  if (!facts.ok) return facts;
+  const previous = process.cwd();
+  const base = options.base ?? "/";
+  const outDir = resolve(facts.value.root, options.outDir ?? "dist");
+  try {
+    process.chdir(facts.value.root);
+    await build(await createViteConfig(facts.value, "build", base, { outDir }));
+    return { ok: true, value: await writeDistManifest(facts.value, base, outDir) };
+  } catch (cause) {
+    return { ok: false, error: commandError(cause, "game-build-failed") };
+  } finally {
+    process.chdir(previous);
+  }
+}
+function releaseSlug(name) {
+  const slug = name.normalize("NFKD").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return slug.length > 0 ? slug : "forgeax-game";
+}
+async function packageCommand(options = {}) {
+  const facts = await readProjectFacts(options.root);
+  if (!facts.ok) return facts;
+  const built = await buildCommand({
+    root: facts.value.root,
+    base: "./",
+    ...options.json === void 0 ? {} : { json: options.json }
+  });
+  if (!built.ok) return built;
+  const distRoot = resolve(facts.value.root, "dist");
+  const verified = await verifyDist(distRoot);
+  if (!verified.ok) return verified;
+  const archive = resolve(
+    facts.value.root,
+    options.output ?? `release/${releaseSlug(facts.value.name)}-web.zip`
+  );
+  const archiveRelativeToDist = relative(distRoot, archive);
+  if (archiveRelativeToDist === "" || !archiveRelativeToDist.startsWith("..")) {
+    return {
+      ok: false,
+      error: {
+        code: "release-output-inside-dist",
+        expected: "the release archive to live outside the derived dist directory",
+        hint: "Use --output release/<game>-web.zip or another path outside dist.",
+        detail: { archive, distRoot }
+      }
+    };
+  }
+  const temporaryArchive = `${archive}.partial-${process.pid}`;
+  const checksumPath = `${archive}.sha256`;
+  const temporaryChecksum = `${checksumPath}.partial-${process.pid}`;
+  try {
+    const paths = [
+      ...verified.value.artifacts.map((artifact) => artifact.path),
+      "forgeax-dist.json"
+    ];
+    const entries2 = await Promise.all(
+      paths.map(async (path) => ({ path, bytes: await readFile(resolve(distRoot, path)) }))
+    );
+    const bytes = createZip(entries2);
+    const sha256 = createHash("sha256").update(bytes).digest("hex");
+    const manifestBytes = await readFile(resolve(distRoot, "forgeax-dist.json"));
+    await mkdir(dirname(archive), { recursive: true });
+    await writeFile(temporaryArchive, bytes);
+    await writeFile(temporaryChecksum, `${sha256}  ${basename(archive)}
+`);
+    await rename(temporaryChecksum, checksumPath);
+    await rename(temporaryArchive, archive);
+    return {
+      ok: true,
+      value: {
+        schemaVersion: "1.0.0",
+        format: "forgeax-web-game",
+        target: "web",
+        project: verified.value.project,
+        base: verified.value.base,
+        engine: {
+          delivery: "bundled-runtime",
+          wasm: verified.value.artifacts.some((artifact) => artifact.path.endsWith(".wasm"))
+        },
+        archive: { path: archive, bytes: bytes.byteLength, sha256 },
+        checksumPath,
+        distManifestSha256: createHash("sha256").update(manifestBytes).digest("hex"),
+        run: {
+          local: "forgeax preview",
+          shared: "upload the ZIP to an HTTPS static or HTML-game host and share its URL"
+        }
+      }
+    };
+  } catch (cause) {
+    return { ok: false, error: commandError(cause, "game-package-failed") };
+  } finally {
+    await Promise.all([
+      rm(temporaryArchive, { force: true }),
+      rm(temporaryChecksum, { force: true })
+    ]);
+  }
+}
+async function devCommand(options = {}) {
+  const facts = await readProjectFacts(options.root);
+  if (!facts.ok) return facts;
+  const previous = process.cwd();
+  try {
+    process.chdir(facts.value.root);
+    const server = await createServer(await createViteConfig(facts.value, "serve"));
+    await server.listen();
+    if (options.json !== true) server.printUrls();
+    return { ok: true, value: { root: facts.value.root, urls: server.resolvedUrls } };
+  } catch (cause) {
+    process.chdir(previous);
+    return { ok: false, error: commandError(cause, "dev-server-failed") };
+  }
+}
+async function previewCommand(options = {}) {
+  const root = resolve(options.root ?? process.cwd());
+  const verified = await verifyDist(resolve(root, "dist"));
+  if (!verified.ok) return verified;
+  try {
+    const server = await preview({
+      root,
+      configFile: false,
+      base: verified.value.base,
+      preview: { open: false, port: 0, strictPort: false },
+      build: { outDir: resolve(root, "dist") }
+    });
+    if (options.json !== true) server.printUrls();
+    return { ok: true, value: { root, urls: server.resolvedUrls } };
+  } catch (cause) {
+    return { ok: false, error: commandError(cause, "preview-server-failed") };
+  }
+}
+async function testCommand(options = {}) {
+  const facts = await readProjectFacts(options.root);
+  if (!facts.ok) return facts;
+  try {
+    const context = await startVitest("test", [], {
+      root: facts.value.root,
+      run: true,
+      watch: false,
+      passWithNoTests: false
+    });
+    if (context === void 0) {
+      return {
+        ok: false,
+        error: {
+          code: "test-runner-unavailable",
+          expected: "Vitest to create a project test context",
+          hint: "Inspect the project test configuration.",
+          detail: { root: facts.value.root }
+        }
+      };
+    }
+    const failed = context.state.getFiles().filter((file) => file.result?.state === "fail");
+    await context.close();
+    if (failed.length > 0) {
+      return {
+        ok: false,
+        error: {
+          code: "project-tests-failed",
+          expected: "all project tests to pass",
+          hint: "Repair the failing game test before building a release.",
+          detail: { files: failed.map((file) => file.filepath) }
+        }
+      };
+    }
+    return { ok: true, value: { root: facts.value.root } };
+  } catch (cause) {
+    return { ok: false, error: commandError(cause, "project-tests-failed") };
+  }
+}
+var init_commands = __esm({
+  "src/commands.ts"() {
+    init_archive();
+    init_dist();
+    init_host();
+    init_project();
+    init_assets();
+    init_bootstrap_commands();
+    init_plugin_authoring();
+    init_cli_context();
+    init_operations();
+    init_sdk_install();
+    init_shader_check();
+    init_skill_install();
+    init_operations();
+  }
+});
+var nativePreviewPlugins, nativePreviewTools, nativePreviewDescriptors;
+var init_preview_catalog = __esm({
+  "src/tools/preview-catalog.ts"() {
+    nativePreviewPlugins = [
+      ["@forgeax/engine-preview/material", materialPreviewPlugin],
+      ["@forgeax/engine-preview/mesh", meshPreviewPlugin],
+      ["@forgeax/engine-preview/vfx", vfxPreviewPlugin],
+      ["@forgeax/engine-preview/texture", texturePreviewPlugin]
+    ];
+    nativePreviewTools = nativePreviewPlugins.flatMap(([, plugin]) => plugin.tools);
+    nativePreviewDescriptors = nativePreviewTools.map(
+      ({ descriptor }) => descriptor
+    );
+  }
+});
+function projectDescriptor(descriptor) {
+  return {
+    id: descriptor.id,
+    title: descriptor.title,
+    summary: descriptor.summary,
+    realm: descriptor.realm,
+    evidence: [...descriptor.evidence],
+    ...descriptor.argsSchema.describe === void 0 ? {} : { argsSchema: descriptor.argsSchema.describe },
+    ...descriptor.resultSchema.describe === void 0 ? {} : { resultSchema: descriptor.resultSchema.describe }
+  };
+}
+function missingRealmOwner(descriptor, id) {
+  const realm = descriptor?.realm ?? "build";
+  return {
+    outcome: "failed",
+    failure: capabilityUnavailableError(`realm:${realm}:tool:${id}`, realm),
+    artifacts: []
+  };
+}
+function createRealmDispatch(contributions, owners) {
+  const contributionById = new Map(
+    contributions.map((contribution) => [contribution.descriptor.id, contribution])
+  );
+  const ownerByRealm = /* @__PURE__ */ new Map();
+  for (const owner of owners) {
+    if (ownerByRealm.has(owner.realm)) throw new TypeError(`Duplicate realm owner: ${owner.realm}`);
+    const invalid = owner.contributions.find(
+      (contribution) => contribution.descriptor.realm !== owner.realm
+    );
+    if (invalid !== void 0) {
+      throw new TypeError(
+        `Tool ${invalid.descriptor.id} declares ${invalid.descriptor.realm} but owner is ${owner.realm}`
+      );
+    }
+    ownerByRealm.set(owner.realm, createToolRuntime(owner.contributions));
+  }
+  return {
+    list: () => contributions.map((contribution) => contribution.descriptor),
+    describe: (id) => contributionById.get(id)?.descriptor,
+    async run(id, args2, options = {}) {
+      const contribution = contributionById.get(id);
+      if (contribution === void 0)
+        return missingRealmOwner(void 0, id);
+      const owner = ownerByRealm.get(contribution.descriptor.realm);
+      if (owner === void 0) return missingRealmOwner(contribution.descriptor, id);
+      const bound = owner.get(id);
+      if (bound === void 0) return missingRealmOwner(contribution.descriptor, id);
+      return await owner.run(bound, args2, options).terminal;
+    }
+  };
+}
+function requiredAuthorityDigest(authority) {
+  if (authority.authorityDigest === void 0) {
+    throw new TypeError("Catalog materialization requires an authority digest");
+  }
+  return authority.authorityDigest;
+}
+function digestCatalog(authorityDigest, entries2) {
+  return `sha256:${createHash("sha256").update(JSON.stringify({ authorityDigest, entries: entries2 })).digest("hex")}`;
+}
+function digestAuthority(bytes) {
+  const hash = createHash("sha256");
+  for (const value of bytes) hash.update(value);
+  return `sha256:${hash.digest("hex")}`;
+}
+function projectionValid(catalog, authorityDigest, descriptors = defaultToolDescriptors) {
+  if (catalog === null || typeof catalog !== "object") return false;
+  const value = catalog;
+  const expectedEntries = descriptors.map(projectDescriptor).sort((left, right) => left.id.localeCompare(right.id));
+  return value.schemaVersion === "1.0.0" && value.authorityDigest === authorityDigest && Array.isArray(value.entries) && JSON.stringify(value.entries) === JSON.stringify(expectedEntries) && value.digest === digestCatalog(authorityDigest, value.entries);
+}
+function createProjectToolCatalogAuthority(rootInput, descriptors = defaultToolDescriptors) {
+  const root = resolve(rootInput);
+  return {
+    root,
+    projectionPath: resolve(root, ".forgeax/generated/tool-catalog.json"),
+    async read() {
+      const [forge, packageJson] = await Promise.all([
+        readFile(resolve(root, "forge.json")),
+        readFile(resolve(root, "package.json"))
+      ]);
+      return { authorityDigest: digestAuthority([forge, packageJson]), descriptors };
+    }
+  };
+}
+async function loadToolCatalog(authority, descriptors = defaultToolDescriptors) {
+  const read = authority.read;
+  if (read === void 0) {
+    if (authority.authorityDigest === void 0) {
+      return {
+        ok: false,
+        error: {
+          code: "tool-catalog-authority-unreadable",
+          expected: "an injectable project authority reader",
+          hint: "Create a project authority from a real project root before listing tools.",
+          detail: { reason: "authority reader is missing" }
+        }
+      };
+    }
+    return { ok: true, value: materializeToolDescriptorCatalog(descriptors, authority) };
+  }
+  let snapshot;
+  try {
+    snapshot = await read();
+  } catch (cause) {
+    return {
+      ok: false,
+      error: {
+        code: "tool-catalog-authority-unreadable",
+        expected: "project authority files to be readable",
+        hint: "Repair forge.json and package.json, then retry catalog rebuild.",
+        detail: { reason: cause instanceof Error ? cause.message : String(cause) }
+      }
+    };
+  }
+  const projectionPath = authority.projectionPath;
+  if (projectionPath !== void 0) {
+    try {
+      const current = JSON.parse(await readFile(projectionPath, "utf8"));
+      if (projectionValid(current, snapshot.authorityDigest, snapshot.descriptors)) {
+        return { ok: true, value: current };
+      }
+    } catch {
+    }
+  }
+  const catalog = materializeToolDescriptorCatalog(snapshot.descriptors, {
+    authorityDigest: snapshot.authorityDigest
+  });
+  if (projectionPath !== void 0) {
+    try {
+      await mkdir(resolve(projectionPath, ".."), { recursive: true });
+      await writeFile(projectionPath, `${JSON.stringify(catalog, null, 2)}
+`, "utf8");
+    } catch (cause) {
+      return {
+        ok: false,
+        error: {
+          code: "tool-catalog-projection-invalid",
+          expected: "the generated catalog projection to be writable",
+          hint: "Restore write access to .forgeax/generated and retry cold rebuild.",
+          detail: { reason: cause instanceof Error ? cause.message : String(cause) }
+        }
+      };
+    }
+  }
+  return { ok: true, value: catalog };
+}
+function materializeToolDescriptorCatalog(descriptors, authority) {
+  const entries2 = descriptors.map(projectDescriptor).sort((left, right) => left.id.localeCompare(right.id));
+  const authorityDigest = requiredAuthorityDigest(authority);
+  return {
+    schemaVersion: "1.0.0",
+    authorityDigest,
+    digest: digestCatalog(authorityDigest, entries2),
+    entries: entries2
+  };
+}
+function listTools(catalog) {
+  return catalog.entries;
+}
+function describeTool(catalog, id) {
+  return catalog.entries.find((entry) => entry.id === id);
+}
+var buildArgsSchema, pluginInstallArgsSchema, previewArgsSchema, resultSchema, offlineAnalysisArgsSchema, projectBuildDescriptor, authorPluginInstallDescriptor, previewRunDescriptor, previewOfflineAnalysisDescriptor, defaultToolDescriptors;
+var init_catalog = __esm({
+  "src/tools/catalog.ts"() {
+    init_preview_catalog();
+    buildArgsSchema = {
+      parse(value) {
+        if (value === null || typeof value !== "object")
+          return { ok: false, error: "expected an options object" };
+        return { ok: true, value };
+      },
+      describe: '{"type":"object","properties":{"root":{"type":"string"},"base":{"type":"string"}}}'
+    };
+    pluginInstallArgsSchema = {
+      parse(value) {
+        if (value === null || typeof value !== "object")
+          return { ok: false, error: "expected a plugin install options object" };
+        return { ok: true, value };
+      },
+      describe: '{"type":"object","required":["id","module"],"properties":{"id":{"type":"string"},"module":{"type":"string"},"realm":{"enum":["host","engine","build"]},"dependency":{"type":"string"},"root":{"type":"string"}}}'
+    };
+    previewArgsSchema = {
+      parse(value) {
+        if (value === null || typeof value !== "object")
+          return { ok: false, error: "expected a preview request object" };
+        const request = value;
+        if (request.recipe === void 0 || typeof request.recipe !== "object")
+          return { ok: false, error: "expected recipe in the preview request" };
+        return { ok: true, value };
+      },
+      describe: '{"type":"object","required":["recipe"],"properties":{"recipe":{"type":"object","required":["snapshot"],"properties":{"snapshot":{"type":"object","required":["revision","digest"]},"backend":{"const":"webgpu"},"presentation":{"enum":["hidden","visible"]},"viewport":{"type":"object","properties":{"width":{"type":"integer","minimum":1},"height":{"type":"integer","minimum":1}}},"actions":{"type":"array","items":{"type":"object","required":["frame","name"],"properties":{"frame":{"type":"integer","minimum":0},"name":{"type":"string","minLength":1},"value":{}}}},"deltaSeconds":{"type":"number","minimum":0},"frames":{"type":"integer","minimum":1}}}}}'
+    };
+    resultSchema = {
+      parse: (value) => ({ ok: true, value }),
+      describe: '{"type":"object"}'
+    };
+    offlineAnalysisArgsSchema = {
+      parse(value) {
+        if (value === null || typeof value !== "object")
+          return { ok: false, error: "expected an offline analysis request object" };
+        const request = value;
+        if (request.manifest === void 0 || typeof request.manifest !== "object")
+          return { ok: false, error: "expected manifest in the offline analysis request" };
+        return { ok: true, value };
+      },
+      describe: '{"type":"object","required":["manifest"],"properties":{"manifest":{"type":"object","required":["schemaVersion","identity","artifacts"]},"required":{"type":"array","items":{"enum":["rhi-tape","png","profile-capture"]}}}}'
+    };
+    projectBuildDescriptor = {
+      id: "project.build",
+      title: "Build project",
+      summary: "Builds the project through the existing Vite and Pack authorities.",
+      realm: "build",
+      argsSchema: buildArgsSchema,
+      resultSchema,
+      evidence: []
+    };
+    authorPluginInstallDescriptor = {
+      id: "author.plugin-install",
+      title: "Install project plugin",
+      summary: "Writes one plugin Entry through the project authoring authority.",
+      realm: "build",
+      argsSchema: pluginInstallArgsSchema,
+      resultSchema,
+      evidence: []
+    };
+    previewRunDescriptor = {
+      id: "preview.run",
+      title: "Run hidden WebGPU preview",
+      summary: "Runs one fixed real-WebGPU preview recipe and returns structured evidence refs.",
+      realm: "host",
+      argsSchema: previewArgsSchema,
+      resultSchema,
+      evidence: ["rhi-tape", "png", "profile-capture"]
+    };
+    previewOfflineAnalysisDescriptor = {
+      id: "preview.offline-analysis",
+      title: "Analyze preview artifacts",
+      summary: "Validates owner-separated evidence identity before offline consumption.",
+      realm: "build",
+      argsSchema: offlineAnalysisArgsSchema,
+      resultSchema,
+      evidence: ["rhi-tape", "png", "profile-capture"]
+    };
+    defaultToolDescriptors = [
+      projectBuildDescriptor,
+      authorPluginInstallDescriptor,
+      ...nativePreviewDescriptors
+    ];
+  }
+});
+function retiredPreviewTool() {
+  return {
+    outcome: "failed",
+    failure: domainFailureError(
+      retiredPreviewOperationFailure.code,
+      retiredPreviewOperationFailure.expected,
+      retiredPreviewOperationFailure.hint,
+      retiredPreviewOperationFailure.detail
+    ),
+    artifacts: []
+  };
+}
+var retiredPreviewOperationFailure;
+var init_preview_migration = __esm({
+  "src/tools/preview-migration.ts"() {
+    retiredPreviewOperationFailure = {
+      code: "preview-operation-migrated",
+      expected: "a domain-specific preview contribution selected from the project catalog",
+      hint: "Use material.preview, mesh.preview, vfx.preview, or texture.preview with a Project GUID.",
+      detail: {
+        operation: "preview.run",
+        replacements: ["material.preview", "mesh.preview", "vfx.preview", "texture.preview"]
+      }
+    };
+  }
+});
+
+// src/tools/project-tools.ts
+var project_tools_exports = {};
+__export(project_tools_exports, {
+  discoverProjectTools: () => discoverProjectTools,
+  runProjectTool: () => runProjectTool
+});
+function projectLeaves(entries2, inheritedRealm = "engine") {
+  const leaves = [];
+  for (const entry of entries2) {
+    const realm = entry.realm ?? inheritedRealm;
+    if (entry.disabled === true) continue;
+    if (entry.group === true) {
+      leaves.push(...projectLeaves(entry.config, realm));
+      continue;
+    }
+    if (!entry.name.startsWith("cordis:")) {
+      leaves.push({ entry, moduleName: entry.name, realm });
+    }
+  }
+  return leaves;
+}
+function exportedToolPlugin(module) {
+  if (isToolPlugin(module)) return module;
+  if (typeof module !== "object" || module === null) return void 0;
+  const value = Reflect.get(module, "default");
+  return isToolPlugin(value) ? value : void 0;
+}
+function staticContributions(entry) {
+  if (entry.config === null || typeof entry.config !== "object") return [];
+  const tools = Reflect.get(entry.config, "tools");
+  if (!Array.isArray(tools)) return [];
+  return tools.flatMap((candidate) => {
+    if (candidate === null || typeof candidate !== "object") return [];
+    const declaration = candidate;
+    if (typeof declaration.id !== "string" || typeof declaration.title !== "string" || typeof declaration.summary !== "string" || declaration.realm !== "build" && declaration.realm !== "host" && declaration.realm !== "engine")
+      return [];
+    const descriptor = {
+      id: declaration.id,
+      title: declaration.title,
+      summary: declaration.summary,
+      realm: declaration.realm,
+      argsSchema: {
+        parse: (value) => ({ ok: true, value }),
+        ...declaration.argsSchema === void 0 ? {} : { describe: declaration.argsSchema }
+      },
+      resultSchema: {
+        parse: (value) => ({ ok: true, value }),
+        ...declaration.resultSchema === void 0 ? {} : { describe: declaration.resultSchema }
+      },
+      evidence: declaration.evidence ?? []
+    };
+    return [
+      {
+        descriptor,
+        execute: async () => ({
+          ok: false,
+          error: { code: "tool-static-descriptor", detail: {} }
+        })
+      }
+    ];
+  });
+}
+function hasStaticToolDeclarations(entry) {
+  if (entry.config === null || typeof entry.config !== "object") return false;
+  return Array.isArray(Reflect.get(entry.config, "tools"));
+}
+async function createViteModuleLoader(root) {
+  const server = await createServer({
+    root,
+    appType: "custom",
+    configFile: false,
+    logLevel: "silent",
+    server: { middlewareMode: true }
+  });
+  return {
+    load(name) {
+      const id = name.startsWith(".") ? `/@fs/${resolve(root, name)}` : name;
+      return server.ssrLoadModule(id);
+    },
+    close: () => server.close()
+  };
+}
+async function readProjectEntries(root) {
+  const raw = JSON.parse(await readFile(resolve(root, "forge.json"), "utf8"));
+  const parsed = GameProjectSchema.safeParse(raw);
+  if (!parsed.success) {
+    throw new TypeError(`Invalid forge.json: ${parsed.error.message}`);
+  }
+  return parsed.data.plugins ?? [];
+}
+async function discoverProjectTools(rootInput, options = {}) {
+  const root = resolve(rootInput);
+  const loadModules = options.loadModules ?? true;
+  const loader = loadModules ? options.moduleLoader ?? await createViteModuleLoader(root) : void 0;
+  try {
+    const bindings = [];
+    const ids = /* @__PURE__ */ new Map();
+    for (const leaf of projectLeaves(await readProjectEntries(root))) {
+      if (leaf.realm !== "build" && leaf.realm !== "host" && leaf.realm !== "engine") continue;
+      if (leaf.realm === "engine" && !hasStaticToolDeclarations(leaf.entry)) continue;
+      const toolPlugin = loadModules ? exportedToolPlugin(await loader.load(leaf.moduleName)) : void 0;
+      const contributions = toolPlugin?.tools ?? staticContributions(leaf.entry);
+      for (const contribution of contributions) {
+        if (contribution.descriptor.realm !== leaf.realm) {
+          throw new TypeError(
+            `Tool ${contribution.descriptor.id} declares ${contribution.descriptor.realm} but Entry ${leaf.entry.id} owns ${leaf.realm}`
+          );
+        }
+        const existing = ids.get(contribution.descriptor.id);
+        if (existing !== void 0) {
+          throw new TypeError(
+            `Duplicate project tool id ${contribution.descriptor.id} from ${existing} and ${leaf.entry.id}`
+          );
+        }
+        ids.set(contribution.descriptor.id, leaf.entry.id);
+        bindings.push({
+          contribution,
+          entry: leaf.entry,
+          moduleName: leaf.moduleName,
+          realm: leaf.realm,
+          ...toolPlugin === void 0 ? {} : { toolPlugin },
+          loadToolPlugin: async () => {
+            if (toolPlugin !== void 0) return toolPlugin;
+            const selectedLoader = options.moduleLoader ?? await createViteModuleLoader(root);
+            try {
+              const loaded = exportedToolPlugin(await selectedLoader.load(leaf.moduleName));
+              if (loaded === void 0)
+                throw new TypeError(`Entry ${leaf.entry.id} does not export a ToolPlugin`);
+              return loaded;
+            } finally {
+              await selectedLoader.close();
+            }
+          }
+        });
+      }
+    }
+    return bindings;
+  } finally {
+    if (loader !== void 0) await loader.close();
+  }
+}
+function activationFailure(cause) {
+  const message = cause instanceof Error ? cause.message : String(cause);
+  return {
+    outcome: "failed",
+    failure: {
+      code: "tool-domain-failed",
+      expected: "the owning project plugin Fiber to become ready",
+      hint: "Repair the project Entry, plugin dependencies, or plugin apply failure before retrying.",
+      detail: { code: "tool-plugin-activation-failed", payload: message }
+    },
+    artifacts: []
+  };
+}
+async function runProjectTool(binding, args2, options) {
+  const ctx = new Context();
+  try {
+    const toolPlugin = await binding.loadToolPlugin();
+    const contribution = toolPlugin.tools.find(
+      (candidate) => candidate.descriptor.id === binding.contribution.descriptor.id
+    );
+    if (contribution === void 0)
+      return activationFailure(new Error("selected tool is absent from Entry"));
+    const catalog = /* @__PURE__ */ new Map([
+      [
+        binding.moduleName,
+        {
+          realm: binding.realm,
+          load: async () => ({ default: toolPlugin })
+        }
+      ]
+    ]);
+    const { loader } = await installCatalogLoader(ctx, catalog, binding.realm);
+    const entries2 = projectPluginEntries(
+      [binding.entry],
+      binding.realm,
+      binding.realm
+    );
+    await loader.root.update(entries2);
+    await loader.await();
+    const { createToolRuntime: createToolRuntime4 } = await import('@forgeax/engine-tool-runtime');
+    const { createContextCapabilityResolver } = await import('@forgeax/engine-plugin');
+    return await createToolRuntime4([contribution]).run(contribution, args2, {
+      ...options,
+      capabilityResolver: createContextCapabilityResolver(ctx)
+    }).terminal;
+  } catch (cause) {
+    return activationFailure(cause);
+  } finally {
+    await ctx.fiber.dispose();
+  }
+}
+var init_project_tools = __esm({
+  "src/tools/project-tools.ts"() {
+  }
+});
+function analyzePreviewArtifacts(request) {
+  const required = request.required ?? [];
+  const validated = request.manifest.schemaVersion === "1.0.0" ? required.some((kind) => kind !== "rhi-tape" && kind !== "png" && kind !== "profile-capture") ? {
+    ok: false,
+    error: {
+      code: "tool-artifact-manifest-invalid",
+      expected: "requested evidence kinds to belong to the v1 artifact manifest",
+      hint: "Request one of rhi-tape, png, or profile-capture for a v1 manifest.",
+      detail: { reason: "unsupported required evidence kind" }
+    }
+  } : validateArtifactManifest(request.manifest, required) : validatePreviewArtifactManifest(
+    request.manifest,
+    (request.required ?? []).filter(
+      (role) => role === "report" || role === "rhi-tape" || role === "capture" || role === "fresh-replay" || role === "profile-capture" || role === "contact-sheet"
+    )
+  );
+  if (!validated.ok) return { ok: false, error: validated.error };
+  return {
+    ok: true,
+    value: {
+      runId: request.manifest.identity.runId,
+      captureId: request.manifest.identity.captureId,
+      artifacts: request.manifest.artifacts.map(({ kind, digest }) => ({ kind, digest }))
+    }
+  };
+}
+var init_offline_analysis = __esm({
+  "src/tools/offline-analysis.ts"() {
+  }
+});
+function createPreviewContribution() {
+  return defineTool(previewRunDescriptor, async () => ({
+    ok: false,
+    error: retiredPreviewOperationFailure
+  }));
+}
+function createOfflineAnalysisContribution() {
+  return defineTool(
+    {
+      ...previewOfflineAnalysisDescriptor
+    },
+    (request) => analyzePreviewArtifacts(request)
+  );
+}
+function createPreviewContributions() {
+  return [
+    createPreviewContribution(),
+    createOfflineAnalysisContribution()
+  ];
+}
+function createDomainPreviewContributions() {
+  return [
+    createMaterialPreviewContribution(),
+    createMeshPreviewContribution(),
+    createVfxPreviewContribution(),
+    createTexturePreviewContribution()
+  ];
+}
+var init_preview_contributions = __esm({
+  "src/tools/preview-contributions.ts"() {
+    init_catalog();
+    init_offline_analysis();
+    init_preview_migration();
+  }
+});
+
+// src/tools/contributions.ts
+var contributions_exports = {};
+__export(contributions_exports, {
+  createAuthorContribution: () => createAuthorContribution,
+  createBuildContribution: () => createBuildContribution,
+  createDefaultContributions: () => createDefaultContributions
+});
+function commandFailure(error) {
+  return { ok: false, error: { ...error, detail: error.detail } };
+}
+function createBuildContribution(projectRoot2 = process.cwd()) {
+  return defineTool(
+    projectBuildDescriptor,
+    async (options) => {
+      const { buildCommand: buildCommand2 } = await Promise.resolve().then(() => (init_commands(), commands_exports));
+      const result = await buildCommand2({ ...options, root: options.root ?? projectRoot2 });
+      return result.ok ? result.value : commandFailure(result.error);
+    }
+  );
+}
+function createAuthorContribution(projectRoot2 = process.cwd()) {
+  return defineTool(
+    authorPluginInstallDescriptor,
+    async (options) => {
+      const { pluginInstallCommand: pluginInstallCommand2 } = await Promise.resolve().then(() => (init_plugin_authoring(), plugin_authoring_exports));
+      const result = await pluginInstallCommand2({ ...options, root: options.root ?? projectRoot2 });
+      return result.ok ? result.value : commandFailure(result.error);
+    }
+  );
+}
+function createDefaultContributions(projectRoot2 = process.cwd()) {
+  return [
+    createBuildContribution(projectRoot2),
+    createAuthorContribution(projectRoot2),
+    ...createDomainPreviewContributions()
+  ];
+}
+var init_contributions = __esm({
+  "src/tools/contributions.ts"() {
+    init_catalog();
+    init_preview_contributions();
+  }
+});
+
+// src/tools/runtime.ts
+var runtime_exports = {};
+__export(runtime_exports, {
+  createDevkitToolRuntime: () => createDevkitToolRuntime,
+  createPreviewToolRuntime: () => createPreviewToolRuntime
+});
+function createDevkitToolRuntime(contributions) {
+  return createToolRuntime(contributions);
+}
+function createPreviewToolRuntime() {
+  return createToolRuntime(createPreviewContributions());
+}
+var init_runtime = __esm({
+  "src/tools/runtime.ts"() {
+    init_preview_contributions();
+  }
+});
+
+// src/cli.ts
+init_commands();
+
+// src/tools/client.ts
+init_catalog();
+function decorateResourcePreviewTerminal(terminal) {
+  if (terminal.outcome === "succeeded") return terminal;
+  const recovery = describeResourcePreviewFailure(terminal.failure);
+  if (recovery === void 0) return terminal;
+  if (terminal.failure.code !== "tool-domain-failed") return terminal;
+  return {
+    ...terminal,
+    failure: {
+      ...terminal.failure,
+      detail: {
+        ...terminal.failure.detail,
+        ...recovery.suggestedOperation === void 0 ? {} : { suggestedOperation: recovery.suggestedOperation },
+        recovery: recovery.actions
+      }
+    }
+  };
+}
+
+// src/tools/client.ts
+init_preview_migration();
+function missingTool(id) {
+  return {
+    outcome: "failed",
+    failure: {
+      code: "tool-capability-unavailable",
+      expected: `tool ${id} to exist in the project-derived catalog`,
+      hint: "Run tool list and choose one of the discovered operation ids.",
+      detail: { capability: `tool:${id}`, realm: "build" }
+    },
+    artifacts: []
+  };
+}
+async function createToolClient(options) {
+  const projectDiscovery = options.projectDiscovery;
+  const runProjectTool2 = projectDiscovery === void 0 ? (await Promise.resolve().then(() => (init_project_tools(), project_tools_exports))).runProjectTool : void 0;
+  const builtins = options.baseContributions ?? (await Promise.resolve().then(() => (init_contributions(), contributions_exports))).createDefaultContributions(options.projectRoot);
+  const project = projectDiscovery === void 0 ? await (await Promise.resolve().then(() => (init_project_tools(), project_tools_exports))).discoverProjectTools(
+    options.projectRoot,
+    options
+  ) : await projectDiscovery(options.projectRoot);
+  const contributions = [...builtins, ...project.map(({ contribution }) => contribution)];
+  const runtime = options.baseContributions === void 0 ? (await Promise.resolve().then(() => (init_runtime(), runtime_exports))).createDevkitToolRuntime(contributions) : createToolRuntime(contributions);
+  const realmDispatch = options.realmOwners === void 0 ? void 0 : createRealmDispatch(contributions, options.realmOwners);
+  const bindingById = new Map(
+    project.map((binding) => [binding.contribution.descriptor.id, binding])
+  );
+  const descriptors = runtime.list();
+  const loaded = await loadToolCatalog(
+    createProjectToolCatalogAuthority(options.projectRoot, descriptors),
+    descriptors
+  );
+  if (!loaded.ok) throw loaded.error;
+  return {
+    list: () => listTools(loaded.value),
+    describe: (id) => describeTool(loaded.value, id),
+    async run(id, args2, runOptions = {}) {
+      if (id === "preview.run") return retiredPreviewTool();
+      const contribution = runtime.get(id);
+      if (contribution === void 0) return missingTool(id);
+      const binding = bindingById.get(id);
+      const terminal = binding !== void 0 && runProjectTool2 !== void 0 ? await runProjectTool2(binding, args2, runOptions) : realmDispatch === void 0 ? await runtime.run(contribution, args2, runOptions).terminal : await realmDispatch.run(id, args2, runOptions);
+      return decorateResourcePreviewTerminal(terminal);
+    }
+  };
+}
+
+// src/tools/commands.ts
+init_preview_migration();
+
+// src/tools/run-command.ts
+async function runOperationCommand(options) {
+  const client = await createToolClient({ projectRoot: options.root ?? process.cwd() });
+  return client.run(options.id, JSON.parse(options.args)).then(decorateResourcePreviewTerminal);
+}
+
+// src/tools/commands.ts
+async function commandClient(root) {
+  try {
+    return { ok: true, value: await createToolClient({ projectRoot: root }) };
+  } catch (cause) {
+    return {
+      ok: false,
+      error: {
+        code: "tool-catalog-authority-unreadable",
+        expected: "project plugin modules and tool descriptors to load from the project authority",
+        hint: "Repair forge.json, plugin module exports, or duplicate tool ids before retrying.",
+        detail: { reason: cause instanceof Error ? cause.message : String(cause) }
+      }
+    };
+  }
+}
+async function listCommand(root = process.cwd()) {
+  const client = await commandClient(root);
+  return client.ok ? { ok: true, value: client.value.list() } : client;
+}
+async function describeCommand(options) {
+  if (options.id === void 0) {
+    return {
+      ok: false,
+      error: {
+        code: "cli-parse-error",
+        expected: "forgeax describe <operation-id>",
+        hint: "Pass the stable id returned by forgeax list.",
+        detail: {}
+      }
+    };
+  }
+  const client = await commandClient(options.root ?? process.cwd());
+  if (!client.ok) return client;
+  const entry = client.value.describe(options.id);
+  return entry === void 0 ? {
+    ok: false,
+    error: {
+      code: "tool-not-found",
+      expected: "the requested operation id to exist in the static catalog",
+      hint: "Run forgeax list and choose one of its ids.",
+      detail: { id: options.id }
+    }
+  } : { ok: true, value: entry };
+}
+async function runCommand(options) {
+  if (options.id === "preview.run") return { ok: true, value: retiredPreviewTool() };
+  if (options.id === void 0 || options.input === void 0 && options.args === void 0) {
+    return {
+      ok: false,
+      error: {
+        code: "cli-parse-error",
+        expected: "forgeax run <operation-id> --input <request.json>",
+        hint: "Describe the operation first, then pass a JSON file matching its args schema.",
+        detail: {}
+      }
+    };
+  }
+  let encoded = options.args;
+  try {
+    const input = options.input;
+    encoded = encoded ?? (input === "-" ? readFileSync(0, "utf8") : await readFile(resolve(options.root ?? process.cwd(), input), "utf8"));
+    JSON.parse(encoded);
+  } catch {
+    return {
+      ok: true,
+      value: {
+        outcome: "failed",
+        failure: {
+          code: "tool-invalid-args",
+          expected: "operation arguments to be valid JSON",
+          hint: "Encode one JSON value that conforms to the descriptor argsSchema.",
+          detail: { message: "Invalid JSON", value: null }
+        },
+        artifacts: []
+      }
+    };
+  }
+  return { ok: true, value: await runOperationCommand({ ...options, args: encoded }) };
+}
+async function execCommand(options) {
+  if (options.program === void 0) {
+    return {
+      ok: false,
+      error: {
+        code: "cli-parse-error",
+        expected: "forgeax exec <program.mjs>",
+        hint: "Pass a trusted local JavaScript module exporting a default ToolClient program.",
+        detail: {}
+      }
+    };
+  }
+  const root = options.root ?? process.cwd();
+  try {
+    const module = await import(pathToFileURL(resolve(root, options.program)).href);
+    const program = module.default ?? module.run;
+    if (typeof program !== "function") {
+      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);
+    if (!isSerializableValue(value)) {
+      throw new TypeError("tool program returned a non-serializable live value");
+    }
+    return { ok: true, value };
+  } catch (cause) {
+    return {
+      ok: false,
+      error: {
+        code: "tool-program-failed",
+        expected: "the trusted local operation program to complete with serializable results",
+        hint: "Repair the program module or inspect its selected operation terminal.",
+        detail: { reason: cause instanceof Error ? cause.message : String(cause) }
+      }
+    };
+  }
+}
+
+// src/cli.ts
+var args = process.argv.slice(2);
+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 json = args.includes("--json");
+var dryRun = args.includes("--dry-run");
+var noInstall = args.includes("--no-install");
+function option(name) {
+  const index = args.indexOf(name);
+  return index < 0 ? void 0 : args[index + 1];
+}
+var optionValueIndexes = new Set(
+  [
+    "--artifact",
+    "--base",
+    "--digest",
+    "--id",
+    "--realm",
+    "--dependency",
+    "--out-dir",
+    "--input",
+    "--output",
+    "--root",
+    "--template",
+    "--version",
+    "--work-index"
+  ].flatMap((name) => {
+    const index = args.indexOf(name);
+    return index < 0 ? [] : [index + 1];
+  })
+);
+var positionals = args.filter(
+  (value, index) => !value.startsWith("--") && !optionValueIndexes.has(index)
+);
+var scopedRoot = option("--root") ?? process.cwd();
+var projectRoot = positionals[0] ?? scopedRoot;
+var commands = [
+  "new",
+  "init",
+  "doctor",
+  "test",
+  "dev",
+  "build",
+  "package",
+  "serve",
+  "preview",
+  "run",
+  "plugin.install",
+  "plugin.uninstall",
+  "skill.install",
+  "skill.verify",
+  "sdk.install",
+  "asset.add",
+  "asset.verify",
+  "asset.inspect",
+  "asset.list",
+  "shader.check",
+  "list",
+  "describe",
+  "exec"
+];
+async function run(value) {
+  switch (value) {
+    case "new": {
+      const template = option("--template");
+      return newCommand({
+        root: projectRoot,
+        dryRun,
+        ...template === void 0 ? {} : { template }
+      });
+    }
+    case "init":
+      return initCommand({ root: projectRoot, dryRun, install: !noInstall });
+    case "doctor":
+      return doctorCommand({ root: projectRoot});
+    case "test":
+      return testCommand({ root: projectRoot});
+    case "dev":
+      return devCommand({ root: projectRoot, json });
+    case "build": {
+      const base = option("--base");
+      const outDir = option("--out-dir");
+      return buildCommand({
+        root: projectRoot,
+        ...base === void 0 ? {} : { base },
+        ...outDir === void 0 ? {} : { outDir }
+      });
+    }
+    case "package": {
+      const output = option("--output");
+      return packageCommand({
+        root: projectRoot,
+        json,
+        ...output === void 0 ? {} : { output }
+      });
+    }
+    case "preview":
+      return previewCommand({ root: projectRoot, json });
+    case "serve":
+      return devCommand({ root: projectRoot, json });
+    case "plugin.install": {
+      const module = positionals[0];
+      const id = option("--id");
+      const realm = option("--realm");
+      const dependency = option("--dependency");
+      if (module === void 0 || id === void 0 || realm !== void 0 && realm !== "host" && realm !== "engine" && realm !== "build") {
+        return {
+          ok: false,
+          error: {
+            code: "cli-parse-error",
+            expected: "forgeax plugin install <module> --id <id> [--realm host|engine|build]",
+            hint: "Pass a stable Entry id and an optional physical realm.",
+            detail: {}
+          }
+        };
+      }
+      return pluginInstallCommand({
+        root: option("--root") ?? process.cwd(),
+        module,
+        id,
+        dryRun,
+        ...realm === void 0 ? {} : { realm },
+        ...dependency === void 0 ? {} : { dependency }
+      });
+    }
+    case "plugin.uninstall": {
+      const id = positionals[0];
+      const dependency = option("--dependency");
+      if (id === void 0) {
+        return {
+          ok: false,
+          error: {
+            code: "cli-parse-error",
+            expected: "forgeax plugin uninstall <entry-id>",
+            hint: "Pass the stable Entry id stored in forge.json#plugins.",
+            detail: {}
+          }
+        };
+      }
+      return pluginUninstallCommand({
+        root: option("--root") ?? process.cwd(),
+        id,
+        dryRun,
+        ...dependency === void 0 ? {} : { dependency }
+      });
+    }
+    case "skill.install":
+      return skillInstallCommand({ root: scopedRoot});
+    case "skill.verify":
+      return skillVerifyCommand({ root: scopedRoot});
+    case "sdk.install": {
+      const root = positionals[0];
+      if (root === void 0) {
+        return {
+          ok: false,
+          error: {
+            code: "cli-parse-error",
+            expected: "forgeax sdk install <directory> [--version VERSION]",
+            hint: "Pass an empty destination outside existing SDK and game directories.",
+            detail: {}
+          }
+        };
+      }
+      const version = option("--version");
+      return sdkInstallCommand({ root, ...version === void 0 ? {} : { version } });
+    }
+    case "asset.add": {
+      const path = positionals[0];
+      if (path === void 0) {
+        return {
+          ok: false,
+          error: {
+            code: "cli-parse-error",
+            expected: "forgeax asset add <path>",
+            hint: "Pass one source file or directory.",
+            detail: {}
+          }
+        };
+      }
+      return assetAddCommand({ root: process.cwd(), path, dryRun, json });
+    }
+    case "asset.verify":
+      return assetVerifyCommand({ root: process.cwd()});
+    case "asset.inspect": {
+      const subject = positionals[0];
+      if (subject === void 0) {
+        return {
+          ok: false,
+          error: {
+            code: "cli-parse-error",
+            expected: "forgeax asset inspect <guid-or-name>",
+            hint: "Pass a stable asset GUID or an unambiguous name.",
+            detail: {}
+          }
+        };
+      }
+      return assetInspectCommand({ root: process.cwd(), subject});
+    }
+    case "asset.list":
+      return assetListCommand({ root: process.cwd()});
+    case "shader.check":
+      return shaderCheckCommand({
+        root: process.cwd(),
+        ...positionals[0] === void 0 ? {} : { path: positionals[0] }
+      });
+    case "list":
+      return listCommand(scopedRoot);
+    case "describe":
+      return describeCommand({
+        root: scopedRoot,
+        ...positionals[0] === void 0 ? {} : { id: positionals[0] }
+      });
+    case "exec":
+      return execCommand({
+        root: scopedRoot,
+        ...positionals[0] === void 0 ? {} : { program: positionals[0] }
+      });
+    case "run": {
+      const operation = positionals[0];
+      if (operation === void 0 || args.includes("--help")) {
+        return { ok: true, value: { help: renderRhiDebugHelp() } };
+      }
+      if (!operation.startsWith("rhi.")) {
+        const input = option("--input");
+        return runCommand({
+          root: scopedRoot,
+          id: operation,
+          ...input === void 0 ? {} : { input }
+        });
+      }
+      if (operation !== "rhi.capture" && operation !== "rhi.summary" && operation !== "rhi.inspect") {
+        return {
+          ok: false,
+          error: {
+            code: "cli-parse-error",
+            expected: "rhi.capture, rhi.summary, or rhi.inspect",
+            hint: "Run forgeax run --help to discover the three RHI debug operations.",
+            detail: { operation }
+          }
+        };
+      }
+      const context = createCliRhiDebugOperationContext();
+      if (operation === "rhi.capture") return runRhiDebugCommand(operation, {}, context);
+      const path = option("--artifact");
+      const digest = option("--digest");
+      if (path === void 0 || digest === void 0) {
+        return {
+          ok: false,
+          error: {
+            code: "cli-parse-error",
+            expected: "--artifact PATH and --digest DIGEST",
+            hint: "Pass the same ArtifactRef path and digest returned by capture.",
+            detail: {}
+          }
+        };
+      }
+      const artifact = { kind: "rhi-tape", digest, source: "forgeax", path };
+      if (operation === "rhi.summary") {
+        return runRhiDebugCommand(operation, { artifact }, context);
+      }
+      const workIndex = Number(option("--work-index"));
+      if (!Number.isInteger(workIndex) || workIndex < 0) {
+        return {
+          ok: false,
+          error: {
+            code: "cli-parse-error",
+            expected: "--work-index to be a non-negative integer",
+            hint: "Choose workIndex from rhi.summary output.",
+            detail: { workIndex: option("--work-index") ?? null }
+          }
+        };
+      }
+      return runRhiDebugCommand(operation, { artifact, workIndex }, 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"
+  );
+  process.exitCode = 2;
+} else {
+  const stdoutWrite = process.stdout.write;
+  if (json) {
+    process.stdout.write = ((...writeArgs) => Reflect.apply(
+      process.stderr.write,
+      process.stderr,
+      writeArgs
+    ));
+  }
+  let result;
+  try {
+    result = await run(command);
+  } finally {
+    process.stdout.write = stdoutWrite;
+  }
+  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 process.stderr.write(`[forgeax] ${result.error.code}: ${result.error.hint}
+`);
+  if (!result.ok) process.exitCode = result.error.code === "cli-parse-error" ? 2 : 1;
+}
+//# sourceMappingURL=cli.mjs.map
+//# sourceMappingURL=cli.mjs.map