@hypersoniclabs/helix-cli 0.1.6 → 0.1.23

package/dist/scenePerformance.js

@@ -0,0 +1,905 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.analyzeScenePerformance = analyzeScenePerformance;
+exports.formatScenePerformanceReport = formatScenePerformanceReport;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const helix_manifest_1 = require("@hypersoniclabs/helix-manifest");
+const draw_calls_1 = require("./glb/draw-calls");
+const glb_summary_1 = require("./glb/glb-summary");
+const paletteShowcaseProfiles_1 = require("./paletteShowcaseProfiles");
+const obj = (v) => v !== null && typeof v === "object" && !Array.isArray(v) ? v : null;
+const arr = (v) => (Array.isArray(v) ? v : []);
+const num = (v) => typeof v === "number" && Number.isFinite(v) ? v : null;
+const str = (v) => typeof v === "string" && v.trim() ? v : null;
+function at(root, ...keys) {
+    let v = root;
+    for (const k of keys) {
+        const o = obj(v);
+        if (!o)
+            return undefined;
+        v = o[k];
+    }
+    return v;
+}
+function hash(bytes) {
+    return (0, node_crypto_1.createHash)("sha256").update(bytes).digest("hex");
+}
+function json(path) {
+    try {
+        const v = obj(JSON.parse((0, node_fs_1.readFileSync)(path, "utf8")));
+        if (!v)
+            throw new Error("root is not an object");
+        return v;
+    }
+    catch (e) {
+        throw new TypeError(`Cannot read JSON ${path}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
+function files(root) {
+    return (0, node_fs_1.readdirSync)(root, { withFileTypes: true }).flatMap((e) => {
+        if (["node_modules", ".git", ".next"].includes(e.name))
+            return [];
+        const p = (0, node_path_1.join)(root, e.name);
+        return e.isDirectory() ? files(p) : e.isFile() ? [p] : [];
+    });
+}
+function parseGlb(bytes) {
+    if (bytes.length < 20 || bytes.readUInt32LE(0) !== 0x46546c67)
+        return null;
+    let document = null;
+    let bin = null;
+    let offset = 12;
+    while (offset + 8 <= bytes.length) {
+        const length = bytes.readUInt32LE(offset);
+        const type = bytes.readUInt32LE(offset + 4);
+        const start = offset + 8;
+        if (start + length > bytes.length)
+            return null;
+        if (type === 0x4e4f534a) {
+            try {
+                document = JSON.parse(bytes.subarray(start, start + length).toString("utf8"));
+            }
+            catch {
+                return null;
+            }
+        }
+        else if (type === 0x004e4942)
+            bin = bytes.subarray(start, start + length);
+        offset = start + length;
+    }
+    return document ? { json: document, bin } : null;
+}
+function visual(v) {
+    if (Array.isArray(v))
+        return v.map(visual);
+    const o = obj(v);
+    if (!o)
+        return v;
+    return Object.fromEntries(Object.entries(o)
+        .filter(([k]) => k !== "name" && k !== "extras")
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([k, x]) => [k, visual(x)]));
+}
+function imageReference(parsed, index, glbPath) {
+    const image = parsed.json.images?.[index];
+    if (!image)
+        return { identity: `missing-image:${index}`, file: null };
+    if (image.uri) {
+        const p = (0, node_path_1.resolve)((0, node_path_1.dirname)(glbPath), decodeURIComponent(image.uri));
+        return {
+            identity: (0, node_fs_1.existsSync)(p)
+                ? `sha256:${hash((0, node_fs_1.readFileSync)(p))}`
+                : `unresolved-uri:${p}`,
+            file: p,
+        };
+    }
+    if (typeof image.bufferView === "number" && parsed.bin) {
+        const view = parsed.json.bufferViews?.[image.bufferView];
+        const start = view?.byteOffset ?? 0;
+        const length = view?.byteLength ?? 0;
+        if (length > 0 && start + length <= parsed.bin.length)
+            return {
+                identity: `sha256:${hash(parsed.bin.subarray(start, start + length))}`,
+                file: null,
+            };
+    }
+    return {
+        identity: `unresolved-image:${index}:${image.mimeType ?? ""}`,
+        file: null,
+    };
+}
+function materialId(parsed, material, glbPath, referencedTextureFiles) {
+    const textureIds = (parsed.json.textures ?? []).map((texture, index) => {
+        const basisu = obj(texture.extensions?.KHR_texture_basisu);
+        const source = typeof basisu?.source === "number" ? basisu.source : texture.source;
+        const extensions = { ...(texture.extensions ?? {}) };
+        if (basisu) {
+            const normalizedBasisu = Object.fromEntries(Object.entries(basisu).filter(([key]) => key !== "source"));
+            if (Object.keys(normalizedBasisu).length)
+                extensions.KHR_texture_basisu = normalizedBasisu;
+            else
+                delete extensions.KHR_texture_basisu;
+        }
+        const image = typeof source === "number"
+            ? imageReference(parsed, source, glbPath)
+            : { identity: `missing-source:${index}`, file: null };
+        const sampler = typeof texture.sampler === "number"
+            ? obj(parsed.json.samplers?.[texture.sampler])
+            : null;
+        return {
+            image,
+            sampler: {
+                magFilter: num(sampler?.magFilter) ?? 9729,
+                minFilter: num(sampler?.minFilter) ?? 9987,
+                wrapS: num(sampler?.wrapS) ?? 10497,
+                wrapT: num(sampler?.wrapT) ?? 10497,
+            },
+            extensions: visual(extensions),
+        };
+    });
+    const rewrite = (v) => {
+        if (Array.isArray(v))
+            return v.map(rewrite);
+        const o = obj(v);
+        if (!o)
+            return v;
+        if (typeof o.index === "number") {
+            const texture = textureIds[o.index];
+            if (texture?.image.file)
+                referencedTextureFiles.add((0, node_path_1.resolve)(texture.image.file));
+            return {
+                ...Object.fromEntries(Object.entries(o)
+                    .filter(([k]) => k !== "index")
+                    .map(([k, x]) => [k, rewrite(x)])),
+                texture: texture
+                    ? { ...texture, image: texture.image.identity }
+                    : `missing-texture:${o.index}`,
+            };
+        }
+        return Object.fromEntries(Object.entries(o).map(([k, x]) => [k, rewrite(x)]));
+    };
+    return hash(JSON.stringify(visual(rewrite(material))));
+}
+function declaredResources(scene, scenePath) {
+    if (!scene || !scenePath || !Array.isArray(scene.resources))
+        return null;
+    const out = [];
+    const unresolved = [];
+    const uniqueOwned = new Map();
+    const bundleRoot = (0, node_fs_1.realpathSync)((0, node_path_1.dirname)(scenePath));
+    for (const value of scene.resources) {
+        const r = obj(value);
+        const id = str(r?.id) ?? "unknown-resource";
+        const uri = str(at(r, "source", "uri"));
+        const kind = str(r?.kind);
+        const sourceKind = str(at(r, "source", "kind")) ?? "unknown";
+        if (!r || !kind)
+            continue;
+        if (sourceKind !== "bundle" || !uri) {
+            unresolved.push({ id, kind, sourceKind });
+            continue;
+        }
+        const candidate = (0, node_path_1.resolve)(bundleRoot, decodeURIComponent(uri));
+        if (!(0, node_fs_1.existsSync)(candidate) || !(0, node_fs_1.statSync)(candidate).isFile())
+            throw new TypeError(`Declared Scene resource is missing: ${uri}`);
+        const path = (0, node_fs_1.realpathSync)(candidate);
+        const escaped = (0, node_path_1.relative)(bundleRoot, path);
+        if (escaped === ".." || escaped.startsWith(`..${node_path_1.sep}`)) {
+            throw new TypeError(`Declared Scene bundle resource escapes the Scene directory: ${uri}`);
+        }
+        const bytes = (0, node_fs_1.readFileSync)(path);
+        const expectedBytes = num(r.bytes);
+        const expectedHash = str(at(r, "integrity", "sha256"));
+        if (expectedBytes !== null && expectedBytes !== bytes.length)
+            throw new TypeError(`Declared Scene resource byte count does not match ${uri}`);
+        if (expectedHash && expectedHash !== hash(bytes))
+            throw new TypeError(`Declared Scene resource sha256 does not match ${uri}`);
+        if (!out.some((resource) => resource.path === path && resource.kind === kind))
+            out.push({ path, kind, bytes: bytes.length });
+        uniqueOwned.set(path, bytes.length);
+    }
+    return {
+        resolved: out,
+        unresolved,
+        ownedBytes: [...uniqueOwned.values()].reduce((sum, bytes) => sum + bytes, 0),
+    };
+}
+function visibleTriangles(snapshot) {
+    const root = obj(snapshot?.snapshot) ?? snapshot;
+    const rows = arr(root?.objects);
+    if (!rows.length)
+        return null;
+    let total = 0;
+    let seen = false;
+    for (const value of rows) {
+        const row = obj(value);
+        if (!row || row.visible === false)
+            continue;
+        const n = num(row.triangles);
+        if (n !== null) {
+            total += n;
+            seen = true;
+        }
+    }
+    return seen ? total : null;
+}
+function packageRef(v) {
+    const row = obj(v);
+    const m = obj(at(row, "binding", "material")) ??
+        obj(row?.material) ??
+        obj(row?.package) ??
+        row;
+    return Boolean(m && str(m.packageId) && str(m.version) && str(m.manifestCid));
+}
+function paletteRef(v) {
+    const row = obj(v);
+    const m = obj(at(row, "binding", "material")) ?? obj(row?.material) ?? row;
+    return Boolean(m && (m.palette === true || str(m.paletteFamilyId) || str(m.familyId)));
+}
+function runtimeValues(perf) {
+    const m = obj(perf?.metrics);
+    return {
+        movement: num(at(perf, "movement", "renderedFps")) ??
+            num(at(m, "frame", "fps_p50")),
+        stationary: num(at(perf, "stationary", "renderedFps")),
+        p95: num(at(perf, "movement", "frameIntervalMs", "p95")) ??
+            num(at(m, "frame", "p95")),
+        submitted: num(at(perf, "movement", "submittedTriangles", "p50")) ??
+            num(m?.triangles),
+        draws: num(at(perf, "movement", "drawCalls", "p50")) ?? num(m?.drawCalls),
+        programs: num(at(perf, "probe", "runtime", "programs")) ?? num(m?.programs),
+        offscreen: num(at(perf, "probe", "runtime", "offscreenPasses")) ??
+            num(m?.offscreenPasses),
+        multipliers: num(at(perf, "probe", "runtime", "passMultipliers")) ??
+            num(m?.passMultipliers),
+        shadowLights: num(at(perf, "probe", "runtime", "shadowCastingLights")) ??
+            num(at(m, "lights", "casters")),
+        punctualLights: num(at(perf, "probe", "runtime", "punctualLights")) ??
+            num(at(m, "lights", "punctual")),
+        gpuBytes: num(at(perf, "probe", "runtime", "gpuTextureBytes")) ??
+            num(m?.textureBytes),
+        palette: num(at(perf, "probe", "runtime", "paletteBindings")) ??
+            num(m?.paletteBindings),
+        cold: num(at(perf, "network", "observedColdTransferBytes")),
+        warm: num(at(perf, "network", "observedWarmTransferBytes")),
+        frames: num(at(perf, "movement", "renderedFrames")),
+        duration: num(at(perf, "movement", "elapsedMs")),
+    };
+}
+function receiptIdentity(perf) {
+    if (!perf)
+        return null;
+    const viewport = obj(perf.viewport) ?? obj(at(perf, "metrics", "scenario"));
+    const runtime = obj(perf.runtimeIdentity) ?? obj(at(perf, "metrics", "runtimeIdentity"));
+    const capPresent = Boolean(viewport && Object.prototype.hasOwnProperty.call(viewport, "frameCapFps"));
+    const v = {
+        hardware: str(at(runtime, "webgl", "renderer")) ?? str(runtime?.hardware),
+        browser: str(runtime?.browser),
+        buildRevision: str(at(perf, "deployment", "revision")) ?? str(perf.buildRevision),
+        sceneIdentity: str(perf.expectedSceneCid) ?? str(perf.sceneIdentity),
+        width: num(viewport?.width),
+        height: num(viewport?.height),
+        canvasBufferWidth: num(at(runtime, "canvas", "bufferWidth")),
+        canvasBufferHeight: num(at(runtime, "canvas", "bufferHeight")),
+        dpr: num(viewport?.deviceScaleFactor) ?? num(viewport?.dpr),
+        qualityProfile: str(runtime?.qualityProfile) ?? str(perf.qualityProfile),
+        frameCapFps: viewport?.frameCapFps === null ? null : num(viewport?.frameCapFps),
+    };
+    if (!v.hardware ||
+        !v.browser ||
+        !v.buildRevision ||
+        !v.sceneIdentity ||
+        v.width === null ||
+        v.height === null ||
+        v.canvasBufferWidth === null ||
+        v.canvasBufferHeight === null ||
+        v.dpr === null ||
+        !v.qualityProfile ||
+        !capPresent)
+        return null;
+    return v;
+}
+function firstArrayLength(...values) {
+    for (const v of values)
+        if (Array.isArray(v))
+            return v.length;
+    return null;
+}
+function firstNumber(...values) {
+    for (const v of values) {
+        const n = num(v);
+        if (n !== null)
+            return n;
+    }
+    return null;
+}
+function validateSceneForAnalysis(value, path) {
+    const scene = obj(value);
+    if (!scene) {
+        throw new TypeError(`Invalid Scene v2 document ${path}: expected a JSON object`);
+    }
+    // Analysis accepts an older producer's declared capabilities and extensions
+    // while still reusing the canonical schema and cross-reference validator. A
+    // publish gate separately decides whether the current runtime supports them.
+    const validation = (0, helix_manifest_1.validateSceneDocument)(scene, {
+        capabilityAllowlist: arr(at(scene, "capabilities", "required"))
+            .map(str)
+            .filter((item) => item !== null),
+        behaviorAllowlist: arr(scene.behaviors)
+            .map((item) => str(obj(item)?.component))
+            .filter((item) => item !== null),
+        runtimeExtensionAllowlist: arr(scene.runtimeExtensions)
+            .map((item) => str(obj(item)?.extension))
+            .filter((item) => item !== null),
+    });
+    if (!validation.valid) {
+        throw new TypeError(`Invalid Scene v2 document ${path}: ${validation.errors.join("; ")}`);
+    }
+    return validation.scene;
+}
+function validatePackageForAnalysis(value, path) {
+    const validation = (0, helix_manifest_1.validateContinuumPackageVersion)(value);
+    if (!validation.valid) {
+        throw new TypeError(`Invalid Continuum Package version ${path}: ${validation.errors.join("; ")}`);
+    }
+    return validation.manifest;
+}
+function validateRuntimeClaims(perf) {
+    if (!perf)
+        return;
+    const values = [
+        ["movement.renderedFps", num(at(perf, "movement", "renderedFps")), false],
+        ["stationary.renderedFps", num(at(perf, "stationary", "renderedFps")), false],
+        ["movement.renderedFrames", num(at(perf, "movement", "renderedFrames")), true],
+        ["movement.elapsedMs", num(at(perf, "movement", "elapsedMs")), false],
+    ];
+    for (const [path, value, integer] of values) {
+        if (value === null)
+            continue;
+        if (value <= 0 || (integer && !Number.isInteger(value))) {
+            throw new TypeError(`Invalid performance receipt: ${path} must be a positive${integer ? " integer" : " number"}`);
+        }
+    }
+    const fps = values[0][1];
+    const frames = values[2][1];
+    const durationMs = values[3][1];
+    if (fps !== null && frames !== null && durationMs !== null) {
+        const derived = frames / (durationMs / 1_000);
+        const tolerance = Math.max(0.5, derived * 0.02);
+        if (Math.abs(fps - derived) > tolerance) {
+            throw new TypeError(`Invalid performance receipt: movement.renderedFps ${fps} conflicts with ${frames} rendered frames over ${durationMs} ms (${derived.toFixed(3)} FPS)`);
+        }
+    }
+}
+function analyzeScenePerformance(options) {
+    const directory = (0, node_path_1.resolve)(options.directory);
+    if (!(0, node_fs_1.existsSync)(directory) || !(0, node_fs_1.statSync)(directory).isDirectory())
+        throw new TypeError(`Bundle directory does not exist: ${directory}`);
+    const profile = (options.profile ??
+        paletteShowcaseProfiles_1.PALETTE_SHOWCASE_DEFAULT_PROFILE);
+    const budget = paletteShowcaseProfiles_1.PALETTE_SHOWCASE_DEVICE_BUDGETS[profile];
+    if (!budget)
+        throw new TypeError(`Unknown performance profile "${profile}"; choose ${Object.keys(paletteShowcaseProfiles_1.PALETTE_SHOWCASE_DEVICE_BUDGETS).join(", ")}`);
+    const scenePath = options.scene ? (0, node_path_1.resolve)(options.scene) : null;
+    const packagePath = options.package ? (0, node_path_1.resolve)(options.package) : null;
+    const scene = scenePath
+        ? validateSceneForAnalysis(json(scenePath), scenePath)
+        : null;
+    const packageDoc = packagePath
+        ? validatePackageForAnalysis(json(packagePath), packagePath)
+        : null;
+    const snapshot = options.snapshot ? json((0, node_path_1.resolve)(options.snapshot)) : null;
+    const perf = options.perf ? json((0, node_path_1.resolve)(options.perf)) : null;
+    validateRuntimeClaims(perf);
+    const visualsPath = (0, node_path_1.join)(directory, "helix.visuals.json");
+    const visuals = (0, node_fs_1.existsSync)(visualsPath) ? json(visualsPath) : null;
+    const all = files(directory);
+    const declared = declaredResources(scene, scenePath);
+    const scope = declared?.resolved ??
+        all
+            .filter((p) => (0, node_path_1.extname)(p).toLowerCase() === ".glb")
+            .map((path) => ({
+            path,
+            kind: "unclassified",
+            bytes: (0, node_fs_1.statSync)(path).size,
+        }));
+    const classified = declared !== null;
+    const unresolvedRender = declared?.unresolved.some((resource) => resource.kind === "model") ?? false;
+    const unresolvedCollider = declared?.unresolved.some((resource) => resource.kind === "collider") ??
+        false;
+    const unresolvedTexture = declared?.unresolved.some((resource) => resource.kind === "texture") ??
+        false;
+    const renderResources = scope.filter((r) => r.kind === "model");
+    const collisionResources = scope.filter((r) => r.kind === "collider");
+    const analyzed = (classified ? [...renderResources, ...collisionResources] : scope).filter((r) => (0, node_path_1.extname)(r.path).toLowerCase() === ".glb");
+    const attached = new Set(scope.map((resource) => (0, node_fs_1.realpathSync)(resource.path)));
+    if (scenePath)
+        attached.add((0, node_fs_1.realpathSync)(scenePath));
+    const unattached = all.filter((path) => !attached.has((0, node_fs_1.realpathSync)(path)));
+    let renderTriangles = 0, collisionTriangles = 0, meshDefinitions = 0, meshPlacements = 0, materialSlots = 0, colliderMaterialSlots = 0, materialRecords = 0, draws = 0, instances = 0, embedded = 0;
+    const looks = new Set();
+    const referencedTextureFiles = new Set();
+    for (const resource of analyzed) {
+        const bytes = (0, node_fs_1.readFileSync)(resource.path);
+        const summary = (0, glb_summary_1.summarizeGlb)(bytes);
+        const parsed = parseGlb(bytes);
+        if (!parsed)
+            throw new TypeError(`Cannot read GLB JSON: ${resource.path}`);
+        const collider = classified && resource.kind === "collider";
+        if (collider) {
+            collisionTriangles += summary.triangleCount;
+            for (const mesh of parsed.json.meshes ?? [])
+                colliderMaterialSlots += mesh.primitives?.length ?? 0;
+            continue;
+        }
+        renderTriangles += summary.triangleCount;
+        meshDefinitions += summary.meshCount;
+        materialRecords += summary.materialCount;
+        embedded += (parsed.json.images ?? []).filter((i) => typeof i.bufferView === "number").length;
+        for (const material of parsed.json.materials ?? [])
+            looks.add(materialId(parsed, material, resource.path, referencedTextureFiles));
+        for (const mesh of parsed.json.meshes ?? [])
+            materialSlots += mesh.primitives?.length ?? 0;
+        const placements = new Map();
+        for (const node of parsed.json.nodes ?? [])
+            if (typeof node.mesh === "number") {
+                meshPlacements++;
+                placements.set(node.mesh, (placements.get(node.mesh) ?? 0) + 1);
+            }
+        instances += [...placements.values()].filter((n) => n > 1).length;
+        const local = (0, draw_calls_1.measureDrawCalls)(bytes);
+        if (!local.unreadable)
+            draws += local.drawCalls;
+    }
+    const surfaceKinds = arr(scene?.surfaces).map((s) => str(at(s, "default", "kind")));
+    const packageDependencyBindings = arr(packageDoc?.dependencies).filter((value) => str(obj(value)?.slot)?.startsWith("material:"));
+    const bindings = [
+        ...arr(scene?.materialBindings),
+        ...arr(at(packageDoc, "scene", "materialBindings")),
+        ...packageDependencyBindings,
+    ];
+    const packageBindings = bindings.filter(packageRef).length;
+    const declaredPalette = bindings.filter(paletteRef).length;
+    const lightmapDeclared = arr(packageDoc?.dependencies).some((value) => {
+        const row = obj(value);
+        return (str(row?.role) === "scene-lightmap" ||
+            str(at(row, "reference", "role")) === "scene-lightmap");
+    });
+    const probeFieldDeclared = str(visuals?.mode) === "baked";
+    const rv = runtimeValues(perf);
+    const routeKind = str(at(perf, "measurement", "routeKind"));
+    const preconditioning = arr(at(perf, "measurement", "preconditioning"))
+        .map(str)
+        .filter((value) => value !== null);
+    const compileIdle = at(perf, "measurement", "readiness", "compileIdle");
+    const streamClosure = at(perf, "measurement", "readiness", "streamClosure");
+    const giQuietMs = num(at(perf, "measurement", "readiness", "giAsleepQuietIntervalMs"));
+    const readiness = typeof compileIdle === "boolean" &&
+        typeof streamClosure === "boolean" &&
+        giQuietMs !== null
+        ? {
+            compileIdle,
+            streamClosure,
+            giAsleepQuietIntervalMs: giQuietMs,
+        }
+        : null;
+    const avatars = num(at(perf, "measurement", "occupancy", "avatars"));
+    const vehicles = num(at(perf, "measurement", "occupancy", "vehicles"));
+    const occupancy = avatars !== null && vehicles !== null ? { avatars, vehicles } : null;
+    const internalWidth = num(at(perf, "measurement", "internalResolution", "width"));
+    const internalHeight = num(at(perf, "measurement", "internalResolution", "height"));
+    const internalScale = num(at(perf, "measurement", "internalResolution", "scale"));
+    const internalResolution = internalWidth !== null &&
+        internalHeight !== null &&
+        internalScale !== null
+        ? { width: internalWidth, height: internalHeight, scale: internalScale }
+        : null;
+    const identity = receiptIdentity(perf);
+    let receipt = perf
+        ? "supplied-unbound"
+        : "none";
+    let entryMatched = false, sceneMatched = false;
+    if (perf && str(perf.entrySha256)) {
+        const p = (0, node_path_1.join)(directory, "index.html");
+        if (!(0, node_fs_1.existsSync)(p))
+            throw new TypeError("Performance receipt declares entrySha256 but bundle index.html is missing");
+        if (hash((0, node_fs_1.readFileSync)(p)) !== str(perf.entrySha256))
+            throw new TypeError("Performance receipt entrySha256 does not match this bundle index.html");
+        entryMatched = true;
+        receipt = "entry-sha256-matched";
+    }
+    if (perf && scenePath && str(perf.sceneSha256)) {
+        if (hash((0, node_fs_1.readFileSync)(scenePath)) !== str(perf.sceneSha256))
+            throw new TypeError("Performance receipt sceneSha256 does not match the supplied Scene document");
+        sceneMatched = true;
+        if (entryMatched)
+            receipt = "entry-and-scene-sha256-matched";
+    }
+    const status = !perf
+        ? "unverified"
+        : entryMatched && sceneMatched && identity && rv.movement !== null
+            ? "supplied-identity-matched"
+            : "supplied-unbound";
+    const declaredResourceRows = arr(scene?.resources).map(obj).filter(Boolean);
+    const textureRows = classified
+        ? declaredResourceRows.filter((resource) => str(resource.kind) === "texture")
+        : null;
+    const textures = declared?.resolved.filter((r) => r.kind === "texture") ?? null;
+    const declaredOwnedBytes = declared
+        ? declared.unresolved.length
+            ? null
+            : (scenePath ? (0, node_fs_1.statSync)(scenePath).size : 0) + declared.ownedBytes
+        : null;
+    const checks = [
+        {
+            metric: "asset-local draws",
+            observed: unresolvedRender ? null : draws,
+            budget: budget.drawCalls,
+            unit: "count",
+            status: unresolvedRender
+                ? "unknown"
+                : draws <= budget.drawCalls
+                    ? "within"
+                    : "over",
+            basis: "GLB placements; excludes runtime multipass submissions",
+        },
+        {
+            metric: "material slots",
+            observed: unresolvedRender ? null : materialSlots,
+            budget: budget.materialSlots,
+            unit: "count",
+            status: unresolvedRender
+                ? "unknown"
+                : materialSlots <= budget.materialSlots
+                    ? "within"
+                    : "over",
+            basis: "GLB primitive slots, not unique looks or programs",
+        },
+        {
+            metric: "resident textures",
+            observed: null,
+            budget: budget.textures,
+            unit: "count",
+            status: "unknown",
+            basis: "declared files do not prove residency",
+        },
+        {
+            metric: "GPU textures",
+            observed: null,
+            budget: budget.gpuTextureMiB,
+            unit: "MiB",
+            status: "unknown",
+            basis: "compressed bytes do not equal GPU allocation",
+        },
+        {
+            metric: "resident transfer",
+            observed: null,
+            budget: budget.residentTransferMiB,
+            unit: "MiB",
+            status: "unknown",
+            basis: "owned/transitive bytes do not prove ReadySet residency",
+        },
+        {
+            metric: "shader programs",
+            observed: null,
+            budget: budget.programs,
+            unit: "count",
+            status: "unknown",
+            basis: "runtime probe required",
+        },
+        {
+            metric: "transparent draws",
+            observed: null,
+            budget: budget.transparentDraws,
+            unit: "count",
+            status: "unknown",
+            basis: "runtime probe required",
+        },
+    ];
+    const over = checks.some((c) => c.status === "over");
+    const findings = [];
+    if (!classified)
+        findings.push({
+            severity: "warning",
+            code: "resources.roles-unresolved",
+            message: "No Scene v2 resource table was supplied, so directory GLBs are an unclassified fallback and render/collider counts remain unresolved.",
+            fix: "Pass --scene with the exact Scene v2 document; resource kinds and integrity define the analysis scope.",
+        });
+    if (declared?.unresolved.length) {
+        const unresolvedSummary = declared.unresolved
+            .map((resource) => `${resource.id} (${resource.kind}/${resource.sourceKind})`)
+            .join(", ");
+        findings.push({
+            severity: "warning",
+            code: "resources.external-unresolved",
+            message: `${declared.unresolved.length} declared Scene resource(s) use non-bundle sources and are not locally resolved: ${unresolvedSummary}.`,
+            fix: "Resolve the exact immutable resource bytes into the analysis input or supply runtime counters. Partial local counts remain unknown and cannot pass a reference budget.",
+        });
+    }
+    if (unattached.length && classified)
+        findings.push({
+            severity: "info",
+            code: "delivery.unattached-files",
+            message: `${unattached.length} file(s), ${unattached.reduce((s, p) => s + (0, node_fs_1.statSync)(p).size, 0)} bytes, are outside the declared Scene resource scope.`,
+            fix: "Remove accidental publish-root copies and keep QA reports outside the bundle.",
+        });
+    if (!unresolvedRender && instances)
+        findings.push({
+            severity: "info",
+            code: "geometry.instancing",
+            message: `${instances} GLB mesh definition(s) have repeated local placements. This is a review candidate, not a predicted performance gain; existing material batching can already submit fewer draws.`,
+            fix: "Compare current material-batch draws with proposed instance draws and instance bounds/cell culling on the same route. Use EXT_mesh_gpu_instancing only for eligible repeated single-static-mesh/single-primitive resources when measured submissions improve.",
+        });
+    if (packageBindings && rv.palette === null)
+        findings.push({
+            severity: "warning",
+            code: "materials.palette-unverified",
+            message: `${packageBindings} exact Package material binding(s) exist, but Package provenance does not prove live Palette use.`,
+            fix: "Probe renderer bindings; keep Package refs exact and do not fabricate Vault pins.",
+        });
+    const sourceSurfaceCount = surfaceKinds.filter((kind) => kind === "source").length;
+    if (sourceSurfaceCount && packageBindings)
+        findings.push({
+            severity: "warning",
+            code: "materials.package-binding-gap",
+            message: `${sourceSurfaceCount} surface(s) remain source-bound while ${packageBindings} exact material Package dependency/binding record(s) exist. Dependencies alone do not change the rendered material path.`,
+            fix: "For common surfaces where a material Package matches the intended look, bind it through the native Scene material path and verify the live renderer binding. Keep authored PBR for specific looks the Package does not preserve.",
+        });
+    if (declaredPalette && rv.palette === 0)
+        findings.push({
+            severity: "warning",
+            code: "materials.palette-gap",
+            message: `${declaredPalette} Palette binding(s) are declared while runtime observed zero.`,
+            fix: "Repair the Scene-to-renderer binding path and repeat the runtime probe.",
+        });
+    if (textures?.some((r) => (0, node_path_1.extname)(r.path).toLowerCase() === ".ktx2"))
+        findings.push({
+            severity: "info",
+            code: "textures.cold-bytes",
+            message: "KTX2 reduces decode/GPU cost, but separate 1K maps can still increase cache-cold transfer.",
+            fix: "Reuse exact texture Packages, remove unused maps, and measure cold and warm network bytes separately.",
+        });
+    if (rv.punctualLights !== null && rv.punctualLights > 8)
+        findings.push({
+            severity: "warning",
+            code: "lighting.punctual",
+            message: `${rv.punctualLights} live punctual lights were observed; fragments and shadow passes can multiply cost.`,
+            fix: "First verify importer lightmap UV preservation and runtime/shell binding support. Where supported, use lightmaps for suitable static surfaces; otherwise keep bounded probes/dynamic lights, limit range/shadows, then measure.",
+        });
+    if (!perf)
+        findings.push({
+            severity: "warning",
+            code: "runtime.proof-missing",
+            message: "No runtime receipt was supplied. Static counts cannot predict FPS.",
+            fix: "Run the headless performance harness at the target fullscreen viewport/DPR/quality on the exact Scene/build.",
+        });
+    findings.push({
+        severity: "info",
+        code: "visuals.qa",
+        message: "A capped or low-resolution screenshot is not fullscreen performance or fidelity proof. FPS wins can hide stone/wood normal shimmer, frosted-pane transmission artifacts, contact-shadow loss, and light leaks.",
+        fix: "Compare the same camera route, exposure, time of day, fullscreen viewport, DPR, and quality; check motion frame times and close-up fidelity.",
+    });
+    findings.push({
+        severity: "info",
+        code: "lighting.bake-kind",
+        message: "Baked probes avoid live captures but still add per-fragment sampling. They are not lightmaps and “baked” does not mean fast.",
+        fix: "Use the built-in visual policy. Verify importer/runtime/shell lightmap support before authoring one; a probe-field consumer does not prove shell lightmap support. Keep bounded probes/dynamic light where movement or editability requires them, then measure.",
+    });
+    const missing = [];
+    if (rv.movement === null)
+        missing.push("runtime FPS and frame-time receipt");
+    if (!identity)
+        missing.push("hardware, browser, build revision, scene identity, viewport, DPR, and quality profile");
+    if (!str(at(perf, "runtimeIdentity", "browser")) ||
+        !str(at(perf, "runtimeIdentity", "qualityProfile")))
+        missing.push("effective quality profile and exact browser build");
+    if (rv.submitted === null ||
+        rv.draws === null ||
+        rv.programs === null ||
+        rv.multipliers === null)
+        missing.push("submitted triangles, draw calls, shader programs, and pass multipliers");
+    if (rv.palette === null)
+        missing.push("observed Palette bindings");
+    if (rv.cold === null || rv.warm === null)
+        missing.push("observed cold and warm transfer bytes");
+    if (!routeKind ||
+        !preconditioning.length ||
+        !readiness ||
+        !occupancy ||
+        !internalResolution ||
+        !str(at(perf, "measurement", "renderedBundleSha256")) ||
+        !str(at(perf, "measurement", "dirtyCodeDigest")))
+        missing.push("grounded route, ordered preconditioning, compile/stream/GI readiness, occupancy, internal resolution, rendered bundle hash, and dirty-code digest");
+    const runtimeRating = status === "supplied-identity-matched"
+        ? {
+            label: status,
+            profile,
+            verdict: (rv.movement ?? 0) >= budget.targetFps
+                ? "claimed-meets-target"
+                : "claimed-below-target",
+            targetFps: budget.targetFps,
+            reason: `Supplied identity-matched receipt claims ${rv.movement} movement FPS against the ${budget.targetFps} FPS reference. Hashes bind bytes, not measurement origin.`,
+        }
+        : {
+            label: status,
+            profile,
+            verdict: "unverified",
+            reason: status === "supplied-unbound"
+                ? "Receipt claims are supplied evidence; exact byte binding and complete runtime identity are absent."
+                : "Static estimated budget utilization does not predict FPS.",
+        };
+    return {
+        schema: "helix.scene-performance-report/1",
+        generatedAt: new Date().toISOString(),
+        profile,
+        rating: {
+            estimate: {
+                label: "estimated-budget-utilization",
+                profile,
+                applicability: "palette-showcase-reference",
+                verdict: over ? "over-budget" : "within-known-budgets-incomplete",
+                checks,
+                reason: over
+                    ? "A known static metric exceeds the existing Palette Showcase reference budget."
+                    : "Known static metrics fit this reference; unknown residency, GPU, shader, and pass costs cannot improve the rating or prove FPS.",
+            },
+            runtime: runtimeRating,
+        },
+        authored: {
+            resourceRoleProvenance: !classified
+                ? "directory-fallback-unclassified"
+                : declared.unresolved.length
+                    ? "scene-v2-resources-partial"
+                    : "scene-v2-resources",
+            renderFiles: classified
+                ? declaredResourceRows.filter((resource) => str(resource.kind) === "model")
+                    .length
+                : null,
+            colliderFiles: classified
+                ? declaredResourceRows.filter((resource) => str(resource.kind) === "collider")
+                    .length
+                : null,
+            unresolvedResources: declared?.unresolved ?? [],
+            meshDefinitionTriangles: unresolvedRender ? null : renderTriangles,
+            collisionTriangles: classified && !unresolvedCollider ? collisionTriangles : null,
+            visibleSceneTriangles: visibleTriangles(snapshot),
+            meshDefinitions: unresolvedRender ? null : meshDefinitions,
+            meshPlacements: unresolvedRender ? null : meshPlacements,
+            materialSlots: unresolvedRender ? null : materialSlots,
+            colliderMaterialSlots: classified && !unresolvedCollider ? colliderMaterialSlots : null,
+            fileLocalMaterialRecords: unresolvedRender ? null : materialRecords,
+            uniqueVisualMaterials: unresolvedRender ? null : looks.size,
+            assetLocalDraws: unresolvedRender ? null : draws,
+            instancingCandidates: unresolvedRender ? null : instances,
+            unattachedFiles: unattached.length,
+            unattachedBytes: unattached.reduce((s, p) => s + (0, node_fs_1.statSync)(p).size, 0),
+        },
+        materials: {
+            sourceBoundSurfaces: Array.isArray(scene?.surfaces)
+                ? surfaceKinds.filter((k) => k === "source").length
+                : null,
+            nativeMaterialBoundSurfaces: Array.isArray(scene?.surfaces)
+                ? surfaceKinds.filter((k) => k === "material").length
+                : null,
+            declaredBindings: bindings.length,
+            packageNativeBindings: packageBindings,
+            legacyBindings: bindings.length - packageBindings,
+            declaredPaletteBindings: bindings.length ? declaredPalette : null,
+            observedPaletteBindings: rv.palette,
+            paletteIdentity: rv.palette !== null
+                ? "runtime-observed"
+                : declaredPalette
+                    ? "explicit-declaration"
+                    : "unresolved",
+            note: "Source-bound surfaces, native material surfaces, Package bindings, file-local records, primitive slots, unique looks, programs, and observed Palette bindings are separate counters.",
+        },
+        textures: {
+            declaredTextureResources: textureRows?.length ?? null,
+            materialKtx2Resources: unresolvedRender || unresolvedTexture
+                ? null
+                : (textures?.filter((r) => (0, node_path_1.extname)(r.path).toLowerCase() === ".ktx2" &&
+                    referencedTextureFiles.has((0, node_path_1.resolve)(r.path))).length ?? null),
+            ktx2Resources: unresolvedTexture
+                ? null
+                : (textures?.filter((r) => (0, node_path_1.extname)(r.path).toLowerCase() === ".ktx2")
+                    .length ?? null),
+            declaredTextureBytes: unresolvedTexture || !textures
+                ? null
+                : textures.reduce((s, r) => s + r.bytes, 0),
+            embeddedTextureRecords: embedded,
+            estimatedGpuBytes: null,
+            observedGpuBytes: rv.gpuBytes,
+            note: "Declared/compressed files are not resident texture count or GPU memory.",
+        },
+        delivery: {
+            declaredOwnedBytes,
+            transitiveClosureBytes: firstNumber(at(packageDoc, "expectedClosure", "totalBytes"), at(scene, "compilation", "dependencyClosureBytes")),
+            observedColdTransferBytes: rv.cold,
+            observedWarmTransferBytes: rv.warm,
+            notes: [
+                "Declared owned bytes come from the Scene document and exact resource table.",
+                "Transitive closure is reachability, not actual transfer.",
+                "Cached zero-byte timings are not cold proof.",
+            ],
+        },
+        streaming: {
+            readySetCount: firstArrayLength(scene?.readySets, scene?.streamGroups),
+            dependencyCount: firstArrayLength(packageDoc?.dependencies, scene?.dependencies, at(scene, "compilation", "dependencies")),
+            note: "ReadySets/stream groups and dependencies shape first-frame residency; counts do not prove resident bytes.",
+        },
+        visuals: {
+            policy: visuals ? "builtin" : "unresolved",
+            bakeKind: lightmapDeclared && probeFieldDeclared
+                ? "mixed"
+                : lightmapDeclared
+                    ? "lightmap"
+                    : probeFieldDeclared
+                        ? "probe-field"
+                        : "unresolved",
+            note: "Use the canonical built-in visual policy and record actual lightmap versus baked probe-field use.",
+        },
+        runtime: {
+            status,
+            receiptProvenance: receipt,
+            fps: perf ? { movement: rv.movement, stationary: rv.stationary } : null,
+            frameP95Ms: rv.p95,
+            submittedTriangles: rv.submitted,
+            drawCalls: rv.draws,
+            shaderPrograms: rv.programs,
+            offscreenPasses: rv.offscreen,
+            passMultipliers: rv.multipliers,
+            shadowCastingLights: rv.shadowLights,
+            punctualLights: rv.punctualLights,
+            identity,
+            renderedFrames: rv.frames,
+            durationMs: rv.duration,
+            routeKind,
+            preconditioning: preconditioning.length ? preconditioning : null,
+            readiness,
+            occupancy,
+            internalResolution,
+            renderedBundleSha256: str(at(perf, "measurement", "renderedBundleSha256")),
+            dirtyCodeDigest: str(at(perf, "measurement", "dirtyCodeDigest")),
+            capExplanation: identity
+                ? identity.frameCapFps === null
+                    ? "Receipt declares uncapped capture."
+                    : `Receipt declares a ${identity.frameCapFps} FPS cap; reaching it does not prove spare headroom.`
+                : null,
+        },
+        findings,
+        verificationMissing: [...new Set(missing)],
+    };
+}
+const count = (v) => v === null ? "unknown" : v.toLocaleString("en-US");
+function formatScenePerformanceReport(report) {
+    const lines = [
+        `SCENE PERFORMANCE REPORT — ${report.profile} (${report.rating.estimate.applicability})`,
+        `STATIC: ${report.rating.estimate.verdict} (${report.rating.estimate.label})`,
+        report.runtime.status === "supplied-identity-matched"
+            ? `SUPPLIED IDENTITY-MATCHED RUNTIME CLAIM: ${report.runtime.fps?.movement ?? "unknown"} FPS; ${report.rating.runtime.verdict}`
+            : "UNVERIFIED RUNTIME — static counts do not predict FPS",
+        "",
+        `Resources: ${count(report.authored.renderFiles)} render / ${count(report.authored.colliderFiles)} collider / ${report.authored.unresolvedResources.length} unresolved / ${report.authored.unattachedFiles} unattached files`,
+        `Authored mesh-definition geometry: ${count(report.authored.meshDefinitionTriangles)} triangles`,
+        `Collider geometry: ${count(report.authored.collisionTriangles)} triangles / ${count(report.authored.colliderMaterialSlots)} primitive slots`,
+        `Visible snapshot geometry: ${count(report.authored.visibleSceneTriangles)} triangles`,
+        `Runtime submitted geometry: ${count(report.runtime.submittedTriangles)} triangles`,
+        `Runtime sample: ${count(report.runtime.renderedFrames)} rendered frames / ${count(report.runtime.durationMs)} ms / ${report.runtime.routeKind ?? "unknown route"}`,
+        `Meshes: ${count(report.authored.meshDefinitions)} definitions / ${count(report.authored.meshPlacements)} placements / ${count(report.authored.instancingCandidates)} instancing candidates`,
+        `Materials: ${count(report.authored.uniqueVisualMaterials)} unique visual / ${count(report.authored.fileLocalMaterialRecords)} file-local / ${count(report.authored.materialSlots)} slots / ${count(report.runtime.shaderPrograms)} runtime programs`,
+        `Surfaces: ${count(report.materials.sourceBoundSurfaces)} source / ${count(report.materials.nativeMaterialBoundSurfaces)} native material / ${report.materials.packageNativeBindings} exact Package / ${count(report.materials.observedPaletteBindings)} observed Palette`,
+        `Textures: ${count(report.textures.declaredTextureResources)} declared / ${count(report.textures.materialKtx2Resources)} material KTX2 / ${count(report.textures.ktx2Resources)} total KTX2 / ${count(report.textures.declaredTextureBytes)} compressed bytes / ${count(report.textures.observedGpuBytes)} observed GPU bytes`,
+        `Delivery: ${count(report.delivery.declaredOwnedBytes)} declared owned / ${count(report.delivery.transitiveClosureBytes)} transitive / ${count(report.delivery.observedColdTransferBytes)} cold / ${count(report.delivery.observedWarmTransferBytes)} warm bytes`,
+        "",
+        ...report.findings.flatMap((f) => [
+            `${f.severity.toUpperCase()} ${f.code}: ${f.message}`,
+            `  Fix: ${f.fix}`,
+        ]),
+    ];
+    if (report.verificationMissing.length)
+        lines.push("", `Verification missing: ${report.verificationMissing.join("; ")}`);
+    return lines.join("\n");
+}
+//# sourceMappingURL=scenePerformance.js.map