@vanillaskyai/video 0.6.0 → 0.7.1

package/dist/index.d.ts

@@ -1,6 +1,7 @@
-import { c as Video, g as VideoBrandInput, h as VideoBrand } from './types-BV9IqExh.js';
-export { d as VideoAudio, i as VideoBackground, j as VideoInput, k as VideoKnowledgeMode, b as VideoOrientation, e as VideoScene, V as VideoStyle, l as VideoStyleOptions, m as VideoSuppliedMedia } from './types-BV9IqExh.js';
+import { c as Video, h as VideoBrandInput, i as VideoBrand, e as VideoScene, d as VideoAudio, V as VideoStyle, b as VideoOrientation, j as VideoTemplatePacing } from './types-2wHBqtg8.js';
+export { k as VideoBackground, g as VideoInput, l as VideoKnowledgeMode, m as VideoStyleOptions, n as VideoSuppliedMedia } from './types-2wHBqtg8.js';
 export { V as VideoStatus } from './state-DZcKuS32.js';
+import { b as VideoEvent } from './events-B6qS1Lsb.js';
 
 type VideoValidationErrorCode = "invalid_video" | "unsupported_video_version";
 declare class VideoValidationError extends Error {
@@ -14,4 +15,89 @@ declare function getVideoDuration(config: Video): number;
 
 declare function resolveVideoBrand(input?: VideoBrandInput): VideoBrand;
 
-export { Video, VideoBrand, VideoBrandInput, VideoValidationError, type VideoValidationErrorCode, getVideoDuration, parseVideo, resolveVideoBrand };
+/**
+ * Compose a playable video from scenes the host builds itself.
+ *
+ * `VideoInput.opening` is a single line of copy, so an application that wants
+ * several scenes of its own before the generated ones has nowhere to put them.
+ * Handing the player a fresh `video` prop is not an answer either: that resets
+ * playback to zero on every change, so a video that grows replays its opening
+ * each time something is appended. The player's `stream` prop appends, and this
+ * builds a stream.
+ *
+ * The reason it belongs here rather than in each application is that the
+ * envelope rules are exact and their failure is silent. `response.start` must
+ * be sequence zero, every event exactly one higher, `eventId` exactly
+ * `${runId}:${sequence}`, `scene.add.position` the index the scene lands at,
+ * and the completion snapshot must reproduce what the reducer built. Miss any
+ * one and the whole stream is rejected: the player renders nothing, and the
+ * console stays clean.
+ */
+interface SceneTimeline {
+    /**
+     * Hand this to the player's `stream` prop once. Never swap it: a new stream
+     * is a new video, and playback restarts.
+     */
+    stream: AsyncIterable<VideoEvent>;
+    /** Append a scene. Ignored once the timeline has completed. */
+    add(scene: VideoScene): void;
+    /**
+     * Say what the soundtrack is, or that there is none.
+     *
+     * Only meaningful with `awaitAudio`, where it releases the scenes held back
+     * while the track was unknown. Calling it twice, or after the first scene has
+     * been emitted, does nothing.
+     */
+    setAudio(audio: VideoAudio | undefined): void;
+    /** Finish the video. Safe to call more than once. */
+    complete(): void;
+}
+interface SceneTimelineOptions {
+    style: VideoStyle;
+    orientation?: VideoOrientation;
+    /**
+     * The soundtrack, when it is already known.
+     *
+     * Use `awaitAudio` instead when it is resolved by a request that has not
+     * answered yet.
+     */
+    audio?: VideoAudio;
+    /**
+     * Hold scenes until `setAudio` is called.
+     *
+     * `audio.set` is only valid before the first scene, so a timeline that opens
+     * with host-built scenes cannot add a soundtrack afterwards - the event
+     * arrives too late and the video plays silently, with nothing to show for it.
+     * Holding the openings costs the wait for the track to resolve, not the wait
+     * for the video to be planned.
+     */
+    awaitAudio?: boolean;
+    requestId?: string;
+    runId?: string;
+}
+declare function createSceneTimeline(options: SceneTimelineOptions): SceneTimeline;
+
+interface SceneDurationBounds {
+    /**
+     * The least this scene survives being shown for.
+     *
+     * A compression bound, used when a video must fit a fixed length. It is not
+     * a readability bound and should not be used as one.
+     */
+    minimum: number;
+    /** How long the scene's own content takes to read, given what it holds. */
+    readable: number;
+}
+declare function getSceneDurationBounds(scene: Pick<VideoScene, "variables">, metadata: VideoTemplatePacing | undefined): SceneDurationBounds;
+/**
+ * How long a narrated line takes to say.
+ *
+ * Reading is faster than speech - the readable estimate runs at 4.5 words a
+ * second, a realtime voice lands nearer 2.6 - so the two bounds measure
+ * different things and a scene needs whichever is longer. The tail covers the
+ * breath between lines.
+ */
+declare function getSpokenDuration(narration: string): number;
+declare function getSceneDuration(scene: Pick<VideoScene, "variables" | "narration">, metadata: VideoTemplatePacing | undefined): number;
+
+export { type SceneDurationBounds, type SceneTimeline, type SceneTimelineOptions, Video, VideoAudio, VideoBrand, VideoBrandInput, VideoOrientation, VideoScene, VideoStyle, VideoValidationError, type VideoValidationErrorCode, createSceneTimeline, getSceneDuration, getSceneDurationBounds, getSpokenDuration, getVideoDuration, parseVideo, resolveVideoBrand };

package/dist/index.js

@@ -1,8 +1,15 @@
+import {
+  createSceneTimeline,
+  getSceneDuration,
+  getSceneDurationBounds,
+  getSpokenDuration
+} from "./chunk-SKRGRKHY.js";
 import {
   VideoValidationError,
   parseVideo
-} from "./chunk-66MNRUCR.js";
+} from "./chunk-2PYO6VAC.js";
 import "./chunk-AOWSXU2K.js";
+import "./chunk-3O7OMMMF.js";
 import {
   getVideoDuration
 } from "./chunk-SPVTJH3F.js";
@@ -11,6 +18,10 @@ import {
 } from "./chunk-XGRA2MUV.js";
 export {
   VideoValidationError,
+  createSceneTimeline,
+  getSceneDuration,
+  getSceneDurationBounds,
+  getSpokenDuration,
   getVideoDuration,
   parseVideo,
   resolveVideoBrand

package/dist/{infographic-before-after-2I7YZVDD.js → infographic-before-after-ROS52GOW.js}

@@ -6,7 +6,7 @@ import {
 } from "./chunk-S7HFLYNN.js";
 import {
   smoothSize
-} from "./chunk-TCEHK2BW.js";
+} from "./chunk-YJJC4N4D.js";
 import {
   Emoji,
   renderWithEmoji

package/dist/{infographic-feature-list-QDM4I7XE.js → infographic-feature-list-E7MGUDAN.js}

@@ -7,10 +7,10 @@ import {
 import {
   SceneBackground,
   getMediaBackgroundProps
-} from "./chunk-7BGAU6C3.js";
+} from "./chunk-MXZSDGZQ.js";
 import {
   TemplateText
-} from "./chunk-TCEHK2BW.js";
+} from "./chunk-YJJC4N4D.js";
 import {
   Emoji
 } from "./chunk-L5BTTCZV.js";

package/dist/{infographic-problem-solution-FMLJCPG6.js → infographic-problem-solution-3S6NGO5N.js}

@@ -4,10 +4,10 @@ import {
 import {
   SceneBackground,
   getMediaBackgroundProps
-} from "./chunk-7BGAU6C3.js";
+} from "./chunk-MXZSDGZQ.js";
 import {
   smoothSize
-} from "./chunk-TCEHK2BW.js";
+} from "./chunk-YJJC4N4D.js";
 import "./chunk-L5BTTCZV.js";
 import "./chunk-FRN6WKHA.js";
 import "./chunk-W3VDIBGR.js";

package/dist/{infographic-stat-row-VFTIXS5F.js → infographic-stat-row-SYB7AB7H.js}

@@ -1,10 +1,10 @@
 import {
   SceneBackground,
   getMediaBackgroundProps
-} from "./chunk-7BGAU6C3.js";
+} from "./chunk-MXZSDGZQ.js";
 import {
   TemplateText
-} from "./chunk-TCEHK2BW.js";
+} from "./chunk-YJJC4N4D.js";
 import "./chunk-L5BTTCZV.js";
 import "./chunk-FRN6WKHA.js";
 import {

package/dist/{infographic-steps-L7W24Z35.js → infographic-steps-KCE6JWE2.js}

@@ -8,10 +8,10 @@ import {
 import {
   SceneBackground,
   getMediaBackgroundProps
-} from "./chunk-7BGAU6C3.js";
+} from "./chunk-MXZSDGZQ.js";
 import {
   TemplateText
-} from "./chunk-TCEHK2BW.js";
+} from "./chunk-YJJC4N4D.js";
 import {
   Emoji
 } from "./chunk-L5BTTCZV.js";

package/dist/{kit-DEG3fcaL.d.ts → kit-8g46H2RZ.d.ts}

@@ -1,4 +1,4 @@
-import { V as VideoStyle, a as VideoCapabilities } from './types-BV9IqExh.js';
+import { V as VideoStyle, a as VideoCapabilities } from './types-2wHBqtg8.js';
 import { ComponentType } from 'react';
 import { S as SceneTemplateMetadata, d as TemplateJsonSchema, f as TemplateJsonSchemaProperty } from './catalog-types-BIhSpOWK.js';
 

package/dist/{prompt-input-F3CYU2XH.js → prompt-input-MHX4O42G.js}

@@ -4,7 +4,7 @@ import {
 import {
   SceneBackground,
   getMediaBackgroundProps
-} from "./chunk-7BGAU6C3.js";
+} from "./chunk-MXZSDGZQ.js";
 import "./chunk-FRN6WKHA.js";
 import "./chunk-W3VDIBGR.js";
 import {

package/dist/react.d.ts

@@ -1,8 +1,10 @@
-import { CSSProperties, ReactElement } from 'react';
-import { b as VideoEvent, V as VideoWarning } from './events-BBP30j3c.js';
-import { b as VideoOrientation, c as Video, e as VideoScene, j as VideoInput } from './types-BV9IqExh.js';
-import { T as TemplateRegistry } from './kit-DEG3fcaL.js';
+import * as react from 'react';
+import { CSSProperties, ReactElement, ReactNode } from 'react';
+import { b as VideoEvent, V as VideoWarning } from './events-B6qS1Lsb.js';
+import { b as VideoOrientation, c as Video, e as VideoScene, g as VideoInput, h as VideoBrandInput, m as VideoStyleOptions } from './types-2wHBqtg8.js';
+import { T as TemplateRegistry } from './kit-8g46H2RZ.js';
 import { V as VideoStatus } from './state-DZcKuS32.js';
+import { c as VideoChatMode, e as VideoChatAskOptions, f as VideoChatMedia, g as VideoChatSuggestion, a as VideoChatCapabilities, h as VideoChatWelcome } from './types-DrABlRa7.js';
 import './catalog-types-BIhSpOWK.js';
 
 type VideoPlaybackMode = "manual" | "muted-autoplay" | "autoplay-with-sound" | "autoplay-after-interaction";
@@ -29,8 +31,35 @@ interface VideoPlayerSharedProps {
     style?: CSSProperties;
     /** Accessible name for the player region. */
     ariaLabel?: string;
+    /**
+     * Show the player's own controls: play, mute, fullscreen, and the replay
+     * offered when the video ends. Default true.
+     *
+     * Turn them off where the host drives playback itself and a second set of
+     * controls would contradict it - a narrated answer whose voice and picture
+     * are one thing, where pausing the picture alone desynchronises them, and
+     * where a replay scrim would cover the answer the moment it finished.
+     */
+    controls?: boolean;
+    /**
+     * Hold the playhead where it is, and release it again.
+     *
+     * The counterpart to turning `controls` off. A host that owns playback needs
+     * a lever to drive it with, and until this there was none: the clock is the
+     * player's, so a narrated answer could silence its voice but not stop its
+     * picture, and the two came apart. Setting it back to false resumes from the
+     * same playhead rather than restarting.
+     *
+     * Leave it undefined to keep the player's own behaviour untouched. A video
+     * that has already reached its end is not resumed by it - the playhead is
+     * already there, and starting again is a replay, which is a different act.
+     */
+    paused?: boolean;
     /** Repeat the saved video and its soundtrack instead of showing the replay affordance. */
     loop?: boolean;
+    /** Fires once when the playhead reaches the end of a non-looping video. */
+    onPlaybackEnd?: (video: Video) => void;
+    /** Fires when a streamed response has finished composing. */
     onComplete?: (video: Video) => void;
     onError?: (error: Error) => void;
     /** Fires when the scene under the playhead changes, including on a loop wrap. */
@@ -46,7 +75,7 @@ type VideoPlayerProps = VideoPlayerSharedProps & ({
     templates?: TemplateRegistry;
 });
 
-declare function VideoPlayer({ templates, stream, video, onComplete, onError, ...props }: VideoPlayerProps): ReactElement | null;
+declare function VideoPlayer({ templates, stream, video, onPlaybackEnd, onComplete, onError, ...props }: VideoPlayerProps): ReactElement | null;
 
 interface VideoErrorOptions {
     code: string;
@@ -92,4 +121,163 @@ interface UseVideoResult {
 }
 declare function useVideo(options?: UseVideoOptions): UseVideoResult;
 
-export { type UseVideoOptions, type UseVideoResult, VideoError, type VideoErrorOptions, type VideoPlaybackMode, VideoPlayer, type VideoPlayerProps, useVideo };
+/**
+ * Say a video's narration as it plays.
+ *
+ * A narrated video is not a video with audio bolted on. The line belongs to the
+ * scene, so it has to begin when that scene does and stop when the viewer moves
+ * on - and every one of those was a bug in the application this was extracted
+ * from: the voice starting before the first frame, a follow-up question
+ * silently cutting the response off mid-sentence, a line still playing over the
+ * scene after it.
+ *
+ * The provider is not the SDK's business. An application supplies something
+ * that can speak - a realtime session, a speech model, the browser's own
+ * synthesiser - and this decides what is said, when it starts, and when it
+ * stops. That keeps the package free of provider dependencies and leaves the
+ * choice of voice where the choice of model already is.
+ */
+interface NarrationVoice {
+    /**
+     * Say this line, and resolve when it has been said.
+     *
+     * The signal aborts when the scene changes, when the viewer interrupts, or
+     * when the player goes away. Stop speaking promptly: talking over the next
+     * scene is worse than being cut off.
+     */
+    speak(text: string, options: {
+        signal: AbortSignal;
+    }): void | Promise<void>;
+}
+interface NarrationOptions {
+    voice: NarrationVoice;
+    /** Say nothing at all while false. Defaults to true. */
+    enabled?: boolean;
+}
+interface Narration {
+    /**
+     * Hand this to the player's `onSceneChange`.
+     *
+     * The player already reports which scene is showing, which is the only cue a
+     * narrator needs, so nothing here has to run its own clock.
+     */
+    onSceneChange: (scene: VideoScene, index: number) => void;
+    /** Stop the current line. Nothing is said again until the next scene. */
+    interrupt: () => void;
+    /** Whether a line is being spoken right now. */
+    speaking: boolean;
+}
+declare function useNarration(options: NarrationOptions): Narration;
+
+interface VideoChatPreparedSpeech {
+    /** Measured or conservatively estimated spoken duration, in seconds. */
+    seconds: number;
+}
+interface VideoChatVoice extends NarrationVoice {
+    prepare(text: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<VideoChatPreparedSpeech>;
+    pause(): void;
+    resume(): void;
+    setMuted(muted: boolean): void;
+    dispose?(): void;
+}
+interface CreateVideoChatVoiceOptions {
+    endpoint?: string | URL;
+    headers?: HeadersInit;
+    credentials?: RequestCredentials;
+    fetcher?: typeof fetch;
+    maxCachedLines?: number;
+}
+/**
+ * Create the SDK's generated-speech client with a browser-voice fallback.
+ *
+ * The endpoint is provider-neutral. A no-content response (or a compatible
+ * endpoint's 404) selects browser speech for the rest of the session.
+ */
+declare function createVideoChatVoice(options?: CreateVideoChatVoiceOptions): VideoChatVoice;
+
+type VideoChatStatus = "idle" | "composing" | "playing" | "paused" | "ended" | "cancelled" | "error";
+interface VideoChatTurn {
+    id: string;
+    prompt: string;
+    /** True only after the complete response has been received. */
+    completed: boolean;
+    opening?: string;
+    /** Optional stock footage held behind the opening hook until playback starts. */
+    openingMedia?: VideoChatMedia;
+    orientation: VideoOrientation;
+    /** Generated footage keeps the orientation it was created in. */
+    fixedOrientation: boolean;
+    video?: Video;
+    suggestions: readonly VideoChatSuggestion[];
+}
+interface UseVideoChatOptions {
+    /** One provider-neutral route created with createVideoChatHandler. */
+    endpoint?: string | URL;
+    /** Customer-owned templates that replace built-ins and add new renderers. */
+    templates?: TemplateRegistry;
+    mode?: VideoChatMode;
+    orientation?: VideoOrientation;
+    brand?: VideoBrandInput;
+    style?: VideoStyleOptions;
+    headers?: HeadersInit;
+    credentials?: RequestCredentials;
+    fetcher?: typeof fetch;
+    /** Replace the SDK speech client while keeping session timing and cancellation. */
+    voice?: VideoChatVoice;
+    initialMuted?: boolean;
+    timeoutMs?: number;
+    createTurnId?: () => string;
+    /** Observe how long a fresh response takes to display its first actual scene. */
+    onFirstFrame?: (metric: VideoChatFirstFrameMetric) => unknown;
+}
+interface VideoChatFirstFrameMetric {
+    turnId: string;
+    mode: VideoChatMode;
+    timeToFirstFrameMs: number;
+}
+interface UseVideoChatResult {
+    ask(prompt: string, options?: VideoChatAskOptions): Promise<Video | undefined>;
+    cancel(reason?: string): void;
+    pause(): void;
+    resume(): void;
+    replay(): void;
+    selectTurn(id: string): void;
+    reset(): void;
+    turns: readonly VideoChatTurn[];
+    currentTurn?: VideoChatTurn;
+    shownTurn?: VideoChatTurn;
+    capabilities?: VideoChatCapabilities;
+    welcome?: VideoChatWelcome;
+    availableModes: readonly VideoChatMode[];
+    status: VideoChatStatus;
+    error?: VideoError;
+    suggestions: readonly VideoChatSuggestion[];
+    caption?: string;
+    /** Narration revealed so far for the shown response. */
+    transcript: readonly string[];
+    speaking: boolean;
+    muted: boolean;
+    setMuted(muted: boolean): void;
+    playbackEnded: boolean;
+    /** Changes whenever saved content should restart from zero. */
+    playerKey: number;
+    /** Spread into VideoPlayer when present. */
+    playerProps?: VideoPlayerProps;
+}
+/** Own a complete video conversation while the application owns its UI. */
+declare function useVideoChat(options?: UseVideoChatOptions): UseVideoChatResult;
+
+interface VideoChatProps {
+    /** Connection, providers, templates, and rendering defaults for the session. */
+    options?: UseVideoChatOptions;
+    /** Added to the scoped component root for application layout and branding. */
+    className?: string;
+    /** Replaces the default two-line welcome heading without changing the interaction. */
+    welcomeTitle?: ReactNode;
+}
+/** A complete voice-and-video chat interface backed by createVideoChatHandler. */
+declare function VideoChat({ options, className, welcomeTitle }: VideoChatProps): react.JSX.Element;
+
+export { type CreateVideoChatVoiceOptions, type Narration, type NarrationOptions, type NarrationVoice, type UseVideoChatOptions, type UseVideoChatResult, type UseVideoOptions, type UseVideoResult, VideoChat, VideoChatAskOptions, VideoChatCapabilities, type VideoChatFirstFrameMetric, VideoChatMedia, VideoChatMode, type VideoChatPreparedSpeech, type VideoChatProps, type VideoChatStatus, VideoChatSuggestion, type VideoChatTurn, type VideoChatVoice, VideoChatWelcome, VideoError, type VideoErrorOptions, type VideoPlaybackMode, VideoPlayer, type VideoPlayerProps, createVideoChatVoice, useNarration, useVideo, useVideoChat };