@vibecook/ice 0.11.0 → 0.15.0-desk.1

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

@@ -0,0 +1,83 @@
+import type { FadeIn, View } from "../lattice/lod";
+import type { Presentation } from "../nav/portal";
+import { type GlyphAtlasMeta, type MatConfig, type MatFrame, type PlateName, type SlotLight } from "./layout";
+import { type MatLight } from "./night";
+import type { MatPass } from "../kit/view";
+import type { MatShaders } from "./shaders";
+export declare class CuttingMat implements MatPass {
+    readonly name = "mat/mat";
+    private readonly uniforms;
+    private readonly uniformBuf;
+    /** The wind target this slot samples: its plate's shared one, or its own (`own`) after a clash in one frame. */
+    private wind;
+    /** This slot's own wind target, made only when two keys meet on one plate in one frame. */
+    private own;
+    private windGroups;
+    private matGroup;
+    private bound;
+    private boundWind;
+    /** Turns over whenever this slot's bind groups are made again — a shared asset landed, or the slot samples another silhouette. */
+    private assets;
+    private windRuns;
+    /** The view block as last uploaded (K7a: uploaded only when its bytes moved; a layered kind compares a layer's view by it). */
+    private readonly sentView;
+    private viewSent;
+    private readonly device;
+    private readonly shared;
+    private constructor();
+    static create(device: GPUDevice, format: GPUTextureFormat, src: MatShaders): Promise<CuttingMat>;
+    /** A second slot on the same pipelines and plates — a flight's departed mat, a mini mat's inside. */
+    spawn(): CuttingMat;
+    /** Which assets a host has uploaded — stats, and the lab's boot line. Shared by every slot. */
+    get loaded(): {
+        readonly c: boolean;
+        readonly b: boolean;
+        readonly noise: boolean;
+        readonly glyphs: boolean;
+    };
+    /** What the pass knows about the glyph atlas it samples (RULER.md). */
+    get glyphs(): GlyphAtlasMeta;
+    /** This slot's animated silhouette — the wind target the mat samples; the paper pass (STICKY.md) samples the same, so a note takes the mat's dapple. */
+    get silhouette(): GPUTextureView;
+    /** The slot's ONE VIEW BLOCK (K4a, design-016 K-L3): the uniforms this mat writes once a frame, which every kind in the slot binds. */
+    get view(): GPUBuffer;
+    /** The glyph atlas as uploaded (a 1×1 empty cell until a host uploads one) — the mini mat pass prints with it. */
+    get glyphTexture(): GPUTexture;
+    /** The shared blue noise, as uploaded (a 1×1 grey until a host uploads the tile). */
+    get noiseTexture(): GPUTexture;
+    /** Bumped whenever a shared asset lands or the slot samples another silhouette — a pass that binds them rebinds on a change. */
+    get assetVersion(): number;
+    get viewBytes(): Uint8Array;
+    get silhouetteKey(): number;
+    /** A new frame (the ground's `prepareFrame`, before its slots prepare): a wind key drawn before it may be drawn over. */
+    newFrame(): void;
+    /** A plate's shared wind target, made on first use. */
+    private windOf;
+    private upload;
+    /** (Re)build this slot's bind groups against the shared assets' current version. */
+    private rebind;
+    /** A 512×512 rgba8 plate: R silhouette, G wind amp 1, B phase, A amps 2+3 (assets/gobo-*.rgba). Every slot samples it. */
+    setPlate(name: PlateName, bytes: Uint8Array<ArrayBuffer>): void;
+    /** The 128×128 rgba8 blue-noise tile (assets/blue-noise.rgba). Every slot samples it. */
+    setNoise(bytes: Uint8Array<ArrayBuffer>): void;
+    /**
+     * The glyph atlas (RULER.md): r8 coverage, `meta.width × meta.height` texels, the
+     * first `meta.count` glyphs of `GLYPHS` in a row of `meta.cellW` cells — at least the
+     * rulers' twelve; the capitals after them print a mini mat's name (MINIMAT.md §2).
+     * Every slot samples it (the mini mat pass too); a host re-uploads when the device's
+     * ratio or the text size changes.
+     */
+    setGlyphs(bytes: Uint8Array<ArrayBuffer>, meta: GlyphAtlasMeta): void;
+    get windPasses(): number;
+    /**
+     * Upload the uniforms (under `light` — the theme's Sun or Moon, mat/night.ts — through the lamp `lit`
+     * says: the slot's own when absent, the host desk's for a mini mat's inside, MINIMAT.md §4); run the
+     * wind pass if the silhouette it holds is stale. Returns whether it ran.
+     */
+    prepare(encoder: GPUCommandEncoder, view: View & {
+        readonly dpr: number;
+    }, fadeIn: FadeIn, cfg: MatConfig, frame: MatFrame, present?: Presentation, light?: MatLight, lit?: SlotLight): boolean;
+    draw(pass: GPURenderPassEncoder): void;
+    /** This slot's buffers; the shared plates go with the last slot standing. */
+    dispose(): void;
+}

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/missing/layout.d.ts

@@ -0,0 +1,27 @@
+import type { ObjectRect } from "../kinds/world";
+import { type GroundTheme, type RGB } from "../theme";
+/** The face's record as the pass's WGSL reads it (shaders/missing/missing-pass.wgsl). */
+export declare const MissingFace: import("../engine").StructDef<"rect" | "ink" | "shape" | "mix">;
+/** What the missing face draws for one object: its box, its ink and its fade. `missing` brands it — the pass draws nothing else. */
+export interface MissingRecord {
+    readonly missing: true;
+    readonly cx: number;
+    readonly cy: number;
+    readonly hx: number;
+    readonly hy: number;
+    readonly ink: RGB;
+    readonly fade: number;
+}
+/** Is this record the missing face's? (A kind's own record handed to its missing pass — the frame before a quarantine took — is not.) */
+export declare const isMissingRecord: (r: unknown) => r is MissingRecord;
+/** The face of an object whose box is `rect` (centred, world units) under `theme`, at `fade` (1 whole … 0 gone). */
+export declare function missingFace(rect: ObjectRect, theme: Pick<GroundTheme, "name">, fade?: number): MissingRecord;
+/** The record's values by field — a record that is not the face's packs as nothing (fade 0: the vertex stage collapses it). */
+export declare function missingValues(r: unknown): {
+    rect: number[];
+    ink: number[];
+    mix: number[];
+    shape: number[];
+};
+/** The face's pick: the object itself (`content` — a tap selects it, a drag moves it) anywhere in its box; else a miss. */
+export declare function missingHit(g: ObjectRect, wx: number, wy: number): "content" | null;

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

@@ -0,0 +1,6 @@
+import type { ObjectKind, ObjectRect } from "../kinds/world";
+import { type MissingRecord } from "./layout";
+/** The name an object whose type has no kind is drawn under (a kind may not take it — ground.ts). */
+export declare const MISSING_KIND = "desk.missing";
+/** The missing face's kind: its program (the ground's own — never registered) and its world half. */
+export declare const MISSING_OBJECT: ObjectKind<ObjectRect, MissingRecord>;

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

@@ -0,0 +1,39 @@
+import { type RecordStoreStats } from "../engine/records";
+import type { KindExtra, KindPass, SlotContext } from "../kind";
+import type { MatPass } from "../kit/view";
+import type { ShaderText } from "../shaders";
+export declare class MissingPass implements KindPass<unknown> {
+    readonly name = "desk/missing";
+    private store;
+    private group;
+    private boundStore;
+    private boundAssets;
+    private count;
+    private readonly device;
+    private readonly shared;
+    private readonly mat;
+    private constructor();
+    /**
+     * The root's pass on `mat`, made NOW (no await — a quarantine asks for it mid-frame): its layout and its one pipeline (it is lit by
+     * nothing — the same in every slot). The desk's own WGSL, composed from the host's text; WebGPU compiles it before its first draw.
+     */
+    static make(device: GPUDevice, format: GPUTextureFormat, mat: MatPass, text?: ShaderText): MissingPass;
+    /** A slot's own faces on the shared pipeline, through `mat`'s view block. */
+    spawn(mat: MatPass): MissingPass;
+    prepare(_encoder: GPUCommandEncoder, _slot: SlotContext, records: readonly unknown[], extra?: KindExtra): number;
+    private rebind;
+    drawRange(pass: GPURenderPassEncoder, first: number, end: number): void;
+    /** The store's counters (a rig's witness) — nothing until the slot's first face. */
+    records(): RecordStoreStats;
+    dispose(): void;
+}
+/** A desk's missing faces (petition I24): a slot's own on its mat, at its first ask — the pipeline made at the desk's first. */
+export interface MissingFaces {
+    /** A slot's faces on `mat` (the desk's pipeline made now if this is the first). */
+    spawn(mat: MatPass): KindPass;
+    /** Has the desk made its pipeline (a face was ever asked for)? */
+    readonly made: boolean;
+    dispose(): void;
+}
+/** The missing faces of a desk on `device` — nothing made until the first `spawn` (then the pipeline, on the root's `mat`). */
+export declare function missingFaces(device: GPUDevice, format: GPUTextureFormat, mat: MatPass, text?: ShaderText): MissingFaces;

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

@@ -0,0 +1,7 @@
+import type { ComposeOptions } from "../engine/shader";
+import { type ShaderText } from "../shaders";
+export declare const MISSING_SHADER_FILES: {
+    readonly entry: "missing/missing-pass.wgsl";
+};
+/** The missing face's program for a host's shader text (default: the desk's generated module). */
+export declare function missingShaders(text?: ShaderText): ComposeOptions;

package/dist/types/packages/desk/src/missing/slots.d.ts

@@ -0,0 +1,8 @@
+import type { KindPass } from "../kind";
+import type { SlotSet } from "../ground";
+import type { MissingFaces } from "./pass";
+/**
+ * Kind `name`'s entry in `s` becomes the desk's missing faces on the slot's mat (`faces` — the root's), under the kind's name and
+ * stratum. Returns the pass the entry held (the caller lets it go), or undefined when the slot holds no such kind, or the desk no faces.
+ */
+export declare function swapToMissing(s: SlotSet, name: string, faces: MissingFaces | undefined): KindPass | undefined;

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];