vizmatic 0.7.0 → 0.7.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/stage.d.cts CHANGED
@@ -1,5 +1,5 @@
1
- import { P as Path, N as Node, c as ColorInput, V as Vec, C as CompileOverrides, B as Bounds, b as FilmDefinition, a as CompiledFilm, d as Side, A as AnimOptions, e as Anim, f as Value, R as Rgba, E as Edge, T as Target, g as PathOp, M as Mat } from './svg-import-Djj2q7Pc.cjs';
2
- export { h as AnimContext, i as Aspect, j as BlendMode, k as Canvas2D, l as Caption, m as Chapter, n as Clip, D as DrawOp, o as EMPTY_BOUNDS, p as Ease, q as FadeOptions, r as FilmOptions, s as Frame, F as FromSvgOptions, G as Gradient, I as IDENTITY, t as ImageOp, L as LOOKS, u as Look, v as LookName, w as LookToken, x as NodeProps, y as Paint, z as PlayOptions, H as PropName, J as Ring, K as Stage, O as StageImage, Q as Suspend, S as SvgNode, U as along, W as appear, X as apply, Y as applyMatrix, Z as arcPath, _ as blueprint, $ as bounce, a0 as buildOps, a1 as call, a2 as chalk, a3 as circlePath, a4 as circumscribe, a5 as colorAlong, a6 as compileFilm, a7 as compose, a8 as concat, a9 as css, aa as cubicBezier, ab as curveThrough, ac as delay, ad as draw, ae as during, af as dynamic, ag as easeInCubic, ah as easeInExpo, ai as easeInOutCubic, aj as easeInOutQuint, ak as easeInQuad, al as easeOutCubic, am as easeOutExpo, an as easeOutQuad, ao as easeOutQuint, ap as erase, aq as fade, ar as fadeIn, as as fadeOut, at as film, au as flash, av as frameInkBounds, aw as frameToSvg, ax as fromSvg, ay as group, az as grow, aA as indicate, aB as invert, aC as isFilm, aD as isSuspend, aE as lagged, aF as linePath, aG as linear, aH as linearGradient, aI as lingering, aJ as matScale, aK as midnight, aL as mixColor, aM as morph, aN as morphMatching, aO as moveTo, aP as mul, aQ as neon, aR as notQuiteThere, aS as overshoot, aT as paintFrame, aU as paper, aV as par, aW as parametricPath, aX as parseColor, aY as parseSvgPath, aZ as pathBounds, a_ as pathLength, a$ as pathToD, b0 as pointAt, b1 as polyPath, b2 as pulse, b3 as radialGradient, b4 as ramp, b5 as recolor, b6 as rectPath, b7 as resolveLook, b8 as retime, b9 as reverseRing, ba as ring, bb as ringCenter, bc as ringLength, bd as ripple, be as rotate, bf as runningStart, bg as rushFrom, bh as rushInto, bi as scaleBy, bj as segmentCount, bk as seq, bl as shake, bm as shift, bn as signedArea, bo as slowInto, bp as smooth, bq as smoothBy, br as smoothPath, bs as smoother, bt as spring, bu as subdivideEach, bv as tangentAt, bw as thereAndBack, bx as thereAndBackWithPause, by as to, bz as toPaint, bA as transformPath, bB as trimPath, bC as trimRing, bD as unionBounds, bE as vanish, bF as warp, bG as warpPath, bH as wiggle, bI as write } from './svg-import-Djj2q7Pc.cjs';
1
+ import { P as Path, N as Node, c as ColorInput, V as Vec, C as CompileOverrides, B as Bounds, b as FilmDefinition, a as CompiledFilm, d as Side, A as AnimOptions, e as Anim, f as Value, R as Rgba, E as Edge, T as Target, g as Stage, h as PathOp, M as Mat } from './svg-import-5_oTbEJR.cjs';
2
+ export { i as AnimContext, j as Aspect, k as BlendMode, l as Canvas2D, m as Caption, n as Chapter, o as Clip, D as DrawOp, p as EMPTY_BOUNDS, q as Ease, r as FadeOptions, s as FilmOptions, t as Frame, F as FromSvgOptions, G as Gradient, I as IDENTITY, u as ImageOp, L as LOOKS, v as Look, w as LookName, x as LookToken, y as NodeProps, z as Paint, H as PlayOptions, J as PropName, K as Ring, O as StageImage, Q as Suspend, S as SvgNode, U as along, W as appear, X as apply, Y as applyMatrix, Z as arcPath, _ as blueprint, $ as bounce, a0 as buildOps, a1 as call, a2 as chalk, a3 as circlePath, a4 as circumscribe, a5 as colorAlong, a6 as compileFilm, a7 as compose, a8 as concat, a9 as css, aa as cubicBezier, ab as curveThrough, ac as delay, ad as draw, ae as during, af as dynamic, ag as easeInCubic, ah as easeInExpo, ai as easeInOutCubic, aj as easeInOutQuint, ak as easeInQuad, al as easeOutCubic, am as easeOutExpo, an as easeOutQuad, ao as easeOutQuint, ap as erase, aq as fade, ar as fadeIn, as as fadeOut, at as film, au as flash, av as frameInkBounds, aw as frameToSvg, ax as fromSvg, ay as group, az as grow, aA as indicate, aB as invert, aC as isFilm, aD as isSuspend, aE as lagged, aF as linePath, aG as linear, aH as linearGradient, aI as lingering, aJ as matScale, aK as midnight, aL as mixColor, aM as morph, aN as morphMatching, aO as moveTo, aP as mul, aQ as neon, aR as notQuiteThere, aS as overshoot, aT as paintFrame, aU as paper, aV as par, aW as parametricPath, aX as parseColor, aY as parseSvgPath, aZ as pathBounds, a_ as pathLength, a$ as pathToD, b0 as pointAt, b1 as polyPath, b2 as pulse, b3 as radialGradient, b4 as ramp, b5 as recolor, b6 as rectPath, b7 as resolveLook, b8 as retime, b9 as reverseRing, ba as ring, bb as ringCenter, bc as ringLength, bd as ripple, be as rotate, bf as runningStart, bg as rushFrom, bh as rushInto, bi as scaleBy, bj as segmentCount, bk as seq, bl as shake, bm as shift, bn as signedArea, bo as slowInto, bp as smooth, bq as smoothBy, br as smoothPath, bs as smoother, bt as spring, bu as subdivideEach, bv as tangentAt, bw as thereAndBack, bx as thereAndBackWithPause, by as to, bz as toPaint, bA as transformPath, bB as trimPath, bC as trimRing, bD as unionBounds, bE as vanish, bF as warp, bG as warpPath, bH as wiggle, bI as write } from './svg-import-5_oTbEJR.cjs';
3
3
 
4
4
  interface GlyphOutline {
5
5
  /** Each contour is a closed cubic ring in font units, with y pointing up. */
@@ -104,6 +104,18 @@ declare function rect(width: number, height: number, style?: ShapeStyle & {
104
104
  }): Node;
105
105
  declare function polygon(points: readonly Vec[], style?: ShapeStyle): Node;
106
106
  declare function regularPolygon(sides: number, radius: number, style?: ShapeStyle): Node;
107
+ interface ImageOptions {
108
+ /** Width on the stage. With only one of width and height, the other keeps the picture's proportions. */
109
+ width?: number;
110
+ height?: number;
111
+ opacity?: number;
112
+ }
113
+ /**
114
+ * A raster picture, such as a logo or a photo, centered on its origin. `src` is a URL or a
115
+ * data URL. A data URL keeps a film in one file and renders the same in every tool.
116
+ * It fades, moves, and scales like any node. Give `width`, `height`, or both.
117
+ */
118
+ declare function image(src: string, options?: ImageOptions): Node;
107
119
  /** A filled point. */
108
120
  declare function dot(radius?: number, color?: ColorInput, style?: ShapeStyle): Node;
109
121
  interface ArrowStyle extends ShapeStyle {
@@ -1341,6 +1353,109 @@ declare function highlightSweep(target: Node | readonly Node[], options?: Highli
1341
1353
  mark: Node;
1342
1354
  };
1343
1355
 
1356
+ /** One spoken word, timed in seconds from the start of its beat. */
1357
+ interface NarrationWord {
1358
+ text: string;
1359
+ start: number;
1360
+ end: number;
1361
+ }
1362
+ /** One take of the voice: a sentence or a short paragraph. */
1363
+ interface NarrationBeat {
1364
+ /** The text that the voice speaks. Captions use it. */
1365
+ say: string;
1366
+ /** Measured length of the recording, in seconds. */
1367
+ duration: number;
1368
+ /** Silence after the beat, in seconds, for the viewer to think. */
1369
+ hold?: number;
1370
+ /** Word times, from the speech engine or from a transcription. Cues need them. */
1371
+ words?: readonly NarrationWord[];
1372
+ }
1373
+ interface NarrationScene {
1374
+ id: string;
1375
+ /** Chapter title. A scene without one does not start a chapter. */
1376
+ title?: string;
1377
+ beats: readonly NarrationBeat[];
1378
+ }
1379
+ interface NarrationTiming {
1380
+ scenes: readonly NarrationScene[];
1381
+ /** Seconds before the first word. `NarrationOptions.lead` overrides it. */
1382
+ lead?: number;
1383
+ /** Seconds of silence between scenes. `NarrationOptions.gap` overrides it. */
1384
+ gap?: number;
1385
+ }
1386
+ interface NarrationOptions {
1387
+ /** Seconds before the first word, for a logo or an opening picture. Defaults to 0.6. */
1388
+ lead?: number;
1389
+ /** Seconds of silence between scenes, for the picture to change. Defaults to 0.4. */
1390
+ gap?: number;
1391
+ /** Write a caption for each spoken line. On by default. */
1392
+ captions?: boolean;
1393
+ /** Longest caption line, in characters. Defaults to 74. */
1394
+ captionLength?: number;
1395
+ /** Start a chapter at each scene that has a title. On by default. */
1396
+ chapters?: boolean;
1397
+ }
1398
+ /** Where one beat falls on the film's timeline, in seconds. */
1399
+ interface PlacedBeat {
1400
+ /** The first moment of the recording. */
1401
+ start: number;
1402
+ /** The last moment of the recording. */
1403
+ end: number;
1404
+ /** The end of the silence after it. */
1405
+ until: number;
1406
+ text: string;
1407
+ words: readonly NarrationWord[];
1408
+ }
1409
+ /** Split spoken text into caption lines: by sentence, then by length. */
1410
+ declare function captionLines(text: string, length?: number): string[];
1411
+ /** The clock of one scene. Every time is in film seconds. */
1412
+ declare class SceneClock {
1413
+ private readonly stage;
1414
+ readonly id: string;
1415
+ readonly start: number;
1416
+ readonly end: number;
1417
+ readonly beats: readonly PlacedBeat[];
1418
+ constructor(stage: Stage, id: string, start: number, end: number, beats: readonly PlacedBeat[]);
1419
+ /** When the voice says a phrase. Pass a beat index to search one beat only. Throws if the phrase is not spoken. */
1420
+ cue(phrase: string, beat?: number): {
1421
+ start: number;
1422
+ end: number;
1423
+ };
1424
+ /** Build when the voice starts a phrase. `offset` moves it, in seconds. */
1425
+ on(phrase: string, build: () => void, offset?: number, beat?: number): this;
1426
+ /** Build when the voice finishes a phrase. */
1427
+ after(phrase: string, build: () => void, offset?: number, beat?: number): this;
1428
+ /** Build when a beat starts. */
1429
+ onBeat(index: number, build: () => void, offset?: number): this;
1430
+ /** Build at a time counted from the start of the scene. */
1431
+ at(seconds: number, build: () => void): this;
1432
+ /** Fade nodes out just before the scene ends, so the next picture starts on a clean frame. */
1433
+ clear(nodes: readonly Node[], lead?: number, duration?: number): this;
1434
+ }
1435
+ /** The timeline of a whole narration. */
1436
+ declare class Narration {
1437
+ readonly scenes: readonly SceneClock[];
1438
+ /** The end of the last scene, in seconds. Hold the film at least this long, or the voice is cut. */
1439
+ readonly duration: number;
1440
+ readonly lead: number;
1441
+ readonly gap: number;
1442
+ constructor(stage: Stage, timing: NarrationTiming, options?: NarrationOptions);
1443
+ /** The clock of one scene. */
1444
+ scene(id: string): SceneClock;
1445
+ /** Where every beat's recording starts, in order, for the script that mixes the sound. */
1446
+ placements(): {
1447
+ scene: string;
1448
+ beat: number;
1449
+ start: number;
1450
+ end: number;
1451
+ }[];
1452
+ }
1453
+ /**
1454
+ * Lay a measured narration on the stage. Each scene gets a clock with phrase cues.
1455
+ * Captions and chapters are added to the film, so the MP4 carries them.
1456
+ */
1457
+ declare function narration(stage: Stage, timing: NarrationTiming, options?: NarrationOptions): Narration;
1458
+
1344
1459
  /**
1345
1460
  * 3D on the stage: a camera, meshes, curves, and points, all projected to paths
1346
1461
  * on every frame and drawn back to front. There is no GPU dependency, so the
@@ -1561,6 +1676,7 @@ declare class Vector3D extends Line3D {
1561
1676
  private readonly from3;
1562
1677
  private readonly to3;
1563
1678
  private readonly tipSize;
1679
+ private readonly tipBias;
1564
1680
  constructor(from: Reactive3, to: Reactive3, style?: Line3DStyle & {
1565
1681
  tip?: number;
1566
1682
  });
@@ -1577,6 +1693,8 @@ interface Points3DStyle {
1577
1693
  radius?: number;
1578
1694
  opacity?: number;
1579
1695
  onTop?: boolean;
1696
+ /** Nudge toward the camera so a point resting on a surface is not cut by it. */
1697
+ bias?: number;
1580
1698
  /** Soft ring around each point. */
1581
1699
  halo?: number;
1582
1700
  }
@@ -1675,5 +1793,5 @@ declare function label3d(content: string | Node, position: Reactive3, options?:
1675
1793
  offset?: Vec;
1676
1794
  }): Label3D;
1677
1795
 
1678
- export { Anim, AnimOptions, ArrayCells, Axes, Axes3D, BarChart, Bounds, Callout, CodeBlock, ColorInput, CompileOverrides, CompiledFilm, ComplexPlane, Connector, Counter, Curve3D, Edge, Epicycles, FilmDefinition, Graph, GraphEdge, GraphNode, GridPlane3D, Heatmap, Histogram, InfoBox, Label3D, LabeledDot, Line3D, LineChart, Mat, MatrixNode, NeuralNet, Node, NumberLine, NumberPlane, Object3D, Path, PathOp, PieChart, Points3D, Rgba, Scatter, Scene3D, Side, StreamLines, Surface3D, Target, TexNode, TextNode, TokenRow, Trail3D, TreeGraph, Value, Vec, Vector3D, VectorField, View3D, angleMark, applyComplex, arc, areaUnder, arrayCells, arrow, attentionMatrix, axes, axes3d, barChart, brace, braceLabel, callout, checkFilm, circle, codeBlock, complex, complexPlane, connector, countUp, counter, curve, curve3d, dashedGuides, decimal, donut, dot, ellipse, epicycles, fontFor, fourier, fourierPoint, glyphPath, graph, gridPlane3d, heatmap, highlightSweep, histogram, infoBox, label3d, labeledDot, legend, line, line3d, lineChart, matrix, morphCode, neuralNet, numberLine, parametric, parametricSurface, parseFont, pie, plane, point3d, points3d, polygon, polyline, rect, regularPolygon, riemann, rightAngle, ringThrough, samplePath, scatter, scene3d, secantLine, setAssetBase, shape, sparkline, sphere, spin, streamLines, surface, surroundingBox, svgPath, swap, tangentLine, tex, text, tokenize, tokens, traced, trail3d, tree, typewriter, vector3d, vectorField, wipe };
1679
- export type { AngleOptions, AreaOptions, ArrayCellsOptions, ArrowStyle, AttentionMatrixOptions, Axes3DOptions, AxesOptions, BarChartOptions, BarDatum, BraceLabelOptions, CalloutOptions, ChartOptions, CodeBlockOptions, CodeToken, ComplexPlaneOptions, ConnectorEnd, ConnectorOptions, CounterOptions, DecimalOptions, EpicyclesOptions, FieldFn, FilmCheckOptions, FilmCheckReport, FilmDiagnostic, FilmDiagnosticCode, FontFamily, FontWeight, FourierTerm, GraphEdgeSpec, GraphNodeSpec, GraphOptions, GridPlaneOptions, HeatmapOptions, HighlightOptions, HistogramOptions, InfoBoxOptions, InfoRow, LabeledDotOptions, LegendItem, LegendOptions, Line3DStyle, LineChartOptions, LineSeries, LoadedFont, MatrixOptions, NeuralNetOptions, NumberLineOptions, ParametricFn, PieDatum, PieOptions, PlaneOptions, Points3DStyle, RiemannOptions, ScatterOptions, ScatterPoint, Scene3DOptions, SecantOptions, ShapeStyle, SparklineOptions, StreamLinesOptions, SurfaceOptions, SurroundOptions, TangentOptions, TexOptions, TextOptions, TokenKind, TokenSpec, TokensOptions, TracedOptions, TreeOptions, TreeSpec, TypewriterOptions, Vec3, VectorFieldOptions, WipeOptions };
1796
+ export { Anim, AnimOptions, ArrayCells, Axes, Axes3D, BarChart, Bounds, Callout, CodeBlock, ColorInput, CompileOverrides, CompiledFilm, ComplexPlane, Connector, Counter, Curve3D, Edge, Epicycles, FilmDefinition, Graph, GraphEdge, GraphNode, GridPlane3D, Heatmap, Histogram, InfoBox, Label3D, LabeledDot, Line3D, LineChart, Mat, MatrixNode, Narration, NeuralNet, Node, NumberLine, NumberPlane, Object3D, Path, PathOp, PieChart, Points3D, Rgba, Scatter, Scene3D, SceneClock, Side, Stage, StreamLines, Surface3D, Target, TexNode, TextNode, TokenRow, Trail3D, TreeGraph, Value, Vec, Vector3D, VectorField, View3D, angleMark, applyComplex, arc, areaUnder, arrayCells, arrow, attentionMatrix, axes, axes3d, barChart, brace, braceLabel, callout, captionLines, checkFilm, circle, codeBlock, complex, complexPlane, connector, countUp, counter, curve, curve3d, dashedGuides, decimal, donut, dot, ellipse, epicycles, fontFor, fourier, fourierPoint, glyphPath, graph, gridPlane3d, heatmap, highlightSweep, histogram, image, infoBox, label3d, labeledDot, legend, line, line3d, lineChart, matrix, morphCode, narration, neuralNet, numberLine, parametric, parametricSurface, parseFont, pie, plane, point3d, points3d, polygon, polyline, rect, regularPolygon, riemann, rightAngle, ringThrough, samplePath, scatter, scene3d, secantLine, setAssetBase, shape, sparkline, sphere, spin, streamLines, surface, surroundingBox, svgPath, swap, tangentLine, tex, text, tokenize, tokens, traced, trail3d, tree, typewriter, vector3d, vectorField, wipe };
1797
+ export type { AngleOptions, AreaOptions, ArrayCellsOptions, ArrowStyle, AttentionMatrixOptions, Axes3DOptions, AxesOptions, BarChartOptions, BarDatum, BraceLabelOptions, CalloutOptions, ChartOptions, CodeBlockOptions, CodeToken, ComplexPlaneOptions, ConnectorEnd, ConnectorOptions, CounterOptions, DecimalOptions, EpicyclesOptions, FieldFn, FilmCheckOptions, FilmCheckReport, FilmDiagnostic, FilmDiagnosticCode, FontFamily, FontWeight, FourierTerm, GraphEdgeSpec, GraphNodeSpec, GraphOptions, GridPlaneOptions, HeatmapOptions, HighlightOptions, HistogramOptions, ImageOptions, InfoBoxOptions, InfoRow, LabeledDotOptions, LegendItem, LegendOptions, Line3DStyle, LineChartOptions, LineSeries, LoadedFont, MatrixOptions, NarrationBeat, NarrationOptions, NarrationScene, NarrationTiming, NarrationWord, NeuralNetOptions, NumberLineOptions, ParametricFn, PieDatum, PieOptions, PlacedBeat, PlaneOptions, Points3DStyle, RiemannOptions, ScatterOptions, ScatterPoint, Scene3DOptions, SecantOptions, ShapeStyle, SparklineOptions, StreamLinesOptions, SurfaceOptions, SurroundOptions, TangentOptions, TexOptions, TextOptions, TokenKind, TokenSpec, TokensOptions, TracedOptions, TreeOptions, TreeSpec, TypewriterOptions, Vec3, VectorFieldOptions, WipeOptions };
package/dist/stage.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- import { P as Path, N as Node, c as ColorInput, V as Vec, C as CompileOverrides, B as Bounds, b as FilmDefinition, a as CompiledFilm, d as Side, A as AnimOptions, e as Anim, f as Value, R as Rgba, E as Edge, T as Target, g as PathOp, M as Mat } from './svg-import-Djj2q7Pc.js';
2
- export { h as AnimContext, i as Aspect, j as BlendMode, k as Canvas2D, l as Caption, m as Chapter, n as Clip, D as DrawOp, o as EMPTY_BOUNDS, p as Ease, q as FadeOptions, r as FilmOptions, s as Frame, F as FromSvgOptions, G as Gradient, I as IDENTITY, t as ImageOp, L as LOOKS, u as Look, v as LookName, w as LookToken, x as NodeProps, y as Paint, z as PlayOptions, H as PropName, J as Ring, K as Stage, O as StageImage, Q as Suspend, S as SvgNode, U as along, W as appear, X as apply, Y as applyMatrix, Z as arcPath, _ as blueprint, $ as bounce, a0 as buildOps, a1 as call, a2 as chalk, a3 as circlePath, a4 as circumscribe, a5 as colorAlong, a6 as compileFilm, a7 as compose, a8 as concat, a9 as css, aa as cubicBezier, ab as curveThrough, ac as delay, ad as draw, ae as during, af as dynamic, ag as easeInCubic, ah as easeInExpo, ai as easeInOutCubic, aj as easeInOutQuint, ak as easeInQuad, al as easeOutCubic, am as easeOutExpo, an as easeOutQuad, ao as easeOutQuint, ap as erase, aq as fade, ar as fadeIn, as as fadeOut, at as film, au as flash, av as frameInkBounds, aw as frameToSvg, ax as fromSvg, ay as group, az as grow, aA as indicate, aB as invert, aC as isFilm, aD as isSuspend, aE as lagged, aF as linePath, aG as linear, aH as linearGradient, aI as lingering, aJ as matScale, aK as midnight, aL as mixColor, aM as morph, aN as morphMatching, aO as moveTo, aP as mul, aQ as neon, aR as notQuiteThere, aS as overshoot, aT as paintFrame, aU as paper, aV as par, aW as parametricPath, aX as parseColor, aY as parseSvgPath, aZ as pathBounds, a_ as pathLength, a$ as pathToD, b0 as pointAt, b1 as polyPath, b2 as pulse, b3 as radialGradient, b4 as ramp, b5 as recolor, b6 as rectPath, b7 as resolveLook, b8 as retime, b9 as reverseRing, ba as ring, bb as ringCenter, bc as ringLength, bd as ripple, be as rotate, bf as runningStart, bg as rushFrom, bh as rushInto, bi as scaleBy, bj as segmentCount, bk as seq, bl as shake, bm as shift, bn as signedArea, bo as slowInto, bp as smooth, bq as smoothBy, br as smoothPath, bs as smoother, bt as spring, bu as subdivideEach, bv as tangentAt, bw as thereAndBack, bx as thereAndBackWithPause, by as to, bz as toPaint, bA as transformPath, bB as trimPath, bC as trimRing, bD as unionBounds, bE as vanish, bF as warp, bG as warpPath, bH as wiggle, bI as write } from './svg-import-Djj2q7Pc.js';
1
+ import { P as Path, N as Node, c as ColorInput, V as Vec, C as CompileOverrides, B as Bounds, b as FilmDefinition, a as CompiledFilm, d as Side, A as AnimOptions, e as Anim, f as Value, R as Rgba, E as Edge, T as Target, g as Stage, h as PathOp, M as Mat } from './svg-import-5_oTbEJR.js';
2
+ export { i as AnimContext, j as Aspect, k as BlendMode, l as Canvas2D, m as Caption, n as Chapter, o as Clip, D as DrawOp, p as EMPTY_BOUNDS, q as Ease, r as FadeOptions, s as FilmOptions, t as Frame, F as FromSvgOptions, G as Gradient, I as IDENTITY, u as ImageOp, L as LOOKS, v as Look, w as LookName, x as LookToken, y as NodeProps, z as Paint, H as PlayOptions, J as PropName, K as Ring, O as StageImage, Q as Suspend, S as SvgNode, U as along, W as appear, X as apply, Y as applyMatrix, Z as arcPath, _ as blueprint, $ as bounce, a0 as buildOps, a1 as call, a2 as chalk, a3 as circlePath, a4 as circumscribe, a5 as colorAlong, a6 as compileFilm, a7 as compose, a8 as concat, a9 as css, aa as cubicBezier, ab as curveThrough, ac as delay, ad as draw, ae as during, af as dynamic, ag as easeInCubic, ah as easeInExpo, ai as easeInOutCubic, aj as easeInOutQuint, ak as easeInQuad, al as easeOutCubic, am as easeOutExpo, an as easeOutQuad, ao as easeOutQuint, ap as erase, aq as fade, ar as fadeIn, as as fadeOut, at as film, au as flash, av as frameInkBounds, aw as frameToSvg, ax as fromSvg, ay as group, az as grow, aA as indicate, aB as invert, aC as isFilm, aD as isSuspend, aE as lagged, aF as linePath, aG as linear, aH as linearGradient, aI as lingering, aJ as matScale, aK as midnight, aL as mixColor, aM as morph, aN as morphMatching, aO as moveTo, aP as mul, aQ as neon, aR as notQuiteThere, aS as overshoot, aT as paintFrame, aU as paper, aV as par, aW as parametricPath, aX as parseColor, aY as parseSvgPath, aZ as pathBounds, a_ as pathLength, a$ as pathToD, b0 as pointAt, b1 as polyPath, b2 as pulse, b3 as radialGradient, b4 as ramp, b5 as recolor, b6 as rectPath, b7 as resolveLook, b8 as retime, b9 as reverseRing, ba as ring, bb as ringCenter, bc as ringLength, bd as ripple, be as rotate, bf as runningStart, bg as rushFrom, bh as rushInto, bi as scaleBy, bj as segmentCount, bk as seq, bl as shake, bm as shift, bn as signedArea, bo as slowInto, bp as smooth, bq as smoothBy, br as smoothPath, bs as smoother, bt as spring, bu as subdivideEach, bv as tangentAt, bw as thereAndBack, bx as thereAndBackWithPause, by as to, bz as toPaint, bA as transformPath, bB as trimPath, bC as trimRing, bD as unionBounds, bE as vanish, bF as warp, bG as warpPath, bH as wiggle, bI as write } from './svg-import-5_oTbEJR.js';
3
3
 
4
4
  interface GlyphOutline {
5
5
  /** Each contour is a closed cubic ring in font units, with y pointing up. */
@@ -104,6 +104,18 @@ declare function rect(width: number, height: number, style?: ShapeStyle & {
104
104
  }): Node;
105
105
  declare function polygon(points: readonly Vec[], style?: ShapeStyle): Node;
106
106
  declare function regularPolygon(sides: number, radius: number, style?: ShapeStyle): Node;
107
+ interface ImageOptions {
108
+ /** Width on the stage. With only one of width and height, the other keeps the picture's proportions. */
109
+ width?: number;
110
+ height?: number;
111
+ opacity?: number;
112
+ }
113
+ /**
114
+ * A raster picture, such as a logo or a photo, centered on its origin. `src` is a URL or a
115
+ * data URL. A data URL keeps a film in one file and renders the same in every tool.
116
+ * It fades, moves, and scales like any node. Give `width`, `height`, or both.
117
+ */
118
+ declare function image(src: string, options?: ImageOptions): Node;
107
119
  /** A filled point. */
108
120
  declare function dot(radius?: number, color?: ColorInput, style?: ShapeStyle): Node;
109
121
  interface ArrowStyle extends ShapeStyle {
@@ -1341,6 +1353,109 @@ declare function highlightSweep(target: Node | readonly Node[], options?: Highli
1341
1353
  mark: Node;
1342
1354
  };
1343
1355
 
1356
+ /** One spoken word, timed in seconds from the start of its beat. */
1357
+ interface NarrationWord {
1358
+ text: string;
1359
+ start: number;
1360
+ end: number;
1361
+ }
1362
+ /** One take of the voice: a sentence or a short paragraph. */
1363
+ interface NarrationBeat {
1364
+ /** The text that the voice speaks. Captions use it. */
1365
+ say: string;
1366
+ /** Measured length of the recording, in seconds. */
1367
+ duration: number;
1368
+ /** Silence after the beat, in seconds, for the viewer to think. */
1369
+ hold?: number;
1370
+ /** Word times, from the speech engine or from a transcription. Cues need them. */
1371
+ words?: readonly NarrationWord[];
1372
+ }
1373
+ interface NarrationScene {
1374
+ id: string;
1375
+ /** Chapter title. A scene without one does not start a chapter. */
1376
+ title?: string;
1377
+ beats: readonly NarrationBeat[];
1378
+ }
1379
+ interface NarrationTiming {
1380
+ scenes: readonly NarrationScene[];
1381
+ /** Seconds before the first word. `NarrationOptions.lead` overrides it. */
1382
+ lead?: number;
1383
+ /** Seconds of silence between scenes. `NarrationOptions.gap` overrides it. */
1384
+ gap?: number;
1385
+ }
1386
+ interface NarrationOptions {
1387
+ /** Seconds before the first word, for a logo or an opening picture. Defaults to 0.6. */
1388
+ lead?: number;
1389
+ /** Seconds of silence between scenes, for the picture to change. Defaults to 0.4. */
1390
+ gap?: number;
1391
+ /** Write a caption for each spoken line. On by default. */
1392
+ captions?: boolean;
1393
+ /** Longest caption line, in characters. Defaults to 74. */
1394
+ captionLength?: number;
1395
+ /** Start a chapter at each scene that has a title. On by default. */
1396
+ chapters?: boolean;
1397
+ }
1398
+ /** Where one beat falls on the film's timeline, in seconds. */
1399
+ interface PlacedBeat {
1400
+ /** The first moment of the recording. */
1401
+ start: number;
1402
+ /** The last moment of the recording. */
1403
+ end: number;
1404
+ /** The end of the silence after it. */
1405
+ until: number;
1406
+ text: string;
1407
+ words: readonly NarrationWord[];
1408
+ }
1409
+ /** Split spoken text into caption lines: by sentence, then by length. */
1410
+ declare function captionLines(text: string, length?: number): string[];
1411
+ /** The clock of one scene. Every time is in film seconds. */
1412
+ declare class SceneClock {
1413
+ private readonly stage;
1414
+ readonly id: string;
1415
+ readonly start: number;
1416
+ readonly end: number;
1417
+ readonly beats: readonly PlacedBeat[];
1418
+ constructor(stage: Stage, id: string, start: number, end: number, beats: readonly PlacedBeat[]);
1419
+ /** When the voice says a phrase. Pass a beat index to search one beat only. Throws if the phrase is not spoken. */
1420
+ cue(phrase: string, beat?: number): {
1421
+ start: number;
1422
+ end: number;
1423
+ };
1424
+ /** Build when the voice starts a phrase. `offset` moves it, in seconds. */
1425
+ on(phrase: string, build: () => void, offset?: number, beat?: number): this;
1426
+ /** Build when the voice finishes a phrase. */
1427
+ after(phrase: string, build: () => void, offset?: number, beat?: number): this;
1428
+ /** Build when a beat starts. */
1429
+ onBeat(index: number, build: () => void, offset?: number): this;
1430
+ /** Build at a time counted from the start of the scene. */
1431
+ at(seconds: number, build: () => void): this;
1432
+ /** Fade nodes out just before the scene ends, so the next picture starts on a clean frame. */
1433
+ clear(nodes: readonly Node[], lead?: number, duration?: number): this;
1434
+ }
1435
+ /** The timeline of a whole narration. */
1436
+ declare class Narration {
1437
+ readonly scenes: readonly SceneClock[];
1438
+ /** The end of the last scene, in seconds. Hold the film at least this long, or the voice is cut. */
1439
+ readonly duration: number;
1440
+ readonly lead: number;
1441
+ readonly gap: number;
1442
+ constructor(stage: Stage, timing: NarrationTiming, options?: NarrationOptions);
1443
+ /** The clock of one scene. */
1444
+ scene(id: string): SceneClock;
1445
+ /** Where every beat's recording starts, in order, for the script that mixes the sound. */
1446
+ placements(): {
1447
+ scene: string;
1448
+ beat: number;
1449
+ start: number;
1450
+ end: number;
1451
+ }[];
1452
+ }
1453
+ /**
1454
+ * Lay a measured narration on the stage. Each scene gets a clock with phrase cues.
1455
+ * Captions and chapters are added to the film, so the MP4 carries them.
1456
+ */
1457
+ declare function narration(stage: Stage, timing: NarrationTiming, options?: NarrationOptions): Narration;
1458
+
1344
1459
  /**
1345
1460
  * 3D on the stage: a camera, meshes, curves, and points, all projected to paths
1346
1461
  * on every frame and drawn back to front. There is no GPU dependency, so the
@@ -1561,6 +1676,7 @@ declare class Vector3D extends Line3D {
1561
1676
  private readonly from3;
1562
1677
  private readonly to3;
1563
1678
  private readonly tipSize;
1679
+ private readonly tipBias;
1564
1680
  constructor(from: Reactive3, to: Reactive3, style?: Line3DStyle & {
1565
1681
  tip?: number;
1566
1682
  });
@@ -1577,6 +1693,8 @@ interface Points3DStyle {
1577
1693
  radius?: number;
1578
1694
  opacity?: number;
1579
1695
  onTop?: boolean;
1696
+ /** Nudge toward the camera so a point resting on a surface is not cut by it. */
1697
+ bias?: number;
1580
1698
  /** Soft ring around each point. */
1581
1699
  halo?: number;
1582
1700
  }
@@ -1675,5 +1793,5 @@ declare function label3d(content: string | Node, position: Reactive3, options?:
1675
1793
  offset?: Vec;
1676
1794
  }): Label3D;
1677
1795
 
1678
- export { Anim, AnimOptions, ArrayCells, Axes, Axes3D, BarChart, Bounds, Callout, CodeBlock, ColorInput, CompileOverrides, CompiledFilm, ComplexPlane, Connector, Counter, Curve3D, Edge, Epicycles, FilmDefinition, Graph, GraphEdge, GraphNode, GridPlane3D, Heatmap, Histogram, InfoBox, Label3D, LabeledDot, Line3D, LineChart, Mat, MatrixNode, NeuralNet, Node, NumberLine, NumberPlane, Object3D, Path, PathOp, PieChart, Points3D, Rgba, Scatter, Scene3D, Side, StreamLines, Surface3D, Target, TexNode, TextNode, TokenRow, Trail3D, TreeGraph, Value, Vec, Vector3D, VectorField, View3D, angleMark, applyComplex, arc, areaUnder, arrayCells, arrow, attentionMatrix, axes, axes3d, barChart, brace, braceLabel, callout, checkFilm, circle, codeBlock, complex, complexPlane, connector, countUp, counter, curve, curve3d, dashedGuides, decimal, donut, dot, ellipse, epicycles, fontFor, fourier, fourierPoint, glyphPath, graph, gridPlane3d, heatmap, highlightSweep, histogram, infoBox, label3d, labeledDot, legend, line, line3d, lineChart, matrix, morphCode, neuralNet, numberLine, parametric, parametricSurface, parseFont, pie, plane, point3d, points3d, polygon, polyline, rect, regularPolygon, riemann, rightAngle, ringThrough, samplePath, scatter, scene3d, secantLine, setAssetBase, shape, sparkline, sphere, spin, streamLines, surface, surroundingBox, svgPath, swap, tangentLine, tex, text, tokenize, tokens, traced, trail3d, tree, typewriter, vector3d, vectorField, wipe };
1679
- export type { AngleOptions, AreaOptions, ArrayCellsOptions, ArrowStyle, AttentionMatrixOptions, Axes3DOptions, AxesOptions, BarChartOptions, BarDatum, BraceLabelOptions, CalloutOptions, ChartOptions, CodeBlockOptions, CodeToken, ComplexPlaneOptions, ConnectorEnd, ConnectorOptions, CounterOptions, DecimalOptions, EpicyclesOptions, FieldFn, FilmCheckOptions, FilmCheckReport, FilmDiagnostic, FilmDiagnosticCode, FontFamily, FontWeight, FourierTerm, GraphEdgeSpec, GraphNodeSpec, GraphOptions, GridPlaneOptions, HeatmapOptions, HighlightOptions, HistogramOptions, InfoBoxOptions, InfoRow, LabeledDotOptions, LegendItem, LegendOptions, Line3DStyle, LineChartOptions, LineSeries, LoadedFont, MatrixOptions, NeuralNetOptions, NumberLineOptions, ParametricFn, PieDatum, PieOptions, PlaneOptions, Points3DStyle, RiemannOptions, ScatterOptions, ScatterPoint, Scene3DOptions, SecantOptions, ShapeStyle, SparklineOptions, StreamLinesOptions, SurfaceOptions, SurroundOptions, TangentOptions, TexOptions, TextOptions, TokenKind, TokenSpec, TokensOptions, TracedOptions, TreeOptions, TreeSpec, TypewriterOptions, Vec3, VectorFieldOptions, WipeOptions };
1796
+ export { Anim, AnimOptions, ArrayCells, Axes, Axes3D, BarChart, Bounds, Callout, CodeBlock, ColorInput, CompileOverrides, CompiledFilm, ComplexPlane, Connector, Counter, Curve3D, Edge, Epicycles, FilmDefinition, Graph, GraphEdge, GraphNode, GridPlane3D, Heatmap, Histogram, InfoBox, Label3D, LabeledDot, Line3D, LineChart, Mat, MatrixNode, Narration, NeuralNet, Node, NumberLine, NumberPlane, Object3D, Path, PathOp, PieChart, Points3D, Rgba, Scatter, Scene3D, SceneClock, Side, Stage, StreamLines, Surface3D, Target, TexNode, TextNode, TokenRow, Trail3D, TreeGraph, Value, Vec, Vector3D, VectorField, View3D, angleMark, applyComplex, arc, areaUnder, arrayCells, arrow, attentionMatrix, axes, axes3d, barChart, brace, braceLabel, callout, captionLines, checkFilm, circle, codeBlock, complex, complexPlane, connector, countUp, counter, curve, curve3d, dashedGuides, decimal, donut, dot, ellipse, epicycles, fontFor, fourier, fourierPoint, glyphPath, graph, gridPlane3d, heatmap, highlightSweep, histogram, image, infoBox, label3d, labeledDot, legend, line, line3d, lineChart, matrix, morphCode, narration, neuralNet, numberLine, parametric, parametricSurface, parseFont, pie, plane, point3d, points3d, polygon, polyline, rect, regularPolygon, riemann, rightAngle, ringThrough, samplePath, scatter, scene3d, secantLine, setAssetBase, shape, sparkline, sphere, spin, streamLines, surface, surroundingBox, svgPath, swap, tangentLine, tex, text, tokenize, tokens, traced, trail3d, tree, typewriter, vector3d, vectorField, wipe };
1797
+ export type { AngleOptions, AreaOptions, ArrayCellsOptions, ArrowStyle, AttentionMatrixOptions, Axes3DOptions, AxesOptions, BarChartOptions, BarDatum, BraceLabelOptions, CalloutOptions, ChartOptions, CodeBlockOptions, CodeToken, ComplexPlaneOptions, ConnectorEnd, ConnectorOptions, CounterOptions, DecimalOptions, EpicyclesOptions, FieldFn, FilmCheckOptions, FilmCheckReport, FilmDiagnostic, FilmDiagnosticCode, FontFamily, FontWeight, FourierTerm, GraphEdgeSpec, GraphNodeSpec, GraphOptions, GridPlaneOptions, HeatmapOptions, HighlightOptions, HistogramOptions, ImageOptions, InfoBoxOptions, InfoRow, LabeledDotOptions, LegendItem, LegendOptions, Line3DStyle, LineChartOptions, LineSeries, LoadedFont, MatrixOptions, NarrationBeat, NarrationOptions, NarrationScene, NarrationTiming, NarrationWord, NeuralNetOptions, NumberLineOptions, ParametricFn, PieDatum, PieOptions, PlacedBeat, PlaneOptions, Points3DStyle, RiemannOptions, ScatterOptions, ScatterPoint, Scene3DOptions, SecantOptions, ShapeStyle, SparklineOptions, StreamLinesOptions, SurfaceOptions, SurroundOptions, TangentOptions, TexOptions, TextOptions, TokenKind, TokenSpec, TokensOptions, TracedOptions, TreeOptions, TreeSpec, TypewriterOptions, Vec3, VectorFieldOptions, WipeOptions };
package/dist/stage.js CHANGED
@@ -357,6 +357,45 @@ function regularPolygon(sides, radius, style = {}) {
357
357
  }
358
358
  return polygon(points, style);
359
359
  }
360
+ function intrinsicSize(src) {
361
+ const match = /^data:image\/(png|gif|jpeg|jpg);base64,/.exec(src);
362
+ if (!match || typeof atob !== "function") return null;
363
+ let head;
364
+ try {
365
+ head = atob(src.slice(match[0].length, match[0].length + (match[1] === "jpeg" || match[1] === "jpg" ? 87384 : 44)));
366
+ } catch {
367
+ return null;
368
+ }
369
+ const byte = (i) => head.charCodeAt(i);
370
+ if (match[1] === "png") return head.length >= 24 ? [byte(16) * 16777216 + byte(17) * 65536 + byte(18) * 256 + byte(19), byte(20) * 16777216 + byte(21) * 65536 + byte(22) * 256 + byte(23)] : null;
371
+ if (match[1] === "gif") return head.length >= 10 ? [byte(6) + byte(7) * 256, byte(8) + byte(9) * 256] : null;
372
+ for (let i = 2; i + 9 < head.length; ) {
373
+ if (byte(i) !== 255) return null;
374
+ const marker = byte(i + 1);
375
+ if (marker >= 192 && marker <= 207 && marker !== 196 && marker !== 200 && marker !== 204) return [byte(i + 7) * 256 + byte(i + 8), byte(i + 5) * 256 + byte(i + 6)];
376
+ i += 2 + byte(i + 2) * 256 + byte(i + 3);
377
+ }
378
+ return null;
379
+ }
380
+ function image(src, options = {}) {
381
+ const natural = intrinsicSize(src);
382
+ let width = options.width, height = options.height;
383
+ if (width === void 0 && height === void 0) {
384
+ if (!natural) throw new Error("image() needs a width or a height when the picture is not a PNG, GIF, or JPEG data URL.");
385
+ [width, height] = natural;
386
+ } else if (width === void 0 || height === void 0) {
387
+ if (!natural) throw new Error("image() needs both width and height when the picture is not a PNG, GIF, or JPEG data URL.");
388
+ if (width === void 0) width = height * natural[0] / natural[1];
389
+ else height = width * natural[1] / natural[0];
390
+ }
391
+ if (!(width > 0) || !(height > 0)) throw new Error("image() needs a positive width and height.");
392
+ const picture = new Node().at(-width / 2, -height / 2);
393
+ picture.base.image = { src, width, height };
394
+ const out = new Node();
395
+ out.add(picture);
396
+ if (options.opacity !== void 0) out.opacity(options.opacity);
397
+ return out;
398
+ }
360
399
  function dot(radius = 9, color = "ink", style = {}) {
361
400
  return styled(new Node(circlePath(0, 0, radius)), style, { fill: color });
362
401
  }
@@ -3138,7 +3177,7 @@ var CodeBlock = class extends Node {
3138
3177
  const font = fontFor("mono", 400);
3139
3178
  const scale = size / font.unitsPerEm;
3140
3179
  const advance = font.advance(font.glyphFor(48)) * scale;
3141
- const tokens2 = tokenize(source, options.language ?? "ts");
3180
+ const tokens3 = tokenize(source, options.language ?? "ts");
3142
3181
  const rows = source.split("\n");
3143
3182
  const gutter = options.lineNumbers ? (String(rows.length).length + 2) * advance : 0;
3144
3183
  const pad2 = options.padding ?? size * 0.9;
@@ -3170,7 +3209,7 @@ var CodeBlock = class extends Node {
3170
3209
  }
3171
3210
  const colors = { ...CODE_COLORS, ...options.colors };
3172
3211
  const column = /* @__PURE__ */ new Map();
3173
- for (const token of tokens2) {
3212
+ for (const token of tokens3) {
3174
3213
  const start = column.get(token.line) ?? 0;
3175
3214
  column.set(token.line, start + token.text.length);
3176
3215
  const entry = { ...token, glyphs: [] };
@@ -4184,6 +4223,144 @@ function highlightSweep(target, options = {}) {
4184
4223
  };
4185
4224
  }
4186
4225
 
4226
+ // src/stage/narration.ts
4227
+ var tokens2 = (text2) => text2.toLowerCase().replace(/[^a-z0-9.]+/g, " ").split(" ").map((token) => token.replace(/^\.+|\.+$/g, "")).filter(Boolean);
4228
+ function captionLines(text2, length = 74) {
4229
+ const lines = [];
4230
+ for (const sentence of text2.match(/[^.?!]+(?:[.?!]+(?=\s|$)|\.\d[^.?!]*[.?!]?|$)/g) ?? []) {
4231
+ let line2 = "";
4232
+ for (const word of sentence.split(/\s+/).filter(Boolean)) {
4233
+ if (line2 && line2.length + word.length + 1 > length) {
4234
+ lines.push(line2);
4235
+ line2 = word;
4236
+ } else {
4237
+ line2 = line2 ? `${line2} ${word}` : word;
4238
+ }
4239
+ }
4240
+ if (line2) lines.push(line2);
4241
+ }
4242
+ return lines;
4243
+ }
4244
+ var SceneClock = class {
4245
+ constructor(stage, id, start, end, beats) {
4246
+ this.stage = stage;
4247
+ this.id = id;
4248
+ this.start = start;
4249
+ this.end = end;
4250
+ this.beats = beats;
4251
+ }
4252
+ stage;
4253
+ id;
4254
+ start;
4255
+ end;
4256
+ beats;
4257
+ /** When the voice says a phrase. Pass a beat index to search one beat only. Throws if the phrase is not spoken. */
4258
+ cue(phrase, beat) {
4259
+ const want = tokens2(phrase);
4260
+ if (want.length === 0) throw new Error(`narration: scene "${this.id}": a cue needs at least one word`);
4261
+ if (beat !== void 0 && !this.beats[beat]) throw new Error(`narration: scene "${this.id}" has no beat ${beat}`);
4262
+ const list2 = beat === void 0 ? this.beats : [this.beats[beat]];
4263
+ for (const placed of list2) {
4264
+ const spoken = placed.words.flatMap((word) => tokens2(word.text).map((token) => ({ token, start: word.start, end: word.end })));
4265
+ for (let i = 0; i + want.length <= spoken.length; i++) {
4266
+ if (want.every((token, j) => spoken[i + j].token === token)) {
4267
+ return { start: placed.start + spoken[i].start, end: placed.start + spoken[i + want.length - 1].end };
4268
+ }
4269
+ }
4270
+ }
4271
+ const where = beat === void 0 ? "" : ` in beat ${beat}`;
4272
+ throw new Error(`narration: scene "${this.id}": the voice never says "${phrase}"${where}`);
4273
+ }
4274
+ /** Build when the voice starts a phrase. `offset` moves it, in seconds. */
4275
+ on(phrase, build, offset = 0, beat) {
4276
+ this.stage.at(Math.max(0, this.cue(phrase, beat).start + offset), build);
4277
+ return this;
4278
+ }
4279
+ /** Build when the voice finishes a phrase. */
4280
+ after(phrase, build, offset = 0, beat) {
4281
+ this.stage.at(Math.max(0, this.cue(phrase, beat).end + offset), build);
4282
+ return this;
4283
+ }
4284
+ /** Build when a beat starts. */
4285
+ onBeat(index, build, offset = 0) {
4286
+ const beat = this.beats[index];
4287
+ if (!beat) throw new Error(`narration: scene "${this.id}" has no beat ${index}`);
4288
+ this.stage.at(Math.max(0, beat.start + offset), build);
4289
+ return this;
4290
+ }
4291
+ /** Build at a time counted from the start of the scene. */
4292
+ at(seconds, build) {
4293
+ this.stage.at(Math.max(0, this.start + seconds), build);
4294
+ return this;
4295
+ }
4296
+ /** Fade nodes out just before the scene ends, so the next picture starts on a clean frame. */
4297
+ clear(nodes, lead = 0.24, duration = 0.26) {
4298
+ this.stage.at(this.end - lead, () => this.stage.play(...nodes.map((node) => fade(node, 0, { duration }))));
4299
+ return this;
4300
+ }
4301
+ };
4302
+ var Narration = class {
4303
+ scenes;
4304
+ /** The end of the last scene, in seconds. Hold the film at least this long, or the voice is cut. */
4305
+ duration;
4306
+ lead;
4307
+ gap;
4308
+ constructor(stage, timing, options = {}) {
4309
+ this.lead = options.lead ?? timing.lead ?? 0.6;
4310
+ this.gap = options.gap ?? timing.gap ?? 0.4;
4311
+ if (!(this.lead >= 0) || !(this.gap >= 0)) throw new Error("narration: lead and gap must be zero or more seconds");
4312
+ const seen = /* @__PURE__ */ new Set();
4313
+ const scenes = [];
4314
+ let now = this.lead;
4315
+ let last = now;
4316
+ for (const scene of timing.scenes) {
4317
+ if (seen.has(scene.id)) throw new Error(`narration: two scenes are named "${scene.id}"`);
4318
+ seen.add(scene.id);
4319
+ const start = now;
4320
+ const beats = [];
4321
+ for (const beat of scene.beats) {
4322
+ if (!(beat.duration > 0)) throw new Error(`narration: scene "${scene.id}" has a beat without a measured duration: "${beat.say}"`);
4323
+ const hold = beat.hold ?? 0;
4324
+ beats.push({ start: now, end: now + beat.duration, until: now + beat.duration + hold, text: beat.say, words: beat.words ?? [] });
4325
+ now += beat.duration + hold;
4326
+ }
4327
+ scenes.push(new SceneClock(stage, scene.id, start, now, beats));
4328
+ if (options.chapters !== false && scene.title) stage.chapters.push({ title: scene.title, time: scenes.length === 1 ? 0 : start });
4329
+ if (options.captions !== false) {
4330
+ for (const beat of beats) {
4331
+ const lines = captionLines(beat.text, options.captionLength);
4332
+ const total = lines.reduce((sum, line2) => sum + line2.length, 0);
4333
+ let t0 = beat.start;
4334
+ for (const line2 of lines) {
4335
+ const t1 = t0 + (beat.end - beat.start) * line2.length / total;
4336
+ stage.captions.push({ t0, t1, text: line2 });
4337
+ t0 = t1;
4338
+ }
4339
+ }
4340
+ }
4341
+ last = now;
4342
+ now += this.gap;
4343
+ }
4344
+ this.scenes = scenes;
4345
+ this.duration = last;
4346
+ stage.at(last, () => {
4347
+ });
4348
+ }
4349
+ /** The clock of one scene. */
4350
+ scene(id) {
4351
+ const found = this.scenes.find((scene) => scene.id === id);
4352
+ if (!found) throw new Error(`narration: no scene "${id}". The scenes are: ${this.scenes.map((scene) => scene.id).join(", ")}`);
4353
+ return found;
4354
+ }
4355
+ /** Where every beat's recording starts, in order, for the script that mixes the sound. */
4356
+ placements() {
4357
+ return this.scenes.flatMap((scene) => scene.beats.map((beat, index) => ({ scene: scene.id, beat: index, start: beat.start, end: beat.end })));
4358
+ }
4359
+ };
4360
+ function narration(stage, timing, options = {}) {
4361
+ return new Narration(stage, timing, options);
4362
+ }
4363
+
4187
4364
  // src/stage/three/index.ts
4188
4365
  var read3 = (value) => typeof value === "function" ? value() : value;
4189
4366
  var normalize = (v) => {
@@ -4863,6 +5040,7 @@ var Vector3D = class extends Line3D {
4863
5040
  from3;
4864
5041
  to3;
4865
5042
  tipSize;
5043
+ tipBias;
4866
5044
  constructor(from, to2, style = {}) {
4867
5045
  super(from, () => {
4868
5046
  const a = read3(from), b = read3(to2);
@@ -4873,6 +5051,7 @@ var Vector3D = class extends Line3D {
4873
5051
  this.from3 = from;
4874
5052
  this.to3 = to2;
4875
5053
  this.tipSize = style.tip ?? 24;
5054
+ this.tipBias = style.onTop ? ON_TOP : style.bias ?? 0;
4876
5055
  }
4877
5056
  emit(view) {
4878
5057
  super.emit(view);
@@ -4891,7 +5070,7 @@ var Vector3D = class extends Line3D {
4891
5070
  const rgb = solidOf(this.get("stroke"));
4892
5071
  const color = view.fogged(rgb[0], rgb[1], rgb[2], depth);
4893
5072
  const ring2 = polygonRing([bx, by, bx - ux * size - uy * half, by - uy * size + ux * half, bx - ux * size + uy * half, by - uy * size - ux * half]);
4894
- view.push(fillOp([ring2], color, alpha, null, 0, 0), depth + 0.01);
5073
+ view.push(fillOp([ring2], color, alpha, null, 0, 0), depth + 0.01 + this.tipBias);
4895
5074
  }
4896
5075
  };
4897
5076
  function vector3d(from, to2, style = {}) {
@@ -4914,7 +5093,7 @@ var Points3D = class extends Object3D {
4914
5093
  const trim = this.get("trimTo");
4915
5094
  const shown = Math.ceil(points.length * trim);
4916
5095
  const base = solidOf(this.get("fill"));
4917
- const bias = this.style.onTop ? ON_TOP : 0;
5096
+ const bias = this.style.onTop ? ON_TOP : this.style.bias ?? 0;
4918
5097
  for (let i = 0; i < shown; i++) {
4919
5098
  const point = points[i];
4920
5099
  if (!view.project(point[0], point[1], point[2])) continue;
@@ -4973,13 +5152,23 @@ var Trail3D = class extends Object3D {
4973
5152
  const fade2 = this.style.fade ?? (tail !== void 0 ? 0 : 1);
4974
5153
  const bias = this.style.onTop ? ON_TOP : this.style.bias ?? 0;
4975
5154
  const glow = (this.style.glow ?? 0) * view.scale;
4976
- const piece = Math.max(1, Math.ceil((i1 - i0) / 48));
4977
- for (let i = i0; i < i1; i += piece) {
5155
+ const moved = [];
5156
+ let last = null;
5157
+ for (let k = i0; k <= i1; k++) {
5158
+ const p = this.sample(k, rate);
5159
+ if (last && Math.abs(p[0] - last[0]) + Math.abs(p[1] - last[1]) + Math.abs(p[2] - last[2]) < 1e-9) continue;
5160
+ moved.push(p);
5161
+ last = p;
5162
+ }
5163
+ const span = moved.length - 1;
5164
+ if (span < 1) return;
5165
+ const piece = Math.max(1, Math.ceil(span / 48));
5166
+ for (let i = 0; i < span; i += piece) {
4978
5167
  const coords = [];
4979
5168
  let depth = 0;
4980
5169
  let scale = 0;
4981
- for (let k = i; k <= Math.min(i1, i + piece); k++) {
4982
- const p = this.sample(k, rate);
5170
+ for (let k = i; k <= Math.min(span, i + piece); k++) {
5171
+ const p = moved[k];
4983
5172
  if (!view.project(p[0], p[1], p[2])) continue;
4984
5173
  coords.push([view.px, view.py]);
4985
5174
  depth += view.pz;
@@ -4988,7 +5177,7 @@ var Trail3D = class extends Object3D {
4988
5177
  if (coords.length < 2) continue;
4989
5178
  depth /= coords.length;
4990
5179
  scale /= coords.length;
4991
- const fraction = (i + piece / 2 - i0) / (i1 - i0);
5180
+ const fraction = Math.min(1, (i + piece / 2) / span);
4992
5181
  const light = fade2 + (1 - fade2) * Math.pow(fraction, 1.6);
4993
5182
  const color = view.fogged(base[0], base[1], base[2], depth);
4994
5183
  view.push(strokeOp([chain(coords)], color, alpha * light, width * scale, glow, "butt"), depth + bias);
@@ -5187,6 +5376,7 @@ export {
5187
5376
  Line3D,
5188
5377
  LineChart,
5189
5378
  MatrixNode,
5379
+ Narration,
5190
5380
  NeuralNet,
5191
5381
  Node,
5192
5382
  NumberLine,
@@ -5196,6 +5386,7 @@ export {
5196
5386
  Points3D,
5197
5387
  Scatter,
5198
5388
  Scene3D,
5389
+ SceneClock,
5199
5390
  Stage,
5200
5391
  StreamLines,
5201
5392
  Surface3D,
@@ -5232,6 +5423,7 @@ export {
5232
5423
  buildOps,
5233
5424
  call,
5234
5425
  callout,
5426
+ captionLines,
5235
5427
  chalk,
5236
5428
  checkFilm,
5237
5429
  circle,
@@ -5291,6 +5483,7 @@ export {
5291
5483
  heatmap,
5292
5484
  highlightSweep,
5293
5485
  histogram,
5486
+ image,
5294
5487
  indicate,
5295
5488
  infoBox,
5296
5489
  invert,
@@ -5316,6 +5509,7 @@ export {
5316
5509
  morphMatching,
5317
5510
  moveTo,
5318
5511
  mul,
5512
+ narration,
5319
5513
  neon,
5320
5514
  neuralNet,
5321
5515
  notQuiteThere,