paperlab 0.5.2 → 0.7.0

package/dist/index.d.cts

@@ -1,8 +1,10 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
 import * as THREE from 'three';
-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, i as LightOverrides, j as BackdropConfig } from './slots-CIo7FnlY.cjs';
-export { k as BackContentConfig, l as BehaviorConfig, m as ClothConfig, n as CoreStateName, o as DeformerInstanceConfig, p as LightOverridesInput, q as PaperEdge, r as PaperStates, s as PhysicsConfig, t as SceneConfig, u as StateDef, v as StateName, w as StateTransitionConfig, x as SurfaceConfig, W as WashConfig, y as backdropSchema, z as behaviorConfigSchema, A as clothConfigSchema, E as contentNames, G as contentSchemaFor, H as coreStateNames, I as lightSchema, J as lightingNames, K as paperConfigSchema, M as paperEdges, N as paperStatesSchema, O as physicsNames, Q as sceneSchema, R as stateDefSchema, T as stockNames, U as washSchema } from './slots-CIo7FnlY.cjs';
+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, M as MemoryConfigInput, d as SceneConfigInput, e as PhysicsConfigInput, f as CreaseConfig, F as FieldPaperSlot, g as ContentConfig, h as PaperStatesInput, L as LightingName, i as FilmName, j as LightOverrides, k as BackdropConfig } from './slots-C5PqY0Q5.cjs';
+export { l as BackContentConfig, m as BehaviorConfig, n as ClothConfig, o as CoreStateName, p as CreaseConfigInput, q as DeformerInstanceConfig, r as LightOverridesInput, s as MemoryConfig, t as PaperEdge, u as PaperStates, v as PhysicsConfig, w as SceneConfig, x as StateDef, y as StateName, z as StateTransitionConfig, A as StripConfig, E as SurfaceConfig, W as WashConfig, G as backdropSchema, H as behaviorConfigSchema, I as clothConfigSchema, J as contentNames, K as contentSchemaFor, N as coreStateNames, O as creaseSchema, Q as lightSchema, R as lightingNames, T as memorySchema, U as paperConfigSchema, V as paperEdges, X as paperStatesSchema, Y as physicsNames, Z as sceneSchema, _ as stateDefSchema, $ as stockNames, a0 as stripConfigSchema, a1 as washSchema } from './slots-C5PqY0Q5.cjs';
+import { D as DamageSource } from './damageContract-DPF1YFLZ.cjs';
+export { a as DAMAGE_CHANNELS, b as DAMAGE_LOOK_DEFAULTS, c as DamageLook } from './damageContract-DPF1YFLZ.cjs';
 import { z } from 'zod';
 
 /**
@@ -133,6 +135,13 @@ interface PaperMeshProps {
     deformers?: DeformerInstanceConfigInput[];
     /** Fragment-side effects: grain, aging, deckle, creases, perforation. */
     surface?: SurfaceConfigInput;
+    /**
+     * What the sheet remembers being folded — how much of a fold this paper
+     * keeps, and the creases it already carries. A sheet can be handed its
+     * creases (a letter that arrives having been folded once) as readily as it
+     * can be folded into them.
+     */
+    memory?: MemoryConfigInput;
     /** Scene-level presentation that travels with the paper (lighting). */
     scene?: SceneConfigInput;
     physics?: PhysicsConfigInput | 'cloth';
@@ -149,6 +158,17 @@ interface PaperMeshProps {
     onProgress?(value: number): void;
     /** Fires when a handle drag ends, with the params the drag changed. */
     onBehaviorChange?(patch: Record<string, unknown>): void;
+    /**
+     * Fires when folding the paper leaves a crease it did not have.
+     *
+     * The sheet applies its own creases immediately — this is how they get
+     * PERSISTED. Recording happens in the frame loop, where a fold's peak
+     * actually is, and routing that through React sixty times a second would
+     * cost more than the rest of the feature; so the mesh holds the live truth
+     * and reports it, and the host writes it into config whenever it likes.
+     * The same split `onBehaviorChange` uses for handle drags.
+     */
+    onCrease?(creases: CreaseConfig[]): void;
     /**
      * Interaction states: when the config carries `states`, pointer triggers
      * are live by default. Set false to sculpt a stateful paper without the
@@ -159,6 +179,18 @@ interface PaperMeshProps {
     onStateChange?(state: string): void;
     /** Fires for `onEnter` actions ('emit:<event>'). */
     onStateAction?(event: string, state: string): void;
+    /**
+     * What has happened to this sheet — char, wet, heat and missing paper — as
+     * a grid over its UV.
+     *
+     * The sheet draws whatever damage it is handed and does not know what
+     * caused it, the same way it draws `content` without knowing who painted
+     * it. `DamageField` from `paperlab/fx` is one source; a baked texture or a
+     * recorded burn played back would be others. A prop and not config,
+     * because it is live state that changes every frame and does not belong in
+     * a preset or a share link. See `DamageSource`.
+     */
+    damage?: DamageSource | null;
 }
 interface PaperHandle {
     play(): void;
@@ -185,6 +217,21 @@ interface PaperHandle {
      * allocate a vector sixty times a second.
      */
     handlePoint(id?: string, target?: THREE.Vector3): THREE.Vector3 | null;
+    /**
+     * Where a point of the sheet is right now, in world space: `(u, v)` over
+     * the sheet, `v = 0` its bottom edge — the same UV the damage grid is laid
+     * out on, so a cell of damage can be asked where it is. Null before the
+     * sheet has mounted.
+     *
+     * On the DRAWN surface, after this frame's simulation and deformer stack,
+     * which is the reason it is a method: an ember that leaves the burn front
+     * has to leave from where the paper is, and a draped or crumpled sheet is
+     * nowhere a UV alone could say. Interpolated across the triangle the GPU
+     * draws, so the point is on the paper and not a hair behind it.
+     *
+     * Written into `target` when one is passed, like {@link handlePoint}.
+     */
+    surfacePoint(u: number, v: number, target?: THREE.Vector3): THREE.Vector3 | null;
     /** Interaction-state machine access (null when the config has no states). */
     readonly state: string;
     sendState(event: StateEvent): string | null;
@@ -200,9 +247,10 @@ interface PaperHandle {
     returnProgrammatic(): boolean;
 }
 /**
- * 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
- * owns animated values; useFrame owns geometry writes.
+ * The atom: one sheet of paper, hero-mode CPU path. The cloth sim solves the
+ * particles and the deformer stack runs over them — both, not either; only a
+ * strip owns its vertices outright. GSAP owns animated values; useFrame owns
+ * geometry writes.
  */
 declare const PaperMesh: react.ForwardRefExoticComponent<PaperMeshProps & react.RefAttributes<PaperHandle>>;
 
@@ -280,7 +328,7 @@ interface Deformer<O = Record<string, unknown>> {
     id: string;
     label: string;
     defaults: O;
-    optionsSchema: z.ZodType<O, z.ZodTypeDef, unknown>;
+    optionsSchema: z.ZodType<O, 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. */
@@ -355,31 +403,12 @@ interface DeformerInstance<O = Record<string, unknown>> {
 declare const sheetLayoutSchema: z.ZodObject<{
     rows: z.ZodDefault<z.ZodNumber>;
     columns: z.ZodDefault<z.ZodNumber>;
-    /** World-units gap between slots. Stamps are printed in register — no jitter. */
     gutter: z.ZodDefault<z.ZodNumber>;
-    /** Slot footprint in world units (the paper preset should match). */
     cellWidth: z.ZodDefault<z.ZodNumber>;
     cellHeight: z.ZodDefault<z.ZodNumber>;
-    /** Render the shared backing sheet behind the grid. */
     backing: z.ZodDefault<z.ZodBoolean>;
     backingMargin: z.ZodDefault<z.ZodNumber>;
-}, "strip", z.ZodTypeAny, {
-    columns: number;
-    rows: number;
-    gutter: number;
-    cellWidth: number;
-    cellHeight: number;
-    backing: boolean;
-    backingMargin: number;
-}, {
-    columns?: number | undefined;
-    rows?: number | undefined;
-    gutter?: number | undefined;
-    cellWidth?: number | undefined;
-    cellHeight?: number | undefined;
-    backing?: boolean | undefined;
-    backingMargin?: number | undefined;
-}>;
+}, z.core.$strip>;
 type SheetLayoutOptions = z.infer<typeof sheetLayoutSchema>;
 
 /** Imperative field controls for the hidden a11y keyboard flow. */
@@ -605,7 +634,7 @@ interface Behavior<O = AnyOptions> {
     id: string;
     label: string;
     defaults: O;
-    optionsSchema: z.ZodType<O, z.ZodTypeDef, unknown>;
+    optionsSchema: z.ZodType<O, unknown>;
     /** Expand human params to the underlying deformer stack. */
     stack(o: O, sheet: SheetDims): DeformerInstance[];
     /** Transient, time-varying option overrides (idle motion). Never persisted. */
@@ -613,10 +642,14 @@ interface Behavior<O = AnyOptions> {
     /**
      * 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).
+     * (options, t, sheet) — the field applies it per instance with a time
+     * offset, so it has to be deterministic (flight's travel-across-the-scene).
+     *
+     * `sheet` is passed because whole-sheet motion is often only meaningful
+     * relative to the sheet's own extent: `unroll` holds the roll still in
+     * space, and where "still" is depends on how long the paper is.
      */
-    transform?(o: O, t: number, pose: AeroPose): void;
+    transform?(o: O, t: number, pose: AeroPose, sheet: SheetDims): void;
     handles?: HandleSpec<O>[];
     /**
      * The two or three options that ARE this behavior — the ones someone
@@ -670,7 +703,7 @@ interface Layout<O = Record<string, unknown>> {
     id: string;
     label: string;
     defaults: O;
-    optionsSchema: z.ZodType<O, z.ZodTypeDef, unknown>;
+    optionsSchema: z.ZodType<O, unknown>;
     /**
      * `sheet` is the field's paper size. Layouts that arrange by CONTACT —
      * edges meeting, sheets resting on each other — cannot work without it,
@@ -724,6 +757,16 @@ interface Stock {
     showThrough: number;
     /** Glossy near-white glue underside (stickers) — forces showThrough 0. */
     adhesive: boolean;
+    /**
+     * How hard this paper holds a crease, 0..1 — the material half of
+     * {@link MemoryConfig}. Fibrous, thick stocks take a set and keep it;
+     * coated and translucent ones spring most of the way back.
+     *
+     * Not a fraction of anything on its own: `memory.ts` scales it by
+     * `MAX_SET`, so 1 here means "as much as paper ever remembers", not "stays
+     * exactly as folded".
+     */
+    takesSet: number;
 }
 declare const stocks: Record<StockName, Stock>;
 declare function getStock(name: StockName): Stock;
@@ -749,6 +792,139 @@ interface IdlePreset {
     stack?(): DeformerInstance[];
 }
 
+/**
+ * The longest strip this chain can still draw properly, for a given
+ * perforation spacing.
+ *
+ * {@link stripNodeCount} is CAPPED, and the cap does not fail loudly: past it
+ * the node count stops growing, so `segment` (which is `length / (count - 1)`)
+ * grows instead, and every constant that was tuned per node quietly changes
+ * meaning. The first thing to break is the roll — a longer chord on the same
+ * radius dips further inside the wrap beneath it, so the spiral heads for the
+ * {@link safeSpiralRadius} threshold and comes apart into a starburst.
+ *
+ * Exported because it is a UI limit as much as a physics one: a length slider
+ * that runs past this hands the user a roll that visibly falls apart, and the
+ * editor has no other way to know where the ceiling is. The constants that set
+ * it live here, so the derivation does too.
+ */
+declare function maxStripLength(perforation: number): number;
+
+/**
+ * Paper memory: the sheet keeps what has been done to it.
+ *
+ * Every deformer is a pure function of its options — a sheet folded to 180°
+ * and back to 0° flows through the stack and comes out pristine. That is
+ * correct for cloth and wrong for paper, which is PLASTIC: the fibres break
+ * along the fold and the crease outlives it.
+ *
+ * The fix lives here rather than inside the deformers, and deliberately.
+ * Deformer purity is load-bearing — it is what gives the GLSL twins
+ * something to be identical to, what lets the field scale one instance's
+ * bend by a per-sheet bias, and what `test:parity` checks. So memory sits
+ * ABOVE the stack: it watches the stack the behavior built, and it rewrites
+ * that stack before it runs. Nothing below this file knows it exists.
+ *
+ * The whole layer is hero-path only. The field composes one GLSL program for
+ * every sheet in an instanced draw call, and a crease is per-sheet state —
+ * so a field of a hundred papers cannot carry a hundred crease sets without
+ * per-instance attributes that don't exist yet. `applyMemory` is called from
+ * `PaperMesh` and from nowhere in `field/`.
+ */
+/**
+ * What a paper at `takesSet: 1` keeps of a fold, as a fraction of the angle
+ * it was folded to.
+ *
+ * Kraft folded flat (180°) comes to rest around 30° open, which is `180 ×
+ * 0.85 × 0.2`. Keeping this multiplier here rather than folding it into the
+ * stock values is what lets `memory.set` and `Stock.takesSet` both be honest
+ * 0..1 knobs that use their whole range, instead of designer-facing sliders
+ * that do everything interesting in their bottom fifth.
+ */
+declare const MAX_SET = 0.2;
+/** What the crease shader carries, and so what memory may record. */
+declare const MAX_CREASES = 4;
+/**
+ * Fold a sheet's remembered creases into the stack that is about to run.
+ *
+ * A crease is a FLOOR on the fold at its line, never an addition. Where the
+ * behavior is already folding that line further, the crease is invisible and
+ * contributes nothing; as the behavior lets go, the fold angle falls to the
+ * crease's depth and stops there. That is what makes the crease appear on
+ * the way back out of a fold without anything having to detect the release —
+ * and it is why the residual is written INTO the live instance rather than
+ * added beside it. Two folds on one line would not be a deeper crease, they
+ * would be two creases a hair apart, and `fold` does not commute.
+ *
+ * Creases with no live fold on their line are prepended: a sheet that is
+ * already creased is creased BEFORE the behavior gets hold of it, so the
+ * behavior bends a creased sheet rather than the crease bending a bent one.
+ */
+declare function applyMemory(stack: DeformerInstance[], creases: CreaseConfig[]): DeformerInstance[];
+/**
+ * Watches a running deformer stack and records the creases it leaves.
+ *
+ * One per sheet, driven from the frame loop. It is deliberately not a
+ * reducer over config: recording has to happen at frame rate to catch the
+ * peak of a fold, and routing sixty writes a second through React would cost
+ * more than the whole rest of the feature. Instead this holds the live truth
+ * and says when it has changed, and the host persists that at its own pace —
+ * the same split `onBehaviorChange` already uses for handle drags.
+ *
+ * Slots are keyed by POSITION in the stack, which is the only stable identity
+ * a fold has: a behavior's stack is a pure function of its options, so
+ * `stack[1]` is the same fold from frame to frame, while its angle and offset
+ * are exactly the things that may legitimately move.
+ */
+declare class CreaseTracker {
+    private slots;
+    private recorded;
+    private authored;
+    /** What `observe` last handed out, so an echo can be told from an edit. */
+    private lastReported;
+    constructor(authored?: CreaseConfig[]);
+    /**
+     * Forget how the paper got here without forgetting the creases.
+     *
+     * Called when the stack is replaced wholesale (a new behavior, a new
+     * sheet): the slots describe folds that no longer exist, but a crease is a
+     * property of the paper and survives being put down and picked up.
+     */
+    reset(authored?: CreaseConfig[]): void;
+    /**
+     * Take on a crease set that came from outside, and work out which kind of
+     * outside it was — because the two kinds want opposite things.
+     *
+     * It is USUALLY this tracker's own recording coming back, a frame or two
+     * after `onCrease` handed it to the host. Then the slots must survive: the
+     * fold that made the crease is very likely still closing, and resetting
+     * its peak on the host's echo would stall the crease halfway into the
+     * fold that was making it.
+     *
+     * But it can also be somebody EDITING the paper — a depth dragged down in
+     * a panel, a shared link opened, a state's overrides settling. Then the
+     * slots are the wrong story to keep. `merge` takes the deeper of two
+     * creases on a line, so a recording of 20° would quietly outvote a human
+     * asking for 5° and the slider would appear not to work; and it would go
+     * on outvoting it, because the fold that recorded the 20 is still sitting
+     * in a slot. An edit means the paper is what it is now, and the next
+     * crease has to be earned by folding it again.
+     *
+     * The two are told apart by what we last reported. Anything else is an
+     * edit, which is the safe way round: mistaking an echo for an edit costs
+     * a crease that gets re-recorded on the next fold, while mistaking an edit
+     * for an echo costs a control that does not work.
+     */
+    adopt(creases: CreaseConfig[]): void;
+    /** Everything the sheet currently carries, authored and recorded merged. */
+    get creases(): CreaseConfig[];
+    /**
+     * Take one frame's reading. Returns true when the crease set changed by
+     * enough to be worth telling anyone about.
+     */
+    observe(stack: DeformerInstance[], set: number): boolean;
+}
+
 /**
  * Lighting presets: each is a key light + ambient level + contact shadow +
  * optional gobo (a texture the key light projects — window blinds, foliage).
@@ -1101,4 +1277,4 @@ declare function segmentsForSine(span: number, amplitude: number, wavelength: nu
  */
 declare function wrapLines(ctx: CanvasRenderingContext2D, text: string, maxWidth: number, font: string): string[];
 
-export { AUTO_CEILING, BackdropConfig, 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, LightOverrides, LightRig, LightingName, type LightingPreset, PARITY_EPSILON, Paper, PaperBackdrop, 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, 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 };
+export { AUTO_CEILING, BackdropConfig, type Behavior, BehaviorConfigInput, ContentConfig, ContentConfigInput, CreaseConfig, CreaseTracker, DamageSource, 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, LightOverrides, LightRig, LightingName, type LightingPreset, MAX_CREASES, MAX_SET, MemoryConfigInput, PARITY_EPSILON, Paper, PaperBackdrop, 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, applyMemory, buildAgentPayload, buildFieldAgentPayload, buildFieldComponentSource, buildJsxSnippet, describeConfig, describeFieldConfig, diffConfig, diffFieldProps, getBehavior, getDeformer, getLayout, getPreset, getStock, idleNames, isBuiltinPreset, lightAngles, listBehaviors, listDeformers, listLayouts, listPresets, maxStripLength, 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 };