@downdraft/engine 0.0.0 → 0.1.0

package/libraries/html-ui-kit/src/nav/router.ts

@@ -0,0 +1,167 @@
+// ============================================================================
+// router.ts — batteries-included nav wiring for an HtmlUiHost.
+//
+//   UiNavRouter owns one NavController per mounted panel, routes a shared
+//   input stream (any connected pad + optional keyboard) to the topmost
+//   panel, and auto-opens the OSK when a pad confirms an editable node.
+//   createHtmlUi wires this up when `nav` is enabled; games can also build
+//   one directly for bespoke integration.
+// ============================================================================
+
+import type { GamepadSource } from "@downdraft/engine/input/local-player-manager";
+import type { HtmlUiHost, UiPanelHandle } from "@downdraft/engine/modules/html-ui";
+import { NavController, type NavAction, type NavControllerOptions } from "./nav-controller";
+import { keyToNavAction, PadNavDriver, type NavInputOptions } from "./nav-input";
+import { openOsk, type OskOptions, type OskSession } from "./osk";
+
+export interface UiNavRouterOptions {
+  screenW: number;
+  screenH: number;
+  /** Pad source — any connected pad drives nav (one driver per slot). */
+  source?: GamepadSource | null;
+  /** PadNavDriver tuning (deadzone, repeat, thresholds). */
+  pad?: NavInputOptions;
+  /** Auto-open the OSK when a pad confirms an editable node. Default true. */
+  autoOsk?: boolean;
+  /** OSK overrides (layout). Screen size comes from this router. */
+  osk?: Omit<OskOptions, "screenW" | "screenH">;
+  /** Extra NavController options applied to every attached panel. */
+  nav?: NavControllerOptions;
+}
+
+/**
+ * Focus-stack + input router for controller navigation. The "active" panel
+ * is the most recently attached live panel — mount a modal on top and it
+ * captures nav; dispose it and focus returns underneath.
+ */
+export class UiNavRouter {
+  /** Master switch — false suspends pad/key routing (OSK stays interactive). */
+  enabled = true;
+
+  private readonly host: HtmlUiHost;
+  private opts: UiNavRouterOptions;
+  private readonly ctrls = new Map<UiPanelHandle, NavController>();
+  private order: UiPanelHandle[] = [];
+  private pads = new Map<number, PadNavDriver>();
+  private source: GamepadSource | null;
+  private oskSession: OskSession | null = null;
+  /** Which device kind produced the in-flight dispatch — read by onConfirm. */
+  private lastVia: "pad" | "key" = "key";
+  private lastTime: number | undefined;
+
+  constructor(host: HtmlUiHost, opts: UiNavRouterOptions) {
+    this.host = host;
+    this.opts = opts;
+    this.source = opts.source ?? null;
+  }
+
+  setScreen(w: number, h: number) {
+    this.opts = { ...this.opts, screenW: w, screenH: h };
+  }
+
+  /** Register a panel for navigation; returns its controller (cached). */
+  attach(handle: UiPanelHandle, navOpts?: NavControllerOptions): NavController {
+    let c = this.ctrls.get(handle);
+    if (c) return c;
+    const userConfirm = navOpts?.onConfirm ?? this.opts.nav?.onConfirm;
+    c = new NavController(handle, {
+      ...this.opts.nav,
+      ...navOpts,
+      onConfirm: (info) => {
+        userConfirm?.(info);
+        const autoOsk = this.opts.autoOsk !== false;
+        if (info.editable && autoOsk && this.lastVia === "pad") {
+          void this.maybeOpenOsk(handle, info.node);
+        }
+      },
+    });
+    this.ctrls.set(handle, c);
+    if (!this.order.includes(handle)) this.order.push(handle);
+    return c;
+  }
+
+  detach(handle: UiPanelHandle) {
+    this.ctrls.delete(handle);
+    this.order = this.order.filter((h) => h !== handle);
+  }
+
+  /** Refresh nav snapshots (call after mutating structure). */
+  invalidate(handle?: UiPanelHandle) {
+    if (handle) { this.ctrls.get(handle)?.invalidate(); return; }
+    for (const c of this.ctrls.values()) c.invalidate();
+  }
+
+  /** NavController for the topmost attached panel. */
+  active(): NavController | null {
+    for (let i = this.order.length - 1; i >= 0; i--) {
+      const c = this.ctrls.get(this.order[i]!);
+      if (c) return c;
+    }
+    return null;
+  }
+
+  /** Make a specific panel's controller the nav target. */
+  setActive(handle: UiPanelHandle | null) {
+    if (!handle) return;
+    this.order = this.order.filter((h) => h !== handle);
+    this.order.push(handle);
+  }
+
+  /** Dispatch an action; `via` records the source device for OSK logic. */
+  dispatch(a: NavAction, via: "pad" | "key" = "key") {
+    this.lastVia = via;
+    if (this.oskSession) {
+      if (this.oskSession.dispatch(a)) return;
+      this.oskSession = null;
+    }
+    if (!this.enabled) return;
+    this.active()?.dispatch(a);
+  }
+
+  /** Keyboard entry point — returns true when the key was consumed. */
+  handleKey(e: { key?: string; keyCode?: number; shiftKey?: boolean }): boolean {
+    const a = keyToNavAction(e.key ?? e.keyCode ?? "", e.shiftKey ?? false);
+    if (!a) return false;
+    // While an editable element holds DOM focus, keys belong to the doc —
+    // arrows/backspace are text input, not navigation. (OSK keys still route.)
+    if (!this.oskSession && this.active()?.focusedInfo()?.editable) return false;
+    if (this.oskSession || this.enabled) { this.dispatch(a, "key"); return true; }
+    return false;
+  }
+
+  /** Poll connected pads — call once per frame (createHtmlUi does this). */
+  update(nowMs?: number) {
+    if (!this.source) return;
+    for (const slot of this.source.listConnected()) {
+      let d = this.pads.get(slot);
+      if (!d) {
+        d = new PadNavDriver(this.source, slot, (a) => this.dispatch(a, "pad"), this.opts.pad);
+        this.pads.set(slot, d);
+      }
+      d.update(nowMs);
+    }
+  }
+
+  /** Open the OSK for a node unless it opted out with `data-no-osk`. */
+  private async maybeOpenOsk(handle: UiPanelHandle, node: number) {
+    const noOsk = await handle.getAttr(node, "data-no-osk");
+    if (noOsk !== null && noOsk !== undefined) return;
+    if (this.oskSession) return; // an OSK may have opened meanwhile
+    this.oskSession = openOsk(this.host, handle, node, {
+      screenW: this.opts.screenW,
+      screenH: this.opts.screenH,
+      ...this.opts.osk,
+    });
+  }
+
+  /** While an OSK session is open, expose it (for inspection/tests). */
+  get osk(): OskSession | null { return this.oskSession; }
+
+  dispose() {
+    this.oskSession?.close(false);
+    this.oskSession = null;
+    this.ctrls.clear();
+    this.order = [];
+    this.pads.clear();
+  }
+}

package/libraries/html-ui-kit/src/nav/vcursor.ts

@@ -0,0 +1,203 @@
+// ============================================================================
+// 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 type { GamepadSource } from "@downdraft/engine/input/local-player-manager";
+import type { HtmlUiHost, UiPanelHandle } from "@downdraft/engine/modules/html-ui";
+import { GP_AXIS, GP_BTN } from "@downdraft/engine/sab/gamepad-devices";
+import { kitStyleTag } from "../theme";
+
+export interface VirtualCursorOptions {
+  screenW: number;
+  screenH: number;
+  /** Overlay z-order (default 2000 — above OSK's 1000). */
+  z?: number;
+  /** Cursor sprite size in px (default 18). */
+  size?: number;
+}
+
+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(): string {
+  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: number;
+  y: number;
+  private host: HtmlUiHost;
+  private overlay: UiPanelHandle;
+  private screenW: number;
+  private screenH: number;
+  private hover: UiPanelHandle | null = null;
+  private captured: UiPanelHandle | null = null;
+  private shown = true;
+
+  constructor(host: HtmlUiHost, opts: VirtualCursorOptions) {
+    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: number, h: number): void {
+    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: number, dy: number): void {
+    this.warp(this.x + dx, this.y + dy);
+  }
+
+  warp(x: number, y: number): void {
+    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" | "middle" | "right" = "left"): void {
+    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" | "middle" | "right" = "left"): void {
+    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" | "middle" | "right" = "left"): void {
+    this.press(button);
+    this.release(button);
+  }
+
+  scroll(dx: number, dy: number): void {
+    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: boolean): void {
+    this.shown = v;
+    this.overlay.setStyle("#vc", "visibility", v ? "visible" : "hidden");
+  }
+
+  private place(): void {
+    this.overlay.mutate([
+      { op: "style", sel: "#vc", prop: "left", value: `${this.x}px` },
+      { op: "style", sel: "#vc", prop: "top", value: `${this.y}px` },
+    ]);
+  }
+
+  dispose(): void {
+    this.overlay.dispose();
+  }
+}
+
+export interface PadCursorOptions {
+  /** Cursor speed at full deflection, px/s (default 700). */
+  speed?: number;
+  /** Right-stick deadzone (default 0.18). */
+  deadzone?: number;
+  /** Response exponent — >1 gives precision near center (default 1.6). */
+  exponent?: number;
+  /** Wheel delta per second at full stick while LT held (default 600). */
+  scrollSpeed?: number;
+}
+
+/** Right stick → cursor motion; A or RT → click; LT held → stick scrolls. */
+export class PadCursorDriver {
+  private prevClick = false;
+
+  constructor(
+    private src: GamepadSource,
+    private slot: number,
+    private cursor: VirtualCursor,
+    private opts: Required<PadCursorOptions> = {
+      speed: 700, deadzone: 0.18, exponent: 1.6, scrollSpeed: 600,
+    },
+  ) {}
+
+  update(dtMs: number): void {
+    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: number) => {
+      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/libraries/html-ui-kit/src/ten-foot.ts

@@ -0,0 +1,182 @@
+// ============================================================================
+// 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";
+
+const on = (v: boolean | undefined) => (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(): string {
+  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; }
+`;
+}
+
+// ── shelves / cards ──
+
+export interface MediaCardOpts {
+  /** Focusable id (optional — cards are reachable by data-action too). */
+  id?: string;
+  label: string;
+  sub?: string;
+  /** Short glyph/text shown in the art tile (e.g. "▶", initials). */
+  art?: string;
+  /** data-action verb fired on confirm — defaults to "kit:open". */
+  action?: string;
+  data?: Record<string, string | number>;
+  /** Card width in px (default 180). */
+  width?: number;
+}
+export function mediaCard(o: MediaCardOpts): string {
+  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: { id: string; title?: string; items: MediaCardOpts[] }): string {
+  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: { id: string; items: MediaCardOpts[]; cols?: number; cardWidth?: number }): string {
+  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: {
+  id: string; title: string; html: string;
+  side?: "left" | "right"; open?: boolean;
+}): string {
+  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: {
+  title: string; sub?: string; description?: string; actionsHtml?: string;
+}): string {
+  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>`;
+}
+
+// ── command palette ──
+
+export interface PaletteItem { label: string; hint?: string; action?: string; data?: Record<string, string | number> }
+/**
+ * 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: { id: string; items: PaletteItem[]; open?: boolean; placeholder?: string }): string {
+  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: {
+  id: string; label: string; hint?: string;
+  /** Right-side control markup (button/switch/slider/…). */
+  control: string;
+  /** data-action fired when the row is confirmed. */
+  action?: string;
+  on?: boolean; disabled?: boolean;
+}): string {
+  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>`;
+}