@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/ui/caption.js

@@ -0,0 +1,286 @@
+import { h } from './dom.js';
+import { prefersReducedMotionIn } from './styles.js';
+/** Area (px²) of `box` that lies inside any of `regions` (overlaps between regions count twice). Pure. */
+export function overlapArea(box, regions) {
+    let area = 0;
+    for (const r of regions) {
+        const w = Math.min(box.x + box.width, r.x + r.width) - Math.max(box.x, r.x);
+        const h = Math.min(box.y + box.height, r.y + r.height) - Math.max(box.y, r.y);
+        if (w > 0 && h > 0)
+            area += w * h;
+    }
+    return area;
+}
+/** The order corners are tried in: the preferred one, its mirror across, then the other edge. Pure. */
+export function cornerOrder(preferred) {
+    const [v, side] = preferred.split('-');
+    const flipV = v === 'top' ? 'bottom' : 'top';
+    const flipS = side === 'left' ? 'right' : 'left';
+    return [preferred, `${v}-${flipS}`, `${flipV}-${side}`, `${flipV}-${flipS}`];
+}
+/** How long a line should stay up once fully revealed. Pure. */
+export function readingTimeMs(text, opts = {}) {
+    const { baseMs = 1200, perCharMs = 45, minMs = 2000, maxMs = 12000 } = opts;
+    const chars = text.trim().length;
+    return Math.round(Math.min(maxMs, Math.max(minMs, baseMs + chars * perCharMs)));
+}
+/** Delay before revealing the next char: pauses after punctuation. Pure. */
+export function revealDelayMs(prev, cps) {
+    const base = 1000 / cps;
+    if (/[.!?…]/.test(prev))
+        return base * 8;
+    if (/[,;:—–]/.test(prev))
+        return base * 4;
+    return base;
+}
+/**
+ * A corner speech/caption card with a typewriter reveal and a queue. The full line goes into a
+ * polite live region at once (screen readers don't hear the typewriter), and the visible text
+ * keeps its final layout from the start (unrevealed chars are `visibility:hidden`) so the card
+ * never reflows while typing.
+ */
+export class CaptionCard {
+    element;
+    portraitEl;
+    speakerEl;
+    textEl;
+    shownEl;
+    pendingEl;
+    liveEl;
+    queue = [];
+    current = null;
+    revealed = 0;
+    timer = null;
+    phase = 'idle';
+    corner;
+    sideEl;
+    bodyEl;
+    placeSubs = new Set();
+    homeEl;
+    dockHost = null;
+    lineCps = 0;
+    isSuspended = false;
+    reducedMotion;
+    cps;
+    constructor(container, opts = {}) {
+        this.corner = opts.corner ?? 'bottom-right';
+        this.reducedMotion = opts.reducedMotion ?? prefersReducedMotionIn();
+        this.cps = opts.cps ?? 45;
+        this.portraitEl = h('div', { class: 'tc-caption-portrait', 'aria-hidden': 'true' });
+        this.speakerEl = h('div', { class: 'tc-caption-speaker', 'aria-hidden': 'true' });
+        this.shownEl = h('span');
+        this.pendingEl = h('span', { class: 'tc-caption-pending' });
+        this.textEl = h('div', { class: 'tc-caption-text', 'aria-hidden': 'true' }, this.shownEl, this.pendingEl);
+        this.liveEl = h('div', {
+            class: 'tc-sr-only',
+            role: 'status',
+            'aria-live': 'polite',
+            'aria-atomic': 'true',
+        });
+        // With a portrait, the speaker's name sits under it (a shorter card); without, above the text.
+        this.sideEl = h('div', { class: 'tc-caption-side' }, this.portraitEl);
+        this.bodyEl = h('div', { class: 'tc-caption-body' }, this.speakerEl, this.textEl);
+        this.element = h('div', { class: 'tc-caption', dataset: { corner: this.corner }, hidden: true }, this.sideEl, this.bodyEl);
+        if (opts.clickToAdvance !== false)
+            this.element.addEventListener('click', () => this.advance());
+        this.homeEl = container;
+        container.append(this.element, this.liveEl);
+    }
+    /** The region the card is docked in (see `dock`), or null in its corner. */
+    get docked() {
+        return this.dockHost;
+    }
+    /**
+     * Region placement (layout regions, `Layout.dockCaption`): move the card into `host` and let
+     * it fill that region instead of floating in a corner. While docked, corners and `onPlace` do
+     * not apply; the region never overlaps another. `null` returns it to its corner in the
+     * original container. The live region stays put.
+     */
+    dock(host) {
+        if (host === this.dockHost)
+            return;
+        this.dockHost = host;
+        this.element.toggleAttribute('data-docked', !!host);
+        this.element.style.maxWidth = '';
+        if (host)
+            host.append(this.element);
+        else
+            this.homeEl.insertBefore(this.element, this.liveEl);
+        this.place();
+    }
+    /** True while a line is showing or queued. */
+    get busy() {
+        return this.current !== null;
+    }
+    get queued() {
+        return this.queue.length;
+    }
+    /** Text of the line being shown, or null. */
+    get currentText() {
+        return this.current?.text ?? null;
+    }
+    /** True while `suspend(true)` holds the card hidden and frozen. */
+    get suspended() {
+        return this.isSuspended;
+    }
+    /**
+     * Called whenever the card is laid out in its corner (a new line, back from suspension or
+     * undocked), after its corner is reset to the line's and its inline `max-width` cleared. A
+     * game that must keep the card off parts of its scene moves or narrows it here (`overlapArea`
+     * and `cornerOrder` help). Returns unsubscribe.
+     */
+    onPlace(fn) {
+        this.placeSubs.add(fn);
+        return () => this.placeSubs.delete(fn);
+    }
+    /** Lay the card out again in its corner and run `onPlace` (e.g. after the scene moved). */
+    relayout() {
+        this.place();
+    }
+    /**
+     * Hide the card and freeze its typing and hold timers (e.g. while a modal panel is open);
+     * `suspend(false)` shows it again and picks up where it left off, with a fresh hold. The
+     * queue and live region are untouched, and `say()` still queues while suspended.
+     */
+    suspend(on) {
+        if (on === this.isSuspended)
+            return;
+        this.isSuspended = on;
+        this.element.toggleAttribute('data-suspended', on);
+        if (on) {
+            this.stopTimer();
+        }
+        else {
+            this.place();
+            this.schedule();
+        }
+    }
+    /** Queue a line; resolves when it's dismissed (held time elapsed, advanced, or cleared). */
+    say(text, opts = {}) {
+        return new Promise((resolve) => {
+            this.queue.push({ text, opts, resolve });
+            if (!this.current)
+                this.next();
+        });
+    }
+    /** Skip the typewriter if typing, else dismiss the current line. */
+    advance() {
+        if (this.phase === 'typing')
+            this.finishReveal();
+        else if (this.phase === 'holding')
+            this.dismiss();
+    }
+    /** Drop the queue and hide the card; all pending `say` promises resolve. */
+    clear() {
+        const pending = this.queue.splice(0);
+        this.stopTimer();
+        const cur = this.current;
+        this.current = null;
+        this.phase = 'idle';
+        this.element.hidden = true;
+        cur?.resolve();
+        for (const l of pending)
+            l.resolve();
+    }
+    destroy() {
+        this.clear();
+        this.placeSubs.clear();
+        this.element.remove();
+        this.liveEl.remove();
+    }
+    next() {
+        const line = this.queue.shift();
+        this.stopTimer();
+        if (!line) {
+            this.current = null;
+            this.phase = 'idle';
+            this.element.hidden = true;
+            return;
+        }
+        this.current = line;
+        this.revealed = 0;
+        this.speakerEl.textContent = line.opts.speaker ?? '';
+        this.portraitEl.replaceChildren(...(line.opts.portrait ? [line.opts.portrait] : []));
+        this.sideEl.hidden = !line.opts.portrait;
+        if (line.opts.portrait)
+            this.sideEl.append(this.speakerEl);
+        else
+            this.bodyEl.prepend(this.speakerEl);
+        this.liveEl.textContent = line.opts.speaker ? `${line.opts.speaker}: ${line.text}` : line.text;
+        this.element.hidden = false;
+        this.lineCps = line.opts.cps ?? this.cps;
+        const instant = this.reducedMotion || this.lineCps <= 0;
+        if (instant)
+            this.revealed = [...line.text].length;
+        this.phase = instant ? 'holding' : 'typing';
+        // The whole line is laid out from the start (pending chars hidden), so place it once now.
+        this.render();
+        this.place();
+        this.schedule();
+    }
+    /** (Re)start the timer for the current phase, unless suspended. */
+    schedule() {
+        this.stopTimer();
+        const line = this.current;
+        if (!line || this.isSuspended)
+            return;
+        if (this.phase === 'typing')
+            this.tick(this.lineCps);
+        else if (this.phase === 'holding') {
+            const hold = line.opts.hold ?? readingTimeMs(line.text);
+            if (hold > 0)
+                this.timer = setTimeout(() => this.dismiss(), hold);
+        }
+    }
+    /** Reset the card to the line's corner and let `onPlace` adjust it. */
+    place() {
+        const el = this.element;
+        const line = this.current;
+        if (!line || el.hidden || this.isSuspended || this.dockHost)
+            return;
+        el.dataset.corner = line.opts.corner ?? this.corner;
+        el.style.maxWidth = '';
+        for (const fn of this.placeSubs)
+            fn(el);
+    }
+    tick(cps) {
+        const line = this.current;
+        const chars = [...line.text];
+        if (this.revealed >= chars.length) {
+            this.finishReveal();
+            return;
+        }
+        const ch = chars[this.revealed];
+        this.revealed++;
+        this.render();
+        if (ch.trim())
+            line.opts.onChar?.(ch, this.revealed - 1);
+        this.timer = setTimeout(() => this.tick(cps), revealDelayMs(ch, cps));
+    }
+    finishReveal() {
+        const line = this.current;
+        if (!line)
+            return;
+        this.revealed = [...line.text].length;
+        this.render();
+        this.phase = 'holding';
+        this.schedule();
+    }
+    dismiss() {
+        const line = this.current;
+        this.stopTimer();
+        this.current = null;
+        line?.resolve();
+        this.next();
+    }
+    render() {
+        const chars = [...(this.current?.text ?? '')];
+        this.shownEl.textContent = chars.slice(0, this.revealed).join('');
+        this.pendingEl.textContent = chars.slice(this.revealed).join('');
+    }
+    stopTimer() {
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = null;
+    }
+}

package/dist/ui/cursor.d.ts

@@ -0,0 +1,105 @@
+/**
+ * World cursor (ws/ui-3): a pad- and keyboard-driven selection cursor over the world. Grid mode
+ * steps by (dx, dy) on each fresh d-pad or arrow press, with latch and repeat (hold to keep
+ * stepping); targets mode snaps to the nearest target in the pressed direction. A/Enter selects.
+ * The cursor element rides `Anchors` on the hud layer when the game says where the cursor is
+ * (`at`) or a target is picked. It yields to a modal panel: while the stack owns the pad
+ * (`stack.padOwner`, followed through `onPadOwnerChange`, ws/ui-4) nothing is read and the latch
+ * is reset, so the pad is the panel's and the cursor resumes afterwards with a fresh latch.
+ * Call `update()` once per frame (before or after `padNav.update()`, both latch on their own).
+ */
+import type { Anchors } from './anchor.js';
+import { type PadDir, type PadLike } from './padnav.js';
+import type { PadOwner } from './stack.js';
+/** A thing the cursor can land on in targets mode: a plane position plus its world point. */
+export interface WorldTarget {
+    id?: string | number;
+    /** Plane coordinates the direction picking reasons in (a cell, a tile, a screen point). */
+    x: number;
+    y: number;
+    /** The point the cursor element is anchored at. */
+    world: ArrayLike<number>;
+}
+export interface CursorRepeat {
+    /** ms a direction is held before it repeats. Default 400. */
+    delay: number;
+    /** ms between repeats. Default 80. */
+    interval: number;
+}
+export interface CursorOptions {
+    /** `grid` steps by (dx, dy); `targets` snaps between `targets()`. */
+    mode: 'grid' | 'targets';
+    /** Grid mode: a press (or repeat) in a direction; dy is +1 for down (y down). */
+    step?: (dx: number, dy: number) => void;
+    /** Grid mode: where the cursor is now, in world units, for its element; null hides it. */
+    at?: () => ArrayLike<number> | null;
+    /** Targets mode: the targets to pick from, read on each press. */
+    targets?: () => readonly WorldTarget[];
+    onSelect?: (target: WorldTarget | null) => void;
+    onMove?: (target: WorldTarget | null) => void;
+    repeat?: Partial<CursorRepeat>;
+    /** Perpendicular drift weight for `pickTarget`. Default 2. */
+    weight?: number;
+    /** Gamepad source. Default `navigator.getGamepads()` (guarded). */
+    getGamepads?: () => readonly (PadLike | null)[];
+    /** Stick deflection that counts as a d-pad press. Default 0.6. */
+    axisThreshold?: number;
+    /** Listen for the arrow keys and Enter too. Default true. */
+    keys?: boolean;
+    /** Start enabled. Default true. */
+    enabled?: boolean;
+}
+export interface WorldCursor {
+    /** The cursor element on the hud layer (`aria-hidden`; a game's own class may style it). */
+    readonly element: HTMLElement;
+    readonly enabled: boolean;
+    /**
+     * True while the latch holds a control (a direction or A is held, or a direction repeats), as
+     * of the last `update()`. It resets on each pad-owner transition.
+     */
+    readonly latched: boolean;
+    /** Targets mode: the target under the cursor. */
+    readonly target: WorldTarget | null;
+    /** The cursor's world position (`at()` in grid mode, the target's `world` in targets mode). */
+    readonly position: ArrayLike<number> | null;
+    /** Read the pad and move; once per frame. `now` (ms) drives repeat; default `performance.now()`. */
+    update(now?: number): void;
+    /** Targets mode: land on a target (or none) without a press; fires `onMove`. */
+    setTarget(target: WorldTarget | null): void;
+    /** A press from the game's own input (a touch d-pad, a binding), latched like the pad. */
+    press(dir: PadDir | 'activate'): void;
+    enable(): void;
+    disable(): void;
+    dispose(): void;
+}
+/** What the cursor needs from its overlay (`Overlay` fits). */
+export interface CursorHost {
+    readonly layers: {
+        readonly hud: HTMLElement;
+    };
+    readonly stack: {
+        /** Read once at creation (and each frame only by a host without `onPadOwnerChange`). */
+        readonly hasModal: boolean;
+        /** The pad-owner transition (ws/ui-4); a host without it is polled through `hasModal`. */
+        onPadOwnerChange?(fn: (owner: PadOwner) => void): () => void;
+    };
+    /** The overlay's `Anchors`; throws until a camera built it. */
+    anchors(): Anchors;
+}
+/**
+ * The target nearest `from` in direction `dir` (y down): among the targets with a positive
+ * component along the direction, the one with the least `along + weight · perpendicular`, so a
+ * neighbour straight ahead beats a nearer one off to the side. Null when none lies that way.
+ */
+export declare function pickTarget(from: {
+    x: number;
+    y: number;
+}, targets: readonly WorldTarget[], dir: PadDir, weight?: number): WorldTarget | null;
+/** The cursor (see the module comment). Also reachable as `ui.cursor(opts)`. */
+export declare function createCursor(host: CursorHost, opts: CursorOptions): WorldCursor;
+/**
+ * Stylesheet for the cursor element (design px, theme tokens).
+ */
+export declare const CURSOR_CSS: string;
+/** Add `CURSOR_CSS` to `doc` once (the first cursor does it). */
+export declare function ensureCursorStyles(doc?: Document): void;

package/dist/ui/cursor.js

@@ -0,0 +1,261 @@
+import { consumesArrows, h } from './dom.js';
+import { defaultPads, readPad } from './padnav.js';
+import { toFrameUnits } from './text-scale.js';
+const DIRS = ['up', 'down', 'left', 'right'];
+const DX = { up: 0, down: 0, left: -1, right: 1 };
+const DY = { up: -1, down: 1, left: 0, right: 0 };
+const KEY_DIR = {
+    ArrowUp: 'up',
+    ArrowDown: 'down',
+    ArrowLeft: 'left',
+    ArrowRight: 'right',
+};
+/**
+ * The target nearest `from` in direction `dir` (y down): among the targets with a positive
+ * component along the direction, the one with the least `along + weight · perpendicular`, so a
+ * neighbour straight ahead beats a nearer one off to the side. Null when none lies that way.
+ */
+export function pickTarget(from, targets, dir, weight = 2) {
+    const dx = DX[dir];
+    const dy = DY[dir];
+    let best = null;
+    let bestCost = Number.POSITIVE_INFINITY;
+    for (const t of targets) {
+        const vx = t.x - from.x;
+        const vy = t.y - from.y;
+        const along = vx * dx + vy * dy;
+        if (along <= 0)
+            continue;
+        const perp = Math.abs(vx * dy - vy * dx);
+        const cost = along + weight * perp;
+        if (cost < bestCost) {
+            bestCost = cost;
+            best = t;
+        }
+    }
+    return best;
+}
+/** The cursor (see the module comment). Also reachable as `ui.cursor(opts)`. */
+export function createCursor(host, opts) {
+    const layer = host.layers.hud;
+    const doc = layer.ownerDocument;
+    ensureCursorStyles(doc);
+    const element = h('div', { class: 'tc-cursor', 'aria-hidden': 'true', hidden: true });
+    const getPads = opts.getGamepads ?? defaultPads;
+    const threshold = opts.axisThreshold ?? 0.6;
+    const delay = opts.repeat?.delay ?? 400;
+    const interval = opts.repeat?.interval ?? 80;
+    const weight = opts.weight ?? 2;
+    const useKeys = opts.keys ?? true;
+    let enabled = opts.enabled ?? true;
+    let target = null;
+    let handle = null;
+    let disposed = false;
+    // The latch: what was held last frame (pad and keys together) and the one direction repeating.
+    const now = new Set();
+    const held = new Set();
+    const keys = new Set();
+    const pressed = new Set();
+    let repeatDir = null;
+    let repeatAt = 0;
+    // Who owns the pad: a subscribing host tells us on each transition (the latch resets, and
+    // nothing is read while the panel has the pad); a polling host is asked each frame.
+    const subscribed = typeof host.stack.onPadOwnerChange === 'function';
+    let yielded = host.stack.hasModal;
+    const resetLatch = () => {
+        held.clear();
+        pressed.clear();
+        repeatDir = null;
+    };
+    const unwatch = subscribed
+        ? host.stack.onPadOwnerChange((owner) => {
+            yielded = owner === 'stack';
+            resetLatch();
+            // Getting the pad back: what is still held from the panel is not a fresh press here.
+            if (!yielded)
+                readPad(getPads(), threshold, held);
+        })
+        : null;
+    const anchorAt = (world) => {
+        if (!world) {
+            if (handle) {
+                handle.remove();
+                handle = null;
+            }
+            element.hidden = true;
+            return;
+        }
+        if (handle)
+            handle.set(world);
+        else
+            handle = host.anchors().add(element, world);
+        if (element.hidden)
+            element.hidden = false;
+    };
+    const move = (dir) => {
+        if (opts.mode === 'grid') {
+            opts.step?.(DX[dir], DY[dir]);
+            opts.onMove?.(null);
+            return;
+        }
+        const list = opts.targets?.() ?? [];
+        const next = target ? pickTarget(target, list, dir, weight) : (list.find(() => true) ?? null);
+        if (next && next !== target)
+            setTarget(next);
+    };
+    function setTarget(t) {
+        target = t;
+        anchorAt(t ? t.world : null);
+        opts.onMove?.(t);
+    }
+    const select = () => opts.onSelect?.(target);
+    // A key held adds to `keys` (for the repeat); its first keydown also queues a one-shot in
+    // `pressed`, so a tap that starts and ends between two frames still counts as a press.
+    const onKeyDown = (e) => {
+        const dir = KEY_DIR[e.key];
+        const active = doc.activeElement;
+        let control;
+        if (dir) {
+            if (active && active !== doc.body && consumesArrows(active, DX[dir] !== 0))
+                return;
+            control = dir;
+        }
+        else if (e.key === 'Enter') {
+            if (active && active !== doc.body && active !== layer)
+                return;
+            control = 'activate';
+        }
+        else
+            return;
+        keys.add(control);
+        if (!e.repeat)
+            pressed.add(control);
+    };
+    const onKeyUp = (e) => {
+        const dir = KEY_DIR[e.key];
+        if (dir)
+            keys.delete(dir);
+        else if (e.key === 'Enter')
+            keys.delete('activate');
+    };
+    const onBlur = () => keys.clear();
+    if (useKeys) {
+        doc.addEventListener('keydown', onKeyDown);
+        doc.addEventListener('keyup', onKeyUp);
+        doc.defaultView?.addEventListener('blur', onBlur);
+    }
+    const cursor = {
+        element,
+        get enabled() {
+            return enabled;
+        },
+        get latched() {
+            return held.size > 0 || repeatDir !== null;
+        },
+        get target() {
+            return target;
+        },
+        get position() {
+            if (opts.mode === 'targets')
+                return target ? target.world : null;
+            return opts.at?.() ?? null;
+        },
+        update(t = typeof performance !== 'undefined' ? performance.now() : Date.now()) {
+            if (disposed)
+                return;
+            if (!subscribed)
+                yielded = host.stack.hasModal;
+            if (yielded) {
+                // The panel has the pad: nothing is read, and the latch stays reset.
+                pressed.clear();
+                if (opts.mode === 'grid')
+                    anchorAt(opts.at?.() ?? null);
+                return;
+            }
+            readPad(getPads(), threshold, now);
+            for (const k of keys)
+                now.add(k);
+            for (const k of pressed)
+                now.add(k);
+            pressed.clear();
+            if (!enabled) {
+                // Disabled: a press that outlives it is not a fresh one.
+                held.clear();
+                for (const k of now)
+                    held.add(k);
+                repeatDir = null;
+            }
+            else {
+                if (now.has('activate') && !held.has('activate'))
+                    select();
+                let fresh = null;
+                for (const d of DIRS)
+                    if (now.has(d) && !held.has(d))
+                        fresh = d;
+                if (fresh) {
+                    move(fresh);
+                    repeatDir = fresh;
+                    repeatAt = t + delay;
+                }
+                else if (repeatDir && now.has(repeatDir)) {
+                    if (t >= repeatAt) {
+                        move(repeatDir);
+                        repeatAt = t + interval;
+                    }
+                }
+                else
+                    repeatDir = null;
+                held.clear();
+                for (const k of now)
+                    held.add(k);
+            }
+            if (opts.mode === 'grid')
+                anchorAt(opts.at?.() ?? null);
+        },
+        setTarget,
+        press(dir) {
+            pressed.add(dir);
+        },
+        enable() {
+            enabled = true;
+        },
+        disable() {
+            enabled = false;
+            repeatDir = null;
+        },
+        dispose() {
+            disposed = true;
+            unwatch?.();
+            if (useKeys) {
+                doc.removeEventListener('keydown', onKeyDown);
+                doc.removeEventListener('keyup', onKeyUp);
+                doc.defaultView?.removeEventListener('blur', onBlur);
+            }
+            anchorAt(null);
+            element.remove();
+        },
+    };
+    return cursor;
+}
+/**
+ * Stylesheet for the cursor element (design px, theme tokens).
+ */
+export const CURSOR_CSS = toFrameUnits(`
+.tc-cursor { width: 48px; height: 48px; box-sizing: border-box; pointer-events: none;
+  border: 3px solid var(--tc-color-accent); border-radius: var(--tc-radius-s);
+  box-shadow: 0 0 0 2px var(--tc-color-surface), var(--tc-shadow);
+  animation: tc-cursor-pulse 1s ease-in-out infinite alternate; }
+.tc-cursor[hidden] { display: none; }
+@keyframes tc-cursor-pulse { from { opacity: 0.7; } to { opacity: 1; } }
+@media (prefers-reduced-motion: reduce) { .tc-cursor { animation: none; } }
+`);
+const STYLE_ID = 'tc-ui-cursor';
+/** Add `CURSOR_CSS` to `doc` once (the first cursor does it). */
+export function ensureCursorStyles(doc = document) {
+    if (doc.getElementById(STYLE_ID))
+        return;
+    const style = doc.createElement('style');
+    style.id = STYLE_ID;
+    style.textContent = CURSOR_CSS;
+    doc.head.appendChild(style);
+}

package/dist/ui/dom.d.ts

@@ -0,0 +1,30 @@
+/** Tiny DOM helpers. */
+export type Child = Node | string | number | null | undefined | false;
+type Props = {
+    class?: string;
+    /** An object of properties (`--custom` ones included) or a `cssText` string. */
+    style?: Partial<CSSStyleDeclaration> | Record<string, string> | string;
+    dataset?: Record<string, string>;
+    /** Event listeners: `on: { click: fn }`. */
+    on?: {
+        [K in keyof HTMLElementEventMap]?: (e: HTMLElementEventMap[K]) => void;
+    };
+    [attr: string]: unknown;
+};
+/**
+ * Hyperscript: `h('div', { class: 'row', 'aria-label': 'x', on: { click } }, 'text', child)`.
+ * Unknown props become attributes (`true` → empty attribute, `false`/null → omitted). `style`
+ * takes an object (`--custom` properties included) or a `cssText` string.
+ */
+export declare function h<K extends keyof HTMLElementTagNameMap>(tag: K, props?: Props | null, ...children: Child[]): HTMLElementTagNameMap[K];
+export declare function append(el: Element, ...children: Child[]): void;
+/** Keyboard-focusable descendants in DOM order (skips `hidden` and `inert` subtrees). */
+export declare function focusableWithin(root: Element): HTMLElement[];
+/**
+ * Whether a focused `el` uses the arrow keys of an axis itself, so focus navigation (the panel
+ * stack's arrows, `PadNav`'s d-pad) must leave them to it: a text field consumes left/right, a
+ * textarea, select, slider (`type=range` or `role=slider`), radio, number, date or other value
+ * input and a contenteditable consume both axes; buttons and checkboxes consume none.
+ */
+export declare function consumesArrows(el: Element, horizontal: boolean): boolean;
+export {};