@aura3d/rendering 3.0.1 → 4.0.2

package/dist/renderer/FrameGraph.js

@@ -0,0 +1,301 @@
+// C-01 seam (PR 0b) — frame contributor phase-hook dispatcher. CONTRACTS.md §C-01.
+// File: packages/rendering/src/renderer/FrameGraph.ts — owner lane 01.
+//
+// Called from Renderer.render / Renderer.renderAsync at the phase boundaries listed
+// in CONTRACTS.md ("collect" after collectRenderItemsWithDiagnostics, "shadows" after
+// executeRendererShadowMap, "background" between EnvironmentBackgroundPass and
+// ForwardPass, "after-opaque"/"transmission"/"transparent"/"after-transparent" after
+// ForwardPass, "post-hdr" before executePostprocess, "after-output" after it).
+// With zero registered contributors every entry point is a no-op: no passes are
+// added, no draws happen, and the frame is pixel-identical.
+import { Scene, identityMat4 } from "@aura3d/scene";
+import { BaseRenderPass } from "../RenderPass.js";
+import { QUALITY_TIERS } from "../contracts/quality.js";
+import { frameContributors } from "../contracts/frameGraph.js";
+const EMPTY_QR_FLAGS = { values: {}, on: () => false };
+let defaultQrFlags = EMPTY_QR_FLAGS;
+// T0-28: per-renderer flag seam. Flags resolve per device so two mounted
+// renderers with different `a3d-qr` values cannot stampede each other —
+// rasterization decision points (Renderer/ForwardPass) always read through
+// the device. The module-level default remains for ambient readers
+// (back-compat; engine sets it at mount alongside the scoped entry).
+const qrFlagsByDevice = new WeakMap();
+/** Engine-side wiring: set once flags resolve (createAuraApp / createGameApp). */
+export function setRendererQrFlags(flags, device) {
+    if (device)
+        qrFlagsByDevice.set(device, flags);
+    else
+        defaultQrFlags = flags;
+}
+export function rendererQrFlags(device) {
+    return (device ? qrFlagsByDevice.get(device) : undefined) ?? defaultQrFlags;
+}
+/**
+ * T0-28: run `fn` with the ambient default bound to `device`'s scoped flags so
+ * device-less `rendererQrFlags()` readers inside a synchronous frame see this
+ * renderer's flags. No scoped entry → `fn` runs unchanged. Restores after.
+ */
+export function withRendererQrFlags(device, fn) {
+    const scoped = qrFlagsByDevice.get(device);
+    if (!scoped || scoped === defaultQrFlags)
+        return fn();
+    const previous = defaultQrFlags;
+    defaultQrFlags = scoped;
+    try {
+        return fn();
+    }
+    finally {
+        defaultQrFlags = previous;
+    }
+}
+const toF32 = (value) => value instanceof Float32Array ? value : Float32Array.from(value);
+/** Best-effort FrameCamera for the PR 0b stub; PRD 01 publishes real history later. */
+export function toFrameCamera(resolvedCamera, cameraViewProjection, cameraPosition) {
+    if (!resolvedCamera)
+        return null;
+    const cam = resolvedCamera.camera;
+    return {
+        viewMatrix: resolvedCamera.viewMatrix ? toF32(resolvedCamera.viewMatrix) : toF32(identityMat4()),
+        projectionMatrix: cam?.projectionMatrix ? toF32(cam.projectionMatrix) : toF32(identityMat4()),
+        viewProjectionMatrix: toF32(cameraViewProjection ?? resolvedCamera.viewProjectionMatrix),
+        previousViewProjectionMatrix: null,
+        near: cam?.near ?? 0.1,
+        far: cam?.far ?? 1000,
+        projection: cam?.projection ?? "perspective",
+        position: cameraPosition ?? resolvedCamera.cameraPosition ?? [0, 0, 0]
+    };
+}
+/** C-01 blackboard key for the forward color target (R-01-1). */
+export const PRD01_FORWARD_TARGET = "prd01.forwardTarget";
+/** C-13 (Q-03-1): lane 03 publishes grade × auto-exposure here; OutputPass multiplies it in. */
+export const PRD03_EXPOSURE = "prd03.exposure";
+/** C-01 (§8.4 step 1): resolved scene-depth copy target published for after-opaque consumers. */
+export const AURA_SCENE_DEPTH_COPY = "aura.scene.depth.copy";
+class ContributorTransparentPass extends BaseRenderPass {
+    queue;
+    frame;
+    constructor(queue, frame) {
+        super("qr.contributor.transparents", [], ["aura.scene.color"]);
+        this.queue = queue;
+        this.frame = frame;
+    }
+    execute(_context) {
+        for (const item of this.queue) {
+            item.draw(this.frame);
+        }
+    }
+}
+export class RendererFrameHooks {
+    input;
+    flags;
+    blackboard = new Map();
+    frameIndex;
+    timeSeconds;
+    renderSource;
+    constructor(input) {
+        this.input = input;
+        this.flags = input.flags ?? rendererQrFlags(input.device);
+        this.frameIndex = input.frameIndex ?? 0;
+        this.timeSeconds = typeof performance !== "undefined" ? performance.now() / 1000 : Date.now() / 1000;
+        const source = input.source;
+        this.renderSource = source instanceof Scene
+            ? { scene: source }
+            : typeof source === "object" && Symbol.iterator in source
+                ? { renderItems: source }
+                : source;
+    }
+    forwardTarget = null;
+    /**
+     * R-01-1: the Renderer hands the forward color target in after
+     * `ensureForwardColorTarget`; `ctx.sceneDepth` then exposes the real depth
+     * texture and the blackboard publishes it at `"prd01.forwardTarget"`.
+     */
+    setForwardTarget(target) {
+        this.forwardTarget = target;
+    }
+    sceneDepthCopy = null;
+    /** Lane 01 publishes the scene-depth copy target before the after-opaque phase. */
+    setSceneDepthCopy(target) {
+        this.sceneDepthCopy = target;
+        if (target)
+            this.blackboard.set(AURA_SCENE_DEPTH_COPY, target);
+    }
+    /** Read a blackboard value published by a contributor (or lane 01 itself). */
+    blackboardValue(key) {
+        return this.blackboard.get(key);
+    }
+    /**
+     * §6.2.7: publish the frame's forward output encoding as
+     * `"prd01.outputColorSpace"` — "linear" when the frame renders into an HDR
+     * target that a later pass encodes (postprocess chain or OutputPass), else
+     * the legacy in-shader "srgb" encode. Lane passes (particles, beams,
+     * ribbons) read it through `resolveOutputColorSpace`; nothing published it,
+     * so they sRGB/filmic-encoded into the linear HDR target and were encoded a
+     * second time downstream (washed-out, near-white particles).
+     */
+    setOutputColorSpace(space) {
+        this.blackboard.set("prd01.outputColorSpace", space);
+    }
+    context(items) {
+        const depthTexture = this.forwardTarget?.depthTexture ?? null;
+        if (this.forwardTarget) {
+            this.blackboard.set(PRD01_FORWARD_TARGET, this.forwardTarget);
+        }
+        return {
+            device: this.input.device,
+            width: this.input.width,
+            height: this.input.height,
+            frameIndex: this.frameIndex,
+            timeSeconds: this.timeSeconds,
+            camera: this.input.camera,
+            source: this.renderSource,
+            items,
+            tier: this.input.tier ?? QUALITY_TIERS.high,
+            flags: this.flags,
+            sceneDepth: {
+                texture: depthTexture,
+                available: depthTexture !== null,
+                linearize: {
+                    near: this.input.camera?.near ?? 0.1,
+                    far: this.input.camera?.far ?? 1000,
+                    orthographic: this.input.camera?.projection === "orthographic"
+                }
+            },
+            blackboard: this.blackboard
+        };
+    }
+    /** "collect" phase — contributor item-list transforms, applied in order. */
+    collect(items) {
+        const contributors = frameContributors(this.flags);
+        if (contributors.length === 0)
+            return items;
+        let out = items;
+        for (const contributor of contributors) {
+            if (!contributor.phases.includes("collect") || !contributor.collect)
+                continue;
+            const next = contributor.collect([...out], this.context(out));
+            if (next)
+                out = next;
+        }
+        return out;
+    }
+    /** Graph-attached phases — contributor passes appended to the render graph. */
+    addPasses(graph, phase, items) {
+        const contributors = frameContributors(this.flags);
+        if (contributors.length === 0)
+            return;
+        const ctx = this.context(items);
+        // Every contributor's transparent queue rides ONE graph pass: pass names
+        // and resource writers are unique per graph, so a pass per contributor
+        // threw "Render pass already exists" (failing the mount) as soon as two
+        // contributors queued transparents in one frame (particles + beams).
+        const transparentQueue = [];
+        for (const contributor of contributors) {
+            if (!contributor.phases.includes(phase))
+                continue;
+            for (const pass of contributor.passes?.(phase, ctx) ?? []) {
+                assertPhaseSpace(phase, pass, contributor);
+                graph.addPass(pass);
+            }
+            if (phase === "transparent") {
+                const queue = contributor.transparentItems?.(ctx);
+                if (queue && queue.length > 0)
+                    transparentQueue.push(...queue);
+            }
+        }
+        if (transparentQueue.length > 0)
+            graph.addPass(new ContributorTransparentPass(transparentQueue, ctx));
+    }
+    /**
+     * "transparent" phase queue: contributor `TransparentQueueItem`s plus the
+     * context they draw with, so the Renderer can interleave them with forward
+     * transparents by `sortDepth` (§8.4 step 1) instead of drawing them in a
+     * block after the pass. Empty when no contributor emits queue items.
+     */
+    transparentQueues(items) {
+        const ctx = this.context(items);
+        const queues = [];
+        for (const contributor of frameContributors(this.flags)) {
+            if (!contributor.phases.includes("transparent"))
+                continue;
+            const queue = contributor.transparentItems?.(ctx);
+            if (queue)
+                queues.push(...queue);
+        }
+        return { ctx, queues };
+    }
+    /** Contributor `passes("transparent")` only — queue items are handled by transparentQueues(). */
+    addTransparentContributorPasses(graph, items) {
+        const contributors = frameContributors(this.flags);
+        if (contributors.length === 0)
+            return;
+        const ctx = this.context(items);
+        for (const contributor of contributors) {
+            if (!contributor.phases.includes("transparent"))
+                continue;
+            for (const pass of contributor.passes?.("transparent", ctx) ?? []) {
+                graph.addPass(pass);
+            }
+        }
+    }
+    /** Direct phases executed outside the graph (post-hdr, after-output). */
+    runPhase(phase, items, enabled = true) {
+        const contributors = frameContributors(this.flags);
+        if (contributors.length === 0)
+            return;
+        const ctx = this.context(items);
+        const passContext = { device: this.input.device, width: this.input.width, height: this.input.height };
+        for (const contributor of contributors) {
+            if (!contributor.phases.includes(phase))
+                continue;
+            if (!enabled) {
+                if (typeof console !== "undefined")
+                    console.warn(`FRAME_PHASE_SKIPPED:${phase}:${contributor.id}`);
+                continue;
+            }
+            for (const pass of contributor.passes?.(phase, ctx) ?? []) {
+                assertPhaseSpace(phase, pass, contributor);
+                pass.execute(passContext);
+            }
+        }
+    }
+    async runPhaseAsync(phase, items, enabled = true) {
+        const contributors = frameContributors(this.flags);
+        if (contributors.length === 0)
+            return;
+        const ctx = this.context(items);
+        const passContext = { device: this.input.device, width: this.input.width, height: this.input.height };
+        for (const contributor of contributors) {
+            if (!contributor.phases.includes(phase))
+                continue;
+            if (!enabled) {
+                if (typeof console !== "undefined")
+                    console.warn(`FRAME_PHASE_SKIPPED:${phase}:${contributor.id}`);
+                continue;
+            }
+            for (const pass of contributor.passes?.(phase, ctx) ?? []) {
+                assertPhaseSpace(phase, pass, contributor);
+                if (pass.executeAsync) {
+                    await pass.executeAsync(passContext);
+                }
+                else {
+                    pass.execute(passContext);
+                }
+            }
+        }
+    }
+}
+/**
+ * §8.4 step 4 (lane 01's half of C-13): a contributor pass in `post-hdr` that
+ * declares display space is rejected — everything upstream of OutputPass is
+ * linear scene-referred.
+ */
+function assertPhaseSpace(phase, pass, contributor) {
+    if (phase === "post-hdr" && pass.space === "display") {
+        throw new Error(`FRAME_PHASE_SPACE_MISMATCH:${phase}:${contributor.id}:${pass.name}`);
+    }
+}
+export function createRendererFrameHooks(input) {
+    return new RendererFrameHooks(input);
+}
+//# sourceMappingURL=FrameGraph.js.map

package/dist/renderer/FrameGraph.js.map

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

package/dist/renderer/InterleavedTransparentPass.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `renderer/InterleavedTransparentPass.ts` (PRD-01 §9.1 "transparent", C-01) —
+ * the v2 transparent phase: forward transparents and contributor
+ * `TransparentQueueItem`s drawn in one sequence merged by `sortDepth`
+ * (larger = farther; `order` breaks contributor ties), rather than the
+ * contributor queue running as a block after the engine transparents.
+ * Consecutive engine items group into a single `ForwardPass` draw run so the
+ * merge costs nothing when no contributor emits queue items.
+ */
+import { type ForwardPassOptions, type RenderItem } from "../ForwardPass.js";
+import { BaseRenderPass, type RenderPassContext } from "../RenderPass.js";
+import type { FrameContributorContext, TransparentQueueItem } from "../contracts/frameGraph.js";
+export interface TransparentEngineItem {
+    readonly item: RenderItem;
+    readonly sortDepth: number;
+}
+interface DrawSegment {
+    readonly engine?: readonly RenderItem[];
+    readonly queue?: TransparentQueueItem;
+}
+export declare function mergeTransparentSegments(engineItems: readonly TransparentEngineItem[], queues: readonly TransparentQueueItem[]): readonly DrawSegment[];
+export declare class InterleavedTransparentPass extends BaseRenderPass {
+    private readonly forwardOptions;
+    private readonly engineItems;
+    private readonly queues;
+    private readonly contributorContext;
+    constructor(forwardOptions: ForwardPassOptions, engineItems: readonly TransparentEngineItem[], queues: readonly TransparentQueueItem[], contributorContext: FrameContributorContext, reads?: readonly string[]);
+    execute(context: RenderPassContext): void;
+}
+export {};
+//# sourceMappingURL=InterleavedTransparentPass.d.ts.map

package/dist/renderer/InterleavedTransparentPass.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InterleavedTransparentPass.d.ts","sourceRoot":"","sources":["../../../../../packages/rendering/src/renderer/InterleavedTransparentPass.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAe,KAAK,kBAAkB,EAAE,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACvF,OAAO,EAAE,cAAc,EAAE,KAAK,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvE,OAAO,KAAK,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAE7F,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,UAAU,WAAW;IACnB,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IACxC,QAAQ,CAAC,KAAK,CAAC,EAAE,oBAAoB,CAAC;CACvC;AAED,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,SAAS,qBAAqB,EAAE,EAC7C,MAAM,EAAE,SAAS,oBAAoB,EAAE,GACtC,SAAS,WAAW,EAAE,CAyBxB;AAED,qBAAa,0BAA2B,SAAQ,cAAc;IAE1D,OAAO,CAAC,QAAQ,CAAC,cAAc;IAC/B,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,kBAAkB;gBAHlB,cAAc,EAAE,kBAAkB,EAClC,WAAW,EAAE,SAAS,qBAAqB,EAAE,EAC7C,MAAM,EAAE,SAAS,oBAAoB,EAAE,EACvC,kBAAkB,EAAE,uBAAuB,EAC5D,KAAK,GAAE,SAAS,MAAM,EAAgC;IAQxD,OAAO,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI;CAU1C"}

package/dist/renderer/InterleavedTransparentPass.js

@@ -0,0 +1,65 @@
+/**
+ * `renderer/InterleavedTransparentPass.ts` (PRD-01 §9.1 "transparent", C-01) —
+ * the v2 transparent phase: forward transparents and contributor
+ * `TransparentQueueItem`s drawn in one sequence merged by `sortDepth`
+ * (larger = farther; `order` breaks contributor ties), rather than the
+ * contributor queue running as a block after the engine transparents.
+ * Consecutive engine items group into a single `ForwardPass` draw run so the
+ * merge costs nothing when no contributor emits queue items.
+ */
+import { ForwardPass } from "../ForwardPass.js";
+import { BaseRenderPass } from "../RenderPass.js";
+export function mergeTransparentSegments(engineItems, queues) {
+    const queue = [...queues].sort((a, b) => (b.sortDepth - a.sortDepth) || ((a.order ?? 0) - (b.order ?? 0)));
+    const segments = [];
+    let run = [];
+    let qi = 0;
+    const flush = () => {
+        if (run.length > 0) {
+            segments.push({ engine: run });
+            run = [];
+        }
+    };
+    for (const { item, sortDepth } of engineItems) {
+        while (qi < queue.length && (queue[qi]?.sortDepth ?? 0) >= sortDepth) {
+            flush();
+            segments.push({ queue: queue[qi] });
+            qi += 1;
+        }
+        run.push(item);
+    }
+    flush();
+    while (qi < queue.length) {
+        segments.push({ queue: queue[qi] });
+        qi += 1;
+    }
+    return segments;
+}
+export class InterleavedTransparentPass extends BaseRenderPass {
+    forwardOptions;
+    engineItems;
+    queues;
+    contributorContext;
+    constructor(forwardOptions, engineItems, queues, contributorContext, reads = ["aura.scene.color.opaque"]) {
+        // The interleaved pass is the sole canonical writer of `aura.scene.color`
+        // — post-phase contributors chain to it. Earlier phases write their own
+        // per-phase resources since the graph enforces single-producer writes.
+        super("prd01.transparent", reads, ["aura.scene.color"]);
+        this.forwardOptions = forwardOptions;
+        this.engineItems = engineItems;
+        this.queues = queues;
+        this.contributorContext = contributorContext;
+    }
+    execute(context) {
+        const segments = mergeTransparentSegments(this.engineItems, this.queues);
+        for (const segment of segments) {
+            if (segment.engine) {
+                new ForwardPass({ ...this.forwardOptions, items: segment.engine }).execute(context);
+            }
+            else if (segment.queue) {
+                segment.queue.draw(this.contributorContext);
+            }
+        }
+    }
+}
+//# sourceMappingURL=InterleavedTransparentPass.js.map

package/dist/renderer/InterleavedTransparentPass.js.map

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

package/dist/renderer/PixelRatio.d.ts

@@ -0,0 +1,64 @@
+/**
+ * PRD-01 §6.9 canvas resolution policy (lane 01). `resolveCanvasPixelRatio`
+ * is the single DPR decision point — `explicit ?? resolution.pixelRatio ??
+ * min(devicePixelRatio, tier.maxPixelRatio)`, with NO [1, 2] clamp (the Ultra
+ * tier cap is 3). `resolveCanvasContextAttributes` owns the §6.9/§8 context
+ * attribute set under `A3D_QR_CORE`.
+ */
+import type { AuraQualityTierSettings } from "../contracts/quality.js";
+/** Engine-facing `renderer.resolution` options (C-27 consumer surface). */
+export interface AuraResolutionOptions {
+    /** Backing-pixel ratio: a number, or "device" for `min(devicePixelRatio, cap)`. */
+    readonly pixelRatio?: number | "device";
+    /** Per-app cap, defaults to `tier.maxPixelRatio`. */
+    readonly maxPixelRatio?: number;
+    /** Dynamic resolution governor. Default true for the "auto" tier. */
+    readonly dynamic?: boolean;
+    /** Governor target frame budget. Default 16.7. */
+    readonly targetFrameMs?: number;
+    /** Governor floor, defaults to `tier.minRenderScale`. */
+    readonly minRenderScale?: number;
+    /** Lift the `1/devicePixelRatio` governor floor. Default false. */
+    readonly allowSubCssResolution?: boolean;
+}
+/**
+ * `explicit ?? resolution.pixelRatio ?? min(devicePixelRatio, tier.maxPixelRatio)`.
+ * `resolution.pixelRatio === "device"` resolves through the capped DPR branch;
+ * `resolution.maxPixelRatio` narrows the cap further. No [1, 2] clamp — the
+ * only clamp is the tier/per-app cap.
+ */
+export declare function resolveCanvasPixelRatio(options: {
+    readonly devicePixelRatio: number;
+    readonly tier: Pick<AuraQualityTierSettings, "maxPixelRatio">;
+    readonly explicit?: number;
+    readonly resolution?: AuraResolutionOptions;
+}): number;
+/** WebGL2 context attributes passed to `canvas.getContext("webgl2", ...)`. */
+export interface AuraCanvasContextAttributes {
+    readonly antialias: boolean;
+    readonly alpha: boolean;
+    readonly preserveDrawingBuffer: boolean;
+    readonly powerPreference: WebGLPowerPreference;
+}
+/**
+ * §6.9: under `A3D_QR_CORE`, lane canvases create their context with
+ * `{ antialias: false, preserveDrawingBuffer: false, alpha: false,
+ * powerPreference: "high-performance" }` — MSAA lives on the offscreen scene
+ * target and `capture()` reads the framebuffer in the same task, so the canvas
+ * never needs `preserveDrawingBuffer`. `renderer.debug.preserveDrawingBuffer`
+ * opts back into the legacy attribute for one minor release (a dev warning is
+ * the caller's job — pass `warn` to emit it here). Flag-off callers get the
+ * legacy attribute set ({antialias:true, alpha:false, preserveDrawingBuffer:false}).
+ */
+export declare function resolveCanvasContextAttributes(options: {
+    readonly flagOn: boolean;
+    readonly debugPreserveDrawingBuffer?: boolean;
+    readonly warn?: (message: string) => void;
+}): AuraCanvasContextAttributes;
+/**
+ * Re-evaluates `onChange` when `devicePixelRatio` changes (window moved across
+ * monitors, browser zoom) via `matchMedia("(resolution: Xdppx)")`. Returns the
+ * unsubscribe function; a no-op when matchMedia is unavailable.
+ */
+export declare function watchDevicePixelRatio(onChange: (devicePixelRatio: number) => void, readDevicePixelRatio?: () => number): () => void;
+//# sourceMappingURL=PixelRatio.d.ts.map

package/dist/renderer/PixelRatio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PixelRatio.d.ts","sourceRoot":"","sources":["../../../../../packages/rendering/src/renderer/PixelRatio.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAEpE,2EAA2E;AAC3E,MAAM,WAAW,qBAAqB;IACpC,mFAAmF;IACnF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;IACxC,qDAAqD;IACrD,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,qEAAqE;IACrE,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,kDAAkD;IAClD,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,yDAAyD;IACzD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,mEAAmE;IACnE,QAAQ,CAAC,qBAAqB,CAAC,EAAE,OAAO,CAAC;CAC1C;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE;IAC/C,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,uBAAuB,EAAE,eAAe,CAAC,CAAC;IAC9D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,qBAAqB,CAAC;CAC7C,GAAG,MAAM,CAYT;AAMD,8EAA8E;AAC9E,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,qBAAqB,EAAE,OAAO,CAAC;IACxC,QAAQ,CAAC,eAAe,EAAE,oBAAoB,CAAC;CAChD;AAED;;;;;;;;;GASG;AACH,wBAAgB,8BAA8B,CAAC,OAAO,EAAE;IACtD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,0BAA0B,CAAC,EAAE,OAAO,CAAC;IAC9C,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CAC3C,GAAG,2BAA2B,CAgB9B;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,CAAC,gBAAgB,EAAE,MAAM,KAAK,IAAI,EAAE,oBAAoB,GAAE,MAAM,MAA+C,GAAG,MAAM,IAAI,CAkB3K"}

package/dist/renderer/PixelRatio.js

@@ -0,0 +1,81 @@
+/**
+ * PRD-01 §6.9 canvas resolution policy (lane 01). `resolveCanvasPixelRatio`
+ * is the single DPR decision point — `explicit ?? resolution.pixelRatio ??
+ * min(devicePixelRatio, tier.maxPixelRatio)`, with NO [1, 2] clamp (the Ultra
+ * tier cap is 3). `resolveCanvasContextAttributes` owns the §6.9/§8 context
+ * attribute set under `A3D_QR_CORE`.
+ */
+/**
+ * `explicit ?? resolution.pixelRatio ?? min(devicePixelRatio, tier.maxPixelRatio)`.
+ * `resolution.pixelRatio === "device"` resolves through the capped DPR branch;
+ * `resolution.maxPixelRatio` narrows the cap further. No [1, 2] clamp — the
+ * only clamp is the tier/per-app cap.
+ */
+export function resolveCanvasPixelRatio(options) {
+    const dpr = Number.isFinite(options.devicePixelRatio) && options.devicePixelRatio > 0 ? options.devicePixelRatio : 1;
+    // `explicit` wins verbatim — callers validate finiteness (ResizeToDisplayOptions).
+    if (options.explicit !== undefined) {
+        return options.explicit;
+    }
+    const cap = validPositive(options.resolution?.maxPixelRatio) ? options.resolution.maxPixelRatio : options.tier.maxPixelRatio;
+    const requested = options.resolution?.pixelRatio;
+    if (typeof requested === "number" && validPositive(requested)) {
+        return requested;
+    }
+    return Math.min(dpr, cap);
+}
+function validPositive(value) {
+    return value !== undefined && Number.isFinite(value) && value > 0;
+}
+/**
+ * §6.9: under `A3D_QR_CORE`, lane canvases create their context with
+ * `{ antialias: false, preserveDrawingBuffer: false, alpha: false,
+ * powerPreference: "high-performance" }` — MSAA lives on the offscreen scene
+ * target and `capture()` reads the framebuffer in the same task, so the canvas
+ * never needs `preserveDrawingBuffer`. `renderer.debug.preserveDrawingBuffer`
+ * opts back into the legacy attribute for one minor release (a dev warning is
+ * the caller's job — pass `warn` to emit it here). Flag-off callers get the
+ * legacy attribute set ({antialias:true, alpha:false, preserveDrawingBuffer:false}).
+ */
+export function resolveCanvasContextAttributes(options) {
+    if (!options.flagOn) {
+        return { antialias: true, alpha: false, preserveDrawingBuffer: false, powerPreference: "default" };
+    }
+    const preserveDrawingBuffer = options.debugPreserveDrawingBuffer === true;
+    if (preserveDrawingBuffer) {
+        options.warn?.("renderer.debug.preserveDrawingBuffer keeps the legacy readback attribute for one minor release; migrate callers to app.capture() before the flag is removed.");
+    }
+    return {
+        antialias: false,
+        alpha: false,
+        preserveDrawingBuffer,
+        powerPreference: "high-performance"
+    };
+}
+/**
+ * Re-evaluates `onChange` when `devicePixelRatio` changes (window moved across
+ * monitors, browser zoom) via `matchMedia("(resolution: Xdppx)")`. Returns the
+ * unsubscribe function; a no-op when matchMedia is unavailable.
+ */
+export function watchDevicePixelRatio(onChange, readDevicePixelRatio = () => globalThis.devicePixelRatio ?? 1) {
+    if (typeof globalThis.matchMedia !== "function")
+        return () => undefined;
+    let media = null;
+    let last = readDevicePixelRatio();
+    const attach = () => {
+        media?.removeEventListener?.("change", listener);
+        media = globalThis.matchMedia(`(resolution: ${last}dppx)`);
+        media.addEventListener?.("change", listener);
+    };
+    const listener = () => {
+        const next = readDevicePixelRatio();
+        if (next === last)
+            return;
+        last = next;
+        attach();
+        onChange(next);
+    };
+    attach();
+    return () => media?.removeEventListener?.("change", listener);
+}
+//# sourceMappingURL=PixelRatio.js.map

package/dist/renderer/PixelRatio.js.map

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