@driftengine/core 3.61.0

package/dist/geometry/tangents.js

@@ -0,0 +1,142 @@
+/**
+ * A tangent frame: which way is *along the texture*.
+ *
+ * **Every map in Phase 1.3 needs one and nothing in this engine had it.** A normal map stores its
+ * directions in the surface's own space, and turning those into world directions takes three
+ * axes: the normal, a tangent running with u, and a bitangent running with v. Two of the three
+ * come from geometry the engine already has; this derives the third.
+ *
+ * **Four floats a vertex, and `w` is the interesting one.** The bitangent is
+ * `cross(normal, tangent) * w`, and the sign is needed because a UV layout can mirror: an artist
+ * mapping the left and right of a model onto one patch of texture gives one side a flipped frame,
+ * and a bitangent computed without the sign lights that side inside out. Storing it costs a float
+ * a vertex, and every format that has been through this — glTF included — settled on the same
+ * four rather than storing the bitangent outright, which costs three.
+ */
+/** Scratch, so a build that derives many meshes does not allocate per mesh. */
+const accumulated = {
+    tangents: new Float32Array(0),
+    bitangents: new Float32Array(0),
+};
+function scratchFor(vertices) {
+    if (accumulated.tangents.length < vertices * 3) {
+        accumulated.tangents = new Float32Array(vertices * 3);
+        accumulated.bitangents = new Float32Array(vertices * 3);
+    }
+    else {
+        accumulated.tangents.fill(0, 0, vertices * 3);
+        accumulated.bitangents.fill(0, 0, vertices * 3);
+    }
+    return accumulated;
+}
+function accumulate(tangents, bitangents, v, tx, ty, tz, bx, by, bz) {
+    tangents[v * 3] = (tangents[v * 3] ?? 0) + tx;
+    tangents[v * 3 + 1] = (tangents[v * 3 + 1] ?? 0) + ty;
+    tangents[v * 3 + 2] = (tangents[v * 3 + 2] ?? 0) + tz;
+    bitangents[v * 3] = (bitangents[v * 3] ?? 0) + bx;
+    bitangents[v * 3 + 1] = (bitangents[v * 3 + 1] ?? 0) + by;
+    bitangents[v * 3 + 2] = (bitangents[v * 3 + 2] ?? 0) + bz;
+}
+/**
+ * Derive a tangent frame from positions, normals and texture coordinates.
+ *
+ * **Accumulated per triangle, then orthogonalised per vertex.** A vertex shared by two triangles
+ * gets the sum of their tangents, which is what makes a smooth surface's frame smooth; the sum is
+ * then no longer square to the interpolated normal, and Gram-Schmidt is what puts it back.
+ * Dropping that step is a normal map that shears wherever the geometry curves.
+ *
+ * Never returns a NaN. A triangle whose three vertices share one texture coordinate has no
+ * direction along the texture at all and the arithmetic divides by zero — which is the common
+ * case in a bought asset rather than an edge case, and a NaN in a vertex buffer takes the whole
+ * triangle off the screen. Those vertices get some unit vector perpendicular to their normal,
+ * which is arbitrary and finite, and arbitrary is the honest answer to an unanswerable question.
+ */
+export function generateTangents(positions, normals, uvs, indices, out) {
+    const vertices = Math.floor(positions.length / 3);
+    const result = out ?? new Float32Array(vertices * 4);
+    const scratch = scratchFor(vertices);
+    const { tangents, bitangents } = scratch;
+    for (let i = 0; i + 2 < indices.length; i += 3) {
+        const a = indices[i] ?? 0;
+        const b = indices[i + 1] ?? 0;
+        const c = indices[i + 2] ?? 0;
+        const x1 = (positions[b * 3] ?? 0) - (positions[a * 3] ?? 0);
+        const y1 = (positions[b * 3 + 1] ?? 0) - (positions[a * 3 + 1] ?? 0);
+        const z1 = (positions[b * 3 + 2] ?? 0) - (positions[a * 3 + 2] ?? 0);
+        const x2 = (positions[c * 3] ?? 0) - (positions[a * 3] ?? 0);
+        const y2 = (positions[c * 3 + 1] ?? 0) - (positions[a * 3 + 1] ?? 0);
+        const z2 = (positions[c * 3 + 2] ?? 0) - (positions[a * 3 + 2] ?? 0);
+        const s1 = (uvs[b * 2] ?? 0) - (uvs[a * 2] ?? 0);
+        const t1 = (uvs[b * 2 + 1] ?? 0) - (uvs[a * 2 + 1] ?? 0);
+        const s2 = (uvs[c * 2] ?? 0) - (uvs[a * 2] ?? 0);
+        const t2 = (uvs[c * 2 + 1] ?? 0) - (uvs[a * 2 + 1] ?? 0);
+        /*
+         * The area of the triangle in texture space. Zero means the three vertices share one
+         * coordinate, so this triangle says nothing about direction and is skipped — leaving its
+         * vertices to whatever their other triangles say, or to the fallback below if they have none.
+         */
+        const area = s1 * t2 - s2 * t1;
+        if (Math.abs(area) < 1e-12)
+            continue;
+        const r = 1 / area;
+        const tx = (t2 * x1 - t1 * x2) * r;
+        const ty = (t2 * y1 - t1 * y2) * r;
+        const tz = (t2 * z1 - t1 * z2) * r;
+        const bx = (s1 * x2 - s2 * x1) * r;
+        const by = (s1 * y2 - s2 * y1) * r;
+        const bz = (s1 * z2 - s2 * z1) * r;
+        /* Written out rather than looped over `[a, b, c]`, which allocates an array per triangle —
+           and a large import has hundreds of thousands of them. */
+        accumulate(tangents, bitangents, a, tx, ty, tz, bx, by, bz);
+        accumulate(tangents, bitangents, b, tx, ty, tz, bx, by, bz);
+        accumulate(tangents, bitangents, c, tx, ty, tz, bx, by, bz);
+    }
+    for (let v = 0; v < vertices; v += 1) {
+        const nx = normals[v * 3] ?? 0;
+        const ny = normals[v * 3 + 1] ?? 0;
+        const nz = normals[v * 3 + 2] ?? 0;
+        let tx = tangents[v * 3] ?? 0;
+        let ty = tangents[v * 3 + 1] ?? 0;
+        let tz = tangents[v * 3 + 2] ?? 0;
+        /* Gram-Schmidt: take out whatever part of the tangent points along the normal. */
+        const along = tx * nx + ty * ny + tz * nz;
+        tx -= nx * along;
+        ty -= ny * along;
+        tz -= nz * along;
+        let length = Math.sqrt(tx * tx + ty * ty + tz * tz);
+        if (length < 1e-8) {
+            /*
+             * No usable direction: a vertex no triangle mentions, or one whose triangles all had no
+             * area in texture space. Any unit vector perpendicular to the normal will do, and the
+             * cross with whichever axis the normal points least along is the one that is never
+             * degenerate.
+             */
+            const ax = Math.abs(nx);
+            const ay = Math.abs(ny);
+            const az = Math.abs(nz);
+            const px = ax <= ay && ax <= az ? 1 : 0;
+            const py = ay < ax && ay <= az ? 1 : 0;
+            const pz = px === 0 && py === 0 ? 1 : 0;
+            tx = ny * pz - nz * py;
+            ty = nz * px - nx * pz;
+            tz = nx * py - ny * px;
+            length = Math.sqrt(tx * tx + ty * ty + tz * tz) || 1;
+        }
+        const inv = 1 / length;
+        result[v * 4] = tx * inv;
+        result[v * 4 + 1] = ty * inv;
+        result[v * 4 + 2] = tz * inv;
+        /*
+         * The handedness. `cross(normal, tangent)` is the bitangent the frame implies; if the one the
+         * texture actually asks for points the other way, `w` is -1 and the shader flips it.
+         */
+        const cx = ny * tz - nz * ty;
+        const cy = nz * tx - nx * tz;
+        const cz = nx * ty - ny * tx;
+        const bx = bitangents[v * 3] ?? 0;
+        const by = bitangents[v * 3 + 1] ?? 0;
+        const bz = bitangents[v * 3 + 2] ?? 0;
+        result[v * 4 + 3] = cx * bx + cy * by + cz * bz < 0 ? -1 : 1;
+    }
+    return result;
+}

package/dist/geometry/textMesh.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Text as static world geometry: one box per lit glyph cell.
+ *
+ * The screen-space `TextRenderer` exists because a grid of cells gives you
+ * *boxes to light* rather than outlines to rasterise. This is the same idea
+ * standing in the world instead of over it — a string that a consumer can merge
+ * into its static mesh, place on a surface's own basis, and light with
+ * everything else. No draw call of its own, no atlas, no font file.
+ *
+ * Laid out in a local frame: x to the right, y up from the baseline, z the
+ * depth the cells stand out through. The caller supplies the basis that turns
+ * that into a place in the world (`MeshBuilder.addOrientedMesh`), which is what
+ * lets a line of text bank with a road or face back along a curve.
+ */
+import type { MeshData } from '../render/mesh.ts';
+import type { Vec3 } from '../math/color.ts';
+export interface TextMeshStyle {
+    /** World size of one glyph cell. A glyph is five of these across, seven tall. */
+    cellSizeM: number;
+    /**
+     * Cell height, where it differs from the width. Defaults to square.
+     *
+     * For text read at a shallow angle: a word laid flat on the ground is
+     * foreshortened along the direction it is read from, and stretching the cells
+     * that way is what road markings have always done about it. It is a property
+     * of the *viewing* rather than of the font, which is why it belongs to a style
+     * and not to the glyph table.
+     */
+    cellHeightM?: number;
+    color: Vec3;
+    /**
+     * Depth through the plane, world units. Defaults to the cell size, which
+     * gives cubes — the shape the flat-shaded look is built out of, and the one
+     * that catches a light from the side rather than going flat as the sun moves.
+     */
+    depthM?: number;
+    emissive?: number;
+    /**
+     * Where the origin sits horizontally. Centred by default: a marker is aimed
+     * at a place, and left-aligning it would move the thing being marked whenever
+     * the string changed length.
+     */
+    align?: 'left' | 'center';
+    /** Where the origin sits vertically: on the baseline, or at the middle. */
+    baseline?: 'bottom' | 'center';
+}
+/** Width of a string in world units, before the basis is applied. */
+export declare function textMeshWidthM(text: string, cellSizeM: number): number;
+/** Height of a line in world units. Every glyph is the same seven cells tall. */
+export declare function textMeshHeightM(cellSizeM: number): number;
+export declare function buildTextMesh(text: string, style: TextMeshStyle): MeshData;

package/dist/geometry/textMesh.js

@@ -0,0 +1,57 @@
+/**
+ * Text as static world geometry: one box per lit glyph cell.
+ *
+ * The screen-space `TextRenderer` exists because a grid of cells gives you
+ * *boxes to light* rather than outlines to rasterise. This is the same idea
+ * standing in the world instead of over it — a string that a consumer can merge
+ * into its static mesh, place on a surface's own basis, and light with
+ * everything else. No draw call of its own, no atlas, no font file.
+ *
+ * Laid out in a local frame: x to the right, y up from the baseline, z the
+ * depth the cells stand out through. The caller supplies the basis that turns
+ * that into a place in the world (`MeshBuilder.addOrientedMesh`), which is what
+ * lets a line of text bank with a road or face back along a curve.
+ */
+import { GLYPH_HEIGHT, forEachRun, measureText } from './pixelFont.js';
+import { MeshBuilder } from './meshBuilder.js';
+/** Width of a string in world units, before the basis is applied. */
+export function textMeshWidthM(text, cellSizeM) {
+    return measureText(text) * cellSizeM;
+}
+/** Height of a line in world units. Every glyph is the same seven cells tall. */
+export function textMeshHeightM(cellSizeM) {
+    return GLYPH_HEIGHT * cellSizeM;
+}
+export function buildTextMesh(text, style) {
+    if (style.cellSizeM <= 0) {
+        throw new Error(`buildTextMesh needs a positive cell size, got ${style.cellSizeM}`);
+    }
+    const cell = style.cellSizeM;
+    const cellHigh = style.cellHeightM ?? cell;
+    const depth = style.depthM ?? cell;
+    const emissive = style.emissive ?? 0;
+    const half = [cell * 0.5, cellHigh * 0.5, depth * 0.5];
+    const offsetX = style.align === 'left' ? 0 : -textMeshWidthM(text, cell) * 0.5;
+    const offsetY = style.baseline === 'center' ? -textMeshHeightM(cellHigh) * 0.5 : 0;
+    const builder = new MeshBuilder();
+    const centre = [0, 0, 0];
+    const extent = [0, half[1], half[2]];
+    /*
+     * **One box per horizontal run, not per lit cell.** The two produce the same outer surface — a
+     * run of three cells and the box that spans them have identical outsides, and what goes is the
+     * interior faces between them, which nothing can ever see. Measured against a consumer's own
+     * 1,168 strings, it takes 65,271 boxes to 42,631: **1.53x**, for a change that is invisible.
+     *
+     * `half[0]` grows with the run and the other two do not, which is why the extent is rebuilt here
+     * rather than reusing `half`.
+     */
+    forEachRun(text, (x, y, width) => {
+        // Cell coordinates address a cell's corner; a box is placed by its centre.
+        extent[0] = width * cell * 0.5;
+        centre[0] = offsetX + (x + width * 0.5) * cell;
+        centre[1] = offsetY + (y + 0.5) * cellHigh;
+        centre[2] = 0;
+        builder.addBox(centre, extent, style.color, emissive);
+    });
+    return builder.build();
+}

package/dist/geometry/treeBuilder.d.ts

@@ -0,0 +1,37 @@
+import type { MeshData } from '../render/mesh.ts';
+import type { Vec3 } from '../math/color.ts';
+/**
+ * Procedural trees from parameters and a seeded RNG.
+ *
+ * Game-agnostic: it takes numbers and a random source and knows nothing about
+ * days, palettes or where a tree is going to stand.
+ *
+ * The geometry comes back in two pieces, and the split is structural rather
+ * than a convenience. The trunk is *solid* — merged into static world geometry
+ * and paired with a collider, so it must never deform, or it would visibly
+ * separate from the thing you collide with. The canopy is *flexible* — drawn as
+ * instanced scatter that bends in the wind, which merging into the static world
+ * would make impossible. A tree that is one mesh can be collidable or animated,
+ * not both.
+ */
+export interface TreeParams {
+    height: number;
+    trunkRadius: number;
+    /** How much narrower the trunk is at the top, 0..1. */
+    taper: number;
+    canopyRadius: number;
+    canopyClusters: number;
+    trunkColor: Vec3;
+    canopyColor: Vec3;
+}
+export interface TreeGeometry {
+    /** Trunk and limbs: collidable, never deformed. */
+    solid: MeshData;
+    /** Canopy: instanced and wind-bent, never collidable. */
+    flexible: MeshData;
+    /** Trunk radius at the base, so a caller can build a matching collider. */
+    colliderRadius: number;
+    /** Height of the solid part, likewise. */
+    colliderHeight: number;
+}
+export declare function buildTree(params: TreeParams, rand: () => number): TreeGeometry;

package/dist/geometry/treeBuilder.js

@@ -0,0 +1,56 @@
+import { MeshBuilder } from './meshBuilder.js';
+const TRUNK_SEGMENTS = 3;
+export function buildTree(params, rand) {
+    if (params.height <= 0 || params.trunkRadius <= 0) {
+        throw new Error('Tree height and trunk radius must be positive.');
+    }
+    const solid = new MeshBuilder();
+    const flexible = new MeshBuilder();
+    /*
+     * Trunk as stacked tapering sections rather than one cylinder: a real trunk
+     * narrows, and the taper is what stops a tree reading as a post with leaves
+     * balanced on it.
+     */
+    const sectionHeight = params.height / TRUNK_SEGMENTS;
+    for (let i = 0; i < TRUNK_SEGMENTS; i++) {
+        const t = i / TRUNK_SEGMENTS;
+        const radius = params.trunkRadius * (1 - params.taper * t);
+        const lean = (rand() - 0.5) * 0.12 * params.height;
+        solid.addCylinder([lean * t, sectionHeight * (i + 0.5), lean * t], Math.max(radius, 0.02), sectionHeight * 0.5, 'y', params.trunkColor, 0, 7);
+    }
+    /*
+     * No separate limbs. `MeshBuilder` only produces axis-aligned boxes and
+     * cylinders, so a "branch" here can only be a vertical stub offset sideways —
+     * which reads as a post floating beside the trunk, not as a limb. The
+     * clustered canopy below carries the silhouette instead. Real branches want
+     * oriented primitives, which is a builder change rather than a tree change.
+     */
+    /*
+     * Canopy as overlapping clusters, not one sphere. A single blob reads as a
+     * lollipop from any angle; clusters give a silhouette that changes as you run
+     * past, which is most of what makes a tree look like a tree at speed.
+     */
+    const canopyBase = params.height * 0.62;
+    for (let i = 0; i < params.canopyClusters; i++) {
+        const angle = rand() * Math.PI * 2;
+        /*
+         * Spread and size are budgeted together so the furthest corner of the
+         * furthest cluster stays inside `canopyRadius` with margin. The placer
+         * keeps trees off the route using that number, so a canopy that quietly
+         * overruns it pokes through geometry it was placed clear of.
+         */
+        const spread = params.canopyRadius * (0.12 + rand() * 0.4);
+        const size = params.canopyRadius * (0.2 + rand() * 0.16);
+        flexible.addBox([
+            Math.cos(angle) * spread,
+            canopyBase + rand() * (params.height - canopyBase) * 0.9,
+            Math.sin(angle) * spread,
+        ], [size, size * (0.62 + rand() * 0.3), size], params.canopyColor, 0);
+    }
+    return {
+        solid: solid.build(),
+        flexible: flexible.build(),
+        colliderRadius: params.trunkRadius,
+        colliderHeight: params.height * 0.62,
+    };
+}

package/dist/host/display.d.ts

@@ -0,0 +1,135 @@
+/**
+ * What the engine may ask about, and ask of, the surface it draws on.
+ *
+ * This is the seam a video settings screen is built on: which window mode the game is in, what
+ * size the drawing surface is, what displays exist, and what the refresh rate is. A browser can
+ * answer some of it and a native shell can answer all of it, so **the browser implementation
+ * returns the value that is true** where it cannot answer — `null` for a refresh rate rather than
+ * 60, and `false` from a call it cannot perform rather than a silent no-op. `AGENTS.md` requires
+ * that of a backend for the same reason it is required here: a plausible answer is a picture
+ * rather than an error, and something will divide by it or grey out the wrong control.
+ *
+ * **There are two window modes and not three, and that is a statement about the platform.**
+ * Chromium never takes an exclusive fullscreen: it does not change the display's mode, it covers
+ * the display. So "borderless fullscreen" and "fullscreen" would be the same setting under two
+ * names, and a settings screen offering both would have one that does nothing. What a game
+ * changes instead of a display mode is *how much it renders* — that is `RenderQuality`'s
+ * `resolutionScale` and the `ResolutionGovernor`, not this interface.
+ *
+ * **Mobile is deliberately not modelled here.** A phone has no window and no window mode; what it
+ * has is an orientation, a set of safe-area insets and a screen that wants to sleep. Those are
+ * `ScreenPresentation`, a separate capability, because a desktop shell has no use for them and a
+ * phone has no use for most of this.
+ *
+ * Taken as parameters, never imported: nothing under `src/` may name a shell, exactly as nothing
+ * under `src/` names `localStorage` outside `KeyValueStore`.
+ *
+ * Not a hot path. Nothing here is called per frame.
+ */
+/** Windowed, or covering the display. See the class comment for why there is no third. */
+export type WindowMode = 'windowed' | 'fullscreen';
+/** A display the game could be shown on, as the platform reports it. */
+export interface DisplayInfo {
+    /** Stable for as long as the display is attached. Opaque: do not parse it. */
+    readonly id: string;
+    /** What to show in a list. A platform that has no name for it repeats the size. */
+    readonly label: string;
+    /** Logical pixels, which is what a window is sized in. */
+    readonly width: number;
+    readonly height: number;
+    /** Device pixels per logical pixel on this display. */
+    readonly scale: number;
+    /** Null where the platform will not say, which includes every browser. */
+    readonly refreshHz: number | null;
+    readonly primary: boolean;
+}
+export interface DisplayControl {
+    /** The refresh rate of the display the game is on, or null where the platform will not say. */
+    readonly refreshHz: number | null;
+    /** Which mode the game is in right now, read rather than remembered. */
+    mode(): WindowMode;
+    /** `false` where the platform refused or cannot. Never rejects. */
+    setMode(mode: WindowMode): Promise<boolean>;
+    isFullscreen(): boolean;
+    /** Never rejects. A browser refuses fullscreen outside a gesture, which is ordinary. */
+    setFullscreen(on: boolean): Promise<void>;
+    /** The drawing surface, in logical pixels. */
+    size(): {
+        readonly width: number;
+        readonly height: number;
+    };
+    /**
+     * Whether `setSize` would work right now, asked without performing one.
+     *
+     * **A question rather than a mutation, since 2026-08-28.** `false` from `setSize` was the only
+     * way to learn this, and `setSize` is the mutator — so a settings screen deciding whether to
+     * draw a resolution control at all had to call the thing that changes the window in order to
+     * find out whether it may. Reported from outside, where the workaround was a no-op probe at
+     * boot, `setSize(...size())`, with a paragraph explaining that it is not what it looks like.
+     *
+     * **Read on each call and not a constant**, for the reason `mode()` is a call: a shell that can
+     * resize a window cannot resize one that is covering a display, so the answer changes with the
+     * window mode. A screen that greys its control reads this when it draws.
+     *
+     * It must agree with `setSize`, and in a shell that agreement is one function rather than two
+     * conditions written twice — see `ipc.ts`. Two implementations of one decision drift, and here
+     * they would drift into a greyed control that works or a live one that does not.
+     *
+     * **The engine already had this shape and this surface lacked it**: `pad.canRumble` says whether
+     * a browser can drive a pad's motors at all, beside a `rumble` that answers whether the call was
+     * taken. A question and a mutation, and the question is the half a settings screen draws with.
+     */
+    canSetSize(): boolean;
+    /**
+     * Resize the drawing surface. `false` where the platform will not — a browser never can, and a
+     * shell will not while the window is covering a display.
+     */
+    setSize(width: number, height: number): Promise<boolean>;
+    /** Every display the platform will admit to. Never empty where at least one is known. */
+    displays(): readonly DisplayInfo[];
+}
+export declare class BrowserDisplay implements DisplayControl {
+    private readonly element;
+    constructor(element: HTMLElement);
+    /**
+     * Null always, here: no browser API reports this.
+     *
+     * Measuring it from frame intervals is possible and is deliberately not done — the answer
+     * would be wrong on exactly the machines that care, where the compositor is capping a display
+     * that runs faster. A shell asks the operating system and knows.
+     */
+    readonly refreshHz: number | null;
+    isFullscreen(): boolean;
+    mode(): WindowMode;
+    setMode(mode: WindowMode): Promise<boolean>;
+    setFullscreen(on: boolean): Promise<void>;
+    size(): {
+        readonly width: number;
+        readonly height: number;
+    };
+    /**
+     * Always false, and it touches nothing to say so.
+     *
+     * The same answer `setSize` gives and for the same reason, which is why they are written next to
+     * each other: a browser cannot resize a window it did not open, so a settings screen greys the
+     * control rather than offering one that quietly does nothing.
+     */
+    canSetSize(): boolean;
+    /**
+     * Always false.
+     *
+     * `window.resizeTo` is refused for anything but a window the script opened itself, so a browser
+     * genuinely cannot do this. Saying so lets a settings screen disable the control; returning
+     * `true` and doing nothing would leave a resolution list that appears to work.
+     */
+    setSize(_width: number, _height: number): Promise<boolean>;
+    /**
+     * The one screen this browser can see.
+     *
+     * One entry rather than none: the browser does know the screen it is on, and an empty list
+     * would make a settings screen report no displays on a machine that plainly has one. What it
+     * does not know is the refresh rate or the names and positions of any other display, and it
+     * says so by leaving them null and absent respectively.
+     */
+    displays(): readonly DisplayInfo[];
+}

package/dist/host/display.js

@@ -0,0 +1,114 @@
+/**
+ * What the engine may ask about, and ask of, the surface it draws on.
+ *
+ * This is the seam a video settings screen is built on: which window mode the game is in, what
+ * size the drawing surface is, what displays exist, and what the refresh rate is. A browser can
+ * answer some of it and a native shell can answer all of it, so **the browser implementation
+ * returns the value that is true** where it cannot answer — `null` for a refresh rate rather than
+ * 60, and `false` from a call it cannot perform rather than a silent no-op. `AGENTS.md` requires
+ * that of a backend for the same reason it is required here: a plausible answer is a picture
+ * rather than an error, and something will divide by it or grey out the wrong control.
+ *
+ * **There are two window modes and not three, and that is a statement about the platform.**
+ * Chromium never takes an exclusive fullscreen: it does not change the display's mode, it covers
+ * the display. So "borderless fullscreen" and "fullscreen" would be the same setting under two
+ * names, and a settings screen offering both would have one that does nothing. What a game
+ * changes instead of a display mode is *how much it renders* — that is `RenderQuality`'s
+ * `resolutionScale` and the `ResolutionGovernor`, not this interface.
+ *
+ * **Mobile is deliberately not modelled here.** A phone has no window and no window mode; what it
+ * has is an orientation, a set of safe-area insets and a screen that wants to sleep. Those are
+ * `ScreenPresentation`, a separate capability, because a desktop shell has no use for them and a
+ * phone has no use for most of this.
+ *
+ * Taken as parameters, never imported: nothing under `src/` may name a shell, exactly as nothing
+ * under `src/` names `localStorage` outside `KeyValueStore`.
+ *
+ * Not a hot path. Nothing here is called per frame.
+ */
+export class BrowserDisplay {
+    element;
+    constructor(element) {
+        this.element = element;
+    }
+    /**
+     * Null always, here: no browser API reports this.
+     *
+     * Measuring it from frame intervals is possible and is deliberately not done — the answer
+     * would be wrong on exactly the machines that care, where the compositor is capping a display
+     * that runs faster. A shell asks the operating system and knows.
+     */
+    refreshHz = null;
+    isFullscreen() {
+        return document.fullscreenElement !== null;
+    }
+    mode() {
+        return this.isFullscreen() ? 'fullscreen' : 'windowed';
+    }
+    async setMode(mode) {
+        const before = this.mode();
+        await this.setFullscreen(mode === 'fullscreen');
+        /* Read back rather than assume: a browser refuses fullscreen outside a user gesture and
+           says nothing, and a settings screen that believed the request would show the wrong state
+           until something else redrew it. */
+        const after = this.mode();
+        return after === mode || before === mode;
+    }
+    async setFullscreen(on) {
+        try {
+            if (on)
+                await this.element.requestFullscreen?.();
+            else
+                await document.exitFullscreen?.();
+        }
+        catch {
+            /* A refusal is normal: fullscreen needs a user gesture and the caller may not be in one.
+               Throwing would put a try/catch in every consumer's settings screen. */
+        }
+    }
+    size() {
+        return { width: window.innerWidth, height: window.innerHeight };
+    }
+    /**
+     * Always false, and it touches nothing to say so.
+     *
+     * The same answer `setSize` gives and for the same reason, which is why they are written next to
+     * each other: a browser cannot resize a window it did not open, so a settings screen greys the
+     * control rather than offering one that quietly does nothing.
+     */
+    canSetSize() {
+        return false;
+    }
+    /**
+     * Always false.
+     *
+     * `window.resizeTo` is refused for anything but a window the script opened itself, so a browser
+     * genuinely cannot do this. Saying so lets a settings screen disable the control; returning
+     * `true` and doing nothing would leave a resolution list that appears to work.
+     */
+    async setSize(_width, _height) {
+        return false;
+    }
+    /**
+     * The one screen this browser can see.
+     *
+     * One entry rather than none: the browser does know the screen it is on, and an empty list
+     * would make a settings screen report no displays on a machine that plainly has one. What it
+     * does not know is the refresh rate or the names and positions of any other display, and it
+     * says so by leaving them null and absent respectively.
+     */
+    displays() {
+        const screen = window.screen;
+        return [
+            {
+                id: 'browser',
+                label: `${screen.width}x${screen.height}`,
+                width: screen.width,
+                height: screen.height,
+                scale: window.devicePixelRatio,
+                refreshHz: null,
+                primary: true,
+            },
+        ];
+    }
+}

package/dist/host/files.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Choosing a file, and writing one out.
+ *
+ * **Nothing in a game needs this**; an editor does, which is why it is a separate capability
+ * rather than a member of a larger one — a consumer that never opens a file never has to supply
+ * it. `AGENTS.md` calls this the SDF-text shape: opt-in costs a consumer nothing until asked for.
+ *
+ * **A cancel and an absent API are different answers.** Cancel is `null`, because a person
+ * changing their mind is ordinary. No picker at all throws, because that is a boot-time
+ * capability failure and the caller should say so rather than show an empty screen.
+ */
+export interface OpenedFile {
+    readonly name: string;
+    readonly bytes: Uint8Array;
+}
+export interface FileDialogs {
+    /** `null` when the person cancelled. Throws when the platform has no picker. */
+    openFile(accept: readonly string[]): Promise<OpenedFile | null>;
+    /** `false` when the person cancelled. Throws when the platform has no picker. */
+    saveFile(name: string, bytes: Uint8Array): Promise<boolean>;
+}
+export declare class BrowserFileDialogs implements FileDialogs {
+    openFile(accept: readonly string[]): Promise<OpenedFile | null>;
+    saveFile(name: string, bytes: Uint8Array): Promise<boolean>;
+}

package/dist/host/files.js

@@ -0,0 +1,44 @@
+export class BrowserFileDialogs {
+    async openFile(accept) {
+        const picker = globalThis.showOpenFilePicker;
+        if (typeof picker !== 'function') {
+            throw new Error('[driftengine] no file picker in this browser; a shell supplies one');
+        }
+        try {
+            const [handle] = await picker({
+                /* One entry rather than one per extension: the map's keys are MIME types and the
+                   engine's own container has none registered, so the extensions carry the filter. */
+                types: [{ description: 'files', accept: { '*/*': [...accept] } }],
+            });
+            if (handle === undefined)
+                return null;
+            const file = await handle.getFile();
+            return { name: file.name, bytes: new Uint8Array(await file.arrayBuffer()) };
+        }
+        catch {
+            /* Every rejection here is a cancel: the picker was present, so a failure to produce a
+               file is a person who closed it. A real read error surfaces from `getFile` as a throw
+               that this also swallows, which is the one case where null is thin — and a caller that
+               got null after a chooser closed has nothing better to do either way. */
+            return null;
+        }
+    }
+    async saveFile(name, bytes) {
+        const picker = globalThis.showSaveFilePicker;
+        if (typeof picker !== 'function') {
+            throw new Error('[driftengine] no save picker in this browser; a shell supplies one');
+        }
+        try {
+            const handle = await picker({
+                suggestedName: name,
+            });
+            const writable = await handle.createWritable();
+            await writable.write(bytes);
+            await writable.close();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}