paperlab 0.2.0 → 0.3.0

package/dist/stage.js

@@ -0,0 +1,2214 @@
+import {
+  AGENT_PAYLOAD_VERSION,
+  LightRig,
+  PaperFieldMesh,
+  PaperLighting,
+  createWalkPath,
+  cssColorOr,
+  diffConfig,
+  getLayout,
+  getWalkPath,
+  lightSchema,
+  lightingNames,
+  paperConfigSchema,
+  resolveConfig,
+  resolveLighting,
+  usePrefersReducedMotion,
+  walkPathSchema
+} from "./chunk-3IMUEESH.js";
+
+// src/stage/PaperStage.tsx
+import * as THREE6 from "three";
+import { Canvas, useFrame as useFrame4, useThree as useThree2 } from "@react-three/fiber";
+import { useCallback as useCallback2, useEffect as useEffect7, useMemo as useMemo7, useRef as useRef5, useState } from "react";
+import { z as z5 } from "zod";
+
+// src/stage/camera.ts
+import { z } from "zod";
+var shotNames = ["follow", "lead", "low", "wide"];
+var shotSchema = z.object({
+  shot: z.enum(shotNames).default("follow"),
+  /**
+   * How far the camera stands off the figure ALONG the walk, world units.
+   * `wide` reads it as how far back it stands; how far it steps aside is
+   * derived from the paper, since that is what it has to clear.
+   */
+  distance: z.number().min(0.2).max(40).default(4.5),
+  /** Multiplier on the shot's natural camera height. 1 is as designed. */
+  height: z.number().min(0).max(6).default(1),
+  /** How far up the walk the camera looks past the figure, world units. */
+  lookAhead: z.number().min(0).max(40).default(7),
+  /** Sideways step off the walk line, world units. Positive is the walker's left. */
+  offset: z.number().min(-20).max(20).default(0)
+});
+var EYE = {
+  follow: 0.95,
+  lead: 0.95,
+  // Down near the floor, where the banners tower — the worm's-eye of the
+  // reference frames, and the cheapest way to make paper read as architecture.
+  low: 0.12,
+  wide: 1.1
+};
+var AIM = {
+  // Chest height on the figure, a third of the way up the paper — enough
+  // tilt that a printed banner reads, not so much that the floor is lost.
+  follow: { figure: 0.62, paper: 0.3 },
+  // Framing the figure itself, so the paper only lifts the aim a little.
+  lead: { figure: 0.62, paper: 0.1 },
+  // Up the banners. The figure is incidental to this shot.
+  low: { figure: 0, paper: 0.62 },
+  wide: { figure: 0.62, paper: 0.2 }
+};
+var WIDE_STANDOFF = 1.5;
+var DEFAULT_PAPER_RATIO = 4.9;
+function resolveScale(scale) {
+  if (typeof scale === "number") return { figure: scale, paper: scale * DEFAULT_PAPER_RATIO };
+  return scale;
+}
+function walkPoint(path, distance) {
+  if (path.length === 0) return path.pointAt(0);
+  if (path.closed) return path.pointAt(distance / path.length);
+  if (distance < 0) {
+    const [x, z6] = path.pointAt(0);
+    const [tx, tz] = path.tangentAt(0);
+    return [x + tx * distance, z6 + tz * distance];
+  }
+  if (distance > path.length) {
+    const over = distance - path.length;
+    const [x, z6] = path.pointAt(1);
+    const [tx, tz] = path.tangentAt(1);
+    return [x + tx * over, z6 + tz * over];
+  }
+  return path.pointAt(distance / path.length);
+}
+function walkNormal(path, distance) {
+  if (path.length === 0) return path.normalAt(0);
+  if (path.closed) return path.normalAt(distance / path.length);
+  return path.normalAt(Math.min(Math.max(distance, 0), path.length) / path.length);
+}
+function stageCamera(path, walked, scale, options) {
+  const { figure, paper } = resolveScale(scale);
+  const eye = figure * EYE[options.shot] * options.height;
+  const aim = figure * AIM[options.shot].figure + paper * AIM[options.shot].paper;
+  let station;
+  let mark;
+  if (options.shot === "lead") {
+    station = walked + options.distance;
+    mark = walked;
+  } else if (options.shot === "wide") {
+    station = walked - options.distance;
+    mark = walked;
+  } else {
+    station = walked - options.distance;
+    mark = walked + options.lookAhead;
+  }
+  const [sx, sz] = walkPoint(path, station);
+  const [mx, mz] = walkPoint(path, mark);
+  const [nx, nz] = walkNormal(path, station);
+  const step = options.offset + (options.shot === "wide" ? paper * WIDE_STANDOFF : 0);
+  return {
+    position: [sx + nx * step, eye, sz + nz * step],
+    target: [mx, aim, mz]
+  };
+}
+
+// src/stage/Figure.tsx
+import * as THREE2 from "three";
+import { Suspense, useEffect as useEffect2, useMemo as useMemo2, useRef } from "react";
+import { useFrame as useFrame2 } from "@react-three/fiber";
+
+// src/stage/RiggedFigure.tsx
+import { useGLTF } from "@react-three/drei";
+import { useFrame } from "@react-three/fiber";
+import { Component, useEffect, useMemo } from "react";
+import * as THREE from "three";
+import { clone as cloneSkeleton } from "three/examples/jsm/utils/SkeletonUtils.js";
+
+// src/stage/gait.ts
+import { z as z2 } from "zod";
+var figureSchema = z2.object({
+  /** Standing height in world units — the scale reference the whole stage is read against. */
+  height: z2.number().min(0.5).max(4).default(1.75),
+  /** World units per second along the walk. A relaxed indoor pace is ~1.2. */
+  speed: z2.number().min(0).max(4).default(1.2),
+  /** Stride length as a fraction of height — how far one step carries. */
+  stride: z2.number().min(0.1).max(1).default(0.42),
+  /** Arm swing, 0..1. Drop it toward 0 for hands-in-pockets stillness. */
+  swing: z2.number().min(0).max(1).default(1),
+  /** Silhouette color. Near-black by default: it should read as an absence, not an object. */
+  color: z2.string().default("#0a0a0c"),
+  /**
+   * How the figure takes light.
+   *
+   * `silhouette` is the flat unlit shape this mode was built around: the
+   * nave is lit from behind, and a shape that reads as an absence never
+   * competes with the paper for attention.
+   *
+   * `shaded` hands the figure to the rig instead — its own materials, lit
+   * by the key and the studio light, so a backlit hall gives it a rim down
+   * one edge and the room fills the other. It costs nothing extra and it is
+   * the reason to bring a good model: at `silhouette` any two rigs with the
+   * same outline are the same picture. Ignored by the capsule figure, which
+   * has no materials worth lighting.
+   */
+  finish: z2.enum(["silhouette", "shaded"]).default("shaded"),
+  /**
+   * Walk or run. `'auto'` decides from `speed` and leg length, at the point
+   * people actually break into a run — see `isRunning`.
+   */
+  gait: z2.enum(["auto", "walk", "run"]).default("auto"),
+  /**
+   * URL of a rigged glTF/GLB to use instead of the capsules. Serializes as a
+   * string, so a `.paper` carrying one stays a `.paper` — but the asset is
+   * NOT part of the library and never ships in the npm tarball; the app hosts
+   * it. Anything that fails to load falls back to the capsule figure rather
+   * than emptying the stage.
+   */
+  model: z2.string().optional()
+});
+var PROPORTIONS = {
+  hip: 0.53,
+  shoulder: 0.82,
+  headRadius: 0.045,
+  headCenter: 0.935,
+  thigh: 0.245,
+  shin: 0.235,
+  upperArm: 0.185,
+  foreArm: 0.165,
+  torsoWidth: 0.19,
+  hipWidth: 0.095,
+  limbRadius: 0.028
+};
+var WALK = {
+  thigh: 0.42,
+  arm: 0.5,
+  knee: 1.1,
+  elbow: 0.38,
+  pelvis: 0.07,
+  chest: 0.14,
+  sway: 0.05,
+  hipDrop: 0.07,
+  lean: 0.045
+};
+var RUN = {
+  thigh: 0.7,
+  arm: 0.95,
+  knee: 1.9,
+  elbow: 1.5,
+  pelvis: 0.14,
+  chest: 0.26,
+  sway: 0.08,
+  hipDrop: 0.1,
+  lean: 0.16
+};
+var BOB = 0.016;
+var RUN_COMPRESS = 0.035;
+var RUN_LIFT = 0.03;
+var RUN_STRIDE = 1.7;
+var LEAN_FULL_SPEED = 1.2;
+var GRAVITY = 9.81;
+var FROUDE_RUN = 0.5;
+var TAU = Math.PI * 2;
+function isRunning(o) {
+  if (o.gait !== "auto") return o.gait === "run";
+  const legLength = PROPORTIONS.hip * o.height;
+  if (legLength <= 0) return false;
+  return o.speed * o.speed / (GRAVITY * legLength) > FROUDE_RUN;
+}
+function cycleLength(o) {
+  const stride = o.stride * (isRunning(o) ? RUN_STRIDE : 1);
+  return stride * o.height * 2;
+}
+function figureGait(distance, o) {
+  const running = isRunning(o);
+  const a = running ? RUN : WALK;
+  const cycle = cycleLength(o);
+  const phase = cycle > 0 ? (distance / cycle % 1 + 1) % 1 : 0;
+  const w = phase * TAU;
+  const leftThigh = a.thigh * Math.sin(w);
+  const rightThigh = a.thigh * Math.sin(w + Math.PI);
+  const flex = (at) => -a.knee * Math.max(0, Math.cos(w - at)) ** 1.5;
+  const leftKnee = flex(7 * Math.PI / 4);
+  const rightKnee = flex(3 * Math.PI / 4);
+  const leftArm = -a.arm * o.swing * Math.sin(w);
+  const rightArm = -a.arm * o.swing * Math.sin(w + Math.PI);
+  const bend = (forwardness) => a.elbow * o.swing * (0.7 + 0.3 * Math.max(0, forwardness));
+  const leftElbow = bend(-Math.sin(w));
+  const rightElbow = bend(-Math.sin(w + Math.PI));
+  const pelvis = a.pelvis * Math.sin(w);
+  const chest = -a.chest * Math.sin(w);
+  const sway = -a.sway * Math.cos(w);
+  const hipDrop = a.hipDrop * Math.cos(w);
+  const midstance = Math.abs(Math.cos(w));
+  const bob = running ? o.height * (RUN_LIFT * (1 - midstance) - RUN_COMPRESS * midstance) : -BOB * o.height * (1 - midstance);
+  return {
+    phase,
+    running,
+    bob,
+    lean: running ? a.lean : a.lean * Math.min(o.speed / LEAN_FULL_SPEED, 1),
+    pelvis,
+    chest,
+    sway,
+    hipDrop,
+    leftThigh,
+    rightThigh,
+    leftKnee,
+    rightKnee,
+    leftArm,
+    rightArm,
+    leftElbow,
+    rightElbow
+  };
+}
+function pickClip(names, running) {
+  return matchClip(names, running ? RUN_CLIP : WALK_CLIP, running ? WALK_CLIP : RUN_CLIP);
+}
+function pickStillClip(names) {
+  return matchClip(names, IDLE_CLIP, WALK_CLIP);
+}
+var WALK_CLIP = /walk/i;
+var RUN_CLIP = /run|jog|sprint/i;
+var IDLE_CLIP = /idle|stand/i;
+function matchClip(names, wanted, fallback) {
+  const best = (re) => names.filter((n) => re.test(n)).sort((a, b) => a.length - b.length)[0];
+  return best(wanted) ?? best(fallback) ?? names[0];
+}
+function clipTimeFor(distance, o, clipDuration) {
+  if (!(clipDuration > 0)) return 0;
+  const cycle = cycleLength(o);
+  if (!(cycle > 0)) return 0;
+  const phase = (distance / cycle % 1 + 1) % 1;
+  return phase * clipDuration;
+}
+function placeFigure(path, distance, o) {
+  const raw = path.length > 0 ? distance / path.length : 0;
+  const s = path.closed ? (raw % 1 + 1) % 1 : Math.min(Math.max(raw, 0), 1);
+  const [x, z6] = path.pointAt(s);
+  const [tx, tz] = path.tangentAt(s);
+  const travelled = path.closed ? distance : Math.min(distance, path.length);
+  return {
+    position: [x, 0, z6],
+    yaw: Math.atan2(tx, tz),
+    pose: figureGait(travelled, o),
+    s
+  };
+}
+
+// src/stage/RiggedFigure.tsx
+import { jsx } from "react/jsx-runtime";
+var ModelBoundary = class extends Component {
+  state = { failed: false };
+  static getDerivedStateFromError() {
+    return { failed: true };
+  }
+  componentDidCatch(error) {
+    console.warn("[paperlab] figure.model failed to load \u2014 using the capsule figure.", error);
+  }
+  render() {
+    return this.state.failed ? this.props.fallback : this.props.children;
+  }
+};
+function Rigged({ url, options, distance, frozen }) {
+  const gltf = useGLTF(url);
+  const scene = useMemo(() => cloneSkeleton(gltf.scene), [gltf.scene]);
+  const silhouette = options.finish === "silhouette";
+  const material = useMemo(
+    () => silhouette ? new THREE.MeshBasicMaterial({ color: options.color, toneMapped: false }) : null,
+    [silhouette, options.color]
+  );
+  useEffect(() => () => material?.dispose(), [material]);
+  const scale = useMemo(() => {
+    scene.traverse((child) => {
+      const mesh = child;
+      if (!mesh.isMesh) return;
+      mesh.userData.plAuthored ??= mesh.material;
+      mesh.material = material ?? mesh.userData.plAuthored;
+      mesh.castShadow = true;
+      mesh.receiveShadow = !silhouette;
+    });
+    scene.updateMatrixWorld(true);
+    const box = new THREE.Box3().setFromObject(scene);
+    const height = box.max.y - box.min.y;
+    return height > 0 ? options.height / height : 1;
+  }, [scene, material, silhouette, options.height]);
+  const mixer = useMemo(() => new THREE.AnimationMixer(scene), [scene]);
+  const clip = useMemo(() => {
+    const names = gltf.animations.map((a) => a.name);
+    const wanted = frozen ? pickStillClip(names) : pickClip(names, isRunning(options));
+    return gltf.animations.find((a) => a.name === wanted) ?? gltf.animations[0];
+  }, [gltf.animations, options, frozen]);
+  useEffect(() => {
+    if (!clip) return;
+    mixer.clipAction(clip).play();
+    return () => {
+      mixer.stopAllAction();
+      mixer.uncacheClip(clip);
+    };
+  }, [mixer, clip]);
+  useFrame(() => {
+    if (!clip) return;
+    mixer.setTime(frozen ? 0 : clipTimeFor(distance.current, options, clip.duration));
+  });
+  return /* @__PURE__ */ jsx("primitive", { object: scene, scale });
+}
+function RiggedFigure({ fallback, ...props }) {
+  return /* @__PURE__ */ jsx(ModelBoundary, { fallback, children: /* @__PURE__ */ jsx(Rigged, { ...props }) });
+}
+
+// src/stage/Figure.tsx
+import { jsx as jsx2, jsxs } from "react/jsx-runtime";
+function Segment({ length, radius, material }) {
+  const shaft = Math.max(length - radius * 2, 1e-3);
+  return /* @__PURE__ */ jsx2("mesh", { position: [0, -length / 2, 0], material, castShadow: true, children: /* @__PURE__ */ jsx2("capsuleGeometry", { args: [radius, shaft, 4, 10] }) });
+}
+function Figure({ path, figure, distance, distanceRef, walkLength, frozen }) {
+  const reducedMotion = usePrefersReducedMotion();
+  const still = frozen ?? reducedMotion;
+  const options = useMemo2(() => figureSchema.parse(figure ?? {}), [figure]);
+  const walk = useMemo2(() => getWalkPath(walkPathSchema.parse(path ?? {})), [path]);
+  const root = useRef(null);
+  const walkedRef = useRef(0);
+  const hips = useRef(null);
+  const chest = useRef(null);
+  const legL = useRef(null);
+  const legR = useRef(null);
+  const kneeL = useRef(null);
+  const kneeR = useRef(null);
+  const armL = useRef(null);
+  const armR = useRef(null);
+  const elbowL = useRef(null);
+  const elbowR = useRef(null);
+  const material = useMemo2(
+    () => new THREE2.MeshBasicMaterial({ color: options.color, toneMapped: false }),
+    [options.color]
+  );
+  useEffect2(() => () => material.dispose(), [material]);
+  const h = options.height;
+  const p = PROPORTIONS;
+  const torso = (p.shoulder - p.hip) * h;
+  useFrame2((state) => {
+    const walked = distanceRef !== void 0 ? distanceRef.current * (walkLength ?? walk.length) : distance ?? (still ? 0 : state.clock.elapsedTime * options.speed);
+    walkedRef.current = walked;
+    const { position, yaw, pose } = placeFigure(walk, walked, options);
+    root.current?.position.set(position[0], position[1], position[2]);
+    if (root.current) root.current.rotation.y = yaw;
+    if (hips.current) {
+      hips.current.position.y = p.hip * h + (still ? 0 : pose.bob);
+      hips.current.rotation.y = still ? 0 : pose.pelvis;
+      hips.current.rotation.z = still ? 0 : pose.hipDrop;
+    }
+    if (chest.current) {
+      chest.current.rotation.x = pose.lean;
+      chest.current.rotation.y = still ? 0 : pose.chest - pose.pelvis;
+      chest.current.rotation.z = still ? 0 : pose.sway - pose.hipDrop;
+    }
+    if (legL.current) legL.current.rotation.x = still ? 0 : -pose.leftThigh;
+    if (legR.current) legR.current.rotation.x = still ? 0 : -pose.rightThigh;
+    if (kneeL.current) kneeL.current.rotation.x = still ? 0 : -pose.leftKnee;
+    if (kneeR.current) kneeR.current.rotation.x = still ? 0 : -pose.rightKnee;
+    if (armL.current) armL.current.rotation.x = still ? 0 : -pose.leftArm;
+    if (armR.current) armR.current.rotation.x = still ? 0 : -pose.rightArm;
+    if (elbowL.current) elbowL.current.rotation.x = still ? 0 : -pose.leftElbow;
+    if (elbowR.current) elbowR.current.rotation.x = still ? 0 : -pose.rightElbow;
+  });
+  const capsules = /* @__PURE__ */ jsxs("group", { ref: hips, children: [
+    [-1, 1].map((side) => {
+      const leg = side < 0 ? legL : legR;
+      const knee = side < 0 ? kneeL : kneeR;
+      return /* @__PURE__ */ jsxs("group", { ref: leg, position: [side * p.hipWidth * h / 2, 0, 0], children: [
+        /* @__PURE__ */ jsx2(Segment, { length: p.thigh * h, radius: p.limbRadius * h, material }),
+        /* @__PURE__ */ jsx2("group", { ref: knee, position: [0, -p.thigh * h, 0], children: /* @__PURE__ */ jsx2(Segment, { length: p.shin * h, radius: p.limbRadius * h * 0.9, material }) })
+      ] }, `leg${side}`);
+    }),
+    /* @__PURE__ */ jsxs("group", { ref: chest, children: [
+      /* @__PURE__ */ jsx2("mesh", { position: [0, torso / 2, 0], material, castShadow: true, children: /* @__PURE__ */ jsx2("capsuleGeometry", { args: [p.torsoWidth * h / 2, torso * 0.72, 4, 12] }) }),
+      /* @__PURE__ */ jsx2("mesh", { position: [0, (p.headCenter - p.hip) * h, 0], material, castShadow: true, children: /* @__PURE__ */ jsx2("sphereGeometry", { args: [p.headRadius * h, 14, 12] }) }),
+      [-1, 1].map((side) => /* @__PURE__ */ jsxs(
+        "group",
+        {
+          ref: side < 0 ? armL : armR,
+          position: [side * p.torsoWidth * h / 2, torso, 0],
+          children: [
+            /* @__PURE__ */ jsx2(Segment, { length: p.upperArm * h, radius: p.limbRadius * h * 0.8, material }),
+            /* @__PURE__ */ jsx2("group", { ref: side < 0 ? elbowL : elbowR, position: [0, -p.upperArm * h, 0], children: /* @__PURE__ */ jsx2(Segment, { length: p.foreArm * h, radius: p.limbRadius * h * 0.72, material }) })
+          ]
+        },
+        `arm${side}`
+      ))
+    ] })
+  ] });
+  return /* @__PURE__ */ jsx2("group", { ref: root, children: options.model ? (
+    // The capsules are both the fallback and the thing being replaced, so
+    // a model that is still downloading shows a walking figure rather than
+    // a hole, and one that never arrives leaves the stage as it was.
+    /* @__PURE__ */ jsx2(Suspense, { fallback: capsules, children: /* @__PURE__ */ jsx2(
+      RiggedFigure,
+      {
+        url: options.model,
+        options,
+        distance: walkedRef,
+        frozen: still,
+        fallback: capsules
+      }
+    ) })
+  ) : capsules });
+}
+
+// src/stage/Surround.tsx
+import * as THREE3 from "three";
+import { useEffect as useEffect3, useMemo as useMemo3 } from "react";
+import { jsx as jsx3, jsxs as jsxs2 } from "react/jsx-runtime";
+function makeSkyTexture(sky) {
+  const canvas = document.createElement("canvas");
+  canvas.width = 4;
+  canvas.height = 256;
+  const ctx = canvas.getContext("2d");
+  const grade = ctx.createLinearGradient(0, 0, 0, canvas.height);
+  const zenith = cssColorOr(sky.zenith, "#241c17");
+  const horizon = cssColorOr(sky.horizon, "#fff4e2");
+  const ground = cssColorOr(sky.ground, "#141210");
+  grade.addColorStop(0, zenith);
+  grade.addColorStop(0.3, zenith);
+  grade.addColorStop(0.62, horizon);
+  grade.addColorStop(0.7, horizon);
+  grade.addColorStop(1, ground);
+  ctx.fillStyle = grade;
+  ctx.fillRect(0, 0, canvas.width, canvas.height);
+  const texture = new THREE3.CanvasTexture(canvas);
+  texture.colorSpace = THREE3.SRGBColorSpace;
+  return texture;
+}
+function makeGlowTexture(color) {
+  const size = 256;
+  const canvas = document.createElement("canvas");
+  canvas.width = canvas.height = size;
+  const ctx = canvas.getContext("2d");
+  const glow = ctx.createRadialGradient(size / 2, size / 2, 0, size / 2, size / 2, size / 2);
+  const c = new THREE3.Color(color);
+  const rgb = `${c.r * 255 | 0}, ${c.g * 255 | 0}, ${c.b * 255 | 0}`;
+  for (const [stop, alpha] of [
+    [0, 1],
+    [0.5, 1],
+    [0.62, 0.66],
+    [0.74, 0.34],
+    [0.86, 0.11],
+    [0.94, 0.03],
+    [1, 0]
+  ]) {
+    glow.addColorStop(stop, `rgba(${rgb}, ${alpha})`);
+  }
+  ctx.fillStyle = glow;
+  ctx.fillRect(0, 0, size, size);
+  const texture = new THREE3.CanvasTexture(canvas);
+  texture.colorSpace = THREE3.SRGBColorSpace;
+  return texture;
+}
+var SOURCE_INTENSITY = 3.4;
+function Source({
+  size,
+  position,
+  yaw,
+  color,
+  intensity = SOURCE_INTENSITY
+}) {
+  const texture = useMemo3(() => makeGlowTexture(color), [color]);
+  useEffect3(() => () => texture.dispose(), [texture]);
+  return /* @__PURE__ */ jsxs2("mesh", { position, rotation: [0, yaw, 0], children: [
+    /* @__PURE__ */ jsx3("planeGeometry", { args: [size * 2.4, size * 1.8] }),
+    /* @__PURE__ */ jsx3(
+      "meshBasicMaterial",
+      {
+        map: texture,
+        transparent: true,
+        color: new THREE3.Color(intensity, intensity, intensity),
+        depthWrite: false,
+        fog: false
+      }
+    )
+  ] });
+}
+function Surround({ radius, sky }) {
+  const { zenith, horizon, ground } = sky;
+  const texture = useMemo3(() => makeSkyTexture({ zenith, horizon, ground }), [zenith, horizon, ground]);
+  useEffect3(() => () => texture.dispose(), [texture]);
+  return /* @__PURE__ */ jsxs2("mesh", { children: [
+    /* @__PURE__ */ jsx3("sphereGeometry", { args: [radius, 32, 24] }),
+    /* @__PURE__ */ jsx3("meshBasicMaterial", { map: texture, side: THREE3.BackSide, fog: false })
+  ] });
+}
+
+// src/stage/Room.tsx
+import * as THREE4 from "three";
+import { useEffect as useEffect4, useMemo as useMemo4, useRef as useRef2 } from "react";
+import { jsx as jsx4, jsxs as jsxs3 } from "react/jsx-runtime";
+function makeFloorTexture(color, repeats) {
+  const size = 256;
+  const canvas = document.createElement("canvas");
+  canvas.width = canvas.height = size;
+  const ctx = canvas.getContext("2d");
+  ctx.fillStyle = color;
+  ctx.fillRect(0, 0, size, size);
+  const base = new THREE4.Color(color);
+  const dark = base.clone().multiplyScalar(0.55);
+  const softer = base.clone().multiplyScalar(0.78);
+  const css = (c) => `rgb(${c.r * 255 | 0}, ${c.g * 255 | 0}, ${c.b * 255 | 0})`;
+  ctx.strokeStyle = css(softer);
+  ctx.lineWidth = 5;
+  ctx.strokeRect(0, 0, size, size);
+  ctx.strokeStyle = css(dark);
+  ctx.lineWidth = 1.5;
+  ctx.strokeRect(0, 0, size, size);
+  const texture = new THREE4.CanvasTexture(canvas);
+  texture.colorSpace = THREE4.SRGBColorSpace;
+  texture.wrapS = texture.wrapT = THREE4.RepeatWrapping;
+  texture.repeat.set(repeats, repeats);
+  texture.anisotropy = 8;
+  return texture;
+}
+function Floor({
+  size,
+  color,
+  slab
+}) {
+  const repeats = slab > 0 ? Math.max(1, Math.round(size / slab)) : 0;
+  const texture = useMemo4(() => repeats > 0 ? makeFloorTexture(color, repeats) : null, [color, repeats]);
+  useEffect4(() => () => texture?.dispose(), [texture]);
+  return /* @__PURE__ */ jsxs3("mesh", { rotation: [-Math.PI / 2, 0, 0], receiveShadow: true, children: [
+    /* @__PURE__ */ jsx4("planeGeometry", { args: [size, size] }),
+    /* @__PURE__ */ jsx4("meshStandardMaterial", { map: texture, color: texture ? "#ffffff" : color, roughness: 1 })
+  ] });
+}
+function Ceiling({ size, height, color }) {
+  return /* @__PURE__ */ jsxs3("mesh", { position: [0, height, 0], rotation: [Math.PI / 2, 0, 0], receiveShadow: true, children: [
+    /* @__PURE__ */ jsx4("planeGeometry", { args: [size, size] }),
+    /* @__PURE__ */ jsx4("meshStandardMaterial", { color, roughness: 1, side: THREE4.FrontSide })
+  ] });
+}
+function Columns({
+  path,
+  ceiling,
+  spacing,
+  width,
+  offset,
+  color
+}) {
+  const placements = useMemo4(() => {
+    if (!(spacing > 0) || !(path.length > 0)) return [];
+    const bays = Math.max(1, Math.round(path.length / spacing));
+    const out = [];
+    for (let i = 0; i <= bays; i++) {
+      const s = i / bays;
+      const [px, pz] = path.pointAt(s);
+      const [nx, nz] = path.normalAt(s);
+      const [tx, tz] = path.tangentAt(s);
+      const yaw = Math.atan2(tx, tz);
+      for (const side of [-1, 1]) {
+        out.push({ position: [px + nx * side * offset, 0, pz + nz * side * offset], yaw });
+      }
+    }
+    return out;
+  }, [path, spacing, offset]);
+  const shaft = useRef2(null);
+  const base = useRef2(null);
+  const capital = useRef2(null);
+  const plate = width * 1.45;
+  const plateHeight = width * 0.24;
+  useEffect4(() => {
+    const m = new THREE4.Matrix4();
+    const q = new THREE4.Quaternion();
+    const scale = new THREE4.Vector3(1, 1, 1);
+    const put = (mesh, y) => {
+      if (!mesh) return;
+      placements.forEach((p, i) => {
+        q.setFromEuler(new THREE4.Euler(0, p.yaw, 0));
+        m.compose(new THREE4.Vector3(p.position[0], y, p.position[2]), q, scale);
+        mesh.setMatrixAt(i, m);
+      });
+      mesh.instanceMatrix.needsUpdate = true;
+      mesh.count = placements.length;
+    };
+    put(shaft.current, ceiling / 2);
+    put(base.current, plateHeight / 2);
+    put(capital.current, ceiling - plateHeight / 2);
+  }, [placements, ceiling, plateHeight]);
+  if (placements.length === 0) return null;
+  const n = placements.length;
+  return /* @__PURE__ */ jsxs3("group", { children: [
+    /* @__PURE__ */ jsxs3("instancedMesh", { ref: shaft, args: [void 0, void 0, n], castShadow: true, receiveShadow: true, children: [
+      /* @__PURE__ */ jsx4("boxGeometry", { args: [width, ceiling, width] }),
+      /* @__PURE__ */ jsx4("meshStandardMaterial", { color, roughness: 0.92 })
+    ] }),
+    /* @__PURE__ */ jsxs3("instancedMesh", { ref: base, args: [void 0, void 0, n], castShadow: true, receiveShadow: true, children: [
+      /* @__PURE__ */ jsx4("boxGeometry", { args: [plate, plateHeight, plate] }),
+      /* @__PURE__ */ jsx4("meshStandardMaterial", { color, roughness: 0.92 })
+    ] }),
+    /* @__PURE__ */ jsxs3("instancedMesh", { ref: capital, args: [void 0, void 0, n], castShadow: true, receiveShadow: true, children: [
+      /* @__PURE__ */ jsx4("boxGeometry", { args: [plate, plateHeight, plate] }),
+      /* @__PURE__ */ jsx4("meshStandardMaterial", { color, roughness: 0.92 })
+    ] })
+  ] });
+}
+var NUDGE = 0.08;
+function Doorway({
+  position,
+  yaw,
+  size,
+  opening,
+  color,
+  extent
+}) {
+  const geometry = useMemo4(() => {
+    const w = size * 2.4 * opening;
+    const h = size * 1.8 * opening;
+    const shape = new THREE4.Shape();
+    shape.moveTo(-extent, -extent);
+    shape.lineTo(extent, -extent);
+    shape.lineTo(extent, extent);
+    shape.lineTo(-extent, extent);
+    shape.closePath();
+    const hole = new THREE4.Path();
+    hole.moveTo(-w / 2, -h / 2);
+    hole.lineTo(w / 2, -h / 2);
+    hole.lineTo(w / 2, h / 2);
+    hole.lineTo(-w / 2, h / 2);
+    hole.closePath();
+    shape.holes.push(hole);
+    return new THREE4.ShapeGeometry(shape);
+  }, [size, opening, extent]);
+  useEffect4(() => () => geometry.dispose(), [geometry]);
+  const stood = useMemo4(
+    () => [position[0] + Math.sin(yaw) * NUDGE, position[1], position[2] + Math.cos(yaw) * NUDGE],
+    [position, yaw]
+  );
+  return /* @__PURE__ */ jsx4("mesh", { geometry, position: stood, rotation: [0, yaw, 0], receiveShadow: true, children: /* @__PURE__ */ jsx4("meshStandardMaterial", { color, roughness: 1, side: THREE4.DoubleSide }) });
+}
+
+// src/stage/Suspension.tsx
+import * as THREE5 from "three";
+import { useEffect as useEffect5, useMemo as useMemo5, useRef as useRef3 } from "react";
+import { jsx as jsx5, jsxs as jsxs4 } from "react/jsx-runtime";
+var euler = (pose) => new THREE5.Euler(pose.rotation[0], pose.rotation[1], pose.rotation[2]);
+function rodLength(sheet, pose) {
+  return sheet.width * pose.scale * 1.22;
+}
+function topOfSheet(pose, paperHeight) {
+  const half = paperHeight * pose.scale / 2;
+  const up = new THREE5.Vector3(0, half, 0).applyEuler(
+    new THREE5.Euler(pose.rotation[0], pose.rotation[1], pose.rotation[2])
+  );
+  return new THREE5.Vector3(...pose.position).add(up);
+}
+function Suspension({
+  layout,
+  layoutOptions,
+  count,
+  sheet,
+  paperHeight,
+  ceiling,
+  color,
+  type,
+  hardware
+}) {
+  const poses = useMemo5(() => {
+    const entry = getLayout(layout);
+    if (!entry) return [];
+    const options = entry.optionsSchema.parse(layoutOptions);
+    return Array.from({ length: count }, (_, i) => entry.pose(i, count, options, 0, sheet));
+  }, [layout, layoutOptions, count, sheet]);
+  const geometry = useMemo5(() => {
+    const points = [];
+    const end = new THREE5.Vector3();
+    for (const pose of poses) {
+      const top = topOfSheet(pose, paperHeight);
+      if (top.y >= ceiling) continue;
+      if (type === "rod") {
+        const half = rodLength(sheet, pose) / 2;
+        for (const side of [-1, 1]) {
+          end.set(side * half, 0, 0).applyEuler(euler(pose)).add(top);
+          points.push(end.x, ceiling, end.z, end.x, end.y, end.z);
+        }
+      } else {
+        points.push(top.x, ceiling, top.z, top.x, top.y, top.z);
+      }
+    }
+    const g = new THREE5.BufferGeometry();
+    g.setAttribute("position", new THREE5.Float32BufferAttribute(points, 3));
+    return g;
+  }, [poses, paperHeight, ceiling, type, sheet]);
+  useEffect5(() => () => geometry.dispose(), [geometry]);
+  const clipRef = useRef3(null);
+  const rodRef = useRef3(null);
+  const rodGeometry = useMemo5(() => {
+    const r = sheet.width * 0.018;
+    const g = new THREE5.CylinderGeometry(r, r, sheet.width * 1.22, 8);
+    g.rotateZ(Math.PI / 2);
+    return g;
+  }, [sheet.width]);
+  useEffect5(() => () => rodGeometry.dispose(), [rodGeometry]);
+  useEffect5(() => {
+    const m = new THREE5.Matrix4();
+    const q = new THREE5.Quaternion();
+    const at = new THREE5.Vector3();
+    const size = new THREE5.Vector3();
+    const place = (mesh, lift) => {
+      if (!mesh) return;
+      poses.forEach((pose, i) => {
+        const top = topOfSheet(pose, paperHeight);
+        q.setFromEuler(euler(pose));
+        at.set(top.x, top.y + lift, top.z);
+        size.setScalar(pose.scale);
+        m.compose(at, q, size);
+        mesh.setMatrixAt(i, m);
+      });
+      mesh.instanceMatrix.needsUpdate = true;
+      mesh.count = poses.length;
+    };
+    place(clipRef.current, 0);
+    place(rodRef.current, sheet.height * 4e-3);
+  }, [poses, paperHeight, sheet.height]);
+  if (poses.length === 0) return null;
+  return /* @__PURE__ */ jsxs4("group", { children: [
+    /* @__PURE__ */ jsx5("lineSegments", { geometry, children: /* @__PURE__ */ jsx5("lineBasicMaterial", { color, transparent: true, opacity: 0.42 }) }),
+    type === "rod" && /* @__PURE__ */ jsxs4("instancedMesh", { ref: rodRef, args: [void 0, void 0, Math.max(poses.length, 1)], castShadow: true, children: [
+      /* @__PURE__ */ jsx5("primitive", { object: rodGeometry, attach: "geometry" }),
+      /* @__PURE__ */ jsx5("meshStandardMaterial", { color, roughness: 0.7, metalness: 0.15 })
+    ] }),
+    hardware !== "none" && /* @__PURE__ */ jsxs4("instancedMesh", { ref: clipRef, args: [void 0, void 0, Math.max(poses.length, 1)], castShadow: true, children: [
+      hardware === "peg" ? /* @__PURE__ */ jsx5("boxGeometry", { args: [sheet.width * 0.055, sheet.height * 0.038, sheet.width * 0.05] }) : /* @__PURE__ */ jsx5("boxGeometry", { args: [sheet.width * 0.13, sheet.height * 0.016, sheet.width * 0.05] }),
+      /* @__PURE__ */ jsx5(
+        "meshStandardMaterial",
+        {
+          color,
+          roughness: hardware === "peg" ? 0.85 : 0.45,
+          metalness: hardware === "peg" ? 0 : 0.6
+        }
+      )
+    ] })
+  ] });
+}
+
+// src/stage/Grade.tsx
+import {
+  EffectComposer,
+  Bloom,
+  DepthOfField,
+  Vignette,
+  Noise,
+  ToneMapping
+} from "@react-three/postprocessing";
+import { BlendFunction, ToneMappingMode } from "postprocessing";
+import { jsx as jsx6, jsxs as jsxs5 } 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__ */ jsxs5(EffectComposer, { children: [
+    bloom ? /* @__PURE__ */ jsx6(
+      Bloom,
+      {
+        intensity: grade.bloom,
+        luminanceThreshold: grade.threshold,
+        luminanceSmoothing: 0.22,
+        mipmapBlur: true
+      }
+    ) : null,
+    depth ? /* @__PURE__ */ jsx6(
+      DepthOfField,
+      {
+        focusDistance: 8e-3,
+        focalLength: 0.02 + grade.depth * 0.04,
+        bokehScale: grade.depth * 2.5
+      }
+    ) : null,
+    /* @__PURE__ */ jsx6(ToneMapping, { mode: toneMappingModes[film] }),
+    vignette ? /* @__PURE__ */ jsx6(Vignette, { offset: 0.32, darkness: grade.vignette }) : null,
+    grain ? /* @__PURE__ */ jsx6(Noise, { opacity: grade.grain, blendFunction: BlendFunction.OVERLAY }) : null
+  ] });
+}
+
+// src/stage/schema.ts
+import { z as z3 } from "zod";
+var stageSourceSchema = z3.object({
+  /** The bright void the walk resolves toward. Without it the vanishing point is a hole. */
+  enabled: z3.boolean().default(true),
+  color: z3.string().default("#fff4e2"),
+  /** How far past the end of the walk it stands, world units. */
+  beyond: z3.number().min(0).max(80).default(10),
+  /**
+   * A cyclorama around the whole stage, graded from the source colour at the
+   * horizon to near-dark overhead. The source plane only faces down the walk,
+   * so without this every shot that isn't axial — `wide` especially — looks
+   * out at a black void where the room should be.
+   */
+  surround: z3.boolean().default(true),
+  /** Colour overhead. The horizon takes the source's own colour. */
+  zenith: z3.string().default("#241c17"),
+  /**
+   * Size, as a multiple of the PAPER height.
+   *
+   * It is an OPENING, not a wall. At 5 the plane was 100 units across and
+   * filled the entire frame behind the colonnade, so the hall had no dark
+   * end to resolve toward and the whole picture sat at one value. Sized to
+   * roughly the height of the paper it stands behind, it reads as the way
+   * out — which is what the figure is walking toward.
+   */
+  spread: z3.number().min(0.2).max(60).default(2)
+});
+var stageGroundSchema = z3.object({
+  /** The floor. Without something to catch the shadows there is no ground and no scale. */
+  enabled: z3.boolean().default(true),
+  /**
+   * Lifted off near-black (`#0e0b09`). A floor dark enough to disappear
+   * cannot show its own seams, and the seams are the scale cue — the hall
+   * kept its contrast against the source and gained a surface you can read
+   * the size of the room from.
+   */
+  color: z3.string().default("#241e19"),
+  /**
+   * Width of one poured slab, in world units. 0 leaves the floor unseamed.
+   *
+   * The cheapest scale cue there is, and the one this scene most lacked. A
+   * concrete floor is poured in bays of roughly two and a half metres, and a
+   * viewer knows that without being told — so a floor with seams in it
+   * states the size of the room, while a floor without them is a gradient
+   * that happens to be horizontal.
+   */
+  slab: z3.number().min(0).max(20).default(2.4)
+});
+var stageSuspensionSchema = z3.object({
+  /**
+   * What carries the load.
+   *
+   * `thread` is monofilament to the ceiling — one straight line per sheet.
+   * `rod` is a dowel across each sheet's top edge, hung from the ceiling at
+   * both ends, which is a different image entirely: a rank on threads reads
+   * as sheets floating in a row, and a rank on rods reads as sheets that
+   * were HUNG, by someone, on something. `none` is for a stage where the
+   * paper is meant to be impossible.
+   */
+  type: z3.enum(["none", "thread", "rod"]).default("thread"),
+  color: z3.string().default("#9c948a"),
+  /**
+   * What grips the sheet.
+   *
+   * A clip is wide and shallow — the bulldog clip of a gallery. A peg is
+   * narrow and deep, and grips DOWN the face of the sheet rather than
+   * across its edge: the domestic one, a line of paper on a washing line.
+   * They are told apart by silhouette at any distance, which is the only
+   * thing that survives being one instanced box at the top of an
+   * eight-metre banner.
+   *
+   * This replaced a `clips: boolean`. Two of the four pieces of hardware the
+   * plan named — pegs, and a rod — had no way to be asked for, and a boolean
+   * cannot grow a third answer.
+   */
+  hardware: z3.enum(["none", "clip", "peg"]).default("clip")
+});
+var stageColumnsSchema = z3.object({
+  enabled: z3.boolean().default(false),
+  /** Centres this far apart along the walk. Roughly a bay. */
+  spacing: z3.number().min(1).max(24).default(7),
+  /** Shaft width. The number doing the work — a column is a known size. */
+  width: z3.number().min(0.1).max(3).default(0.44),
+  /**
+   * How far off the walk's centreline each rank stands.
+   *
+   * Outside the banners, always. Columns are the room; the paper is the
+   * subject, and a column standing between the viewer and a banner has
+   * swapped the two over. Default clears a `colonnade`'s widest sensible
+   * aisle with room to spare.
+   */
+  offset: z3.number().min(0.5).max(24).default(6.6),
+  /**
+   * Stone, and darker than paper on purpose.
+   *
+   * The brightest thing in any of these frames has to be the light, and the
+   * second brightest has to be the paper. A column the same value as a
+   * banner does not read as architecture behind the subject; it reads as
+   * more banners, and the eye stops being able to tell what the room is made
+   * of from what is hanging in it.
+   */
+  color: z3.string().default("#5c554d")
+});
+var stageDoorwaySchema = z3.object({
+  enabled: z3.boolean().default(false),
+  /** Opening size, as a multiple of the source's own. 1 frames it exactly. */
+  opening: z3.number().min(0.2).max(3).default(1.05),
+  color: z3.string().default("#171310")
+});
+var stageRoomSchema = z3.object({
+  enabled: z3.boolean().default(true),
+  /**
+   * Ceiling height, as a multiple of the paper's own height.
+   *
+   * Relative rather than absolute because the banners ARE the architecture
+   * here: a hall whose ceiling sits just above its hangings reads as built
+   * for them, and one at a fixed world height reads as whatever the paper
+   * happened to be scaled to that day.
+   */
+  height: z3.number().min(1).max(6).default(2.2),
+  color: z3.string().default("#171310"),
+  /** Columns flanking the walk — see `stageColumnsSchema`. */
+  columns: stageColumnsSchema.default({}),
+  /** A wall at the end of the walk with the source in it. */
+  doorway: stageDoorwaySchema.default({})
+});
+var stageGradeSchema = z3.object({
+  /**
+   * How far light bleeds past what is emitting it.
+   *
+   * This is the one that matters most in a backlit hall, because the source
+   * plane is drawn with `toneMapped: false` — it is light, not an object, so
+   * no tone curve ever rolls it off. Bloom is the only thing that gives it
+   * an edge that behaves like light instead of like a lit rectangle.
+   */
+  bloom: z3.number().min(0).max(3).default(0.45),
+  /**
+   * How bright a pixel has to be before it blooms at all, in LINEAR light.
+   *
+   * Above 1.0 is not only legal, it is the useful range — and that is the
+   * whole reason the bound is 4 rather than 1. Bloom reads the scene before
+   * the tone curve, while values are still unbounded, so "1.0" means "as
+   * bright as white" rather than "as bright as the brightest pixel on
+   * screen". Lit near-white paper sits close to 1.0 all by itself; the
+   * source burns at `SOURCE_INTENSITY`, several times that. A threshold
+   * under 1 therefore blooms the PAPER, which fogs the hall and costs the
+   * sheets their edges — the exact failure this default is set to avoid.
+   */
+  threshold: z3.number().min(0).max(4).default(1.6),
+  /**
+   * Depth falloff — how much the near and far ends of the walk go soft.
+   *
+   * **Defaults to 0, and that is a considered default rather than a stub.**
+   * Depth in this scene is already staged by haze, which is how a real hall
+   * does it and which costs one fragment instruction; optical blur is a
+   * second full-screen pass with a circle-of-confusion buffer behind it, and
+   * it is the effect most likely to read as a video game rather than as a
+   * photograph. Every paper installation worth copying is shot deep — an
+   * f/11 room where the sheets at the far end are as sharp as the ones you
+   * can touch.
+   *
+   * It is here because a shallow frame is a legitimate look and the schema
+   * is the only place a look is allowed to live. Turn it up for a close shot
+   * on one banner; leave it alone for a hall.
+   */
+  depth: z3.number().min(0).max(1).default(0),
+  /** How far the corners fall off. A frame with no edge reads as a viewport rather than a photograph. */
+  vignette: z3.number().min(0).max(1).default(0.34),
+  /**
+   * Film grain.
+   *
+   * Worth more here than in most scenes: grain is the one texture shared
+   * between the render and the thing being rendered. Keep it under ~0.05 —
+   * past that it stops reading as stock and starts reading as noise.
+   */
+  grain: z3.number().min(0).max(0.5).default(0.022)
+});
+var stageSchema = z3.object({
+  path: walkPathSchema.default({}),
+  shot: shotSchema.default({}),
+  figure: figureSchema.default({}),
+  /** Stage mode is built for `nave`; the others are all front-lit. */
+  lighting: z3.enum(lightingNames).default("nave"),
+  /**
+   * The light, by hand: exposure, key, direction, height, ambient, studio,
+   * haze. Overrides on `lighting` rather than a replacement for it, so a
+   * shared stage carries the sliders that were moved and nothing else.
+   */
+  light: lightSchema.default({}),
+  /**
+   * OFF by default now.
+   *
+   * The figure existed to say "this is a room at gallery scale", which is a
+   * real job and the right instinct. A rendered human is simply the most
+   * expensive and least reliable way to do it: it is the one thing in frame
+   * every viewer appraises, and a low-polygon one reads as an asset-store
+   * placeholder no matter how good the hall around it is.
+   *
+   * `stageRoomSchema` does the job instead, with objects whose size the
+   * viewer already knows. And the deciding argument is that the stage is
+   * NAVIGABLE — drag, wheel, arrow-step, click-to-approach — so there is
+   * already a person in the hall and it is the viewer. A second one walking
+   * the same aisle on its own clock competes for that role.
+   *
+   * Still one flag away for anyone who wants it.
+   */
+  showFigure: z3.boolean().default(false),
+  source: stageSourceSchema.default({}),
+  ground: stageGroundSchema.default({}),
+  /** Ceiling and the architecture around the walk — see `stageRoomSchema`. */
+  room: stageRoomSchema.default({}),
+  /** Thread and clips — see `stageSuspensionSchema`. */
+  suspension: stageSuspensionSchema.default({}),
+  /**
+   * The print — bloom, vignette, grain.
+   *
+   * Needs `@react-three/postprocessing` and `postprocessing`. They are
+   * declared OPTIONAL peers, which means `<Paper>` never pulls them in and a
+   * bundle that only imports `<Paper>` never contains them — not that a
+   * stage renders without them. A bundler asked to resolve `<PaperStage>`
+   * without them installed fails at build time, and that is the intended
+   * behaviour: a stage silently losing its grade would be worse than a
+   * missing-module error that names the package.
+   */
+  grade: stageGradeSchema.default({})
+});
+
+// src/stage/navigate.ts
+import { z as z4 } from "zod";
+var stageMotionSchema = z4.object({
+  /**
+   * Who drives the walk. Same three names as a field's, and they mean the
+   * same things — a stage and a field are the same contract seen from two
+   * distances.
+   *
+   * - `drag` — the viewer. Pointer, wheel, arrow keys, or a click on a paper.
+   *   It DRIFTS on the clock until the first time they touch it, and then it
+   *   is theirs for good. That is one behaviour rather than two drivers, and
+   *   it is the default because the alternatives are each half wrong: a stage
+   *   that only autoplays cannot be touched, and one that only waits opens as
+   *   a still photograph of itself.
+   * - `autoplay` — the clock, and only the clock. It never hands over.
+   * - `none` — nothing. The walk stands wherever it was left.
+   *
+   * An explicit `progress` prop outranks all three: a stage bound to page
+   * scroll is a controlled component, and a driver fighting the page for the
+   * same number is the bug you would spend an afternoon on.
+   */
+  driver: z4.enum(["autoplay", "drag", "none"]).default("drag"),
+  /** Multiplier on the pace: the figure's walking speed for `autoplay`, the hand for `drag`. */
+  speed: z4.number().min(0).max(6).default(1),
+  /**
+   * Whether the walk takes the WHEEL and the TOUCH away from the page.
+   *
+   * True for a stage that fills the screen — it is the page, so there is
+   * nothing to take it from. False for one sitting in a column of prose,
+   * where capturing them means a reader who scrolls past it has their scroll
+   * eaten and a reader on a phone has their finger trapped. Dragging with a
+   * mouse and stepping with the arrow keys work either way, because neither
+   * is a gesture the page also wants.
+   *
+   * Even when captured, the wheel is handed BACK at the ends of an open
+   * walk: scrolling past the last banner should carry on down the page
+   * rather than press silently into a wall.
+   */
+  capture: z4.boolean().default(true)
+});
+var WALK_PER_PIXEL = 0.2 / 800;
+var WALK_PER_WHEEL = 0.2 / 1400;
+var COAST_TAU = 0.32;
+var COAST_FLOOR = 15e-4;
+function dragWalk(dy, speed) {
+  return -dy * WALK_PER_PIXEL * speed;
+}
+function wheelWalk(deltaY, speed) {
+  return deltaY * WALK_PER_WHEEL * speed;
+}
+function coast(velocity, dt) {
+  const next = velocity * Math.exp(-dt / COAST_TAU);
+  return Math.abs(next) < COAST_FLOOR ? 0 : next;
+}
+function holdOnWalk(walk, closed) {
+  if (!closed) return Math.min(1, Math.max(0, walk));
+  return (walk % 1 + 1) % 1;
+}
+function nextStop(stops, from, direction, closed = false) {
+  if (stops.length === 0) return from;
+  const sorted = [...stops].sort((a, b) => a - b);
+  const EPS = 1e-4;
+  const found = direction > 0 ? sorted.find((s) => s > from + EPS) : [...sorted].reverse().find((s) => s < from - EPS);
+  if (found !== void 0) return found;
+  if (closed) return direction > 0 ? sorted[0] : sorted[sorted.length - 1];
+  return direction > 0 ? sorted[sorted.length - 1] : sorted[0];
+}
+var TRAVEL_SECONDS = 0.75;
+function travelEase(t) {
+  const x = Math.min(1, Math.max(0, t));
+  return x * x * x * (x * (x * 6 - 15) + 10);
+}
+function travelBetween(from, to, t, closed) {
+  let delta = to - from;
+  if (closed) {
+    if (delta > 0.5) delta -= 1;
+    if (delta < -0.5) delta += 1;
+  }
+  return holdOnWalk(from + delta * t, closed);
+}
+
+// src/stage/useWalk.ts
+import { useCallback, useEffect as useEffect6, useMemo as useMemo6, useRef as useRef4 } from "react";
+import { useFrame as useFrame3, useThree } from "@react-three/fiber";
+function useWalk({
+  path,
+  motion,
+  progress,
+  figureSpeed,
+  stops,
+  reduced,
+  onProgress
+}) {
+  const gl = useThree((s) => s.gl);
+  const walk = useRef4(progress ?? 0);
+  const velocity = useRef4(0);
+  const dragged = useRef4(false);
+  const travel = useRef4(null);
+  const controlled = progress !== void 0;
+  const interactive = !controlled && motion.driver === "drag";
+  const engaged = useRef4(false);
+  const travelTo = useCallback(
+    (target) => {
+      engaged.current = true;
+      velocity.current = 0;
+      const to = holdOnWalk(target, path.closed);
+      if (reduced) {
+        walk.current = to;
+        travel.current = null;
+        return;
+      }
+      travel.current = { from: walk.current, to, t: 0 };
+    },
+    [path.closed, reduced]
+  );
+  const step = useCallback(
+    (direction) => {
+      const from = travel.current?.to ?? walk.current;
+      travelTo(nextStop(stops, from, direction, path.closed));
+    },
+    [stops, path.closed, travelTo]
+  );
+  useEffect6(() => {
+    if (controlled) {
+      walk.current = progress;
+      travel.current = null;
+      velocity.current = 0;
+    }
+  }, [controlled, progress]);
+  const canvas = gl.domElement;
+  useEffect6(() => {
+    if (!interactive) return;
+    const hadTabIndex = canvas.hasAttribute("tabindex");
+    if (!hadTabIndex) canvas.tabIndex = 0;
+    const hadRole = canvas.getAttribute("role");
+    const hadLabel = canvas.getAttribute("aria-label");
+    if (!hadRole) canvas.setAttribute("role", "application");
+    if (!hadLabel) {
+      canvas.setAttribute(
+        "aria-label",
+        "A walk through hanging paper. Drag or use the arrow keys to move along it."
+      );
+    }
+    const hadTouch = canvas.style.touchAction;
+    if (motion.capture) canvas.style.touchAction = "none";
+    let pointer = null;
+    let lastY = 0;
+    let lastAt = 0;
+    let startY = 0;
+    const SLOP = 5;
+    const down = (event) => {
+      if (!event.isPrimary) return;
+      engaged.current = true;
+      pointer = event.pointerId;
+      dragged.current = false;
+      startY = event.clientY;
+      lastY = event.clientY;
+      lastAt = event.timeStamp;
+      velocity.current = 0;
+      travel.current = null;
+      canvas.setPointerCapture(event.pointerId);
+      canvas.style.cursor = "grabbing";
+    };
+    const move = (event) => {
+      if (pointer !== event.pointerId) return;
+      const dy = event.clientY - lastY;
+      if (Math.abs(event.clientY - startY) > SLOP) dragged.current = true;
+      const dt = Math.max((event.timeStamp - lastAt) / 1e3, 1 / 240);
+      const moved = dragWalk(dy, motion.speed);
+      walk.current = holdOnWalk(walk.current + moved, path.closed);
+      velocity.current = moved / dt;
+      lastY = event.clientY;
+      lastAt = event.timeStamp;
+    };
+    const up = (event) => {
+      if (pointer !== event.pointerId) return;
+      pointer = null;
+      canvas.style.cursor = "grab";
+      if (event.timeStamp - lastAt > 90) velocity.current = 0;
+    };
+    const wheel = (event) => {
+      const lines = event.deltaMode === 1 ? 16 : event.deltaMode === 2 ? 400 : 1;
+      const moved = wheelWalk(event.deltaY * lines, motion.speed);
+      if (!path.closed && (walk.current >= 1 && moved > 0 || walk.current <= 0 && moved < 0)) return;
+      engaged.current = true;
+      travel.current = null;
+      velocity.current = 0;
+      walk.current = holdOnWalk(walk.current + moved, path.closed);
+      event.preventDefault();
+    };
+    const key = (event) => {
+      const forward = event.key === "ArrowRight" || event.key === "ArrowDown" || event.key === "PageDown";
+      const back = event.key === "ArrowLeft" || event.key === "ArrowUp" || event.key === "PageUp";
+      if (forward || back) step(forward ? 1 : -1);
+      else if (event.key === "Home") travelTo(stops[0] ?? 0);
+      else if (event.key === "End") travelTo(stops[stops.length - 1] ?? 1);
+      else return;
+      engaged.current = true;
+      event.preventDefault();
+    };
+    canvas.style.cursor = "grab";
+    canvas.addEventListener("pointerdown", down);
+    canvas.addEventListener("pointermove", move);
+    canvas.addEventListener("pointerup", up);
+    canvas.addEventListener("pointercancel", up);
+    if (motion.capture) canvas.addEventListener("wheel", wheel, { passive: false });
+    canvas.addEventListener("keydown", key);
+    return () => {
+      canvas.removeEventListener("pointerdown", down);
+      canvas.removeEventListener("pointermove", move);
+      canvas.removeEventListener("pointerup", up);
+      canvas.removeEventListener("pointercancel", up);
+      canvas.removeEventListener("wheel", wheel);
+      canvas.removeEventListener("keydown", key);
+      canvas.style.cursor = "";
+      canvas.style.touchAction = hadTouch;
+      if (!hadTabIndex) canvas.removeAttribute("tabindex");
+      if (!hadRole) canvas.removeAttribute("role");
+      if (!hadLabel) canvas.removeAttribute("aria-label");
+    };
+  }, [canvas, interactive, motion.speed, motion.capture, path.closed, step, travelTo, stops]);
+  const reported = useRef4(-1);
+  useFrame3((_, delta) => {
+    if (onProgress && Math.abs(walk.current - reported.current) > 1e-4) {
+      reported.current = walk.current;
+      onProgress(walk.current);
+    }
+    if (controlled) return;
+    const dt = Math.min(delta, 0.1);
+    if (travel.current) {
+      travel.current.t += dt / TRAVEL_SECONDS;
+      const { from, to, t } = travel.current;
+      walk.current = travelBetween(from, to, travelEase(t), path.closed);
+      if (t >= 1) travel.current = null;
+      return;
+    }
+    const drifting = motion.driver === "autoplay" || interactive && !engaged.current;
+    if (drifting && !reduced) {
+      const perSecond = path.length > 0 ? figureSpeed * motion.speed / path.length : 0;
+      walk.current = ((walk.current + perSecond * dt) % 1 + 1) % 1;
+      return;
+    }
+    if (velocity.current !== 0) {
+      walk.current = holdOnWalk(walk.current + velocity.current * dt, path.closed);
+      velocity.current = coast(velocity.current, dt);
+      if (!path.closed && (walk.current <= 0 || walk.current >= 1)) velocity.current = 0;
+    }
+  });
+  return useMemo6(() => ({ walk, travelTo, step, dragged }), [travelTo, step]);
+}
+
+// src/stage/quality.ts
+var qualityNames = ["auto", "low", "medium", "high"];
+var qualityTiers = {
+  /**
+   * Anything with a GPU — and measured to mean it, since `auto` only arrives
+   * here after holding 55 fps. `segments: 128` is where the banners' folds
+   * actually resolve: the drape asks for 133 across and spent every previous
+   * version of this file getting 72, which is the difference between paper
+   * that bends and paper with facets. Free on hardware — an M4 Pro holds 120
+   * banners at 16 megapixels on the panel's own clock — and unreachable on
+   * anything that cannot, because the ladder never promotes a machine there.
+   */
+  high: {
+    dpr: 2,
+    shadowMapSize: 2048,
+    segments: 128,
+    surround: true,
+    contactShadow: true,
+    environment: true,
+    grade: true
+  },
+  /** The default worth aiming at: an integrated laptop GPU from the last few years. */
+  medium: {
+    dpr: 1.5,
+    shadowMapSize: 1024,
+    segments: 48,
+    surround: true,
+    contactShadow: false,
+    environment: true,
+    grade: false
+  },
+  /**
+   * Old integrated graphics, a throttled phone, a software rasterizer. The
+   * scene still READS — banners, figure, backlight, walk — it just stops
+   * paying for the parts nobody would miss at this framerate.
+   */
+  low: {
+    dpr: 1,
+    shadowMapSize: 0,
+    segments: 28,
+    surround: true,
+    contactShadow: false,
+    environment: false,
+    grade: false
+  }
+};
+var INITIAL_TIER = "medium";
+var FIRST_WINDOW = 20;
+var STEADY_WINDOW = 60;
+var SETTLE_FRAMES = 45;
+var TIER_ORDER = ["low", "medium", "high"];
+function qualityFor(name) {
+  return qualityTiers[name === "auto" ? INITIAL_TIER : name];
+}
+function tierUp(tier) {
+  return TIER_ORDER[Math.min(TIER_ORDER.indexOf(tier) + 1, TIER_ORDER.length - 1)];
+}
+function tierDown(tier) {
+  return TIER_ORDER[Math.max(TIER_ORDER.indexOf(tier) - 1, 0)];
+}
+var FLOOR_FPS = 26;
+var CEILING_FPS = 55;
+function settleTier(tier, fps, failed) {
+  if (fps < FLOOR_FPS) {
+    const next = tierDown(tier);
+    return next === tier ? { tier, failed } : { tier: next, failed: tier };
+  }
+  if (fps > CEILING_FPS) {
+    const next = tierUp(tier);
+    if (next !== tier && next !== failed) return { tier: next, failed };
+  }
+  return { tier, failed };
+}
+
+// src/stage/PaperStage.tsx
+import { jsx as jsx7, jsxs as jsxs6 } from "react/jsx-runtime";
+var BANNER = {
+  sheet: { width: 1.5, height: 8.5, segments: "auto" },
+  stock: "vellum",
+  surface: { grain: 0.22 },
+  deformers: [{ type: "drape", options: { amplitude: 0.16, folds: 3, falloff: 1.7, gather: 0.28 } }]
+};
+function splitAcrossBanners(text, banners) {
+  const words = text.split(/\s+/).filter(Boolean);
+  if (words.length === 0 || banners <= 0) return [];
+  const each = Math.floor(words.length / banners);
+  const extra = words.length % banners;
+  const out = [];
+  let at = 0;
+  for (let i = 0; i < banners && at < words.length; i++) {
+    const take = each + (i < extra ? 1 : 0);
+    if (take === 0) break;
+    out.push(words.slice(at, at + take).join("\n"));
+    at += take;
+  }
+  return out;
+}
+function letterColumn(word) {
+  return [...word].join("\n");
+}
+function bannerTextSize(lines, longestWord = 0, measure = Number.POSITIVE_INFINITY) {
+  const byDrop = 720 / Math.max(lines, 1);
+  const byMeasure = longestWord > 0 ? measure / (longestWord * 0.62) : Number.POSITIVE_INFINITY;
+  return Math.floor(Math.min(150, Math.max(26, Math.min(byDrop, byMeasure))));
+}
+var PADDING = 0.06;
+function bannerMeasure(sheet, padding = PADDING) {
+  const long = Math.max(sheet.width, sheet.height);
+  if (!(long > 0)) return Number.POSITIVE_INFINITY;
+  return sheet.width / long * 1024 * (1 - padding * 2);
+}
+function ShotRig({
+  stage,
+  paperHeight,
+  walk
+}) {
+  const camera = useThree2((s) => s.camera);
+  const path = useMemo7(() => getWalkPath(stage.path), [stage.path]);
+  const scale = useMemo7(
+    () => ({ figure: stage.figure.height, paper: paperHeight }),
+    [stage.figure.height, paperHeight]
+  );
+  useFrame4(() => {
+    const { position, target } = stageCamera(path, walk.current * path.length, scale, stage.shot);
+    camera.position.set(position[0], position[1], position[2]);
+    camera.lookAt(target[0], target[1], target[2]);
+  });
+  return null;
+}
+function QualityWatch({ tier, onChange }) {
+  const samples = useRef5([]);
+  const settle = useRef5(SETTLE_FRAMES);
+  const window = useRef5(FIRST_WINDOW);
+  const failed = useRef5(null);
+  const settled = useCallback2((next) => {
+    samples.current = [];
+    settle.current = SETTLE_FRAMES;
+    window.current = STEADY_WINDOW;
+    return next;
+  }, []);
+  useFrame4((_, delta) => {
+    if (settle.current > 0) {
+      settle.current -= 1;
+      return;
+    }
+    if (delta > 0.5) return;
+    samples.current.push(delta);
+    if (samples.current.length < window.current) return;
+    const sorted = [...samples.current].sort((a, b) => a - b);
+    const median = sorted[Math.floor(sorted.length / 2)];
+    const fps = 1 / median;
+    samples.current = [];
+    window.current = STEADY_WINDOW;
+    const verdict = settleTier(tier, fps, failed.current);
+    failed.current = verdict.failed;
+    if (verdict.tier !== tier) onChange(settled(verdict.tier));
+  });
+  return null;
+}
+function PaperStageScene({
+  stage: stageInput,
+  quality = "auto",
+  onQualityChange,
+  layout = "colonnade",
+  layoutOptions,
+  papers,
+  images,
+  text,
+  preset,
+  count = 22,
+  progress,
+  motion,
+  onVisit,
+  onProgress,
+  reducedMotion
+}) {
+  const still = usePrefersReducedMotion(reducedMotion);
+  const [tier, setTier] = useState(quality === "auto" ? INITIAL_TIER : quality);
+  useEffect7(() => {
+    if (quality !== "auto") setTier(quality);
+  }, [quality]);
+  const reportQuality = useRef5(onQualityChange);
+  useEffect7(() => {
+    reportQuality.current = onQualityChange;
+  });
+  useEffect7(() => {
+    reportQuality.current?.(tier);
+  }, [tier]);
+  const settings = quality === "auto" ? qualityTiers[tier] : qualityFor(quality);
+  const stageKey = JSON.stringify(stageInput ?? {});
+  const stage = useMemo7(() => stageSchema.parse(stageInput ?? {}), [stageKey]);
+  const path = useMemo7(() => getWalkPath(stage.path), [stage.path]);
+  const rig = useMemo7(() => {
+    const resolved = resolveLighting(stage.lighting, stage.light);
+    return {
+      ...resolved,
+      sky: { zenith: stage.source.zenith, horizon: stage.source.color, ground: stage.ground.color }
+    };
+  }, [stage.lighting, stage.light, stage.source.zenith, stage.source.color, stage.ground.color]);
+  const sheetDims = useMemo7(() => {
+    const { width, height } = resolveConfig({ preset: preset ?? BANNER }).sheet;
+    return { width, height };
+  }, [preset]);
+  const paperHeight = sheetDims.height;
+  const paperWidth = sheetDims.width;
+  const paper = preset ?? BANNER;
+  const resolvedLayoutOptions = useMemo7(() => {
+    const schema = getLayout(layout).optionsSchema;
+    const takesPath = schema instanceof z5.ZodObject && "path" in schema.shape;
+    return takesPath ? { ...layoutOptions, path: stage.path } : layoutOptions;
+  }, [layout, layoutOptions, stage.path]);
+  const slots = useMemo7(() => {
+    if (papers) return papers;
+    if (images) return void 0;
+    if (text !== void 0) {
+      const split = Array.isArray(text) ? text : splitAcrossBanners(text, count);
+      const vertical = split.every((c) => !c.includes("\n"));
+      const columns = vertical ? split.map(letterColumn) : split;
+      const longest = columns.reduce((n, c) => Math.max(n, c.split("\n").length), 1);
+      const longestWord = columns.reduce(
+        (n, c) => c.split("\n").reduce((m, w) => Math.max(m, w.length), n),
+        1
+      );
+      const size = bannerTextSize(longest, longestWord, bannerMeasure(sheetDims, PADDING));
+      return columns.map((column) => ({
+        content: {
+          type: "text",
+          text: column,
+          size,
+          align: "center",
+          // Centred down the drop as well as across it. One size is shared
+          // by the whole rank — that is what makes it read as set rather
+          // than scaled — so a short word necessarily leaves slack, and the
+          // slack belongs at both ends. Hung from the top instead, "the"
+          // reads as a caption that ran out while "remembers" fills its
+          // banner, and the rank looks broken rather than composed.
+          valign: "center",
+          color: "#241f1a",
+          lineHeight: 1.25,
+          font: 'Georgia, "Times New Roman", serif',
+          weight: 400,
+          padding: PADDING
+        }
+      }));
+    }
+    return Array.from({ length: count }, () => ({}));
+  }, [papers, images, text, count, sheetDims]);
+  const drive = stageMotionSchema.parse(motion ?? {});
+  const slotCount = slots?.length ?? images?.length ?? count;
+  const stops = useMemo7(() => {
+    const spec = getLayout(layout);
+    const placed = spec.walkStops?.(slotCount, spec.optionsSchema.parse(resolvedLayoutOptions ?? {}));
+    if (placed && placed.length > 0) return placed;
+    return Array.from({ length: slotCount }, (_, i) => slotCount > 1 ? i / (slotCount - 1) : 0.5);
+  }, [layout, resolvedLayoutOptions, slotCount]);
+  const walk = useWalk({
+    path,
+    motion: drive,
+    progress,
+    figureSpeed: stage.figure.speed,
+    stops,
+    reduced: still,
+    onProgress
+  });
+  const surroundRadius = useMemo7(
+    () => Math.max(path.length * 1.6, paperHeight * 9),
+    [path.length, paperHeight]
+  );
+  const source = useMemo7(() => {
+    const [x, z6] = walkPoint(path, path.length + stage.source.beyond);
+    const [tx, tz] = path.tangentAt(1);
+    const size = paperHeight * stage.source.spread;
+    return { position: [x, size * 0.35, z6], yaw: Math.atan2(-tx, -tz), size };
+  }, [path, stage.source.beyond, stage.source.spread, paperHeight]);
+  return /* @__PURE__ */ jsxs6(LightRig, { rig, children: [
+    /* @__PURE__ */ jsx7(ShotRig, { stage, paperHeight, walk: walk.walk }),
+    /* @__PURE__ */ jsx7(
+      PaperLighting,
+      {
+        rig,
+        floor: 0,
+        scale: 60,
+        reducedMotion,
+        shadowMapSize: settings.shadowMapSize,
+        contactShadow: settings.contactShadow,
+        environment: settings.environment
+      }
+    ),
+    quality === "auto" && /* @__PURE__ */ jsx7(QualityWatch, { tier, onChange: setTier }),
+    stage.source.surround && settings.surround && /* @__PURE__ */ jsx7(Surround, { radius: surroundRadius, sky: rig.sky }),
+    stage.source.enabled && /* @__PURE__ */ jsx7(Source, { size: source.size, position: source.position, yaw: source.yaw, color: rig.sky.horizon }),
+    stage.ground.enabled && /* @__PURE__ */ jsx7(Floor, { size: surroundRadius * 1.3, color: stage.ground.color, slab: stage.ground.slab }),
+    stage.room.enabled && stage.room.doorway.enabled && stage.source.enabled && /* @__PURE__ */ jsx7(
+      Doorway,
+      {
+        position: source.position,
+        yaw: source.yaw,
+        size: source.size,
+        opening: stage.room.doorway.opening,
+        color: stage.room.doorway.color,
+        extent: surroundRadius * 0.9
+      }
+    ),
+    stage.room.enabled && stage.room.columns.enabled && /* @__PURE__ */ jsx7(
+      Columns,
+      {
+        path,
+        ceiling: paperHeight * stage.room.height,
+        spacing: stage.room.columns.spacing,
+        width: stage.room.columns.width,
+        offset: stage.room.columns.offset,
+        color: stage.room.columns.color
+      }
+    ),
+    stage.suspension.type !== "none" && /* @__PURE__ */ jsx7(
+      Suspension,
+      {
+        layout,
+        layoutOptions: resolvedLayoutOptions ?? {},
+        count: slots?.length ?? count,
+        sheet: { width: paperWidth, height: paperHeight },
+        paperHeight,
+        ceiling: paperHeight * stage.room.height,
+        color: stage.suspension.color,
+        type: stage.suspension.type,
+        hardware: stage.suspension.hardware
+      }
+    ),
+    stage.room.enabled && /* @__PURE__ */ jsx7(
+      Ceiling,
+      {
+        size: surroundRadius * 1.3,
+        height: paperHeight * stage.room.height,
+        color: stage.room.color
+      }
+    ),
+    /* @__PURE__ */ jsx7(
+      PaperFieldMesh,
+      {
+        preset: paper,
+        segmentCeiling: settings.segments,
+        papers: slots,
+        images,
+        layout,
+        layoutOptions: resolvedLayoutOptions,
+        motion: { driver: "none" },
+        entrance: { type: "none" },
+        reducedMotion,
+        onSelect: drive.driver === "drag" && progress === void 0 ? (paperIndex) => {
+          if (walk.dragged.current) return;
+          walk.travelTo(stops[paperIndex] ?? 0);
+          onVisit?.(paperIndex);
+        } : void 0
+      }
+    ),
+    stage.showFigure && /* @__PURE__ */ jsx7(
+      Figure,
+      {
+        path: stage.path,
+        figure: stage.figure,
+        distanceRef: walk.walk,
+        walkLength: path.length,
+        frozen: reducedMotion
+      }
+    ),
+    settings.grade && /* @__PURE__ */ jsx7(Grade, { grade: stage.grade, film: rig.film })
+  ] });
+}
+function PaperStage({ children, className, style, ...sceneProps }) {
+  const dpr = qualityFor(sceneProps.quality ?? "auto").dpr;
+  return /* @__PURE__ */ jsx7("div", { className, style: { width: "100%", height: "100%", ...style }, children: /* @__PURE__ */ jsxs6(
+    Canvas,
+    {
+      shadows: true,
+      dpr: [1, dpr],
+      camera: { fov: 38, near: 0.05, far: 400 },
+      onCreated: ({ scene }) => {
+        scene.background = new THREE6.Color("#0c0a0b");
+      },
+      children: [
+        /* @__PURE__ */ jsx7(PaperStageScene, { ...sceneProps }),
+        children
+      ]
+    }
+  ) });
+}
+
+// src/stage/walks.ts
+var walkNames = ["straight", "bend", "ess", "ring", "spiral"];
+var walks = {
+  /** Straight down the nave, away from the camera. The reference shot. */
+  straight: {
+    points: [
+      [0, 16],
+      [0, -20]
+    ],
+    closed: false
+  },
+  /** One long curve, so the far end of the colonnade stays hidden until you reach it. */
+  bend: {
+    points: [
+      [-2, 16],
+      [0, 6],
+      [5, -3],
+      [12, -10]
+    ],
+    closed: false
+  },
+  /** Two opposed curves — the walk turns twice and the banners turn with it. */
+  ess: {
+    points: [
+      [6, 17],
+      [-3, 7],
+      [3, -5],
+      [-6, -17]
+    ],
+    closed: false
+  },
+  /** A closed loop: the only walk `phase` can slide, and the only endless one. */
+  ring: {
+    points: [
+      [11, 0],
+      [0, 11],
+      [-11, 0],
+      [0, -11]
+    ],
+    closed: true
+  },
+  /** Inward and tightening — the space closes as the figure goes deeper. */
+  spiral: {
+    points: [
+      [14, 2],
+      [2, 13],
+      [-11, 1],
+      [-1, -9],
+      [7, -2],
+      [1, 4]
+    ],
+    closed: false
+  }
+};
+function getWalk(name) {
+  return walks[name];
+}
+
+// src/stage/presets.ts
+var banner = (width, height, drape = {}) => ({
+  sheet: { width, height, segments: "auto" },
+  stock: "vellum",
+  surface: { grain: 0.22 },
+  deformers: [
+    { type: "drape", options: { amplitude: 0.16, folds: 3, falloff: 1.7, gather: 0.28, ...drape } }
+  ]
+});
+var stagePresets = {
+  nave: {
+    id: "nave",
+    label: "Nave",
+    description: "A straight aisle of hanging banners, lit from the far end.",
+    stage: {
+      path: walks.straight,
+      shot: { shot: "follow", distance: 5, lookAhead: 12, offset: 1.5 },
+      lighting: "nave",
+      // The hall this stage is named for. Columns give it the one thing a
+      // ceiling and floor seams cannot: an object of known size standing IN
+      // the room rather than bounding it.
+      room: { columns: { enabled: true } }
+    },
+    layout: "colonnade",
+    layoutOptions: { aisle: 2.6, twist: 22, drape: 0.6, rise: 0.3 },
+    paper: banner(1.5, 8.5),
+    count: 18,
+    text: "the paper remembers every hand that folded it and every room it was carried through"
+  },
+  procession: {
+    id: "procession",
+    label: "Procession",
+    description: "The walk turns twice, so the far end stays hidden until you reach it.",
+    stage: {
+      path: walks.ess,
+      shot: { shot: "low", distance: 4, lookAhead: 9, offset: 1.1 },
+      lighting: "nave",
+      figure: { speed: 1.05 }
+    },
+    layout: "colonnade",
+    layoutOptions: { aisle: 2.2, twist: 34, breathe: 0.45, drape: 0.7 },
+    paper: banner(1.3, 9.5, { folds: 4, amplitude: 0.2 }),
+    count: 28,
+    text: "every letter you did not send is still folded somewhere in the dark waiting to be read aloud"
+  },
+  cloister: {
+    id: "cloister",
+    label: "Cloister",
+    description: "A closed loop. The figure walks it forever and the banners drift past.",
+    stage: {
+      path: walks.ring,
+      shot: { shot: "follow", distance: 4.5, lookAhead: 8, offset: 1.2 },
+      lighting: "nave",
+      // Pegs, not clips. A cloister is a walk you repeat, and the sheets are
+      // the same words coming back — hung the way you hang washing, not the
+      // way a gallery mounts a print. The silhouette is the whole difference
+      // at this distance: a peg grips DOWN the face where a clip grips
+      // across the edge.
+      suspension: { hardware: "peg" }
+    },
+    layout: "colonnade",
+    layoutOptions: { aisle: 2.4, twist: 18, rise: 0.22 },
+    paper: banner(1.6, 7.5),
+    count: 24,
+    text: "around and around and the same words come back changed"
+  },
+  threshold: {
+    id: "threshold",
+    label: "Threshold",
+    description: "A few enormous sheets, wide enough apart to walk between and read.",
+    stage: {
+      // Its own short walk. A colonnade spreads over the WHOLE path whatever
+      // it is populating, so ten banners on the default 36-unit walk stand
+      // seven apart and the shot looks down an empty corridor.
+      path: {
+        points: [
+          [0, 9],
+          [0, -11]
+        ],
+        closed: false
+      },
+      // The aisle has to stay inside the frustum at the distance the shot
+      // stands: paper half a frame-width off the walk line is paper you
+      // never see. `lead` fails here for the same reason and worse.
+      shot: { shot: "follow", distance: 6.5, lookAhead: 9, offset: 0.9 },
+      lighting: "nave",
+      figure: { speed: 0.85 },
+      /**
+       * The one room in the set with a COLOUR in it.
+       *
+       * Every other stage is a warm neutral corridor, and white paper against
+       * warm neutral is white paper against nothing — the sheets and the room
+       * sit at the same temperature and the picture flattens. Against a
+       * saturated ground the paper sings, which is why the installations
+       * worth copying are shot in rooms painted terracotta and washed with
+       * gels rather than in white boxes.
+       *
+       * `source.color` is the horizon and `ground.color` the floor of the
+       * same three-stop sky that builds the environment map, so the light
+       * bouncing onto the sheets is the room's own colour and cannot
+       * disagree with the walls the viewer can see.
+       */
+      source: { spread: 1.1, color: "#ffd7a8", zenith: "#3d1c12" },
+      ground: { color: "#6b2f1d" },
+      // The stage named for a doorway now has one. Without the wall the
+      // source is a bright rectangle floating in a coloured void — it reads
+      // as light, but not as light coming from anywhere. With it, the walk
+      // resolves toward an opening in a surface, and the room gets the
+      // corner it never had. The wall takes the terracotta so the opening is
+      // the only bright thing in the frame that is not paper.
+      room: { doorway: { enabled: true, color: "#4a2013" } }
+    },
+    layout: "colonnade",
+    layoutOptions: { aisle: 2.4, twist: 14, breathe: 0.18, margin: 0.12, rise: 0.2 },
+    paper: banner(2.6, 10, { folds: 2, amplitude: 0.24, falloff: 2 }),
+    count: 10,
+    text: "stand closer and read what it cost to write this down"
+  },
+  /**
+   * The one stage that is not a colonnade of banners.
+   *
+   * A ribbon reaches the floor and keeps going, and everything built in the
+   * last four phases exists so that this reads: a room with a ceiling to
+   * hang from, hardware to hang by, type that can be set down a length
+   * without looking like a caption, and a `roll` that begins at the floor
+   * line rather than at the sheet's centre.
+   */
+  ribbon: {
+    id: "ribbon",
+    label: "Ribbon",
+    description: "Printed strips falling the full drop of the room, pooling where they land.",
+    stage: {
+      path: walks.straight,
+      // Close. Ribbons are a curtain you part rather than a hall you walk
+      // down, so the camera stands nearer and looks less far ahead than any
+      // other stage in the set.
+      // Lower than the other stages. Pooled paper lies FLAT, so from
+      // standing height it foreshortens to a sliver; the shot has to get
+      // down toward the floor for the thing this stage is about to read.
+      shot: { shot: "follow", distance: 4.6, height: 2.3, lookAhead: 3.6, offset: 0.34 },
+      lighting: "nave",
+      // A low ceiling: the strips ARE the height of the room, so a lid far
+      // above them would leave metres of empty air and make the drop read as
+      // short. This is the stage the room proportion matters most on.
+      room: { height: 1.12 },
+      source: { spread: 1.3 },
+      suspension: { hardware: "clip" }
+    },
+    layout: "colonnade",
+    // Packed tighter than the banner stages, barely twisted, and hung at a
+    // steady height — a rank of strips reads by its rhythm, and jitter that
+    // flatters a colonnade of banners just makes this look untidy.
+    // `hover` is NEGATIVE by exactly the pool fraction, and that is the whole
+    // trick. A colonnade hangs a sheet with its BOTTOM edge on the floor, but
+    // a ribbon's crease sits a pool-length above its bottom edge — so at
+    // hover 0 the pooled length lies flat in mid-air, parallel to a ground it
+    // never touches. Dropping the strip by the same fraction puts the crease
+    // on the floor and the pool ON it.
+    layoutOptions: {
+      aisle: 1.75,
+      twist: 5,
+      breathe: 0.1,
+      margin: 0.06,
+      rise: 0.06,
+      drape: 0.2,
+      hover: -0.22
+    },
+    paper: {
+      sheet: { width: 1.05, height: 9, segments: "auto" },
+      stock: "printer",
+      surface: { grain: 0.2 },
+      behavior: { type: "ribbon", pool: 0.22, curl: 0.34, drape: 0.6 }
+    },
+    // Eight, not twelve, and the reason is the type rather than the room.
+    // A strip 1.05 wide holds about 105px of measure, which caps the type at
+    // 26px, which means a column needs roughly twenty-six words to reach the
+    // bottom of a nine-metre drop. Twelve strips wanted three hundred words;
+    // eight want two hundred, which is a passage rather than an essay. Fewer
+    // and longer is also what the reference installations look like.
+    count: 8,
+    // Long, because the whole point of this stage is type running the length
+    // of the paper. It shipped with twenty words across twelve banners — two
+    // words a strip — which set as a caption at the top of nine metres of
+    // blank paper. Every word here is kept to seven letters or fewer: the
+    // measure is narrow, and one long word shrinks the type on every banner
+    // in the room, because a rank of banners is set at one size or it reads
+    // as a mistake.
+    text: "the paper kept going long after the floor ran out from under it and nobody moved to pick it up we let it lie there the way you let a letter lie it had come down from a height no one could name and it held the shape of the fall in its folds someone inked it once and you can still read the last of it where the light gets in a room is only a room until you hang a thing in it then it is a place you walk across slowly the strips move when the door opens and settle again before you reach them paper holds what it was rolled around it holds being flat too and it will go back to flat if you leave it alone long enough but not today today it lies in a curve at the foot of the wall and the curve is the whole point the floor was never meant to hold this much so the paper takes over where the floor gives up it pools the way water would if water could be inked we came to look at the light we stayed for the paper on the ground"
+  },
+  archive: {
+    id: "archive",
+    label: "Archive",
+    description: "Narrow strips packed tight \u2014 a corridor of records you edge through.",
+    stage: {
+      path: walks.bend,
+      // Far enough back that the figure reads as small; a `low` camera
+      // three units behind a body is all body.
+      shot: { shot: "low", distance: 8, lookAhead: 13, offset: 0.5 },
+      lighting: "nave",
+      ground: { color: "#0b0908" },
+      // Its banners are eleven units tall and `spread` is a multiple of that,
+      // so the default opening would be fifty units across — a wall, on a
+      // walk whose whole point is that it is narrow.
+      source: { spread: 1.1 },
+      // Records on a rail. Forty-four strips each on their own invisible
+      // thread read as forty-four accidents; on rods they read as a system
+      // somebody filed them into, which is what the stage is called.
+      suspension: { type: "rod" }
+    },
+    layout: "colonnade",
+    layoutOptions: { aisle: 1.7, twist: 44, breathe: 0.5, drape: 0.75, rise: 0.4 },
+    paper: banner(0.85, 11, { folds: 2, amplitude: 0.12 }),
+    count: 44,
+    text: "catalogued indexed cross referenced filed and never once opened by anyone at all"
+  }
+};
+function getStagePreset(id) {
+  const preset = stagePresets[id];
+  if (!preset) {
+    throw new Error(
+      `[paperlab] Unknown stage preset "${id}". Available: ${Object.keys(stagePresets).join(", ")}`
+    );
+  }
+  return preset;
+}
+function listStagePresets() {
+  return Object.keys(stagePresets);
+}
+
+// src/stage/export.ts
+var SCROLL_HEIGHTS = 4;
+function walkNameFor(path) {
+  const key = JSON.stringify({ points: path.points, closed: path.closed });
+  return walkNames.find(
+    (name) => JSON.stringify({ points: walks[name].points, closed: walks[name].closed }) === key
+  );
+}
+function stripDefaults(value, defaults) {
+  if (Array.isArray(value) || Array.isArray(defaults)) {
+    return JSON.stringify(value) === JSON.stringify(defaults) ? void 0 : value;
+  }
+  if (value && defaults && typeof value === "object" && typeof defaults === "object") {
+    const out = {};
+    for (const [key, child] of Object.entries(value)) {
+      const kept = stripDefaults(child, defaults[key]);
+      if (kept !== void 0) out[key] = kept;
+    }
+    return Object.keys(out).length > 0 ? out : void 0;
+  }
+  return value === defaults ? void 0 : value;
+}
+function diffStage(stage) {
+  const resolved = stageSchema.parse(stage);
+  const defaults = stageSchema.parse({});
+  const diff = stripDefaults(resolved, defaults) ?? {};
+  if (diff.path !== void 0) diff.path = resolved.path;
+  return diff;
+}
+function stringifyStage(value, indent = 0) {
+  const pad = "  ".repeat(indent);
+  const inner = "  ".repeat(indent + 1);
+  if (Array.isArray(value)) {
+    if (value.length === 0) return "[]";
+    if (value.every((v) => typeof v === "number")) return `[${value.join(", ")}]`;
+    const items = value.map((v) => `${inner}${stringifyStage(v, indent + 1)}`);
+    return `[
+${items.join(",\n")}
+${pad}]`;
+  }
+  if (value && typeof value === "object") {
+    const entries = Object.entries(value);
+    if (entries.length === 0) return "{}";
+    const items = entries.map(([k, v]) => `${inner}${JSON.stringify(k)}: ${stringifyStage(v, indent + 1)}`);
+    return `{
+${items.join(",\n")}
+${pad}}`;
+  }
+  return JSON.stringify(value);
+}
+var SHOT_PHRASES = {
+  follow: "from behind and a little above them, looking up the walk",
+  lead: "from in front, walking backward as they come on",
+  low: "from down at floor level, looking up the banners",
+  wide: "from off to one side, level with them"
+};
+function describeStage(input) {
+  const stage = stageSchema.parse(input.stage);
+  const count = input.count ?? 22;
+  const walk = walkNameFor(stage.path);
+  const parts = [];
+  const shape = walk === "straight" || walk === void 0 ? "a straight walk" : walk === "ring" ? "a closed loop of a walk" : `an "${walk}" walk that curves as it goes`;
+  parts.push(`${count} tall paper banners standing along ${shape}`);
+  if (input.text?.trim()) {
+    parts.push("each printed with a column of your text running down it");
+  }
+  parts.push(`seen ${SHOT_PHRASES[stage.shot.shot]}`);
+  if (stage.showFigure) {
+    parts.push("a small dark figure walking between them");
+  }
+  if (stage.room.enabled) {
+    parts.push("a ceiling overhead and seams in the poured floor, so the hall has a knowable size");
+  }
+  parts.push(
+    stage.lighting === "nave" ? "the whole space dim and lit from behind, so the paper glows and the far end of the walk is a bright void" : `lit with the "${stage.lighting}" preset`
+  );
+  const moved = Object.entries(stage.light).filter(([, value]) => value !== void 0).map(([key]) => key);
+  if (moved.length > 0) parts.push(`with its ${moved.join(", ")} set by hand`);
+  if (input.scroll) parts.push("and scrolling the page walks the figure deeper into it");
+  return parts.join(", ");
+}
+function propLines(input, indent) {
+  const lines = [];
+  if (input.paper) lines.push(`${indent}preset={banner}`);
+  if (input.text?.trim()) lines.push(`${indent}text={text}`);
+  if (input.count !== void 0) lines.push(`${indent}count={${input.count}}`);
+  if (input.layout !== "colonnade") lines.push(`${indent}layout="${input.layout}"`);
+  const layoutOptions = input.layoutOptions ?? {};
+  const layoutDefaults = getLayout(input.layout).defaults;
+  const changed = {};
+  for (const [key, value] of Object.entries(layoutOptions)) {
+    if (JSON.stringify(value) !== JSON.stringify(layoutDefaults[key])) changed[key] = value;
+  }
+  if (Object.keys(changed).length > 0) {
+    lines.push(`${indent}layoutOptions={${stringifyStage(changed).replace(/\n\s*/g, " ")}}`);
+  }
+  lines.push(`${indent}stage={stage}`);
+  return lines.join("\n");
+}
+function buildStageComponentSource(input) {
+  const name = input.componentName ?? "PaperNave";
+  const stage = diffStage(input.stage);
+  const stageConst = `const stage = ${stringifyStage(stage)} satisfies StageConfigInput`;
+  const bannerConst = input.paper ? `
+
+const banner = ${stringifyStage(diffConfig(paperConfigSchema.parse(input.paper)))} satisfies PaperConfigInput` : "";
+  const textConst = input.text?.trim() ? `
+
+const text = ${JSON.stringify(input.text)}` : "";
+  if (!input.scroll) {
+    return `import { PaperStage, type StageConfigInput } from 'paperlab/stage'${input.paper ? "\nimport type { PaperConfigInput } from 'paperlab'" : ""}
+
+${stageConst}${bannerConst}${textConst}
+
+export function ${name}() {
+  return (
+    <PaperStage
+${propLines(input, "      ")}
+    />
+  )
+}`;
+  }
+  return `import { useEffect, useRef, useState } from 'react'
+import { PaperStage, type StageConfigInput } from 'paperlab/stage'${input.paper ? "\nimport type { PaperConfigInput } from 'paperlab'" : ""}
+
+${stageConst}${bannerConst}${textConst}
+
+export function ${name}() {
+  const ref = useRef<HTMLDivElement>(null)
+  const [progress, setProgress] = useState(0)
+
+  // Scroll the section, walk the figure. The stage is pinned for the height
+  // of the section, so the page scrolling past it IS the walk.
+  useEffect(() => {
+    const el = ref.current
+    if (!el) return
+    const onScroll = () => {
+      const { top, height } = el.getBoundingClientRect()
+      const travel = Math.max(height - window.innerHeight, 1)
+      setProgress(Math.min(Math.max(-top / travel, 0), 1))
+    }
+    onScroll()
+    window.addEventListener('scroll', onScroll, { passive: true })
+    window.addEventListener('resize', onScroll)
+    return () => {
+      window.removeEventListener('scroll', onScroll)
+      window.removeEventListener('resize', onScroll)
+    }
+  }, [])
+
+  return (
+    <div ref={ref} style={{ height: '${SCROLL_HEIGHTS * 100}vh' }}>
+      <div style={{ position: 'sticky', top: 0, height: '100vh' }}>
+        <PaperStage
+${propLines(input, "          ")}
+          progress={progress}
+        />
+      </div>
+    </div>
+  )
+}`;
+}
+function buildStageAgentPayload(input) {
+  const name = input.componentName ?? "PaperNave";
+  const sizing = input.scroll ? `4. Sizing: the component brings its own height \u2014 it reserves ${SCROLL_HEIGHTS} viewport
+   heights of scroll and pins the canvas inside that. Drop it into the page
+   flow as a section; do NOT wrap it in a fixed-height container.` : `4. Sizing: the component fills its parent container. Place it where I ask;
+   give the parent an explicit height.`;
+  return `Integrate a Paperlab stage \u2014 paper as architecture, with a figure walking through it \u2014 into this project. (paperlab agent-payload v${AGENT_PAYLOAD_VERSION})
+
+1. Install the dependencies:
+
+   npm i paperlab three @react-three/fiber gsap @react-three/postprocessing postprocessing
+
+   The last two are only needed by stage mode \u2014 <Paper> and <PaperField> do
+   not use them \u2014 but <PaperStage> imports the print pass (bloom, tone curve,
+   vignette, grain), so a stage will not build without them.
+
+2. Create the component below as \`components/${name}.tsx\` (or the project's
+   component convention). It is self-contained \u2014 it owns its own <Canvas>,
+   its own camera and its own lighting:
+
+\`\`\`tsx
+${buildStageComponentSource(input)}
+\`\`\`
+
+3. Placement: this is a full-bleed scene, not an inline element. Give it the
+   full width of the viewport.
+
+${sizing}
+
+5. Verify: run the dev server. You should see ${describeStage(input)}.
+   If the canvas is blank, the container almost certainly has no height \u2014 give
+   it one (this is the classic React Three Fiber integration bug, not a
+   paperlab bug).
+
+Constraints: don't modify the stage values; the camera is driven by the
+stage's own shot, so don't add OrbitControls; three >= 0.160 and React 19 are
+required; the component needs no props.`;
+}
+export {
+  PaperStage,
+  PaperStageScene,
+  SOURCE_INTENSITY,
+  buildStageAgentPayload,
+  buildStageComponentSource,
+  createWalkPath,
+  describeStage,
+  diffStage,
+  getStagePreset,
+  getWalk,
+  listStagePresets,
+  qualityNames,
+  shotNames,
+  stageGradeSchema,
+  stageMotionSchema,
+  stagePresets,
+  stageRoomSchema,
+  stageSchema,
+  stageSuspensionSchema,
+  stringifyStage,
+  walkNameFor,
+  walkNames,
+  walks
+};
+//# sourceMappingURL=stage.js.map