@vibecook/ice 0.11.0 → 0.14.0

package/dist/types/packages/desk/src/mat/night.d.ts

@@ -0,0 +1,95 @@
+import type { RGB } from "../theme";
+/** What the mat is lit by — a theme's light. `night` 0 is the reference's day chain, bit for bit. */
+export interface MatLight {
+    /** 0 = the day (the reference's chain, exactly) · 1 = the night · between: a cross-fade of the two on the display. */
+    readonly night: number;
+    /** The Moon's illuminance on the desk, lux — where on the mesopic ramp the eye sits. */
+    readonly lux: number;
+    /** Scene → display: the scale the adapted eye's report is drawn at. */
+    readonly exposure: number;
+    /** The rods' own noise, display units, peak to peak. */
+    readonly snow: number;
+    /** The Moon's colour as the (partly) adapted eye takes it — linear sRGB at Y = 1. */
+    readonly moon: RGB;
+    /** The sky's share of the light where the Moon is blocked. */
+    readonly fill: number;
+    /** The rods' signal drawn as a colour — linear sRGB at Y = 1. */
+    readonly rod: RGB;
+    /** The dark the eye adds to everything — linear sRGB. */
+    readonly eigengrau: RGB;
+}
+/** The day: the reference's chain, untouched — every night number inert. */
+export declare const DAY_LIGHT: MatLight;
+/** The night as the theme states it (theme.ts `NIGHT`). */
+export interface NightSpec {
+    /** The Moon's colour temperature, K. */
+    readonly kelvin: number;
+    /** Its illuminance on the desk, lux. */
+    readonly lux: number;
+    /** The sky's share in the shadow. */
+    readonly fill: number;
+    /** The rods' hue: a spectral wavelength (470–500 nm) and how far from white toward it. */
+    readonly rodHue: {
+        readonly nm: number;
+        readonly purity: number;
+    };
+    /** Eigengrau, sRGB 0..1. */
+    readonly eigengrau: RGB;
+    /** The display luminance (linear, Eigengrau included) the moonlit ground is drawn at — the appearance's one scale. */
+    readonly litLuminance: number;
+    /** The rods' noise, display units peak to peak. */
+    readonly snow: number;
+    /** CIECAM02's surround factor F for the degree of adaptation: 1 average · 0.9 dim · 0.8 dark. */
+    readonly surround: number;
+}
+export declare const srgbToLinear: (c: number) => number;
+export declare const linearToSrgb: (c: number) => number;
+export declare const linear: (c: RGB) => RGB;
+/** Photopic luminance Y of a linear sRGB colour. */
+export declare const luminance: (c: RGB) => number;
+/**
+ * Scotopic luminance V' from XYZ — Larson, Rushmeier & Piatko 1997's regression
+ * (the one the night-rendering literature uses: Jensen et al. 2000, Kirk & O'Brien 2011).
+ * The rods peak at 507 nm: greens and blues keep their brightness by night, reds die.
+ */
+export declare function scotopic(c: RGB): number;
+/** The rods' signal, white = 1 — what the shader calls `rod`. */
+export declare const rodSignal: (c: RGB) => number;
+/** CIE 191:2010's mesopic adaptation coefficient (first order, seeded by the photopic luminance): 0 at 0.005 cd/m² (the rods alone), 1 at 5 (the cones alone). */
+export declare const mesopicWeight: (L: number) => number;
+/** CIECAM02's degree of chromatic adaptation at an adapting luminance (cd/m²): how much of the illuminant's colour the eye discounts. */
+export declare const degreeOfAdaptation: (LA: number, F: number) => number;
+/** The Planckian locus in CIE 1931 xy — Kang et al. 2002's fit, 1667–25000 K. */
+export declare function planckianXY(T: number): readonly [number, number];
+/** A chromaticity as linear sRGB at Y = 1. */
+export declare const xyToLinear: (x: number, y: number) => RGB;
+/** D65's chromaticity — sRGB's white. */
+export declare const D65: readonly [number, number];
+export declare function spectralXY(nm: number): readonly [number, number];
+/** White pulled `purity` of the way toward a spectral hue, as linear sRGB at Y = 1. */
+export declare function hueTint(nm: number, purity: number): RGB;
+/**
+ * The reference's day chain writes the LINEARISED albedo to the swap chain as sRGB
+ * (README §4e), so what the display shows for a lit pixel is that value decoded once
+ * more: the day's displayed luminance of a ground colour.
+ */
+export declare const dayLuminance: (groundSrgb: RGB) => number;
+/** The eye's report of a linear albedo under `light` at `shade` (1 lit · `fill` in full shadow) — linear, before Eigengrau and the exposure. */
+export declare function nightReport(light: MatLight, albedoLinear: RGB, shade: number): RGB;
+/** The shader's `night_mat` on the CPU: what the display shows (sRGB 0..1), the snow left out. */
+export declare function nightAppearance(light: MatLight, albedoLinear: RGB, shade: number): RGB;
+/** The theme's night, computed for a ground colour (sRGB 0..1): the light the mat pass reads. */
+export declare function nightLight(spec: NightSpec, groundSrgb: RGB): MatLight;
+/** The light's four vec4s, by name (MatUniforms). */
+export declare function lightValues(l: MatLight): {
+    night: number[];
+    moon: number[];
+    rod: number[];
+    eigengrau: number[];
+};
+/**
+ * A light between two (design-015 §8, D4b — the reading light): the object in hand keeps its DAY light while the mat
+ * stays moonlit, the change riding the carry (`t` 0 = `a`, 1 = `b`); every field lerped, the colours channel-wise.
+ * `nightAppearance` is linear in each of them within a frame, so a lerp of the parameters is an honest in-between.
+ */
+export declare function mixLight(a: MatLight, b: MatLight, t: number): MatLight;

package/dist/types/packages/desk/src/mat/projector.d.ts

@@ -0,0 +1,39 @@
+/** 16 column-major floats — `Matrix4.elements`, and what WGSL's `mat4x4f` reads. */
+export type Mat4 = Float32Array;
+/** The sixteen cells as a tuple: the length is the type, so a literal index needs no guard (ICE's kernel casts bounded reads the same way). */
+export type Mat4Cells = readonly [number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number];
+export declare const cells: (m: Mat4) => Mat4Cells;
+export type Vec3 = readonly [number, number, number];
+export type Quat = readonly [number, number, number, number];
+export interface ProjectorSpec {
+    /** World metres, y up — the desk scene's frame. */
+    readonly position: Vec3;
+    readonly quaternion: Quat;
+    readonly fovDeg: number;
+    readonly aspect: number;
+    readonly near: number;
+    readonly far: number;
+}
+/** three's `makePerspective`, WebGL coordinate system. */
+export declare function perspective(fovDeg: number, aspect: number, near: number, far: number): Mat4;
+/** Rotation matrix of a unit quaternion (three's `makeRotationFromQuaternion`). */
+export declare function fromQuat(q: Quat): Mat4;
+/** `a · b`, column-major. */
+export declare function mul4(a: Mat4, b: Mat4): Mat4;
+/** The inverse of `translate(p) · rotate(q)`: `Rᵀ · translate(−p)` — a camera's `matrixWorldInverse`. */
+export declare function rigidInverse(position: Vec3, q: Quat): Mat4;
+/** `projection · view` for a projector — the matrix a receiver multiplies its world position by. */
+export declare function projectorMatrix(spec: ProjectorSpec): Mat4;
+/** three's `Quaternion.setFromEuler`, order XYZ. */
+export declare function quatFromEuler(x: number, y: number, z: number): Quat;
+/** The reference's mouse tilt: `rotate(euler) · base`, the rotation applied in clip space. */
+export declare function tilted(base: Mat4, ex: number, ey: number, ez: number): Mat4;
+/** A world point through the matrix: NDC xyz and clip w (the linear depth of a perspective projector). */
+export declare function project(m: Mat4, p: Vec3): {
+    ndc: [number, number, number];
+    w: number;
+};
+/** mat.wgsl `blur_ratio` — the reference's `getGoboBlurRatio`: linearise the WebGL NDC z, then a ramp between two depths. */
+export declare function blurRatio(ndcZ: number, sharp: number, soft: number, near: number, far: number): number;
+/** The hero desk's projector, as baked in the reference (research/tree-shadow/prototype/src/scenes.js). */
+export declare const HERO_PROJECTOR: ProjectorSpec;

package/dist/types/packages/desk/src/mat/shaders.d.ts

@@ -0,0 +1,17 @@
+import type { ShaderPart } from "../engine/shader";
+export interface MatShaders {
+    readonly modules: readonly ShaderPart[];
+    readonly wind: ShaderPart;
+    readonly entry: ShaderPart;
+}
+export interface MatShaderText {
+    /** shaders/portal.wgsl — the portal clip every pass includes. */
+    readonly portal: string;
+    readonly mat: string;
+    /** shaders/mat/ruler.wgsl — the rulers' print (RULER.md). */
+    readonly ruler: string;
+    readonly wind: string;
+    readonly matPass: string;
+}
+export declare const MAT_SHADER_FILES: Record<keyof MatShaderText, string>;
+export declare function matShaders(t: MatShaderText): MatShaders;

package/dist/types/packages/desk/src/mat/tilt.d.ts

@@ -0,0 +1,14 @@
+export interface SecondOrder {
+    readonly k1: number;
+    readonly k2: number;
+    readonly k3: number;
+    readonly w: number;
+    readonly z: number;
+    readonly d: number;
+    target: [number, number];
+    prevTarget: [number, number];
+    value: [number, number];
+    velocity: [number, number];
+}
+export declare function secondOrder(f?: number, z?: number, r?: number, value?: readonly [number, number]): SecondOrder;
+export declare function stepSecondOrder(s: SecondOrder, dt: number): void;

package/dist/types/packages/desk/src/nav/flight.d.ts

@@ -0,0 +1,186 @@
+export interface CameraState {
+    readonly x: number;
+    readonly y: number;
+    readonly zoom: number;
+}
+export interface Rect {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+export interface Viewport {
+    readonly width: number;
+    readonly height: number;
+}
+/** Uniform scale + translate: `A(q) = o + q·s`. */
+export interface PortalAffine {
+    readonly s: number;
+    readonly ox: number;
+    readonly oy: number;
+}
+/** The world rect a camera shows through a viewport. */
+export declare function visibleRect(cam: CameraState, vpW: number, vpH: number): Rect;
+/**
+ * The portal embedding: map `arrival` (the world rect the arrival camera will
+ * show, in the CHILD frame's coords) onto `portal` (the container's body rect,
+ * in the PARENT frame's coords). Aspect-FIT with centres aligned (design-006
+ * §8.3 — the container's chrome absorbs the letterbox; a mini mat's face shows
+ * the inside past the arrival on its longer side, MINIMAT.md §3).
+ */
+export declare function portalAffine(arrival: Rect, portal: Rect): PortalAffine;
+export declare function invertAffine(a: PortalAffine): PortalAffine;
+/** `(outer ∘ inner)(q) = outer(inner(q))` — for multi-level exit portals. */
+export declare function composeAffine(outer: PortalAffine, inner: PortalAffine): PortalAffine;
+/**
+ * Continuity solve: the camera `c0` (in the DESTINATION frame) under which
+ * departed-frame content mapped through `A` (departed → destination coords)
+ * renders EXACTLY as it did under `camPre` (in the departed frame) the instant
+ * before the cut. Zoom limits deliberately do NOT apply here — flight paths
+ * transit far outside the user-gesture band; only the ARRIVAL camera is
+ * clamped by the caller.
+ */
+export declare function solveFlightStart(A: PortalAffine, camPre: CameraState): CameraState;
+/**
+ * Destination camera expressed in departed-frame coordinates. Rendering the
+ * outgoing ground with this camera is pixel-equivalent to first mapping its
+ * points through A and then rendering under `destination`.
+ */
+export declare function outgoingCamera(A: PortalAffine, destination: CameraState): CameraState;
+/** Zoom distance in octaves — the flight-length measure (design-006 §4/§5). */
+export declare function flightOctaves(from: CameraState, to: CameraState): number;
+/**
+ * Depth-cap a flight start (design-006 §5): beyond `maxOctaves`, clamp the
+ * start zoom to `capFactor ×` the arrival zoom (dive direction preserved),
+ * keeping the exact start's view CENTRE — the portal anchor — so the motion
+ * still comes from/goes to the right place. `capped: true` means the caller
+ * presents the flight as a crossfade (`flightOpacity` with `frozen`).
+ */
+export declare function capFlightStart(exact: CameraState, arrival: CameraState, vpW: number, vpH: number, maxOctaves: number, capFactor: number): {
+    c0: CameraState;
+    capped: boolean;
+};
+/**
+ * The flight path `c(p)`, p ∈ [0,1]: zoom log-lerped (constant perceived zoom
+ * velocity); view CENTRE linear in 1/zoom — exactly an anchored zoom whenever
+ * a fixed screen point exists between the endpoints, a graceful blend
+ * otherwise. Endpoints are exact: c(0) = c0, c(1) = c1.
+ */
+export declare function flightCamera(c0: CameraState, c1: CameraState, p: number, vpW: number, vpH: number): CameraState;
+/**
+ * One step of the critically-damped progress spring toward 1, in CLOSED FORM:
+ * with u = 1 − p, the exact solution is `u(t) = (u₀ + Bt)·e^(−ωt)`,
+ * `B = −v₀ + ω·u₀`. Unconditionally stable at ANY dt. From rest (v = 0) the
+ * approach is monotonic: p never overshoots 1.
+ */
+export declare function springStep(p: number, v: number, omega: number, dtSec: number): {
+    p: number;
+    v: number;
+};
+/** Zoom-to-fit `content` with `pad` (world units), the zoom clamped into a band (kernel coords.ts). */
+export declare function fitCamera(content: Rect, vpW: number, vpH: number, opts: {
+    pad: number;
+    minZoom: number;
+    maxZoom: number;
+}): CameraState;
+/** `@ice/core` NAV_TRANSITION_DEFAULTS — the response the product flies at. */
+export declare const NAV: {
+    readonly responseMs: 420;
+    readonly exitResponseFactor: 0.8;
+    readonly durationPerOctave: 0.12;
+    readonly baseOctaves: 3.5;
+    readonly freezeOctaves: 4.2;
+    readonly capFactor: 10;
+    readonly settleP: 0.999;
+    readonly settleV: 0.02;
+};
+export type FlightTuning = {
+    readonly [K in keyof typeof NAV]: number;
+};
+/** `@ice/core` FIT_DEFAULTS — the NATURAL band an arrival is framed into (design-006, amended 2026-07-18). */
+export declare const FIT: {
+    readonly pad: 80;
+    readonly minZoom: 0.5;
+    readonly maxZoom: 1;
+};
+export type FitBand = {
+    readonly [K in keyof typeof FIT]: number;
+};
+export type NavKind = "enter" | "exit";
+/**
+ * The departing and arriving presentations' opacity at progress `p` — ICE
+ * core `opacityAt`, verbatim. Enter: the parent holds until p ≈ 0.3 and is
+ * gone by 0.75 (most of it has physically left the viewport by then). Exit:
+ * the inner frame holds to 0.85 and fades as it lands on the card face. A
+ * FROZEN (depth-capped) flight is a crossfade: out 0.05→0.45, in 0.3→0.7.
+ */
+export declare function flightOpacity(kind: NavKind, p: number, frozen: boolean): {
+    readonly outgoing: number;
+    readonly incoming: number;
+};
+/**
+ * One in-flight transition — what ICE keeps in its `NavTransition` resource,
+ * minus the ECS. The host owns the clock: `stepFlight` each frame until
+ * `active` clears, `flightAt` for a pinned still.
+ */
+export interface Flight {
+    readonly kind: NavKind;
+    /** A: departed-frame coords → destination-frame coords. */
+    readonly affine: PortalAffine;
+    /** The departed frame's camera at the cut — what it renders under at p = 0, and throughout a frozen flight. */
+    readonly camPre: CameraState;
+    readonly c0: CameraState;
+    readonly c1: CameraState;
+    /** Depth-capped: present as a crossfade (`flightOpacity`). */
+    readonly frozen: boolean;
+    /** Response multiplier from octave distance, locked at start (§4). */
+    readonly durMul: number;
+    p: number;
+    v: number;
+    active: boolean;
+}
+/**
+ * Arm a flight from the already-cut world: `camPre` the departed frame's
+ * camera at the cut (the continuity solve gives c0 in destination coords),
+ * `c1` the clamped arrival. Applies the depth cap and the octave response.
+ * The host snaps its camera to `flight.c0`.
+ */
+export declare function startFlight(kind: NavKind, A: PortalAffine, camPre: CameraState, c1: CameraState, vp: Viewport, tune?: FlightTuning, exact?: CameraState): Flight;
+/**
+ * The camera the DEPARTED frame renders under this frame. Riding the flight
+ * through the affine (`outgoingCamera`) — except at the cut itself, where it
+ * is the pre-cut camera bit for bit (the affine and its inverse round-trip to
+ * within an ulp, and at zoom 1 an ulp is the other side of a decade), and
+ * throughout a FROZEN flight, where the departed frame stays at its pre-cut
+ * appearance and fades (design-006 §5: the cap broke the geometry, so the
+ * story is a dissolve, not a portal).
+ */
+export declare function departedCamera(f: Flight, cam: CameraState): CameraState;
+/** Advance the spring by `dtSec`; returns the camera for this frame. Lands EXACTLY on c1 and clears `active` at settle. */
+export declare function stepFlight(f: Flight, dtSec: number, vp: Viewport, tune?: FlightTuning): CameraState;
+/** The camera at progress `p` — a pinned still (the oracle's scenes, the harness's shots). The endpoints are c0 and c1 themselves, bit for bit. */
+export declare function flightAt(f: Flight, p: number, vp: Viewport): CameraState;
+/** The bounds of some rects, or null when there are none. */
+export declare function boundsOf(rects: readonly Rect[]): Rect | null;
+/**
+ * The DEFAULT framing for a frame (design-006 as amended): zoom-to-fit its
+ * content capped into the natural band; an empty frame arrives centred on
+ * its origin at zoom 1.
+ */
+export declare function arrivalCamera(content: Rect | null, vp: Viewport, fit?: FitBand): CameraState;
+/** A flight that is already over — what a degenerate portal (no area) gets: the host snaps to the arrival, as ICE's rect-less link "degrades the whole jump to a snap — never half-fly". */
+export declare function cutFlight(kind: NavKind, camPre: CameraState, c1: CameraState): Flight;
+/**
+ * ENTER a container whose body rect is `K` (parent coords) holding `content`
+ * (child coords): the arrival is the child's default framing, the portal maps
+ * that arrival onto K, and the flight starts where the parent was. The host
+ * switches frames, snaps its camera to `flight.c0`, then steps.
+ */
+export declare function enterFlight(K: Rect, content: Rect | null, camPre: CameraState, vp: Viewport, tune?: FlightTuning, fit?: FitBand, exact?: CameraState): Flight;
+/**
+ * EXIT to the parent: the portal is rebuilt from the container's CURRENT rect
+ * `K` and the inner frame's default framing (so arrival and preview agree),
+ * and the landing is the camera saved at entry. `camPre` is the inner camera
+ * at the cut.
+ */
+export declare function exitFlight(K: Rect, inner: Rect | null, camPre: CameraState, saved: CameraState, vp: Viewport, tune?: FlightTuning, fit?: FitBand): Flight;

package/dist/types/packages/desk/src/nav/portal.d.ts

@@ -0,0 +1,95 @@
+import type { Box } from "../lattice/lod";
+import type { CameraState, Rect, Viewport } from "./flight";
+/**
+ * A rounded rect in screen CSS px: centre, half extents, corner radius — and a top FEATHER (design-018 §4): what the face shows
+ * fades in over this many CSS px below its top edge, a smoothstep in every pass's `portal_cover` (absent or 0: a hard edge). The
+ * pegboard tray's face carries one — its top the foot of the drawer's clear header (design-018 R4) — so its specimens dissolve into the
+ * board under the header instead of being cut.
+ */
+export interface PortalClip {
+    readonly cx: number;
+    readonly cy: number;
+    readonly hx: number;
+    readonly hy: number;
+    readonly r: number;
+    readonly feather?: number;
+}
+/**
+ * The most faces a slot can be seen through, its own included — the length
+ * of every uniform block's `portals`/`clips` arrays; portal.wgsl's
+ * `PORTAL_CHAIN` is the same number (a mismatch fails to compile). Six holds
+ * a host's depth belt of four plus the flight's face.
+ */
+export declare const PORTAL_CHAIN = 6;
+/** The struct field type of a chain record (gpu/struct.ts). */
+export declare const PORTAL_CHAIN_TYPE: "array<vec4f, 6>";
+export interface Presentation {
+    /** Multiplies the slot's every alpha; 1 at rest. */
+    readonly opacity: number;
+    /**
+     * Multiplies its OBJECTS' alphas on top — not its mat (MINIMAT.md §5): a mini mat's live inside
+     * comes in over the face's own drawing with its mat whole at once (the same lattice, lit by the
+     * same lamp — nothing to see) and its objects fading in by the gate's answer, as the face's chips
+     * fade out over them. Absent = 1.
+     */
+    readonly objects?: number;
+    /** The face this slot is seen through; absent = visible everywhere (the root). */
+    readonly portal?: PortalClip;
+    /**
+     * The faces the slot's PARENT is seen through, nearest first: a nested slot is
+     * visible only inside all of them. The ground fills this in from the tree
+     * (PORTAL.md §10); a host never needs to.
+     */
+    readonly within?: readonly PortalClip[];
+}
+/** The chain a presentation clips to: its own face first, then every face above it. Empty = everywhere. */
+export declare function chainOf(p: Presentation | undefined): PortalClip[];
+/** The `portals` and `clips` records every uniform block carries: the chain in order, a zero `clips[i].y` ending it; `clips[i].z` the feather. */
+export declare function portalValues(p: Presentation | undefined): {
+    portals: number[];
+    clips: number[];
+};
+/** A world rect (with a corner radius) as the portal it makes on screen under `cam`. */
+export declare function clipOf(K: Rect, radius: number, cam: CameraState): PortalClip;
+/**
+ * The slot's BOX for a portal (CSS px, inside the attachment; lod.ts `Box`):
+ * the portal's bounding box plus a CSS px for the AA ramp. What a nested
+ * slot instances, bakes and culls — its cost (PORTAL.md §2.3). The ground
+ * intersects it with the parent's box (§10).
+ */
+export declare function boxOfPortal(c: PortalClip, attach: {
+    readonly width: number;
+    readonly height: number;
+}): Box;
+/** The intersection of two boxes; empty (zero size) when they miss. */
+export declare function intersectBox(a: Box, b: Box): Box;
+/**
+ * The GATE (PORTAL.md §2.5, MINIMAT.md §5): a container's face shows its LIVE
+ * inside only when its short side on screen is at least `lo` CSS px, fading in
+ * fully by `hi` — the rung law applied to portals. Below it no slot exists and
+ * the mini mat draws its face itself (its far LOD); zoomed out, a desk of mini
+ * mats costs one instanced draw. The engine holds the numbers (theme.ts
+ * `PORTAL.gate`); the mini mat, the one container, takes them by name.
+ */
+export declare const PORTAL_GATE: readonly [number, number];
+/** The pool's cap: at most this many faces carry a slot per frame, largest first (PORTAL.md Q-f). */
+export declare const PORTAL_CAP = 16;
+/** The slot's presence for a face on screen — its opacity; 0 = no slot. */
+export declare const portalPresence: (c: PortalClip, gate?: readonly [number, number]) => number;
+/**
+ * ZOOM-THROUGH (PORTAL.md §8, §9): does a face COVER the viewport — every corner of the
+ * viewport inside the face's rounded rect by at least `margin` CSS px (negative = may
+ * poke out by that much)? Entering when it does is a cut nobody can see: the whole view
+ * is already the inside; leaving when it no longer does shows the parent only where the
+ * face has left the view. The two margins make the dead band.
+ */
+export declare function faceCovers(c: PortalClip, vp: Viewport, margin: number): boolean;
+/** The dead band: enter once the face covers the view by this much … */
+export declare const THROUGH_IN = 2;
+/** … leave once it fails to cover by this much. */
+export declare const THROUGH_OUT = 6;
+/** The scissor a presentation draws inside (device px): the chain's bounding boxes intersected, a device px of slack for the AA ramp; the attachment when there is no chain. */
+export declare function scissorOf(p: Presentation | undefined, dpr: number, size: {
+    readonly w: number;
+    readonly h: number;
+}): readonly [number, number, number, number];

package/dist/types/packages/desk/src/object.d.ts

@@ -0,0 +1,46 @@
+import { type WidgetContainerDef, type WidgetDef, type WidgetType } from "../../core/src/index";
+import { type KindDriver, type KindDriverHost, type ObjectHost, type ObjectKind } from "./kinds/world";
+/** An object that PROVIDES this lies on the desk: the desk canvas places what provides it (K5b's D-K5b.2, folded into the SDK). */
+export declare const DESK_OBJECT = "desk.object";
+/**
+ * An object that PROVIDES this may be held in a container's desk — the mini mat accepts it (K8a: D-K4a.3's type names retired). It
+ * declares its CHIP (`ObjectKind.chip` — its far impostor in the container's face), or it vanishes there when the face is far.
+ */
+export declare const CONTAINABLE = "desk.containable";
+/** An object that PROVIDES this may be pinned to another's part — a note stuck to a desk calendar's day (`KindDriverHost.provides`). */
+export declare const PINNABLE = "desk.pinnable";
+/** A kind's drivers on one desk, made by the host from what it lends (D7 #5, D-D7-A.3). Undefined: the kind has none. */
+export type DriverFactory = (host: KindDriverHost) => KindDriver | undefined;
+/** What an object declares: a widget definition without a view, plus its KIND. */
+export interface ObjectDef extends Omit<WidgetDef, "object" | "stratum" | "openable" | "defaultSize" | "container" | "heldTools" | "heldTool"> {
+    /** The kind: its program (the ground registers it) and its world half (the builder and the pick source drive it). */
+    readonly kind: ObjectKind;
+    /** The size a new one spawns at, world units (`defaultSize`). */
+    readonly size?: {
+        readonly w: number;
+        readonly h: number;
+    };
+    /** A container object — the mini mat: what it accepts and the FACE its inside shows through (`portal` insets). */
+    readonly container?: WidgetContainerDef;
+    /**
+     * The kind's DRIVERS (D7 #5): the hand onto its state — a pen, a carry, a leaf, a writing session — made once per desk by
+     * the host from what it lends (`KindDriverHost`) and ticked before the kinds' clocks. The object hands its own components to
+     * its driver here, so no driver need import its object back. Absent: the kind is looked at and moved, never worked in.
+     */
+    readonly drivers?: DriverFactory;
+    /**
+     * The object's DOM HALF (K4b, `ObjectHost`): what its kind needs of the browser — services lent by key (K8a: the calendar's print
+     * raster), its TEXT PARTS that lease the desk's one editor (the note's body, the calendar's day line), a screen-space half (the
+     * calendar's days and pen) — declared here as its drivers are, so the host builds it without naming the kind. Absent: the object
+     * needs nothing of the browser.
+     */
+    readonly host?: ObjectHost;
+}
+/** Compile an object through `defineWidget` — one door, one registry. */
+export declare function defineObject(def: ObjectDef): WidgetType;
+/** The kind behind a widget type, or undefined: not an object, or a binding that is not a desk kind. */
+export declare function objectKindOf(widget: WidgetType | undefined): ObjectKind | undefined;
+/** The drivers an object declared (`ObjectDef.drivers`), or undefined: none, or not an object of this desk. */
+export declare function driversOf(widget: WidgetType | undefined): DriverFactory | undefined;
+/** The DOM half an object declared (`ObjectDef.host`), or undefined: none, or not an object of this desk. */
+export declare function hostOf(widget: WidgetType | undefined): ObjectHost | undefined;

package/dist/types/packages/desk/src/pass-instrument.d.ts

@@ -0,0 +1,89 @@
+/** Dawn's timestamp quantum when quantisation is on: 100 µs, in the nanoseconds a timestamp query reads. */
+export declare const TIMESTAMP_QUANTUM_NS = 100000n;
+/** The Chrome switch that turns the quantisation off (the rigs pass it — scripts/cdp.mjs). */
+export declare const UNQUANTISED_TIMESTAMPS_FLAG = "--disable-dawn-features=timestamp_quantization";
+export interface PassCounts {
+    /** Command encoders made. */
+    readonly encoders: number;
+    /** Render and compute passes begun, and how many of them were timed. */
+    readonly passes: number;
+    readonly timed: number;
+    /** `draw` + `drawIndexed` + `drawIndirect` + `drawIndexedIndirect`. */
+    readonly draws: number;
+    /** The instances the direct draws asked for (an indirect draw's count is the GPU's: counted in `indirect`, not here). */
+    readonly instances: number;
+    readonly indirect: number;
+    readonly dispatches: number;
+    /** `setPipeline` / `setBindGroup` calls — every call is a command, a rebind of the same object included. */
+    readonly pipelines: number;
+    readonly bindGroups: number;
+    /** `executeBundles` calls (their draws are the bundles', unseen here). */
+    readonly bundles: number;
+}
+export interface KindDraws {
+    readonly draws: number;
+    readonly instances: number;
+}
+/** A timed pass: its label, and its begin and end in ms from the frame's earliest timestamp. */
+export interface PassTime {
+    readonly label: string;
+    readonly begin: number;
+    readonly end: number;
+}
+export type PassTiming = "timed" | "unsupported" | "dropped" | "untimed" | "lost";
+export interface PassFrame {
+    readonly serial: number;
+    /** "frame": closed by the submit of a frame's own encoder — a frame drawn; "loose": GPU work a boundary closed with no frame in it. */
+    readonly kind: "frame" | "loose";
+    /** `performance.now()` at the frame's first command encoder, at its first submit, and at its close. */
+    readonly t0: number;
+    readonly firstSubmit: number;
+    readonly t1: number;
+    readonly counts: PassCounts;
+    /** Draws and instances by the pipeline's label prefix — the kind that drew (`paper`, `photo`, `mat` …; `?` before any pipeline). */
+    readonly byKind: Readonly<Record<string, KindDraws>>;
+    /** The timed passes in the order begun. Empty unless `timing` is "timed". */
+    readonly passes: readonly PassTime[];
+    /**
+     * "timed" — read back; "unsupported" — the device has no timestamp-query; "dropped" — every readback slot was still in flight
+     * (never a stall); "untimed" — no labelled pass; "lost" — the readback failed (a lost device).
+     */
+    readonly timing: PassTiming;
+    /** Every delta between the frame's timestamps is a whole multiple of 100 µs (Dawn's quantisation); null with fewer than two. */
+    readonly quantised: boolean | null;
+}
+export interface PassInstrumentOptions {
+    /** The labels of the encoders whose submit CLOSES a frame — the frame's last command buffer. Default: the ground's, `ground` and `hold`. */
+    readonly frameEncoders?: readonly string[];
+    /** Timed passes a frame may hold (64); the rest are counted, not timed. */
+    readonly capacity?: number;
+    /** Readback slots (3). */
+    readonly ring?: number;
+    /** At a frame's close, synchronously — before its timing is read (a reader of other counters diffs them here). */
+    readonly onClose?: (serial: number, kind: "frame" | "loose") => void;
+    /** A frame complete: its counts, and its timing once read back — always a later task than its close. */
+    readonly onFrame?: (frame: PassFrame) => void;
+}
+export interface PassInstrument {
+    /** The device has timestamp-query: labelled passes are timed. */
+    readonly supported: boolean;
+    /** Close the open frame now (the host's boundary — the layer's flush): whatever was encoded since the last close is a "loose" frame. */
+    cut(): void;
+    /** Frames closed, readbacks in flight, samples dropped for a full ring. */
+    stats(): {
+        readonly frames: number;
+        readonly inFlight: number;
+        readonly dropped: number;
+    };
+    /** Put `createCommandEncoder` back and leave the submit tap; the query set and buffers go a task later (no encoder of this task then holds them). Idempotent. */
+    detach(): void;
+}
+/** A frame's timestamps → its passes and whether they are quantised. Passes with an unwritten (zero) stamp are left out. */
+export declare function readTimestamps(stamps: BigUint64Array, timed: readonly {
+    readonly label: string;
+    readonly q: number;
+}[]): {
+    passes: PassTime[];
+    quantised: boolean | null;
+};
+export declare function instrumentPasses(device: GPUDevice, opts?: PassInstrumentOptions): PassInstrument;

package/dist/types/packages/desk/src/shaders.d.ts

@@ -0,0 +1,12 @@
+/**
+ * A host's shader text: a shader-file map (`MAT_SHADER_FILES`, …) → the text of every file it names, by the map's
+ * keys — `shaderText` below (the generated module) in a browser, the .wgsl files read from disk in the Node oracle.
+ * A kind's program is made for one (kinds/: `paperProgram(text)`, `deskKinds(text)`).
+ */
+export type ShaderText = <T extends Record<string, string>>(files: T) => {
+    readonly [K in keyof T]: string;
+};
+/** The text of every file a shader-file map names, by the map's keys. */
+export declare function shaderText<T extends Record<string, string>>(files: T): {
+    readonly [K in keyof T]: string;
+};