create-three-blocks-starter 0.5.6 → 0.6.0-alpha.402.g6a35bb19fa05

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # create-three-blocks-starter
 
+## 0.6.0-alpha.402.g6a35bb19fa05
+
+- Library: Three.js r186 is supported, and development always compiles shaders live until previewed.
+
+- Library: Vite builds capture precompiled shaders from the built bundle; nothing to commit.
+
+- Devtools: The shader watch command, the 186dev Three.js lane and Playwright driver names are gone.
+
+- Starter: New projects ship no generated shader files; the build captures them.
+
+- CLI: One check command verifies types, the production build and every scene, with a PNG per scene.
+
+- Devtools: Development names the shaders that compile after the first frame, once per burst.
+
+- Library: Ambient occlusion compiles again with antialiasing on Three.js r186.
+
+- Devtools: Interrupted captures and checks no longer leave renderer processes running.
+
+- Devtools: Captures and checks deliver pointer and wheel input to listeners on the window.
+
+- Starter: Add a scene by adding a folder; the build captures it and the check command boots it.
+
+- CLI: JSON output of devtools commands no longer starts with a banner line.
+
+- Devtools: Precompiled temporal antialiasing and upscaling jitter the camera again.
+
+- Library: Ambient occlusion loads precompiled on WebGPU instead of compiling at startup.
+
+- Website: The shader precompilation benchmark now measures the official Three.js r186 examples.
+
+- Library: Precompiled ambient occlusion no longer crashes on its first frame on Three.js r186.
+
+- Packages: Built from `6a35bb19fa05`.
+
+
 ## 0.5.6
 
 ### Patch Changes

package/dist/artifacts.d.ts

@@ -1,65 +1,5 @@
-import { type ArtifactStatus, type CompatibilityVersions, type GeneratedFile, type TemplateName } from "./types.js";
-declare const SHADER_BACKENDS: readonly ["webgpu", "webgl"];
-type ShaderBackend = (typeof SHADER_BACKENDS)[number];
-declare const SHADER_COMPATIBILITIES: {
-    readonly webgpu: "three-webgpu-r185-v1";
-    readonly webgl: "three-webgl-r185-v1";
-};
-declare const SHADER_ADDRESS_VERSION: 2;
-declare const SHADER_RECIPE_VERSION: 1;
-declare const SHADER_HYDRATION_VERSION: 2;
-declare const SHADER_TRANSFORM_VERSION: 64;
-interface ShaderCoverage {
-    readonly render: number;
-    readonly vertex: number;
-    readonly fragment: number;
-    readonly compute: number;
-}
-interface ShaderSceneReceipt {
-    readonly backend: ShaderBackend;
-    readonly artifact: string;
-    readonly artifactHash: string;
-    readonly asset: string;
-    readonly assetHash: string;
-    readonly bytes: number;
-    readonly inputs: Readonly<Record<string, string>>;
-    readonly coverage: ShaderCoverage;
-    readonly skipped: {
-        readonly render: number;
-        readonly compute: number;
-    };
-}
-interface ShaderReceipt {
-    readonly schemaVersion: 2;
-    readonly runtime: Pick<CompatibilityVersions, "three" | "threeBlocks"> & {
-        readonly threeBlocksShaderClosure: string;
-    };
-    readonly tool: {
-        readonly name: "@three-blocks/devtools";
-        readonly version: string;
-        readonly compatibility: (typeof SHADER_COMPATIBILITIES)[ShaderBackend];
-        readonly compatibilities: Readonly<Partial<Record<ShaderBackend, (typeof SHADER_COMPATIBILITIES)[ShaderBackend]>>>;
-        readonly transform: typeof SHADER_TRANSFORM_VERSION;
-        readonly address: typeof SHADER_ADDRESS_VERSION;
-        readonly recipe: typeof SHADER_RECIPE_VERSION;
-        readonly hydration: typeof SHADER_HYDRATION_VERSION;
-    };
-    readonly scenes: Readonly<Record<string, ShaderSceneReceipt>>;
-}
-interface LoadedShaderArtifact {
-    readonly status: ArtifactStatus;
-    readonly files: readonly GeneratedFile[];
-    readonly note: string;
-}
-/** Validate the exact pair emitted by public shader capture before it can become a fresh catalog payload. */
-export declare function validateShaderArtifactPayload(template: TemplateName, manifest: string | Uint8Array, metadata: string | Uint8Array, versions?: Pick<CompatibilityVersions, "three" | "threeBlocks">, backend?: ShaderBackend): ShaderReceipt;
-export declare function shaderArtifactPaths(template: TemplateName): readonly string[];
-export declare function shaderArtifactFiles(template: TemplateName): readonly GeneratedFile[];
-export declare function shaderArtifactState(template: TemplateName): Pick<LoadedShaderArtifact, "status" | "note">;
-/** Prove that a fresh payload was captured from the exact fully composed generated template. */
-export declare function validateShaderArtifactProject(template: TemplateName, files: ReadonlyMap<string, GeneratedFile>, versions: Pick<CompatibilityVersions, "three" | "threeBlocks">): void;
+import type { GeneratedFile } from "./types.js";
 export declare function textArtifactFiles(): readonly GeneratedFile[];
 export declare const textArtifactPaths: readonly string[];
 export declare function environmentArtifactFiles(): readonly GeneratedFile[];
 export declare const environmentArtifactPaths: readonly string[];
-export {};

package/dist/artifacts.js

@@ -1,9 +1,6 @@
-import { createHash } from "node:crypto";
-import { existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
-import path from "node:path";
-import { COMPATIBILITY_VERSIONS } from "./constants.js";
-import { TEMPLATE_NAMES, } from "./types.js";
-import { snapshotGeneratedShaderInputs } from "./shader-inputs.js";
+import { readFileSync } from "node:fs";
+// Shaders are not here on purpose: `vite build` captures the built bundle and writes its
+// manifests next to it, so a scaffold carries no generated shader file to keep fresh.
 const TEXT_FILES = [
     "public/fonts/OFL-1.1.txt",
     "public/fonts/geist.woff2",
@@ -17,535 +14,6 @@ const TEXT_FILES = [
     "public/fonts/noto-jp.msdf.ktx2",
     "public/fonts/noto-jp.msdf.meta.json",
 ];
-const SHADER_BACKENDS = ["webgpu", "webgl"];
-const SHADER_COMPATIBILITIES = {
-    webgpu: "three-webgpu-r185-v1",
-    webgl: "three-webgl-r185-v1",
-};
-const SHADER_ADDRESS_VERSION = 2;
-const SHADER_RECIPE_VERSION = 1;
-const SHADER_HYDRATION_VERSION = 2;
-const SHADER_TRANSFORM_VERSION = 64;
-const SHA256 = /^[a-f0-9]{64}$/u;
-const SAFE_VERSION = /^[0-9A-Za-z][0-9A-Za-z.+_-]{0,127}$/u;
-const MAX_MANIFEST_BYTES = 32 * 1_024 * 1_024;
-const MAX_RECEIPT_BYTES = 2 * 1_024 * 1_024;
-const MAX_TIMING_BYTES = 1_024 * 1_024;
-const MAX_INPUTS = 4_096;
-const MAX_ENTRIES = 4_096;
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function bytes(content) {
-    return typeof content === "string" ? Buffer.from(content, "utf8") : content;
-}
-function text(content, label) {
-    try {
-        return typeof content === "string"
-            ? content
-            : new TextDecoder("utf-8", { fatal: true }).decode(content);
-    }
-    catch {
-        throw new Error(`${label} must be valid UTF-8.`);
-    }
-}
-function sha256(content) {
-    return createHash("sha256").update(bytes(content)).digest("hex");
-}
-function shaderReceiptKey(template, backend) {
-    return backend === "webgpu" ? template : `${template}.webgl`;
-}
-function nonNegativeInteger(value, label) {
-    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
-        throw new Error(`${label} must be a non-negative integer.`);
-    }
-    return value;
-}
-function safeRelativePath(value, label) {
-    if (typeof value !== "string" ||
-        value.length === 0 ||
-        value.includes("\\") ||
-        path.posix.isAbsolute(value) ||
-        path.posix.normalize(value) !== value ||
-        value === ".." ||
-        value.startsWith("../") ||
-        /[\u0000-\u001f\u007f]/u.test(value)) {
-        throw new Error(`${label} must be a safe project-relative path.`);
-    }
-    return value;
-}
-function coverage(value, label) {
-    if (!isRecord(value))
-        throw new Error(`${label} is missing.`);
-    return {
-        render: nonNegativeInteger(value.render, `${label}.render`),
-        vertex: nonNegativeInteger(value.vertex, `${label}.vertex`),
-        fragment: nonNegativeInteger(value.fragment, `${label}.fragment`),
-        compute: nonNegativeInteger(value.compute, `${label}.compute`),
-    };
-}
-function parseInputs(value, template) {
-    if (!isRecord(value))
-        throw new Error(`Shader receipt inputs for "${template}" are invalid.`);
-    const entries = Object.entries(value);
-    if (entries.length === 0 || entries.length > MAX_INPUTS) {
-        throw new Error(`Shader receipt inputs for "${template}" must contain 1...${MAX_INPUTS} files.`);
-    }
-    const result = {};
-    for (const [inputPath, hash] of entries) {
-        safeRelativePath(inputPath, `Shader receipt input for "${template}"`);
-        if (typeof hash !== "string" || !SHA256.test(hash))
-            throw new Error(`Shader receipt input hash for "${template}" is invalid.`);
-        result[inputPath] = hash;
-    }
-    return result;
-}
-function parseReceipt(template, content, versions) {
-    if (bytes(content).byteLength > MAX_RECEIPT_BYTES)
-        throw new Error(`Shader metadata for "${template}" exceeds ${MAX_RECEIPT_BYTES} bytes.`);
-    let value;
-    try {
-        value = JSON.parse(text(content, `Shader metadata for "${template}"`));
-    }
-    catch (error) {
-        if (error instanceof Error &&
-            error.message.endsWith("must be valid UTF-8."))
-            throw error;
-        throw new Error(`Shader metadata for "${template}" is not valid JSON.`);
-    }
-    if (!isRecord(value) ||
-        value.schemaVersion !== 2 ||
-        !isRecord(value.runtime) ||
-        value.runtime.three !== versions.three ||
-        typeof value.runtime.threeBlocks !== "string" ||
-        !SAFE_VERSION.test(value.runtime.threeBlocks)) {
-        throw new Error(`Shader metadata for "${template}" has an incompatible schema or runtime version.`);
-    }
-    if (typeof value.runtime.threeBlocksShaderClosure !== "string" ||
-        !SHA256.test(value.runtime.threeBlocksShaderClosure)) {
-        throw new Error(`Shader metadata for "${template}" has an invalid three-blocks shader runtime closure.`);
-    }
-    if (!isRecord(value.tool) ||
-        value.tool.name !== "@three-blocks/devtools" ||
-        typeof value.tool.version !== "string" ||
-        !SAFE_VERSION.test(value.tool.version) ||
-        (value.tool.compatibility !== SHADER_COMPATIBILITIES.webgpu &&
-            value.tool.compatibility !== SHADER_COMPATIBILITIES.webgl) ||
-        value.tool.transform !== SHADER_TRANSFORM_VERSION ||
-        value.tool.address !== SHADER_ADDRESS_VERSION ||
-        value.tool.recipe !== SHADER_RECIPE_VERSION ||
-        value.tool.hydration !== SHADER_HYDRATION_VERSION) {
-        throw new Error(`Shader metadata for "${template}" has incompatible public tool metadata.`);
-    }
-    if (value.tool.compatibilities !== undefined &&
-        (!isRecord(value.tool.compatibilities) ||
-            Object.entries(value.tool.compatibilities).some(([backend, compatibility]) => (backend !== "webgpu" && backend !== "webgl") ||
-                compatibility !==
-                    SHADER_COMPATIBILITIES[backend]))) {
-        throw new Error(`Shader metadata for "${template}" has incompatible backend metadata.`);
-    }
-    const rawScenes = isRecord(value.scenes) ? value.scenes : undefined;
-    const sceneKeys = rawScenes === undefined ? [] : Object.keys(rawScenes);
-    const allowedSceneKeys = new Set(SHADER_BACKENDS.map((backend) => shaderReceiptKey(template, backend)));
-    if (rawScenes === undefined ||
-        sceneKeys.length === 0 ||
-        sceneKeys.length > SHADER_BACKENDS.length ||
-        sceneKeys.some((key) => !allowedSceneKeys.has(key) || !isRecord(rawScenes[key]))) {
-        throw new Error(`Shader metadata for "${template}" must contain only that template's backend scenes.`);
-    }
-    const scenes = {};
-    for (const key of sceneKeys) {
-        const backend = key.endsWith(".webgl")
-            ? "webgl"
-            : "webgpu";
-        const raw = rawScenes[key];
-        const expectedArtifact = `${template}.${backend}.ts`;
-        const expectedAsset = `three-blocks/shaders/${template}.${backend}.json`;
-        if (raw.backend !== undefined &&
-            raw.backend !== backend) {
-            throw new Error(`Shader receipt for "${key}" names the wrong backend.`);
-        }
-        if (raw.artifact !== expectedArtifact ||
-            typeof raw.artifactHash !== "string" ||
-            !SHA256.test(raw.artifactHash)) {
-            throw new Error(`Shader receipt for "${key}" references an invalid artifact.`);
-        }
-        if (raw.asset !== expectedAsset ||
-            typeof raw.assetHash !== "string" ||
-            !SHA256.test(raw.assetHash)) {
-            throw new Error(`Shader receipt for "${key}" references an invalid public asset.`);
-        }
-        const selectedCoverage = coverage(raw.coverage, `Shader coverage for "${key}"`);
-        if (selectedCoverage.render === 0 ||
-            selectedCoverage.vertex === 0 ||
-            selectedCoverage.fragment === 0) {
-            throw new Error(`Shader capture for "${key}" has no complete render pipeline coverage.`);
-        }
-        if (!isRecord(raw.skipped))
-            throw new Error(`Shader skipped-build counts for "${key}" are missing.`);
-        scenes[key] = {
-            backend,
-            artifact: expectedArtifact,
-            artifactHash: raw.artifactHash,
-            asset: expectedAsset,
-            assetHash: raw.assetHash,
-            bytes: nonNegativeInteger(raw.bytes, `Shader artifact bytes for "${key}"`),
-            inputs: parseInputs(raw.inputs, template),
-            coverage: selectedCoverage,
-            skipped: {
-                render: nonNegativeInteger(raw.skipped.render, `Shader skipped render builds for "${key}"`),
-                compute: nonNegativeInteger(raw.skipped.compute, `Shader skipped compute builds for "${key}"`),
-            },
-        };
-    }
-    return {
-        schemaVersion: 2,
-        runtime: {
-            three: versions.three,
-            threeBlocks: value.runtime.threeBlocks,
-            threeBlocksShaderClosure: value.runtime.threeBlocksShaderClosure,
-        },
-        tool: {
-            name: "@three-blocks/devtools",
-            version: value.tool.version,
-            compatibility: value.tool.compatibility,
-            compatibilities: isRecord(value.tool.compatibilities)
-                ? Object.fromEntries(Object.entries(value.tool.compatibilities).filter(([backend]) => backend === "webgpu" || backend === "webgl"))
-                : {},
-            transform: SHADER_TRANSFORM_VERSION,
-            address: SHADER_ADDRESS_VERSION,
-            recipe: SHADER_RECIPE_VERSION,
-            hydration: SHADER_HYDRATION_VERSION,
-        },
-        scenes,
-    };
-}
-function parseManifestObject(template, content) {
-    const manifestBytes = bytes(content);
-    if (manifestBytes.byteLength === 0 ||
-        manifestBytes.byteLength > MAX_MANIFEST_BYTES) {
-        throw new Error(`Shader manifest for "${template}" must contain 1...${MAX_MANIFEST_BYTES} bytes.`);
-    }
-    const source = text(content, `Shader manifest for "${template}"`);
-    const exportDefault = source.indexOf("export default");
-    const firstBrace = source.indexOf("{", exportDefault);
-    const lastBrace = source.lastIndexOf("}");
-    if (exportDefault < 0 || firstBrace < 0 || lastBrace <= firstBrace) {
-        throw new Error(`Shader manifest for "${template}" is not a generated TypeScript manifest module.`);
-    }
-    for (const match of source.matchAll(/^\s*import(?:\s+type)?[\s\S]*?\sfrom\s+['"]([^'"]+)['"];?\s*$/gmu)) {
-        if (match[1] !== "three-blocks/shaders")
-            throw new Error(`Shader manifest for "${template}" imports a non-runtime module.`);
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(source.slice(firstBrace, lastBrace + 1));
-    }
-    catch {
-        throw new Error(`Shader manifest for "${template}" does not contain the deterministic JSON payload emitted by public devtools.`);
-    }
-    if (!isRecord(parsed))
-        throw new Error(`Shader manifest for "${template}" has no object payload.`);
-    return parsed;
-}
-function manifestCoverage(template, content, versions, backend, capturedThreeBlocks) {
-    const manifest = parseManifestObject(template, content);
-    if (manifest.version !== 3 ||
-        manifest.scene !== template ||
-        manifest.three !== versions.three ||
-        manifest.threeBlocks !== capturedThreeBlocks ||
-        !isRecord(manifest.runtime) ||
-        manifest.runtime.id !== SHADER_COMPATIBILITIES[backend] ||
-        manifest.runtime.address !== SHADER_ADDRESS_VERSION ||
-        manifest.runtime.recipe !== SHADER_RECIPE_VERSION ||
-        manifest.runtime.hydration !== SHADER_HYDRATION_VERSION ||
-        !isRecord(manifest.entries)) {
-        throw new Error(`Shader manifest for "${template}" has an incompatible scene, runtime, or schema.`);
-    }
-    const entries = Object.entries(manifest.entries);
-    if (entries.length === 0 || entries.length > MAX_ENTRIES)
-        throw new Error(`Shader manifest for "${template}" must contain 1...${MAX_ENTRIES} entries.`);
-    const states = Array.isArray(manifest.states) ? manifest.states : [];
-    let render = 0;
-    let vertex = 0;
-    let fragment = 0;
-    let compute = 0;
-    for (const [key, stateIndex] of entries) {
-        const state = typeof stateIndex === "number" ? states[stateIndex] : undefined;
-        if (!isRecord(state))
-            throw new Error(`Shader manifest entry "${key}" for "${template}" references an invalid state.`);
-        for (const stage of ["vertex", "fragment", "compute"]) {
-            if (state[stage] !== null && typeof state[stage] !== "number")
-                throw new Error(`Shader manifest entry "${key}" has an invalid ${stage} module reference.`);
-        }
-        const hasVertex = typeof state.vertex === "number";
-        const hasFragment = typeof state.fragment === "number";
-        const hasCompute = typeof state.compute === "number";
-        if (!hasVertex && !hasFragment && !hasCompute)
-            throw new Error(`Shader manifest entry "${key}" has no shader stage.`);
-        if (hasVertex || hasFragment)
-            render++;
-        if (hasVertex)
-            vertex++;
-        if (hasFragment)
-            fragment++;
-        if (hasCompute)
-            compute++;
-    }
-    return { render, vertex, fragment, compute };
-}
-function sameCoverage(left, right) {
-    return (left.render === right.render &&
-        left.vertex === right.vertex &&
-        left.fragment === right.fragment &&
-        left.compute === right.compute);
-}
-function manifestAsset(template, content) {
-    const source = text(content, `Shader manifest for "${template}"`);
-    return `${source.slice(source.indexOf("{", source.indexOf("export default")), source.lastIndexOf("}") + 1)}\n`;
-}
-/** Validate the exact pair emitted by public shader capture before it can become a fresh catalog payload. */
-export function validateShaderArtifactPayload(template, manifest, metadata, versions = COMPATIBILITY_VERSIONS, backend = "webgpu") {
-    const receipt = parseReceipt(template, metadata, versions);
-    const key = shaderReceiptKey(template, backend);
-    const selected = receipt.scenes[key];
-    if (selected === undefined)
-        throw new Error(`Shader receipt for "${key}" is missing.`);
-    if (selected.artifactHash !== sha256(manifest))
-        throw new Error(`Shader manifest checksum for "${key}" does not match metadata.`);
-    if (selected.bytes !== bytes(manifest).byteLength)
-        throw new Error(`Shader manifest byte count for "${key}" does not match metadata.`);
-    if (!sameCoverage(manifestCoverage(template, manifest, versions, backend, receipt.runtime.threeBlocks), selected.coverage)) {
-        throw new Error(`Shader manifest coverage for "${key}" does not match metadata.`);
-    }
-    if (selected.assetHash !== sha256(manifestAsset(template, manifest))) {
-        throw new Error(`Shader public asset checksum for "${key}" does not match metadata.`);
-    }
-    return receipt;
-}
-function nonNegativeDuration(value, label) {
-    if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
-        throw new Error(`${label} must be a non-negative duration.`);
-    }
-    return value;
-}
-function validateShaderTimingPayload(template, content, metadata, receipt) {
-    if (bytes(content).byteLength > MAX_TIMING_BYTES)
-        throw new Error(`Shader timing for "${template}" exceeds ${MAX_TIMING_BYTES} bytes.`);
-    let value;
-    try {
-        value = JSON.parse(text(content, `Shader timing for "${template}"`));
-    }
-    catch (error) {
-        if (error instanceof Error &&
-            error.message.endsWith("must be valid UTF-8."))
-            throw error;
-        throw new Error(`Shader timing for "${template}" is not valid JSON.`);
-    }
-    if (!isRecord(value) ||
-        value.schemaVersion !== 3 ||
-        value.source !== "committed-capture" ||
-        value.receiptHash !== sha256(metadata) ||
-        typeof value.measuredAt !== "string" ||
-        !Number.isFinite(Date.parse(value.measuredAt)) ||
-        typeof value.adapter !== "string" ||
-        value.adapter.length === 0 ||
-        value.adapter.length > 256 ||
-        typeof value.platform !== "string" ||
-        value.platform.length === 0 ||
-        value.platform.length > 256 ||
-        /[\u0000-\u001f\u007f]/u.test(value.adapter) ||
-        /[\u0000-\u001f\u007f]/u.test(value.platform) ||
-        !isRecord(value.scenes)) {
-        throw new Error(`Shader timing for "${template}" is invalid or does not match its receipt.`);
-    }
-    const timingScenes = value.scenes;
-    const keys = Object.keys(receipt.scenes).sort();
-    if (Object.keys(timingScenes).sort().join("\0") !== keys.join("\0") ||
-        keys.some((key) => !isRecord(timingScenes[key]))) {
-        throw new Error(`Shader timing for "${template}" does not cover its receipt matrix.`);
-    }
-    for (const key of keys) {
-        const selected = timingScenes[key];
-        const scene = receipt.scenes[key];
-        const expectedBuilds = scene.coverage.render + scene.coverage.compute;
-        const builds = nonNegativeInteger(selected.builds, `Shader timing builds for "${key}"`);
-        const runs = nonNegativeInteger(selected.runs, `Shader timing runs for "${key}"`);
-        const liveBuildMs = nonNegativeDuration(selected.liveBuildMs, `Shader live timing for "${key}"`);
-        const precompiledBuildMs = nonNegativeDuration(selected.precompiledBuildMs, `Shader precompiled timing for "${key}"`);
-        const avoidedBuildMs = nonNegativeDuration(selected.avoidedBuildMs, `Shader avoided timing for "${key}"`);
-        nonNegativeDuration(selected.spreadMs, `Shader timing spread for "${key}"`);
-        if (builds !== expectedBuilds ||
-            runs < 1 ||
-            Math.abs(avoidedBuildMs - Math.max(0, liveBuildMs - precompiledBuildMs)) > 0.001) {
-            throw new Error(`Shader timing for "${key}" does not match its captured pipelines.`);
-        }
-    }
-}
-export function shaderArtifactPaths(template) {
-    return [
-        `.three-blocks/shaders/${template}.webgpu.ts`,
-        ".three-blocks/shaders/meta.json",
-        ".three-blocks/shaders/timing.json",
-        `public/three-blocks/shaders/${template}.webgpu.json`,
-        `.three-blocks/shaders/${template}.webgl.ts`,
-        `public/three-blocks/shaders/${template}.webgl.json`,
-    ];
-}
-function loadShaderArtifact(template) {
-    const directory = new URL(`../template-assets/shaders/${template}/`, import.meta.url);
-    if (!existsSync(directory))
-        return {
-            status: "pending",
-            files: [],
-            note: "Pending verified shader capture; runtime behavior must not treat this descriptor as fresh.",
-        };
-    const directoryMetadata = lstatSync(directory);
-    if (directoryMetadata.isSymbolicLink() || !directoryMetadata.isDirectory())
-        throw new Error(`Shader template asset root for "${template}" must be a real directory.`);
-    const expected = [
-        `${template}.webgpu.ts`,
-        `${template}.webgl.ts`,
-        "meta.json",
-        "timing.json",
-    ];
-    const entries = readdirSync(directory, { withFileTypes: true });
-    if (entries.length === 0)
-        return {
-            status: "pending",
-            files: [],
-            note: "Pending verified shader capture; runtime behavior must not treat this descriptor as fresh.",
-        };
-    const unexpected = entries
-        .filter((entry) => !expected.includes(entry.name))
-        .map((entry) => entry.name);
-    if (unexpected.length > 0)
-        throw new Error(`Shader payload for "${template}" contains non-allowlisted files: ${unexpected.join(", ")}.`);
-    for (const expectedFile of expected) {
-        const entry = entries.find((candidate) => candidate.name === expectedFile);
-        if (entry === undefined || entry.isSymbolicLink() || !entry.isFile())
-            throw new Error(`Shader payload for "${template}" is incomplete: expected ${expected.join(" and ")}.`);
-    }
-    const webgpuManifest = readFileSync(new URL(`${template}.webgpu.ts`, directory));
-    const webglManifest = readFileSync(new URL(`${template}.webgl.ts`, directory));
-    const metadata = readFileSync(new URL("meta.json", directory));
-    const timing = readFileSync(new URL("timing.json", directory));
-    const metadataValue = JSON.parse(text(metadata, `Shader metadata for "${template}"`));
-    if (isRecord(metadataValue) &&
-        isRecord(metadataValue.runtime) &&
-        metadataValue.runtime.threeBlocksShaderClosure === undefined) {
-        return {
-            status: "pending",
-            files: [],
-            note: "Existing capture predates shader-relevant closure receipts and must be recaptured.",
-        };
-    }
-    const receipt = validateShaderArtifactPayload(template, webgpuManifest, metadata);
-    validateShaderArtifactPayload(template, webglManifest, metadata, COMPATIBILITY_VERSIONS, "webgl");
-    validateShaderTimingPayload(template, timing, metadata, receipt);
-    const selected = receipt.scenes[template];
-    const selectedWebGL = receipt.scenes[`${template}.webgl`];
-    if (selected === undefined)
-        throw new Error(`Shader receipt for "${template}" is missing.`);
-    if (selectedWebGL === undefined)
-        throw new Error(`Shader receipt for "${template}.webgl" is missing.`);
-    const targets = shaderArtifactPaths(template);
-    return {
-        status: "fresh",
-        files: [
-            {
-                path: targets[0],
-                content: webgpuManifest,
-                owner: "generator",
-            },
-            { path: targets[1], content: metadata, owner: "generator" },
-            { path: targets[2], content: timing, owner: "generator" },
-            {
-                path: targets[3],
-                content: manifestAsset(template, webgpuManifest),
-                owner: "generator",
-            },
-            {
-                path: targets[4],
-                content: webglManifest,
-                owner: "generator",
-            },
-            {
-                path: targets[5],
-                content: manifestAsset(template, webglManifest),
-                owner: "generator",
-            },
-        ],
-        note: `Captured complete ${template} template for WebGPU and WebGL.`,
-    };
-}
-const SHADER_ARTIFACTS = Object.freeze(Object.fromEntries(TEMPLATE_NAMES.map((template) => [
-    template,
-    loadShaderArtifact(template),
-])));
-export function shaderArtifactFiles(template) {
-    return SHADER_ARTIFACTS[template].files;
-}
-export function shaderArtifactState(template) {
-    const artifact = SHADER_ARTIFACTS[template];
-    return { status: artifact.status, note: artifact.note };
-}
-/** Prove that a fresh payload was captured from the exact fully composed generated template. */
-export function validateShaderArtifactProject(template, files, versions) {
-    const targets = shaderArtifactPaths(template);
-    const manifest = files.get(targets[0]);
-    const metadata = files.get(targets[1]);
-    const timing = files.get(targets[2]);
-    const asset = files.get(targets[3]);
-    const webglManifest = files.get(targets[4]);
-    const webglAsset = files.get(targets[5]);
-    if (manifest === undefined ||
-        metadata === undefined ||
-        timing === undefined ||
-        asset === undefined ||
-        webglManifest === undefined ||
-        webglAsset === undefined) {
-        throw new Error(`Fresh shader artifact for "${template}" is missing its allowlisted manifest, metadata, timing, or public asset.`);
-    }
-    const receipt = validateShaderArtifactPayload(template, manifest.content, metadata.content, versions);
-    validateShaderArtifactPayload(template, webglManifest.content, metadata.content, versions, "webgl");
-    validateShaderTimingPayload(template, timing.content, metadata.content, receipt);
-    const selected = receipt.scenes[template];
-    const selectedWebGL = receipt.scenes[`${template}.webgl`];
-    if (selected === undefined)
-        throw new Error(`Shader receipt for "${template}" is missing.`);
-    if (selectedWebGL === undefined)
-        throw new Error(`Shader receipt for "${template}.webgl" is missing.`);
-    if (selected.assetHash !== sha256(asset.content)) {
-        throw new Error(`Fresh shader public asset for "${template}" does not match its receipt.`);
-    }
-    if (selectedWebGL.assetHash !== sha256(webglAsset.content)) {
-        throw new Error(`Fresh shader public asset for "${template}.webgl" does not match its receipt.`);
-    }
-    const current = snapshotGeneratedShaderInputs(files);
-    // Receipts hash the exact composed source bytes. Keep hash-relevant inputs
-    // ASCII so character representation stays explicit and stable across editors,
-    // archives, and capture runtimes; write other characters as source escapes.
-    for (const input of Object.keys(current)) {
-        const file = files.get(input);
-        if (file === undefined)
-            continue;
-        const content = typeof file.content === "string"
-            ? Buffer.from(file.content)
-            : file.content;
-        if (content.some((byte) => byte > 0x7f)) {
-            throw new Error(`Shader semantic input "${input}" for "${template}" contains non-ASCII bytes; embed them as escape sequences so composition is runtime-independent.`);
-        }
-    }
-    const recorded = selected.inputs;
-    const changed = Object.keys(current).filter((input) => recorded[input] !== current[input]);
-    const removed = Object.keys(recorded).filter((input) => !Object.hasOwn(current, input));
-    if (changed.length > 0 || removed.length > 0) {
-        throw new Error(`Fresh shader artifact for "${template}" does not match its composed semantic inputs` +
-            ` (${changed.length} added/changed: ${changed.join(", ") || "none"};` +
-            ` ${removed.length} removed: ${removed.join(", ") || "none"}).`);
-    }
-}
 function textPayload(relativePath) {
     return {
         path: relativePath,