odori 0.0.1 → 0.0.2

package/dist/index.d.ts

@@ -0,0 +1,464 @@
+import { V as VideoEntry, a as VideoLayout, C as CompiledTimeline, A as AudioTrack } from './manifest-CEuFXG0U.js';
+export { b as Audio, c as AudioCue, d as AudioPolicy, e as AudioProps, f as CompiledScene, g as CreateManifestOptions, D as DUCK_GAIN, h as DUCK_RAMP_FRAMES, E as EnvelopePoint, i as ExportJob, F as Fill, j as Freeze, L as Loop, M as ManifestAsset, k as ManifestAudioCue, l as ManifestFont, m as MotionPolicy, O as OdoriRuntime, n as OdoriRuntimeProps, R as RenderManifest, S as SafeArea, o as SafeAreaPolicy, p as Scene, q as SceneTransition, r as Stagger, s as Video, t as VideoFormat, u as VideoLayoutInput, v as createRenderManifest, w as cueId, x as defaultLayout, y as defineVideoLayout, z as duckEnvelope, B as entryDurationInFrames, G as envelopeAtFrame, H as gainAtFrame, I as isAssetReference, J as resolveEntryLayout, K as sampleGainCurve, N as sortCues, P as trackDuration, Q as trackGainAtFrame, T as useSceneTransition } from './manifest-CEuFXG0U.js';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { CSSProperties, RefObject } from 'react';
+import { B as Brand, S as Signal, D as Duration } from './brand-D71KbhAe.js';
+export { a as BrandColors, b as BrandFont, c as BrandInput, d as BrandTypography, C as ChordQuality, e as CueContext, f as CueDefinition, E as Envelope, g as SAMPLE_RATE, h as Step, i as brandCssVariables, j as chord, k as cueSamples, l as cueSignature, m as cueUrl, n as defaultBrand, o as defineBrand, p as defineCue, q as formatTimecode, r as framesFromDuration, s as gain, t as highPass, u as isCueDefinition, v as loop, w as lowPass, x as mix, y as noise, z as normalize, A as note, F as pad, G as seamless, H as seconds, I as secondsFromFrames, J as seeded, K as sequence, L as shape, M as silence, N as sine, O as step, P as sweep, Q as triangle } from './brand-D71KbhAe.js';
+import { P as ParsableSchema } from './schema-DXxRezrk.js';
+export { F as FieldDescriptor, I as InputSchema, d as defineInputSchema, i as isOdoriSchema, p as parseWithSchema } from './schema-DXxRezrk.js';
+
+/**
+ * Integrated loudness, ITU-R BS.1770-4.
+ *
+ * The number a mix is judged by is not peak or RMS: it is K-weighted, gated
+ * loudness. Studio measures what it is about to hand the encoder so the
+ * brand's target is something you can mix toward rather than discover after an
+ * export.
+ */
+type Biquad = {
+    b0: number;
+    b1: number;
+    b2: number;
+    a1: number;
+    a2: number;
+};
+/**
+ * Channel weights for stereo. Surround weights the surround channels higher;
+ * a video mix is stereo, so both channels count equally.
+ */
+declare const integratedLufs: (channels: Float32Array[], sampleRate: number) => number | null;
+
+type PlayerProps = {
+    entry: VideoEntry;
+    input?: Record<string, unknown>;
+    prepared?: unknown;
+    assets?: Array<{
+        reference: string;
+        url: string;
+    }>;
+    layout?: VideoLayout;
+    initialFrame?: number;
+    autoPlay?: boolean;
+    loop?: boolean;
+    controls?: boolean;
+    style?: CSSProperties;
+    muted?: boolean;
+    onFrame?: (frame: number) => void;
+    onTimeline?: (timeline: CompiledTimeline) => void;
+    onAudio?: (track: AudioTrack) => void;
+};
+/**
+ * The seekable frame clock. Playback advances a fractional frame counter from
+ * wall-clock deltas, but React only ever sees an integer frame, so a paused
+ * player and a render worker produce identical output.
+ */
+declare const Player: ({ entry, input, prepared, assets, layout, initialFrame, autoPlay, loop, controls, muted, style, onFrame, onTimeline, onAudio, }: PlayerProps) => react_jsx_runtime.JSX.Element;
+
+type AudioPlaybackOptions = {
+    track: AudioTrack | null;
+    frame: number;
+    fps: number;
+    playing: boolean;
+    muted?: boolean;
+    masterGain?: number;
+    /** Cue id to hear alone, or null for the whole mix. */
+    soloCue?: string | null;
+    /** True while the playhead is being dragged, which auditions under the cursor. */
+    scrubbing?: boolean;
+    /** Playback rate, so cues stay with the frame clock when it is sped up. */
+    rate?: number;
+    /**
+     * Called when the browser refuses to start a cue without a user gesture, and
+     * again when it relents. Autoplay policy is the difference between a silent
+     * preview and a broken one, so it is reported rather than swallowed.
+     */
+    onBlocked?: (blocked: boolean) => void;
+    /**
+     * Called with the cues whose files failed to load or decode. A cue pointing
+     * at a missing or wrong file is silence with no other symptom, so it is
+     * reported rather than swallowed.
+     */
+    onFailed?: (sources: string[]) => void;
+};
+/**
+ * Drives one HTMLAudioElement per cue from the frame clock.
+ *
+ * Audio is the one thing that cannot be derived from a frame index, so preview
+ * playback resyncs whenever the element drifts more than a frame from where the
+ * timeline says it should be. The exported mix is built separately by the
+ * encoder from the same cues, which keeps the file frame accurate.
+ */
+declare const useAudioPlayback: ({ track, frame, fps, playing, muted, masterGain, soloCue, scrubbing, rate, onBlocked, onFailed, }: AudioPlaybackOptions) => void;
+
+type PlaybackOptions = {
+    fps: number;
+    durationInFrames: number;
+    initialFrame?: number;
+    autoPlay?: boolean;
+    loop?: boolean;
+    /** Wall-clock multiplier. The frame clock keeps its rate; only time moves. */
+    rate?: number;
+    onFrame?: (frame: number) => void;
+};
+type Playback = {
+    frame: number;
+    playing: boolean;
+    rate: number;
+    play(): void;
+    pause(): void;
+    toggle(): void;
+    seek(frame: number): void;
+    step(delta: number): void;
+    restart(): void;
+};
+/**
+ * The seekable frame clock. Playback advances a fractional counter from
+ * wall-clock deltas, but React only ever sees an integer frame, so a paused
+ * player, a still, and the export worker agree by construction.
+ */
+/**
+ * How far the clock moves for a wall-clock delta.
+ *
+ * Rate scales elapsed time, never the frame index, so frame 90 is the same
+ * image at 0.25x, 1x, and 4x, and an export ignores rate entirely.
+ */
+declare const advanceFrames: (fractional: number, deltaMs: number, fps: number, rate?: number) => number;
+declare const usePlayback: ({ fps, durationInFrames, initialFrame, autoPlay, loop, rate, onFrame, }: PlaybackOptions) => Playback;
+
+declare global {
+    interface Window {
+        __ODORI_SET_FRAME__?: (frame: number) => void;
+        __ODORI_TIMELINE__?: CompiledTimeline;
+        __ODORI_AUDIO__?: AudioTrack;
+        __ODORI_READY__?: boolean;
+    }
+}
+/**
+ * The surface the render worker drives. It exposes an explicit frame setter
+ * and a readiness handshake instead of relying on timing heuristics.
+ */
+declare const RenderSurface: ({ entry, initialFrame, input, prepared, assets, layout, }: {
+    entry: VideoEntry;
+    initialFrame?: number;
+    input?: Record<string, unknown>;
+    prepared?: unknown;
+    assets?: Array<{
+        reference: string;
+        url: string;
+    }>;
+    layout?: VideoLayout;
+}) => react_jsx_runtime.JSX.Element;
+
+type FrameState = {
+    frame: number;
+    fps: number;
+    width: number;
+    height: number;
+    durationInFrames: number;
+};
+type SceneState = {
+    id: string;
+    name?: string;
+    index: number;
+    start: number;
+    durationInFrames: number;
+};
+type AssetRegistry = {
+    resolve(reference: string): string;
+    list(): Array<{
+        reference: string;
+        url: string;
+    }>;
+    ready: boolean;
+};
+type Readiness = {
+    /** Hold the frame open. Call the returned function when the work is done. */
+    hold(): () => void;
+};
+/**
+ * Block the frame until asynchronous work finishes.
+ *
+ * The driver waits for the frame attribute, and the runtime only writes it once
+ * every held handle is released. Without this a component that decodes an image
+ * would be screenshotted before it had anything to show.
+ */
+declare const useReadiness: () => Readiness;
+/** The frame index local to the nearest scene, or the video frame at the top level. */
+declare const useFrame: () => number;
+declare const useVideo: () => Omit<FrameState, "frame">;
+/**
+ * A single number components multiply their design values by.
+ *
+ * Sizing from the shorter side keeps type and spacing readable when the same
+ * component is composed into a 16:9, 9:16, or 1:1 frame. A width-derived scale
+ * would shrink a vertical cut into unreadable text.
+ */
+declare const useDesignScale: (reference?: number) => number;
+declare const useBrand: () => Brand;
+declare const useLayout: () => VideoLayout;
+declare const useScene: () => SceneState;
+declare const useAssets: () => AssetRegistry;
+declare const createAssetRegistry: (entries: Array<{
+    reference: string;
+    url: string;
+}>) => AssetRegistry;
+
+/**
+ * Signal to a 16 bit PCM WAV. Small, lossless, and readable by FFmpeg without
+ * a decoder, which is all the mix needs from a generated cue.
+ *
+ * Encoding lives in the runtime rather than the CLI so preview and export
+ * share it: the browser can hand the same bytes to an AudioContext that the
+ * render worker writes to disk.
+ */
+declare const encodeWav: (signal: Signal) => Uint8Array;
+
+type EasingFunction = (value: number) => number;
+declare const Easing: {
+    linear: (value: number) => number;
+    bezier: (x1: number, y1: number, x2: number, y2: number) => EasingFunction;
+    standard: EasingFunction;
+    quad: (value: number) => number;
+    cubic: (value: number) => number;
+    in: (easing: EasingFunction) => EasingFunction;
+    out: (easing: EasingFunction) => EasingFunction;
+    inOut: (easing: EasingFunction) => EasingFunction;
+};
+type InterpolateOptions = {
+    easing?: EasingFunction;
+    extrapolateLeft?: "extend" | "clamp";
+    extrapolateRight?: "extend" | "clamp";
+};
+declare function interpolate(value: number, input: number[], output: number[], options?: InterpolateOptions): number;
+declare function interpolate(value: number, input: number[], output: string[], options?: InterpolateOptions): string;
+type SpringOptions = {
+    frame: number;
+    fps: number;
+    from?: number;
+    to?: number;
+    stiffness?: number;
+    damping?: number;
+    mass?: number;
+    delayInFrames?: number;
+};
+/**
+ * A deterministic damped-spring solve. The value depends only on the frame
+ * index, so preview and render always agree.
+ */
+declare const spring: ({ frame, fps, from, to, stiffness, damping, mass, delayInFrames, }: SpringOptions) => number;
+
+type CursorStop = {
+    /** Frame this stop is reached, from the start of the enclosing scene. */
+    frame: number;
+    /** Canvas coordinates, in the composition's own pixels. */
+    x: number;
+    y: number;
+    /**
+     * A click landing on this stop. The press is drawn at the stop's frame and
+     * decays over a few frames, so the pointer visibly does the thing the UI is
+     * about to react to.
+     */
+    click?: boolean;
+    /** Hold here until this many frames have passed before moving on. */
+    hold?: number;
+};
+type CursorState = {
+    x: number;
+    y: number;
+    /** 0 before the path starts and after it ends, 1 while it is on screen. */
+    visible: number;
+    /** 1 at the instant of a click, decaying to 0. Drives the press ring. */
+    pressed: number;
+    /** True while a click is within its press window, for a UI to react to. */
+    clicking: boolean;
+};
+/**
+ * Where an authored pointer is at this frame.
+ *
+ * Recording a real cursor would make a video that cannot be re-rendered: the
+ * path would live in a file, not in the composition, and a change of copy or
+ * canvas would leave it pointing at nothing. An authored path is source — it
+ * diffs, it survives a reflow, and it produces the same pixels every run.
+ *
+ * Movement eases between stops rather than running linearly, because a pointer
+ * that travels at constant speed reads as a machine. A `hold` keeps the
+ * pointer still without needing a duplicate stop at the same coordinates.
+ */
+declare const cursorAt: (stops: CursorStop[], frame: number) => CursorState;
+/** The last frame an authored path is still on screen, for sizing a scene. */
+declare const cursorDuration: (stops: CursorStop[]) => number;
+
+/**
+ * Randomness that survives a re-render.
+ *
+ * A frame is a pure function of its number. `Math.random()` breaks that in the
+ * quietest possible way: the preview looks fine, every export looks fine, and
+ * the two are different — and so are two chunks of the same export, because a
+ * render is parallel and each worker rolls its own numbers. Fifty particles
+ * that jump between chunk boundaries is the usual symptom, found late.
+ *
+ * So a composition asks for a number by name instead. The same seed always
+ * gives the same value, on every machine and in every worker, and a seed that
+ * includes the frame gives motion that is random-looking and reproducible.
+ */
+/**
+ * A number in `[0, 1)` for a seed. The same seed always returns the same
+ * number, which is the whole point.
+ *
+ * ```tsx
+ * const drift = random(`particle-${index}`) * 40;
+ * const jitter = random([frame, index]) - 0.5;
+ * ```
+ *
+ * An array seed is joined, which is the convenient way to say "this thing, on
+ * this frame" without building the string by hand.
+ */
+declare const random: (seed: number | string | Array<number | string>) => number;
+/** A number in `[min, max)`, for a seed. */
+declare const randomBetween: (seed: number | string | Array<number | string>, min: number, max: number) => number;
+/** One item from a list, for a seed. Empty lists return undefined. */
+declare const randomPick: <T>(seed: number | string | Array<number | string>, items: readonly T[]) => T | undefined;
+/**
+ * A shuffled copy, for a seed. Fisher-Yates driven by the same generator, so
+ * the order is arbitrary but fixed — a list that reshuffles every frame is an
+ * animation nobody asked for.
+ */
+declare const randomOrder: <T>(seed: number | string | Array<number | string>, items: readonly T[]) => T[];
+
+type CanvasDraw = (context: CanvasRenderingContext2D, state: {
+    frame: number;
+    width: number;
+    height: number;
+}) => void;
+/**
+ * Draw to a canvas from the frame clock.
+ *
+ * The contract a video runs on is that frame N produces the same pixels every
+ * time. A canvas is where that is easiest to lose: the obvious way to animate
+ * one is `requestAnimationFrame`, which is wall time, and wall time means the
+ * export samples wherever the loop happened to be. Two workers rendering
+ * neighbouring chunks then disagree, and the seam shows.
+ *
+ * So the draw is a pure function of the frame, called synchronously before the
+ * browser paints, and the frame is held until it has run. The capture waits on
+ * the same readiness handshake an image decode uses, which is what makes the
+ * screenshot see finished pixels rather than an empty buffer.
+ */
+declare const useCanvas: (draw: CanvasDraw, dependencies?: readonly unknown[]) => RefObject<HTMLCanvasElement | null>;
+/**
+ * Rasterize HTML into a canvas, deterministically.
+ *
+ * The browser will draw an SVG containing a `foreignObject` onto a canvas, and
+ * a `foreignObject` can hold ordinary markup. That is the whole trick, and the
+ * reason it needs care: the image decode is asynchronous, so the frame has to
+ * be held until it lands, and the markup has to carry its own styles because
+ * nothing outside the SVG reaches into it.
+ *
+ * Fonts are the sharp edge. A face that is not loaded when this runs will fall
+ * back, and the fallback is what gets baked into the pixels — which is why the
+ * caller waits on `document.fonts.ready` before drawing.
+ */
+declare const drawHtml: (context: CanvasRenderingContext2D, html: string, options: {
+    width: number;
+    height: number;
+    style?: string;
+}) => Promise<void>;
+
+type PlaceholderOptions = {
+    width?: number;
+    height?: number;
+    /** Drawn across the middle, so a fixture says what it is standing in for. */
+    label?: string;
+    /** Two colours the gradient runs between. */
+    from?: string;
+    to?: string;
+    /** Seed for the scatter, so two placeholders differ without differing runs. */
+    seed?: string;
+};
+/**
+ * A picture that ships as code.
+ *
+ * A component that shows media needs media to show, and a fixture that ships a
+ * JPEG cannot be reviewed in a diff, cannot be recoloured by a brand, and adds
+ * a binary to a repository forever. Generating an SVG instead keeps the
+ * registry's rule intact — install copies source — and makes the picture do
+ * something a file cannot: describe itself.
+ *
+ * It is deliberately obviously a placeholder. A fixture that looks like real
+ * photography invites someone to ship it.
+ */
+declare const placeholderSvg: ({ width, height, label, from, to, seed, }?: PlaceholderOptions) => string;
+/**
+ * The same picture as a data URL, which is what an `<img>` or a canvas draw
+ * wants. Inline rather than fetched: a fixture that needs the network is a
+ * fixture that fails on a plane, in CI, and in a sandboxed render.
+ */
+declare const placeholderImage: (options?: PlaceholderOptions) => string;
+/**
+ * A frame of a placeholder "clip": the same picture with a moving marker and a
+ * timecode, so a component that plays media has something to play that visibly
+ * advances and is still a pure function of the frame.
+ */
+declare const placeholderFrame: (frame: number, options?: PlaceholderOptions & {
+    fps?: number;
+}) => string;
+
+type VideoMetadata<Input = Record<string, unknown>> = {
+    readonly kind: "odori-video-metadata";
+    id: string;
+    title: string;
+    description?: string;
+    duration?: Duration;
+    layout?: VideoLayout;
+    schema?: ParsableSchema<Input>;
+    defaultProps?: Partial<Input>;
+    tags?: string[];
+    thumbnailFrame?: number;
+};
+type VideoMetadataInput<Input = Record<string, unknown>> = Omit<VideoMetadata<Input>, "kind" | "id"> & {
+    /**
+     * Defaults to the entry's path under `videos/`, so the directory names a
+     * video the way a route names a page. Set it to keep an id stable across a
+     * directory move.
+     */
+    id?: string;
+};
+declare const isValidVideoId: (id: string) => boolean;
+/**
+ * An id left unset is resolved from the filesystem by discovery. The empty
+ * string is the unresolved state: no entry reaches a manifest, a render, or
+ * Studio without an id stamped in.
+ */
+declare const resolveVideoId: (id: string | undefined, pathId: string) => string;
+declare const defineVideoMetadata: <Input = Record<string, unknown>>(metadata: VideoMetadataInput<Input>) => VideoMetadata<Input>;
+type PrepareContext<Input> = {
+    input: Input;
+    assets: {
+        resolve(reference: string): Promise<string>;
+    };
+    cache: {
+        getOrSet<Value>(key: string, factory: () => Promise<Value>): Promise<Value>;
+    };
+    signal?: AbortSignal;
+};
+type PrepareFunction<Input = Record<string, unknown>, Prepared = unknown> = {
+    readonly kind: "odori-prepare";
+    version: string;
+    run(context: PrepareContext<Input>): Promise<Prepared>;
+};
+declare const definePrepare: <Input = Record<string, unknown>, Prepared = unknown>(run: (context: PrepareContext<Input>) => Promise<Prepared>, options?: {
+    version?: string;
+}) => PrepareFunction<Input, Prepared>;
+
+/**
+ * Deterministic, dependency-free content hash.
+ *
+ * The renderer only needs stable identity for cache keys and frozen manifests,
+ * so a 128-bit FNV-1a variant over canonical JSON is sufficient and runs
+ * identically in Node and the browser.
+ */
+declare const canonicalJson: (value: unknown) => string;
+declare const hashString: (input: string) => string;
+declare const hashValue: (value: unknown) => string;
+
+export { type AssetRegistry, type AudioPlaybackOptions, AudioTrack, type Biquad, Brand, type CanvasDraw, CompiledTimeline, type CursorState, type CursorStop, Duration, Easing, type EasingFunction, type FrameState, type InterpolateOptions, ParsableSchema, type PlaceholderOptions, type Playback, type PlaybackOptions, Player, type PlayerProps, type PrepareContext, type PrepareFunction, type Readiness, RenderSurface, type SceneState, Signal, type SpringOptions, VideoEntry, VideoLayout, type VideoMetadata, type VideoMetadataInput, advanceFrames, canonicalJson, createAssetRegistry, cursorAt, cursorDuration, definePrepare, defineVideoMetadata, drawHtml, encodeWav, hashString, hashValue, integratedLufs, interpolate, isValidVideoId, placeholderFrame, placeholderImage, placeholderSvg, random, randomBetween, randomOrder, randomPick, resolveVideoId, spring, useAssets, useAudioPlayback, useBrand, useCanvas, useDesignScale, useFrame, useLayout, usePlayback, useReadiness, useScene, useVideo };