@vibecook/ice 0.11.0 → 0.14.0

package/dist/types/packages/desk/src/tray/drawer.d.ts

@@ -0,0 +1,113 @@
+/** The drawer's numbers (design-017 §7). Lengths are CSS px; times ms. */
+export declare const DRAWER: {
+    /** The pegboard's pitch — the research's unit on screen, chosen by eye for a UI board. */
+    readonly pitch: 40;
+    /** `min(1120 px, 100 % − 32 px)`, snapped DOWN to whole pitches (its sides a solid border — lattice.ts `PEG.border`, D-K3.1). */
+    readonly maxWidth: 1120;
+    readonly margin: 16;
+    /** ≈ 44 % of the view high, clamped. */
+    readonly heightFrac: 0.44;
+    readonly minHeight: 220;
+    readonly maxHeight: 640;
+    /**
+     * The top corners' radius — a hardboard panel's, about SKÅDIS's ¼ pitch (design-018 §2: widgetlab's 22 read as a card) — and the
+     * ARRIS: the board's edge, a quarter-round this wide where its face meets the outline, in the face's own material (the rim retired;
+     * D-R1.1 — the thinner end of design-018's 1.5–2: at 2 px the lit top edge read as a thin cream rim again).
+     */
+    readonly radius: 10;
+    readonly arris: 1.5;
+    /** The edge's inner shadow on the lamp's side (D-R1.2): black at this alpha just inside the edge, fading over this many px. */
+    readonly inner: {
+        readonly alpha: 0.18;
+        readonly width: 3;
+    };
+    /**
+     * The HEADER (design-018 R4 — James, 2026-09-28: "make the fade stronger and more gap, and design the filters nicely at that empty
+     * safe top space instead"): a CLEAR band this high under the face's top edge (inside the arris) where what hangs on the board — the
+     * specimens, their shadows, their accessories and their tags — and the holes are wholly gone: the plain face, on which the bar lays
+     * its category chips as label tape (`<TrayBar>`, @ice/react — the handle's `anchor().drawer.header`). The face's portal clip starts
+     * this far down, so nothing of the content is even drawn above it.
+     */
+    readonly header: 48;
+    /**
+     * The CONTENT's fade under the header (design-018 §4, R4): the specimens, their shadows, their accessories, their tags and the holes
+     * fade in over this band (CSS px, 0.8 pitch) — `smoothstep(top + header, top + header + fade, y)`, `top` the face's top edge — the
+     * feather on the face's portal clip (R1's 28 px band at the edge itself, stretched and moved down: D-R4.1). The board does not fade.
+     */
+    readonly fade: 32;
+    /** The slide: widgetlab rev 1's curve. */
+    readonly slideMs: 340;
+    readonly curve: readonly [0.32, 0.72, 0, 1];
+    /** Black over the desk at the full slide: widgetlab's 10 % by day, 40 % by night. */
+    readonly dim: {
+        readonly day: 0.1;
+        readonly night: 0.4;
+    };
+    /**
+     * The shadows on the desk: the ROOM's, round the whole outline (what shows above the drawer: it lies over the desk), and the LAMP's,
+     * pushed along its ground direction — each the outline's SDF blurred σ, at α.
+     */
+    readonly shadow: {
+        readonly room: {
+            readonly sigma: 14;
+            readonly alpha: 0.22;
+        };
+        readonly lamp: {
+            readonly sigma: 18;
+            readonly alpha: 0.18;
+            readonly push: 8;
+        };
+    };
+    /** The rubber band: its asymptote and stiffness (iOS's curve), how long the scroll input must be quiet before it lets go, the settle's spring. */
+    readonly band: {
+        readonly max: 72;
+        readonly c: 0.55;
+        readonly letGoMs: 120;
+        readonly hz: 8;
+    };
+    /** A specimen's hover lift spring (K5a). */
+    readonly hoverHz: 7;
+    /** A click's slop. */
+    readonly slop: 4;
+};
+/**
+ * How far the drawer's shadows reach past its outline (CSS px): three of the wider blur's σ and the lamp's push — tray.wgsl's `reach`,
+ * one law. Closed, the drawer rests this far below the view, so nothing of it — its shadows included — is on screen (design-018 §5).
+ */
+export declare const SHADOW_REACH: number;
+/** A rect on screen, CSS px: the drawer's outline box as drawn (its top-left, its width, its FULL height — the part below the view included). */
+export interface DrawerRect {
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+}
+/** The drawer's size in a view: whole pitches wide (≤ 1120, ≤ the view − 32), ≈ 44 % of the view high, clamped. */
+export declare function drawerSize(vw: number, vh: number): {
+    readonly w: number;
+    readonly h: number;
+};
+/**
+ * The drawer as drawn at slide `p` (0 closed … 1 open): centred on whole CSS px — open, its bottom flush with the view; closed, wholly
+ * below it with its shadows' reach (design-018 §5: no lip — at p 0 nothing of the drawer is on screen, and nothing is drawn).
+ */
+export declare function drawerRect(vw: number, vh: number, p: number): DrawerRect;
+/**
+ * What of the board's CONTENT shows at screen `y` under a drawer drawn at `rect` (design-018 §4, R4) — the shaders' law on the CPU (the
+ * face's feather in `portal_cover`, `tray_board`'s holes, `tray_accessory`, the tags' draw): 0 above the face and in its header, the
+ * smoothstep over `fade` under it, 1 past it.
+ */
+export declare function contentShown(rect: DrawerRect, y: number): number;
+/** The slide's ease: widgetlab rev 1's `cubic-bezier(0.32,0.72,0,1)`, the exact curve CSS runs (the kernel's). */
+export declare const slideEase: (t: number) => number;
+/**
+ * The rubber band (design-017 §3): what a pull of `stretch` px past an end SHOWS — iOS's curve, `B·(1 − 1/(1 + |s|·c/B))`,
+ * signed: ever less per px pulled, never past `B`.
+ */
+export declare function band(stretch: number): number;
+/**
+ * How far the board scrolls before the band (design-017 §8; K5a — K3's 26-row stub retired): the laid content's foot (`TrayContent.bottom`,
+ * board px) plus a pitch, less the face the drawer shows (its whole height: the face runs to the outline — design-018 §2) — kernel
+ * `trayScrollMax`; 0 with nothing laid.
+ */
+export declare function scrollRange(vw: number, vh: number, bottom: number): number;

package/dist/types/packages/desk/src/tray/flux.d.ts

@@ -0,0 +1,46 @@
+import type { TrayScreenFrame } from "../../../core/src/index";
+import type { TrayFrameInputs } from "./pass";
+/** The facts the flux follows (core's `Tray` and `TrayContent`, as read). */
+export interface TrayFacts {
+    readonly open: boolean;
+    readonly scroll: number;
+    readonly stretch: number;
+    /** K5a: the specimen under the mouse ("" none) — its hover lifts it. */
+    readonly hover?: string;
+    /** K5a: the laid content's foot (board px) — the scroll's range — and the lay count (the specimens moved when it does). */
+    readonly bottom?: number;
+    readonly laid?: number;
+}
+/** A still's pins (a rig's, the oracle's): the slide, the band's shown pull; `hidden` — no tray at all; `bare` — the board without its specimens (K5a). Absent keys follow the facts. */
+export interface TrayPin {
+    readonly p?: number;
+    readonly band?: number;
+    readonly hidden?: boolean;
+    readonly bare?: boolean;
+}
+/** What the flux holds, for a rig: the facts it last read, the slide and when (frame clock, ms) its tween began (−1: not yet stepped), the shown band, the specimens' hover lifts by type (K5a), whether it moves. */
+export interface TrayFluxState {
+    readonly facts: TrayFacts | null;
+    readonly p: number;
+    readonly since: number;
+    readonly band: number;
+    readonly hovers: Readonly<Record<string, number>>;
+    readonly live: boolean;
+}
+export interface TrayFlux {
+    /** Read the world's facts (undefined: no tray); true when they changed since the last read — a frame is due. */
+    read(facts: TrayFacts | undefined): boolean;
+    /** Step the motion to `now` (the frame's clock, ms) for a view `vw × vh` and return the frame's tray — undefined when hidden or absent. */
+    step(now: number, vw: number, vh: number): TrayFrameInputs | undefined;
+    /** Something still moves: the next frame paints too. */
+    live(): boolean;
+    /** The drawer as the last step laid it (the pose seam's answer). */
+    frame(): TrayScreenFrame | undefined;
+    /** A specimen's hover lift this frame, 0 … 1 (K5a). */
+    lift(type: string): number;
+    /** The pins in force (null: none). */
+    pinned(): TrayPin | null;
+    pin(pin: TrayPin | null): void;
+    state(): TrayFluxState;
+}
+export declare function createTrayFlux(): TrayFlux;

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

@@ -0,0 +1,4 @@
+export { band, DRAWER, type DrawerRect, drawerRect, drawerSize, scrollRange, slideEase } from "./drawer";
+export { carry, cellOf, holeCentre, holeSdf, PEG, type PegCell, type PegPoint, pointAt, punched } from "./lattice";
+export type { TrayFacts, TrayFluxState, TrayPin } from "./flux";
+export type { TrayLaid } from "./pass";

package/dist/types/packages/desk/src/tray/lattice.d.ts

@@ -0,0 +1,71 @@
+/** The board in pitches (the research's unit, ≈ 20 mm): SKÅDIS-style vertical stadium holes, odd rows shifted half a pitch. */
+export declare const PEG: {
+    /** The stadium's radius and its straight half-length: a hole 0.26 × 0.66 of a pitch. */
+    readonly holeR: 0.13;
+    readonly holeHalf: 0.2;
+    /** The smooth-max fillet on the punched rims. */
+    readonly rimK: 0.018;
+    /**
+     * The hardboard's thickness, and its height off the mat: it LIES on it (design-018 §3 — the research's spacer and wall retired) —
+     * a 4 mm board on a hair of air, 0.13 pitch in all: the height the drawer's own lamp shadow is pushed by (8 px at the HOME lamp).
+     */
+    readonly thick: 0.1;
+    readonly gap: 0.03;
+    /** The phase (§6.1): holes at x = c + ¼ + ½·(r odd) from the drawer's left edge, rows at Y = r + ¾ below its top at scroll 0. */
+    readonly colPhase: 0.25;
+    readonly rowPhase: 0.75;
+    /**
+     * The solid BORDER along the sides (D-K3.1): a hole is punched only where its centre lies this far from both — as a manufactured
+     * board's is. (Across both parities the holes stand every ½ pitch, so no phase alone keeps them all clear of a sawn side.)
+     */
+    readonly border: 0.75;
+};
+/**
+ * The scroll's CARRY (§6.2): the shown scroll (CSS px, any size) split into whole ROWS — an integer the shader adds to its
+ * rows on screen in i32 — and the FRACTION of a row, the only part of the scroll that ever enters an f32.
+ */
+export declare function carry(scroll: number, pitch: number): {
+    readonly rowBase: number;
+    readonly frac: number;
+};
+/** A board point as the shader forms it: `x` in pitches, `R` the whole row of Y (an integer), `fy` ∈ [0,1) the rest. */
+export interface PegPoint {
+    readonly x: number;
+    readonly R: number;
+    readonly fy: number;
+}
+/** A point on screen, on the board: `y` CSS px below the drawer's top, under the carry — `R` = rowBase + ⌊ly⌋ in integers (the shader's `peg_point`). */
+export declare function pointAt(xPitches: number, yPx: number, pitch: number, c: {
+    readonly rowBase: number;
+    readonly frac: number;
+}): PegPoint;
+/** The hole nearest a board point — its row (the nearest row: a hole's half-height, 0.33, is under half a pitch), its column, and the point's offset from its centre. */
+export interface PegCell {
+    readonly row: number;
+    readonly col: number;
+    readonly odd: boolean;
+    readonly qx: number;
+    readonly qy: number;
+}
+/** The cell of a board point (the shader's `peg_hole`; half-up rounding throughout — WGSL's `round` ties to even, so neither side uses it). */
+export declare function cellOf(p: PegPoint): PegCell;
+/** Is the cell's hole punched on a board `width` pitches wide — its centre at least the border from both sides? (The shader's `peg_hole` answers the same.) */
+export declare function punched(cell: PegCell, width: number): boolean;
+/** The vertical stadium's signed distance at an offset from its centre, pitches: negative inside the hole. */
+export declare function holeSdf(qx: number, qy: number): number;
+/** The centre of hole (row, col), in board pitches (x from the left edge, Y from the top at scroll 0) — the stagger's law. */
+export declare function holeCentre(row: number, col: number): {
+    readonly x: number;
+    readonly y: number;
+};
+/**
+ * The TURNED lattice's cell of a board point (tray.wgsl `peg_rot`, the face's tone and grain): lattice coordinates M·(x, Y)·num/den with
+ * M = [[a, −b], [b, a]] an integer rotation and scale. The carried row splits R = den·Q + r, so Q's share (−b·num·Q, a·num·Q) is an
+ * exact integer and only the small rest is a float — the shader's f32 (`Math.fround`) — at any depth.
+ */
+export declare function rotCell(p: PegPoint, a: number, b: number, num: number, den: number): {
+    readonly u: number;
+    readonly v: number;
+    readonly fu: number;
+    readonly fv: number;
+};

package/dist/types/packages/desk/src/tray/layout.d.ts

@@ -0,0 +1,7 @@
+/** The tray's own block (tray.wgsl `t`). */
+export declare const TrayUniforms: import("../engine").StructDef<"depth" | "view" | "shadow" | "lamp" | "fade" | "edge" | "face" | "accessory" | "rect" | "shape" | "rowBase" | "frac" | "fp" | "dim" | "hole" | "room" | "faceSrgb" | "cavity" | "keepFace" | "keepFine" | "keepEdge">;
+/**
+ * One specimen's ACCESSORY (K5a — tray.wgsl `tray_accessory`): drawn with the board, one instance each, its quad the accessory and its
+ * shadow's reach. Screen CSS px throughout (the drawer's camera is zoom 1): the quad, the specimen's rect, up to four pegs' hole centres.
+ */
+export declare const TrayAccessoryStruct: import("../engine").StructDef<"kind" | "rect" | "box" | "pegs0" | "pegs1">;

package/dist/types/packages/desk/src/tray/look.d.ts

@@ -0,0 +1,29 @@
+import { type RGB } from "../theme";
+export declare const TRAY_LOOK: {
+    /** The tempered hardboard face — and the byte it is configured as (a flat, lit face is drawn at exactly this). */
+    readonly face: RGB;
+    readonly faceSrgb: RGB;
+    /** The paler, fuzzier punched edge: the face scaled by the research's edge/face ratio. */
+    readonly edge: RGB;
+    /** The room's light on the mat in a hole: at its edge, at its heart, over what width (pitches). */
+    readonly cavity: {
+        readonly edge: 0.9;
+        readonly heart: 1;
+        readonly width: 0.1;
+    };
+    /** The unit direction to the lamp in the board's frame (x right, y down, z toward the eye) — the research's HOME lamp, its y turned down. */
+    readonly lamp: readonly [number, number, number];
+    /** The lamp's angular radius, rad. */
+    readonly lampSize: 0.06;
+    /** K5a: the accessories' powder coat, linear; each accessory's standing-off (pitches); their shadows' strength. */
+    readonly accessory: RGB;
+    readonly accessoryHeight: {
+        readonly hook: 0.45;
+        readonly shelf: 0.6;
+        readonly clip: 0.3;
+        readonly rail: 0.4;
+    };
+    readonly accessoryShadow: 0.38;
+    /** K5a: a hovered specimen's lift — a share of its kind's hold. */
+    readonly hoverLift: 0.3;
+};

package/dist/types/packages/desk/src/tray/pass.d.ts

@@ -0,0 +1,96 @@
+import type { View } from "../lattice/lod";
+import type { GridConfig } from "../mat/grid";
+import { type MatFrame } from "../mat/layout";
+import type { MatPass } from "../kit/view";
+import type { GroundTheme } from "../theme";
+import { type DrawerRect } from "./drawer";
+import type { TrayShaders } from "./shaders";
+import { accessoryOf, type TrayCarriedFrame, type TraySpecimenFrame } from "./specimens";
+/** The tray this frame (the renderer's flux — design-017 §3): where the slide is, and the SHOWN scroll. */
+export interface TrayFrameInputs {
+    /** The slide as drawn: 0 closed (wholly off the view — nothing drawn) … 1 open. */
+    readonly p: number;
+    /** The SHOWN scroll — CSS px of board past its top, the band included; any size (its whole rows are carried on the CPU). */
+    readonly scroll: number;
+    /** K5a: the specimens this frame (tray/specimens.ts) — their accessories are the pass's, their pixels their kinds'; absent = none. */
+    readonly specimens?: readonly TraySpecimenFrame[];
+    /** K5b: what is CARRIED this frame (tray/carry.ts) — the lifted copy, a ghost growing out of it or shrinking home — over the drawer, whole. */
+    readonly carried?: readonly TrayCarriedFrame[];
+}
+/** What the last prepare laid (a rig's and a check's witness): the rect, the carry, the dim, the accessories' records (screen px). */
+export interface TrayLaid {
+    readonly rect: DrawerRect;
+    readonly rowBase: number;
+    readonly frac: number;
+    readonly dim: number;
+    readonly accessories: readonly ReturnType<typeof accessoryOf>[];
+}
+/** The hash texture's side: the noise tiles every 256 lattice cells (for a band of F per pitch, every 256/F pitches). */
+export declare const HASH_SIZE = 256;
+/**
+ * The PRE-GATHERED noise (design-017 §6.7), 256² rgba8 — each texel the four corners one value-noise lookup interpolates, so a band is
+ * ONE load: texel (i, j) holds the research's hash of lattice points (i, j), (i+1, j), (i, j+1), (i+1, j+1) (`pcg(i ^ pcg(j))`, its
+ * top 8 bits), wrapping at the side; each band reads it at its own offset. It tiles every 256 cells of a band's lattice.
+ */
+export declare function hashTexels(): Uint8Array<ArrayBuffer>;
+/** A band of F cycles per pitch at a footprint of `fp` pitches per device px: kept while a cycle spans ≥ 4 px, gone at 2 (tray.wgsl's fade). */
+export declare function keep(fp: number, F: number): number;
+export declare class TrayPass {
+    private readonly device;
+    private readonly mat;
+    private readonly pipeline;
+    /** K5a: the accessories' own fragment entry on the same layout (a branch in one entry slowed the board). */
+    private readonly accPipeline;
+    /** The VEIL (design-018 rev 5): the plain board laid over everything the drawer holds at its top — its own entries on the same layout. */
+    private readonly veilPipeline;
+    private readonly layout;
+    private readonly sampler;
+    private readonly trayBuf;
+    private readonly lightBuf;
+    private readonly hash;
+    private readonly tray;
+    private readonly light;
+    private readonly sentTray;
+    private readonly sentLight;
+    private sent;
+    /** The quads the last prepare laid: 0 while the drawer is shut (p 0) — then it draws nothing. */
+    private quads;
+    private group;
+    private boundAssets;
+    private last;
+    private acc;
+    private accBuf;
+    private accSent;
+    private accCount;
+    private constructor();
+    /** The pipeline on `format`, sampling `mat`'s blue noise (the root's: its assets are every slot's). */
+    static create(device: GPUDevice, format: GPUTextureFormat, src: TrayShaders, mat: MatPass): Promise<TrayPass>;
+    /**
+     * Lay the drawer out for this frame and upload what changed (before the frame's pass begins): the view, the theme's light, the
+     * root grid's grade, the frame's noise offset. Returns the quads that will draw: one (the view whole while it dims) — none while
+     * the drawer is shut (p 0: it and its shadows lie below the view — nothing is uploaded, nothing drawn; design-018 §5).
+     */
+    prepare(view: View & {
+        readonly dpr: number;
+    }, theme: GroundTheme, grid: GridConfig, frame: MatFrame | undefined, inputs: TrayFrameInputs): number;
+    /** The accessories' records to the GPU — grown by doubling, written only when their bytes moved (a drawer at rest costs no write). */
+    private layAccessories;
+    /** A block to the GPU only when its bytes moved since the last upload (a drawer at rest costs no write). */
+    private upload;
+    /** A pipeline and the group, bound (the group remade when the mat's assets or the accessories' buffer changed). */
+    private bind;
+    /**
+     * The drawer UNDER its specimens into the open pass — over everything drawn so far (the caller left the scissor on the whole view):
+     * the dim, the drawer's shadows, the board to its edge; then each specimen's accessory with its shadow on the board (K5a).
+     */
+    draw(pass: GPURenderPassEncoder): void;
+    /**
+     * THE VEIL (design-018 rev 5) — LAST, over everything the drawer holds (the caller left the scissor on the whole view): the plain board
+     * whole in the header and fading out over its ramp, so what hangs there and the holes behind it fade into the board together — a
+     * specimen never turns see-through over a hole. One quad.
+     */
+    drawVeil(pass: GPURenderPassEncoder): void;
+    /** What the last prepare laid (a rig's witness). */
+    get laid(): TrayLaid | null;
+    dispose(): void;
+}

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

@@ -0,0 +1,10 @@
+import type { ComposeOptions } from "../engine/shader";
+import { type ShaderText } from "../kit/wgsl";
+/** The tray's own shader files (the kit's pieces come by name). */
+export declare const TRAY_SHADER_FILES: {
+    readonly tray: "tray/tray.wgsl";
+    readonly trayPass: "tray/tray-pass.wgsl";
+};
+/** The tray pass's program: the kit's view · sdf · light, then the tray's record, module and entry. */
+export type TrayShaders = ComposeOptions;
+export declare function trayShaders(text: ShaderText): TrayShaders;

package/dist/types/packages/desk/src/tray/specimens.d.ts

@@ -0,0 +1,199 @@
+import { type TrayAccessory } from "../../../kernel/src/index";
+import type { GridConfig } from "../mat/grid";
+import type { Lamp } from "../mat/lamp";
+import type { SlotSet } from "../ground";
+import type { KindProgram } from "../kind";
+import type { ObjectKind } from "../kinds/world";
+import type { View } from "../lattice/lod";
+import type { PortalClip, Presentation } from "../nav/portal";
+import type { GroundTheme } from "../theme";
+import { type CarryPose } from "./carry";
+import { type DrawerRect } from "./drawer";
+/** A specimen as the renderer reads it — from the world (the reflector), or a still's scene (the oracle). */
+export interface TraySpecimen {
+    /** A stable key for the kind's persistent records (the world's entity; a still's index). */
+    readonly key: number;
+    readonly type: string;
+    readonly kind: ObjectKind;
+    /** The object's own size — the size its kind draws it at (the widget's `defaultSize`). */
+    readonly natural: {
+        readonly w: number;
+        readonly h: number;
+    };
+    /** Where it hangs, board px (x from the drawer's left edge, y down from the board's top at scroll 0): its `Position` and `Size`. */
+    readonly rect: {
+        readonly x: number;
+        readonly y: number;
+        readonly w: number;
+        readonly h: number;
+    };
+    readonly props: Readonly<Record<string, unknown>>;
+    /** Its hang's accessory and pegs (pitches from its hang point) — the entry's. */
+    readonly accessory: TrayAccessory;
+    readonly pegs: readonly (readonly [number, number])[];
+    readonly label: string;
+    /** K5b (D-K5b.3): its kind's desk state, when its entry draws it with it (`tray.local`) — the face that lives there. */
+    readonly local?: unknown;
+    /** A per-specimen asset (a still's committed raster — the oracle's; the product's writing pins its own). */
+    readonly asset?: unknown;
+}
+/** One specimen this frame: its kind's record under its own view block, where it is on screen, its accessory's pegs on screen, its tag. */
+export interface TraySpecimenFrame {
+    readonly type: string;
+    /** The kind's registry name, and the record its `record` made for this frame. */
+    readonly kind: string;
+    readonly record: unknown;
+    readonly key: number;
+    /** Its slot's camera: the drawer's, scaled about it. */
+    readonly view: View & {
+        readonly dpr: number;
+    };
+    readonly grid: GridConfig;
+    /** Its rect on screen, CSS px. */
+    readonly screen: {
+        readonly x0: number;
+        readonly y0: number;
+        readonly x1: number;
+        readonly y1: number;
+    };
+    /** Its OBJECT as drawn on screen (the kernel's fit inside the hang), CSS px (K5b — what a take grabs, where one put back lands). */
+    readonly object: {
+        readonly x0: number;
+        readonly y0: number;
+        readonly x1: number;
+        readonly y1: number;
+    };
+    /** Its pegs' hole centres on screen, CSS px. */
+    readonly pegs: readonly (readonly [number, number])[];
+    readonly accessory: TrayAccessory;
+    readonly label: string;
+}
+/** The drawer this frame, as its flux drew it: the rect and the SHOWN scroll (the band in it). */
+export interface TrayDrawn {
+    readonly rect: DrawerRect;
+    readonly scroll: number;
+}
+/** What building the frames needs of the desk: the view, the theme, the root's grid, the kinds' looks, each specimen's hover lift (0 … 1). */
+export interface TraySpecimenEnv {
+    readonly view: {
+        readonly width: number;
+        readonly height: number;
+        readonly dpr: number;
+    };
+    readonly theme: GroundTheme;
+    readonly grid: GridConfig;
+    readonly looks: ReadonlyMap<string, unknown>;
+    readonly lift: (type: string) => number;
+}
+/**
+ * The FACE the specimens show through: the outline inside the board's edge (the arris — design-018 §2: nothing hangs over it), its foot
+ * past the view's, its top the HEADER's foot (design-018 R4: `DRAWER.header` under the edge, where nothing of them shows — the bar's
+ * chips lie there) — with NO feather (design-018 rev 5): a specimen is opaque to the clip's top, and the VEIL (tray.wgsl `tray_veil`)
+ * lays the plain board over it there — whole in the header, fading out over `DRAWER.fade` — so it fades into the board and never
+ * turns see-through over a hole (R1–R4's feather let the holes show through it). (Its top corners keep the arris's inner radius, under
+ * the veil's whole.)
+ */
+export declare function faceClip(rect: DrawerRect, vh: number): PortalClip;
+/** The tray's grid: the root's with no gobo dapple (D-K3.6 — the drawer lies above the desk; the wind would wake it). */
+export declare function trayGrid(grid: GridConfig): GridConfig;
+/**
+ * The specimens this frame: each culled where it cannot show (its rect and its reach outside the face), else resolved and recorded by
+ * its OWN kind — its object at its natural size, centred on its world origin, under the drawer's camera scaled about it — with the
+ * board's lamp, the tray's grid, the kind's look, its hover (the kinds' `lift`, a share of the hold's, and `hover`), no local and no
+ * asset (a specimen writes nothing into a kind's state on the desk) — unless its entry draws it with its kind's desk state (K5b, D-K5b.3:
+ * `tray.local` — a note's writing, a print's pictures), whose records the reflector lets go of as the specimen goes.
+ */
+export declare function specimenFrames(specimens: readonly TraySpecimen[], drawn: TrayDrawn, env: TraySpecimenEnv): TraySpecimenFrame[];
+/** The accessories' numbers (theme.ts `TRAY.accessory`): the kind index the shader reads, each's standing-off in pitches. */
+export declare const ACCESSORY_INDEX: Readonly<Record<TrayAccessory, number>>;
+/**
+ * One specimen's accessory record (tray.wgsl `TrayAccessory`), screen CSS px: its quad the ACCESSORY's own parts — the plugs and what they
+ * hold, a shelf's plank, a rail's bar, never the specimen's body between — grown by the shadow's push and blur (down and right, away
+ * from the lamp) and a pixel.
+ */
+export declare function accessoryOf(f: TraySpecimenFrame): {
+    readonly box: number[];
+    readonly kind: number[];
+    readonly rect: number[];
+    readonly pegs0: number[];
+    readonly pegs1: number[];
+};
+/** A carried object this frame (K5b — tray/carry.ts): its kind's record under its pose's view, the slot it is drawn in, where it is on screen. */
+export interface TrayCarriedFrame {
+    /** Its slot's key in `TraySlots` — one per type, apart from the specimens' (a copy and its specimen draw in the same frame). */
+    readonly slot: string;
+    readonly type: string;
+    readonly kind: string;
+    readonly record: unknown;
+    readonly key: number;
+    readonly view: View & {
+        readonly dpr: number;
+    };
+    readonly grid: GridConfig;
+    readonly phase: CarryPose["phase"];
+    /** The insert ghost it presents (absent: the lifted copy). */
+    readonly ghost?: number;
+    /** Its object's rect on screen, CSS px. */
+    readonly screen: {
+        readonly x0: number;
+        readonly y0: number;
+        readonly x1: number;
+        readonly y1: number;
+    };
+}
+/** What a carried pose is drawn from: its kind, its rect in its own units (the world's for a ghost — top-left; its natural size about the origin for a copy), its props, its key, the desk's lamp in those units, the kind's desk state. */
+export interface TrayCarriedSource {
+    readonly kind: ObjectKind;
+    readonly rect: {
+        readonly x: number;
+        readonly y: number;
+        readonly w: number;
+        readonly h: number;
+    };
+    readonly props: Readonly<Record<string, unknown>>;
+    readonly key: number;
+    readonly lamp: Lamp;
+    readonly local?: unknown;
+}
+/** The slot a carried type draws in. */
+export declare const carrySlot: (type: string) => string;
+/**
+ * A carried pose as its kind records it: its view (`carryView` — the object's grab point at the pose's pivot, at its scale), the tray's
+ * grid (no dapple: it lies above the desk, D-K3.6), the pose's lift, the desk's lamp where the object is — so the copy lifted off the
+ * board and the ghost it becomes are lit alike, and coincide at the hand-off.
+ */
+export declare function carriedFrame(pose: CarryPose, src: TrayCarriedSource, env: Omit<TraySpecimenEnv, "lift">): TrayCarriedFrame;
+/** The presentation every specimen's slot is drawn through: whole, clipped to the face. */
+export declare function facePresent(drawn: TrayDrawn, vh: number): Presentation;
+/**
+ * THE TRAY'S SLOTS (the GPU half): one per specimen type, each its own view block (the mat spawned from the root's — K-L3) and its kind's
+ * pass: SPAWNED from the root's (its buffers on the shared pipelines), or — a composite kind, root only by D-D18 (its spawned pass draws
+ * nothing) — made from the kind's program on the slot's mat, once, the first time the tray shows one (`warm`; async, so the specimen
+ * shows from the frame after it is made — `onReady` asks for that frame). Freed with the ground.
+ */
+export declare class TraySlots {
+    private readonly device;
+    private readonly format;
+    private readonly root;
+    private readonly programs;
+    private readonly slots;
+    private readonly making;
+    private disposed;
+    constructor(device: GPUDevice, format: GPUTextureFormat, root: SlotSet, programs: readonly KindProgram[]);
+    /** The slot of a specimen `type` of kind `kind`: spawned at once for a kind that spawns; undefined while a composite kind's pass is made. */
+    get(type: string, kind: string): SlotSet | undefined;
+    /** Make the passes of the composite kinds among `wanted` ([type, kind]) not made yet; `onReady` when each is (a frame is due). */
+    warm(wanted: readonly (readonly [string, string])[], onReady: () => void): void;
+    /** Every composite kind's pass among `wanted`, made now — a still's host (the oracle) waits for them. */
+    ready(wanted: readonly (readonly [string, string])[]): Promise<void>;
+    /**
+     * Each slot's passes let go of what they make again at their next draw when none of their objects was drawn within `ms` (D-K6a.3
+     * — the notebook's and the calendar's layers, a few seconds after the drawer shuts); asked every tick, drawing or not.
+     */
+    idle(ms?: number): void;
+    /** When `idle` next lets a layer go — the soonest slot's (K7a: the host's registered time wake); ∞ — nothing to let go. */
+    idleAt(ms?: number): number;
+    /** The slots made so far (a rig's witness). */
+    get size(): number;
+    dispose(): void;
+}

package/dist/types/packages/devtools/src/attach.d.ts

@@ -20,7 +20,22 @@
  *                   `lastFrame()` telemetry (one frame late by construction:
  *                   publish runs before this frame's reflect).
  *
- * By default all three tools mount into ONE draggable dock (dock.ts —
+ *   GPU SLOT        (design-016 K2) the WebGPU desk's frames — the GPU span,
+ *                   its passes, draws by kind, pipelines, bind groups,
+ *                   uploads, memory — pushed by the host through `gpuFrame`
+ *                   as the STRUCTURAL MIRROR `GpuPanelFrame` (gpu-panel.ts:
+ *                   devtools cannot import desk; the old GlPanelStats way),
+ *                   mounted at once when configured (`gpu: {…}`), else on
+ *                   the first push; each push also reports the
+ *                   host LANES `desk flush`, `encode` and `gpu` beside
+ *                   strata's per-system lanes. They are readings side by
+ *                   side, not a partition: `desk flush` runs inside `reflect`,
+ *                   `encode` inside `desk flush`, and `gpu` on the GPU, in
+ *                   parallel with the next frame's CPU — and a frame's GPU
+ *                   span lands a frame or two late (its timestamps are read
+ *                   back asynchronously), in the frame the report arrives.
+ *
+ * By default all the tools mount into ONE draggable dock (dock.ts —
  * 2026-07-13, James: "make the 3 tools into one draggable panel"); pass
  * `dock: false` for the classic scattered corners.
  *
@@ -30,7 +45,7 @@
 import type { Entity, World } from "@vibecook/strata-ecs";
 import { type DescribeFn, type EntityDescription, type ObserverHandle, type ObserverOptions, type ProfilerHandle, type ProfilerOptions } from "@vibecook/strata-ecs/tools";
 import { type DockOptions } from "./dock";
-import { type GlPanelOptions, type GlPanelStats } from "./gl-panel";
+import { type GpuPanelFrame, type GpuPanelOptions, type GpuPanelStats } from "./gpu-panel";
 import { type CanvasEngine, type Engine, type PresenceSession } from "../../core/src/index";
 export interface DevtoolsOpts {
     /** Where the dock (or, with `dock: false`, each panel) mounts (default: document.body). */
@@ -45,10 +60,10 @@ export interface DevtoolsOpts {
     readonly observer?: boolean | Pick<ObserverOptions, "defaultTab" | "tab" | "recorderCap">;
     /** Profiler HUD: `false` to omit, or strata passthrough options. */
     readonly profiler?: boolean | Pick<ProfilerOptions, "budgetMs" | "windowSize" | "corner" | "expanded" | "lanes">;
-    /** GL metrics panel: `false` to omit, or placement/budget options. Mounts lazily on the first `glStats` push. */
-    readonly glPanel?: boolean | Pick<GlPanelOptions, "corner" | "budgetMs" | "expanded">;
     /** Collab demos: the presence session whose store feeds the ephemeral tab. */
     readonly presence?: () => PresenceSession | null | undefined;
+    /** The GPU slot (K2): `false` to omit, or its options (budget, expanded, the host's capture) — given as an object it mounts at once (saying it waits for a frame); otherwise on the first `gpuFrame` push. */
+    readonly gpu?: boolean | Pick<GpuPanelOptions, "budgetMs" | "expanded" | "capture" | "captureFrames">;
     /** Override entity labeling (default: the engine describe below). */
     readonly describe?: DescribeFn;
 }
@@ -58,11 +73,10 @@ export interface DevtoolsHandle {
     /** Host-cost lane passthrough (paint, decode…); no-op when the profiler is off. */
     lane(name: string, ms: number): void;
     /**
-     * Feed one GL frame's metrics (wire `<GLViews onFrameStats>` here). The GL
-     * panel mounts on the first push — renderer counts, virtual-texture census,
-     * LOD banding, cull population. No-op when opts.glPanel === false.
+     * Feed one GPU frame (K2 — wire the desk's GPU profiler here: `profiler.subscribe((r) => devtools.gpuFrame(r, profiler.stats()))`).
+     * Mounts the GPU slot on the first push and reports the host lanes `desk flush` / `encode` / `gpu`. No-op when `gpu: false`.
      */
-    glStats(stats: GlPanelStats): void;
+    gpuFrame(frame: GpuPanelFrame, stats?: GpuPanelStats): void;
     /** Tear all panels + the telemetry hook down. Idempotent. */
     detach(): void;
 }