@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/ui/padnav.js

@@ -0,0 +1,146 @@
+import { focusableWithin } from './dom.js';
+import { activateLink } from './link.js';
+// Standard mapping: 0 = A/south, 1 = B/east, 12–15 = d-pad up, down, left, right.
+const BTN_ACTIVATE = 0;
+const BTN_BACK = 1;
+const DPAD = { up: 12, down: 13, left: 14, right: 15 };
+const DIRS = ['up', 'down', 'left', 'right'];
+/** `navigator.getGamepads()`, guarded; empty where there is no navigator. */
+export function defaultPads() {
+    try {
+        return typeof navigator !== 'undefined' && navigator.getGamepads ? navigator.getGamepads() : [];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Drives the top modal panel with a gamepad, the way Tab, Enter and Esc drive it from a
+ * keyboard: the d-pad (or left stick) moves focus through the panel's controls, A activates
+ * the focused one, B dismisses the panel. On a focused range slider left/right step its value,
+ * and on a `select` they pick the previous/next option. Call `update()` once per frame. It does
+ * nothing (and reads no pad) while the stack does not own the pad (`stack.padOwner`), so the
+ * game's own input map keeps it; the latch resets on each owner transition.
+ */
+export class PadNav {
+    stack;
+    getGamepads;
+    threshold;
+    prev = new Set();
+    next = new Set();
+    /** True while the stack owns the pad (a modal is open); kept by `onPadOwnerChange`. */
+    owning;
+    unwatch;
+    constructor(stack, opts = {}) {
+        this.stack = stack;
+        this.getGamepads = opts.getGamepads ?? defaultPads;
+        this.threshold = opts.axisThreshold ?? 0.6;
+        this.owning = stack.padOwner === 'stack';
+        // The latch resets on each transition: what is held when the panel opens is not a fresh
+        // press on it (the A that opened a menu never activates its first control), and nothing is
+        // read while the game owns the pad.
+        this.unwatch = stack.onPadOwnerChange((owner) => {
+            this.owning = owner === 'stack';
+            this.prev.clear();
+            if (this.owning)
+                readPad(this.getGamepads(), this.threshold, this.prev);
+        });
+    }
+    /** Stop following the stack; `update()` does nothing after. */
+    dispose() {
+        this.unwatch();
+        this.owning = false;
+    }
+    update() {
+        if (!this.owning)
+            return;
+        const now = readPad(this.getGamepads(), this.threshold, this.next);
+        const before = this.prev;
+        const fresh = (k) => now.has(k) && !before.has(k);
+        this.next = before;
+        this.prev = now;
+        const panel = this.stack.topModalElement;
+        if (!panel)
+            return;
+        if (fresh('back')) {
+            this.stack.dismissTop();
+            return;
+        }
+        const active = panel.ownerDocument.activeElement;
+        const inside = active !== null && active !== panel && panel.contains(active);
+        if (fresh('activate')) {
+            // External links open through the host with block detection (a pad press is no gesture).
+            if (inside)
+                activateLink(active, 'gamepad');
+            return;
+        }
+        for (const dir of ['up', 'down', 'left', 'right']) {
+            if (!fresh(dir))
+                continue;
+            if (inside && (dir === 'left' || dir === 'right') && this.adjust(active, dir === 'right'))
+                return;
+            const items = focusableWithin(panel);
+            if (items.length === 0)
+                return;
+            const i = inside ? items.indexOf(active) : -1;
+            const step = dir === 'down' || dir === 'right' ? 1 : -1;
+            const next = i < 0 ? (step > 0 ? 0 : items.length - 1) : (i + step + items.length) % items.length;
+            items[next]?.focus();
+            return;
+        }
+    }
+    /** Left/right on a value control changes the value instead of moving focus. */
+    adjust(el, up) {
+        if (el instanceof HTMLInputElement && el.type === 'range') {
+            const num = (v, d) => (v === '' || Number.isNaN(Number(v)) ? d : Number(v));
+            const min = num(el.min, 0);
+            const max = num(el.max, 100);
+            const step = el.step === 'any' ? (max - min) / 20 : num(el.step, 1);
+            const v = Math.min(max, Math.max(min, Number(el.value) + (up ? step : -step)));
+            el.value = String(Math.round(v / step) * step);
+        }
+        else if (el instanceof HTMLSelectElement) {
+            const n = el.options.length;
+            if (n === 0)
+                return true;
+            el.selectedIndex = Math.max(0, Math.min(n - 1, el.selectedIndex + (up ? 1 : -1)));
+        }
+        else {
+            return false;
+        }
+        el.dispatchEvent(new Event('input', { bubbles: true }));
+        el.dispatchEvent(new Event('change', { bubbles: true }));
+        return true;
+    }
+}
+/**
+ * The controls held on any of `pads` right now (standard mapping: 0 = A, 1 = B, 12–15 = d-pad;
+ * the left stick past `threshold` counts as the d-pad). `out` is cleared and filled when given,
+ * so a per-frame reader allocates nothing. `PadNav` and the world cursor (`ui/cursor.ts`) latch
+ * on this set: a control is fresh when it is in this frame's set and not the last one's.
+ */
+export function readPad(pads, threshold = 0.6, out = new Set()) {
+    out.clear();
+    for (const p of pads) {
+        if (!p)
+            continue;
+        const b = (i) => p.buttons[i]?.pressed === true;
+        if (b(BTN_ACTIVATE))
+            out.add('activate');
+        if (b(BTN_BACK))
+            out.add('back');
+        for (const dir of DIRS)
+            if (b(DPAD[dir]))
+                out.add(dir);
+        const [x = 0, y = 0] = p.axes ?? [];
+        if (x <= -threshold)
+            out.add('left');
+        if (x >= threshold)
+            out.add('right');
+        if (y <= -threshold)
+            out.add('up');
+        if (y >= threshold)
+            out.add('down');
+    }
+    return out;
+}

package/dist/ui/perf.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Frame-cost readout (ws/perf-overlay): a monitor that keeps the last N frame times and copies
+ * the renderer's counters into one plain object, and a small DOM overlay that shows those
+ * numbers with a sparkline. Quality validation needs to see the cost on screen; demos, the
+ * bench and e2e read the same numbers without the DOM.
+ *
+ * ```ts
+ * const perf = createPerfMonitor();
+ * const hud = createPerfOverlay(perf, { parent: stageEl, corner: 'tr' });
+ * // each frame, after renderer.endFrame():
+ * state.perf = perf.sample(renderer);
+ * hud.update();
+ * ```
+ *
+ * The monitor is pure (no DOM, no GPU): `begin`/`end` bracket the CPU frame when the caller
+ * wants an exact span, otherwise `sample` measures the interval between its own calls. Steady
+ * state allocates nothing: the ring, the stats object and the count and pass records are reused;
+ * a new counter or pass label adds a key once.
+ */
+/** What `PerfMonitor.sample` reads: the renderer's counters, its timing and its scale. */
+export interface PerfSource {
+    /**
+     * `Renderer.stats` (any object; `RenderStats` has no index signature): every own numeric
+     * field is a counter (`drawCalls`, `instances`, `culled`, …).
+     */
+    readonly stats: object;
+    /** `Renderer.timing`: the last GPU sample, by pass when the device has `timestamp-query`. */
+    readonly timing?: {
+        readonly gpuMs: number;
+        readonly passes: Readonly<Record<string, number>>;
+        readonly samples: number;
+    };
+    /** `Renderer.timingEvery`: how often the renderer samples GPU time (0 = never). */
+    timingEvery?: number;
+    /** `Renderer.resolutionScale`: effective scene-target scale vs the output. */
+    readonly resolutionScale?: number;
+}
+export interface PerfFrameStats {
+    /** Last frame time (ms). */
+    last: number;
+    /** Mean over the filled part of the ring (ms). */
+    avg: number;
+    /** 95th percentile over the filled part of the ring (ms). */
+    p95: number;
+    /** Largest sample in the ring (ms). */
+    max: number;
+    /** `1000 / avg`, 0 while nothing has been sampled. */
+    fps: number;
+}
+export interface PerfGpuStats {
+    /** GPU time of the renderer's last sample (ms). */
+    total: number;
+    /** Per pass label, ms; empty when the device has no `timestamp-query`. */
+    passes: Record<string, number>;
+}
+/** The numbers, as one plain JSON-safe object (the monitor reuses it; copy to keep one). */
+export interface PerfSample {
+    frame: PerfFrameStats;
+    /** `null` until the renderer has delivered a GPU time sample. */
+    gpu: PerfGpuStats | null;
+    /**
+     * Every numeric field of `source.stats`, read by key each frame (never a fixed set), plus
+     * `draws` as an alias of `drawCalls` when the source has that counter.
+     */
+    counts: Record<string, number>;
+    resolutionScale: number;
+    /** `performance.memory.usedJSHeapSize` (bytes) where the browser exposes it; else absent. */
+    memory?: number;
+    /** Frames sampled since creation or `reset()`. */
+    samples: number;
+    /** How many slots of `history` hold a frame time (`min(samples, window)`). */
+    filled: number;
+    /** The ring's length (frames). */
+    window: number;
+}
+export interface PerfMonitorOptions {
+    /** Frames kept in `history` and used for `avg`, `p95` and `max`. Default 120. */
+    window?: number;
+    /**
+     * When `sample` finds the source's `timingEvery` at 0, it sets it to this so GPU times arrive.
+     * Default 1 (the renderer keeps one sample in flight at a time anyway). 0 leaves it alone.
+     */
+    gpuEvery?: number;
+    /** Clock (ms). Default `performance.now`. */
+    now?: () => number;
+}
+export interface PerfMonitor extends PerfSample {
+    /** Mark the start of the CPU frame. Optional: without it `sample` times the frame interval. */
+    begin(nowMs?: number): void;
+    /** Mark the end of the CPU frame; the span since `begin` is the next frame time. */
+    end(nowMs?: number): void;
+    /**
+     * Read the source once per frame, after `renderer.endFrame()`. Pushes the frame time into
+     * `history` and refreshes every field. Returns this monitor's `PerfSample` (the same object).
+     */
+    sample(source: PerfSource): PerfSample;
+    /** Frame times (ms), a ring of `window` slots; `filled` says how many hold data. */
+    readonly history: Float32Array;
+    /** Index of the slot the next frame time goes into (the oldest sample while the ring is full). */
+    readonly head: number;
+    /** Forget every sample. */
+    reset(): void;
+}
+export declare function createPerfMonitor(opts?: PerfMonitorOptions): PerfMonitor;
+export type PerfCorner = 'tl' | 'tr' | 'bl' | 'br';
+export interface PerfOverlayOptions {
+    /** Which corner of the parent. Default `'tl'`. */
+    corner?: PerfCorner;
+    /** Draw the frame-time sparkline. Default true. */
+    graph?: boolean;
+    /**
+     * Element to mount into (positioned: the overlay is `position: absolute` inside it). Default:
+     * `document.body`, where the overlay is `position: fixed`.
+     */
+    parent?: HTMLElement;
+    /** Redraw the numbers every N `update()` calls. Default 10. The graph redraws with them. */
+    updateEvery?: number;
+}
+export interface PerfOverlay {
+    /** The overlay root (`.tc-perf`), `aria-hidden`, `pointer-events: none`. */
+    readonly el: HTMLElement;
+    /** Call once a frame after `monitor.sample`; redraws every `updateEvery` calls. */
+    update(): void;
+    show(): void;
+    hide(): void;
+    toggle(): void;
+    readonly visible: boolean;
+    destroy(): void;
+}
+export declare function createPerfOverlay(monitor: PerfMonitor, opts?: PerfOverlayOptions): PerfOverlay;

package/dist/ui/perf.js

@@ -0,0 +1,329 @@
+/**
+ * Frame-cost readout (ws/perf-overlay): a monitor that keeps the last N frame times and copies
+ * the renderer's counters into one plain object, and a small DOM overlay that shows those
+ * numbers with a sparkline. Quality validation needs to see the cost on screen; demos, the
+ * bench and e2e read the same numbers without the DOM.
+ *
+ * ```ts
+ * const perf = createPerfMonitor();
+ * const hud = createPerfOverlay(perf, { parent: stageEl, corner: 'tr' });
+ * // each frame, after renderer.endFrame():
+ * state.perf = perf.sample(renderer);
+ * hud.update();
+ * ```
+ *
+ * The monitor is pure (no DOM, no GPU): `begin`/`end` bracket the CPU frame when the caller
+ * wants an exact span, otherwise `sample` measures the interval between its own calls. Steady
+ * state allocates nothing: the ring, the stats object and the count and pass records are reused;
+ * a new counter or pass label adds a key once.
+ */
+import { h } from './dom.js';
+const DEFAULT_WINDOW = 120;
+/** `performance.memory.usedJSHeapSize` where it exists (Chromium); never throws. */
+function usedHeap() {
+    try {
+        const mem = globalThis.performance?.memory;
+        const used = mem?.usedJSHeapSize;
+        return typeof used === 'number' && Number.isFinite(used) ? used : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function createPerfMonitor(opts = {}) {
+    const window = Math.max(1, Math.floor(opts.window ?? DEFAULT_WINDOW));
+    const gpuEvery = opts.gpuEvery ?? 1;
+    const now = opts.now ?? (() => performance.now());
+    const history = new Float32Array(window);
+    const sorted = new Float32Array(window);
+    let head = 0;
+    let filled = 0;
+    let samples = 0;
+    /** `begin` time, or NaN when `begin` was not called since the last sample. */
+    let beginAt = Number.NaN;
+    /** Frame time from `end`, or NaN when `end` was not called since the last sample. */
+    let ended = Number.NaN;
+    /** The clock at the previous `sample`, for the interval fallback. */
+    let lastSampleAt = Number.NaN;
+    const frame = { last: 0, avg: 0, p95: 0, max: 0, fps: 0 };
+    const gpu = { total: 0, passes: {} };
+    const counts = {};
+    const monitor = {
+        frame,
+        gpu: null,
+        counts,
+        resolutionScale: 1,
+        memory: undefined,
+        samples: 0,
+        filled: 0,
+        window,
+        history,
+        get head() {
+            return head;
+        },
+        begin(nowMs = now()) {
+            beginAt = nowMs;
+        },
+        end(nowMs = now()) {
+            if (Number.isNaN(beginAt))
+                return;
+            ended = Math.max(0, nowMs - beginAt);
+            beginAt = Number.NaN;
+        },
+        sample(source) {
+            const t = now();
+            let ms;
+            if (!Number.isNaN(ended)) {
+                ms = ended;
+                ended = Number.NaN;
+            }
+            else if (!Number.isNaN(beginAt)) {
+                // `begin` without `end`: the span up to this call.
+                ms = Math.max(0, t - beginAt);
+                beginAt = Number.NaN;
+            }
+            else {
+                ms = Number.isNaN(lastSampleAt) ? 0 : Math.max(0, t - lastSampleAt);
+            }
+            lastSampleAt = t;
+            history[head] = ms;
+            head = (head + 1) % window;
+            if (filled < window)
+                filled++;
+            samples++;
+            monitor.samples = samples;
+            monitor.filled = filled;
+            // Frame statistics over the filled part of the ring.
+            let sum = 0;
+            let max = 0;
+            for (let i = 0; i < filled; i++) {
+                const v = history[i];
+                sum += v;
+                if (v > max)
+                    max = v;
+                sorted[i] = v;
+            }
+            // Unfilled slots sort last, so no subarray view is made per frame.
+            for (let i = filled; i < window; i++)
+                sorted[i] = Number.POSITIVE_INFINITY;
+            sorted.sort();
+            frame.last = ms;
+            frame.avg = sum / filled;
+            frame.max = max;
+            frame.p95 = sorted[Math.min(filled - 1, Math.floor(0.95 * filled))];
+            frame.fps = frame.avg > 0 ? 1000 / frame.avg : 0;
+            // Counters, by key.
+            const stats = source.stats;
+            for (const k in stats) {
+                const v = stats[k];
+                if (typeof v === 'number')
+                    counts[k] = v;
+            }
+            if (typeof stats.drawCalls === 'number' && typeof stats.draws !== 'number') {
+                counts.draws = stats.drawCalls;
+            }
+            // GPU time, once the renderer samples it.
+            const timing = source.timing;
+            if (timing && gpuEvery > 0 && source.timingEvery === 0)
+                source.timingEvery = gpuEvery;
+            if (timing && timing.samples > 0) {
+                gpu.total = timing.gpuMs;
+                const passes = timing.passes;
+                for (const k in passes) {
+                    const v = passes[k];
+                    if (typeof v === 'number')
+                        gpu.passes[k] = v;
+                }
+                monitor.gpu = gpu;
+            }
+            else {
+                monitor.gpu = null;
+            }
+            const scale = source.resolutionScale;
+            monitor.resolutionScale = typeof scale === 'number' && Number.isFinite(scale) ? scale : 1;
+            monitor.memory = usedHeap();
+            return monitor;
+        },
+        reset() {
+            history.fill(0);
+            head = 0;
+            filled = 0;
+            samples = 0;
+            beginAt = Number.NaN;
+            ended = Number.NaN;
+            lastSampleAt = Number.NaN;
+            frame.last = frame.avg = frame.p95 = frame.max = frame.fps = 0;
+            gpu.total = 0;
+            for (const k in gpu.passes)
+                delete gpu.passes[k];
+            for (const k in counts)
+                delete counts[k];
+            monitor.gpu = null;
+            monitor.samples = 0;
+            monitor.filled = 0;
+            monitor.resolutionScale = 1;
+            monitor.memory = undefined;
+        },
+    };
+    return monitor;
+}
+const STYLE_ATTR = 'perf';
+/**
+ * Theme tokens with fallbacks (`defaultTheme`'s values), so the overlay reads the same on a
+ * page without a `.tc-overlay` root. Sizes are CSS px: this is a debug readout, not game UI.
+ */
+const CSS = /* css */ `
+.tc-perf { position: absolute; z-index: 1000; margin: 8px; padding: 6px 8px; min-width: 180px;
+  pointer-events: none; user-select: none; -webkit-user-select: none; box-sizing: border-box;
+  font-family: var(--tc-font-mono, ui-monospace, Menlo, Consolas, monospace); font-size: 11px; line-height: 1.35;
+  color: var(--tc-color-text, #ece6d8); background: var(--tc-color-surface, rgba(18, 21, 30, 0.94));
+  border: 1px solid var(--tc-color-border, rgba(224, 180, 90, 0.35)); border-radius: var(--tc-radius-s, 6px);
+  white-space: pre; font-variant-numeric: tabular-nums; }
+.tc-perf[hidden] { display: none; }
+.tc-perf[data-fixed] { position: fixed; }
+.tc-perf[data-corner^="t"] { top: 0; }
+.tc-perf[data-corner^="b"] { bottom: 0; }
+.tc-perf[data-corner$="l"] { left: 0; }
+.tc-perf[data-corner$="r"] { right: 0; }
+.tc-perf-head { color: var(--tc-color-accent, #e0b45a); }
+.tc-perf-dim { color: var(--tc-color-text-muted, #a7a091); }
+.tc-perf-graph { display: block; width: 100%; height: 36px; margin-top: 4px; }
+`;
+const GRAPH_W = 240;
+const GRAPH_H = 36;
+/** The graph's floor: two 60 Hz frames, so a steady 16.7 ms sits at half height. */
+const GRAPH_MIN_MS = 1000 / 30;
+function fmt(ms) {
+    return ms >= 100 ? ms.toFixed(0) : ms.toFixed(ms >= 10 ? 1 : 2);
+}
+function fmtBytes(b) {
+    if (b >= 1024 * 1024 * 1024)
+        return `${(b / (1024 * 1024 * 1024)).toFixed(2)} GB`;
+    if (b >= 1024 * 1024)
+        return `${(b / (1024 * 1024)).toFixed(1)} MB`;
+    return `${(b / 1024).toFixed(0)} KB`;
+}
+export function createPerfOverlay(monitor, opts = {}) {
+    const parent = opts.parent ?? document.body;
+    const doc = parent.ownerDocument;
+    const updateEvery = Math.max(1, Math.floor(opts.updateEvery ?? 10));
+    const graph = opts.graph ?? true;
+    if (!doc.querySelector(`style[data-tc="${STYLE_ATTR}"]`)) {
+        doc.head.append(h('style', { 'data-tc': STYLE_ATTR }, CSS));
+    }
+    const head = h('div', { class: 'tc-perf-head' });
+    const body = h('div', { class: 'tc-perf-body' });
+    const canvas = graph
+        ? h('canvas', { class: 'tc-perf-graph', width: GRAPH_W, height: GRAPH_H })
+        : null;
+    const el = h('div', {
+        class: 'tc-perf',
+        'aria-hidden': 'true',
+        dataset: { corner: opts.corner ?? 'tl' },
+        'data-fixed': !opts.parent,
+    }, head, body, canvas);
+    parent.append(el);
+    let ctx = null;
+    try {
+        ctx = canvas?.getContext('2d') ?? null;
+    }
+    catch {
+        ctx = null;
+    }
+    let tick = 0;
+    let destroyed = false;
+    const drawGraph = () => {
+        if (!ctx || !canvas)
+            return;
+        const w = canvas.width;
+        const hgt = canvas.height;
+        ctx.clearRect(0, 0, w, hgt);
+        const n = monitor.filled;
+        const win = monitor.window;
+        if (n === 0)
+            return;
+        let max = GRAPH_MIN_MS;
+        const hist = monitor.history;
+        for (let i = 0; i < n; i++)
+            if (hist[i] > max)
+                max = hist[i];
+        // 16.7 ms guide.
+        const guide = hgt - (hgt * (1000 / 60)) / max;
+        ctx.fillStyle = 'rgba(255, 255, 255, 0.18)';
+        ctx.fillRect(0, Math.round(guide), w, 1);
+        // Oldest to newest, left to right; a full ring starts at `head`.
+        const start = n < win ? 0 : monitor.head;
+        const barW = w / win;
+        ctx.fillStyle = 'rgba(224, 180, 90, 0.85)';
+        for (let i = 0; i < n; i++) {
+            const v = hist[(start + i) % win];
+            const bh = Math.max(1, (hgt * v) / max);
+            ctx.fillRect(i * barW, hgt - bh, Math.max(1, barW - 0.5), bh);
+        }
+    };
+    const render = () => {
+        const f = monitor.frame;
+        head.textContent = `${fmt(f.avg)} ms  ${f.fps.toFixed(0)} fps`;
+        let text = `cpu  last ${fmt(f.last)}  p95 ${fmt(f.p95)}  max ${fmt(f.max)}`;
+        const g = monitor.gpu;
+        if (g) {
+            text += `\ngpu  ${fmt(g.total)} ms`;
+            for (const k in g.passes) {
+                const v = g.passes[k];
+                if (v > 0.005)
+                    text += `\n  ${k.padEnd(10)} ${fmt(v)}`;
+            }
+        }
+        else {
+            text += '\ngpu  –';
+        }
+        const c = monitor.counts;
+        const parts = [];
+        for (const k in c) {
+            if (k === 'draws' && 'drawCalls' in c)
+                continue;
+            parts.push(`${k} ${c[k]}`);
+        }
+        if (parts.length > 0)
+            text += `\n${parts.join('  ')}`;
+        text += `\nscale ${monitor.resolutionScale.toFixed(2)}`;
+        if (monitor.memory !== undefined)
+            text += `  heap ${fmtBytes(monitor.memory)}`;
+        body.textContent = text;
+        drawGraph();
+    };
+    render();
+    const show = () => {
+        el.hidden = false;
+        tick = updateEvery - 1;
+    };
+    const hide = () => {
+        el.hidden = true;
+    };
+    return {
+        el,
+        update() {
+            if (destroyed || el.hidden)
+                return;
+            if (++tick < updateEvery)
+                return;
+            tick = 0;
+            render();
+        },
+        show,
+        hide,
+        toggle() {
+            if (el.hidden)
+                show();
+            else
+                hide();
+        },
+        get visible() {
+            return !el.hidden && el.isConnected;
+        },
+        destroy() {
+            destroyed = true;
+            el.remove();
+        },
+    };
+}

package/dist/ui/rotate-card.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The "turn it sideways" card for a landscape game on a phone held upright (interim API: Phase 2's
+ * portrait layout regions retire it, D-041).
+ *
+ * The card covers the whole viewport, outside the scaled overlay (upright, the overlay is a thin
+ * strip), and goes the moment the phone turns. Nothing is paused: the game underneath just waits
+ * for input. All words are the game's, passed as options.
+ *
+ * It shows when the viewport is portrait and the device is a phone in hand: a handheld by
+ * `deviceTraits()`, or a finger on a phone-scale screen by the device mode. A narrow desktop
+ * window never gets it.
+ */
+import type { DeviceMode } from '../platform/device-mode.js';
+/** The card's look. Each is a CSS value; omitted ones use neutral engine defaults. */
+export interface RotateCardColors {
+    /** Card background (any `background` value, gradients included). */
+    background?: string;
+    text?: string;
+    /** Heading, phone outline and the note's tag. */
+    accent?: string;
+    /** The phone outline's glow. */
+    glow?: string;
+    /** The note line. */
+    muted?: string;
+    font?: string;
+}
+export interface RotateCardOptions {
+    /** Heading, e.g. "Turn your phone sideways". Also the dialog's accessible name by default. */
+    title: string;
+    /** Body paragraphs under the heading. */
+    lines?: readonly string[];
+    /** An optional last line in italics, with a short bold tag before it (a speaker, say). */
+    note?: {
+        tag?: string;
+        text: string;
+    };
+    /** Accessible name. Default: `title`. */
+    ariaLabel?: string;
+    /** The device mode; a finger on a phone-scale screen counts as a phone in hand. */
+    device?: Pick<DeviceMode, 'phone' | 'touch' | 'onChange'>;
+    colors?: RotateCardColors;
+    /** Document to mount into. Default: the global `document`. */
+    doc?: Document;
+}
+export interface RotateCard {
+    /** The card (`role=dialog`), appended to `<body>`. */
+    readonly element: HTMLElement;
+    /** True while the card shows. */
+    readonly visible: boolean;
+    /** Re-check orientation. It also runs on resize, orientation change and device-mode change. */
+    update(): void;
+    destroy(): void;
+}
+export declare function createRotateCard(opts: RotateCardOptions): RotateCard;