@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/render/gpu-timer.d.ts

@@ -0,0 +1,73 @@
+/**
+ * GPU pass timing with `timestamp-query` (feature-detected; see `initGpu`).
+ *
+ * One sampled frame is in flight at a time. On a sampled frame, every pass that asks for
+ * `pass(label)` gets begin/end timestamp writes; passes sharing a label are summed (the bloom
+ * mip chain is many passes, one label). `mark()` opens the frame with an empty compute pass so
+ * the work encoded before the first labelled pass (pre-passes, drawable prepare) is counted.
+ *
+ * Results land in `result` (plain object, reused) after the readback maps. Per-frame work is
+ * allocation-free apart from the `mapAsync` promise and the mapped range on sampled frames.
+ */
+/** Pass label → GPU ms for the last resolved frame. */
+export type GpuPassTimes = Record<string, number>;
+export interface GpuTimerResult {
+    /** First timestamp to last timestamp of the sampled frame (ms). */
+    totalMs: number;
+    /** Per-label sums (ms). `pre` is the gap between `mark()` and the first labelled pass. */
+    passes: GpuPassTimes;
+    /** Frames resolved so far. */
+    samples: number;
+}
+/** True when the device was created with the `timestamp-query` feature. */
+export declare function supportsTimestamps(device: GPUDevice): boolean;
+export declare class GpuTimer {
+    readonly maxPasses: number;
+    readonly result: GpuTimerResult;
+    /** True between `begin()` and `resolve()`: passes should take `pass(label)` writes. */
+    active: boolean;
+    private readonly querySet;
+    private readonly resolveBuf;
+    private readonly readBuf;
+    private readonly writes;
+    private readonly markWrites;
+    private readonly markDesc;
+    /** Label index per used pair this frame. */
+    private readonly pairLabel;
+    private readonly labels;
+    private readonly labelIndex;
+    private readonly sums;
+    private used;
+    private marked;
+    private pending;
+    private destroyed;
+    private readonly listeners;
+    private readonly onMapped;
+    private readonly onMapFailed;
+    constructor(device: GPUDevice, maxPasses?: number);
+    /** True while a sampled frame is being read back (the next `begin` would be refused). */
+    get busy(): boolean;
+    /** Called with each resolved frame. Returns unsubscribe. */
+    onResult(fn: (r: GpuTimerResult) => void): () => void;
+    /** Start a sampled frame. Returns false (and stays inactive) while the last one is in flight. */
+    begin(): boolean;
+    /** Frame start marker: an empty compute pass with timestamps. Call first in the encoder. */
+    mark(encoder: GPUCommandEncoder): void;
+    /**
+     * Timestamp writes for one pass under `label`, or undefined when not sampling (or out of
+     * slots). Pass the result as the render/compute pass descriptor's `timestampWrites`.
+     */
+    pass(label: string): GPURenderPassTimestampWrites | undefined;
+    /** Resolve the queries into the readback buffer. Call after the last timed pass. */
+    resolve(encoder: GPUCommandEncoder): void;
+    /** Start the readback. Call after `queue.submit`. */
+    afterSubmit(): void;
+    /**
+     * Per-pass cost is the pass's *marginal* time: its end minus the later of its own start and
+     * the previous pass's end. Tiled GPUs (Apple, many mobiles) overlap consecutive passes, so a
+     * plain end − begin counts the overlap twice and sums past the frame; ends are in order, so
+     * marginal times add up to the frame total.
+     */
+    private read;
+    destroy(): void;
+}

package/dist/render/gpu-timer.js

@@ -0,0 +1,186 @@
+/**
+ * GPU pass timing with `timestamp-query` (feature-detected; see `initGpu`).
+ *
+ * One sampled frame is in flight at a time. On a sampled frame, every pass that asks for
+ * `pass(label)` gets begin/end timestamp writes; passes sharing a label are summed (the bloom
+ * mip chain is many passes, one label). `mark()` opens the frame with an empty compute pass so
+ * the work encoded before the first labelled pass (pre-passes, drawable prepare) is counted.
+ *
+ * Results land in `result` (plain object, reused) after the readback maps. Per-frame work is
+ * allocation-free apart from the `mapAsync` promise and the mapped range on sampled frames.
+ */
+/** True when the device was created with the `timestamp-query` feature. */
+export function supportsTimestamps(device) {
+    const f = device.features;
+    return !!f && typeof f.has === 'function' && f.has('timestamp-query');
+}
+export class GpuTimer {
+    maxPasses;
+    result = { totalMs: 0, passes: {}, samples: 0 };
+    /** True between `begin()` and `resolve()`: passes should take `pass(label)` writes. */
+    active = false;
+    querySet;
+    resolveBuf;
+    readBuf;
+    writes = [];
+    markWrites;
+    markDesc;
+    /** Label index per used pair this frame. */
+    pairLabel;
+    labels = [];
+    labelIndex = new Map();
+    sums;
+    used = 0;
+    marked = false;
+    pending = false;
+    destroyed = false;
+    listeners = new Set();
+    onMapped = () => this.read();
+    onMapFailed = () => {
+        this.pending = false;
+    };
+    constructor(device, maxPasses = 48) {
+        this.maxPasses = maxPasses;
+        // Pair 0 is the frame mark; pairs 1.. are labelled passes.
+        const count = (maxPasses + 1) * 2;
+        this.querySet = device.createQuerySet({ label: 'gpu-timer', type: 'timestamp', count });
+        this.resolveBuf = device.createBuffer({
+            label: 'gpu-timer-resolve',
+            size: count * 8,
+            usage: GPUBufferUsage.QUERY_RESOLVE | GPUBufferUsage.COPY_SRC,
+        });
+        this.readBuf = device.createBuffer({
+            label: 'gpu-timer-read',
+            size: count * 8,
+            usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST,
+        });
+        for (let i = 1; i <= maxPasses; i++) {
+            this.writes.push({
+                querySet: this.querySet,
+                beginningOfPassWriteIndex: i * 2,
+                endOfPassWriteIndex: i * 2 + 1,
+            });
+        }
+        this.markWrites = {
+            querySet: this.querySet,
+            beginningOfPassWriteIndex: 0,
+            endOfPassWriteIndex: 1,
+        };
+        this.markDesc = { label: 'gpu-timer-mark', timestampWrites: this.markWrites };
+        this.pairLabel = new Int32Array(maxPasses);
+        this.sums = new Float64Array(maxPasses);
+    }
+    /** True while a sampled frame is being read back (the next `begin` would be refused). */
+    get busy() {
+        return this.pending || this.active;
+    }
+    /** Called with each resolved frame. Returns unsubscribe. */
+    onResult(fn) {
+        this.listeners.add(fn);
+        return () => this.listeners.delete(fn);
+    }
+    /** Start a sampled frame. Returns false (and stays inactive) while the last one is in flight. */
+    begin() {
+        if (this.busy || this.destroyed)
+            return false;
+        this.active = true;
+        this.used = 0;
+        this.marked = false;
+        return true;
+    }
+    /** Frame start marker: an empty compute pass with timestamps. Call first in the encoder. */
+    mark(encoder) {
+        if (!this.active)
+            return;
+        encoder.beginComputePass(this.markDesc).end();
+        this.marked = true;
+    }
+    /**
+     * Timestamp writes for one pass under `label`, or undefined when not sampling (or out of
+     * slots). Pass the result as the render/compute pass descriptor's `timestampWrites`.
+     */
+    pass(label) {
+        if (!this.active || this.used >= this.maxPasses)
+            return undefined;
+        let li = this.labelIndex.get(label);
+        if (li === undefined) {
+            li = this.labels.length;
+            if (li >= this.maxPasses)
+                return undefined;
+            this.labels.push(label);
+            this.labelIndex.set(label, li);
+        }
+        this.pairLabel[this.used] = li;
+        return this.writes[this.used++];
+    }
+    /** Resolve the queries into the readback buffer. Call after the last timed pass. */
+    resolve(encoder) {
+        if (!this.active)
+            return;
+        this.active = false;
+        if (this.used === 0 && !this.marked)
+            return;
+        const count = (this.used + 1) * 2;
+        encoder.resolveQuerySet(this.querySet, 0, count, this.resolveBuf, 0);
+        encoder.copyBufferToBuffer(this.resolveBuf, 0, this.readBuf, 0, count * 8);
+        this.pending = true;
+    }
+    /** Start the readback. Call after `queue.submit`. */
+    afterSubmit() {
+        if (!this.pending || this.readBuf.mapState !== 'unmapped')
+            return;
+        this.readBuf.mapAsync(GPUMapMode.READ).then(this.onMapped, this.onMapFailed);
+    }
+    /**
+     * Per-pass cost is the pass's *marginal* time: its end minus the later of its own start and
+     * the previous pass's end. Tiled GPUs (Apple, many mobiles) overlap consecutive passes, so a
+     * plain end − begin counts the overlap twice and sums past the frame; ends are in order, so
+     * marginal times add up to the frame total.
+     */
+    read() {
+        if (this.destroyed)
+            return;
+        const ts = new BigInt64Array(this.readBuf.getMappedRange());
+        const used = this.used;
+        const sums = this.sums;
+        sums.fill(0);
+        const markB = this.marked ? ts[0] : 0n;
+        const markE = this.marked ? ts[1] : 0n;
+        let first = markB;
+        let prevEnd = markE;
+        let firstPass = 0n;
+        for (let i = 0; i < used; i++) {
+            const b = ts[(i + 1) * 2];
+            const e = ts[(i + 1) * 2 + 1];
+            // A zero timestamp was never written (a skipped pass): ignore the pair.
+            if (b <= 0n || e < b)
+                continue;
+            if (first === 0n || b < first)
+                first = b;
+            if (firstPass === 0n)
+                firstPass = b;
+            // biome-ignore lint/complexity/useMathMinMax: bigint (Math.max takes numbers)
+            const from = prevEnd > b ? prevEnd : b;
+            if (e > from)
+                sums[this.pairLabel[i]] += Number(e - from) / 1e6;
+            if (e > prevEnd)
+                prevEnd = e;
+        }
+        this.readBuf.unmap();
+        this.pending = false;
+        const r = this.result;
+        r.totalMs = first > 0n && prevEnd > first ? Number(prevEnd - first) / 1e6 : 0;
+        for (let i = 0; i < this.labels.length; i++)
+            r.passes[this.labels[i]] = sums[i];
+        r.passes.pre = markE > 0n && firstPass > markE ? Number(firstPass - markE) / 1e6 : 0;
+        r.samples++;
+        for (const fn of this.listeners)
+            fn(r);
+    }
+    destroy() {
+        this.destroyed = true;
+        this.querySet.destroy();
+        this.resolveBuf.destroy();
+        this.readBuf.destroy();
+    }
+}

package/dist/render/index.d.ts

@@ -0,0 +1,53 @@
+export type { RenderBlendMode } from './blend.js';
+export type { CameraPoint, CameraRect } from './camera.js';
+export { ALL_LAYERS, Camera, FRUSTUM_FLOATS, ORTHO2D_HALF_DEPTH, } from './camera.js';
+export type { Follow2D, Follow2DBounds, Follow2DCamera, Follow2DOptions } from './camera-2d.js';
+export { createFollow2D } from './camera-2d.js';
+export type { RGBA } from './color.js';
+export { hex, linearToSrgb, rgba, scaleRgb, srgbToLinear } from './color.js';
+export type { BlockInfo, CompressedUploadTarget, CompressionFamily, Ktx2LevelLayout, RendererCaps, UploadKtx2Options, } from './compressed.js';
+export { blockInfo, COMPRESSION_FEATURES, CompressedTextureError, compressionFeatures, ktx2LevelLayout, rendererCaps, uploadKtx2, } from './compressed.js';
+export { gpuDiagnostics, installGpuErrorLogging, onGpuError, reportGpuError } from './diagnostics.js';
+export { DynamicResolution, type DynamicResolutionOptions, } from './dynamic-resolution.js';
+export type { AtlasGrid, Flipbook, FlipbookOptions, UvRect } from './flipbook.js';
+export { atlasFrames, createFlipbook } from './flipbook.js';
+export type { Drawable, DrawParams, InstanceBatch, InstanceParams, ViewInfo } from './frame.js';
+export { Frame, INSTANCE_PARAM_FLOATS, SKIN_PARAM, writeInstanceParams } from './frame.js';
+export type { FullscreenEncodeOptions, FullscreenPassDesc } from './fullscreen.js';
+export { FullscreenPass } from './fullscreen.js';
+export type { GpuPassTimes, GpuTimerResult } from './gpu-timer.js';
+export { GpuTimer, supportsTimestamps } from './gpu-timer.js';
+export { InstanceList, type InstanceListOptions } from './instance-list.js';
+export type { DirectionalLight, DistanceFog, PointLight, ShadowUniforms, SpotLight, SunLight, SunShadow, } from './lights.js';
+export { ALL_LIGHT_LAYERS, DEFAULT_SHADOW_BIAS, INSTANCE_LAYER_BITS, INSTANCE_LAYER_SHIFT, Lights, MAX_POINT_LIGHTS, MAX_SPOT_LIGHTS, POINT_LIGHT_FLOATS, packInstanceFlags, SPOT_LIGHT_FLOATS, spotCone, } from './lights.js';
+export type { MeshLod, MeshLodChain, MeshLodDesc } from './lod.js';
+export { DEFAULT_LOD_HYSTERESIS, isMeshLod, lodSizePx, pickLodLevel } from './lod.js';
+export type { DepthMode, MaterialDesc } from './material.js';
+export { DEPTH_FORMAT, INSTANCE_BUFFER_LAYOUT, INSTANCE_FLOATS, INSTANCE_OFFSET, INSTANCE_STRIDE, Material, } from './material.js';
+export type { MeshBounds, MeshCapacity, MeshDesc, MeshRange, MeshReply, MeshUpdate, VertexLayout, } from './mesh.js';
+export { AUTO_BOUNDS_MAX_VERTICES, Mesh, quadGeometry, SKIN_JOINTS_BYTE_OFFSET, SKIN_WEIGHTS_BYTE_OFFSET, VERTEX_BUFFER_LAYOUT, VERTEX_FLOATS, VERTEX_LAYOUT_2D, VERTEX_LAYOUT_3D, VERTEX_LAYOUT_3D_TANGENT, VERTEX_LAYOUT_3D_UV2, VERTEX_LAYOUT_SKINNED, VERTEX_SKINNED_BUFFER_LAYOUT, VERTEX_SKINNED_FLOATS, VERTEX_SKINNED_STRIDE, VERTEX_STRIDE, VERTEX3D_BUFFER_LAYOUT, VERTEX3D_FLOATS, VERTEX3D_STRIDE, VERTEX3D_UV2_FLOATS, VERTEX3D_UV2_STRIDE, } from './mesh.js';
+export type { GenerateMipmapsOptions, MipFilter } from './mipmap.js';
+export { generateMipmaps } from './mipmap.js';
+export type { Parallax, ParallaxLayer, ParallaxLayerOptions } from './parallax.js';
+export { createParallax, parallaxOffset } from './parallax.js';
+export { WGSL_PBR } from './pbr-wgsl.js';
+export type { PingPongStepOptions } from './ping-pong.js';
+export { PingPong } from './ping-pong.js';
+export type { FrameTiming, JitterFn, PostInputs, PostProcessor, PostProjection, PostView, RendererGpu, RendererOptions, RenderStats, ResolutionOptions, SpriteMaterialOptions, TextureFromSourceOptions, } from './renderer.js';
+export { MIN_RESOLUTION_SCALE, Renderer, sceneSize } from './renderer.js';
+export type { SceneTargetAux, SceneTargetExternal, SceneTargetViewport } from './scene-target.js';
+export { ROUGH_METAL_FORMAT, SCENE_FORMAT, SceneTarget, type SceneTargetDesc, VELOCITY_FORMAT, } from './scene-target.js';
+export { DEFAULT_SHADOW_SIZE, SHADOW_FORMAT, ShadowMap } from './shadow.js';
+export type { SkinPaletteDesc } from './skin.js';
+export { JOINT_FLOATS, SkinPalette, setVertexSkin } from './skin.js';
+export { type SnapshotOptions, SnapshotRenderer } from './snapshot.js';
+export type { StandardDissolve, StandardMapDesc, StandardMapSlot, StandardMaterialDesc, } from './standard.js';
+export { createStandardMaterial, packStandardUniforms, STANDARD_DISSOLVE_OFFSET, STANDARD_TEXTURE_SLOTS, STANDARD_UNIFORM_FLOATS, } from './standard.js';
+export type { DefaultTextures, LoadTextureArrayOptions, LoadTextureOptions, PixelData, PixelSource, SamplerKind, TextureArrayDesc, TextureDesc, TextureLayerSource, TextureLike, TextureSource, } from './texture.js';
+export { bytesPerTexel, createTextureArray, defaultTextures, loadTexture, loadTextureArray, mipLevelCount, Texture, } from './texture.js';
+export type { TileLayer, TileLayerOptions, TileLayerOrder } from './tile-layer.js';
+export { createTileLayer } from './tile-layer.js';
+export type { ReadonlyQuat, ReadonlyVec3 } from './transform.js';
+export { Transform } from './transform.js';
+export type { PreludeVariant } from './wgsl.js';
+export { createShaderModule, materialPrelude, PLAIN_VARIANT, prevLaneBufferLayout, prevLaneLocations, SKIN_PALETTE_BINDING, WGSL_FULLSCREEN_PRELUDE, WGSL_GLOBALS, WGSL_LAMBERT_BRDF, WGSL_LIGHTS, WGSL_NOISE, WGSL_SKIN, wgslLightLoop, } from './wgsl.js';

package/dist/render/index.js

@@ -0,0 +1,29 @@
+export { ALL_LAYERS, Camera, FRUSTUM_FLOATS, ORTHO2D_HALF_DEPTH, } from './camera.js';
+export { createFollow2D } from './camera-2d.js';
+export { hex, linearToSrgb, rgba, scaleRgb, srgbToLinear } from './color.js';
+export { blockInfo, COMPRESSION_FEATURES, CompressedTextureError, compressionFeatures, ktx2LevelLayout, rendererCaps, uploadKtx2, } from './compressed.js';
+export { gpuDiagnostics, installGpuErrorLogging, onGpuError, reportGpuError } from './diagnostics.js';
+export { DynamicResolution, } from './dynamic-resolution.js';
+export { atlasFrames, createFlipbook } from './flipbook.js';
+export { Frame, INSTANCE_PARAM_FLOATS, SKIN_PARAM, writeInstanceParams } from './frame.js';
+export { FullscreenPass } from './fullscreen.js';
+export { GpuTimer, supportsTimestamps } from './gpu-timer.js';
+export { InstanceList } from './instance-list.js';
+export { ALL_LIGHT_LAYERS, DEFAULT_SHADOW_BIAS, INSTANCE_LAYER_BITS, INSTANCE_LAYER_SHIFT, Lights, MAX_POINT_LIGHTS, MAX_SPOT_LIGHTS, POINT_LIGHT_FLOATS, packInstanceFlags, SPOT_LIGHT_FLOATS, spotCone, } from './lights.js';
+export { DEFAULT_LOD_HYSTERESIS, isMeshLod, lodSizePx, pickLodLevel } from './lod.js';
+export { DEPTH_FORMAT, INSTANCE_BUFFER_LAYOUT, INSTANCE_FLOATS, INSTANCE_OFFSET, INSTANCE_STRIDE, Material, } from './material.js';
+export { AUTO_BOUNDS_MAX_VERTICES, Mesh, quadGeometry, SKIN_JOINTS_BYTE_OFFSET, SKIN_WEIGHTS_BYTE_OFFSET, VERTEX_BUFFER_LAYOUT, VERTEX_FLOATS, VERTEX_LAYOUT_2D, VERTEX_LAYOUT_3D, VERTEX_LAYOUT_3D_TANGENT, VERTEX_LAYOUT_3D_UV2, VERTEX_LAYOUT_SKINNED, VERTEX_SKINNED_BUFFER_LAYOUT, VERTEX_SKINNED_FLOATS, VERTEX_SKINNED_STRIDE, VERTEX_STRIDE, VERTEX3D_BUFFER_LAYOUT, VERTEX3D_FLOATS, VERTEX3D_STRIDE, VERTEX3D_UV2_FLOATS, VERTEX3D_UV2_STRIDE, } from './mesh.js';
+export { generateMipmaps } from './mipmap.js';
+export { createParallax, parallaxOffset } from './parallax.js';
+export { WGSL_PBR } from './pbr-wgsl.js';
+export { PingPong } from './ping-pong.js';
+export { MIN_RESOLUTION_SCALE, Renderer, sceneSize } from './renderer.js';
+export { ROUGH_METAL_FORMAT, SCENE_FORMAT, SceneTarget, VELOCITY_FORMAT, } from './scene-target.js';
+export { DEFAULT_SHADOW_SIZE, SHADOW_FORMAT, ShadowMap } from './shadow.js';
+export { JOINT_FLOATS, SkinPalette, setVertexSkin } from './skin.js';
+export { SnapshotRenderer } from './snapshot.js';
+export { createStandardMaterial, packStandardUniforms, STANDARD_DISSOLVE_OFFSET, STANDARD_TEXTURE_SLOTS, STANDARD_UNIFORM_FLOATS, } from './standard.js';
+export { bytesPerTexel, createTextureArray, defaultTextures, loadTexture, loadTextureArray, mipLevelCount, Texture, } from './texture.js';
+export { createTileLayer } from './tile-layer.js';
+export { Transform } from './transform.js';
+export { createShaderModule, materialPrelude, PLAIN_VARIANT, prevLaneBufferLayout, prevLaneLocations, SKIN_PALETTE_BINDING, WGSL_FULLSCREEN_PRELUDE, WGSL_GLOBALS, WGSL_LAMBERT_BRDF, WGSL_LIGHTS, WGSL_NOISE, WGSL_SKIN, wgslLightLoop, } from './wgsl.js';

package/dist/render/instance-list.d.ts

@@ -0,0 +1,185 @@
+import { type InstanceBatch, type InstanceParams } from './frame.js';
+import { type MeshLod } from './lod.js';
+import { type Material } from './material.js';
+import type { Mesh, MeshBounds } from './mesh.js';
+import { Transform } from './transform.js';
+/** `renderer.createInstanceList` options. */
+export interface InstanceListOptions {
+    /**
+     * Keep each instance's previous-frame matrix in a second vertex buffer (`prevBuffer`), so a
+     * material writing a velocity attachment (`SceneTargetDesc.aux.velocity`) sees the
+     * instance's own motion rather than the camera's alone. A LOD list keeps the matrices but
+     * no buffer: they travel with its per-frame copy. Default false.
+     */
+    velocity?: boolean;
+}
+/**
+ * A retained list of up to `capacity` instances of one mesh and material, drawn with
+ * `frame.list(list)`; made by `renderer.createInstanceList`. Instances are set and removed by
+ * index (`set`, `remove`: swap-remove) and live in the list's own GPU vertex buffer, in the
+ * engine instance format: a frame uploads only the index range touched since the last one, so
+ * an unchanged list costs nothing on the CPU and no `writeBuffer`. `matrices` (12 floats per
+ * instance, 3×4 row-major) and `params` (`INSTANCE_PARAM_FLOATS` each) are the CPU copies; code
+ * that writes them directly calls `touch(i)` so the range uploads.
+ *
+ * The list is culled as one unit by `bounds`, a world-space sphere: computed from the mesh's
+ * bounds through every instance (the centre of their box, the radius to the farthest one plus
+ * its scaled mesh radius) whenever instances changed, or fixed by `setBounds`. A mesh without
+ * bounds (`radius` Infinity) gives a list that is never culled.
+ */
+export declare class InstanceList implements InstanceBatch {
+    readonly material: Material;
+    readonly capacity: number;
+    readonly matrices: Float32Array;
+    readonly params: Float32Array;
+    /** Layer mask of the whole list (`camera.layers`); default 1. */
+    layerBits: number;
+    /** Sort key (`InstanceParams.order`); default 0. */
+    order: number;
+    /** Draw into the sun's shadow map; default: the mesh is not 2D. */
+    castShadow?: boolean;
+    /**
+     * The GPU vertex buffer the instances live in (`capacity` × `INSTANCE_STRIDE` bytes). A LOD
+     * list (`lod`) never writes it (ws/render-9): its instances reach the GPU in the frame's
+     * per-level copy.
+     */
+    readonly buffer: GPUBuffer;
+    /**
+     * With `velocity` (ws/render-4): the previous frame's matrices (12 floats per instance) and
+     * the vertex buffer (48 bytes per instance, slot 2) a material writing a velocity attachment
+     * reads them from; null otherwise. A slot `set` this frame keeps what it held before as
+     * previous; one left alone settles to its current matrix at the next flush (no motion).
+     * A LOD list (`lod`) keeps `prevMatrices` but has no `prevBuffer` and uploads none
+     * (ws/render-8): the renderer copies its previous matrices into its shared lane.
+     */
+    readonly prevMatrices: Float32Array | null;
+    readonly prevBuffer: GPUBuffer | null;
+    /** Keeps a previous-matrix lane (`createInstanceList(..., { velocity: true })`). */
+    readonly velocity: boolean;
+    private _count;
+    private _bounds;
+    private fixedBounds;
+    private boundsDirty;
+    /** Instance range `[dirtyLo, dirtyHi)` to upload; empty when `dirtyLo >= dirtyHi`. */
+    private dirtyLo;
+    private dirtyHi;
+    /** Interleaved staging for the upload, in the instance format. */
+    private readonly data;
+    private readonly center;
+    /** With velocity: the flush each slot was last captured in (0: never); `flushes` counts them. */
+    private readonly stamp;
+    private flushes;
+    /** With velocity: the range dirty at the last flush, settled (prev := current) at the next. */
+    private settleLo;
+    private settleHi;
+    /** Live instances at the last flush. */
+    private lastCount;
+    /** Per-slot keys (`setKey`; NaN: none), made on the first `setKey`. */
+    private keys;
+    /**
+     * Key → slot hash tables (open addressing, `tableMask + 1` entries): `tableSlots[t]` -1 is
+     * empty. `cur` is the one the last flush filled; the other is refilled at the next.
+     */
+    private tableKeys;
+    private tableSlots;
+    private tableMask;
+    private cur;
+    /** With velocity and keys: each slot's matrix at the last flush. */
+    private lastMatrices;
+    private _previousIndex;
+    /** The list's mesh: the one it was made with, or the first level of its `lod`. */
+    readonly mesh: Mesh;
+    /**
+     * The LOD chain the list was made with (ws/render-6), else null. Each instance then picks a
+     * level per view, and `frame.list` copies the instances into the frame's upload bucketed by
+     * level rather than drawing from `buffer`; with `velocity` its `prevMatrices` travel with
+     * the copy into the renderer's shared lane (ws/render-7), so it has no `prevBuffer`.
+     */
+    readonly lod: MeshLod | null;
+    constructor(device: GPUDevice, mesh: Mesh | MeshLod, material: Material, capacity: number, opts?: InstanceListOptions);
+    /** Live instances (the first `count` slots). */
+    get count(): number;
+    /**
+     * The world sphere the list is culled by: `setBounds`'s, or the one computed from the
+     * instances (refreshed by the next `frame.list` after a change, or by `flush`); null for a
+     * mesh without bounds.
+     */
+    get bounds(): MeshBounds | null;
+    /**
+     * True once any instance has a key (`setKey`, ws/render-7): the list then matches each
+     * instance to last frame's by key (keyless slots by index) at every flush, for its LOD
+     * level memory and its velocity history.
+     */
+    get keyed(): boolean;
+    /**
+     * Flushes so far (`flush`, once per `frame.list`). `previousIndex` maps the instances of
+     * flush `flushCount` onto those of flush `flushCount - 1`.
+     */
+    get flushCount(): number;
+    /**
+     * With keys (`keyed`), after each flush: per live instance, the index it held at the
+     * previous flush (matched by key, a keyless slot by its own index), or -1 for an instance
+     * that was not there (a new key, or an index past last flush's count). Null until keyed.
+     */
+    get previousIndex(): Int32Array | null;
+    /**
+     * Give instance `i` (0..count-1) a stable `key` (ws/render-7): a finite number, an entity
+     * id, unique in the list (on duplicates the last slot wins). The instance's LOD level
+     * memory and velocity history then follow the key, not the index, so removing or
+     * reordering instances (`remove`'s swap, a `clear` and refill in another order) changes no
+     * other instance's level and no other instance's motion. `null` clears it. The key stays
+     * with the slot through `set` and moves with `remove`; a slot appended by `set` starts
+     * without one. Chain it after `set`: `list.set(i, t).setKey(i, id)`.
+     */
+    setKey(i: number, key: number | null): this;
+    /** Instance `i`'s key (`setKey`), or null for none. */
+    keyOf(i: number): number | null;
+    /** True when the next `frame.list` has something to upload. */
+    get dirty(): boolean;
+    /**
+     * Place instance `i` (0..count; `count` appends) by a `Transform` or a 3×4 row-major matrix
+     * (12 floats, read from `offset`), with `params` (`InstanceParams`; omitted: the defaults).
+     * `size` is the transform's scale.xy, or the matrix's x and y column lengths.
+     */
+    set(i: number, m: Transform | ArrayLike<number>, params?: InstanceParams, offset?: number): this;
+    /**
+     * Remove instance `i`: the last instance moves into its slot (swap-remove). Returns the index
+     * that moved (the old last), or -1 when `i` was the last. Callers keeping indices update
+     * the moved one.
+     */
+    remove(i: number): number;
+    /** Drop every instance (nothing to upload: the next `set`s mark their own range). */
+    clear(): void;
+    /** Mark instance `i` changed (after writing `matrices` / `params` directly). */
+    touch(i: number): void;
+    /**
+     * Fix the cull sphere (world space, copied), or pass null to go back to the automatic one.
+     */
+    setBounds(bounds: MeshBounds | null): this;
+    /**
+     * Upload the changed range to `buffer` (one `writeBuffer`, or none when nothing changed) and
+     * refresh the automatic bounds. The renderer calls it from `frame.list`; no allocation. A LOD
+     * list uploads nothing: `frame.list` copies its instances into the frame's upload per level.
+     */
+    flush(queue: GPUQueue): void;
+    destroy(): void;
+    /** With velocity: the first `set` of a slot in a frame keeps its current matrix as previous. */
+    private capture;
+    /**
+     * Settle the slots dirty last flush but untouched this one (previous := current), give a
+     * brand-new instance its current matrix as previous, and upload the previous lane over the
+     * union of both ranges.
+     */
+    private flushPrevious;
+    private ensureKeys;
+    /** Hash table start index of `k`. */
+    private hashOf;
+    /**
+     * Fill `previousIndex` from the table of the last flush (keyed slots by key, keyless by
+     * index), then refill the other table with this flush's keys and make it current. No
+     * allocation.
+     */
+    private matchKeys;
+    /** The automatic sphere: `mesh.bounds` through every live instance. */
+    private computeBounds;
+}