paperlab 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -1,19 +1,19 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
 import * as THREE from 'three';
-import { P as PaperConfig, S as StateName, a as PaperConfigInput, b as SheetConfig, c as StockName, C as ContentConfigInput, B as BehaviorConfigInput, D as DeformerInstanceConfigInput, d as SurfaceConfigInput, e as SceneConfigInput, f as PhysicsConfigInput, g as PaperEdge, F as FieldPaperSlot, L as LightingName, h as FilmName, i as ContentConfig, j as SurfaceConfig, k as PaperStatesInput } from './slots-D0Nc_5dq.js';
-export { l as BackContentConfig, m as BehaviorConfig, n as ClothConfig, o as CoreStateName, p as DeformerInstanceConfig, q as FieldGroupData, r as PaperStates, s as PhysicsConfig, t as SceneConfig, u as StateDef, v as StateTransitionConfig, w as backContentSchema, x as behaviorConfigSchema, y as cardContentSchema, z as clothConfigSchema, A as contentSchema, E as coreStateNames, G as deformerInstanceSchema, H as filmNames, I as groupFieldPapers, J as lightingNames, K as paperConfigSchema, M as paperEdges, N as paperStatesSchema, O as physicsNames, Q as physicsSchema, R as receiptContentSchema, T as resolveFieldSlotConfig, U as sceneSchema, V as sheetSchema, W as stateDefSchema, X as stateTransitionSchema, Y as stockNames, Z as stockSchema, _ as surfaceSchema } from './slots-D0Nc_5dq.js';
+import { P as PaperConfig, a as PaperConfigInput, S as SheetConfig, b as StockName, C as ContentConfigInput, B as BehaviorConfigInput, D as DeformerInstanceConfigInput, c as SurfaceConfigInput, d as SceneConfigInput, e as PhysicsConfigInput, F as FieldPaperSlot, f as ContentConfig, g as PaperStatesInput, L as LightingName, h as FilmName } from './slots-BYoLxVZ4.js';
+export { i as BackContentConfig, j as BehaviorConfig, k as ClothConfig, l as CoreStateName, m as DeformerInstanceConfig, n as PaperEdge, o as PaperStates, p as PhysicsConfig, q as SceneConfig, r as StateDef, s as StateName, t as StateTransitionConfig, u as SurfaceConfig, v as behaviorConfigSchema, w as clothConfigSchema, x as coreStateNames, y as lightingNames, z as paperConfigSchema, A as paperEdges, E as paperStatesSchema, G as physicsNames, H as stateDefSchema, I as stockNames } from './slots-BYoLxVZ4.js';
 import { z } from 'zod';
 
 /**
  * The interaction-state engine. A state is a set of parameter overrides on
- * the base preset — never a separate preset (spec M6 §1.1). The machine
+ * the base preset — never a separate preset. The machine
  * resolves each state to a full config (base + overrides), keeps ONE live
  * tween target of flattened numeric leaves, and always tweens FROM CURRENT
  * VALUES: a pointer that enters/leaves rapidly retargets the same tween
  * values instead of stacking or snapping.
  *
- * Delivery split (spec v0.2 §4: GSAP owns values, useFrame owns uploads):
+ * Delivery split (GSAP owns values, useFrame owns uploads):
  * GSAP animates the STABLE `flat` object in place; per-tick values are polled
  * off `liveConfig` by the consumer's frame loop, never pushed through React.
  * `onChange` fires only on STRUCTURAL boundaries (a transition's start and
@@ -22,10 +22,6 @@ import { z } from 'zod';
  */
 /** Built-in trigger events (v1 — user-defined wiring is parked for editor v2). */
 type StateEvent = 'enter' | 'leave' | 'down' | 'up' | 'pick' | 'place' | 'return';
-/** The fixed v1 transition table: pointer flow + pick/drop flow. */
-declare const stateEventTransitions: Record<string, Partial<Record<StateEvent, StateName>>>;
-/** The base config with `states` stripped — what a state resolves against. */
-declare function stripStates(config: PaperConfig): PaperConfig;
 /**
  * Resolve a state name to its full config: base + that state's overrides.
  * States without a recorded def (e.g. an untouched 'rest') are the base.
@@ -43,7 +39,6 @@ declare function resolveStateConfig(base: PaperConfig, state: string): PaperConf
  * cleanly throws here.
  */
 declare function recordStateOverride(config: PaperConfig, stateName: string, patch: Record<string, unknown>): PaperConfig;
-declare function flattenNumeric(value: unknown, prefix?: string, out?: Record<string, number>): Record<string, number>;
 interface PaperStateMachineOptions {
     /** Reduced motion: every transition applies instantly (duration 0). */
     instant?: boolean;
@@ -204,8 +199,6 @@ interface PaperHandle {
     /** Instant, legal return (picked → rest). */
     returnProgrammatic(): boolean;
 }
-/** Resolve preset + prop overrides into a validated config. */
-declare function resolveConfig(props: PaperMeshProps): PaperConfig;
 /**
  * The atom: one sheet of paper, hero-mode CPU path. The deformer stack (or
  * the cloth sim — never both) writes geometry positions each frame. GSAP
@@ -249,26 +242,6 @@ interface PlacedPaper {
 interface DropZoneProps extends DropZoneConfig {
     onPlace?(paper: PlacedPaper, zone: string): void;
 }
-interface ZoneEntry extends DropZoneConfig {
-    onPlace?: DropZoneProps['onPlace'];
-}
-/** Shared zone state: `<DropZone>` children register; the carry loop hit-tests. */
-declare class DropZoneRegistry {
-    private zones;
-    private hoveredId;
-    private listeners;
-    private version;
-    register(zone: ZoneEntry): () => void;
-    list(): ZoneEntry[];
-    get(id: string): ZoneEntry | undefined;
-    get hovered(): string | null;
-    setHovered(id: string | null): void;
-    subscribe: (fn: () => void) => (() => void);
-    getVersion: () => number;
-    private notify;
-}
-/** True when `name` matches the zone's accept globs (all zones accept by default). */
-declare function zoneAccepts(zone: Pick<DropZoneConfig, 'accept'>, name: string): boolean;
 /**
  * A drop target inside a `<PaperField>`. While a paper is picked, its center
  * is tested against the bounds each frame; hovering applies the highlight
@@ -301,7 +274,7 @@ interface DeformerContext {
  * A deformer is a pure vertex-mapping function. The JS implementation is the
  * CPU path (hero mode) and must be allocation-free in the loop: it mutates
  * `out` in place. The mirrored GLSL implementation (GPU path, field mode)
- * lands in M4 — golden-vector parity tests will enforce identical results.
+ * lands with field mode — golden-vector parity tests will enforce identical results.
  */
 interface Deformer<O = Record<string, unknown>> {
     id: string;
@@ -310,7 +283,7 @@ interface Deformer<O = Record<string, unknown>> {
     optionsSchema: z.ZodType<O, z.ZodTypeDef, unknown>;
     /** Mutate `out` (sheet-local space; flat sheet is the XY plane facing +Z). */
     displace(out: THREE.Vector3, uv: THREE.Vector2, o: O, ctx: DeformerContext): void;
-    /** GPU path — arrives with field mode (M4). */
+    /** GPU path — arrives with field mode. */
     glsl?: {
         chunk: string;
         uniforms(o: O): Record<string, unknown>;
@@ -373,37 +346,6 @@ interface DeformerInstance<O = Record<string, unknown>> {
     enabled?: boolean;
 }
 
-declare const cornerNames: readonly ["top-left", "top-right", "bottom-left", "bottom-right"];
-declare const curlOptionsSchema: z.ZodObject<{
-    corner: z.ZodDefault<z.ZodEnum<["top-left", "top-right", "bottom-left", "bottom-right"]>>;
-    /** How far the curl has traveled from the corner, as a fraction of the diagonal. */
-    amount: z.ZodDefault<z.ZodNumber>;
-    /** Cylinder radius — curl sharpness. */
-    radius: z.ZodDefault<z.ZodNumber>;
-    /** Skew of the fold line away from the corner diagonal, degrees. */
-    skew: z.ZodDefault<z.ZodNumber>;
-}, "strip", z.ZodTypeAny, {
-    corner: "top-left" | "top-right" | "bottom-left" | "bottom-right";
-    amount: number;
-    radius: number;
-    skew: number;
-}, {
-    corner?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | undefined;
-    amount?: number | undefined;
-    radius?: number | undefined;
-    skew?: number | undefined;
-}>;
-type CurlOptions = z.infer<typeof curlOptionsSchema>;
-/**
- * Corner-anchored cylinder wrap — the peel/dog-ear deformer, and the
- * crown-jewel realism case: the mesh genuinely wraps the cylinder so content
- * bends with perfect continuity and the backside becomes visible.
- *
- * The fold line runs perpendicular to the corner diagonal and travels inward
- * with `amount`; everything cornerward of it wraps around the cylinder.
- */
-declare const curl: Deformer<CurlOptions>;
-
 /**
  * Pure grid math for the `sheet` layout — a block of stamps on a shared
  * backing. Shared by the layout's pose function, the backing silhouette
@@ -439,40 +381,6 @@ declare const sheetLayoutSchema: z.ZodObject<{
     backingMargin?: number | undefined;
 }>;
 type SheetLayoutOptions = z.infer<typeof sheetLayoutSchema>;
-/** Backing thickness + ε — papers float just above the backing sheet. */
-declare const SHEET_LIFT = 0.012;
-/**
- * Cell footprint = the paper's own sheet dims unless the user set an
- * explicit cellWidth/cellHeight — so `gutter` is literally the spacing
- * between stamps, whatever preset populates the grid.
- */
-declare function withSheetCellFromPaper(parsed: SheetLayoutOptions, rawOptions: Record<string, unknown> | undefined, paperDims: {
-    width: number;
-    height: number;
-} | undefined): SheetLayoutOptions;
-declare function sheetSlotXY(i: number, o: SheetLayoutOptions): {
-    x: number;
-    y: number;
-};
-/** Grid bounds + margin — the backing sheet's size. */
-declare function sheetBackingSize(o: SheetLayoutOptions): {
-    width: number;
-    height: number;
-};
-type Corner = CurlOptions['corner'];
-/**
- * The corner facing away from the sheet's center — what a thumb would find
- * (spec M6 §1.3). A tie (an odd grid's exact-center row/column, where the
- * cell straddles the midline) breaks outward-and-down: strict `<` on both
- * axes sends the center right and down, so a dead-center cell peels
- * bottom-right — the standalone peel default.
- */
-declare function outwardCorner(i: number, o: Pick<SheetLayoutOptions, 'rows' | 'columns'>): Corner;
-/**
- * Perforation auto-wiring on detach: edges that faced a neighboring slot tear
- * through; edges on the sheet's outer boundary keep their clean punches.
- */
-declare function tornEdgesOnDetach(i: number, o: Pick<SheetLayoutOptions, 'rows' | 'columns'>): Partial<Record<PaperEdge, 'torn' | 'intact'>>;
 
 /** Imperative field controls for the hidden a11y keyboard flow. */
 interface FieldA11yController {
@@ -483,26 +391,6 @@ interface FieldA11yController {
     slotState(slot: number): string;
 }
 
-/** Carry state of the hidden keyboard mirror: which paper is aloft, which zone is focused. */
-interface KeyboardCarry {
-    slot: number;
-    zoneIndex: number;
-}
-/** A keyboard step's decision: the next carry state and whether it consumed the key. */
-interface KeyboardStepResult {
-    carry: KeyboardCarry | null;
-    handled: boolean;
-}
-/**
- * The M6 §6 keyboard flow as a pure step (so it's testable without a DOM):
- * given the current carry state, the focused paper `slot`, and the pressed
- * `key`, it drives the field `controller` (pick → move between zones → place /
- * cancel) and returns the next carry state. All side effects go through
- * `controller`; the caller applies `carry` to its state and calls
- * `preventDefault()` when `handled` is true.
- */
-declare function fieldKeyboardStep(carry: KeyboardCarry | null, slot: number, key: string, controller: FieldA11yController): KeyboardStepResult;
-
 interface PaperFieldMeshProps {
     /** Per-paper slots; length sets the instance count. Slot presets override the shared one. */
     papers?: FieldPaperSlot[];
@@ -570,152 +458,379 @@ declare const PaperFieldMesh: react.ForwardRefExoticComponent<PaperFieldMeshProp
 /** `<PaperField />` owns its own Canvas; PaperFieldMesh drops into existing scenes. */
 declare const PaperField: react.ForwardRefExoticComponent<PaperFieldProps & react.RefAttributes<THREE.Group<THREE.Object3DEventMap>>>;
 
-interface UsePaperStatesResult {
-    /** The config to render this frame — animated when a machine is live. */
-    config: PaperConfig;
-    /** Current state name ('rest' when no machine). */
-    state: string;
-    /** Send triggers through this; null when states are absent or disabled. */
-    machine: PaperStateMachine | null;
-}
+declare function getPreset(name: string): PaperConfig;
+/** Register a user preset (validated). Built-in names are reserved. */
+declare function registerPreset(name: string, input: PaperConfigInput): void;
+declare function unregisterPreset(name: string): void;
+declare function isBuiltinPreset(name: string): boolean;
+declare function listPresets(): string[];
 /**
- * Bind a state machine to a config with `states`. The machine survives
- * config edits via `rebase` (current state and live values are kept —
- * flipping perforation to torn mid-pick must not snap the stamp to rest);
- * it is only rebuilt when states are toggled on/off.
+ * A collision-free preset name built from `base`: `base`, else `base 2`,
+ * `base 3`, … The disambiguating suffix always grows from the SAME base — a
+ * name derived from a synthetic base (e.g. an untitled import → "imported")
+ * must not fall back to the original when it collides. `taken` reports whether
+ * a candidate is already used (built-in or user preset).
+ */
+declare function uniquePresetName(base: string, taken: (name: string) => boolean): string;
+
+/**
+ * Deep-merge preset config with prop overrides (overrides win; arrays and
+ * discriminated unions replace wholesale, plain objects merge).
  *
- * `animated` holds an IMMUTABLE structural snapshot for the React tree; it
- * updates only on structural boundaries (transition start/settle, state swap,
- * rebase), not per frame. Per-tick numeric values are read straight off
- * `machine.liveConfig` by the caller's frame loop — GSAP owns values, useFrame
- * owns uploads. `machine` is returned so the caller can poll it.
+ * Lives in its own module (not serialize.ts) because the schema needs it to
+ * validate state overrides — schema → serialize would be circular.
  */
-declare function usePaperStates(config: PaperConfig, enabled: boolean, instant: boolean, onAction?: (event: string, state: string) => void, onStateChange?: (state: string) => void): UsePaperStatesResult;
+declare function mergeConfig<T>(base: T, override: unknown): T;
+/**
+ * Like {@link mergeConfig}, but an explicit `undefined` DELETES its key instead
+ * of being ignored — the semantics a BASE-config write needs: structural
+ * setters can clear `behavior`/`deformers` or toggle a surface effect off.
+ * Discriminated unions (differing `type`) still replace wholesale.
+ */
+declare function mergeWithDeletes<T>(base: T, patch: unknown): T;
+
+/** Parse anything preset-shaped (object or JSON string) into a full, defaulted config. */
+declare function parsePreset(input: PaperConfigInput | string): PaperConfig;
+/** Serialize a config to `.paper` JSON. */
+declare function serializePreset(config: PaperConfig): string;
 
+/** The minimal PaperConfigInput that parses back to `config`. */
+declare function diffConfig(config: PaperConfig): PaperConfigInput;
 /**
- * The backing sheet's generated content: per-slot ghost silhouettes a few
- * percent lighter than the backing tint. When a slot's paper detaches
- * (picked/placed), its silhouette lightens further and gains a faint
- * adhesive-sheen gradient — the visual proof of removal. Redrawn on state
- * change, never per-frame.
+ * A plain `<Paper />` snippet with only the non-default props — the
+ * secondary export for people who read code.
  */
-interface SilhouetteRect {
-    /** Canvas-UV rect (0..1, y down) of slot i on the backing sheet. */
-    x: number;
-    y: number;
-    w: number;
-    h: number;
-}
-/** Pure: where each slot's silhouette sits on the backing, in canvas UV. */
-declare function silhouetteRects(o: SheetLayoutOptions, count: number): SilhouetteRect[];
-/** Lighten a hex tint toward white by `amount` (0..1). */
-declare function lightenHex(hex: string, amount: number): string;
-interface BackingDrawSpec {
-    options: SheetLayoutOptions;
-    count: number;
-    tint: string;
-    /** Slot indices whose paper has been picked/placed away. */
-    removed: ReadonlySet<number>;
-}
-/** Draw the backing content onto a canvas (called on state change only). */
-declare function drawBacking(canvas: HTMLCanvasElement, spec: BackingDrawSpec): void;
+declare function buildJsxSnippet(config: PaperConfig): string;
+
+/** One line an agent can verify against what it sees after `npm run dev`. */
+declare function describeConfig(config: PaperConfig): string;
+/** The self-contained integration brief — one paste into a coding agent. */
+declare function buildAgentPayload(config: PaperConfig): string;
 
 /**
- * Lighting presets: each is a key light + ambient level + contact shadow +
- * optional gobo (a texture the key light projects — window blinds, foliage).
- * Pure data here (testable in node); textures and R3F live in
- * PaperLighting.tsx. Serialized into presets as `scene.lighting`.
- *
- * A preset is the *starting point*, not the ceiling. `lightSchema` below is
- * the art-directable half: a handful of overrides that ride on top of a
- * named preset, so "nave, but the sun is lower and the room is dimmer" is a
- * thing you can say — and serialize — instead of a preset you have to fork.
+ * Field-mode export. Every preset a field references is INLINED as a const —
+ * receivers don't have the sender's local preset library. Same fixed payload
+ * anatomy as the single-paper export, same version.
  */
-interface LightingPreset {
-    id: LightingName;
-    label: string;
-    ambient: number;
-    key: {
-        color: string;
-        intensity: number;
+interface FieldExportPaper {
+    /** Display name of the preset this slot uses (const naming + description). */
+    presetName: string;
+    /** The RESOLVED preset config (user presets included — nothing to fetch). */
+    preset: PaperConfig;
+    content?: ContentConfig;
+    /** Per-slot state overrides (slot 3's hover deeper than slot 4's). */
+    states?: PaperStatesInput;
+}
+interface FieldExportZone {
+    id: string;
+    accept?: string[];
+    bounds: {
         position: [number, number, number];
+        size: [number, number];
     };
-    contactShadowOpacity: number;
-    /** Contact shadow blur — hard for noir, long and soft for golden hour. */
-    contactShadowBlur: number;
-    /** Renderer tone-mapping exposure while active. */
-    exposure: number;
-    /**
-     * The tone curve the picture is printed through.
-     *
-     * `exposure` picks the stop; this picks the FILM, and on a subject that is
-     * almost white the film is the louder of the two. Every preset ships
-     * `neutral` — Khronos PBR Neutral — because it is the only one of the
-     * three that keeps a clipping sheet BOTH bright and the colour it actually
-     * is. See the note on `filmNames` for what the other two do to warm light.
-     */
-    film: FilmName;
-    shadow: {
-        mapSize: number;
-        radius: number;
-    };
-    gobo?: {
-        kind: 'blinds' | 'leaves';
-        drift: number;
-        angle: number;
-    };
-    /**
-     * Distance haze. Depth in a deep space is staged almost entirely by fog —
-     * it is what turns a row of banners into a receding colonnade instead of
-     * a flat row of rectangles.
-     */
-    fog?: {
-        color: string;
-        near: number;
-        far: number;
+    highlight?: 'none' | 'glow' | 'outline';
+}
+interface FieldExportInput {
+    layout: string;
+    layoutOptions?: Record<string, unknown>;
+    motion?: {
+        driver?: 'autoplay' | 'drag' | 'none';
+        speed?: number;
     };
-    /**
-     * The studio light: how strongly the room itself lights the paper.
-     *
-     * `<ambientLight>` adds brightness with no direction at all, which is the
-     * single biggest reason a surface reads flat. This is the same brightness
-     * with a SHAPE — an environment built from the sky below, so a sheet
-     * turned toward the bright side of the room gets more light than one
-     * turned away, and paper's sheen finally has something to reflect.
-     */
-    studio: number;
-    /**
-     * The room, as three colours. It grades zenith → horizon → floor, carries
-     * a soft disc of the key's own colour where the key stands, and becomes
-     * both the environment map and (in stage mode) the cyclorama, so the
-     * light and the space it is in cannot disagree.
-     */
-    sky: {
-        zenith: string;
-        horizon: string;
-        ground: string;
+    entrance?: {
+        type?: 'rise' | 'scatter' | 'none';
+        stagger?: number;
+        duration?: number;
     };
+    papers: FieldExportPaper[];
+    /** Drop zones — exported as `<DropZone>` children with an onPlace stub. */
+    zones?: FieldExportZone[];
+}
+/** The layout/motion/entrance props of the export, defaults stripped. */
+declare function diffFieldProps(input: FieldExportInput): Record<string, unknown>;
+/** The one-line visual an agent verifies after `npm run dev`. */
+declare function describeFieldConfig(input: FieldExportInput): string;
+/** Component source shared by the JSX snippet and the agent payload. */
+declare function buildFieldComponentSource(input: FieldExportInput): string;
+/** The self-contained field integration brief — one paste into a coding agent. */
+declare function buildFieldAgentPayload(input: FieldExportInput): string;
+
+/** Community deformers register here; built-ins are pre-registered. */
+declare function registerDeformer(deformer: Deformer<AnyOptions>): void;
+declare function getDeformer(id: string): Deformer<AnyOptions>;
+declare function listDeformers(): string[];
+
+/**
+ * The shared fake-aerodynamics core: velocity-linked lift +
+ * curated noise, per v0.2's "reads more real than a true sim" doctrine.
+ * Pure math, no three.js, no allocation in the per-frame paths — `carry`
+ * and `flight` both source their motion here.
+ */
+interface AeroPose {
+    position: [number, number, number];
+    rotation: [number, number, number];
+}
+
+/** A draggable 3D grab point; drags write back to behavior params. */
+interface HandleSpec<O = AnyOptions> {
+    id: string;
+    /** UV-space (0..1) anchor of the grab point on the flat sheet. */
+    anchor(o: O, sheet: SheetDims): [number, number];
+    /** Map a pointer position in sheet-local XY to option updates. */
+    drag(local: {
+        x: number;
+        y: number;
+    }, o: O, sheet: SheetDims): Partial<O>;
 }
-declare const lightingPresets: Record<LightingName, LightingPreset>;
-declare function getLightingPreset(name: LightingName): LightingPreset;
 /**
- * Overrides on top of a named preset — the Blender-panel half of lighting.
- *
- * Every field is optional ON PURPOSE. An unset field means "whatever the
- * preset says", so a shared link carries the two sliders you actually moved
- * rather than a frozen copy of a rig you never touched, and re-basing onto
- * another preset keeps your intent instead of your numbers.
+ * A behavior is a named, curated bundle: a deformer stack + a parameter
+ * mapping + optional idle loop + handles for direct manipulation. Designers
+ * see 3–5 human-named params ('tightness', not 'cylinderRadius'); the stack
+ * underneath is an Advanced disclosure. New behaviors are the community
+ * on-ramp: ~50 lines over existing deformers.
  */
-declare const lightSchema: z.ZodObject<{
-    /** Tone-mapping exposure — the stop the whole picture is printed at. */
-    exposure: z.ZodOptional<z.ZodNumber>;
+interface Behavior<O = AnyOptions> {
+    id: string;
+    label: string;
+    defaults: O;
+    optionsSchema: z.ZodType<O, z.ZodTypeDef, unknown>;
+    /** Expand human params to the underlying deformer stack. */
+    stack(o: O, sheet: SheetDims): DeformerInstance[];
+    /** Transient, time-varying option overrides (idle motion). Never persisted. */
+    loop?(o: O, t: number): Partial<O>;
     /**
-     * The tone curve — the film, where `exposure` is the stop.
-     *
-     * `filmic` is ACES, which is what every preset used to be pinned to and is
-     * kept so a scene tuned against it can say so. On near-white paper it is
-     * the wrong film: it desaturates and drags bright neutrals toward
-     * yellow-green, which is the sepia cast a lit sheet used to pick up.
+     * Whole-sheet motion written into `pose` each frame (allocation-free),
+     * composed after any idle preset's transform. Must be a pure function of
+     * (options, t) — the field applies it per instance with a time offset, so
+     * it has to be deterministic (flight's travel-across-the-scene).
+     */
+    transform?(o: O, t: number, pose: AeroPose): void;
+    handles?: HandleSpec<O>[];
+    /**
+     * The two or three options that ARE this behavior — the ones someone
+     * reaches for first, in the order they'd reach for them.
+     *
+     * The schema still generates a control for every option; this only says
+     * which ones get the big controls and which fold away behind "More". A
+     * behavior that nominates nothing shows all of its options flat, because
+     * the library must never hide a param it was not told to hide — silence
+     * from a community behavior is not permission to guess.
+     *
+     * Every name here has to be a field of {@link optionsSchema}; the built-in
+     * behaviors are checked for that, and for staying within three.
+     */
+    signature?: (keyof O & string)[];
+    /** The option the transport scrubber drives. */
+    progressParam: keyof O & string;
+    /** Seconds for a full 0→1 play, and how play repeats. */
+    duration: number;
+    loopMode: 'yoyo' | 'restart';
+}
+
+/** Community behaviors register here; built-ins are pre-registered. */
+declare function registerBehavior(behavior: Behavior<AnyOptions>): void;
+declare function getBehavior(id: string): Behavior<AnyOptions>;
+declare function listBehaviors(): string[];
+
+/**
+ * A layout is a pure `pose(i, n, options, phase)` function — no state, no
+ * three.js. `phase` is the motion driver's continuous offset in turns
+ * (0..1 = one full cycle); cyclic layouts use it, static ones ignore it.
+ * Community layouts are ~30 lines.
+ *
+ * Every built-in names a place paper actually sits — a fanned swatch deck, a
+ * slipped stack, a heap on a desk — because arrangement alone is what makes a
+ * field read as a photo carousel instead of as paper. The other half of that
+ * is `bias`: paper in the world does not all bend alike.
+ */
+interface PaperPose {
+    position: [number, number, number];
+    rotation: [number, number, number];
+    scale: number;
+    /**
+     * How strongly this sheet takes the field's deformation: 1 = exactly as the
+     * preset configures it, 0 = flat. Lets one instanced draw call curl the top
+     * of a pile while the sheets pressed underneath stay flat. Omitted = 1.
+     */
+    bias?: number;
+}
+interface Layout<O = Record<string, unknown>> {
+    id: string;
+    label: string;
+    defaults: O;
+    optionsSchema: z.ZodType<O, z.ZodTypeDef, unknown>;
+    /**
+     * `sheet` is the field's paper size. Layouts that arrange by CONTACT —
+     * edges meeting, sheets resting on each other — cannot work without it,
+     * and a layout that ignores it may simply omit the parameter.
+     */
+    pose(i: number, n: number, o: O, phase: number, sheet: SheetDims): PaperPose;
+    /**
+     * Where along a walk this layout put each paper, as normalized arc length,
+     * in the layout's own index order.
+     *
+     * Only layouts that arrange along a PATH can answer, which is why it is
+     * optional. Stage mode uses it to let a viewer step from one paper to the
+     * next: the stops have to be where the paper actually is, and the only
+     * thing that knows that is the function that placed it.
+     */
+    walkStops?(n: number, o: O): number[];
+}
+declare function registerLayout(layout: Layout<AnyOptions>): void;
+declare function getLayout(id: string): Layout<AnyOptions>;
+declare function listLayouts(): string[];
+
+/**
+ * A stock is a named bundle of material + geometry defaults — choosing paper
+ * at a print shop. Individual controls always override; schema-wise these are
+ * just defaults.
+ */
+interface Stock {
+    id: StockName;
+    label: string;
+    /** Base tint, also used as the canvas background behind content. */
+    color: string;
+    roughness: number;
+    /** 0 = opaque. Vellum is translucent. */
+    opacity: number;
+    /**
+     * How much light passes THROUGH the sheet when something is behind it,
+     * 0..1. Distinct from `opacity`: newsprint is fully opaque to look at and
+     * still glows on a lightbox. This is what makes a backlit banner read.
+     */
+    translucency: number;
+    /** Ink multiply tint for content drawn on this stock (thermal prints grey-black). */
+    inkColor: string;
+    /** Thermal-printer banding intensity baked into the grain effect. */
+    banding: number;
+    /** Surface effects this stock ships with; explicit surface config overrides per key. */
+    defaultSurface: {
+        grain?: number;
+        aging?: number;
+    };
+    /** Reversed front-content ghost on the backside (thin stocks let ink show). */
+    showThrough: number;
+    /** Glossy near-white glue underside (stickers) — forces showThrough 0. */
+    adhesive: boolean;
+}
+declare const stocks: Record<StockName, Stock>;
+declare function getStock(name: StockName): Stock;
+
+declare const idleNames: readonly ["float", "tumble", "dangle", "taped", "breeze"];
+type IdleName = (typeof idleNames)[number];
+interface IdlePose {
+    /** Offsets added to the paper's base transform each frame. */
+    position: [number, number, number];
+    rotation: [number, number, number];
+}
+/**
+ * Curated fake physics: hand-tuned motion presets, no simulation. Cheap
+ * enough for both hero and field modes, and — for things like the
+ * falling-leaf tumble — they read *more* real than a true sim.
+ */
+interface IdlePreset {
+    id: IdleName;
+    label: string;
+    /** Whole-sheet motion, written into `pose` (allocation-free). */
+    transform?(t: number, pose: IdlePose): void;
+    /** Extra deformers appended after the behavior's stack. */
+    stack?(): DeformerInstance[];
+}
+
+/**
+ * Lighting presets: each is a key light + ambient level + contact shadow +
+ * optional gobo (a texture the key light projects — window blinds, foliage).
+ * Pure data here (testable in node); textures and R3F live in
+ * PaperLighting.tsx. Serialized into presets as `scene.lighting`.
+ *
+ * A preset is the *starting point*, not the ceiling. `lightSchema` below is
+ * the art-directable half: a handful of overrides that ride on top of a
+ * named preset, so "nave, but the sun is lower and the room is dimmer" is a
+ * thing you can say — and serialize — instead of a preset you have to fork.
+ */
+interface LightingPreset {
+    id: LightingName;
+    label: string;
+    ambient: number;
+    key: {
+        color: string;
+        intensity: number;
+        position: [number, number, number];
+    };
+    contactShadowOpacity: number;
+    /** Contact shadow blur — hard for noir, long and soft for golden hour. */
+    contactShadowBlur: number;
+    /** Renderer tone-mapping exposure while active. */
+    exposure: number;
+    /**
+     * The tone curve the picture is printed through.
+     *
+     * `exposure` picks the stop; this picks the FILM, and on a subject that is
+     * almost white the film is the louder of the two. Every preset ships
+     * `neutral` — Khronos PBR Neutral — because it is the only one of the
+     * three that keeps a clipping sheet BOTH bright and the colour it actually
+     * is. See the note on `filmNames` for what the other two do to warm light.
+     */
+    film: FilmName;
+    shadow: {
+        mapSize: number;
+        radius: number;
+    };
+    gobo?: {
+        kind: 'blinds' | 'leaves';
+        drift: number;
+        angle: number;
+    };
+    /**
+     * Distance haze. Depth in a deep space is staged almost entirely by fog —
+     * it is what turns a row of banners into a receding colonnade instead of
+     * a flat row of rectangles.
+     */
+    fog?: {
+        color: string;
+        near: number;
+        far: number;
+    };
+    /**
+     * The studio light: how strongly the room itself lights the paper.
+     *
+     * `<ambientLight>` adds brightness with no direction at all, which is the
+     * single biggest reason a surface reads flat. This is the same brightness
+     * with a SHAPE — an environment built from the sky below, so a sheet
+     * turned toward the bright side of the room gets more light than one
+     * turned away, and paper's sheen finally has something to reflect.
+     */
+    studio: number;
+    /**
+     * The room, as three colours. It grades zenith → horizon → floor, carries
+     * a soft disc of the key's own colour where the key stands, and becomes
+     * both the environment map and (in stage mode) the cyclorama, so the
+     * light and the space it is in cannot disagree.
+     */
+    sky: {
+        zenith: string;
+        horizon: string;
+        ground: string;
+    };
+}
+/**
+ * Overrides on top of a named preset — the Blender-panel half of lighting.
+ *
+ * Every field is optional ON PURPOSE. An unset field means "whatever the
+ * preset says", so a shared link carries the two sliders you actually moved
+ * rather than a frozen copy of a rig you never touched, and re-basing onto
+ * another preset keeps your intent instead of your numbers.
+ */
+declare const lightSchema: z.ZodObject<{
+    /** Tone-mapping exposure — the stop the whole picture is printed at. */
+    exposure: z.ZodOptional<z.ZodNumber>;
+    /**
+     * The tone curve — the film, where `exposure` is the stop.
+     *
+     * `filmic` is ACES, which is what every preset used to be pinned to and is
+     * kept so a scene tuned against it can say so. On near-white paper it is
+     * the wrong film: it desaturates and drags bright neutrals toward
+     * yellow-green, which is the sepia cast a lit sheet used to pick up.
      */
     film: z.ZodOptional<z.ZodEnum<["agx", "neutral", "filmic"]>>;
     /** Key light strength. */
@@ -777,8 +892,6 @@ interface LightAngles {
  * they have to agree.
  */
 declare function lightAngles(position: readonly [number, number, number]): LightAngles;
-/** The inverse: put a light back where those angles say it stands. */
-declare function lightPosition(angles: LightAngles): [number, number, number];
 /**
  * A preset with the overrides applied — the rig everything else reads.
  *
@@ -791,11 +904,6 @@ declare function lightPosition(angles: LightAngles): [number, number, number];
  */
 declare function resolveLighting(base: LightingName | LightingPreset, overrides?: LightOverrides): LightingPreset;
 
-/**
- * Procedural gobo textures — no binary assets in the repo. White passes
- * light, dark blocks it (SpotLight.map multiplies the beam).
- */
-declare function makeGoboTexture(kind: 'blinds' | 'leaves'): THREE.CanvasTexture;
 interface PaperLightingProps {
     preset?: LightingName;
     /**
@@ -845,33 +953,56 @@ declare function LightRig({ rig, children }: {
     children: ReactNode;
 }): react.JSX.Element;
 
-/** Community deformers register here; built-ins are pre-registered. */
-declare function registerDeformer(deformer: Deformer<AnyOptions>): void;
-declare function getDeformer(id: string): Deformer<AnyOptions>;
-declare function listDeformers(): string[];
+interface UsePaperStatesResult {
+    /** The config to render this frame — animated when a machine is live. */
+    config: PaperConfig;
+    /** Current state name ('rest' when no machine). */
+    state: string;
+    /** Send triggers through this; null when states are absent or disabled. */
+    machine: PaperStateMachine | null;
+}
 /**
- * Resolve a raw `deformers` stack — the Advanced fork of a behavior — into
- * instances safe to render.
- *
- * The escape hatch used to pass its options straight through, so a preset
- * naming an option that doesn't exist (`frequency` where wave wants
- * `wavelength`) reached the GLSL builder as `undefined` and died there with
- * a message about `.length`, or reached the CPU path and quietly produced
- * NaN vertices. Parsing through each deformer's own schema turns that into
- * the validation error it always was, and fills in defaults for whatever a
- * hand-written preset left out.
+ * Bind a state machine to a config with `states`. The machine survives
+ * config edits via `rebase` (current state and live values are kept —
+ * flipping perforation to torn mid-pick must not snap the stamp to rest);
+ * it is only rebuilt when states are toggled on/off.
  *
- * Disabled entries keep their slot: the GLSL uniform namespace is indexed by
- * position, so dropping one here would rename every uniform after it.
+ * `animated` holds an IMMUTABLE structural snapshot for the React tree; it
+ * updates only on structural boundaries (transition start/settle, state swap,
+ * rebase), not per frame. Per-tick numeric values are read straight off
+ * `machine.liveConfig` by the caller's frame loop — GSAP owns values, useFrame
+ * owns uploads. `machine` is returned so the caller can poll it.
  */
-declare function resolveDeformerStack(raw: {
-    type: string;
-    options?: Record<string, unknown>;
-    enabled?: boolean;
-}[]): DeformerInstance[];
+declare function usePaperStates(config: PaperConfig, enabled: boolean, instant: boolean, onAction?: (event: string, state: string) => void, onStateChange?: (state: string) => void): UsePaperStatesResult;
 
 /**
- * How finely a sheet has to be subdivided for a deformer to look like the
+ * Accessibility layer: reduced-motion handling, a hidden DOM mirror so the
+ * paper's content exists for screen readers and find-in-page, and a no-WebGL
+ * DOM fallback.
+ */
+declare function usePrefersReducedMotion(override?: boolean): boolean;
+declare function supportsWebGL(): boolean;
+
+/** highp float + sin/cos implementation differences across GPUs. */
+declare const PARITY_EPSILON = 0.0005;
+interface ParityCase {
+    name: string;
+    stack: DeformerInstance[];
+    sheet: SheetDims;
+    t: number;
+}
+interface ParityResult {
+    name: string;
+    maxError: number;
+    pass: boolean;
+}
+/** One case per deformer feature worth guarding, both easy and adversarial. */
+declare const parityCases: ParityCase[];
+/** Run every parity case. Requires a WebGL2 context with float render targets. */
+declare function runParityHarness(canvas?: HTMLCanvasElement): ParityResult[];
+
+/**
+ * How finely a sheet has to be subdivided for a deformer to look like the
  * surface it is approximating instead of like the polygons it is made of.
  *
  * A deformed mesh is a piecewise-linear stand-in for a curved surface, and the
@@ -957,16 +1088,6 @@ declare const AUTO_CEILING = 192;
 declare const FLAT_SEGMENTS = 8;
 /** Smallest ladder step at or above `n`, clamped to the ceiling. */
 declare function quantizeSegments(n: number): number;
-/**
- * A resolved grid: segments along the sheet's own X and Y.
- *
- * Two numbers rather than one because a sheet is not subdivided by a single
- * density. A banner 1.5 wide and 8.5 tall, draped in folds that run across
- * its width, needs the folds resolved ACROSS and needs almost nothing down
- * the drop — and a single number, however it is distributed, answers one of
- * those questions by getting the other one wrong.
- */
-type SegmentPair = [x: number, y: number];
 /**
  * Extent of the sheet along a direction in its own plane, degrees. For a
  * rectangle centered on the origin this is exactly `|w·cos| + |h·sin|` — the
@@ -991,1598 +1112,22 @@ declare function segmentsForArc(span: number, radius: number, tol?: number): num
 declare function segmentsForSine(span: number, amplitude: number, wavelength: number, tol?: number): number;
 
 /**
- * Run an ordered deformer stack over a sheet geometry: each vertex starts
- * from its flat base position and flows through every enabled deformer in
- * order. Writes positions in place and recomputes normals.
- */
-declare function applyDeformerStack(geometry: THREE.BufferGeometry, basePositions: Float32Array, stack: DeformerInstance[], ctx: DeformerContext): void;
-/** A single point through the stack — used for handle anchors and tests. */
-declare function displacePoint(point: THREE.Vector3, uvX: number, uvY: number, stack: DeformerInstance[], ctx: DeformerContext): THREE.Vector3;
-/**
- * The densest grid any deformer in the stack REQUIRES to work at all, per
- * axis — the componentwise max of every entry's floor projected onto the
- * sheet's own X and Y by the direction that entry curves in.
- */
-declare function stackMinSegments(stack: DeformerInstance[], sheet: SheetDims): SegmentPair;
-/**
- * The densest grid any deformer in the stack WANTS, given the options it is
- * actually carrying — what `segments: 'auto'` resolves to, per axis.
- *
- * Disabled instances are skipped, exactly as `applyDeformerStack` skips them:
- * a deformer that is not displacing anything has no opinion about the grid.
- * (`stackMinSegments` does not skip them, and that difference is deliberate —
- * a floor is about what the stack could do, a target about what it is doing.)
- *
- * A deformer with no `autoSegments` falls back to its floor, which is the
- * right answer for one whose cost does not move with its options.
- */
-declare function stackAutoSegments(stack: DeformerInstance[], sheet: SheetDims): SegmentPair;
-
-declare const rollOptionsSchema: z.ZodObject<{
-    /** Direction of rolling in the sheet plane, degrees. 0 = +x, 90 = +y. */
-    angle: z.ZodDefault<z.ZodNumber>;
-    /** Signed distance (along the roll direction, from sheet center) where the roll begins. */
-    boundary: z.ZodDefault<z.ZodNumber>;
-    /** Cylinder radius — sharpness of the roll. */
-    radius: z.ZodDefault<z.ZodNumber>;
-    /** Radius growth per radian so multi-turn rolls spiral instead of z-fighting. */
-    spiral: z.ZodDefault<z.ZodNumber>;
-}, "strip", z.ZodTypeAny, {
-    radius: number;
-    angle: number;
-    boundary: number;
-    spiral: number;
-}, {
-    radius?: number | undefined;
-    angle?: number | undefined;
-    boundary?: number | undefined;
-    spiral?: number | undefined;
-}>;
-type RollOptions = z.infer<typeof rollOptionsSchema>;
-/**
- * Wrap the sheet around a virtual cylinder lying across the roll direction.
- * Everything past `boundary` wraps; the wrap is C¹-continuous at the
- * boundary and preserves arc length (content never stretches).
- *
- * Points arriving with z ≠ 0 (from earlier deformers in the stack) ride
- * along the rolled surface's normal, so stacks compose sanely.
- */
-declare const roll: Deformer<RollOptions>;
-
-declare const bendOptionsSchema: z.ZodObject<{
-    /** 1/radius in world units; sign flips the arc direction. 0 = flat. */
-    curvature: z.ZodDefault<z.ZodNumber>;
-    /** Bend axis direction in the sheet plane, degrees. 0 bends across x. */
-    angle: z.ZodDefault<z.ZodNumber>;
-}, "strip", z.ZodTypeAny, {
-    angle: number;
-    curvature: number;
-}, {
-    angle?: number | undefined;
-    curvature?: number | undefined;
-}>;
-type BendOptions = z.infer<typeof bendOptionsSchema>;
-/**
- * Gentle global arc around a cylinder centered on the sheet — a standing
- * paper's lean. Arc-length preserving, like roll, but symmetric about the
- * center instead of one-sided.
- *
- * Written in its cancellation-free form throughout: `r(1 − cos θ)` is
- * `2r·sin²(θ/2)`, and the in-plane shift goes through `sinMinusX`. Same arc,
- * same numbers to sixteen places — it is only the float32 half that could
- * tell the difference, and that is exactly the half the parity gate checks.
- */
-declare const bend: Deformer<BendOptions>;
-
-declare const foldOptionsSchema: z.ZodObject<{
-    /** Direction of the fold travel in the sheet plane, degrees (the crease line runs perpendicular). */
-    angle: z.ZodDefault<z.ZodNumber>;
-    /** Signed distance of the crease line from the sheet center, along the travel direction. */
-    offset: z.ZodDefault<z.ZodNumber>;
-    /** How far the flap folds over, degrees. 180 = flat against the sheet. */
-    foldAngle: z.ZodDefault<z.ZodNumber>;
-    /** Width of the soft hinge — paper never creases to a mathematical edge. */
-    radius: z.ZodDefault<z.ZodNumber>;
-}, "strip", z.ZodTypeAny, {
-    radius: number;
-    angle: number;
-    offset: number;
-    foldAngle: number;
-}, {
-    radius?: number | undefined;
-    angle?: number | undefined;
-    offset?: number | undefined;
-    foldAngle?: number | undefined;
-}>;
-type FoldOptions = z.infer<typeof foldOptionsSchema>;
-/**
- * Angular crease across a line: within the hinge width the sheet wraps a
- * small cylinder (a roll), beyond it the flap continues rigid at the full
- * fold angle. n folds = n instances stacked (half-fold, letter-fold,
- * accordion). Arc-length preserving like every Paperlab deformer.
- */
-declare const fold: Deformer<FoldOptions>;
-
-declare const waveOptionsSchema: z.ZodObject<{
-    amplitude: z.ZodDefault<z.ZodNumber>;
-    wavelength: z.ZodDefault<z.ZodNumber>;
-    /** Travel speed; 0 freezes the ripple. */
-    speed: z.ZodDefault<z.ZodNumber>;
-    /** Travel direction in the sheet plane, degrees. */
-    angle: z.ZodDefault<z.ZodNumber>;
-    /** Zero the displacement at one edge (a taped/pinned edge doesn't ripple). */
-    pinnedEdge: z.ZodDefault<z.ZodEnum<["none", "top", "bottom", "left", "right"]>>;
-}, "strip", z.ZodTypeAny, {
-    angle: number;
-    amplitude: number;
-    wavelength: number;
-    speed: number;
-    pinnedEdge: "left" | "right" | "top" | "none" | "bottom";
-}, {
-    angle?: number | undefined;
-    amplitude?: number | undefined;
-    wavelength?: number | undefined;
-    speed?: number | undefined;
-    pinnedEdge?: "left" | "right" | "top" | "none" | "bottom" | undefined;
-}>;
-type WaveOptions = z.infer<typeof waveOptionsSchema>;
-/**
- * Traveling sine displacement with a quieter second harmonic — idle flutter
- * and wind ripple. The only time-driven deformer so far: stacks containing
- * it re-deform every frame.
- */
-declare const wave: Deformer<WaveOptions>;
-
-declare const drapeOptionsSchema: z.ZodObject<{
-    /** Fold depth at the free edge, world units. */
-    amplitude: z.ZodDefault<z.ZodNumber>;
-    /** How many folds run down the drop. */
-    folds: z.ZodDefault<z.ZodNumber>;
-    /**
-     * How fast folds deepen away from the pinned edge. 1 is linear; higher
-     * holds the top flat and gathers all the movement at the free end, which
-     * is what a sheet hung from a rod actually does.
-     */
-    falloff: z.ZodDefault<z.ZodNumber>;
-    /** How much a second, non-harmonic fold breaks the regularity. */
-    irregular: z.ZodDefault<z.ZodNumber>;
-    /** How much the sheet narrows as its folds deepen. */
-    gather: z.ZodDefault<z.ZodNumber>;
-    pinnedEdge: z.ZodDefault<z.ZodEnum<["top", "bottom"]>>;
-}, "strip", z.ZodTypeAny, {
-    amplitude: number;
-    pinnedEdge: "top" | "bottom";
-    folds: number;
-    falloff: number;
-    irregular: number;
-    gather: number;
-}, {
-    amplitude?: number | undefined;
-    pinnedEdge?: "top" | "bottom" | undefined;
-    folds?: number | undefined;
-    falloff?: number | undefined;
-    irregular?: number | undefined;
-    gather?: number | undefined;
-}>;
-type DrapeOptions = z.infer<typeof drapeOptionsSchema>;
-/**
- * Hung paper: vertical folds running the length of the drop, shallow at the
- * fixed edge and deepening toward the free one.
- *
- * `wave` can put ripples on a sheet, but a traveling sine is a flag, not a
- * curtain — it kinks the sheet ACROSS its drop and it is uniform end to end.
- * Cloth hung from an edge does the opposite: the folds run WITH the drop and
- * they grow as they get further from whatever is holding the sheet up. Two
- * details do most of the work:
- *
- * - the folds are not harmonic. A pure sine reads as corrugated metal, so a
- *   second wave at an incommensurate frequency breaks the repeat.
- * - gathered paper is narrower than flat paper. Pulling the surface toward
- *   its centerline in proportion to fold depth is what stops the drape from
- *   looking like a texture painted on a rectangle.
- */
-declare const drape: Deformer<DrapeOptions>;
-
-declare const crumpleOptionsSchema: z.ZodObject<{
-    /** How crushed, 0..1. Peak-to-peak height, and it drives the pull too. */
-    amount: z.ZodDefault<z.ZodNumber>;
-    /** Facets per world unit. Higher is finer, and needs more segments to resolve. */
-    scale: z.ZodDefault<z.ZodNumber>;
-    /**
-     * How much the sheet draws in on itself. Crumpled paper occupies a smaller
-     * footprint than flat paper; without this it reads as an embossed sheet
-     * rather than a crushed one.
-     */
-    pull: z.ZodDefault<z.ZodNumber>;
-    /** A different crush of the same paper. */
-    seed: z.ZodDefault<z.ZodNumber>;
-}, "strip", z.ZodTypeAny, {
-    amount: number;
-    seed: number;
-    scale: number;
-    pull: number;
-}, {
-    amount?: number | undefined;
-    seed?: number | undefined;
-    scale?: number | undefined;
-    pull?: number | undefined;
-}>;
-type CrumpleOptions = z.infer<typeof crumpleOptionsSchema>;
-/**
- * Paper that has been handled.
- *
- * Six deformers and not one of them crushed a sheet — `wave` and `fold` were
- * the nearest and neither reads as crumpled. This is the missing primitive.
- *
- * The field is a jittered grid of cells, each pushed up or down, with the
- * height going to zero exactly on the boundary between them: `F2 − F1`, the
- * gap between the two nearest cell points, signed per cell. That vanishes on
- * every boundary, so the sheet stays continuous, and its gradient flips
- * across one — which is a crease. The result is an irregular polygonal
- * network of facets alternating toward and away from you, which is what a
- * sheet crushed in a fist actually is.
- *
- * **The normals matter more than the displacement here**, and getting there
- * took three tries worth recording. Three summed triangle waves: periodic,
- * an egg-crate. Plain distance-to-nearest (`F1`): irregular but smooth cone
- * tips, so it read as hammered metal. Only creases with a sign change across
- * them shade like paper.
- *
- * Both normal paths agree with that: the hero path averages vertex normals
- * over a dense grid, the field path probes two tangents a hundredth of a
- * sheet apart. Both need facets several segments wide.
- *
- * Cost, measured rather than assumed (`pnpm perf:field --soft`): a field of
- * these runs about four times longer per frame at ×20, and six at ×60, than
- * the same field of an undeformed preset. That ratio used to read 45%, and it
- * grew without this deformer getting one instruction slower — `'auto'` now
- * sizes the grid to the work, so the undeformed sheet it is measured against
- * went from 72 segments a side to 8 and got very cheap, while crumple keeps
- * the density its creases need. Which makes the point sharper than before:
- * almost none of this cost is geometry. It is the nine cell lookups per
- * probe, three probes deep for the normal.
- */
-declare const crumple: Deformer<CrumpleOptions>;
-
-/**
- * The shared fake-aerodynamics core (spec M6 §4): velocity-linked lift +
- * curated noise, per v0.2's "reads more real than a true sim" doctrine.
- * Pure math, no three.js, no allocation in the per-frame paths — `carry`
- * and `flight` both source their motion here.
- */
-interface AeroPose {
-    position: [number, number, number];
-    rotation: [number, number, number];
-}
-/**
- * Critically-damped spring toward a target — the carry pin's cursor
- * follow. Mutates `state` in place; returns nothing.
- */
-interface DampedValue {
-    value: number;
-    velocity: number;
-}
-declare function dampTo(state: DampedValue, target: number, smoothing: number, dt: number): void;
-/** Coherent gust factor in [1-g, 1+g] — curated, seeded, cheap. */
-declare function gust(t: number, seed: number, gustiness: number): number;
-interface FlightParams {
-    wind: [number, number, number];
-    gustiness: number;
-    tumble: number;
-    path: 'drift' | 'loop';
-    /** Exit the scene → re-enter the opposite side (drift only). */
-    respawn: boolean;
-    /** Half-extent of the drift travel before respawn wraps it. */
-    range: number;
-}
-/**
- * Free paper on the wind: the falling-leaf tumble core + a directional wind
- * vector + lift, so paper travels ACROSS, not just down. A pure function of
- * time and phase — instancing-safe, deterministic, loopable.
- */
-declare function flightPose(t: number, o: FlightParams, phase: number, pose: AeroPose): void;
-/**
- * Carry flutter drive: how much a held paper ripples for a given drag speed
- * (world units/s). Saturates — a violent drag doesn't tear the illusion.
- */
-declare function carryDrive(speed: number): number;
-
-/** A draggable 3D grab point; drags write back to behavior params. */
-interface HandleSpec<O = AnyOptions> {
-    id: string;
-    /** UV-space (0..1) anchor of the grab point on the flat sheet. */
-    anchor(o: O, sheet: SheetDims): [number, number];
-    /** Map a pointer position in sheet-local XY to option updates. */
-    drag(local: {
-        x: number;
-        y: number;
-    }, o: O, sheet: SheetDims): Partial<O>;
-}
-/**
- * A behavior is a named, curated bundle: a deformer stack + a parameter
- * mapping + optional idle loop + handles for direct manipulation. Designers
- * see 3–5 human-named params ('tightness', not 'cylinderRadius'); the stack
- * underneath is an Advanced disclosure. New behaviors are the community
- * on-ramp: ~50 lines over existing deformers.
- */
-interface Behavior<O = AnyOptions> {
-    id: string;
-    label: string;
-    defaults: O;
-    optionsSchema: z.ZodType<O, z.ZodTypeDef, unknown>;
-    /** Expand human params to the underlying deformer stack. */
-    stack(o: O, sheet: SheetDims): DeformerInstance[];
-    /** Transient, time-varying option overrides (idle motion). Never persisted. */
-    loop?(o: O, t: number): Partial<O>;
-    /**
-     * Whole-sheet motion written into `pose` each frame (allocation-free),
-     * composed after any idle preset's transform. Must be a pure function of
-     * (options, t) — the field applies it per instance with a time offset, so
-     * it has to be deterministic (flight's travel-across-the-scene).
-     */
-    transform?(o: O, t: number, pose: AeroPose): void;
-    handles?: HandleSpec<O>[];
-    /**
-     * The two or three options that ARE this behavior — the ones someone
-     * reaches for first, in the order they'd reach for them.
-     *
-     * The schema still generates a control for every option; this only says
-     * which ones get the big controls and which fold away behind "More". A
-     * behavior that nominates nothing shows all of its options flat, because
-     * the library must never hide a param it was not told to hide — silence
-     * from a community behavior is not permission to guess.
-     *
-     * Every name here has to be a field of {@link optionsSchema}; the built-in
-     * behaviors are checked for that, and for staying within three.
-     */
-    signature?: (keyof O & string)[];
-    /** The option the transport scrubber drives. */
-    progressParam: keyof O & string;
-    /** Seconds for a full 0→1 play, and how play repeats. */
-    duration: number;
-    loopMode: 'yoyo' | 'restart';
-}
-
-/** Community behaviors register here; built-ins are pre-registered. */
-declare function registerBehavior(behavior: Behavior<AnyOptions>): void;
-declare function getBehavior(id: string): Behavior<AnyOptions>;
-declare function listBehaviors(): string[];
-
-declare const peelOptionsSchema: z.ZodObject<{
-    progress: z.ZodDefault<z.ZodNumber>;
-    /** 'auto' resolves per slot in a `sheet` field (outward-facing corner); standalone it means bottom-right. */
-    corner: z.ZodDefault<z.ZodEnum<["top-left", "top-right", "bottom-left", "bottom-right", "auto"]>>;
-    /** Curl sharpness — small is a tight dog-ear, large a soft lift. */
-    radius: z.ZodDefault<z.ZodNumber>;
-}, "strip", z.ZodTypeAny, {
-    corner: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "auto";
-    radius: number;
-    progress: number;
-}, {
-    corner?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "auto" | undefined;
-    radius?: number | undefined;
-    progress?: number | undefined;
-}>;
-type PeelOptions = z.infer<typeof peelOptionsSchema>;
-/** A corner lifts and curls back — the hero-image hover peel. */
-declare const peel: Behavior<PeelOptions>;
-
-declare const unrollOptionsSchema: z.ZodObject<{
-    /** 0 = fully rolled cylinder, 1 = flat sheet. */
-    progress: z.ZodDefault<z.ZodNumber>;
-    /** How tightly the paper is wound. */
-    tightness: z.ZodDefault<z.ZodNumber>;
-    /** Idle rocking of the rolled end. */
-    sway: z.ZodDefault<z.ZodNumber>;
-}, "strip", z.ZodTypeAny, {
-    progress: number;
-    tightness: number;
-    sway: number;
-}, {
-    progress?: number | undefined;
-    tightness?: number | undefined;
-    sway?: number | undefined;
-}>;
-type UnrollOptions = z.infer<typeof unrollOptionsSchema>;
-/**
- * A receipt unrolls from the bottom: the sheet hangs flat from its top edge
- * and the remaining paper is wound in a roll at the bottom. Content bends
- * true around the roll — the reference-image requirement.
- */
-declare const unroll: Behavior<UnrollOptions>;
-
-declare const flipOptionsSchema: z.ZodObject<{
-    /** 0 = flat, 1 = page fully turned over the spine. */
-    progress: z.ZodDefault<z.ZodNumber>;
-    /** Which edge is the spine. */
-    spine: z.ZodDefault<z.ZodEnum<["left", "right"]>>;
-    /** Softness of the turning curl. */
-    radius: z.ZodDefault<z.ZodNumber>;
-}, "strip", z.ZodTypeAny, {
-    radius: number;
-    progress: number;
-    spine: "left" | "right";
-}, {
-    radius?: number | undefined;
-    progress?: number | undefined;
-    spine?: "left" | "right" | undefined;
-}>;
-type FlipOptions = z.infer<typeof flipOptionsSchema>;
-/**
- * A page turn: the free edge curls up and rolls over toward the spine —
- * the roll deformer with its boundary swept across the page.
- */
-declare const flip: Behavior<FlipOptions>;
-
-declare const letterFoldOptionsSchema: z.ZodObject<{
-    /** 0 = flat letter, 1 = fully tri-folded. */
-    progress: z.ZodDefault<z.ZodNumber>;
-    /** Softness of the two creases. */
-    crease: z.ZodDefault<z.ZodNumber>;
-}, "strip", z.ZodTypeAny, {
-    progress: number;
-    crease: number;
-}, {
-    progress?: number | undefined;
-    crease?: number | undefined;
-}>;
-type LetterFoldOptions = z.infer<typeof letterFoldOptionsSchema>;
-/**
- * The classic tri-fold: the bottom third folds up first, then the top third
- * folds down over it. Two fold deformers stacked — order is the physics.
- */
-declare const letterFold: Behavior<LetterFoldOptions>;
-
-declare const hangOptionsSchema: z.ZodObject<{
-    /** Wind strength driving the ripple. */
-    wind: z.ZodDefault<z.ZodNumber>;
-    /** Gravity bulge of the hanging sheet. */
-    sag: z.ZodDefault<z.ZodNumber>;
-}, "strip", z.ZodTypeAny, {
-    wind: number;
-    sag: number;
-}, {
-    wind?: number | undefined;
-    sag?: number | undefined;
-}>;
-type HangOptions = z.infer<typeof hangOptionsSchema>;
-/** A poster hanging from its top edge, rippling in wind. */
-declare const hang: Behavior<HangOptions>;
-
-declare const flyOptionsSchema: z.ZodObject<{
-    /** Ripple energy. */
-    flutter: z.ZodDefault<z.ZodNumber>;
-    /** Aerodynamic arc of the sheet. */
-    curve: z.ZodDefault<z.ZodNumber>;
-}, "strip", z.ZodTypeAny, {
-    flutter: number;
-    curve: number;
-}, {
-    flutter?: number | undefined;
-    curve?: number | undefined;
-}>;
-type FlyOptions = z.infer<typeof flyOptionsSchema>;
-/** A note carried on air — arched and fluttering. Pair with the `tumble` idle. */
-declare const fly: Behavior<FlyOptions>;
-
-declare const fallOptionsSchema: z.ZodObject<{
-    /** Air resistance ripple while falling. */
-    flutter: z.ZodDefault<z.ZodNumber>;
-    /** A falling sheet always lifts a corner. */
-    curl: z.ZodDefault<z.ZodNumber>;
-}, "strip", z.ZodTypeAny, {
-    curl: number;
-    flutter: number;
-}, {
-    curl?: number | undefined;
-    flutter?: number | undefined;
-}>;
-type FallOptions = z.infer<typeof fallOptionsSchema>;
-/** A dropped sheet — corner lifted, rippling. Pair with the `tumble` idle for the descent. */
-declare const fall: Behavior<FallOptions>;
-
-declare const settleOptionsSchema: z.ZodObject<{
-    /**
-     * How long ago it landed, 0..1.
-     *
-     * 0 is the instant of arrival — still carrying the shape it fell in. 1 is
-     * a sheet that has been lying there, where its own weight has flattened
-     * out everything except what its stiffness refuses to give up.
-     */
-    relax: z.ZodDefault<z.ZodNumber>;
-    /**
-     * How hard the paper resists lying flat, 0..1.
-     *
-     * This is the stock, not the pose: tissue surrenders completely, card
-     * never does. It is the whole reason a settled sheet reads as PAPER and
-     * not as a decal — at 0 the mesh is a rectangle painted on the floor.
-     */
-    lift: z.ZodDefault<z.ZodNumber>;
-    /** Which corner stayed up. */
-    corner: z.ZodDefault<z.ZodEnum<["top-left", "top-right", "bottom-left", "bottom-right"]>>;
-    /**
-     * Slack across the middle — the low, long undulation of a sheet that is
-     * touching a floor in two places and bridging between them.
-     */
-    slack: z.ZodDefault<z.ZodNumber>;
-}, "strip", z.ZodTypeAny, {
-    corner: "top-left" | "top-right" | "bottom-left" | "bottom-right";
-    relax: number;
-    lift: number;
-    slack: number;
-}, {
-    corner?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | undefined;
-    relax?: number | undefined;
-    lift?: number | undefined;
-    slack?: number | undefined;
-}>;
-type SettleOptions = z.infer<typeof settleOptionsSchema>;
-/**
- * A sheet that has landed and relaxed.
- *
- * The library could drop paper (`fall`), fly it (`fly`, `flight`), heap it
- * (`pile`) and catch it mid-air (`spill`) — and had no way at all to show a
- * sheet that has ARRIVED. Every reference installation worth copying has
- * paper on the floor: sheets settled on concrete after the fall, ribbons
- * pooling where they meet the ground. It is the most beautiful detail in the
- * set and it appears in it twice.
- *
- * The distinction from `fall` is not the shape, it is the CLOCK. `fall`
- * flutters — its wave carries `speed: 1.3`, and it is a sheet still arguing
- * with the air. This one is over. Everything here is static, and that is the
- * point: a settled sheet that ripples is a settled sheet nobody believes.
- *
- * Which is also why it composes rather than deforming: a landed sheet is a
- * gentle curl the stiffness held on to, plus a long slack undulation where
- * it bridges the floor. Both already exist, and a deformer that can be
- * spelled out of the ones we have does not earn a GLSL twin and a parity
- * case.
- */
-declare const settle: Behavior<SettleOptions>;
-
-declare const ribbonOptionsSchema: z.ZodObject<{
-    /**
-     * How much of the drop is lying on the floor, as a fraction of the height.
-     *
-     * This is the whole image. A strip that stops dead at the ground reads as
-     * a strip that was cut to fit; one that arrives with a length to spare and
-     * turns over reads as paper meeting a floor, which is the thing the
-     * reference installations are actually about.
-     */
-    pool: z.ZodDefault<z.ZodNumber>;
-    /** How tightly it turns where it lands. Low is a soft slump, high is a curl. */
-    curl: z.ZodDefault<z.ZodNumber>;
-    /** Folds running down the length. A printed strip is never a flat plane. */
-    drape: z.ZodDefault<z.ZodNumber>;
-}, "strip", z.ZodTypeAny, {
-    curl: number;
-    pool: number;
-    drape: number;
-}, {
-    curl?: number | undefined;
-    pool?: number | undefined;
-    drape?: number | undefined;
-}>;
-type RibbonOptions = z.infer<typeof ribbonOptionsSchema>;
-/**
- * A strip hung from the ceiling that reaches the floor and keeps going.
- *
- * The single most striking image in the reference set, and the reason it
- * took until now to build is that it needs three separate things that did
- * not exist a week ago: a room with a ceiling to hang from, hardware to hang
- * BY, and type that can be set down the length of a sheet without looking
- * like a caption. It is the payoff for all of them.
+ * Line breaking, shared by every content type that sets prose.
  *
- * The mathematics is not new, which is the point of the contribution ladder.
- * A ribbon is a `drape` down its length and a `fold` whose hinge sits at the
- * floor line rather than at the sheet's centre — `fold.offset` has always
- * been able to say "crease here", and nothing had ever asked it to.
- */
-declare const ribbon: Behavior<RibbonOptions>;
-
-declare const carryOptionsSchema: z.ZodObject<{
-    /**
-     * The grab point — where the pointer was on the paper at pick time.
-     * 'auto' is resolved by the carry controller (usually the peeled corner:
-     * continuity from peel → carry is the immersion moment).
-     */
-    grab: z.ZodDefault<z.ZodEnum<["top-left", "top-right", "bottom-left", "bottom-right", "auto"]>>;
-    /** From stock feel: a stamp is stiff — it flutters, it doesn't flow. */
-    stiffness: z.ZodDefault<z.ZodNumber>;
-    flutter: z.ZodDefault<z.ZodNumber>;
-    /** How far the paper's yaw trails the drag direction (runtime transform). */
-    lag: z.ZodDefault<z.ZodNumber>;
-    /** Drag-speed drive (0..1). Written live by the carry controller. */
-    drive: z.ZodDefault<z.ZodNumber>;
-}, "strip", z.ZodTypeAny, {
-    flutter: number;
-    grab: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "auto";
-    stiffness: number;
-    lag: number;
-    drive: number;
-}, {
-    flutter?: number | undefined;
-    grab?: "top-left" | "top-right" | "bottom-left" | "bottom-right" | "auto" | undefined;
-    stiffness?: number | undefined;
-    lag?: number | undefined;
-    drive?: number | undefined;
-}>;
-type CarryOptions = z.infer<typeof carryOptionsSchema>;
-/**
- * A held paper, alive from motion (spec M6 §4.1, the field/cheap path):
- * droop away from the grab point + drag-velocity flutter. The hero path —
- * cloth with a single pin following the cursor — is the existing
- * `physics: 'cloth'` grab; this behavior is what fields and exports run.
- */
-declare const carry: Behavior<CarryOptions>;
-
-declare const flightOptionsSchema: z.ZodObject<{
-    /** Directional wind vector — paper travels ACROSS the scene, not just down. */
-    wind: z.ZodDefault<z.ZodTuple<[z.ZodNumber, z.ZodNumber, z.ZodNumber], null>>;
-    gustiness: z.ZodDefault<z.ZodNumber>;
-    tumble: z.ZodDefault<z.ZodNumber>;
-    /** 'loop' is a seamless idle cycle; 'drift' travels along the wind. */
-    path: z.ZodDefault<z.ZodEnum<["drift", "loop"]>>;
-    /** Drift only: exit the scene → re-enter the opposite side. */
-    respawn: z.ZodDefault<z.ZodBoolean>;
-    /** Half-extent of the travel before respawn wraps it. */
-    range: z.ZodDefault<z.ZodNumber>;
-}, "strip", z.ZodTypeAny, {
-    path: "drift" | "loop";
-    wind: [number, number, number];
-    gustiness: number;
-    tumble: number;
-    respawn: boolean;
-    range: number;
-}, {
-    path?: "drift" | "loop" | undefined;
-    wind?: [number, number, number] | undefined;
-    gustiness?: number | undefined;
-    tumble?: number | undefined;
-    respawn?: boolean | undefined;
-    range?: number | undefined;
-}>;
-type FlightOptions = z.infer<typeof flightOptionsSchema>;
-/**
- * Untethered paper carried across the scene on the wind (spec M6 §4.2) —
- * the falling-leaf tumble core + directional travel + lift. Transform +
- * deformer based, so it's instancing-safe: a `scatter` layout + `flight`
- * idle = papers blowing through a hero section.
+ * It lives on its own because `paintText` and `paintCard` were about to
+ * carry two copies of it, and two copies of a line-breaker is two answers to
+ * "where does this wrap" — which on a sheet that CURLS is not a cosmetic
+ * disagreement: the reader sees the break land on a fold.
  */
-declare const flight: Behavior<FlightOptions>;
-
-declare const crumpleBehaviorOptionsSchema: z.ZodObject<{
-    /** 0 = flat sheet, 1 = crushed. */
-    progress: z.ZodDefault<z.ZodNumber>;
-    /** Few big facets at 0, many small ones at 1. */
-    coarseness: z.ZodDefault<z.ZodNumber>;
-    /** How far the sheet curls in on itself as it crushes. */
-    ball: z.ZodDefault<z.ZodNumber>;
-    /** A different crush of the same paper. */
-    seed: z.ZodDefault<z.ZodNumber>;
-}, "strip", z.ZodTypeAny, {
-    progress: number;
-    coarseness: number;
-    ball: number;
-    seed: number;
-}, {
-    progress?: number | undefined;
-    coarseness?: number | undefined;
-    ball?: number | undefined;
-    seed?: number | undefined;
-}>;
-type CrumpleBehaviorOptions = z.infer<typeof crumpleBehaviorOptionsSchema>;
 /**
- * A sheet being screwed up in a fist.
+ * Wrap a paragraph to a measure, breaking a word that cannot fit on its own.
  *
- * Two deformers, in this order for a reason: `crumple` reads the flat sheet
- * position to place its creases, so it has to run before anything that moves
- * the sheet around. Crush the paper, then curl the crushed paper — the other
- * way round would crease a curved sheet as if it were still flat.
- */
-declare const crumpleBehavior: Behavior<CrumpleBehaviorOptions>;
-
-declare const idleNames: readonly ["float", "tumble", "dangle", "taped", "breeze"];
-type IdleName = (typeof idleNames)[number];
-interface IdlePose {
-    /** Offsets added to the paper's base transform each frame. */
-    position: [number, number, number];
-    rotation: [number, number, number];
-}
-/**
- * Curated fake physics: hand-tuned motion presets, no simulation. Cheap
- * enough for both hero and field modes, and — for things like the
- * falling-leaf tumble — they read *more* real than a true sim.
- */
-interface IdlePreset {
-    id: IdleName;
-    label: string;
-    /** Whole-sheet motion, written into `pose` (allocation-free). */
-    transform?(t: number, pose: IdlePose): void;
-    /** Extra deformers appended after the behavior's stack. */
-    stack?(): DeformerInstance[];
-}
-declare const idlePresets: Record<IdleName, IdlePreset>;
-declare function getIdlePreset(name: IdleName): IdlePreset;
-
-/**
- * Compose a deformer stack into GLSL — the GPU twin of deformers/compose.ts.
- * Each stack entry gets its own uniform namespace (`uRoll0_angle`,
- * `uFold1_offset`, …) so the same deformer type can appear twice
- * (letter-fold is two folds). Golden-vector parity with the JS path is
- * enforced by the GPU harness test.
- */
-interface ComposedDisplacement {
-    /** Uniform declarations + displacement functions. */
-    functionsSrc: string;
-    /** `vec3 plDisplace(vec3 p, vec2 uv, float t)` applying the whole stack. */
-    displaceSrc: string;
-    /** Initial uniform values, keyed by their namespaced GLSL names (uSheet included). */
-    uniforms: Record<string, number | number[]>;
-}
-/**
- * Just the uniform VALUES for a stack (same namespaced keys as
- * buildDisplacementGLSL) — cheap enough to call every frame while a behavior
- * animates. Structure (names) is stable as long as the stack's type order is.
- */
-declare function stackUniformValues(stack: DeformerInstance[], sheet: SheetDims): Record<string, number | number[]>;
-declare function buildDisplacementGLSL(stack: DeformerInstance[], sheet: SheetDims): ComposedDisplacement;
-/**
- * The field-mode CSM vertex shader: displaced position + numerically
- * recomputed normal (two tangent probes — exact normals of an arbitrary
- * stack have no closed form).
- */
-declare function buildFieldVertexShader(composed: ComposedDisplacement): string;
-/**
- * Field fragment shader: per-instance tile from the shared content atlas on
- * the FRONT face; the BACK face renders the stock with an optional reversed
- * show-through ghost (per-paper back textures are a hero-mode feature).
- */
-declare function buildFieldFragmentShader(): string;
-
-/**
- * A layout is a pure `pose(i, n, options, phase)` function — no state, no
- * three.js. `phase` is the motion driver's continuous offset in turns
- * (0..1 = one full cycle); cyclic layouts use it, static ones ignore it.
- * Community layouts are ~30 lines.
- *
- * Every built-in names a place paper actually sits — a fanned swatch deck, a
- * slipped stack, a heap on a desk — because arrangement alone is what makes a
- * field read as a photo carousel instead of as paper. The other half of that
- * is `bias`: paper in the world does not all bend alike.
- */
-interface PaperPose {
-    position: [number, number, number];
-    rotation: [number, number, number];
-    scale: number;
-    /**
-     * How strongly this sheet takes the field's deformation: 1 = exactly as the
-     * preset configures it, 0 = flat. Lets one instanced draw call curl the top
-     * of a pile while the sheets pressed underneath stay flat. Omitted = 1.
-     */
-    bias?: number;
-}
-interface Layout<O = Record<string, unknown>> {
-    id: string;
-    label: string;
-    defaults: O;
-    optionsSchema: z.ZodType<O, z.ZodTypeDef, unknown>;
-    /**
-     * `sheet` is the field's paper size. Layouts that arrange by CONTACT —
-     * edges meeting, sheets resting on each other — cannot work without it,
-     * and a layout that ignores it may simply omit the parameter.
-     */
-    pose(i: number, n: number, o: O, phase: number, sheet: SheetDims): PaperPose;
-    /**
-     * Where along a walk this layout put each paper, as normalized arc length,
-     * in the layout's own index order.
-     *
-     * Only layouts that arrange along a PATH can answer, which is why it is
-     * optional. Stage mode uses it to let a viewer step from one paper to the
-     * next: the stops have to be where the paper actually is, and the only
-     * thing that knows that is the function that placed it.
-     */
-    walkStops?(n: number, o: O): number[];
-}
-declare const ringSchema: z.ZodObject<{
-    radius: z.ZodDefault<z.ZodNumber>;
-    tiltDeg: z.ZodDefault<z.ZodNumber>;
-}, "strip", z.ZodTypeAny, {
-    radius: number;
-    tiltDeg: number;
-}, {
-    radius?: number | undefined;
-    tiltDeg?: number | undefined;
-}>;
-/** Prints pegged around a circle — the one carousel worth keeping. */
-declare const ring: Layout<z.infer<typeof ringSchema>>;
-declare const fanSchema: z.ZodObject<{
-    /** Total angular sweep from the first sheet to the last, degrees. */
-    sweep: z.ZodDefault<z.ZodNumber>;
-    /** Where the shared pin sits, in half-sheet-heights below center. 1 = the bottom edge. */
-    hinge: z.ZodDefault<z.ZodNumber>;
-    /** Thickness step so the sheets stack in order instead of z-fighting. */
-    lift: z.ZodDefault<z.ZodNumber>;
-    /** How much flatter the middle of the fan sits than its outer sheets. */
-    bow: z.ZodDefault<z.ZodNumber>;
-}, "strip", z.ZodTypeAny, {
-    lift: number;
-    sweep: number;
-    hinge: number;
-    bow: number;
-}, {
-    lift?: number | undefined;
-    sweep?: number | undefined;
-    hinge?: number | undefined;
-    bow?: number | undefined;
-}>;
-/**
- * A Pantone deck, a paint-chip book, a hand of cards: every sheet pinned at
- * one shared point and swung open. The sheets nearest the outside of the
- * sweep carry the most curl, which is what sells the hinge as a hinge.
- */
-declare const fan: Layout<z.infer<typeof fanSchema>>;
-declare const spreadSchema: z.ZodObject<{
-    /** How far each sheet slides past the one below it. */
-    slip: z.ZodDefault<z.ZodNumber>;
-    /** Direction of the slide, degrees. 0 slides right, 90 slides up. */
-    angle: z.ZodDefault<z.ZodNumber>;
-    lift: z.ZodDefault<z.ZodNumber>;
-    /** How much more the sheets at the far end of the slide bow. */
-    bow: z.ZodDefault<z.ZodNumber>;
-    /** Nothing hand-slid is perfectly square — a touch of per-sheet rotation. */
-    drift: z.ZodDefault<z.ZodNumber>;
-}, "strip", z.ZodTypeAny, {
-    drift: number;
-    angle: number;
-    lift: number;
-    bow: number;
-    slip: number;
-}, {
-    drift?: number | undefined;
-    angle?: number | undefined;
-    lift?: number | undefined;
-    bow?: number | undefined;
-    slip?: number | undefined;
-}>;
-/**
- * A ream pushed sideways, or a deck dealt across a table: parallel sheets at
- * a constant offset, each one bowing a little more as it comes free of the
- * stack's weight.
- */
-declare const spread: Layout<z.infer<typeof spreadSchema>>;
-declare const pileSchema: z.ZodObject<{
-    /** How far sheets wander from the center of the heap. */
-    scatter: z.ZodDefault<z.ZodNumber>;
-    /** Widest angle a sheet sits off square, degrees. */
-    turn: z.ZodDefault<z.ZodNumber>;
-    lift: z.ZodDefault<z.ZodNumber>;
-    /** How flat the sheets underneath are pressed by the ones on top. */
-    press: z.ZodDefault<z.ZodNumber>;
-    seed: z.ZodDefault<z.ZodNumber>;
-}, "strip", z.ZodTypeAny, {
-    seed: number;
-    lift: number;
-    scatter: number;
-    turn: number;
-    press: number;
-}, {
-    seed?: number | undefined;
-    lift?: number | undefined;
-    scatter?: number | undefined;
-    turn?: number | undefined;
-    press?: number | undefined;
-}>;
-/**
- * The heap on a desk. The physical tell no parametric curve can fake: sheets
- * rest ON each other, so only the top of the pile keeps its curl and
- * everything below is pressed flat by the weight above it.
- */
-declare const pile: Layout<z.infer<typeof pileSchema>>;
-declare const wallSchema: z.ZodObject<{
-    gapX: z.ZodDefault<z.ZodNumber>;
-    gapY: z.ZodDefault<z.ZodNumber>;
-    jitterAmt: z.ZodDefault<z.ZodNumber>;
-    /** Spread of sag across the wall — no two pinned sheets hang alike. */
-    sag: z.ZodDefault<z.ZodNumber>;
-}, "strip", z.ZodTypeAny, {
-    sag: number;
-    gapX: number;
-    gapY: number;
-    jitterAmt: number;
-}, {
-    sag?: number | undefined;
-    gapX?: number | undefined;
-    gapY?: number | undefined;
-    jitterAmt?: number | undefined;
-}>;
-/** A studio wall of pinned sheets: a grid, but nothing hangs quite square. */
-declare const wall: Layout<z.infer<typeof wallSchema>>;
-declare const spillSchema: z.ZodObject<{
-    spreadX: z.ZodDefault<z.ZodNumber>;
-    spreadY: z.ZodDefault<z.ZodNumber>;
-    depth: z.ZodDefault<z.ZodNumber>;
-    /** How far sheets pitch and roll out of the picture plane. */
-    tumble: z.ZodDefault<z.ZodNumber>;
-    /** Spread of bend across the sheets — a spill does not fold them alike. */
-    vary: z.ZodDefault<z.ZodNumber>;
-    seed: z.ZodDefault<z.ZodNumber>;
-}, "strip", z.ZodTypeAny, {
-    tumble: number;
-    seed: number;
-    spreadX: number;
-    spreadY: number;
-    depth: number;
-    vary: number;
-}, {
-    tumble?: number | undefined;
-    seed?: number | undefined;
-    spreadX?: number | undefined;
-    spreadY?: number | undefined;
-    depth?: number | undefined;
-    vary?: number | undefined;
-}>;
-/**
- * A dropped folder's worth of paper, mid-air — what a `pile` looks like the
- * moment before it settles. Loose in all three axes, and (the part that
- * separates it from confetti) every sheet caught at its own angle AND its
- * own amount of bend.
- */
-declare const spill: Layout<z.infer<typeof spillSchema>>;
-declare const sweepSchema: z.ZodObject<{
-    columns: z.ZodDefault<z.ZodNumber>;
-    /** Breathing room around each specimen. */
-    gap: z.ZodDefault<z.ZodNumber>;
-    /** Deformation at the first specimen and at the last. */
-    from: z.ZodDefault<z.ZodNumber>;
-    to: z.ZodDefault<z.ZodNumber>;
-}, "strip", z.ZodTypeAny, {
-    columns: number;
-    gap: number;
-    from: number;
-    to: number;
-}, {
-    columns?: number | undefined;
-    gap?: number | undefined;
-    from?: number | undefined;
-    to?: number | undefined;
-}>;
-/**
- * A specimen chart: the same sheet mounted in a grid, its deformation ramped
- * across the series so one image shows a curl at ten stages instead of one.
- * The layout the rest of this library exists to make possible — and the one
- * that documents every deformer for free.
- *
- * Only as legible as the preset it charts: a sheet with no behavior or
- * deformers has nothing for the ramp to scale, and every specimen comes out
- * identical.
- */
-declare const sweep: Layout<z.infer<typeof sweepSchema>>;
-declare const bookSchema: z.ZodObject<{
-    /** How far the outermost page lifts off the block, degrees. */
-    spread: z.ZodDefault<z.ZodNumber>;
-    /** Fraction of the pages bound to the left. 0 = a one-sided sample book. */
-    split: z.ZodDefault<z.ZodNumber>;
-    /** Page thickness — the gap between pages of one block. */
-    lift: z.ZodDefault<z.ZodNumber>;
-    /** How much more a lifted page arcs than one lying flat in the block. */
-    gutter: z.ZodDefault<z.ZodNumber>;
-}, "strip", z.ZodTypeAny, {
-    lift: number;
-    split: number;
-    gutter: number;
-    spread: number;
-}, {
-    lift?: number | undefined;
-    split?: number | undefined;
-    gutter?: number | undefined;
-    spread?: number | undefined;
-}>;
-/**
- * An open codex: pages hinged on a shared spine, each block splaying away
- * from the gutter. `split` slides it between the two bound forms paper takes
- * — 0.5 is a book lying open, 0 is a swatch deck or sample book bound down
- * one side. Pages lying flat in the block are pressed by the ones above;
- * only the lifted pages keep their arc.
- */
-declare const book: Layout<z.infer<typeof bookSchema>>;
-declare const accordionSchema: z.ZodObject<{
-    /** How far each panel tilts off the strip's line, degrees. 0 = flat, 90 = shut. */
-    angle: z.ZodDefault<z.ZodNumber>;
-    /** A concertina holds its creases — how much bow the panels keep. */
-    slack: z.ZodDefault<z.ZodNumber>;
-}, "strip", z.ZodTypeAny, {
-    angle: number;
-    slack: number;
-}, {
-    angle?: number | undefined;
-    slack?: number | undefined;
-}>;
-/**
- * A concertina: panels alternating about creases they genuinely share, so
- * the sheets read as ONE folded strip rather than as N separate papers —
- * the only layout here where that is true. Adjacent edges are solved to
- * meet, which is why it needs the sheet's real width.
- */
-declare const accordion: Layout<z.infer<typeof accordionSchema>>;
-declare const rackSchema: z.ZodObject<{
-    /** Gap along the row, as a fraction of the paper's width. Under 1 they overlap. */
-    spacing: z.ZodDefault<z.ZodNumber>;
-    /** How far a sheet leans back off vertical, degrees. */
-    lean: z.ZodDefault<z.ZodNumber>;
-    /** How much that lean differs sheet to sheet — nothing propped is uniform. */
-    vary: z.ZodDefault<z.ZodNumber>;
-    /** Small rotations off square. */
-    sway: z.ZodDefault<z.ZodNumber>;
-    seed: z.ZodDefault<z.ZodNumber>;
-}, "strip", z.ZodTypeAny, {
-    sway: number;
-    seed: number;
-    spacing: number;
-    vary: number;
-    lean: number;
-}, {
-    sway?: number | undefined;
-    seed?: number | undefined;
-    spacing?: number | undefined;
-    vary?: number | undefined;
-    lean?: number | undefined;
-}>;
-/**
- * Prints stood in a row and leaning back — against a wall, in a rack, propped
- * along a shelf. The one arrangement here that RESTS on a surface rather than
- * floating: every sheet pivots on the bottom edge it actually stands on, so
- * the row shares a floor. The further a sheet has leaned, the more it bows
- * under its own weight.
- *
- * (Stacking these front-to-back the way a letter tray really holds paper is
- * physically honest and visually useless — the front sheet hides the rest.
- * A row is the arrangement you can actually see.)
- */
-declare const rack: Layout<z.infer<typeof rackSchema>>;
-declare const colonnadeSchema: z.ZodObject<{
-    /** The walk the colonnade is built along — see `stage/path`. */
-    path: z.ZodDefault<z.ZodObject<{
-        points: z.ZodDefault<z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>, "many">>;
-        closed: z.ZodDefault<z.ZodBoolean>;
-    }, "strip", z.ZodTypeAny, {
-        points: [number, number][];
-        closed: boolean;
-    }, {
-        points?: [number, number][] | undefined;
-        closed?: boolean | undefined;
-    }>>;
-    /** Half-width of the clear aisle: how far each banner stands off the walk line. */
-    aisle: z.ZodDefault<z.ZodNumber>;
-    /** How much that gap opens and closes along the walk. Nothing hung by hand is a corridor. */
-    breathe: z.ZodDefault<z.ZodNumber>;
-    /** Widest angle a banner turns off square to the aisle, degrees. */
-    twist: z.ZodDefault<z.ZodNumber>;
-    /** Fraction of the walk left clear at each end, so the figure has somewhere to enter from. */
-    margin: z.ZodDefault<z.ZodNumber>;
-    /** Spread of banner heights, 0..1. */
-    rise: z.ZodDefault<z.ZodNumber>;
-    /**
-     * How far the banners lift off the floor, as a fraction of their height.
-     *
-     * NEGATIVE is allowed, and it is what pooling actually requires. At 0 a
-     * banner's bottom EDGE sits on the floor — which is not the same as paper
-     * pooling on it, however much the old comment here claimed otherwise. A
-     * ribbon creases a pool-length above its bottom edge, so it has to hang
-     * that much lower for the crease to land on the ground and the slack to
-     * lie ON it rather than in mid-air parallel to it.
-     *
-     * The bound used to be 0, so the one thing this option documented itself
-     * as doing was the one thing it could not do.
-     */
-    hover: z.ZodDefault<z.ZodNumber>;
-    /** Spread of deformation — no two lengths of hung paper drape alike. */
-    drape: z.ZodDefault<z.ZodNumber>;
-    seed: z.ZodDefault<z.ZodNumber>;
-}, "strip", z.ZodTypeAny, {
-    path: {
-        points: [number, number][];
-        closed: boolean;
-    };
-    seed: number;
-    drape: number;
-    hover: number;
-    margin: number;
-    twist: number;
-    aisle: number;
-    breathe: number;
-    rise: number;
-}, {
-    path?: {
-        points?: [number, number][] | undefined;
-        closed?: boolean | undefined;
-    } | undefined;
-    seed?: number | undefined;
-    drape?: number | undefined;
-    hover?: number | undefined;
-    margin?: number | undefined;
-    twist?: number | undefined;
-    aisle?: number | undefined;
-    breathe?: number | undefined;
-    rise?: number | undefined;
-}>;
-declare const colonnade: Layout<z.infer<typeof colonnadeSchema>>;
-/**
- * A block of stamps: flat rows × columns grid in register, floating a hair
- * above the (field-rendered) backing sheet. Standard layout contract — it
- * also works standalone as a plain grid; `backing`/`backingMargin` are read
- * by the field renderer, not by `pose`.
- */
-declare const sheet: Layout<SheetLayoutOptions>;
-declare function registerLayout(layout: Layout<AnyOptions>): void;
-declare function getLayout(id: string): Layout<AnyOptions>;
-declare function listLayouts(): string[];
-
-/**
- * Framing a field is arithmetic, not guesswork: layouts are pure `pose`
- * functions, so we can just ask one where all its sheets are and put the
- * camera where they all fit. Community layouts get framed for free.
- */
-interface FieldBounds {
-    center: [number, number, number];
-    /** Half-extents — the box reaches `center ± half`. */
-    half: [number, number, number];
-}
-/**
- * The box `n` sheets occupy under a layout. Each sheet is treated as a ball
- * of its half-diagonal, which covers every rotation the pose can apply
- * without having to build the pose matrices.
- */
-declare function fieldBounds(layout: Layout<AnyOptions>, n: number, options: unknown, sheet: SheetDims): FieldBounds;
-/**
- * Where to put a perspective camera so every sheet a layout poses lands in
- * frame. Solved per sheet at its own depth rather than against the field's
- * bounding box: a `ring`'s widest sheets sit at mid-depth, and pretending
- * that width exists at the near face would shove the camera far enough back
- * to lose the gallery entirely.
- */
-declare function fitCamera(layout: Layout<AnyOptions>, n: number, options: unknown, sheet: SheetDims, fovDeg: number, aspect: number, margin?: number): {
-    position: [number, number, number];
-    target: [number, number, number];
-};
-
-/** How much of the incident key light a fully translucent sheet passes on. */
-declare const TRANSMISSION_GAIN = 0.5;
-interface TranslucencyValues {
-    translucency: number;
-    /** Unit world direction from the scene toward the key light. */
-    direction: THREE.Vector3;
-    color: THREE.Color;
-    /** Light the room passes through the sheet from every direction at once. */
-    ambient: number;
-}
-/**
- * Resolve the transmission uniforms from the paper and the scene's lighting
- * — the key light's own position and color, so translucency can never
- * disagree with the lamp casting the shadows.
- *
- * It takes a resolved rig as well as a name because a rig is no longer
- * always a preset: once the light can be moved, the lamp this sheet is
- * backlit by is the one the SCENE ended up with, not the one the paper was
- * authored against.
- */
-declare function translucencyValues(translucency: number, lighting: LightingName | LightingPreset): TranslucencyValues;
-/** Ready-to-bind uniform objects for a shader program. */
-declare function translucencyUniforms(translucency: number, lighting: LightingName | LightingPreset): Record<string, {
-    value: unknown;
-}>;
-
-/**
- * A stock is a named bundle of material + geometry defaults — choosing paper
- * at a print shop. Individual controls always override; schema-wise these are
- * just defaults.
- */
-interface Stock {
-    id: StockName;
-    label: string;
-    /** Base tint, also used as the canvas background behind content. */
-    color: string;
-    roughness: number;
-    /** 0 = opaque. Vellum is translucent. */
-    opacity: number;
-    /**
-     * How much light passes THROUGH the sheet when something is behind it,
-     * 0..1. Distinct from `opacity`: newsprint is fully opaque to look at and
-     * still glows on a lightbox. This is what makes a backlit banner read.
-     */
-    translucency: number;
-    /** Ink multiply tint for content drawn on this stock (thermal prints grey-black). */
-    inkColor: string;
-    /** Thermal-printer banding intensity baked into the grain effect. */
-    banding: number;
-    /** Surface effects this stock ships with; explicit surface config overrides per key. */
-    defaultSurface: {
-        grain?: number;
-        aging?: number;
-    };
-    /** Reversed front-content ghost on the backside (thin stocks let ink show). */
-    showThrough: number;
-    /** Glossy near-white glue underside (stickers) — forces showThrough 0. */
-    adhesive: boolean;
-}
-declare const stocks: Record<StockName, Stock>;
-declare function getStock(name: StockName): Stock;
-
-/**
- * Grid shape for `count` tiles of a given aspect (height / width).
- *
- * Square tiles want a square grid, but a stage banner is 5.7 times taller
- * than it is wide, and packing those into a square GRID makes an atlas five
- * times taller than it is wide — which then has to be squashed to fit the
- * texture budget, and the content with it. Choosing cols/rows ≈ aspect keeps
- * the atlas itself roughly square whatever shape the paper is.
- */
-declare function atlasGrid(count: number, aspect?: number): {
-    cols: number;
-    rows: number;
-};
-interface ContentAtlas {
-    texture: THREE.CanvasTexture;
-    cols: number;
-    rows: number;
-}
-declare function useContentAtlas(contents: ContentConfig[], sheet: SheetConfig, stock: Stock): ContentAtlas | null;
-
-/** highp float + sin/cos implementation differences across GPUs. */
-declare const PARITY_EPSILON = 0.0005;
-interface ParityCase {
-    name: string;
-    stack: DeformerInstance[];
-    sheet: SheetDims;
-    t: number;
-}
-interface ParityResult {
-    name: string;
-    maxError: number;
-    pass: boolean;
-}
-/** One case per deformer feature worth guarding, both easy and adversarial. */
-declare const parityCases: ParityCase[];
-/** Run every parity case. Requires a WebGL2 context with float render targets. */
-declare function runParityHarness(canvas?: HTMLCanvasElement): ParityResult[];
-
-type PinMode = 'top-edge' | 'top-corners' | 'corner' | 'none';
-interface ClothParams {
-    /** Bend-spring strength: 1 = crisp paper, 0 = silk. Fabric mode falls out for free. */
-    stiffness: number;
-    gravity: number;
-    wind: number;
-    /** Local-space y of the ground plane; particles settle onto it. */
-    floor: number;
-}
-/**
- * Verlet mass-spring grid on the sheet's own vertices — structural + shear +
- * bend springs, pins as the interface, wind as a force field, fixed timestep
- * with substeps, sleep when kinetic energy is negligible.
- *
- * Constraint (enforced in the schema): cloth OWNS vertex positions — a paper
- * runs a behavior (deformer stack) OR cloth, never both. Pure JS, no three
- * dependency: the PaperMesh adapter copies `positions` into the geometry.
- */
-declare class ClothSim {
-    readonly cols: number;
-    readonly rows: number;
-    readonly count: number;
-    readonly positions: Float32Array;
-    private readonly prev;
-    private readonly pinned;
-    private readonly pinTargets;
-    private readonly constraints;
-    private params;
-    private time;
-    private accumulator;
-    private stillFrames;
-    private grabbedIndex;
-    /** True when the sim has settled and steps are skipped. */
-    asleep: boolean;
-    constructor(cols: number, rows: number, width: number, height: number, pins: PinMode, params: ClothParams);
-    setParams(params: Partial<ClothParams>): void;
-    wake(): void;
-    /** Nearest particle to a local-space point — the grab interface. */
-    grabNearest(x: number, y: number, z: number): number;
-    moveGrab(x: number, y: number, z: number): void;
-    release(): void;
-    step(delta: number): void;
-    private substep;
-}
-
-/**
- * Surface effects are fragment-side chunks composed into ONE shader program
- * per effect set (grain + deckle + aging = one program). Uniforms are
- * namespaced per effect; shared helpers (noise) are included once.
- */
-interface ComposedSurface {
-    /** Distinguishes shader *structures* — same key ⇒ same program, only uniforms change. */
-    structureKey: string;
-    vertexShader: string;
-    fragmentShader: string;
-    uniforms: Record<string, {
-        value: unknown;
-    }>;
-    /** Deckle discards via alphaTest (not blending) so shadows stay correct. */
-    alphaTest: number;
-}
-/** Which content textures exist — part of the shader structure. */
-interface SurfaceMaps {
-    hasFrontMap: boolean;
-    hasBackMap: boolean;
-}
-/**
- * Compose the enabled effects into one program. The shader owns the base
- * color entirely: the FRONT face samples the content texture, the BACK face
- * renders the stock (or content.back) with an optional reversed show-through
- * ghost — a single DoubleSide map would mirror the front content onto the
- * back, which real paper doesn't do.
- */
-declare function composeSurface(surface: SurfaceConfig, stock: Stock, thickness: number, maps?: SurfaceMaps, 
-/** World dims — perforation holes are sized in world units. */
-sheet?: {
-    width: number;
-    height: number;
-}, 
-/** Whose key light transmission is measured against — a preset name or the scene's resolved rig. */
-lighting?: LightingName | LightingPreset): ComposedSurface;
-
-interface PaperMaterialProps {
-    stock: Stock;
-    texture: THREE.Texture | null;
-    /** content.back rendered on the reverse side (stock color otherwise). */
-    backTexture?: THREE.Texture | null;
-    surface: SurfaceConfig;
-    thickness: number;
-    /** World dims — perforation holes are sized in world units. */
-    sheet?: {
-        width: number;
-        height: number;
-    };
-    /**
-     * Scene lighting — transmission is measured against its key light. A
-     * `<LightRig>` above this material wins over it: in a stage the paper is
-     * lit by the hall, not by the preset it was authored with.
-     */
-    lighting?: LightingName;
-}
-/**
- * The paper's skin: MeshStandardMaterial (real lighting preserved) extended
- * with the composed surface-effect chunks. Content textures are sampled by
- * OUR fragment (not material.map) so front and back faces can differ — real
- * paper doesn't mirror its front through the sheet. Programs rebuild only
- * on structure change; value edits mutate uniforms in place.
- */
-declare function PaperMaterial({ stock, texture, backTexture, surface, thickness, sheet, lighting, }: PaperMaterialProps): react.JSX.Element;
-
-type ReceiptContent = Extract<ContentConfig, {
-    type: 'receipt';
-}>;
-interface ReceiptTotals {
-    subtotal: number;
-    tax: number;
-    total: number;
-}
-declare function receiptTotals(content: ReceiptContent): ReceiptTotals;
-/** Deterministic bar widths from a string — stylized Code-128 look. */
-declare function barcodeBars(seed: string): number[];
-
-type CardContent = Extract<ContentConfig, {
-    type: 'card';
-}>;
-
-/**
- * Line breaking, shared by every content type that sets prose.
- *
- * It lives on its own because `paintText` and `paintCard` were about to
- * carry two copies of it, and two copies of a line-breaker is two answers to
- * "where does this wrap" — which on a sheet that CURLS is not a cosmetic
- * disagreement: the reader sees the break land on a fold.
- */
-/**
- * Wrap a paragraph to a measure, breaking a word that cannot fit on its own.
- *
- * The last clause is the part the old loop got wrong. It appended a word
- * whenever the line was empty, on the reasonable theory that one word always
- * fits — but a long URL or a compound on a narrow banner does not, and it
- * ran off the edge of the sheet with nothing to stop it. A sheet is a
- * physical object: type that leaves it has left it.
+ * The last clause is the part the old loop got wrong. It appended a word
+ * whenever the line was empty, on the reasonable theory that one word always
+ * fits — but a long URL or a compound on a narrow banner does not, and it
+ * ran off the edge of the sheet with nothing to stop it. A sheet is a
+ * physical object: type that leaves it has left it.
  */
 declare function wrapLines(ctx: CanvasRenderingContext2D, text: string, maxWidth: number, font: string): string[];
 
-/**
- * Deep-merge preset config with prop overrides (overrides win; arrays and
- * discriminated unions replace wholesale, plain objects merge).
- *
- * Lives in its own module (not serialize.ts) because the schema needs it to
- * validate state overrides — schema → serialize would be circular.
- */
-declare function mergeConfig<T>(base: T, override: unknown): T;
-/**
- * Like {@link mergeConfig}, but an explicit `undefined` DELETES its key instead
- * of being ignored — the semantics a BASE-config write needs: structural
- * setters can clear `behavior`/`deformers` or toggle a surface effect off.
- * Discriminated unions (differing `type`) still replace wholesale.
- */
-declare function mergeWithDeletes<T>(base: T, patch: unknown): T;
-
-/** Parse anything preset-shaped (object or JSON string) into a full, defaulted config. */
-declare function parsePreset(input: PaperConfigInput | string): PaperConfig;
-/** Serialize a config to `.paper` JSON. */
-declare function serializePreset(config: PaperConfig): string;
-
-/** The minimal PaperConfigInput that parses back to `config`. */
-declare function diffConfig(config: PaperConfig): PaperConfigInput;
-/**
- * A plain `<Paper />` snippet with only the non-default props — the
- * secondary export for people who read code.
- */
-declare function buildJsxSnippet(config: PaperConfig): string;
-
-/**
- * The primary export consumer is a coding agent; the human is the courier.
- * This template IS product surface: versioned, snapshot-tested, regenerated
- * from the config. Anatomy is fixed — install → inlined code → placement
- * contract → a verification step the agent can self-check → pre-empted
- * failure modes.
- */
-/**
- * v2: field exports (multi-preset galleries with inlined preset consts).
- * v3: interaction states, sheet/backing fields, drop zones, carry/flight.
- */
-declare const AGENT_PAYLOAD_VERSION = 3;
-/** One line an agent can verify against what it sees after `npm run dev`. */
-declare function describeConfig(config: PaperConfig): string;
-/** The self-contained integration brief — one paste into a coding agent. */
-declare function buildAgentPayload(config: PaperConfig): string;
-
-/**
- * Field-mode export. Every preset a field references is INLINED as a const —
- * receivers don't have the sender's local preset library. Same fixed payload
- * anatomy as the single-paper export, same version.
- */
-interface FieldExportPaper {
-    /** Display name of the preset this slot uses (const naming + description). */
-    presetName: string;
-    /** The RESOLVED preset config (user presets included — nothing to fetch). */
-    preset: PaperConfig;
-    content?: ContentConfig;
-    /** Per-slot state overrides (slot 3's hover deeper than slot 4's). */
-    states?: PaperStatesInput;
-}
-interface FieldExportZone {
-    id: string;
-    accept?: string[];
-    bounds: {
-        position: [number, number, number];
-        size: [number, number];
-    };
-    highlight?: 'none' | 'glow' | 'outline';
-}
-interface FieldExportInput {
-    layout: string;
-    layoutOptions?: Record<string, unknown>;
-    motion?: {
-        driver?: 'autoplay' | 'drag' | 'none';
-        speed?: number;
-    };
-    entrance?: {
-        type?: 'rise' | 'scatter' | 'none';
-        stagger?: number;
-        duration?: number;
-    };
-    papers: FieldExportPaper[];
-    /** Drop zones — exported as `<DropZone>` children with an onPlace stub. */
-    zones?: FieldExportZone[];
-}
-interface DistinctPreset {
-    varName: string;
-    presetName: string;
-    preset: PaperConfig;
-}
-/** Distinct presets in slot order, with collision-safe const names. */
-declare function distinctFieldPresets(input: FieldExportInput): DistinctPreset[];
-/** The layout/motion/entrance props of the export, defaults stripped. */
-declare function diffFieldProps(input: FieldExportInput): Record<string, unknown>;
-/** The one-line visual an agent verifies after `npm run dev`. */
-declare function describeFieldConfig(input: FieldExportInput): string;
-/** Component source shared by the JSX snippet and the agent payload. */
-declare function buildFieldComponentSource(input: FieldExportInput): string;
-/** The self-contained field integration brief — one paste into a coding agent. */
-declare function buildFieldAgentPayload(input: FieldExportInput): string;
-
-/**
- * Accessibility layer: reduced-motion handling, a hidden DOM mirror so the
- * paper's content exists for screen readers and find-in-page, and a no-WebGL
- * DOM fallback.
- */
-declare function usePrefersReducedMotion(override?: boolean): boolean;
-declare function supportsWebGL(): boolean;
-/** Human-readable text equivalent of a paper's content. */
-declare function contentText(config: PaperConfig): string;
-/** Hidden DOM twin of the 3D paper — screen readers read it, ctrl-F finds it. */
-declare function PaperMirror({ config }: {
-    config: PaperConfig;
-}): react.JSX.Element;
-/** No WebGL: the paper renders flat — content on a stock-tinted card. */
-declare function PaperFallback({ config }: {
-    config: PaperConfig;
-}): react.JSX.Element;
-
-/**
- * Stop-motion feel: quantize continuous time to animation "twos"
- * (12 steps per second, like shooting on twos at 24fps). Applies to
- * deformer time, idle motion, and behavior progress; the camera is
- * excluded by default — quantized cameras read as jank, not craft.
- */
-declare const ON_TWOS_FPS = 12;
-declare function quantizeTime(t: number, fps?: number): number;
-/** Snap a 0..1 progress that plays over `duration` seconds to whole frames. */
-declare function quantizeProgress(p: number, duration: number, fps?: number): number;
-
-declare function getPreset(name: string): PaperConfig;
-/** Register a user preset (validated). Built-in names are reserved. */
-declare function registerPreset(name: string, input: PaperConfigInput): void;
-declare function unregisterPreset(name: string): void;
-declare function isBuiltinPreset(name: string): boolean;
-declare function listPresets(): string[];
-/**
- * A collision-free preset name built from `base`: `base`, else `base 2`,
- * `base 3`, … The disambiguating suffix always grows from the SAME base — a
- * name derived from a synthetic base (e.g. an untitled import → "imported")
- * must not fall back to the original when it collides. `taken` reports whether
- * a candidate is already used (built-in or user preset).
- */
-declare function uniquePresetName(base: string, taken: (name: string) => boolean): string;
-
-/**
- * Resolve the subdivision grid for a sheet.
- *
- * `minSegments` is the correctness floor the active deformers require, and it
- * applies however `segments` is set. `autoSegments` is what those deformers
- * WANT for the options they are carrying, and it is what `'auto'` resolves
- * to — see `stackAutoSegments` and `core/tessellation.ts`.
- *
- * Both are per axis, because a demand is a demand along a DIRECTION. A
- * banner draped in folds across its width needs those folds resolved across
- * and needs almost nothing down its drop; a single number spread by aspect
- * ratio gives the drop the density and the folds the leftovers, which is
- * both the expensive answer and the wrong-looking one. A bare number is
- * still accepted and still means "this many, both ways".
- *
- * `'auto'` used to hand the long side a flat 72 whatever was on the sheet, so
- * a blank page was tessellated exactly as finely as a crumpled one and every
- * `minSegments` in the library was dead weight — nothing could ever raise a
- * grid that already started at the highest value anyone asked for. It now
- * sizes to the work, quantized onto a ladder so that dragging a slider does
- * not rebuild the mesh.
- *
- * Omitting `autoSegments` keeps the old flat 72, which is what a caller with
- * no deformer stack in hand should get — this helper is exported, and its
- * answer to an unchanged call should not have changed.
- */
-declare function resolveSegments(sheet: SheetConfig, minSegments?: number | SegmentPair, autoSegments?: number | SegmentPair): [number, number];
-/**
- * Geometry factory. The sheet lives in its local XY plane, centered on the
- * origin, facing +Z. Deformers displace these vertices; the base (flat)
- * positions are kept by the caller for re-deformation each frame.
- */
-declare function createSheetGeometry(sheet: SheetConfig, minSegments?: number | SegmentPair, autoSegments?: number | SegmentPair): THREE.PlaneGeometry;
-
-type PaperMode = 'hero' | 'field';
-type PaperModeRequest = PaperMode | 'auto';
-interface ModeContext {
-    interactive: boolean;
-    physics: string;
-    count: number;
-}
-/**
- * Hero mode: deformer stack runs in JS on the CPU, writing BufferGeometry
- * positions (correct raycasting, shadows, physics, handle drags).
- * Field mode: composed GLSL vertex chunks, instanced (galleries, 10+ sheets).
- * The same preset JSON drives both.
- */
-declare function resolveMode(requested: PaperModeRequest, ctx: ModeContext): PaperMode;
-
-export { AGENT_PAYLOAD_VERSION, AUTO_CEILING, type AeroPose, type BackingDrawSpec, type Behavior, BehaviorConfigInput, type BendOptions, type CardContent, type CarryOptions, type ClothParams, ClothSim, type ComposedDisplacement, type ComposedSurface, type ContentAtlas, ContentConfig, ContentConfigInput, type CrumpleBehaviorOptions, type CrumpleOptions, type CurlOptions, type DampedValue, type Deformer, type DeformerContext, type DeformerInstance, DeformerInstanceConfigInput, type DrapeOptions, DropZone, type DropZoneConfig, type DropZoneProps, DropZoneRegistry, FLAT_SEGMENTS, type FallOptions, type FieldA11yController, type FieldBounds, type FieldExportInput, type FieldExportPaper, type FieldExportZone, FieldPaperSlot, FilmName, type FlightOptions, type FlightParams, type FlipOptions, type FlyOptions, type FoldOptions, type HandleSpec, type HangOptions, type IdleName, type IdlePreset, type KeyboardCarry, type KeyboardStepResult, type Layout, type LetterFoldOptions, type LightAngles, type LightOverrides, type LightOverridesInput, LightRig, LightingName, type LightingPreset, ON_TWOS_FPS, PARITY_EPSILON, Paper, PaperConfig, PaperConfigInput, PaperEdge, PaperFallback, PaperField, PaperFieldMesh, type PaperFieldMeshProps, type PaperFieldProps, type PaperHandle, PaperLighting, type PaperLightingProps, PaperMaterial, type PaperMaterialProps, PaperMesh, type PaperMeshProps, PaperMirror, type PaperMode, type PaperModeRequest, type PaperPose, type PaperProps, PaperStateMachine, type PaperStateMachineOptions, PaperStatesInput, type ParityCase, type ParityResult, type PeelOptions, PhysicsConfigInput, type PinMode, type PlacedPaper, type ReceiptContent, type RibbonOptions, type RollOptions, SAG_TOL, SHEET_LIFT, SceneConfigInput, type SettleOptions, SheetConfig, type SheetDims, type SheetLayoutOptions, type StateEvent, StateName, type Stock, StockName, SurfaceConfig, SurfaceConfigInput, type SurfaceMaps, TRANSMISSION_GAIN, type TranslucencyValues, type UnrollOptions, type UsePaperStatesResult, type WaveOptions, accordion, applyDeformerStack, atlasGrid, barcodeBars, bend, bendOptionsSchema, book, buildAgentPayload, buildDisplacementGLSL, buildFieldAgentPayload, buildFieldComponentSource, buildFieldFragmentShader, buildFieldVertexShader, buildJsxSnippet, carry, carryDrive, carryOptionsSchema, colonnade, composeSurface, contentText, cornerNames, createSheetGeometry, crumple, crumpleBehavior, crumpleBehaviorOptionsSchema, crumpleOptionsSchema, curl, curlOptionsSchema, dampTo, describeConfig, describeFieldConfig, diffConfig, diffFieldProps, displacePoint, distinctFieldPresets, drape, drapeOptionsSchema, drawBacking, fall, fallOptionsSchema, fan, fieldBounds, fieldKeyboardStep, fitCamera, flattenNumeric, flight, flightOptionsSchema, flightPose, flip, flipOptionsSchema, fly, flyOptionsSchema, fold, foldOptionsSchema, getBehavior, getDeformer, getIdlePreset, getLayout, getLightingPreset, getPreset, getStock, gust, hang, hangOptionsSchema, idleNames, idlePresets, isBuiltinPreset, letterFold, letterFoldOptionsSchema, lightAngles, lightPosition, lightSchema, lightenHex, lightingPresets, listBehaviors, listDeformers, listLayouts, listPresets, makeGoboTexture, mergeConfig, mergeWithDeletes, outwardCorner, parityCases, parsePreset, peel, peelOptionsSchema, pile, quantizeProgress, quantizeSegments, quantizeTime, rack, receiptTotals, recordStateOverride, registerBehavior, registerDeformer, registerLayout, registerPreset, resolveConfig, resolveDeformerStack, resolveLighting, resolveMode, resolveSegments, resolveStateConfig, ribbon, ribbonOptionsSchema, ring, roll, rollOptionsSchema, runParityHarness, segmentsForArc, segmentsForSine, serializePreset, settle, settleOptionsSchema, sheet, sheetBackingSize, sheetLayoutSchema, sheetSlotXY, silhouetteRects, spanAlong, spill, spread, stackAutoSegments, stackMinSegments, stackUniformValues, stateEventTransitions, stocks, stripStates, supportsWebGL, sweep, tornEdgesOnDetach, translucencyUniforms, translucencyValues, uniquePresetName, unregisterPreset, unroll, unrollOptionsSchema, useContentAtlas, usePaperStates, usePrefersReducedMotion, wall, wave, waveOptionsSchema, withSheetCellFromPaper, wrapLines, zoneAccepts };
+export { AUTO_CEILING, type Behavior, BehaviorConfigInput, ContentConfig, ContentConfigInput, type Deformer, type DeformerContext, type DeformerInstance, DeformerInstanceConfigInput, DropZone, type DropZoneConfig, type DropZoneProps, FLAT_SEGMENTS, type FieldExportInput, type FieldExportPaper, type FieldExportZone, FieldPaperSlot, FilmName, type HandleSpec, type IdleName, type IdlePreset, type Layout, type LightAngles, type LightOverrides, type LightOverridesInput, LightRig, LightingName, type LightingPreset, PARITY_EPSILON, Paper, PaperConfig, PaperConfigInput, PaperField, PaperFieldMesh, type PaperFieldMeshProps, type PaperFieldProps, type PaperHandle, PaperLighting, type PaperLightingProps, PaperMesh, type PaperMeshProps, type PaperPose, type PaperProps, PaperStatesInput, type ParityCase, type ParityResult, PhysicsConfigInput, type PlacedPaper, SAG_TOL, SceneConfigInput, SheetConfig, type SheetDims, type SheetLayoutOptions, type StateEvent, type Stock, StockName, SurfaceConfigInput, type UsePaperStatesResult, buildAgentPayload, buildFieldAgentPayload, buildFieldComponentSource, buildJsxSnippet, describeConfig, describeFieldConfig, diffConfig, diffFieldProps, getBehavior, getDeformer, getLayout, getPreset, getStock, idleNames, isBuiltinPreset, lightAngles, lightSchema, listBehaviors, listDeformers, listLayouts, listPresets, mergeConfig, mergeWithDeletes, parityCases, parsePreset, quantizeSegments, recordStateOverride, registerBehavior, registerDeformer, registerLayout, registerPreset, resolveLighting, resolveStateConfig, runParityHarness, segmentsForArc, segmentsForSine, serializePreset, sheetLayoutSchema, spanAlong, stocks, supportsWebGL, uniquePresetName, unregisterPreset, usePaperStates, usePrefersReducedMotion, wrapLines };