paperlab 0.2.0 → 0.3.0

package/dist/stage.d.cts

@@ -0,0 +1,1156 @@
+import * as react from 'react';
+import { F as FieldPaperSlot, a as PaperConfigInput } from './slots-D0Nc_5dq.cjs';
+import { z } from 'zod';
+
+/**
+ * The room the walk is in.
+ *
+ * Stage mode was a void with a horizon: a graded dome, a flat plane, and a
+ * bright rectangle at the end, none of it a knowable size. That is why the
+ * walking figure was carrying the whole scale burden by itself — and why
+ * simply removing the figure would have left an abstraction rather than a
+ * hall. Architecture is the better answer: objects whose size the viewer
+ * already knows, made of flat surfaces under good light, which is the one
+ * thing a renderer never gets wrong.
+ */
+/**
+ * What holds the paper up.
+ *
+ * Every paper installation shows its hardware — monofilament from a ceiling
+ * grid, steel wire, bulldog clips, a rod — and in the scattered-sheet pieces
+ * the threads are half the composition. Stage mode's banners hung from
+ * nothing at all, which is a bigger realism gap than any shader in the
+ * backlog and closes for a few thin lines of geometry.
+ */
+declare const stageSuspensionSchema: z.ZodObject<{
+    /**
+     * 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: z.ZodDefault<z.ZodEnum<["none", "thread", "rod"]>>;
+    color: z.ZodDefault<z.ZodString>;
+    /**
+     * 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: z.ZodDefault<z.ZodEnum<["none", "clip", "peg"]>>;
+}, "strip", z.ZodTypeAny, {
+    type: "none" | "thread" | "rod";
+    color: string;
+    hardware: "none" | "clip" | "peg";
+}, {
+    type?: "none" | "thread" | "rod" | undefined;
+    color?: string | undefined;
+    hardware?: "none" | "clip" | "peg" | undefined;
+}>;
+declare const stageRoomSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    /**
+     * 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: z.ZodDefault<z.ZodNumber>;
+    color: z.ZodDefault<z.ZodString>;
+    /** Columns flanking the walk — see `stageColumnsSchema`. */
+    columns: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        /** Centres this far apart along the walk. Roughly a bay. */
+        spacing: z.ZodDefault<z.ZodNumber>;
+        /** Shaft width. The number doing the work — a column is a known size. */
+        width: z.ZodDefault<z.ZodNumber>;
+        /**
+         * 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: z.ZodDefault<z.ZodNumber>;
+        /**
+         * 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: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        width: number;
+        offset: number;
+        color: string;
+        spacing: number;
+        enabled: boolean;
+    }, {
+        width?: number | undefined;
+        offset?: number | undefined;
+        color?: string | undefined;
+        spacing?: number | undefined;
+        enabled?: boolean | undefined;
+    }>>;
+    /** A wall at the end of the walk with the source in it. */
+    doorway: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        /** Opening size, as a multiple of the source's own. 1 frames it exactly. */
+        opening: z.ZodDefault<z.ZodNumber>;
+        color: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        color: string;
+        enabled: boolean;
+        opening: number;
+    }, {
+        color?: string | undefined;
+        enabled?: boolean | undefined;
+        opening?: number | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    height: number;
+    color: string;
+    enabled: boolean;
+    columns: {
+        width: number;
+        offset: number;
+        color: string;
+        spacing: number;
+        enabled: boolean;
+    };
+    doorway: {
+        color: string;
+        enabled: boolean;
+        opening: number;
+    };
+}, {
+    height?: number | undefined;
+    color?: string | undefined;
+    enabled?: boolean | undefined;
+    columns?: {
+        width?: number | undefined;
+        offset?: number | undefined;
+        color?: string | undefined;
+        spacing?: number | undefined;
+        enabled?: boolean | undefined;
+    } | undefined;
+    doorway?: {
+        color?: string | undefined;
+        enabled?: boolean | undefined;
+        opening?: number | undefined;
+    } | undefined;
+}>;
+/**
+ * The print: what happens to the frame after the scene is drawn.
+ *
+ * This lives on the stage rather than on the lighting rig, even though it
+ * belongs to the same family as `exposure` and `film`, because the rig is
+ * read by `<Paper>` too and `<Paper>` has no composer. A grade in the rig
+ * would be a promise one of the two modes could not keep.
+ *
+ * Every value defaults to a real look rather than to zero — a stage that
+ * asks for nothing should still be graded, and `grade: { bloom: 0 }` is how
+ * you say you want it raw.
+ */
+declare const stageGradeSchema: z.ZodObject<{
+    /**
+     * 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: z.ZodDefault<z.ZodNumber>;
+    /**
+     * 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: z.ZodDefault<z.ZodNumber>;
+    /**
+     * 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: z.ZodDefault<z.ZodNumber>;
+    /** How far the corners fall off. A frame with no edge reads as a viewport rather than a photograph. */
+    vignette: z.ZodDefault<z.ZodNumber>;
+    /**
+     * 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: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    grain: number;
+    depth: number;
+    bloom: number;
+    threshold: number;
+    vignette: number;
+}, {
+    grain?: number | undefined;
+    depth?: number | undefined;
+    bloom?: number | undefined;
+    threshold?: number | undefined;
+    vignette?: number | undefined;
+}>;
+declare const stageSchema: z.ZodObject<{
+    path: z.ZodDefault<z.ZodObject<{
+        points: z.ZodDefault<z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>, "many">>;
+        closed: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        points: [number, number][];
+        closed: boolean;
+    }, {
+        points?: [number, number][] | undefined;
+        closed?: boolean | undefined;
+    }>>;
+    shot: z.ZodDefault<z.ZodObject<{
+        shot: z.ZodDefault<z.ZodEnum<["follow", "lead", "low", "wide"]>>;
+        distance: z.ZodDefault<z.ZodNumber>;
+        height: z.ZodDefault<z.ZodNumber>;
+        lookAhead: z.ZodDefault<z.ZodNumber>;
+        offset: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        height: number;
+        offset: number;
+        distance: number;
+        shot: "low" | "follow" | "lead" | "wide";
+        lookAhead: number;
+    }, {
+        height?: number | undefined;
+        offset?: number | undefined;
+        distance?: number | undefined;
+        shot?: "low" | "follow" | "lead" | "wide" | undefined;
+        lookAhead?: number | undefined;
+    }>>;
+    figure: z.ZodDefault<z.ZodObject<{
+        height: z.ZodDefault<z.ZodNumber>;
+        speed: z.ZodDefault<z.ZodNumber>;
+        stride: z.ZodDefault<z.ZodNumber>;
+        swing: z.ZodDefault<z.ZodNumber>;
+        color: z.ZodDefault<z.ZodString>;
+        finish: z.ZodDefault<z.ZodEnum<["silhouette", "shaded"]>>;
+        gait: z.ZodDefault<z.ZodEnum<["auto", "walk", "run"]>>;
+        model: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        height: number;
+        speed: number;
+        color: string;
+        stride: number;
+        swing: number;
+        finish: "silhouette" | "shaded";
+        gait: "auto" | "walk" | "run";
+        model?: string | undefined;
+    }, {
+        height?: number | undefined;
+        speed?: number | undefined;
+        color?: string | undefined;
+        stride?: number | undefined;
+        swing?: number | undefined;
+        finish?: "silhouette" | "shaded" | undefined;
+        gait?: "auto" | "walk" | "run" | undefined;
+        model?: string | undefined;
+    }>>;
+    /** Stage mode is built for `nave`; the others are all front-lit. */
+    lighting: z.ZodDefault<z.ZodEnum<["studio", "window", "leaves", "goldenhour", "noir", "nave", "raking", "lightbox"]>>;
+    /**
+     * 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: z.ZodDefault<z.ZodObject<{
+        exposure: z.ZodOptional<z.ZodNumber>;
+        film: z.ZodOptional<z.ZodEnum<["agx", "neutral", "filmic"]>>;
+        key: z.ZodOptional<z.ZodNumber>;
+        color: z.ZodOptional<z.ZodString>;
+        direction: z.ZodOptional<z.ZodNumber>;
+        height: z.ZodOptional<z.ZodNumber>;
+        ambient: z.ZodOptional<z.ZodNumber>;
+        studio: z.ZodOptional<z.ZodNumber>;
+        haze: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        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;
+    }, {
+        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;
+    }>>;
+    /**
+     * 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: z.ZodDefault<z.ZodBoolean>;
+    source: z.ZodDefault<z.ZodObject<{
+        /** The bright void the walk resolves toward. Without it the vanishing point is a hole. */
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        color: z.ZodDefault<z.ZodString>;
+        /** How far past the end of the walk it stands, world units. */
+        beyond: z.ZodDefault<z.ZodNumber>;
+        /**
+         * 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: z.ZodDefault<z.ZodBoolean>;
+        /** Colour overhead. The horizon takes the source's own colour. */
+        zenith: z.ZodDefault<z.ZodString>;
+        /**
+         * 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: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        color: string;
+        enabled: boolean;
+        spread: number;
+        zenith: string;
+        beyond: number;
+        surround: boolean;
+    }, {
+        color?: string | undefined;
+        enabled?: boolean | undefined;
+        spread?: number | undefined;
+        zenith?: string | undefined;
+        beyond?: number | undefined;
+        surround?: boolean | undefined;
+    }>>;
+    ground: z.ZodDefault<z.ZodObject<{
+        /** The floor. Without something to catch the shadows there is no ground and no scale. */
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        /**
+         * 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: z.ZodDefault<z.ZodString>;
+        /**
+         * 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: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        color: string;
+        enabled: boolean;
+        slab: number;
+    }, {
+        color?: string | undefined;
+        enabled?: boolean | undefined;
+        slab?: number | undefined;
+    }>>;
+    /** Ceiling and the architecture around the walk — see `stageRoomSchema`. */
+    room: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        /**
+         * 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: z.ZodDefault<z.ZodNumber>;
+        color: z.ZodDefault<z.ZodString>;
+        /** Columns flanking the walk — see `stageColumnsSchema`. */
+        columns: z.ZodDefault<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            /** Centres this far apart along the walk. Roughly a bay. */
+            spacing: z.ZodDefault<z.ZodNumber>;
+            /** Shaft width. The number doing the work — a column is a known size. */
+            width: z.ZodDefault<z.ZodNumber>;
+            /**
+             * 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: z.ZodDefault<z.ZodNumber>;
+            /**
+             * 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: z.ZodDefault<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            width: number;
+            offset: number;
+            color: string;
+            spacing: number;
+            enabled: boolean;
+        }, {
+            width?: number | undefined;
+            offset?: number | undefined;
+            color?: string | undefined;
+            spacing?: number | undefined;
+            enabled?: boolean | undefined;
+        }>>;
+        /** A wall at the end of the walk with the source in it. */
+        doorway: z.ZodDefault<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            /** Opening size, as a multiple of the source's own. 1 frames it exactly. */
+            opening: z.ZodDefault<z.ZodNumber>;
+            color: z.ZodDefault<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            color: string;
+            enabled: boolean;
+            opening: number;
+        }, {
+            color?: string | undefined;
+            enabled?: boolean | undefined;
+            opening?: number | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        height: number;
+        color: string;
+        enabled: boolean;
+        columns: {
+            width: number;
+            offset: number;
+            color: string;
+            spacing: number;
+            enabled: boolean;
+        };
+        doorway: {
+            color: string;
+            enabled: boolean;
+            opening: number;
+        };
+    }, {
+        height?: number | undefined;
+        color?: string | undefined;
+        enabled?: boolean | undefined;
+        columns?: {
+            width?: number | undefined;
+            offset?: number | undefined;
+            color?: string | undefined;
+            spacing?: number | undefined;
+            enabled?: boolean | undefined;
+        } | undefined;
+        doorway?: {
+            color?: string | undefined;
+            enabled?: boolean | undefined;
+            opening?: number | undefined;
+        } | undefined;
+    }>>;
+    /** Thread and clips — see `stageSuspensionSchema`. */
+    suspension: z.ZodDefault<z.ZodObject<{
+        /**
+         * 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: z.ZodDefault<z.ZodEnum<["none", "thread", "rod"]>>;
+        color: z.ZodDefault<z.ZodString>;
+        /**
+         * 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: z.ZodDefault<z.ZodEnum<["none", "clip", "peg"]>>;
+    }, "strip", z.ZodTypeAny, {
+        type: "none" | "thread" | "rod";
+        color: string;
+        hardware: "none" | "clip" | "peg";
+    }, {
+        type?: "none" | "thread" | "rod" | undefined;
+        color?: string | undefined;
+        hardware?: "none" | "clip" | "peg" | undefined;
+    }>>;
+    /**
+     * 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: z.ZodDefault<z.ZodObject<{
+        /**
+         * 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: z.ZodDefault<z.ZodNumber>;
+        /**
+         * 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: z.ZodDefault<z.ZodNumber>;
+        /**
+         * 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: z.ZodDefault<z.ZodNumber>;
+        /** How far the corners fall off. A frame with no edge reads as a viewport rather than a photograph. */
+        vignette: z.ZodDefault<z.ZodNumber>;
+        /**
+         * 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: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        grain: number;
+        depth: number;
+        bloom: number;
+        threshold: number;
+        vignette: number;
+    }, {
+        grain?: number | undefined;
+        depth?: number | undefined;
+        bloom?: number | undefined;
+        threshold?: number | undefined;
+        vignette?: number | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    path: {
+        points: [number, number][];
+        closed: boolean;
+    };
+    lighting: "studio" | "window" | "leaves" | "goldenhour" | "noir" | "nave" | "raking" | "lightbox";
+    figure: {
+        height: number;
+        speed: number;
+        color: string;
+        stride: number;
+        swing: number;
+        finish: "silhouette" | "shaded";
+        gait: "auto" | "walk" | "run";
+        model?: string | undefined;
+    };
+    source: {
+        color: string;
+        enabled: boolean;
+        spread: number;
+        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;
+        distance: number;
+        shot: "low" | "follow" | "lead" | "wide";
+        lookAhead: number;
+    };
+    ground: {
+        color: string;
+        enabled: boolean;
+        slab: number;
+    };
+    showFigure: boolean;
+    room: {
+        height: number;
+        color: string;
+        enabled: boolean;
+        columns: {
+            width: number;
+            offset: number;
+            color: string;
+            spacing: number;
+            enabled: boolean;
+        };
+        doorway: {
+            color: string;
+            enabled: boolean;
+            opening: number;
+        };
+    };
+    suspension: {
+        type: "none" | "thread" | "rod";
+        color: string;
+        hardware: "none" | "clip" | "peg";
+    };
+    grade: {
+        grain: number;
+        depth: number;
+        bloom: number;
+        threshold: number;
+        vignette: number;
+    };
+}, {
+    path?: {
+        points?: [number, number][] | undefined;
+        closed?: boolean | undefined;
+    } | undefined;
+    lighting?: "studio" | "window" | "leaves" | "goldenhour" | "noir" | "nave" | "raking" | "lightbox" | undefined;
+    figure?: {
+        height?: number | undefined;
+        speed?: number | undefined;
+        color?: string | undefined;
+        stride?: number | undefined;
+        swing?: number | undefined;
+        finish?: "silhouette" | "shaded" | undefined;
+        gait?: "auto" | "walk" | "run" | undefined;
+        model?: string | undefined;
+    } | undefined;
+    source?: {
+        color?: string | undefined;
+        enabled?: boolean | undefined;
+        spread?: number | 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;
+        distance?: number | undefined;
+        shot?: "low" | "follow" | "lead" | "wide" | undefined;
+        lookAhead?: number | undefined;
+    } | undefined;
+    ground?: {
+        color?: string | undefined;
+        enabled?: boolean | undefined;
+        slab?: number | undefined;
+    } | undefined;
+    showFigure?: boolean | undefined;
+    room?: {
+        height?: number | undefined;
+        color?: string | undefined;
+        enabled?: boolean | undefined;
+        columns?: {
+            width?: number | undefined;
+            offset?: number | undefined;
+            color?: string | undefined;
+            spacing?: number | undefined;
+            enabled?: boolean | undefined;
+        } | undefined;
+        doorway?: {
+            color?: string | undefined;
+            enabled?: boolean | undefined;
+            opening?: number | undefined;
+        } | undefined;
+    } | undefined;
+    suspension?: {
+        type?: "none" | "thread" | "rod" | undefined;
+        color?: string | undefined;
+        hardware?: "none" | "clip" | "peg" | undefined;
+    } | undefined;
+    grade?: {
+        grain?: number | undefined;
+        depth?: number | undefined;
+        bloom?: number | undefined;
+        threshold?: number | undefined;
+        vignette?: number | undefined;
+    } | undefined;
+}>;
+type StageConfig = z.infer<typeof stageSchema>;
+type StageConfigInput = z.input<typeof stageSchema>;
+type StageGradeConfig = z.infer<typeof stageGradeSchema>;
+
+/**
+ * Moving through a stage.
+ *
+ * The scene was a picture you watched: the camera is stationed on the walk,
+ * the walk is driven by `progress`, and if nobody supplied one it ran on a
+ * clock. There was nothing to touch. This is the other half — the viewer
+ * drives the walk themselves, by dragging, by wheel, by arrow key, or by
+ * clicking the paper they want to stand in front of.
+ *
+ * It drives ONE number: distance walked. Everything else in the scene is
+ * already derived from that — the figure, the camera, the light at the end —
+ * so navigation cannot pull the parts of the scene away from each other,
+ * which is the failure this whole component is arranged to prevent. In
+ * particular the camera is still not something anything else may move: there
+ * is no orbit here, and dragging does not look around. It walks.
+ *
+ * Pure math lives here so it tests in node; the listeners are in `useWalk`.
+ */
+declare const stageMotionSchema: z.ZodObject<{
+    /**
+     * 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: z.ZodDefault<z.ZodEnum<["autoplay", "drag", "none"]>>;
+    /** Multiplier on the pace: the figure's walking speed for `autoplay`, the hand for `drag`. */
+    speed: z.ZodDefault<z.ZodNumber>;
+    /**
+     * 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: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    speed: number;
+    driver: "none" | "autoplay" | "drag";
+    capture: boolean;
+}, {
+    speed?: number | undefined;
+    driver?: "none" | "autoplay" | "drag" | undefined;
+    capture?: boolean | undefined;
+}>;
+type StageMotion = z.infer<typeof stageMotionSchema>;
+type StageMotionInput = z.input<typeof stageMotionSchema>;
+
+/**
+ * Render quality tiers.
+ *
+ * A stage is the heaviest thing this library draws — tens of thousands of
+ * subdivided vertices, a shadow pass, a translucent fragment shader and a
+ * full-screen backdrop — and it has to run on machines nobody developing it
+ * owns. Quality is deliberately NOT part of `stageSchema`: it describes the
+ * device, not the artwork, so it must never travel in a preset or a shared
+ * link. Two people opening the same link should see the same scene at
+ * whatever fidelity their hardware can hold.
+ *
+ * The five knobs, in the order they actually cost:
+ *
+ * - `segments` — a CEILING on what `segments: 'auto'` may ask for along the
+ *   direction a banner's folds run. Quadratic in principle, though a
+ *   deformer's own floor holds the bottom: `drape` states it needs 48 across
+ *   its folds, so `low` cannot take the banners below that and should not.
+ *
+ *   It used to be written straight over the sheet's `segments` as a number,
+ *   and that made it **do nothing at all**. A number applies to BOTH axes,
+ *   the field caps it at 48 on the way down, and the deformer floor raised
+ *   it back to 48 on the way up — so every tier drew the identical 48 × 48
+ *   banner. Measured before the fix: 143,644 triangles at `medium` whatever
+ *   the tier said. Worth remembering as a shape of bug — a knob nobody had
+ *   measured, in the file that exists to describe what things cost.
+ * - `shadowMapSize` — the shadow pass re-renders the scene's geometry. 0
+ *   turns shadows off, which on a weak machine is the difference between
+ *   moving and not.
+ * - `dpr` — fragment cost scales with the square of it, and this scene is
+ *   fragment-heavy (translucency, fog, a full-screen backdrop).
+ * - `environment` — the studio light. One prefiltered cube built once, then
+ *   a texture read per fragment for every lit surface in the scene. Measured
+ *   at a third of the frame at `medium` (51 ms → 33 ms with it off), which
+ *   makes it the most expensive single thing here after the geometry, so the
+ *   bottom tier falls back to the flat ambient it replaced.
+ * - `surround` — one more full-screen draw; cheap, but free to drop.
+ */
+declare const qualityNames: readonly ["auto", "low", "medium", "high"];
+type QualityName = (typeof qualityNames)[number];
+type QualityTier = Exclude<QualityName, 'auto'>;
+
+interface PaperStageSceneProps {
+    /** Walk, shot, figure, lighting — see `stageSchema`. */
+    stage?: StageConfigInput;
+    /** Any layout, but `colonnade` is the one built to arrange along a walk. */
+    layout?: string;
+    layoutOptions?: Record<string, unknown>;
+    /** Per-banner slots, exactly as in field mode. */
+    papers?: FieldPaperSlot[];
+    images?: string[];
+    /**
+     * Words on the banners. A string is split across them a line at a time; an
+     * array is used as given. This is the whole point of the mode — a space
+     * built out of something the viewer wrote.
+     */
+    text?: string | string[];
+    /** Shared preset behind every banner. */
+    preset?: string | PaperConfigInput;
+    /** How many banners, when none of `papers` / `images` / `text` says. */
+    count?: number;
+    /**
+     * How far along the walk the figure is, 0..1. Bind it to scroll and the
+     * page scrolls the walk. Omit and `motion` decides who drives.
+     *
+     * Supplying it makes the stage a CONTROLLED component and outranks
+     * `motion` entirely — a driver and a page both writing the same number is
+     * a fight, not a feature.
+     */
+    progress?: number;
+    /**
+     * Who drives the walk when `progress` does not: `drag` hands it to the
+     * viewer (pointer, wheel, arrow keys, clicking a paper), `autoplay` to the
+     * clock, `none` to nobody. Same contract as a field's `motion`.
+     */
+    motion?: StageMotionInput;
+    /** Fires when the viewer moves to a paper — by clicking it, or by stepping onto it. */
+    onVisit?(paper: number): void;
+    /**
+     * The live position on the walk, 0..1, every frame it changes — whoever is
+     * driving. Mirror it into an uncontrolled input to show a scrubber that
+     * follows the walk without re-rendering the scene sixty times a second;
+     * `<PaperMesh>`'s `onProgress` is the same affordance for a behavior.
+     */
+    onProgress?(walk: number): void;
+    reducedMotion?: boolean;
+    /**
+     * How much the render is allowed to cost. `auto` (the default) starts in
+     * the middle and adapts to whatever the machine turns out to manage — this
+     * scene runs on hardware nobody developing it owns. Not part of the stage
+     * config: quality describes the DEVICE, not the artwork, so it must never
+     * travel in a preset or a shared link.
+     */
+    quality?: QualityName;
+    /**
+     * Fires when `auto` moves the tier. Useful for showing the viewer what
+     * they are getting, and for measuring what real machines settle on.
+     */
+    onQualityChange?(tier: QualityTier): void;
+}
+interface PaperStageProps extends PaperStageSceneProps {
+    children?: React.ReactNode;
+    className?: string;
+    style?: React.CSSProperties;
+}
+declare function PaperStageScene({ stage: stageInput, quality, onQualityChange, layout, layoutOptions, papers, images, text, preset, count, progress, motion, onVisit, onProgress, reducedMotion, }: PaperStageSceneProps): react.JSX.Element;
+/** `<PaperStage />` owns its Canvas; `<PaperStageScene />` drops into an existing one. */
+declare function PaperStage({ children, className, style, ...sceneProps }: PaperStageProps): react.JSX.Element;
+
+/**
+ * The source's default burn, in linear light.
+ *
+ * Chosen by matching: at 3.4 the tone-mapped source lands on the same read
+ * as the un-mapped plane it replaces, so a stage that never mounts a
+ * composer looks the way it always did, and one that does gets a source
+ * that blooms instead of a rectangle that clips.
+ */
+declare const SOURCE_INTENSITY = 3.4;
+
+/**
+ * Named stages. A mode with no presets asks its visitor to invent a space
+ * out of eleven sliders before it will show them anything — and stage mode
+ * takes about fifteen seconds to understand once you have seen one, which
+ * means the presets ARE the explanation.
+ *
+ * Each names somewhere paper is actually hung at architectural scale, the
+ * same rule the layouts follow.
+ */
+interface StagePreset {
+    id: string;
+    label: string;
+    /** One line, shown under the name. What you are about to look at. */
+    description: string;
+    stage: StageConfigInput;
+    layout: string;
+    layoutOptions?: Record<string, unknown>;
+    /** The paper itself — banners differ per stage more than anything else. */
+    paper?: PaperConfigInput;
+    count: number;
+    text?: string;
+}
+declare const stagePresets: Record<string, StagePreset>;
+declare function getStagePreset(id: string): StagePreset;
+declare function listStagePresets(): string[];
+
+/**
+ * The walk — a path across the ground plane that a figure follows and that
+ * layouts arrange paper along. Pure 2D math (x, z on the floor, y is always
+ * up), no three.js, so it tests in node and is cheap enough to call from
+ * inside a layout's pure `pose`.
+ *
+ * Centripetal Catmull-Rom through the control points — it will not cusp or
+ * overshoot when two points bunch together, which a uniform spline does —
+ * resampled to a uniform arc-length polyline. That resampling is the point:
+ * `pointAt(s)` advances at constant SPEED, so a figure stepping `s` forward
+ * at a steady rate covers ground at a steady rate. A raw spline parameter
+ * would have it sprint through the straights and crawl around the corners.
+ */
+/** A point on the floor. */
+type Ground = [x: number, z: number];
+declare const walkPathSchema: z.ZodObject<{
+    /**
+     * Control points on the ground plane, [x, z]. The default walks away from
+     * the camera down -Z — the shot every reference image is composed on.
+     */
+    points: z.ZodDefault<z.ZodArray<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>, "many">>;
+    /** Join the last point back to the first: an endless walk, and the only form `phase` can slide. */
+    closed: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    points: [number, number][];
+    closed: boolean;
+}, {
+    points?: [number, number][] | undefined;
+    closed?: boolean | undefined;
+}>;
+type WalkPathOptions = z.infer<typeof walkPathSchema>;
+interface WalkPath {
+    /** Total arc length in world units. */
+    readonly length: number;
+    readonly closed: boolean;
+    /** `s` is normalized arc length: 0 = the start, 1 = the end. Closed paths wrap, open paths clamp. */
+    pointAt(s: number): Ground;
+    /** Unit forward direction at `s`. */
+    tangentAt(s: number): Ground;
+    /** Unit LEFT-hand normal at `s` — the side of the aisle a walker's left hand points to. */
+    normalAt(s: number): Ground;
+}
+declare function createWalkPath(options: WalkPathOptions): WalkPath;
+
+/**
+ * Named walks. A path is a list of control points, which is the right thing
+ * to serialize and the wrong thing to put in front of someone — nobody wants
+ * to type coordinates to find out what a curved colonnade looks like. These
+ * are the shapes worth starting from; every one resolves to ordinary points,
+ * so editing on from here stays possible.
+ */
+declare const walkNames: readonly ["straight", "bend", "ess", "ring", "spiral"];
+type WalkName = (typeof walkNames)[number];
+declare const walks: Record<WalkName, WalkPathOptions>;
+declare function getWalk(name: WalkName): WalkPathOptions;
+
+/**
+ * Where to put the camera on a walk.
+ *
+ * `fitCamera` in field/framing.ts solves a different problem — get every
+ * sheet inside the frustum — and solving it here would produce the neutral
+ * three-quarter product shot that stage mode exists to avoid. These are
+ * SHOTS: a camera stationed relative to the walking figure, framing the
+ * space rather than the objects, with the vanishing point doing the work.
+ */
+declare const shotNames: readonly ["follow", "lead", "low", "wide"];
+type ShotName = (typeof shotNames)[number];
+declare const shotSchema: z.ZodObject<{
+    shot: z.ZodDefault<z.ZodEnum<["follow", "lead", "low", "wide"]>>;
+    /**
+     * 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.ZodDefault<z.ZodNumber>;
+    /** Multiplier on the shot's natural camera height. 1 is as designed. */
+    height: z.ZodDefault<z.ZodNumber>;
+    /** How far up the walk the camera looks past the figure, world units. */
+    lookAhead: z.ZodDefault<z.ZodNumber>;
+    /** Sideways step off the walk line, world units. Positive is the walker's left. */
+    offset: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    height: number;
+    offset: number;
+    distance: number;
+    shot: "low" | "follow" | "lead" | "wide";
+    lookAhead: number;
+}, {
+    height?: number | undefined;
+    offset?: number | undefined;
+    distance?: number | undefined;
+    shot?: "low" | "follow" | "lead" | "wide" | undefined;
+    lookAhead?: number | undefined;
+}>;
+type ShotOptions = z.infer<typeof shotSchema>;
+interface StageShot {
+    position: [x: number, y: number, z: number];
+    target: [x: number, y: number, z: number];
+}
+/**
+ * What each shot is FOR. A stage has two subjects at very different scales —
+ * a body about 1.75 units tall and paper five times that — and a camera that
+ * only knows about the body frames the body, which is how a colonnade of
+ * printed banners ends up showing its bottom third and the tops of some
+ * letterforms. Camera height stays a body measurement (eye level is eye
+ * level); where it AIMS is a blend, and the paper carries most of it.
+ */
+interface StageScale {
+    /** Standing height of the figure. */
+    figure: number;
+    /** Height of the tallest paper on the stage. */
+    paper: number;
+}
+
+/**
+ * Stage-mode export. Same anatomy and version as the paper and field
+ * exports, with one addition that matters more than the rest: the scroll
+ * variant. `progress` is the whole interaction model of a stage, and a
+ * scroll-driven hero is what most people opening this menu actually want —
+ * so the export writes the pinning and the scroll math, which is the part
+ * that is fiddly to get right and boring to write.
+ */
+interface StageExportInput {
+    stage: StageConfigInput;
+    layout: string;
+    layoutOptions?: Record<string, unknown>;
+    /** The banner itself — dims, stock, drape. Omitted uses the built-in banner. */
+    paper?: PaperConfigInput;
+    /** The words the space is built from. Omitted renders blank banners. */
+    text?: string;
+    count?: number;
+    /** Bind the walk to page scroll, pinned, rather than to the clock. */
+    scroll?: boolean;
+    /** Exported component name. */
+    componentName?: string;
+}
+/** Which named walk these points are, if any — the export reads better for it. */
+declare function walkNameFor(path: StageConfig['path']): WalkName | undefined;
+/** The stage config with defaults removed — what actually needs writing down. */
+declare function diffStage(stage: StageConfigInput): Record<string, unknown>;
+/**
+ * JSON.stringify, except an array of plain numbers stays on one line. A walk
+ * is a list of coordinate pairs, and the default pretty-printer spreads each
+ * `[6, 17]` over four lines — twenty lines of punctuation for one gentle
+ * curve. Exported code is a product surface; it should read like something a
+ * person wrote.
+ */
+declare function stringifyStage(value: unknown, indent?: number): string;
+/** The one-line visual an agent verifies after `npm run dev`. */
+declare function describeStage(input: StageExportInput): string;
+/** Component source shared by the JSX snippet and the agent payload. */
+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, SOURCE_INTENSITY, 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, stageGradeSchema, stageMotionSchema, stagePresets, stageRoomSchema, stageSchema, stageSuspensionSchema, stringifyStage, walkNameFor, walkNames, walks };