@nodaro/prompts 1.47.0 → 1.48.0

package/dist/transitions-BgwWM37i.d.ts

@@ -1,450 +0,0 @@
-import { P as PickerHintMode } from './term-C01_g6s1.js';
-
-/**
- * Canonical catalog of cinematic transitions for AI-video generation.
- *
- * Shared between frontend (picker UI, prompt hint injection) and backend
- * (orchestrator payload builder). The `promptHint` is a natural-language
- * cue that gets composed into the user prompt when a transition node is
- * connected to a video consumer.
- *
- * Multi-pick supported: value field accepts `string | string[]` (cap 2).
- * Graph-aware: `startState` / `endState` input handles accept upstream
- * parameter nodes whose hints are folded into the composed clause as
- * "starting from <X>, ending at <Y>".
- */
-
-type TransitionCategory = "standard" | "time" | "element" | "morph" | "portal" | "physics" | "light" | "glitch";
-interface Transition {
-    readonly id: string;
-    readonly label: string;
-    readonly category: TransitionCategory;
-    readonly description: string;
-    readonly promptHint: string;
-    /**
-     * Optional authored compact term (see `term.ts`). Authored where the
-     * lowercased label is not what an editor would write in a prompt — a UI
-     * compound ("None / Hard Cut" → "hard cut"), an annotation the derivation
-     * drops ("Fast-Forward (Day → Night)" → "day-to-night time-lapse"), a bare
-     * word that collides with another meaning ("Melt Down", "Channel Flip",
-     * "Roll"), or a coinage that is not the trade term ("Seamless Match" →
-     * "invisible cut"). Everywhere else the label IS the term.
-     */
-    readonly term?: string;
-    /**
-     * `true` on rows whose mechanism IS A CUT — the change happens between two
-     * frames, so it has no duration to time. A duration clause ("lasting
-     * approximately 1 second") on such a row tells the video model to spend a
-     * second on the change, and it obliges with a dissolve: a match cut rendered
-     * as a 1.75 s cross-dissolve in QA. The composer therefore skips the duration
-     * clause when every picked transition is instant (on a BLENDABLE cut, a
-     * `blendsCut` step changes the cut itself instead — see `blendable`), and
-     * consumers offer only the levers a cut takes — Position without `full`, no
-     * Intensity, and Duration only on a blendable cut, as a Blend lever of "hard
-     * cut" plus the `blendsCut` steps — reading `isInstantTransition` /
-     * `isBlendableTransition` (the canvas panel) or the picker catalog's
-     * `instant` / `blendable` / `blendsCut` flags (an id-only client).
-     *
-     * The same holds for INTENSITY: every intensity clause describes how the
-     * change PERFORMS over time ("natural unhurried timing", "wild flourishes and
-     * dramatic distortion"), and a cut has no performance to shape — "unhurried"
-     * on a match cut is another invitation to blend. So the composer drops the
-     * intensity clause too when every pick is instant. Position still applies —
-     * WHERE the cut lands is a real choice — except `full`: a single-frame cut
-     * cannot "span the entire clip", so that clause is dropped on an all-instant
-     * pick (start / middle / end still place the cut).
-     *
-     * The bare term is not enough on its own either: "match cut" still came back
-     * as a ~1 s superimposition in prod QA (seedance-2-5). The composer therefore
-     * puts `INSTANT_CUT_CLAUSE` inside an all-instant pick's parentheses, once — the explicit
-     * anti-blend instruction that made the model render a true single-frame cut.
-     */
-    readonly instant?: boolean;
-    /**
-     * `true` on a CUT that may become a BLENDED CUT: picked with a duration step
-     * that `blendsCut` (Short), the pick's anti-blend `INSTANT_CUT_CLAUSE` is
-     * REPLACED by `blendedCutClause` — the two shots blend into each other over
-     * that step's own `term` — and every other rule of a cut stands (position
-     * without `full`, no duration clause, no intensity clause). Any other
-     * duration leaves it a hard cut. See `isBlendableTransition`.
-     *
-     * Set on `seamless-match` and `jump-match` only. In the blended-cut test
-     * round (2026-10-04) their blended takes at Short kept what makes each row
-     * itself — the invisible cut still hid its join, the jump match still held
-     * the subject's place across the leap — and were approved. The blended takes
-     * of `match-cut`, `jump-cut` and `action-relay` lost their trait and rated
-     * below their hard cut, so those rows stay hard cuts at every duration, as
-     * do `none`, `snap-to-black` and `smash-cut`, whose descriptions a blend
-     * would contradict ("instantaneous", "on a single frame", "no fade").
-     */
-    readonly blendable?: boolean;
-    /**
-     * PER-ROW OPTIONS — extra choices that only mean something for THIS
-     * transition (a wipe's direction), each written into the row's own hint.
-     *
-     * Unlike the timing scales (every row has a position), an option is declared
-     * by the row that reads it, so it never appears beside a transition it would
-     * not change. The row authors `promptTemplate` — its hint with one
-     * `{<field>}` token per option — and `promptHint` is DERIVED from it with
-     * every option on its `auto` choice (see `withOptionSlots`), so a reader of
-     * the plain `promptHint` (the picker catalog, the analyzer, a catalog pack)
-     * always sees a finished sentence and never a token.
-     *
-     * The choice's `phrase` is what fills the token, so the row BODY and the
-     * option WORDING are separate: a reworded body keeps its options as long as
-     * it keeps the token. `transition-options.test.ts` pins that every template
-     * carries exactly one token per option and no other.
-     */
-    readonly options?: ReadonlyArray<TransitionOption>;
-    /** The hint with a `{<field>}` token per `options` entry — see `options`. */
-    readonly promptTemplate?: string;
-}
-/**
- * One choice of a per-row option. `auto` leads every option and is the choice
- * `promptHint` is written with: picking it (or picking nothing) sends no value.
- */
-interface TransitionOptionChoice {
-    readonly id: string;
-    readonly label: string;
-    readonly description: string;
-    /** The words that fill the row template's `{<field>}` token. */
-    readonly phrase: string;
-    /** The compact term for the choice ("left to right"); `""` on `auto`. */
-    readonly term: string;
-}
-/** A per-row option (see `Transition.options`). */
-interface TransitionOption {
-    /** The node-data field the chosen id is stored under — also the template
-     *  token's name (`{wipeDirection}`). Unique within a row; SHARED across rows
-     *  only where the rows mean the same kind of setting (`style`, see
-     *  `TRANSITION_STYLE_FIELD`) — each row still declares its own choices, and
-     *  a value is read only by the row that declares it. */
-    readonly field: string;
-    readonly label: string;
-    /** `auto` first. */
-    readonly choices: ReadonlyArray<TransitionOptionChoice>;
-}
-/**
- * The chosen option ids, keyed by `TransitionOption.field`
- * (`{ wipeDirection: "left-to-right" }`). One flat record for a whole pick: a
- * row reads only the fields it declares, so the other row of a two-pick, or a
- * value left behind by an earlier pick, changes nothing.
- */
-type TransitionOptionValues = Readonly<Record<string, string | undefined>>;
-/**
- * The wipe's direction. The phrase is the edge AND its travel, so the row's
- * body is free to change around it (`a clean {wipeDirection}, revealing …`).
- * `auto` names no orientation at all — a straight edge — and is what a pick
- * with no direction has always meant.
- */
-declare const WIPE_DIRECTION: TransitionOption;
-/** The shared node-data field every styled row stores its look under. */
-declare const TRANSITION_STYLE_FIELD = "style";
-declare const DEBRIS_SHOWER_STYLE: TransitionOption;
-declare const GARDEN_BLOOM_STYLE: TransitionOption;
-declare const SMOKE_PUFF_STYLE: TransitionOption;
-declare const SAKURA_PETALS_STYLE: TransitionOption;
-declare const AURORA_SWEEP_STYLE: TransitionOption;
-declare const SAND_STORM_STYLE: TransitionOption;
-declare const WHITE_FLASH_STYLE: TransitionOption;
-/**
- * The three timing scales, each derived from the catalog that defines it (see
- * `TRANSITION_POSITIONS` and friends below).
- *
- * The direction matters. These used to be hand-written unions with the clause
- * tables written out separately beside them, so the two could disagree: add a
- * step to the union, forget the clause, and the composer indexed a missing key
- * — pushing `undefined` into the parts list, which `join(", ")` renders as a
- * dangling separator on a prompt that then ships to a provider with the user's
- * chosen parameter silently dropped. Deriving the union FROM the catalog makes
- * that unrepresentable: one array is the source of the type, the option list
- * the API serves, and the clause table, so a new step reaches all three or
- * none. The exact id sets are pinned by `transition-timing-catalogs.test.ts`.
- */
-type TransitionPosition = (typeof TRANSITION_POSITIONS)[number]["id"];
-type TransitionDuration = (typeof TRANSITION_DURATIONS)[number]["id"];
-type TransitionIntensity = (typeof TRANSITION_INTENSITIES)[number]["id"];
-interface TransitionTiming {
-    position?: TransitionPosition;
-    duration?: TransitionDuration;
-    intensity?: TransitionIntensity;
-}
-declare const TRANSITIONS: ReadonlyArray<Transition>;
-declare const TRANSITION_CATEGORY_ORDER: ReadonlyArray<TransitionCategory>;
-declare const TRANSITION_CATEGORY_LABELS: Readonly<Record<TransitionCategory, string>>;
-declare function getTransition(id: string | undefined | null): Transition | undefined;
-declare function getTransitionLabel(id: string | undefined | null, fallback?: string): string;
-/**
- * The row's hint. With `values`, a row that declares `options` is written with
- * the chosen choices in its template (an absent or unknown choice reads as
- * `auto`, which IS `promptHint`); every other row ignores them.
- *
- * A catalog pack that REWROTE the row's hint owns its words: its text has no
- * token to fill, so it is returned as written and the options add nothing.
- */
-declare function getTransitionPromptHint(id: string | undefined | null, values?: TransitionOptionValues): string;
-/** The per-row options a transition declares (`[]` for most rows, an unknown
- *  id and `auto`). Reads through `getTransition`, like every other getter. */
-declare function getTransitionOptions(id: string | undefined | null): ReadonlyArray<TransitionOption>;
-/** Every option field any row declares, in catalog order — what a node-data
- *  reader collects into `TransitionOptionValues`. */
-declare const TRANSITION_OPTION_FIELDS: ReadonlyArray<string>;
-/**
- * Collect `TransitionOptionValues` from a node-data-shaped record: every
- * declared option field whose value is a non-empty string. Validation against
- * a row's choices happens at render (an unknown id reads as `auto`).
- */
-declare function readTransitionOptionValues(data: Readonly<Record<string, unknown>> | undefined | null): TransitionOptionValues | undefined;
-/**
- * Compact professional TERM for an id — the short phrase an editor would write
- * in a prompt ("hard cut", "invisible cut", "day-to-night time-lapse"), as
- * opposed to the paragraph-length `promptHint`.
- *
- * Same lookup and same empty-string-on-miss behavior as
- * `getTransitionPromptHint`, so the two can never disagree about which entry
- * they describe. The no-op "Auto" entry resolves to `""` in both.
- */
-declare function getTransitionTerm(id: string | undefined | null): string;
-declare const TRANSITION_IDS: ReadonlyArray<string>;
-/**
- * Whether a transition is a CUT — instantaneous by nature, so it takes no
- * duration (see `Transition.instant`). Reads through `getTransition`, so it
- * answers for the same entry every other getter describes; an unknown id, the
- * no-op "auto" and an empty value are all `false`.
- *
- * A multi-pick (`string[]`) is instant only when EVERY picked id is: a cut
- * paired with a dissolve still has a dissolve to time.
- */
-declare function isInstantTransition(id: string | ReadonlyArray<string> | undefined | null): boolean;
-/**
- * Whether a pick may become a BLENDED CUT (see `Transition.blendable`): every
- * picked id is a blendable cut. Same lookup and same empty-pick answer as
- * `isInstantTransition`, so a pick is blendable only where it is instant. Like
- * that check, it reads the ids it is given: the composer passes only the ids
- * that contribute a fragment, so a no-op "auto" beside a blendable cut does not
- * stop the blend there (`["auto", "seamless-match"]` given whole is `false`).
- */
-declare function isBlendableTransition(id: string | ReadonlyArray<string> | undefined | null): boolean;
-/**
- * The anti-blend instruction an all-instant transition pick carries — the ONE
- * place this sentence lives (see `Transition.instant`). Each row keeps its own
- * meaning in its own hint (a match cut still matches shapes, snap to black
- * still holds black for a beat); this clause only forbids the blend a video
- * model otherwise puts between the two images. Measured on prod with
- * seedance-2-5: with it, a match cut renders as a true single-frame hard cut,
- * with and without an end frame; without it, as a ~1 s dissolve.
- */
-declare const INSTANT_CUT_CLAUSE = "an abrupt single-frame hard cut, no dissolve, crossfade or superimposition; the two images never blend";
-/**
- * The transition BASE fragments for a pick — one `<term> (<hint body>)` per id
- * that resolves to a term, in pick order. When EVERY contributing id is
- * instant, the FIRST fragment's parentheses also carry `; INSTANT_CUT_CLAUSE`
- * (once per pick — two cuts picked together are still one cut). FIRST, not
- * last: the direction fold sheds fragments from the TAIL under a provider cap,
- * so the clause rides the fragment that survives longest. A mixed pick carries
- * no clause: its non-cut is meant to blend.
- *
- * The same text in both hint modes. A transition only ever reaches a VIDEO
- * prompt (the registry row is `surface: "video"`; the canvas node is in
- * `VIDEO_ONLY_PARAMETER_NODE_TYPES`), and there the bare compact term was not
- * enough to steer the model, so the mode no longer changes a transition.
- *
- * Each fragment is ONE string, parentheses included: the cap-aware assemblers
- * shed whole fragments from the tail, so a fragment is kept or dropped whole
- * and can never lose its hint or its clause on its own.
- *
- * Shared by `composeTransitionHintFromConnections` (the canvas transition node,
- * Studio's transition clauses) and the direction registry's `transition` row
- * (the server fold of `direction.transition`), so both paths word a transition
- * identically.
- *
- * `values` are the per-row option choices (`TransitionOptionValues`) — a wipe's
- * direction. The direction registry passes none, so a `direction.transition`
- * wipe reads as `auto`.
- *
- * These bases are always the HARD cut's: a pick here has no duration, so it
- * never becomes a blended cut. The blend exists only where a duration is
- * picked, in `composeTransitionHintFromConnections`.
- */
-declare function renderTransitionBases(ids: ReadonlyArray<string>, _mode?: PickerHintMode, values?: TransitionOptionValues): string[];
-/**
- * THE BLENDED CUT — what a blendable cut becomes when a duration that
- * `blendsCut` (Short) is picked on it: instead of the anti-blend
- * `INSTANT_CUT_CLAUSE`, the two shots blend into each other over that step's
- * own `term` ("about 1 second"), so the time words are the catalog's and never
- * typed here. "" for every other value (auto, instant, medium, long, an unknown
- * id, none), which leaves the cut a hard cut.
- */
-declare function blendedCutClause(duration: string | undefined): string;
-/**
- * The transition node's three timing parameters, as catalogs.
- *
- * These are graded scales, not free numbers — the same shape as
- * `exposure-settings`' aperture or `temporal`'s speed — so a consumer that can
- * only send ids (Studio, the SDK, MCP) can offer them without composing prompt
- * text of its own. `auto` is the no-op head of each scale: an empty
- * `promptHint`, so an unset parameter contributes nothing and the model is left
- * to decide, exactly as before these were enumerable.
- *
- * `POSITION_CLAUSES` / `DURATION_CLAUSES` / `INTENSITY_CLAUSES` below are
- * DERIVED from these arrays, so the clause the composer injects and the hint
- * the catalog advertises are the same string by construction and cannot drift.
- */
-interface TransitionTimingOption {
-    readonly id: string;
-    readonly label: string;
-    readonly description: string;
-    readonly promptHint: string;
-    readonly term?: string;
-    /** Duration rows only: `true` on a step a blendable CUT may take — picked on
-     *  such a pick it turns the cut into a BLENDED CUT over this row's `term`
-     *  (see `blendedCutClause`). Absent = a cut ignores the step and stays a
-     *  hard cut. Set on `short` only: the 2026-10-04 test round approved the
-     *  blend at about 1 second, not at Medium's 2. */
-    readonly blendsCut?: boolean;
-}
-declare const TRANSITION_POSITIONS: readonly [{
-    readonly id: "auto";
-    readonly label: "Auto";
-    readonly description: "Let the model place it";
-    readonly promptHint: "";
-    readonly term: "";
-}, {
-    readonly id: "start";
-    readonly label: "Start";
-    readonly description: "At the opening of the clip";
-    readonly promptHint: "the transition occurs at the opening of the clip";
-    readonly term: "at the opening of the clip";
-}, {
-    readonly id: "middle";
-    readonly label: "Middle";
-    readonly description: "In the middle of the clip";
-    readonly promptHint: "the transition occurs in the middle of the clip";
-    readonly term: "mid-clip";
-}, {
-    readonly id: "end";
-    readonly label: "End";
-    readonly description: "At the end of the clip";
-    readonly promptHint: "the transition occurs at the end of the clip";
-    readonly term: "at the end of the clip";
-}, {
-    readonly id: "full";
-    readonly label: "Full";
-    readonly description: "Spans the entire clip";
-    readonly promptHint: "the transition spans the entire clip";
-    readonly term: "across the whole clip";
-}];
-declare const TRANSITION_DURATIONS: readonly [{
-    readonly id: "auto";
-    readonly label: "Auto";
-    readonly description: "Let the model time it";
-    readonly promptHint: "";
-    readonly term: "";
-}, {
-    readonly id: "instant";
-    readonly label: "Instant";
-    readonly description: "No perceptible duration";
-    readonly promptHint: "occurring instantaneously";
-    readonly term: "instantaneous";
-}, {
-    readonly id: "short";
-    readonly label: "Short (~1s)";
-    readonly description: "Approximately 1 second";
-    readonly promptHint: "lasting approximately 1 second";
-    readonly term: "about 1 second";
-    readonly blendsCut: true;
-}, {
-    readonly id: "medium";
-    readonly label: "Medium (~2s)";
-    readonly description: "Approximately 2 seconds";
-    readonly promptHint: "lasting approximately 2 seconds";
-    readonly term: "about 2 seconds";
-}, {
-    readonly id: "long";
-    readonly label: "Long (~3s)";
-    readonly description: "Approximately 3 seconds";
-    readonly promptHint: "lasting approximately 3 seconds";
-    readonly term: "about 3 seconds";
-}];
-declare const TRANSITION_INTENSITIES: readonly [{
-    readonly id: "auto";
-    readonly label: "Auto";
-    readonly description: "Let the model judge it";
-    readonly promptHint: "";
-    readonly term: "";
-}, {
-    readonly id: "subtle";
-    readonly label: "Subtle";
-    readonly description: "Restrained, minimal flourish";
-    readonly promptHint: "with subtle restrained energy and minimal flourish";
-    readonly term: "subtly";
-}, {
-    readonly id: "natural";
-    readonly label: "Natural";
-    readonly description: "Unhurried, unforced timing";
-    readonly promptHint: "with natural timing";
-    readonly term: "at a natural pace";
-}, {
-    readonly id: "dynamic";
-    readonly label: "Dynamic";
-    readonly description: "Assertive, energetic";
-    readonly promptHint: "with dynamic energy and assertive flourish";
-    readonly term: "energetically";
-}, {
-    readonly id: "crazy";
-    readonly label: "Crazy";
-    readonly description: "Extreme, wild, distorted";
-    readonly promptHint: "with extreme exaggerated energy, wild flourishes, and dramatic distortion";
-    readonly term: "wildly exaggerated";
-}];
-/**
- * Where the composed hint lands. `"clip"` (the default) is a whole video's
- * prompt, so a position is placed within "the clip". `"shot"` is one shot's
- * time window inside a multi-shot prompt (`0-2s — …`, `2-4s — …`): there "the
- * middle of the clip" points the model at the wrong span, so the position
- * clause says "of this shot" instead.
- */
-type TransitionHintScope = "clip" | "shot";
-interface TransitionHintOptions {
-    readonly scope?: TransitionHintScope;
-    /** The per-row option choices (a wipe's `wipeDirection`) — see
-     *  `Transition.options`. Absent, every row reads as `auto`. */
-    readonly optionValues?: TransitionOptionValues;
-}
-/**
- * Compose a structural prompt-hint sentence from a transition id (or array
- * of 1-2 ids for multi-pick) plus optional start-state/end-state hints
- * (collected by walking the source node's startState / endState input
- * handle edges upstream) and optional timing fields.
- *
- * Behavior:
- * - 0 hints (no transition, empty array, or all-empty hints) → ""
- * - each pick rendered `<term> (<hint body>)` (`renderTransitionBases`),
- *   n picks joined with ", and "
- * - Timing/start/end clauses apply ONCE at the outer layer, not per-id
- * - When every picked id is instant (a cut — see `isInstantTransition`) the
- *   first base's parentheses carry `INSTANT_CUT_CLAUSE` once, and the
- *   duration and intensity clauses are dropped; position still applies,
- *   except `full` — a single-frame cut spans nothing, so it adds no clause
- * - A BLENDED CUT: when every picked id is a blendable cut
- *   (`isBlendableTransition`) and the duration `blendsCut` (Short), that
- *   clause is `blendedCutClause(duration)` INSTEAD of `INSTANT_CUT_CLAUSE`
- *   (replaced, not appended; still once, in the first parentheses); every
- *   other rule above stands as for a hard cut, so there is still no duration
- *   clause, no intensity clause and no `full`. Any other duration on such a
- *   pick, and any duration on any other cut, leaves the hard cut
- * - null input is treated like undefined (falsy short-circuit → returns "")
- *
- * @param _mode Accepted for the picker-hint signature; a transition composes
- *   the same text in both modes — each pick as `<term> (<hint body>)`, see
- *   `renderTransitionBases`.
- * @param options `scope: "shot"` when the hint is folded into one shot's time
- *   window of a multi-shot prompt — the position clause then says "of this
- *   shot" instead of "of the clip" (and `full`, on a non-cut, "spans this
- *   entire shot"). Omitted, the wording is the clip's. `optionValues` are the
- *   per-row option choices (a wipe's direction), written into the row's own
- *   description; omitted, every row reads as `auto`.
- */
-declare function composeTransitionHintFromConnections(transitionId: string | ReadonlyArray<string> | undefined, startHints: ReadonlyArray<string>, endHints: ReadonlyArray<string>, timing?: TransitionTiming, _mode?: PickerHintMode, options?: TransitionHintOptions): string;
-
-export { AURORA_SWEEP_STYLE as A, getTransitionLabel as B, getTransitionOptions as C, DEBRIS_SHOWER_STYLE as D, getTransitionPromptHint as E, getTransitionTerm as F, GARDEN_BLOOM_STYLE as G, isBlendableTransition as H, INSTANT_CUT_CLAUSE as I, isInstantTransition as J, readTransitionOptionValues as K, renderTransitionBases as L, SAKURA_PETALS_STYLE as S, TRANSITIONS as T, WHITE_FLASH_STYLE as W, SAND_STORM_STYLE as a, SMOKE_PUFF_STYLE as b, TRANSITION_CATEGORY_LABELS as c, TRANSITION_CATEGORY_ORDER as d, TRANSITION_DURATIONS as e, TRANSITION_IDS as f, TRANSITION_INTENSITIES as g, TRANSITION_OPTION_FIELDS as h, TRANSITION_POSITIONS as i, TRANSITION_STYLE_FIELD as j, type Transition as k, type TransitionCategory as l, type TransitionDuration as m, type TransitionHintOptions as n, type TransitionHintScope as o, type TransitionIntensity as p, type TransitionOption as q, type TransitionOptionChoice as r, type TransitionOptionValues as s, type TransitionPosition as t, type TransitionTiming as u, type TransitionTimingOption as v, WIPE_DIRECTION as w, blendedCutClause as x, composeTransitionHintFromConnections as y, getTransition as z };