paperlab 0.4.0 → 0.5.1

package/dist/stage.d.cts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { F as FieldPaperSlot, a as PaperConfigInput } from './slots-BYoLxVZ4.cjs';
+import { F as FieldPaperSlot, a as PaperConfigInput } from './slots-CIo7FnlY.cjs';
 import { z } from 'zod';
 
 /**
@@ -218,15 +218,15 @@ declare const stageSchema: z.ZodObject<{
         spread: z.ZodDefault<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
         color: string;
-        enabled: boolean;
         spread: number;
+        enabled: boolean;
         zenith: string;
         beyond: number;
         surround: boolean;
     }, {
         color?: string | undefined;
-        enabled?: boolean | undefined;
         spread?: number | undefined;
+        enabled?: boolean | undefined;
         zenith?: string | undefined;
         beyond?: number | undefined;
         surround?: boolean | undefined;
@@ -478,6 +478,17 @@ declare const stageSchema: z.ZodObject<{
         closed: boolean;
     };
     lighting: "studio" | "window" | "leaves" | "goldenhour" | "noir" | "nave" | "raking" | "lightbox";
+    light: {
+        key?: number | undefined;
+        height?: number | undefined;
+        color?: string | undefined;
+        studio?: number | undefined;
+        exposure?: number | undefined;
+        film?: "agx" | "neutral" | "filmic" | undefined;
+        direction?: number | undefined;
+        ambient?: number | undefined;
+        haze?: number | undefined;
+    };
     figure: {
         height: number;
         speed: number;
@@ -490,23 +501,12 @@ declare const stageSchema: z.ZodObject<{
     };
     source: {
         color: string;
-        enabled: boolean;
         spread: number;
+        enabled: boolean;
         zenith: string;
         beyond: number;
         surround: boolean;
     };
-    light: {
-        key?: number | undefined;
-        height?: number | undefined;
-        color?: string | undefined;
-        studio?: number | undefined;
-        exposure?: number | undefined;
-        film?: "agx" | "neutral" | "filmic" | undefined;
-        direction?: number | undefined;
-        ambient?: number | undefined;
-        haze?: number | undefined;
-    };
     shot: {
         height: number;
         offset: number;
@@ -555,6 +555,17 @@ declare const stageSchema: z.ZodObject<{
         closed?: boolean | undefined;
     } | undefined;
     lighting?: "studio" | "window" | "leaves" | "goldenhour" | "noir" | "nave" | "raking" | "lightbox" | undefined;
+    light?: {
+        key?: number | undefined;
+        height?: number | undefined;
+        color?: string | undefined;
+        studio?: number | undefined;
+        exposure?: number | undefined;
+        film?: "agx" | "neutral" | "filmic" | undefined;
+        direction?: number | undefined;
+        ambient?: number | undefined;
+        haze?: number | undefined;
+    } | undefined;
     figure?: {
         height?: number | undefined;
         speed?: number | undefined;
@@ -567,23 +578,12 @@ declare const stageSchema: z.ZodObject<{
     } | undefined;
     source?: {
         color?: string | undefined;
-        enabled?: boolean | undefined;
         spread?: number | undefined;
+        enabled?: boolean | undefined;
         zenith?: string | undefined;
         beyond?: number | undefined;
         surround?: boolean | undefined;
     } | undefined;
-    light?: {
-        key?: number | undefined;
-        height?: number | undefined;
-        color?: string | undefined;
-        studio?: number | undefined;
-        exposure?: number | undefined;
-        film?: "agx" | "neutral" | "filmic" | undefined;
-        direction?: number | undefined;
-        ambient?: number | undefined;
-        haze?: number | undefined;
-    } | undefined;
     shot?: {
         height?: number | undefined;
         offset?: number | undefined;
@@ -739,6 +739,28 @@ declare const qualityNames: readonly ["auto", "low", "medium", "high"];
 type QualityName = (typeof qualityNames)[number];
 type QualityTier = Exclude<QualityName, 'auto'>;
 
+/**
+ * Stage mode: paper as architecture, with a figure walking through it.
+ *
+ * The one guarantee worth stating — every part of the scene reads the SAME
+ * walk. The layout arranges along it, the figure follows it, the camera is
+ * stationed on it, and the source stands at the end of it. Handing those
+ * four their own copies of a path is the failure this component exists to
+ * prevent: a colonnade whose aisle the figure does not walk down is not a
+ * near-miss, it is a completely different picture.
+ */
+/** A banner: tall, translucent, with folds running the length of its drop. */
+/**
+ * The sheet a stage hangs when the caller does not name one.
+ *
+ * Exported because it is the base anyone RESHAPING a banner has to start
+ * from. A caller who wants a wider drop wants this stock, this grain and
+ * this drape with different dimensions — and rebuilding it from the schema
+ * defaults instead gives a sheet of printer paper with no fold in it, which
+ * is a different object. A second copy of these numbers in a caller is a
+ * copy free to drift from the one the scene actually falls back to.
+ */
+declare const stageBanner: PaperConfigInput;
 interface PaperStageSceneProps {
     /** Walk, shot, figure, lighting — see `stageSchema`. */
     stage?: StageConfigInput;
@@ -962,6 +984,8 @@ interface StageExportInput {
     paper?: PaperConfigInput;
     /** The words the space is built from. Omitted renders blank banners. */
     text?: string;
+    /** Pictures on the banners, one per drop, instead of words. */
+    images?: string[];
     count?: number;
     /** Bind the walk to page scroll, pinned, rather than to the clock. */
     scroll?: boolean;
@@ -977,4 +1001,4 @@ declare function buildStageComponentSource(input: StageExportInput): string;
 /** The self-contained stage integration brief — one paste into a coding agent. */
 declare function buildStageAgentPayload(input: StageExportInput): string;
 
-export { type Ground, PaperStage, type PaperStageProps, PaperStageScene, type PaperStageSceneProps, type QualityName, type QualityTier, type ShotName, type ShotOptions, type StageConfig, type StageConfigInput, type StageExportInput, type StageGradeConfig, type StageMotion, type StageMotionInput, type StagePreset, type StageScale, type StageShot, type WalkName, type WalkPath, type WalkPathOptions, buildStageAgentPayload, buildStageComponentSource, createWalkPath, describeStage, diffStage, getStagePreset, getWalk, listStagePresets, qualityNames, shotNames, stagePresets, stageSchema, walkNames, walks };
+export { type Ground, PaperStage, type PaperStageProps, PaperStageScene, type PaperStageSceneProps, type QualityName, type QualityTier, type ShotName, type ShotOptions, type StageConfig, type StageConfigInput, type StageExportInput, type StageGradeConfig, type StageMotion, type StageMotionInput, type StagePreset, type StageScale, type StageShot, type WalkName, type WalkPath, type WalkPathOptions, buildStageAgentPayload, buildStageComponentSource, createWalkPath, describeStage, diffStage, getStagePreset, getWalk, listStagePresets, qualityNames, shotNames, stageBanner, stagePresets, stageSchema, walkNames, walks };

package/dist/stage.d.ts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { F as FieldPaperSlot, a as PaperConfigInput } from './slots-BYoLxVZ4.js';
+import { F as FieldPaperSlot, a as PaperConfigInput } from './slots-CIo7FnlY.js';
 import { z } from 'zod';
 
 /**
@@ -218,15 +218,15 @@ declare const stageSchema: z.ZodObject<{
         spread: z.ZodDefault<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
         color: string;
-        enabled: boolean;
         spread: number;
+        enabled: boolean;
         zenith: string;
         beyond: number;
         surround: boolean;
     }, {
         color?: string | undefined;
-        enabled?: boolean | undefined;
         spread?: number | undefined;
+        enabled?: boolean | undefined;
         zenith?: string | undefined;
         beyond?: number | undefined;
         surround?: boolean | undefined;
@@ -478,6 +478,17 @@ declare const stageSchema: z.ZodObject<{
         closed: boolean;
     };
     lighting: "studio" | "window" | "leaves" | "goldenhour" | "noir" | "nave" | "raking" | "lightbox";
+    light: {
+        key?: number | undefined;
+        height?: number | undefined;
+        color?: string | undefined;
+        studio?: number | undefined;
+        exposure?: number | undefined;
+        film?: "agx" | "neutral" | "filmic" | undefined;
+        direction?: number | undefined;
+        ambient?: number | undefined;
+        haze?: number | undefined;
+    };
     figure: {
         height: number;
         speed: number;
@@ -490,23 +501,12 @@ declare const stageSchema: z.ZodObject<{
     };
     source: {
         color: string;
-        enabled: boolean;
         spread: number;
+        enabled: boolean;
         zenith: string;
         beyond: number;
         surround: boolean;
     };
-    light: {
-        key?: number | undefined;
-        height?: number | undefined;
-        color?: string | undefined;
-        studio?: number | undefined;
-        exposure?: number | undefined;
-        film?: "agx" | "neutral" | "filmic" | undefined;
-        direction?: number | undefined;
-        ambient?: number | undefined;
-        haze?: number | undefined;
-    };
     shot: {
         height: number;
         offset: number;
@@ -555,6 +555,17 @@ declare const stageSchema: z.ZodObject<{
         closed?: boolean | undefined;
     } | undefined;
     lighting?: "studio" | "window" | "leaves" | "goldenhour" | "noir" | "nave" | "raking" | "lightbox" | undefined;
+    light?: {
+        key?: number | undefined;
+        height?: number | undefined;
+        color?: string | undefined;
+        studio?: number | undefined;
+        exposure?: number | undefined;
+        film?: "agx" | "neutral" | "filmic" | undefined;
+        direction?: number | undefined;
+        ambient?: number | undefined;
+        haze?: number | undefined;
+    } | undefined;
     figure?: {
         height?: number | undefined;
         speed?: number | undefined;
@@ -567,23 +578,12 @@ declare const stageSchema: z.ZodObject<{
     } | undefined;
     source?: {
         color?: string | undefined;
-        enabled?: boolean | undefined;
         spread?: number | undefined;
+        enabled?: boolean | undefined;
         zenith?: string | undefined;
         beyond?: number | undefined;
         surround?: boolean | undefined;
     } | undefined;
-    light?: {
-        key?: number | undefined;
-        height?: number | undefined;
-        color?: string | undefined;
-        studio?: number | undefined;
-        exposure?: number | undefined;
-        film?: "agx" | "neutral" | "filmic" | undefined;
-        direction?: number | undefined;
-        ambient?: number | undefined;
-        haze?: number | undefined;
-    } | undefined;
     shot?: {
         height?: number | undefined;
         offset?: number | undefined;
@@ -739,6 +739,28 @@ declare const qualityNames: readonly ["auto", "low", "medium", "high"];
 type QualityName = (typeof qualityNames)[number];
 type QualityTier = Exclude<QualityName, 'auto'>;
 
+/**
+ * Stage mode: paper as architecture, with a figure walking through it.
+ *
+ * The one guarantee worth stating — every part of the scene reads the SAME
+ * walk. The layout arranges along it, the figure follows it, the camera is
+ * stationed on it, and the source stands at the end of it. Handing those
+ * four their own copies of a path is the failure this component exists to
+ * prevent: a colonnade whose aisle the figure does not walk down is not a
+ * near-miss, it is a completely different picture.
+ */
+/** A banner: tall, translucent, with folds running the length of its drop. */
+/**
+ * The sheet a stage hangs when the caller does not name one.
+ *
+ * Exported because it is the base anyone RESHAPING a banner has to start
+ * from. A caller who wants a wider drop wants this stock, this grain and
+ * this drape with different dimensions — and rebuilding it from the schema
+ * defaults instead gives a sheet of printer paper with no fold in it, which
+ * is a different object. A second copy of these numbers in a caller is a
+ * copy free to drift from the one the scene actually falls back to.
+ */
+declare const stageBanner: PaperConfigInput;
 interface PaperStageSceneProps {
     /** Walk, shot, figure, lighting — see `stageSchema`. */
     stage?: StageConfigInput;
@@ -962,6 +984,8 @@ interface StageExportInput {
     paper?: PaperConfigInput;
     /** The words the space is built from. Omitted renders blank banners. */
     text?: string;
+    /** Pictures on the banners, one per drop, instead of words. */
+    images?: string[];
     count?: number;
     /** Bind the walk to page scroll, pinned, rather than to the clock. */
     scroll?: boolean;
@@ -977,4 +1001,4 @@ declare function buildStageComponentSource(input: StageExportInput): string;
 /** The self-contained stage integration brief — one paste into a coding agent. */
 declare function buildStageAgentPayload(input: StageExportInput): string;
 
-export { type Ground, PaperStage, type PaperStageProps, PaperStageScene, type PaperStageSceneProps, type QualityName, type QualityTier, type ShotName, type ShotOptions, type StageConfig, type StageConfigInput, type StageExportInput, type StageGradeConfig, type StageMotion, type StageMotionInput, type StagePreset, type StageScale, type StageShot, type WalkName, type WalkPath, type WalkPathOptions, buildStageAgentPayload, buildStageComponentSource, createWalkPath, describeStage, diffStage, getStagePreset, getWalk, listStagePresets, qualityNames, shotNames, stagePresets, stageSchema, walkNames, walks };
+export { type Ground, PaperStage, type PaperStageProps, PaperStageScene, type PaperStageSceneProps, type QualityName, type QualityTier, type ShotName, type ShotOptions, type StageConfig, type StageConfigInput, type StageExportInput, type StageGradeConfig, type StageMotion, type StageMotionInput, type StagePreset, type StageScale, type StageShot, type WalkName, type WalkPath, type WalkPathOptions, buildStageAgentPayload, buildStageComponentSource, createWalkPath, describeStage, diffStage, getStagePreset, getWalk, listStagePresets, qualityNames, shotNames, stageBanner, stagePresets, stageSchema, walkNames, walks };

package/dist/stage.js

@@ -3,6 +3,7 @@ import {
   LightRig,
   PaperFieldMesh,
   PaperLighting,
+  ReleaseContextOnUnmount,
   createWalkPath,
   cssColorOr,
   diffConfig,
@@ -15,7 +16,7 @@ import {
   resolveLighting,
   usePrefersReducedMotion,
   walkPathSchema
-} from "./chunk-4ZU5DZEF.js";
+} from "./chunk-HRXQTJFS.js";
 
 // src/stage/PaperStage.tsx
 import * as THREE6 from "three";
@@ -136,7 +137,7 @@ var figureSchema = z2.object({
   /** 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"),
+  color: z2.string().default("#0a0a0c").describe("color"),
   /**
    * How the figure takes light.
    *
@@ -838,7 +839,7 @@ 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"),
+  color: z3.string().default("#fff4e2").describe("color"),
   /** How far past the end of the walk it stands, world units. */
   beyond: z3.number().min(0).max(80).default(10),
   /**
@@ -870,7 +871,7 @@ var stageGroundSchema = z3.object({
    * kept its contrast against the source and gained a surface you can read
    * the size of the room from.
    */
-  color: z3.string().default("#241e19"),
+  color: z3.string().default("#241e19").describe("color"),
   /**
    * Width of one poured slab, in world units. 0 leaves the floor unseamed.
    *
@@ -894,7 +895,7 @@ var stageSuspensionSchema = z3.object({
    * paper is meant to be impossible.
    */
   type: z3.enum(["none", "thread", "rod"]).default("thread"),
-  color: z3.string().default("#9c948a"),
+  color: z3.string().default("#9c948a").describe("color"),
   /**
    * What grips the sheet.
    *
@@ -935,13 +936,13 @@ var stageColumnsSchema = z3.object({
    * 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")
+  color: z3.string().default("#5c554d").describe("color")
 });
 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")
+  color: z3.string().default("#171310").describe("color")
 });
 var stageRoomSchema = z3.object({
   enabled: z3.boolean().default(true),
@@ -954,7 +955,7 @@ var stageRoomSchema = z3.object({
    * happened to be scaled to that day.
    */
   height: z3.number().min(1).max(6).default(2.2),
-  color: z3.string().default("#171310"),
+  color: z3.string().default("#171310").describe("color"),
   /** Columns flanking the walk — see `stageColumnsSchema`. */
   columns: stageColumnsSchema.default({}),
   /** A wall at the end of the walk with the source in it. */
@@ -1388,12 +1389,13 @@ function settleTier(tier, fps, failed) {
 
 // src/stage/PaperStage.tsx
 import { jsx as jsx7, jsxs as jsxs6 } from "react/jsx-runtime";
-var BANNER = {
+var stageBanner = {
   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 } }]
 };
+var BANNER = stageBanner;
 function splitAcrossBanners(text, banners) {
   const words = text.split(/\s+/).filter(Boolean);
   if (words.length === 0 || banners <= 0) return [];
@@ -1693,7 +1695,8 @@ function PaperStage({ children, className, style, ...sceneProps }) {
       },
       children: [
         /* @__PURE__ */ jsx7(PaperStageScene, { ...sceneProps }),
-        children
+        children,
+        /* @__PURE__ */ jsx7(ReleaseContextOnUnmount, {})
       ]
     }
   ) });
@@ -2051,6 +2054,8 @@ function describeStage(input) {
   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");
+  } else if (input.images?.length) {
+    parts.push(`each printed with one of ${input.images.length} pictures`);
   }
   parts.push(`seen ${SHOT_PHRASES[stage.shot.shot]}`);
   if (stage.showFigure) {
@@ -2064,13 +2069,27 @@ function describeStage(input) {
   );
   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");
+  if (input.scroll) {
+    parts.push(
+      stage.showFigure ? "and scrolling the page walks the figure deeper into it" : "and scrolling the page carries the camera deeper into it"
+    );
+  }
   return parts.join(", ");
 }
+function exportableImages(images) {
+  let substituted = false;
+  const list = images.map((src, i) => {
+    if (!src.startsWith("data:")) return src;
+    substituted = true;
+    return `/banner-${i + 1}.jpg`;
+  });
+  return { list, substituted };
+}
 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.images?.length) lines.push(`${indent}images={images}`);
   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 ?? {};
@@ -2095,10 +2114,15 @@ const banner = ${stringifyStage(diffConfig(paperConfigSchema.parse(input.paper))
   const textConst = input.text?.trim() ? `
 
 const text = ${JSON.stringify(input.text)}` : "";
+  const scrolls = stageSchema.parse(input.stage).showFigure ? "walk the figure" : "move the camera";
+  const images = input.images?.length ? exportableImages(input.images) : null;
+  const imagesConst = images ? `
+${images.substituted ? "\n// Your uploaded pictures cannot travel in a snippet \u2014 these are\n// placeholders in the same order. Point them at your own files." : ""}
+const images = ${JSON.stringify(images.list, null, 2)}` : "";
   if (!input.scroll) {
     return `import { PaperStage, type StageConfigInput } from 'paperlab/stage'${input.paper ? "\nimport type { PaperConfigInput } from 'paperlab'" : ""}
 
-${stageConst}${bannerConst}${textConst}
+${stageConst}${bannerConst}${textConst}${imagesConst}
 
 export function ${name}() {
   return (
@@ -2111,13 +2135,13 @@ ${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}
+${stageConst}${bannerConst}${textConst}${imagesConst}
 
 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
+  // Scroll the section, ${scrolls}. The stage is pinned for the height
   // of the section, so the page scrolling past it IS the walk.
   useEffect(() => {
     const el = ref.current
@@ -2154,7 +2178,8 @@ function buildStageAgentPayload(input) {
    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})
+  const subject = stageSchema.parse(input.stage).showFigure ? "paper as architecture, with a figure walking through it" : "paper as architecture, banners hung along a walk you move through";
+  return `Integrate a Paperlab stage \u2014 ${subject} \u2014 into this project. (paperlab agent-payload v${AGENT_PAYLOAD_VERSION})
 
 1. Install the dependencies:
 
@@ -2199,6 +2224,7 @@ export {
   listStagePresets,
   qualityNames,
   shotNames,
+  stageBanner,
   stagePresets,
   stageSchema,
   walkNames,