@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/fx/random.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The fx module's default randomness (ws/fx-4). Every random draw in `src/fx` goes through a
+ * core `Random`; an object built without one forks its own stream from one module default,
+ * seeded once with `FX_DEFAULT_SEED`. Forks are named by kind and creation index
+ * (`particles#0`, `decals#1`, …), so a page that builds the same objects in the same order gets
+ * the same numbers on every load. Pass `random` (`createRandom(seed)` or a fork of a game's
+ * own stream) to make an object independent of construction order.
+ */
+import { type Random } from '../core/random.js';
+/** The seed of the fx module's default stream. */
+export declare const FX_DEFAULT_SEED = "thunderclap-fx";
+/** Largest particle spawn seed (exactly representable in a `f32`). */
+export declare const SPAWN_SEED_MAX = 16777214;
+/** A fork of the module default (`FX_DEFAULT_SEED`) for one object of `kind`. */
+export declare function defaultFxRandom(kind: string): Random;

package/dist/fx/random.js

@@ -0,0 +1,20 @@
+/**
+ * The fx module's default randomness (ws/fx-4). Every random draw in `src/fx` goes through a
+ * core `Random`; an object built without one forks its own stream from one module default,
+ * seeded once with `FX_DEFAULT_SEED`. Forks are named by kind and creation index
+ * (`particles#0`, `decals#1`, …), so a page that builds the same objects in the same order gets
+ * the same numbers on every load. Pass `random` (`createRandom(seed)` or a fork of a game's
+ * own stream) to make an object independent of construction order.
+ */
+import { createRandom } from '../core/random.js';
+/** The seed of the fx module's default stream. */
+export const FX_DEFAULT_SEED = 'thunderclap-fx';
+/** Largest particle spawn seed (exactly representable in a `f32`). */
+export const SPAWN_SEED_MAX = 16777214;
+let root = null;
+let forks = 0;
+/** A fork of the module default (`FX_DEFAULT_SEED`) for one object of `kind`. */
+export function defaultFxRandom(kind) {
+    root ??= createRandom(FX_DEFAULT_SEED);
+    return root.fork(`${kind}#${forks++}`);
+}

package/dist/fx/sky-wgsl.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The sky shader: one fullscreen triangle at the far plane whose fragment reconstructs the view
+ * ray from the camera block and shades a procedural dome.
+ *
+ * View ray. The camera block carries `proj` and `view`, no inverse. A perspective projection
+ * (including an off-centre XR one) inverts analytically: with `vz = -1`,
+ * `ndc.x = (p00 * vx + p20 * vz) / (p23 * vz)` gives `vx = (p20 - p23 * ndc.x) / p00`, and y the
+ * same with `p11`, `p21`. The world direction is the view rotation's transpose applied to that
+ * (`dot(view[i].xyz, d)` per component, the view's columns). An orthographic projection
+ * (`p23 == 0`) has one view direction, the camera's forward (`-z`, or `+z` when `p22 > 0`, the
+ * 2D camera's convention). `skyRay` in `sky.ts` is the same
+ * math in TypeScript, tested against `Camera.screenToWorld`.
+ *
+ * Colour, all in linear space: zenith → horizon → ground by the ray's elevation; a band around
+ * the horizon mixes towards `lights.fog` (scaled by its density) so fogged geometry meets the
+ * sky; the sun disc (`sunSize` radians of angular radius, `sky.horizon.w`) and two glow lobes
+ * (`sunGlow`, `sky.ground.w`) tinted by `lights.sun_color` at `-lights.sun_dir`; when the sun
+ * is below the horizon the dome darkens and the stars (a hash of the direction on a grid of
+ * `density` cells per unit) appear. Without a sun (colour all zero) the dome is as set and the
+ * stars, if on, are full. The sun disc and the stars also go to the emissive target so bloom
+ * picks them up.
+ */
+export declare const SKY_WGSL: string;

package/dist/fx/sky-wgsl.js

@@ -0,0 +1,127 @@
+import { WGSL_GLOBALS, WGSL_LIGHTS, WGSL_NOISE } from '../render/wgsl.js';
+/**
+ * The sky shader: one fullscreen triangle at the far plane whose fragment reconstructs the view
+ * ray from the camera block and shades a procedural dome.
+ *
+ * View ray. The camera block carries `proj` and `view`, no inverse. A perspective projection
+ * (including an off-centre XR one) inverts analytically: with `vz = -1`,
+ * `ndc.x = (p00 * vx + p20 * vz) / (p23 * vz)` gives `vx = (p20 - p23 * ndc.x) / p00`, and y the
+ * same with `p11`, `p21`. The world direction is the view rotation's transpose applied to that
+ * (`dot(view[i].xyz, d)` per component, the view's columns). An orthographic projection
+ * (`p23 == 0`) has one view direction, the camera's forward (`-z`, or `+z` when `p22 > 0`, the
+ * 2D camera's convention). `skyRay` in `sky.ts` is the same
+ * math in TypeScript, tested against `Camera.screenToWorld`.
+ *
+ * Colour, all in linear space: zenith → horizon → ground by the ray's elevation; a band around
+ * the horizon mixes towards `lights.fog` (scaled by its density) so fogged geometry meets the
+ * sky; the sun disc (`sunSize` radians of angular radius, `sky.horizon.w`) and two glow lobes
+ * (`sunGlow`, `sky.ground.w`) tinted by `lights.sun_color` at `-lights.sun_dir`; when the sun
+ * is below the horizon the dome darkens and the stars (a hash of the direction on a grid of
+ * `density` cells per unit) appear. Without a sun (colour all zero) the dome is as set and the
+ * stars, if on, are full. The sun disc and the stars also go to the emissive target so bloom
+ * picks them up.
+ */
+export const SKY_WGSL = /* wgsl */ `
+${WGSL_GLOBALS}
+${WGSL_LIGHTS}
+${WGSL_NOISE}
+struct SkyParams {
+  zenith: vec4f,   // rgb, exposure
+  horizon: vec4f,  // rgb, sun angular radius (radians)
+  ground: vec4f,   // rgb, sun glow
+  stars: vec4f,    // density, seed, enabled, night floor
+};
+@group(1) @binding(0) var<uniform> sky: SkyParams;
+
+struct SkyOut {
+  @builtin(position) clip: vec4f,
+  @location(0) ndc: vec2f,
+};
+
+struct FragOut {
+  @location(0) color: vec4f,
+  @location(1) emissive: vec4f,
+};
+
+// One triangle covering clip space, at the far plane (z = 1): with depth compare less-equal
+// and no depth write, geometry drawn before or after it always wins.
+@vertex fn vs(@builtin(vertex_index) i: u32) -> SkyOut {
+  let x = f32(i32(i & 1u) * 4 - 1);
+  let y = f32(i32(i >> 1u) * 4 - 1);
+  var o: SkyOut;
+  o.clip = vec4f(x, y, 1.0, 1.0);
+  o.ndc = vec2f(x, y);
+  return o;
+}
+
+fn sky_ray(ndc: vec2f) -> vec3f {
+  let p = camera.proj;
+  var d = vec3f(0.0, 0.0, -1.0);
+  if (p[2][3] != 0.0) {
+    d.x = (p[2][0] - p[2][3] * ndc.x) / p[0][0];
+    d.y = (p[2][1] - p[2][3] * ndc.y) / p[1][1];
+  } else if (p[2][2] > 0.0) {
+    d.z = 1.0; // an orthographic view that looks down +z (the 2D camera)
+  }
+  let v = camera.view;
+  return normalize(vec3f(dot(v[0].xyz, d), dot(v[1].xyz, d), dot(v[2].xyz, d)));
+}
+
+fn sky_stars(d: vec3f, density: f32, seed: f32) -> f32 {
+  let p = d * density;
+  let cell = floor(p);
+  let key = cell.xy + vec2f(cell.z * 37.0 + seed, cell.z * 11.0 - seed);
+  let h = engine_hash22(key);
+  let hz = engine_hash21(key + 17.0);
+  let bright = engine_hash21(key + 41.0);
+  if (bright < 0.72) { return 0.0; }
+  let centre = normalize(cell + 0.5 + (vec3f(h, hz) - 0.5) * 0.8);
+  let r = 0.07 / density;
+  let c = dot(d, centre);
+  let edge = 1.0 - r * r * 0.5;
+  let s = smoothstep(edge, edge + r * r * 0.4, c);
+  return s * (0.4 + 0.6 * (bright - 0.72) / 0.28);
+}
+
+@fragment fn fs(in: SkyOut) -> FragOut {
+  let d = sky_ray(in.ndc);
+  let up = d.y;
+  let exposure = sky.zenith.w;
+
+  // The dome.
+  let above = mix(sky.horizon.rgb, sky.zenith.rgb, pow(saturate(up), 0.6));
+  let below = mix(sky.horizon.rgb, sky.ground.rgb, smoothstep(0.0, 0.25, -up));
+  var col = select(below, above, up >= 0.0);
+
+  // Horizon haze towards the fog colour, so fogged ground meets the sky.
+  let haze = saturate(lights.fog.w) * exp(-abs(up) * 6.0);
+  col = mix(col, lights.fog.rgb, haze);
+
+  // Day and night from the sun's elevation; no sun at all leaves the dome as set.
+  let to_sun = -lights.sun_dir;
+  let sun_color = lights.sun_color;
+  let has_sun = dot(sun_color, vec3f(1.0)) > 0.0;
+  let day = select(1.0, smoothstep(-0.12, 0.08, to_sun.y), has_sun);
+  col *= mix(sky.stars.w, 1.0, day);
+
+  // Sun disc and glow.
+  let cos_a = dot(d, to_sun);
+  let cos_disc = cos(sky.horizon.w);
+  let disc = smoothstep(cos_disc - 0.0004, cos_disc, cos_a) * smoothstep(-0.02, 0.0, up);
+  let glow = sky.ground.w * (0.3 * pow(saturate(cos_a), 16.0) + pow(saturate(cos_a), 256.0));
+  let sun = sun_color * (disc * 12.0 + glow);
+  col += sun;
+
+  // Stars at night.
+  var stars = 0.0;
+  if (sky.stars.z > 0.5) {
+    stars = sky_stars(d, sky.stars.x, sky.stars.y) * (1.0 - day) * smoothstep(-0.05, 0.05, up);
+  }
+  col += vec3f(stars * 2.0);
+
+  var o: FragOut;
+  o.color = vec4f(col * exposure, 1.0);
+  o.emissive = vec4f((sun_color * disc * 2.0 + vec3f(stars * 1.5)) * exposure, 1.0);
+  return o;
+}
+`;

package/dist/fx/sky.d.ts

@@ -0,0 +1,96 @@
+import type { Camera } from '../render/camera.js';
+import type { Drawable, Frame } from '../render/frame.js';
+import type { Renderer } from '../render/renderer.js';
+/** Floats in the sky's params block (4 × vec4f, 64 bytes). */
+export declare const SKY_PARAMS_FLOATS = 16;
+/** Starfield settings (`Sky.stars`). */
+export interface SkyStars {
+    /** Grid cells per unit of direction; more cells, more and smaller stars. Default 24. */
+    density: number;
+    /** Shuffles the field. Default 0. */
+    seed: number;
+}
+export interface SkyOptions {
+    /** Linear RGB straight up. Default a clear blue. */
+    zenith?: ArrayLike<number>;
+    /** Linear RGB at the horizon. Default a pale haze. */
+    horizon?: ArrayLike<number>;
+    /** Linear RGB below the horizon (where no geometry covers the dome). Default a dark earth. */
+    ground?: ArrayLike<number>;
+    /** Angular radius of the sun disc, radians. Default 0.03. */
+    sunSize?: number;
+    /** Strength of the glow around the sun (0 for none). Default 1. */
+    sunGlow?: number;
+    /** Stars at night: `true` for the defaults, or `{ density, seed }`. Default off. */
+    stars?: boolean | Partial<SkyStars>;
+    /** Multiplier on the whole dome. Default 1. */
+    exposure?: number;
+    /**
+     * How dark the dome goes at night, as a fraction of its daytime colour (the floor of the
+     * day/night fade driven by the sun's elevation). Default 0.06. Raise it for brighter nights,
+     * lower it towards 0 for black skies behind the stars.
+     */
+    ambientFloor?: number;
+}
+/**
+ * A procedural sky: a gradient dome with a sun disc and glow that follow `frame.lights.sun`,
+ * horizon haze towards `frame.lights.fog.color`, and stars once the sun sets. One fullscreen
+ * triangle, no asset, no instance; `frame.drawable(sky)` draws it.
+ *
+ * It reads the sun and fog from the lights block the renderer uploads with every view, so its
+ * only upload is the 64-byte params block, written once per frame in `prepare`. The fields are
+ * live: mutate `zenith`, `sunSize`, `stars`... and the next frame shows it.
+ *
+ * Depth: under a depth camera the triangle sits at the far plane with depth compare
+ * `less-equal` and no depth write (the test-only state, `DepthMode` 1), so geometry drawn before
+ * or after it wins wherever it wrote depth and the sky fills the rest. Without depth (a 2D
+ * camera) it paints the whole view; give it the lowest `order` then. Nothing to cull.
+ */
+export declare class Sky implements Drawable {
+    /** Linear RGB straight up. Live. */
+    readonly zenith: Float32Array<ArrayBuffer>;
+    /** Linear RGB at the horizon. Live. */
+    readonly horizon: Float32Array<ArrayBuffer>;
+    /** Linear RGB below the horizon. Live. */
+    readonly ground: Float32Array<ArrayBuffer>;
+    /** Angular radius of the sun disc, radians. Live. */
+    sunSize: number;
+    /** Glow strength around the sun. Live. */
+    sunGlow: number;
+    /** Starfield settings, or null for no stars. Live (replace or mutate). */
+    stars: SkyStars | null;
+    /** Multiplier on the whole dome. Live. */
+    exposure: number;
+    /** Night brightness as a fraction of day (`SkyOptions.ambientFloor`). Live. */
+    ambientFloor: number;
+    private readonly device;
+    private readonly params;
+    private readonly paramsBuffer;
+    private readonly group;
+    private readonly desc;
+    private readonly renderer;
+    /**
+     * Pipelines per depth format (null: none; a depth one tests without writing) × the view
+     * target's aux key, built on first use from `renderer.sceneTargets` (ws/render-10).
+     */
+    private readonly pipelines;
+    constructor(renderer: Renderer, opts?: SkyOptions);
+    /**
+     * Pack the live fields into the params block (`SKY_PARAMS_FLOATS` floats: zenith rgb +
+     * exposure, horizon rgb + sunSize, ground rgb + sunGlow, stars density, seed, enabled,
+     * ambientFloor) and
+     * upload it. Called by the renderer once per frame. No allocation.
+     */
+    prepare(_encoder: GPUCommandEncoder, _frame?: Frame): void;
+    /** Draw inside the scene pass: one 3-vertex draw, a depth pipeline when the frame has depth. */
+    draw(pass: GPURenderPassEncoder, frame?: Frame): void;
+    private pipelineFor;
+    destroy(): void;
+}
+/**
+ * The world-space view direction through clip point (`nx`, `ny`) (NDC, -1..1, y up) of
+ * `camera`, into `out` (normalised): the math the sky shader runs per pixel, from the camera's
+ * `projection` and `view` alone. A perspective projection is inverted analytically (its
+ * off-centre terms included); an orthographic one gives the camera's forward for every pixel.
+ */
+export declare function skyRay(camera: Camera, nx: number, ny: number, out: Float32Array): Float32Array;

package/dist/fx/sky.js

@@ -0,0 +1,175 @@
+import { auxSuffix, ScenePipelineCache, sceneVariant } from '../render/scene-pipelines.js';
+import { createShaderModule } from '../render/wgsl.js';
+import { SKY_WGSL } from './sky-wgsl.js';
+/** Floats in the sky's params block (4 × vec4f, 64 bytes). */
+export const SKY_PARAMS_FLOATS = 16;
+const DEFAULT_ZENITH = [0.18, 0.38, 0.85];
+const DEFAULT_HORIZON = [0.62, 0.72, 0.9];
+const DEFAULT_GROUND = [0.22, 0.2, 0.18];
+const DEFAULT_STARS = { density: 24, seed: 0 };
+/**
+ * A procedural sky: a gradient dome with a sun disc and glow that follow `frame.lights.sun`,
+ * horizon haze towards `frame.lights.fog.color`, and stars once the sun sets. One fullscreen
+ * triangle, no asset, no instance; `frame.drawable(sky)` draws it.
+ *
+ * It reads the sun and fog from the lights block the renderer uploads with every view, so its
+ * only upload is the 64-byte params block, written once per frame in `prepare`. The fields are
+ * live: mutate `zenith`, `sunSize`, `stars`... and the next frame shows it.
+ *
+ * Depth: under a depth camera the triangle sits at the far plane with depth compare
+ * `less-equal` and no depth write (the test-only state, `DepthMode` 1), so geometry drawn before
+ * or after it wins wherever it wrote depth and the sky fills the rest. Without depth (a 2D
+ * camera) it paints the whole view; give it the lowest `order` then. Nothing to cull.
+ */
+export class Sky {
+    /** Linear RGB straight up. Live. */
+    zenith = new Float32Array(3);
+    /** Linear RGB at the horizon. Live. */
+    horizon = new Float32Array(3);
+    /** Linear RGB below the horizon. Live. */
+    ground = new Float32Array(3);
+    /** Angular radius of the sun disc, radians. Live. */
+    sunSize;
+    /** Glow strength around the sun. Live. */
+    sunGlow;
+    /** Starfield settings, or null for no stars. Live (replace or mutate). */
+    stars;
+    /** Multiplier on the whole dome. Live. */
+    exposure;
+    /** Night brightness as a fraction of day (`SkyOptions.ambientFloor`). Live. */
+    ambientFloor;
+    device;
+    params;
+    paramsBuffer;
+    group;
+    desc;
+    renderer;
+    /**
+     * Pipelines per depth format (null: none; a depth one tests without writing) × the view
+     * target's aux key, built on first use from `renderer.sceneTargets` (ws/render-10).
+     */
+    pipelines = new ScenePipelineCache();
+    constructor(renderer, opts = {}) {
+        const device = renderer.device;
+        this.device = device;
+        this.renderer = renderer;
+        set3(this.zenith, opts.zenith ?? DEFAULT_ZENITH);
+        set3(this.horizon, opts.horizon ?? DEFAULT_HORIZON);
+        set3(this.ground, opts.ground ?? DEFAULT_GROUND);
+        this.sunSize = opts.sunSize ?? 0.03;
+        this.sunGlow = opts.sunGlow ?? 1;
+        this.exposure = opts.exposure ?? 1;
+        this.ambientFloor = opts.ambientFloor ?? 0.06;
+        const s = opts.stars;
+        this.stars = s
+            ? {
+                density: (s === true ? undefined : s.density) ?? DEFAULT_STARS.density,
+                seed: (s === true ? undefined : s.seed) ?? DEFAULT_STARS.seed,
+            }
+            : null;
+        this.params = new Float32Array(SKY_PARAMS_FLOATS);
+        this.paramsBuffer = device.createBuffer({
+            label: 'sky-params',
+            size: this.params.byteLength,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        });
+        const layout = device.createBindGroupLayout({
+            label: 'sky-layout',
+            entries: [{ binding: 0, visibility: GPUShaderStage.FRAGMENT, buffer: {} }],
+        });
+        this.group = device.createBindGroup({
+            label: 'sky',
+            layout,
+            entries: [{ binding: 0, resource: { buffer: this.paramsBuffer } }],
+        });
+        const module = createShaderModule(device, SKY_WGSL, 'sky');
+        this.desc = {
+            label: 'sky',
+            layout: device.createPipelineLayout({ bindGroupLayouts: [renderer.globalsLayout, layout] }),
+            vertex: { module, entryPoint: 'vs' },
+            fragment: {
+                module,
+                entryPoint: 'fs',
+                targets: renderer.sceneTargets(),
+            },
+            primitive: { topology: 'triangle-list', cullMode: 'none' },
+        };
+        this.pipelines.set(null, renderer.target.auxKey, device.createRenderPipeline(this.desc));
+    }
+    /**
+     * Pack the live fields into the params block (`SKY_PARAMS_FLOATS` floats: zenith rgb +
+     * exposure, horizon rgb + sunSize, ground rgb + sunGlow, stars density, seed, enabled,
+     * ambientFloor) and
+     * upload it. Called by the renderer once per frame. No allocation.
+     */
+    prepare(_encoder, _frame) {
+        const p = this.params;
+        p[0] = this.zenith[0];
+        p[1] = this.zenith[1];
+        p[2] = this.zenith[2];
+        p[3] = this.exposure;
+        p[4] = this.horizon[0];
+        p[5] = this.horizon[1];
+        p[6] = this.horizon[2];
+        p[7] = this.sunSize;
+        p[8] = this.ground[0];
+        p[9] = this.ground[1];
+        p[10] = this.ground[2];
+        p[11] = this.sunGlow;
+        const s = this.stars;
+        p[12] = s ? s.density : 0;
+        p[13] = s ? s.seed : 0;
+        p[14] = s ? 1 : 0;
+        p[15] = this.ambientFloor;
+        this.device.queue.writeBuffer(this.paramsBuffer, 0, p);
+    }
+    /** Draw inside the scene pass: one 3-vertex draw, a depth pipeline when the frame has depth. */
+    draw(pass, frame) {
+        const fmt = frame?.depthFormat ?? null;
+        pass.setPipeline(this.pipelineFor(fmt, frame ? frame.auxKey : this.renderer.target.auxKey));
+        pass.setBindGroup(1, this.group);
+        pass.draw(3);
+    }
+    pipelineFor(format, aux) {
+        const p = this.pipelines.get(format, aux);
+        if (p)
+            return p;
+        return this.pipelines.set(format, aux, this.device.createRenderPipeline(sceneVariant(this.desc, this.renderer.sceneTargets(undefined, aux), `sky${format ? `:${format}` : ''}${auxSuffix(aux)}`, format ? { format, depthWriteEnabled: false, depthCompare: 'less-equal' } : undefined)));
+    }
+    destroy() {
+        this.paramsBuffer.destroy();
+    }
+}
+/**
+ * The world-space view direction through clip point (`nx`, `ny`) (NDC, -1..1, y up) of
+ * `camera`, into `out` (normalised): the math the sky shader runs per pixel, from the camera's
+ * `projection` and `view` alone. A perspective projection is inverted analytically (its
+ * off-centre terms included); an orthographic one gives the camera's forward for every pixel.
+ */
+export function skyRay(camera, nx, ny, out) {
+    const p = camera.projection;
+    const v = camera.view;
+    // Column-major: p[c * 4 + r].
+    const p23 = p[11];
+    let dx = 0;
+    let dy = 0;
+    if (p23 !== 0) {
+        dx = (p[8] - p23 * nx) / p[0];
+        dy = (p[9] - p23 * ny) / p[5];
+    }
+    // Orthographic: every pixel looks along the camera's forward (+z for the 2D camera).
+    const dz = p23 === 0 && p[10] > 0 ? 1 : -1;
+    const wx = v[0] * dx + v[1] * dy + v[2] * dz;
+    const wy = v[4] * dx + v[5] * dy + v[6] * dz;
+    const wz = v[8] * dx + v[9] * dy + v[10] * dz;
+    const k = 1 / Math.hypot(wx, wy, wz);
+    out[0] = wx * k;
+    out[1] = wy * k;
+    out[2] = wz * k;
+    return out;
+}
+function set3(out, v) {
+    out[0] = v[0] ?? 0;
+    out[1] = v[1] ?? 0;
+    out[2] = v[2] ?? 0;
+}

package/dist/fx/text-atlas.d.ts

@@ -0,0 +1,143 @@
+/**
+ * A canvas text atlas: strings rasterised once with `CanvasRenderingContext2D.fillText` into
+ * one square canvas, packed on shelves, cached by text and style, with least-recently-used
+ * eviction when the canvas is full. No GPU and no DOM beyond the canvas itself: the owner
+ * uploads `canvas` when `dirty` is set (`Billboards` does it once per frame at most).
+ */
+/** How a string is drawn into the atlas. Colours are CSS colour strings (the canvas's). */
+export interface TextStyle {
+    /** CSS font family (and weight), e.g. `'bold sans-serif'`. Default: the atlas's font. */
+    font?: string;
+    /** Font size in atlas px. Default 32. */
+    size?: number;
+    /** Fill colour. Default `'#fff'`. */
+    color?: string;
+    /** Outline colour; none when unset. */
+    stroke?: string;
+    /** Outline width in atlas px. Default 0 (none even with `stroke`). */
+    strokeWidth?: number;
+    /** Transparent px kept around the glyphs on every side. Default 2. */
+    padding?: number;
+}
+/**
+ * A rectangle of the atlas: the uv rect to sample (`u0, v0` top left, `u1, v1` bottom right, v
+ * down as in the canvas) and its size in atlas px, for a billboard's aspect ratio.
+ */
+export interface AtlasRegion {
+    u0: number;
+    v0: number;
+    u1: number;
+    v1: number;
+    /** Size in atlas px. */
+    width: number;
+    height: number;
+}
+/** The subset of the canvas 2D context the atlas draws with (so tests can stub it). */
+export interface AtlasContext2D {
+    font: string;
+    textBaseline: CanvasTextBaseline;
+    textAlign: CanvasTextAlign;
+    fillStyle: string | CanvasGradient | CanvasPattern;
+    strokeStyle: string | CanvasGradient | CanvasPattern;
+    lineWidth: number;
+    lineJoin: CanvasLineJoin;
+    measureText(text: string): {
+        width: number;
+    };
+    fillText(text: string, x: number, y: number): void;
+    strokeText(text: string, x: number, y: number): void;
+    clearRect(x: number, y: number, w: number, h: number): void;
+}
+/** The canvas the atlas draws into: an `OffscreenCanvas`, an `HTMLCanvasElement` or a stub. */
+export interface AtlasCanvas {
+    width: number;
+    height: number;
+    getContext(kind: '2d'): AtlasContext2D | null;
+}
+export interface TextAtlasOptions {
+    /** Canvas side in px (square). Default 1024. */
+    size?: number;
+    /** Default font family for styles without one. Default `'sans-serif'`. */
+    font?: string;
+    /**
+     * The canvas to draw into. Default: an `OffscreenCanvas` when the platform has one, else a
+     * `document.createElement('canvas')`. Tests pass a stub with a fake 2D context.
+     */
+    canvas?: AtlasCanvas;
+}
+/**
+ * Text rendered once into a canvas and shared by every quad that shows it. `text(text, style)`
+ * returns the cached `AtlasRegion` or rasterises and packs a new one; when the canvas is full the
+ * least recently used shelf is cleared and reused. Read `dirty` and `canvas` to upload, then
+ * call `markUploaded()`.
+ */
+export declare class TextAtlas {
+    readonly size: number;
+    readonly canvas: AtlasCanvas;
+    /** The canvas has text the GPU has not seen yet. */
+    dirty: boolean;
+    /** Strings currently cached. */
+    count: number;
+    /** Evictions so far (shelves cleared because the canvas was full). */
+    evictions: number;
+    private readonly ctx;
+    private readonly font;
+    private readonly cache;
+    private readonly shelves;
+    /** Next free y for a new shelf. */
+    private top;
+    private tick;
+    /** Owned cells made so far (their cache keys). */
+    private cells;
+    constructor(opts?: TextAtlasOptions);
+    /** Atlas px in use, as a share of the canvas (shelf area, 0..1). */
+    get used(): number;
+    /**
+     * The region for `text` in `style`: cached, or rasterised now. Returns `null` only when the
+     * string is wider or taller than the whole canvas.
+     */
+    text(text: string, style?: TextStyle): AtlasRegion | null;
+    /**
+     * An **owned** cell for text that changes (ws/fx-4): not shared through the cache, its width
+     * rounded up for headroom, the region covering the whole cell with `text` centred in it.
+     * Change its text with `rewrite`; `release` it when done. Evicted like any string when the
+     * canvas is full and it is the least recently used (`touch` keeps it). Returns `null` only
+     * when the text is larger than the whole canvas.
+     */
+    cell(text: string, style?: TextStyle): AtlasRegion | null;
+    /** The size in atlas px `cell(text, style)` would get, without placing anything. */
+    cellSize(text: string, style?: TextStyle): {
+        width: number;
+        height: number;
+    };
+    /**
+     * Redraw an owned cell with `text`, in place (the same region object, nothing allocated) when
+     * it fits the cell, else in a new wider cell (the old one released). Also a new cell when
+     * `cell` was evicted since. Returns `null` when the text is larger than the whole canvas.
+     */
+    rewrite(cell: AtlasRegion, text: string): AtlasRegion | null;
+    /** Give back an owned cell (a no-op for a cached string or one already released/evicted). */
+    release(cell: AtlasRegion): void;
+    /** Mark `region` as used now, so a live quad's text is not the first evicted. */
+    touch(region: AtlasRegion): void;
+    /** Is `region` still what it was made for (not evicted since)? */
+    has(region: AtlasRegion): boolean;
+    /** The owner uploaded `canvas`. */
+    markUploaded(): void;
+    /** Forget every string and clear the canvas. */
+    clear(): void;
+    private resolve;
+    private measure;
+    private lineHeight;
+    private makeCell;
+    /** Place, size and cache a `w × h` entry under `key`. */
+    private make;
+    /** Clear `e`'s rect and draw `text` centred in it. */
+    private draw;
+    /** Find or make room for a `w × h` rect: a fitting shelf, a new shelf, or an evicted one. */
+    private place;
+    private fit;
+    private alloc;
+    private evict;
+    private recycle;
+}