pro-visu 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,818 @@
+import { z } from 'zod';
+
+declare const easingSchema: z.ZodEnum<["linear", "easeInOutCubic", "easeInOutQuad", "easeOutCubic", "easeInOutSine", "easeInOutExpo", "easeOutQuint"]>;
+type Easing = z.infer<typeof easingSchema>;
+/** One choreographed scroll step. */
+interface ChoreographyStepInput {
+    /** Target: a 0..1 number, an "NN%" string, or a CSS selector to bring into view. */
+    to: number | string;
+    /** Travel time to this target (ms). Default 1200. */
+    durationMs?: number;
+    /** Hold time at this target after arriving (ms). Default 800. */
+    holdMs?: number;
+    /** Easing for the travel to this target. Default "easeInOutCubic". */
+    easing?: Easing;
+}
+/** One step of a scripted interaction (`actions` / `focus.actions`). */
+interface InteractionActionInput {
+    /** What this step does. */
+    do: "move" | "click" | "hover" | "type" | "scrollTo" | "wait";
+    /** Target element for move/click/hover/type. */
+    selector?: string;
+    /** Viewport-relative X target for a selector-less `move` (0..1). */
+    x?: number;
+    /** Viewport-relative Y target for a selector-less `move` (0..1). */
+    y?: number;
+    /** Text to type (for `type`). */
+    text?: string;
+    /** Scroll target for `scrollTo`: a 0..1 number, an "NN%" string, or a CSS selector. */
+    to?: number | string;
+    /** Cursor travel / scroll animation time (ms). Default 700. */
+    durationMs?: number;
+    /** Pause after the step (ms). Default 600. */
+    holdMs?: number;
+}
+/** Tuning for auto-section choreography (`autoSections`). */
+interface AutoSectionsInput {
+    /** Min element height (as a fraction of the viewport) to count as a section. Default 0.5. */
+    minHeightFraction?: number;
+    /** Explicit section selector; overrides the heuristic. Omit to auto-detect. */
+    selector?: string;
+    /** Hold at each detected section (ms). Default 700. */
+    holdMs?: number;
+    /** Total clip length (ms) split across detected sections. Default 12000. */
+    durationMs?: number;
+    /** Cap on the number of sections. Default 8. */
+    maxSections?: number;
+    /** Distribute travel time by distance for uniform scroll speed. Default true. */
+    constantVelocity?: boolean;
+}
+/** An intro / outro card (`intro` / `outro`). */
+interface CardInput {
+    /** Card title (large). Omit for none. */
+    title?: string;
+    /** Card subtitle (small, under the title). Omit for none. */
+    subtitle?: string;
+    /** Card background color. Default black. */
+    background?: string;
+    /** Card text color. Default white. */
+    color?: string;
+    /** How long the card holds (ms). Default 1500. */
+    durationMs?: number;
+    /** Fade in/out length (ms). Default 400. */
+    fadeMs?: number;
+}
+/** A timed on-screen annotation (`annotations`). */
+interface AnnotationInput {
+    /** Caption text shown while active. Omit for a ring/spotlight with no caption. */
+    text?: string;
+    /** Selector to outline with a highlight ring. */
+    ring?: string;
+    /** Selector to spotlight (everything else dimmed). */
+    spotlight?: string;
+    /** When it appears (clip time, ms). Default 0. */
+    atMs?: number;
+    /** When it disappears (clip time, ms). Default = end of clip. */
+    untilMs?: number;
+    /** Caption placement. Default "bottom". */
+    position?: "top" | "bottom" | "center";
+}
+/** Ken Burns slow-zoom config ("frames" capture only). */
+interface KenBurnsInput {
+    /** Start scale (1 = no zoom). Default 1. */
+    scaleFrom?: number;
+    /** End scale. Default 1.08. */
+    scaleTo?: number;
+    /** Easing for the zoom ramp. Default "easeInOutCubic". */
+    easing?: Easing;
+    /** Zoom origin X within the viewport (0 = left, 1 = right). Default 0.5. */
+    originX?: number;
+    /** Zoom origin Y within the viewport (0 = top, 1 = bottom). Default 0.5. */
+    originY?: number;
+}
+/** The synthetic cursor shown during an interaction. */
+interface CursorInput {
+    /** Show the cursor. Default true (when `actions` is set). */
+    show?: boolean;
+    /** Cursor size (px). Default 22. */
+    size?: number;
+    /** Cursor color. Default white-with-shadow. */
+    color?: string;
+}
+/** Element-focused clip config (`focus`). */
+interface FocusInput {
+    /** Selector of the element to scroll into view and crop to. */
+    selector: string;
+    /** Padding (px) around the element when cropping. Default 24. */
+    padding?: number;
+    /** Optional steps to trigger the component (e.g. open a dropdown) before holding. */
+    actions?: InteractionActionInput[];
+    /** Time to dwell on the element after positioning / triggering (ms). Default 2000. */
+    holdMs?: number;
+}
+/** One extra viewport to also capture the reel at (`viewports`). */
+interface ViewportInput {
+    /** Name appended to the asset (<name>-<viewport name>). */
+    name: string;
+    /** Viewport width in CSS px. */
+    width: number;
+    /** Viewport height in CSS px. */
+    height: number;
+    /** Override the generator-level `deviceScaleFactor` for this viewport. Omit to inherit it. */
+    deviceScaleFactor?: number;
+}
+/** One route in a multi-page tour: a URL string, or an object with per-route choreography. */
+type RouteInput = string | {
+    /** Route URL (absolute, or a "/path" against the managed server). */
+    url: string;
+    /** Per-route choreographed scroll (overrides the tour default). */
+    choreography?: ChoreographyStepInput[];
+    /** Per-route auto-section choreography. */
+    autoSections?: boolean | AutoSectionsInput;
+    /** This route's slice of the tour (ms). */
+    durationMs?: number;
+};
+/** Target output aspect: a preset, or an explicit pixel box. */
+type AspectInput = "16:9" | "9:16" | "1:1" | {
+    width: number;
+    height: number;
+};
+/**
+ * Author-facing options for the `scroll-reel` generator — a video of a page. By default it eases a
+ * single top→bottom scroll; the options below switch it into choreographed / auto-section / focus /
+ * interaction / multi-route modes, add cards & annotations, clean up the page, and reframe / re-encode
+ * the output. Everything is optional, with the defaults noted below.
+ */
+interface ScrollReelOptionsInput {
+    /** Viewport + output width in CSS px. Default 1280. */
+    width?: number;
+    /** Viewport + output height in CSS px. Default 800. */
+    height?: number;
+    /** Render scale (2 = retina-crisp capture, downscaled into the video). Default 2. */
+    deviceScaleFactor?: number;
+    /** Output frames per second (re-encoded from the recording). Default 30. */
+    fps?: number;
+    /** Time to scroll from top to bottom (ms). Default 6000. */
+    duration?: number;
+    /** Easing for the default top→bottom scroll. Default "easeInOutCubic". */
+    easing?: Easing;
+    /** Dwell at the top before scrolling (ms). Default 500. */
+    startDelayMs?: number;
+    /** Dwell at the bottom after scrolling (ms). Default 800. */
+    endDwellMs?: number;
+    /** Page-load milestone to wait for before recording. Default "networkidle". */
+    waitUntil?: "load" | "domcontentloaded" | "networkidle" | "commit";
+    /** Optional element to wait for before recording (e.g. a hero section). Omit to skip. */
+    waitForSelector?: string;
+    /** x264 quality, 0–51 (lower = better quality / larger file). Default 18. */
+    crf?: number;
+    /**
+     * Capture strategy. "frames" (default) steps a virtual clock per frame — frame-accurate, crisp,
+     * reproducible. "realtime" records the live session; use it only for time-based hero animation or
+     * autoplay video. Default "frames".
+     */
+    capture?: "frames" | "realtime";
+    /** Parallel render workers for "frames" (each its own browser context). Omit to auto-pick by cores. */
+    workers?: number;
+    /** Intermediate frame format for "frames". "jpeg" (default) is faster; "png" is lossless. Default "jpeg". */
+    frameFormat?: "jpeg" | "png";
+    /**
+     * Choreographed scroll: an ordered list of steps instead of one top→bottom sweep ("frames" only).
+     * Omit for the default single eased sweep.
+     */
+    choreography?: ChoreographyStepInput[];
+    /**
+     * Auto-choreograph: detect the page's sections and pan/hold through them ("frames" only). `true`
+     * for defaults, or an object to tune. Ignored if `choreography` is set. Omit to disable.
+     */
+    autoSections?: boolean | AutoSectionsInput;
+    /** Loop style. "boomerang" plays the scroll forward then back for a seamless loop. Default "none". */
+    loop?: "none" | "boomerang";
+    /** Ken Burns slow zoom over the clip ("frames" only). Omit for no zoom. */
+    kenBurns?: KenBurnsInput;
+    /**
+     * Drive a scripted interaction instead of an auto-scroll (move/click/hover/type/scrollTo/wait).
+     * Setting this records in REALTIME and emits a single asset (variants/aspect/extra outputs skipped).
+     */
+    actions?: InteractionActionInput[];
+    /** The synthetic cursor shown during an interaction. Omit for the default cursor. */
+    cursor?: CursorInput;
+    /**
+     * Element-focused clip: scroll one component into view, optionally trigger it, hold, and crop the
+     * output to its box. Realtime; emits a single asset (variants/aspect/outputs/cards skipped).
+     */
+    focus?: FocusInput;
+    /** Force a color scheme. "both" emits a light AND a dark asset (<name>-light / <name>-dark). Omit to leave as-is. */
+    colorScheme?: "light" | "dark" | "both";
+    /** Add this class to <html> before capture (e.g. to trigger a CSS-class dark theme). Omit for none. */
+    themeClass?: string;
+    /** Also capture the reel at these viewports; each emits an asset (<name>-<viewport name>). */
+    viewports?: ViewportInput[];
+    /**
+     * Capture several routes and concatenate them into one reel ("frames" path). Emits a single asset
+     * (variants skipped; aspect/outputs apply to the final tour).
+     */
+    routes?: RouteInput[];
+    /** Hide elements matching these CSS selectors before capture (cookie banners, chat widgets, …). Default none. */
+    hideSelectors?: string[];
+    /** Extra CSS injected before capture (e.g. a brand backdrop, or hiding a sticky header). Omit for none. */
+    injectCss?: string;
+    /** Click these selectors once after load to dismiss overlays (consent dialogs); best-effort. Default none. */
+    clickSelectors?: string[];
+    /** Hide scrollbars so they don't appear in the capture. Default true. */
+    hideScrollbars?: boolean;
+    /** Pause CSS animations/transitions for fully static, deterministic frames. Default false. */
+    pauseAnimations?: boolean;
+    /** Freeze Date.now / performance.now / Math.random (seeded) so time/random content is stable. Default false. */
+    freezeClock?: boolean;
+    /** Abort common analytics/ads/session-replay requests during capture (cleaner, faster). Default true. */
+    blockTrackers?: boolean;
+    /** Extra hostname substrings to block during capture. Default none. */
+    blockHosts?: string[];
+    /** Playwright resource types to block (e.g. "media", "font", "image"). Default none. */
+    blockResourceTypes?: string[];
+    /** Wait for fonts + in-view images before each frame's screenshot ("frames"). Defaults on (off in draft). */
+    settlePerFrame?: boolean;
+    /** Max time (ms) to wait per frame for settling before screenshotting anyway. Default 250. */
+    settleMaxMs?: number;
+    /** Reframe the output to a target aspect: a preset ("16:9"|"9:16"|"1:1") or explicit {width,height}. Omit to keep the capture aspect. */
+    aspect?: AspectInput;
+    /** How to fit the capture into `aspect`: "cover" (scale + center-crop) or "contain" (scale + pad). Default "cover". */
+    fit?: "cover" | "contain";
+    /** Pad color used by "contain". Default "#0b0b0f". */
+    padColor?: string;
+    /** Files to emit per variant; each becomes its own asset. Default ["mp4"]. */
+    outputs?: ("mp4" | "gif" | "webp" | "poster")[];
+    /** GIF / animated-WebP frame rate. Defaults to min(fps, 15). */
+    gifFps?: number;
+    /** Intro card shown before the reel (fades from black). Applies to frames / route tours. Omit for none. */
+    intro?: CardInput;
+    /** Outro / end card shown after the reel. Omit for none. */
+    outro?: CardInput;
+    /** Timed on-screen annotations (caption text, a highlight ring, or a spotlight on a selector). */
+    annotations?: AnnotationInput[];
+    /** Output filename; defaults to "<slug(asset name)>.mp4". */
+    fileName?: string;
+}
+/** Author-facing input (documented for editor hover; the schema validates it at run time). */
+type ScrollReelOptions = ScrollReelOptionsInput;
+
+/** A named viewport to capture at; each breakpoint emits its own asset. */
+interface BreakpointInput {
+    /** Label for this viewport — used in the filename + manifest id (e.g. "desktop"). */
+    name: string;
+    /** Viewport width in CSS px. */
+    width: number;
+    /**
+     * Viewport height in CSS px. Default 900. Ignored for `fullPage` shots (Playwright resizes to the
+     * full page height); only affects viewport/element captures.
+     */
+    height?: number;
+    /** Override the generator-level `deviceScaleFactor` for this breakpoint. Omit to inherit it. */
+    deviceScaleFactor?: number;
+}
+/** A specific element to capture (in addition to the page) at each breakpoint. */
+interface ElementShotInput {
+    /** CSS selector of the element to shoot. */
+    selector: string;
+    /** Name used in the filename + manifest id for this element shot. */
+    name: string;
+}
+/**
+ * Author-facing options for the `screenshots` generator — responsive stills of a page (one per
+ * breakpoint), plus optional per-element crops. Everything is optional; sensible defaults apply.
+ */
+interface ScreenshotsOptionsInput {
+    /**
+     * Viewports to capture at (at least one); each emits its own asset. Default:
+     * desktop 1440×900 + mobile 390×844.
+     */
+    breakpoints?: BreakpointInput[];
+    /** Capture the entire scrollable page (vs. just the viewport). Default true. */
+    fullPage?: boolean;
+    /** Image format. Default "png". */
+    format?: "png" | "jpeg";
+    /** JPEG quality, 1–100 (jpeg only; rejected for png). Omit for the encoder default. */
+    quality?: number;
+    /** Render scale (2 = retina-crisp). Default 2. */
+    deviceScaleFactor?: number;
+    /** Page-load milestone to wait for before capturing. Default "networkidle". */
+    waitUntil?: "load" | "domcontentloaded" | "networkidle" | "commit";
+    /** Optional element to wait for before capturing (e.g. a hero image). Omit to skip. */
+    waitForSelector?: string;
+    /** Specific elements to crop (in addition to the page) at every breakpoint. Default none. */
+    elements?: ElementShotInput[];
+    /** Capture with a transparent background (png only). Default false. */
+    omitBackground?: boolean;
+    /** Extra settle time after load before capturing (ms). Default 0. */
+    settleMs?: number;
+}
+/** Author-facing input (documented for editor hover; the schema validates it at run time). */
+type ScreenshotsOptions = ScreenshotsOptionsInput;
+
+/** The wall's easing curves (kebab-cased, matching the rest of the tool). */
+declare const wallEasingEnum: z.ZodEnum<["linear", "ease-in", "ease-out", "ease-in-out", "ease-in-out-strong"]>;
+/** The wall's easing curves. */
+type WallEasing = z.infer<typeof wallEasingEnum>;
+/** One eased move — the uniform motion primitive (columns, wall default, and pan all use it). */
+interface WallPulseInput {
+    /** When the pulse starts, as a fraction of the clip (0..1). */
+    at: number;
+    /** How long the move takes, as a fraction of the clip (0..1). If `at + duration > 1`, the start
+     *  shifts back so the move ends at the loop point. */
+    duration: number;
+    /** How far it travels, in periods (1 = one full tile-set / one wrap). Usually 0..1. */
+    distance: number;
+    /** Easing of the move's ramp. Default "ease-in-out". */
+    easing?: WallEasing;
+}
+interface WallPanInput {
+    /** Pan direction. Default "left". */
+    direction?: "left" | "right";
+    /** Continuous whole-clip horizontal loops (0 = no pan unless `pulses` move it). Default 0. */
+    loops?: number;
+    /** Pulses added on top of the base loops. Default none. */
+    pulses?: WallPulseInput[];
+}
+/** One column of the wall: its tiles (assets by name) + its own optional Y motion. */
+interface WallColumnInput {
+    /** Assets stacked in this column, by name (cycled to fill the height). At least one. */
+    tiles: string[];
+    /** Constant start-position shift, 0..1 of a tile-set — de-aligns columns with similar content. Default 0. */
+    stagger?: number;
+    /** Scroll direction. Defaults to "down". */
+    direction?: "up" | "down";
+    /** Continuous whole-clip loops for this column. Omit to inherit the wall-level `loops`. */
+    loops?: number;
+    /** This column's pulses. Omit to inherit the wall-level `pulses`. */
+    pulses?: WallPulseInput[];
+}
+/** A faux tile for `test` preview mode — a flat color box labeled with its name. */
+interface FauxTileInput {
+    /** Box fill (any CSS color). Omit to auto-derive a distinct color from the tile name. */
+    color?: string;
+    /** Optional caption shown under the name (e.g. "16:9") — purely cosmetic. */
+    size?: string;
+    /** This faux tile's aspect ratio (width / height): 1.78 = 16:9 (short), 0.56 = 9:16 (tall), 1 =
+     *  square. Omit to use the wall's `tileAspect` default. Real tiles use their media's own aspect. */
+    aspect?: number;
+}
+
+/**
+ * Author-facing options for the `wall` generator. Each entry in `columns` is a self-contained unit
+ * (its `tiles` + its own optional motion); everything else is optional, with defaults noted below.
+ * Motion is the uniform pulse model: `loops` (continuous base) + `pulses` (eased moves), summed and
+ * rounded up to a whole number of periods so the wall always loops seamlessly.
+ */
+interface WallOptionsInput {
+    /** Output width in CSS px. Default 1920. */
+    width?: number;
+    /** Output height in CSS px. Default 1080. */
+    height?: number;
+    /** Render scale (2 = retina-crisp, downscaled into the video). Default 2. */
+    deviceScaleFactor?: number;
+    /** Output frames per second. Default 30. */
+    fps?: number;
+    /** Clip length in seconds — the whole loop. Default 16. */
+    durationSeconds?: number;
+    /** x264 quality, 0–51 (lower = better quality / larger file). Default 18. */
+    crf?: number;
+    /**
+     * Capture strategy. "frames" (default) is deterministic + parallelizable; "realtime" records the
+     * live session. Default "frames".
+     */
+    capture?: "frames" | "realtime";
+    /**
+     * Parallel frame-render workers. Video-heavy walls can cold-start to black tiles under many
+     * workers — set 1 (or omit) for those. Omit to auto-pick from cores.
+     */
+    workers?: number;
+    /** Intermediate frame format (frames capture). "jpeg" (default) is fast; "png" is lossless. */
+    frameFormat?: "jpeg" | "png";
+    /** Backdrop shown in the gutters between tiles. Default "#0b0b0f". */
+    background?: string;
+    /** Output filename; defaults to "<slug(asset name)>.mp4". */
+    fileName?: string;
+    /**
+     * The columns (≥3). Each column lists the assets stacked in it (`tiles`, by name — cycled to fill
+     * the height) and may carry its own motion (`direction` / `loops` / `pulses`); omitted `loops` /
+     * `pulses` inherit the wall-level defaults below. Column count = `columns.length`.
+     */
+    columns: WallColumnInput[];
+    /** Gap between columns and between tiles (px). Default 8. */
+    gap?: number;
+    /** Default/fallback tile aspect (width / height). Tiles fit the column width and take their OWN
+     *  height from their media's aspect (16:9 → short, 9:16 → tall); this is only used for faux
+     *  (`test`) tiles that don't set their own `aspect`. 0.75 = 3:4 portrait. Default 0.75. */
+    tileAspect?: number;
+    /** Tile corner radius (px). Default 6. */
+    cornerRadius?: number;
+    /** The whole wall's horizontal pan (`direction` / `loops` / `pulses`). Default: no pan. */
+    pan?: WallPanInput;
+    /** Default continuous whole-clip loops for columns that omit their own `loops`. Default 0 (static
+     *  unless a pulse moves it — a single pulse then rounds up to one loop). */
+    loops?: number;
+    /** Default pulses for columns that omit their own `pulses` (the uniform wall-level motion). Default none. */
+    pulses?: WallPulseInput[];
+    /**
+     * Preview mode: render every tile as a flat labeled color box instead of the real assets. No
+     * producer assets run, so the wall renders in seconds — flip it on to dial in layout + motion,
+     * then off for the real render. Default false.
+     */
+    test?: boolean;
+    /** Per-tile faux appearance for `test` mode, keyed by tile name (color + caption). Default {} (auto colors + names). */
+    testTiles?: Record<string, FauxTileInput>;
+}
+/** Author-facing input (documented for editor hover; the schema validates it at run time). */
+type WallOptions = WallOptionsInput;
+
+/** One "pulse" (beat) of the animation storyboard. */
+interface PulseInput {
+    /** Human label for the beat, e.g. "color sweep" — purely to keep the config readable. */
+    name?: string;
+    /** Length of this beat, in seconds. */
+    duration: number;
+    /** Fraction of cells whose glyph changes during this beat (0..1; 1 = every cell once; 0 = a hold). */
+    chars?: number;
+    /** Fraction of cells whose color changes during this beat (0..1; 1 = every cell once). */
+    colors?: number;
+    /**
+     * Target color for this beat's color changes. When set, every color change goes to this exact
+     * token (a deliberate sweep) rather than a weighted-random pick. Set `colors: 1` with
+     * `pacing: "even"` to evenly wash the whole specimen to one color. Omit for the default
+     * scattered, weighted-random recoloring.
+     */
+    color?: "foreground" | "muted" | "accent";
+    /**
+     * How the changes are distributed in time across the beat — like a CSS easing curve:
+     * "linear"/"even" = uniform, "ease-in" = front-loaded, "ease-out" = back-loaded,
+     * "ease-in-out" = bunched at both ends, "random" = scattered.
+     */
+    pacing?: "even" | "linear" | "ease-in" | "ease-out" | "ease-in-out" | "random";
+}
+/**
+ * Relative likelihood each color token is chosen on a (non-targeted) color change. Higher = more
+ * frequent. The default keeps foreground/muted common and accent a rare pop (2 / 2 / 1). Set any to
+ * 0 to exclude that token from random recoloring (an explicit pulse `color` can still target it).
+ */
+interface SpecimenColorWeightsInput {
+    foreground?: number;
+    muted?: number;
+    accent?: number;
+}
+/** The specimen's color palette (any CSS colors). Override any subset. */
+interface SpecimenColorsInput {
+    /** Backdrop behind the glyphs. */
+    background?: string;
+    /** Primary glyph color — the resting majority. */
+    foreground?: string;
+    /** Muted/secondary glyph color. */
+    muted?: string;
+    /** Accent color for occasional pops; defaults to `background` (accent glyphs blend in) if unset. */
+    accent?: string;
+    /** Color of the font-name label (bottom corner); defaults to `foreground` if unset. */
+    label?: string;
+}
+/** A named option preset. The keys here are the selectable `template` values. */
+type SpecimenTemplate = "demo" | "sweep";
+/**
+ * Author-facing options for the `specimen` generator — a looping type-specimen video. Only `font`
+ * is required; everything else has a sensible default.
+ */
+interface SpecimenOptionsInput {
+    /** Font file to showcase (path relative to the working dir, or absolute). Required. */
+    font: string;
+    /**
+     * Load a named option preset; your explicit options below still override what it sets. Options:
+     * - `"demo"` — labeled walkthrough of every pulse behavior (each easing curve, a color sweep, a
+     *   mingle) with demo mode on; runs once, no mirror. Good for seeing what each setting does.
+     * - `"sweep"` — seamless-looping showcase of the even per-character color sweeps (muted → accent
+     *   → foreground) on a dark palette chosen so the accent reads.
+     */
+    template?: SpecimenTemplate;
+    /** Display name shown bottom-left (e.g. "ABC Oracle"). Default none. */
+    name?: string;
+    /** Demo mode: overlay the active pulse's name bottom-right, to see which beat is playing. Default false. */
+    demo?: boolean;
+    /** Output frames per second. Default 30. */
+    fps?: number;
+    /** Clip length in seconds. Defaults to the (mirrored) sum of the pulse durations; set to override. */
+    durationSeconds?: number;
+    /** Output frame width in px. Default 1920. */
+    width?: number;
+    /** Output frame height in px. Default 1080. */
+    height?: number;
+    /** Render scale (1 = 1:1; higher = crisper capture, downscaled into the video). Default 1. */
+    deviceScaleFactor?: number;
+    /** Glyph weight on the variable-font axis, 1–1000. Default 820. */
+    weight?: number;
+    /** Number of glyph rows. The glyph size is derived so the rows fill the top 80% of the frame. Default 3. */
+    lines?: number;
+    /** Line-height of the glyph block. Default 0.78 (tight, cap-height-hugging). */
+    leading?: number;
+    /** Glyphs to exclude from the showcase, e.g. "QXZ" (case-insensitive). Default none. */
+    blacklist?: string;
+    /** Override the glyph pool the specimen draws from (≥2 distinct characters). Default A–Z 0–9 + symbols. */
+    characterPool?: string;
+    /** Schedule seed — same seed ⇒ identical animation. Change for a different (still deterministic) take. Default 1. */
+    seed?: number;
+    /** Color tokens the glyphs cycle through. Override any subset. Default: light-grey palette. */
+    colors?: SpecimenColorsInput;
+    /** Relative likelihood of each color token on a random (non-targeted) color change. Default 2 / 2 / 1. */
+    colorWeights?: SpecimenColorWeightsInput;
+    /** The animation storyboard: an ordered sequence of pulses (beats). Default: a lively built-in storyboard. */
+    pulses?: PulseInput[];
+    /** Multiply every pulse's glyph-change fraction (1 = baseline, 2 = twice as busy, 0 = none). Default 1. */
+    characterIntensity?: number;
+    /** Multiply every pulse's color-change fraction (1 = baseline, 2 = twice as busy, 0 = none). Default 1. */
+    colorIntensity?: number;
+    /**
+     * Max fraction a line's total width may drift as its glyphs change. Default 0.05. Glyph swaps are
+     * width-compensated to stay within this, so the left-aligned right edge barely moves.
+     */
+    maxLineDrift?: number;
+    /**
+     * Mirror the pulses (play them out and back) so the clip ends on its opening frame and loops
+     * seamlessly. Doubles the clip length. Set false for a one-shot that ends on the last state. Default true.
+     */
+    mirror?: boolean;
+    /** x264 quality, 0–51 (lower = better quality / larger file). Default 18. */
+    crf?: number;
+    /** Output filename; defaults to "<slug(asset name)>.mp4". */
+    fileName?: string;
+}
+/** Author-facing input (documented for editor hover; the schema above validates it at run time). */
+type SpecimenOptions = SpecimenOptionsInput;
+
+/** A field that can be shown on a swatch. */
+type FieldId = "name" | "hex" | "rgb" | "oklch" | "hsl" | "cmyk";
+
+/** One color in the palette. */
+interface PaletteColorInput {
+    /** Display name, e.g. "Wet Grey". */
+    name: string;
+    /** Hex value (#rgb or #rrggbb, with or without #). */
+    hex: string;
+}
+/**
+ * Author-facing options for the `palette` generator — a still color-palette image. Each color is a
+ * swatch labeled with the fields you place in its corners (name / hex / rgb / oklch / hsl / cmyk),
+ * with auto-contrasting text. Only `colors` is required.
+ */
+interface PaletteOptionsInput {
+    /** The colors to show (at least one). */
+    colors: PaletteColorInput[];
+    /** Swatch arrangement: full-width bands, full-height columns, or an N-wide grid. Default "rows". */
+    layout?: "rows" | "columns" | "grid";
+    /** Columns when `layout: "grid"`. Default 3. */
+    gridColumns?: number;
+    /** Output width in px. Default 1400. */
+    width?: number;
+    /** Output height in px. Default 1750 (portrait 4:5 with the default width). */
+    height?: number;
+    /** Render scale (2 = retina-crisp). Default 2. */
+    deviceScaleFactor?: number;
+    /** Page background, shown only in the gaps between swatches. Default "#ffffff". */
+    background?: string;
+    /** Gap between swatches (px). Default 0 (swatches abut). */
+    gap?: number;
+    /** Swatch corner radius (px). Default 0 (square). */
+    cornerRadius?: number;
+    /** Fields stacked in the top-left corner. Default name + hex. */
+    topLeft?: FieldId[];
+    /** Fields stacked in the top-right corner. Default rgb + oklch. */
+    topRight?: FieldId[];
+    /** Fields stacked in the bottom-left corner. Default none. */
+    bottomLeft?: FieldId[];
+    /** Fields stacked in the bottom-right corner. Default none. */
+    bottomRight?: FieldId[];
+    /** Uppercase the color names. Default false. */
+    uppercase?: boolean;
+    /** RGB string style. Default "labeled". */
+    rgbStyle?: "labeled" | "css" | "plain";
+    /** OKLCH string style. Default "css". */
+    oklchStyle?: "css" | "labeled";
+    /** Custom font file (woff2/woff/ttf/otf), embedded into the render. Omit for a system bold sans. */
+    fontFile?: string;
+    /** Label font size in px. Omit to derive from the width. */
+    fontSize?: number;
+    /** Label font weight. Default 700. */
+    fontWeight?: number;
+    /** Light text color, used on dark swatches (picked by contrast). Default "#ffffff". */
+    textLight?: string;
+    /** Dark text color, used on light swatches (picked by contrast). Default "#141414". */
+    textDark?: string;
+    /** Luminance above which the dark text is used (0..1). Default 0.5. */
+    contrastThreshold?: number;
+    /** Inset of the labels from the swatch edges (px). Omit to derive from the width. */
+    padding?: number;
+    /** Output filename; defaults to "<slug(asset name)>.png". */
+    fileName?: string;
+}
+/** Author-facing input (documented for editor hover; the schema validates it at run time). */
+type PaletteOptions = PaletteOptionsInput;
+
+/**
+ * Author-facing options for the `palette-reel` generator — a looping reveal *video* of a color
+ * palette (the moving counterpart of the still `palette` generator). The colors start as thin
+ * slivers showing only their name; one at a time a sliver expands into a band that reveals its
+ * configured `details` (hex / oklch / rgb …), holds, then collapses before the next opens — sweeping
+ * every color and looping seamlessly. Only `colors` is required; everything else has a default.
+ */
+interface PaletteReelOptionsInput {
+    /** The colors to reveal (at least one). */
+    colors: PaletteColorInput[];
+    /** Sliver arrangement: horizontal bands (names upright) or full-height vertical strips. Default "rows". */
+    orientation?: "rows" | "columns";
+    /** Fields revealed when a color expands (the name is always shown, so it's ignored here). Default hex + oklch + rgb. */
+    details?: FieldId[];
+    /** How long each color stays fully open before handing off to the next. Default 2. */
+    holdSeconds?: number;
+    /** Crossfade length from one open color to the next. Default 0.7. */
+    transitionSeconds?: number;
+    /**
+     * Ping-pong the sweep (down the list then back up) so every handoff is between neighbouring bands —
+     * the open band only ever slides by one, avoiding the "pinch" of a last→first jump at the loop seam.
+     * Off wraps directly (last→first): shorter, but crossfades non-adjacent bands at the seam. Default true.
+     */
+    bounce?: boolean;
+    /** Easing applied to the crossfade ramp. Default "ease-in-out". */
+    easing?: "linear" | "ease-in" | "ease-out" | "ease-in-out";
+    /** Clip length override (s). Omit to derive (count × (hold + transition)) for a clean loop. */
+    durationSeconds?: number;
+    /** How many times a sliver's share a fully-open band takes (a collapsed sliver is the baseline). Default 12. */
+    grownFlex?: number;
+    /** Minimum cross-size of a sliver in px so its name stays legible. Default 0 (derive from height). */
+    minCrossPx?: number;
+    /** Keep the name fully visible even in a collapsed sliver (else it fades with the band). Default true. */
+    nameAlwaysVisible?: boolean;
+    /** Uppercase the color names. Default false. */
+    uppercase?: boolean;
+    /** RGB string style. Default "labeled". */
+    rgbStyle?: "labeled" | "css" | "plain";
+    /** OKLCH string style. Default "css". */
+    oklchStyle?: "css" | "labeled";
+    /** Light text color, used on dark bands (picked by contrast). Default "#ffffff". */
+    textLight?: string;
+    /** Dark text color, used on light bands (picked by contrast). Default "#141414". */
+    textDark?: string;
+    /** Luminance above which the dark text is used (0..1). Default 0.5. */
+    contrastThreshold?: number;
+    /** Custom font file (woff2/woff/ttf/otf), served into the render. Omit for a system bold sans. */
+    fontFile?: string;
+    /** Label font weight. Default 700. */
+    fontWeight?: number;
+    /** Name font size in px. Omit to derive from the frame size. */
+    fontSize?: number;
+    /** Detail-line font size as a fraction of the name size. Default 0.62. */
+    detailFontScale?: number;
+    /** Backdrop behind the bands (shown in `gap` between them). Default "#ffffff". */
+    background?: string;
+    /** Gap between bands (px). Default 0 (bands abut). */
+    gap?: number;
+    /** Band corner radius (px). Default 0 (square). */
+    cornerRadius?: number;
+    /** Output frame width in px. Default 1920. */
+    width?: number;
+    /** Output frame height in px. Default 1080. */
+    height?: number;
+    /** Render scale (higher = crisper capture, downscaled into the video). Default 1. */
+    deviceScaleFactor?: number;
+    /** Output frames per second. Default 30. */
+    fps?: number;
+    /** x264 quality, 0–51 (lower = better quality / larger file). Default 18. */
+    crf?: number;
+    /** Output filename; defaults to "<slug(asset name)>.mp4". */
+    fileName?: string;
+}
+/** Author-facing input (documented for editor hover; the schema validates it at run time). */
+type PaletteReelOptions = PaletteReelOptionsInput;
+
+/**
+ * Author-facing options for the `image` generator — a passthrough that records an existing image
+ * file as an asset so it can feed a scene (e.g. high-resolution photos as media-wall tiles) or be
+ * tracked in the manifest. Only `src` is required.
+ */
+interface ImageOptions {
+    /** Path to the source image (relative to the cwd, or absolute). */
+    src: string;
+    /** Output filename; defaults to "<slug(asset name)><ext of src>". */
+    fileName?: string;
+}
+
+/**
+ * Author-facing config types. These power editor autocomplete in `pro-visu.config.ts`.
+ * The runtime validator lives in `schema.ts`; each generator validates its own options.
+ * When a new generator is added, extend `AssetSpecInput` and `defaults` here.
+ */
+type LogLevel = "silent" | "error" | "warn" | "info" | "debug";
+interface BrowserSettingsInput {
+    /** Run the browser without a visible window (default true). Set false to watch captures. */
+    headless?: boolean;
+    /** Browser channel, e.g. "chrome" or "msedge". Omit to use the managed Chromium. */
+    channel?: string;
+    /** Absolute path to a browser executable (overrides `channel` + managed Chromium). */
+    executablePath?: string;
+    /** Extra launch args, e.g. ["--no-sandbox"] on CI. */
+    args?: string[];
+    /** Browser launch timeout (ms). */
+    timeout?: number;
+}
+interface ServerSettingsInput {
+    /**
+     * Command that starts the server, run via the shell. The tool sets PORT/HOST in its environment
+     * to the readiness port/host, so frameworks that honor PORT (Next, Vite, …) bind it
+     * automatically — `command: "next start"` is enough. An explicit flag still wins.
+     */
+    command: string;
+    /** Optional one-shot build to run first, e.g. "next build". */
+    build?: string;
+    /** Health-check URL polled until it responds. Defaults to http://127.0.0.1:<port>. */
+    url?: string;
+    /**
+     * Port the readiness check polls — also derives `url` when `url` is omitted, and is passed to
+     * the command as PORT so it binds the same port automatically. Defaults to 3101.
+     */
+    port?: number;
+    /** Working dir for build + command, relative to the config dir. Defaults to it. */
+    cwd?: string;
+    /** Max time to wait for the server to become reachable (ms). Default 120000. */
+    readyTimeoutMs?: number;
+    /** If a server is already reachable at the URL, use it as-is (don't start/stop one). */
+    reuseExisting?: boolean;
+}
+interface ShowcaseSettingsInput {
+    /** Output directory for generated assets, relative to the repo root (default "pro-visu"). */
+    outDir?: string;
+    /** How many assets to generate in parallel (shared browser, separate contexts). */
+    concurrency?: number;
+    /**
+     * Raise the Node heap (V8 old-space) to this many MB. Heavy jobs — large frame-stepped walls
+     * especially — can exceed Node's ~4 GB default and crash with "JavaScript heap out of memory".
+     * When set above the current limit, the CLI re-execs itself with `--max-old-space-size`. This is
+     * the Node process heap, not the browser's.
+     */
+    maxMemoryMB?: number;
+    /** CLI log verbosity. */
+    logLevel?: LogLevel;
+    /** Playwright launch controls. */
+    browser?: BrowserSettingsInput;
+    /** Build → start → wait → capture → stop a server automatically. */
+    server?: ServerSettingsInput;
+    /** "draft" lowers fps/scale and speeds the encoder for fast iteration. */
+    quality?: "draft" | "final";
+    /** Skip assets whose inputs+options+tool fingerprint is unchanged (opt-in). */
+    cache?: boolean;
+    /** Per-generator option defaults, keyed by generator id, merged under each asset. */
+    defaults?: {
+        "scroll-reel"?: ScrollReelOptions;
+        screenshots?: ScreenshotsOptions;
+        specimen?: SpecimenOptions;
+        palette?: PaletteOptions;
+        "palette-reel"?: PaletteReelOptions;
+    };
+}
+/** Fields common to every asset. */
+interface AssetBaseInput {
+    /** Unique id for this asset — also the output filename (`<slug(name)>.mp4`) and manifest key. */
+    name: string;
+    /** Other assets this one consumes, as `{ slotName: assetName }`. Producers run first. */
+    inputs?: Record<string, string>;
+}
+/**
+ * Discriminated by `generator` so each asset gets the right `options` autocomplete. URL-based
+ * generators take a `url` — absolute, or a `/path` resolved against the managed server; omit it
+ * to capture the managed server's root. A local `scene` composites its `inputs` and needs none.
+ */
+type AssetSpecInput = (AssetBaseInput & {
+    url?: string;
+    generator: "scroll-reel";
+    options?: ScrollReelOptions;
+}) | (AssetBaseInput & {
+    url?: string;
+    generator: "screenshots";
+    options?: ScreenshotsOptions;
+}) | (AssetBaseInput & {
+    generator: "wall";
+    options?: WallOptions;
+}) | (AssetBaseInput & {
+    generator: "specimen";
+    options: SpecimenOptions;
+}) | (AssetBaseInput & {
+    generator: "palette";
+    options: PaletteOptions;
+}) | (AssetBaseInput & {
+    generator: "palette-reel";
+    options: PaletteReelOptions;
+}) | (AssetBaseInput & {
+    generator: "image";
+    options: ImageOptions;
+});
+interface ShowcaseUserConfig {
+    settings?: ShowcaseSettingsInput;
+    assets: AssetSpecInput[];
+}
+/** Identity helper that gives `pro-visu.config.ts` full type-checking + autocomplete. */
+declare function defineConfig(config: ShowcaseUserConfig): ShowcaseUserConfig;
+
+export { type AssetSpecInput, type BrowserSettingsInput, type LogLevel, type ScreenshotsOptions, type ScrollReelOptions, type ServerSettingsInput, type ShowcaseSettingsInput, type ShowcaseUserConfig, type SpecimenOptions, type WallOptions, defineConfig };