@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/ui/anchor.js

@@ -0,0 +1,307 @@
+import { logicalToClient } from '../platform/letterbox.js';
+const BEHIND = 1e-6;
+const IDENTITY = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
+const ZERO_RECT = { x: 0, y: 0, width: 0, height: 0 };
+/** How far past the viewport an off-screen point is pushed before clamping (clip units). */
+const FAR = 1e6;
+class Anchor {
+    el;
+    owner;
+    world = new Float32Array(3);
+    visible = true;
+    clamped = false;
+    x = Number.NaN;
+    y = Number.NaN;
+    scale = 1;
+    removed = false;
+    ax;
+    ay;
+    ox;
+    oy;
+    clamp;
+    margin;
+    byDistance;
+    distance;
+    min;
+    max;
+    hideBehind;
+    layer;
+    typed;
+    /** The string fallback's tail: `scale(…)` is written in front of it. */
+    alignCss;
+    constructor(el, world, opts, owner) {
+        this.el = el;
+        this.owner = owner;
+        this.set(world);
+        [this.ax, this.ay] = opts.align ?? [0.5, 0.5];
+        [this.ox, this.oy] = opts.offset ?? [0, 0];
+        this.clamp = opts.clamp ?? false;
+        this.margin = opts.margin ?? 16;
+        this.byDistance = opts.scale === 'distance';
+        this.distance = opts.distance ?? 10;
+        this.min = opts.min ?? 0.25;
+        this.max = opts.max ?? 2;
+        this.hideBehind = opts.hideBehind ?? true;
+        this.layer = opts.layer ?? null;
+        this.alignCss = `translate(${-this.ax * 100}%, ${-this.ay * 100}%)`;
+        this.typed = typedTransform(el, this.ax, this.ay);
+    }
+    set(world) {
+        this.world[0] = world[0] ?? 0;
+        this.world[1] = world[1] ?? 0;
+        this.world[2] = world[2] ?? 0;
+    }
+    remove() {
+        if (this.removed)
+            return;
+        this.removed = true;
+        this.owner.drop(this);
+        this.el.remove();
+    }
+    /** Write the element's place; only what changed touches the DOM. */
+    place(x, y, s, visible, clamped) {
+        const el = this.el;
+        if (visible !== this.visible) {
+            this.visible = visible;
+            el.hidden = !visible;
+        }
+        if (clamped !== this.clamped) {
+            this.clamped = clamped;
+            el.toggleAttribute('data-anchor-clamped', clamped);
+        }
+        if (!visible || (x === this.x && y === this.y && s === this.scale))
+            return;
+        this.x = x;
+        this.y = y;
+        this.scale = s;
+        const t = this.typed;
+        if (t) {
+            t.x.value = x;
+            t.y.value = y;
+            t.s.value = s;
+            el.attributeStyleMap.set('transform', t.value);
+        }
+        else {
+            el.style.transform = `translate3d(${x}px, ${y}px, 0) scale(${s}) ${this.alignCss}`;
+        }
+    }
+}
+/**
+ * CSS Typed OM where the browser has it (Chromium, WebKit); null elsewhere (string fallback).
+ * `translate3d(x, y, 0) scale(s) translate(-ax%, -ay%)` with its three values reusable.
+ * @internal shared with the float numbers.
+ */
+export function typedTransform(el, ax, ay) {
+    if (typeof CSSUnitValue === 'undefined' ||
+        typeof CSSTransformValue === 'undefined' ||
+        !('attributeStyleMap' in el)) {
+        return null;
+    }
+    try {
+        const x = new CSSUnitValue(0, 'px');
+        const y = new CSSUnitValue(0, 'px');
+        const s = new CSSUnitValue(1, 'number');
+        const value = new CSSTransformValue([
+            new CSSTranslate(x, y, new CSSUnitValue(0, 'px')),
+            new CSSScale(s, s),
+            new CSSTranslate(new CSSUnitValue(-ax * 100, 'percent'), new CSSUnitValue(-ay * 100, 'percent')),
+        ]);
+        return { x, y, s, value };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * DOM elements that follow world points: a name over a character, a damage number, a hint on a
+ * tile, a marker that stays on screen for something off it. Each `update()` projects every point
+ * through the camera (`viewProjection`), maps clip space onto the camera's `screen` and that onto
+ * the canvas rect in CSS px, and writes `transform` on the element (layout never reflows). A
+ * point behind the camera or outside clip space hides its element (`hidden`) unless it is
+ * clamped. `update()` allocates nothing in steady state where CSS Typed OM exists; elsewhere a
+ * moved element gets one transform string.
+ *
+ * In a game, `ctx.ui.anchors(camera)` builds the overlay's one `Anchors` on `ui.layers.hud`, and
+ * `createGame` updates it after every frame.
+ */
+export class Anchors {
+    opts;
+    list = [];
+    clip = new Float32Array(4);
+    pt = { x: 0, y: 0 };
+    cam;
+    frameState = { width: 0, height: 0, rect: ZERO_RECT };
+    // The camera and viewport as of `prepare()`, shared by `update()` and `project()`.
+    m = IDENTITY;
+    sc = ZERO_RECT;
+    kx = 1;
+    ky = 1;
+    vx0 = 0;
+    vy0 = 0;
+    vx1 = 0;
+    vy1 = 0;
+    /** The clip w of the last projected point (view depth under a perspective camera). */
+    depth = 1;
+    constructor(opts) {
+        this.opts = opts;
+        this.cam = opts.camera;
+    }
+    /** Anchored elements. */
+    get size() {
+        return this.list.length;
+    }
+    /** The logical size and CSS rect projected into, as the surface has them now (one reused object). */
+    get frame() {
+        const surf = this.opts.surface;
+        const f = this.frameState;
+        f.width = surf.logicalWidth;
+        f.height = surf.logicalHeight;
+        f.rect = surf.rect;
+        return f;
+    }
+    /**
+     * Project a world point into frame CSS px (the hud layer's coordinates), written to `out`, the
+     * way an anchor is placed before its offset and clamp. Returns whether the point is in view: a
+     * point behind the camera is pushed far out along its direction, one outside the viewport
+     * lands where it would. Allocates nothing.
+     */
+    project(x, y, z, out) {
+        this.prepare();
+        return this.projectPrepared(x, y, z, out);
+    }
+    /** Project through another camera from the next `update()` on. */
+    setCamera(camera) {
+        this.cam = camera;
+    }
+    /**
+     * Place `el` at the world point `world` (copied) from the next `update()` on. The element is
+     * appended to its layer (`opts.layer`, else `root`) and positioned absolutely at the layer's
+     * top-left, moved by `transform` only.
+     */
+    add(el, world, opts = {}) {
+        const a = new Anchor(el, world, opts, this);
+        const layer = (a.layer !== null && this.opts.layers?.[a.layer]) || this.opts.root;
+        const s = el.style;
+        s.position = 'absolute';
+        s.left = '0';
+        s.top = '0';
+        s.transformOrigin = '0 0';
+        s.willChange = 'transform';
+        el.classList.add('tc-anchor');
+        layer.append(el);
+        this.list.push(a);
+        return a;
+    }
+    /** Remove every anchored element. */
+    clear() {
+        for (let i = this.list.length - 1; i >= 0; i--)
+            this.list[i].remove();
+    }
+    /** @internal */
+    drop(a) {
+        const i = this.list.indexOf(a);
+        if (i >= 0)
+            this.list.splice(i, 1);
+    }
+    /** Place every element for the camera as it is now. Call once a frame, after the camera moved. */
+    update() {
+        this.prepare();
+        const rect = this.opts.surface.rect;
+        const onFrame = this.opts.onFrame;
+        const pt = this.pt;
+        const vx0 = this.vx0;
+        const vy0 = this.vy0;
+        const vx1 = this.vx1;
+        const vy1 = this.vy1;
+        for (let i = 0; i < this.list.length; i++) {
+            const a = this.list[i];
+            const inside = this.projectPrepared(a.world[0], a.world[1], a.world[2], pt);
+            if (!inside && !a.clamp && a.hideBehind) {
+                a.place(a.x, a.y, a.scale, false, false);
+                continue;
+            }
+            const w = this.depth;
+            let x = pt.x + a.ox;
+            let y = pt.y + a.oy;
+            let clamped = false;
+            if (a.clamp) {
+                const mg = a.margin;
+                const cx = Math.min(Math.max(x, vx0 + mg), vx1 - mg);
+                const cy = Math.min(Math.max(y, vy0 + mg), vy1 - mg);
+                clamped = !inside || cx !== x || cy !== y;
+                x = cx;
+                y = cy;
+            }
+            if (a.layer !== null && onFrame && !onFrame(a.layer)) {
+                x += rect.x;
+                y += rect.y;
+            }
+            let s = 1;
+            if (a.byDistance) {
+                s = w > BEHIND ? a.distance / w : a.max;
+                s = Math.min(Math.max(s, a.min), a.max);
+            }
+            a.place(x, y, s, true, clamped);
+        }
+    }
+    /** Read the camera and the viewport (camera.screen in frame CSS px) for the projections after. */
+    prepare() {
+        const cam = this.cam();
+        const sc = cam.screen;
+        const surf = this.opts.surface;
+        const lw = surf.logicalWidth;
+        const lh = surf.logicalHeight;
+        const rect = surf.rect;
+        // camera.screen → logical px: a rect inside the unit square is a fraction of the canvas.
+        const frac = sc.x >= 0 && sc.y >= 0 && sc.x + sc.width <= 1 && sc.y + sc.height <= 1;
+        const kx = frac ? lw : 1;
+        const ky = frac ? lh : 1;
+        const pt = this.pt;
+        logicalToClient(rect, lw, lh, sc.x * kx, sc.y * ky, pt);
+        this.vx0 = pt.x - rect.x;
+        this.vy0 = pt.y - rect.y;
+        logicalToClient(rect, lw, lh, (sc.x + sc.width) * kx, (sc.y + sc.height) * ky, pt);
+        this.vx1 = pt.x - rect.x;
+        this.vy1 = pt.y - rect.y;
+        this.m = cam.viewProjection;
+        this.sc = sc;
+        this.kx = kx;
+        this.ky = ky;
+    }
+    /** One point through the prepared camera: `out` gets frame CSS px, `depth` the clip w. */
+    projectPrepared(wx, wy, wz, out) {
+        const m = this.m;
+        const sc = this.sc;
+        const surf = this.opts.surface;
+        const rect = surf.rect;
+        const c = this.clip;
+        for (let r = 0; r < 4; r++) {
+            c[r] = m[r] * wx + m[4 + r] * wy + m[8 + r] * wz + m[12 + r];
+        }
+        const w = c[3];
+        this.depth = w;
+        const inside = w > BEHIND && Math.abs(c[0]) <= w && Math.abs(c[1]) <= w && c[2] >= 0 && c[2] <= w;
+        let nx;
+        let ny;
+        if (w > BEHIND) {
+            nx = c[0] / w;
+            ny = c[1] / w;
+        }
+        else {
+            // Behind the eye the projection mirrors; the point's direction is x, y over |w|, and it
+            // is off screen whatever its size, so push it far out before clamping.
+            const d = Math.max(Math.abs(c[0]), Math.abs(c[1])) || 1;
+            nx = (c[0] / d) * FAR;
+            ny = (c[1] / d) * FAR;
+            if (nx === 0 && ny === 0)
+                ny = -FAR;
+        }
+        // NDC → screen units → logical px → frame CSS px.
+        const sx = (sc.x + ((nx + 1) / 2) * sc.width) * this.kx;
+        const sy = (sc.y + ((1 - ny) / 2) * sc.height) * this.ky;
+        logicalToClient(rect, surf.logicalWidth, surf.logicalHeight, sx, sy, out);
+        out.x -= rect.x;
+        out.y -= rect.y;
+        return inside;
+    }
+}

package/dist/ui/caption.d.ts

@@ -0,0 +1,122 @@
+import type { Rect } from './overlay.js';
+export type Corner = 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+/** Area (px²) of `box` that lies inside any of `regions` (overlaps between regions count twice). Pure. */
+export declare function overlapArea(box: Rect, regions: readonly Rect[]): number;
+/** The order corners are tried in: the preferred one, its mirror across, then the other edge. Pure. */
+export declare function cornerOrder(preferred: Corner): Corner[];
+export interface ReadingTimeOptions {
+    /** Base time added to every line. Default 1200 ms. */
+    baseMs?: number;
+    /** Per character. Default 45 ms (~220 wpm with base). */
+    perCharMs?: number;
+    /** Floor. Default 2000 ms. */
+    minMs?: number;
+    /** Ceiling. Default 12000 ms. */
+    maxMs?: number;
+}
+/** How long a line should stay up once fully revealed. Pure. */
+export declare function readingTimeMs(text: string, opts?: ReadingTimeOptions): number;
+/** Delay before revealing the next char: pauses after punctuation. Pure. */
+export declare function revealDelayMs(prev: string, cps: number): number;
+export interface SayOptions {
+    /** Shown above the text (e.g. a name). Omit for none. */
+    speaker?: string;
+    /** Optional element shown left of the text (a canvas, an svg glyph...). */
+    portrait?: Node;
+    /** Reveal speed in characters per second. `0` or reduced motion = instant. Default 45. */
+    cps?: number;
+    /** ms to hold once fully shown; `0` = until clicked / `advance()`. Default `readingTimeMs(text)`. */
+    hold?: number;
+    /** Called with each revealed character (e.g. to blip a sound). Not called for whitespace. */
+    onChar?: (ch: string, index: number) => void;
+    /** Override the card's corner for this line. */
+    corner?: Corner;
+}
+export interface CaptionOptions {
+    corner?: Corner;
+    /** Force reduced motion (default: the user's `prefers-reduced-motion`). */
+    reducedMotion?: boolean;
+    /** Default reveal speed. */
+    cps?: number;
+    /** Clicking the card skips the reveal, then advances. Default true. */
+    clickToAdvance?: boolean;
+}
+/**
+ * A corner speech/caption card with a typewriter reveal and a queue. The full line goes into a
+ * polite live region at once (screen readers don't hear the typewriter), and the visible text
+ * keeps its final layout from the start (unrevealed chars are `visibility:hidden`) so the card
+ * never reflows while typing.
+ */
+export declare class CaptionCard {
+    readonly element: HTMLElement;
+    private readonly portraitEl;
+    private readonly speakerEl;
+    private readonly textEl;
+    private readonly shownEl;
+    private readonly pendingEl;
+    private readonly liveEl;
+    private readonly queue;
+    private current;
+    private revealed;
+    private timer;
+    private phase;
+    private readonly corner;
+    private readonly sideEl;
+    private readonly bodyEl;
+    private readonly placeSubs;
+    private readonly homeEl;
+    private dockHost;
+    private lineCps;
+    private isSuspended;
+    reducedMotion: boolean;
+    cps: number;
+    constructor(container: HTMLElement, opts?: CaptionOptions);
+    /** The region the card is docked in (see `dock`), or null in its corner. */
+    get docked(): HTMLElement | null;
+    /**
+     * Region placement (layout regions, `Layout.dockCaption`): move the card into `host` and let
+     * it fill that region instead of floating in a corner. While docked, corners and `onPlace` do
+     * not apply; the region never overlaps another. `null` returns it to its corner in the
+     * original container. The live region stays put.
+     */
+    dock(host: HTMLElement | null): void;
+    /** True while a line is showing or queued. */
+    get busy(): boolean;
+    get queued(): number;
+    /** Text of the line being shown, or null. */
+    get currentText(): string | null;
+    /** True while `suspend(true)` holds the card hidden and frozen. */
+    get suspended(): boolean;
+    /**
+     * Called whenever the card is laid out in its corner (a new line, back from suspension or
+     * undocked), after its corner is reset to the line's and its inline `max-width` cleared. A
+     * game that must keep the card off parts of its scene moves or narrows it here (`overlapArea`
+     * and `cornerOrder` help). Returns unsubscribe.
+     */
+    onPlace(fn: (el: HTMLElement) => void): () => void;
+    /** Lay the card out again in its corner and run `onPlace` (e.g. after the scene moved). */
+    relayout(): void;
+    /**
+     * Hide the card and freeze its typing and hold timers (e.g. while a modal panel is open);
+     * `suspend(false)` shows it again and picks up where it left off, with a fresh hold. The
+     * queue and live region are untouched, and `say()` still queues while suspended.
+     */
+    suspend(on: boolean): void;
+    /** Queue a line; resolves when it's dismissed (held time elapsed, advanced, or cleared). */
+    say(text: string, opts?: SayOptions): Promise<void>;
+    /** Skip the typewriter if typing, else dismiss the current line. */
+    advance(): void;
+    /** Drop the queue and hide the card; all pending `say` promises resolve. */
+    clear(): void;
+    destroy(): void;
+    private next;
+    /** (Re)start the timer for the current phase, unless suspended. */
+    private schedule;
+    /** Reset the card to the line's corner and let `onPlace` adjust it. */
+    private place;
+    private tick;
+    private finishReveal;
+    private dismiss;
+    private render;
+    private stopTimer;
+}