@downdraft/engine 0.1.1 → 0.1.2-alpha.5

package/dist/core/src/render/renderer-module-host.js

@@ -0,0 +1,539 @@
+// ============================================================================
+// RendererModuleHost — owns renderer-plugin lifecycle and dispatch
+//
+// Owned by `GameRenderer`. Holds the `RendererInputBus`, the active
+// `CameraControllerLike`, and per-phase frame/resize/render-pass hook lists.
+// Each plugin receives a per-plugin `RendererModuleContext` facade during
+// `register()` so hooks/dispose fns are tracked per-plugin and cleaned up on
+// `unloadModule`.
+//
+// Setters for offscreen/render-target/RAF are routed to the `GameRenderer`
+// via callbacks supplied at construction — the host does not import
+// `GameRenderer` directly (avoids a circular import).
+// ============================================================================
+import { assertNoDuplicate, assertRequired, isStrict, warnLeak } from "../module/diagnostics.js";
+import { getNativeHost } from "../platform/runtime.js";
+import { createLogger } from "../util/logger.js";
+import { RendererInputBusImpl } from "./renderer-input-bus.js";
+const log = createLogger();
+export class RendererModuleHost {
+    canvas;
+    callbacks;
+    inputBus;
+    plugins = new Map();
+    loadOrder = [];
+    active = new Map();
+    /** Plugins registered via registerModuleDeferred() but not yet activated. */
+    pending = new Map();
+    /** Typed resource store: tokenKey → { token, value } */
+    resources = new Map();
+    /** Reverse map: tokenKey → provider plugin name */
+    providers = new Map();
+    frameHooks = {
+        beforeFrame: [],
+        beforeViewports: [],
+        afterViewports: [],
+        afterFrame: [],
+    };
+    resizeHooks = [];
+    renderPassHooks = [];
+    cameraController = null;
+    /** Name of the module that installed the current camera controller (for unload cleanup). */
+    cameraControllerOwner = null;
+    viewportCameraProvider = null;
+    /** Name of the module that installed the current viewport camera provider (for unload cleanup). */
+    viewportCameraProviderOwner = null;
+    _devtools = null;
+    constructor(canvas, callbacks) {
+        this.canvas = canvas;
+        this.callbacks = callbacks;
+        this.inputBus = new RendererInputBusImpl(canvas);
+    }
+    /**
+     * Inject the DevTools API so renderer plugins can self-register debug
+     * panels via `ctx.devtools.registerPanel(...)` during their `register()`.
+     */
+    setDevToolsAPI(api) {
+        this._devtools = api;
+    }
+    // ── Registration ──
+    registerModule(plugin) {
+        if (this.plugins.has(plugin.name)) {
+            throw new Error(`Renderer plugin "${plugin.name}" already registered`);
+        }
+        if (plugin.dependencies) {
+            for (let i = 0; i < plugin.dependencies.length; i++) {
+                if (!this.plugins.has(plugin.dependencies[i])) {
+                    throw new Error(`Renderer plugin "${plugin.name}" requires "${plugin.dependencies[i]}" which is not registered`);
+                }
+            }
+        }
+        // isStrict(): validate provides/requires against already-active plugins.
+        if (isStrict()) {
+            const selfProvides = new Set(plugin.provides?.map((t) => t.key) ?? []);
+            // Check for duplicate provides
+            (plugin.provides ?? []).forEach((token) => {
+                if (this.providers.has(token.key)) {
+                    throw new Error(`Renderer plugin "${plugin.name}" provides "${token.key}" but it is already provided by "${this.providers.get(token.key)}". ` +
+                        `Duplicate provides are not allowed.`);
+                }
+            });
+            // Check requires
+            (plugin.requires ?? []).forEach((token) => {
+                if (!this.providers.has(token.key) && !selfProvides.has(token.key)) {
+                    assertRequired(this.providers, token, plugin.name);
+                }
+            });
+        }
+        this.plugins.set(plugin.name, plugin);
+        this.loadOrder.push(plugin.name);
+        this.activateModule(plugin);
+    }
+    /**
+     * Register a renderer plugin without activating it.
+     * Call `activateAll()` after all plugins are registered
+     * to activate them in dependency-resolved order (topological sort).
+     */
+    registerModuleDeferred(plugin) {
+        if (this.plugins.has(plugin.name)) {
+            throw new Error(`Renderer plugin "${plugin.name}" already registered`);
+        }
+        this.plugins.set(plugin.name, plugin);
+        this.pending.set(plugin.name, plugin);
+    }
+    /**
+     * Validate the full dependency graph across all pending + active renderer plugins.
+     * Called before batch activation in activateAll().
+     */
+    validateGraph() {
+        if (!isStrict())
+            return;
+        // Build a complete providers map from all pending + active plugins
+        const allProviders = new Map();
+        for (const [name, active] of this.active.entries()) {
+            (active.plugin.provides ?? []).forEach((token) => {
+                allProviders.set(token.key, name);
+            });
+        }
+        for (const [name, plugin] of this.pending.entries()) {
+            (plugin.provides ?? []).forEach((token) => {
+                if (allProviders.has(token.key)) {
+                    throw new Error(`Renderer plugin "${name}" provides "${token.key}" but it is already provided by "${allProviders.get(token.key)}". ` +
+                        `Duplicate provides are not allowed.`);
+                }
+                allProviders.set(token.key, name);
+            });
+        }
+        // Check all requires
+        for (const [name, plugin] of this.pending.entries()) {
+            if (!plugin.requires)
+                continue;
+            plugin.requires.forEach((token) => {
+                if (!allProviders.has(token.key)) {
+                    assertRequired(allProviders, token, name);
+                }
+            });
+        }
+    }
+    /**
+     * Activate all plugins registered via `registerModuleDeferred()` in
+     * dependency-resolved order (topological sort by `dependencies` AND
+     * `requires` tokens — a plugin that requires a token activates after
+     * whichever pending/active plugin provides it).
+     * Plugins with no dependencies are activated first.
+     *
+     * In DOWNDRAFT_STRICT mode, validates the full dependency graph
+     * (provides/requires) before activating any plugin.
+     */
+    activateAll() {
+        this.validateGraph();
+        // Provider map: token key → module name (across pending + active).
+        const tokenProviders = new Map();
+        const collectProvides = (plugin) => {
+            (plugin.provides ?? []).forEach((token) => {
+                if (!tokenProviders.has(token.key))
+                    tokenProviders.set(token.key, plugin.name);
+            });
+        };
+        for (const [, active] of this.active.entries())
+            collectProvides(active.plugin);
+        for (const [, plugin] of this.pending.entries())
+            collectProvides(plugin);
+        // Topological sort by dependencies (string-based plugin names) and by
+        // requires (typed tokens → provider module).
+        const resolved = [];
+        const visited = new Set();
+        const visiting = new Set();
+        const resolve = (name) => {
+            if (visited.has(name))
+                return;
+            if (visiting.has(name)) {
+                throw new Error(`Circular renderer plugin dependency detected at "${name}"`);
+            }
+            visiting.add(name);
+            const plugin = this.pending.get(name);
+            if (plugin) {
+                if (plugin.dependencies) {
+                    plugin.dependencies.forEach((dep) => {
+                        if (!this.plugins.has(dep)) {
+                            throw new Error(`Renderer plugin "${name}" requires "${dep}" which is not registered`);
+                        }
+                        if (this.pending.has(dep))
+                            resolve(dep);
+                    });
+                }
+                if (plugin.requires) {
+                    plugin.requires.forEach((token) => {
+                        const providerName = tokenProviders.get(token.key);
+                        if (providerName && providerName !== name && this.pending.has(providerName)) {
+                            resolve(providerName);
+                        }
+                    });
+                }
+            }
+            visiting.delete(name);
+            visited.add(name);
+            resolved.push(name);
+        };
+        for (const name of this.pending.keys()) {
+            resolve(name);
+        }
+        resolved.forEach((name) => {
+            if (this.pending.has(name) && !this.active.has(name)) {
+                const plugin = this.pending.get(name);
+                this.pending.delete(name);
+                this.loadOrder.push(name);
+                this.activateModule(plugin);
+            }
+        });
+    }
+    /**
+     * Register and activate multiple renderer plugins in dependency-resolved order.
+     * This is the standard batch registration pattern — equivalent to
+     * calling `registerModuleDeferred()` for each plugin followed by
+     * `activateAll()`. Use this when multiple plugins have interdependencies
+     * (via `provides`/`requires` typed tokens or `dependencies` string arrays).
+     */
+    useModules(plugins) {
+        for (let i = 0; i < plugins.length; i++) {
+            this.registerModuleDeferred(plugins[i]);
+        }
+        this.activateAll();
+    }
+    activateModule(plugin) {
+        const active = {
+            plugin,
+            disposeFns: [],
+            providedKeys: new Set(),
+            frameHookIds: new Map(),
+        };
+        this.active.set(plugin.name, active);
+        const ctx = this.makeContext(plugin.name, active);
+        try {
+            plugin.register(ctx);
+        }
+        catch (err) {
+            // Roll back partial activation, then re-throw so the caller sees it —
+            // mirrors ModuleHost semantics (a failed register() must not be silent).
+            this.unloadModule(plugin.name);
+            throw err;
+        }
+    }
+    unloadModule(name) {
+        const active = this.active.get(name);
+        if (!active)
+            return;
+        if (isStrict()) {
+            warnLeak(name, {
+                providedCount: active.providedKeys.size,
+                sabCount: 0, // renderer plugins don't allocate SAB channels
+                disposeFnCount: active.disposeFns.length,
+            });
+        }
+        // Clean up provided resources
+        for (const key of active.providedKeys.values()) {
+            this.resources.delete(key);
+            this.providers.delete(key);
+        }
+        for (let i = active.disposeFns.length - 1; i >= 0; i--) {
+            try {
+                active.disposeFns[i]();
+            }
+            catch (err) {
+                log.error("renderer-module-host", `Dispose error in plugin "${name}": ${err}`);
+            }
+        }
+        // Remove this plugin's hooks.
+        this.frameHooks.beforeFrame = this.frameHooks.beforeFrame.filter((h) => h.owner !== name);
+        this.frameHooks.beforeViewports = this.frameHooks.beforeViewports.filter((h) => h.owner !== name);
+        this.frameHooks.afterViewports = this.frameHooks.afterViewports.filter((h) => h.owner !== name);
+        this.frameHooks.afterFrame = this.frameHooks.afterFrame.filter((h) => h.owner !== name);
+        this.resizeHooks = this.resizeHooks.filter((h) => h.owner !== name);
+        this.renderPassHooks = this.renderPassHooks.filter((h) => h.owner !== name);
+        // If this plugin owned the camera controller / viewport camera provider,
+        // clear it so a disposed object isn't invoked on the next frame. (If
+        // another plugin overwrote the slot later, its ownership is preserved.)
+        if (this.cameraControllerOwner === name) {
+            this.cameraController = null;
+            this.cameraControllerOwner = null;
+        }
+        if (this.viewportCameraProviderOwner === name) {
+            this.viewportCameraProvider = null;
+            this.viewportCameraProviderOwner = null;
+        }
+        this.active.delete(name);
+        this.plugins.delete(name);
+        this.pending.delete(name);
+        const idx = this.loadOrder.indexOf(name);
+        if (idx >= 0)
+            this.loadOrder.splice(idx, 1);
+    }
+    disposeAll() {
+        // Unload in reverse registration order.
+        const names = [...this.loadOrder].reverse();
+        names.forEach((name) => { this.unloadModule(name); ; });
+        this.inputBus.destroy();
+        this.cameraController = null;
+        this.cameraControllerOwner = null;
+        this.viewportCameraProvider = null;
+        this.viewportCameraProviderOwner = null;
+    }
+    // ── Getters ──
+    getInputBus() {
+        return this.inputBus;
+    }
+    getCameraController() {
+        return this.cameraController;
+    }
+    getModule(name) {
+        return this.plugins.get(name);
+    }
+    listModules() {
+        return [...this.loadOrder];
+    }
+    /**
+     * Produce a thread-tagged snapshot of all active renderer modules for the
+     * cross-thread report + doctor panel. `thread` is normally "renderer" but
+     * is parameterized for symmetry with `ModuleHost.snapshot()`.
+     *
+     * Tokens created via `crossThreadToken()` carry a `__thread` tag; the
+     * snapshot records it in `tokenThreads` so `buildCrossThreadReport()`
+     * can flag tokens provided on the wrong thread.
+     */
+    snapshot(thread) {
+        const out = [];
+        for (const [name, active] of this.active.entries()) {
+            const plugin = active.plugin;
+            const tokenThreads = {};
+            const collectTags = (tokens) => {
+                (tokens ?? []).forEach((t) => {
+                    const tag = t.__thread;
+                    if (tag)
+                        tokenThreads[t.key] = tag;
+                });
+            };
+            collectTags(plugin.provides);
+            collectTags(plugin.requires);
+            out.push({
+                name,
+                version: plugin.version,
+                thread,
+                provides: (plugin.provides ?? []).map((t) => t.key),
+                requires: (plugin.requires ?? []).map((t) => t.key),
+                active: true,
+                tokenThreads: Object.keys(tokenThreads).length > 0 ? tokenThreads : undefined,
+            });
+        }
+        return out;
+    }
+    // ── Dispatch (called by GameRenderer) ──
+    dispatchFrame(phase, dt, elapsedTime) {
+        const hooks = this.frameHooks[phase];
+        for (let i = 0; i < hooks.length; i++) {
+            try {
+                hooks[i].fn(dt, elapsedTime);
+            }
+            catch (err) {
+                log.error("renderer-module-host", `Frame hook error (${phase}) in "${hooks[i].owner}": ${err}`);
+            }
+        }
+    }
+    dispatchResize(cssWidth, cssHeight, dpr) {
+        for (let i = 0; i < this.resizeHooks.length; i++) {
+            try {
+                this.resizeHooks[i].fn(cssWidth, cssHeight, dpr);
+            }
+            catch (err) {
+                log.error("renderer-module-host", `Resize hook error in "${this.resizeHooks[i].owner}": ${err}`);
+            }
+        }
+        this.cameraController?.setAspect(Math.round(cssWidth * dpr), Math.round(cssHeight * dpr));
+    }
+    dispatchRenderPass(passEncoder, camera, viewportIdx) {
+        for (let i = 0; i < this.renderPassHooks.length; i++) {
+            try {
+                this.renderPassHooks[i].fn(passEncoder, camera, viewportIdx);
+            }
+            catch (err) {
+                log.error("renderer-module-host", `Render-pass hook error in "${this.renderPassHooks[i].owner}": ${err}`);
+            }
+        }
+    }
+    /**
+     * Returns the active camera controller's state for a viewport, or null if
+     * no controller is registered. `GameRenderer` uses this as a fallback when
+     * the game's `onViewport` callback returns null.
+     */
+    getCameraState(viewportIdx) {
+        if (!this.cameraController)
+            return null;
+        try {
+            return this.cameraController.getCameraState(viewportIdx);
+        }
+        catch (err) {
+            log.error("renderer-module-host", `Camera controller error: ${err}`);
+            return null;
+        }
+    }
+    /**
+     * If a viewport camera provider is installed (e.g. by XR), call it for the
+     * given viewport. Returns the provider's result or null. `GameRenderer`
+     * calls this *before* the game's `onViewport` callback — a non-null result
+     * takes priority.
+     */
+    getViewportCameraInfo(viewportIdx, dt, elapsedTime) {
+        if (!this.viewportCameraProvider)
+            return null;
+        try {
+            return this.viewportCameraProvider(viewportIdx, dt, elapsedTime);
+        }
+        catch (err) {
+            log.error("renderer-module-host", `Viewport camera provider error: ${err}`);
+            return null;
+        }
+    }
+    // ── Typed DI (renderer-side) ──
+    /**
+     * Provide a typed resource to the renderer plugin graph. Called from the
+     * per-plugin context facade.
+     */
+    provideResource(name, token, value, active) {
+        if (isStrict()) {
+            assertNoDuplicate(this.providers, token, name);
+        }
+        this.resources.set(token.key, { token: token, value });
+        this.providers.set(token.key, name);
+        active.providedKeys.add(token.key);
+    }
+    /**
+     * Provide a typed resource from an external provider (e.g. the LibraryHost).
+     * Unlike `provideResource`, this does not require an active plugin context.
+     * The `providerName` is used for diagnostics and cleanup tracking.
+     */
+    provideExternal(providerName, token, value) {
+        if (isStrict()) {
+            assertNoDuplicate(this.providers, token, providerName);
+        }
+        this.resources.set(token.key, { token: token, value });
+        this.providers.set(token.key, providerName);
+    }
+    /**
+     * Inject a typed resource from the renderer plugin graph. Public so the
+     * LibraryHost can read resources provided by renderer plugins.
+     */
+    injectResource(token) {
+        const entry = this.resources.get(token.key);
+        if (!entry) {
+            throw new Error(`Renderer plugin injects "${token.key}" which is not provided. ` +
+                `Add a plugin that provides it, or use injectOptional() for safe reads.`);
+        }
+        return entry.value;
+    }
+    /**
+     * Inject a typed resource optionally. Public so the LibraryHost can read
+     * resources provided by renderer plugins.
+     */
+    injectResourceOptional(token) {
+        const entry = this.resources.get(token.key);
+        return entry?.value;
+    }
+    // ── Per-plugin context facade ──
+    makeContext(name, active) {
+        const devtoolsApi = () => this._devtools ?? NoopRendererDevToolsAPI;
+        return {
+            name,
+            getSurface: () => this.callbacks.getSurface(),
+            getCanvas: () => this.callbacks.getSurface(),
+            getDevice: () => this.callbacks.getDevice(),
+            getFormat: () => this.callbacks.getFormat(),
+            getGraph: () => this.callbacks.getGraph(),
+            getSlotRegistry: () => this.callbacks.getSlotRegistry(),
+            getInputBus: () => this.inputBus,
+            getUIInputRouter: () => this.callbacks.getUIInputRouter(),
+            registerUiCompositor: this.callbacks.registerUiCompositor
+                ? (c) => this.callbacks.registerUiCompositor(c)
+                : undefined,
+            // The mailbox lives on the native host — null on browser/standalone.
+            getGpuPassMailbox: () => getNativeHost()?.passMailbox ?? null,
+            onFrame: (phase, fn) => {
+                const entry = { owner: name, fn };
+                this.frameHooks[phase].push(entry);
+                return () => {
+                    const arr = this.frameHooks[phase];
+                    const idx = arr.indexOf(entry);
+                    if (idx >= 0)
+                        arr.splice(idx, 1);
+                };
+            },
+            onResize: (fn) => {
+                const entry = { owner: name, fn };
+                this.resizeHooks.push(entry);
+                return () => {
+                    const idx = this.resizeHooks.indexOf(entry);
+                    if (idx >= 0)
+                        this.resizeHooks.splice(idx, 1);
+                };
+            },
+            onRenderPass: (fn) => {
+                const entry = { owner: name, fn };
+                this.renderPassHooks.push(entry);
+                return () => {
+                    const idx = this.renderPassHooks.indexOf(entry);
+                    if (idx >= 0)
+                        this.renderPassHooks.splice(idx, 1);
+                };
+            },
+            setCameraController: (controller) => {
+                // Only one active controller at a time. Last writer wins; a plugin
+                // should null this in its dispose fn if it wants to release the slot.
+                this.cameraController = controller;
+                this.cameraControllerOwner = controller ? name : null;
+            },
+            getCameraController: () => this.cameraController,
+            setViewportCameraProvider: (provider) => {
+                this.viewportCameraProvider = provider;
+                this.viewportCameraProviderOwner = provider ? name : null;
+            },
+            setViewportCount: (count) => this.callbacks.setViewportCount(count),
+            setOffscreenMode: (mode) => this.callbacks.setOffscreenMode(mode),
+            setRenderTargetProvider: (provider) => this.callbacks.setRenderTargetProvider(provider),
+            setRAFSource: (src, cancel) => this.callbacks.setRAFSource(src, cancel),
+            // Lazy — the DevTools API may be injected after register() runs.
+            get devtools() { return devtoolsApi(); },
+            provide: (token, value) => this.provideResource(name, token, value, active),
+            inject: (token) => this.injectResource(token),
+            injectOptional: (token) => this.injectResourceOptional(token),
+            onDispose: (fn) => {
+                active.disposeFns.push(fn);
+            },
+        };
+    }
+}
+// No-op DevTools API stub — used when setDevToolsAPI() hasn't been called.
+const NoopRendererDevToolsAPI = {
+    registerPanel: () => { },
+    registerOverlayToggle: () => { },
+    registerDataFeed: () => { },
+    registerCommand: () => { },
+    registerSABStat: () => { },
+};

package/dist/core/src/render/resource-tracker.js

@@ -0,0 +1,59 @@
+/**
+ * GPU resource destruction helpers.
+ *
+ * WebGPU objects (GPURenderPipeline, GPUBuffer, GPUTexture, GPUShaderModule,
+ * GPUBindGroup, GPUSampler, GPUTextureView) should be explicitly `.destroy()`ed
+ * when no longer needed. These helpers ensure all resources in a collection are
+ * destroyed before the collection is cleared.
+ */
+/**
+ * Calls `.destroy()` on every non-null resource in the array.
+ * Swallows errors from individual destroy calls so one failure doesn't
+ * prevent cleanup of remaining resources.
+ */
+export function destroyAll(resources) {
+    resources.forEach((res) => {
+        if (res) {
+            try {
+                res.destroy();
+            }
+            catch {
+                // Swallow — resource may already be destroyed or invalid
+            }
+        }
+    });
+}
+/**
+ * Destroys all values in a Map that hold destroyable resources, then clears
+ * the map. Safe to call on maps with mixed value types — non-destroyable
+ * values are simply removed.
+ */
+export function destroyMapValues(map) {
+    for (const value of map.values()) {
+        if (value && typeof value.destroy === "function") {
+            try {
+                value.destroy();
+            }
+            catch {
+                // Swallow
+            }
+        }
+    }
+    map.clear();
+}
+/**
+ * Destroys a single resource if it is non-null and has a destroy method.
+ * Sets the property to null after destruction (via a setter callback).
+ */
+export function destroyAndNull(getResource, setResource) {
+    const res = getResource();
+    if (res) {
+        try {
+            res.destroy();
+        }
+        catch {
+            // Swallow
+        }
+    }
+    setResource(null);
+}

package/dist/core/src/render/sab-canvas-overlay.js

@@ -0,0 +1,83 @@
+// ============================================================================
+// SabCanvasOverlay — DOM <canvas> overlay backed by a SharedArrayBuffer bitmap
+//
+// Generalized from overburden's MapCanvas. Provides the generic shell:
+//   - A visible <canvas> fixed-positioned over the game canvas
+//     (pointer-events: none, configurable z-index, hidden while opacity <= 0).
+//   - An offscreen "bitmap" canvas at a fixed data resolution that is repainted
+//     only when a SAB sequence counter changes (via getSeq + redrawBitmap).
+//   - Per-frame window resize tracking and opacity control.
+//
+// The game supplies the compositing + drawing logic via callbacks; the overlay
+// owns all DOM plumbing.
+// ============================================================================
+export class SabCanvasOverlay {
+    canvas;
+    ctx;
+    /** Offscreen bitmap canvas (fixed data resolution). Null when unconfigured. */
+    bitmapCanvas = null;
+    bitmapCtx = null;
+    opts;
+    lastSeq = -1;
+    constructor(opts) {
+        this.opts = opts;
+        this.canvas = document.createElement("canvas");
+        this.canvas.id = opts.id ?? "sab-canvas-overlay";
+        this.canvas.style.position = "fixed";
+        this.canvas.style.top = "0";
+        this.canvas.style.left = "0";
+        this.canvas.style.width = "100%";
+        this.canvas.style.height = "100%";
+        this.canvas.style.pointerEvents = "none";
+        this.canvas.style.zIndex = String(opts.zIndex ?? 55);
+        this.canvas.style.display = "none"; // hidden until opacity > 0
+        this.canvas.style.imageRendering = opts.imageRendering ?? "pixelated";
+        this.ctx = this.canvas.getContext("2d");
+        if (opts.bitmapWidth !== undefined && opts.bitmapHeight !== undefined) {
+            this.bitmapCanvas = document.createElement("canvas");
+            this.bitmapCanvas.width = opts.bitmapWidth;
+            this.bitmapCanvas.height = opts.bitmapHeight;
+            this.bitmapCtx = this.bitmapCanvas.getContext("2d");
+        }
+    }
+    /** Attach the canvas to the DOM (call once during init). */
+    mount(parent = document.body) {
+        parent.appendChild(this.canvas);
+    }
+    /**
+     * Per-frame update. Call from the render loop.
+     * Hides the canvas while `opacity <= 0`; otherwise resizes the canvas to the
+     * window, repaints the bitmap when the seq counter advanced, and invokes
+     * the draw callback.
+     */
+    update(opacity) {
+        if (opacity <= 0) {
+            this.canvas.style.display = "none";
+            return;
+        }
+        this.canvas.style.display = "block";
+        this.canvas.style.opacity = String(opacity);
+        // Resize the visible canvas to match the window if needed.
+        const w = window.innerWidth;
+        const h = window.innerHeight;
+        if (this.canvas.width !== w || this.canvas.height !== h) {
+            this.canvas.width = w;
+            this.canvas.height = h;
+        }
+        // Repaint the bitmap if the backing data has a new seq value.
+        const seq = this.opts.getSeq?.();
+        if (this.bitmapCtx && (seq === undefined || seq !== this.lastSeq)) {
+            if (seq !== undefined)
+                this.lastSeq = seq;
+            this.opts.redrawBitmap?.(this.bitmapCtx, this.bitmapCanvas.width, this.bitmapCanvas.height);
+        }
+        this.opts.draw(this.ctx, this.bitmapCanvas, w, h);
+    }
+    /** Mark the bitmap stale so it repaints on the next visible frame. */
+    invalidate() {
+        this.lastSeq = -1;
+    }
+    dispose() {
+        this.canvas.remove();
+    }
+}