@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/ui/link.d.ts

@@ -0,0 +1,64 @@
+import type { Host } from '../host/types.js';
+import { type CopyResult, type LinkActivation, type OpenResult } from '../platform/links.js';
+import { type Child } from './dom.js';
+export interface ExternalLinkLabels {
+    /** Copy button text, e.g. "Copy link". */
+    copy: string;
+    /** Shown on the button for a moment after a copy, e.g. "Copied!". */
+    copied: string;
+    /** Read by screen readers after a copy, e.g. "Link copied." */
+    copiedAnnounce: string;
+    /** Copy button's accessible name; should start with `copy` (WCAG 2.5.3). Default: `copy`. */
+    copyAriaLabel?: string;
+    /** Fallback heading when copying failed, e.g. "Your browser blocked copying. Copy the link:". */
+    copyBlocked: string;
+    /** Fallback heading when the new tab was blocked, e.g. "Your browser blocked the new tab. Copy the link:". */
+    popupBlocked: string;
+    /** The fallback's close button, e.g. "Close". */
+    close: string;
+}
+export interface ExternalLinkOptions {
+    url: string;
+    /** Opens and copies the link. Default: `defaultHost()`. */
+    host?: Pick<Host, 'openExternal' | 'copyText'>;
+    /** The link's visible content (text, icon). */
+    content: Child | Child[];
+    labels: ExternalLinkLabels;
+    /** Extra class on the wrapper. */
+    className?: string;
+    /** Class on the anchor. */
+    linkClass?: string;
+    /**
+     * `data-action` names for tests and analytics-free debugging: the anchor gets `action`, the
+     * parts get `<action>-copy`, `<action>-fallback`, `<action>-close`.
+     */
+    action?: string;
+    /** Where the fallback popover opens relative to the row. Default `below`. */
+    place?: 'above' | 'below';
+    /** How the popover lines up with the row. Default `center`. */
+    align?: 'start' | 'center' | 'end';
+    /** How long "Copied" shows, ms. Default 2200. */
+    copiedMs?: number;
+}
+export interface ExternalLink {
+    /** Wrapper to insert into the page. */
+    readonly element: HTMLElement;
+    readonly anchor: HTMLAnchorElement;
+    readonly copyButton: HTMLButtonElement;
+    /** Opens the link for `activation`; on `blocked` the fallback appears. */
+    open(activation: LinkActivation): OpenResult;
+    /** Copies the URL (the Copy button calls this); on `manual` the fallback appears. */
+    copy(): Promise<CopyResult>;
+    showFallback(reason: 'copy' | 'popup'): void;
+    hideFallback(): void;
+}
+/**
+ * Builds the widget, or returns null when the URL is not a safe https link (hide the control).
+ */
+export declare function externalLink(opts: ExternalLinkOptions): ExternalLink | null;
+/**
+ * Activates `el` for a non-native input (a gamepad press): an external-link anchor opens through
+ * its host with block detection (`window.open` on the web); anything else is clicked. Returns the open result for an
+ * external link, else null.
+ */
+export declare function activateLink(el: HTMLElement, activation: LinkActivation): OpenResult | null;

package/dist/ui/link.js

@@ -0,0 +1,155 @@
+/**
+ * External link widget (D-036): a real new-tab link, a "Copy link" button beside it with
+ * "Copied" feedback, and a fallback popover with the URL in a selected read-only field for when
+ * the browser blocks the copy or the new tab. Opening and copying go through the host
+ * (`Host.openExternal`, `Host.copyText`; engine/host).
+ *
+ * - Mouse and Enter use the anchor natively (a user gesture, so popup blockers allow it).
+ * - A gamepad press is not a gesture: route it through `activateLink(el, 'gamepad')`
+ *   (PadNav does this for modals), which opens through the host with block detection (the web
+ *   host uses `window.open`) and shows the fallback if blocked.
+ * - Nothing opens or copies without the player acting. No network calls.
+ * Labels come from the caller; the look comes from theme tokens (override the `tc-link-*` classes).
+ */
+import { defaultHost } from '../host/default.js';
+import { safeExternalUrl, } from '../platform/links.js';
+import { h } from './dom.js';
+const SVG = 'http://www.w3.org/2000/svg';
+const registry = new WeakMap();
+let ids = 0;
+function copyIcon() {
+    const svg = document.createElementNS(SVG, 'svg');
+    svg.setAttribute('viewBox', '0 0 24 24');
+    svg.setAttribute('aria-hidden', 'true');
+    svg.setAttribute('class', 'tc-link-copy-icon');
+    svg.setAttribute('fill', 'none');
+    svg.setAttribute('stroke', 'currentColor');
+    svg.setAttribute('stroke-width', '2');
+    svg.setAttribute('stroke-linejoin', 'round');
+    for (const d of ['M8 8h11v13H8z', 'M5 16H4V3h11v1']) {
+        const p = document.createElementNS(SVG, 'path');
+        p.setAttribute('d', d);
+        svg.append(p);
+    }
+    return svg;
+}
+/**
+ * Builds the widget, or returns null when the URL is not a safe https link (hide the control).
+ */
+export function externalLink(opts) {
+    const url = safeExternalUrl(opts.url);
+    if (!url)
+        return null;
+    const { labels } = opts;
+    const host = opts.host ?? defaultHost();
+    const act = (part) => (opts.action ? { action: `${opts.action}${part}` } : undefined);
+    const anchor = h('a', {
+        class: ['tc-link-anchor', opts.linkClass ?? ''].join(' ').trim(),
+        href: url,
+        target: '_blank',
+        rel: 'noopener noreferrer',
+        dataset: act(''),
+    }, ...(Array.isArray(opts.content) ? opts.content : [opts.content]));
+    const copyLabel = h('span', null, labels.copy);
+    const copyButton = h('button', {
+        type: 'button',
+        class: 'tc-link-copy',
+        'aria-label': labels.copyAriaLabel ?? labels.copy,
+        dataset: act('-copy'),
+    }, copyIcon(), copyLabel);
+    const fieldId = `tc-link-field-${++ids}`;
+    const message = h('label', { class: 'tc-link-message', for: fieldId }, '');
+    const field = h('input', {
+        id: fieldId,
+        class: 'tc-link-field',
+        type: 'text',
+        readonly: true,
+        value: url,
+        // Wide enough to show the whole URL; the popover grows to fit (text scale included).
+        size: url.length + 1,
+        spellcheck: 'false',
+        autocomplete: 'off',
+        on: { focus: () => field.select(), click: () => field.select() },
+    });
+    const close = h('button', { type: 'button', class: 'tc-link-close', dataset: act('-close') }, labels.close);
+    const fallback = h('div', {
+        class: 'tc-link-fallback',
+        dataset: { ...act('-fallback'), place: opts.place ?? 'below', align: opts.align ?? 'center' },
+    }, h('div', { class: 'tc-link-fallback-head' }, message, close), field);
+    fallback.hidden = true;
+    const live = h('span', { class: 'tc-sr-only', 'aria-live': 'polite' }, '');
+    const element = h('div', { class: ['tc-link', opts.className ?? ''].join(' ').trim() }, h('div', { class: 'tc-link-row' }, anchor, copyButton), fallback, live);
+    const announce = (text) => {
+        // Cleared first, so the same message twice is still read.
+        live.textContent = '';
+        setTimeout(() => {
+            live.textContent = text;
+        }, 60);
+    };
+    let resetTimer;
+    const widget = {
+        element,
+        anchor,
+        copyButton,
+        open(activation) {
+            const r = host.openExternal(url, { activation });
+            if (r === 'blocked')
+                widget.showFallback('popup');
+            return r;
+        },
+        async copy() {
+            const r = await host.copyText(url);
+            if (r === 'manual') {
+                widget.showFallback('copy');
+                return r;
+            }
+            copyLabel.textContent = labels.copied;
+            copyButton.dataset.copied = '';
+            announce(labels.copiedAnnounce);
+            clearTimeout(resetTimer);
+            resetTimer = setTimeout(() => {
+                copyLabel.textContent = labels.copy;
+                delete copyButton.dataset.copied;
+            }, opts.copiedMs ?? 2200);
+            return r;
+        },
+        showFallback(reason) {
+            const text = reason === 'popup' ? labels.popupBlocked : labels.copyBlocked;
+            message.textContent = text;
+            field.value = url;
+            fallback.hidden = false;
+            field.focus({ preventScroll: true });
+            field.select();
+            announce(text);
+        },
+        hideFallback() {
+            const had = !fallback.hidden;
+            fallback.hidden = true;
+            if (had)
+                copyButton.focus({ preventScroll: true });
+        },
+    };
+    copyButton.addEventListener('click', () => void widget.copy());
+    close.addEventListener('click', () => widget.hideFallback());
+    fallback.addEventListener('keydown', (e) => {
+        if (e.key !== 'Escape')
+            return;
+        e.preventDefault();
+        e.stopPropagation();
+        widget.hideFallback();
+    });
+    registry.set(anchor, widget);
+    return widget;
+}
+/**
+ * Activates `el` for a non-native input (a gamepad press): an external-link anchor opens through
+ * its host with block detection (`window.open` on the web); anything else is clicked. Returns the open result for an
+ * external link, else null.
+ */
+export function activateLink(el, activation) {
+    const w = registry.get(el);
+    if (w)
+        return w.open(activation);
+    el.click();
+    return null;
+}

package/dist/ui/loading.d.ts

@@ -0,0 +1,40 @@
+import type { PanelStack } from './stack.js';
+export interface LoadingOptions {
+    title?: string;
+    /** One tip, or several to rotate through every `tipInterval` ms. */
+    tip?: string | readonly string[];
+    /** ms between tips when `tip` is a list. Default 4000. */
+    tipInterval?: number;
+    /** Initial progress, 0..1. Default 0. */
+    progress?: number;
+    /** Accessible name of the bar. Default `Loading`. */
+    label?: string;
+    /** Skip the fade (also skipped under `prefers-reduced-motion`). */
+    reducedMotion?: boolean;
+}
+export interface LoadingScreen {
+    readonly element: HTMLElement;
+    /** 0..1 as last set. */
+    readonly progress: number;
+    /** True from creation until `done()` resolves. */
+    readonly visible: boolean;
+    /** Progress 0..1; `label` replaces the text beside the bar. */
+    set(progress: number, label?: string): void;
+    /** Show this tip now (and stop rotating). */
+    tip(text: string): void;
+    /** Fade out, close the panel, release the root; resolves after the transition. Idempotent. */
+    done(): Promise<void>;
+}
+/** What the loading screen needs from its overlay (`Overlay` fits). */
+export interface LoadingHost {
+    readonly root: HTMLElement;
+    readonly stack: PanelStack;
+}
+/** Show a loading screen; see the module comment. Also reachable as `ui.loading(opts)`. */
+export declare function createLoading(host: LoadingHost, opts?: LoadingOptions): LoadingScreen;
+/**
+ * Stylesheet for the loading screen (design px, theme tokens).
+ */
+export declare const LOADING_CSS: string;
+/** Add `LOADING_CSS` to `doc` once (the first loading screen does it). */
+export declare function ensureLoadingStyles(doc?: Document): void;

package/dist/ui/loading.js

@@ -0,0 +1,157 @@
+/**
+ * Loading screen (ws/ui-3): a full-frame, non-dismissible panel on the `panels` layer with a
+ * title, a progress `bar` and a tip line that can rotate through strings. While it is shown the
+ * overlay root carries `aria-busy="true"`, the lower layers are inert (a modal panel), the game's
+ * `Input` is blocked through `stack.hasModal`, and keys other than Tab are swallowed at the
+ * document's capture phase. `done()` fades it out and resolves after the transition.
+ */
+import { h } from './dom.js';
+import { prefersReducedMotionIn } from './styles.js';
+import { toFrameUnits } from './text-scale.js';
+import { bar } from './widgets-2.js';
+/** Fallback for when no `transitionend` arrives (display: none, a hidden tab). */
+const FADE_FALLBACK_MS = 400;
+/** Show a loading screen; see the module comment. Also reachable as `ui.loading(opts)`. */
+export function createLoading(host, opts = {}) {
+    const doc = host.root.ownerDocument;
+    ensureLoadingStyles(doc);
+    const label = opts.label ?? 'Loading';
+    const progressBar = bar(label, opts.progress ?? 0, {
+        format: (v) => `${Math.round(v * 100)}%`,
+    });
+    const tipEl = h('p', { class: 'tc-loading-tip', role: 'status', 'aria-live': 'polite' });
+    const titleEl = opts.title ? h('h2', { class: 'tc-loading-title' }, opts.title) : null;
+    const body = h('div', { class: 'tc-loading-body' }, titleEl, progressBar.element, tipEl);
+    let progress = opts.progress ?? 0;
+    let visible = true;
+    let closing = null;
+    let tipTimer = null;
+    const tips = typeof opts.tip === 'string' ? [opts.tip] : [...(opts.tip ?? [])];
+    let tipIndex = 0;
+    const showTip = (text) => {
+        if (tipEl.textContent !== text)
+            tipEl.textContent = text;
+    };
+    if (tips.length > 0) {
+        showTip(tips[0]);
+        if (tips.length > 1) {
+            tipTimer = setInterval(() => {
+                tipIndex = (tipIndex + 1) % tips.length;
+                showTip(tips[tipIndex]);
+            }, opts.tipInterval ?? 4000);
+        }
+    }
+    const panel = host.stack.push({
+        content: body,
+        modal: true,
+        dismissible: false,
+        closeOnBackdrop: false,
+        chrome: 'none',
+        className: 'tc-loading',
+        label: opts.title ?? label,
+        arrowNav: 'none',
+    });
+    const element = panel.element;
+    host.root.setAttribute('aria-busy', 'true');
+    // Swallow keys at the document: the panel traps focus, this keeps Enter/Space/arrows from
+    // reaching a game's own key handlers behind it. Tab still moves focus for screen readers.
+    const onKey = (e) => {
+        if (e.key === 'Tab')
+            return;
+        e.preventDefault();
+        e.stopPropagation();
+    };
+    doc.addEventListener('keydown', onKey, true);
+    doc.addEventListener('keyup', onKey, true);
+    const release = () => {
+        if (tipTimer) {
+            clearInterval(tipTimer);
+            tipTimer = null;
+        }
+        doc.removeEventListener('keydown', onKey, true);
+        doc.removeEventListener('keyup', onKey, true);
+        host.root.removeAttribute('aria-busy');
+        visible = false;
+        if (panel.open)
+            panel.close('programmatic');
+    };
+    const screen = {
+        element,
+        get progress() {
+            return progress;
+        },
+        get visible() {
+            return visible;
+        },
+        set(p, text) {
+            progress = Math.min(1, Math.max(0, p));
+            progressBar.set(progress);
+            if (text !== undefined) {
+                const value = element.querySelector('.tc-ui-bar-value');
+                if (value && value.textContent !== text)
+                    value.textContent = text;
+            }
+        },
+        tip(text) {
+            if (tipTimer) {
+                clearInterval(tipTimer);
+                tipTimer = null;
+            }
+            showTip(text);
+        },
+        done() {
+            if (closing)
+                return closing;
+            const skipFade = opts.reducedMotion || prefersReducedMotionIn();
+            closing = new Promise((resolve) => {
+                if (skipFade) {
+                    release();
+                    resolve();
+                    return;
+                }
+                let settled = false;
+                const finish = () => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    element.removeEventListener('transitionend', onEnd);
+                    clearTimeout(fallback);
+                    release();
+                    resolve();
+                };
+                const onEnd = (e) => {
+                    if (e.target === element)
+                        finish();
+                };
+                element.addEventListener('transitionend', onEnd);
+                const fallback = setTimeout(finish, FADE_FALLBACK_MS);
+                element.dataset.done = '';
+            });
+            return closing;
+        },
+    };
+    return screen;
+}
+/**
+ * Stylesheet for the loading screen (design px, theme tokens).
+ */
+export const LOADING_CSS = toFrameUnits(`
+.tc-panel.tc-loading { position: absolute; inset: 0; display: grid; place-items: center; max-width: none; max-height: none;
+  width: auto; height: auto; margin: 0; padding: 0; background: var(--tc-color-surface); border-radius: 0;
+  transition: opacity var(--tc-duration-normal) var(--tc-easing); }
+.tc-panel.tc-loading[data-done] { opacity: 0; pointer-events: none; }
+.tc-loading-body { display: grid; gap: var(--tc-space-4); width: min(720px, 80%); color: var(--tc-color-text); font-family: var(--tc-font-ui); }
+.tc-loading-title { margin: 0; font-size: var(--tc-font-size-l); font-weight: 700; text-align: center; }
+.tc-loading-tip { margin: 0; min-height: 1.4em; font-size: var(--tc-font-size-s); color: var(--tc-color-text-muted); text-align: center; }
+@media (prefers-reduced-motion: reduce) { .tc-panel.tc-loading { transition: none; } }
+`);
+const STYLE_ID = 'tc-ui-loading';
+/** Add `LOADING_CSS` to `doc` once (the first loading screen does it). */
+export function ensureLoadingStyles(doc = document) {
+    if (doc.getElementById(STYLE_ID))
+        return;
+    const style = doc.createElement('style');
+    style.id = STYLE_ID;
+    style.textContent = LOADING_CSS;
+    doc.head.appendChild(style);
+}

package/dist/ui/loupe.d.ts

@@ -0,0 +1,74 @@
+export interface LoupeOptions {
+    /** Diameter in CSS px (default 120). */
+    size?: number;
+    /** Magnification (default 2.5). */
+    zoom?: number;
+    /** Where the loupe element goes (default document.body). It is `position: fixed`. */
+    parent?: HTMLElement;
+    /** Extra class names for styling. */
+    className?: string;
+}
+export interface LoupeView {
+    /** Client point the loupe is centred on (what it magnifies). */
+    focus: {
+        x: number;
+        y: number;
+    };
+    /** Client point where the loupe itself is drawn (its centre). */
+    at: {
+        x: number;
+        y: number;
+    };
+    /** Optional ring: a client point and radius (CSS px, before zoom). */
+    ring?: {
+        x: number;
+        y: number;
+        r: number;
+        color?: string;
+    } | null;
+    /**
+     * Optional leader: a thin line from the loupe's rim to a client point and radius (the real
+     * spot the loupe magnifies, outside it), so the eye joins the two. Hidden when the spot is
+     * under or touching the loupe.
+     */
+    leader?: {
+        x: number;
+        y: number;
+        r: number;
+    } | null;
+}
+/**
+ * The leader's segment (client px) from the rim of a loupe `size` across at `at` to `r` short
+ * of the spot, or `null` when there is no room for one.
+ */
+export declare function loupeLeader(at: {
+    x: number;
+    y: number;
+}, size: number, spot: {
+    x: number;
+    y: number;
+    r: number;
+}): {
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+} | null;
+export declare class Loupe {
+    private readonly source;
+    readonly el: HTMLElement;
+    readonly size: number;
+    readonly zoom: number;
+    private readonly cv;
+    /** The leader line (`tc-loupe-leader`), a sibling of the loupe so it draws outside it. */
+    readonly leaderEl: HTMLElement;
+    private readonly g;
+    private on;
+    private pending;
+    constructor(source: HTMLCanvasElement, opts?: LoupeOptions);
+    get visible(): boolean;
+    show(v: LoupeView): void;
+    private draw;
+    hide(): void;
+    destroy(): void;
+}

package/dist/ui/loupe.js

@@ -0,0 +1,164 @@
+/**
+ * Loupe: a round magnifier over a canvas, for fingers on small screens. It copies a patch of
+ * the source canvas (WebGPU or 2D: whatever the page last showed) into its own small 2D canvas
+ * each time `show` is called, and can ring one spot in the patch. Everything is in client (CSS)
+ * px. It never takes input (`pointer-events: none`), and fades out on `hide`.
+ *
+ * Styling is the caller's: the root element has class `tc-loupe` (plus `className`), and is
+ * `data-on` while shown.
+ */
+import { h } from './dom.js';
+/**
+ * The leader's segment (client px) from the rim of a loupe `size` across at `at` to `r` short
+ * of the spot, or `null` when there is no room for one.
+ */
+export function loupeLeader(at, size, spot) {
+    const dx = spot.x - at.x;
+    const dy = spot.y - at.y;
+    const d = Math.hypot(dx, dy);
+    const from = size / 2 + 1;
+    const to = d - spot.r - 2;
+    if (to - from < 6)
+        return null;
+    const ux = dx / d;
+    const uy = dy / d;
+    return { x0: at.x + ux * from, y0: at.y + uy * from, x1: at.x + ux * to, y1: at.y + uy * to };
+}
+export class Loupe {
+    source;
+    el;
+    size;
+    zoom;
+    cv;
+    /** The leader line (`tc-loupe-leader`), a sibling of the loupe so it draws outside it. */
+    leaderEl;
+    g;
+    on = false;
+    pending = null;
+    constructor(source, opts = {}) {
+        this.source = source;
+        this.size = opts.size ?? 120;
+        this.zoom = opts.zoom ?? 2.5;
+        const doc = source.ownerDocument;
+        this.cv = h('canvas', { 'aria-hidden': 'true' });
+        this.el = h('div', {
+            class: `tc-loupe${opts.className ? ` ${opts.className}` : ''}`,
+            'aria-hidden': 'true',
+            style: {
+                position: 'fixed',
+                left: '0px',
+                top: '0px',
+                width: `${this.size}px`,
+                height: `${this.size}px`,
+                pointerEvents: 'none',
+                opacity: '0',
+            },
+        }, this.cv);
+        Object.assign(this.cv.style, { width: '100%', height: '100%', display: 'block' });
+        this.g = this.cv.getContext('2d');
+        this.leaderEl = h('div', {
+            class: `tc-loupe-leader${opts.className ? ` ${opts.className}-leader` : ''}`,
+            'aria-hidden': 'true',
+            hidden: true,
+            style: {
+                position: 'fixed',
+                left: '0px',
+                top: '0px',
+                height: '2px',
+                transformOrigin: '0 50%',
+                pointerEvents: 'none',
+                background: '#ffd56a',
+                boxShadow: '0 0 0 1px #000a',
+            },
+        });
+        (opts.parent ?? doc.body).append(this.leaderEl, this.el);
+    }
+    get visible() {
+        return this.on;
+    }
+    show(v) {
+        const win = this.source.ownerDocument.defaultView ?? window;
+        const dpr = Math.min(3, win.devicePixelRatio || 1);
+        const px = Math.round(this.size * dpr);
+        if (this.cv.width !== px) {
+            this.cv.width = px;
+            this.cv.height = px;
+        }
+        const d = this.size;
+        this.el.style.transform = `translate(${Math.round(v.at.x - d / 2)}px, ${Math.round(v.at.y - d / 2)}px)`;
+        const seg = v.leader ? loupeLeader(v.at, d, v.leader) : null;
+        this.leaderEl.hidden = !seg;
+        if (seg) {
+            const len = Math.hypot(seg.x1 - seg.x0, seg.y1 - seg.y0);
+            const deg = (Math.atan2(seg.y1 - seg.y0, seg.x1 - seg.x0) * 180) / Math.PI;
+            this.leaderEl.style.width = `${len.toFixed(1)}px`;
+            this.leaderEl.style.transform = `translate(${seg.x0.toFixed(1)}px, ${(seg.y0 - 1).toFixed(1)}px) rotate(${deg.toFixed(2)}deg)`;
+        }
+        if (!this.on) {
+            this.on = true;
+            this.el.dataset.on = '';
+            this.el.style.opacity = '1';
+        }
+        // Copy after the caller's frame is drawn: a WebGPU canvas is only readable between its
+        // render and the browser presenting it, so a copy made earlier in the frame comes out blank.
+        // A microtask runs once the current task (update then render) is over.
+        const queued = this.pending !== null;
+        this.pending = { view: v, px, dpr };
+        if (!queued)
+            queueMicrotask(() => this.draw());
+    }
+    draw() {
+        const p = this.pending;
+        this.pending = null;
+        const g = this.g;
+        if (!p || !g || !this.on)
+            return;
+        const { view: v, px, dpr } = p;
+        const d = this.size;
+        const r = this.source.getBoundingClientRect();
+        if (r.width <= 0 || r.height <= 0)
+            return;
+        const kx = this.source.width / r.width;
+        const ky = this.source.height / r.height;
+        const span = d / this.zoom; // client px shown across the loupe
+        g.setTransform(1, 0, 0, 1, 0, 0);
+        g.clearRect(0, 0, px, px);
+        g.fillStyle = '#000';
+        g.fillRect(0, 0, px, px);
+        try {
+            g.drawImage(this.source, (v.focus.x - span / 2 - r.left) * kx, (v.focus.y - span / 2 - r.top) * ky, span * kx, span * ky, 0, 0, px, px);
+        }
+        catch {
+            // A source that can't be read yet: the loupe stays dark for this frame.
+        }
+        const ring = v.ring;
+        if (ring) {
+            const s = px / span; // device px per client px inside the loupe
+            const cx = (ring.x - (v.focus.x - span / 2)) * s;
+            const cy = (ring.y - (v.focus.y - span / 2)) * s;
+            g.lineWidth = 3 * dpr;
+            g.strokeStyle = '#000a';
+            g.beginPath();
+            g.arc(cx, cy, ring.r * s + 2 * dpr, 0, Math.PI * 2);
+            g.stroke();
+            g.lineWidth = 2.5 * dpr;
+            g.strokeStyle = ring.color ?? '#ffd56a';
+            g.beginPath();
+            g.arc(cx, cy, ring.r * s, 0, Math.PI * 2);
+            g.stroke();
+        }
+    }
+    hide() {
+        this.pending = null;
+        if (!this.on)
+            return;
+        this.on = false;
+        this.leaderEl.hidden = true;
+        delete this.el.dataset.on;
+        this.el.style.opacity = '0';
+    }
+    destroy() {
+        this.el.remove();
+        this.leaderEl.remove();
+    }
+}

package/dist/ui/menu-nav.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Up/down and gamepad confirm for a non-modal menu (a title screen, an end card), so every
+ * control on it, links included, is reachable without a mouse. Modal panels use `PadNav`
+ * instead.
+ *
+ * Arrow keys reach this while a button or link has focus if the game lists them as Input
+ * `buttonKeys`, but Enter and Space do not: the focused control handles those natively. So
+ * `confirm` is only taken here when it came from a gamepad.
+ *
+ * A pad press is not a user gesture, so a new-tab link is opened with `window.open` and checked:
+ * if the browser blocks it, the link's copy field appears instead (`activateLink`).
+ */
+import type { InputDevice } from '../input/types.js';
+/** What a tick of menu input did: moved focus, clicked the focused control, or nothing. */
+export type MenuNavResult = 'moved' | 'clicked' | null;
+/** The slice of `Input` menu navigation reads. */
+export interface MenuNavInput<A extends string> {
+    pressed(action: A): boolean;
+    readonly lastDevice: InputDevice;
+}
+/** The game's action names for up, down and confirm. Default `up`, `down`, `confirm`. */
+export interface MenuNavActions<A extends string> {
+    up: A;
+    down: A;
+    confirm: A;
+}
+/**
+ * One tick of menu navigation over the focusable controls in `root`. Call it from the scene's
+ * update while no modal is open. Up and down move focus (wrapping; from outside the menu, down
+ * goes to the first control and up to the last). Confirm from a gamepad activates the focused
+ * control.
+ */
+export declare function menuNav<A extends string>(input: MenuNavInput<A>, root: HTMLElement, actions?: MenuNavActions<A>): MenuNavResult;