@aura3d/cli 5.0.3 → 5.2.0

package/dist/look-hdri-check.d.ts

@@ -0,0 +1,7 @@
+/** Preset id -> HDRI file stem (mirrors packages/engine/src/agent-api/looks/lookPresets.ts `v0.hdri`; null presets need none). */
+export declare const LOOK_PRESET_HDRI: Readonly<Record<string, string | null>>;
+/** The HDRI stems the project's source asks for: `looks.preset("id")` / `look: "id"` presets and literal `/hdri/<stem>.hdr` urls. */
+export declare function usedLookHdris(projectDir: string): ReadonlyMap<string, string>;
+/** Warnings for every used HDRI that is not under public/hdri (or dist/hdri after a build) or is an LFS pointer. */
+export declare function lookHdriWarnings(projectDir: string, distDir?: string): string[];
+//# sourceMappingURL=look-hdri-check.d.ts.map

package/dist/look-hdri-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"look-hdri-check.d.ts","sourceRoot":"","sources":["../src/look-hdri-check.ts"],"names":[],"mappings":"AAOA,kIAAkI;AAClI,eAAO,MAAM,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAgBpE,CAAC;AAYF,qIAAqI;AACrI,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAe7E;AAYD,oHAAoH;AACpH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,SAAS,GAAG,MAAM,EAAE,CAe/E"}

package/dist/look-hdri-check.js

@@ -0,0 +1,88 @@
+// Scaffold/deploy-time check for LOOK_HDRI_MISSING: `looks.preset("golden-hour")` (and every other HDRI-backed
+// preset) loads /hdri/<file>.hdr at runtime. When that file is absent from public/hdri (or is an unsmudged git-LFS
+// pointer) the engine now degrades to a procedural probe and logs LOOK_HDRI_MISSING; this check warns before that.
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+/** Preset id -> HDRI file stem (mirrors packages/engine/src/agent-api/looks/lookPresets.ts `v0.hdri`; null presets need none). */
+export const LOOK_PRESET_HDRI = {
+    "outdoor-day": "autumn_field_puresky_1k",
+    "golden-hour": "kloppenheim_06_puresky_1k",
+    overcast: "autumn_field_puresky_1k",
+    "night-city": null,
+    "polar-night": null,
+    "alpine-snow": "autumn_field_puresky_1k",
+    "interior-warm": "studio_small_08_1k",
+    "interior-neutral": "studio_small_08_1k",
+    "interior-industrial": "studio_small_08_1k",
+    space: null,
+    underwater: null,
+    "product-studio": "studio_small_08_1k",
+    "character-showcase": "studio_small_08_1k",
+    "arena-fight": "studio_small_08_1k",
+    "neon-arcade": null
+};
+function* sourceFiles(dir, depth = 0) {
+    if (depth > 6 || !existsSync(dir))
+        return;
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (entry.name === "node_modules" || entry.name.startsWith("."))
+            continue;
+        const path = join(dir, entry.name);
+        if (entry.isDirectory())
+            yield* sourceFiles(path, depth + 1);
+        else if (/\.(?:[cm]?[jt]sx?)$/.test(entry.name) && !/\.d\.ts$/.test(entry.name))
+            yield path;
+    }
+}
+/** The HDRI stems the project's source asks for: `looks.preset("id")` / `look: "id"` presets and literal `/hdri/<stem>.hdr` urls. */
+export function usedLookHdris(projectDir) {
+    const used = new Map();
+    for (const file of sourceFiles(join(projectDir, "src"))) {
+        let text;
+        try {
+            text = readFileSync(file, "utf8");
+        }
+        catch {
+            continue;
+        }
+        const label = file.slice(projectDir.length + 1);
+        for (const match of text.matchAll(/looks\.(?:preset|describe|resolve)\(\s*["'`]([a-z0-9-]+)["'`]|\blook\s*:\s*["'`]([a-z0-9-]+)["'`]/g)) {
+            const stem = LOOK_PRESET_HDRI[match[1] ?? match[2] ?? ""];
+            if (stem && !used.has(stem))
+                used.set(stem, `looks.preset("${match[1] ?? match[2]}") in ${label}`);
+        }
+        for (const match of text.matchAll(/["'`]\/hdri\/([A-Za-z0-9_.-]+?)\.hdr["'`]/g)) {
+            if (!used.has(match[1]))
+                used.set(match[1], `"/hdri/${match[1]}.hdr" in ${label}`);
+        }
+    }
+    return used;
+}
+function isUsableHdr(path) {
+    if (!existsSync(path))
+        return false;
+    const size = statSync(path).size;
+    if (size < 1024) {
+        const head = readFileSync(path, "utf8").slice(0, 64);
+        if (head.startsWith("version https://git-lfs") || !head.startsWith("#?"))
+            return false;
+    }
+    return true;
+}
+/** Warnings for every used HDRI that is not under public/hdri (or dist/hdri after a build) or is an LFS pointer. */
+export function lookHdriWarnings(projectDir, distDir = "dist") {
+    const root = resolve(projectDir);
+    const warnings = [];
+    for (const [stem, where] of usedLookHdris(root)) {
+        const file = `${stem}.hdr`;
+        const inPublic = isUsableHdr(join(root, "public", "hdri", file));
+        const inDist = isUsableHdr(join(root, distDir, "hdri", file));
+        if (inPublic || inDist)
+            continue;
+        warnings.push(`LOOK_HDRI_MISSING: ${where} loads /hdri/${file}, but public/hdri/${file} is missing or a git-LFS pointer. ` +
+            `At runtime the engine falls back to a procedural probe (lighting will differ) and logs LOOK_HDRI_MISSING. ` +
+            `Fix: copy fixtures/environment-corpus/hdri/${file} into public/hdri/ (scaffolded templates ship it) and run \`git lfs pull\`.`);
+    }
+    return warnings;
+}
+//# sourceMappingURL=look-hdri-check.js.map

package/dist/look-hdri-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"look-hdri-check.js","sourceRoot":"","sources":["../src/look-hdri-check.ts"],"names":[],"mappings":"AAAA,+GAA+G;AAC/G,mHAAmH;AACnH,mHAAmH;AAEnH,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC1E,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE1C,kIAAkI;AAClI,MAAM,CAAC,MAAM,gBAAgB,GAA4C;IACvE,aAAa,EAAE,yBAAyB;IACxC,aAAa,EAAE,2BAA2B;IAC1C,QAAQ,EAAE,yBAAyB;IACnC,YAAY,EAAE,IAAI;IAClB,aAAa,EAAE,IAAI;IACnB,aAAa,EAAE,yBAAyB;IACxC,eAAe,EAAE,oBAAoB;IACrC,kBAAkB,EAAE,oBAAoB;IACxC,qBAAqB,EAAE,oBAAoB;IAC3C,KAAK,EAAE,IAAI;IACX,UAAU,EAAE,IAAI;IAChB,gBAAgB,EAAE,oBAAoB;IACtC,oBAAoB,EAAE,oBAAoB;IAC1C,aAAa,EAAE,oBAAoB;IACnC,aAAa,EAAE,IAAI;CACpB,CAAC;AAEF,QAAQ,CAAC,CAAC,WAAW,CAAC,GAAW,EAAE,KAAK,GAAG,CAAC;IAC1C,IAAI,KAAK,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO;IAC1C,KAAK,MAAM,KAAK,IAAI,WAAW,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;QAC9D,IAAI,KAAK,CAAC,IAAI,KAAK,cAAc,IAAI,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,SAAS;QAC1E,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QACnC,IAAI,KAAK,CAAC,WAAW,EAAE;YAAE,KAAK,CAAC,CAAC,WAAW,CAAC,IAAI,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;aACxD,IAAI,qBAAqB,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;YAAE,MAAM,IAAI,CAAC;IAC9F,CAAC;AACH,CAAC;AAED,qIAAqI;AACrI,MAAM,UAAU,aAAa,CAAC,UAAkB;IAC9C,MAAM,IAAI,GAAG,IAAI,GAAG,EAAkB,CAAC;IACvC,KAAK,MAAM,IAAI,IAAI,WAAW,CAAC,IAAI,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC;QACxD,IAAI,IAAY,CAAC;QACjB,IAAI,CAAC;YAAC,IAAI,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC;YAAC,SAAS;QAAC,CAAC;QAC9D,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QAChD,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,CAAC,oGAAoG,CAAC,EAAE,CAAC;YACxI,MAAM,IAAI,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;YAC1D,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC;gBAAE,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,iBAAiB,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,SAAS,KAAK,EAAE,CAAC,CAAC;QACrG,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,CAAC,4CAA4C,CAAC,EAAE,CAAC;YAChF,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC;gBAAE,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAE,EAAE,UAAU,KAAK,CAAC,CAAC,CAAC,YAAY,KAAK,EAAE,CAAC,CAAC;QACvF,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,WAAW,CAAC,IAAY;IAC/B,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IACpC,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC;IACjC,IAAI,IAAI,GAAG,IAAI,EAAE,CAAC;QAChB,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACrD,IAAI,IAAI,CAAC,UAAU,CAAC,yBAAyB,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;YAAE,OAAO,KAAK,CAAC;IACzF,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,oHAAoH;AACpH,MAAM,UAAU,gBAAgB,CAAC,UAAkB,EAAE,OAAO,GAAG,MAAM;IACnE,MAAM,IAAI,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACjC,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,aAAa,CAAC,IAAI,CAAC,EAAE,CAAC;QAChD,MAAM,IAAI,GAAG,GAAG,IAAI,MAAM,CAAC;QAC3B,MAAM,QAAQ,GAAG,WAAW,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;QACjE,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;QAC9D,IAAI,QAAQ,IAAI,MAAM;YAAE,SAAS;QACjC,QAAQ,CAAC,IAAI,CACX,sBAAsB,KAAK,gBAAgB,IAAI,qBAAqB,IAAI,oCAAoC;YAC1G,4GAA4G;YAC5G,8CAA8C,IAAI,6EAA6E,CAClI,CAAC;IACJ,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/physics-backend-check.d.ts

@@ -0,0 +1,8 @@
+export declare const PHYSICS_BACKEND_INSTALL_COMMAND = "npm install @dimforge/rapier3d-compat@0.20.0";
+/**
+ * Lint-time signal for the typed PHYSICS_BACKEND_MISSING runtime error: a project whose sources call `.physics(...)`,
+ * `app.physics` or `PhysicsWorld` must be able to resolve the Rapier backend. Returns one failure line (with the exact
+ * install command) or an empty list.
+ */
+export declare function physicsBackendFailures(projectDir: string): string[];
+//# sourceMappingURL=physics-backend-check.d.ts.map

package/dist/physics-backend-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"physics-backend-check.d.ts","sourceRoot":"","sources":["../src/physics-backend-check.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,+BAA+B,iDAAkC,CAAC;AAe/E;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,CAcnE"}

package/dist/physics-backend-check.js

@@ -0,0 +1,44 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join, resolve } from "node:path";
+const BACKEND = "@dimforge/rapier3d-compat";
+export const PHYSICS_BACKEND_INSTALL_COMMAND = `npm install ${BACKEND}@0.20.0`;
+const PHYSICS_USE = /\.physics\s*\(|\bapp\.physics\b|\bpreloadPhysics\b|\bPhysicsWorld\b|\bphysics\s*:\s*\{/u;
+function sourceFiles(directory, depth = 0, found = []) {
+    if (depth > 6 || found.length > 400 || !existsSync(directory))
+        return found;
+    for (const name of readdirSync(directory)) {
+        if (name === "node_modules" || name === "dist" || name.startsWith("."))
+            continue;
+        const path = join(directory, name);
+        const stats = statSync(path);
+        if (stats.isDirectory())
+            sourceFiles(path, depth + 1, found);
+        else if (/\.(?:ts|tsx|mts|js|jsx|mjs)$/u.test(name) && !name.endsWith(".d.ts") && stats.size < 512 * 1024)
+            found.push(path);
+    }
+    return found;
+}
+/**
+ * Lint-time signal for the typed PHYSICS_BACKEND_MISSING runtime error: a project whose sources call `.physics(...)`,
+ * `app.physics` or `PhysicsWorld` must be able to resolve the Rapier backend. Returns one failure line (with the exact
+ * install command) or an empty list.
+ */
+export function physicsBackendFailures(projectDir) {
+    const root = resolve(projectDir);
+    const used = sourceFiles(join(root, "src")).filter((file) => PHYSICS_USE.test(readFileSync(file, "utf8")));
+    if (used.length === 0)
+        return [];
+    let resolvable = false;
+    try {
+        createRequire(join(root, "package.json")).resolve(`${BACKEND}/package.json`);
+        resolvable = true;
+    }
+    catch { /* not installed */ }
+    if (!resolvable) {
+        // Some package exports maps hide package.json; fall back to the installed directory.
+        resolvable = existsSync(join(root, "node_modules", BACKEND, "package.json"));
+    }
+    return resolvable ? [] : [`PHYSICS_BACKEND_MISSING: ${used.length} source file(s) use Aura3D physics (first: ${used[0].slice(root.length + 1)}) but ${BACKEND} is not installed. Run: ${PHYSICS_BACKEND_INSTALL_COMMAND}`];
+}
+//# sourceMappingURL=physics-backend-check.js.map

package/dist/physics-backend-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"physics-backend-check.js","sourceRoot":"","sources":["../src/physics-backend-check.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC1E,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE1C,MAAM,OAAO,GAAG,2BAA2B,CAAC;AAC5C,MAAM,CAAC,MAAM,+BAA+B,GAAG,eAAe,OAAO,SAAS,CAAC;AAC/E,MAAM,WAAW,GAAG,yFAAyF,CAAC;AAE9G,SAAS,WAAW,CAAC,SAAiB,EAAE,KAAK,GAAG,CAAC,EAAE,QAAkB,EAAE;IACrE,IAAI,KAAK,GAAG,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC;QAAE,OAAO,KAAK,CAAC;IAC5E,KAAK,MAAM,IAAI,IAAI,WAAW,CAAC,SAAS,CAAC,EAAE,CAAC;QAC1C,IAAI,IAAI,KAAK,cAAc,IAAI,IAAI,KAAK,MAAM,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,SAAS;QACjF,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;QACnC,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC7B,IAAI,KAAK,CAAC,WAAW,EAAE;YAAE,WAAW,CAAC,IAAI,EAAE,KAAK,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;aACxD,IAAI,+BAA+B,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,IAAI,GAAG,GAAG,GAAG,IAAI;YAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC9H,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CAAC,UAAkB;IACvD,MAAM,IAAI,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACjC,MAAM,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IAC3G,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACjC,IAAI,UAAU,GAAG,KAAK,CAAC;IACvB,IAAI,CAAC;QACH,aAAa,CAAC,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,OAAO,eAAe,CAAC,CAAC;QAC7E,UAAU,GAAG,IAAI,CAAC;IACpB,CAAC;IAAC,MAAM,CAAC,CAAC,mBAAmB,CAAC,CAAC;IAC/B,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,qFAAqF;QACrF,UAAU,GAAG,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC;IAC/E,CAAC;IACD,OAAO,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,4BAA4B,IAAI,CAAC,MAAM,8CAA8C,IAAI,CAAC,CAAC,CAAE,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,SAAS,OAAO,2BAA2B,+BAA+B,EAAE,CAAC,CAAC;AAC9N,CAAC"}

package/dist/verify/cdp.d.ts

@@ -0,0 +1,69 @@
+export interface RenderCaptureOptions {
+    readonly width: number;
+    readonly height: number;
+    /** Quiet time after the app reports ready, before the first frame. */
+    readonly settleMs: number;
+    /** Time between the two frames used by the motion check. */
+    readonly motionGapMs: number;
+    /** Navigation budget. */
+    readonly timeoutMs: number;
+    /** How long to wait for `data-aura3d-ready` after load. */
+    readonly readyTimeoutMs: number;
+}
+export interface RenderCapture {
+    readonly status: number | null;
+    readonly consoleMessages: readonly {
+        readonly level: string;
+        readonly text: string;
+    }[];
+    readonly pageErrors: readonly string[];
+    readonly failedRequests: readonly string[];
+    readonly badResponses: readonly string[];
+    readonly appState: {
+        /** document.body.dataset.aura3dReady: "true", "error" or absent. */
+        readonly ready?: string;
+        readonly error?: string;
+        /** Page-level facts that explain a blank frame (tab visibility, canvas count and size, body data attributes). */
+        readonly page?: {
+            readonly visibility?: string;
+            readonly canvases?: number;
+            readonly canvasSize?: string;
+            readonly bodyData?: Readonly<Record<string, string>>;
+        };
+        readonly routeReady?: {
+            readonly status?: string;
+            readonly diagnostics?: {
+                readonly degradations?: readonly {
+                    readonly code: string;
+                    readonly message: string;
+                    readonly nodeId?: string;
+                }[];
+                readonly warnings?: readonly string[];
+                readonly errors?: readonly string[];
+                readonly backend?: string;
+                readonly drawCalls?: number;
+            };
+        } | null;
+    };
+    /** PNG frames: [first, second]. */
+    readonly frames: readonly Buffer[];
+    readonly driver: string;
+}
+export interface VerifyBrowserDriver {
+    readonly name: string;
+    capture(url: string, options: RenderCaptureOptions): Promise<RenderCapture>;
+    close(): Promise<void>;
+}
+export declare class BrowserUnavailableError extends Error {
+    constructor(message: string);
+}
+export declare function findChrome(explicit?: string): string | undefined;
+export interface ChromeDriverOptions {
+    readonly chromePath?: string;
+    /** Force software GL (SwiftShader). Default: the machine's GPU. */
+    readonly softwareGl?: boolean;
+    readonly extraArgs?: readonly string[];
+}
+/** Launch Chrome headless on an ephemeral loopback debugging port and drive one page per `capture`. */
+export declare function createChromeCdpDriver(options?: ChromeDriverOptions): VerifyBrowserDriver;
+//# sourceMappingURL=cdp.d.ts.map

package/dist/verify/cdp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdp.d.ts","sourceRoot":"","sources":["../../src/verify/cdp.ts"],"names":[],"mappings":"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"}

package/dist/verify/cdp.js

@@ -0,0 +1,223 @@
+// Default render driver for `aura3d verify`: a locally installed Chrome driven over the DevTools protocol on a loopback socket.
+// No Playwright, no download, no remote service. The protocol client is ~60 lines on Node's global WebSocket.
+// The driver is pluggable: anything that implements `VerifyBrowserDriver` can replace it (tests inject a mock).
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+export class BrowserUnavailableError extends Error {
+    constructor(message) { super(message); this.name = "BrowserUnavailableError"; }
+}
+const CHROME_CANDIDATES = [
+    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+    "/Applications/Chromium.app/Contents/MacOS/Chromium",
+    "/usr/bin/google-chrome", "/usr/bin/google-chrome-stable", "/usr/bin/chromium", "/usr/bin/chromium-browser"
+];
+export function findChrome(explicit) {
+    const fromEnv = explicit ?? process.env.AURA3D_CHROME ?? process.env.CHROME_PATH;
+    if (fromEnv)
+        return existsSync(fromEnv) ? fromEnv : undefined;
+    const found = CHROME_CANDIDATES.find((candidate) => existsSync(candidate));
+    if (found)
+        return found;
+    for (const name of ["google-chrome", "chromium", "chrome"]) {
+        const which = spawnSync("which", [name], { encoding: "utf8" });
+        if (which.status === 0 && which.stdout.trim())
+            return which.stdout.trim();
+    }
+    return undefined;
+}
+class CdpConnection {
+    socket;
+    nextId = 1;
+    pending = new Map();
+    listeners = new Map();
+    constructor(socket) {
+        this.socket = socket;
+        socket.addEventListener("message", (event) => {
+            const message = JSON.parse(String(event.data));
+            if (message.id !== undefined) {
+                const waiter = this.pending.get(message.id);
+                if (!waiter)
+                    return;
+                this.pending.delete(message.id);
+                if (message.error)
+                    waiter.reject(new Error(message.error.message));
+                else
+                    waiter.resolve(message.result ?? {});
+            }
+            else if (message.method) {
+                for (const listener of this.listeners.get(message.method) ?? [])
+                    listener(message.params ?? {}, message.sessionId);
+            }
+        });
+        socket.addEventListener("close", () => { for (const waiter of this.pending.values())
+            waiter.reject(new Error("DevTools connection closed")); this.pending.clear(); });
+    }
+    static connect(url) {
+        return new Promise((resolve, reject) => {
+            const socket = new WebSocket(url);
+            socket.addEventListener("open", () => resolve(new CdpConnection(socket)), { once: true });
+            socket.addEventListener("error", () => reject(new Error(`could not open DevTools socket ${url}`)), { once: true });
+        });
+    }
+    send(method, params = {}, sessionId) {
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, { resolve, reject });
+            this.socket.send(JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) }));
+        });
+    }
+    on(method, listener) { this.listeners.set(method, [...(this.listeners.get(method) ?? []), listener]); }
+    close() { try {
+        this.socket.close();
+    }
+    catch { /* already closed */ } }
+}
+const sleep = (ms) => new Promise((done) => setTimeout(done, ms));
+/** Launch Chrome headless on an ephemeral loopback debugging port and drive one page per `capture`. */
+export function createChromeCdpDriver(options = {}) {
+    let chrome;
+    let profileDir;
+    let connection;
+    async function launch() {
+        if (connection)
+            return connection;
+        const executable = findChrome(options.chromePath);
+        if (!executable)
+            throw new BrowserUnavailableError("No Chrome found. Pass --chrome <path> or set AURA3D_CHROME.");
+        profileDir = mkdtempSync(join(tmpdir(), "aura3d-verify-chrome-"));
+        const args = [
+            "--headless=new", "--remote-debugging-port=0", "--remote-debugging-address=127.0.0.1", `--user-data-dir=${profileDir}`,
+            "--no-first-run", "--no-default-browser-check", "--disable-extensions", "--disable-background-timer-throttling", "--disable-renderer-backgrounding",
+            "--ignore-gpu-blocklist", "--hide-scrollbars", "--mute-audio",
+            ...(options.softwareGl ? ["--use-angle=swiftshader", "--enable-unsafe-swiftshader"] : []),
+            ...(options.extraArgs ?? []), "about:blank"
+        ];
+        chrome = spawn(executable, args, { stdio: "ignore" });
+        const portFile = join(profileDir, "DevToolsActivePort");
+        const deadline = Date.now() + 20_000;
+        while (!existsSync(portFile)) {
+            if (chrome.exitCode !== null)
+                throw new BrowserUnavailableError(`Chrome exited early (code ${chrome.exitCode}).`);
+            if (Date.now() > deadline)
+                throw new BrowserUnavailableError("Chrome did not open a DevTools port within 20s.");
+            await sleep(100);
+        }
+        await sleep(100);
+        const [port, path] = readFileSync(portFile, "utf8").trim().split("\n");
+        connection = await CdpConnection.connect(`ws://127.0.0.1:${port}${path}`);
+        return connection;
+    }
+    return {
+        name: "chrome-cdp",
+        async capture(url, o) {
+            const cdp = await launch();
+            const { targetId } = (await cdp.send("Target.createTarget", { url: "about:blank" }));
+            const { sessionId } = (await cdp.send("Target.attachToTarget", { targetId, flatten: true }));
+            const send = (method, params = {}) => cdp.send(method, params, sessionId);
+            const consoleMessages = [];
+            const pageErrors = [];
+            const failedRequests = [];
+            const badResponses = [];
+            const documentRequests = new Set();
+            let status = null;
+            let loaded = false;
+            const mine = (id) => id === sessionId;
+            const pathOf = (value) => { try {
+                return new URL(value).pathname;
+            }
+            catch {
+                return value.slice(0, 120);
+            } };
+            cdp.on("Runtime.consoleAPICalled", (p, id) => {
+                if (!mine(id))
+                    return;
+                const type = String(p.type);
+                const args = p.args ?? [];
+                const text = args.map((a) => (a.value !== undefined ? String(a.value) : a.description ?? "")).join(" ").slice(0, 600);
+                consoleMessages.push({ level: type === "warning" ? "warning" : type, text });
+            });
+            cdp.on("Runtime.exceptionThrown", (p, id) => {
+                if (!mine(id))
+                    return;
+                const d = (p.exceptionDetails ?? {});
+                pageErrors.push(String(d.exception?.description ?? d.text ?? "exception").split("\n").slice(0, 3).join(" | ").slice(0, 600));
+            });
+            cdp.on("Log.entryAdded", (p, id) => {
+                if (!mine(id))
+                    return;
+                const entry = (p.entry ?? {});
+                if (entry.level === "error" && entry.text)
+                    consoleMessages.push({ level: "error", text: `${entry.text}${entry.url ? ` (${pathOf(entry.url)})` : ""}`.slice(0, 600) });
+            });
+            cdp.on("Network.responseReceived", (p, id) => {
+                if (!mine(id))
+                    return;
+                const response = (p.response ?? {});
+                if (p.type === "Document" && status === null)
+                    status = response.status ?? null;
+                if ((response.status ?? 0) >= 400)
+                    badResponses.push(`${response.status} ${pathOf(response.url ?? "")}`);
+            });
+            cdp.on("Network.requestWillBeSent", (p, id) => { if (mine(id) && p.type === "Document")
+                documentRequests.add(String(p.requestId)); });
+            cdp.on("Network.loadingFailed", (p, id) => {
+                if (!mine(id) || p.canceled)
+                    return;
+                failedRequests.push(`${p.requestId} (${String(p.errorText ?? "failed")})`);
+            });
+            cdp.on("Page.loadEventFired", (_p, id) => { if (mine(id))
+                loaded = true; });
+            try {
+                await send("Page.enable");
+                await send("Runtime.enable");
+                await send("Log.enable");
+                await send("Network.enable");
+                await send("Emulation.setDeviceMetricsOverride", { width: o.width, height: o.height, deviceScaleFactor: 1, mobile: false });
+                await send("Emulation.setFocusEmulationEnabled", { enabled: true }).catch(() => undefined);
+                const nav = (await send("Page.navigate", { url }));
+                if (nav.errorText)
+                    throw new Error(`navigation failed: ${nav.errorText}`);
+                const deadline = Date.now() + o.timeoutMs;
+                while (!loaded && Date.now() < deadline)
+                    await sleep(50);
+                const readyDeadline = Date.now() + o.readyTimeoutMs;
+                const stateExpr = `(() => { const b = document.body; const r = window.__AURA3D_ROUTE_READY__; return JSON.stringify({ ready: b && b.dataset ? b.dataset.aura3dReady : undefined, error: b && b.dataset ? b.dataset.aura3dError : undefined, page: { visibility: document.visibilityState, canvases: document.querySelectorAll('canvas').length, canvasSize: (document.querySelector('canvas') || {}).width + 'x' + (document.querySelector('canvas') || {}).height, bodyData: b ? Object.assign({}, b.dataset) : {} }, routeReady: r ? { status: r.status, diagnostics: r.diagnostics ? { degradations: (r.diagnostics.degradations || []).slice(0, 40).map(function (d) { return { code: d.code, message: String(d.message).slice(0, 400), nodeId: d.nodeId }; }), warnings: r.diagnostics.warnings, errors: r.diagnostics.errors, backend: r.diagnostics.backend, drawCalls: r.diagnostics.drawCalls } : undefined } : null }); })()`;
+                const readState = async () => {
+                    const result = (await send("Runtime.evaluate", { expression: stateExpr, returnByValue: true }));
+                    return JSON.parse(result.result?.value ?? "{}");
+                };
+                let state = await readState();
+                while (state.ready === undefined && Date.now() < readyDeadline) {
+                    await sleep(250);
+                    state = await readState();
+                }
+                await sleep(o.settleMs);
+                const shot = async () => Buffer.from((await send("Page.captureScreenshot", { format: "png" })).data, "base64");
+                const first = await shot();
+                await sleep(o.motionGapMs);
+                const second = await shot();
+                state = await readState();
+                return { status, consoleMessages, pageErrors, failedRequests: failedRequests.map((f) => f), badResponses, appState: state, frames: [first, second], driver: "chrome-cdp" };
+            }
+            finally {
+                await cdp.send("Target.closeTarget", { targetId }).catch(() => undefined);
+            }
+        },
+        async close() {
+            connection?.close();
+            connection = undefined;
+            if (chrome && chrome.exitCode === null)
+                chrome.kill("SIGTERM");
+            await sleep(150);
+            if (chrome && chrome.exitCode === null)
+                chrome.kill("SIGKILL");
+            if (profileDir)
+                rmSync(profileDir, { recursive: true, force: true });
+            chrome = undefined;
+            profileDir = undefined;
+        }
+    };
+}
+//# sourceMappingURL=cdp.js.map

package/dist/verify/cdp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdp.js","sourceRoot":"","sources":["../../src/verify/cdp.ts"],"names":[],"mappings":"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"}

package/dist/verify/codes.d.ts

@@ -0,0 +1,17 @@
+export type VerifySeverity = "error" | "warning" | "info";
+export type VerifyStepId = "typecheck" | "assets" | "lint" | "build" | "serve" | "render" | "inspect" | "verify";
+export interface VerifyCodeEntry {
+    readonly code: string;
+    readonly severity: VerifySeverity;
+    readonly step: VerifyStepId;
+    readonly title: string;
+    /** Plain-English cause. */
+    readonly cause: string;
+    /** Concrete fix hint an agent can act on. */
+    readonly fix: string;
+}
+export declare const VERIFY_CODE_TABLE: readonly VerifyCodeEntry[];
+/** Look up a code. `X_DEGRADED` codes without their own row resolve to RENDER_DEGRADED. Case-insensitive. */
+export declare function explainCode(code: string): VerifyCodeEntry | undefined;
+export declare function formatExplanation(item: VerifyCodeEntry): string;
+//# sourceMappingURL=codes.d.ts.map

package/dist/verify/codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codes.d.ts","sourceRoot":"","sources":["../../src/verify/codes.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAC1D,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEjH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,2BAA2B;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,6CAA6C;IAC7C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAID,eAAO,MAAM,iBAAiB,EAAE,SAAS,eAAe,EA0CvD,CAAC;AAIF,6GAA6G;AAC7G,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CASrE;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CAE/D"}

package/dist/verify/codes.js

@@ -0,0 +1,64 @@
+// Error-code explainer for `aura3d verify`. One table, keyed by stable code: severity, the step that raises it, a plain-English
+// cause and a concrete fix hint. `aura3d verify --explain <code>` prints an entry; a future MCP server can serve the same table.
+// Codes are append-only: never rename or reuse one, because agents key their repair logic on them.
+const entry = (code, severity, step, title, cause, fix) => ({ code, severity, step, title, cause, fix });
+export const VERIFY_CODE_TABLE = [
+    entry("VERIFY_STEP_CRASHED", "error", "verify", "A verify step threw", "The step itself failed unexpectedly (not a finding about your project).", "Re-run with --only <step> to isolate it; if it repeats, report the message field."),
+    entry("TYPECHECK_ERROR", "error", "typecheck", "TypeScript error", "tsc rejected the project; the message carries the TS code and text.", "Fix the reported line. For an unknown @aura3d/engine export, `rg` the export in docs/agents/api-surface.md instead of guessing a name."),
+    entry("TYPECHECK_UNAVAILABLE", "warning", "typecheck", "Typecheck skipped", "No tsconfig.json or no TypeScript compiler could be resolved for this project.", "Add a tsconfig.json (strict, moduleResolution bundler) and `npm i -D typescript`."),
+    entry("ASSET_VALIDATION_FAILED", "error", "assets", "Asset manifest check failed", "`assets validate` rejected aura.assets.json or a referenced file (missing file, hash drift, licence or provenance gap).", "Run `aura3d assets validate --source` for the full list, then re-add the asset with `aura3d assets add` or `assets resolve` instead of editing the manifest by hand."),
+    entry("ASSET_VALIDATION_WARNING", "warning", "assets", "Asset manifest warning", "`assets validate` accepted the manifest but flagged something worth fixing.", "Read the message; fix it before a release gate (`assets validate --release`)."),
+    entry("ASSET_PATH_INVENTED", "error", "assets", "Model path is not a typed asset", "A model is referenced by a string path instead of a typed `assets.<key>`, so nothing proved the file exists, is licensed or has bounds. Invented paths load as 404s and draw nothing.", "Run `aura3d assets resolve \"<object>\" --name <name>` (or `assets add ./file.glb --name <name>`), then use `model(assets.<name>)` from src/aura-assets.ts."),
+    entry("ASSET_KEY_UNKNOWN", "error", "assets", "assets.<key> is not defined", "The code reads `assets.<key>` but src/aura-assets.ts defines no such key.", "Use a key listed in src/aura-assets.ts, or add the asset first with `aura3d assets add`."),
+    entry("LINT_SHADOW_NO_RECEIVER", "warning", "lint", "Light has shadow on, nothing receives shadows", "A light sets `shadow`, but every surface node in the project is a receiver-off node: `receiveShadow: false`, or a `material.custom` without `receiveShadow: true` (custom materials do not receive by default). The shadow pass runs and no shadow is ever visible.", "Add `receiveShadow: true` to the ground or surface that should show the shadow (or `receiveShadow: true` inside the `material.custom` spec and multiply your lit term by `a3dSunShadowAuto(worldPos, normal)`), and keep `castShadow` on the objects that cast. Remove `shadow` from the light if you do not want shadows."),
+    entry("LINT_SKY_HIDES_BACKGROUND", "info", "lint", "Sky node covers the scene background", "The scene sets a background colour and also adds a sky (`sky.*`). The sky draws over the clear colour, so the background you set is never seen (it still seeds fog and fallback colour). The canonical recipes do this on purpose, so it is informational.", "If you expected the background colour to show, drop the sky node; if you want the sky, you can drop the background or keep it as the fallback colour."),
+    entry("LINT_SHADER_UNIFORM_UNREAD", "warning", "lint", "Custom shader uniform is never read", "A uniform is declared in `material.custom({ uniforms })` but the GLSL never mentions it, so setting it changes nothing.", "Use the uniform in the vertex or fragment source, or delete it from `uniforms`."),
+    entry("LINT_SHADER_ATTRIBUTE_UNREAD", "warning", "lint", "Custom vertex attribute is never read", "`geometry.*({ attributes })` supplies a named attribute that no custom GLSL in the project reads.", "Declare `in <type> <name>;` in the vertex shader and read it, or drop the attribute."),
+    entry("LINT_EFFECT_OPTION_IGNORED", "warning", "lint", "Option is accepted but ignored", "An `effects.*` or `instances.model` option is not read by the lowering (the engine reports it as OPTION_IGNORED at runtime), so it has no effect.", "Remove the option, or use the builder that implements it (the message lists the valid options)."),
+    entry("LINT_UTIME_NOT_ANIMATED", "warning", "lint", "Shader reads uTime but nothing advances time", "The engine binds `uTime` from the host-supplied clock, which stays 0 unless you drive it, so a uTime-only animation is a frozen frame. This is a static guess; MOTION_NONE confirms it on a real frame.", "Declare your own uniform (e.g. `waveClock`), mark the node `.runtime({ id: \"water\", mutable: true })`, and in `app.onFrame` call `app.nodes.require(\"water\").setUniform?.(\"waveClock\", seconds)`."),
+    entry("LINT_UNIFORM_RESERVED", "error", "lint", "Reserved uniform name", "`uniforms` declares a name the generated GLSL prelude already owns (uTime, uResolution, cameraPosition, the matrices, position, normal, uv ...). The material fails validation and the draw is skipped.", "Rename the uniform (e.g. `uTime` to `waveClock`)."),
+    entry("LINT_READY_NOT_AWAITED", "warning", "lint", "app.ready() is not awaited", "The project mounts an app but never awaits `app.ready()` (or chains on it), so mount errors and asset failures are not observed and code that follows can run before the first frame.", "Await it inside a function (`async function main() { const app = createAuraApp(...); await app.ready(); } void main();`) or chain `app.ready().then(...)`. Avoid module-level await (see LINT_TOP_LEVEL_AWAIT_READY)."),
+    entry("LINT_TOP_LEVEL_AWAIT_READY", "warning", "lint", "Module-level `await app.ready()`", "`await app.ready()` at module scope makes the entry module wait on the app, and in a single-entry Vite bundle the engine's lazily imported chunks import back from that same entry, so the module graph can wait on itself and the app never becomes ready (observed with monorepo-source builds: no console output, blank canvas, no data-aura3d-ready).", "Move the app into `async function main() { ...; await app.ready(); } void main();`, or use `app.ready().then(...)`."),
+    entry("LINT_SCALE_EXTREME", "warning", "lint", "Node scale looks off by orders of magnitude", "A `.scale(...)` literal is >= 50 or <= 0.02. It is probably a unit mix-up (cm vs m) and fills or vanishes from the frame.", "Check the asset's `bounds` in src/aura-assets.ts and scale to metres (1 unit = 1 m)."),
+    entry("LINT_CAMERA_INSIDE_OBJECT", "warning", "lint", "Camera starts inside an object", "The camera distance is smaller than half the size of a large scaled node at the origin, so the camera sits inside it and only back faces (or nothing) draw.", "Increase the camera distance, or reduce the node scale."),
+    entry("BUILD_FAILED", "error", "build", "Build failed", "The project build script exited non-zero.", "Read the build output tail in the finding; fix the first error."),
+    entry("BUILD_SCRIPT_MISSING", "error", "build", "No build script", "package.json has no `build` script.", "Add `\"build\": \"vite build\"` to package.json."),
+    entry("DEPLOY_CHECK_FAILED", "error", "build", "check-deploy failed", "`check-deploy` found a problem in dist (missing hashed asset, unreferenced file, licence gate).", "Run `aura3d check-deploy --dist dist` for the list and fix the first entry."),
+    entry("SERVE_FAILED", "error", "serve", "Static server could not start", "No dist/index.html, or the local static server failed to bind.", "Run the build first and confirm dist/index.html exists."),
+    entry("BROWSER_UNAVAILABLE", "error", "render", "No Chrome found for the render step", "The default driver launches a locally installed Chrome over the DevTools protocol and none was found.", "Pass --chrome <path> or set AURA3D_CHROME; or skip the browser steps with --skip render,inspect."),
+    entry("RENDER_NAVIGATION_FAILED", "error", "render", "Page did not load", "The browser could not load the served page (HTTP error, timeout or navigation failure).", "Check the build output and that index.html loads the module script."),
+    entry("RENDER_NEVER_READY", "error", "render", "App never reported ready", "The page loaded but `document.body.dataset.aura3dReady` never appeared within the readiness budget, so no first frame was reported. Causes seen: module-level `await app.ready()` deadlocking a single-entry bundle (LINT_TOP_LEVEL_AWAIT_READY), a canvas that is not the one passed to createAuraApp, an exception swallowed before mount, or assets that take longer than the budget.", "Check LINT_TOP_LEVEL_AWAIT_READY first, then the console findings; raise --ready-timeout-ms only if the scene loads large assets."),
+    entry("RENDERER_MOUNT_FAILED", "error", "render", "Renderer failed to mount", "createAuraApp could not start a renderer (no WebGL2, a thrown mount error, or an invalid scene). Nothing draws. The text is in app.diagnostics().errors.", "Read the message in the finding; usual causes are an invalid scene spec, missing WebGL2 in the browser, or a zero-size canvas. Pass `strict: true` to createAuraApp to surface it as a rejected ready()."),
+    entry("RENDER_DEGRADED", "warning", "render", "A feature is degraded", "The renderer logged a `*_DEGRADED` code: a requested feature fell back to a simpler path on this device.", "Read the specific code in the evidence (e.g. TRANSMISSION_DEGRADED); remove the feature or accept the fallback."),
+    entry("RUNTIME_OPTION_IGNORED", "warning", "inspect", "Runtime reported OPTION_IGNORED", "A builder option was accepted but not applied; the engine recorded OPTION_IGNORED.", "Remove the listed option or use the builder that reads it."),
+    entry("RUNTIME_DEGRADATION", "warning", "inspect", "Compiler reported a degradation", "The scene compiler recorded a degradation (a node or option that could not be lowered as written); the code is in the evidence.", "Read the message; remove or replace the node it names."),
+    entry("RUNTIME_NO_LIGHTS", "warning", "inspect", "Scene has no lights", "The engine warns that the scene has no lights. Lit materials (pbr, metal) render dark or black without a light or environment.", "Add `lights.studio()`, `lights.directional(...)` or `lights.ambient()`, or a `looks.preset(...)` / `environments.*`."),
+    entry("RUNTIME_NO_INTERACTIONS", "info", "inspect", "Scene has no interactions", "The engine notes that the scene has no camera interaction. Fine for a fixed shot.", "Add `interactions.orbit()` if a viewer should be able to move the camera."),
+    entry("RUNTIME_DIAGNOSTIC_ERROR", "error", "inspect", "Engine diagnostics reported an error", "The engine recorded an error (shader compile failure, asset load failure, invalid node ...).", "Read the message; CUSTOM_SHADER_COMPILE_FAILED includes the GLSL log and the offending line."),
+    entry("RUNTIME_DIAGNOSTIC_WARNING", "warning", "inspect", "Engine diagnostics reported a warning", "The engine recorded a warning during mount or the first frames.", "Read the message and fix it if it describes something you intended to work."),
+    entry("CONSOLE_ERROR", "error", "inspect", "Console error", "The page logged a console error.", "Read the text; fix the first one, later ones are often consequences."),
+    entry("PAGE_EXCEPTION", "error", "inspect", "Uncaught exception", "The page threw an uncaught exception.", "Read the message in the evidence; the first exception is the root cause."),
+    entry("REQUEST_FAILED", "error", "inspect", "A request failed (HTTP error or network failure)", "A file the page asked for returned an HTTP error or failed to load (commonly a model or texture path that is not in dist).", "Put the file under public/ (or import it) so it ships in dist, and reference it through a typed asset."),
+    entry("FRAME_BLACK", "error", "inspect", "Frame is black", "The captured frame has no bright pixels. Typical causes: no light, a light pointing away, a camera looking at nothing, a mount failure, an unlit material on a dark background.", "Add `lights.directional(...)` or a `looks.preset(...)`, check the camera target, and read the other findings first (RENDERER_MOUNT_FAILED, RUNTIME_DIAGNOSTIC_ERROR)."),
+    entry("FRAME_DIM", "warning", "inspect", "Frame is very dim", "The frame has content but its brightest 1% of pixels is dark, usually an under-lit scene.", "Raise light intensity or add an environment/look preset; check exposure."),
+    entry("FRAME_FLAT", "error", "inspect", "Frame is one flat colour", "The frame has almost no distinct colours, i.e. only the clear colour or one fullscreen surface. Typical causes: a fog density that swallows the scene, a background or sky covering everything, the camera inside an object.", "Lower fog density or move `near`/`far`, check the camera position against object sizes and scales, and check LINT_* findings."),
+    entry("FRAME_EMPTY", "warning", "inspect", "Frame has no scene texture", "Most of the frame is flat: the scene is missing, tiny, huge or behind the camera. Typical causes: a scale off by 100x, a camera pointed away, a model that failed to load.", "Check node scale against asset bounds, the camera target and distance, and REQUEST_FAILED / RUNTIME_DIAGNOSTIC_ERROR findings."),
+    entry("MOTION_NONE", "warning", "inspect", "Nothing moved between two frames", "Two frames captured about a second apart are pixel-identical. Fine for a static product shot; a bug for water, particles or a game.", "If the scene should animate, drive time yourself (`setUniform` in `app.onFrame` on a `.runtime({ mutable: true })` node) and check LINT_UTIME_NOT_ANIMATED.")
+];
+const BY_CODE = new Map(VERIFY_CODE_TABLE.map((item) => [item.code, item]));
+/** Look up a code. `X_DEGRADED` codes without their own row resolve to RENDER_DEGRADED. Case-insensitive. */
+export function explainCode(code) {
+    const key = code.trim().toUpperCase();
+    const direct = BY_CODE.get(key);
+    if (direct)
+        return direct;
+    if (/^[A-Z0-9_]+_DEGRADED$/.test(key)) {
+        const base = BY_CODE.get("RENDER_DEGRADED");
+        return { ...base, code: key, title: `${key} (degraded feature)` };
+    }
+    return undefined;
+}
+export function formatExplanation(item) {
+    return [`${item.code}  [${item.severity}, step ${item.step}]`, item.title, "", `Cause: ${item.cause}`, `Fix:   ${item.fix}`].join("\n");
+}
+//# sourceMappingURL=codes.js.map

package/dist/verify/codes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codes.js","sourceRoot":"","sources":["../../src/verify/codes.ts"],"names":[],"mappings":"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"}