@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/nav/query-queue.js

@@ -0,0 +1,308 @@
+import { NEIGHBOUR_X, NEIGHBOUR_Y, stepCost } from './grid.js';
+import { CellHeap } from './heap.js';
+import { clearPath3, MeshSearch } from './mesh/mesh-path.js';
+import { NavMesh } from './mesh/navmesh.js';
+import { reservePath, smoothPath } from './path.js';
+const SQRT2 = Math.SQRT2;
+function heuristic(x, y, tx, ty, diagonal) {
+    const dx = x > tx ? x - tx : tx - x;
+    const dy = y > ty ? y - ty : ty - y;
+    if (!diagonal)
+        return dx + dy;
+    return dx > dy ? dx + (SQRT2 - 1) * dy : dy + (SQRT2 - 1) * dx;
+}
+/** `findPath`'s A*, resumable: identical expansion order, so identical paths. */
+class GridSearch {
+    grid;
+    state = 'idle';
+    version = -1;
+    g;
+    f;
+    parent;
+    seen;
+    closed;
+    heap;
+    stamp = 0;
+    goal = -1;
+    tx = 0;
+    ty = 0;
+    diagonal = true;
+    weight = 1;
+    maxExpand = 0;
+    maxCost = Number.POSITIVE_INFINITY;
+    expanded = 0;
+    constructor(grid) {
+        this.grid = grid;
+        const n = grid.size;
+        this.g = new Float64Array(n);
+        this.f = new Float64Array(n);
+        this.parent = new Int32Array(n);
+        this.seen = new Uint32Array(n);
+        this.closed = new Uint32Array(n);
+        this.heap = new CellHeap(n, this.f);
+    }
+    begin(from, to, opts) {
+        const grid = this.grid;
+        this.version = grid.version;
+        this.state = 'failed';
+        this.expanded = 0;
+        if (!grid.isWalkable(from.x, from.y) || !grid.isWalkable(to.x, to.y))
+            return false;
+        this.diagonal = opts?.diagonal ?? grid.neighbours === 8;
+        this.maxExpand = opts?.maxExpand ?? grid.size;
+        this.maxCost = opts?.maxCost ?? Infinity;
+        this.weight = opts?.heuristicWeight ?? 1;
+        this.stamp = (this.stamp + 1) >>> 0 || 1;
+        this.heap.clear();
+        const width = grid.width;
+        this.tx = to.x;
+        this.ty = to.y;
+        const start = from.y * width + from.x;
+        this.goal = to.y * width + to.x;
+        this.g[start] = 0;
+        this.f[start] = this.weight * heuristic(from.x, from.y, to.x, to.y, this.diagonal);
+        this.parent[start] = -1;
+        this.seen[start] = this.stamp;
+        this.heap.pushOrDecrease(start);
+        this.state = 'running';
+        return true;
+    }
+    step(maxPops) {
+        if (this.state !== 'running')
+            return 0;
+        const { grid, g, f, parent, seen, closed, heap, stamp, goal, tx, ty, diagonal, weight } = this;
+        const maxCost = this.maxCost;
+        const width = grid.width;
+        const dirs = diagonal ? 8 : 4;
+        let pops = 0;
+        while (pops < maxPops) {
+            if (heap.size === 0) {
+                this.state = 'failed';
+                break;
+            }
+            const cur = heap.pop();
+            pops++;
+            if (cur === goal) {
+                this.state = 'found';
+                break;
+            }
+            if (++this.expanded > this.maxExpand) {
+                this.state = 'failed';
+                break;
+            }
+            closed[cur] = stamp;
+            const cx = cur % width;
+            const cy = (cur - cx) / width;
+            const gc = g[cur];
+            for (let d = 0; d < dirs; d++) {
+                const step = stepCost(grid, cur, cx, cy, d);
+                if (step === Infinity)
+                    continue;
+                const nx = cx + NEIGHBOUR_X[d];
+                const ny = cy + NEIGHBOUR_Y[d];
+                const ni = ny * width + nx;
+                if (closed[ni] === stamp)
+                    continue;
+                const ng = gc + step;
+                if (ng > maxCost)
+                    continue;
+                if (seen[ni] === stamp && ng >= g[ni])
+                    continue;
+                seen[ni] = stamp;
+                g[ni] = ng;
+                f[ni] = ng + weight * heuristic(nx, ny, tx, ty, diagonal);
+                parent[ni] = cur;
+                heap.pushOrDecrease(ni);
+            }
+        }
+        return pops;
+    }
+    finish(out) {
+        out.length = 0;
+        out.cursor = 0;
+        out.version = this.version;
+        if (this.state !== 'found')
+            return false;
+        const { grid, parent, goal } = this;
+        const width = grid.width;
+        let count = 0;
+        for (let i = goal; i >= 0; i = parent[i])
+            count++;
+        reservePath(out, count);
+        const p = out.points;
+        const cs = grid.cellSize;
+        const ox = grid.origin.x;
+        const oz = grid.origin.z;
+        let k = count - 1;
+        for (let i = goal; i >= 0; i = parent[i], k--) {
+            const x = i % width;
+            const y = (i - x) / width;
+            p[k * 2] = ox + (x + 0.5) * cs;
+            p[k * 2 + 1] = oz + (y + 0.5) * cs;
+        }
+        out.length = count;
+        this.state = 'idle';
+        return true;
+    }
+}
+/** A queue of path searches over a mesh or a grid, sliced across `update()` calls. */
+export function createPathQueue(target, opts) {
+    const max = Math.max(1, opts.maxQueries);
+    const budget = Math.max(1, opts.iterationsPerUpdate ?? 256);
+    const mesh = target instanceof NavMesh ? target : null;
+    const grid = mesh ? null : target;
+    const meshSearch = mesh ? new MeshSearch(mesh) : null;
+    const gridSearch = grid ? new GridSearch(grid) : null;
+    // A ring of tickets in request order; finished tickets keep their state until their slot is reused.
+    const ring = [];
+    for (let i = 0; i < max; i++) {
+        ring.push({
+            id: 0,
+            state: 'none',
+            fx: 0,
+            fy: 0,
+            fz: 0,
+            tx: 0,
+            ty: 0,
+            tz: 0,
+            out: null,
+            opts: undefined,
+        });
+    }
+    let head = 0; // the oldest pending ticket's slot
+    let tail = 0; // the next free slot
+    let pending = 0;
+    /** Slots taken, cancelled ones included until the ring reaches them. */
+    let occupied = 0;
+    let finished = 0;
+    let nextId = 1;
+    /** The ticket id the in-flight search belongs to, 0 when none. */
+    let inFlight = 0;
+    const from3 = { x: 0, y: 0, z: 0 };
+    const to3 = { x: 0, y: 0, z: 0 };
+    const fromCell = { x: 0, y: 0 };
+    const toCell = { x: 0, y: 0 };
+    const find = (ticket) => {
+        if (ticket <= 0)
+            return undefined;
+        for (let i = 0; i < max; i++) {
+            const t = ring[i];
+            if (t.id === ticket)
+                return t;
+        }
+        return undefined;
+    };
+    const begin = (t) => {
+        inFlight = t.id;
+        if (meshSearch) {
+            from3.x = t.fx;
+            from3.y = t.fy;
+            from3.z = t.fz;
+            to3.x = t.tx;
+            to3.y = t.ty;
+            to3.z = t.tz;
+            return meshSearch.begin(from3, to3, t.opts);
+        }
+        fromCell.x = t.fx;
+        fromCell.y = t.fy;
+        toCell.x = t.tx;
+        toCell.y = t.ty;
+        return gridSearch.begin(fromCell, toCell, t.opts);
+    };
+    const queue = {
+        get pending() {
+            return pending;
+        },
+        get finished() {
+            return finished;
+        },
+        onDone: null,
+        request(from, to, out, reqOpts) {
+            if (occupied >= max)
+                return -1;
+            const t = ring[tail];
+            tail = tail + 1 === max ? 0 : tail + 1;
+            t.id = nextId++;
+            t.state = 'pending';
+            t.fx = from.x;
+            t.fy = from.y;
+            t.fz = 'z' in from ? from.z : 0;
+            t.tx = to.x;
+            t.ty = to.y;
+            t.tz = 'z' in to ? to.z : 0;
+            t.out = out;
+            t.opts = reqOpts;
+            pending++;
+            occupied++;
+            return t.id;
+        },
+        update() {
+            let left = budget;
+            while (left > 0 && occupied > 0) {
+                const t = ring[head];
+                if (t.state !== 'pending') {
+                    // Cancelled: skip the slot.
+                    head = head + 1 === max ? 0 : head + 1;
+                    occupied--;
+                    continue;
+                }
+                const search = meshSearch ?? gridSearch;
+                let ok;
+                if (inFlight !== t.id || search.version !== target.version) {
+                    ok = begin(t);
+                }
+                else {
+                    ok = true;
+                }
+                if (ok && search.state === 'running') {
+                    left -= search.step(left);
+                    if (search.state === 'running')
+                        break; // budget spent; resume next update
+                }
+                const done = search.state === 'found' &&
+                    (meshSearch
+                        ? meshSearch.finish(t.out)
+                        : gridSearch.finish(t.out));
+                if (done && gridSearch && t.opts?.smooth)
+                    smoothPath(grid, t.out);
+                if (!done && t.out) {
+                    if (meshSearch)
+                        clearPath3(t.out);
+                    else {
+                        t.out.length = 0;
+                        t.out.cursor = 0;
+                    }
+                }
+                search.state = 'idle';
+                inFlight = 0;
+                t.state = done ? 'done' : 'failed';
+                head = head + 1 === max ? 0 : head + 1;
+                pending--;
+                occupied--;
+                finished++;
+                const out = t.out;
+                t.out = null;
+                t.opts = undefined;
+                queue.onDone?.(t.id, done, out);
+            }
+            return budget - left;
+        },
+        status(ticket) {
+            const t = find(ticket);
+            return t ? t.state : 'none';
+        },
+        cancel(ticket) {
+            const t = find(ticket);
+            if (t?.state !== 'pending')
+                return false;
+            t.state = 'none';
+            t.out = null;
+            t.opts = undefined;
+            pending--;
+            if (inFlight === ticket)
+                inFlight = 0;
+            return true;
+        },
+    };
+    return queue;
+}

package/dist/nav/reach.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Bounded reachability: Dijkstra from one or more start cells that stops at a cost budget and
+ * keeps every parent, so a turn-based or tile game asks "where can this unit move" and "by which
+ * path" from one query. The result lives in a `Reach` sized to the grid once and reused.
+ */
+import type { NavGrid } from './grid.js';
+import { type MeshReach, type MeshReachOptions } from './mesh/mesh-reach.js';
+import { NavMesh, type NavPoint3 } from './mesh/navmesh.js';
+import { type NavPath } from './path.js';
+export interface Reach {
+    readonly grid: NavGrid;
+    /** Cells reached by the last query (the starts included). */
+    readonly count: number;
+    /** The reached cells' row-major indices, in order of increasing distance; `count` are valid. */
+    readonly cells: Int32Array;
+    /** Cost-weighted distance from the nearest start per grid cell; `Infinity` when not reached. */
+    readonly distances: Float32Array;
+    /** The cell each reached cell was entered from; -1 at a start or an unreached cell. */
+    readonly parents: Int32Array;
+    /** The budget of the last query. */
+    readonly budget: number;
+    /** `grid.version` at the last query, or -1 before the first. */
+    readonly version: number;
+    /** True when the grid was edited since the last query. */
+    readonly stale: boolean;
+    /** True when the cell was reached within the budget (a start counts). */
+    has(index: number): boolean;
+    /**
+     * Walks the parents from the nearest start to `index` into `path` (world cell centres, like
+     * `findPath`; `cursor` 0, `version` stamped). False, with an empty path, when not reached.
+     */
+    pathTo(index: number, path: NavPath): boolean;
+    /** Calls `fn` for every reached cell, nearest first. */
+    forEach(fn: (index: number, distance: number) => void): void;
+}
+/** A reusable reachability result sized to `grid`; pass it to `reachable` as `out`. */
+export declare function createReach(grid: NavGrid): Reach;
+/**
+ * Grid form: Dijkstra from `start` (a row-major index, or several) over the grid's neighbourhood with its
+ * edge costs, stopping at `budget` (inclusive: a cell whose cost equals the budget is reached).
+ * Writes into `out`, or into one `Reach` kept per grid when omitted, and returns it; nothing
+ * allocates after the first query on a grid. Unwalkable or out-of-grid starts are skipped. The
+ * cells in `out.cells` come nearest first, so the heap order doubles as a frontier order.
+ */
+export declare function reachable(grid: NavGrid, start: number | ArrayLike<number>, budget: number, out?: Reach): Reach;
+/**
+ * Mesh form (ws/nav-5): the polygons whose centre is within path cost `opts.budget` of `from`
+ * (snapped onto the mesh), with their cost to reach, priced as `findMeshPath` prices a route
+ * (areas, links) and stopping at the budget or `opts.maxPolys`. Writes into `out`
+ * (`createMeshReach`) or one `MeshReach` kept per mesh; allocation-free after the first query.
+ * `reachableOutline` draws its boundary.
+ */
+export declare function reachable(mesh: NavMesh, from: Readonly<NavPoint3>, opts: MeshReachOptions, out?: MeshReach): MeshReach;

package/dist/nav/reach.js

@@ -0,0 +1,148 @@
+import { NEIGHBOUR_X, NEIGHBOUR_Y, stepCost } from './grid.js';
+import { CellHeap } from './heap.js';
+import { reachableMesh } from './mesh/mesh-reach.js';
+import { NavMesh } from './mesh/navmesh.js';
+import { reservePath } from './path.js';
+class ReachImpl {
+    grid;
+    cells;
+    distances;
+    parents;
+    count = 0;
+    budget = 0;
+    version = -1;
+    heap;
+    constructor(grid) {
+        this.grid = grid;
+        const n = grid.size;
+        this.cells = new Int32Array(n);
+        this.distances = new Float32Array(n).fill(Infinity);
+        this.parents = new Int32Array(n).fill(-1);
+        this.heap = new CellHeap(n, this.distances);
+    }
+    get stale() {
+        return this.version !== this.grid.version;
+    }
+    has(index) {
+        return index >= 0 && index < this.grid.size && this.distances[index] < Infinity;
+    }
+    pathTo(index, path) {
+        path.length = 0;
+        path.cursor = 0;
+        path.version = this.version;
+        if (!this.has(index))
+            return false;
+        const parents = this.parents;
+        let count = 0;
+        for (let i = index; i >= 0; i = parents[i])
+            count++;
+        reservePath(path, count);
+        const grid = this.grid;
+        const width = grid.width;
+        const cs = grid.cellSize;
+        const ox = grid.origin.x;
+        const oz = grid.origin.z;
+        const p = path.points;
+        let k = count - 1;
+        for (let i = index; i >= 0; i = parents[i], k--) {
+            const x = i % width;
+            const y = (i - x) / width;
+            p[k * 2] = ox + (x + 0.5) * cs;
+            p[k * 2 + 1] = oz + (y + 0.5) * cs;
+        }
+        path.length = count;
+        return true;
+    }
+    forEach(fn) {
+        for (let i = 0; i < this.count; i++) {
+            const c = this.cells[i];
+            fn(c, this.distances[c]);
+        }
+    }
+    /** Forgets the last query's cells only (the untouched rest is still `Infinity` / -1). */
+    reset() {
+        for (let i = 0; i < this.count; i++) {
+            const c = this.cells[i];
+            this.distances[c] = Infinity;
+            this.parents[c] = -1;
+        }
+        this.count = 0;
+        this.heap.clear();
+    }
+}
+/** A reusable reachability result sized to `grid`; pass it to `reachable` as `out`. */
+export function createReach(grid) {
+    return new ReachImpl(grid);
+}
+const reachFor = new WeakMap();
+function seed(r, gi) {
+    if (!(gi >= 0 && gi < r.grid.size) || r.grid.costs[gi] <= 0 || r.distances[gi] === 0)
+        return;
+    r.distances[gi] = 0;
+    r.parents[gi] = -1;
+    r.heap.pushOrDecrease(gi);
+}
+export function reachable(target, start, budget, out) {
+    if (target instanceof NavMesh) {
+        return reachableMesh(target, start, budget, out);
+    }
+    return reachableGrid(target, start, budget, out);
+}
+function reachableGrid(grid, start, budget, out) {
+    let r;
+    if (out) {
+        if (out.grid !== grid)
+            throw new Error('nav: reach belongs to another grid');
+        r = out;
+    }
+    else {
+        const cached = reachFor.get(grid);
+        if (cached) {
+            r = cached;
+        }
+        else {
+            r = new ReachImpl(grid);
+            reachFor.set(grid, r);
+        }
+    }
+    r.reset();
+    r.budget = budget;
+    r.version = grid.version;
+    const width = grid.width;
+    const dist = r.distances;
+    const parents = r.parents;
+    const cells = r.cells;
+    const heap = r.heap;
+    const dirs = grid.neighbours;
+    if (typeof start === 'number') {
+        seed(r, start);
+    }
+    else {
+        for (let i = 0; i < start.length; i++)
+            seed(r, start[i]);
+    }
+    let count = 0;
+    while (heap.size > 0) {
+        const cur = heap.pop();
+        cells[count++] = cur;
+        const cx = cur % width;
+        const cy = (cur - cx) / width;
+        const dc = dist[cur];
+        for (let d = 0; d < dirs; d++) {
+            const step = stepCost(grid, cur, cx, cy, d);
+            if (step === Infinity)
+                continue;
+            const nd = dc + step;
+            if (nd > budget)
+                continue;
+            const ni = (cy + NEIGHBOUR_Y[d]) * width + cx + NEIGHBOUR_X[d];
+            if (nd >= dist[ni])
+                continue;
+            dist[ni] = nd;
+            parents[ni] = cur;
+            heap.pushOrDecrease(ni);
+        }
+    }
+    r.count = count;
+    return r;
+}

package/dist/nav/steer.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Local steering on the XZ plane: small vector helpers an agent combines with a path or flow
+ * direction each tick. Every function writes `out` and returns it; nothing allocates.
+ */
+import type { NavPoint } from './grid.js';
+/** A circular obstacle on the XZ plane. */
+export interface Disc {
+    x: number;
+    z: number;
+    radius: number;
+}
+/**
+ * Pushes `self` away from every neighbour closer than `radius`: the sum over them of the unit
+ * vector away, weighted `(radius - d) / radius`, so a touching neighbour weighs 1 and one at the
+ * edge weighs 0. Zero when none is near; a neighbour exactly at `self` is skipped. Scale the
+ * result by a speed to make it a velocity.
+ */
+export declare function separate(self: Readonly<NavPoint>, neighbours: ArrayLike<Readonly<NavPoint>>, radius: number, out: NavPoint): NavPoint;
+/**
+ * The velocity that reaches `target`: `speed` outside `slowRadius`, scaled down linearly inside
+ * it, zero at the target. `slowRadius` 0 never slows.
+ */
+export declare function arrive(self: Readonly<NavPoint>, target: Readonly<NavPoint>, speed: number, slowRadius: number, out: NavPoint): NavPoint;
+/**
+ * `velocity` bent around `disc`: when the disc lies ahead within one second of travel and the
+ * course passes closer than its radius, a sideways push away from the centre is added, sized by
+ * how deep the course cuts in (full speed at a head-on hit, nothing at a graze). Otherwise `out`
+ * is `velocity`. A disc behind, or a zero velocity, leaves it alone. `out` may be `velocity`.
+ */
+export declare function avoidDisc(self: Readonly<NavPoint>, velocity: Readonly<NavPoint>, disc: Readonly<Disc>, out: NavPoint): NavPoint;
+/** The three helpers as one namespace: `steer.separate`, `steer.arrive`, `steer.avoidDisc`. */
+export declare const steer: {
+    readonly separate: typeof separate;
+    readonly arrive: typeof arrive;
+    readonly avoidDisc: typeof avoidDisc;
+};

package/dist/nav/steer.js

@@ -0,0 +1,78 @@
+/**
+ * Pushes `self` away from every neighbour closer than `radius`: the sum over them of the unit
+ * vector away, weighted `(radius - d) / radius`, so a touching neighbour weighs 1 and one at the
+ * edge weighs 0. Zero when none is near; a neighbour exactly at `self` is skipped. Scale the
+ * result by a speed to make it a velocity.
+ */
+export function separate(self, neighbours, radius, out) {
+    let x = 0;
+    let z = 0;
+    const r2 = radius * radius;
+    for (let i = 0; i < neighbours.length; i++) {
+        const n = neighbours[i];
+        const dx = self.x - n.x;
+        const dz = self.z - n.z;
+        const d2 = dx * dx + dz * dz;
+        if (d2 >= r2 || d2 === 0)
+            continue;
+        const d = Math.sqrt(d2);
+        const w = (radius - d) / radius / d;
+        x += dx * w;
+        z += dz * w;
+    }
+    out.x = x;
+    out.z = z;
+    return out;
+}
+/**
+ * The velocity that reaches `target`: `speed` outside `slowRadius`, scaled down linearly inside
+ * it, zero at the target. `slowRadius` 0 never slows.
+ */
+export function arrive(self, target, speed, slowRadius, out) {
+    const dx = target.x - self.x;
+    const dz = target.z - self.z;
+    const d = Math.sqrt(dx * dx + dz * dz);
+    if (d === 0) {
+        out.x = 0;
+        out.z = 0;
+        return out;
+    }
+    const s = slowRadius > 0 && d < slowRadius ? (speed * d) / slowRadius : speed;
+    out.x = (dx / d) * s;
+    out.z = (dz / d) * s;
+    return out;
+}
+/**
+ * `velocity` bent around `disc`: when the disc lies ahead within one second of travel and the
+ * course passes closer than its radius, a sideways push away from the centre is added, sized by
+ * how deep the course cuts in (full speed at a head-on hit, nothing at a graze). Otherwise `out`
+ * is `velocity`. A disc behind, or a zero velocity, leaves it alone. `out` may be `velocity`.
+ */
+export function avoidDisc(self, velocity, disc, out) {
+    const vx = velocity.x;
+    const vz = velocity.z;
+    const speed = Math.sqrt(vx * vx + vz * vz);
+    out.x = vx;
+    out.z = vz;
+    if (speed === 0)
+        return out;
+    const dx = disc.x - self.x;
+    const dz = disc.z - self.z;
+    // Distance along the course (world units) and the signed distance beside it, measured along
+    // the perpendicular `perp = (vz, -vx) / speed`.
+    const along = (dx * vx + dz * vz) / speed;
+    if (along <= 0 || along > speed + disc.radius)
+        return out;
+    const side = (dx * vz - dz * vx) / speed;
+    const miss = Math.abs(side);
+    if (miss >= disc.radius)
+        return out;
+    const push = (speed * (disc.radius - miss)) / disc.radius;
+    // Push along `perp` away from the centre (a centre dead ahead goes to +perp).
+    const sign = side > 0 ? -1 : 1;
+    out.x = vx + (vz / speed) * push * sign;
+    out.z = vz + (-vx / speed) * push * sign;
+    return out;
+}
+/** The three helpers as one namespace: `steer.separate`, `steer.arrive`, `steer.avoidDisc`. */
+export const steer = { separate, arrive, avoidDisc };

package/dist/platform/boot.d.ts

@@ -0,0 +1,28 @@
+import { type GpuContext, type GpuFailureReason } from './gpu.js';
+import { type Surface, type SurfaceOptions } from './surface.js';
+export interface BootOptions extends SurfaceOptions {
+    /** Shown as the eyebrow on fatal screens (the game's name). */
+    title?: string;
+    /** Called after the device-lost screen is shown (stop loops here). */
+    onDeviceLost?: (info: GPUDeviceLostInfo) => void;
+    /** Dev aid: pretend WebGPU is missing to preview the unsupported screen. */
+    forceUnsupported?: boolean;
+}
+export type BootResult = {
+    ok: true;
+    surface: Surface;
+    gpu: GpuContext;
+    /**
+     * Run `fn` after the device-lost screen is shown, to halt whatever was built after boot
+     * (loop, audio, timers). Returns unsubscribe.
+     */
+    onDeviceLost(fn: (info: GPUDeviceLostInfo) => void): () => void;
+} | {
+    ok: false;
+    reason: GpuFailureReason | 'forced';
+};
+/**
+ * Mount a letterboxed canvas in `root` and bring up WebGPU. On failure the canvas is removed
+ * and the styled unsupported screen is shown; on device loss the reload screen is shown.
+ */
+export declare function boot(root: HTMLElement, opts?: BootOptions): Promise<BootResult>;

package/dist/platform/boot.js

@@ -0,0 +1,43 @@
+import { initGpu } from './gpu.js';
+import { showDeviceLostScreen, showUnsupportedScreen } from './screens.js';
+import { mountSurface } from './surface.js';
+/**
+ * Mount a letterboxed canvas in `root` and bring up WebGPU. On failure the canvas is removed
+ * and the styled unsupported screen is shown; on device loss the reload screen is shown.
+ */
+export async function boot(root, opts = {}) {
+    if (opts.forceUnsupported) {
+        showUnsupportedScreen(root, { title: opts.title });
+        return { ok: false, reason: 'forced' };
+    }
+    const surface = mountSurface(root, opts);
+    const lostListeners = new Set();
+    const res = await initGpu(surface.canvas, {
+        onLost: (info) => {
+            showDeviceLostScreen(root, { title: opts.title, detail: info.message || undefined });
+            opts.onDeviceLost?.(info);
+            for (const fn of [...lostListeners]) {
+                try {
+                    fn(info);
+                }
+                catch (err) {
+                    console.error('[boot] device-lost handler failed', err);
+                }
+            }
+        },
+    });
+    if (!res.ok) {
+        surface.destroy();
+        showUnsupportedScreen(root, { title: opts.title, detail: res.detail ?? res.reason });
+        return { ok: false, reason: res.reason };
+    }
+    return {
+        ok: true,
+        surface,
+        gpu: res.gpu,
+        onDeviceLost(fn) {
+            lostListeners.add(fn);
+            return () => lostListeners.delete(fn);
+        },
+    };
+}