@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/platform/device-mode.d.ts

@@ -0,0 +1,40 @@
+/** Default `phoneScale`: below this overlay scale the screen is phone-sized. Phones are 0.33–0.40, tablets 0.53+. */
+export declare const PHONE_SCALE = 0.45;
+export interface DeviceModeOptions {
+    /** Overlay scale (CSS px per design px) under which the screen counts as a phone. Default 0.45. */
+    phoneScale?: number;
+}
+export interface DeviceMode {
+    /** A phone-sized screen (see `DeviceModeOptions.phoneScale`). */
+    readonly phone: boolean;
+    /** The last input was touch. */
+    readonly touch: boolean;
+    /** Design px per CSS px (1 / overlay scale). */
+    readonly cssPx: number;
+    /** Width of each letterbox bar beside the canvas, design px (0 when it fills the width). */
+    readonly bar: number;
+    /**
+     * Design px cut off the top and bottom of the canvas when a phone fills the width (0
+     * otherwise): the visible band is `[cropT, designHeight - cropB]`.
+     */
+    readonly cropT: number;
+    readonly cropB: number;
+    onChange(fn: () => void): () => void;
+}
+/** See `DeviceModeController.setScale`. */
+export interface CropInfo {
+    readonly fitScale: number;
+    readonly top: number;
+    readonly bottom: number;
+}
+export interface DeviceModeController extends DeviceMode {
+    /**
+     * Call on every resize with the overlay scale. `barCss`: the letterbox bar each side of the
+     * canvas, CSS px. `crop` (a scene that fills the width on a phone): the contain fit's scale,
+     * which decides phone-ness so filling never flips the mode, and the CSS px cut off the top
+     * and bottom of the canvas.
+     */
+    setScale(scale: number, barCss?: number, crop?: CropInfo): void;
+    destroy(): void;
+}
+export declare function createDeviceMode(root: HTMLElement, opts?: DeviceModeOptions): DeviceModeController;

package/dist/platform/device-mode.js

@@ -0,0 +1,104 @@
+/**
+ * Phone and touch modes for a scaled overlay (interim API: Phase 2's layout regions retire it,
+ * D-041). Flags and density tokens on the overlay root, recomputed live:
+ *
+ * - `data-phone`: the design canvas is shown so small (under `phoneScale` CSS px per design px,
+ *   i.e. a phone in landscape) that design-sized text and buttons would be unreadable and
+ *   untappable, so the game should switch to a phone layout. While it is set the root carries,
+ *   in CSS px:
+ *   - `--tc-bar`: the letterbox bar beside the canvas;
+ *   - `--tc-third`: a third of the viewport width less 6 px (the widest a transient card
+ *     should grow).
+ *   Desktop and tablets never get it.
+ * - `--tc-crop-t` / `--tc-crop-b` (always set, CSS px) and `data-fill`: what is cut off the top
+ *   and bottom of the canvas when a phone fills the width instead of letterboxing (0 otherwise).
+ * - `data-touch`: the last input was a finger. A mouse press or a key switches it off again.
+ *
+ * The density tokens (`--tc-text-min`, `--tc-tap-min`) belong to the overlay's layout.
+ */
+import { isTouchOnly, watchPointerKind } from './device.js';
+/** Default `phoneScale`: below this overlay scale the screen is phone-sized. Phones are 0.33–0.40, tablets 0.53+. */
+export const PHONE_SCALE = 0.45;
+export function createDeviceMode(root, opts = {}) {
+    const phoneScale = opts.phoneScale ?? PHONE_SCALE;
+    let phone = false;
+    let touch = isTouchOnly();
+    let cssPx = 1;
+    let bar = 0;
+    let cropT = 0;
+    let cropB = 0;
+    const subs = new Set();
+    const emit = () => {
+        for (const f of subs)
+            f();
+    };
+    const applyTouch = () => root.toggleAttribute('data-touch', touch);
+    applyTouch();
+    const unwatch = watchPointerKind((k) => {
+        const t = k === 'touch';
+        if (t === touch)
+            return;
+        touch = t;
+        applyTouch();
+        emit();
+    }, root.ownerDocument);
+    return {
+        get phone() {
+            return phone;
+        },
+        get touch() {
+            return touch;
+        },
+        get cssPx() {
+            return cssPx;
+        },
+        get bar() {
+            return bar;
+        },
+        get cropT() {
+            return cropT;
+        },
+        get cropB() {
+            return cropB;
+        },
+        onChange(fn) {
+            subs.add(fn);
+            return () => subs.delete(fn);
+        },
+        setScale(scale, barCss = 0, crop) {
+            const s = scale > 0 ? scale : 1;
+            const p = (crop && crop.fitScale > 0 ? crop.fitScale : s) < phoneScale;
+            const ct = p && crop ? Math.max(0, Math.round(crop.top / s)) : 0;
+            const cb = p && crop ? Math.max(0, Math.round(crop.bottom / s)) : 0;
+            // CSS px hidden above and below the screen: top- and bottom-anchored chrome moves in by it.
+            root.style.setProperty('--tc-crop-t', `${p && crop ? Math.max(0, crop.top) : 0}px`);
+            root.style.setProperty('--tc-crop-b', `${p && crop ? Math.max(0, crop.bottom) : 0}px`);
+            root.toggleAttribute('data-fill', ct + cb > 0);
+            const b = Math.max(0, Math.round(barCss / s));
+            const resized = Math.abs(cssPx - 1 / s) > 1e-3 || b !== bar || ct !== cropT || cb !== cropB;
+            cssPx = 1 / s;
+            bar = b;
+            cropT = ct;
+            cropB = cb;
+            if (p) {
+                root.style.setProperty('--tc-bar', `${Math.max(0, barCss)}px`);
+                // A third of the screen, less a margin: the widest any transient card may grow.
+                const vw = root.ownerDocument.defaultView?.innerWidth ?? 0;
+                root.style.setProperty('--tc-third', `${Math.round(vw / 3 - 6)}px`);
+            }
+            else {
+                root.style.removeProperty('--tc-bar');
+                root.style.removeProperty('--tc-third');
+            }
+            if (p === phone && !(p && resized))
+                return;
+            phone = p;
+            root.toggleAttribute('data-phone', p);
+            emit();
+        },
+        destroy() {
+            unwatch();
+            subs.clear();
+        },
+    };
+}

package/dist/platform/device.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Phone and tablet helpers: the kind of pointer the player is using, orientation and fullscreen.
+ * DOM-only, no game nouns. Every function is safe where an API is missing (it answers "no").
+ */
+/** True when the primary pointer is a finger and no mouse or trackpad is attached. */
+export declare function isTouchOnly(): boolean;
+export type PointerKind = 'touch' | 'mouse' | 'keyboard';
+/**
+ * Calls `fn` with the device the player last used anywhere on the page (canvas, buttons or
+ * panels): a touch or pen press is `touch`, a mouse press or move is `mouse`, a key is
+ * `keyboard`. Capture-phase listeners, so a handler that stops propagation can't hide it.
+ * Returns unsubscribe.
+ */
+export declare function watchPointerKind(fn: (kind: PointerKind) => void, doc?: Document): () => void;
+/** True when the viewport is taller than it is wide. */
+export declare function isPortrait(win?: Window): boolean;
+/**
+ * True when the page may go fullscreen. iPhone Safari has no element fullscreen (only video),
+ * and an iframe needs `allowfullscreen`; both answer false here, so callers hide their button.
+ */
+export declare function fullscreenAvailable(doc?: Document): boolean;
+export declare function isFullscreen(doc?: Document): boolean;
+/**
+ * Enter or leave fullscreen (must run inside a tap or click). On entering, also asks for
+ * landscape where the browser allows it (Android Chrome); a refusal is ignored.
+ */
+export declare function toggleFullscreen(el?: HTMLElement, opts?: {
+    lockLandscape?: boolean;
+}): Promise<boolean>;
+/** Calls `fn` when fullscreen starts or ends. Returns unsubscribe. */
+export declare function watchFullscreen(fn: (on: boolean) => void, doc?: Document): () => void;

package/dist/platform/device.js

@@ -0,0 +1,91 @@
+/**
+ * Phone and tablet helpers: the kind of pointer the player is using, orientation and fullscreen.
+ * DOM-only, no game nouns. Every function is safe where an API is missing (it answers "no").
+ */
+const COARSE = '(pointer: coarse)';
+const ANY_FINE = '(any-pointer: fine)';
+/** True when the primary pointer is a finger and no mouse or trackpad is attached. */
+export function isTouchOnly() {
+    if (typeof matchMedia !== 'function')
+        return false;
+    return matchMedia(COARSE).matches && !matchMedia(ANY_FINE).matches;
+}
+/**
+ * Calls `fn` with the device the player last used anywhere on the page (canvas, buttons or
+ * panels): a touch or pen press is `touch`, a mouse press or move is `mouse`, a key is
+ * `keyboard`. Capture-phase listeners, so a handler that stops propagation can't hide it.
+ * Returns unsubscribe.
+ */
+export function watchPointerKind(fn, doc = document) {
+    const onPointer = (e) => {
+        if (e.pointerType === 'touch' || e.pointerType === 'pen')
+            fn('touch');
+        else if (e.pointerType === 'mouse' && (e.type === 'pointerdown' || e.movementX || e.movementY))
+            fn('mouse');
+    };
+    const onKey = (e) => {
+        // Modifier-only presses (a screenshot shortcut, a tab switch) don't mean "playing by keys".
+        if (e.key === 'Shift' || e.key === 'Control' || e.key === 'Meta' || e.key === 'Alt')
+            return;
+        fn('keyboard');
+    };
+    doc.addEventListener('pointerdown', onPointer, true);
+    doc.addEventListener('pointermove', onPointer, true);
+    doc.addEventListener('keydown', onKey, true);
+    return () => {
+        doc.removeEventListener('pointerdown', onPointer, true);
+        doc.removeEventListener('pointermove', onPointer, true);
+        doc.removeEventListener('keydown', onKey, true);
+    };
+}
+/** True when the viewport is taller than it is wide. */
+export function isPortrait(win = window) {
+    return win.innerHeight > win.innerWidth;
+}
+/**
+ * True when the page may go fullscreen. iPhone Safari has no element fullscreen (only video),
+ * and an iframe needs `allowfullscreen`; both answer false here, so callers hide their button.
+ */
+export function fullscreenAvailable(doc = document) {
+    const d = doc;
+    const el = doc.documentElement;
+    const enabled = d.fullscreenEnabled ?? d.webkitFullscreenEnabled ?? false;
+    return !!enabled && (!!el.requestFullscreen || !!el.webkitRequestFullscreen);
+}
+export function isFullscreen(doc = document) {
+    const d = doc;
+    return !!(d.fullscreenElement ?? d.webkitFullscreenElement);
+}
+/**
+ * Enter or leave fullscreen (must run inside a tap or click). On entering, also asks for
+ * landscape where the browser allows it (Android Chrome); a refusal is ignored.
+ */
+export async function toggleFullscreen(el = document.documentElement, opts = {}) {
+    const doc = el.ownerDocument;
+    try {
+        if (isFullscreen(doc)) {
+            await (doc.exitFullscreen?.() ?? doc.webkitExitFullscreen?.());
+            return false;
+        }
+        const f = el;
+        await (f.requestFullscreen?.({ navigationUI: 'hide' }) ?? f.webkitRequestFullscreen?.());
+        if (opts.lockLandscape) {
+            const o = screen.orientation;
+            await o?.lock?.('landscape').catch(() => { });
+        }
+    }
+    catch {
+        // Refused (no gesture, iframe without permission): stay as we are.
+    }
+    return isFullscreen(doc);
+}
+/** Calls `fn` when fullscreen starts or ends. Returns unsubscribe. */
+export function watchFullscreen(fn, doc = document) {
+    const h = () => fn(isFullscreen(doc));
+    doc.addEventListener('fullscreenchange', h);
+    doc.addEventListener('webkitfullscreenchange', h);
+    return () => {
+        doc.removeEventListener('fullscreenchange', h);
+        doc.removeEventListener('webkitfullscreenchange', h);
+    };
+}

package/dist/platform/environment.d.ts

@@ -0,0 +1,42 @@
+/** Page visibility + user-preference helpers. */
+/** Calls `fn(visible)` whenever the tab is hidden/shown. Returns unsubscribe. */
+export declare function watchVisibility(fn: (visible: boolean) => void): () => void;
+/** True when the player asked the OS for reduced motion. `win` defaults to the global window. */
+export declare function isReducedMotion(win?: Window): boolean;
+/** What the device looks like from the page: enough to pick sensible defaults, not to sniff. */
+export interface DeviceTraits {
+    /** The primary pointer is coarse (a finger). */
+    coarsePointer: boolean;
+    /** The screen's shorter side in CSS px (`screen.width/height`, orientation-independent). */
+    shortSide: number;
+    /**
+     * A phone-sized touch device: coarse pointer and a screen whose short side is at most
+     * `HANDHELD_SHORT_SIDE` CSS px. Phones have small batteries, tiled GPUs and throttle when
+     * hot, so callers pick lighter defaults. Tablets (short side 744+) are not handheld.
+     */
+    handheld: boolean;
+}
+/** The largest phones are ~440 CSS px on the short side; the smallest tablets ~744. */
+export declare const HANDHELD_SHORT_SIDE = 600;
+export declare function deviceTraits(): DeviceTraits;
+export interface LifecycleHandlers {
+    /**
+     * The page is going into the background or away: `visibilitychange` to hidden, `pagehide`
+     * (iOS app switch, closing the tab, bfcache) or `freeze` (Chrome on Android freezing a
+     * background tab, which it may later discard with no further event). Stop work and persist
+     * here: it may be the last chance. Can fire several times in a row (hidden, pagehide, freeze).
+     */
+    onHide(reason: 'hidden' | 'pagehide' | 'freeze'): void;
+    /** The page is back and visible (`visibilitychange`, `pageshow`, `resume`). */
+    onShow(reason: 'visible' | 'pageshow' | 'resume'): void;
+}
+/**
+ * A game is input, not a document: stop double-tap, pinch and trackpad smart-zoom (and
+ * ctrl+wheel) from zooming the page. Keyboard zoom (Cmd/Ctrl +/-) is left alone for
+ * accessibility. Returns unsubscribe.
+ */
+export declare function blockBrowserZoom(doc?: Document): () => void;
+/** Page lifecycle across the events phones actually send. Returns unsubscribe. */
+export declare function watchLifecycle(h: LifecycleHandlers): () => void;
+/** Calls `fn(reduced)` when the reduced-motion preference changes. Returns unsubscribe. */
+export declare function watchReducedMotion(fn: (reduced: boolean) => void): () => void;

package/dist/platform/environment.js

@@ -0,0 +1,82 @@
+/** Page visibility + user-preference helpers. */
+/** Calls `fn(visible)` whenever the tab is hidden/shown. Returns unsubscribe. */
+export function watchVisibility(fn) {
+    const h = () => fn(document.visibilityState === 'visible');
+    document.addEventListener('visibilitychange', h);
+    return () => document.removeEventListener('visibilitychange', h);
+}
+const REDUCED = '(prefers-reduced-motion: reduce)';
+/** True when the player asked the OS for reduced motion. `win` defaults to the global window. */
+export function isReducedMotion(win) {
+    const mm = win ? win.matchMedia : typeof matchMedia === 'function' ? matchMedia : undefined;
+    return typeof mm === 'function' && mm.call(win ?? globalThis, REDUCED).matches;
+}
+/** The largest phones are ~440 CSS px on the short side; the smallest tablets ~744. */
+export const HANDHELD_SHORT_SIDE = 600;
+export function deviceTraits() {
+    const coarsePointer = typeof matchMedia === 'function' && matchMedia('(pointer: coarse)').matches;
+    const s = typeof screen !== 'undefined' ? screen : null;
+    const shortSide = s ? Math.min(s.width, s.height) : 0;
+    return {
+        coarsePointer,
+        shortSide,
+        handheld: coarsePointer && shortSide > 0 && shortSide <= HANDHELD_SHORT_SIDE,
+    };
+}
+/**
+ * A game is input, not a document: stop double-tap, pinch and trackpad smart-zoom (and
+ * ctrl+wheel) from zooming the page. Keyboard zoom (Cmd/Ctrl +/-) is left alone for
+ * accessibility. Returns unsubscribe.
+ */
+export function blockBrowserZoom(doc = document) {
+    const block = (e) => e.preventDefault();
+    const wheel = (e) => {
+        if (e.ctrlKey)
+            e.preventDefault();
+    };
+    const types = ['gesturestart', 'gesturechange', 'dblclick'];
+    for (const t of types)
+        doc.addEventListener(t, block, { passive: false });
+    doc.addEventListener('wheel', wheel, { passive: false });
+    return () => {
+        for (const t of types)
+            doc.removeEventListener(t, block);
+        doc.removeEventListener('wheel', wheel);
+    };
+}
+/** Page lifecycle across the events phones actually send. Returns unsubscribe. */
+export function watchLifecycle(h) {
+    const visible = () => document.visibilityState === 'visible';
+    const onVis = () => (visible() ? h.onShow('visible') : h.onHide('hidden'));
+    const onPageHide = () => h.onHide('pagehide');
+    const onPageShow = () => {
+        if (visible())
+            h.onShow('pageshow');
+    };
+    const onFreeze = () => h.onHide('freeze');
+    const onResume = () => {
+        if (visible())
+            h.onShow('resume');
+    };
+    document.addEventListener('visibilitychange', onVis);
+    window.addEventListener('pagehide', onPageHide);
+    window.addEventListener('pageshow', onPageShow);
+    document.addEventListener('freeze', onFreeze);
+    document.addEventListener('resume', onResume);
+    return () => {
+        document.removeEventListener('visibilitychange', onVis);
+        window.removeEventListener('pagehide', onPageHide);
+        window.removeEventListener('pageshow', onPageShow);
+        document.removeEventListener('freeze', onFreeze);
+        document.removeEventListener('resume', onResume);
+    };
+}
+/** Calls `fn(reduced)` when the reduced-motion preference changes. Returns unsubscribe. */
+export function watchReducedMotion(fn) {
+    if (typeof matchMedia !== 'function')
+        return () => { };
+    const mq = matchMedia(REDUCED);
+    const h = () => fn(mq.matches);
+    mq.addEventListener('change', h);
+    return () => mq.removeEventListener('change', h);
+}

package/dist/platform/gpu.d.ts

@@ -0,0 +1,40 @@
+/** WebGPU capability check + device creation. */
+export interface GpuContext {
+    adapter: GPUAdapter;
+    device: GPUDevice;
+    context: GPUCanvasContext;
+    /** Preferred swapchain format (bgra8unorm or rgba8unorm). */
+    format: GPUTextureFormat;
+    /**
+     * The device has `timestamp-query`, so GPU pass times can be measured directly
+     * (`@thunderclap-engine/engine/render` `GpuTimer`). Without it, timing falls back to submit → done.
+     */
+    timestamps: boolean;
+}
+export type GpuFailureReason = 'no-api' | 'no-adapter' | 'no-device' | 'no-context';
+export type GpuInitResult = {
+    ok: true;
+    gpu: GpuContext;
+} | {
+    ok: false;
+    reason: GpuFailureReason;
+    detail?: string;
+};
+export interface GpuInitOptions {
+    powerPreference?: GPUPowerPreference;
+    /** Called when the device is lost for any reason other than an explicit `destroy()`. */
+    onLost?: (info: GPUDeviceLostInfo) => void;
+    /** Ask for `timestamp-query` when the adapter has it. Default true. */
+    timestamps?: boolean;
+    /**
+     * Ask for the adapter's texture-compression features (`compressionFeatures(adapter)`:
+     * `texture-compression-bc`, `-etc2`, `-astc`), so `renderer.caps.compressed` reports what the
+     * adapter can upload without a second device (ws/render-6). Default true.
+     */
+    compression?: boolean;
+}
+/**
+ * Request an adapter + device and configure the canvas. Never throws: failures come back as
+ * `{ ok: false, reason }` so the caller can show the unsupported screen.
+ */
+export declare function initGpu(canvas: HTMLCanvasElement, opts?: GpuInitOptions): Promise<GpuInitResult>;

package/dist/platform/gpu.js

@@ -0,0 +1,57 @@
+/** WebGPU capability check + device creation. */
+import { compressionFeatures } from '../render/compressed.js';
+/**
+ * Request an adapter + device and configure the canvas. Never throws: failures come back as
+ * `{ ok: false, reason }` so the caller can show the unsupported screen.
+ */
+export async function initGpu(canvas, opts = {}) {
+    const gpu = navigator.gpu;
+    if (!gpu)
+        return { ok: false, reason: 'no-api' };
+    let adapter = null;
+    try {
+        adapter = await gpu.requestAdapter({
+            powerPreference: opts.powerPreference ?? 'high-performance',
+        });
+    }
+    catch (e) {
+        return { ok: false, reason: 'no-adapter', detail: String(e) };
+    }
+    if (!adapter)
+        return { ok: false, reason: 'no-adapter' };
+    // Optional features: requested only when the adapter offers them, so a device without
+    // them still comes up (and a refused request retries without any).
+    const wanted = [];
+    if ((opts.timestamps ?? true) && adapter.features.has('timestamp-query')) {
+        wanted.push('timestamp-query');
+    }
+    if (opts.compression ?? true)
+        wanted.push(...compressionFeatures(adapter));
+    let device;
+    try {
+        device = await adapter.requestDevice({ label: 'engine-device', requiredFeatures: wanted });
+    }
+    catch (e) {
+        if (wanted.length === 0)
+            return { ok: false, reason: 'no-device', detail: String(e) };
+        try {
+            device = await adapter.requestDevice({ label: 'engine-device' });
+        }
+        catch (e2) {
+            return { ok: false, reason: 'no-device', detail: String(e2) };
+        }
+    }
+    const timestamps = device.features.has('timestamp-query');
+    device.lost.then((info) => {
+        if (info.reason === 'destroyed')
+            return;
+        console.error(`[gpu] device lost: ${info.reason} ${info.message}`);
+        opts.onLost?.(info);
+    });
+    const context = canvas.getContext('webgpu');
+    if (!context)
+        return { ok: false, reason: 'no-context' };
+    const format = gpu.getPreferredCanvasFormat();
+    context.configure({ device, format, alphaMode: 'opaque' });
+    return { ok: true, gpu: { adapter, device, context, format, timestamps } };
+}

package/dist/platform/index.d.ts

@@ -0,0 +1,18 @@
+export type { BootOptions, BootResult } from './boot.js';
+export { boot } from './boot.js';
+export type { PointerKind } from './device.js';
+export { fullscreenAvailable, isFullscreen, isPortrait, isTouchOnly, toggleFullscreen, watchFullscreen, watchPointerKind, } from './device.js';
+export { type CropInfo, createDeviceMode, type DeviceMode, type DeviceModeController, type DeviceModeOptions, PHONE_SCALE, } from './device-mode.js';
+export type { DeviceTraits, LifecycleHandlers } from './environment.js';
+export { blockBrowserZoom, deviceTraits, HANDHELD_SHORT_SIDE, isReducedMotion, watchLifecycle, watchReducedMotion, watchVisibility, } from './environment.js';
+export type { GpuContext, GpuFailureReason, GpuInitOptions, GpuInitResult } from './gpu.js';
+export { initGpu } from './gpu.js';
+export type { BackbufferSize, Letterbox, LetterboxRect, Vec2 } from './letterbox.js';
+export { clientToLogical, computeBackbuffer, computeLetterbox, logicalToClient, } from './letterbox.js';
+export type { CopyResult, EmbedContext, LinkActivation, OpenResult } from './links.js';
+export { embedContext, safeExternalUrl } from './links.js';
+export type { MessageScreenAction, MessageScreenOptions, PlatformFamily } from './screens.js';
+export { platformFamily, showDeviceLostScreen, showMessageScreen, showUnsupportedScreen, } from './screens.js';
+export type { SurfaceOptions, SurfaceSize } from './surface.js';
+export { mountSurface, Surface } from './surface.js';
+export { type XrEyeView, XrSurface, type XrSurfaceOptions } from './xr-surface.js';

package/dist/platform/index.js

@@ -0,0 +1,10 @@
+export { boot } from './boot.js';
+export { fullscreenAvailable, isFullscreen, isPortrait, isTouchOnly, toggleFullscreen, watchFullscreen, watchPointerKind, } from './device.js';
+export { createDeviceMode, PHONE_SCALE, } from './device-mode.js';
+export { blockBrowserZoom, deviceTraits, HANDHELD_SHORT_SIDE, isReducedMotion, watchLifecycle, watchReducedMotion, watchVisibility, } from './environment.js';
+export { initGpu } from './gpu.js';
+export { clientToLogical, computeBackbuffer, computeLetterbox, logicalToClient, } from './letterbox.js';
+export { embedContext, safeExternalUrl } from './links.js';
+export { platformFamily, showDeviceLostScreen, showMessageScreen, showUnsupportedScreen, } from './screens.js';
+export { mountSurface, Surface } from './surface.js';
+export { XrSurface } from './xr-surface.js';

package/dist/platform/letterbox.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Pure letterbox + coordinate math. No DOM, so it is unit-testable in Node.
+ *
+ * Terms:
+ * - "client" = CSS pixels relative to the container's top-left corner.
+ * - "logical" = the fixed design space (default 1920×1080), origin top-left, y down.
+ * - "backbuffer" = physical pixels of the canvas drawing buffer.
+ */
+export interface LetterboxRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Letterboxed viewport inside a container, in client (CSS) pixels. */
+export interface Letterbox extends LetterboxRect {
+    /** CSS pixels per logical unit. */
+    scale: number;
+}
+export interface Vec2 {
+    x: number;
+    y: number;
+}
+/**
+ * Fit a logicalW×logicalH design space into a container, preserving aspect ratio and centring
+ * it. Size is snapped to whole CSS pixels so the canvas edges stay crisp.
+ */
+export declare function computeLetterbox(containerW: number, containerH: number, logicalW: number, logicalH: number): Letterbox;
+/** Map a client point (CSS px relative to the container) into logical space. */
+export declare function clientToLogical(box: LetterboxRect, logicalW: number, logicalH: number, cx: number, cy: number, out?: Vec2): Vec2;
+/** Map a logical point back to client CSS px relative to the container. */
+export declare function logicalToClient(box: LetterboxRect, logicalW: number, logicalH: number, lx: number, ly: number, out?: Vec2): Vec2;
+export interface BackbufferSize {
+    width: number;
+    height: number;
+    /** Effective pixel ratio actually used (after caps). */
+    pixelRatio: number;
+}
+/**
+ * Choose drawing-buffer size for a CSS rect: devicePixelRatio, capped by `maxDpr`, then scaled
+ * down further if the total pixel count would exceed `maxPixels` (perf budget on iGPUs).
+ */
+export declare function computeBackbuffer(cssW: number, cssH: number, devicePixelRatio: number, maxDpr?: number, maxPixels?: number): BackbufferSize;

package/dist/platform/letterbox.js

@@ -0,0 +1,57 @@
+/**
+ * Pure letterbox + coordinate math. No DOM, so it is unit-testable in Node.
+ *
+ * Terms:
+ * - "client" = CSS pixels relative to the container's top-left corner.
+ * - "logical" = the fixed design space (default 1920×1080), origin top-left, y down.
+ * - "backbuffer" = physical pixels of the canvas drawing buffer.
+ */
+/**
+ * Fit a logicalW×logicalH design space into a container, preserving aspect ratio and centring
+ * it. Size is snapped to whole CSS pixels so the canvas edges stay crisp.
+ */
+export function computeLetterbox(containerW, containerH, logicalW, logicalH) {
+    if (!(containerW > 0) || !(containerH > 0) || !(logicalW > 0) || !(logicalH > 0)) {
+        return { x: 0, y: 0, width: 0, height: 0, scale: 0 };
+    }
+    const fit = Math.min(containerW / logicalW, containerH / logicalH);
+    const width = Math.max(1, Math.min(containerW, Math.round(logicalW * fit)));
+    const height = Math.max(1, Math.min(containerH, Math.round(logicalH * fit)));
+    const x = Math.floor((containerW - width) / 2);
+    const y = Math.floor((containerH - height) / 2);
+    return { x, y, width, height, scale: width / logicalW };
+}
+/** Map a client point (CSS px relative to the container) into logical space. */
+export function clientToLogical(box, logicalW, logicalH, cx, cy, out = { x: 0, y: 0 }) {
+    if (box.width <= 0 || box.height <= 0) {
+        out.x = 0;
+        out.y = 0;
+        return out;
+    }
+    out.x = ((cx - box.x) / box.width) * logicalW;
+    out.y = ((cy - box.y) / box.height) * logicalH;
+    return out;
+}
+/** Map a logical point back to client CSS px relative to the container. */
+export function logicalToClient(box, logicalW, logicalH, lx, ly, out = { x: 0, y: 0 }) {
+    out.x = box.x + (lx / logicalW) * box.width;
+    out.y = box.y + (ly / logicalH) * box.height;
+    return out;
+}
+/**
+ * Choose drawing-buffer size for a CSS rect: devicePixelRatio, capped by `maxDpr`, then scaled
+ * down further if the total pixel count would exceed `maxPixels` (perf budget on iGPUs).
+ */
+export function computeBackbuffer(cssW, cssH, devicePixelRatio, maxDpr = 2, maxPixels = Number.POSITIVE_INFINITY) {
+    if (!(cssW > 0) || !(cssH > 0))
+        return { width: 1, height: 1, pixelRatio: 1 };
+    let ratio = Math.min(Math.max(devicePixelRatio || 1, 0.25), maxDpr);
+    const px = cssW * ratio * cssH * ratio;
+    if (px > maxPixels)
+        ratio *= Math.sqrt(maxPixels / px);
+    return {
+        width: Math.max(1, Math.round(cssW * ratio)),
+        height: Math.max(1, Math.round(cssH * ratio)),
+        pixelRatio: ratio,
+    };
+}

package/dist/platform/links.d.ts

@@ -0,0 +1,20 @@
+/**
+ * External links (D-036): URL validation, embed detection and the result types. Opening and
+ * copying are host services: `Host.openExternal` and `Host.copyText` (engine/host; the web
+ * implementation is host/web-links.ts). The widget is `externalLink` in engine/ui.
+ */
+/** How the player asked for the link: a real gesture (pointer/keyboard) or not (gamepad/script). */
+export type LinkActivation = 'pointer' | 'keyboard' | 'gamepad' | 'script';
+/** `invalid`: the URL failed `safeExternalUrl`, so nothing was attempted. */
+export type OpenResult = 'opened' | 'blocked' | 'invalid';
+/** `manual`: every copy method failed; show the URL for the player to copy by hand. */
+export type CopyResult = 'copied' | 'manual';
+/** Where the page runs: top level, or in a frame of the same or another origin (e.g. itch.io). */
+export type EmbedContext = 'top' | 'same-origin-frame' | 'cross-origin-frame';
+/**
+ * The URL if it is a plain absolute `https:` link (no credentials, no whitespace), else null.
+ * Callers hide the control on null, so a blank or bad constant never renders a dead link.
+ */
+export declare function safeExternalUrl(url: string | null | undefined): string | null;
+/** Detects (does not assume) whether the page is framed, and whether by another origin. */
+export declare function embedContext(win?: Window): EmbedContext;