@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/ui/styles.js

@@ -0,0 +1,200 @@
+import { toFrameUnits } from './text-scale.js';
+/**
+ * The overlay's root and layers (ui/overlay.ts), in CSS px. `--tc-unit` is what one px of a
+ * design-px stylesheet (`toFrameUnits`) draws as on each layer: one design px of the frame
+ * (`--tc-dpx`) on the frame's layers, one CSS px in the layout's regions and, in `css` units,
+ * in the panels and toasts.
+ */
+const ROOT_CSS = `
+.tc-overlay {
+  position: absolute; inset: 0; --tc-unit: var(--tc-dpx, 1px);
+  pointer-events: none; overflow: hidden; contain: layout style;
+  font-family: var(--tc-font-body); font-size: var(--tc-font-size-m);
+  line-height: var(--tc-line-height); color: var(--tc-color-text);
+  -webkit-font-smoothing: antialiased; text-rendering: optimizeLegibility;
+  user-select: none; -webkit-user-select: none;
+}
+.tc-overlay *, .tc-overlay *::before, .tc-overlay *::after { box-sizing: border-box; }
+/* Each layer is its own stacking context: a z-index inside one never lifts it over a later layer. */
+.tc-layer { position: absolute; inset: 0; pointer-events: none; isolation: isolate; }
+.tc-layer[data-layer="hud"], .tc-layer[data-layer="captions"],
+.tc-overlay[data-units="frame"] > .tc-layer:is([data-layer="panels"], [data-layer="toasts"]) {
+  inset: auto; left: var(--tc-frame-x, 0px); top: var(--tc-frame-y, 0px);
+  width: var(--tc-frame-w, 100%); height: var(--tc-frame-h, 100%); overflow: hidden; }
+.tc-layer[data-layer="layout"],
+.tc-overlay[data-units="css"] > .tc-layer:is([data-layer="panels"], [data-layer="toasts"]) { --tc-unit: 1px; }
+/* Native controls draw their thumb, track and arrow in CSS px whatever their box: on the frame's
+   layers they are zoomed by the frame's scale instead, their own px read as design px. */
+.tc-layer:is([data-layer="hud"], [data-layer="captions"]) :is(input[type="range"], select),
+.tc-overlay[data-units="frame"] > .tc-layer:is([data-layer="panels"], [data-layer="toasts"]) :is(input[type="range"], select) {
+  zoom: var(--tc-zoom, 1); --tc-unit: 1px; }
+/* Theme tokens are resolved on the root, so they are frame px already: a zoomed select would
+   draw them at --tc-dpx² (ws/ui-widgets wish). Divide the ones it reads back out. */
+.tc-layer:is([data-layer="hud"], [data-layer="captions"]) select,
+.tc-overlay[data-units="frame"] > .tc-layer:is([data-layer="panels"], [data-layer="toasts"]) select {
+  font-size: calc(var(--tc-font-size-s) / var(--tc-zoom, 1));
+  padding: calc(var(--tc-space-2) / var(--tc-zoom, 1)) calc(var(--tc-space-3) / var(--tc-zoom, 1));
+  border-width: calc(var(--tc-border-width) / var(--tc-zoom, 1));
+  border-radius: calc(var(--tc-radius-m) / var(--tc-zoom, 1)); }
+/* Theme lengths are already frame px there: undo the zoom for them (a hair over, so the
+   whole-pixel ring the token rounds to does not snap down a pixel). */
+.tc-layer:is([data-layer="hud"], [data-layer="captions"]) :is(input[type="range"], select):focus-visible,
+.tc-overlay[data-units="frame"] > .tc-layer:is([data-layer="panels"], [data-layer="toasts"]) :is(input[type="range"], select):focus-visible {
+  outline-width: calc(var(--tc-focus-ring) / var(--tc-zoom, 1) + 0.1px); }
+`;
+/** Base widgets, in design px (`toFrameUnits`: one px is `--tc-unit`). */
+const WIDGET_CSS = `
+.tc-interactive { pointer-events: auto; }
+
+.tc-panel-host { position: absolute; inset: 0; display: grid; place-items: center; pointer-events: none; }
+.tc-panel-host[data-modal="true"] { pointer-events: auto; }
+.tc-backdrop { position: absolute; inset: 0; background: var(--tc-color-backdrop); animation: tc-fade var(--tc-duration-normal) var(--tc-easing); }
+.tc-panel { position: relative; pointer-events: auto; max-width: 90%; max-height: 90%; overflow: auto; outline: none;
+  animation: tc-rise var(--tc-duration-normal) var(--tc-easing); }
+.tc-card { background: var(--tc-color-surface); color: var(--tc-color-text);
+  border: var(--tc-border-width) solid var(--tc-color-border); border-radius: var(--tc-radius-l);
+  box-shadow: var(--tc-shadow); padding: var(--tc-space-5); }
+.tc-panel-title { font-family: var(--tc-font-display); font-size: var(--tc-font-size-l); margin: 0 0 var(--tc-space-3); font-weight: 600; }
+
+.tc-button { pointer-events: auto; font: inherit; font-family: var(--tc-font-display); font-size: var(--tc-font-size-m);
+  color: var(--tc-color-text); background: var(--tc-color-surface-alt);
+  border: var(--tc-border-width) solid var(--tc-color-border); border-radius: var(--tc-radius-m);
+  padding: var(--tc-space-2) var(--tc-space-4); min-height: 64px; cursor: pointer;
+  transition: background var(--tc-duration-fast), border-color var(--tc-duration-fast), transform var(--tc-duration-fast); }
+.tc-button:hover:not(:disabled) { border-color: var(--tc-color-accent); }
+.tc-button:active:not(:disabled) { transform: translateY(1px); }
+.tc-button:disabled { opacity: 0.45; cursor: default; }
+.tc-button[data-variant="primary"] { background: var(--tc-color-accent); color: var(--tc-color-accent-text); border-color: var(--tc-color-accent); }
+.tc-button[data-variant="ghost"] { background: transparent; border-color: transparent; }
+.tc-overlay :focus-visible { outline: var(--tc-focus-ring) solid var(--tc-color-focus); outline-offset: 4px; }
+
+.tc-field { display: flex; align-items: center; gap: var(--tc-space-3); pointer-events: auto; font-family: var(--tc-font-ui); font-size: var(--tc-font-size-s); }
+.tc-field input[type="range"] { flex: 1; accent-color: var(--tc-color-accent); min-height: 48px; }
+.tc-field input[type="checkbox"] { width: 32px; height: 32px; accent-color: var(--tc-color-accent); }
+
+.tc-toasts { position: absolute; left: 50%; top: var(--tc-space-5); transform: translateX(-50%);
+  display: flex; flex-direction: column; align-items: center; gap: var(--tc-space-2); }
+.tc-toast { pointer-events: auto; cursor: pointer; background: var(--tc-color-surface); color: var(--tc-color-text);
+  border-left: 6px solid var(--tc-color-info); border-radius: var(--tc-radius-m); box-shadow: var(--tc-shadow);
+  padding: var(--tc-space-3) var(--tc-space-4); font-family: var(--tc-font-ui); font-size: var(--tc-font-size-s);
+  max-width: 1100px; animation: tc-drop var(--tc-duration-normal) var(--tc-easing); }
+.tc-toast[data-tone="success"] { border-left-color: var(--tc-color-success); }
+.tc-toast[data-tone="warn"] { border-left-color: var(--tc-color-warn); }
+.tc-toast[data-tone="danger"] { border-left-color: var(--tc-color-danger); }
+
+.tc-caption { position: absolute; pointer-events: auto; cursor: pointer; display: flex; gap: var(--tc-space-3); align-items: flex-start;
+  width: max-content; max-width: min(var(--tc-caption-max-width, 720px), calc(100% - 2 * var(--tc-caption-margin, var(--tc-space-5))));
+  background: var(--tc-color-surface); border: var(--tc-border-width) solid var(--tc-color-border);
+  border-radius: var(--tc-radius-m); box-shadow: var(--tc-shadow); padding: var(--tc-space-3) var(--tc-space-4);
+  transition: opacity var(--tc-duration-normal) var(--tc-easing), transform var(--tc-duration-normal) var(--tc-easing); }
+.tc-caption[hidden], .tc-caption[data-suspended] { display: none; }
+.tc-caption[data-corner$="right"] { right: var(--tc-caption-margin, var(--tc-space-5)); }
+.tc-caption[data-corner$="left"] { left: var(--tc-caption-margin, var(--tc-space-5)); }
+.tc-caption[data-corner^="bottom"] { bottom: var(--tc-caption-margin, var(--tc-space-5)); }
+.tc-caption[data-corner^="top"] { top: var(--tc-caption-margin, var(--tc-space-5)); }
+.tc-caption-side { flex: none; display: flex; flex-direction: column; align-items: center; gap: var(--tc-space-1); }
+.tc-caption-side[hidden], .tc-caption-portrait:empty { display: none; }
+.tc-caption-body { flex: 1 1 auto; min-width: 0; }
+.tc-caption-speaker { font-family: var(--tc-font-ui); font-size: var(--tc-font-size-s); color: var(--tc-color-accent);
+  letter-spacing: 0.08em; text-transform: uppercase; line-height: 1.2; }
+.tc-caption-body > .tc-caption-speaker { margin-bottom: var(--tc-space-1); }
+.tc-caption-speaker:empty { display: none; }
+.tc-caption-text { font-size: var(--tc-font-size-m); white-space: pre-wrap; overflow-wrap: break-word; }
+.tc-caption-text .tc-caption-pending { visibility: hidden; }
+
+.tc-link { position: relative; display: flex; flex-direction: column; align-items: center; pointer-events: auto; }
+.tc-link-row { display: flex; align-items: center; gap: var(--tc-space-2); }
+.tc-link-copy { pointer-events: auto; display: inline-flex; align-items: center; gap: var(--tc-space-2); padding: 6px 14px;
+  border-radius: 999px; cursor: pointer; white-space: nowrap; font-family: var(--tc-font-ui); font-size: calc(var(--tc-font-size-s) * 0.75);
+  line-height: 1.2; color: var(--tc-color-text); background: var(--tc-color-surface); border: 1px solid var(--tc-color-border); }
+.tc-link-copy:hover { border-color: var(--tc-color-accent); }
+.tc-link-copy[data-copied] { color: var(--tc-color-success); border-color: var(--tc-color-success); }
+.tc-link-copy-icon { width: 1.1em; height: 1.1em; flex: none; }
+.tc-link-fallback { position: absolute; z-index: 5; display: flex; flex-direction: column; gap: var(--tc-space-2);
+  width: max-content; min-width: 560px; max-width: 1000px;
+  box-sizing: border-box; padding: 12px var(--tc-space-3) 14px; text-align: left; pointer-events: auto;
+  background: var(--tc-color-surface); border: 1px solid var(--tc-color-border); border-radius: var(--tc-radius-m); box-shadow: var(--tc-shadow); }
+.tc-link-fallback[hidden] { display: none; }
+.tc-link-fallback[data-place="below"] { top: calc(100% + 10px); }
+.tc-link-fallback[data-place="above"] { bottom: calc(100% + 10px); }
+.tc-link-fallback[data-align="center"] { left: 50%; transform: translateX(-50%); }
+.tc-link-fallback[data-align="start"] { left: 0; }
+.tc-link-fallback[data-align="end"] { right: 0; }
+.tc-link-fallback-head { display: flex; align-items: flex-start; justify-content: space-between; gap: var(--tc-space-3); }
+.tc-link-message { font-family: var(--tc-font-ui); font-size: calc(var(--tc-font-size-s) * 0.75); line-height: 1.3; color: var(--tc-color-text); }
+.tc-link-close { flex: none; padding: 3px 12px; border-radius: 999px; cursor: pointer; font-family: var(--tc-font-ui);
+  font-size: calc(var(--tc-font-size-s) * 0.67); color: var(--tc-color-text); background: transparent; border: 1px solid var(--tc-color-border); }
+.tc-link-close:hover { border-color: var(--tc-color-accent); }
+.tc-link-field { width: 100%; box-sizing: border-box; padding: 6px 10px; border-radius: var(--tc-radius-s); font-family: var(--tc-font-mono);
+  font-size: calc(var(--tc-font-size-s) * 0.83); color: var(--tc-color-text); background: var(--tc-color-bg); border: 1px solid var(--tc-color-border); }
+
+`;
+/** The layers that follow the form's units (regions, and panels and toasts in `css` units). */
+const CSSU = '.tc-overlay[data-units="css"] :is(.tc-layer[data-layer="layout"], .tc-layer[data-layer="panels"], .tc-layer[data-layer="toasts"])';
+/** `css` units: base widgets in regions, panels and toasts honour the density tokens (CSS px). */
+const CSS_UNITS_CSS = `
+${CSSU} .tc-button { min-height: var(--tc-tap-min, 32px); min-width: var(--tc-tap-min, 32px);
+  padding: var(--tc-space-2) var(--tc-space-4); }
+${CSSU} .tc-field { min-height: var(--tc-tap-min, 32px); }
+${CSSU} .tc-field input[type="range"] { min-height: var(--tc-tap-min, 32px); margin: 0; }
+${CSSU} .tc-field input[type="checkbox"] { width: 20px; height: 20px; }
+${CSSU} .tc-panel-host { padding: var(--tc-modal-top, 8px) var(--tc-modal-right, 8px) var(--tc-modal-bottom, 8px) var(--tc-modal-left, 8px); }
+${CSSU} .tc-panel { max-width: 100%; max-height: 100%; }
+${CSSU} .tc-toasts { top: calc(var(--tc-safe-top-px, 0px) + var(--tc-space-4)); width: max-content; max-width: calc(100% - 32px); }
+${CSSU} .tc-toast { max-width: 560px; }
+${CSSU} .tc-caption { --tc-caption-max-width: 480px; --tc-caption-margin: var(--tc-space-4); }
+${CSSU} .tc-link-fallback { min-width: 0; width: min(480px, 90vw); }
+
+/* Layout regions (ui/layout.ts). The grid is laid out in the safe area; regions scroll rather than spill. */
+.tc-layout { position: absolute; inset: 0; display: grid; pointer-events: none; }
+.tc-region { position: relative; min-width: 0; min-height: 0; overflow: auto; overscroll-behavior: contain;
+  display: flex; gap: var(--tc-region-pad, 8px); padding: var(--tc-region-pad, 8px); pointer-events: none; }
+.tc-region[hidden] { display: none; }
+.tc-region > * { flex: none; }
+.tc-region[data-region="top"], .tc-region[data-region="bottom"] { flex-direction: row; align-items: center; }
+.tc-region[data-region="left"], .tc-region[data-region="right"], .tc-region[data-region="cardLane"] { flex-direction: column; align-items: stretch; }
+.tc-region[data-region="captionLane"] { flex-direction: row; align-items: stretch; }
+.tc-region[data-region="fill"], .tc-region[data-region="modal"] { flex-direction: column; align-items: center; justify-content: center; }
+.tc-region[data-region="modal"] { position: absolute; }
+.tc-layout-free { position: absolute; inset: 0; pointer-events: none; }
+.tc-overlay [data-tc-layout-hidden] { display: none !important; }
+.tc-caption[data-docked] { position: relative; inset: auto; width: 100%; max-width: none; max-height: 100%; overflow: auto; flex: 1 1 auto; }
+
+.tc-sr-only { position: absolute !important; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden;
+  clip: rect(0 0 0 0); clip-path: inset(50%); white-space: nowrap; border: 0; }
+
+@keyframes tc-fade { from { opacity: 0; } }
+@keyframes tc-rise { from { opacity: 0; transform: translateY(16px) scale(0.98); } }
+@keyframes tc-drop { from { opacity: 0; transform: translateY(-12px); } }
+@media (prefers-reduced-motion: reduce) {
+  .tc-overlay *, .tc-overlay *::before, .tc-overlay *::after { animation: none !important; transition: none !important; }
+}
+`;
+/**
+ * The overlay's base stylesheet: tokens, layers, panels, widgets and units. Injected once
+ * per document by `ensureStyles`; the HUD, cursor, tooltip and other widget sheets add
+ * their own `<style>` beside it. Everything is under `.tc-overlay`.
+ */
+export const BASE_CSS = ROOT_CSS + toFrameUnits(WIDGET_CSS) + CSS_UNITS_CSS;
+const STYLE_ID = 'tc-ui-base';
+/** Add the base stylesheet to `doc` once. */
+export function ensureStyles(doc = document) {
+    if (doc.getElementById(STYLE_ID))
+        return;
+    const style = doc.createElement('style');
+    style.id = STYLE_ID;
+    style.textContent = BASE_CSS;
+    doc.head.appendChild(style);
+}
+/**
+ * True if the user prefers reduced motion in `win` (default the global window; false where
+ * `matchMedia` is unavailable). `platform`'s `prefersReducedMotion()` reads the global window only.
+ */
+export function prefersReducedMotionIn(win = globalThis.window) {
+    try {
+        return !!win?.matchMedia?.('(prefers-reduced-motion: reduce)').matches;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/ui/text-scale.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Text size: the density tokens `--tc-text-scale` and `--tc-text-min` on the overlay root.
+ *
+ * - `--tc-text-scale` is the player's text size as a factor (1, 1.25, 1.5 …). A game passes each
+ *   stylesheet through `scaleFontSizes()` when it injects it, so all overlay text follows the
+ *   token live. `applyTextScale()` sets it, plus the engine's own font tokens to match.
+ * - `--tc-text-min` is a floor for every scaled font size, CSS px. The layout sets it from its
+ *   form spec (`FormSpec.textMin`; 0 = no floor).
+ *
+ * A stylesheet written in design px (sizes that scale with the canvas frame) also passes
+ * through `toFrameUnits()`, after `scaleFontSizes()`: every `Npx` becomes N design px.
+ *
+ * Small text scales fully. Large display text is already big, so it only grows as far as needed
+ * to stay at least as large as scaled body text: a size N becomes max(N, min(N, 30) × scale).
+ * At 150%, 24 px → 36, 30 → 45, 40 → 45, 56 → 56.
+ */
+export declare const TEXT_SCALE_VAR = "--tc-text-scale";
+/** Smallest font size in design px; every scaled size floors at it. */
+export declare const TEXT_MIN_VAR = "--tc-text-min";
+/** The scaled value of `px` at `scale` (1 = 100%). */
+export declare function scaledPx(px: number, scale: number): number;
+/** A CSS length for `px` that follows `--tc-text-scale` and floors at `--tc-text-min`. */
+export declare function scalePxCss(px: number): string;
+/**
+ * What one px of a `toFrameUnits` stylesheet draws as, CSS px: one design px of the frame
+ * (`--tc-dpx`, `Overlay.scale`) on the frame's layers; 1px in the layout's regions and, in `css`
+ * units, in the panels and toasts.
+ */
+export declare const UNIT_VAR = "--tc-unit";
+/**
+ * Rewrites every `Npx` length in `css` (a stylesheet, a declaration or one value) as N design
+ * px: `calc(N * var(--tc-unit, 1px))`, so it scales with the canvas frame. Media and container
+ * queries and `url()`s are left alone (custom properties can't be used there).
+ */
+export declare function toFrameUnits(css: string): string;
+/** Rewrites every `font-size: Npx` (and `font: … Npx/…` shorthand) in a stylesheet. */
+export declare function scaleFontSizes(css: string): string;
+/** The engine's font sizes at 100% on a scaled design-px overlay. */
+export declare const DESIGN_FONT_PX: {
+    fontSizeS: number;
+    fontSizeM: number;
+    fontSizeL: number;
+    fontSizeXl: number;
+    fontSizeXxl: number;
+};
+/** The engine's font sizes at 100% on a CSS-px overlay (`cssPxTheme`). */
+export declare const CSS_FONT_PX: {
+    fontSizeS: number;
+    fontSizeM: number;
+    fontSizeL: number;
+    fontSizeXl: number;
+    fontSizeXxl: number;
+};
+/**
+ * Engine theme font tokens at a text scale (the engine's own captions, panels and buttons).
+ * `base` is `DESIGN_FONT_PX` (default) or `CSS_FONT_PX` for a CSS-px overlay. Body sizes scale
+ * as `scaledPx` does relative to the design body size, so both bases grow the same way.
+ */
+export declare function textScaleTokens(scale: number, base?: Record<string, number>): Record<string, string>;
+/**
+ * Sets the text scale (1 = 100%) on the overlay root: `--tc-text-scale`, and
+ * `data-text-scale="<percent>"` when it is not 100% so stylesheets can make room for larger
+ * text. `setTheme` (usually `overlay.setTheme`) gets the engine font tokens to match: CSS-px
+ * sizes while the overlay is in `css` units (`data-units="css"`), design px otherwise (the
+ * overlay scales those with the frame, and re-derives them when its units change).
+ */
+export declare function applyTextScale(root: HTMLElement, scale: number, setTheme?: (t: Record<string, string>) => void): void;

package/dist/ui/text-scale.js

@@ -0,0 +1,102 @@
+/**
+ * Text size: the density tokens `--tc-text-scale` and `--tc-text-min` on the overlay root.
+ *
+ * - `--tc-text-scale` is the player's text size as a factor (1, 1.25, 1.5 …). A game passes each
+ *   stylesheet through `scaleFontSizes()` when it injects it, so all overlay text follows the
+ *   token live. `applyTextScale()` sets it, plus the engine's own font tokens to match.
+ * - `--tc-text-min` is a floor for every scaled font size, CSS px. The layout sets it from its
+ *   form spec (`FormSpec.textMin`; 0 = no floor).
+ *
+ * A stylesheet written in design px (sizes that scale with the canvas frame) also passes
+ * through `toFrameUnits()`, after `scaleFontSizes()`: every `Npx` becomes N design px.
+ *
+ * Small text scales fully. Large display text is already big, so it only grows as far as needed
+ * to stay at least as large as scaled body text: a size N becomes max(N, min(N, 30) × scale).
+ * At 150%, 24 px → 36, 30 → 45, 40 → 45, 56 → 56.
+ */
+export const TEXT_SCALE_VAR = '--tc-text-scale';
+/** Smallest font size in design px; every scaled size floors at it. */
+export const TEXT_MIN_VAR = '--tc-text-min';
+const MIN = `var(${TEXT_MIN_VAR}, 0px)`;
+/** Sizes up to this scale fully; above it, text is only kept from falling behind. */
+const BODY_PX = 30;
+/** The scaled value of `px` at `scale` (1 = 100%). */
+export function scaledPx(px, scale) {
+    return Math.max(px, Math.min(px, BODY_PX) * scale);
+}
+/** A CSS length for `px` that follows `--tc-text-scale` and floors at `--tc-text-min`. */
+export function scalePxCss(px) {
+    const v = `var(${TEXT_SCALE_VAR}, 1)`;
+    if (px <= BODY_PX)
+        return `max(calc(${px}px * ${v}), ${MIN})`;
+    if (px < BODY_PX * 1.5)
+        return `max(${px}px, calc(${BODY_PX}px * ${v}), ${MIN})`;
+    return `${px}px`;
+}
+/**
+ * What one px of a `toFrameUnits` stylesheet draws as, CSS px: one design px of the frame
+ * (`--tc-dpx`, `Overlay.scale`) on the frame's layers; 1px in the layout's regions and, in `css`
+ * units, in the panels and toasts.
+ */
+export const UNIT_VAR = '--tc-unit';
+/**
+ * Rewrites every `Npx` length in `css` (a stylesheet, a declaration or one value) as N design
+ * px: `calc(N * var(--tc-unit, 1px))`, so it scales with the canvas frame. Media and container
+ * queries and `url()`s are left alone (custom properties can't be used there).
+ */
+export function toFrameUnits(css) {
+    return css.replace(/(@(?:media|container|supports)[^{]*)|(url\([^)]*\))|(?<![\w.-])(-?(?:\d+\.?\d*|\.\d+))px\b/g, (m, at, url, n) => at || url || n === undefined ? m : `calc(${n} * var(${UNIT_VAR}, 1px))`);
+}
+/** Rewrites every `font-size: Npx` (and `font: … Npx/…` shorthand) in a stylesheet. */
+export function scaleFontSizes(css) {
+    return css
+        .replace(/font-size:\s*(\d+(?:\.\d+)?)px/g, (_, n) => `font-size: ${scalePxCss(+n)}`)
+        .replace(/(\bfont:\s*(?:\d{3}\s+)?)(\d+(?:\.\d+)?)px(?=\s*\/|\s)/g, (_, pre, n) => `${pre}${scalePxCss(+n)}`);
+}
+/** The engine's font sizes at 100% on a scaled design-px overlay. */
+export const DESIGN_FONT_PX = {
+    fontSizeS: 24,
+    fontSizeM: 30,
+    fontSizeL: 40,
+    fontSizeXl: 56,
+    fontSizeXxl: 84,
+};
+/** The engine's font sizes at 100% on a CSS-px overlay (`cssPxTheme`). */
+export const CSS_FONT_PX = {
+    fontSizeS: 14,
+    fontSizeM: 16,
+    fontSizeL: 20,
+    fontSizeXl: 28,
+    fontSizeXxl: 40,
+};
+/**
+ * Engine theme font tokens at a text scale (the engine's own captions, panels and buttons).
+ * `base` is `DESIGN_FONT_PX` (default) or `CSS_FONT_PX` for a CSS-px overlay. Body sizes scale
+ * as `scaledPx` does relative to the design body size, so both bases grow the same way.
+ */
+export function textScaleTokens(scale, base = DESIGN_FONT_PX) {
+    // scaledPx's body/display split is in design px; map CSS sizes onto it by the M ratio.
+    const k = (base.fontSizeM ?? 30) / 30;
+    const out = {};
+    for (const [name, px] of Object.entries(base)) {
+        const v = Math.round(scaledPx(px / k, scale) * k);
+        out[name] = v < 50 * k ? `max(${v}px, ${MIN})` : `${v}px`;
+    }
+    return out;
+}
+/**
+ * Sets the text scale (1 = 100%) on the overlay root: `--tc-text-scale`, and
+ * `data-text-scale="<percent>"` when it is not 100% so stylesheets can make room for larger
+ * text. `setTheme` (usually `overlay.setTheme`) gets the engine font tokens to match: CSS-px
+ * sizes while the overlay is in `css` units (`data-units="css"`), design px otherwise (the
+ * overlay scales those with the frame, and re-derives them when its units change).
+ */
+export function applyTextScale(root, scale, setTheme) {
+    root.style.setProperty(TEXT_SCALE_VAR, String(scale));
+    const pct = Math.round(scale * 100);
+    if (pct === 100)
+        delete root.dataset.textScale;
+    else
+        root.dataset.textScale = String(pct);
+    setTheme?.(textScaleTokens(scale, root.dataset.units === 'css' ? CSS_FONT_PX : DESIGN_FONT_PX));
+}

package/dist/ui/theme.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Theme tokens, exposed as CSS custom properties on the overlay root: `colorAccent` becomes
+ * `--tc-color-accent`. Sizes are in **design pixels** of the frame (1920×1080 by default): in
+ * `frame` units each is `--tc-dpx` CSS px, so 30px reads as ~15px in a 960×540 embed.
+ *
+ * Fonts are system stacks only: nothing is fetched at runtime. A game may add a self-hosted
+ * font with `@font-face` (committed with its licence) and put it first in a stack.
+ */
+export declare const defaultTheme: {
+    fontBody: string;
+    fontDisplay: string;
+    fontMono: string;
+    fontUi: string;
+    fontSizeS: string;
+    fontSizeM: string;
+    fontSizeL: string;
+    fontSizeXl: string;
+    fontSizeXxl: string;
+    lineHeight: string;
+    colorBg: string;
+    colorSurface: string;
+    colorSurfaceAlt: string;
+    colorBorder: string;
+    colorText: string;
+    colorTextMuted: string;
+    colorAccent: string;
+    colorAccentText: string;
+    colorFocus: string;
+    colorBackdrop: string;
+    colorInfo: string;
+    colorSuccess: string;
+    colorWarn: string;
+    colorDanger: string;
+    /** The damage trail behind a meter's fill (ws/ui-5). */
+    colorMeterTrail: string;
+    space1: string;
+    space2: string;
+    space3: string;
+    space4: string;
+    space5: string;
+    space6: string;
+    radiusS: string;
+    radiusM: string;
+    radiusL: string;
+    borderWidth: string;
+    shadow: string;
+    focusRing: string;
+    durationFast: string;
+    durationNormal: string;
+    easing: string;
+};
+export type ThemeTokens = {
+    [K in keyof typeof defaultTheme]: string;
+};
+/**
+ * Size tokens for the overlay's `css` units (phones; `FormSpec.units`), applied over
+ * `defaultTheme`: the same scale at screen size (about half the design-px values), so 16 px body
+ * text reads as 16 px on every screen. Colours, fonts and timings are shared.
+ */
+export declare const cssPxTheme: Partial<ThemeTokens>;
+/** Games may add their own tokens too; they become `--tc-<kebab-name>` the same way. */
+export type ThemeOverrides = Partial<ThemeTokens> & Record<string, string>;
+/** `colorAccent` → `--tc-color-accent`, `fontSizeXl` → `--tc-font-size-xl`, `space1` → `--tc-space-1`. */
+export declare function tokenVar(name: string): string;
+/** `var(--tc-…)` for use in inline styles. */
+export declare function cssVar(name: keyof ThemeTokens | (string & {})): string;
+/** CSS declarations for a set of tokens, e.g. for a `:root` or class rule. */
+export declare function themeToCss(tokens: Record<string, string>): string;
+/** Set tokens as custom properties on an element (inherits to children). */
+export declare function applyTheme(el: HTMLElement, tokens: Record<string, string>): void;

package/dist/ui/theme.js

@@ -0,0 +1,98 @@
+/**
+ * Theme tokens, exposed as CSS custom properties on the overlay root: `colorAccent` becomes
+ * `--tc-color-accent`. Sizes are in **design pixels** of the frame (1920×1080 by default): in
+ * `frame` units each is `--tc-dpx` CSS px, so 30px reads as ~15px in a 960×540 embed.
+ *
+ * Fonts are system stacks only: nothing is fetched at runtime. A game may add a self-hosted
+ * font with `@font-face` (committed with its licence) and put it first in a stack.
+ */
+export const defaultTheme = {
+    fontBody: "'Iowan Old Style', 'Palatino Linotype', Palatino, 'Book Antiqua', Georgia, serif",
+    fontDisplay: "'Iowan Old Style', 'Palatino Linotype', Palatino, 'Book Antiqua', Georgia, serif",
+    fontMono: "ui-monospace, 'SF Mono', Menlo, Consolas, 'Liberation Mono', monospace",
+    fontUi: "system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif",
+    fontSizeS: '24px',
+    fontSizeM: '30px',
+    fontSizeL: '40px',
+    fontSizeXl: '56px',
+    fontSizeXxl: '84px',
+    lineHeight: '1.4',
+    colorBg: '#0b0d14',
+    colorSurface: 'rgba(18, 21, 30, 0.94)',
+    colorSurfaceAlt: 'rgba(32, 36, 48, 0.96)',
+    colorBorder: 'rgba(224, 180, 90, 0.35)',
+    colorText: '#ece6d8',
+    colorTextMuted: '#a7a091',
+    colorAccent: '#e0b45a',
+    colorAccentText: '#1a1408',
+    colorFocus: '#ffd27a',
+    colorBackdrop: 'rgba(5, 6, 10, 0.6)',
+    colorInfo: '#7cc4e8',
+    colorSuccess: '#8fd18a',
+    colorWarn: '#f0b45a',
+    colorDanger: '#e8766a',
+    /** The damage trail behind a meter's fill (ws/ui-5). */
+    colorMeterTrail: 'rgba(255, 236, 200, 0.75)',
+    space1: '4px',
+    space2: '8px',
+    space3: '16px',
+    space4: '24px',
+    space5: '40px',
+    space6: '64px',
+    radiusS: '6px',
+    radiusM: '12px',
+    radiusL: '20px',
+    borderWidth: '2px',
+    shadow: '0 12px 48px rgba(0, 0, 0, 0.55)',
+    focusRing: '3px',
+    durationFast: '120ms',
+    durationNormal: '240ms',
+    easing: 'cubic-bezier(0.2, 0.7, 0.2, 1)',
+};
+/**
+ * Size tokens for the overlay's `css` units (phones; `FormSpec.units`), applied over
+ * `defaultTheme`: the same scale at screen size (about half the design-px values), so 16 px body
+ * text reads as 16 px on every screen. Colours, fonts and timings are shared.
+ */
+export const cssPxTheme = {
+    fontSizeS: '14px',
+    fontSizeM: '16px',
+    fontSizeL: '20px',
+    fontSizeXl: '28px',
+    fontSizeXxl: '40px',
+    space1: '2px',
+    space2: '4px',
+    space3: '8px',
+    space4: '12px',
+    space5: '20px',
+    space6: '32px',
+    radiusS: '4px',
+    radiusM: '8px',
+    radiusL: '12px',
+    borderWidth: '1px',
+    shadow: '0 6px 24px rgba(0, 0, 0, 0.55)',
+    focusRing: '2px',
+};
+/** `colorAccent` → `--tc-color-accent`, `fontSizeXl` → `--tc-font-size-xl`, `space1` → `--tc-space-1`. */
+export function tokenVar(name) {
+    const kebab = name
+        .replace(/([a-z])([A-Z])/g, '$1-$2')
+        .replace(/([a-zA-Z])(\d)/g, '$1-$2')
+        .toLowerCase();
+    return `--tc-${kebab}`;
+}
+/** `var(--tc-…)` for use in inline styles. */
+export function cssVar(name) {
+    return `var(${tokenVar(name)})`;
+}
+/** CSS declarations for a set of tokens, e.g. for a `:root` or class rule. */
+export function themeToCss(tokens) {
+    return Object.entries(tokens)
+        .map(([k, v]) => `${tokenVar(k)}: ${v};`)
+        .join('\n');
+}
+/** Set tokens as custom properties on an element (inherits to children). */
+export function applyTheme(el, tokens) {
+    for (const [k, v] of Object.entries(tokens))
+        el.style.setProperty(tokenVar(k), v);
+}

package/dist/ui/toast.d.ts

@@ -0,0 +1,23 @@
+export type ToastTone = 'info' | 'success' | 'warn' | 'danger';
+export interface ToastOptions {
+    /** ms before it disappears. `0` = until dismissed. Default 3500. */
+    duration?: number;
+    tone?: ToastTone;
+}
+export interface ToastHandle {
+    readonly element: HTMLElement;
+    dismiss(): void;
+}
+/**
+ * Transient notices in a polite live region. Click to dismiss. At most `max` are shown;
+ * the oldest goes first.
+ */
+export declare class Toaster {
+    private readonly max;
+    readonly element: HTMLElement;
+    private readonly live;
+    constructor(container: HTMLElement, max?: number);
+    get count(): number;
+    show(message: string | Node, opts?: ToastOptions): ToastHandle;
+    clear(): void;
+}

package/dist/ui/toast.js

@@ -0,0 +1,46 @@
+import { h } from './dom.js';
+/**
+ * Transient notices in a polite live region. Click to dismiss. At most `max` are shown;
+ * the oldest goes first.
+ */
+export class Toaster {
+    max;
+    element;
+    live = [];
+    constructor(container, max = 3) {
+        this.max = max;
+        this.element = h('div', { class: 'tc-toasts', role: 'status', 'aria-live': 'polite' });
+        container.append(this.element);
+    }
+    get count() {
+        return this.live.length;
+    }
+    show(message, opts = {}) {
+        const el = h('div', { class: 'tc-toast', dataset: { tone: opts.tone ?? 'info' } }, message);
+        let timer = null;
+        const handle = {
+            element: el,
+            dismiss: () => {
+                if (timer)
+                    clearTimeout(timer);
+                const i = this.live.indexOf(handle);
+                if (i >= 0)
+                    this.live.splice(i, 1);
+                el.remove();
+            },
+        };
+        el.addEventListener('click', () => handle.dismiss());
+        this.element.append(el);
+        this.live.push(handle);
+        while (this.live.length > this.max)
+            this.live[0].dismiss();
+        const duration = opts.duration ?? 3500;
+        if (duration > 0)
+            timer = setTimeout(handle.dismiss, duration);
+        return handle;
+    }
+    clear() {
+        for (const t of [...this.live])
+            t.dismiss();
+    }
+}