@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/ui/widgets-3.js

@@ -0,0 +1,212 @@
+/**
+ * The third set of HUD widgets (ws/ui-4): a radial progress ring and a compass strip. Both are
+ * placed in a layout region (`region`, like the meter and the heading strip) and write the DOM
+ * only when a value changed. Sizes are design px (`themePx`); colours and spacing come from the
+ * theme tokens. `WIDGETS3_CSS` is injected on first use (`ensureWidgets3Styles`).
+ */
+import { h } from './dom.js';
+import { themePx, wrapDegrees } from './hud.js';
+const clamp01 = (v) => Math.min(1, Math.max(0, v));
+/**
+ * A radial progress ring: a conic gradient fills clockwise from the top by `value`, masked to a
+ * ring of `thickness`, with a label in the middle. `role="progressbar"` with `aria-valuenow`.
+ */
+export function createRing(host, opts = {}) {
+    ensureWidgets3Styles(host.layers.hud.ownerDocument);
+    const radius = opts.radius ?? 48;
+    const thickness = opts.thickness ?? 8;
+    const labelEl = h('span', { class: 'tc-ring-label' }, opts.label ?? '');
+    const fill = h('div', { class: 'tc-ring-fill', 'aria-hidden': 'true' });
+    const el = h('div', {
+        class: 'tc-ring',
+        role: 'progressbar',
+        'aria-label': opts.label,
+        'aria-valuemin': '0',
+        'aria-valuemax': '1',
+        style: {
+            '--tc-ring-size': themePx(radius * 2),
+            '--tc-ring-thickness': themePx(thickness),
+            ...(opts.color ? { '--tc-ring-color': opts.color } : {}),
+        },
+    }, fill, labelEl);
+    let value = Number.NaN;
+    const set = (v) => {
+        const next = clamp01(v);
+        if (next === value)
+            return;
+        value = next;
+        el.setAttribute('aria-valuenow', String(next));
+        fill.style.setProperty('--tc-ring-value', String(next));
+    };
+    set(opts.value ?? 0);
+    const handle = host.layout.add(el, {
+        place: { default: opts.region ?? 'bottom' },
+        order: opts.order,
+    });
+    return {
+        el,
+        get value() {
+            return value;
+        },
+        set,
+        setLabel(label) {
+            if (labelEl.textContent === label)
+                return;
+            labelEl.textContent = label;
+            el.setAttribute('aria-label', label);
+        },
+        remove() {
+            handle.remove();
+            el.remove();
+        },
+    };
+}
+/** The signed difference `bearing − heading`, wrapped to −180..180. */
+export function bearingOffset(bearingDeg, headingDeg) {
+    const d = wrapDegrees(bearingDeg - headingDeg);
+    return d > 180 ? d - 360 : d;
+}
+/**
+ * A compass strip: the cardinal ticks scroll under a centre mark as the heading turns, and each
+ * marker sits at its bearing's distance from the heading (`width / (2 × fov)` px per degree),
+ * hidden once it leaves the strip. `role="img"` labelled with the heading.
+ */
+export function createCompass(host, opts = {}) {
+    ensureWidgets3Styles(host.layers.hud.ownerDocument);
+    const width = opts.width ?? 480;
+    const fov = opts.fov ?? 180;
+    const labels = opts.labels ?? ['N', 'E', 'S', 'W'];
+    const ppd = width / (2 * fov);
+    const half = width / 2;
+    const strip = h('div', { class: 'tc-compass-strip', 'aria-hidden': 'true' });
+    // Ticks from −180 to 540 so the strip is covered at any heading (its offset is in 0..360).
+    for (let deg = -180; deg <= 540; deg += 15) {
+        const major = deg % 90 === 0;
+        strip.append(h('span', {
+            class: 'tc-compass-tick',
+            'data-major': major,
+            style: { left: themePx(deg * ppd) },
+        }));
+        if (major) {
+            strip.append(h('span', { class: 'tc-compass-label', style: { left: themePx(deg * ppd) } }, labels[wrapDegrees(deg) / 90] ?? ''));
+        }
+    }
+    const markerLayer = h('div', { class: 'tc-compass-markers', 'aria-hidden': 'true' });
+    const el = h('div', {
+        class: 'tc-compass',
+        role: 'img',
+        'aria-label': 'Compass',
+        style: { '--tc-compass-width': themePx(width) },
+    }, strip, markerLayer, h('span', { class: 'tc-compass-mark', 'aria-hidden': 'true' }));
+    const nodes = [];
+    let heading = Number.NaN;
+    let stripOffset = Number.NaN;
+    const placeMarker = (n) => {
+        const off = bearingOffset(n.marker.bearingDeg, heading) * ppd;
+        const shown = Math.abs(off) <= half;
+        if (shown !== n.shown) {
+            n.shown = shown;
+            n.el.hidden = !shown;
+        }
+        if (!shown || off === n.offset)
+            return;
+        n.offset = off;
+        n.el.style.transform = `translate3d(${themePx(off)}, 0, 0) translateX(-50%)`;
+    };
+    const setHeading = (deg) => {
+        const next = wrapDegrees(deg);
+        if (next === heading)
+            return;
+        heading = next;
+        // The strip's 0° tick sits `heading` degrees left of the centre.
+        const off = half - next * ppd;
+        if (off !== stripOffset) {
+            stripOffset = off;
+            strip.style.transform = `translate3d(${themePx(off)}, 0, 0)`;
+        }
+        el.setAttribute('aria-label', `Compass ${Math.round(next)}°`);
+        for (const n of nodes)
+            placeMarker(n);
+    };
+    const setMarkers = (markers) => {
+        for (let i = 0; i < markers.length; i++) {
+            const m = markers[i];
+            let n = nodes[i];
+            if (!n) {
+                const node = h('span', { class: 'tc-compass-marker', hidden: true });
+                markerLayer.append(node);
+                n = { el: node, marker: m, offset: Number.NaN, shown: false };
+                nodes.push(n);
+            }
+            n.marker = m;
+            n.el.textContent = m.icon ?? m.name.charAt(0);
+            n.el.dataset.name = m.name;
+            n.offset = Number.NaN;
+            placeMarker(n);
+        }
+        while (nodes.length > markers.length)
+            nodes.pop().el.remove();
+    };
+    setHeading(opts.headingDeg ?? 0);
+    setMarkers(opts.markers ?? []);
+    const handle = host.layout.add(el, {
+        place: { default: opts.region ?? 'top' },
+        order: opts.order,
+    });
+    return {
+        el,
+        get heading() {
+            return heading;
+        },
+        setHeading,
+        setMarkers,
+        offsetOf(name) {
+            const n = nodes.find((x) => x.marker.name === name);
+            return n ? bearingOffset(n.marker.bearingDeg, heading) * ppd : null;
+        },
+        remove() {
+            handle.remove();
+            el.remove();
+        },
+    };
+}
+// ------------------------------------------------------------------ styles
+/**
+ * Stylesheet for these widgets (theme tokens).
+ */
+export const WIDGETS3_CSS = `
+.tc-overlay .tc-ring { position: relative; display: grid; place-items: center; width: var(--tc-ring-size); height: var(--tc-ring-size);
+  font-family: var(--tc-font-ui); font-size: var(--tc-font-size-s); color: var(--tc-color-text); }
+.tc-overlay .tc-ring-fill { position: absolute; inset: 0; border-radius: 50%; --tc-ring-value: 0;
+  background: conic-gradient(var(--tc-ring-color, var(--tc-color-accent)) calc(var(--tc-ring-value) * 360deg), var(--tc-color-border) 0);
+  -webkit-mask: radial-gradient(farthest-side, transparent calc(100% - var(--tc-ring-thickness) - 0.5px), #000 calc(100% - var(--tc-ring-thickness) + 0.5px));
+  mask: radial-gradient(farthest-side, transparent calc(100% - var(--tc-ring-thickness) - 0.5px), #000 calc(100% - var(--tc-ring-thickness) + 0.5px)); }
+.tc-overlay .tc-ring-label { position: relative; font-weight: 600; text-shadow: 0 1px 2px rgba(0, 0, 0, 0.7); }
+
+.tc-overlay .tc-compass { position: relative; width: var(--tc-compass-width, ${themePx(480)}); height: var(--tc-space-6); overflow: hidden;
+  font-family: var(--tc-font-ui); font-size: var(--tc-font-size-s); color: var(--tc-color-text-muted);
+  -webkit-mask: linear-gradient(90deg, transparent, #000 15%, #000 85%, transparent);
+  mask: linear-gradient(90deg, transparent, #000 15%, #000 85%, transparent); }
+.tc-overlay .tc-compass-strip, .tc-overlay .tc-compass-markers { position: absolute; left: 0; top: 0; height: 100%; will-change: transform; }
+.tc-overlay .tc-compass-markers { left: 50%; }
+.tc-overlay .tc-compass-tick { position: absolute; bottom: 0; width: var(--tc-border-width); height: var(--tc-space-2);
+  background: var(--tc-color-text-muted); transform: translateX(-50%); }
+.tc-overlay .tc-compass-tick[data-major] { height: var(--tc-space-3); background: var(--tc-color-text); }
+.tc-overlay .tc-compass-label { position: absolute; top: 0; transform: translateX(-50%); line-height: 1.2; font-weight: 600; letter-spacing: 0.08em; }
+.tc-overlay .tc-compass-marker { position: absolute; top: 0; bottom: var(--tc-space-3); display: grid; place-items: center; min-width: var(--tc-space-4);
+  padding: 0 var(--tc-space-1); border-radius: var(--tc-radius-s); background: var(--tc-color-accent); color: var(--tc-color-accent-text);
+  font-weight: 700; line-height: 1; will-change: transform; }
+.tc-overlay .tc-compass-marker[hidden] { display: none; }
+.tc-overlay .tc-compass-mark { position: absolute; left: 50%; top: 0; bottom: 0; width: var(--tc-border-width); transform: translateX(-50%);
+  background: var(--tc-color-accent); }
+`;
+const STYLE_ID = 'tc-ui-widgets-3';
+/** Add `WIDGETS3_CSS` to `doc` once (the first ring or compass does it). */
+export function ensureWidgets3Styles(doc = document) {
+    if (doc.getElementById(STYLE_ID))
+        return;
+    const style = doc.createElement('style');
+    style.id = STYLE_ID;
+    style.textContent = WIDGETS3_CSS;
+    doc.head.appendChild(style);
+}

package/dist/ui/widgets.d.ts

@@ -0,0 +1,34 @@
+export interface ButtonOptions {
+    variant?: 'default' | 'primary' | 'ghost';
+    disabled?: boolean;
+    /** Accessible name when the label is an icon. */
+    ariaLabel?: string;
+    className?: string;
+    /**
+     * The button's stable id (ws/input-12; `data-tc-id`, `CONTROL_ID_ATTR`): what a recording
+     * stores when it fires and what `Overlay.activate` finds it by on replay. Omitted, the id is
+     * derived from its page and label (`controlId`); give one when the label is translated or
+     * not unique on its page.
+     */
+    id?: string;
+}
+export declare function button(label: string | Node, onClick: (e: MouseEvent) => void, opts?: ButtonOptions): HTMLButtonElement;
+export interface SliderOptions {
+    min?: number;
+    max?: number;
+    step?: number;
+    /** Format the value for `aria-valuetext` (e.g. `v => Math.round(v*100)+'%'`). */
+    format?: (v: number) => string;
+}
+/** Labelled range input. `onInput` fires continuously while dragging. */
+export declare function slider(label: string, value: number, onInput: (v: number) => void, opts?: SliderOptions): {
+    element: HTMLLabelElement;
+    input: HTMLInputElement;
+    set(v: number): void;
+};
+/** Labelled checkbox. */
+export declare function toggle(label: string, checked: boolean, onChange: (v: boolean) => void): {
+    element: HTMLLabelElement;
+    input: HTMLInputElement;
+    set(v: boolean): void;
+};

package/dist/ui/widgets.js

@@ -0,0 +1,50 @@
+import { h } from './dom.js';
+export function button(label, onClick, opts = {}) {
+    return h('button', {
+        type: 'button',
+        class: ['tc-button', opts.className ?? ''].join(' ').trim(),
+        dataset: { variant: opts.variant ?? 'default' },
+        disabled: opts.disabled ?? false,
+        'aria-label': opts.ariaLabel,
+        'data-tc-id': opts.id,
+        on: { click: onClick },
+    }, label);
+}
+/** Labelled range input. `onInput` fires continuously while dragging. */
+export function slider(label, value, onInput, opts = {}) {
+    const { min = 0, max = 1, step = 0.01, format } = opts;
+    const input = h('input', { type: 'range', min, max, step });
+    const setText = () => {
+        if (format)
+            input.setAttribute('aria-valuetext', format(Number(input.value)));
+    };
+    input.value = String(value);
+    setText();
+    input.addEventListener('input', () => {
+        setText();
+        onInput(Number(input.value));
+    });
+    const element = h('label', { class: 'tc-field' }, h('span', null, label), input);
+    return {
+        element,
+        input,
+        set(v) {
+            input.value = String(v);
+            setText();
+        },
+    };
+}
+/** Labelled checkbox. */
+export function toggle(label, checked, onChange) {
+    const input = h('input', { type: 'checkbox' });
+    input.checked = checked;
+    input.addEventListener('change', () => onChange(input.checked));
+    const element = h('label', { class: 'tc-field' }, input, h('span', null, label));
+    return {
+        element,
+        input,
+        set(v) {
+            input.checked = v;
+        },
+    };
+}

package/dist/ui/world-panel/index.d.ts

@@ -0,0 +1,5 @@
+export { type FlowItem, type FlowOptions, flowLayout, type PanelRect } from './layout.js';
+export { makePanelCanvas, Painter, type PanelCanvas, type PanelContext2D, type PanelTheme, resolvePanelTheme, } from './paint.js';
+export { createWorldPanel, WorldPanel, type WorldPanelHit, type WorldPanelInput, type WorldPanelOptions, type WorldPanelStats, worldPanelTarget, } from './panel.js';
+export { WORLD_PANEL_WGSL } from './wgsl.js';
+export { button as worldButton, label as worldLabel, list as worldList, type PanelKeyEvent, progress as worldProgress, slider as worldSlider, toggle as worldToggle, WorldButton, type WorldButtonOptions, WorldLabel, type WorldLabelOptions, WorldList, type WorldListOptions, WorldProgress, type WorldProgressOptions, WorldSlider, type WorldSliderOptions, WorldToggle, type WorldToggleOptions, WorldWidget, type WorldWidgetAlign, type WorldWidgetHost, type WorldWidgetSize, type WorldWidgetTone, } from './widgets.js';

package/dist/ui/world-panel/index.js

@@ -0,0 +1,5 @@
+export { flowLayout } from './layout.js';
+export { makePanelCanvas, Painter, resolvePanelTheme, } from './paint.js';
+export { createWorldPanel, WorldPanel, worldPanelTarget, } from './panel.js';
+export { WORLD_PANEL_WGSL } from './wgsl.js';
+export { button as worldButton, label as worldLabel, list as worldList, progress as worldProgress, slider as worldSlider, toggle as worldToggle, WorldButton, WorldLabel, WorldList, WorldProgress, WorldSlider, WorldToggle, WorldWidget, } from './widgets.js';

package/dist/ui/world-panel/layout.d.ts

@@ -0,0 +1,38 @@
+/**
+ * World-panel layout: a vertical flow in panel px. Each widget is given the full inner width and
+ * the height it asks for; a widget with an explicit `rect` is placed there and skipped by the
+ * flow. Pure arithmetic, so it is tested without a canvas.
+ */
+/** A rect in panel px, from the top-left. */
+export interface PanelRect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** What the flow needs from a widget. */
+export interface FlowItem {
+    /** An explicit place; the flow leaves it alone. */
+    rect: PanelRect | null;
+    /** The height wanted for `width` px. */
+    measure(width: number): number;
+    /** The rect the layout assigned (written by `flowLayout`). */
+    readonly layoutRect: PanelRect;
+}
+export interface FlowOptions {
+    width: number;
+    padding: number;
+    gap: number;
+}
+/**
+ * Lay `items` out top to bottom inside `width` with `padding` on every side and `gap` between
+ * rows. Writes each item's `layoutRect` in place and returns the content height used (padding
+ * included), so nothing is allocated.
+ */
+export declare function flowLayout(items: readonly FlowItem[], opts: FlowOptions): number;
+/** Whether the panel px point lies in `r`. */
+export declare function rectContains(r: PanelRect, x: number, y: number): boolean;
+/** Grow `acc` to include `r`; an empty `acc` (w or h ≤ 0) becomes `r`. */
+export declare function rectUnion(acc: PanelRect, r: PanelRect): void;
+/** Clamp `r` to `[0, w) × [0, h)` and snap it outward to whole px. */
+export declare function rectClampSnap(r: PanelRect, w: number, h: number): void;

package/dist/ui/world-panel/layout.js

@@ -0,0 +1,68 @@
+/**
+ * World-panel layout: a vertical flow in panel px. Each widget is given the full inner width and
+ * the height it asks for; a widget with an explicit `rect` is placed there and skipped by the
+ * flow. Pure arithmetic, so it is tested without a canvas.
+ */
+/**
+ * Lay `items` out top to bottom inside `width` with `padding` on every side and `gap` between
+ * rows. Writes each item's `layoutRect` in place and returns the content height used (padding
+ * included), so nothing is allocated.
+ */
+export function flowLayout(items, opts) {
+    const inner = Math.max(0, opts.width - opts.padding * 2);
+    let y = opts.padding;
+    let first = true;
+    for (const item of items) {
+        const r = item.layoutRect;
+        if (item.rect) {
+            r.x = item.rect.x;
+            r.y = item.rect.y;
+            r.w = item.rect.w;
+            r.h = item.rect.h;
+            continue;
+        }
+        if (!first)
+            y += opts.gap;
+        first = false;
+        const h = Math.max(0, Math.round(item.measure(inner)));
+        r.x = opts.padding;
+        r.y = y;
+        r.w = inner;
+        r.h = h;
+        y += h;
+    }
+    return y + opts.padding;
+}
+/** Whether the panel px point lies in `r`. */
+export function rectContains(r, x, y) {
+    return x >= r.x && y >= r.y && x < r.x + r.w && y < r.y + r.h;
+}
+/** Grow `acc` to include `r`; an empty `acc` (w or h ≤ 0) becomes `r`. */
+export function rectUnion(acc, r) {
+    if (acc.w <= 0 || acc.h <= 0) {
+        acc.x = r.x;
+        acc.y = r.y;
+        acc.w = r.w;
+        acc.h = r.h;
+        return;
+    }
+    const x0 = Math.min(acc.x, r.x);
+    const y0 = Math.min(acc.y, r.y);
+    const x1 = Math.max(acc.x + acc.w, r.x + r.w);
+    const y1 = Math.max(acc.y + acc.h, r.y + r.h);
+    acc.x = x0;
+    acc.y = y0;
+    acc.w = x1 - x0;
+    acc.h = y1 - y0;
+}
+/** Clamp `r` to `[0, w) × [0, h)` and snap it outward to whole px. */
+export function rectClampSnap(r, w, h) {
+    const x0 = Math.max(0, Math.floor(r.x));
+    const y0 = Math.max(0, Math.floor(r.y));
+    const x1 = Math.min(w, Math.ceil(r.x + r.w));
+    const y1 = Math.min(h, Math.ceil(r.y + r.h));
+    r.x = x0;
+    r.y = y0;
+    r.w = Math.max(0, x1 - x0);
+    r.h = Math.max(0, y1 - y0);
+}

package/dist/ui/world-panel/paint.d.ts

@@ -0,0 +1,96 @@
+/**
+ * World-panel painting: a Canvas2D the panel texture is uploaded from, the theme read by value
+ * from `theme.ts`, and the small set of drawing helpers the widgets share. The canvas is
+ * injectable (`PanelCanvas`) so tests paint into a stub; `makePanelCanvas` picks `OffscreenCanvas`,
+ * then `document.createElement('canvas')`.
+ */
+import { type ThemeTokens } from '../theme.js';
+import type { PanelRect } from './layout.js';
+/** The Canvas2D subset the panel paints with (a `CanvasRenderingContext2D` satisfies it). */
+export interface PanelContext2D {
+    font: string;
+    textAlign: CanvasTextAlign;
+    textBaseline: CanvasTextBaseline;
+    fillStyle: string | CanvasGradient | CanvasPattern;
+    strokeStyle: string | CanvasGradient | CanvasPattern;
+    lineWidth: number;
+    globalAlpha: number;
+    save(): void;
+    restore(): void;
+    beginPath(): void;
+    closePath(): void;
+    rect(x: number, y: number, w: number, h: number): void;
+    moveTo(x: number, y: number): void;
+    lineTo(x: number, y: number): void;
+    arcTo(x1: number, y1: number, x2: number, y2: number, r: number): void;
+    arc(x: number, y: number, r: number, a0: number, a1: number): void;
+    fill(): void;
+    stroke(): void;
+    clip(): void;
+    clearRect(x: number, y: number, w: number, h: number): void;
+    fillRect(x: number, y: number, w: number, h: number): void;
+    fillText(text: string, x: number, y: number): void;
+    measureText(text: string): {
+        width: number;
+    };
+}
+/** A canvas the panel owns: `width`/`height` in px and a 2D context. */
+export interface PanelCanvas {
+    readonly width: number;
+    readonly height: number;
+    getContext(kind: '2d', opts?: {
+        alpha?: boolean;
+    }): PanelContext2D | null;
+}
+/** `OffscreenCanvas`, else a `<canvas>`; throws where neither exists. */
+export declare function makePanelCanvas(width: number, height: number): PanelCanvas;
+/** Theme tokens as numbers and strings the painter reads each paint. */
+export interface PanelTheme {
+    tokens: ThemeTokens;
+    font: string;
+    fontSizeS: number;
+    fontSizeM: number;
+    fontSizeL: number;
+    space1: number;
+    space2: number;
+    space3: number;
+    space4: number;
+    radiusS: number;
+    radiusM: number;
+    borderWidth: number;
+    focusRing: number;
+}
+/** `'12px'` → 12 (any other unit or junk → `fallback`). */
+export declare function tokenPx(value: string | undefined, fallback: number): number;
+/**
+ * The panel's theme: `cssPxTheme` (the design tokens at CSS px, so a 256 px/unit panel reads at
+ * arm's length) under `overrides`. Every value is read once here; widgets paint from the result.
+ */
+export declare function resolvePanelTheme(overrides?: Partial<ThemeTokens>): PanelTheme;
+/** Trace a rounded rect path (`r` clamped to half the shorter side). */
+export declare function roundRectPath(ctx: PanelContext2D, x: number, y: number, w: number, h: number, r: number): void;
+/**
+ * The painter the widgets draw through: the context, the theme and a text-width cache keyed by
+ * font and string (cleared when the font loads).
+ */
+export declare class Painter {
+    readonly ctx: PanelContext2D;
+    readonly theme: PanelTheme;
+    private readonly widths;
+    constructor(ctx: PanelContext2D, theme: PanelTheme);
+    /** `size`px of the theme font as a CSS font string. */
+    font(size: number, weight?: number): string;
+    /** Text width in px for `font`, measured once per (font, text). */
+    measure(text: string, font: string): number;
+    /** Drop every cached width (after the font loaded). */
+    clearMeasures(): void;
+    fillRoundRect(r: PanelRect, radius: number, fill: string): void;
+    strokeRoundRect(r: PanelRect, radius: number, stroke: string, width: number): void;
+    /** The focus ring: a stroke of `focusRing` px just outside `r`. */
+    focusRing(r: PanelRect, radius: number): void;
+    /**
+     * One line of `text` at `size`px, clipped to `r`, `align`ed inside it with `padX` px of inset
+     * and vertically centred.
+     */
+    text(text: string, r: PanelRect, size: number, color: string, align?: 'left' | 'center' | 'right', padX?: number, weight?: number): void;
+}

package/dist/ui/world-panel/paint.js

@@ -0,0 +1,136 @@
+/**
+ * World-panel painting: a Canvas2D the panel texture is uploaded from, the theme read by value
+ * from `theme.ts`, and the small set of drawing helpers the widgets share. The canvas is
+ * injectable (`PanelCanvas`) so tests paint into a stub; `makePanelCanvas` picks `OffscreenCanvas`,
+ * then `document.createElement('canvas')`.
+ */
+import { cssPxTheme, defaultTheme } from '../theme.js';
+/** `OffscreenCanvas`, else a `<canvas>`; throws where neither exists. */
+export function makePanelCanvas(width, height) {
+    if (typeof OffscreenCanvas !== 'undefined') {
+        return new OffscreenCanvas(width, height);
+    }
+    if (typeof document !== 'undefined') {
+        const c = document.createElement('canvas');
+        c.width = width;
+        c.height = height;
+        return c;
+    }
+    throw new Error('world panel: no OffscreenCanvas or document to make a canvas');
+}
+/** `'12px'` → 12 (any other unit or junk → `fallback`). */
+export function tokenPx(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    const n = Number.parseFloat(value);
+    return Number.isFinite(n) ? n : fallback;
+}
+/**
+ * The panel's theme: `cssPxTheme` (the design tokens at CSS px, so a 256 px/unit panel reads at
+ * arm's length) under `overrides`. Every value is read once here; widgets paint from the result.
+ */
+export function resolvePanelTheme(overrides) {
+    const tokens = { ...defaultTheme, ...cssPxTheme, ...overrides };
+    return {
+        tokens,
+        font: tokens.fontUi,
+        fontSizeS: tokenPx(tokens.fontSizeS, 14),
+        fontSizeM: tokenPx(tokens.fontSizeM, 16),
+        fontSizeL: tokenPx(tokens.fontSizeL, 20),
+        space1: tokenPx(tokens.space1, 2),
+        space2: tokenPx(tokens.space2, 4),
+        space3: tokenPx(tokens.space3, 8),
+        space4: tokenPx(tokens.space4, 12),
+        radiusS: tokenPx(tokens.radiusS, 4),
+        radiusM: tokenPx(tokens.radiusM, 8),
+        borderWidth: tokenPx(tokens.borderWidth, 1),
+        focusRing: tokenPx(tokens.focusRing, 2),
+    };
+}
+/** Trace a rounded rect path (`r` clamped to half the shorter side). */
+export function roundRectPath(ctx, x, y, w, h, r) {
+    const rr = Math.max(0, Math.min(r, w / 2, h / 2));
+    ctx.beginPath();
+    ctx.moveTo(x + rr, y);
+    ctx.arcTo(x + w, y, x + w, y + h, rr);
+    ctx.arcTo(x + w, y + h, x, y + h, rr);
+    ctx.arcTo(x, y + h, x, y, rr);
+    ctx.arcTo(x, y, x + w, y, rr);
+    ctx.closePath();
+}
+/**
+ * The painter the widgets draw through: the context, the theme and a text-width cache keyed by
+ * font and string (cleared when the font loads).
+ */
+export class Painter {
+    ctx;
+    theme;
+    widths = new Map();
+    constructor(ctx, theme) {
+        this.ctx = ctx;
+        this.theme = theme;
+    }
+    /** `size`px of the theme font as a CSS font string. */
+    font(size, weight = 500) {
+        return `${weight} ${size}px ${this.theme.font}`;
+    }
+    /** Text width in px for `font`, measured once per (font, text). */
+    measure(text, font) {
+        const key = `${font}\u0000${text}`;
+        let w = this.widths.get(key);
+        if (w === undefined) {
+            this.ctx.font = font;
+            w = this.ctx.measureText(text).width;
+            this.widths.set(key, w);
+        }
+        return w;
+    }
+    /** Drop every cached width (after the font loaded). */
+    clearMeasures() {
+        this.widths.clear();
+    }
+    fillRoundRect(r, radius, fill) {
+        const ctx = this.ctx;
+        roundRectPath(ctx, r.x, r.y, r.w, r.h, radius);
+        ctx.fillStyle = fill;
+        ctx.fill();
+    }
+    strokeRoundRect(r, radius, stroke, width) {
+        const ctx = this.ctx;
+        const half = width / 2;
+        roundRectPath(ctx, r.x + half, r.y + half, r.w - width, r.h - width, Math.max(0, radius - half));
+        ctx.strokeStyle = stroke;
+        ctx.lineWidth = width;
+        ctx.stroke();
+    }
+    /** The focus ring: a stroke of `focusRing` px just outside `r`. */
+    focusRing(r, radius) {
+        const t = this.theme;
+        const w = t.focusRing;
+        const ctx = this.ctx;
+        roundRectPath(ctx, r.x - w / 2, r.y - w / 2, r.w + w, r.h + w, radius + w / 2);
+        ctx.strokeStyle = t.tokens.colorFocus;
+        ctx.lineWidth = w;
+        ctx.stroke();
+    }
+    /**
+     * One line of `text` at `size`px, clipped to `r`, `align`ed inside it with `padX` px of inset
+     * and vertically centred.
+     */
+    text(text, r, size, color, align = 'left', padX = 0, weight = 500) {
+        if (text.length === 0 || r.w <= 0 || r.h <= 0)
+            return;
+        const ctx = this.ctx;
+        ctx.save();
+        ctx.beginPath();
+        ctx.rect(r.x, r.y, r.w, r.h);
+        ctx.clip();
+        ctx.font = this.font(size, weight);
+        ctx.fillStyle = color;
+        ctx.textBaseline = 'middle';
+        ctx.textAlign = align;
+        const x = align === 'left' ? r.x + padX : align === 'right' ? r.x + r.w - padX : r.x + r.w / 2;
+        ctx.fillText(text, x, r.y + r.h / 2);
+        ctx.restore();
+    }
+}