@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/geom/triangulate.js

@@ -0,0 +1,147 @@
+/**
+ * Ear-clipping triangulation of a simple polygon (`triangulate`), the cap step of `extrude` and
+ * the whole of `polygon`. Pure arithmetic over x, y pairs.
+ */
+/** Twice the signed area of a profile: positive counter-clockwise, negative clockwise. */
+export function profileArea2(profile) {
+    const n = profile.length >> 1;
+    let a = 0;
+    for (let i = 0, j = n - 1; i < n; j = i++) {
+        a += profile[j * 2] * profile[i * 2 + 1] - profile[i * 2] * profile[j * 2 + 1];
+    }
+    return a;
+}
+function cross(ax, ay, bx, by, cx, cy) {
+    return (bx - ax) * (cy - ay) - (by - ay) * (cx - ax);
+}
+/** `p` strictly inside, or on the edge of, triangle `a b c` (counter-clockwise). */
+function inTriangle(ax, ay, bx, by, cx, cy, px, py) {
+    return (cross(ax, ay, bx, by, px, py) >= 0 &&
+        cross(bx, by, cx, cy, px, py) >= 0 &&
+        cross(cx, cy, ax, ay, px, py) >= 0);
+}
+/**
+ * Triangulate a simple polygon by ear clipping: up to `n - 2` triangles over the profile's vertex
+ * indices, wound counter-clockwise in the profile's plane whatever its input winding. Concave
+ * outlines are handled; collinear or repeated points are dropped as zero-area ears (so fewer
+ * triangles come back). Self-intersection detection is out of scope: a self-intersecting outline
+ * still triangulates completely, but which side is "inside" is undefined there. `Uint16Array` up
+ * to 65535 points, `Uint32Array` past it. Fewer than three points gives an empty array. Cost is
+ * O(n · r) for r reflex (inward-turning) corners, so convex outlines fan in O(n); a huge outline
+ * whose corners jitter in and out of convexity (float32 rounding on a 70000-gon) is quadratic.
+ */
+export function triangulate(profile) {
+    const n = profile.length >> 1;
+    const triCount = Math.max(0, n - 2);
+    const out = n > 0xffff ? new Uint32Array(triCount * 3) : new Uint16Array(triCount * 3);
+    if (n < 3)
+        return out;
+    // Doubly linked ring over the vertex indices, in counter-clockwise order.
+    const ccw = profileArea2(profile) >= 0;
+    const next = new Int32Array(n);
+    const prev = new Int32Array(n);
+    for (let k = 0; k < n; k++) {
+        const i = ccw ? k : n - 1 - k;
+        const iNext = ccw ? (k + 1) % n : n - 1 - ((k + 1) % n);
+        next[i] = iNext;
+        prev[iNext] = i;
+    }
+    const x = (i) => profile[i * 2];
+    const y = (i) => profile[i * 2 + 1];
+    // Reflex vertices (an inward turn) are the only ones that can sit inside a candidate ear, so
+    // the containment test skips the others; a convex outline has none and fans in O(n).
+    const reflex = new Uint8Array(n);
+    let reflexCount = 0;
+    for (let i = 0; i < n; i++) {
+        const a = prev[i];
+        const c = next[i];
+        if (cross(x(a), y(a), x(i), y(i), x(c), y(c)) < 0) {
+            reflex[i] = 1;
+            reflexCount++;
+        }
+    }
+    const updateReflex = (i) => {
+        const was = reflex[i];
+        const a = prev[i];
+        const c = next[i];
+        const now = cross(x(a), y(a), x(i), y(i), x(c), y(c)) < 0 ? 1 : 0;
+        if (was !== now) {
+            reflex[i] = now;
+            reflexCount += now - was;
+        }
+    };
+    let remaining = n;
+    let o = 0;
+    let cur = ccw ? 0 : n - 1;
+    let guard = 0;
+    while (remaining > 3) {
+        const a = prev[cur];
+        const b = cur;
+        const c = next[cur];
+        const area = cross(x(a), y(a), x(b), y(b), x(c), y(c));
+        let ear = false;
+        if (Math.abs(area) <= 1e-12 * (1 + Math.abs(x(a)) + Math.abs(y(a)))) {
+            // Collinear or repeated: a zero-area ear, dropped without a triangle.
+            next[a] = c;
+            prev[c] = a;
+            if (reflex[b])
+                reflexCount--;
+            remaining--;
+            updateReflex(a);
+            updateReflex(c);
+            cur = c;
+            guard = 0;
+            continue;
+        }
+        if (area > 0) {
+            ear = true;
+            for (let p = next[c]; reflexCount > 0 && p !== a; p = next[p]) {
+                if (reflex[p] === 1 &&
+                    (x(p) !== x(a) || y(p) !== y(a)) &&
+                    (x(p) !== x(b) || y(p) !== y(b)) &&
+                    (x(p) !== x(c) || y(p) !== y(c)) &&
+                    inTriangle(x(a), y(a), x(b), y(b), x(c), y(c), x(p), y(p))) {
+                    ear = false;
+                    break;
+                }
+            }
+        }
+        if (ear) {
+            out[o++] = a;
+            out[o++] = b;
+            out[o++] = c;
+            next[a] = c;
+            prev[c] = a;
+            remaining--;
+            updateReflex(a);
+            updateReflex(c);
+            cur = a;
+            guard = 0;
+        }
+        else {
+            cur = c;
+            // A full loop without an ear: the outline is not simple; clip anyway so the fan completes.
+            if (++guard > remaining) {
+                out[o++] = a;
+                out[o++] = b;
+                out[o++] = c;
+                next[a] = c;
+                prev[c] = a;
+                if (reflex[b])
+                    reflexCount--;
+                remaining--;
+                updateReflex(a);
+                updateReflex(c);
+                cur = a;
+                guard = 0;
+            }
+        }
+    }
+    if (remaining === 3) {
+        out[o++] = prev[cur];
+        out[o++] = cur;
+        out[o++] = next[cur];
+    }
+    // Dropped degenerate ears leave fewer triangles than n - 2: trim to what was written.
+    return o < out.length ? out.slice(0, o) : out;
+}

package/dist/host/default.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The host engine modules use when the caller passes none (`createSaveStore`, `listSlots`,
+ * `persistMixer`, `externalLink`): a web host, made on first use. A shell that is not the
+ * browser (Electron) calls `setDefaultHost` before anything else runs. Games should still pass
+ * their host explicitly.
+ */
+import type { Host } from './types.js';
+export declare function defaultHost(): Host;
+/** Replaces the default host (null: a fresh web host on next use). */
+export declare function setDefaultHost(host: Host | null): void;

package/dist/host/default.js

@@ -0,0 +1,10 @@
+import { createWebHost } from './web.js';
+let current = null;
+export function defaultHost() {
+    current ??= createWebHost();
+    return current;
+}
+/** Replaces the default host (null: a fresh web host on next use). */
+export function setDefaultHost(host) {
+    current = host;
+}

package/dist/host/index.d.ts

@@ -0,0 +1,4 @@
+export { defaultHost, setDefaultHost } from './default.js';
+export type { FrameSource, HapticImpact, HapticNotification, Host, HostFullscreen, HostHaptics, HostInsets, HostKind, HostLifecycle, HostLifecycleState, HostSafeArea, HostStorage, HostWindow, } from './types.js';
+export { createWebHaptics, createWebHost, createWebLifecycle, createWebSafeArea, type WebHostOptions, } from './web.js';
+export { createXrHost, type XrHost } from './xr.js';

package/dist/host/index.js

@@ -0,0 +1,3 @@
+export { defaultHost, setDefaultHost } from './default.js';
+export { createWebHaptics, createWebHost, createWebLifecycle, createWebSafeArea, } from './web.js';
+export { createXrHost } from './xr.js';

package/dist/host/types.d.ts

@@ -0,0 +1,144 @@
+/**
+ * The host: what the page or shell the game runs in can do for it (D-041, ARCHITECTURE.md
+ * "Host"). The engine reaches the outside world only through this: frame scheduling, opening a
+ * link, copying text, fullscreen, and where saves are kept. `createWebHost()` (host/web.ts) is the browser,
+ * at top level or in a frame such as itch.io's; `createElectronHost()` (`@thunderclap-engine/host-electron`)
+ * satisfies the same interface through a preload bridge and adds `window`;
+ * `createCapacitorHost()` (`@thunderclap-engine/host-capacitor`) fills it from Capacitor's plugins for a
+ * store app; `createXrHost()` (host/xr.ts) takes frames from an XR session and delegates the
+ * rest to the host it wraps. The optional facets `lifecycle`, `haptics` and `safeArea` (ws/host-mobile) are what
+ * a mobile shell adds and the web host can also answer.
+ */
+import type { CopyResult, EmbedContext, LinkActivation, OpenResult } from '../platform/links.js';
+import type { StorageLike } from '../save/storage.js';
+/** Which implementation this is. */
+export type HostKind = 'web' | 'electron' | 'xr' | 'capacitor';
+/**
+ * Where saves are kept. `open()` returns a working backend right now, or null when there is
+ * none (missing, blocked by the browser, or failing a round-trip). It never throws and it
+ * probes on every call, so a caller that got null can try again later (the save store does,
+ * on each write). Writes may still throw (quota); `engine/save` handles that.
+ */
+export interface HostStorage {
+    /** `local`: the web host's `localStorage`. Other hosts name their own. */
+    readonly kind: string;
+    open(): StorageLike | null;
+}
+/** Fullscreen for the game's page or window. */
+export interface HostFullscreen {
+    /** True when going fullscreen can work here (false on iPhone Safari, or in a frame without `allowfullscreen`). */
+    available(): boolean;
+    /** True while fullscreen (a getter: read it each time). */
+    readonly active: boolean;
+    /**
+     * Enters or leaves fullscreen; call it inside a tap or click. `lockLandscape` also asks for
+     * landscape where the platform allows it. Resolves to whether it is fullscreen afterwards;
+     * a refusal leaves things as they were and never rejects.
+     */
+    toggle(opts?: {
+        lockLandscape?: boolean;
+    }): Promise<boolean>;
+    /** Calls `fn` when fullscreen starts or ends. Returns unsubscribe. */
+    watch(fn: (on: boolean) => void): () => void;
+}
+/** Window controls a desktop shell offers. The web host has none. */
+export interface HostWindow {
+    close(): void;
+    minimize?(): void;
+    toggleMaximize?(): void;
+    /** Sets the window's title bar text. */
+    setTitle?(title: string): void;
+}
+/** Whether the app is in front of the player or paged out (a hidden tab, a backgrounded app). */
+export type HostLifecycleState = 'active' | 'background';
+/**
+ * The app's lifecycle (ws/host-mobile). `createGame` stops requesting frames and flushes the
+ * save on `background` and starts them again on `active`; a game autosaves from
+ * `hooks.lifecycle`. The web host reads it from `visibilitychange` and `pagehide`/`pageshow`; a
+ * store app's host reads it from the shell (Capacitor's `appStateChange`).
+ */
+export interface HostLifecycle {
+    /**
+     * The state now (a getter, E-036: read it each time). Before ws/core-8 this was a method,
+     * `state()`; a custom host writes it as a getter.
+     */
+    readonly state: HostLifecycleState;
+    /** Calls `fn` on every change (never twice with the same state). Returns unsubscribe. */
+    watch(fn: (state: HostLifecycleState) => void): () => void;
+}
+export type HapticImpact = 'light' | 'medium' | 'heavy';
+export type HapticNotification = 'success' | 'warning' | 'error';
+/**
+ * Haptic feedback. Every call is fire-and-forget and safe when `available()` is false (it does
+ * nothing). The web host maps everything onto `navigator.vibrate`; a store app's host onto the
+ * platform's haptics engine.
+ */
+export interface HostHaptics {
+    /** True when the device can produce any haptic at all. */
+    available(): boolean;
+    /** A short tap of the given weight, for a press or a landing. */
+    impact(style: HapticImpact): void;
+    /** A patterned buzz for an outcome. */
+    notification(kind: HapticNotification): void;
+    /** A plain vibration of `ms` milliseconds. */
+    vibrate(ms: number): void;
+}
+/** Safe-area insets in CSS px: what a notch, a home indicator or rounded corners cover. */
+export interface HostInsets {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+/**
+ * The viewport's safe-area insets, CSS px. The UI layout pads its regions by them
+ * (`followSafeArea` in `ui/layout`). The web host reads `env(safe-area-inset-*)` and re-reads
+ * on resize.
+ */
+export interface HostSafeArea {
+    /** The insets now. The object is reused: copy it to keep it. */
+    insets(): Readonly<HostInsets>;
+    /** Calls `fn` when the insets change (a rotation, a resize). Returns unsubscribe. */
+    watch(fn: (insets: Readonly<HostInsets>) => void): () => void;
+}
+/**
+ * Where frames come from: the display's refresh (`requestAnimationFrame` in a browser), a
+ * test's manual stepping, or an XR session's `requestAnimationFrame` (`createXrHost`). `GameLoop` schedules
+ * every frame through this, never through the globals.
+ */
+export interface FrameSource {
+    /**
+     * Calls `cb(timeMs)` once, at the next frame, with the frame's timestamp in ms on the same
+     * clock as `performance.now()`. Returns a handle for `cancelFrame`.
+     */
+    requestFrame(cb: (timeMs: number) => void): number;
+    /** Drops a pending request; a handle already run or cancelled is ignored. */
+    cancelFrame(handle: number): void;
+}
+export interface Host extends FrameSource {
+    readonly kind: HostKind;
+    /** Where the page runs: top level, or framed by the same or another origin (itch.io). */
+    readonly embed: EmbedContext;
+    /**
+     * Opens `url` (a plain `https:` link, else `invalid`) outside the game. `activation` says how
+     * the player asked: `pointer` and `keyboard` are real gestures, `gamepad` and `script` are
+     * not, so the open may come back `blocked` (then show the URL for copying instead).
+     */
+    openExternal(url: string, opts: {
+        activation: LinkActivation;
+    }): OpenResult;
+    /** Copies `text`; `manual` means every method failed (show it for copying by hand). */
+    copyText(text: string): Promise<CopyResult>;
+    /** False when the platform rules out writing the clipboard directly (itch's frame policy). */
+    clipboardWriteAllowed(): boolean;
+    readonly fullscreen: HostFullscreen;
+    readonly storage: HostStorage;
+    /** Desktop window controls, when the host has a window of its own. */
+    readonly window?: HostWindow;
+    /** The app's foreground/background state, when the host can tell (web and capacitor do; the XR host passes on its base host's). */
+    readonly lifecycle?: HostLifecycle;
+    /** Haptic feedback, when the host offers any (`available()` says whether the device does). */
+    readonly haptics?: HostHaptics;
+    /** The viewport's safe-area insets, when the host can measure them. */
+    readonly safeArea?: HostSafeArea;
+}

package/dist/host/types.js

@@ -0,0 +1 @@
+export {};

package/dist/host/web-links.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The web host's link service (D-036): opening and copying. Reached through `Host.openExternal`
+ * and `Host.copyText` (createWebHost); nothing else in the engine calls `window.open` or the
+ * clipboard.
+ *
+ * Rules: nothing here runs on its own (call it from a player action), and nothing is fetched.
+ *
+ * Facts this is built on (docs/research/itch-webgpu.md, "Clipboard and popups"):
+ * - A tab opened from a real click or key press on `<a target=_blank>` is allowed by popup
+ *   blockers. A gamepad press is not a user activation, so `window.open` from it can be blocked
+ *   (it then returns null).
+ * - Embeds may lack `clipboard-write` in the iframe's permissions policy (itch.io does:
+ *   https://github.com/itchio/itch.io/issues/1202), so Chromium rejects `clipboard.writeText`
+ *   there. `execCommand('copy')` on a selected textarea, inside the gesture, still works.
+ */
+import { type CopyResult, type LinkActivation, type OpenResult } from '../platform/links.js';
+/**
+ * Opens `url` in a new tab. With a real gesture (`pointer`/`keyboard`) it clicks a temporary
+ * `<a target=_blank rel="noopener noreferrer">`, which popup blockers allow; the browser gives no
+ * signal back, so the result is `opened`. Otherwise (`gamepad`/`script`) it uses `window.open`,
+ * whose null return means `blocked`; the opened tab's `opener` is cleared.
+ */
+export declare function openExternal(url: string, opts: {
+    activation: LinkActivation;
+}, win?: Window): OpenResult;
+/**
+ * Copies `text`: the async Clipboard API, then a hidden textarea + `execCommand('copy')`, else
+ * `manual`. Call it from the player's click or key handler; both methods need that gesture.
+ */
+export declare function copyText(text: string, win?: Window): Promise<CopyResult>;
+/**
+ * False when the frame's permissions policy rules out `clipboard-write` (itch's iframe: its
+ * `allow` list lacks it). Checked where the browser exposes the policy (Chromium), so the
+ * Clipboard API is not even tried there and no policy-violation error is logged. Elsewhere true.
+ */
+export declare function clipboardWriteAllowed(doc?: Document): boolean;
+/** `execCommand('copy')` from an off-screen textarea; focus goes back where it was. */
+export declare function execCopy(text: string, doc?: Document): boolean;

package/dist/host/web-links.js

@@ -0,0 +1,110 @@
+/**
+ * The web host's link service (D-036): opening and copying. Reached through `Host.openExternal`
+ * and `Host.copyText` (createWebHost); nothing else in the engine calls `window.open` or the
+ * clipboard.
+ *
+ * Rules: nothing here runs on its own (call it from a player action), and nothing is fetched.
+ *
+ * Facts this is built on (docs/research/itch-webgpu.md, "Clipboard and popups"):
+ * - A tab opened from a real click or key press on `<a target=_blank>` is allowed by popup
+ *   blockers. A gamepad press is not a user activation, so `window.open` from it can be blocked
+ *   (it then returns null).
+ * - Embeds may lack `clipboard-write` in the iframe's permissions policy (itch.io does:
+ *   https://github.com/itchio/itch.io/issues/1202), so Chromium rejects `clipboard.writeText`
+ *   there. `execCommand('copy')` on a selected textarea, inside the gesture, still works.
+ */
+import { safeExternalUrl, } from '../platform/links.js';
+/**
+ * Opens `url` in a new tab. With a real gesture (`pointer`/`keyboard`) it clicks a temporary
+ * `<a target=_blank rel="noopener noreferrer">`, which popup blockers allow; the browser gives no
+ * signal back, so the result is `opened`. Otherwise (`gamepad`/`script`) it uses `window.open`,
+ * whose null return means `blocked`; the opened tab's `opener` is cleared.
+ */
+export function openExternal(url, opts, win = window) {
+    const href = safeExternalUrl(url);
+    if (!href)
+        return 'invalid';
+    if (opts.activation === 'pointer' || opts.activation === 'keyboard') {
+        const doc = win.document;
+        const a = doc.createElement('a');
+        a.href = href;
+        a.target = '_blank';
+        a.rel = 'noopener noreferrer';
+        a.style.display = 'none';
+        doc.body.append(a);
+        a.click();
+        a.remove();
+        return 'opened';
+    }
+    let w = null;
+    try {
+        // Not the 'noopener' feature: with it, window.open returns null even when the tab opened.
+        w = win.open(href, '_blank');
+    }
+    catch {
+        w = null;
+    }
+    if (!w)
+        return 'blocked';
+    try {
+        w.opener = null;
+    }
+    catch {
+        // Read-only in some browsers; the tab is open either way.
+    }
+    return 'opened';
+}
+/**
+ * Copies `text`: the async Clipboard API, then a hidden textarea + `execCommand('copy')`, else
+ * `manual`. Call it from the player's click or key handler; both methods need that gesture.
+ */
+export async function copyText(text, win = window) {
+    try {
+        const clip = win.navigator.clipboard;
+        if (clip?.writeText && clipboardWriteAllowed(win.document)) {
+            await clip.writeText(text);
+            return 'copied';
+        }
+    }
+    catch {
+        // Refused (permissions policy, no focus, no gesture): try the older way.
+    }
+    return execCopy(text, win.document) ? 'copied' : 'manual';
+}
+/**
+ * False when the frame's permissions policy rules out `clipboard-write` (itch's iframe: its
+ * `allow` list lacks it). Checked where the browser exposes the policy (Chromium), so the
+ * Clipboard API is not even tried there and no policy-violation error is logged. Elsewhere true.
+ */
+export function clipboardWriteAllowed(doc = document) {
+    const d = doc;
+    const policy = d.permissionsPolicy ?? d.featurePolicy;
+    try {
+        return policy?.allowsFeature ? policy.allowsFeature('clipboard-write') : true;
+    }
+    catch {
+        return true;
+    }
+}
+/** `execCommand('copy')` from an off-screen textarea; focus goes back where it was. */
+export function execCopy(text, doc = document) {
+    const prev = doc.activeElement;
+    const ta = doc.createElement('textarea');
+    ta.value = text;
+    ta.setAttribute('readonly', '');
+    ta.setAttribute('aria-hidden', 'true');
+    ta.setAttribute('tabindex', '-1');
+    ta.style.cssText = 'position:fixed;left:-9999px;top:0;width:1px;height:1px;opacity:0;';
+    doc.body.append(ta);
+    ta.select();
+    let ok = false;
+    try {
+        ok = typeof doc.execCommand === 'function' && doc.execCommand('copy');
+    }
+    catch {
+        ok = false;
+    }
+    ta.remove();
+    prev?.focus?.({ preventScroll: true });
+    return ok;
+}

package/dist/host/web.d.ts

@@ -0,0 +1,30 @@
+import type { Host, HostHaptics, HostInsets, HostLifecycle, HostSafeArea } from './types.js';
+export interface WebHostOptions {
+    /** The window to act on. Default: the global `window`. Tests pass a stub. */
+    win?: Window;
+}
+export declare function createWebHost(opts?: WebHostOptions): Host;
+/**
+ * The page's lifecycle as a `HostLifecycle`: `background` once the document is hidden or paged
+ * out (`pagehide`, `freeze`), `active` when it is visible again (`visibilitychange`, `pageshow`,
+ * `resume`). Each watcher sees a change only when the state differs from what it last saw.
+ */
+export declare function createWebLifecycle(win: Window): HostLifecycle;
+/**
+ * Haptics over `navigator.vibrate`, when the browser has it (Android Chrome does; iOS Safari
+ * does not, so `available()` is false there and every call is a no-op). A vibrate call outside a
+ * user gesture may be refused; that is ignored.
+ */
+export declare function createWebHaptics(win: Window): HostHaptics;
+/**
+ * CSS px safe-area insets of `win`'s viewport, read through a probe element padded with
+ * `env(safe-area-inset-*)` (the `--tc-safe-*` custom properties override them, for emulation).
+ * Zero when the document has no body yet or the window cannot compute styles.
+ */
+export declare function readSafeAreaInsets(win: Window, out: HostInsets): HostInsets;
+/**
+ * The viewport's safe area as a `HostSafeArea`. `insets()` reads the page once and then serves
+ * the cached values until a `resize` (or `orientationchange`) invalidates them; watchers are
+ * called after a resize only when a value changed.
+ */
+export declare function createWebSafeArea(win: Window): HostSafeArea;