paperlab 0.6.0 → 0.7.0

package/README.md

@@ -25,13 +25,17 @@ npm i paperlab three @react-three/fiber gsap
 
 Requires React ≥ 19 and three ≥ 0.162. TypeScript types ship with the package; both ESM and CJS builds are published.
 
+> **npm users:** `@react-three/fiber@9.7.0` caps React at `>=19 <19.3`, and npm installs React 19.3 by default, so the line above can fail with `ERESOLVE`. Ask for a React the renderer accepts — `npm i paperlab three @react-three/fiber gsap react@19.2 react-dom@19.2` — until fiber widens its range. pnpm and yarn resolve it without complaint. This is upstream's ceiling, not Paperlab's: the library itself supports any React ≥ 19.
+
 Stage mode lives at the `paperlab/stage` subpath and needs two more peers:
 
 ```sh
 npm i @react-three/postprocessing postprocessing
 ```
 
-They are optional. `<Paper>` and `<PaperField>` never reach for them, so a bundle that does not import `paperlab/stage` contains none of it — and the subpath is what keeps the import specifier itself out of your build graph.
+They are genuinely optional, in both directions. `<Paper>` and `<PaperField>` never reach for them, so a bundle that does not import `paperlab/stage` contains none of it — the subpath keeps the import specifier itself out of your build graph. And `paperlab/stage` loads the print pass on demand rather than at module scope, so a stage renders without them too: you lose the tone curve, bloom, vignette and grain, and the console says so once.
+
+`paperlab/fx` is the third entry point: what happens **to** the paper. A sheet takes `<Paper damage={source}>` — char, water, heat and missing paper over its own UV — and draws it, cuts its shadow with it, and on a simulated sheet shrinks, curls, weighs down and breaks the paper it describes. What *causes* damage lives behind the subpath: a field that burns, soaks and erodes; the embers, smoke and ash a burn throws off; and a fire synthesised from the same numbers the picture is drawn from. A `<Paper>`-only bundle resolves none of it.
 
 ## Quick start
 

package/dist/FxPostPass-M66QMVVC.js

@@ -0,0 +1,166 @@
+import {
+  FX_BLOOM,
+  FX_BLOOM_THRESHOLD,
+  PAPER_WHITE,
+  flameAnchors,
+  fxQualityFor
+} from "./chunk-GB6BMHC3.js";
+import "./chunk-7TLIWPGM.js";
+
+// src/fx/FxPostPass.tsx
+import { Bloom, EffectComposer, ToneMapping } from "@react-three/postprocessing";
+import { useFrame } from "@react-three/fiber";
+import { ToneMappingMode } from "postprocessing";
+import { useMemo, useRef } from "react";
+import * as THREE2 from "three";
+
+// src/fx/haze.ts
+import * as THREE from "three";
+import { BlendFunction, Effect } from "postprocessing";
+var HAZE_SOURCES = 16;
+var FRAGMENT = (
+  /* glsl */
+  `
+uniform vec4 uSources[${HAZE_SOURCES}];
+uniform int uCount;
+uniform float uTime;
+uniform float uAmount;
+uniform vec3 uWarm;
+uniform float uGrade;
+
+float hzHash(vec2 p) { return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453123); }
+float hzNoise(vec2 p) {
+  vec2 i = floor(p);
+  vec2 f = fract(p);
+  vec2 u = f * f * (3.0 - 2.0 * f);
+  return mix(mix(hzHash(i), hzHash(i + vec2(1.0, 0.0)), u.x), mix(hzHash(i + vec2(0.0, 1.0)), hzHash(i + vec2(1.0, 1.0)), u.x), u.y);
+}
+
+// Heat haze: the air above a flame is hotter than the air beside it, and
+// light bends through the difference. A few pixels of upward-scrolling
+// displacement, only in the column above each flame, fading with height.
+void mainUv(inout vec2 uv) {
+  vec2 offset = vec2(0.0);
+  for (int i = 0; i < ${HAZE_SOURCES}; i++) {
+    if (i >= uCount) break;
+    vec4 s = uSources[i];
+    vec2 d = uv - s.xy;
+    float h = max(s.z, 1e-4);
+    float above = d.y / h;
+    if (above < -0.1 || above > 3.2) continue;
+    float across = abs(d.x) / (h * 0.55 + 1e-4);
+    // Around the flame's own boundary as well as above it: gentle inside the
+    // body, strongest in the hot column over it, gone by three flame heights.
+    float column = smoothstep(0.3, 0.9, above) * (1.0 - smoothstep(1.4, 3.2, above));
+    float around = smoothstep(-0.1, 0.15, above) * (1.0 - smoothstep(0.8, 1.2, above)) * 0.45;
+    float m = (1.0 - smoothstep(0.45, 1.15, across)) * max(column, around) * s.w;
+    vec2 q = vec2(uv.x * 140.0, uv.y * 90.0 - uTime * 3.0);
+    offset += (vec2(hzNoise(q), hzNoise(q + 31.7)) - 0.5) * m;
+  }
+  uv += offset * uAmount;
+}
+
+// The grade: the whole frame warms as the fire grows \u2014 a few percent, no
+// more (spec \xA77). A multiply, so black stays black.
+void mainImage(const in vec4 inputColor, const in vec2 uv, out vec4 outputColor) {
+  outputColor = vec4(inputColor.rgb * mix(vec3(1.0), uWarm, uGrade), inputColor.a);
+}
+`
+);
+var HazeGradeEffect = class extends Effect {
+  constructor() {
+    super("HazeGradeEffect", FRAGMENT, {
+      blendFunction: BlendFunction.NORMAL,
+      uniforms: /* @__PURE__ */ new Map([
+        ["uSources", new THREE.Uniform(Array.from({ length: HAZE_SOURCES }, () => new THREE.Vector4()))],
+        ["uCount", new THREE.Uniform(0)],
+        ["uTime", new THREE.Uniform(0)],
+        // 1–3 px at 1080p, as a fraction of the frame.
+        ["uAmount", new THREE.Uniform(2.2 / 1080)],
+        ["uWarm", new THREE.Uniform(new THREE.Vector3(1.04, 1, 0.94))],
+        ["uGrade", new THREE.Uniform(0)]
+      ])
+    });
+  }
+  get sources() {
+    return this.uniforms.get("uSources").value;
+  }
+  set count(n) {
+    this.uniforms.get("uCount").value = n;
+  }
+  set time(t) {
+    this.uniforms.get("uTime").value = t;
+  }
+  /** 0 turns the shimmer off (the low tier) and keeps the grade. */
+  set amount(px1080) {
+    this.uniforms.get("uAmount").value = px1080 / 1080;
+  }
+  /** 0..1 — how much of the warm grade to apply. */
+  set grade(g) {
+    this.uniforms.get("uGrade").value = g;
+  }
+};
+
+// src/fx/FxPostPass.tsx
+import { jsx, jsxs } from "react/jsx-runtime";
+var modes = {
+  agx: ToneMappingMode.AGX,
+  neutral: ToneMappingMode.NEUTRAL,
+  filmic: ToneMappingMode.ACES_FILMIC
+};
+var root = new THREE2.Vector3();
+var top = new THREE2.Vector3();
+function FxPostPass({
+  film = "neutral",
+  quality = "medium",
+  bloom = FX_BLOOM,
+  threshold = FX_BLOOM_THRESHOLD,
+  field,
+  locate,
+  haze: hazeOverride
+}) {
+  const { bloomScale, haze: tierHaze } = fxQualityFor(quality);
+  const hazePx = hazeOverride ?? tierHaze;
+  const haze = useMemo(() => new HazeGradeEffect(), []);
+  const anchors = useRef([]);
+  useFrame(({ camera }) => {
+    if (!field || !locate) {
+      haze.count = 0;
+      haze.grade = 0;
+      return;
+    }
+    const n = hazePx > 0 ? flameAnchors(field, locate, HAZE_SOURCES, anchors.current) : 0;
+    const sources = haze.sources;
+    for (let i = 0; i < n; i++) {
+      const a = anchors.current[i];
+      root.set(a.x, a.y, a.z).project(camera);
+      top.set(a.x, a.y + a.height, a.z).project(camera);
+      sources[i].set(root.x * 0.5 + 0.5, root.y * 0.5 + 0.5, Math.max(0, (top.y - root.y) * 0.5), a.heat);
+    }
+    haze.count = n;
+    haze.time = field.time;
+    haze.amount = hazePx;
+    haze.grade = Math.min(1, field.lastStats.front / 0.03);
+  });
+  return /* @__PURE__ */ jsxs(EffectComposer, { children: [
+    bloom > 0 ? /* @__PURE__ */ jsx(
+      Bloom,
+      {
+        intensity: bloom,
+        luminanceThreshold: threshold,
+        luminanceSmoothing: 0.02,
+        mipmapBlur: true,
+        resolutionScale: bloomScale
+      }
+    ) : null,
+    /* @__PURE__ */ jsx("primitive", { object: haze }),
+    /* @__PURE__ */ jsx(ToneMapping, { mode: modes[film] })
+  ] });
+}
+export {
+  FX_BLOOM,
+  FX_BLOOM_THRESHOLD,
+  FxPostPass,
+  PAPER_WHITE
+};
+//# sourceMappingURL=FxPostPass-M66QMVVC.js.map

package/dist/FxPostPass-M66QMVVC.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/fx/FxPostPass.tsx","../src/fx/haze.ts"],"sourcesContent":["import { Bloom, EffectComposer, ToneMapping } from '@react-three/postprocessing'\nimport { useFrame } from '@react-three/fiber'\nimport { ToneMappingMode } from 'postprocessing'\nimport { useMemo, useRef } from 'react'\nimport * as THREE from 'three'\nimport { FX_BLOOM, FX_BLOOM_THRESHOLD, PAPER_WHITE } from './emission'\nimport type { FxPostProps } from './FxPost'\nimport { flameAnchors, type FlameAnchor } from './flames'\nimport { HAZE_SOURCES, HazeGradeEffect } from './haze'\nimport { fxQualityFor } from './quality'\n\n/**\n * Where fire's glow comes from: bloom on the HDR frame, the heat haze and the\n * warm grade, then the tone curve.\n *\n * The ONLY file in `paperlab/fx` that imports `@react-three/postprocessing`\n * (with `haze.ts`, which only this imports), and nothing imports it\n * statically — `FxPost` reaches it through a dynamic import, so the two peers\n * stay optional the way stage's `Grade` keeps them. Importing this from\n * anywhere else would put the specifier back into fx's module graph and a\n * consumer without the peers could no longer load fx.\n *\n * Why it exists, in the words of `paperlab-fx-fire-spec.md` §0 and §7: the\n * first fire's glow was PAINT — a warm colour added to `csm_Emissive` over\n * paper that had not burnt — and red added to white makes pink. Real glow is\n * light too bright for the film: an ember is brighter than the whitest paper\n * in the frame, the lens spreads it, and the curve rolls it off to white.\n * Nothing on the sheet paints glow any more; anything that wants to glow\n * emits past paper white and this makes it bloom.\n *\n * Order is the whole argument: bloom reads the frame while it is still HDR —\n * which is what lets a threshold mean \"brighter than paper\" — the haze bends\n * the light above the flames and the grade warms the frame, and the curve\n * lands the result last.\n *\n * **The composer takes the tone curve off the renderer, so this gives it\n * back.** `<EffectComposer>` sets `gl.toneMapping = NoToneMapping` while it is\n * mounted; without the `<ToneMapping>` below, mounting this pass would\n * silently throw away the rig's film and the unburnt sheet would change. The\n * spec's own test for this pass is that it does not: with no fire in frame,\n * post on and post off are the same picture (§14.3, `pnpm test:fire-look`).\n */\n\nconst modes = {\n  agx: ToneMappingMode.AGX,\n  neutral: ToneMappingMode.NEUTRAL,\n  filmic: ToneMappingMode.ACES_FILMIC,\n} as const\n\nconst root = new THREE.Vector3()\nconst top = new THREE.Vector3()\n\nexport function FxPostPass({\n  film = 'neutral',\n  quality = 'medium',\n  bloom = FX_BLOOM,\n  threshold = FX_BLOOM_THRESHOLD,\n  field,\n  locate,\n  haze: hazeOverride,\n}: FxPostProps) {\n  const { bloomScale, haze: tierHaze } = fxQualityFor(quality)\n  const hazePx = hazeOverride ?? tierHaze\n  const haze = useMemo(() => new HazeGradeEffect(), [])\n  const anchors = useRef<FlameAnchor[]>([])\n\n  // The flames, in screen space, for the haze; the front, for the grade.\n  useFrame(({ camera }) => {\n    if (!field || !locate) {\n      haze.count = 0\n      haze.grade = 0\n      return\n    }\n    const n = hazePx > 0 ? flameAnchors(field, locate, HAZE_SOURCES, anchors.current) : 0\n    const sources = haze.sources\n    for (let i = 0; i < n; i++) {\n      const a = anchors.current[i]!\n      root.set(a.x, a.y, a.z).project(camera)\n      top.set(a.x, a.y + a.height, a.z).project(camera)\n      sources[i]!.set(root.x * 0.5 + 0.5, root.y * 0.5 + 0.5, Math.max(0, (top.y - root.y) * 0.5), a.heat)\n    }\n    haze.count = n\n    haze.time = field.time\n    haze.amount = hazePx\n    // A few percent at most, and only as the fire grows (§7).\n    haze.grade = Math.min(1, field.lastStats.front / 0.03)\n  })\n\n  return (\n    <EffectComposer>\n      {bloom > 0 ? (\n        <Bloom\n          intensity={bloom}\n          luminanceThreshold={threshold}\n          // Nearly a hard knee. A wide one reaches BELOW the threshold, and\n          // below it is paper: the whole point of the threshold is that paper\n          // never blooms (§7), and a soft knee would bloom it a little.\n          luminanceSmoothing={0.02}\n          mipmapBlur\n          resolutionScale={bloomScale}\n        />\n      ) : null}\n      <primitive object={haze} />\n      <ToneMapping mode={modes[film]} />\n    </EffectComposer>\n  )\n}\n\n/**\n * Re-exported, not defined here.\n *\n * It moved to `emission.ts` because it is half of a unit — \"brighter than\n * paper\" is only meaningful beside the paper white it is measured against,\n * and every emitter now authors itself in multiples of that same number. It\n * also could not be public from here: this file is the only one in\n * `paperlab/fx` allowed to import `postprocessing` (see `boundary.test.ts`),\n * so anything exported from it is unreachable for a consumer who has not\n * installed the optional peers.\n */\nexport { FX_BLOOM, FX_BLOOM_THRESHOLD, PAPER_WHITE }\n","import * as THREE from 'three'\nimport { BlendFunction, Effect } from 'postprocessing'\n\n/** How many flames the haze can shimmer above at once. */\nexport const HAZE_SOURCES = 16\n\nconst FRAGMENT = /* glsl */ `\nuniform vec4 uSources[${HAZE_SOURCES}];\nuniform int uCount;\nuniform float uTime;\nuniform float uAmount;\nuniform vec3 uWarm;\nuniform float uGrade;\n\nfloat hzHash(vec2 p) { return fract(sin(dot(p, vec2(127.1, 311.7))) * 43758.5453123); }\nfloat hzNoise(vec2 p) {\n  vec2 i = floor(p);\n  vec2 f = fract(p);\n  vec2 u = f * f * (3.0 - 2.0 * f);\n  return mix(mix(hzHash(i), hzHash(i + vec2(1.0, 0.0)), u.x), mix(hzHash(i + vec2(0.0, 1.0)), hzHash(i + vec2(1.0, 1.0)), u.x), u.y);\n}\n\n// Heat haze: the air above a flame is hotter than the air beside it, and\n// light bends through the difference. A few pixels of upward-scrolling\n// displacement, only in the column above each flame, fading with height.\nvoid mainUv(inout vec2 uv) {\n  vec2 offset = vec2(0.0);\n  for (int i = 0; i < ${HAZE_SOURCES}; i++) {\n    if (i >= uCount) break;\n    vec4 s = uSources[i];\n    vec2 d = uv - s.xy;\n    float h = max(s.z, 1e-4);\n    float above = d.y / h;\n    if (above < -0.1 || above > 3.2) continue;\n    float across = abs(d.x) / (h * 0.55 + 1e-4);\n    // Around the flame's own boundary as well as above it: gentle inside the\n    // body, strongest in the hot column over it, gone by three flame heights.\n    float column = smoothstep(0.3, 0.9, above) * (1.0 - smoothstep(1.4, 3.2, above));\n    float around = smoothstep(-0.1, 0.15, above) * (1.0 - smoothstep(0.8, 1.2, above)) * 0.45;\n    float m = (1.0 - smoothstep(0.45, 1.15, across)) * max(column, around) * s.w;\n    vec2 q = vec2(uv.x * 140.0, uv.y * 90.0 - uTime * 3.0);\n    offset += (vec2(hzNoise(q), hzNoise(q + 31.7)) - 0.5) * m;\n  }\n  uv += offset * uAmount;\n}\n\n// The grade: the whole frame warms as the fire grows — a few percent, no\n// more (spec §7). A multiply, so black stays black.\nvoid mainImage(const in vec4 inputColor, const in vec2 uv, out vec4 outputColor) {\n  outputColor = vec4(inputColor.rgb * mix(vec3(1.0), uWarm, uGrade), inputColor.a);\n}\n`\n\n/**\n * Heat haze above the flames, and the warm grade of a frame with a fire in\n * it — spec §7's last two items, as one pass because both are cheap and both\n * run on the HDR frame before the tone curve.\n *\n * Fed each frame by `FxPostPass`: `sources` holds up to {@link HAZE_SOURCES}\n * flames as (screen u, screen v, flame height in screen v, strength).\n */\nexport class HazeGradeEffect extends Effect {\n  constructor() {\n    super('HazeGradeEffect', FRAGMENT, {\n      blendFunction: BlendFunction.NORMAL,\n      uniforms: new Map<string, THREE.Uniform>([\n        ['uSources', new THREE.Uniform(Array.from({ length: HAZE_SOURCES }, () => new THREE.Vector4()))],\n        ['uCount', new THREE.Uniform(0)],\n        ['uTime', new THREE.Uniform(0)],\n        // 1–3 px at 1080p, as a fraction of the frame.\n        ['uAmount', new THREE.Uniform(2.2 / 1080)],\n        ['uWarm', new THREE.Uniform(new THREE.Vector3(1.04, 1.0, 0.94))],\n        ['uGrade', new THREE.Uniform(0)],\n      ]),\n    })\n  }\n\n  get sources(): THREE.Vector4[] {\n    return this.uniforms.get('uSources')!.value as THREE.Vector4[]\n  }\n\n  set count(n: number) {\n    this.uniforms.get('uCount')!.value = n\n  }\n\n  set time(t: number) {\n    this.uniforms.get('uTime')!.value = t\n  }\n\n  /** 0 turns the shimmer off (the low tier) and keeps the grade. */\n  set amount(px1080: number) {\n    this.uniforms.get('uAmount')!.value = px1080 / 1080\n  }\n\n  /** 0..1 — how much of the warm grade to apply. */\n  set grade(g: number) {\n    this.uniforms.get('uGrade')!.value = g\n  }\n}\n"],"mappings":"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","names":["THREE"]}

package/dist/Grade-SBGYELKV.js

@@ -0,0 +1,49 @@
+// src/stage/Grade.tsx
+import {
+  EffectComposer,
+  Bloom,
+  DepthOfField,
+  Vignette,
+  Noise,
+  ToneMapping
+} from "@react-three/postprocessing";
+import { BlendFunction, ToneMappingMode } from "postprocessing";
+import { jsx, jsxs } from "react/jsx-runtime";
+var toneMappingModes = {
+  agx: ToneMappingMode.AGX,
+  neutral: ToneMappingMode.NEUTRAL,
+  filmic: ToneMappingMode.ACES_FILMIC
+};
+function Grade({ grade, film }) {
+  const bloom = grade.bloom > 0;
+  const depth = grade.depth > 0;
+  const vignette = grade.vignette > 0;
+  const grain = grade.grain > 0;
+  if (!bloom && !depth && !vignette && !grain) return null;
+  return /* @__PURE__ */ jsxs(EffectComposer, { children: [
+    bloom ? /* @__PURE__ */ jsx(
+      Bloom,
+      {
+        intensity: grade.bloom,
+        luminanceThreshold: grade.threshold,
+        luminanceSmoothing: 0.22,
+        mipmapBlur: true
+      }
+    ) : null,
+    depth ? /* @__PURE__ */ jsx(
+      DepthOfField,
+      {
+        focusDistance: 8e-3,
+        focalLength: 0.02 + grade.depth * 0.04,
+        bokehScale: grade.depth * 2.5
+      }
+    ) : null,
+    /* @__PURE__ */ jsx(ToneMapping, { mode: toneMappingModes[film] }),
+    vignette ? /* @__PURE__ */ jsx(Vignette, { offset: 0.32, darkness: grade.vignette }) : null,
+    grain ? /* @__PURE__ */ jsx(Noise, { opacity: grade.grain, blendFunction: BlendFunction.OVERLAY }) : null
+  ] });
+}
+export {
+  Grade
+};
+//# sourceMappingURL=Grade-SBGYELKV.js.map

package/dist/Grade-SBGYELKV.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/stage/Grade.tsx"],"sourcesContent":["import {\n  EffectComposer,\n  Bloom,\n  DepthOfField,\n  Vignette,\n  Noise,\n  ToneMapping,\n} from '@react-three/postprocessing'\nimport { BlendFunction, ToneMappingMode } from 'postprocessing'\nimport type { FilmName } from '../config/schema'\nimport type { StageGradeConfig } from './schema'\n\n/**\n * The print pass: tone curve, bloom, vignette, grain.\n *\n * Kept in its own module for one reason — it is the ONLY file in the library\n * that imports `@react-three/postprocessing`, and nothing imports it\n * statically. `GradeLazy` reaches it through a dynamic import, which is what\n * lets the two peers stay genuinely optional; importing this module directly\n * from anywhere would put the specifier back into stage's module graph and\n * undo that. Adding an import here is fine. Importing this from anywhere but\n * `GradeLazy` is not.\n *\n * **The composer takes the tone curve away from the renderer, so this file\n * has to give it back.** `<EffectComposer>` sets `gl.toneMapping =\n * NoToneMapping` for as long as it is mounted — it has to, because tone\n * mapping belongs at the END of a post chain rather than at the end of the\n * scene pass, and a frame mapped twice is wrong twice. What that means here\n * is that mounting a composer without a `<ToneMapping>` effect silently\n * throws away `light.film` entirely: the stage's own grade would have been\n * the one thing capable of un-doing the AgX curve everything else reads.\n *\n * Why the rest of it is needed, in the order it shows up in a frame:\n *\n * - **Bloom.** The source at the end of the walk is a `meshBasicMaterial`\n *   with `toneMapped: false`, deliberately, because it is light rather than\n *   an object. Nothing rolls it off, so without bloom it clips to a flat\n *   shape with a boundary — a lit panel hanging in the room. `Surround`\n *   already spends a seven-stop alpha ramp fighting that in geometry, which\n *   is the wrong layer to fight it in.\n * - **Vignette.** A frame with no edge reads as a viewport.\n * - **Grain.** The one texture the render and the subject have in common.\n */\n\n/** The rig's film, as a postprocessing mode. Mirrors `toneMappings` in PaperLighting. */\nconst toneMappingModes: Record<FilmName, ToneMappingMode> = {\n  agx: ToneMappingMode.AGX,\n  neutral: ToneMappingMode.NEUTRAL,\n  filmic: ToneMappingMode.ACES_FILMIC,\n}\n\nexport function Grade({ grade, film }: { grade: StageGradeConfig; film: FilmName }) {\n  const bloom = grade.bloom > 0\n  const depth = grade.depth > 0\n  const vignette = grade.vignette > 0\n  const grain = grade.grain > 0\n\n  // A composer is a full-screen render target and a second pass over every\n  // pixel. A stage graded to nothing should not pay for one — and crucially,\n  // must not MOUNT one, because an empty composer would still take the tone\n  // curve off the renderer and hand back nothing.\n  if (!bloom && !depth && !vignette && !grain) return null\n\n  return (\n    <EffectComposer>\n      {/*\n        Order is the whole correctness argument here.\n\n        Bloom reads the scene while it is still HDR — that is what lets a\n        threshold near 1.0 mean \"brighter than paper\" rather than \"brighter\n        than whatever the curve happened to flatten paper to\". Tone mapping\n        then lands the result in display range, and vignette and grain come\n        after it because both are darkroom moves on a finished print, not\n        light in the room.\n      */}\n      {bloom ? (\n        <Bloom\n          intensity={grade.bloom}\n          luminanceThreshold={grade.threshold}\n          luminanceSmoothing={0.22}\n          mipmapBlur\n        />\n      ) : null}\n      {/*\n        Depth goes with bloom on the HDR side, before the curve, because a\n        blur of tone-mapped pixels averages DISPLAY values and a blur of\n        scene values averages light. Only the second one puts a bright\n        highlight's glow into the soft region, which is the entire reason a\n        real lens's out-of-focus areas look the way they do.\n\n        `focusDistance` is normalized against the camera's far plane, and the\n        stage's camera stands ON the walk looking down it — so the focal\n        plane sits a little ahead of the viewer and both ends fall away.\n      */}\n      {depth ? (\n        <DepthOfField\n          // Normalized against the camera's far plane, which this scene sets\n          // to 400 — so 0.008 is roughly three units out, which is where the\n          // banner you are standing in front of actually is. The first pass\n          // at this focused eight units away and put the focal plane in the\n          // empty air past the paper, so nothing in frame was sharp.\n          focusDistance={0.008}\n          focalLength={0.02 + grade.depth * 0.04}\n          bokehScale={grade.depth * 2.5}\n        />\n      ) : null}\n      <ToneMapping mode={toneMappingModes[film]} />\n      {vignette ? <Vignette offset={0.32} darkness={grade.vignette} /> : null}\n      {/*\n        OVERLAY rather than NORMAL: grain added flat lifts the blacks and\n        turns a dark hall grey. Overlay leaves them where they are and puts\n        the texture into the midtones, which is where film grain lives.\n      */}\n      {grain ? <Noise opacity={grade.grain} blendFunction={BlendFunction.OVERLAY} /> : null}\n    </EffectComposer>\n  )\n}\n"],"mappings":";AAAA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AACP,SAAS,eAAe,uBAAuB;AAwD3C,SAYI,KAZJ;AAnBJ,IAAM,mBAAsD;AAAA,EAC1D,KAAK,gBAAgB;AAAA,EACrB,SAAS,gBAAgB;AAAA,EACzB,QAAQ,gBAAgB;AAC1B;AAEO,SAAS,MAAM,EAAE,OAAO,KAAK,GAAgD;AAClF,QAAM,QAAQ,MAAM,QAAQ;AAC5B,QAAM,QAAQ,MAAM,QAAQ;AAC5B,QAAM,WAAW,MAAM,WAAW;AAClC,QAAM,QAAQ,MAAM,QAAQ;AAM5B,MAAI,CAAC,SAAS,CAAC,SAAS,CAAC,YAAY,CAAC,MAAO,QAAO;AAEpD,SACE,qBAAC,kBAWE;AAAA,YACC;AAAA,MAAC;AAAA;AAAA,QACC,WAAW,MAAM;AAAA,QACjB,oBAAoB,MAAM;AAAA,QAC1B,oBAAoB;AAAA,QACpB,YAAU;AAAA;AAAA,IACZ,IACE;AAAA,IAYH,QACC;AAAA,MAAC;AAAA;AAAA,QAMC,eAAe;AAAA,QACf,aAAa,OAAO,MAAM,QAAQ;AAAA,QAClC,YAAY,MAAM,QAAQ;AAAA;AAAA,IAC5B,IACE;AAAA,IACJ,oBAAC,eAAY,MAAM,iBAAiB,IAAI,GAAG;AAAA,IAC1C,WAAW,oBAAC,YAAS,QAAQ,MAAM,UAAU,MAAM,UAAU,IAAK;AAAA,IAMlE,QAAQ,oBAAC,SAAM,SAAS,MAAM,OAAO,eAAe,cAAc,SAAS,IAAK;AAAA,KACnF;AAEJ;","names":[]}

package/dist/chunk-7TLIWPGM.js

@@ -0,0 +1,36 @@
+// src/surface/damageContract.ts
+var DAMAGE_LOOK_DEFAULTS = {
+  // §5 asks for 0.3–1 mm. 1.8 was outside it, and outside the slider's range
+  // it was tuned in — a control at its limit is a report that something
+  // underneath is wrong, which in this case was a fire nothing could see.
+  emberWidth: 0.9,
+  emberIntensity: 1.45,
+  emberCoverage: 0.6,
+  emberFlicker: 1.65,
+  emberGlow: 1.25,
+  sparkle: 0.5,
+  lipWidth: 1.2,
+  // Was 1.5, its slider's ceiling, which made the ash lip brighter than the
+  // paper it sits on. Ash is pale GREY; the reference's lip is dimmer than
+  // the sheet, not a highlight drawn on it.
+  lipBrightness: 0.85,
+  // Was 1, also a ceiling. At full warmth the char is milk chocolate —
+  // closer to cardboard than to charcoal (§5). Burnt paper keeps a little
+  // warmth in the plates and reads near black in a frame with a fire in it.
+  charWarmth: 0.3,
+  // Was 1, also a ceiling. The cracks are drawn as thin polygon outlines, so
+  // at full strength the char reads as a mosaic rather than as broken plates.
+  charCracks: 0.55,
+  scorchReach: 30,
+  scorchDarkness: 1.17,
+  fingers: 1.25,
+  edgeWave: 8.5,
+  edgeBite: 3.6
+};
+var DAMAGE_CHANNELS = { char: 0, saturation: 1, heat: 2, presence: 3 };
+
+export {
+  DAMAGE_LOOK_DEFAULTS,
+  DAMAGE_CHANNELS
+};
+//# sourceMappingURL=chunk-7TLIWPGM.js.map

package/dist/chunk-7TLIWPGM.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/surface/damageContract.ts"],"sourcesContent":["/**\n * What damage IS, as far as a sheet is concerned. The whole seam.\n *\n * The split is by responsibility. What has happened to the paper belongs to\n * the sheet — it is shading, alpha and eventually stiffness, and only the\n * sheet can draw or simulate those. What CAUSES it belongs to `paperlab/fx`:\n * a flame, a cup of water, a pair of scissors. The main entry draws whatever\n * damage it is handed and has no idea where it came from, which is exactly\n * how `content` already works — `<Paper>` renders a texture without knowing\n * who painted it.\n *\n * The alternative was a public plugin API for the surface composer and the\n * cloth solver, so that fx could reach in. More flexible, and it would have\n * had to be supported for years before a single effect existed to justify its\n * shape. This is one interface and four constants.\n *\n * **This file imports nothing, on purpose.** `paperlab/fx` depends on it —\n * the field is a `DamageSource` and its channel offsets are these — and the\n * boundary test allows fx to reach this one file and nothing else in the\n * library. The moment it imports three, React or the config schema, fx starts\n * dragging the library in behind it.\n */\n\n/**\n * A grid of damage over the sheet's UV, as the sheet reads it.\n *\n * Satisfied structurally by `DamageField` in `paperlab/fx`, and by anything\n * else that can produce four bytes per texel — a baked texture, a recorded\n * burn played back, a test fixture.\n */\nexport interface DamageSource {\n  /** Texels along each edge. The grid is square and covers the whole sheet. */\n  readonly size: number\n  /**\n   * RGBA per texel, 0..255, row-major from v = 0 — the channels are\n   * {@link DAMAGE_CHANNELS}. Read in place, never copied: the source mutates\n   * it and bumps `version`.\n   *\n   * Eight bits, deliberately. The simulation behind it can run in float; what\n   * reaches the GPU is 16 KB per changed frame at 64², against 256 KB for a\n   * 128² float texture, and it does not depend on float-texture filtering,\n   * which not every phone GPU guarantees.\n   */\n  readonly pixels: Uint8Array\n  /** Bumped whenever `pixels` changes. The sheet uploads on a change and never otherwise. */\n  readonly version: number\n  /**\n   * How ragged a burnt or cut edge is DRAWN, 0..1; omitted means 1.\n   *\n   * Presentation only: per-fragment noise that moves the edge within the\n   * grid's soft band, finer than the grid itself can carry. The physics reads\n   * the grid and never this. It is the one part of drawing damage that costs\n   * per pixel, which is why it is a number a source can turn down — `paperlab/fx`\n   * sets it from its quality tier.\n   */\n  readonly detail?: number\n  /**\n   * The burn's own clock, in seconds; omitted means the frame clock.\n   *\n   * Presentation only. The ember line on a burning edge is beaded and alive —\n   * its beads flicker and crawl — and a source that can be replayed wants\n   * that motion to replay too: the same moment of the same burn should draw\n   * the same beads, which the frame clock cannot promise. `DamageField`\n   * hands over its simulated time.\n   */\n  readonly time?: number\n  /**\n   * How a burn is DRAWN — widths, intensities and shapes the sheet's damage\n   * shading reads each frame. Presentation only; the physics never sees it.\n   * Anything left out takes {@link DAMAGE_LOOK_DEFAULTS}.\n   */\n  readonly look?: DamageLook\n}\n\n/**\n * The knobs on what a burn looks like, in the units a person tunes by —\n * millimetres of A4 and plain multipliers. Every one is optional.\n */\nexport interface DamageLook {\n  /** The ember line's widest bead, mm. */\n  emberWidth?: number\n  /** How bright the beads burn, × the default. */\n  emberIntensity?: number\n  /** How much of the edge is lit at once, 0..1. */\n  emberCoverage?: number\n  /** How fast the beads flicker and crawl, × the default. */\n  emberFlicker?: number\n  /** The dim crimson glow beside the beads, reaching into the char, 0..2. */\n  emberGlow?: number\n  /** Specks of glowing fibre along the edge, 0..2. */\n  sparkle?: number\n  /** The pale ash lip's widest point, mm. */\n  lipWidth?: number\n  /** How pale the ash lip is, × the sampled grey. */\n  lipBrightness?: number\n  /** 0 is grey char, 1 is dark orange to deep brown. */\n  charWarmth?: number\n  /** How visible the crack network in the char is, 0..1. */\n  charCracks?: number\n  /** How far the scorch reaches UP past the burn, mm. */\n  scorchReach?: number\n  /** How dark the scorch browns go, × the sampled ramp. */\n  scorchDarkness?: number\n  /** How strongly the scorch front breaks into fingers, × the default. */\n  fingers?: number\n  /** The burnt edge's long waves, ±mm. */\n  edgeWave?: number\n  /** The burnt edge's small bites in and out, ±mm. */\n  edgeBite?: number\n}\n\n/**\n * What every burn is drawn with unless told otherwise — the combination Noor\n * tuned in the lab's sidebar on 2026-09-12, which is the look this ships.\n */\nexport const DAMAGE_LOOK_DEFAULTS: Required<DamageLook> = {\n  // §5 asks for 0.3–1 mm. 1.8 was outside it, and outside the slider's range\n  // it was tuned in — a control at its limit is a report that something\n  // underneath is wrong, which in this case was a fire nothing could see.\n  emberWidth: 0.9,\n  emberIntensity: 1.45,\n  emberCoverage: 0.6,\n  emberFlicker: 1.65,\n  emberGlow: 1.25,\n  sparkle: 0.5,\n  lipWidth: 1.2,\n  // Was 1.5, its slider's ceiling, which made the ash lip brighter than the\n  // paper it sits on. Ash is pale GREY; the reference's lip is dimmer than\n  // the sheet, not a highlight drawn on it.\n  lipBrightness: 0.85,\n  // Was 1, also a ceiling. At full warmth the char is milk chocolate —\n  // closer to cardboard than to charcoal (§5). Burnt paper keeps a little\n  // warmth in the plates and reads near black in a frame with a fire in it.\n  charWarmth: 0.3,\n  // Was 1, also a ceiling. The cracks are drawn as thin polygon outlines, so\n  // at full strength the char reads as a mosaic rather than as broken plates.\n  charCracks: 0.55,\n  scorchReach: 30,\n  scorchDarkness: 1.17,\n  fingers: 1.25,\n  edgeWave: 8.5,\n  edgeBite: 3.6,\n}\n\n/**\n * Which byte of a texel means what.\n *\n * char — scorch colour, the brown halo; on cloth, shrinkage and a curl toward the front.\n * saturation — wet darkening and smoothing; on cloth, added mass.\n * heat — how hot the paper is. Drawn only where it burns: the ember line, not the sheet.\n * presence — how much paper is there at all; below half, none is drawn.\n */\nexport const DAMAGE_CHANNELS = { char: 0, saturation: 1, heat: 2, presence: 3 } as const\n"],"mappings":";AAmHO,IAAM,uBAA6C;AAAA;AAAA;AAAA;AAAA,EAIxD,YAAY;AAAA,EACZ,gBAAgB;AAAA,EAChB,eAAe;AAAA,EACf,cAAc;AAAA,EACd,WAAW;AAAA,EACX,SAAS;AAAA,EACT,UAAU;AAAA;AAAA;AAAA;AAAA,EAIV,eAAe;AAAA;AAAA;AAAA;AAAA,EAIf,YAAY;AAAA;AAAA;AAAA,EAGZ,YAAY;AAAA,EACZ,aAAa;AAAA,EACb,gBAAgB;AAAA,EAChB,SAAS;AAAA,EACT,UAAU;AAAA,EACV,UAAU;AACZ;AAUO,IAAM,kBAAkB,EAAE,MAAM,GAAG,YAAY,GAAG,MAAM,GAAG,UAAU,EAAE;","names":[]}