entangled-worlds-orbiters-shared 3.3.0 → 4.0.0

package/dist/render/viewportCompositor.js

@@ -0,0 +1,643 @@
+/**
+ * @file src/render/viewportCompositor.ts
+ * @description A multi-view render host: ONE `WebGLRenderer`, ONE rAF loop, many cells.
+ * Each frame it iterates the registered voices and renders each voice's scene into its own cell via
+ * `setViewport`/`setScissor` (three's "multiple views, one renderer"). This replaces the N-canvas
+ * spike, which hit a hard wall: N canvases = N WebGL contexts, and KTX2/compressed textures only
+ * upload to the FIRST context, so only voice-0 ever textured. One context → every voice textures.
+ *
+ * Each voice's controller runs in `sharedRenderer` mode — it contributes a scene+camera and per-frame
+ * callbacks but owns no renderer and no loop; this host drives it through `renderViewport(rect)`.
+ *
+ * Cell geometry has two sources:
+ *   - default: the compositor builds its own `⌈√n⌉` square grid (`ensureGrid`).
+ *   - external: a `cellSource` supplies the cells — real DOM the layout owns, so the compositor
+ *     renders each voice into its cell's rect and never builds or removes grid DOM.
+ *
+ * ## Presentation modes
+ * How rendered pixels reach the screen is a per-host choice (`presentation` option):
+ *
+ * - `'fixed-overlay'` (default): the WebGL canvas itself is displayed — appended to `document.body`,
+ *   `position:fixed;inset:0`, each voice scissor-rendered at its cell's on-screen rect. Right for
+ *   full-screen stage layouts the compositor was built for. Its structural limit: cell positions are
+ *   re-read on the main thread each frame, while the page scrolls on the compositor thread — so
+ *   inside a scrolling document the painted rect trails the DOM by a frame or more (the "viewport
+ *   detaches from the page" symptom). Don't use it under scrolling content.
+ *
+ * - `'per-cell'`: the WebGL canvas stays detached and is only a render source. Every voice gets a
+ *   compositor-owned 2D canvas inside its cell (`position:absolute;inset:0`), and each frame the
+ *   voice is rendered at the buffer's origin and blitted into that canvas (`drawImage`, a GPU-side
+ *   copy). The DOM owns the pixels' position, so cells scroll glued to the page — scroll can never
+ *   detach them, no matter how the rAF loop is scheduled. One WebGL context still serves
+ *   every voice, so the KTX2 single-context constraint holds. Requires each cell to be a positioned
+ *   element (the compositor makes a `static` cell `relative`); browser-fullscreen needs no canvas
+ *   reparenting in this mode — the cell brings its own canvas into the top layer.
+ *
+ * ## Host contract (this module is app-agnostic, but NOT assumption-free)
+ * A host adopting it must accept all of the following, or wrap it:
+ * - `'fixed-overlay'` only: the canvas is appended to `document.body`, `position:fixed;inset:0`,
+ *   `z-index:40`, opaque black CSS background; browser-fullscreen on a registered CELL reparents the
+ *   shared canvas into that cell. The host must not move the canvas itself.
+ * - The default grid it may build is `#multi-orbiter-grid` at `z-index:41`.
+ * - A voice is `{ voiceId, cell, controller }`, where `controller` exposes `renderActive`,
+ *   `renderViewport(rect)` and `setViewportSize(w, h)`. Rects are CSS px, GL bottom-left origin.
+ * - It owns the realm clear: every frame it re-asserts a fully transparent clear colour.
+ *
+ * @see `devHandleKey` — the one window global it can write, opt-in.
+ */
+import * as THREE from 'three';
+import { createFrameBudget } from './frameBudget.js';
+const GRID_ID = 'multi-orbiter-grid';
+/** Renderer defaults. Overridable via `rendererProfile`; these values are the historical constants. */
+const DEFAULT_RENDERER_PROFILE = {
+    antialias: true,
+    alpha: true,
+    preserveDrawingBuffer: false,
+    powerPreference: 'high-performance',
+    maxDevicePixelRatio: 1.5,
+};
+/** `'per-cell'`: how far past the viewport (CSS px) a cell still renders. Cull geometry is a cached
+ *  rect that can be a frame stale during fast scrolls — the slop keeps a cell entering the viewport
+ *  from flashing empty on that frame. */
+const CULL_SLOP_PX = 256;
+/**
+ * Options, all optional:
+ * - `cellSource`: external owner of the cell DOM. When present, `createCell` delegates to it and the
+ *   compositor builds no grid of its own; when absent, the default `⌈√n⌉` grid is used.
+ * - `presentation` (default `'fixed-overlay'`): how pixels reach the screen — the displayed fixed
+ *   canvas (full-screen stage layouts) or a per-cell blit canvas the DOM positions (cells inside
+ *   scrolling content). See the module doc.
+ * - `rendererProfile`: renderer construction + pixel-ratio cap. Omit for the historical defaults.
+ * - `performanceMode` (default false): start with the realm's renderer savings on — pixel ratio
+ *   clamped to 1, shadow map off, this loop capped at 30fps. Off by default, and off means the
+ *   renderer and the cadence are exactly what they were before this option existed. Toggle it live
+ *   with `setPerformanceMode`.
+ * - `devHandleKey` (default null): when set, publish the returned api on `window[devHandleKey]` so
+ *   tooling can force a composited frame while rAF is throttled (a hidden tab during automated
+ *   checks). Off by default — a library does not name globals for its host.
+ */
+export function createViewportCompositor({ cellSource = null, presentation = 'fixed-overlay', rendererProfile = null, devHandleKey = null, performanceMode = false, } = {}) {
+    const profile = { ...DEFAULT_RENDERER_PROFILE, ...(rendererProfile || {}) };
+    // The realm's renderer and the realm's loop are this module's, and they are the only things a
+    // single voice cannot change for itself: pixel ratio, shadow map and frame rate are one per realm,
+    // so a voice reaching for them would be deciding for its siblings. When the host says the realm is
+    // in performance mode, this is where that decision is made once, for all of them.
+    //
+    // Off is the default and off means untouched — a host that never mentions it (the feed embeds)
+    // gets exactly the renderer and the cadence it got before this existed.
+    let performanceOn = Boolean(performanceMode);
+    // What the realm's shadow map was before performance mode touched it, so turning the mode off puts
+    // the host's own choice back rather than asserting a default over it.
+    let baseShadowMapEnabled = null;
+    const frameBudget = createFrameBudget();
+    const perCell = presentation === 'per-cell';
+    // The one WebGL canvas. Fixed-overlay: full-bleed behind the grid, it owns the pixels for ALL
+    // voices. Per-cell: never enters the DOM — a render source the per-cell canvases copy from.
+    const canvas = document.createElement('canvas');
+    canvas.id = 'multi-orbiter-canvas';
+    if (!perCell) {
+        // A <canvas> is a REPLACED element: `inset:0` alone leaves it at its intrinsic 300×150 (unlike a
+        // div, it does not stretch to the inset box). Explicit width/height make it fill the viewport so the
+        // drawing buffer matches the grid — without this every voice renders into a 300×150 buffer (off-screen).
+        canvas.style.cssText =
+            'position:fixed;inset:0;width:100%;height:100%;z-index:40;display:block;background:#000;';
+        document.body.appendChild(canvas);
+    }
+    /**
+     * The renderer settings actually in force. Performance mode overrides the host's profile rather
+     * than replacing it, so whatever the host asked for comes back untouched when the mode goes off.
+     *
+     * `antialias` is deliberately not in here: it is fixed when the WebGL context is created, so
+     * turning it off would cost the host its antialiasing for the rest of the session the moment the
+     * mode was switched back on. The saving that IS live is the pixel ratio, and at dpr 2 that is
+     * three quarters of the fragments.
+     */
+    function effectiveProfile() {
+        return performanceOn ? { ...profile, maxDevicePixelRatio: 1 } : profile;
+    }
+    /** Re-assert the realm-wide knobs. Called at construction and whenever the mode changes. */
+    function applyRealmRendererProfile() {
+        applyPixelRatio(renderer, effectiveProfile());
+        // Only ever called after construction has read the base value, so it is a boolean here.
+        renderer.shadowMap.enabled = performanceOn ? false : baseShadowMapEnabled;
+    }
+    const renderer = createRenderer(canvas, effectiveProfile());
+    // Read before the mode has touched anything, so leaving performance mode restores the host's own
+    // setting instead of asserting three's default over it.
+    baseShadowMapEnabled = renderer.shadowMap.enabled;
+    if (performanceOn)
+        renderer.shadowMap.enabled = false;
+    /** voiceId → { cell, controller, lastW, lastH, rect, blit } — `rect` is the GL draw rect
+     *  (fixed-overlay) or the viewport-relative cull/size box (per-cell); `blit` is the per-cell
+     *  presentation canvas + its 2d context (per-cell only). */
+    const voices = new Map();
+    let grid = null;
+    let raf = null;
+    let disposed = false;
+    // A load meter's watch on the realm's frames (`setFrameProbe`): null when nobody is watching.
+    let frameProbe = null;
+    let frameProbeAt = 0;
+    let probePixel = null;
+    let lastCanvasW = 0;
+    let lastCanvasH = 0;
+    let viewportH = 0; // per-cell cull band (CSS px), refreshed with the rects
+    let viewportW = 0;
+    // The rAF loop must NOT read layout every frame. `getBoundingClientRect()` / `clientHeight`
+    // force a synchronous reflow, and while dragging the camera the per-tile knob re-renders dirty the
+    // layout every frame — so N per-frame reads = N reflows = the janky, irregular knob response in multi.
+    // Instead we CACHE each cell's rect + the canvas size and refresh only when something actually changes
+    // (a cell resizes, the stack scrolls, or the window resizes). A steady drag then reads zero layout.
+    // (Per-cell mode keeps the same cache: there the rect only culls and sizes — a stale frame merely
+    // renders one extra cell; it can't misplace pixels, the DOM owns their position.)
+    let rectsDirty = true;
+    const markRectsDirty = () => { rectsDirty = true; };
+    const cellObserver = typeof ResizeObserver !== 'undefined' ? new ResizeObserver(markRectsDirty) : null;
+    // Cells move (without resizing) when the mobile vertical stage stack scrolls — capture-phase catches
+    // scrolling of any ancestor container, not just the window. Window resize changes the canvas box too.
+    // The BODY observer catches layout shifts with no scroll/resize event at all: content above a cell
+    // expanding or collapsing moves the cell (and changes the body box) while every cell keeps its own
+    // size — without it, per-cell culling could keep skipping a voice that shifted into the viewport.
+    if (typeof window !== 'undefined') {
+        window.addEventListener('scroll', markRectsDirty, { passive: true, capture: true });
+        window.addEventListener('resize', markRectsDirty);
+    }
+    if (typeof document !== 'undefined' && document.body)
+        cellObserver?.observe(document.body);
+    // Browser-fullscreen ownership for a voice. Fixed-overlay: the shared canvas lives on
+    // `<body>` (fixed, inset:0) and scissor-renders every cell; a cell is a transparent div on top of
+    // it. When a voice's header fullscreens ITS cell, the fullscreen "top layer" draws the cell (and
+    // its chrome) above an opaque backdrop that HIDES the body-level canvas — so the orbiter's 3D
+    // pixels would vanish. Fix: reparent the one shared canvas INTO the fullscreened cell (so it
+    // paints inside the top layer) and solo-render that voice full-bleed; restore both on exit.
+    // Single-orbiter never builds a compositor, so this path is realm-only. The header only calls
+    // `requestFullscreen()` on the cell — this listener owns the canvas move + solo, keeping the
+    // compositor the single owner of its canvas. Per-cell: the cell's own canvas rides into the top
+    // layer with it — no reparenting, only the solo-render (and the buffer grows to the cell's new
+    // size through the normal resize path).
+    let fullscreenVoiceId = null; // voiceId rendered solo full-bleed while fullscreen, else null
+    let canvasHome = null; // { parent, next, cssText } to restore the canvas to its realm home on exit
+    const fullscreenElement = () => (typeof document !== 'undefined'
+        ? document.fullscreenElement || document.webkitFullscreenElement || null
+        : null);
+    const voiceIdForCell = (el) => {
+        if (!el)
+            return null;
+        for (const [id, voice] of voices)
+            if (voice.cell === el)
+                return id;
+        return null;
+    };
+    /** Put the canvas back to its realm home (`<body>`) and un-mutate its style. Safe to call when not
+     *  fullscreen (no-op). `next` may have been detached from `parent` during fullscreen, so fall back
+     *  to append rather than let `insertBefore` throw NotFoundError. Clears `fullscreenVoiceId`. */
+    const restoreCanvasHome = () => {
+        if (canvasHome) {
+            const { parent, next, cssText } = canvasHome;
+            canvas.style.cssText = cssText;
+            if (parent)
+                parent.insertBefore(canvas, next && next.parentNode === parent ? next : null);
+            canvasHome = null;
+        }
+        fullscreenVoiceId = null;
+    };
+    const onFullscreenChange = () => {
+        const enteringId = voiceIdForCell(fullscreenElement());
+        if (enteringId) {
+            if (fullscreenVoiceId === enteringId)
+                return;
+            if (perCell) {
+                // The fullscreened cell carries its own presentation canvas into the top layer; solo-render
+                // is all the compositor contributes here.
+                fullscreenVoiceId = enteringId;
+                markRectsDirty();
+                return;
+            }
+            // Direct switch from another fullscreen cell (no intervening exit): restore FIRST so canvasHome
+            // captures the true realm home, not the previous cell / already-mutated style.
+            if (fullscreenVoiceId)
+                restoreCanvasHome();
+            // enteringId came from a cell match, so this is set.
+            const cell = voices.get(enteringId)?.cell;
+            // Remember where the canvas belongs, then move it into the fullscreened cell. z-index:0 keeps
+            // it BEHIND the cell's pointer-events:none chrome host (a positioned, z-auto later sibling), so
+            // the buttons still show; it stays position:fixed;inset:0 to fill the now-full-viewport cell.
+            canvasHome = { parent: canvas.parentNode, next: canvas.nextSibling, cssText: canvas.style.cssText };
+            canvas.style.zIndex = '0';
+            cell.insertBefore(canvas, cell.firstChild);
+            fullscreenVoiceId = enteringId;
+        }
+        else if (fullscreenVoiceId) {
+            // Exit (or fullscreen moved off our cells): restore the canvas to its realm home and resume the grid.
+            restoreCanvasHome();
+        }
+        markRectsDirty();
+    };
+    if (typeof document !== 'undefined') {
+        document.addEventListener('fullscreenchange', onFullscreenChange);
+        document.addEventListener('webkitfullscreenchange', onFullscreenChange);
+    }
+    /** Recompute + cache every voice's rect (and the buffer size) in ONE layout pass. Called from the
+     *  loop only when `rectsDirty`, so the steady state does no forced layout.
+     *  Fixed-overlay: rect = GL draw rect on the displayed canvas (bottom-left origin, so y flips
+     *  against the fixed full-viewport canvas height). Per-cell: rect = the cell's viewport-relative
+     *  box (top-left origin) — used only to cull and size; the buffer grows (never shrinks) to hold
+     *  the largest cell, since every voice renders at the buffer origin. */
+    function refreshRects() {
+        if (perCell) {
+            viewportW = window.innerWidth;
+            viewportH = window.innerHeight;
+            let maxW = lastCanvasW;
+            let maxH = lastCanvasH;
+            for (const voice of voices.values()) {
+                const box = voice.cell?.getBoundingClientRect();
+                voice.rect = box
+                    ? { x: box.left, y: box.top, width: box.width, height: box.height }
+                    : null;
+                if (box) {
+                    if (box.width > maxW)
+                        maxW = Math.ceil(box.width);
+                    if (box.height > maxH)
+                        maxH = Math.ceil(box.height);
+                }
+            }
+            if (maxW > lastCanvasW || maxH > lastCanvasH) {
+                lastCanvasW = maxW;
+                lastCanvasH = maxH;
+                renderer.setSize(maxW, maxH, false);
+                // The EFFECTIVE profile, not the host's: a cell growing must not quietly hand the realm its
+                // full pixel ratio back while performance mode is still on.
+                applyPixelRatio(renderer, effectiveProfile());
+            }
+            rectsDirty = false;
+            return;
+        }
+        syncCanvasSize();
+        const canvasH = lastCanvasH || canvas.clientHeight || window.innerHeight;
+        for (const voice of voices.values()) {
+            const box = voice.cell?.getBoundingClientRect();
+            voice.rect = box
+                ? { x: box.left, y: canvasH - box.bottom, width: box.width, height: box.height }
+                : null;
+        }
+        rectsDirty = false;
+    }
+    /** Create-or-get the CSS grid that lays the cells out (square-ish: ⌈√n⌉ columns). */
+    function ensureGrid(total) {
+        if (grid)
+            return grid;
+        const cols = Math.ceil(Math.sqrt(total));
+        const rows = Math.ceil(total / cols);
+        grid = document.createElement('div');
+        grid.id = GRID_ID;
+        // Above the canvas, but transparent + click-through: cells exist to define viewport rects (and to
+        // anchor per-tile GUI later); the canvas underneath paints every voice.
+        grid.style.cssText = [
+            'position:fixed',
+            'inset:0',
+            'z-index:41',
+            'display:grid',
+            'gap:2px',
+            'pointer-events:none',
+            `grid-template-columns:repeat(${cols},1fr)`,
+            `grid-template-rows:repeat(${rows},1fr)`,
+        ].join(';');
+        document.body.appendChild(grid);
+        return grid;
+    }
+    function createCell(index, total) {
+        // Collection mode: the slot layout owns the cell DOM (a resizable slot). Borrow its element as this
+        // voice's viewport rect + GUI mount — the compositor builds no grid of its own.
+        if (cellSource) {
+            return cellSource.acquireCell(index, total);
+        }
+        const cell = document.createElement('div');
+        cell.className = 'multi-orbiter-cell';
+        cell.dataset.voiceIndex = String(index);
+        // The cell is this voice's own interactive input surface (pointer-events:auto), so its
+        // CameraController receives its planet drags directly and DOM hit-testing routes clicks to the right
+        // tile. The grid CONTAINER stays pointer-events:none, so the 2px inter-tile gaps still click through.
+        cell.style.cssText = 'position:relative;overflow:hidden;min-width:0;min-height:0;pointer-events:auto;';
+        ensureGrid(total).appendChild(cell);
+        return cell;
+    }
+    /** Per-cell mode: the compositor-owned presentation canvas living INSIDE a voice's cell. The DOM
+     *  positions it (absolute, inset:0), so it scrolls with the page on the compositor thread — the
+     *  whole point of the mode. First child + z-index:0 keeps it under the cell's chrome; pointer
+     *  events pass through to the cell, which owns the voice's camera input binding. */
+    function createBlitCanvas(cell) {
+        // An absolutely-positioned child anchors to the nearest positioned ancestor — make sure that's
+        // the cell itself, not something above it.
+        if (typeof getComputedStyle === 'function' && getComputedStyle(cell).position === 'static') {
+            cell.style.position = 'relative';
+        }
+        const el = document.createElement('canvas');
+        el.className = 'multi-orbiter-cell-canvas';
+        el.style.cssText =
+            'position:absolute;inset:0;width:100%;height:100%;display:block;pointer-events:none;z-index:0;';
+        cell.insertBefore(el, cell.firstChild);
+        const ctx = el.getContext('2d');
+        return { el, ctx };
+    }
+    function addVoice({ voiceId, cell, controller }) {
+        if (!voiceId || !cell || !controller)
+            return;
+        const blit = perCell ? createBlitCanvas(cell) : null;
+        voices.set(voiceId, { cell, controller, lastW: 0, lastH: 0, rect: null, blit });
+        cellObserver?.observe(cell); // resize of this tile → recompute its cached rect
+        markRectsDirty();
+    }
+    function removeVoice(voiceId) {
+        const voice = voices.get(voiceId);
+        if (!voice)
+            return;
+        // If this voice is fullscreen its cell hosts the shared canvas — restore the canvas to its
+        // realm home FIRST, so removing the cell below (grid mode) can't take the canvas down with it.
+        if (voiceId === fullscreenVoiceId)
+            restoreCanvasHome();
+        voices.delete(voiceId);
+        if (voice.cell)
+            cellObserver?.unobserve(voice.cell);
+        // The blit canvas is compositor-owned even when the HOST owns the cell — always take it out.
+        voice.blit?.el.remove();
+        markRectsDirty();
+        // Collection mode: the slot layout owns the cell DOM — leave it in place (the layout reclaims or
+        // re-fills the slot). Only the compositor-built grid removes its own cells.
+        if (cellSource)
+            return;
+        voice.cell?.remove();
+        if (grid && grid.childElementCount === 0) {
+            grid.remove();
+            grid = null;
+        }
+    }
+    /** Keep the renderer's drawing buffer matched to the canvas's CSS box (handles window resize).
+     *  Fixed-overlay only — per-cell sizes the buffer to the largest cell in `refreshRects`. */
+    function syncCanvasSize() {
+        const w = canvas.clientWidth || window.innerWidth;
+        const h = canvas.clientHeight || window.innerHeight;
+        if (!w || !h || (w === lastCanvasW && h === lastCanvasH))
+            return;
+        lastCanvasW = w;
+        lastCanvasH = h;
+        renderer.setSize(w, h, false);
+        // The EFFECTIVE profile, not the host's. A window resize — or dragging the window to a display
+        // with a different pixel ratio — must not restore full-resolution fragments while performance
+        // mode is still on, which is what re-applying the raw profile here would do.
+        applyPixelRatio(renderer, effectiveProfile());
+    }
+    /** Fixed-overlay frame: clear the displayed canvas, then scissor-render every visible voice at its
+     *  on-screen rect. */
+    function renderOverlayFrame() {
+        // Clear the WHOLE buffer once (scissor off) so the gridline gaps and any paused/empty cell show
+        // the canvas CSS background, not stale pixels — then each voice scissor-renders into its own
+        // rect. The compositor owns the realm clear: re-assert a fully transparent clear color, because
+        // a voice's boot can leave an opaque clear on the SHARED renderer, which would paint the entire
+        // canvas over an embedding host page (the app's own full-screen canvas hides this — its CSS
+        // background is already black).
+        renderer.setClearColor(0x000000, 0);
+        renderer.setScissorTest(false);
+        renderer.clear();
+        const canvasW = lastCanvasW;
+        const canvasH = lastCanvasH;
+        for (const [voiceId, voice] of voices) {
+            // While one voice is browser-fullscreen its cell hosts the shared canvas in the top
+            // layer and fills the viewport (rect = whole canvas). Render ONLY that voice — the other cells
+            // sit behind the fullscreen backdrop, so scissor-rendering them would stamp stray tiles over it.
+            if (fullscreenVoiceId && voiceId !== fullscreenVoiceId)
+                continue;
+            const { controller, rect } = voice;
+            if (!controller.renderActive || !rect)
+                continue;
+            if (rect.width <= 0 || rect.height <= 0)
+                continue;
+            // Cull stages scrolled fully off-canvas (the mobile vertical stage stack) — no point scissor-
+            // rendering a viewport with no on-screen pixels. rect is GL bottom-left; visible band is [0,canvasH].
+            if (rect.y + rect.height <= 0 || rect.y >= canvasH || rect.x + rect.width <= 0 || rect.x >= canvasW) {
+                continue;
+            }
+            // Re-aspect the camera only when the cell's box actually changed (avoids a per-frame projection rebuild).
+            if (rect.width !== voice.lastW || rect.height !== voice.lastH) {
+                controller.setViewportSize(rect.width, rect.height);
+                voice.lastW = rect.width;
+                voice.lastH = rect.height;
+            }
+            controller.renderViewport(rect);
+        }
+    }
+    /** Per-cell frame: render each visible voice at the buffer ORIGIN, then blit that region into the
+     *  voice's own canvas. Every voice reuses the same origin region (cleared per voice), so the
+     *  buffer only ever needs to hold the largest single cell. The blit is `drawImage` straight from
+     *  the WebGL canvas — same-task with the render, so `preserveDrawingBuffer:false` stays safe. */
+    function renderPerCellFrame() {
+        renderer.setClearColor(0x000000, 0);
+        const dpr = renderer.getPixelRatio();
+        // The blit reads DEVICE pixels; the canvas attribute is the buffer's true height (three floors
+        // internally — recomputing from CSS px could drift by a pixel).
+        const bufH = canvas.height;
+        for (const [voiceId, voice] of voices) {
+            if (fullscreenVoiceId && voiceId !== fullscreenVoiceId)
+                continue;
+            const { controller, rect, blit } = voice;
+            if (!controller.renderActive || !rect || !blit?.ctx)
+                continue;
+            const { width, height } = rect;
+            if (width <= 0 || height <= 0)
+                continue;
+            // Cull cells fully outside the viewport (+slop: the cached rect may be a frame stale during a
+            // fast scroll — better one extra render than a blank cell entering the screen).
+            if (rect.y + height <= -CULL_SLOP_PX ||
+                rect.y >= viewportH + CULL_SLOP_PX ||
+                rect.x + width <= -CULL_SLOP_PX ||
+                rect.x >= viewportW + CULL_SLOP_PX) {
+                continue;
+            }
+            // Floor to match three's own device-px math (setViewport/setScissor floor after the dpr
+            // multiply) — rounding UP would blit a stale 1px edge the render never touched.
+            const sw = Math.floor(width * dpr);
+            const sh = Math.floor(height * dpr);
+            if (width !== voice.lastW || height !== voice.lastH) {
+                controller.setViewportSize(width, height);
+                voice.lastW = width;
+                voice.lastH = height;
+            }
+            // Setting a canvas's backing-store size clears it, so only do it on actual change.
+            if (blit.el.width !== sw || blit.el.height !== sh) {
+                blit.el.width = sw;
+                blit.el.height = sh;
+            }
+            // Clear this voice's region (previous voice's pixels live there), then let it render.
+            renderer.setViewport(0, 0, width, height);
+            renderer.setScissor(0, 0, width, height);
+            renderer.setScissorTest(true);
+            renderer.clear();
+            controller.renderViewport({ x: 0, y: 0, width, height });
+            // GL origin is bottom-left: the region sits at the BOTTOM of the buffer in 2D (top-left) coords.
+            // 'copy' replaces the destination (alpha included) — no clearRect pass needed.
+            blit.ctx.globalCompositeOperation = 'copy';
+            blit.ctx.drawImage(canvas, 0, bufH - sh, sw, sh, 0, 0, sw, sh);
+        }
+    }
+    /** Render exactly ONE composited frame (every active voice into its cell). Also the unit the rAF
+     *  loop runs each tick. Exposed on the dev handle so a paused/hidden tab can force a frame.
+     *  three's setViewport/setScissor multiply by the renderer's pixelRatio internally, so the cached
+     *  rects are CSS px — pre-multiplying by dpr would double-scale (correct only at dpr=1, broken on retina). */
+    function renderOnce() {
+        if (disposed)
+            return;
+        // Refresh cached rects/canvas size ONLY when layout changed (never per frame — see refreshRects).
+        if (rectsDirty)
+            refreshRects();
+        if (perCell) {
+            renderPerCellFrame();
+        }
+        else {
+            renderOverlayFrame();
+        }
+    }
+    function tick(nowMs) {
+        if (disposed)
+            return;
+        raf = requestAnimationFrame(tick);
+        // The cap belongs HERE, to the realm's own loop — never to a voice declining to draw inside
+        // `renderViewport`. A composited frame clears the whole canvas and then scissor-renders each cell
+        // into it, so a voice that skipped its draw would leave a black hole where its cell is and flash
+        // at half the realm's rate. Skipping the whole frame instead leaves every cell showing the last
+        // frame that was drawn — together, which is the only way a shared canvas can be consistent.
+        if (performanceOn && !frameBudget.shouldRender(nowMs))
+            return;
+        if (!frameProbe) {
+            renderOnce();
+            return;
+        }
+        const probe = frameProbe;
+        probe.onFrame?.(nowMs);
+        const timed = nowMs - frameProbeAt >= probe.everyMs;
+        if (!timed) {
+            renderOnce();
+            return;
+        }
+        frameProbeAt = nowMs;
+        // Every cell's draw counted together: one composited frame is several renders.
+        const info = renderer.info;
+        const autoReset = info.autoReset;
+        info.autoReset = false;
+        info.reset();
+        try {
+            const started = performance.now();
+            renderOnce();
+            // A lost context draws nothing and answers nothing: no reading, not a good one.
+            if (waitForDraw()) {
+                const drawn = performance.now();
+                // Asked again with nothing left to draw: what the asking itself costs, taken off the reading.
+                waitForDraw();
+                probe.onDraw(Math.max(0, drawn - started - (performance.now() - drawn)), info.render.calls, info.render.triangles);
+            }
+        }
+        finally {
+            // Put back as it was, even when a voice throws mid-frame.
+            info.autoReset = autoReset;
+        }
+    }
+    /** Block until the graphics chip has drawn what was sent: reading a pixel back is the one wait every
+     *  browser honours. False when there is no context to ask. */
+    function waitForDraw() {
+        const gl = renderer.getContext?.();
+        if (!gl || gl.isContextLost())
+            return false;
+        probePixel ??= new Uint8Array(4);
+        gl.readPixels(0, 0, 1, 1, gl.RGBA, gl.UNSIGNED_BYTE, probePixel);
+        return true;
+    }
+    /**
+     * Watch the realm's frames, for a load meter: `onFrame(nowMs)` for every frame drawn, and one frame
+     * every `everyMs` timed to the end of its drawing (`onDraw(workMs, calls, triangles)`, every cell
+     * together). Only the timed frame waits for the graphics chip; every other frame is untouched.
+     * `null` stops it.
+     */
+    function setFrameProbe(probe) {
+        frameProbe = probe ?? null;
+        frameProbeAt = 0;
+    }
+    /**
+     * Turn the realm's performance mode on or off, live. Clamps the realm pixel ratio to 1, turns the
+     * shadow map off and caps this loop at 30fps while on; puts all three back when off. Returns
+     * whether the mode actually changed.
+     */
+    function setPerformanceMode(enabled) {
+        const next = Boolean(enabled);
+        if (disposed || next === performanceOn)
+            return false;
+        performanceOn = next;
+        applyRealmRendererProfile();
+        // The next frame is the first of the new cadence — it must not be judged against a frame drawn
+        // under the old one.
+        frameBudget.reset();
+        return true;
+    }
+    function dispose() {
+        if (disposed)
+            return;
+        disposed = true;
+        if (raf != null)
+            cancelAnimationFrame(raf);
+        raf = null;
+        cellObserver?.disconnect();
+        if (typeof window !== 'undefined') {
+            window.removeEventListener('scroll', markRectsDirty, { capture: true });
+            window.removeEventListener('resize', markRectsDirty);
+        }
+        if (typeof document !== 'undefined') {
+            document.removeEventListener('fullscreenchange', onFullscreenChange);
+            document.removeEventListener('webkitfullscreenchange', onFullscreenChange);
+        }
+        // If disposed while a voice was fullscreen, put the canvas style back before `canvas.remove()`.
+        restoreCanvasHome();
+        for (const voice of voices.values())
+            voice.blit?.el.remove();
+        voices.clear();
+        if (typeof window !== 'undefined' && devHandleKey) {
+            const devWindow = window;
+            if (devWindow[devHandleKey]?.renderer === renderer)
+                delete devWindow[devHandleKey];
+        }
+        renderer.dispose();
+        grid?.remove();
+        grid = null;
+        canvas.remove();
+    }
+    raf = requestAnimationFrame(tick);
+    const api = {
+        renderer,
+        canvas,
+        createCell,
+        addVoice,
+        removeVoice,
+        renderOnce,
+        setPerformanceMode,
+        setFrameProbe,
+        dispose,
+    };
+    // Dev handle: lets tooling force a composited frame when rAF is throttled (e.g. a hidden/background
+    // tab during automated checks). The HOST names it — this module invents no global of its own.
+    if (devHandleKey && typeof window !== 'undefined') {
+        window[devHandleKey] = api;
+    }
+    return api;
+}
+function createRenderer(canvas, profile) {
+    const renderer = new THREE.WebGLRenderer({
+        canvas,
+        antialias: profile.antialias,
+        alpha: profile.alpha,
+        preserveDrawingBuffer: profile.preserveDrawingBuffer,
+        powerPreference: profile.powerPreference,
+    });
+    applyPixelRatio(renderer, profile);
+    renderer.setSize(canvas.clientWidth || window.innerWidth, canvas.clientHeight || window.innerHeight, false);
+    renderer.outputColorSpace = THREE.SRGBColorSpace;
+    return renderer;
+}
+function applyPixelRatio(renderer, profile) {
+    const dpr = typeof window !== 'undefined' && Number.isFinite(window.devicePixelRatio) ? window.devicePixelRatio : 1;
+    renderer.setPixelRatio(Math.min(dpr, profile.maxDevicePixelRatio));
+}

package/dist/studio/headerBroadcast.d.ts

@@ -1,7 +1,16 @@
 type Setter = (arg: never) => void;
 /** A header sink implements any subset of the setters. */
 export type HeaderSinkOf<K extends string> = Partial<Record<K, Setter>>;
-export type HeaderBroadcast<Shell extends object, K extends string> = Shell & {
+/** The setter the wrapper puts on `P`: the shell's own one-argument signature, or any argument. */
+type ForwardingSetter<Shell, P extends string> = P extends keyof Shell ? Exclude<Shell[P], undefined> extends (arg: infer A) => unknown ? (arg: A) => void : (arg: unknown) => void : (arg: unknown) => void;
+/**
+ * The wrapped shell: the shell's own members, a forwarding setter (always there) for every header
+ * key, including keys the shell lacks (they reach the sink only), and `replayInto`. Header keys
+ * typed only as `string` name no setter.
+ */
+export type HeaderBroadcast<Shell extends object, K extends string> = Shell & (string extends K ? unknown : {
+    [P in K]-?: ForwardingSetter<Shell, P>;
+}) & {
     /** Push the last value of every header setter into a freshly registered sink. */
     replayInto(sink: HeaderSinkOf<K> | null | undefined): void;
 };