paperlab 0.5.2 → 0.7.0

package/dist/damageContract-DPF1YFLZ.d.cts

@@ -0,0 +1,129 @@
+/**
+ * What damage IS, as far as a sheet is concerned. The whole seam.
+ *
+ * The split is by responsibility. What has happened to the paper belongs to
+ * the sheet — it is shading, alpha and eventually stiffness, and only the
+ * sheet can draw or simulate those. What CAUSES it belongs to `paperlab/fx`:
+ * a flame, a cup of water, a pair of scissors. The main entry draws whatever
+ * damage it is handed and has no idea where it came from, which is exactly
+ * how `content` already works — `<Paper>` renders a texture without knowing
+ * who painted it.
+ *
+ * The alternative was a public plugin API for the surface composer and the
+ * cloth solver, so that fx could reach in. More flexible, and it would have
+ * had to be supported for years before a single effect existed to justify its
+ * shape. This is one interface and four constants.
+ *
+ * **This file imports nothing, on purpose.** `paperlab/fx` depends on it —
+ * the field is a `DamageSource` and its channel offsets are these — and the
+ * boundary test allows fx to reach this one file and nothing else in the
+ * library. The moment it imports three, React or the config schema, fx starts
+ * dragging the library in behind it.
+ */
+/**
+ * A grid of damage over the sheet's UV, as the sheet reads it.
+ *
+ * Satisfied structurally by `DamageField` in `paperlab/fx`, and by anything
+ * else that can produce four bytes per texel — a baked texture, a recorded
+ * burn played back, a test fixture.
+ */
+interface DamageSource {
+    /** Texels along each edge. The grid is square and covers the whole sheet. */
+    readonly size: number;
+    /**
+     * RGBA per texel, 0..255, row-major from v = 0 — the channels are
+     * {@link DAMAGE_CHANNELS}. Read in place, never copied: the source mutates
+     * it and bumps `version`.
+     *
+     * Eight bits, deliberately. The simulation behind it can run in float; what
+     * reaches the GPU is 16 KB per changed frame at 64², against 256 KB for a
+     * 128² float texture, and it does not depend on float-texture filtering,
+     * which not every phone GPU guarantees.
+     */
+    readonly pixels: Uint8Array;
+    /** Bumped whenever `pixels` changes. The sheet uploads on a change and never otherwise. */
+    readonly version: number;
+    /**
+     * How ragged a burnt or cut edge is DRAWN, 0..1; omitted means 1.
+     *
+     * Presentation only: per-fragment noise that moves the edge within the
+     * grid's soft band, finer than the grid itself can carry. The physics reads
+     * the grid and never this. It is the one part of drawing damage that costs
+     * per pixel, which is why it is a number a source can turn down — `paperlab/fx`
+     * sets it from its quality tier.
+     */
+    readonly detail?: number;
+    /**
+     * The burn's own clock, in seconds; omitted means the frame clock.
+     *
+     * Presentation only. The ember line on a burning edge is beaded and alive —
+     * its beads flicker and crawl — and a source that can be replayed wants
+     * that motion to replay too: the same moment of the same burn should draw
+     * the same beads, which the frame clock cannot promise. `DamageField`
+     * hands over its simulated time.
+     */
+    readonly time?: number;
+    /**
+     * How a burn is DRAWN — widths, intensities and shapes the sheet's damage
+     * shading reads each frame. Presentation only; the physics never sees it.
+     * Anything left out takes {@link DAMAGE_LOOK_DEFAULTS}.
+     */
+    readonly look?: DamageLook;
+}
+/**
+ * The knobs on what a burn looks like, in the units a person tunes by —
+ * millimetres of A4 and plain multipliers. Every one is optional.
+ */
+interface DamageLook {
+    /** The ember line's widest bead, mm. */
+    emberWidth?: number;
+    /** How bright the beads burn, × the default. */
+    emberIntensity?: number;
+    /** How much of the edge is lit at once, 0..1. */
+    emberCoverage?: number;
+    /** How fast the beads flicker and crawl, × the default. */
+    emberFlicker?: number;
+    /** The dim crimson glow beside the beads, reaching into the char, 0..2. */
+    emberGlow?: number;
+    /** Specks of glowing fibre along the edge, 0..2. */
+    sparkle?: number;
+    /** The pale ash lip's widest point, mm. */
+    lipWidth?: number;
+    /** How pale the ash lip is, × the sampled grey. */
+    lipBrightness?: number;
+    /** 0 is grey char, 1 is dark orange to deep brown. */
+    charWarmth?: number;
+    /** How visible the crack network in the char is, 0..1. */
+    charCracks?: number;
+    /** How far the scorch reaches UP past the burn, mm. */
+    scorchReach?: number;
+    /** How dark the scorch browns go, × the sampled ramp. */
+    scorchDarkness?: number;
+    /** How strongly the scorch front breaks into fingers, × the default. */
+    fingers?: number;
+    /** The burnt edge's long waves, ±mm. */
+    edgeWave?: number;
+    /** The burnt edge's small bites in and out, ±mm. */
+    edgeBite?: number;
+}
+/**
+ * What every burn is drawn with unless told otherwise — the combination Noor
+ * tuned in the lab's sidebar on 2026-09-12, which is the look this ships.
+ */
+declare const DAMAGE_LOOK_DEFAULTS: Required<DamageLook>;
+/**
+ * Which byte of a texel means what.
+ *
+ * char — scorch colour, the brown halo; on cloth, shrinkage and a curl toward the front.
+ * saturation — wet darkening and smoothing; on cloth, added mass.
+ * heat — how hot the paper is. Drawn only where it burns: the ember line, not the sheet.
+ * presence — how much paper is there at all; below half, none is drawn.
+ */
+declare const DAMAGE_CHANNELS: {
+    readonly char: 0;
+    readonly saturation: 1;
+    readonly heat: 2;
+    readonly presence: 3;
+};
+
+export { type DamageSource as D, DAMAGE_CHANNELS as a, DAMAGE_LOOK_DEFAULTS as b, type DamageLook as c };

package/dist/damageContract-DPF1YFLZ.d.ts

@@ -0,0 +1,129 @@
+/**
+ * What damage IS, as far as a sheet is concerned. The whole seam.
+ *
+ * The split is by responsibility. What has happened to the paper belongs to
+ * the sheet — it is shading, alpha and eventually stiffness, and only the
+ * sheet can draw or simulate those. What CAUSES it belongs to `paperlab/fx`:
+ * a flame, a cup of water, a pair of scissors. The main entry draws whatever
+ * damage it is handed and has no idea where it came from, which is exactly
+ * how `content` already works — `<Paper>` renders a texture without knowing
+ * who painted it.
+ *
+ * The alternative was a public plugin API for the surface composer and the
+ * cloth solver, so that fx could reach in. More flexible, and it would have
+ * had to be supported for years before a single effect existed to justify its
+ * shape. This is one interface and four constants.
+ *
+ * **This file imports nothing, on purpose.** `paperlab/fx` depends on it —
+ * the field is a `DamageSource` and its channel offsets are these — and the
+ * boundary test allows fx to reach this one file and nothing else in the
+ * library. The moment it imports three, React or the config schema, fx starts
+ * dragging the library in behind it.
+ */
+/**
+ * A grid of damage over the sheet's UV, as the sheet reads it.
+ *
+ * Satisfied structurally by `DamageField` in `paperlab/fx`, and by anything
+ * else that can produce four bytes per texel — a baked texture, a recorded
+ * burn played back, a test fixture.
+ */
+interface DamageSource {
+    /** Texels along each edge. The grid is square and covers the whole sheet. */
+    readonly size: number;
+    /**
+     * RGBA per texel, 0..255, row-major from v = 0 — the channels are
+     * {@link DAMAGE_CHANNELS}. Read in place, never copied: the source mutates
+     * it and bumps `version`.
+     *
+     * Eight bits, deliberately. The simulation behind it can run in float; what
+     * reaches the GPU is 16 KB per changed frame at 64², against 256 KB for a
+     * 128² float texture, and it does not depend on float-texture filtering,
+     * which not every phone GPU guarantees.
+     */
+    readonly pixels: Uint8Array;
+    /** Bumped whenever `pixels` changes. The sheet uploads on a change and never otherwise. */
+    readonly version: number;
+    /**
+     * How ragged a burnt or cut edge is DRAWN, 0..1; omitted means 1.
+     *
+     * Presentation only: per-fragment noise that moves the edge within the
+     * grid's soft band, finer than the grid itself can carry. The physics reads
+     * the grid and never this. It is the one part of drawing damage that costs
+     * per pixel, which is why it is a number a source can turn down — `paperlab/fx`
+     * sets it from its quality tier.
+     */
+    readonly detail?: number;
+    /**
+     * The burn's own clock, in seconds; omitted means the frame clock.
+     *
+     * Presentation only. The ember line on a burning edge is beaded and alive —
+     * its beads flicker and crawl — and a source that can be replayed wants
+     * that motion to replay too: the same moment of the same burn should draw
+     * the same beads, which the frame clock cannot promise. `DamageField`
+     * hands over its simulated time.
+     */
+    readonly time?: number;
+    /**
+     * How a burn is DRAWN — widths, intensities and shapes the sheet's damage
+     * shading reads each frame. Presentation only; the physics never sees it.
+     * Anything left out takes {@link DAMAGE_LOOK_DEFAULTS}.
+     */
+    readonly look?: DamageLook;
+}
+/**
+ * The knobs on what a burn looks like, in the units a person tunes by —
+ * millimetres of A4 and plain multipliers. Every one is optional.
+ */
+interface DamageLook {
+    /** The ember line's widest bead, mm. */
+    emberWidth?: number;
+    /** How bright the beads burn, × the default. */
+    emberIntensity?: number;
+    /** How much of the edge is lit at once, 0..1. */
+    emberCoverage?: number;
+    /** How fast the beads flicker and crawl, × the default. */
+    emberFlicker?: number;
+    /** The dim crimson glow beside the beads, reaching into the char, 0..2. */
+    emberGlow?: number;
+    /** Specks of glowing fibre along the edge, 0..2. */
+    sparkle?: number;
+    /** The pale ash lip's widest point, mm. */
+    lipWidth?: number;
+    /** How pale the ash lip is, × the sampled grey. */
+    lipBrightness?: number;
+    /** 0 is grey char, 1 is dark orange to deep brown. */
+    charWarmth?: number;
+    /** How visible the crack network in the char is, 0..1. */
+    charCracks?: number;
+    /** How far the scorch reaches UP past the burn, mm. */
+    scorchReach?: number;
+    /** How dark the scorch browns go, × the sampled ramp. */
+    scorchDarkness?: number;
+    /** How strongly the scorch front breaks into fingers, × the default. */
+    fingers?: number;
+    /** The burnt edge's long waves, ±mm. */
+    edgeWave?: number;
+    /** The burnt edge's small bites in and out, ±mm. */
+    edgeBite?: number;
+}
+/**
+ * What every burn is drawn with unless told otherwise — the combination Noor
+ * tuned in the lab's sidebar on 2026-09-12, which is the look this ships.
+ */
+declare const DAMAGE_LOOK_DEFAULTS: Required<DamageLook>;
+/**
+ * Which byte of a texel means what.
+ *
+ * char — scorch colour, the brown halo; on cloth, shrinkage and a curl toward the front.
+ * saturation — wet darkening and smoothing; on cloth, added mass.
+ * heat — how hot the paper is. Drawn only where it burns: the ember line, not the sheet.
+ * presence — how much paper is there at all; below half, none is drawn.
+ */
+declare const DAMAGE_CHANNELS: {
+    readonly char: 0;
+    readonly saturation: 1;
+    readonly heat: 2;
+    readonly presence: 3;
+};
+
+export { type DamageSource as D, DAMAGE_CHANNELS as a, DAMAGE_LOOK_DEFAULTS as b, type DamageLook as c };