@aura3d/rendering 3.0.0 → 4.0.0

package/dist/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/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/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/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/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/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/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"}

package/dist/program/ProgramFeatures.js

@@ -0,0 +1,95 @@
+/**
+ * `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.
+ */
+export const DEFAULT_SHADOW_RECEIVE = {
+    cascades: 0,
+    pcfTaps: 1,
+    localShadows: 0,
+    contact: false
+};
+export const DEFAULT_LIGHTS = {
+    dir: 0,
+    point: 0,
+    spot: 0,
+    rect: 0,
+    clustered: false,
+    hemisphere: false
+};
+export const DEFAULT_PROGRAM_FEATURES = {
+    pass: "forward",
+    target: "glsl300es",
+    lighting: "unlit",
+    maps: {},
+    extensions: [],
+    alphaMode: "opaque",
+    doubleSided: false,
+    vertexColors: false,
+    flatShading: false,
+    lights: DEFAULT_LIGHTS,
+    shadows: DEFAULT_SHADOW_RECEIVE,
+    environment: "none",
+    fog: "none",
+    diffuseModel: "lambert",
+    specularAntialiasing: false,
+    backgroundCoverage: false,
+    features: {}
+};
+function dropUndefined(value) {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+        if (v !== undefined)
+            out[k] = v;
+    }
+    return out;
+}
+/** Fill every ProgramFeatures field with canonical defaults; strips undefined leaves. */
+export function normalizeProgramFeatures(features) {
+    const f = features ?? {};
+    const lights = dropUndefined({ ...DEFAULT_LIGHTS, ...(f.lights ?? {}) });
+    const shadows = dropUndefined({ ...DEFAULT_SHADOW_RECEIVE, ...(f.shadows ?? {}) });
+    return {
+        pass: f.pass ?? "forward",
+        target: f.target ?? "glsl300es",
+        lighting: f.lighting ?? "unlit",
+        maps: dropUndefined({ ...(f.maps ?? {}) }),
+        extensions: f.extensions ?? [],
+        alphaMode: f.alphaMode ?? "opaque",
+        doubleSided: f.doubleSided ?? false,
+        vertexColors: f.vertexColors ?? false,
+        flatShading: f.flatShading ?? false,
+        skinning: f.skinning,
+        morph: f.morph,
+        instancing: f.instancing,
+        drawId: f.drawId,
+        lights,
+        shadows,
+        environment: f.environment ?? "none",
+        fog: f.fog ?? "none",
+        diffuseModel: f.diffuseModel ?? "lambert",
+        specularAntialiasing: f.specularAntialiasing ?? false,
+        backgroundCoverage: f.backgroundCoverage ?? false,
+        features: { ...(f.features ?? {}) }
+    };
+}
+/** The light-count keys that bound the unrolled `fragment:lights` loop. */
+export function totalLightCount(lights) {
+    return lights.dir + lights.point + lights.spot + lights.rect;
+}
+/** Texture map feature bits → define names, in frozen map order. */
+export const MAP_DEFINES = [
+    ["baseColor", "USE_BASE_COLOR_MAP"],
+    ["normal", "USE_NORMAL_MAP"],
+    ["metallicRoughness", "USE_METALLIC_ROUGHNESS_MAP"],
+    ["occlusion", "USE_OCCLUSION_MAP"],
+    ["emissive", "USE_EMISSIVE_MAP"]
+];
+export function mapUvSet(slot) {
+    return slot?.uvSet ?? 0;
+}
+//# sourceMappingURL=ProgramFeatures.js.map

package/dist/program/ProgramFeatures.js.map

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

package/dist/program/ProgramGenerator.d.ts

@@ -0,0 +1,60 @@
+/**
+ * `program/ProgramGenerator.ts` (PRD-01 §6.4, §8.1, §8.5, §8.7) — C-02 real impl.
+ *
+ * Assembles GLSL ES 3.00 vertex+fragment sources from a normalized
+ * `ProgramFeatures` record:
+ *   `#version 300 es`, precision, `#define` block, lane-01 chunks
+ *   (common/colorspace/brdf/normal/instancing/alpha/lights_legacy/
+ *   indirect_default/fog_default/depth) with registered C-02 chunks spliced
+ *   at the hook points in `(feature.order, feature.id)` order.
+ *
+ * Splice convention (pars/call split, T0-05): a ShaderFeature's `chunks[i]`
+ * lands at `hooks[min(i, hooks.length - 1)]`.
+ *   - Declaration hooks (`vertex:pars`, `vertex:deform`, `fragment:pars`) emit
+ *     the chunk at global scope before `main`.
+ *   - Body hooks emit the chunk (a *call* chunk: statements only) inside
+ *     `main`; its `requires` closure is emitted at global scope.
+ *   - `requires` are resolved requires-first (depth-first post-order), each
+ *     chunk at most once per stage. `brdf`/`common` name the built-in lane-01
+ *     chunks. A missing or cyclic `requires` throws (`SHADER_CHUNK_MISSING` /
+ *     `SHADER_CHUNK_CYCLE`), which the cache reports as C-36
+ *     `program-compile-failed`. Missing chunks are never skipped silently.
+ *   - `fragment:indirect` contributions are appended after the default
+ *     indirect body (ambient + env); every other body hook that a feature
+ *     claims replaces that hook's default. One exception (E3 stage-2b):
+ *     under A3D_QR_COMPILER ∧ A3D_QR_LIGHTING the `prd02.ibl` contribution
+ *     REPLACES the default indirect body instead of appending to it.
+ * The `vertex:deform` call is canonical: the generator emits
+ * `a3dDeform(pos, nrm, tan)` when a registered feature claims the hook and
+ * the C-18 passthrough otherwise (CONTRACTS §8.5).
+ *
+ * C-03 lobes (lit forward programs): `chunks.pars` is emitted at global scope,
+ * `chunks.fragment` is a call chunk at `fragment:material` (after
+ * `PhysicalMaterial material` exists), and `chunks.ibl` is a call chunk
+ * appended to `fragment:indirect`. A record's extension matches a lobe by
+ * `lobe.id` or `lobe.glTFExtension`. Each active lobe defines
+ * `A3D_LOBE_<ID>` (plus `A3D_LOBE_<ID>_<BIT>` for truthy bits) so chunk
+ * guards follow the record.
+ *
+ * Unknown extensions (`features.extensions` with no matching C-03 lobe in
+ * `materialLobes`) record `extension-lobe-pending` (`ownerPrd: 4`) into
+ * `programDegradationLog` and through the optional sink.
+ */
+import type { QrFlags } from "../contracts/core.js";
+import type { ProgramFeatures, GeneratedProgram } from "../contracts/program.js";
+export declare const GENERATED_PROGRAM_MARKER = "a3d-generated-program";
+export interface ProgramDegradation {
+    readonly code: "extension-lobe-pending" | "program-compile-failed";
+    readonly message: string;
+    readonly ownerPrd?: number;
+}
+/** Process-local log of generator-recorded degradations (drained by diagnostics/tests). */
+export declare const programDegradationLog: ProgramDegradation[];
+export interface GenerateProgramOptions {
+    readonly flags?: QrFlags;
+    readonly onDegradation?: (degradation: ProgramDegradation) => void;
+}
+export declare function registerProgramWgslEmitter(emitter: (features: ProgramFeatures) => GeneratedProgram): void;
+/** Real C-02 program generation (PRD-01 §6.4). Flags may be omitted: feature bits then resolve no contributors. */
+export declare function generateProgramImpl(features: ProgramFeatures, options?: GenerateProgramOptions): GeneratedProgram;
+//# sourceMappingURL=ProgramGenerator.d.ts.map

package/dist/program/ProgramGenerator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProgramGenerator.d.ts","sourceRoot":"","sources":["../../../../../packages/rendering/src/program/ProgramGenerator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,KAAK,EAAkC,eAAe,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAiB9G,eAAO,MAAM,wBAAwB,0BAA0B,CAAC;AAEhE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,wBAAwB,GAAG,wBAAwB,CAAC;IACnE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,2FAA2F;AAC3F,eAAO,MAAM,qBAAqB,EAAE,kBAAkB,EAAO,CAAC;AAE9D,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,WAAW,EAAE,kBAAkB,KAAK,IAAI,CAAC;CACpE;AAID,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,eAAe,KAAK,gBAAgB,GAAG,IAAI,CAEzG;AAmoBD,mHAAmH;AACnH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,eAAe,EAAE,OAAO,GAAE,sBAA2B,GAAG,gBAAgB,CAqCrH"}