@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/ui/dom.js

@@ -0,0 +1,92 @@
+/** Tiny DOM helpers. */
+/**
+ * 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 function h(tag, props = null, ...children) {
+    const el = document.createElement(tag);
+    if (props) {
+        for (const [k, v] of Object.entries(props)) {
+            if (v === undefined || v === null || v === false)
+                continue;
+            if (k === 'class')
+                el.className = String(v);
+            else if (k === 'style') {
+                if (typeof v === 'string') {
+                    el.style.cssText = v;
+                    continue;
+                }
+                for (const [sk, sv] of Object.entries(v)) {
+                    if (sk.startsWith('--'))
+                        el.style.setProperty(sk, sv);
+                    else
+                        el.style[sk] = sv;
+                }
+            }
+            else if (k === 'dataset')
+                Object.assign(el.dataset, v);
+            else if (k === 'on') {
+                for (const [ev, fn] of Object.entries(v))
+                    el.addEventListener(ev, fn);
+            }
+            else
+                el.setAttribute(k, v === true ? '' : String(v));
+        }
+    }
+    append(el, ...children);
+    return el;
+}
+export function append(el, ...children) {
+    for (const c of children) {
+        if (c === null || c === undefined || c === false)
+            continue;
+        el.append(typeof c === 'number' ? String(c) : c);
+    }
+}
+const FOCUSABLE = [
+    'a[href]',
+    'button:not([disabled])',
+    'input:not([disabled]):not([type="hidden"])',
+    'select:not([disabled])',
+    'textarea:not([disabled])',
+    '[tabindex]:not([tabindex="-1"])',
+    '[contenteditable="true"]',
+].join(',');
+/** Keyboard-focusable descendants in DOM order (skips `hidden` and `inert` subtrees). */
+export function focusableWithin(root) {
+    return [...root.querySelectorAll(FOCUSABLE)].filter((el) => !el.closest('[hidden], [inert]') && el.getAttribute('aria-hidden') !== 'true');
+}
+/** Input types whose own arrow handling is only horizontal (the caret). */
+const TEXT_INPUTS = new Set(['text', 'search', 'url', 'email', 'password', 'tel']);
+/** Input types that never use the arrow keys. */
+const ARROWLESS_INPUTS = new Set([
+    'button',
+    'submit',
+    'reset',
+    'checkbox',
+    'image',
+    'file',
+    'color',
+]);
+/**
+ * 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 function consumesArrows(el, horizontal) {
+    if (el.getAttribute('role') === 'slider' || el.isContentEditable)
+        return true;
+    const tag = el.tagName;
+    if (tag === 'TEXTAREA' || tag === 'SELECT')
+        return true;
+    if (tag !== 'INPUT')
+        return false;
+    const type = el.type;
+    if (ARROWLESS_INPUTS.has(type))
+        return false;
+    if (TEXT_INPUTS.has(type))
+        return horizontal;
+    return true;
+}

package/dist/ui/floats.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Floating text (ws/ui-5): damage, healing and pickup numbers that rise from a world point and
+ * fade. `createFloats(host, camera)` returns a `Floats` whose labels are a fixed pool of DOM nodes
+ * on the hud layer (`max`, default 64), projected each `update(dt)` through the overlay's
+ * `Anchors` (`anchors.project`, the path `ui.anchors` places its elements on) and hidden when
+ * the point is behind the camera or off screen.
+ *
+ * - Each spawn takes its own `color`, `size` (a factor on the theme's `--tc-font-size-m`),
+ *   `rise` (design px over the life), `life` (seconds) and `crit` (a scale pop on arrival).
+ * - `stack` (on by default) fans out spawns landing on one point while earlier ones are still
+ *   young: alternately right and left, each a step higher, so a burst of hits stays readable.
+ * - Past `max` the oldest label is recycled. `update` writes `transform` (Typed OM where it
+ *   exists) and `opacity` from a table of precomputed strings, so a steady frame allocates
+ *   nothing; a spawn writes the text (and the colour or size only when they change).
+ * - `prefers-reduced-motion` keeps the labels still: no rise, no pop, only the fade.
+ */
+import { type AnchorCamera, type Anchors } from './anchor.js';
+/** What floats need from their overlay (`Overlay` fits). */
+export interface FloatsHost {
+    readonly layers: {
+        readonly hud: HTMLElement;
+    };
+    /** The overlay's `Anchors`; the first call needs a camera. */
+    anchors(camera?: () => AnchorCamera): Anchors;
+}
+export interface FloatsOptions {
+    /** Pool size: the most labels in flight at once. Default 64. */
+    max?: number;
+    /** Default life, seconds. Default 1. */
+    life?: number;
+    /** Default rise over the life, design px. Default 56. */
+    rise?: number;
+    /** World distance under which two spawns count as one point for `stack`. Default 0.35. */
+    stackRadius?: number;
+    /** Horizontal and vertical fan step for `stack`, design px. Default 30 and 18. */
+    stackStep?: readonly [number, number];
+    /** An extra class on every label (a game's own style). */
+    style?: string;
+    /** Keep labels still (no rise, no pop). Default: `prefers-reduced-motion`. */
+    reducedMotion?: boolean;
+}
+export interface FloatTextOptions {
+    /** CSS colour. Default the theme text colour (`--tc-color-text`). */
+    color?: string;
+    /** Font size factor on `--tc-font-size-m`. Default 1 (1.3 for a crit). */
+    size?: number;
+    /** Rise over the life, design px. Default `FloatsOptions.rise`. */
+    rise?: number;
+    /** Life, seconds. Default `FloatsOptions.life`. */
+    life?: number;
+    /** Pop in scale on arrival and draw a touch larger. Default false. */
+    crit?: boolean;
+    /** Fan out from younger labels at the same point. Default true. */
+    stack?: boolean;
+}
+export interface Floats {
+    /** Labels in flight. */
+    readonly live: number;
+    /** Nodes made so far (never more than `max`). */
+    readonly pooled: number;
+    readonly max: number;
+    /** Start a label at the world point (copied). Past `max` the oldest is recycled. */
+    spawn(text: string, world: ArrayLike<number>, opts?: FloatTextOptions): void;
+    /** Age, place and retire the labels; call once per update with the step in seconds. */
+    update(dt: number): void;
+    /** Retire every label now. */
+    clear(): void;
+    /** `clear()` and take the nodes out of the layer. */
+    dispose(): void;
+}
+/** The fade: full for the first 60 % of the life, then down to 0. @internal */
+export declare function floatOpacity(t: number): number;
+/** The crit pop: 0.6 → 1.5 over the first 8 % of the life, back to 1.15 by 20 %. @internal */
+export declare function critScale(t: number): number;
+/**
+ * The floats (see the module comment). `camera` is handed to `host.anchors(camera)` once, so the
+ * overlay's anchors project through it; without one the anchors must already exist or the
+ * overlay have a default (`OverlayOptions.camera`, which `createGame` sets).
+ */
+export declare function createFloats(host: FloatsHost, camera?: () => AnchorCamera, opts?: FloatsOptions): Floats;
+/**
+ * Stylesheet for the labels (design px, theme tokens).
+ */
+export declare const FLOATS_CSS: string;
+/** Add `FLOATS_CSS` to `doc` once (the first `createFloats` does it). */
+export declare function ensureFloatsStyles(doc?: Document): void;

package/dist/ui/floats.js

@@ -0,0 +1,260 @@
+/**
+ * Floating text (ws/ui-5): damage, healing and pickup numbers that rise from a world point and
+ * fade. `createFloats(host, camera)` returns a `Floats` whose labels are a fixed pool of DOM nodes
+ * on the hud layer (`max`, default 64), projected each `update(dt)` through the overlay's
+ * `Anchors` (`anchors.project`, the path `ui.anchors` places its elements on) and hidden when
+ * the point is behind the camera or off screen.
+ *
+ * - Each spawn takes its own `color`, `size` (a factor on the theme's `--tc-font-size-m`),
+ *   `rise` (design px over the life), `life` (seconds) and `crit` (a scale pop on arrival).
+ * - `stack` (on by default) fans out spawns landing on one point while earlier ones are still
+ *   young: alternately right and left, each a step higher, so a burst of hits stays readable.
+ * - Past `max` the oldest label is recycled. `update` writes `transform` (Typed OM where it
+ *   exists) and `opacity` from a table of precomputed strings, so a steady frame allocates
+ *   nothing; a spawn writes the text (and the colour or size only when they change).
+ * - `prefers-reduced-motion` keeps the labels still: no rise, no pop, only the fade.
+ */
+import { typedTransform } from './anchor.js';
+import { h } from './dom.js';
+import { prefersReducedMotionIn } from './styles.js';
+import { toFrameUnits } from './text-scale.js';
+/** Opacity steps, precomputed so a fade writes no new string. */
+const STEPS = 32;
+const OPACITY = [];
+for (let i = 0; i <= STEPS; i++)
+    OPACITY.push(String(i / STEPS));
+/** The fade: full for the first 60 % of the life, then down to 0. @internal */
+export function floatOpacity(t) {
+    return t <= 0.6 ? 1 : Math.max(0, 1 - (t - 0.6) / 0.4);
+}
+/** The crit pop: 0.6 → 1.5 over the first 8 % of the life, back to 1.15 by 20 %. @internal */
+export function critScale(t) {
+    if (t < 0.08)
+        return 0.6 + (1.5 - 0.6) * (t / 0.08);
+    if (t < 0.2)
+        return 1.5 + (1.15 - 1.5) * ((t - 0.08) / 0.12);
+    return 1.15;
+}
+const pt = { x: 0, y: 0 };
+/**
+ * The floats (see the module comment). `camera` is handed to `host.anchors(camera)` once, so the
+ * overlay's anchors project through it; without one the anchors must already exist or the
+ * overlay have a default (`OverlayOptions.camera`, which `createGame` sets).
+ */
+export function createFloats(host, camera, opts = {}) {
+    const layer = host.layers.hud;
+    const doc = layer.ownerDocument;
+    ensureFloatsStyles(doc);
+    if (camera)
+        host.anchors(camera);
+    const max = Math.max(1, Math.floor(opts.max ?? 64));
+    const life = Math.max(1e-3, opts.life ?? 1);
+    const rise = opts.rise ?? 56;
+    const r2 = (opts.stackRadius ?? 0.35) ** 2;
+    const [stepX, stepY] = opts.stackStep ?? [30, 18];
+    const still = opts.reducedMotion ?? prefersReducedMotionIn(doc.defaultView ?? undefined);
+    const nodes = [];
+    const free = [];
+    let live = 0;
+    let seq = 0;
+    let disposed = false;
+    const make = () => {
+        const el = h('span', {
+            class: opts.style ? `tc-floats ${opts.style}` : 'tc-floats',
+            'aria-hidden': 'true',
+            hidden: true,
+        });
+        layer.append(el);
+        const n = {
+            el,
+            world: new Float32Array(3),
+            live: false,
+            seq: 0,
+            age: 0,
+            life,
+            rise,
+            crit: false,
+            ox: 0,
+            oy: 0,
+            color: '',
+            size: 1,
+            x: Number.NaN,
+            y: Number.NaN,
+            s: Number.NaN,
+            q: -1,
+            typed: typedTransform(el, 0.5, 1),
+        };
+        nodes.push(n);
+        return n;
+    };
+    const retire = (n) => {
+        if (!n.live)
+            return;
+        n.live = false;
+        live--;
+        n.el.hidden = true;
+        n.x = Number.NaN;
+        n.y = Number.NaN;
+        free.push(n);
+    };
+    const take = () => {
+        const f = free.pop();
+        if (f)
+            return f;
+        if (nodes.length < max)
+            return make();
+        // Full: recycle the oldest.
+        let oldest = nodes[0];
+        for (const n of nodes)
+            if (n.seq < oldest.seq)
+                oldest = n;
+        retire(oldest);
+        free.pop();
+        return oldest;
+    };
+    /** Younger labels within `stackRadius` of the point: the fan index of a new one. */
+    const stackIndex = (x, y, z) => {
+        let k = 0;
+        for (const n of nodes) {
+            if (!n.live || n.age > n.life * 0.5)
+                continue;
+            const dx = n.world[0] - x;
+            const dy = n.world[1] - y;
+            const dz = n.world[2] - z;
+            if (dx * dx + dy * dy + dz * dz <= r2)
+                k++;
+        }
+        return k;
+    };
+    const floats = {
+        get live() {
+            return live;
+        },
+        get pooled() {
+            return nodes.length;
+        },
+        max,
+        spawn(text, world, o = {}) {
+            if (disposed)
+                return;
+            const x = world[0] ?? 0;
+            const y = world[1] ?? 0;
+            const z = world[2] ?? 0;
+            const k = o.stack === false ? 0 : stackIndex(x, y, z);
+            const n = take();
+            n.live = true;
+            live++;
+            n.seq = ++seq;
+            n.age = 0;
+            n.life = Math.max(1e-3, o.life ?? life);
+            n.rise = still ? 0 : (o.rise ?? rise);
+            n.crit = o.crit === true;
+            n.ox = k === 0 ? 0 : (k % 2 === 1 ? 1 : -1) * Math.ceil(k / 2) * stepX;
+            n.oy = -k * stepY;
+            n.world[0] = x;
+            n.world[1] = y;
+            n.world[2] = z;
+            n.x = Number.NaN;
+            n.s = Number.NaN;
+            n.q = -1;
+            if (n.el.textContent !== text)
+                n.el.textContent = text;
+            const color = o.color ?? '';
+            if (color !== n.color) {
+                n.color = color;
+                n.el.style.color = color;
+            }
+            const size = o.size ?? (n.crit ? 1.3 : 1);
+            if (size !== n.size) {
+                n.size = size;
+                n.el.style.fontSize = size === 1 ? '' : `calc(var(--tc-font-size-m) * ${size})`;
+            }
+            n.el.toggleAttribute('data-crit', n.crit);
+            // Placed (and shown) by the next update.
+        },
+        update(dt) {
+            if (disposed || live === 0)
+                return;
+            const anchors = host.anchors();
+            const f = anchors.frame;
+            const unit = f.width > 0 ? f.rect.width / f.width : 1;
+            for (const n of nodes) {
+                if (!n.live)
+                    continue;
+                n.age += dt;
+                if (n.age >= n.life) {
+                    retire(n);
+                    continue;
+                }
+                const inside = anchors.project(n.world[0], n.world[1], n.world[2], pt);
+                if (!inside) {
+                    if (!n.el.hidden)
+                        n.el.hidden = true;
+                    continue;
+                }
+                const t = n.age / n.life;
+                const x = pt.x + n.ox * unit;
+                const y = pt.y + (n.oy - n.rise * t) * unit;
+                const s = n.crit && !still ? critScale(t) : 1;
+                const q = Math.round(floatOpacity(t) * STEPS);
+                if (n.el.hidden)
+                    n.el.hidden = false;
+                if (q !== n.q) {
+                    n.q = q;
+                    n.el.style.opacity = OPACITY[q];
+                }
+                if (x === n.x && y === n.y && s === n.s)
+                    continue;
+                n.x = x;
+                n.y = y;
+                n.s = s;
+                const ty = n.typed;
+                if (ty) {
+                    ty.x.value = x;
+                    ty.y.value = y;
+                    ty.s.value = s;
+                    n.el.attributeStyleMap.set('transform', ty.value);
+                }
+                else {
+                    n.el.style.transform = `translate3d(${x}px, ${y}px, 0) scale(${s}) translate(-50%, -100%)`;
+                }
+            }
+        },
+        clear() {
+            for (const n of nodes)
+                retire(n);
+        },
+        dispose() {
+            if (disposed)
+                return;
+            floats.clear();
+            disposed = true;
+            for (const n of nodes)
+                n.el.remove();
+            nodes.length = 0;
+            free.length = 0;
+        },
+    };
+    return floats;
+}
+/**
+ * Stylesheet for the labels (design px, theme tokens).
+ */
+export const FLOATS_CSS = toFrameUnits(`
+.tc-floats { position: absolute; left: 0; top: 0; transform-origin: 0 0; will-change: transform, opacity;
+  pointer-events: none; white-space: nowrap; font-family: var(--tc-font-display); font-size: var(--tc-font-size-m);
+  font-weight: 800; line-height: 1; color: var(--tc-color-text); font-variant-numeric: tabular-nums;
+  text-shadow: 0 2px 3px rgba(0, 0, 0, 0.85), 0 0 6px rgba(0, 0, 0, 0.5); }
+.tc-floats[hidden] { display: none; }
+.tc-floats[data-crit] { letter-spacing: 0.02em; text-shadow: 0 2px 3px rgba(0, 0, 0, 0.9), 0 0 10px var(--tc-color-warn); }
+`);
+const STYLE_ID = 'tc-ui-floats';
+/** Add `FLOATS_CSS` to `doc` once (the first `createFloats` does it). */
+export function ensureFloatsStyles(doc = document) {
+    if (doc.getElementById(STYLE_ID))
+        return;
+    const style = doc.createElement('style');
+    style.id = STYLE_ID;
+    style.textContent = FLOATS_CSS;
+    doc.head.appendChild(style);
+}

package/dist/ui/hud.d.ts

@@ -0,0 +1,198 @@
+import type { FormSize, Layout, RegionName, WidgetOptions } from './layout.js';
+import type { PanelStack } from './stack.js';
+/** What the HUD factories need from the overlay. */
+export interface HudHost {
+    readonly layers: {
+        hud: HTMLElement;
+    };
+    readonly layout: Layout;
+    readonly stack: PanelStack;
+}
+/** `n` theme px (see the module comment). */
+export declare function themePx(n: number): string;
+/**
+ * The HUD stylesheet, under `.tc-overlay` and in `--tc-*` tokens only. Injected once per document
+ * by the first HUD widget (`ensureHudStyles`), next to the overlay's base sheet.
+ */
+export declare const HUD_CSS: string;
+/** Add the HUD stylesheet to `doc` once. */
+export declare function ensureHudStyles(doc: Document): void;
+export type ReticleStyle = 'dot' | 'cross' | 'circle';
+export interface ReticleOptions {
+    style?: ReticleStyle;
+    /** Overall size, theme px. Default 24. */
+    size?: number;
+    /** Gap between the arms of a `cross`, theme px. Default 6. */
+    gap?: number;
+    /** CSS colour. Default `var(--tc-color-text)`. */
+    color?: string;
+}
+export interface Reticle {
+    readonly el: HTMLElement;
+    /** The reticle's own state; it also hides while a modal is open (`data-modal`). */
+    readonly visible: boolean;
+    readonly style: ReticleStyle;
+    show(): void;
+    hide(): void;
+    /** A short scale-and-tint flash (`tc-reticle-pulse`), e.g. on a hit. */
+    pulse(): void;
+    setStyle(style: ReticleStyle): void;
+    remove(): void;
+}
+/** A reticle centred on the frame, on the `hud` layer; hidden while a modal panel is open. */
+export declare function createReticle(host: HudHost, opts?: ReticleOptions): Reticle;
+export type MeterTone = 'accent' | 'info' | 'success' | 'warn' | 'danger';
+export interface MeterOptions {
+    /** Visible label; also the accessible name. */
+    label?: string;
+    /** Default 1. */
+    max?: number;
+    /** Initial value. Default `max`. */
+    value?: number;
+    /** Layout region. Default `bottom`. */
+    region?: RegionName;
+    /**
+     * Placement per form factor, as `layout.add` takes it (ws/ui-11); overrides `region`. The
+     * layout moves the live meter when the form factor changes: `{ default: 'bottom',
+     * 'phone-landscape': 'right' }`. A region name alone is `{ default: name }`.
+     */
+    place?: RegionName | WidgetOptions['place'];
+    order?: number;
+    /** Fill colour token. Default `accent`. */
+    tone?: MeterTone;
+    /** Width, theme px. Default 240. */
+    width?: number;
+    /** Show the value as text beside the label (`v => \`${v}/${max}\``). Default none. */
+    format?: (value: number, max: number) => string;
+    /** `'bar'` (default) or `'orb'`, a round fill gauge (`ui/orb.ts`, ws/ui-5). */
+    shape?: MeterShape;
+    /**
+     * A lagging damage band behind the fill: it holds where the value was, then drains to it.
+     * `true` for the defaults (`delay` 400 ms, `duration` 600 ms). Off under reduced motion.
+     */
+    trail?: boolean | MeterTrailOptions;
+    /**
+     * What the readout shows: the value (`format`, else the rounded value), a whole percent or
+     * nothing. Default `'value'` on an orb; a bar shows `format` only, as before.
+     */
+    readout?: MeterReadout;
+    /** A CSS colour for the fill, over the `tone` token. */
+    color?: string;
+    /**
+     * An orb's diameter, theme px. Default 128. A number, or one per form factor (ws/ui-10,
+     * `FormSizes`: `{ phone: 56, default: 96 }`), applied before the layout measures the orb.
+     */
+    size?: FormSize;
+    /** Turn the trail and the fill's easing off. Default: `prefers-reduced-motion`. */
+    reducedMotion?: boolean;
+    /** The clock the trail is read on, ms. Default `performance.now`. */
+    now?: () => number;
+}
+/** A meter's shape: a horizontal bar or a round orb. */
+export type MeterShape = 'bar' | 'orb';
+/** What a meter's readout shows. */
+export type MeterReadout = 'value' | 'percent' | 'none';
+/** The damage trail's timing, ms. */
+export interface MeterTrailOptions {
+    /** How long the band holds before it drains. Default 400. */
+    delay?: number;
+    /** How long it takes to drain. Default 600. */
+    duration?: number;
+}
+export interface Meter {
+    readonly el: HTMLElement;
+    readonly shape: MeterShape;
+    readonly value: number;
+    readonly max: number;
+    /** Where the damage trail is now (same units as `value`); `value` without a trail. */
+    readonly trail: number;
+    /**
+     * An orb's `size` as last given (a number or `FormSizes`, theme px; 128 when none was), ws/ui-11.
+     * `formSize(meter.size, layout.formFactor)` is the diameter now. `undefined` on a bar.
+     */
+    readonly size: FormSize | undefined;
+    /** Where the layout has it now: a region, `free` or `hidden` (ws/ui-11). */
+    readonly region: RegionName | 'free' | 'hidden';
+    /** Clamped to `[0, max]`; a new `max` re-clamps. */
+    set(value: number, max?: number): void;
+    setTone(tone: MeterTone): void;
+    /** A CSS colour for the fill over the tone, or null for the tone's token. */
+    setColor(color: string | null): void;
+    /**
+     * Change an orb's `size` (a number or one per form factor, theme px) live (ws/ui-10); the
+     * layout re-lays out once when the diameter in the current form factor changes. A bar ignores it.
+     */
+    setSize(size: FormSize): void;
+    /**
+     * Move the live meter (ws/ui-11): a region, or a placement per form factor as
+     * `MeterOptions.place` takes it. The same element moves, so its value, trail, tone, colour and
+     * size stay; a running trail carries on from where it was.
+     */
+    setPlace(place: RegionName | WidgetOptions['place']): void;
+    remove(): void;
+}
+/** A labelled bar with `role="meter"`, in a layout region. */
+export declare function createMeter(host: HudHost, opts?: MeterOptions): Meter;
+export interface SlotsOptions {
+    count: number;
+    /** Layout region. Default `bottom`. */
+    region?: RegionName;
+    order?: number;
+    /** Key-hint badge per slot (`['1', '2', …]`). */
+    hints?: string[];
+    /** Accessible name of the strip. Default `Slots`. */
+    label?: string;
+    /** Initially selected index. Default 0. */
+    selected?: number;
+    /** Slot size, theme px. Default 72. */
+    size?: number;
+}
+export interface Slots {
+    readonly el: HTMLElement;
+    readonly count: number;
+    readonly selected: number;
+    /** Wraps: `select(count)` is slot 0 and `select(-1)` the last, so a wheel can cycle. */
+    select(i: number): void;
+    /** Replace a slot's content (text or an element); an empty string clears it. */
+    setContent(i: number, content: string | HTMLElement): void;
+    setHint(i: number, hint: string): void;
+    remove(): void;
+}
+/** A strip of equal slots with key-hint badges and one selected highlight. */
+export declare function createSlots(host: HudHost, opts: SlotsOptions): Slots;
+export interface HeadingOptions {
+    /** Layout region. Default `top`. */
+    region?: RegionName;
+    order?: number;
+    /** Visible width, theme px. Default 480. */
+    width?: number;
+    /** Degrees of heading shown across the width. Default 90. */
+    span?: number;
+    /** Degrees between ticks. Default 15. */
+    tickEvery?: number;
+    /** The four cardinal labels, clockwise from yaw 0. Default `['N', 'E', 'S', 'W']`. */
+    labels?: [string, string, string, string];
+}
+export interface Heading {
+    readonly el: HTMLElement;
+    /** The strip that slides. */
+    readonly strip: HTMLElement;
+    /** Last yaw set, radians. */
+    readonly yaw: number;
+    /** Where the strip sits, theme px (`translate3d(offset, 0, 0)`). */
+    readonly offset: number;
+    /**
+     * Yaw in radians, clockwise from the first label (0 is `N`, π/2 is `E`). Any value: it wraps.
+     */
+    setYaw(radians: number): void;
+    remove(): void;
+}
+/** Degrees in `[0, 360)`. */
+export declare function wrapDegrees(deg: number): number;
+/** The strip offset (theme px) for a yaw, given the visible width and span. */
+export declare function headingOffset(yawRadians: number, width: number, span: number): number;
+/**
+ * A sliding cardinal strip: the four labels and ticks at every `tickEvery` degrees, drawn over
+ * two turns (−180° to 540°) so the strip never jumps at north. The centre mark shows the yaw.
+ */
+export declare function createHeading(host: HudHost, opts?: HeadingOptions): Heading;