@vibecook/ice 0.11.0 → 0.14.0

package/dist/types/packages/objects/src/photo/carry.d.ts

@@ -0,0 +1,33 @@
+import { type Component, type Entity, type World } from "../../../core/src/index";
+import type { Prints } from "./kind";
+import { type TypingDocs } from "../../../desk/src/index";
+export interface PhotoCarryOptions {
+    readonly world: World;
+    /** The document a rest commits into — the facade's `engine.docs`. */
+    readonly docs: TypingDocs;
+    /** The print's props cell (its `angle`) — the object hands its own (D-D7-A.3); absent, a rest commits no turn. */
+    readonly props?: Component | undefined;
+    /** The photo kind's state on this desk (undefined before it is made). */
+    readonly prints: () => Prints | undefined;
+    /** Is this entity a print (the desk's builder knows each entity's kind). */
+    readonly isPrint: (e: Entity) => boolean;
+    /** Where a rest's transaction runs: out of the frame (a microtask) unless a test says. */
+    readonly defer?: (fn: () => void) => void;
+    /** A press on a TAPED print became a drag (the recognizer Active): not carried — told once a gesture, so the desk's marks give it (D4a). */
+    readonly refused?: (e: Entity) => void;
+}
+export interface PhotoCarry {
+    /** Nothing to follow (D7 #14): no print in a hand, no press on the desk, no rest owed by the kind. */
+    idle(): boolean;
+    /** Once a frame, before the kinds' clocks: the hands onto the bodies, and last frame's rests into their transactions. */
+    follow(now: number): void;
+    /** The prints in a hand now. */
+    held(): readonly Entity[];
+    /** Carries cancelled since creation (a rig's witness). */
+    cancels(): number;
+    /** Transactions committed since creation (a rig's witness). */
+    commits(): number;
+}
+/** The lab's wheel: a wheel unit turns a held print by this many radians (lab/photo.ts). */
+export declare const TWIST_PER_WHEEL = 0.0035;
+export declare function createPhotoCarry(opts: PhotoCarryOptions): PhotoCarry;

package/dist/types/packages/objects/src/photo/kind.d.ts

@@ -0,0 +1,136 @@
+import type { Entity } from "../../../core/src/index";
+import { type KindExtra, type KindPass, type KindProgram, type SlotContext, type KindHost, type KindLocal, type ObjectContext, type ObjectKind, type ObjectRect } from "../../../desk/src/index";
+import { type MarkFrame, type MatPass, type ShaderText } from "../../../desk/src/kit/index";
+import { type PhotoBody, type PhotoGeometry, type PhotoLaw } from "./photo";
+import { type Picture, type PhotoInstance, PhotoPass } from "./photo-pass";
+import type { PictureStats } from "./pictures";
+/** The print's kind name — its key in the registry and in every slot's `objects`. */
+export declare const PHOTO_KIND = "photo";
+export declare class PhotoKind implements KindPass<PhotoInstance> {
+    /** The photo pass itself: a host's door to the pictures (`picture`, `pictureFrom`, `dropPicture`) and the print's law (`law`). */
+    readonly pass: PhotoPass;
+    constructor(pass: PhotoPass);
+    spawn(mat: MatPass): PhotoKind;
+    tune(root: KindPass<PhotoInstance>): void;
+    /** The pass's own `prepare`, argument for argument: the slot's camera, grid, clocks, the objects' presence, the light, the lamp — and the records' keys (D6). */
+    prepare(_encoder: GPUCommandEncoder, s: SlotContext, records: readonly PhotoInstance[], extra?: KindExtra): number;
+    dropped(): number;
+    /** Records [first, end) — indices into the prints `prepare` was handed, each drawn with its picture. */
+    drawRange(pass: GPURenderPassEncoder, first: number, end: number): void;
+    records(): import("../../../desk/src/index").RecordStoreStats;
+    cardResources(): {
+        readonly version: number;
+        readonly resources: readonly (GPUBuffer | GPUTextureView | GPUSampler)[];
+    };
+    cardSlot(index: number): number;
+    dispose(): void;
+}
+/** The print's program for a host's shader text: its pass made on the root's mat. */
+export declare function photoProgram(text: ShaderText): KindProgram<PhotoInstance>;
+/** The print's silhouette for the desk's marks (D4a): the sheet's own axes on the desk plane (its height's parallax aside), its corner. */
+export declare function photoFrame(G: PhotoGeometry): MarkFrame;
+/** A print's extent on the desk, world units: its picture's aspect at the law's long side (the lab's `addPicture`); 3:2 without one. */
+export declare const printExtent: (width: number, height: number, long?: number) => {
+    readonly w: number;
+    readonly h: number;
+};
+/**
+ * How far a print's drawing reaches past its rect, world units: the leave's height (1.6 × the lift) and the held droop cast
+ * along the lamp's capped slope and blurred, and the local eye's scale of a sheet at that height about its far corner.
+ */
+export declare function photoReach(law?: PhotoLaw): number;
+/** A print's pose as a still pins it (a FLUX pin, never a Grab — D-D2a-world.5): its height, slope, bend, anchor and the hand holding it. */
+export interface PhotoPose {
+    readonly h?: number;
+    readonly sx?: number;
+    readonly sy?: number;
+    readonly bend?: number;
+    readonly ax?: number;
+    readonly ay?: number;
+    readonly hold?: {
+        readonly gx: number;
+        readonly gy: number;
+        readonly px: number;
+        readonly py: number;
+    };
+}
+/** A print that came to rest where its facts are not — ONE transaction's worth for the carry: its centre, world units, and its turn (the wheel twists a carried print, D3t-a). */
+export interface PrintRest {
+    readonly entity: Entity;
+    readonly x: number;
+    readonly y: number;
+    readonly angle: number;
+}
+/** A flick's witness: the body as the hand let it go, and every step the desk took with it since (the law replays them). */
+export interface FlickWitness {
+    readonly body: PhotoBody;
+    readonly dts: number[];
+    landed: {
+        readonly x: number;
+        readonly y: number;
+    } | null;
+}
+/** The photo kind's own state on one desk: the prints' bodies, their pictures, the carry's door. */
+export interface Prints extends KindLocal {
+    /** When the kind is next live (K7a — `KindLocal.due`, declared: the six built-ins all say). */
+    due(now: number): number;
+    /** The hand takes print `e` at a world point (the carry); a body at rest is lifted off its facts. */
+    hold(e: Entity, wx: number, wy: number, t: number): void;
+    /** The hand moved (world, t seconds) — the grab point follows it exactly. */
+    move(e: Entity, wx: number, wy: number, t: number): void;
+    /** The hand let go: the flick from the last 70 ms, capped; the body glides from here. */
+    drop(e: Entity, t: number): void;
+    /**
+     * The carry was CANCELLED (Esc — D3t-a): the hand lets go and the print flies back to where it began — its facts, its turn —
+     * in `PRINT_RETURN_MS` on the island ease, landing there; nothing is committed.
+     */
+    cancel(e: Entity, t: number): void;
+    /** The wheel turns a carried print about the finger (PHOTO.md), radians; a print in the air takes it as spin. */
+    twist(e: Entity, da: number): void;
+    /** The print is drawn LIFTED — in a hand, in the air, flying home, its rest not yet in the facts (the builder paints it on top). */
+    lifted(e: Entity): boolean;
+    /** Prints that came to rest away from their facts since the last ask — the carry commits each in ONE transaction. */
+    rests(): PrintRest[];
+    /** How many rests wait to be asked for (D7 #14: the carry never idles over one). */
+    owed(): number;
+    /** The carry committed `e`'s rest (or could not): the body leads until the facts show it (or a second runs out). */
+    settle(e: Entity, committed: boolean): void;
+    /** A still's pose on `e` (undefined unpins). */
+    pin(e: Entity, pose: PhotoPose | undefined): void;
+    /** A print just laid by a paste or a drop arrives: it falls from `arrive` onto its place and fades in (PHOTO.md §3). */
+    arrive(e: Entity): void;
+    /** Fetch, decode and upload a blob's picture before a print names it (a scene's still); resolves once it is on the device. */
+    preload(hash: string, width: number, height: number): Promise<void>;
+    /** Print `e`'s body as it is now — a copy (a rig's witness); undefined for a print never met. */
+    body(e: Entity): PhotoBody | undefined;
+    /** The last flick of print `e` — a copy. */
+    flick(e: Entity): FlickWitness | undefined;
+    /** The pictures: on the device, on their way, missing from the store or undecodable — and where they are resident (K6a: thumbnails, details, slots). */
+    pictures(): {
+        readonly ready: number;
+        readonly loading: number;
+        readonly failed: number;
+        readonly resident?: PictureStats;
+    };
+    /** The world half's: the body to resolve for this frame (the facts at rest, the live body while it leads). */
+    bodyFor(ctx: ObjectContext, hx: number, hy: number): PhotoBody;
+    /** The world half's: the picture a print's `blob` names (null while it loads, or without one). */
+    pictureFor(e: Entity, hash: string, width: number, height: number): Picture | null;
+}
+/** A cancelled carry's flight home, ms (D3t-a) — the put-down's own length (design-015 §8: 440 ms home), on the hand's island ease. */
+export declare const PRINT_RETURN_MS = 440;
+/** The photo kind's `local()` on one desk. */
+export declare function createPrints(host: KindHost, law?: PhotoLaw): Prints;
+export interface PhotoKindOptions {
+    /** The host's shader text; the generated module unless a host says. */
+    readonly text?: ShaderText;
+    /** The print's numbers (photo.ts `PHOTO`) — the engine's unless a host tweaks them. */
+    readonly law?: PhotoLaw;
+}
+/** The print's kind, whole (kinds/world.ts `ObjectKind`): the program, and the world half on the photo lab's body. */
+export declare function photoKind(opts?: PhotoKindOptions): ObjectKind<PhotoGeometry, PhotoInstance>;
+/** The rect a print lies in at rest, for a host that places one by its centre: top-left and the f32 size the world stores. */
+export declare function printRect(cx: number, cy: number, width: number, height: number, long?: number): ObjectRect & {
+    readonly x: number;
+    readonly y: number;
+};

package/dist/types/packages/objects/src/photo/layout.d.ts

@@ -0,0 +1,39 @@
+import { type PhotoGeometry, type PhotoLaw } from "./photo";
+export declare const Photo: import("../../../desk/src/engine/index").StructDef<"eye" | "light" | "tier" | "n" | "bounds" | "centre" | "slope" | "bend" | "ex" | "ey" | "image">;
+export declare const PhotoUniforms: import("../../../desk/src/engine/index").StructDef<"paper" | "night" | "gloss" | "penumbra" | "contact" | "shade">;
+export declare const MAX_PHOTOS = 256;
+/** A picture as a record names it: its texels and chain, where its thumbnail lies, and its detail's slot while a frame binds one (pictures.ts `Picture`). */
+export interface PhotoPicture {
+    readonly width: number;
+    readonly height: number;
+    readonly mips: number;
+    readonly layer: number;
+    readonly base: number;
+    readonly slot: number;
+    readonly detail: {
+        readonly base: number;
+    } | null;
+}
+export declare function photoValues(G: PhotoGeometry, border: number, pic: PhotoPicture | null): {
+    centre: number[];
+    ex: number[];
+    ey: number[];
+    n: number[];
+    eye: number[];
+    bend: number[];
+    bounds: number[];
+    image: number[];
+    light: number[];
+    slope: number[];
+    tier: number[];
+};
+export declare function photoUniformValues(law?: PhotoLaw): {
+    shade: number[];
+    paper: number[];
+    penumbra: number[];
+    contact: number[];
+    gloss: number[];
+    night: number[];
+};
+/** The border's width in world units for a print of half extents `hx × hy`. */
+export declare const borderOf: (hx: number, hy: number, law?: PhotoLaw) => number;

package/dist/types/packages/objects/src/photo/object.d.ts

@@ -0,0 +1,5 @@
+import { printExtent } from "./kind";
+/** The print's durable type id. */
+export declare const PHOTO_TYPE = "desk.photo";
+export { printExtent };
+export declare const Photo: import("../../../core/src/index").WidgetType;

package/dist/types/packages/objects/src/photo/photo-pass.d.ts

@@ -0,0 +1,104 @@
+import { type RasterBudget } from "../../../desk/src/index";
+import { type FadeIn, type View, type MatConfig, type MatFrame, type SlotLight, type MatPass, type Presentation, type MatLight } from "../../../desk/src/kit/index";
+import { type Picture, type PictureSource, type PictureStats } from "./pictures";
+import { type PhotoGeometry, type PhotoLaw } from "./photo";
+import type { PhotoShaders } from "./shaders";
+/** The largest side a picture keeps on the device — a 6×4 print at zoom 5 on a 2× screen. */
+export declare const PICTURE_MAX = 4096;
+export type { Picture } from "./pictures";
+/** One print for the pass: its resolved pose, its border's width, its picture. */
+export interface PhotoInstance {
+    readonly geometry: PhotoGeometry;
+    readonly border: number;
+    readonly picture: Picture | null;
+}
+export declare class PhotoPass {
+    readonly name = "photo/prints";
+    private readonly knobs;
+    /** The prints' PERSISTENT records (engine/records.ts, design-015 §4.3; D6): a slot per print while drawn, written when it changed. */
+    private readonly store;
+    /** The records the last prepare turned away at the pass's cap — not drawn; the ground reports them (`GroundStats.dropped`, D7). */
+    dropped: number;
+    private readonly knobBuf;
+    /** What the GPU holds of the knobs: they are written only when they change (K4a — a standing value costs a frame nothing). */
+    private readonly knobsSent;
+    private group;
+    private bound;
+    private boundStore;
+    /** This frame's prints, in the order `prepare` was handed them — what `drawRange` counts in. */
+    private count;
+    /** This frame's slot is lit from elsewhere: it draws with the second pipeline. */
+    private litElsewhere;
+    /** The print's numbers (photo.ts `PHOTO`) — a host tunes the root's copy; every slot takes it (`tune`). */
+    law: PhotoLaw;
+    private readonly device;
+    private readonly shared;
+    private readonly mat;
+    private constructor();
+    /** The root's pass, on the root's mat (its silhouette and noise). */
+    static create(device: GPUDevice, format: GPUTextureFormat, src: PhotoShaders, mat: MatPass): Promise<PhotoPass>;
+    /** A second slot on the same pipeline, samplers and pictures, reading ITS mat's silhouette and noise — a mini mat's inside, a flight's departed desk. */
+    spawn(mat: MatPass): PhotoPass;
+    /** Take the root's law — what every spawned slot does each frame. */
+    tune(from: PhotoPass): void;
+    private rebind;
+    /**
+     * A picture from raw sRGB rgba8 bytes (row 0 = top, straight alpha) — what a Node host or a test hands in. A picture is
+     * the PASS's resource, shared by every slot: a print's record names it by this handle (`PhotoInstance.picture`), and it
+     * lives until the host drops it (`dropPicture`). The bytes are kept (by reference) to make a detail from; null when the
+     * thumbnail array holds no more pictures (the device's layers — the print draws its paper alone).
+     */
+    picture(bytes: Uint8Array<ArrayBuffer>, width: number, height: number): Picture | null;
+    /**
+     * A picture from a decoded image (a pasted or dropped file, an `<img>`, a canvas) — the browser's path; `again` decodes it
+     * afresh for a print large on screen (its detail) — without it the picture keeps its thumbnail alone.
+     */
+    pictureFrom(source: ImageBitmap | HTMLCanvasElement | OffscreenCanvas | HTMLImageElement, width: number, height: number, again?: PictureSource): Picture | null;
+    /** A picture no print names any more: its layer given back, its detail destroyed. */
+    dropPicture(p: Picture): void;
+    /**
+     * THE RESIDENCY's frame boundary (pictures.ts `step` — the kind's tick, before the build): details bound, fetched, cut or let
+     * go for what the last frame's prints asked. True when a print's tier moved (the desk must draw again).
+     */
+    residency(): boolean;
+    /** The last frame's asks still unanswered (K7a): the next tick owes them a `residency` step — a detail fetched, a slot freed. */
+    get residencyOwed(): boolean;
+    /** The pictures under the desk's budget (the kind's host lends it) — and its ask of what stays. */
+    budget(budget: RasterBudget | undefined): void;
+    keeps(key: string): boolean;
+    /** A detail landed or was evicted (async): `wake` asks the desk for a frame. */
+    set onPictures(wake: () => void);
+    /** The pictures' counters (a rig's witness): thumbnails, details, slots, bytes. */
+    get pictureStats(): PictureStats;
+    /**
+     * Upload this frame's prints in paint order (first = lowest) and the mat's block for this slot's camera,
+     * its light (`light` the Sun or the Moon, `lit` the lamp it is seen by — MINIMAT.md §4): the dapple falls
+     * on the prints. Returns the count that will draw.
+     */
+    prepare(view: View & {
+        readonly dpr: number;
+    }, fadeIn: FadeIn, cfg: MatConfig, frame: MatFrame | undefined, prints: readonly PhotoInstance[], present?: Presentation, light?: MatLight, lit?: SlotLight, keys?: readonly number[], hand?: boolean): number;
+    /** The store's counters (a rig's witness): records written, bytes, draw-list writes, slots in use. */
+    get records(): import("../../../desk/src/index").RecordStoreStats;
+    /** K7b: record `index` of the last prepare drawn by the flat-card pipeline — its slot in the store — or −1: a detail is bound, the pass draws it. */
+    cardSlot(index: number): number;
+    private cards;
+    /** K7b: this slot's resources for the print's card material (shaders.ts `photoCard`), in its bindings' order — made again when the store or the thumbnails grew. */
+    cardResources(): {
+        readonly version: number;
+        readonly resources: readonly (GPUBuffer | GPUTextureView | GPUSampler)[];
+    };
+    private card;
+    private cardOver;
+    get drawn(): number;
+    /** Every print prepared this frame, into a pass the caller opened: `drawRange` over the whole list. */
+    draw(pass: GPURenderPassEncoder): void;
+    /**
+     * The prints `prepare` was handed at [first, end) — indices into ITS list, as the ground's runs count a kind's records —
+     * as ONE instanced draw (K6a, K-L4): the slot's group and the pictures' bound once, on the pipeline for the slot's light,
+     * each print an instance whose record says where its pixels are. An empty range records nothing, not even the pipeline.
+     */
+    drawRange(pass: GPURenderPassEncoder, first: number, end: number): void;
+    /** This slot's buffers; the pictures go with the last slot standing (a host's pictures are the host's to drop until then). */
+    dispose(): void;
+}

package/dist/types/packages/objects/src/photo/photo.d.ts

@@ -0,0 +1,262 @@
+import { type RGB } from "../../../desk/src/index";
+import { type Lamp } from "../../../desk/src/kit/index";
+/**
+ * The desk's ONE light: the mat's gobo projector as a lamp over the desk (paper.ts `lampOf` —
+ * world (1930, −826), 994 up), the same the notes and the notebooks are lit and shadowed by.
+ * Per print, the direction toward it from the print, and the shadow's ground slope away from
+ * it, capped at `PHYSICS.shadow.slopeMax` (a print far from the lamp keeps a finite shadow).
+ */
+export declare const LAMP: Lamp;
+/**
+ * The shadow's two terms: the PENUMBRA is the note's (kit/physics.ts `PHYSICS.shadow`: σ at contact, alpha
+ * resting, the slope's cap — one physics for every sheet on the desk; its growth and held alpha below) — and a
+ * tight CONTACT term at the base that fades as the sheet rises off the mat (gone by `reach`), as
+ * the notebook's slab has (the tree-shadow design system's `--lift-1`).
+ */
+export declare const DESK_SHADOW: {
+    readonly penumbra: {
+        readonly sigma0: 2.2;
+        readonly sigmaPerHeight: 0.36;
+        readonly alpha: 0.36;
+        readonly alphaHeld: 0.42;
+        readonly slopeMax: 2.2;
+    };
+    readonly contact: {
+        readonly alpha: 0.22;
+        readonly sigma: 1.1;
+        readonly reach: 2.5;
+    };
+};
+/** The colour a shadow casts ON the mat — theme.ts `MAT.cast` (the tree-shadow design system's `--cast-rgb`, "the world's darkest value"). */
+export declare const CAST: RGB;
+declare const PHOTO_SPEC: {
+    /** The print's long side — a 6×4 at the note's scale. */
+    readonly long: 400;
+    /** The white border, as a fraction of the short side (a classic bordered print). 0 = borderless. */
+    readonly border: 0.05;
+    /** The die-cut corner. */
+    readonly radius: 2.5;
+    /** The paper under the emulsion: a resin-coated white, a touch warm (sRGB), and its fibre ±/255. */
+    readonly paper: RGB;
+    readonly grain: number;
+    /** The local eye's height over the desk: at h the sheet reads eye/(eye − h) larger. */
+    readonly eye: 720;
+    /** How high a held sheet rides, and how far a hovered one rises (the edge lifting under the finger). */
+    readonly lift: 24;
+    readonly hover: 2.2;
+    /** Where a pasted print starts its fall from. */
+    readonly arrive: 70;
+    /** The height spring: rising under the hand, falling to the mat (Hz, ζ), and the landing's bounce (restitution; below this speed it just settles). */
+    readonly rise: {
+        readonly hz: 5.5;
+        readonly zeta: 0.82;
+    };
+    readonly fall: {
+        readonly hz: 3.6;
+        readonly zeta: 0.5;
+        readonly restitution: 0.18;
+        readonly settle: 30;
+    };
+    /**
+     * The tilt (the sheet's slope): toward the fingers while held (the far edge hangs lowest — degrees at
+     * the far corner), with the air while it moves (the leading edge rides up — degrees per 1000 u/s),
+     * never past `max`; a spring (Hz, ζ) so it wobbles once when the hand stops.
+     */
+    readonly tilt: {
+        readonly grab: 3;
+        readonly motion: 5;
+        readonly max: 12;
+        readonly hz: 3.2;
+        readonly zeta: 0.42;
+    };
+    /** The bend: a held sheet droops away from the fingers (units at the far corner); a resting print keeps a faint curl along its long side. */
+    readonly bend: {
+        readonly held: 5;
+        readonly rest: 0.9;
+        readonly rate: 9;
+    };
+    /**
+     * The swing about the grab point: `drag` = the air's pull on the sheet's centre (the centre trails the
+     * motion), `inertia` = the share of the hand's acceleration the sheet feels (it swings when the hand
+     * jerks or stops), `damp` = rotational damping per second. OFF (James, 2026-09-24: "do not make them
+     * rotate") — a carried print keeps its turn; only the wheel turns it. The machinery stays for the panel.
+     */
+    readonly swing: {
+        readonly drag: 0;
+        readonly inertia: 0;
+        readonly damp: 2.2;
+    };
+    /**
+     * Sliding: in the air a glide with `air` drag per second; on the mat the cutting mat's grip — a
+     * constant deceleration (u/s²) plus a viscous share per second; the same for the turn (rad/s², /s).
+     */
+    readonly slide: {
+        readonly air: 0.9;
+        readonly grip: 2400;
+        readonly viscous: 5;
+        readonly spinGrip: 7;
+        readonly spinViscous: 4;
+    };
+    /** A flick's velocity is the hand's over this window (s), capped at this speed (u/s). */
+    readonly throw: {
+        readonly window: 0.07;
+        readonly max: 4200;
+    };
+    /** The shadow's two terms (`DESK_SHADOW`). */
+    readonly shadow: {
+        readonly penumbra: {
+            readonly sigma0: 2.2;
+            readonly sigmaPerHeight: 0.36;
+            readonly alpha: 0.36;
+            readonly alphaHeld: 0.42;
+            readonly slopeMax: 2.2;
+        };
+        readonly contact: {
+            readonly alpha: 0.22;
+            readonly sigma: 1.1;
+            readonly reach: 2.5;
+        };
+    };
+    /** The gloss: the lamp's highlight (strength, shininess), and the room's sheen off the coating (strength). */
+    readonly gloss: {
+        readonly spec: 0.2;
+        readonly shininess: 42;
+        readonly sheen: 0.5;
+    };
+    /**
+     * By night (PHOTO.md §4a): the print is lit by the Moon at the mat's night law — `level` of its day
+     * luminance in the Moon's light (MAT.md: the moonlit sage shows at ½ the sunlit) — the palm's shade
+     * deepening to the sky's fill; its paper seen as the mat is (the rods' blue), its picture foveally
+     * (`keep` 1 = cones alone, white-balanced: the picture's hue exactly).
+     */
+    readonly night: {
+        readonly level: 0.5;
+        readonly keep: 1;
+    };
+    /** Going away (delete): the sheet lifts and fades over this long (s). */
+    readonly leave: 0.28;
+};
+/** The law with its literals widened — what a host tunes (a copy: `structuredClone(PHOTO)`). */
+type Widen<T> = T extends number ? number : T extends RGB ? RGB : {
+    -readonly [K in keyof T]: Widen<T[K]>;
+};
+export type PhotoLaw = Widen<typeof PHOTO_SPEC>;
+/** The engine's numbers. Never written — a host tunes its own copy. */
+export declare const PHOTO: PhotoLaw;
+/** The unit direction toward the lamp from a point of the desk at height z (x right, y down, z up). */
+export declare function lightAt(x: number, y: number, z?: number, lamp?: Lamp): readonly [number, number, number];
+/** A cast shadow's offset on the mat per unit of height at a desk point — away from the lamp, capped. */
+export declare function shadowSlope(x: number, y: number, lamp?: Lamp, max?: number): readonly [number, number];
+export interface Hold {
+    /** The grab point in the sheet's own frame (unrotated, centre origin). */
+    gx: number;
+    gy: number;
+    /** The finger, world — where the grab point is, exactly. */
+    px: number;
+    py: number;
+    /** The finger's filtered velocity and acceleration (world/s, world/s²). */
+    vx: number;
+    vy: number;
+    ax: number;
+    ay: number;
+    /** Recent finger samples for the flick: [t, x, y]. */
+    trail: [number, number, number][];
+}
+export interface PhotoBody {
+    /** Centre on the mat plane, world. */
+    x: number;
+    y: number;
+    /** The turn in the plane, radians (positive = clockwise on screen). */
+    angle: number;
+    vx: number;
+    vy: number;
+    spin: number;
+    /** Height of the centre off the mat, and its rate. */
+    h: number;
+    vh: number;
+    /** The slope (dz/dx, dz/dy, world axes) and its rate. */
+    sx: number;
+    sy: number;
+    vsx: number;
+    vsy: number;
+    bend: number;
+    /** Half extents (world). */
+    readonly hx: number;
+    readonly hy: number;
+    /** The perspective's anchor in the sheet's frame — the grab point while held (so the finger's point never slides), kept after. */
+    ax: number;
+    ay: number;
+    hold: Hold | null;
+    hovered: boolean;
+    /** Presence: 1 here, falling to 0 as it leaves; `leaving` = on its way out. */
+    alpha: number;
+    leaving: boolean;
+}
+export declare function newBody(x: number, y: number, w: number, h: number, angle?: number, height?: number): PhotoBody;
+/** The print's size for an image: the long side is `law.long`, the aspect is the picture's. */
+export declare function printSize(imgW: number, imgH: number, long?: number): {
+    w: number;
+    h: number;
+};
+/** Take hold of the sheet at a world point (the finger), in its own frame. */
+export declare function grab(b: PhotoBody, wx: number, wy: number, t: number): void;
+/** The finger moved (world, at time t in seconds). */
+export declare function moveHold(b: PhotoBody, wx: number, wy: number, t: number): void;
+/** Let go at time t: the sheet leaves with the finger's recent velocity (and its own swing). */
+export declare function release(b: PhotoBody, t: number, law?: PhotoLaw): void;
+/** Turn a held sheet about the finger (the wheel), radians. */
+export declare function twist(b: PhotoBody, da: number): void;
+/** Is the sheet still moving (or still settling)? A host renders on demand while any is. */
+export declare function restless(b: PhotoBody): boolean;
+/** Advance the body by `dt` seconds (substepped at 240 Hz). */
+export declare function stepPhoto(b: PhotoBody, dt0: number, law?: PhotoLaw): void;
+/**
+ * No corner goes through the mat: the lowest point of the tilted, drooping sheet is the
+ * centre's height less the slope's fall to the far corner less the droop — when that is
+ * under 0 the slope gives (the far corner rests on the mat while the near one lifts, as a
+ * sheet lifted by its corner does) and its rate with it.
+ */
+export declare function clearMat(b: PhotoBody): void;
+export type Vec3 = readonly [number, number, number];
+export interface PhotoGeometry {
+    /** The sheet's centre in 3D (world units, z = height). */
+    readonly centre: Vec3;
+    /** The sheet's own axes in 3D (unit) and its normal. */
+    readonly ex: Vec3;
+    readonly ey: Vec3;
+    readonly n: Vec3;
+    readonly half: readonly [number, number];
+    readonly radius: number;
+    /** The local eye (world units): over the anchor, `law.eye` above the mat. */
+    readonly eye: Vec3;
+    /** The bend: the droop's amount and where it hangs from (the sheet's frame); the rest curl. Signed (droop, held). */
+    readonly droop: number;
+    readonly curl: number;
+    readonly grab: readonly [number, number];
+    readonly alpha: number;
+    /** Toward the lamp from the print (unit), the shadow's slope on the mat, the penumbra's alpha (resting → held). */
+    readonly light: Vec3;
+    readonly slope: readonly [number, number];
+    readonly shadowAlpha: number;
+    /** The world rect the pass's quad covers: the sheet as seen and its shadow. */
+    readonly bounds: {
+        readonly x0: number;
+        readonly y0: number;
+        readonly x1: number;
+        readonly y1: number;
+    };
+}
+/** The pose → what the pass draws and the hit-test reads. */
+export declare function resolvePhoto(b: PhotoBody, law?: PhotoLaw, lamp?: Lamp): PhotoGeometry;
+/** The sheet's own frame → a 3D point on its (flat) plane. */
+export declare function pointAt(G: Pick<PhotoGeometry, "centre" | "ex" | "ey">, u: number, v: number): Vec3;
+/** A 3D point as the local eye sees it on the desk plane (world units). */
+export declare function project(eye: Vec3, P: Vec3): [number, number];
+/** The bend's offset along the normal at a point of the sheet (photo.wgsl `photo_bend`). */
+export declare function bendAt(G: Pick<PhotoGeometry, "half" | "droop" | "curl" | "grab">, u: number, v: number): number;
+/** A desk point (world) → the point of the sheet the eye sees there, in the sheet's frame (photo.wgsl `photo_unproject`). */
+export declare function unproject(G: PhotoGeometry, wx: number, wy: number): [number, number];
+export declare function sdRoundBox(qx: number, qy: number, hx: number, hy: number, r: number): number;
+/** Is the desk point on the sheet as drawn? */
+export declare function hitPhoto(G: PhotoGeometry, wx: number, wy: number): boolean;
+export {};