@vibecook/ice 0.10.0 → 0.14.0

package/dist/types/packages/desk/src/engine/device.d.ts

@@ -0,0 +1,54 @@
+export interface GpuOptions {
+    /** `navigator.gpu` in a browser; Dawn's `create([])` in Node. */
+    readonly gpu: GPU;
+    readonly label?: string;
+    readonly powerPreference?: GPUPowerPreference;
+    /** Features to enable where the adapter has them, beside `timestamp-query` — asked for whenever the adapter has it (the GPU profiler's clock, design-016 §4: a feature cannot be added to a device later, and one unused costs nothing). */
+    readonly requiredFeatures?: readonly GPUFeatureName[];
+    /** Device loss and uncaptured errors — the layer degrades, it does not throw. */
+    readonly onLost?: (info: GPUDeviceLostInfo) => void;
+    readonly onError?: (error: GPUError) => void;
+}
+export interface Gpu {
+    readonly adapter: GPUAdapter;
+    readonly device: GPUDevice;
+    readonly info: {
+        readonly vendor: string;
+        readonly architecture: string;
+        readonly description: string;
+    };
+}
+export declare function acquire(opts: GpuOptions): Promise<Gpu>;
+/**
+ * The one limit the desk asks above WebGPU's floor (K9 R1): the adapter's own `maxTextureArrayLayers` — a device asked for
+ * nothing gets the floor, 256, whatever the hardware holds (Apple 2048), and the kinds' shared thumbnail arrays (kit/arrays.ts
+ * `LayerArray`) stop there: the 257th picture has no layer, the 257th whiteboard no far-LOD thumbnail. On an adapter AT the floor
+ * this asks for 256 and changes nothing — the arrays' own reclaim and the boards' bare draw carry that cap honestly.
+ */
+export declare function arrayLayerLimit(adapter: Pick<GPUAdapter, "limits">): Record<string, number> | undefined;
+/**
+ * A device the host already HAS — the engine's (design-015 D7: ONE device per engine) — wired as `acquire` wires one it
+ * made: its loss and its uncaptured errors reach the handlers. The caller does not own it, so it never destroys it.
+ */
+export declare function adopt(adapter: GPUAdapter, device: GPUDevice, opts?: Pick<GpuOptions, "onLost" | "onError">): Gpu;
+/** A swap chain as the ground draws into it — made by `host/surface.ts` (a canvas) or a test's fake. */
+export interface Surface {
+    readonly context: GPUCanvasContext;
+    readonly format: GPUTextureFormat;
+    /** Size the drawing buffer to the CSS box × dpr (clamped). True when it changed. */
+    fit(maxDpr?: number): {
+        changed: boolean;
+        width: number;
+        height: number;
+        cssWidth: number;
+        cssHeight: number;
+        dpr: number;
+    };
+    /** The swap-chain texture view for this frame. */
+    view(): GPUTextureView;
+    /** The drawing buffer's size in device px — whatever sized the canvas, `fit()` or the host. */
+    size(): {
+        readonly w: number;
+        readonly h: number;
+    };
+}

package/dist/types/packages/desk/src/engine/index.d.ts

@@ -0,0 +1,5 @@
+export { defineStruct, type StructDef, type StructBuffer, type FieldSlot, type FieldType, type FieldValue, type StructValues } from "./struct";
+export { compose, compile, type ComposedShader, type ComposeOptions, type ShaderPart } from "./shader";
+export { acquire, adopt, type Gpu, type GpuOptions, type Surface } from "./device";
+export { bindLayout, bindGroup, renderPipeline, uniformBuffer, storageBuffer, BLEND_OVER, type BindEntry, type BindKind, type RenderPipelineOptions, type Visibility, } from "./pipeline";
+export { Target, beginPass, readback, type Clear, type TargetOptions } from "./target";

package/dist/types/packages/desk/src/engine/pipeline.d.ts

@@ -0,0 +1,36 @@
+export type Visibility = "vertex" | "fragment" | "compute";
+export type BindEntry = {
+    readonly binding: number;
+    readonly stages: readonly Visibility[];
+    readonly buffer: GPUBufferBindingType;
+} | {
+    readonly binding: number;
+    readonly stages: readonly Visibility[];
+    readonly texture: GPUTextureSampleType;
+    readonly dimension?: GPUTextureViewDimension;
+} | {
+    readonly binding: number;
+    readonly stages: readonly Visibility[];
+    readonly sampler: GPUSamplerBindingType;
+};
+/** A binding's layout without its number — what a card material declares (K7b), the card deals the numbers. */
+export type BindKind = BindEntry extends infer E ? (E extends BindEntry ? Omit<E, "binding"> : never) : never;
+export declare function bindLayout(device: GPUDevice, entries: readonly BindEntry[], label?: string): GPUBindGroupLayout;
+export declare function bindGroup(device: GPUDevice, layout: GPUBindGroupLayout, resources: ReadonlyArray<GPUBuffer | GPUTextureView | GPUSampler>, label?: string): GPUBindGroup;
+/** Straight-alpha "source over": colour by src-alpha, alpha accumulates. */
+export declare const BLEND_OVER: GPUBlendState;
+export interface RenderPipelineOptions {
+    readonly label?: string;
+    readonly layout: GPUPipelineLayout;
+    readonly module: GPUShaderModule;
+    readonly vertex?: string;
+    readonly fragment?: string;
+    readonly format: GPUTextureFormat;
+    readonly blend?: GPUBlendState;
+    /** WGSL `override` values, fixed at creation — how one file becomes N specialised pipelines. */
+    readonly constants?: Record<string, number>;
+    readonly topology?: GPUPrimitiveTopology;
+}
+export declare function renderPipeline(device: GPUDevice, o: RenderPipelineOptions): Promise<GPURenderPipeline>;
+export declare function uniformBuffer(device: GPUDevice, size: number, label?: string): GPUBuffer;
+export declare function storageBuffer(device: GPUDevice, size: number, label?: string): GPUBuffer;

package/dist/types/packages/desk/src/engine/rasters.d.ts

@@ -0,0 +1,66 @@
+import type { Entity } from "../../../core/src/index";
+/** What a run says: `done` — the raster is laid (or no longer owed); `wait` — no room for it now: held until its owner `wake`s. */
+export type RasterRun = () => "done" | "wait";
+export interface RasterQueueStats {
+    /** The frame's budget, ms. */
+    readonly budgetMs: number;
+    /** Asks waiting for their turn, and those held for room. */
+    readonly waiting: number;
+    readonly held: number;
+    /** Runs since the queue was made, the turns that ran any, and their ms. */
+    readonly ran: number;
+    readonly turns: number;
+    readonly ms: number;
+    /** Asks let go unrun: their object was not drawn when their turn came. */
+    readonly dropped: number;
+    /** The most runs one turn made, the most ms one turn spent, and the most one run took — a turn overshoots its budget by at most its last run. */
+    readonly peakRuns: number;
+    readonly peakMs: number;
+    readonly dearest: number;
+}
+export interface RasterQueue {
+    /** The frame's budget, ms (the turn's first run excepted). */
+    readonly budgetMs: number;
+    /**
+     * Ask for `owner`'s raster of `key` (a kind and its object): `priority` orders the turn (lower first — a kind puts what shows
+     * nothing before what shows a stand-in, and the nearest the view's centre first); `run` lays it when its turn comes. A second ask
+     * for the same key replaces the first — its priority and its run, and a held ask is waiting again.
+     */
+    ask(owner: string, key: Entity, priority: number, run: RasterRun): void;
+    /** The ask is withdrawn: the object's need went away before its turn (the zoom came back to the band it holds), or it left. */
+    drop(owner: string, key: Entity): void;
+    has(owner: string, key: Entity): boolean;
+    /** Room may have been made — `owner` let a raster go, or (no owner) the host drew a frame: the held asks wait for their turn again. */
+    wake(owner?: string): void;
+    /** Every ask of `owner` withdrawn (its state reset), or every ask. */
+    clear(owner?: string): void;
+    /** The host's turn, once a tick before the build: the runs, lowest priority first, while the budget lasts. Returns how many ran. */
+    drain(): number;
+    /** Asks waiting for their turn — the host keeps the desk awake while there are any (held asks are not counted). */
+    readonly size: number;
+    stats(): RasterQueueStats;
+}
+export interface RasterQueueOptions {
+    /** The frame's budget, ms (default `RASTER_BUDGET_MS`). */
+    readonly budgetMs?: number;
+    /** The clock the budget is kept on (default `performance.now`). */
+    readonly clock?: () => number;
+    /** Was the object drawn in the last build (the builder's word, `DeskBuilder.shows`)? Absent: every ask is run. */
+    readonly shows?: (key: Entity) => boolean;
+}
+/**
+ * The frame's raster budget, ms: a zoom's frame keeps its other work (≈ 1 ms of JS on the stress desk) inside design-016 §6's
+ * 8 ms with a raster's worth to spare — a note's ink at band 2 costs ≈ 2 ms on this Mac, and the turn's first always runs.
+ */
+export declare const RASTER_BUDGET_MS = 4;
+/**
+ * What an object shows while its raster waits its turn (K6b): NOTHING (a blank sheet, a bare board), its old raster MAGNIFIED (a
+ * band or a density short of the screen's — soft), or its old raster MINIFIED (past it — only the pages' room is at stake).
+ */
+export type RasterWait = "nothing" | "magnified" | "minified";
+/**
+ * The priority every kind asks with, so one turn orders them all alike (K6b): what shows nothing first, then a stand-in magnified,
+ * then one minified — the nearest the view's centre (`px`, screen px) first within each.
+ */
+export declare function rasterPriority(shows: RasterWait, px: number): number;
+export declare function createRasterQueue(opts?: RasterQueueOptions): RasterQueue;

package/dist/types/packages/desk/src/engine/records.d.ts

@@ -0,0 +1,56 @@
+import type { StructBuffer, StructDef } from "./struct";
+/** How the pass packs one record into its slot; `blocks` (when the store has them) and `blockBase` name the slot's block. Returns the block records used (0 without blocks). */
+export type RecordPacker<R, F extends string, B extends string> = (record: R, aux: number, into: StructBuffer<F>, slot: number, blocks: StructBuffer<B> | null, blockBase: number) => number;
+export interface RecordStoreOptions<R, F extends string, B extends string = never> {
+    readonly device: GPUDevice;
+    readonly def: StructDef<F>;
+    /** Slots at the start; grown by doubling up to `max` (65,536). */
+    readonly capacity: number;
+    readonly max?: number;
+    /** The records buffer's label (`paper/notes`); the draw list is `<label> order`, the blocks `blocks.label`. */
+    readonly label: string;
+    readonly pack: RecordPacker<R, F, B>;
+    /** A fixed block of `per` sub-records of `def` a slot (the mini mat's chips). */
+    readonly blocks?: {
+        readonly def: StructDef<B>;
+        readonly per: number;
+        readonly label: string;
+    };
+}
+export interface RecordStoreStats {
+    /** Records packed and uploaded since the store was made. */
+    readonly written: number;
+    /** Bytes those uploads carried (records and blocks). */
+    readonly bytes: number;
+    /** Draw-list uploads. */
+    readonly orderWrites: number;
+    /** Slots in use, the capacity, how many times the buffers were remade. */
+    readonly slots: number;
+    readonly capacity: number;
+    readonly grown: number;
+}
+export interface RecordStore<R> {
+    /** The records buffer, the draw list and (with blocks) the blocks buffer — bind them; their identity moves on growth, `version` says when. */
+    readonly records: GPUBuffer;
+    readonly order: GPUBuffer;
+    readonly blocks: GPUBuffer | null;
+    readonly version: number;
+    /**
+     * One frame's records in paint order. `keys`: one per record, stable across frames (absent = transient: slots dealt from 0,
+     * everything packed). `aux(i)`: a number per record folded into the change test and handed to the pack. Returns the count
+     * that will draw — `order[0 … count)` names each paint index's slot.
+     */
+    prepare(records: readonly R[], keys: readonly number[] | undefined, aux?: (index: number) => number): number;
+    /** The slot drawn at paint index `i` this frame. */
+    slotAt(i: number): number;
+    /** What the pack folded in at paint index `i`: its aux and the block records it used. */
+    entryAt(i: number): {
+        readonly aux: number;
+        readonly blockN: number;
+    };
+    /** Every live record repacked at the next `prepare` (a law changed under them). */
+    invalidate(): void;
+    stats(): RecordStoreStats;
+    dispose(): void;
+}
+export declare function createRecordStore<R, F extends string, B extends string = never>(opts: RecordStoreOptions<R, F, B>): RecordStore<R>;

package/dist/types/packages/desk/src/engine/shader.d.ts

@@ -0,0 +1,22 @@
+import type { StructDef } from "./struct";
+export interface ShaderPart {
+    readonly label: string;
+    readonly text: string;
+}
+export interface ComposeOptions {
+    /** Structs whose WGSL text is prepended, in order. */
+    readonly structs?: ReadonlyArray<StructDef<string>>;
+    /** Pure modules, in dependency order. */
+    readonly modules?: ReadonlyArray<ShaderPart>;
+    /** The entry: bindings + @vertex/@fragment/@compute. */
+    readonly entry: ShaderPart;
+}
+export interface ComposedShader {
+    readonly code: string;
+    readonly label: string;
+    /** Map a line of the composed code back to `<part>:<line>`. */
+    locate(line: number): string;
+}
+export declare function compose(opts: ComposeOptions): ComposedShader;
+/** Create the module and surface compilation errors with mapped locations. */
+export declare function compile(device: GPUDevice, shader: ComposedShader): Promise<GPUShaderModule>;

package/dist/types/packages/desk/src/engine/struct.d.ts

@@ -0,0 +1,39 @@
+/** The scalar and vector types, and a fixed array of vec4f (`array<vec4f, N>`: stride 16, legal in a uniform block) — the portal chain's. */
+export type FieldType = "f32" | "i32" | "u32" | "vec2f" | "vec3f" | "vec4f" | "mat4x4f" | `array<vec4f, ${number}>`;
+interface TypeInfo {
+    readonly align: number;
+    readonly size: number;
+    readonly n: number;
+    readonly scalar: "f" | "i" | "u";
+}
+/** A field type's layout: the table's, or a vec4f array's — N × 16 bytes, 4N floats, written as one flat list. */
+export declare function typeInfo(type: FieldType): TypeInfo | undefined;
+export interface FieldSlot {
+    readonly byte: number;
+    readonly type: FieldType;
+    readonly n: number;
+}
+export type FieldValue = number | boolean | ArrayLike<number>;
+export type StructValues<F extends string> = Partial<Record<F, FieldValue>>;
+export interface StructDef<F extends string> {
+    readonly name: string;
+    readonly fields: ReadonlyArray<readonly [F, FieldType]>;
+    /** Padded size in bytes; also the array stride. */
+    readonly size: number;
+    readonly slots: Readonly<Record<F, FieldSlot>>;
+    /** `struct <name> { ... }` — prepend to any shader that binds this. */
+    readonly wgsl: string;
+    /** Backing storage for `count` elements. */
+    alloc(count?: number): StructBuffer<F>;
+}
+export interface StructBuffer<F extends string> {
+    readonly def: StructDef<F>;
+    readonly count: number;
+    readonly bytes: ArrayBuffer;
+    /** Write fields by name into element `index`. Unknown names and wrong arity throw. */
+    set(values: StructValues<F>, index?: number): void;
+    /** The byte view to upload; `elements` trims to a prefix of the array. */
+    view(elements?: number): Uint8Array<ArrayBuffer>;
+}
+export declare function defineStruct<F extends string>(name: string, fields: ReadonlyArray<readonly [F, FieldType]>): StructDef<F>;
+export {};

package/dist/types/packages/desk/src/engine/target.d.ts

@@ -0,0 +1,26 @@
+export interface TargetOptions {
+    readonly format: GPUTextureFormat;
+    readonly label?: string;
+    /** Add COPY_SRC when a host wants to read the pixels back (the oracle does). */
+    readonly readable?: boolean;
+}
+export declare class Target {
+    texture: GPUTexture;
+    view: GPUTextureView;
+    width: number;
+    height: number;
+    readonly format: GPUTextureFormat;
+    private readonly usage;
+    private readonly device;
+    private readonly opts;
+    constructor(device: GPUDevice, opts: TargetOptions, width?: number, height?: number);
+    private make;
+    /** True when the texture was recreated (and therefore holds nothing). */
+    resize(w0: number, h0: number): boolean;
+    dispose(): void;
+}
+export type Clear = readonly [number, number, number, number];
+/** Begin a colour-only render pass; `clear` omitted loads the existing contents. */
+export declare function beginPass(encoder: GPUCommandEncoder, view: GPUTextureView, clear?: Clear, label?: string): GPURenderPassEncoder;
+/** Read a texture back as raw bytes with row padding removed (oracle / tests). */
+export declare function readback(device: GPUDevice, texture: GPUTexture, bytesPerTexel: number): Promise<Uint8Array>;

package/dist/types/packages/desk/src/gpu-ablation.d.ts

@@ -0,0 +1,61 @@
+import type { GroundFrameInputs } from "./ground";
+export interface KindCostOptions {
+    /** Rounds (7). */
+    readonly rounds?: number;
+    /** The batch's target GPU time, ms (25). */
+    readonly targetMs?: number;
+    /** The probe's frames (4). */
+    readonly probeFrames?: number;
+    /** The batch's bounds (3 … 300 frames). */
+    readonly minFrames?: number;
+    readonly maxFrames?: number;
+    /** The kinds to leave out (default: every kind with an object in the frame). */
+    readonly kinds?: readonly string[];
+}
+export interface Sampled {
+    readonly median: number;
+    readonly min: number;
+}
+export interface KindCost {
+    /** ms per frame the frame loses without the kind: the median of the paired base − without-k over rounds. */
+    readonly ms: number;
+    /** …as a share of the base frame. */
+    readonly share: number;
+    /** The frame without the kind, ms per frame. */
+    readonly without: Sampled;
+    /** The kind's objects in the frame (every slot's). */
+    readonly objects: number;
+    /** The cost clears the noise floor. */
+    readonly clears: boolean;
+}
+export interface KindCostReport {
+    /** Frames a batch, rounds, and every round's batches in the order drawn. */
+    readonly frames: number;
+    readonly rounds: number;
+    /** The frame as it is, ms per frame. */
+    readonly base: Sampled;
+    /** The A/A control: the same frame as a variant of its own. */
+    readonly control: Sampled;
+    /** median(control) − median(base): the A/A offset. */
+    readonly aa: number;
+    /** The noise floor: the median over rounds of |control − base| within a round. */
+    readonly noise: number;
+    readonly kinds: Readonly<Record<string, KindCost>>;
+    /** Every batch, ms per frame, by variant (`base`, `control`, each kind), in round order — round r drew variant i at position (i − r) mod n. */
+    readonly samples: Readonly<Record<string, readonly number[]>>;
+}
+export interface Ablation {
+    /** The frame to measure (the last one drawn). */
+    readonly inputs: GroundFrameInputs;
+    /** Draw one frame of these inputs, synchronously (`Ground.render`). */
+    render(inputs: GroundFrameInputs): void;
+    /** Resolve once the GPU finished everything submitted (`queue.onSubmittedWorkDone`). */
+    drain(): Promise<unknown>;
+    now(): number;
+}
+/** Every kind with an object in the frame, and how many — the root's, the insides', the departed desk's. */
+export declare function kindsIn(inputs: GroundFrameInputs): Record<string, number>;
+/** The frame with `kind`'s objects left out of every slot (its insides with them); `null` kind: the frame as it is. The held object is always left out (the rest frame). */
+export declare function withoutKind(inputs: GroundFrameInputs, kind: string | null): GroundFrameInputs;
+/** Measure what each kind costs the frame (the header's method). */
+export declare function ablateKinds(a: Ablation, opts?: KindCostOptions): Promise<KindCostReport>;

package/dist/types/packages/desk/src/gpu-memory.d.ts

@@ -0,0 +1,54 @@
+/** A format's block: its footprint in texels and its bytes. `guessed` — a format this table does not know, weighed as 4 bytes a texel. */
+export interface FormatBlock {
+    readonly w: number;
+    readonly h: number;
+    readonly bytes: number;
+    readonly guessed?: boolean;
+}
+export declare function formatBlock(format: string): FormatBlock;
+/** An extent's width, height and depth-or-layers — the list form (`[w, h?, d?]`) or the dictionary form. */
+export declare function extentOf(size: GPUExtent3DStrict): [number, number, number];
+/** The bytes of `size` texels of `format` in one mip (a copy's weight): ⌈w / bw⌉ × ⌈h / bh⌉ × blockBytes × depth. */
+export declare function regionBytes(format: string, size: GPUExtent3DStrict): number;
+/** A texture's logical bytes by the formula above. */
+export declare function textureBytes(d: {
+    readonly size: GPUExtent3DStrict;
+    readonly format: string;
+    readonly mipLevelCount?: number;
+    readonly sampleCount?: number;
+    readonly dimension?: GPUTextureDimension;
+}): number;
+/** One ledger row: the live bytes, and how many textures and buffers make them. */
+export interface GpuMemoryRow {
+    readonly bytes: number;
+    readonly textures: number;
+    readonly buffers: number;
+}
+/** The ledger's reading: live bytes by label prefix (the kind), textures and buffers apart, the total; and its turnover. */
+export interface GpuMemory {
+    /** Live bytes by the resource's label prefix — `paper`, `board`, `photo` …; `?` for an unlabelled one. */
+    readonly byLabel: Readonly<Record<string, GpuMemoryRow>>;
+    readonly textures: number;
+    readonly buffers: number;
+    readonly total: number;
+    /** Resources made since the install (a make every frame is a finding), destroyed, and taken by the collector undestroyed. */
+    readonly made: number;
+    readonly destroyed: number;
+    readonly collected: number;
+    /** Textures whose format the byte table does not know (weighed as 4 bytes a texel). */
+    readonly guessed: number;
+}
+export interface MemoryLedger {
+    /** The ledger as of now (a fresh copy). */
+    read(): GpuMemory;
+    /** The `n` heaviest live labels, full label (`board/ink 12` — every board's raster its own row), heaviest first. */
+    top(n?: number): readonly {
+        readonly label: string;
+        readonly bytes: number;
+        readonly count: number;
+    }[];
+    /** Restore the device's own `createTexture` / `createBuffer`. What it made meanwhile still reports its `destroy` to nobody. Idempotent. */
+    detach(): void;
+}
+/** Keep a ledger of `device`'s live textures and buffers from now on. One per device: asking twice returns the one. */
+export declare function instrumentMemory(device: GPUDevice): MemoryLedger;

package/dist/types/packages/desk/src/gpu-profiler.d.ts

@@ -0,0 +1,141 @@
+import type { GpuMemory, MemoryLedger } from "./gpu-memory";
+import { type KindDraws, type PassCounts, type PassTime, type PassTiming } from "./pass-instrument";
+import type { SubmitInstrument, UploadTally } from "./submit-instrument";
+export interface GpuFrameCounts extends PassCounts {
+    /** `queue.submit` calls in the frame. */
+    readonly submits: number;
+    /** Uploads (`writeBuffer` + `writeTexture` + `copyExternalImageToTexture`) and their bytes. */
+    readonly writes: number;
+    readonly uploadBytes: number;
+    /** The `copyExternalImageToTexture` uploads alone (a picture, a calendar tile). */
+    readonly externals: number;
+}
+export interface GpuFrameReport {
+    /** The profiler's frame number (monotonic across arms). */
+    readonly frame: number;
+    /** "frame": one the desk drew; "loose": GPU work the host's boundary closed with no frame in it — reported, never in the window. */
+    readonly kind: "frame" | "loose";
+    /** `performance.now()` at the frame's first command encoder. */
+    readonly at: number;
+    /** THE HEADLINE: GPU ms from the first timed pass's begin to the last one's end; null when untimed. */
+    readonly span: number | null;
+    /** The passes' own durations summed — NOT the frame's time: overlapping passes count twice, the GPU's waits between them not at all. */
+    readonly sum: number | null;
+    /** The GPU BUSY in the frame: the union of its passes' intervals — overlaps once, waits not at all; `span − busy` is what it waited (the drawable). */
+    readonly busy: number | null;
+    /** The timed passes, ms from the frame's earliest timestamp. */
+    readonly passes: readonly PassTime[];
+    readonly counts: GpuFrameCounts;
+    /** Draws and instances by the kind that drew (the pipeline's label prefix). */
+    readonly byKind: Readonly<Record<string, KindDraws>>;
+    /** The frame's uploads by the written resource's label prefix. */
+    readonly uploads: Readonly<Record<string, UploadTally>>;
+    /** CPU ms: `encode` — the frame's first command encoder to its close; `flush` — the host's flush that held it (null: none, a tool's frame). */
+    readonly cpu: {
+        readonly encode: number;
+        readonly flush: number | null;
+    };
+    /** The ledger's live GPU memory as the frame completed; null when the host keeps no ledger. */
+    readonly memory: GpuMemory | null;
+    readonly timing: PassTiming;
+    /** Every timestamp delta a whole multiple of 100 µs — Dawn's quantisation (`UNQUANTISED_TIMESTAMPS_FLAG` turns it off); null untimed. */
+    readonly quantised: boolean | null;
+}
+/** Rolling percentiles over the window: nearest rank. */
+export interface Rolling {
+    readonly n: number;
+    readonly p50: number;
+    readonly p95: number;
+    readonly max: number;
+}
+export interface GpuProfileStats {
+    readonly armed: boolean;
+    /** Drawn frames in the window (loose work never enters it). */
+    readonly frames: number;
+    /** The GPU span; null while no frame in the window was timed. */
+    readonly span: Rolling | null;
+    /** The GPU busy (the span less the waits). */
+    readonly busy: Rolling | null;
+    readonly encode: Rolling | null;
+    readonly flush: Rolling | null;
+    readonly draws: Rolling | null;
+    readonly instances: Rolling | null;
+    readonly pipelines: Rolling | null;
+    readonly bindGroups: Rolling | null;
+    readonly passes: Rolling | null;
+    readonly submits: Rolling | null;
+    readonly uploadBytes: Rolling | null;
+    /** Most timed frames in the window read quantised → true (a real delta lands on a 100 µs multiple now and then, by chance — one frame is not the clock); else false; nothing timed → null. */
+    readonly quantised: boolean | null;
+    /** The switch that unquantises timestamps — what the dock says when `quantised`. */
+    readonly unquantise: string;
+    /** Samples dropped for a full readback ring, and readbacks in flight (this arming). */
+    readonly dropped: number;
+    readonly inFlight: number;
+}
+export interface TraceEvent {
+    readonly name: string;
+    readonly ph: "X" | "C" | "M";
+    readonly ts: number;
+    readonly dur?: number;
+    readonly pid: number;
+    readonly tid: number;
+    readonly cat?: string;
+    readonly args?: Readonly<Record<string, unknown>>;
+}
+/** A Chrome trace-event file (the JSON object format): Perfetto's and chrome://tracing's. */
+export interface TraceJson {
+    readonly traceEvents: readonly TraceEvent[];
+    readonly displayTimeUnit: "ms";
+    readonly metadata: Readonly<Record<string, unknown>>;
+}
+export interface GpuProfiler {
+    /** The device has timestamp-query: frames are timed. */
+    readonly supported: boolean;
+    armed(): boolean;
+    /** Arm — refcounted: the first arm installs the instruments; returns this arm's release (the last release takes them all off). */
+    arm(): () => void;
+    /** The frames completed since the last take (drained, oldest first) — a rig's reading. */
+    take(): GpuFrameReport[];
+    /** The last frame completed. */
+    last(): GpuFrameReport | null;
+    /** Rolling p50 / p95 / max over the window's drawn frames. */
+    stats(): GpuProfileStats;
+    /** Called with every frame completed while armed; returns the unsubscribe. */
+    subscribe(listener: (report: GpuFrameReport) => void): () => void;
+    /** The host's boundary — its flush ended after `ms`: work with no frame is closed as loose, and the frames it held are given its ms. */
+    flushed(ms: number): void;
+    /** The next `n` frames as a trace-event JSON (arming for as long as it takes); at `timeoutMs` (10 s) it answers with what came. */
+    capture(n: number, opts?: {
+        readonly timeoutMs?: number;
+        readonly measure?: boolean;
+    }): Promise<TraceJson>;
+    /** Disarm whatever holds it and stop. */
+    dispose(): void;
+}
+export interface GpuProfilerOptions {
+    readonly device: GPUDevice;
+    /** The submit instrument, held while armed and released after — the host's (the layer's `submits()` may hold it for good). */
+    readonly submits: {
+        hold(): SubmitInstrument;
+        release(): void;
+    };
+    /** The host's memory ledger, if it keeps one. */
+    readonly ledger?: () => MemoryLedger | undefined;
+    /** Drawn frames in the rolling window (120). */
+    readonly window?: number;
+    /** The encoders whose submit closes a frame (the pass instrument's default: `ground`, `hold`). */
+    readonly frameEncoders?: readonly string[];
+}
+/** Nearest-rank percentiles of `values`; null when empty. */
+export declare function rolling(values: readonly number[]): Rolling | null;
+/** The GPU's busy time in `passes`: the union of their intervals — overlapping passes counted once, the gaps between them not at all. */
+export declare function busyOf(passes: readonly PassTime[]): number | null;
+/** The span of `passes`: first begin → last end; null when there are none. */
+export declare function spanOf(passes: readonly PassTime[]): number | null;
+export declare function createGpuProfiler(opts: GpuProfilerOptions): GpuProfiler;
+/** Frames → a trace-event JSON: CPU spans on the main thread, each GPU pass on a track of its own, the span, counters. µs throughout. */
+export declare function traceOf(frames: readonly GpuFrameReport[], where: ReadonlyMap<number, {
+    readonly flushAt: number | null;
+    readonly firstSubmit: number;
+}>, meta?: Readonly<Record<string, unknown>>): TraceJson;

package/dist/types/packages/desk/src/gpu-wrap.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Replace `obj[key]` with `value`; the undo puts back exactly what was there — the own property it had, or no own property at all
+ * (the prototype's method shows through again, so "the wrappers are gone" is literal). Wrapped over since, the undo leaves
+ * ours beneath theirs: the caller's wrapper must then pass through.
+ */
+export declare function swapMethod<T extends object, K extends keyof T>(obj: T, key: K, value: T[K]): () => void;
+/** A resource's label prefix — its kind: `paper/notes` → `paper`; no label → `?`. */
+export declare const prefixOf: (label: string | undefined) => string;