@downdraft/engine 0.1.0 → 0.1.2-alpha.5

package/dist/libraries/blitz-ui/src/native-osr-ffi.js

@@ -0,0 +1,409 @@
+// ============================================================================
+// native-osr-ffi.ts — bun:ffi binding for the downdraft-blitz-osr cdylib
+// (libraries/blitz-ui/native-osr). Native-only — import via the
+// "@downdraft/engine/libraries/blitz-ui/native-osr-ffi" subpath so it never
+// enters a web bundle (mirrors native-module.ts).
+//
+// One `OsrDoc` = one Blitz HtmlDocument + vello_cpu rasterizer. The platform
+// host (platform-native/src/osr) owns documents per OSR renderer and pulls
+// dirty RGBA frames; the renderer side (modules/native-osr) uploads them to
+// GPU textures.
+// ============================================================================
+import { dlopen, ptr, readMappedRange } from "@downdraft/platform-native/ffi/ffi-adapter";
+import { resolveNativeLibrary } from "@downdraft/platform-native/ffi/lib-paths";
+import { findPackageRoot } from "@downdraft/engine/platform/pkg-root";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const _dirname = typeof globalThis.__dirname !== "undefined"
+    ? globalThis.__dirname
+    : dirname(fileURLToPath(import.meta.url));
+function findOsrLibrary() {
+    return resolveNativeLibrary("downdraft_blitz_osr", {
+        envVars: ["DOWNDRAFT_OSR_LIB"],
+        crateDir: join(findPackageRoot(_dirname), "libraries", "blitz-ui", "native-osr"),
+        optional: true,
+    });
+}
+// ── FFI symbol table ──
+//
+// ABI conventions:
+//  - handles are opaque `*mut OsrDoc` pointers
+//  - strings are (ptr, len) UTF-8 pairs
+//  - `mods` is a u32 bitmask: bit0=shift, bit1=ctrl, bit2=alt, bit3=meta
+//  - `button` uses DOM numbering: 0=left, 1=middle, 2=right
+//  - coordinates are physical px (doc CSS px at scale 1)
+const OSR_SPEC = {
+    dd_osr_init: { args: ["f64", "f64", "f64", "ptr", "usize"], returns: "ptr" },
+    dd_osr_set_html: { args: ["ptr", "ptr", "usize"], returns: "i32" },
+    dd_osr_frame: { args: ["ptr"], returns: "ptr" },
+    dd_osr_pixels_len: { args: ["ptr"], returns: "usize" },
+    dd_osr_resize: { args: ["ptr", "f64", "f64", "f64"], returns: "i32" },
+    dd_osr_pointer: { args: ["ptr", "i32", "f64", "f64", "i32", "u32"], returns: "i32" },
+    dd_osr_wheel: { args: ["ptr", "f64", "f64", "f64", "f64", "u32"], returns: "i32" },
+    dd_osr_key: { args: ["ptr", "i32", "ptr", "usize", "ptr", "usize", "ptr", "usize", "u32"], returns: "i32" },
+    dd_osr_hit_test: { args: ["ptr", "f64", "f64"], returns: "i32" },
+    dd_osr_destroy: { args: ["ptr"], returns: "i32" },
+    // ── Frame metadata / refresh control ──
+    dd_osr_frame_rect: { args: ["ptr"], returns: "u64" },
+    dd_osr_pending: { args: ["ptr"], returns: "i32" },
+    // ── Zero-copy frame channel (SharedArrayBuffer staging) ──
+    dd_osr_buf_needed: { args: ["ptr"], returns: "usize" },
+    dd_osr_bind_frame_buf: { args: ["ptr", "ptr", "usize"], returns: "i32" },
+    dd_osr_frame_into: { args: ["ptr"], returns: "i32" },
+    dd_osr_refresh_into: { args: ["ptr"], returns: "i32" },
+    // ── Per-frame instrumentation ──
+    dd_osr_last_stats: { args: ["ptr"], returns: "ptr" },
+    // ── Layout query ──
+    dd_osr_node_rect: { args: ["ptr", "u64"], returns: "ptr" },
+    // ── DOM event queue ──
+    dd_osr_poll_events: { args: ["ptr"], returns: "ptr" },
+    dd_osr_events_len: { args: ["ptr"], returns: "usize" },
+    // ── Incremental DOM mutation ──
+    dd_osr_query: { args: ["ptr", "ptr", "usize"], returns: "u64" },
+    dd_osr_set_text: { args: ["ptr", "u64", "ptr", "usize"], returns: "i32" },
+    dd_osr_set_attr: { args: ["ptr", "u64", "ptr", "usize", "ptr", "usize"], returns: "i32" },
+    dd_osr_remove_attr: { args: ["ptr", "u64", "ptr", "usize"], returns: "i32" },
+    dd_osr_set_style: { args: ["ptr", "u64", "ptr", "usize", "ptr", "usize"], returns: "i32" },
+    dd_osr_set_inner_html: { args: ["ptr", "u64", "ptr", "usize"], returns: "i32" },
+    dd_osr_get_attr: { args: ["ptr", "u64", "ptr", "usize"], returns: "ptr" },
+    dd_osr_out_len: { args: ["ptr"], returns: "usize" },
+    dd_osr_focus: { args: ["ptr", "u64"], returns: "i32" },
+    dd_osr_focused_node: { args: ["ptr"], returns: "u64" },
+    dd_osr_query_all: { args: ["ptr", "ptr", "usize"], returns: "ptr" },
+    dd_osr_query_all_len: { args: ["ptr"], returns: "usize" },
+    dd_osr_closest: { args: ["ptr", "u64", "ptr", "usize"], returns: "u64" },
+    dd_osr_scroll_into_view: { args: ["ptr", "u64", "i32", "i32", "i32"], returns: "i32" },
+    dd_osr_scroll_to: { args: ["ptr", "u64", "f64", "f64", "i32"], returns: "i32" },
+    // ── Process-wide ui:// resources (fonts, images, stylesheets) ──
+    dd_osr_register_resource: { args: ["ptr", "usize", "ptr", "usize"], returns: "i32" },
+};
+/**
+ * Optional append-only DOM ops — resolved on a second dlopen so a cdylib
+ * built before they existed can still satisfy OSR_SPEC (the failure mode
+ * is `incrementalDom === false`, not a dlopen crash). Callers must check
+ * `OsrDoc.incrementalDom` (or the `ready` message's caps) and fall back to
+ * innerHTML-style mutations when absent.
+ */
+const OSR_APPEND_SPEC = {
+    dd_osr_append_html: { args: ["ptr", "u64", "ptr", "usize"], returns: "i32" },
+    dd_osr_trim_children: { args: ["ptr", "u64", "u64"], returns: "i32" },
+};
+/**
+ * Register a process-wide `ui://` resource served to every document's
+ * NetProvider — fonts (@font-face src), images (<img src>), stylesheets.
+ */
+export function registerOsrResource(url, bytes) {
+    const entry = loadOsrLib();
+    if (!entry)
+        return false;
+    const u = enc.encode(url);
+    const b = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+    return entry.symbols.dd_osr_register_resource(ptr(u), u.length, ptr(b.length ? b : EMPTY_STR), b.length) === 0;
+}
+let cached = null;
+/** dlopen the Blitz OSR cdylib. Returns null when the artifact is absent
+ *  (not built / not staged) so hosts can disable OSR instead of crashing. */
+export function loadOsrLib() {
+    if (cached)
+        return cached;
+    const path = findOsrLibrary();
+    if (!path)
+        return null;
+    try {
+        const symbols = dlopen(path, OSR_SPEC).symbols;
+        let append = null;
+        try {
+            append = dlopen(path, OSR_APPEND_SPEC).symbols;
+        }
+        catch { /* older cdylib — incrementalDom stays off */ }
+        cached = { symbols, append, path };
+        return cached;
+    }
+    catch {
+        return null;
+    }
+}
+const enc = new TextEncoder();
+// bun:ffi's ptr() can't convert a zero-length buffer — empty strings pass
+// this scratch pointer with len 0 (read_str bounds-checks on len anyway).
+const EMPTY_STR = new Uint8Array(1);
+/** DOM-button name → DOM button number (matches `MouseEvent.button`). */
+function domButton(b) {
+    return b === "right" ? 2 : b === "middle" ? 1 : 0;
+}
+/** Modifier names → the u32 bitmask the ABI expects. */
+export function osrModifierBits(mods) {
+    let bits = 0;
+    (mods ?? []).forEach((m) => {
+        const k = m.toLowerCase();
+        if (k === "shift")
+            bits |= 1;
+        else if (k === "control" || k === "ctrl")
+            bits |= 2;
+        else if (k === "alt")
+            bits |= 4;
+        else if (k === "meta" || k === "super" || k === "cmd")
+            bits |= 8;
+    });
+    return bits;
+}
+/** Byte offset of the pixel region inside a bound frame buffer. */
+export const OSR_FRAME_HEADER = 64;
+/** Typed handle over one Blitz document. */
+export class OsrDoc {
+    handle;
+    lib;
+    appendLib;
+    /** Physical px dimensions tracked host-side (updated on resize). */
+    width;
+    height;
+    constructor(lib, appendLib, handle, width, height) {
+        this.lib = lib;
+        this.appendLib = appendLib;
+        this.handle = handle;
+        this.width = width;
+        this.height = height;
+    }
+    /** Capabilities of the loaded cdylib — read once and cache; the lib is
+     *  resolved lazily so this stays false before the first create(). */
+    static get caps() {
+        return { incrementalDom: !!loadOsrLib()?.append };
+    }
+    static create(width, height, scale, html) {
+        const entry = loadOsrLib();
+        if (!entry)
+            return null;
+        const bytes = enc.encode(html);
+        const h = entry.symbols.dd_osr_init(width, height, scale, ptr(bytes), bytes.length);
+        if (!h)
+            return null;
+        return new OsrDoc(entry.symbols, entry.append, h, width, height);
+    }
+    /** Replace the whole document (Blitz has no in-place reparse). */
+    setHtml(html) {
+        const bytes = enc.encode(html);
+        return this.lib.dd_osr_set_html(this.handle, ptr(bytes), bytes.length) === 0;
+    }
+    /** Rasterize when dirty; returns the RGBA8 buffer or null when clean. */
+    frame() {
+        const p = this.lib.dd_osr_frame(this.handle);
+        if (!p)
+            return null;
+        const len = Number(this.lib.dd_osr_pixels_len(this.handle));
+        if (len <= 0)
+            return null;
+        return readMappedRange(p, len);
+    }
+    resize(width, height, scale) {
+        const ok = this.lib.dd_osr_resize(this.handle, width, height, scale) === 0;
+        if (ok) {
+            this.width = width;
+            this.height = height;
+        }
+        return ok;
+    }
+    pointerMove(x, y, mods) {
+        this.lib.dd_osr_pointer(this.handle, 0, x, y, 0, osrModifierBits(mods));
+    }
+    pointerDown(x, y, button, mods) {
+        this.lib.dd_osr_pointer(this.handle, 1, x, y, domButton(button), osrModifierBits(mods));
+    }
+    pointerUp(x, y, button, mods) {
+        this.lib.dd_osr_pointer(this.handle, 2, x, y, domButton(button), osrModifierBits(mods));
+    }
+    wheel(x, y, deltaX, deltaY, mods) {
+        // Callers pass DOM WheelEvent deltas (+y = scroll down). Blitz wheel
+        // deltas follow winit semantics (+y = scroll up / decreases the scroll
+        // offset — see scroll_node_by_has_changed), so negate both axes.
+        this.lib.dd_osr_wheel(this.handle, x, y, -deltaX, -deltaY, osrModifierBits(mods));
+    }
+    /** `key`/`code` are W3C UI-Events strings ("Enter"/"a", "KeyF"/"Escape"). */
+    key(down, key, code, text, mods) {
+        const kb = enc.encode(key);
+        const cb = enc.encode(code ?? "");
+        const tb = enc.encode(text ?? "");
+        this.lib.dd_osr_key(this.handle, down ? 0 : 1, ptr(kb.length ? kb : EMPTY_STR), kb.length, ptr(cb.length ? cb : EMPTY_STR), cb.length, ptr(tb.length ? tb : EMPTY_STR), tb.length, osrModifierBits(mods));
+    }
+    /** Is (x, y) over a `data-ui` element? */
+    hitTest(x, y) {
+        return this.lib.dd_osr_hit_test(this.handle, x, y) === 1;
+    }
+    /**
+     * Dirty rect of the last successful frame() in physical px, or null when
+     * the whole buffer is new/changed shape. Packed u64: x<<48|y<<32|w<<16|h.
+     */
+    frameRect() {
+        const v = BigInt(this.lib.dd_osr_frame_rect(this.handle));
+        const x = Number(v >> 48n), y = Number((v >> 32n) & 0xffffn);
+        const w = Number((v >> 16n) & 0xffffn), h = Number(v & 0xffffn);
+        return w > 0 && h > 0 ? { x, y, w, h } : null;
+    }
+    /** True when the doc has damage worth rasterizing (dirty or animating). */
+    pending() {
+        return this.lib.dd_osr_pending(this.handle) !== 0;
+    }
+    /** Drain queued DOM events (click/input/key/focus/scroll) as parsed JSON. */
+    pollEvents() {
+        const p = this.lib.dd_osr_poll_events(this.handle);
+        if (!p)
+            return [];
+        const len = Number(this.lib.dd_osr_events_len(this.handle));
+        if (len <= 0)
+            return [];
+        try {
+            return JSON.parse(new TextDecoder().decode(readMappedRange(p, len)));
+        }
+        catch {
+            return [];
+        }
+    }
+    /** CSS selector → node handle (0 on miss). Re-query after structural edits. */
+    query(selector) {
+        const s = enc.encode(selector);
+        return Number(this.lib.dd_osr_query(this.handle, ptr(s), s.length));
+    }
+    setText(node, text) {
+        const t = enc.encode(text);
+        return this.lib.dd_osr_set_text(this.handle, BigInt(node), ptr(t.length ? t : EMPTY_STR), t.length) === 0;
+    }
+    setAttr(node, name, value) {
+        const n = enc.encode(name), v = enc.encode(value);
+        return this.lib.dd_osr_set_attr(this.handle, BigInt(node), ptr(n), n.length, ptr(v.length ? v : EMPTY_STR), v.length) === 0;
+    }
+    removeAttr(node, name) {
+        const n = enc.encode(name);
+        return this.lib.dd_osr_remove_attr(this.handle, BigInt(node), ptr(n), n.length) === 0;
+    }
+    setStyle(node, prop, value) {
+        // Stylo's PropertyId::parse wants CSS names — accept JS-style camelCase
+        // too ("fontSize" → "font-size") so callers can use DOM-style props.
+        const name = /[A-Z]/.test(prop) ? prop.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`) : prop;
+        const p = enc.encode(name), v = enc.encode(value);
+        return this.lib.dd_osr_set_style(this.handle, BigInt(node), ptr(p), p.length, ptr(v.length ? v : EMPTY_STR), v.length) === 0;
+    }
+    /** Replace a node's children with parsed HTML (invalidates child NodeIds). */
+    setInnerHtml(node, html) {
+        const h = enc.encode(html);
+        return this.lib.dd_osr_set_inner_html(this.handle, BigInt(node), ptr(h.length ? h : EMPTY_STR), h.length) === 0;
+    }
+    /** Parse an HTML fragment and append it as the node's last children —
+     *  `innerHTML +=` semantics; existing children (and their NodeIds)
+     *  survive. False when the loaded cdylib lacks dd_osr_append_html. */
+    appendHtml(node, html) {
+        if (!this.appendLib)
+            return false;
+        const h = enc.encode(html);
+        return this.appendLib.dd_osr_append_html(this.handle, BigInt(node), ptr(h.length ? h : EMPTY_STR), h.length) === 0;
+    }
+    /** Drop all but the last `keep` children of `node`. False when the loaded
+     *  cdylib lacks dd_osr_trim_children. */
+    trimChildren(node, keep) {
+        if (!this.appendLib)
+            return false;
+        return this.appendLib.dd_osr_trim_children(this.handle, BigInt(node), BigInt(keep)) === 0;
+    }
+    /** Attribute value — for "value" on <input>/<textarea> returns live text. */
+    getAttr(node, name) {
+        const n = enc.encode(name);
+        const p = this.lib.dd_osr_get_attr(this.handle, BigInt(node), ptr(n), n.length);
+        if (!p)
+            return null;
+        const len = Number(this.lib.dd_osr_out_len(this.handle));
+        if (len === 0)
+            return ""; // attr/value present but empty
+        return new TextDecoder().decode(readMappedRange(p, len));
+    }
+    /** Focus a node (0 = blur). */
+    focus(node) {
+        return this.lib.dd_osr_focus(this.handle, BigInt(node)) === 0;
+    }
+    /** Currently-focused node handle, or 0. */
+    focusedNode() {
+        return Number(this.lib.dd_osr_focused_node(this.handle));
+    }
+    /** CSS selector → all matching node handles (empty on miss/parse error).
+     *  Re-query after structural edits. */
+    queryAll(selector) {
+        const s = enc.encode(selector);
+        const p = this.lib.dd_osr_query_all(this.handle, ptr(s), s.length);
+        const len = Number(this.lib.dd_osr_query_all_len(this.handle));
+        if (!p || len === 0)
+            return [];
+        const u8 = readMappedRange(p, len * 8);
+        const u64 = new BigUint64Array(u8.buffer, u8.byteOffset, len);
+        return Array.from(u64, (v) => Number(v));
+    }
+    /** Nearest ancestor-or-self matching `selector` → node handle (0 on miss). */
+    closest(node, selector) {
+        const s = enc.encode(selector);
+        return Number(this.lib.dd_osr_closest(this.handle, BigInt(node), ptr(s), s.length));
+    }
+    /** Scroll the viewport so `node` is visible.
+     *  align: "start" | "center" | "end" | "nearest" (nearest = minimal scroll). */
+    scrollIntoView(node, opts) {
+        const A = { start: 0, center: 1, end: 2, nearest: 3 };
+        return this.lib.dd_osr_scroll_into_view(this.handle, BigInt(node), opts?.smooth ? 1 : 0, A[opts?.vertical ?? "nearest"], A[opts?.horizontal ?? "nearest"]) === 0;
+    }
+    /** Scroll a specific node (scroll container) to absolute (x, y) offsets.
+     *  Reaches nested scrollports — scrollIntoView only moves the root viewport.
+     *  Offsets clamp to the node's scroll range; y=1e9 pins to the bottom. */
+    scrollTo(node, x, y, smooth = false) {
+        return this.lib.dd_osr_scroll_to(this.handle, BigInt(node), x, y, smooth ? 1 : 0) === 0;
+    }
+    // ── Zero-copy frame channel ──
+    /** Bytes the bound frame buffer must hold at the doc's current size. */
+    bufNeeded() {
+        return Number(this.lib.dd_osr_buf_needed(this.handle));
+    }
+    /**
+     * Bind a SharedArrayBuffer as the frame staging buffer. The Rust side
+     * writes a 64-byte header + dirty pixel rows at 256-aligned stride.
+     * Returns true when bound (false = buffer too small / lib absent).
+     */
+    bindFrameBuf(sab) {
+        const view = new Uint8Array(sab);
+        return this.lib.dd_osr_bind_frame_buf(this.handle, ptr(view), view.byteLength) === 0;
+    }
+    /**
+     * Rasterize (when dirty) straight into the bound buffer.
+     * Returns 1 = frame written, 0 = nothing new, -2 = buffer too small
+     * (rebind + refreshInto), -3 = unbound.
+     */
+    frameInto() {
+        return this.lib.dd_osr_frame_into(this.handle);
+    }
+    /** Re-emit the current pixels into the bound buffer (no raster). */
+    refreshInto() {
+        return this.lib.dd_osr_refresh_into(this.handle);
+    }
+    /**
+     * Border-box rect of a node in logical px (doc-space — matches DOM event
+     * client_x/client_y). Null when the node id is stale.
+     */
+    nodeRect(node) {
+        const p = this.lib.dd_osr_node_rect(this.handle, BigInt(node));
+        if (!p)
+            return null;
+        const u8 = readMappedRange(p, 32);
+        const f = new Float64Array(u8.buffer, u8.byteOffset, 4);
+        return { x: f[0], y: f[1], w: f[2], h: f[3] };
+    }
+    /** Per-frame timings from the last raster, or null when unavailable. */
+    lastStats() {
+        const p = this.lib.dd_osr_last_stats(this.handle);
+        if (!p)
+            return null;
+        const u8 = readMappedRange(p, 64);
+        const f = new Float64Array(u8.buffer, u8.byteOffset, 8);
+        return {
+            resolveMs: f[0], paintMs: f[1], diffMs: f[2], pixelsLen: f[3],
+            rasters: f[4], skippedClean: f[5],
+        };
+    }
+    destroy() {
+        if (!this.handle)
+            return;
+        this.lib.dd_osr_destroy(this.handle);
+        this.handle = 0;
+    }
+}

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

@@ -0,0 +1,82 @@
+// ============================================================================
+// BlitzUiRouter — drop-in replacement for the engine's UIInputRouter.
+//
+// The engine's InputManager already delivers window-level mouse/wheel events
+// converted to canvas *backing-pixel* coordinates — exactly what the wasm
+// exports expect. Keyboard events need the full KeyboardEvent (key/code/mods)
+// which InputManager doesn't pass, so the router registers its own key
+// listeners in attachKeyboard()/detachKeyboard().
+// ============================================================================
+import { UIInputRouter } from "@downdraft/engine";
+export class BlitzUiRouter extends UIInputRouter {
+    wasm;
+    lastX = -1;
+    lastY = -1;
+    mods = 0;
+    keyDown;
+    keyUp;
+    constructor(wasm) {
+        super();
+        this.wasm = wasm;
+        this.keyDown = (e) => {
+            this.mods = modBits(e);
+            this.wasm.ui_key(true, e.key, e.code, this.mods, e.key.length === 1 ? e.key : undefined);
+        };
+        this.keyUp = (e) => {
+            this.mods = modBits(e);
+            this.wasm.ui_key(false, e.key, e.code, this.mods);
+        };
+    }
+    /** Register the router's own keyboard listeners (call once on mount). */
+    attachKeyboard() {
+        window.addEventListener("keydown", this.keyDown);
+        window.addEventListener("keyup", this.keyUp);
+    }
+    detachKeyboard() {
+        window.removeEventListener("keydown", this.keyDown);
+        window.removeEventListener("keyup", this.keyUp);
+    }
+    handleMouseMove(mx, my) {
+        this.lastX = mx;
+        this.lastY = my;
+        this.wasm.ui_pointer(0, mx, my, 0, this.mods);
+    }
+    handleMouseDown(mx, my) {
+        this.lastX = mx;
+        this.lastY = my;
+        this.wasm.ui_pointer(1, mx, my, 0, this.mods);
+    }
+    handleMouseUp(mx, my) {
+        this.lastX = mx;
+        this.lastY = my;
+        this.wasm.ui_pointer(2, mx, my, 0, this.mods);
+    }
+    handleWheel(dx, dy) {
+        // DOM WheelEvent deltas (+y = scroll down) → Blitz wheel-delta
+        // semantics (+y = scroll up / decreases the scroll offset).
+        this.wasm.ui_wheel(-dx, -dy, this.lastX, this.lastY, this.mods);
+        // Consume the event when over an interactive element so the page
+        // doesn't scroll behind a scrollable panel.
+        return this.isPointerOverUI();
+    }
+    handlePointerLeave() {
+        this.lastX = -1;
+        this.lastY = -1;
+        this.wasm.ui_pointer_leave();
+    }
+    getPointerPos() {
+        return [this.lastX, this.lastY];
+    }
+    /** Hit-test the live document at the last pointer position. */
+    isPointerOverUI() {
+        return this.lastX >= 0 && this.wasm.ui_hit_test(this.lastX, this.lastY);
+    }
+    // Key routing happens through our own listeners (InputManager only passes
+    // keyCode, which can't reconstruct `key`). Base no-ops are fine.
+    handleKeyDown(_code) { }
+    handleKeyUp(_code) { }
+    handleCharInput(_char) { }
+}
+function modBits(e) {
+    return (e.shiftKey ? 1 : 0) | (e.ctrlKey ? 2 : 0) | (e.altKey ? 4 : 0) | (e.metaKey ? 8 : 0);
+}

package/dist/libraries/blitz-ui/src/shaders/ui-blit.wgsl.js

@@ -0,0 +1,32 @@
+// UI blit shader — fullscreen triangle that samples a UI texture and
+// alpha-blends it over the game frame. The UI texture is premultiplied
+// alpha, so the blend is src*1 + dst*(1-srcAlpha).
+const FULLSCREEN_VS = `
+struct VertexOutput {
+  @builtin(position) clipPos: vec4<f32>,
+  @location(0) uv: vec2<f32>,
+};
+
+@vertex
+fn vs_main(@builtin(vertex_index) vi: u32) -> VertexOutput {
+  // Fullscreen triangle: covers the clip space with one triangle.
+  var p = array<vec2<f32>, 3>(
+    vec2(-1.0, -1.0), vec2(3.0, -1.0), vec2(-1.0, 3.0),
+  );
+  var o: VertexOutput;
+  o.clipPos = vec4(p[vi], 0.0, 1.0);
+  // Flip Y so the UI texture (rendered top-down) maps upright.
+  o.uv = vec2(p[vi].x * 0.5 + 0.5, 0.5 - p[vi].y * 0.5);
+  return o;
+}
+`;
+const UI_BLIT_FS = `
+@group(0) @binding(0) var uiTex: texture_2d<f32>;
+@group(0) @binding(1) var samp: sampler;
+
+@fragment
+fn fs_main(input: VertexOutput) -> @location(0) vec4<f32> {
+  return textureSample(uiTex, samp, input.uv);
+}
+`;
+export const UI_BLIT_WGSL = FULLSCREEN_VS + "\n" + UI_BLIT_FS;

package/dist/libraries/blitz-ui/src/ui-blit-pass.js

@@ -0,0 +1,108 @@
+// ============================================================================
+// ui-blit-pass.ts — screen-space WebGPU pass that composites a UI texture
+// over the game frame.
+//
+// Each frame, after the UI system (Blitz/html-ui worker, Blitz devtools) has
+// rendered into its GPUTexture (on the shared device/queue), the game calls
+// `execute(commandEncoder, targetView)` with the swapchain texture view. This
+// begins a render pass on `targetView` with loadOp:"load" (preserving the 3D
+// frame), binds the UI texture + a linear sampler, and draws a fullscreen
+// triangle with premultiplied-alpha blending.
+// ============================================================================
+import { createValidatedShaderModule } from "@downdraft/engine";
+const __dd_raw_0 = "// UI blit shader — fullscreen triangle that samples a UI texture and\n// alpha-blends it over the game frame. The UI texture is premultiplied\n// alpha, so the blend is src*1 + dst*(1-srcAlpha).\n\nconst FULLSCREEN_VS = `\nstruct VertexOutput {\n  @builtin(position) clipPos: vec4<f32>,\n  @location(0) uv: vec2<f32>,\n};\n\n@vertex\nfn vs_main(@builtin(vertex_index) vi: u32) -> VertexOutput {\n  // Fullscreen triangle: covers the clip space with one triangle.\n  var p = array<vec2<f32>, 3>(\n    vec2(-1.0, -1.0), vec2(3.0, -1.0), vec2(-1.0, 3.0),\n  );\n  var o: VertexOutput;\n  o.clipPos = vec4(p[vi], 0.0, 1.0);\n  // Flip Y so the UI texture (rendered top-down) maps upright.\n  o.uv = vec2(p[vi].x * 0.5 + 0.5, 0.5 - p[vi].y * 0.5);\n  return o;\n}\n`;\n\nconst UI_BLIT_FS = `\n@group(0) @binding(0) var uiTex: texture_2d<f32>;\n@group(0) @binding(1) var samp: sampler;\n\n@fragment\nfn fs_main(input: VertexOutput) -> @location(0) vec4<f32> {\n  return textureSample(uiTex, samp, input.uv);\n}\n`;\n\nexport const UI_BLIT_WGSL = FULLSCREEN_VS + \"\\n\" + UI_BLIT_FS;\n";
+const { UI_BLIT_WGSL } = __dd_raw_0;
+export class UiBlitPass {
+    device;
+    pipeline;
+    bindGroupLayout;
+    sampler;
+    format;
+    disposed = false;
+    constructor(device, targetFormat) {
+        this.device = device;
+        this.format = targetFormat;
+        this.bindGroupLayout = device.createBindGroupLayout({
+            entries: [
+                { binding: 0, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "float" } },
+                { binding: 1, visibility: GPUShaderStage.FRAGMENT, sampler: { type: "filtering" } },
+            ],
+        });
+        this.sampler = device.createSampler({
+            magFilter: "linear",
+            minFilter: "linear",
+            addressModeU: "clamp-to-edge",
+            addressModeV: "clamp-to-edge",
+        });
+        const shader = createValidatedShaderModule(device, { code: UI_BLIT_WGSL, label: "UiBlitPass" });
+        const pipelineLayout = device.createPipelineLayout({ bindGroupLayouts: [this.bindGroupLayout] });
+        this.pipeline = device.createRenderPipeline({
+            layout: pipelineLayout,
+            vertex: { module: shader, entryPoint: "vs_main" },
+            fragment: {
+                module: shader,
+                entryPoint: "fs_main",
+                targets: [{
+                        format: targetFormat,
+                        // Premultiplied alpha blend: the UI texture is premultiplied.
+                        blend: {
+                            color: { srcFactor: "one", dstFactor: "one-minus-src-alpha", operation: "add" },
+                            alpha: { srcFactor: "one", dstFactor: "one-minus-src-alpha", operation: "add" },
+                        },
+                    }],
+            },
+            primitive: { topology: "triangle-list" },
+        });
+    }
+    /**
+     * Encode the UI blit into `commandEncoder`, sampling `uiTextureView` over
+     * `targetView` (the swapchain texture view for the current frame).
+     */
+    execute(commandEncoder, targetView, uiTextureView) {
+        if (this.disposed || !uiTextureView)
+            return;
+        const bindGroup = this.device.createBindGroup({
+            layout: this.bindGroupLayout,
+            entries: [
+                { binding: 0, resource: uiTextureView },
+                { binding: 1, resource: this.sampler },
+            ],
+        });
+        const pass = commandEncoder.beginRenderPass({
+            colorAttachments: [{
+                    view: targetView,
+                    loadOp: "load",
+                    storeOp: "store",
+                }],
+        });
+        pass.setPipeline(this.pipeline);
+        pass.setBindGroup(0, bindGroup);
+        pass.draw(3, 1, 0, 0);
+        pass.end();
+    }
+    /**
+     * Draw the UI texture into an already-open render pass (fullscreen
+     * triangle, premultiplied-alpha blend). Used by `ScreenUiCompositor`
+     * integrations where `GameRenderer` owns the surface pass.
+     */
+    renderInto(pass, uiTextureView) {
+        if (this.disposed || !uiTextureView)
+            return;
+        const bindGroup = this.device.createBindGroup({
+            layout: this.bindGroupLayout,
+            entries: [
+                { binding: 0, resource: uiTextureView },
+                { binding: 1, resource: this.sampler },
+            ],
+        });
+        pass.setPipeline(this.pipeline);
+        pass.setBindGroup(0, bindGroup);
+        pass.draw(3, 1, 0, 0);
+    }
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        // Pipelines/layouts/samplers are implicitly released with the device.
+    }
+}