@jbrowse/render-core 4.3.0

package/esm/useRenderingBackend.d.ts

@@ -0,0 +1,83 @@
+export declare const CONTEXT_LOST_REPORT_GRACE_MS = 400;
+/**
+ * Flagged rather than matched by message or `instanceof`, so the error UI can
+ * offer the remedy specific to a loss (switch the page to Canvas2D) without
+ * offering it for render errors whose remedy differs (an over-allocation says to
+ * zoom in).
+ *
+ * A lost WebGPU device carries the same flag deliberately: the two causes
+ * differ, but the remedy on offer — take the page off the GPU — is the same one.
+ */
+export declare function createGpuContextLostError(message?: string): Error & {
+    gpuContextLost: true;
+};
+export declare function createGpuDeviceLostError(): Error & {
+    gpuContextLost: true;
+};
+export declare function isGpuContextLostError(error: unknown): error is object & Record<"gpuContextLost", unknown>;
+/**
+ * Duck-typed shape of an MST display model that owns a GPU backend
+ * lifecycle via `RenderLifecycleMixin`. Plugins pass their own
+ * model; the hook only touches these actions/fields.
+ */
+export interface RenderLifecycleModel<RenderingBackendType> {
+    startRenderingBackend: (backend: RenderingBackendType) => void;
+    stopRenderingBackend: () => void;
+    renderNow: () => void;
+    renderError: unknown;
+    setRenderError: (error: unknown) => void;
+}
+/**
+ * Drives the GPU/Canvas2D backend lifecycle for a display: canvas
+ * initialization, context-loss / device-loss recovery, page-navigation
+ * cleanup, and retry — wiring each event directly to the model's
+ * `RenderLifecycleMixin` actions so the model (not React-local hook state)
+ * owns every terminal state.
+ *
+ * The returned `canvasRef` is a callback ref — assign it directly to a
+ * `<canvas ref={canvasRef} />`. React invokes it with the DOM node on mount
+ * and with `null` on unmount, so the initialization effect re-runs when the
+ * underlying canvas element is actually replaced (e.g. after regionTooLarge
+ * unmounts then remounts the canvas).
+ *
+ * Lifecycle:
+ *   1. Canvas mounts → init effect calls `factory(canvas)`; on success
+ *      `setRenderError(undefined)` + `startRenderingBackend(backend)`, on
+ *      failure `setRenderError(error)`.
+ *   2. WebGL context loss → the browser gets one grace window to fire
+ *      `webglcontextrestored` (which bumps `contextVersion` → rebuild, no user-
+ *      visible state); if it doesn't, the loss is reported as `renderError`
+ *      (`createGpuContextLostError`), which unmounts the canvas and so is what
+ *      makes a fresh context obtainable at all. Bounded auto-recovery then
+ *      clears it. WebGPU device loss bumps `contextVersion` directly.
+ *   3. `retry()` clears `renderError` + bumps `contextVersion` so the next
+ *      mount reinitializes.
+ *
+ * Page navigation fires `pagehide` on every mounted component, disposing its
+ * backend AND clearing `model.currentRenderingBackend` (so the render/upload
+ * autoruns no-op); React unmount disposes via the effect cleanup. A bfcache
+ * restore fires `pageshow` with `persisted`, which rebuilds the backend for the
+ * still-mounted canvas. No global tracking.
+ *
+ * The model argument is duck-typed to the slot mixin's contract — the listed
+ * actions/fields are all the hook touches.
+ *
+ * **`factory` must be referentially stable** — a module-level constant, as every
+ * consumer in this repo passes (`AlignmentsRenderer`, `createDotplotRenderer`,
+ * …). It is a dependency of the init effect, so an inline
+ * `canvas => new MyBackend(canvas)` rebuilds the backend on every render:
+ * dispose, async re-create, `startRenderingBackend`, forever. Nothing throws and
+ * nothing logs — the display just paints from a backend a render behind, and the
+ * GPU churn shows up only in a profile. Bind the factory outside the component
+ * (or `useCallback` it with no deps).
+ */
+export declare function useRenderingBackend<RenderingBackendType extends {
+    dispose(): void;
+    setErrorHandler: (handler: (error: Error) => void) => void;
+}>(factory: (canvas: HTMLCanvasElement) => Promise<RenderingBackendType>, model: RenderLifecycleModel<RenderingBackendType>): {
+    canvas: HTMLCanvasElement | null;
+    canvasRef: (node: HTMLCanvasElement | null) => void;
+    error: unknown;
+    retry: () => void;
+    canvasKey: number;
+};

package/esm/useRenderingBackend.js

@@ -0,0 +1,422 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { isAlive, isStateTreeNode } from '@jbrowse/mobx-state-tree';
+import { onDeviceLost } from './gpuDevice.js';
+import { RecoveryBudget } from './recoveryBudget.js';
+import { useTabVisibilityRerender } from './useTabVisibilityRerender.js';
+// Auto-recovery from WebGL context loss. The browser force-loses the oldest
+// context when too many are live (and may never fire `webglcontextrestored`),
+// which strands the display on the GPU error overlay. We re-init a FEW times on
+// an exponential backoff so it comes back once GPU capacity frees — then stop
+// and leave the manual Retry button, deliberately leaning on manual recovery
+// rather than risk thrashing the page with endless re-inits. The budget is
+// `RecoveryBudget`, which is windowed: a context that keeps flapping climbs to
+// the cap and stops, but two losses far enough apart to not be a flap each get
+// their own recovery. It resets outright only on a genuine browser restore or a
+// manual retry (never on a bare re-acquire — every flap contains one).
+const CONTEXT_RECOVER_BASE_MS = 1000;
+// A lost context reports itself because nothing else will: calls on it are
+// silent no-ops, and it can't be re-acquired on its element (see `canvasKey`
+// below, which is what gets every consumer a fresh element).
+//
+// The report waits out a grace window first — a race against
+// `webglcontextrestored`, which lands within a frame or two for the recoverable
+// causes (GPU crash, driver reset) and needs no banner at all. Nothing is
+// aborted when the window expires, so this is not a readiness cap.
+export const CONTEXT_LOST_REPORT_GRACE_MS = 400;
+const CONTEXT_LOST_MESSAGE = 'WebGL context lost. The browser reclaimed the GPU context for this display, ' +
+    'usually because too many GPU-rendered views are open at once.';
+const DEVICE_LOST_MESSAGE = 'WebGPU device lost. The GPU device backing this display went away and kept ' +
+    'going away after several attempts to rebuild on a fresh one.';
+/**
+ * Flagged rather than matched by message or `instanceof`, so the error UI can
+ * offer the remedy specific to a loss (switch the page to Canvas2D) without
+ * offering it for render errors whose remedy differs (an over-allocation says to
+ * zoom in).
+ *
+ * A lost WebGPU device carries the same flag deliberately: the two causes
+ * differ, but the remedy on offer — take the page off the GPU — is the same one.
+ */
+export function createGpuContextLostError(message = CONTEXT_LOST_MESSAGE) {
+    return Object.assign(new Error(message), {
+        gpuContextLost: true,
+    });
+}
+export function createGpuDeviceLostError() {
+    return createGpuContextLostError(DEVICE_LOST_MESSAGE);
+}
+export function isGpuContextLostError(error) {
+    return (typeof error === 'object' && error !== null && 'gpuContextLost' in error);
+}
+/**
+ * The display's recovery budget, created on first read. Reached through the ref
+ * at every use site rather than unwrapped once in the hook body: the unwrapped
+ * value is a fresh binding each render, so an effect closing over it has to
+ * name it as a dependency, and then the effect re-subscribes on every render.
+ * The ref itself is stable and needs no dependency.
+ */
+function budgetOf(ref) {
+    return (ref.current ??= new RecoveryBudget());
+}
+function nodeAlive(model) {
+    if (isStateTreeNode(model)) {
+        return isAlive(model);
+    }
+    return true;
+}
+/**
+ * Drives the GPU/Canvas2D backend lifecycle for a display: canvas
+ * initialization, context-loss / device-loss recovery, page-navigation
+ * cleanup, and retry — wiring each event directly to the model's
+ * `RenderLifecycleMixin` actions so the model (not React-local hook state)
+ * owns every terminal state.
+ *
+ * The returned `canvasRef` is a callback ref — assign it directly to a
+ * `<canvas ref={canvasRef} />`. React invokes it with the DOM node on mount
+ * and with `null` on unmount, so the initialization effect re-runs when the
+ * underlying canvas element is actually replaced (e.g. after regionTooLarge
+ * unmounts then remounts the canvas).
+ *
+ * Lifecycle:
+ *   1. Canvas mounts → init effect calls `factory(canvas)`; on success
+ *      `setRenderError(undefined)` + `startRenderingBackend(backend)`, on
+ *      failure `setRenderError(error)`.
+ *   2. WebGL context loss → the browser gets one grace window to fire
+ *      `webglcontextrestored` (which bumps `contextVersion` → rebuild, no user-
+ *      visible state); if it doesn't, the loss is reported as `renderError`
+ *      (`createGpuContextLostError`), which unmounts the canvas and so is what
+ *      makes a fresh context obtainable at all. Bounded auto-recovery then
+ *      clears it. WebGPU device loss bumps `contextVersion` directly.
+ *   3. `retry()` clears `renderError` + bumps `contextVersion` so the next
+ *      mount reinitializes.
+ *
+ * Page navigation fires `pagehide` on every mounted component, disposing its
+ * backend AND clearing `model.currentRenderingBackend` (so the render/upload
+ * autoruns no-op); React unmount disposes via the effect cleanup. A bfcache
+ * restore fires `pageshow` with `persisted`, which rebuilds the backend for the
+ * still-mounted canvas. No global tracking.
+ *
+ * The model argument is duck-typed to the slot mixin's contract — the listed
+ * actions/fields are all the hook touches.
+ *
+ * **`factory` must be referentially stable** — a module-level constant, as every
+ * consumer in this repo passes (`AlignmentsRenderer`, `createDotplotRenderer`,
+ * …). It is a dependency of the init effect, so an inline
+ * `canvas => new MyBackend(canvas)` rebuilds the backend on every render:
+ * dispose, async re-create, `startRenderingBackend`, forever. Nothing throws and
+ * nothing logs — the display just paints from a backend a render behind, and the
+ * GPU churn shows up only in a profile. Bind the factory outside the component
+ * (or `useCallback` it with no deps).
+ */
+export function useRenderingBackend(factory, model) {
+    const [canvas, setCanvas] = useState(null);
+    const [contextVersion, setContextVersion] = useState(0);
+    const rendererRef = useRef(null);
+    // Set true the moment a `webglcontextlost` fires; gates auto-recovery so only
+    // a genuine context loss triggers it (not a config/render-logic error). The
+    // canvas often unmounts behind the error overlay before recovery runs, so
+    // recovery is driven by `renderError` (always observed) + this sticky flag,
+    // not by the canvas-bound listener.
+    const contextLostRef = useRef(false);
+    // One budget across both loss families, not one each: a display renders on a
+    // single HAL rung at a time, and sharing it stops a display that flaps
+    // between the two from spending a fresh allowance on each.
+    const budgetRef = useRef(null);
+    // Latched once the budget says stop. The recovery effect below runs on every
+    // render, so it needs a non-mutating way to know it has already given up —
+    // asking the budget again would refresh its window and it would never lapse.
+    const gaveUpRef = useRef(false);
+    const recoverTimerRef = useRef(undefined);
+    // Pending "the browser didn't restore it" report; see
+    // CONTEXT_LOST_REPORT_GRACE_MS. Separate from recoverTimerRef because the two
+    // are different phases: this one sets renderError, that one clears it.
+    const lossReportTimerRef = useRef(undefined);
+    // The element the component is showing RIGHT NOW, written in the commit phase
+    // by the ref callback — ahead of the passive effects, which is what makes it
+    // able to answer a question `canvas` cannot. See the init effect.
+    const currentCanvasRef = useRef(null);
+    const canvasRef = useCallback((node) => {
+        currentCanvasRef.current = node;
+        setCanvas(node);
+    }, []);
+    // A DIFFERENT model on the same component is a re-init, so it needs the fresh
+    // canvas element every other re-init gets, plus a clean recovery history —
+    // inheriting the old display's `gaveUp` latch would leave the new one unable
+    // to recover at all.
+    //
+    // Re-initializing on the element it was already using is a `dispose()` — which
+    // unconfigures the canvas's WebGPU swap chain — racing a `create()` on the same
+    // context, and whichever lands last decides whether the display can draw again.
+    //
+    // Defensive: no consumer reaches it today, because all three remount instead.
+    // A synteny band's section sits inside a Fragment keyed on `view.id`, and the
+    // `setViews` that replaces the levels mints fresh view ids along with them; a
+    // dotplot's model is its own view; and a display-type swap changes the element
+    // type, since no two display types registered for one track type share a
+    // `ReactComponent`. Each of those is one edit away from not being true, and
+    // what this costs is a ref and a compare.
+    //
+    // During render rather than in an effect, because the effect below must never
+    // observe the mismatched pair — a new model with the previous one's element.
+    // This is React's documented "adjust state when a prop changes": the render
+    // whose output is discarded is this one, before anything commits.
+    //
+    // The backoff a departing model armed is cancelled by the effect below, not
+    // here: a `clearTimeout` during render is a side effect, which `retry()` and
+    // `onRestored` can do and this cannot.
+    const lastModelRef = useRef(model);
+    if (lastModelRef.current !== model) {
+        lastModelRef.current = model;
+        contextLostRef.current = false;
+        gaveUpRef.current = false;
+        budgetOf(budgetRef).reset();
+        setContextVersion(v => v + 1);
+    }
+    useEffect(() => {
+        if (canvas) {
+            const onLost = (e) => {
+                // preventDefault is what permits `webglcontextrestored` at all; the timer
+                // below is the wait for it
+                e.preventDefault();
+                contextLostRef.current = true;
+                clearTimeout(lossReportTimerRef.current);
+                lossReportTimerRef.current = setTimeout(() => {
+                    lossReportTimerRef.current = undefined;
+                    if (nodeAlive(model)) {
+                        model.setRenderError(createGpuContextLostError());
+                    }
+                }, CONTEXT_LOST_REPORT_GRACE_MS);
+            };
+            const onRestored = () => {
+                // browser recovered on its own: cancel pending timers, reset, rebuild
+                // (every GL object from the old context is dead even though
+                // `isContextLost()` now reads false)
+                clearTimeout(lossReportTimerRef.current);
+                lossReportTimerRef.current = undefined;
+                clearTimeout(recoverTimerRef.current);
+                recoverTimerRef.current = undefined;
+                contextLostRef.current = false;
+                gaveUpRef.current = false;
+                budgetOf(budgetRef).reset();
+                setContextVersion(v => v + 1);
+            };
+            canvas.addEventListener('webglcontextlost', onLost);
+            canvas.addEventListener('webglcontextrestored', onRestored);
+            return () => {
+                // Drop a report still in its grace window: nothing left to recover, and
+                // `renderError` outranks every other phase, so a late one would replace a
+                // legitimate too-large banner with a GPU error.
+                clearTimeout(lossReportTimerRef.current);
+                lossReportTimerRef.current = undefined;
+                canvas.removeEventListener('webglcontextlost', onLost);
+                canvas.removeEventListener('webglcontextrestored', onRestored);
+            };
+        }
+        return undefined;
+    }, [canvas, model]);
+    // The third site that resets the recovery state, alongside `retry()` and
+    // `onRestored`, and like them it cancels the pending backoff first. A timer
+    // armed for the model that left bumps `contextVersion` when it fires, which
+    // rebuilds a device, pipeline set and swap chain for a display with nothing
+    // wrong with it — and until it fires it occupies the one-pending-timer guard
+    // below, so the arriving model cannot arm the recovery it is owed.
+    useEffect(() => {
+        clearTimeout(recoverTimerRef.current);
+        recoverTimerRef.current = undefined;
+    }, [model]);
+    // Auto-recover a context-loss-induced error: re-init on bounded backoff. Gated
+    // on `contextLostRef` so non-GPU render errors are never auto-retried, and on
+    // a one-pending-timer guard so it schedules at most one attempt at a time. The
+    // budget is spent only when an attempt is actually scheduled, so a context
+    // that keeps re-losing climbs to the cap then stops — never spins.
+    // Runs every render (no dep array) on purpose: the guards make it idempotent,
+    // and depending on `model.renderError` is unreliable here (a plain re-render
+    // can miss the value transition). The unmount cleanup is the separate effect
+    // below.
+    useEffect(() => {
+        if (model.renderError &&
+            contextLostRef.current &&
+            !gaveUpRef.current &&
+            recoverTimerRef.current === undefined) {
+            const budget = budgetOf(budgetRef);
+            if (budget.record(performance.now()) === 'give-up') {
+                gaveUpRef.current = true;
+                return;
+            }
+            const delay = CONTEXT_RECOVER_BASE_MS * 2 ** (budget.attempt - 1);
+            recoverTimerRef.current = setTimeout(() => {
+                recoverTimerRef.current = undefined;
+                if (nodeAlive(model)) {
+                    model.setRenderError(undefined);
+                }
+                setContextVersion(v => v + 1);
+            }, delay);
+        }
+    });
+    // Clear any pending loss-report / auto-recovery timer on unmount.
+    useEffect(() => () => {
+        clearTimeout(lossReportTimerRef.current);
+        clearTimeout(recoverTimerRef.current);
+    }, []);
+    // WebGPU device loss. This re-inits invisibly — no grace window and no
+    // `renderError`, because `gpuDevice` has already dropped the dead device and
+    // the next `getGpuDevice()` acquires a fresh one — but it is bounded by the
+    // same budget as the WebGL path, and for a sharper reason. A WebGL loss that
+    // never recovers is at least *reported*: it sets `renderError`, which is what
+    // unmounts the canvas. Nothing reports this one, so an uncapped version of it
+    // is a display that re-initializes against a dying device forever, silently,
+    // for as long as the tab is open. On give-up it says so instead.
+    useEffect(() => onDeviceLost(() => {
+        if (gaveUpRef.current) {
+            return;
+        }
+        if (budgetOf(budgetRef).record(performance.now()) === 'give-up') {
+            gaveUpRef.current = true;
+            if (nodeAlive(model)) {
+                model.setRenderError(createGpuDeviceLostError());
+            }
+            return;
+        }
+        setContextVersion(v => v + 1);
+    }), [model]);
+    useEffect(() => {
+        const handleGlobalPageHide = () => {
+            rendererRef.current?.dispose();
+            rendererRef.current = null;
+            // On a bfcache freeze this timer thaws AFTER pageshow rebuilt the backend,
+            // bannering a working canvas.
+            clearTimeout(lossReportTimerRef.current);
+            lossReportTimerRef.current = undefined;
+            // Also clear the model's backend reference — not just dispose the GPU
+            // object. On a bfcache navigate-away the component is frozen, not
+            // unmounted, so the effect cleanup never runs; leaving
+            // currentRenderingBackend pointing at the disposed backend would let the
+            // upload/render autoruns fire against dead GPU state on restore. With it
+            // cleared, those autoruns no-op (they guard `backend === undefined`) until
+            // pageshow rebuilds a fresh one.
+            if (nodeAlive(model)) {
+                model.stopRenderingBackend();
+            }
+        };
+        const handleGlobalPageShow = (e) => {
+            // Restored from bfcache (persisted): the canvas DOM node survived but its
+            // backend was disposed on pagehide. Bump contextVersion so the init effect
+            // re-runs and builds a fresh backend for the same canvas.
+            if (e.persisted) {
+                setContextVersion(v => v + 1);
+            }
+        };
+        window.addEventListener('pagehide', handleGlobalPageHide, true);
+        window.addEventListener('pageshow', handleGlobalPageShow, true);
+        return () => {
+            window.removeEventListener('pagehide', handleGlobalPageHide, true);
+            window.removeEventListener('pageshow', handleGlobalPageShow, true);
+        };
+    }, [model]);
+    useEffect(() => {
+        // Initialize the element the component is CURRENTLY showing, which the
+        // `canvas` state alone does not identify. Bumping `contextVersion` remounts
+        // the canvas, and the ref callback's `setCanvas(node2)` lands in a later
+        // render than the commit that swapped the element — so this effect runs once
+        // with the new version still paired to the previous, now-superseded element.
+        // Initializing there builds an entire backend (device, pipelines, swap
+        // chain) on an element nothing can see, attaches it, and discards it on the
+        // next render. That was the second live init behind the WebGPU swap-chain
+        // race: two overlapping `factory` calls whose teardown order decided which
+        // context was left configured.
+        //
+        // Compared against the ref rather than `canvas.isConnected`, which answers
+        // this only for a host that mounts into the document and would silently
+        // refuse to initialize for one that does not.
+        if (canvas && canvas === currentCanvasRef.current) {
+            let cancelled = false;
+            let backend = null;
+            factory(canvas)
+                .then(r => {
+                if (cancelled) {
+                    r.dispose();
+                }
+                else {
+                    backend = r;
+                    rendererRef.current = r;
+                    // Route HAL out-of-memory / over-device-limit allocation failures to
+                    // renderError so an over-large view shows an error overlay (with a
+                    // manual Retry) instead of a silently-blank canvas. Not gated on
+                    // contextLostRef, so it never auto-retries — an OOM recurs on retry.
+                    r.setErrorHandler(e => {
+                        if (nodeAlive(model)) {
+                            model.setRenderError(e);
+                        }
+                    });
+                    // init produced a backend: clear the context-loss scoping flag so a
+                    // later non-GPU error isn't mistaken for a context loss. The attempt
+                    // counter is deliberately NOT reset here — a context that resolves
+                    // then immediately re-loses must keep climbing toward the cap rather
+                    // than spin forever; only a real restore / manual retry resets it.
+                    contextLostRef.current = false;
+                    if (nodeAlive(model)) {
+                        model.setRenderError(undefined);
+                        model.startRenderingBackend(r);
+                    }
+                }
+            })
+                .catch((e) => {
+                if (!cancelled && nodeAlive(model)) {
+                    model.setRenderError(e);
+                }
+            });
+            return () => {
+                cancelled = true;
+                backend?.dispose();
+                rendererRef.current = null;
+                if (nodeAlive(model)) {
+                    model.stopRenderingBackend();
+                }
+            };
+        }
+        return undefined;
+    }, [canvas, contextVersion, factory, model]);
+    useTabVisibilityRerender(() => {
+        if (nodeAlive(model)) {
+            model.renderNow();
+        }
+    });
+    function retry() {
+        // manual retry = fresh start: cancel pending timers and reset the budget
+        clearTimeout(lossReportTimerRef.current);
+        lossReportTimerRef.current = undefined;
+        clearTimeout(recoverTimerRef.current);
+        recoverTimerRef.current = undefined;
+        contextLostRef.current = false;
+        gaveUpRef.current = false;
+        budgetOf(budgetRef).reset();
+        if (nodeAlive(model)) {
+            model.setRenderError(undefined);
+        }
+        setContextVersion(v => v + 1);
+    }
+    // `error` is sourced from model volatile, not React-local hook state: the
+    // model owns the terminal state, the hook only writes/reads it. Returned for
+    // standalone consumers (dotplot, synteny) that render their own banner;
+    // DisplayChrome reads `model.renderError` directly.
+    //
+    // `canvasKey` must reach the `<canvas key=…>` of EVERY consumer, not just the
+    // standalone ones. A re-init needs an element that never held a context:
+    // `getContext('webgl2')` keeps returning the lost one, `getContext('2d')`
+    // returns null on any element that once had WebGL, and more generally a
+    // canvas's context kind is permanent — so a re-init whose ladder lands on a
+    // different rung than last time cannot bind at all.
+    //
+    // This used to say DisplayChrome consumers got it free, because `renderError`
+    // unmounts the canvas. That covers only a *reported* loss: `onRestored`,
+    // `onDeviceLost` and the bfcache `pageshow` above all bump `contextVersion`
+    // and deliberately set no `renderError`, and those reused the element.
+    // `DisplayChromeBase` now keys its render-prop body on this value, and the
+    // standalone consumers get it from `RenderCanvas`.
+    return {
+        canvas,
+        canvasRef,
+        error: model.renderError,
+        retry,
+        canvasKey: contextVersion,
+    };
+}

package/esm/useTabVisibilityRerender.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Re-renders GPU canvases when the browser tab becomes visible again.
+ *
+ * WebGPU (and some WebGL configurations) discard the swap-chain texture when
+ * a tab is hidden. MobX autoruns only re-fire when observables change, so
+ * returning to the tab shows a black canvas. This hook triggers one extra
+ * render on `visibilitychange` to restore the content.
+ *
+ * Pass whatever function your component uses to issue GPU draw calls. It is
+ * captured via `useEventCallback` so it always sees the latest closure values
+ * without needing to be listed as a dependency.
+ */
+export declare function useTabVisibilityRerender(renderFn: () => void): void;

package/esm/useTabVisibilityRerender.js

@@ -0,0 +1,39 @@
+import { useEffect } from 'react';
+import { useEventCallback } from './useEventCallback.js';
+/**
+ * Re-renders GPU canvases when the browser tab becomes visible again.
+ *
+ * WebGPU (and some WebGL configurations) discard the swap-chain texture when
+ * a tab is hidden. MobX autoruns only re-fire when observables change, so
+ * returning to the tab shows a black canvas. This hook triggers one extra
+ * render on `visibilitychange` to restore the content.
+ *
+ * Pass whatever function your component uses to issue GPU draw calls. It is
+ * captured via `useEventCallback` so it always sees the latest closure values
+ * without needing to be listed as a dependency.
+ */
+export function useTabVisibilityRerender(renderFn) {
+    const stableRender = useEventCallback(renderFn);
+    useEffect(() => {
+        let rafId = null;
+        const handle = () => {
+            if (!document.hidden) {
+                // Schedule the render inside requestAnimationFrame so that
+                // getCurrentTexture() is called within a proper frame. Calling it
+                // directly from a visibilitychange handler can return a detached
+                // texture in WebGPU, causing the GPU timeline to hang.
+                rafId = requestAnimationFrame(() => {
+                    rafId = null;
+                    stableRender();
+                });
+            }
+        };
+        document.addEventListener('visibilitychange', handle);
+        return () => {
+            document.removeEventListener('visibilitychange', handle);
+            if (rafId !== null) {
+                cancelAnimationFrame(rafId);
+            }
+        };
+    }, [stableRender]);
+}

package/esm/webgpuUtils.d.ts

@@ -0,0 +1,23 @@
+export declare const STANDARD_BLEND_STATE: GPUBlendState;
+/**
+ * Creates a bind group for uniforms at binding 1.
+ * This bind group is intended for use with shaders generated by Slang,
+ * which typically place uniforms at binding index 1.
+ * @param device - The GPUDevice.
+ * @param layout - `DeviceLayouts.uniformOnlyBindGroupLayout`.
+ * @param uniformBuffer - The GPUBuffer containing the uniform data.
+ * @param uniformVisibleSize - The visible size of the uniform buffer.
+ * @returns The GPUBindGroup.
+ */
+export declare function createUniformOnlyBindGroup(device: GPUDevice, layout: GPUBindGroupLayout, uniformBuffer: GPUBuffer, uniformVisibleSize: number): GPUBindGroup;
+export declare function createVertexBuffer(device: GPUDevice, data: ArrayBuffer | ArrayBufferView): GPUBuffer;
+/**
+ * Converts one entry of a pass's vertex input layout to a WebGPU vertex format
+ * string. Example: { components: 2, type: 'float' } -> 'float32x2'
+ * @param attr - Vertex attribute descriptor.
+ * @returns GPUVertexFormat string.
+ */
+export declare function toGpuVertexFormat(attr: {
+    components: number;
+    type: 'float' | 'uint' | 'int';
+}): GPUVertexFormat;

package/esm/webgpuUtils.js

@@ -0,0 +1,76 @@
+/// <reference types="@webgpu/types" />
+// Standard alpha blend state:
+//   - Uses src-alpha, one-minus-src-alpha for color.
+//   - Converts straight (non-premultiplied) alpha output from shaders
+//     into premultiplied alpha in the framebuffer.
+// Shaders MUST output straight alpha: vec4(rgb, alpha).
+//
+// Some passes use a 'premultiplied' blend state ({ srcFactor: 'one' }).
+// Those shaders MUST output premultiplied alpha: vec4(rgb*alpha, alpha).
+export const STANDARD_BLEND_STATE = {
+    color: {
+        srcFactor: 'src-alpha',
+        dstFactor: 'one-minus-src-alpha',
+        operation: 'add',
+    },
+    alpha: {
+        srcFactor: 'one',
+        dstFactor: 'one-minus-src-alpha',
+        operation: 'add',
+    },
+};
+// Per-instance data is always fed through a vertex buffer (matching Slang's
+// vertex-attribute input semantics). The bind group carries only the uniform
+// at binding 1 (and, optionally, a texture + sampler at 2/3). Binding index 1
+// matches what the codegen emits so shaders share the same @binding(1)
+// annotation regardless of whether they sample textures, and
+// `assertRenderBindingShape` is what checks that rather than promising it.
+//
+// The layouts themselves are built once per device in `hal/deviceGpuCache.ts`;
+// a bind GROUP is per-HAL, because it names that HAL's uniform ring buffer.
+/**
+ * Creates a bind group for uniforms at binding 1.
+ * This bind group is intended for use with shaders generated by Slang,
+ * which typically place uniforms at binding index 1.
+ * @param device - The GPUDevice.
+ * @param layout - `DeviceLayouts.uniformOnlyBindGroupLayout`.
+ * @param uniformBuffer - The GPUBuffer containing the uniform data.
+ * @param uniformVisibleSize - The visible size of the uniform buffer.
+ * @returns The GPUBindGroup.
+ */
+export function createUniformOnlyBindGroup(device, layout, uniformBuffer, uniformVisibleSize) {
+    return device.createBindGroup({
+        layout,
+        entries: [
+            {
+                binding: 1, // Standard binding for uniforms generated by Slang codegen.
+                resource: {
+                    buffer: uniformBuffer,
+                    offset: 0,
+                    size: uniformVisibleSize,
+                },
+            },
+        ],
+    });
+}
+export function createVertexBuffer(device, data) {
+    const buf = device.createBuffer({
+        // WebGPU buffers must be at least 4 bytes in size.
+        size: Math.max(data.byteLength, 4),
+        usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
+    });
+    device.queue.writeBuffer(buf, 0, data);
+    return buf;
+}
+/**
+ * Converts one entry of a pass's vertex input layout to a WebGPU vertex format
+ * string. Example: { components: 2, type: 'float' } -> 'float32x2'
+ * @param attr - Vertex attribute descriptor.
+ * @returns GPUVertexFormat string.
+ */
+export function toGpuVertexFormat(attr) {
+    const base = attr.type === 'uint' ? 'uint32' : attr.type === 'int' ? 'sint32' : 'float32';
+    return attr.components === 1
+        ? base
+        : `${base}x${attr.components}`;
+}