`scaledByDpr()` — rescale constants by effective DPR

Part of #114.

Part of #114 (dogfood API). Package: @vgpu/render/utils.

Context

canvasResolution (packages/render/src/utils/canvas-resolution.ts) only reads canvas.width/height. Every consumer hand-rolls the write side — measure CSS size, resolve/clamp devicePixelRatio, guarded write to canvas.width/height:

• Eve hero (apps/docs/.../eve-logo-shader/index.tsx:342-351): resizeCanvas clamps DPR to MAX_DEVICE_PIXEL_RATIO (max 2), floor(rect × dpr), no-change guard — called both on mount and per frame.
• triangle-led-4 (front/.../triangle-led-4/bridge/dimensions.ts:55-58): resolveDevicePixelRatio clamps the opposite direction (max(dpr, 1), plus a mobile max). Same pattern, different clamp — dprClamp: [min, max] expresses both.

Separately, Eve hit the same bug twice: constants (BLOOM_RADIUS = 16, imprint cell size) tuned at DPR 2 were silently 2× too large at DPR 1. The fix added two near-identical ~13-line scaling helpers plus a safeDevicePixelRatioOrDefault guard — and that guard is itself the hazard: a worker/offline context passing undefined quietly renders at the wrong scale. The bug survived precisely because of an implicit default and a silent fallback, so this API has deliberately hard edges: referenceDpr is required and invalid DPR throws.

None of this exists in vgpu today; canvasResolution stays as the read-only contract (for consumers that don't own sizing), and canvasSizing becomes its write-side companion.

Proposed API

// -- 8a: write-side companion to canvasResolution ---------------------------
export interface CanvasSizing {
  /** Device-pixel size last applied to the canvas. */
  readonly width: number;
  readonly height: number;
  /** Clamped DPR actually in effect (use this for scaledByDpr). */
  readonly dpr: number;
  /** Re-measure CSS size + devicePixelRatio, clamp, write canvas.width/height
   *  only if changed. Returns true when dimensions changed. */
  apply(): boolean;
  dispose(): void;
}

export function canvasSizing(canvas: HTMLCanvasElement, opts?: {
  /** number = max clamp (the common perf cap); tuple = [min, max]. Default: none. */
  readonly dprClamp?: number | readonly [min: number, max: number];
  /** Auto-apply on size/DPR changes. Default: false (pull via apply()). */
  readonly observe?: boolean;
  /** Fires after each applied change (not for the initial sizing). */
  readonly onResize?: (size: { width: number; height: number; dpr: number }) => void;
}): CanvasSizing;

Semantics.

• Construction measures and applies once — the util's job is sizing the canvas; deferring the first write would leave sizing.width ≠ canvas.width.
• Measurement: devicePixelContentBoxSize via ResizeObserver when supported (exact device pixels; immune to floor-vs-round fractional-DPR mismatch). Fallback: round(getBoundingClientRect() × clampedDpr) — round, not floor, to match what the observer reports (≤1px change vs Eve's floor; changelog-note it).
• observe: true: observes with { box: "device-pixel-content-box" } where supported — this fires on browser zoom and cross-monitor DPR changes even when CSS size is unchanged, no matchMedia needed. Fallback (Safari): content-box ResizeObserver plus a re-armed matchMedia("(resolution: <dpr>dppx)") listener to catch pure-DPR changes. Observer auto-applies; apply() stays callable either way (idempotent).
• apply() is the only mutation point in pull mode — the guarded write to canvas.width/height (which resets the drawing buffer) is the caller's cue to rebuild size-dependent render targets; hence the boolean return.
• SSR: safe by construction — requires a live HTMLCanvasElement, so it can only run client-side. No typeof window soft-guards. Workers/OffscreenCanvas are out of scope (no CSS box); pass a DPR across and use scaledByDpr.
• No device coupling: does not touch GPUCanvasContext or device limits; callers min against device.limits.maxTextureDimension2D if needed (docs note).

// -- 8b: scale a tuned constant to the actual DPR ---------------------------
export function scaledByDpr(value: number, dpr: number, opts: {
  /** REQUIRED — the DPR the constant was tuned at. No default, deliberately. */
  readonly referenceDpr: number;
  readonly round?: "round" | "floor" | "ceil";  // default: no rounding
  readonly min?: number;
}): number;
// value * (dpr / referenceDpr), then round, then min.
// Throws ValidationError when dpr or referenceDpr is not finite-positive
// (matches vgpu's existing ValidationError convention).

Pure function, no DOM — works in workers and offline harnesses (scripts/render-eve-5.ts).

Example

const sizing = canvasSizing(canvas, { dprClamp: [1, 2] });

// per frame (Eve's pull style):
if (sizing.apply()) rebuildTargets(sizing.width, sizing.height);

// the silent DPR-2 tuning bug, now explicit:
const bloomRadius = scaledByDpr(BLOOM_RADIUS, sizing.dpr, { referenceDpr: 2, round: "round", min: 0 });
const cellSize    = scaledByDpr(DEFAULT_IMPRINT_CELL_SIZE, sizing.dpr, { referenceDpr: 2 });

Same example without the util

// eve-logo-shader/index.tsx:342-351 — hand-rolled write side
function resizeCanvas(canvas: HTMLCanvasElement | null) {
  if (!canvas) return;
  const dpr = Math.min(window.devicePixelRatio || 1, MAX_DEVICE_PIXEL_RATIO);
  const rect = canvas.getBoundingClientRect();
  const width = Math.max(1, Math.floor(rect.width * dpr));   // floor ≠ observer px
  const height = Math.max(1, Math.floor(rect.height * dpr));
  if (canvas.width !== width || canvas.height !== height) {
    canvas.width = width;
    canvas.height = height;
  }
}
// no zoom / cross-monitor DPR listener; caller re-detects change by re-measuring

// constants.ts — two near-identical helpers, both hiding the tuning assumption
function scaleBloomRadiusForDpr(dpr: number): number {
  const safe = Number.isFinite(dpr) && dpr > 0 ? dpr : 2;    // silent fallback = the bug
  return Math.max(0, Math.round(BLOOM_RADIUS * (safe / 2))); // "/ 2" is implicit referenceDpr
}
function scaleImprintCellForDpr(dpr: number): number {
  const safe = Number.isFinite(dpr) && dpr > 0 ? dpr : 2;
  return DEFAULT_IMPRINT_CELL_SIZE * (safe / 2);
}

~40 lines per consumer, duplicated with opposite clamp directions across Eve and triangle-led-4, and the safe = ... : 2 fallback is exactly how the wrong-scale render shipped.

Alternatives

• Merge into canvasResolution — rejected. Read-only vs canvas-mutating are different contracts; silently changing an existing export's behavior is a bad trade. Both coexist: canvasSizing for owners of the canvas size, canvasResolution for read-only consumers (its width/height reflect whatever canvasSizing.apply() wrote, so they compose cleanly).
• sizing.scaled(value, opts) method instead of standalone scaledByDpr — rejected. The pure function must run in workers/offline harnesses with no canvas; coupling it to a DOM object kills the main use case that motivated the throw-on-invalid-DPR edge.
• Default referenceDpr: 2 (or 1) — rejected. The entire bug class is an implicit tuning assumption; a default re-hides it. This is the one place ergonomics deliberately lose to safety.
• Ambient DprContext threaded through the renderer — rejected as framework-shaped; two small explicit primitives beat one ambient context.