@pixerate/flair 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { C as ControlValue, a as ControlDef } from './controls-DdXMbovi.js';
-export { c as ControlCheck, b as ControlType, T as TextureSettings, d as checkControlValue, e as coerceControlValue, f as componentCount, g as controlValue, h as describeValue, i as hexToRgb, j as humanise, k as imageUrls, l as isImageUrl, p as parseControls, r as rgbToHex } from './controls-DdXMbovi.js';
-export { B as BUILTIN_UNIFORMS, C as CompileError, b as CompileResult, a as CompileStatus, c as CompiledShader, F as FrameState, I as ImageLoadError, R as RendererStats, S as SVG_EDGE, d as ShaderCompileError, e as ShaderRenderer, T as TextureCache, f as TextureSource, V as VERTEX_SOURCE, g as applyTextureSettings, h as compileShader, i as createContext, j as drawFrame, k as formatCompileError, l as isSvgUrl, m as loadImage, p as parseCompileLog, n as preloadImages, r as releaseImages, o as resetGlCaches, s as sizeSvg, w as wrapSource } from './renderer-Oyynz-fs.js';
+import { C as ControlValue, a as ControlDef } from './controls-Syr6drzO.js';
+export { c as ControlCheck, b as ControlType, T as TextureSettings, d as checkControlValue, e as coerceControlValue, f as componentCount, g as controlValue, h as describeValue, i as hexToRgb, j as humanise, k as imageUrls, l as isImageUrl, p as parseControls, r as rgbToHex } from './controls-Syr6drzO.js';
+export { B as BUILTIN_UNIFORMS, C as CompileError, b as CompileResult, a as CompileStatus, c as CompiledShader, F as FrameState, I as ImageLoadError, R as RendererStats, S as SVG_EDGE, d as ShaderCompileError, e as ShaderRenderer, T as TextureCache, f as TextureSource, V as VERTEX_SOURCE, g as applyTextureSettings, h as compileShader, i as createContext, j as drawFrame, k as formatCompileError, l as isSvgUrl, m as loadImage, p as parseCompileLog, n as preloadImages, r as releaseImages, o as resetGlCaches, s as sizeSvg, w as wrapSource } from './renderer-DtnFkpkf.js';
 import { C as Clock } from './clock-BhdXWH-n.js';
 export { M as ManualClock, j as jitter, p as pageHidden, r as realClock } from './clock-BhdXWH-n.js';
 export { D as DataKey, E as EASES, a as EaseName, b as STEP_MS, c as SVG_PICTURE, d as SvgAnimation, e as SvgBox, f as SvgElementFrame, S as SvgMotion, g as defaultDataKey, l as lerpAttr, h as lerpData, s as stepData, i as stepProgress, j as stepStart, k as svgFrame, m as svgMotionIssues, n as svgOpeningTag } from './motion-D0TVv2CF.js';
@@ -649,11 +649,42 @@ interface Stage {
 }
 declare const DEFAULT_STAGE: Stage;
 declare const CAMERA_MS = 600;
-/** Camera view into the scene: drawn at (point + scroll) × zoom. */
-interface View {
+/**
+ * How the camera is turned in 3D, in degrees: the board is drawn flat (see
+ * {@link View}), then turned round the middle of the stage and seen in
+ * perspective. Each is optional and 0 (flat) by default.
+ */
+interface CameraAngle {
+    /** Tips the board back round its horizontal axis (CSS `rotateX`): positive leans the top away, like a desk seen from above. −75 to 75. */
+    tilt?: number;
+    /** Swings the board round its vertical axis (CSS `rotateY`): positive brings the left side nearer. −75 to 75. */
+    turn?: number;
+    /** Rolls the board round the line of sight (CSS `rotateZ`), clockwise. −180 to 180. */
+    roll?: number;
+    /** How far the lens sits from the board, as a multiple of the stage width (default {@link DEFAULT_PERSPECTIVE}); smaller is more dramatic. */
+    perspective?: number;
+}
+/** The camera's default distance from the board, as a multiple of the stage width. */
+declare const DEFAULT_PERSPECTIVE = 1.2;
+/** The largest tilt or turn, in degrees: past this the board is seen edge-on. */
+declare const MAX_TILT = 75;
+/**
+ * Camera view into the scene: drawn at (point + scroll) × zoom, then turned
+ * by its {@link CameraAngle} (see {@link cameraTransform}) and blurred by
+ * `blur` while the camera moves.
+ */
+interface View extends CameraAngle {
     zoom: number;
     scrollX: number;
     scrollY: number;
+    /** Motion blur in stage pixels, set while the camera moves (see `ShotCamera.motionBlur`); 0 or absent when still. */
+    blur?: number;
+    /**
+     * The direction the picture streaks in, in degrees on screen (0 is
+     * horizontal, 90 vertical), when the move is mostly a pan; absent when it
+     * blurs every way (a zoom or a turn).
+     */
+    blurAngle?: number;
 }
 declare const boardHeight: (stage: Stage) => number;
 /** View with `(cx, cy)` in the middle of the board at `zoom`. */
@@ -675,11 +706,56 @@ interface FramingOptions {
  * while preserving the stage aspect ratio and applying optional margin padding.
  */
 declare function calculateFramingRect(elements: readonly SceneElement[], stage: Stage, options?: FramingOptions): Rect;
+/** Whether a view is turned in 3D at all. */
+declare function isAngled(view: CameraAngle): boolean;
+/** The view's angle with each part clamped to its range (see {@link CameraAngle}); flat parts are left out. */
+declare function cameraAngle(view: CameraAngle): CameraAngle;
 /**
  * The view part-way (`t` from 0 to 1) from one view to another.
- * Centre moves linearly and zoom scales exponentially for smooth motion.
+ * Centre moves linearly and zoom scales exponentially for smooth motion;
+ * angles and perspective move linearly.
  */
 declare function between(from: View, to: View, t: number, stage: Stage): View;
+/**
+ * The CSS `transform` that turns a board layer (a box the stage's size,
+ * with `transform-origin` in its middle) to the view's angle, or "none" when
+ * the view is flat. Zoom and scroll are not in it: draw them inside the
+ * layer, as for a flat view. `width` is the layer's width on screen in CSS
+ * pixels (default: the stage width).
+ */
+declare function cameraTransform(view: View, stage: Stage, width?: number): string;
+/**
+ * The view's motion blur as standard deviations along the board layer's own
+ * x and y axes, in CSS pixels at a layer `width` wide: for an SVG
+ * `<feGaussianBlur stdDeviation="x y">`, so a pan streaks along its
+ * direction (CSS `blur()` can only blur every way). The layer is turned
+ * after it is blurred, so the direction is taken back through its roll.
+ * [0, 0] when still.
+ */
+declare function cameraBlur(view: View, stage: Stage, width?: number): [number, number];
+/** The CSS `filter` for the view's motion blur at a layer `width` CSS pixels wide (the same every way; see {@link cameraBlur} for a streak), or "none". */
+declare function cameraFilter(view: View, stage: Stage, width?: number): string;
+/**
+ * Where a scene point lands on screen, in stage pixels from the top left of
+ * the board: drawn by the view's zoom and scroll, then turned and seen in
+ * perspective as {@link cameraTransform} does. Null when the point is
+ * behind the camera.
+ */
+declare function projectPoint(view: View, stage: Stage, [x, y]: readonly [number, number]): [number, number] | null;
+/**
+ * Motion blur for one step of a camera move, in stage pixels: how far the
+ * picture moves on screen between two views (centre, zoom and angle), times
+ * `strength` (`ShotCamera.motionBlur`), capped at 40.
+ */
+declare function motionBlur(from: View, to: View, stage: Stage, strength: number): number;
+/**
+ * The direction a step of a camera move streaks in, in degrees on screen
+ * (0 to 180, 0 horizontal), when most of it is a pan; undefined when it is
+ * mostly zooming or turning, which blurs every way.
+ */
+declare function motionBlurAngle(from: View, to: View, stage: Stage): number | undefined;
+/** The blur fields of a step of a camera move with this strength: `{ blur, blurAngle }`, or nothing when still. */
+declare function moveBlur(from: View, to: View, stage: Stage, strength: number): Pick<View, 'blur' | 'blurAngle'>;
 /** The part of the scene the camera currently shows. */
 declare function visibleRect(view: View, stage: Stage): Rect;
 /** Smooth cubic ease in / ease out. */
@@ -952,14 +1028,32 @@ interface DynamicFraming {
     /** Minimum height in scene units. */
     minHeight?: number;
 }
-type ShotCamera = Rect | DynamicFraming;
+/**
+ * A shot's camera beyond its framing: its 3D angle (see `CameraAngle`) and
+ * how much it blurs while moving into the shot. A part left out keeps the
+ * value the camera already has, so set `tilt: 0` to come back flat.
+ */
+interface CameraLens extends CameraAngle {
+    /**
+     * Motion blur while the camera moves into this shot: 0 (the default) for
+     * none, 1 for natural, up to 3 for a whip. The blur follows the move's
+     * speed, so it peaks mid-move and is gone when the camera settles.
+     */
+    motionBlur?: number;
+}
+/**
+ * Where the camera goes for a shot: a framing box, a dynamic framing, or
+ * neither (only a new angle or blur, keeping the framing), with any
+ * {@link CameraLens} fields alongside: `{ "frame": ["chart"], "tilt": 30 }`.
+ */
+type ShotCamera = (Rect | DynamicFraming | Record<never, never>) & CameraLens;
 /** One beat of a scene: camera framing, title, narration/caption, commands, and procedural effects. */
 interface Shot {
     /** Narration / caption spoken or displayed during this beat. */
     caption?: string;
     /** High-level title or callout displayed on screen. */
     title?: string;
-    /** Camera framing box in scene units, or dynamic auto-framing target. */
+    /** Camera framing box in scene units or dynamic auto-framing target, with an optional 3D angle and motion blur. */
     camera?: ShotCamera;
     /** Pause/dwell duration after this shot's actions run (in milliseconds). Default: 800ms. */
     hold?: number;
@@ -987,6 +1081,53 @@ interface Scene {
     shots: Shot[];
 }
 
+/** The camera through one shot, timed as `playScene` plays it: a move from `from` to `to`, then a hold. */
+interface CameraShot {
+    shot: Shot;
+    index: number;
+    /** When the shot starts on the scene's timeline, in ms. */
+    startMs: number;
+    /** How long the camera moves at the start of the shot (0 when it cuts or stays). */
+    moveMs: number;
+    /** How long the shot holds after the move. */
+    holdMs: number;
+    from: View;
+    to: View;
+    /** The shot's `camera.motionBlur` (0 for none). */
+    motionBlur: number;
+    /** The elements on stage once the shot's commands have run. */
+    elements: SceneElement[];
+}
+/** The scene's stage with defaults filled in. */
+declare function sceneStage(scene: Scene): Stage;
+/**
+ * The camera through every shot of a scene, worked out the way `playScene`
+ * moves it, for exporters and players that lay a scene out on a timeline:
+ * each shot's move (framing, angle and blur strength) and hold.
+ */
+declare function cameraTrack(scene: Scene): CameraShot[];
+/** The time the player waits between steps of a camera move, in ms (its blur is measured over one). */
+declare const CAMERA_STEP_MS: number;
+/**
+ * The camera `ms` into a shot: part-way through its move (eased, with its
+ * motion blur) or settled.
+ */
+declare function cameraAt(entry: CameraShot, ms: number, stage: Stage): View;
+/** The camera at one frame of a scene's timeline. */
+interface CameraSample {
+    frame: number;
+    view: View;
+    /** The shot (0-based) the frame is in. */
+    shot: number;
+}
+/**
+ * The camera sampled for a timeline at `frameRate`: every `every` frames
+ * during each move (so an editor's straight-line interpolation follows the
+ * eased path and perspective), and once where each move settles. Views
+ * include the move's motion blur.
+ */
+declare function cameraSamples(scene: Scene, frameRate: number, every?: number): CameraSample[];
+
 interface ShotCheck {
     /** Elements this shot drew or changed that the camera frame leaves out ("outside") or cuts ("cut"). */
     framing: {
@@ -1016,7 +1157,17 @@ declare const NO_CHECK: ShotCheck;
 declare const SMALL_TEXT_PX = 24;
 declare function titleBox(title: string, stage: Stage): Rect;
 declare function touchedIds(shot: Shot): string[];
-/** Evaluates the elements on stage against the current camera view and shot settings. */
+/**
+ * Where a scene box lands on screen (stage pixels from the board's top
+ * left), turned and in perspective as the view draws it: the bounds of its
+ * four corners. Null when part of it is behind the camera.
+ */
+declare function screenBox(box: Rect, view: View, stage: Stage): Rect | null;
+/**
+ * Evaluates the elements on stage against the current camera view and shot
+ * settings. Framing, edges, text size and the title are judged on screen,
+ * where the view (its angle included) puts each element.
+ */
 declare function checkShot(shot: Shot, elements: readonly SceneElement[], view: View, stage: Stage, title?: string): ShotCheck;
 
 interface SceneIssue {
@@ -1076,6 +1227,14 @@ declare class MemorySceneBoard implements SceneBoard {
     setCaption(text: string): void;
     setEffects(effects: readonly RunningEffect[]): void;
 }
+/**
+ * The view a shot's camera moves to: its framing (a box, or the elements it
+ * frames, from the board or the shot's own commands) at its angle, zoomed
+ * out when angled so the framed box still fits. Framing
+ * or angle parts the camera leaves out keep `current`'s. Undefined when the
+ * shot has no camera.
+ */
+declare function shotView(shot: Shot, elements: readonly SceneElement[], stage: Stage, current: View): View | undefined;
 interface PlayOptions {
     check?: boolean;
     afterShot?: (log: ShotLog) => void | Promise<void>;
@@ -1103,8 +1262,9 @@ declare function simulateScene(scene: Scene, options?: {
 
 /**
  * Generates a self-contained, standalone HTML player for an animated scene.
- * Includes interactive playback controls, camera panning/zooming, title and caption rendering,
- * and embedded WebGL fragment shaders for bespoke motion graphics.
+ * Includes interactive playback controls, camera moves (panning, zooming,
+ * 3D angles and motion blur), title and caption rendering, and embedded
+ * WebGL fragment shaders for bespoke motion graphics.
  */
 declare function standaloneSceneHtml(scene: Scene): string;
 
@@ -1277,7 +1437,9 @@ interface MotnExportOptions {
     frameRate?: number;
 }
 /**
- * Serializes a Flair Scene into Apple Motion ozml 4.0 XML document format (.motn).
+ * Serializes a Flair Scene into Apple Motion ozml 4.0 XML document format
+ * (.motn). A scene with a camera puts its shots in a "Camera" group that
+ * moves, zooms and turns as the camera does.
  */
 declare function exportMotn(scene: Scene, options?: MotnExportOptions): string;
 
@@ -1315,7 +1477,11 @@ interface LottieTransform {
     p: LottieAnimatable<[number, number, number], [number, number, number]>;
     a: LottieAnimatable<[number, number, number], [number, number, number]>;
     s: LottieAnimatable<[number, number, number], [number, number, number]>;
-    r: LottieAnimatable<number, [number]>;
+    r?: LottieAnimatable<number, [number]>;
+    or?: LottieAnimatable<[number, number, number]>;
+    rx?: LottieAnimatable<number, [number]>;
+    ry?: LottieAnimatable<number, [number]>;
+    rz?: LottieAnimatable<number, [number]>;
     o: LottieAnimatable<number, [number]>;
 }
 interface LottieShapeItem {
@@ -1328,6 +1494,10 @@ interface LottieLayer {
     ind: number;
     ty: number;
     nm: string;
+    /** Index of the parent layer: element layers hang off the camera rig. */
+    parent?: number;
+    /** Camera layers: perspective (the AE camera's zoom), in px. */
+    pe?: LottieAnimatable<number, [number]>;
     sr: number;
     ks: LottieTransform;
     ao: 0 | 1;
@@ -1348,7 +1518,7 @@ interface LottieAnimation {
     w: number;
     h: number;
     nm: string;
-    ddd: 0;
+    ddd: 0 | 1;
     assets: unknown[];
     layers: LottieLayer[];
 }
@@ -1366,7 +1536,9 @@ declare function createLottieEase(durationFrames: number, deltaVal: number, outE
     };
 };
 /**
- * Serializes a Flair Scene into standard Lottie JSON animation.
+ * Serializes a Flair Scene into standard Lottie JSON animation. A scene
+ * with a camera gets a camera rig the element layers hang off, in 3D (with
+ * an AE camera) when the camera is angled.
  */
 declare function exportLottie(scene: Scene, options?: LottieExportOptions): LottieAnimation;
 
@@ -1419,13 +1591,17 @@ declare function framesToTimecode(frame: number, timebase?: number, dropFrame?:
 declare function timecodeToFrames(timecode: string, timebase?: number, dropFrame?: boolean): number;
 /**
  * Serializes a Flair Scene into Apple Final Cut Pro 7 XML Interchange Format (xmeml v4).
- * Compatible with Premiere Pro, DaVinci Resolve, and Final Cut Pro.
+ * Compatible with Premiere Pro, DaVinci Resolve, and Final Cut Pro. Each
+ * shot's camera (zoom, pan and 3D angle) is a keyframed Distort corner pin
+ * on its clip, with Motion Blur when the shot's move blurs.
  */
 declare function exportFcp7Xml(scene: Scene, options?: Fcp7ExportOptions): string;
 /**
  * Serializes a Flair Scene into standard CMX 3600 Edit Decision List (EDL).
+ * The format has no transforms, so each shot's camera is written as a
+ * `* CAMERA:` comment.
  * Fully readable by DaVinci Resolve, Premiere Pro, Avid, and Lightworks.
  */
 declare function exportCmx3600Edl(scene: Scene, options?: EdlExportOptions): string;
 
-export { ALL_BLEND_MODES, ALL_TRANSITION_TYPES, type AgentToolDefinition, type AscCdl, type BatchCommand, type BatchExecutionResult, type BatchExecutionStepResult, type Behavior, type BehaviorBase, type BlendMode, type BlockDissolveOptions, type BlurEffect, type BurstEffect, CAMERA_MS, COMMON_FRAME_RATES, type ClearCommand, Clock, type ColorRGB, type ColorRGBA, type ColorRgba, type ColorSpace, ControlDef, ControlValue, type CounterEffect, type CrossZoomOptions, type CustomCommand, DEFAULT_STAGE, type DeleteCommand, type DynamicFraming, EASY_EASE, EFFECT_FADE_MS, EFFECT_TYPES, type EasingCurve, type EdlExportOptions, type Effect, type EffectBase, type ElementCommand, FLAIR_AGENT_TOOLS, type Fcp7ExportOptions, type FlowEffect, type FramingOptions, type GifOptions, type GlassWipeOptions, type GlowEffect, type GradientEffect, type GridWipeOptions, type HighlightEffect, type KeyframeEase, type LiftGammaGain, type LightLeakOptions, type LinearWipeOptions, type LottieAnimatable, type LottieAnimation, type LottieExportOptions, type LottieKeyframe, type LottieLayer, type LottieShapeItem, type LottieTransform, type MediaEffect, MemorySceneBoard, type MotnExportOptions, NO_CHECK, type OscillateBehavior, type OvershootBehavior, type PathWaypoint, type PlayOptions, type PlayResult, type Point, type PopupWidget, type RadialIrisOptions, type RampBehavior, type RateBehavior, type RationalFrameRate, type Rect, type RenderOptions, type ReplicatorConfig, type ReplicatorPattern, type ReplicatorSequence, type Review, type ReviewOptions, type RigWidget, type RippleEffect, type RunningEffect, SMALL_TEXT_PX, type SMPTEFields, type Scene, type SceneBoard, type SceneCommand, type SceneElement, type SceneIssue, type SceneMedia, type SceneRig, type SceneToolResult, ShaderFrames, type ShaderFramesOptions, type ShimmerEffect, type Shot, type ShotCamera, type ShotCheck, type ShotLog, type ShotTiming, type SliderSnapshot, type SliderWidget, type SpatialMotionPath, type SpatialPathSample, type SpotlightEffect, type Stage, type StandaloneOptions, type StandardFrameRateKey, type ThrowBehavior, type ThumbnailHandle, ThumbnailPool, type ThumbnailPoolOptions, type TimerEffect, type ToggleWidget, type TransitionOptions, type TransitionSample, type TransitionType, type TwisterOptions, type UpdateCommand, type Vec2, type Vec3, type View, type WriggleBehavior, applyAscCdl, applyLiftGammaGain, applyRig, applySceneBatch, applySceneTool, applyVibrance, areaOf, between, bez1d, bez1dDerivative, blendRgba, blendTransitionPixel, boardHeight, boundsOf, calculateFramingRect, calculateShotTimings, centreOf, checkShot, convertColorSpace, createFrameRate, createLottieEase, createMotionPath, easeInOutCubic, easeProgress, effectGone, effectOpacity, evaluateBehavior, evaluateKeyframeSegment, expandReplicator, exportCmx3600Edl, exportFcp7Xml, exportLottie, exportMotn, formatTimecode, fractalWiggle, frame, framesToSMPTE, framesToTimecode, getColorGradingGLSL, getDropFrameCount, getGlslBlendFunction, getOklabGLSL, getTimecodeBase, getTransitionGLSL, getWhiteBalanceGains, hash64, holdTime, interpolateOklab, interpolateOklch, isDeleteCommand, isElementCommand, isUpdateCommand, linearRgbToSrgb, linearSrgbToOklab, linearToSrgb, loopTime, mixSeeds, noise1d, noise3d, oklabToLinearSrgb, oklabToOklch, oklabToSrgb, oklchToOklab, overlapArea, parseTimecode, pingPongTime, playScene, quinticFade, recordGif, registerThumbnail, reviewScene, sampleMotionPath, sampleMotionPathAtTime, sampleTransition, setRigWidget, sharedThumbnailPool, simulateScene, smpteToFrames, solveBezierU, speedRampTime, srgbToLinear, srgbToLinearRgb, srgbToOklab, standaloneHtml, standaloneSceneHtml, strobeTime, substituteVariables, supportsDropFrame, timecodeToFrames, titleBox, touchedIds, unitFloat, validateScene, viewAt, visibleRect };
+export { ALL_BLEND_MODES, ALL_TRANSITION_TYPES, type AgentToolDefinition, type AscCdl, type BatchCommand, type BatchExecutionResult, type BatchExecutionStepResult, type Behavior, type BehaviorBase, type BlendMode, type BlockDissolveOptions, type BlurEffect, type BurstEffect, CAMERA_MS, CAMERA_STEP_MS, COMMON_FRAME_RATES, type CameraAngle, type CameraLens, type CameraSample, type CameraShot, type ClearCommand, Clock, type ColorRGB, type ColorRGBA, type ColorRgba, type ColorSpace, ControlDef, ControlValue, type CounterEffect, type CrossZoomOptions, type CustomCommand, DEFAULT_PERSPECTIVE, DEFAULT_STAGE, type DeleteCommand, type DynamicFraming, EASY_EASE, EFFECT_FADE_MS, EFFECT_TYPES, type EasingCurve, type EdlExportOptions, type Effect, type EffectBase, type ElementCommand, FLAIR_AGENT_TOOLS, type Fcp7ExportOptions, type FlowEffect, type FramingOptions, type GifOptions, type GlassWipeOptions, type GlowEffect, type GradientEffect, type GridWipeOptions, type HighlightEffect, type KeyframeEase, type LiftGammaGain, type LightLeakOptions, type LinearWipeOptions, type LottieAnimatable, type LottieAnimation, type LottieExportOptions, type LottieKeyframe, type LottieLayer, type LottieShapeItem, type LottieTransform, MAX_TILT, type MediaEffect, MemorySceneBoard, type MotnExportOptions, NO_CHECK, type OscillateBehavior, type OvershootBehavior, type PathWaypoint, type PlayOptions, type PlayResult, type Point, type PopupWidget, type RadialIrisOptions, type RampBehavior, type RateBehavior, type RationalFrameRate, type Rect, type RenderOptions, type ReplicatorConfig, type ReplicatorPattern, type ReplicatorSequence, type Review, type ReviewOptions, type RigWidget, type RippleEffect, type RunningEffect, SMALL_TEXT_PX, type SMPTEFields, type Scene, type SceneBoard, type SceneCommand, type SceneElement, type SceneIssue, type SceneMedia, type SceneRig, type SceneToolResult, ShaderFrames, type ShaderFramesOptions, type ShimmerEffect, type Shot, type ShotCamera, type ShotCheck, type ShotLog, type ShotTiming, type SliderSnapshot, type SliderWidget, type SpatialMotionPath, type SpatialPathSample, type SpotlightEffect, type Stage, type StandaloneOptions, type StandardFrameRateKey, type ThrowBehavior, type ThumbnailHandle, ThumbnailPool, type ThumbnailPoolOptions, type TimerEffect, type ToggleWidget, type TransitionOptions, type TransitionSample, type TransitionType, type TwisterOptions, type UpdateCommand, type Vec2, type Vec3, type View, type WriggleBehavior, applyAscCdl, applyLiftGammaGain, applyRig, applySceneBatch, applySceneTool, applyVibrance, areaOf, between, bez1d, bez1dDerivative, blendRgba, blendTransitionPixel, boardHeight, boundsOf, calculateFramingRect, calculateShotTimings, cameraAngle, cameraAt, cameraBlur, cameraFilter, cameraSamples, cameraTrack, cameraTransform, centreOf, checkShot, convertColorSpace, createFrameRate, createLottieEase, createMotionPath, easeInOutCubic, easeProgress, effectGone, effectOpacity, evaluateBehavior, evaluateKeyframeSegment, expandReplicator, exportCmx3600Edl, exportFcp7Xml, exportLottie, exportMotn, formatTimecode, fractalWiggle, frame, framesToSMPTE, framesToTimecode, getColorGradingGLSL, getDropFrameCount, getGlslBlendFunction, getOklabGLSL, getTimecodeBase, getTransitionGLSL, getWhiteBalanceGains, hash64, holdTime, interpolateOklab, interpolateOklch, isAngled, isDeleteCommand, isElementCommand, isUpdateCommand, linearRgbToSrgb, linearSrgbToOklab, linearToSrgb, loopTime, mixSeeds, motionBlur, motionBlurAngle, moveBlur, noise1d, noise3d, oklabToLinearSrgb, oklabToOklch, oklabToSrgb, oklchToOklab, overlapArea, parseTimecode, pingPongTime, playScene, projectPoint, quinticFade, recordGif, registerThumbnail, reviewScene, sampleMotionPath, sampleMotionPathAtTime, sampleTransition, sceneStage, screenBox, setRigWidget, sharedThumbnailPool, shotView, simulateScene, smpteToFrames, solveBezierU, speedRampTime, srgbToLinear, srgbToLinearRgb, srgbToOklab, standaloneHtml, standaloneSceneHtml, strobeTime, substituteVariables, supportsDropFrame, timecodeToFrames, titleBox, touchedIds, unitFloat, validateScene, viewAt, visibleRect };

package/dist/index.js

@@ -19,39 +19,18 @@ import {
 } from "./chunk-G5FNZDTA.js";
 import {
   ALL_BLEND_MODES,
-  EFFECT_FADE_MS,
-  EFFECT_TYPES,
-  MemorySceneBoard,
-  NO_CHECK,
-  SMALL_TEXT_PX,
   ShaderFrames,
   ShaderRenderer,
   ThumbnailPool,
   blendRgba,
-  checkShot,
-  effectGone,
-  effectOpacity,
-  evaluateBehavior,
-  fractalWiggle,
   getGlslBlendFunction,
-  hash64,
-  mixSeeds,
-  noise1d,
-  noise3d,
-  playScene,
-  quinticFade,
   recordGif,
   registerThumbnail,
-  reviewScene,
   sharedThumbnailPool,
-  simulateScene,
   standaloneHtml,
   standaloneSceneHtml,
-  titleBox,
-  touchedIds,
-  unitFloat,
   validateScene
-} from "./chunk-JWZCPMFG.js";
+} from "./chunk-GL37YCCM.js";
 import {
   BUILTIN_UNIFORMS,
   ImageLoadError,
@@ -91,19 +70,13 @@ import {
   srgbToLinearRgb,
   srgbToOklab,
   wrapSource
-} from "./chunk-HKXOHRCD.js";
+} from "./chunk-VA74HBPK.js";
 import {
   ALL_TRANSITION_TYPES,
   blendTransitionPixel,
   getTransitionGLSL,
   sampleTransition
 } from "./chunk-EHDJ3CPJ.js";
-import {
-  ManualClock,
-  jitter,
-  pageHidden,
-  realClock
-} from "./chunk-WMZQCUFJ.js";
 import {
   calculateShotTimings,
   createLottieEase,
@@ -113,25 +86,70 @@ import {
   exportMotn,
   framesToTimecode,
   timecodeToFrames
-} from "./chunk-UQQNZSYL.js";
+} from "./chunk-GTIAOYOK.js";
 import {
   CAMERA_MS,
+  CAMERA_STEP_MS,
+  DEFAULT_PERSPECTIVE,
   DEFAULT_STAGE,
+  EFFECT_FADE_MS,
+  EFFECT_TYPES,
+  MAX_TILT,
+  MemorySceneBoard,
+  NO_CHECK,
+  SMALL_TEXT_PX,
   areaOf,
   between,
   boardHeight,
   boundsOf,
   calculateFramingRect,
+  cameraAngle,
+  cameraAt,
+  cameraBlur,
+  cameraFilter,
+  cameraSamples,
+  cameraTrack,
+  cameraTransform,
   centreOf,
+  checkShot,
   easeInOutCubic,
+  effectGone,
+  effectOpacity,
+  evaluateBehavior,
+  fractalWiggle,
   frame,
+  hash64,
+  isAngled,
   isDeleteCommand,
   isElementCommand,
   isUpdateCommand,
+  mixSeeds,
+  motionBlur,
+  motionBlurAngle,
+  moveBlur,
+  noise1d,
+  noise3d,
   overlapArea,
+  playScene,
+  projectPoint,
+  quinticFade,
+  reviewScene,
+  sceneStage,
+  screenBox,
+  shotView,
+  simulateScene,
+  titleBox,
+  touchedIds,
+  unitFloat,
   viewAt,
   visibleRect
-} from "./chunk-36DTNSHU.js";
+} from "./chunk-WAMA45G3.js";
+import {
+  ManualClock,
+  jitter,
+  pageHidden,
+  realClock
+} from "./chunk-WMZQCUFJ.js";
 import {
   checkControlValue,
   coerceControlValue,
@@ -144,7 +162,7 @@ import {
   isImageUrl,
   parseControls,
   rgbToHex
-} from "./chunk-J55UBNAT.js";
+} from "./chunk-WC3VADZC.js";
 
 // src/time/retiming.ts
 function loopTime(t, duration, start = 0) {
@@ -814,7 +832,7 @@ var FLAIR_AGENT_TOOLS = [
       properties: {
         scene: {
           type: "object",
-          description: "Full Scene object with name, stage, media, and shots."
+          description: "Full Scene object with name, stage, media, and shots. A shot camera frames a box {x, y, width, height} or elements {frame: [ids]}, and may add tilt, turn, roll (degrees, tilt/turn up to 75), perspective (default 1.2) and motionBlur (0-3, 1 natural); angles persist until changed."
         }
       },
       required: ["scene"],
@@ -1103,7 +1121,9 @@ export {
   ALL_TRANSITION_TYPES,
   BUILTIN_UNIFORMS,
   CAMERA_MS,
+  CAMERA_STEP_MS,
   COMMON_FRAME_RATES,
+  DEFAULT_PERSPECTIVE,
   DEFAULT_STAGE,
   EASES,
   EASY_EASE,
@@ -1111,6 +1131,7 @@ export {
   EFFECT_TYPES,
   FLAIR_AGENT_TOOLS,
   ImageLoadError,
+  MAX_TILT,
   ManualClock,
   MemorySceneBoard,
   NO_CHECK,
@@ -1142,6 +1163,13 @@ export {
   boundsOf,
   calculateFramingRect,
   calculateShotTimings,
+  cameraAngle,
+  cameraAt,
+  cameraBlur,
+  cameraFilter,
+  cameraSamples,
+  cameraTrack,
+  cameraTransform,
   centreOf,
   checkControlValue,
   checkShot,
@@ -1188,6 +1216,7 @@ export {
   imageUrls,
   interpolateOklab,
   interpolateOklch,
+  isAngled,
   isDeleteCommand,
   isElementCommand,
   isImageUrl,
@@ -1202,6 +1231,9 @@ export {
   loadImage,
   loopTime,
   mixSeeds,
+  motionBlur,
+  motionBlurAngle,
+  moveBlur,
   noise1d,
   noise3d,
   oklabToLinearSrgb,
@@ -1217,6 +1249,7 @@ export {
   pingPongTime,
   playScene,
   preloadImages,
+  projectPoint,
   quinticFade,
   realClock,
   recordGif,
@@ -1228,8 +1261,11 @@ export {
   sampleMotionPath,
   sampleMotionPathAtTime,
   sampleTransition,
+  sceneStage,
+  screenBox,
   setRigWidget,
   sharedThumbnailPool,
+  shotView,
   simulateScene,
   sizeSvg,
   smpteToFrames,