@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/platform/links.js

@@ -0,0 +1,43 @@
+/**
+ * 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.
+ */
+/**
+ * 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 function safeExternalUrl(url) {
+    const t = (url ?? '').trim();
+    if (!t || /\s/.test(t) || !/^https:\/\//i.test(t))
+        return null;
+    let u;
+    try {
+        u = new URL(t);
+    }
+    catch {
+        return null;
+    }
+    if (u.protocol !== 'https:' || !u.hostname || u.username || u.password)
+        return null;
+    return t;
+}
+/** Detects (does not assume) whether the page is framed, and whether by another origin. */
+export function embedContext(win = window) {
+    let framed;
+    try {
+        framed = win.self !== win.top;
+    }
+    catch {
+        return 'cross-origin-frame';
+    }
+    if (!framed)
+        return 'top';
+    try {
+        // Reading a cross-origin parent's location throws (or yields nothing).
+        return win.top?.location.href ? 'same-origin-frame' : 'cross-origin-frame';
+    }
+    catch {
+        return 'cross-origin-frame';
+    }
+}

package/dist/platform/screens.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Full-screen DOM message screens for fatal states (no WebGPU, device lost).
+ * Styled dark slate + gold. Text is generic; the game passes its own title.
+ */
+export interface MessageScreenAction {
+    label: string;
+    onClick: () => void;
+}
+export interface MessageScreenOptions {
+    /** Small caps line above the heading (e.g. the game's name). */
+    eyebrow?: string;
+    heading: string;
+    /** Paragraphs of body text. */
+    body: string[];
+    /** A bulleted list after the body. */
+    list?: string[];
+    /** Paragraphs after the list, in small print. */
+    footer?: string[];
+    actions?: MessageScreenAction[];
+}
+/** Show a modal message screen over `root`. Returns a function that removes it. */
+export declare function showMessageScreen(root: HTMLElement, opts: MessageScreenOptions): () => void;
+export type PlatformFamily = 'ios' | 'android' | 'desktop';
+/** The visitor's platform, for advice only (never to gate anything). */
+export declare function platformFamily(ua?: string, touchPoints?: number): PlatformFamily;
+/** "Your browser can't run this" screen: where it does run, the visitor's platform first. */
+export declare function showUnsupportedScreen(root: HTMLElement, opts?: {
+    title?: string;
+    detail?: string;
+}): () => void;
+/** GPU device lost: offer a reload. */
+export declare function showDeviceLostScreen(root: HTMLElement, opts?: {
+    title?: string;
+    detail?: string;
+    onReload?: () => void;
+}): () => void;

package/dist/platform/screens.js

@@ -0,0 +1,138 @@
+/**
+ * Full-screen DOM message screens for fatal states (no WebGPU, device lost).
+ * Styled dark slate + gold. Text is generic; the game passes its own title.
+ */
+const STYLE_ID = 'engine-message-screen-style';
+const CSS = `
+.engine-msg{position:absolute;inset:0;display:flex;align-items:center;justify-content:center;
+  background:radial-gradient(ellipse at 50% 40%,#1c2130 0%,#0b0d14 70%);z-index:1000;
+  font-family:Georgia,'Iowan Old Style','Palatino Linotype',serif;color:#d9d3c3;padding:24px;box-sizing:border-box}
+.engine-msg__card{max-width:560px;width:100%;padding:36px 40px;border:1px solid #a8863a;border-radius:10px;
+  background:linear-gradient(180deg,#191d29,#12151f);box-shadow:0 0 0 4px #0b0d14,0 0 0 5px #5a4a24,0 20px 60px #000a}
+.engine-msg__eyebrow{letter-spacing:.25em;text-transform:uppercase;font-size:12px;color:#a8863a;margin:0 0 10px}
+.engine-msg__heading{font-size:28px;line-height:1.2;margin:0 0 16px;color:#f0cf74;
+  text-shadow:0 2px 0 #4b2a6b,0 0 18px #f0cf7433}
+.engine-msg__body{font-size:16px;line-height:1.55;margin:0 0 12px}
+.engine-msg__actions{margin-top:22px;display:flex;gap:12px}
+.engine-msg__btn{font:inherit;font-size:16px;padding:10px 22px;border-radius:6px;cursor:pointer;
+  color:#1a1408;background:linear-gradient(180deg,#f5d77f,#c99a2e);border:1px solid #7a5c1a}
+.engine-msg__btn:focus-visible{outline:2px solid #f0cf74;outline-offset:3px}
+.engine-msg__list{font-size:16px;line-height:1.5;margin:0 0 12px;padding-left:1.2em}
+.engine-msg__list li{margin:0 0 6px}
+.engine-msg__small{font-size:13px;color:#9a9484;overflow-wrap:anywhere}
+@media (max-height:520px),(max-width:600px){
+  .engine-msg{align-items:flex-start;overflow-y:auto;padding:12px}
+  .engine-msg__card{padding:18px 20px;margin:auto}
+  .engine-msg__heading{font-size:22px;margin-bottom:10px}
+  .engine-msg__body,.engine-msg__list{font-size:15px;line-height:1.45;margin-bottom:8px}
+  .engine-msg__eyebrow{margin-bottom:6px}
+}
+`;
+function ensureStyle() {
+    if (document.getElementById(STYLE_ID))
+        return;
+    const s = document.createElement('style');
+    s.id = STYLE_ID;
+    s.textContent = CSS;
+    document.head.appendChild(s);
+}
+/** Show a modal message screen over `root`. Returns a function that removes it. */
+export function showMessageScreen(root, opts) {
+    ensureStyle();
+    const wrap = document.createElement('div');
+    wrap.className = 'engine-msg';
+    wrap.setAttribute('role', 'alertdialog');
+    wrap.setAttribute('aria-live', 'assertive');
+    const card = document.createElement('div');
+    card.className = 'engine-msg__card';
+    if (opts.eyebrow) {
+        const e = document.createElement('p');
+        e.className = 'engine-msg__eyebrow';
+        e.textContent = opts.eyebrow;
+        card.appendChild(e);
+    }
+    const h = document.createElement('h1');
+    h.className = 'engine-msg__heading';
+    h.textContent = opts.heading;
+    card.appendChild(h);
+    for (const para of opts.body) {
+        const p = document.createElement('p');
+        p.className = 'engine-msg__body';
+        p.textContent = para;
+        card.appendChild(p);
+    }
+    if (opts.list?.length) {
+        const ul = document.createElement('ul');
+        ul.className = 'engine-msg__list';
+        for (const item of opts.list) {
+            const li = document.createElement('li');
+            li.textContent = item;
+            ul.appendChild(li);
+        }
+        card.appendChild(ul);
+    }
+    for (const para of opts.footer ?? []) {
+        const p = document.createElement('p');
+        p.className = 'engine-msg__body engine-msg__small';
+        p.textContent = para;
+        card.appendChild(p);
+    }
+    if (opts.actions?.length) {
+        const row = document.createElement('div');
+        row.className = 'engine-msg__actions';
+        for (const a of opts.actions) {
+            const b = document.createElement('button');
+            b.className = 'engine-msg__btn';
+            b.type = 'button';
+            b.textContent = a.label;
+            b.addEventListener('click', a.onClick);
+            row.appendChild(b);
+        }
+        card.appendChild(row);
+    }
+    wrap.appendChild(card);
+    root.appendChild(wrap);
+    wrap.querySelector('button')?.focus();
+    return () => wrap.remove();
+}
+/** The visitor's platform, for advice only (never to gate anything). */
+export function platformFamily(ua = typeof navigator !== 'undefined' ? navigator.userAgent : '', touchPoints = typeof navigator !== 'undefined' ? navigator.maxTouchPoints : 0) {
+    // iPadOS asks for desktop sites and reports itself as a Mac with touch.
+    if (/iPhone|iPad|iPod/.test(ua) || (/Macintosh/.test(ua) && touchPoints > 1))
+        return 'ios';
+    if (/Android/.test(ua))
+        return 'android';
+    return 'desktop';
+}
+/** Where WebGPU runs (docs/design/mobile.md has the matrix and its sources). */
+const WHERE = {
+    ios: 'iPhone and iPad: Safari on iOS 26 or newer. Opened from inside another app? Open the link in Safari.',
+    android: 'Android: the latest Chrome on Android 12 or newer. Firefox and in-app browsers cannot run it yet, so open the link in Chrome.',
+    desktop: 'Computer: the latest Chrome or Edge, or Safari 26 or newer on a Mac. On Linux, Chrome may need hardware acceleration turned on.',
+};
+/** "Your browser can't run this" screen: where it does run, the visitor's platform first. */
+export function showUnsupportedScreen(root, opts = {}) {
+    const mine = platformFamily();
+    const others = ['ios', 'android', 'desktop'].filter((p) => p !== mine);
+    return showMessageScreen(root, {
+        eyebrow: opts.title,
+        heading: 'WebGPU is not available',
+        body: [
+            'This game draws with WebGPU, and this browser (or this device) did not give us access to it. It runs on:',
+        ],
+        list: [WHERE[mine], ...others.map((p) => WHERE[p])],
+        footer: opts.detail ? [`Details: ${opts.detail}`] : [],
+    });
+}
+/** GPU device lost: offer a reload. */
+export function showDeviceLostScreen(root, opts = {}) {
+    const body = ['The graphics device stopped responding. Your progress is saved locally.'];
+    if (opts.detail)
+        body.push(`Details: ${opts.detail}`);
+    return showMessageScreen(root, {
+        eyebrow: opts.title,
+        heading: 'The lights went out',
+        body,
+        actions: [{ label: 'Reload', onClick: opts.onReload ?? (() => location.reload()) }],
+    });
+}

package/dist/platform/surface.d.ts

@@ -0,0 +1,72 @@
+import { type BackbufferSize, type Letterbox, type Vec2 } from './letterbox.js';
+export interface SurfaceOptions {
+    /** Logical design width. Default 1920. */
+    logicalWidth?: number;
+    /** Logical design height. Default 1080. */
+    logicalHeight?: number;
+    /** Cap on devicePixelRatio. Default 2. */
+    maxDpr?: number;
+    /** Cap on drawing-buffer pixel count. Default 2560×1440. */
+    maxPixels?: number;
+    /** CSS colour of the letterbox bars (the container background). Default near-black ink. */
+    barColor?: string;
+}
+export interface SurfaceSize {
+    /** Letterboxed rect in CSS px relative to the container. */
+    rect: Letterbox;
+    /** Drawing-buffer size in physical pixels. */
+    backbuffer: BackbufferSize;
+}
+/**
+ * What a surface is to the engine (ws/platform-surface): a letterboxed logical design space, the
+ * drawing-buffer size, and the resize events and coordinate maps over them. `EngineCtx.surface`,
+ * `BootResult.surface` and `mountSurface` are typed with it.
+ *
+ * `new Surface(root, opts)` (the DOM canvas below) implements it, and so can anything else with
+ * these members, with no cast: core's no-DOM surface (`createGame({ overlay: false })`) and a
+ * game's own surface. A surface with no DOM throws from `root` and `canvas`.
+ */
+export interface Surface {
+    /** The container the canvas letterboxes in. */
+    readonly root: HTMLElement;
+    /** The canvas the renderer draws to. */
+    readonly canvas: HTMLCanvasElement;
+    /** Logical design width. */
+    readonly logicalWidth: number;
+    /** Logical design height. */
+    readonly logicalHeight: number;
+    /** Letterboxed rect, CSS px, relative to `root`. Updated in place on resize. */
+    rect: Letterbox;
+    /** The plain contain fit for the whole container (what `rect` is unless a frame is set). */
+    fitRect: Letterbox;
+    /** Drawing-buffer size in device px, and the pixel ratio used. */
+    backbuffer: BackbufferSize;
+    /** Subscribe to size changes. Called immediately with the current size. Returns unsubscribe. */
+    onResize(fn: (size: SurfaceSize) => void): () => void;
+    /** Viewport coordinates (e.g. `PointerEvent.clientX/Y`) to logical design space. */
+    clientToLogical(clientX: number, clientY: number, out?: Vec2): Vec2;
+    /** Logical coordinates to viewport coordinates (CSS px, same space as clientX/Y). */
+    logicalToClient(x: number, y: number, out?: Vec2): Vec2;
+    /** True if a logical point is inside the design space. */
+    containsLogical(p: Vec2): boolean;
+    /** Letterbox inside a part of the container (CSS px, relative to `root`); `null` is all of it. */
+    setFrame(frame: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null): void;
+    /** Force a re-layout (e.g. after fullscreen toggles). */
+    layout(): void;
+    /** Stop listening and release what the surface owns. */
+    destroy(): void;
+}
+/**
+ * The DOM surface's constructor: `new Surface(root, opts)` mounts a letterboxed canvas in
+ * `root`. A class may extend it.
+ */
+export declare const Surface: {
+    new (root: HTMLElement, opts?: SurfaceOptions): Surface;
+    readonly prototype: Surface;
+};
+export declare function mountSurface(root: HTMLElement, opts?: SurfaceOptions): Surface;

package/dist/platform/surface.js

@@ -0,0 +1,157 @@
+import { clientToLogical, computeBackbuffer, computeLetterbox, logicalToClient, } from './letterbox.js';
+/**
+ * A canvas mounted in a container, letterboxed to a fixed logical aspect, DPR-aware.
+ * Owns the canvas element and keeps its CSS box + drawing buffer in sync with the container.
+ *
+ * Other systems (input, DOM overlay) hook in via `rect`, `onResize` and `clientToLogical`.
+ * Exported as the value `Surface`; its private state stays off the `Surface` type.
+ */
+class DomSurface {
+    root;
+    canvas;
+    logicalWidth;
+    logicalHeight;
+    /** Letterboxed rect, CSS px, relative to `root`. Updated in place on resize. */
+    rect = { x: 0, y: 0, width: 0, height: 0, scale: 0 };
+    /** The plain contain fit for the whole container (what `rect` is unless a frame is set). */
+    fitRect = { x: 0, y: 0, width: 0, height: 0, scale: 0 };
+    backbuffer = { width: 1, height: 1, pixelRatio: 1 };
+    frame = null;
+    maxDpr;
+    maxPixels;
+    listeners = new Set();
+    ro;
+    dprQuery = null;
+    onDprChange = () => {
+        this.watchDpr();
+        this.layout();
+    };
+    onWindowResize = () => this.layout();
+    constructor(root, opts = {}) {
+        this.root = root;
+        this.logicalWidth = opts.logicalWidth ?? 1920;
+        this.logicalHeight = opts.logicalHeight ?? 1080;
+        this.maxDpr = opts.maxDpr ?? 2;
+        this.maxPixels = opts.maxPixels ?? 2560 * 1440;
+        if (getComputedStyle(root).position === 'static')
+            root.style.position = 'relative';
+        root.style.overflow = 'hidden';
+        if (opts.barColor)
+            root.style.background = opts.barColor;
+        const canvas = document.createElement('canvas');
+        canvas.style.position = 'absolute';
+        canvas.style.display = 'block';
+        canvas.style.touchAction = 'none';
+        canvas.tabIndex = 0; // focusable so key handling can be scoped to the game (itch iframe)
+        canvas.style.outline = 'none';
+        canvas.setAttribute('aria-label', 'Game view');
+        root.appendChild(canvas);
+        this.canvas = canvas;
+        this.ro = new ResizeObserver(() => this.layout());
+        this.ro.observe(root);
+        window.addEventListener('resize', this.onWindowResize);
+        this.watchDpr();
+        this.layout();
+    }
+    /** Subscribe to size changes. Called immediately with the current size. Returns unsubscribe. */
+    onResize(fn) {
+        this.listeners.add(fn);
+        fn({ rect: this.rect, backbuffer: this.backbuffer });
+        return () => this.listeners.delete(fn);
+    }
+    /**
+     * Convert viewport coordinates (e.g. `PointerEvent.clientX/Y`) to logical design space.
+     * Pass `out` to avoid allocation in hot paths.
+     */
+    clientToLogical(clientX, clientY, out) {
+        const r = this.root.getBoundingClientRect();
+        return clientToLogical(this.rect, this.logicalWidth, this.logicalHeight, clientX - r.left, clientY - r.top, out);
+    }
+    /** Convert logical coordinates to viewport coordinates (CSS px, same space as clientX/Y). */
+    logicalToClient(x, y, out) {
+        const r = this.root.getBoundingClientRect();
+        const p = logicalToClient(this.rect, this.logicalWidth, this.logicalHeight, x, y, out);
+        p.x += r.left;
+        p.y += r.top;
+        return p;
+    }
+    /** True if a logical point is inside the design space. */
+    containsLogical(p) {
+        return p.x >= 0 && p.y >= 0 && p.x <= this.logicalWidth && p.y <= this.logicalHeight;
+    }
+    /**
+     * Keep the canvas inside a part of the container (CSS px, relative to `root`), e.g. the
+     * world's region of a layout (`Layout.freeRect`) when UI regions take the rest of the screen.
+     * The letterbox is computed inside it; `null` (the default) uses the whole
+     * container. `fitRect` is always the whole container's fit, so device-mode decisions do not
+     * depend on the frame. Lays out again at once if the result changes.
+     */
+    setFrame(frame) {
+        const f = this.frame;
+        if (f === frame ||
+            (f &&
+                frame &&
+                f.x === frame.x &&
+                f.y === frame.y &&
+                f.width === frame.width &&
+                f.height === frame.height))
+            return;
+        this.frame = frame
+            ? { x: frame.x, y: frame.y, width: frame.width, height: frame.height }
+            : null;
+        this.layout();
+    }
+    /** Force a re-layout (e.g. after fullscreen toggles). */
+    layout() {
+        const cw = this.root.clientWidth;
+        const ch = this.root.clientHeight;
+        this.fitRect = computeLetterbox(cw, ch, this.logicalWidth, this.logicalHeight);
+        const fr = this.frame;
+        const w = fr ? Math.max(1, Math.min(fr.width, cw)) : cw;
+        const h = fr ? Math.max(1, Math.min(fr.height, ch)) : ch;
+        let rect = fr ? computeLetterbox(w, h, this.logicalWidth, this.logicalHeight) : this.fitRect;
+        if (fr)
+            rect = { ...rect, x: rect.x + fr.x, y: rect.y + fr.y };
+        const bb = computeBackbuffer(rect.width, rect.height, window.devicePixelRatio, this.maxDpr, this.maxPixels);
+        const same = rect.x === this.rect.x &&
+            rect.y === this.rect.y &&
+            rect.width === this.rect.width &&
+            rect.height === this.rect.height &&
+            bb.width === this.backbuffer.width &&
+            bb.height === this.backbuffer.height;
+        if (same)
+            return;
+        this.rect = rect;
+        this.backbuffer = bb;
+        const s = this.canvas.style;
+        s.left = `${rect.x}px`;
+        s.top = `${rect.y}px`;
+        s.width = `${rect.width}px`;
+        s.height = `${rect.height}px`;
+        this.canvas.width = bb.width;
+        this.canvas.height = bb.height;
+        const size = { rect, backbuffer: bb };
+        for (const fn of this.listeners)
+            fn(size);
+    }
+    destroy() {
+        this.ro.disconnect();
+        window.removeEventListener('resize', this.onWindowResize);
+        this.dprQuery?.removeEventListener('change', this.onDprChange);
+        this.listeners.clear();
+        this.canvas.remove();
+    }
+    watchDpr() {
+        this.dprQuery?.removeEventListener('change', this.onDprChange);
+        this.dprQuery = window.matchMedia(`(resolution: ${window.devicePixelRatio}dppx)`);
+        this.dprQuery.addEventListener('change', this.onDprChange);
+    }
+}
+/**
+ * The DOM surface's constructor: `new Surface(root, opts)` mounts a letterboxed canvas in
+ * `root`. A class may extend it.
+ */
+export const Surface = DomSurface;
+export function mountSurface(root, opts) {
+    return new Surface(root, opts);
+}

package/dist/platform/xr-fake.d.ts

@@ -0,0 +1,168 @@
+/**
+ * A fake WebXR stack for unit tests (ws/xr): `XRSystem`, `XRSession`, `XRFrame`, input sources
+ * and the WebXR/WebGPU binding, stepped by hand. `installFakeXr(device)` puts a `navigator.xr`
+ * and a `globalThis.XRGPUBinding` in place over a fake GPU device (`createFakeDevice`), so
+ * `createGame`'s `ctx.xr.enter()`, `XrSurface` and `XrPointerSource` run end to end in Node;
+ * the returned `uninstall` restores the globals. Not exported from any module index.
+ *
+ * Geometry: two eyes at ±`ipd / 2` on x, looking down -z with a 90° projection, side by side in
+ * one `textureType: 'texture'` layer texture (`2 * eyeWidth × eyeHeight`); a `texture-array`
+ * layer gives each eye its own array layer. Input sources carry a position and point down -z.
+ */
+/// <reference path="./xr-types.d.ts" preserve="true" />
+export interface FakeXrOptions {
+    /** Per-eye texture size. Default 64 × 32. */
+    eyeWidth?: number;
+    eyeHeight?: number;
+    /** Interpupillary distance (metres). Default 0.064. */
+    ipd?: number;
+    /** What `isSessionSupported('immersive-vr')` answers. Default true. */
+    supported?: boolean;
+    /** A new layer texture every frame (a real compositor rotates them). Default false. */
+    rotateTextures?: boolean;
+}
+/** A rigid transform that is a pure translation, with its inverse. */
+export declare function fakeTransform(x: number, y: number, z: number): XRRigidTransform;
+export declare class FakeXrSpace implements XRSpace {
+    readonly name: string;
+    constructor(name: string);
+}
+export declare class FakeXrReferenceSpace extends FakeXrSpace implements XRReferenceSpace {
+    getOffsetReferenceSpace(): XRReferenceSpace;
+}
+export declare class FakeXrJointSpace extends FakeXrSpace implements XRJointSpace {
+    readonly jointName: XRHandJoint;
+    constructor(jointName: XRHandJoint);
+}
+/** A hand whose joint positions a test sets (`joints.set('thumb-tip', [x, y, z])`). */
+export declare class FakeXrHand implements XRHand {
+    readonly joints: Map<XRHandJoint, [number, number, number]>;
+    private readonly spaces;
+    get size(): number;
+    get(joint: XRHandJoint): XRJointSpace | undefined;
+}
+export declare class FakeXrInputSource implements XRInputSource {
+    readonly handedness: XRHandedness;
+    readonly targetRayMode: XRTargetRayMode;
+    readonly targetRaySpace: FakeXrSpace;
+    readonly gripSpace: XRSpace | null;
+    readonly profiles: readonly string[];
+    /** Where the target ray starts, in the reference space; it points down -z. */
+    position: [number, number, number];
+    /** `buttons[0]` trigger, `buttons[1]` squeeze. */
+    readonly buttons: {
+        pressed: boolean;
+        touched: boolean;
+        value: number;
+    }[];
+    /** Null for a source without a gamepad (events only). */
+    gamepad: Gamepad | null;
+    hand: FakeXrHand | null;
+    constructor(handedness: XRHandedness, opts?: {
+        gamepad?: boolean;
+        hand?: boolean;
+    });
+}
+export declare class FakeXrFrame implements XRFrame {
+    readonly session: FakeXrSession;
+    readonly predictedDisplayTime: number;
+    constructor(session: FakeXrSession, predictedDisplayTime: number);
+    getViewerPose(referenceSpace: XRReferenceSpace): XRViewerPose | undefined;
+    getPose(space: XRSpace, baseSpace: XRSpace): XRPose | undefined;
+    getJointPose(joint: XRJointSpace, baseSpace: XRSpace): XRJointPose | undefined;
+}
+export declare class FakeXrSession extends EventTarget implements XRSession {
+    readonly mode: XRSessionMode;
+    readonly init: XRSessionInit | undefined;
+    readonly opts: Required<FakeXrOptions>;
+    readonly inputSources: FakeXrInputSource[];
+    readonly referenceSpace: FakeXrReferenceSpace;
+    renderState: XRRenderState;
+    visibilityState: 'visible' | 'visible-blurred' | 'hidden';
+    headPosition: [number, number, number];
+    /** False makes `getViewerPose` return nothing (tracking lost). */
+    tracking: boolean;
+    ended: boolean;
+    /** Every `requestReferenceSpace` type asked for. */
+    readonly referenceSpaceRequests: XRReferenceSpaceType[];
+    readonly renderStateUpdates: XRRenderStateInit[];
+    private readonly pending;
+    private nextHandle;
+    private frameTime;
+    constructor(mode: XRSessionMode, init: XRSessionInit | undefined, opts: Required<FakeXrOptions>);
+    /** The clock of the frame running now (the last `step`), ms. */
+    get now(): number;
+    /** Callbacks waiting for the next frame. */
+    get pendingFrames(): number;
+    requestReferenceSpace(type: XRReferenceSpaceType): Promise<XRReferenceSpace>;
+    updateRenderState(state?: XRRenderStateInit): void;
+    requestAnimationFrame(callback: XRFrameRequestCallback): number;
+    cancelAnimationFrame(handle: number): void;
+    /** Run the pending frame callbacks with a new `XRFrame`, `dtMs` after the last one. */
+    step(dtMs?: number): FakeXrFrame;
+    /** Add an input source (fires `inputsourceschange`). */
+    addInputSource(src: FakeXrInputSource): void;
+    removeInputSource(src: FakeXrInputSource): void;
+    /** Fire `selectstart` / `selectend` (or `squeeze…`) for a source, as a headset would. */
+    fire(kind: 'select' | 'squeeze', src: FakeXrInputSource, down: boolean): void;
+    end(): Promise<void>;
+}
+export declare class FakeXrSystem implements XRSystem {
+    readonly opts: Required<FakeXrOptions>;
+    readonly sessions: FakeXrSession[];
+    constructor(opts: Required<FakeXrOptions>);
+    isSessionSupported(mode: XRSessionMode): Promise<boolean>;
+    requestSession(mode: XRSessionMode, init?: XRSessionInit): Promise<XRSession>;
+    /** The session requested last. */
+    get session(): FakeXrSession;
+}
+export declare class FakeXrProjectionLayer implements XRProjectionLayer {
+    readonly binding: FakeXRGPUBinding;
+    readonly init: XRGPUProjectionLayerInit;
+    readonly layout: 'stereo';
+    readonly mipLevels = 1;
+    needsRedraw: boolean;
+    readonly ignoreDepthValues = false;
+    fixedFoveation: number | null;
+    destroyed: boolean;
+    /** Textures handed out so far (one per frame when rotating). */
+    readonly colorTextures: GPUTexture[];
+    readonly depthTextures: GPUTexture[];
+    private color;
+    private depth;
+    private lastFrameTime;
+    constructor(binding: FakeXRGPUBinding, init: XRGPUProjectionLayerInit);
+    get textureType(): 'texture' | 'texture-array';
+    get textureWidth(): number;
+    get textureHeight(): number;
+    get textureArrayLength(): number;
+    /** This frame's textures, made on first use and, when rotating, anew each frame. */
+    textures(frameTime: number): {
+        color: GPUTexture;
+        depth: GPUTexture | null;
+    };
+    destroy(): void;
+}
+export declare class FakeXRGPUBinding implements XRGPUBinding {
+    readonly session: FakeXrSession;
+    readonly device: GPUDevice;
+    readonly nativeProjectionScaleFactor = 1;
+    readonly layers: FakeXrProjectionLayer[];
+    constructor(session: FakeXrSession, device: GPUDevice);
+    createProjectionLayer(init?: XRGPUProjectionLayerInit): XRProjectionLayer;
+    getViewSubImage(layer: XRProjectionLayer, view: XRView): XRGPUSubImage;
+    getPreferredColorFormat(): GPUTextureFormat;
+}
+export interface FakeXr {
+    readonly system: FakeXrSystem;
+    /** Every binding `new XRGPUBinding(session, device)` made. */
+    readonly bindings: FakeXRGPUBinding[];
+    /** Advance the session's frame clock and run its pending frame callbacks. */
+    step(dtMs?: number): FakeXrFrame;
+    uninstall(): void;
+}
+/**
+ * Install `navigator.xr` and `XRGPUBinding` fakes. `supported: false` keeps `navigator.xr` but
+ * answers no to `immersive-vr`; to test a browser with no WebXR at all, install nothing.
+ */
+export declare function installFakeXr(opts?: FakeXrOptions): FakeXr;