@downdraft/engine 0.1.1 → 0.2.0

package/dist/libraries/html-ui-kit/src/nav/vcursor.js

@@ -0,0 +1,177 @@
+// ============================================================================
+// vcursor.ts — controller-driven virtual cursor over html-ui panels.
+//
+// VirtualCursor owns a fullscreen, non-interactive overlay panel containing a
+// cursor arrow; it tracks a screen-space position and routes synthetic
+// pointer events (move/down/up/wheel) through host.panelAtHandle →
+// handle.sendPointer, so hover, click, scroll and drag all reach the real
+// doc pipeline exactly like a mouse.
+//
+// PadCursorDriver polls a GamepadSource slot each frame: right stick moves
+// the cursor (velocity response curve), A / right-trigger clicks, and
+// holding LT turns the right stick into scroll. Steam-Deck-style mapping.
+// ============================================================================
+import { GP_AXIS, GP_BTN } from "@downdraft/engine/sab/gamepad-devices";
+import { kitStyleTag } from "../theme.js";
+const CURSOR_CSS = `
+html,body { margin:0; padding:0; }
+/* overflow:visible — kit's body{overflow:hidden} clips everything when the
+   body has no in-flow content (all-absolute children collapse its height). */
+body { background: transparent; overflow: visible; }
+#vc { position:absolute; left:0; top:0; width:18px; height:18px; }
+.vc-stem { position:absolute; left:0; top:1px; width:7px; height:13px;
+  background:#000; }
+.vc-head { position:absolute; left:7px; top:3px; width:0; height:0;
+  border-top:5px solid transparent; border-bottom:5px solid transparent;
+  border-left:9px solid #000; }
+.vc-stem-i { position:absolute; left:1px; top:2px; width:5px; height:11px;
+  background:#f5f7fa; }
+.vc-head-i { position:absolute; left:7px; top:4px; width:0; height:0;
+  border-top:4px solid transparent; border-bottom:4px solid transparent;
+  border-left:8px solid #f5f7fa; }
+`;
+function cursorHtml() {
+    return `<html><head>${kitStyleTag()}<style>${CURSOR_CSS}</style></head>
+<body><div id="vc"><div class="vc-stem"></div><div class="vc-head"></div>
+<div class="vc-stem-i"></div><div class="vc-head-i"></div></div></body></html>`;
+}
+/**
+ * A mouse-like pointer driven programmatically (typically by a gamepad via
+ * PadCursorDriver). Position is screen-space CSS px; events land on the
+ * topmost interactive panel under the cursor, or no-one when over the world.
+ */
+export class VirtualCursor {
+    x;
+    y;
+    host;
+    overlay;
+    screenW;
+    screenH;
+    hover = null;
+    captured = null;
+    shown = true;
+    constructor(host, opts) {
+        this.host = host;
+        this.screenW = opts.screenW;
+        this.screenH = opts.screenH;
+        this.x = opts.screenW / 2;
+        this.y = opts.screenH / 2;
+        this.overlay = host.mount({
+            id: "dd-vcursor",
+            rect: { x: 0, y: 0, w: opts.screenW, h: opts.screenH },
+            z: opts.z ?? 2000,
+            scale: 1,
+            interactive: false,
+            html: cursorHtml(),
+        });
+        this.place();
+    }
+    /** Screen resized — the overlay is fullscreen so it must track. */
+    setScreen(w, h) {
+        this.screenW = w;
+        this.screenH = h;
+        this.overlay.setRect({ x: 0, y: 0, w, h });
+        this.x = Math.min(this.x, w - 1);
+        this.y = Math.min(this.y, h - 1);
+        this.place();
+    }
+    moveBy(dx, dy) {
+        this.warp(this.x + dx, this.y + dy);
+    }
+    warp(x, y) {
+        this.x = Math.max(0, Math.min(this.screenW - 1, x));
+        this.y = Math.max(0, Math.min(this.screenH - 1, y));
+        this.place();
+        if (!this.shown)
+            return;
+        const target = this.captured ?? this.host.panelAtHandle(this.x, this.y);
+        this.hover = target;
+        target?.sendPointer({ kind: "move", x: this.x - target.rect.x, y: this.y - target.rect.y });
+    }
+    press(button = "left") {
+        const p = this.hover ?? this.host.panelAtHandle(this.x, this.y);
+        if (!p)
+            return;
+        this.captured = p;
+        p.sendPointer({ kind: "down", x: this.x - p.rect.x, y: this.y - p.rect.y, button });
+    }
+    release(button = "left") {
+        const p = this.captured ?? this.host.panelAtHandle(this.x, this.y);
+        this.captured = null;
+        if (!p)
+            return;
+        p.sendPointer({ kind: "up", x: this.x - p.rect.x, y: this.y - p.rect.y, button });
+    }
+    click(button = "left") {
+        this.press(button);
+        this.release(button);
+    }
+    scroll(dx, dy) {
+        const p = this.hover ?? this.host.panelAtHandle(this.x, this.y);
+        p?.sendPointer({ kind: "wheel", x: this.x - p.rect.x, y: this.y - p.rect.y, deltaX: dx, deltaY: dy });
+    }
+    setVisible(v) {
+        this.shown = v;
+        this.overlay.setStyle("#vc", "visibility", v ? "visible" : "hidden");
+    }
+    place() {
+        this.overlay.mutate([
+            { op: "style", sel: "#vc", prop: "left", value: `${this.x}px` },
+            { op: "style", sel: "#vc", prop: "top", value: `${this.y}px` },
+        ]);
+    }
+    dispose() {
+        this.overlay.dispose();
+    }
+}
+/** Right stick → cursor motion; A or RT → click; LT held → stick scrolls. */
+export class PadCursorDriver {
+    src;
+    slot;
+    cursor;
+    opts;
+    prevClick = false;
+    constructor(src, slot, cursor, opts = {
+        speed: 700, deadzone: 0.18, exponent: 1.6, scrollSpeed: 600,
+    }) {
+        this.src = src;
+        this.slot = slot;
+        this.cursor = cursor;
+        this.opts = opts;
+    }
+    update(dtMs) {
+        const snap = this.src.read(this.slot);
+        if (!snap) {
+            this.prevClick = false;
+            return;
+        }
+        const o = this.opts;
+        const dz = o.deadzone;
+        const rx = snap.axes[GP_AXIS.RIGHT_X] ?? 0;
+        const ry = snap.axes[GP_AXIS.RIGHT_Y] ?? 0;
+        const lt = snap.axes[GP_AXIS.LEFT_TRIGGER] ?? 0;
+        const rt = snap.axes[GP_AXIS.RIGHT_TRIGGER] ?? 0;
+        const curve = (v) => {
+            const m = Math.abs(v);
+            if (m < dz)
+                return 0;
+            return Math.sign(v) * Math.pow((m - dz) / (1 - dz), o.exponent);
+        };
+        const dt = dtMs / 1000;
+        const vx = curve(rx), vy = curve(ry);
+        if (lt > 0.4) {
+            // Scroll mode: right stick becomes wheel deltas.
+            if (vx || vy)
+                this.cursor.scroll(vx * o.scrollSpeed * dt, vy * o.scrollSpeed * dt);
+        }
+        else if (vx || vy) {
+            this.cursor.moveBy(vx * o.speed * dt, vy * o.speed * dt);
+        }
+        const click = (snap.buttonsLo & (1 << GP_BTN.SOUTH)) !== 0 || rt > 0.6;
+        if (click && !this.prevClick)
+            this.cursor.press();
+        if (!click && this.prevClick)
+            this.cursor.release();
+        this.prevClick = click;
+    }
+}

package/dist/libraries/html-ui-kit/src/ten-foot.js

@@ -0,0 +1,138 @@
+// ============================================================================
+// ten-foot.ts — 10-foot / couch UI widgets + TV theme preset.
+//
+// These build on the same conventions as components.ts (data-kit roots,
+// data-action verbs, data-* state attrs) plus nav markup understood by
+// NavController: `data-nav` marks items focusable and `data-nav-zone`
+// declares a focus scope (pushZone traps pad input inside blades/modals,
+// popZone returns to the remembered focus).
+//
+// Pair with tvCss() for distance legibility; then a game only mounts a
+// panel — pad nav, OSK, and scroll-into-view come free.
+// ============================================================================
+import { dataAttrs, esc } from "./components.js";
+const on = (v) => (v ? ` data-on="true"` : ` data-on="false"`);
+// ── TV theme preset ──
+/**
+ * Stylesheet for couch-distance UIs (~10 feet). Compose after kitStyleTag():
+ * `mount("<style>" + kitCss + tvCss() + "</style>")`. Scales type/controls
+ * ~1.5×, widens hit targets, and strengthens the nav focus ring.
+ */
+export function tvCss() {
+    return `
+body { font-size: 18px; }
+.dd-btn { font-size:17px; padding:11px 20px; }
+.dd-input, .dd-textarea { font-size:17px; padding:9px 12px; }
+.dd-section { font-size:14px; }
+.dd-li, .dd-mi { font-size:16px; padding:10px 14px; }
+.dd-t { font-size:16px; padding:9px 18px; }
+/* NavController focus ring — bigger + animated-friendly for TV. */
+[data-nav-focus="1"] { border-color:var(--dd-accent); background:var(--dd-accent-bg); }
+.dd-card[data-nav-focus="1"] { border-color:var(--dd-accent); background:#25313f; }
+/* Shelf + card widgets. */
+.dd-shelf { margin: 14px 0; }
+.dd-shelf-title { font-size:15px; color:var(--dd-dim); letter-spacing:1px; margin:0 0 8px 4px; }
+.dd-shelf-row { display:flex; gap:14px; overflow-x:auto; padding:4px; }
+.dd-card { flex:0 0 auto; width:180px; border:2px solid var(--dd-line); border-radius:8px;
+  background:var(--dd-panel); padding:12px; }
+.dd-card-art { height:96px; border-radius:5px; background:var(--dd-panel2); margin-bottom:9px;
+  display:flex; align-items:center; justify-content:center; color:var(--dd-faint); font-size:26px; }
+.dd-card-label { font-size:15px; color:var(--dd-text); }
+.dd-card-sub { font-size:12px; color:var(--dd-dim); margin-top:3px; }
+/* Blade — slide-in edge panel. data-open controls visibility. */
+.dd-blade { position:absolute; top:0; bottom:0; width:360px; background:var(--dd-panel);
+  border-left:1px solid var(--dd-line2); padding:22px; }
+.dd-blade[data-side="right"] { right:0; border-left:1px solid var(--dd-line2); border-right:0; }
+.dd-blade[data-side="left"] { left:0; border-right:1px solid var(--dd-line2); border-left:0; }
+.dd-blade[data-open="false"] { display:none; }
+.dd-blade-title { font-size:20px; margin-bottom:16px; }
+/* Detail hero. */
+.dd-detail { padding:26px; }
+.dd-detail-title { font-size:30px; margin-bottom:6px; }
+.dd-detail-sub { font-size:15px; color:var(--dd-dim); margin-bottom:14px; }
+.dd-detail-desc { font-size:15px; line-height:1.5; max-width:640px; margin-bottom:18px; }
+/* Command palette. */
+.dd-cmdk { position:absolute; top:12%; left:50%; transform:translateX(-50%);
+  width:560px; background:var(--dd-panel); border:1px solid var(--dd-line2);
+  border-radius:10px; padding:14px; }
+.dd-cmdk[data-open="false"] { display:none; }
+.dd-cmdk input { width:100%; font-size:17px; padding:11px 13px; margin-bottom:8px;
+  background:var(--dd-sink); border:1px solid var(--dd-line2); border-radius:6px; color:var(--dd-text); }
+/* Settings row — label left, control right. */
+.dd-srow { display:flex; align-items:center; padding:11px 14px; border-radius:6px;
+  border:1px solid transparent; gap:16px; }
+.dd-srow[data-nav-focus="1"] { background:var(--dd-panel2); border-color:var(--dd-accent); }
+.dd-srow-lbl { flex:1; }
+.dd-srow-title { font-size:16px; }
+.dd-srow-hint { font-size:12px; color:var(--dd-dim); margin-top:2px; }
+.dd-srow-ctl { flex:0 0 auto; }
+`;
+}
+export function mediaCard(o) {
+    const id = o.id ?? `card-${o.label.replace(/\W+/g, "-").toLowerCase()}`;
+    const w = o.width ? ` style="width:${o.width}px"` : "";
+    return `<div class="dd-card" id="${esc(id)}" data-nav data-action="${esc(o.action ?? "kit:open")}"` +
+        ` data-id="${esc(id)}"${o.data ? dataAttrs(o.data) : ""}${w}>` +
+        `<div class="dd-card-art">${esc(o.art ?? "▶")}</div>` +
+        `<div class="dd-card-label">${esc(o.label)}</div>` +
+        (o.sub ? `<div class="dd-card-sub">${esc(o.sub)}</div>` : "") + `</div>`;
+}
+/** Horizontal scrolling shelf of cards — the Netflix row. */
+export function shelf(o) {
+    return `<div class="dd-shelf" id="${esc(o.id)}" data-kit="shelf">` +
+        (o.title ? `<div class="dd-shelf-title">${esc(o.title)}</div>` : "") +
+        `<div class="dd-shelf-row">${o.items.map(mediaCard).join("")}</div></div>`;
+}
+/** Poster grid — same cards, fixed column count, vertical flow. */
+export function mediaGrid(o) {
+    const w = o.cardWidth ?? 160;
+    return `<div id="${esc(o.id)}" data-kit="grid" style="display:flex;flex-wrap:wrap;gap:14px;` +
+        `padding:4px">${o.items.map((c) => mediaCard({ ...c, width: w })).join("")}</div>`;
+}
+// ── blade / detail ──
+/**
+ * Slide-in edge panel (Xbox blade). Markup carries `data-nav-zone` so the
+ * app can `nav.pushZone("blade:<id>")` when opening — cancel pops back out.
+ */
+export function blade(o) {
+    return `<div class="dd-blade" id="${esc(o.id)}" data-kit="blade" data-nav-zone="blade:${esc(o.id)}"` +
+        ` data-side="${o.side ?? "right"}" data-open="${o.open ? "true" : "false"}">` +
+        `<div class="dd-blade-title">${esc(o.title)}</div>${o.html}</div>`;
+}
+/** Hero detail panel — title, subtitle, description, action row. */
+export function detailPanel(o) {
+    return `<div class="dd-detail" data-kit="detail">` +
+        `<div class="dd-detail-title">${esc(o.title)}</div>` +
+        (o.sub ? `<div class="dd-detail-sub">${esc(o.sub)}</div>` : "") +
+        (o.description ? `<div class="dd-detail-desc">${esc(o.description)}</div>` : "") +
+        (o.actionsHtml ? `<div class="dd-row" style="gap:12px">${o.actionsHtml}</div>` : "") +
+        `</div>`;
+}
+/**
+ * Modal command palette — filter input + nav list. `data-nav-zone` scopes
+ * pad focus while open; the input is editable so OSK auto-open applies.
+ */
+export function commandPalette(o) {
+    const items = o.items.map((it, i) => `<div class="dd-mi" data-nav data-action="${esc(it.action ?? "kit:palette")}" data-id="${esc(o.id)}"` +
+        ` data-i="${i}"${it.data ? dataAttrs(it.data) : ""}>${esc(it.label)}` +
+        (it.hint ? ` <span style="color:var(--dd-faint);font-size:12px">${esc(it.hint)}</span>` : "") +
+        `</div>`).join("");
+    return `<div class="dd-cmdk" id="${esc(o.id)}" data-kit="cmdk" data-nav-zone="cmdk:${esc(o.id)}"` +
+        ` data-open="${o.open ? "true" : "false"}">` +
+        `<input type="text" placeholder="${esc(o.placeholder ?? "Type a command…")}" data-no-osk>` +
+        `<div class="dd-col" style="gap:2px">${items}</div></div>`;
+}
+// ── settings rows ──
+/**
+ * Settings row primitive — label + hint on the left, any control markup on
+ * the right. The row itself is focusable (`data-nav`) so pad users land on
+ * the whole row; confirm fires `action` (e.g. toggle the control).
+ */
+export function settingsRow(o) {
+    return `<div class="dd-srow" id="${esc(o.id)}" data-kit="srow" data-nav` +
+        ` data-action="${esc(o.action ?? "kit:srow")}" data-id="${esc(o.id)}"${on(o.on)}` +
+        `${o.disabled ? ` data-disabled="true"` : ""}>` +
+        `<div class="dd-srow-lbl"><div class="dd-srow-title">${esc(o.label)}</div>` +
+        (o.hint ? `<div class="dd-srow-hint">${esc(o.hint)}</div>` : "") + `</div>` +
+        `<div class="dd-srow-ctl">${o.control}</div></div>`;
+}

package/dist/libraries/html-ui-kit/src/theme.js

@@ -0,0 +1,235 @@
+// ============================================================================
+// theme.ts — Downdraft kit stylesheet. Dark-first tokens; every state that JS
+// can change lives in a `data-*` attribute so DOM mutations are single-attr
+// writes (setAttr), and hover/active/focus stay in CSS where Blitz can
+// repaint them without a host round-trip.
+//
+// IMPORTANT: state colors must come from stylesheets, not inline styles —
+// inline styles beat :hover rules in the cascade and mask state painting.
+// ============================================================================
+export const KIT_FONT_FAMILY = "sans-serif";
+export const KIT_CSS = `
+* { margin:0; padding:0; box-sizing:border-box; }
+:root {
+  --dd-bg: #10141a;      --dd-panel: #161b23;   --dd-panel2: #1c222c;
+  --dd-sink: #0f1319;    --dd-line: #2a313c;    --dd-line2: #3a4553;
+  --dd-text: #e8ecf1;    --dd-dim: #8a94a3;     --dd-faint: #5d6775;
+  --dd-accent: #4fc2f7;  --dd-accent-bg: #1d3547;
+  --dd-good: #6fbf73;    --dd-warn: #f0a04b;    --dd-bad: #e5534b;
+  --dd-radius: 5px;
+}
+body { background: var(--dd-bg); color: var(--dd-text); font-family: ${KIT_FONT_FAMILY}; font-size: 13px; overflow: hidden; }
+
+/* ── primitives ── */
+.dd-btn { display:inline-block; padding:7px 14px; border-radius:var(--dd-radius);
+  border:1px solid var(--dd-line2); background:var(--dd-panel2); color:var(--dd-text);
+  font-size:12px; }
+.dd-btn:hover { background:#26303d; border-color:#4a5568; }
+.dd-btn:active { background:#31404f; }
+.dd-btn[data-kind="accent"] { background:var(--dd-accent-bg); color:var(--dd-accent); border-color:var(--dd-accent); }
+.dd-btn[data-kind="accent"]:hover { background:#27455c; }
+.dd-btn[data-kind="danger"] { background:#3a1d1d; color:#f28b82; border-color:var(--dd-bad); }
+.dd-btn[data-kind="danger"]:hover { background:#4a2525; }
+.dd-btn[data-kind="ghost"] { background:transparent; border-color:transparent; color:var(--dd-dim); }
+.dd-btn[data-kind="ghost"]:hover { background:var(--dd-panel2); color:var(--dd-text); }
+.dd-btn[data-disabled="true"] { opacity:.45; }
+.dd-btn[data-on="true"] { background:var(--dd-accent-bg); color:var(--dd-accent); border-color:var(--dd-accent); }
+
+/* NavController focus ring — applied via data-nav-focus on any focusable. */
+[data-nav-focus="1"] { border-color:var(--dd-accent); }
+.dd-btn[data-nav-focus="1"], .dd-input[data-nav-focus="1"] { background:#26303d; border-color:var(--dd-accent); }
+
+.dd-badge { display:inline-block; padding:1px 8px; border-radius:8px; font-size:10px;
+  background:var(--dd-panel2); color:var(--dd-dim); border:1px solid var(--dd-line); }
+.dd-badge[data-kind="accent"] { color:var(--dd-accent); border-color:var(--dd-accent); }
+.dd-badge[data-kind="good"] { color:var(--dd-good); border-color:var(--dd-good); }
+.dd-badge[data-kind="warn"] { color:var(--dd-warn); border-color:var(--dd-warn); }
+.dd-badge[data-kind="bad"] { color:var(--dd-bad); border-color:var(--dd-bad); }
+
+.dd-label { font-size:11px; color:var(--dd-dim); }
+.dd-section { font-size:11px; color:var(--dd-dim); letter-spacing:1px; margin-bottom:10px; }
+.dd-divider { height:1px; background:var(--dd-line); margin:8px 0; }
+
+.dd-panel { background:var(--dd-panel); border:1px solid var(--dd-line); border-radius:6px; padding:14px; }
+.dd-row { display:flex; align-items:center; gap:8px; }
+.dd-col { display:flex; flex-direction:column; gap:8px; }
+.dd-grow { flex:1; }
+
+/* ── checkbox / switch / radio ── */
+.dd-check { display:flex; align-items:center; gap:8px; padding:3px 0; }
+.dd-check .dd-box { width:16px; height:16px; border:1px solid var(--dd-line2);
+  border-radius:3px; background:var(--dd-sink); color:#10141a; font-size:11px;
+  font-weight:bold; text-align:center; line-height:14px; }
+.dd-check:hover .dd-box { border-color:var(--dd-accent); }
+.dd-check[data-on="true"] .dd-box { background:var(--dd-accent); }
+.dd-check[data-disabled="true"] { opacity:.45; }
+.dd-check .dd-lbl { font-size:12px; }
+
+.dd-switch { display:flex; align-items:center; gap:8px; padding:3px 0; }
+.dd-switch .dd-rail { width:32px; height:16px; border-radius:8px; background:var(--dd-panel2);
+  border:1px solid var(--dd-line2); position:relative; }
+.dd-switch .dd-knob { position:absolute; top:1px; left:1px; width:12px; height:12px;
+  border-radius:6px; background:var(--dd-dim); }
+.dd-switch:hover .dd-rail { border-color:var(--dd-accent); }
+.dd-switch[data-on="true"] .dd-rail { background:var(--dd-accent-bg); border-color:var(--dd-accent); }
+.dd-switch[data-on="true"] .dd-knob { left:17px; background:var(--dd-accent); }
+.dd-switch .dd-lbl { font-size:12px; }
+
+.dd-radio .dd-opt { display:flex; align-items:center; gap:8px; padding:3px 0; }
+.dd-radio .dd-dot { width:14px; height:14px; border-radius:7px; border:1px solid var(--dd-line2);
+  background:var(--dd-sink); }
+.dd-radio .dd-opt:hover .dd-dot { border-color:var(--dd-accent); }
+.dd-radio .dd-opt[data-on="true"] .dd-dot { border-color:var(--dd-accent); background:var(--dd-accent); }
+.dd-radio .dd-lbl { font-size:12px; }
+
+/* ── text inputs ── */
+.dd-field { display:flex; flex-direction:column; gap:4px; }
+.dd-field .dd-lbl { font-size:11px; color:var(--dd-dim); }
+.dd-input { width:200px; padding:7px 10px; background:var(--dd-sink);
+  border:1px solid var(--dd-line2); border-radius:4px; font-size:13px; color:var(--dd-text); }
+.dd-input:focus { border-color:var(--dd-accent); }
+.dd-input[data-invalid="true"] { border-color:var(--dd-bad); }
+.dd-input[data-disabled="true"] { opacity:.45; }
+.dd-textarea { width:280px; min-height:64px; padding:7px 10px; background:var(--dd-sink);
+  border:1px solid var(--dd-line2); border-radius:4px; font-size:12px; color:var(--dd-text); }
+.dd-textarea:focus { border-color:var(--dd-accent); }
+.dd-num { display:flex; align-items:stretch; gap:4px; }
+.dd-num .dd-input { width:110px; }
+.dd-num .dd-step { padding:0 10px; font-size:13px; display:flex; align-items:center; }
+
+/* ── slider / progress / spinner ── */
+.dd-slider { display:flex; flex-direction:column; gap:4px; }
+.dd-slider .dd-srow { display:flex; justify-content:space-between; font-size:11px; color:var(--dd-dim); }
+.dd-slider .dd-track { height:14px; background:var(--dd-panel2); border-radius:7px;
+  border:1px solid var(--dd-line); position:relative; }
+.dd-slider .dd-fill { position:absolute; top:0; left:0; height:100%; background:var(--dd-accent); border-radius:7px; }
+.dd-slider .dd-thumb { position:absolute; top:-3px; width:8px; height:20px; margin-left:-4px;
+  background:var(--dd-text); border-radius:4px; border:1px solid var(--dd-line2); }
+.dd-slider .dd-track:hover { border-color:var(--dd-accent); }
+.dd-slider[data-disabled="true"] { opacity:.45; }
+
+.dd-progress { height:10px; background:var(--dd-panel2); border-radius:5px; overflow:hidden; }
+.dd-progress .dd-pfill { height:10px; background:var(--dd-good); border-radius:5px; }
+.dd-progress[data-kind="accent"] .dd-pfill { background:var(--dd-accent); }
+.dd-progress[data-kind="warn"] .dd-pfill { background:var(--dd-warn); }
+.dd-progress[data-kind="bad"] .dd-pfill { background:var(--dd-bad); }
+
+.dd-spinner { width:18px; height:18px; border-radius:10px; border:2px solid var(--dd-line2);
+  border-top-color:var(--dd-accent); animation:dd-spin .8s linear infinite; }
+@keyframes dd-spin { from { transform:rotate(0deg); } to { transform:rotate(360deg); } }
+
+/* ── segmented / tabs ── */
+.dd-seg { display:flex; gap:4px; background:var(--dd-sink); border-radius:5px;
+  padding:3px; width:fit-content; }
+.dd-seg .dd-o { padding:5px 16px; border-radius:4px; font-size:11px; color:var(--dd-dim); }
+.dd-seg .dd-o:hover { color:var(--dd-text); }
+.dd-seg .dd-o[data-on="true"] { background:#2e4361; color:var(--dd-accent); }
+
+.dd-tabs { display:flex; gap:2px; border-bottom:1px solid var(--dd-line); }
+.dd-tabs .dd-t { padding:8px 16px; font-size:12px; color:var(--dd-dim);
+  border-bottom:2px solid transparent; }
+.dd-tabs .dd-t:hover { color:var(--dd-text); }
+.dd-tabs .dd-t[data-on="true"] { color:var(--dd-accent); border-bottom-color:var(--dd-accent); }
+
+/* ── dropdown / menus ── */
+.dd-dd { position:relative; width:200px; }
+.dd-dd .dd-ddbtn { display:flex; justify-content:space-between; align-items:center;
+  padding:7px 10px; background:var(--dd-sink); border:1px solid var(--dd-line2);
+  border-radius:4px; font-size:12px; }
+.dd-dd:hover .dd-ddbtn { border-color:var(--dd-accent); }
+.dd-dd .dd-caret { color:var(--dd-dim); font-size:10px; }
+.dd-dd .dd-menu { display:none; position:absolute; top:100%; left:0; right:0;
+  margin-top:2px; background:var(--dd-panel); border:1px solid var(--dd-line2);
+  border-radius:4px; overflow:hidden; }
+.dd-dd[data-open="true"] .dd-menu { display:block; }
+.dd-menu .dd-mi { padding:7px 10px; font-size:12px; color:var(--dd-text); }
+.dd-menu .dd-mi:hover { background:var(--dd-panel2); }
+.dd-menu .dd-mi[data-on="true"] { color:var(--dd-accent); }
+.dd-menu .dd-msep { height:1px; background:var(--dd-line); }
+
+/* ── list / scroll / table / tree ── */
+.dd-list { background:var(--dd-sink); border:1px solid var(--dd-line); border-radius:4px;
+  overflow-y:auto; }
+.dd-list .dd-li { padding:5px 10px; font-size:12px; color:#c8d0db;
+  border-bottom:1px solid var(--dd-panel2); }
+.dd-list .dd-li:hover { background:var(--dd-panel2); }
+.dd-list .dd-li[data-on="true"] { background:#2e4361; color:var(--dd-accent); }
+
+.dd-scroll { overflow-y:auto; border:1px solid var(--dd-line); border-radius:4px;
+  background:var(--dd-sink); padding:8px; }
+
+.dd-table { width:100%; font-size:12px; border-collapse:collapse; }
+.dd-table th { text-align:left; padding:6px 8px; color:var(--dd-dim); font-size:11px;
+  border-bottom:1px solid var(--dd-line2); }
+.dd-table td { padding:6px 8px; border-bottom:1px solid var(--dd-panel2); }
+.dd-table tr[data-on="true"] td { background:#2e4361; color:var(--dd-accent); }
+.dd-table tr:hover td { background:var(--dd-panel2); }
+
+.dd-tree { font-size:12px; }
+.dd-tree .dd-trow { display:flex; align-items:center; gap:6px; padding:3px 6px;
+  border-radius:3px; }
+.dd-tree .dd-trow:hover { background:var(--dd-panel2); }
+.dd-tree .dd-trow[data-on="true"] { background:#2e4361; color:var(--dd-accent); }
+.dd-tree .dd-caret { width:12px; color:var(--dd-dim); font-size:9px; text-align:center; }
+.dd-tree .dd-kids { margin-left:16px; }
+.dd-tree .dd-trow[data-open="false"] + .dd-kids { display:none; }
+
+.dd-acc .dd-ah { display:flex; justify-content:space-between; padding:7px 10px;
+  font-size:12px; background:var(--dd-panel2); border:1px solid var(--dd-line);
+  border-radius:4px; }
+.dd-acc .dd-ah:hover { border-color:var(--dd-line2); }
+.dd-acc .dd-ab { padding:8px 10px; font-size:12px; color:#c8d0db;
+  border:1px solid var(--dd-line); border-top:none; }
+.dd-acc .dd-as[data-open="false"] .dd-ab { display:none; }
+
+/* ── overlays: modal / tooltip / context menu / toast ── */
+/* Positive z-index on positioned elements breaks hit-testing in the pinned
+   Blitz rev (element leaves the hit tree). Overlays stack by DOM order —
+   render modal/ctx/toasts markup LAST in the body. */
+.dd-modal { display:none; position:absolute; top:0; left:0; right:0; bottom:0; }
+.dd-modal[data-open="true"] { display:block; }
+.dd-modal .dd-backdrop { position:absolute; top:0; left:0; right:0; bottom:0;
+  background:rgba(4,6,9,.62); }
+.dd-modal .dd-dlg { position:absolute; left:50%; top:18%; width:340px; margin-left:-170px;
+  background:var(--dd-panel); border:1px solid var(--dd-line2); border-radius:8px;
+  padding:16px; }
+.dd-modal .dd-dtitle { font-size:14px; font-weight:bold; margin-bottom:10px; }
+.dd-modal .dd-dbtns { display:flex; justify-content:flex-end; gap:8px; margin-top:14px; }
+
+.dd-tipwrap { position:relative; width:fit-content; }
+/* bottom: anchoring resolves wrong in Blitz — tips render BELOW the target
+   (top:100%) instead of above it. */
+.dd-tipwrap .dd-tip { display:none; position:absolute; top:100%; left:0;
+  margin-top:5px; width:140px; padding:5px 8px;
+  background:#0b0e13; border:1px solid var(--dd-line2); border-radius:4px;
+  font-size:10px; color:var(--dd-dim); }
+.dd-tipwrap:hover .dd-tip { display:block; }
+
+.dd-ctx { display:none; position:absolute; min-width:150px;
+  background:var(--dd-panel); border:1px solid var(--dd-line2); border-radius:5px;
+  overflow:hidden; }
+.dd-ctx[data-open="true"] { display:block; }
+
+.dd-toasts { position:absolute; right:14px; top:14px; display:flex;
+  flex-direction:column; gap:8px; }
+.dd-toast { display:flex; gap:10px; align-items:center; min-width:220px;
+  padding:10px 12px; border-radius:6px; font-size:11px;
+  background:#1d2a1d; border:1px solid #4a7a4a; color:#9fd89f; }
+.dd-toast[data-kind="warn"] { background:#2a2517; border-color:#8a6d3b; color:#e8c88a; }
+.dd-toast[data-kind="bad"] { background:#2f1a1a; border-color:#8a4a4a; color:#f0a8a0; }
+.dd-toast[data-kind="info"] { background:#182430; border-color:#3d6d94; color:#9fcdf0; }
+.dd-toast .dd-x { margin-left:auto; color:var(--dd-dim); padding:0 4px; }
+.dd-toast .dd-x:hover { color:var(--dd-text); }
+
+/* ── misc ── */
+.dd-toolbar { display:flex; align-items:center; gap:8px; padding:8px 12px;
+  background:var(--dd-panel); border:1px solid var(--dd-line); border-radius:6px; }
+.dd-kv { display:flex; font-size:12px; }
+.dd-kv .dd-k { width:120px; color:var(--dd-dim); font-size:11px; }
+.dd-kv .dd-v { color:var(--dd-text); }
+.dd-err { font-size:10px; color:var(--dd-bad); min-height:12px; }
+`;
+/** Full `<style>` tag containing the kit theme — drop into a doc <head>. */
+export function kitStyleTag() {
+    return `<style>${KIT_CSS}</style>`;
+}

package/dist/libraries/inspectable/src/index.js

@@ -0,0 +1,6 @@
+// ============================================================================
+// @downdraft/engine/libraries/inspectable — schema'd registry of named
+// game-state nodes that automation can read and write semantically
+// (no synthetic input). See inspectable.ts for the design notes.
+// ============================================================================
+export { InspectableError, InspectableRegistry } from "./inspectable.js";