@aura3d/engine 3.0.1 → 4.0.0

package/dist/rendering/program/MaterialFeatures.d.ts

@@ -0,0 +1,66 @@
+/**
+ * `program/MaterialFeatures.ts` (PRD-01 §15 Phase-3) — material → C-02 record.
+ *
+ * `defaultProgramFeatures(material, ctx)` derives the record every allow-listed
+ * material produces from its parameters, so `Material.programFeatures(ctx)`
+ * has a real default instead of a per-subclass override:
+ *   lighting    — `lit` for PBR-family shaderKeys, `unlit` otherwise
+ *   maps        — `u_<slot>Texture` TextureBinding with a texture bound;
+ *                 `u_<slot>TextureTexCoord` selects uvSet; a bound transform
+ *                 sets `transform`
+ *   alphaMode   — `blend`/`blendMode!=="opaque"` → "blend",
+ *                 `u_alphaCutoff > 0` → "mask", else "opaque"
+ *   doubleSided — `renderState.cullMode === "none"`
+ *   vertexColors/instancing/skinning/morph — from `requiredAttributes`
+ *   extensions  — extension factor params > 0 → `MaterialExtensionFeature`s
+ *                 (lobe chunks come from `materialLobes(flags)`; an unregistered
+ *                 extension records `extension-lobe-pending` at generate time)
+ *
+ * Allow-list: materials outside `ALLOWLIST_PROGRAM_SHADERS` keep `shaderKey`
+ * (the ForwardPass flag-off path). `materialFeatureWarning` returns the
+ * "nearest superset" note for an allow-listed shader with unrecognized state.
+ */
+import type { Material } from "../Material.js";
+import type { ProgramFeatures } from "../contracts/program.js";
+import type { MaterialFeatureContext } from "../contracts/materialLobes.js";
+type FeatureRecord = Omit<ProgramFeatures, "lights" | "shadows" | "environment" | "fog" | "pass" | "target" | "backgroundCoverage">;
+/** Shader keys the generated-program path covers (the §15 allow-list). */
+export declare const ALLOWLIST_PROGRAM_SHADERS: ReadonlySet<string>;
+export declare function defaultProgramFeatures(material: Material, ctx: MaterialFeatureContext): FeatureRecord;
+/** Geometry attribute presence test, by shader name (`a_uv`, `a_joints`, …). */
+export type GeometryAttributeTest = (shaderName: string) => boolean;
+/** True when the geometry carries a full skin (joints + weights). */
+export declare function geometryHasSkin(has: GeometryAttributeTest): boolean;
+/**
+ * #867 (games): the program's feature set follows the geometry, as in
+ * three.js. A primitive or procedural mesh with no `a_uv` cannot sample
+ * uv-set-0 maps (they and the extension lobe maps are dropped); no `a_uv1`
+ * drops uv-set-1 maps; no `a_color` drops vertex colors; no joints/weights
+ * drops skinning segments from `prd06.deform` (morph is texture-driven and
+ * untouched). Normal maps need only uv: the generated program never reads `a_tangent`
+ * (derivative TBN when the geometry has none). Returns `record` itself when
+ * nothing is dropped, so program keys stay stable for complete geometry.
+ */
+export declare function featuresForGeometry<T extends FeatureRecord>(record: T, has: GeometryAttributeTest): T;
+/** Allow-listed shader → covered by the generated path. */
+export declare function materialUsesGeneratedProgram(material: Material): boolean;
+/**
+ * Draw-time route. `core` (A3D_QR_CORE generator): every allow-listed material
+ * is generated. `lobes` (PRD-04 `qrMaterialsLobeProgramsOn`): only
+ * allow-listed materials whose record carries an r185 lobe extension are —
+ * otherwise those lobes never reach the GPU under `materials` alone.
+ */
+export declare function materialRoutesToGeneratedProgram(material: Material, route: {
+    readonly core: boolean;
+    readonly lobes: boolean;
+}, ctx: MaterialFeatureContext): boolean;
+/**
+ * §15: "nearest superset" warning when an allow-listed material carries state
+ * the feature derivation cannot see. A `shaderVariant` override is the one
+ * such state today (variants are legacy-library axes the generator does not
+ * model) — the feature record describes the base shader, which is a superset
+ * of nothing; warn so the silent-widening rule is observable.
+ */
+export declare function materialFeatureWarning(material: Material): string | null;
+export {};
+//# sourceMappingURL=MaterialFeatures.d.ts.map

package/dist/rendering/program/MaterialFeatures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MaterialFeatures.d.ts","sourceRoot":"","sources":["../../../../../packages/rendering/src/program/MaterialFeatures.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,KAAK,EAA4B,eAAe,EAAsB,MAAM,sBAAsB,CAAC;AAC1G,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AAGzE,KAAK,aAAa,GAAG,IAAI,CAAC,eAAe,EAAE,QAAQ,GAAG,SAAS,GAAG,aAAa,GAAG,KAAK,GAAG,MAAM,GAAG,QAAQ,GAAG,oBAAoB,CAAC,CAAC;AA+CpI,0EAA0E;AAC1E,eAAO,MAAM,yBAAyB,EAAE,WAAW,CAAC,MAAM,CAUxD,CAAC;AAkBH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,sBAAsB,GAAG,aAAa,CA8CrG;AAED,gFAAgF;AAChF,MAAM,MAAM,qBAAqB,GAAG,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC;AAEpE,qEAAqE;AACrE,wBAAgB,eAAe,CAAC,GAAG,EAAE,qBAAqB,GAAG,OAAO,CAEnE;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,aAAa,EAAE,MAAM,EAAE,CAAC,EAAE,GAAG,EAAE,qBAAqB,GAAG,CAAC,CA+CrG;AAED,2DAA2D;AAC3D,wBAAgB,4BAA4B,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAExE;AAED;;;;;GAKG;AACH,wBAAgB,gCAAgC,CAC9C,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,EAC1D,GAAG,EAAE,sBAAsB,GAC1B,OAAO,CAIT;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,GAAG,IAAI,CAMxE"}

package/dist/rendering/program/MaterialFeatures.js

@@ -0,0 +1,242 @@
+/**
+ * `program/MaterialFeatures.ts` (PRD-01 §15 Phase-3) — material → C-02 record.
+ *
+ * `defaultProgramFeatures(material, ctx)` derives the record every allow-listed
+ * material produces from its parameters, so `Material.programFeatures(ctx)`
+ * has a real default instead of a per-subclass override:
+ *   lighting    — `lit` for PBR-family shaderKeys, `unlit` otherwise
+ *   maps        — `u_<slot>Texture` TextureBinding with a texture bound;
+ *                 `u_<slot>TextureTexCoord` selects uvSet; a bound transform
+ *                 sets `transform`
+ *   alphaMode   — `blend`/`blendMode!=="opaque"` → "blend",
+ *                 `u_alphaCutoff > 0` → "mask", else "opaque"
+ *   doubleSided — `renderState.cullMode === "none"`
+ *   vertexColors/instancing/skinning/morph — from `requiredAttributes`
+ *   extensions  — extension factor params > 0 → `MaterialExtensionFeature`s
+ *                 (lobe chunks come from `materialLobes(flags)`; an unregistered
+ *                 extension records `extension-lobe-pending` at generate time)
+ *
+ * Allow-list: materials outside `ALLOWLIST_PROGRAM_SHADERS` keep `shaderKey`
+ * (the ForwardPass flag-off path). `materialFeatureWarning` returns the
+ * "nearest superset" note for an allow-listed shader with unrecognized state.
+ */
+import { isTextureBinding } from "../TextureBinding.js";
+// Lit iff the shader key names a PBR or skinned-lit program ("unlit" must not match).
+const LIT_SHADER_MARKERS = /pbr|skinned-lit/i;
+/** Texture parameter → maps slot. */
+const MAP_PARAMS = [
+    ["u_baseColorTexture", "baseColor"],
+    ["u_normalTexture", "normal"],
+    ["u_metallicRoughnessTexture", "metallicRoughness"],
+    ["u_occlusionTexture", "occlusion"],
+    ["u_emissiveTexture", "emissive"]
+];
+/** Extension factor parameter → glTF extension id (C-03). */
+const EXTENSION_PARAMS = [
+    ["u_clearcoatFactor", "KHR_materials_clearcoat"],
+    ["u_anisotropyStrength", "KHR_materials_anisotropy"],
+    ["u_iridescenceFactor", "KHR_materials_iridescence"],
+    ["u_transmissionFactor", "KHR_materials_transmission"],
+    ["u_volumeThicknessFactor", "KHR_materials_volume"],
+    ["u_diffuseTransmissionFactor", "KHR_materials_diffuse_transmission"],
+    ["u_dispersion", "KHR_materials_dispersion"]
+];
+const SPECIAL_EXTENSIONS = ["KHR_materials_sheen", "KHR_materials_ior", "KHR_materials_specular", "KHR_materials_emissive_strength"];
+/** Extensions whose presence test is not a plain `param > 0`. */
+function specialExtensionPresent(material, glTF) {
+    const num = (n) => (typeof material.getParameter(n) === "number" ? material.getParameter(n) : undefined);
+    switch (glTF) {
+        case "KHR_materials_sheen": {
+            const color = material.getParameter("u_sheenColorFactor");
+            const anyColor = (Array.isArray(color) || color instanceof Float32Array) && [...color].some((c) => c > 0);
+            return anyColor === true || (num("u_sheenRoughnessFactor") ?? 0) > 0;
+        }
+        case "KHR_materials_ior":
+            return (num("u_ior") ?? 1.5) !== 1.5;
+        case "KHR_materials_specular":
+            return (num("u_specularFactor") ?? 1) < 1;
+        case "KHR_materials_emissive_strength":
+            return (num("u_emissiveStrength") ?? 1) > 1;
+        default:
+            return false;
+    }
+}
+/** Shader keys the generated-program path covers (the §15 allow-list). */
+export const ALLOWLIST_PROGRAM_SHADERS = new Set([
+    "aura3d/pbr-direct",
+    "aura3d/instanced-pbr",
+    "aura3d/pbr-textured",
+    "aura3d/pbr-normal-map",
+    "aura3d/skinned-lit",
+    "aura3d/skinned-lit-8",
+    "aura3d/unlit",
+    "aura3d/textured-unlit",
+    "aura3d/instanced-unlit"
+]);
+function paramNumber(material, name) {
+    const v = material.getParameter(name);
+    return typeof v === "number" ? v : undefined;
+}
+function mapSlot(material, param) {
+    const binding = material.getParameter(param);
+    if (!isTextureBinding(binding) || binding.texture === undefined)
+        return undefined;
+    const texCoord = paramNumber(material, `${param}TexCoord`);
+    const transform = material.getParameter(`${param}Transform`);
+    const hasTransform = transform !== undefined &&
+        !(Array.isArray(transform) && transform.length >= 8 && transform.every((v, i) => v === (i % 4 === 0 || i === 4 ? 1 : 0)));
+    return { uvSet: texCoord === 1 ? 1 : 0, transform: hasTransform };
+}
+export function defaultProgramFeatures(material, ctx) {
+    const maps = {};
+    for (const [param, slot] of MAP_PARAMS) {
+        const feature = mapSlot(material, param);
+        if (feature)
+            maps[slot] = feature;
+    }
+    const extensions = [];
+    const push = (glTF) => {
+        if (!extensions.some((e) => e.lobe === glTF))
+            extensions.push({ lobe: glTF, maps: [], bits: {} });
+    };
+    for (const [param, glTF] of EXTENSION_PARAMS) {
+        const value = paramNumber(material, param);
+        if (value !== undefined && value > 0)
+            push(glTF);
+    }
+    for (const glTF of SPECIAL_EXTENSIONS) {
+        if (specialExtensionPresent(material, glTF))
+            push(glTF);
+    }
+    const attrs = new Set(material.requiredAttributes);
+    const skinned = attrs.has("a_joints");
+    const instanced = attrs.has("a_instanceMatrix0") || attrs.has("a_instanceMatrix") || /instanced/i.test(material.shaderKey);
+    const alphaCutoff = paramNumber(material, "u_alphaCutoff") ?? 0;
+    const transparent = material.renderState.blend === true || (material.renderState.blendMode !== undefined && material.renderState.blendMode !== "opaque");
+    const features = {};
+    if (skinned)
+        features["prd06.deform"] = true;
+    void ctx;
+    return {
+        lighting: LIT_SHADER_MARKERS.test(material.shaderKey) ? "lit" : "unlit",
+        maps,
+        extensions,
+        alphaMode: transparent ? "blend" : alphaCutoff > 0 ? "mask" : "opaque",
+        doubleSided: material.renderState.cullMode === "none",
+        vertexColors: attrs.has("a_color"),
+        flatShading: paramNumber(material, "u_flatShading") === 1,
+        // PRD-01 §8.3: Lambert by default (glTF / three.js); Burley is opt-in
+        // (`u_diffuseModel = 1` → DIFFUSE_BURLEY). 01-GENTEST / C-02 + C-03.
+        diffuseModel: paramNumber(material, "u_diffuseModel") === 1 ? "burley" : "lambert",
+        specularAntialiasing: paramNumber(material, "u_specularAntialiasing") !== 0,
+        skinning: skinned ? { influences: attrs.has("a_joints1") ? 8 : 4, palette: "uniform" } : undefined,
+        morph: attrs.has("a_morphTarget") ? { targetBucket: 4, normals: attrs.has("a_morphNormal"), tangents: attrs.has("a_morphTangent") } : undefined,
+        instancing: instanced ? { color: attrs.has("a_instanceColor") } : undefined,
+        features
+    };
+}
+/** True when the geometry carries a full skin (joints + weights). */
+export function geometryHasSkin(has) {
+    return has("a_joints") && has("a_weights");
+}
+/**
+ * #867 (games): the program's feature set follows the geometry, as in
+ * three.js. A primitive or procedural mesh with no `a_uv` cannot sample
+ * uv-set-0 maps (they and the extension lobe maps are dropped); no `a_uv1`
+ * drops uv-set-1 maps; no `a_color` drops vertex colors; no joints/weights
+ * drops skinning segments from `prd06.deform` (morph is texture-driven and
+ * untouched). Normal maps need only uv: the generated program never reads `a_tangent`
+ * (derivative TBN when the geometry has none). Returns `record` itself when
+ * nothing is dropped, so program keys stay stable for complete geometry.
+ */
+export function featuresForGeometry(record, has) {
+    const uv0 = has("a_uv");
+    const uv1 = has("a_uv1");
+    const skin = geometryHasSkin(has);
+    let changed = false;
+    const maps = {};
+    for (const [slot, feature] of Object.entries(record.maps)) {
+        if (!feature)
+            continue;
+        if ((feature.uvSet === 1 ? uv1 : uv0))
+            maps[slot] = feature;
+        else
+            changed = true;
+    }
+    const extensions = uv0
+        ? record.extensions
+        : record.extensions.map((ext) => {
+            if (ext.maps.length === 0)
+                return ext;
+            changed = true;
+            return { ...ext, maps: [] };
+        });
+    const vertexColors = record.vertexColors && has("a_color");
+    if (vertexColors !== record.vertexColors)
+        changed = true;
+    const extraSkin = skin && has("a_joints1") && has("a_weights1");
+    const skinning = skin
+        ? record.skinning?.influences === 8 && !extraSkin
+            ? { ...record.skinning, influences: 4 }
+            : record.skinning
+        : undefined;
+    if (skinning !== record.skinning)
+        changed = true;
+    let features = record.features;
+    const deform = features["prd06.deform"];
+    if (deform !== undefined) {
+        // Selection may combine skinning and texture-driven morphs. Dropping the
+        // whole feature for a geometry without joint attributes freezes morphs.
+        const masked = typeof deform === "string"
+            ? deform.split("|").flatMap((part) => {
+                if (part === "skin4" || part === "skin8")
+                    return skin ? [part === "skin8" && !extraSkin ? "skin4" : part] : [];
+                return [part];
+            }).join("|") || undefined
+            : skin ? deform : undefined;
+        if (masked !== deform) {
+            features = { ...features };
+            if (masked === undefined)
+                delete features["prd06.deform"];
+            else
+                features = { ...features, "prd06.deform": masked };
+            changed = true;
+        }
+    }
+    if (!changed)
+        return record;
+    return { ...record, maps, extensions, vertexColors, skinning, features };
+}
+/** Allow-listed shader → covered by the generated path. */
+export function materialUsesGeneratedProgram(material) {
+    return ALLOWLIST_PROGRAM_SHADERS.has(material.shaderKey);
+}
+/**
+ * Draw-time route. `core` (A3D_QR_CORE generator): every allow-listed material
+ * is generated. `lobes` (PRD-04 `qrMaterialsLobeProgramsOn`): only
+ * allow-listed materials whose record carries an r185 lobe extension are —
+ * otherwise those lobes never reach the GPU under `materials` alone.
+ */
+export function materialRoutesToGeneratedProgram(material, route, ctx) {
+    if (!materialUsesGeneratedProgram(material))
+        return false;
+    if (route.core)
+        return true;
+    return route.lobes && material.programFeatures(ctx).extensions.length > 0;
+}
+/**
+ * §15: "nearest superset" warning when an allow-listed material carries state
+ * the feature derivation cannot see. A `shaderVariant` override is the one
+ * such state today (variants are legacy-library axes the generator does not
+ * model) — the feature record describes the base shader, which is a superset
+ * of nothing; warn so the silent-widening rule is observable.
+ */
+export function materialFeatureWarning(material) {
+    if (!materialUsesGeneratedProgram(material))
+        return null;
+    if (material.shaderVariant !== undefined) {
+        return `material "${material.name}" (${material.shaderKey}) sets shaderVariant "${material.shaderVariant}" — the generated-program path does not model variants; the base feature record (a strict superset's complement) is used`;
+    }
+    return null;
+}
+//# sourceMappingURL=MaterialFeatures.js.map

package/dist/rendering/program/MaterialFeatures.js.map

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

package/dist/rendering/program/ProgramCache.d.ts

@@ -0,0 +1,83 @@
+/**
+ * `program/ProgramCache.ts` (PRD-01 §6.4) — real `ProgramCacheLike`.
+ *
+ * `acquire` normalizes + keys the record, returns the cached handle when
+ * present, otherwise generates through `generateProgramImpl` and compiles:
+ *   - async path (KHR_parallel_shader_compile polling) when
+ *     `o.parallelCompile ?? device.probe?.parallelShaderCompile` and the
+ *     device implements `compileAsync` — the handle starts `pending` and
+ *     flips `ready`/`failed` when the promise settles;
+ *   - sync path otherwise (`createShaderProgram` blocks, handle is
+ *     `ready`/`failed` immediately — "warm-then-block" stays the default).
+ *
+ * `precompile` awaits every pending entry (what `ProgramWarmup`/`app.ready`
+ * await). Stats accumulate `compiled`/`pending`/`failed`/`compileMsTotal`.
+ */
+import type { QrFlags } from "../contracts/core.js";
+import type { ProgramFeatures, ProgramHandle, ProgramCacheLike } from "../contracts/program.js";
+import type { RenderDevice } from "../RenderDevice.js";
+import { type GenerateProgramOptions } from "./ProgramGenerator.js";
+export interface ProgramCacheOptions {
+    /** When true, `generateProgramImpl` resolves registered feature contributors. */
+    readonly flags?: QrFlags;
+    /** When unset, falls back to `device.probe?.parallelShaderCompile`. */
+    readonly parallelCompile?: boolean;
+    /** Sink for generator degradations (e.g. extension-lobe-pending). */
+    readonly onDegradation?: GenerateProgramOptions["onDegradation"];
+    /**
+     * T0-06 (§403): bound on synchronous compiles issued inside one frame epoch
+     * (`beginFrame` resets it). Beyond the bound a new entry stays `pending`
+     * without a compile — the next frame's `acquire` retries it. Async
+     * (`compileAsync`) compiles do not count against the bound.
+     */
+    readonly maxSyncCompilesPerFrame?: number;
+}
+export declare class ProgramCache implements ProgramCacheLike {
+    private readonly device;
+    private readonly options;
+    private readonly entries;
+    private readonly parallel;
+    private readonly maxSyncCompilesPerFrame;
+    private compileMsTotal;
+    private reuseCount;
+    private disposed;
+    private frameSyncCompiles;
+    private readyMarked;
+    private compiledSinceReadyCount;
+    constructor(device: RenderDevice, options?: ProgramCacheOptions);
+    /** T0-06: start of a frame's sync-compile budget. */
+    beginFrame(): void;
+    /** T0-06: mark the ready barrier — later compiles count `compiledSinceReady`. */
+    markReady(): void;
+    private noteCompiled;
+    acquire(features: ProgramFeatures): ProgramHandle;
+    precompile(list: readonly ProgramFeatures[]): Promise<void>;
+    stats(): {
+        readonly compiled: number;
+        readonly pending: number;
+        readonly failed: number;
+        readonly compileMsTotal: number;
+        readonly compiledSinceReady: number;
+    };
+    /** PRD-01 Phase 6 C-31: introspection for the lane's `programs` section. */
+    keys(): readonly string[];
+    /** Acquires served from an existing entry (cache hits). */
+    get reused(): number;
+    dispose(): void;
+    /**
+     * T0-03/C-36: one `program-compile-failed` degradation + one console.error
+     * per failed key, recorded when the entry first flips to `failed` (repeat
+     * acquires reuse the entry and never re-report).
+     */
+    private reportCompileFailure;
+    /** Return the live entry so a held "pending" handle observes the flip to ready/failed. */
+    private toHandle;
+}
+/**
+ * Error text for a failed program (T0-03/C-36). It appends the driver info log
+ * and the stage from `RenderDeviceError.details`, so a remote run (strict
+ * throw, console.error, C-36 degradation) says which line failed and why
+ * instead of only "WebGL shader compile failed".
+ */
+export declare function describeCompileError(error: unknown): string;
+//# sourceMappingURL=ProgramCache.d.ts.map

package/dist/rendering/program/ProgramCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProgramCache.d.ts","sourceRoot":"","sources":["../../../../../packages/rendering/src/program/ProgramCache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC7F,OAAO,KAAK,EAAE,YAAY,EAAsC,MAAM,iBAAiB,CAAC;AACxF,OAAO,EAAwE,KAAK,sBAAsB,EAA2B,MAAM,oBAAoB,CAAC;AAYhK,MAAM,WAAW,mBAAmB;IAClC,iFAAiF;IACjF,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,uEAAuE;IACvE,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC,qEAAqE;IACrE,QAAQ,CAAC,aAAa,CAAC,EAAE,sBAAsB,CAAC,eAAe,CAAC,CAAC;IACjE;;;;;OAKG;IACH,QAAQ,CAAC,uBAAuB,CAAC,EAAE,MAAM,CAAC;CAC3C;AAED,qBAAa,YAAa,YAAW,gBAAgB;IAYjD,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAZ1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiC;IACzD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAU;IACnC,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAS;IACjD,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,uBAAuB,CAAK;gBAGjB,MAAM,EAAE,YAAY,EACpB,OAAO,GAAE,mBAAwB;IAMpD,qDAAqD;IACrD,UAAU,IAAI,IAAI;IAIlB,iFAAiF;IACjF,SAAS,IAAI,IAAI;IAIjB,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,QAAQ,EAAE,eAAe,GAAG,aAAa;IAoE3C,UAAU,CAAC,IAAI,EAAE,SAAS,eAAe,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAWjE,KAAK,IAAI;QAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAA;KAAE;IAY/J,4EAA4E;IAC5E,IAAI,IAAI,SAAS,MAAM,EAAE;IAIzB,2DAA2D;IAC3D,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,OAAO,IAAI,IAAI;IASf;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IAQ5B,0FAA0F;IAC1F,OAAO,CAAC,QAAQ;CAGjB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAO3D"}

package/dist/rendering/program/ProgramCache.js

@@ -0,0 +1,194 @@
+/**
+ * `program/ProgramCache.ts` (PRD-01 §6.4) — real `ProgramCacheLike`.
+ *
+ * `acquire` normalizes + keys the record, returns the cached handle when
+ * present, otherwise generates through `generateProgramImpl` and compiles:
+ *   - async path (KHR_parallel_shader_compile polling) when
+ *     `o.parallelCompile ?? device.probe?.parallelShaderCompile` and the
+ *     device implements `compileAsync` — the handle starts `pending` and
+ *     flips `ready`/`failed` when the promise settles;
+ *   - sync path otherwise (`createShaderProgram` blocks, handle is
+ *     `ready`/`failed` immediately — "warm-then-block" stays the default).
+ *
+ * `precompile` awaits every pending entry (what `ProgramWarmup`/`app.ready`
+ * await). Stats accumulate `compiled`/`pending`/`failed`/`compileMsTotal`.
+ */
+import { generateProgramImpl, GENERATED_PROGRAM_MARKER, programDegradationLog } from "./ProgramGenerator.js";
+import { normalizeProgramFeatures } from "./ProgramFeatures.js";
+import { programKey } from "./ProgramKey.js";
+export class ProgramCache {
+    device;
+    options;
+    entries = new Map();
+    parallel;
+    maxSyncCompilesPerFrame;
+    compileMsTotal = 0;
+    reuseCount = 0;
+    disposed = false;
+    frameSyncCompiles = 0;
+    readyMarked = false;
+    compiledSinceReadyCount = 0;
+    constructor(device, options = {}) {
+        this.device = device;
+        this.options = options;
+        this.parallel = options.parallelCompile ?? device.probe?.parallelShaderCompile ?? false;
+        this.maxSyncCompilesPerFrame = options.maxSyncCompilesPerFrame ?? 8;
+    }
+    /** T0-06: start of a frame's sync-compile budget. */
+    beginFrame() {
+        this.frameSyncCompiles = 0;
+    }
+    /** T0-06: mark the ready barrier — later compiles count `compiledSinceReady`. */
+    markReady() {
+        this.readyMarked = true;
+    }
+    noteCompiled() {
+        if (this.readyMarked)
+            this.compiledSinceReadyCount += 1;
+    }
+    acquire(features) {
+        const normalized = normalizeProgramFeatures(features);
+        const key = programKey(normalized);
+        const existing = this.entries.get(key);
+        if (existing && (existing.status !== "pending" || existing.pending !== undefined)) {
+            this.reuseCount += 1;
+            return this.toHandle(existing);
+        }
+        // A pending entry with no in-flight promise was bounded out by the T0-06
+        // per-frame sync-compile bound — fall through to retry under this frame's
+        // budget (or the async path).
+        const entry = existing ?? { key, status: "pending" };
+        if (!existing)
+            this.entries.set(key, entry);
+        const started = Date.now();
+        let sources;
+        try {
+            const generated = generateProgramImpl(normalized, {
+                flags: this.options.flags,
+                onDegradation: this.options.onDegradation
+            });
+            sources = {
+                label: `a3d-program:${key.slice(0, 40)}`,
+                marker: GENERATED_PROGRAM_MARKER,
+                vertex: generated.vertex,
+                fragment: generated.fragment
+            };
+        }
+        catch (error) {
+            entry.status = "failed";
+            entry.error = describeCompileError(error);
+            this.reportCompileFailure(entry);
+            return this.toHandle(entry);
+        }
+        if (this.parallel && typeof this.device.compileAsync === "function") {
+            entry.pending = this.device.compileAsync(sources)
+                .then((program) => {
+                entry.status = "ready";
+                entry.program = program;
+                this.compileMsTotal += Date.now() - started;
+                this.noteCompiled();
+            })
+                .catch((error) => {
+                entry.status = "failed";
+                entry.error = describeCompileError(error);
+                this.reportCompileFailure(entry);
+                this.compileMsTotal += Date.now() - started;
+            });
+        }
+        else {
+            if (this.frameSyncCompiles >= this.maxSyncCompilesPerFrame) {
+                // T0-06 per-frame bound: leave the entry pending (no compile, no
+                // promise); the next frame's `acquire` retries under a fresh budget.
+                return this.toHandle(entry);
+            }
+            this.frameSyncCompiles += 1;
+            try {
+                entry.program = this.device.createShaderProgram(sources);
+                entry.status = "ready";
+                this.noteCompiled();
+            }
+            catch (error) {
+                entry.status = "failed";
+                entry.error = describeCompileError(error);
+                this.reportCompileFailure(entry);
+            }
+            this.compileMsTotal += Date.now() - started;
+        }
+        return this.toHandle(entry);
+    }
+    async precompile(list) {
+        const pending = [];
+        for (const features of list) {
+            this.acquire(features);
+        }
+        for (const entry of this.entries.values()) {
+            if (entry.pending)
+                pending.push(entry.pending);
+        }
+        await Promise.all(pending);
+    }
+    stats() {
+        let compiled = 0;
+        let pending = 0;
+        let failed = 0;
+        for (const entry of this.entries.values()) {
+            if (entry.status === "ready")
+                compiled++;
+            else if (entry.status === "pending")
+                pending++;
+            else
+                failed++;
+        }
+        return { compiled, pending, failed, compileMsTotal: this.compileMsTotal, compiledSinceReady: this.compiledSinceReadyCount };
+    }
+    /** PRD-01 Phase 6 C-31: introspection for the lane's `programs` section. */
+    keys() {
+        return [...this.entries.keys()];
+    }
+    /** Acquires served from an existing entry (cache hits). */
+    get reused() {
+        return this.reuseCount;
+    }
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        for (const entry of this.entries.values()) {
+            entry.program?.dispose();
+        }
+        this.entries.clear();
+    }
+    /**
+     * T0-03/C-36: one `program-compile-failed` degradation + one console.error
+     * per failed key, recorded when the entry first flips to `failed` (repeat
+     * acquires reuse the entry and never re-report).
+     */
+    reportCompileFailure(entry) {
+        const message = `generated program failed to compile (key ${entry.key}): ${entry.error ?? "unknown error"}`;
+        const degradation = { code: "program-compile-failed", message, ownerPrd: 1 };
+        programDegradationLog.push(degradation);
+        this.options.onDegradation?.(degradation);
+        console.error(`[prd01] ${message}`);
+    }
+    /** Return the live entry so a held "pending" handle observes the flip to ready/failed. */
+    toHandle(entry) {
+        return entry;
+    }
+}
+/**
+ * Error text for a failed program (T0-03/C-36). It appends the driver info log
+ * and the stage from `RenderDeviceError.details`, so a remote run (strict
+ * throw, console.error, C-36 degradation) says which line failed and why
+ * instead of only "WebGL shader compile failed".
+ */
+export function describeCompileError(error) {
+    if (!(error instanceof Error))
+        return String(error);
+    const details = error.details;
+    const log = typeof details?.log === "string" ? details.log.trim() : "";
+    if (!log)
+        return error.message;
+    const stage = details?.stage === undefined ? "" : ` [stage ${String(details.stage)}]`;
+    return `${error.message}${stage}: ${log.length > 1200 ? `${log.slice(0, 1200)}…` : log}`;
+}
+//# sourceMappingURL=ProgramCache.js.map

package/dist/rendering/program/ProgramCache.js.map

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

package/dist/rendering/program/ProgramFeatures.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `ProgramFeatures` helpers (PRD-01 §6.4) — canonical feature records.
+ *
+ * `computeProgramKey` only sorts keys: `{ maps: {} }` and a record missing
+ * `maps` produce different keys for the same draw. `normalizeProgramFeatures`
+ * fills every field of the frozen C-02 record with canonical defaults and
+ * strips `undefined` leaves, so records built anywhere (materials, depth
+ * passes, warmup) key identically.
+ */
+import type { ProgramFeatures, TextureSlotFeature } from "../contracts/program.js";
+export declare const DEFAULT_SHADOW_RECEIVE: ProgramFeatures["shadows"];
+export declare const DEFAULT_LIGHTS: ProgramFeatures["lights"];
+export declare const DEFAULT_PROGRAM_FEATURES: ProgramFeatures;
+/** Fill every ProgramFeatures field with canonical defaults; strips undefined leaves. */
+export declare function normalizeProgramFeatures(features: Partial<ProgramFeatures> | undefined): ProgramFeatures;
+/** The light-count keys that bound the unrolled `fragment:lights` loop. */
+export declare function totalLightCount(lights: ProgramFeatures["lights"]): number;
+/** Texture map feature bits → define names, in frozen map order. */
+export declare const MAP_DEFINES: readonly [keyof ProgramFeatures["maps"], string][];
+export declare function mapUvSet(slot: TextureSlotFeature | undefined): 0 | 1;
+//# sourceMappingURL=ProgramFeatures.d.ts.map

package/dist/rendering/program/ProgramFeatures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProgramFeatures.d.ts","sourceRoot":"","sources":["../../../../../packages/rendering/src/program/ProgramFeatures.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAEhF,eAAO,MAAM,sBAAsB,EAAE,eAAe,CAAC,SAAS,CAK7D,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,eAAe,CAAC,QAAQ,CAOpD,CAAC;AAEF,eAAO,MAAM,wBAAwB,EAAE,eAkBtC,CAAC;AAUF,yFAAyF;AACzF,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,SAAS,GAAG,eAAe,CA2BxG;AAED,2EAA2E;AAC3E,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,CAAC,QAAQ,CAAC,GAAG,MAAM,CAEzE;AAED,oEAAoE;AACpE,eAAO,MAAM,WAAW,EAAE,SAAS,CAAC,MAAM,eAAe,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,EAMzE,CAAC;AAEF,wBAAgB,QAAQ,CAAC,IAAI,EAAE,kBAAkB,GAAG,SAAS,GAAG,CAAC,GAAG,CAAC,CAEpE"}