@downdraft/engine 0.1.1 → 0.2.0

package/dist/libraries/audio-kira/src/backend.js

@@ -0,0 +1,405 @@
+import { createLogger } from "@downdraft/engine";
+import { findPackageRoot } from "@downdraft/engine/platform/pkg-root";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const log = createLogger();
+let audioLoadAttempted = false;
+async function loadAudioLib() {
+    if (audioLoadAttempted)
+        return null;
+    audioLoadAttempted = true;
+    try {
+        const { dlopen, ptr, resolveNativeLibrary } = await import("@downdraft/platform-native");
+        const libPath = resolveNativeLibrary("downdraft_audio", {
+            envVars: ["AUDIO_NATIVE_PATH"],
+            crateDir: join(findPackageRoot(dirname(fileURLToPath(import.meta.url))), "libraries", "audio-kira", "native"),
+            buildHint: 'run "bun run build:native" from the repo root',
+            optional: true,
+        });
+        if (!libPath) {
+            log.info("audio-kira", "Using JS audio backend (no native library available).");
+            return null;
+        }
+        const s = dlopen(libPath, {
+            dd_audio_init: { args: ["i32", "i32"], returns: "i32" },
+            dd_audio_destroy: { args: [], returns: "i32" },
+            dd_audio_load_buffer: { args: ["ptr", "u64", "i32"], returns: "i32" },
+            dd_audio_unload_buffer: { args: ["i32"], returns: "i32" },
+            dd_audio_play: { args: ["i32", "i32", "f32"], returns: "i32" },
+            dd_audio_stop: { args: ["i32"], returns: "i32" },
+            dd_audio_pause: { args: ["i32"], returns: "i32" },
+            dd_audio_resume: { args: ["i32"], returns: "i32" },
+            dd_audio_set_volume: { args: ["i32", "f32"], returns: "i32" },
+            dd_audio_set_master_volume: { args: ["f32"], returns: "i32" },
+            dd_audio_update: { args: [], returns: "i32" },
+            dd_audio_is_playing: { args: ["i32"], returns: "i32" },
+        }).symbols;
+        log.info("audio-kira", `Native audio backend: ${libPath}`);
+        return {
+            init: (sr, bs) => s.dd_audio_init(sr, bs),
+            destroy: () => s.dd_audio_destroy(),
+            // from_cursor copies the bytes — safe to hand over a transient view.
+            loadBuffer: (data, format) => s.dd_audio_load_buffer(ptr(data), data.byteLength, format),
+            unloadBuffer: (id) => s.dd_audio_unload_buffer(id),
+            play: (b, loop, vol) => s.dd_audio_play(b, loop, vol),
+            stop: (id) => s.dd_audio_stop(id),
+            pause: (id) => s.dd_audio_pause(id),
+            resume: (id) => s.dd_audio_resume(id),
+            setVolume: (id, v) => s.dd_audio_set_volume(id, v),
+            setMasterVolume: (v) => s.dd_audio_set_master_volume(v),
+            update: () => s.dd_audio_update(),
+            isPlaying: (id) => s.dd_audio_is_playing(id),
+        };
+    }
+    catch (e) {
+        log.info("audio-kira", `Native audio unavailable (${e}) — using JS backend.`);
+        return null;
+    }
+}
+const FORMAT_MAP = {
+    wav: 0,
+    ogg: 1,
+    mp3: 2,
+    flac: 3,
+};
+const CHANNEL_VOLUMES = {
+    master: 1.0,
+    sfx: 0.8,
+    music: 0.7,
+    voice: 0.9,
+    ambient: 0.6,
+    ui: 0.8,
+};
+const CHANNEL_MUTED = {
+    master: false,
+    sfx: false,
+    music: false,
+    voice: false,
+    ambient: false,
+    ui: false,
+};
+export class KiraAudioBackend {
+    name = "kira";
+    version = "0.1.0";
+    lib = null;
+    buffers = new Map();
+    sources = new Map();
+    listener = {
+        position: [0, 0, 0],
+        orientation: [0, 0, 0, 1],
+        velocity: [0, 0, 0],
+        gain: 1.0,
+    };
+    nextBufferId = 1;
+    nextSourceId = 1;
+    initialized = false;
+    destroyed = false;
+    async init(config) {
+        if (this.initialized)
+            return;
+        this.lib = await loadAudioLib();
+        if (this.lib) {
+            const result = this.lib.init(config.sampleRate, config.bufferSize);
+            if (result !== 0) {
+                log.warn("audio-kira", "Native init failed, falling back to JS mode");
+                this.lib = null;
+            }
+        }
+        this.initialized = true;
+    }
+    isInitialized() {
+        return this.initialized;
+    }
+    loadBuffer(desc) {
+        const id = String(this.nextBufferId++);
+        const data = desc.samples.buffer;
+        const format = typeof desc.format === "string" ? desc.format : "wav";
+        const samples = desc.samples;
+        let nativeBufferId = -1;
+        if (this.lib) {
+            const result = this.lib.loadBuffer(new Uint8Array(data), FORMAT_MAP[format] ?? 0);
+            if (result > 0) {
+                nativeBufferId = result;
+            }
+        }
+        const buffer = {
+            id,
+            format,
+            sampleRate: desc.sampleRate ?? 44100,
+            channels: desc.channels ?? 2,
+            samples,
+            duration: samples.length / (desc.sampleRate ?? 44100),
+        };
+        buffer._nativeId = nativeBufferId;
+        this.buffers.set(id, buffer);
+    }
+    unloadBuffer(bufferId) {
+        const buffer = this.buffers.get(String(bufferId));
+        if (!buffer)
+            return;
+        if (this.lib) {
+            const nativeId = buffer._nativeId;
+            if (nativeId && nativeId > 0) {
+                this.lib.unloadBuffer(nativeId);
+            }
+        }
+        this.buffers.delete(String(bufferId));
+    }
+    getBuffer(bufferId) {
+        return this.buffers.get(String(bufferId));
+    }
+    play(bufferId, opts) {
+        const buffer = this.buffers.get(String(bufferId));
+        if (!buffer)
+            throw new Error(`Audio buffer ${bufferId} not found`);
+        const sourceId = this.nextSourceId++;
+        const handle = {
+            sourceId,
+            bufferId,
+            playing: true,
+            paused: false,
+            loop: opts?.loop ?? false,
+            volume: opts?.volume ?? 1.0,
+            pitch: opts?.pitch ?? 1.0,
+            pan: opts?.pan ?? 0.0,
+            spatial: opts?.spatial ?? true,
+            position: opts?.position ?? [0, 0, 0],
+            velocity: opts?.velocity ?? [0, 0, 0],
+            minDistance: opts?.minDistance ?? 1.0,
+            maxDistance: opts?.maxDistance ?? 100.0,
+            rolloffFactor: opts?.rolloffFactor ?? 1.0,
+            channel: opts?.channel ?? "sfx",
+        };
+        let nativeSoundId = -1;
+        if (this.lib) {
+            const nativeBufferId = buffer._nativeId;
+            if (nativeBufferId && nativeBufferId > 0) {
+                const channelVol = CHANNEL_VOLUMES[handle.channel ?? "master"] ?? 1.0;
+                const effectiveVol = (handle.volume ?? 1.0) * channelVol;
+                nativeSoundId = this.lib.play(nativeBufferId, handle.loop ? 1 : 0, effectiveVol);
+                if (nativeSoundId > 0 && (handle.volume ?? 1.0) !== effectiveVol) {
+                    this.lib.setVolume(nativeSoundId, effectiveVol);
+                }
+            }
+        }
+        this.sources.set(sourceId, { handle, nativeSoundId });
+        return handle;
+    }
+    stop(sourceId) {
+        const id = typeof sourceId === "number" ? sourceId : sourceId.sourceId ?? -1;
+        const source = this.sources.get(id);
+        if (!source)
+            return;
+        if (this.lib && source.nativeSoundId > 0) {
+            this.lib.stop(source.nativeSoundId);
+        }
+        source.handle.playing = false;
+        this.sources.delete(id);
+    }
+    pause(sourceId) {
+        if (sourceId === undefined)
+            return;
+        const id = typeof sourceId === "number" ? sourceId : sourceId.sourceId ?? -1;
+        const source = this.sources.get(id);
+        if (!source)
+            return;
+        if (this.lib && source.nativeSoundId > 0) {
+            this.lib.pause(source.nativeSoundId);
+        }
+        source.handle.playing = false;
+        source.handle.paused = true;
+    }
+    resume(sourceId) {
+        if (sourceId === undefined)
+            return;
+        const id = typeof sourceId === "number" ? sourceId : sourceId.sourceId ?? -1;
+        const source = this.sources.get(id);
+        if (!source)
+            return;
+        if (this.lib && source.nativeSoundId > 0) {
+            this.lib.resume(source.nativeSoundId);
+        }
+        source.handle.playing = true;
+        source.handle.paused = false;
+    }
+    seek(sourceId, _positionSec) {
+        const source = this.sources.get(sourceId);
+        if (!source)
+            return;
+    }
+    setSourceVolume(sourceId, volume) {
+        const source = this.sources.get(sourceId);
+        if (!source)
+            return;
+        source.handle.volume = volume;
+        if (this.lib && source.nativeSoundId > 0) {
+            const channelVol = CHANNEL_VOLUMES[source.handle.channel ?? "master"] ?? 1.0;
+            this.lib.setVolume(source.nativeSoundId, volume * channelVol);
+        }
+    }
+    setSourcePitch(_sourceId, _pitch) {
+    }
+    setSourcePan(_sourceId, _pan) {
+    }
+    setSourceLoop(sourceId, loop) {
+        const source = this.sources.get(sourceId);
+        if (!source)
+            return;
+        source.handle.loop = loop;
+    }
+    setSourcePosition(sourceId, pos) {
+        const source = this.sources.get(sourceId);
+        if (!source)
+            return;
+        source.handle.position = pos;
+    }
+    setSourceVelocity(sourceId, vel) {
+        const source = this.sources.get(sourceId);
+        if (!source)
+            return;
+        source.handle.velocity = vel;
+    }
+    setSourceSpatial(sourceId, spatial) {
+        const source = this.sources.get(sourceId);
+        if (!source)
+            return;
+        source.handle.spatial = spatial;
+    }
+    setSourceDistanceModel(sourceId, minDist, maxDist, rolloff) {
+        const source = this.sources.get(sourceId);
+        if (!source)
+            return;
+        source.handle.minDistance = minDist;
+        source.handle.maxDistance = maxDist;
+        source.handle.rolloffFactor = rolloff;
+    }
+    setSourceChannel(sourceId, channel) {
+        const source = this.sources.get(sourceId);
+        if (!source)
+            return;
+        source.handle.channel = channel;
+        if (this.lib && source.nativeSoundId > 0) {
+            const channelVol = CHANNEL_VOLUMES[channel] ?? 1.0;
+            this.lib.setVolume(source.nativeSoundId, (source.handle.volume ?? 1.0) * channelVol);
+        }
+    }
+    getSourceState(sourceId) {
+        const source = this.sources.get(sourceId);
+        if (!source)
+            return null;
+        if (this.lib && source.nativeSoundId > 0) {
+            const playing = this.lib.isPlaying(source.nativeSoundId);
+            if (playing === 0 && source.handle.playing) {
+                source.handle.playing = false;
+            }
+        }
+        return { ...source.handle };
+    }
+    getActiveSources() {
+        const active = [];
+        for (const [sourceId, source] of this.sources.entries()) {
+            if (this.lib && source.nativeSoundId > 0) {
+                const playing = this.lib.isPlaying(source.nativeSoundId);
+                if (playing === 0) {
+                    source.handle.playing = false;
+                    this.sources.delete(sourceId);
+                    continue;
+                }
+            }
+            active.push({ ...source.handle });
+        }
+        return active;
+    }
+    setListener(listener) {
+        this.listener = { ...listener };
+    }
+    getListener() {
+        return { ...this.listener };
+    }
+    setChannelVolume(channel, volume) {
+        CHANNEL_VOLUMES[channel] = volume;
+        if (channel === "master" && this.lib) {
+            this.lib.setMasterVolume(volume);
+        }
+        for (const [, source] of this.sources.entries()) {
+            if (source.handle.channel === channel && this.lib && source.nativeSoundId > 0) {
+                this.lib.setVolume(source.nativeSoundId, (source.handle.volume ?? 1.0) * volume);
+            }
+        }
+    }
+    setChannelMuted(channel, muted) {
+        CHANNEL_MUTED[channel] = muted;
+        for (const [, source] of this.sources.entries()) {
+            if (source.handle.channel === channel && this.lib && source.nativeSoundId > 0) {
+                this.lib.setVolume(source.nativeSoundId, muted ? 0 : (source.handle.volume ?? 1.0) * CHANNEL_VOLUMES[channel]);
+            }
+        }
+    }
+    getChannelVolume(channel) {
+        return CHANNEL_VOLUMES[channel] ?? 1.0;
+    }
+    isChannelMuted(channel) {
+        return CHANNEL_MUTED[channel] ?? false;
+    }
+    addEffect(_channel, _effect) {
+        return -1;
+    }
+    removeEffect(_channel, _effectId) {
+    }
+    updateEffect(_channel, _effectId, _params) {
+    }
+    update(_dt) {
+        if (this.lib) {
+            this.lib.update();
+        }
+        for (const [sourceId, source] of this.sources.entries()) {
+            if (this.lib && source.nativeSoundId > 0) {
+                const playing = this.lib.isPlaying(source.nativeSoundId);
+                if (playing === 0) {
+                    source.handle.playing = false;
+                    this.sources.delete(sourceId);
+                }
+            }
+        }
+    }
+    syncPositions(positionBuffer, sourceCount) {
+        let idx = 0;
+        for (const [, source] of this.sources.entries()) {
+            if (idx >= sourceCount)
+                break;
+            if (!source.handle.spatial)
+                continue;
+            const offset = idx * 3;
+            if (offset + 2 < positionBuffer.length) {
+                positionBuffer[offset] = source.handle.position?.[0] ?? 0;
+                positionBuffer[offset + 1] = source.handle.position?.[1] ?? 0;
+                positionBuffer[offset + 2] = source.handle.position?.[2] ?? 0;
+            }
+            idx++;
+        }
+    }
+    destroy() {
+        if (this.destroyed)
+            return;
+        this.destroyed = true;
+        for (const [, source] of this.sources.entries()) {
+            if (this.lib && source.nativeSoundId > 0) {
+                this.lib.stop(source.nativeSoundId);
+            }
+        }
+        this.sources.clear();
+        for (const buffer of this.buffers.values()) {
+            if (this.lib) {
+                const nativeId = buffer._nativeId;
+                if (nativeId && nativeId > 0) {
+                    this.lib.unloadBuffer(nativeId);
+                }
+            }
+        }
+        this.buffers.clear();
+        if (this.lib) {
+            this.lib.destroy();
+        }
+        this.initialized = false;
+    }
+}

package/dist/libraries/audio-kira/src/index.js

@@ -0,0 +1,4 @@
+import { KiraAudioBackend } from "./backend.js";
+export { KiraAudioBackend };
+// Engine library descriptor (declarative GameModule wiring)
+export { AudioEngineTok, AudioKiraLib } from "./library.js";

package/dist/libraries/audio-kira/src/library.js

@@ -0,0 +1,54 @@
+// ============================================================================
+// AudioKiraLib — declarative engine library descriptor for @downdraft/engine/libraries/audio-kira
+//
+// Games declare `libraries: [AudioKiraLib]` (or with config override) in their
+// GameModule. The host creates the KiraAudioBackend (sim-side only — audio is
+// simulated on the sim thread and mixed there) and exposes it via the
+// AudioEngineTok typed token.
+//
+// Games that need full control can still import KiraAudioBackend directly
+// (escape hatch).
+// ============================================================================
+import { resourceToken } from "@downdraft/engine";
+import { KiraAudioBackend } from "./backend.js";
+// ── Typed tokens (DI) ──
+/** Token for the sim-side audio backend. Inject in sim systems that play audio. */
+export const AudioEngineTok = resourceToken("audio:engine");
+// ── Descriptor ──
+export const AudioKiraLib = {
+    name: "audio-kira",
+    version: "1.0.0",
+    // No SAB channels — audio is sim-only; the backend mixes in-process.
+    sabChannels: [],
+    provides: [AudioEngineTok],
+    sim: {
+        async create(config, ctx) {
+            const backend = new KiraAudioBackend();
+            await backend.init({
+                sampleRate: config.sampleRate ?? 44100,
+                bufferSize: config.bufferSize ?? 1024,
+                channels: config.channels ?? 2,
+                spatialEnabled: config.spatialEnabled ?? true,
+                maxSources: config.maxSources ?? 256,
+                speedOfSound: config.speedOfSound ?? 343,
+            });
+            ctx.provide(AudioEngineTok, backend);
+            return backend;
+        },
+        dispose(backend) {
+            backend.destroy();
+        },
+        // tick is game-specific (calls backend.update(dt), syncs listener/source
+        // positions, etc.) — games wire this via onReady or a sim system.
+    },
+    tickPhase: "post-physics",
+    // No renderer setup — audio is entirely sim-side.
+    defaultConfig: {
+        sampleRate: 44100,
+        bufferSize: 1024,
+        channels: 2,
+        spatialEnabled: true,
+        maxSources: 256,
+        speedOfSound: 343,
+    },
+};

package/dist/libraries/blitz-ui/src/index.js

@@ -0,0 +1,13 @@
+// ============================================================================
+// @downdraft/engine/libraries/blitz-ui — shared Blitz/Dioxus UI support.
+//
+// - BlitzUiRouter: InputManager → wasm UI input bridge (works on both
+//   web and native).
+// - createBlitzUiNativeModule: headless vello_cpu → texture → UiBlitPass
+//   compositing for the native runtime — native-only, import via
+//   "@downdraft/engine/libraries/blitz-ui/native-module". Game crates
+//   compile the shared `downdraft-blitz-shell` Rust crate
+//   (libraries/blitz-ui/native) with their own Dioxus app + snapshot type.
+// ============================================================================
+export { BlitzUiRouter } from "./router.js";
+export { UiBlitPass } from "./ui-blit-pass.js";

package/dist/libraries/blitz-ui/src/native-module.js

@@ -0,0 +1,162 @@
+// ============================================================================
+// createBlitzUiNativeModule — native (winit/SDL) Blitz UI renderer module.
+//
+// The native runtime can't attach winit-web + WebGL2 to a DOM canvas, so this
+// module drives the headless wasm build instead: DioxusDocument + vello_cpu
+// rasterize the UI into an RGBA8 buffer on ui_frame(), which is uploaded to
+// a GPUTexture and composited over the swapchain with UiBlitPass (the
+// premultiplied-alpha blit pass in this library).
+//
+// Input, state, and action bridging are identical to the web build — the
+// window-level event polyfills feed the engine's InputManager → BlitzUiRouter
+// → ui_pointer/ui_key, and store snapshots flow through ui_set_state.
+//
+// Frame cadence: the module hooks "afterFrame" (runs after the game's custom
+// render, before present). ui_tick() drains queued input/snapshots and
+// reports dirtiness; only then is ui_frame() rasterized + uploaded. The blit
+// itself runs every frame — the swapchain is re-cleared each frame while the
+// UI texture persists.
+// ============================================================================
+import { UIInputRouter } from "@downdraft/engine";
+import { createLogger } from "@downdraft/engine/util/logger";
+import { captureScreenshot } from "@downdraft/platform-native";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { BlitzUiRouter } from "./router.js";
+import { UiBlitPass } from "./ui-blit-pass.js";
+const log = createLogger("info");
+export function createBlitzUiNativeModule(options) {
+    let started = null;
+    const start = async (width, height, scale) => {
+        const wasm = await options.loadModule();
+        // Bun can't fetch() a file:// URL inside wasm-bindgen's async init —
+        // load the binary from disk and initialize synchronously instead.
+        wasm.initSync({ module: readFileSync(fileURLToPath(options.wasmUrl)) });
+        wasm.ui_init_headless(width, height, scale, (action, payload) => {
+            options.dispatch(action, payload);
+        });
+        log.info(options.name ?? "blitz-ui-native", "started");
+        return { wasm };
+    };
+    return {
+        name: options.name ?? "blitz-ui-native",
+        version: "1.0.0",
+        register(ctx) {
+            let disposed = false;
+            let router = null;
+            let prevRouter = null;
+            let unsubscribe = null;
+            let blitPass = null;
+            let uiTexture = null;
+            let uiTextureView = null;
+            let wasmRef = null;
+            const canvas = ctx.getSurface();
+            const renderer = options.renderer;
+            const push = (wasm) => {
+                try {
+                    wasm.ui_set_state(JSON.stringify(options.snapshot(options.store.getState())));
+                }
+                catch (e) {
+                    log.warn("blitz-ui-native", `ui_set_state failed: ${e}`);
+                }
+            };
+            const onKeyDown = (e) => {
+                if (e.key === "Escape")
+                    options.onEscape?.();
+            };
+            void (async () => {
+                try {
+                    const scale = window.devicePixelRatio || 1;
+                    started ??= start(canvas.width, canvas.height, scale);
+                    const { wasm } = await started;
+                    if (disposed)
+                        return;
+                    wasmRef = wasm;
+                    const device = ctx.getDevice();
+                    blitPass = new UiBlitPass(device, ctx.getFormat());
+                    prevRouter = renderer.getUIInputRouter();
+                    router = new BlitzUiRouter(wasm);
+                    renderer.getInputManager().setUIInputRouter(router);
+                    renderer.uiInputRouter = router;
+                    router.attachKeyboard();
+                    window.addEventListener("keydown", onKeyDown);
+                    push(wasm);
+                    unsubscribe = options.store.subscribe(() => push(wasm));
+                    globalThis.__blitzDump = wasm.ui_dump;
+                }
+                catch (e) {
+                    log.error("blitz-ui-native", `failed to start — UI will be unavailable: ${e}`);
+                }
+            })();
+            const ensureTexture = (device) => {
+                const w = canvas.width;
+                const h = canvas.height;
+                if (uiTexture && uiTexture.width === w && uiTexture.height === h)
+                    return uiTextureView;
+                uiTexture?.destroy();
+                uiTexture = device.createTexture({
+                    size: { width: Math.max(1, w), height: Math.max(1, h) },
+                    format: "rgba8unorm",
+                    usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
+                });
+                uiTextureView = uiTexture.createView();
+                return uiTextureView;
+            };
+            // Debug: <ENV>=path.png captures the composited frame on frame 4
+            // (the surface texture is still acquired inside afterFrame, and
+            // must be read back with the *renderer* device — the host's
+            // device is a different wgpu device).
+            const shotPath = options.debugScreenshotEnv ? process.env[options.debugScreenshotEnv] : undefined;
+            let frameCount = 0;
+            ctx.onFrame("afterFrame", () => {
+                ++frameCount;
+                const wasm = wasmRef;
+                if (!wasm || disposed || !blitPass)
+                    return;
+                const device = ctx.getDevice();
+                const view = ensureTexture(device);
+                const context = ctx.getSurface().getContext("webgpu");
+                const targetTex = context?.getCurrentTexture();
+                const target = targetTex?.createView();
+                if (!view || !target || !targetTex)
+                    return;
+                if (options.shouldRepush?.(options.store.getState()))
+                    push(wasm);
+                if (wasm.ui_tick()) {
+                    const rgba = wasm.ui_frame();
+                    device.queue.copyExternalImageToTexture(
+                    // vello_cpu output is already premultiplied — pass
+                    // it through (premultipliedAlpha would double-multiply).
+                    { source: { data: rgba, width: canvas.width, height: canvas.height } }, { texture: uiTexture }, { width: canvas.width, height: canvas.height });
+                }
+                const encoder = device.createCommandEncoder();
+                blitPass.execute(encoder, target, view);
+                device.queue.submit([encoder.finish()]);
+                if (shotPath && frameCount === 4) {
+                    captureScreenshot(device, targetTex, canvas.width, canvas.height, shotPath, ctx.getFormat());
+                    log.info("blitz-ui-native", `screenshot → ${shotPath}`);
+                }
+            });
+            ctx.onResize(() => {
+                const scale = window.devicePixelRatio || 1;
+                wasmRef?.ui_resize(canvas.width, canvas.height, scale);
+            });
+            ctx.onDispose(() => {
+                disposed = true;
+                window.removeEventListener("keydown", onKeyDown);
+                unsubscribe?.();
+                router?.detachKeyboard();
+                const restore = prevRouter ?? new UIInputRouter();
+                renderer.getInputManager().setUIInputRouter(restore);
+                renderer.uiInputRouter = restore;
+                uiTexture?.destroy();
+                blitPass?.dispose();
+                // Tear down the Dioxus document and drop the module-level
+                // singleton so a re-register boots a fresh instance.
+                wasmRef?.ui_shutdown();
+                wasmRef = null;
+                started = null;
+            });
+        },
+    };
+}