vizmatic 0.7.1 → 0.7.3

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.
Files changed (35) hide show
  1. package/PROMPT.md +25 -1
  2. package/ROADMAP.md +1 -1
  3. package/dist/{chunk-DTD35LPT.js → chunk-F6QI6QJY.js} +60 -2
  4. package/dist/chunk-QVYHYC7T.js +88 -0
  5. package/dist/cli.js +10 -9
  6. package/dist/index.cjs +70 -3
  7. package/dist/index.d.cts +4 -2
  8. package/dist/index.d.ts +4 -2
  9. package/dist/index.js +14 -3
  10. package/dist/scene-cli.js +1 -1
  11. package/dist/stage-browser/browser.d.ts +144 -5
  12. package/dist/stage-browser/stage.js +5 -5
  13. package/dist/stage-export.cjs +67 -1
  14. package/dist/stage-export.d.cts +5 -1
  15. package/dist/stage-export.d.ts +5 -1
  16. package/dist/stage-export.js +11 -1
  17. package/dist/stage.cjs +286 -22
  18. package/dist/stage.d.cts +146 -7
  19. package/dist/stage.d.ts +146 -7
  20. package/dist/stage.js +268 -9
  21. package/dist/{svg-import-Djj2q7Pc.d.cts → svg-import-5_oTbEJR.d.cts} +2 -2
  22. package/dist/{svg-import-Djj2q7Pc.d.ts → svg-import-5_oTbEJR.d.ts} +2 -2
  23. package/dist/{video-CcHW1qhV.d.cts → video-BSwNJZkn.d.cts} +25 -1
  24. package/dist/{video-CcHW1qhV.d.ts → video-BSwNJZkn.d.ts} +25 -1
  25. package/examples/_teaching/categorical-tail-loss.ts +3 -3
  26. package/examples/_teaching/teaching-byte-diff.ts +3 -3
  27. package/examples/_teaching/teaching-routed-transfer.ts +3 -3
  28. package/examples/_teaching/teaching-token-history.ts +2 -2
  29. package/examples/_teaching/teaching-weighted-vector.ts +3 -3
  30. package/examples/films/attention.ts +5 -4
  31. package/examples/films/fourier-epicycles.ts +5 -2
  32. package/examples/films/pythagoras.ts +2 -2
  33. package/examples/films/taylor-series.ts +3 -2
  34. package/package.json +1 -1
  35. package/dist/chunk-3LQLKLGH.js +0 -79
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 {
@@ -221,7 +233,7 @@ interface DecimalOptions {
221
233
  /** A number readout that follows a function of the timeline, drawn fresh each frame. */
222
234
  declare function decimal(read: () => number, options?: DecimalOptions): Node;
223
235
 
224
- type FilmDiagnosticCode = 'film.off_canvas' | 'film.text_overlap' | 'film.text_crossed' | 'film.missing_glyph';
236
+ type FilmDiagnosticCode = 'film.off_canvas' | 'film.text_overlap' | 'film.text_crossed' | 'film.missing_glyph' | 'film.blank';
225
237
  interface FilmDiagnostic {
226
238
  code: FilmDiagnosticCode;
227
239
  severity: 'error' | 'warning';
@@ -241,14 +253,24 @@ interface FilmDiagnostic {
241
253
  text?: string;
242
254
  /** The second text involved in an overlap. */
243
255
  other?: string;
256
+ /**
257
+ * Set when a motion scan finds the problem only while something moves. `time` and `until` then
258
+ * bound the longest stretch. `spans` counts the separate stretches, and `seconds` is their total length.
259
+ */
260
+ motion?: {
261
+ spans: number;
262
+ seconds: number;
263
+ };
244
264
  }
245
265
  interface FilmCheckReport {
246
266
  ok: boolean;
247
267
  width: number;
248
268
  height: number;
249
269
  duration: number;
250
- /** The times that were inspected, in seconds. */
270
+ /** The moments at rest that were inspected, in seconds. */
251
271
  sampled: number[];
272
+ /** The number of frames that a motion scan inspected. */
273
+ frames?: number;
252
274
  diagnostics: FilmDiagnostic[];
253
275
  summary: {
254
276
  errors: number;
@@ -260,11 +282,22 @@ interface FilmCheckOptions extends CompileOverrides {
260
282
  times?: readonly number[];
261
283
  /** Add this many evenly spaced samples to the moments at rest. */
262
284
  samples?: number;
285
+ /**
286
+ * Also inspect every frame. A problem that appears only while something moves is a warning, because
287
+ * the check cannot tell a collision from one picture that replaces another. A stretch of 0.2 seconds
288
+ * or more with nothing visible is reported as `film.blank`.
289
+ */
290
+ motion?: boolean;
291
+ /**
292
+ * For a motion scan, the canvas y where the content starts. Marks above it, such as a heading that
293
+ * stays up, do not count as content when the scan looks for blank frames.
294
+ */
295
+ contentTop?: number;
263
296
  }
264
297
  /**
265
298
  * Inspect a film for layout defects: marks off the canvas, text on text, strokes
266
299
  * through text, and characters that no font can draw. It looks where the film comes to rest, because objects may
267
- * cross each other while moving. Runs anywhere, with no rendering.
300
+ * cross each other while moving. With `motion`, it also looks at every frame. Runs anywhere, with no rendering.
268
301
  */
269
302
  declare function checkFilm(film: FilmDefinition | CompiledFilm, options?: FilmCheckOptions): Promise<FilmCheckReport>;
270
303
 
@@ -1341,6 +1374,109 @@ declare function highlightSweep(target: Node | readonly Node[], options?: Highli
1341
1374
  mark: Node;
1342
1375
  };
1343
1376
 
1377
+ /** One spoken word, timed in seconds from the start of its beat. */
1378
+ interface NarrationWord {
1379
+ text: string;
1380
+ start: number;
1381
+ end: number;
1382
+ }
1383
+ /** One take of the voice: a sentence or a short paragraph. */
1384
+ interface NarrationBeat {
1385
+ /** The text that the voice speaks. Captions use it. */
1386
+ say: string;
1387
+ /** Measured length of the recording, in seconds. */
1388
+ duration: number;
1389
+ /** Silence after the beat, in seconds, for the viewer to think. */
1390
+ hold?: number;
1391
+ /** Word times, from the speech engine or from a transcription. Cues need them. */
1392
+ words?: readonly NarrationWord[];
1393
+ }
1394
+ interface NarrationScene {
1395
+ id: string;
1396
+ /** Chapter title. A scene without one does not start a chapter. */
1397
+ title?: string;
1398
+ beats: readonly NarrationBeat[];
1399
+ }
1400
+ interface NarrationTiming {
1401
+ scenes: readonly NarrationScene[];
1402
+ /** Seconds before the first word. `NarrationOptions.lead` overrides it. */
1403
+ lead?: number;
1404
+ /** Seconds of silence between scenes. `NarrationOptions.gap` overrides it. */
1405
+ gap?: number;
1406
+ }
1407
+ interface NarrationOptions {
1408
+ /** Seconds before the first word, for a logo or an opening picture. Defaults to 0.6. */
1409
+ lead?: number;
1410
+ /** Seconds of silence between scenes, for the picture to change. Defaults to 0.4. */
1411
+ gap?: number;
1412
+ /** Write a caption for each spoken line. On by default. */
1413
+ captions?: boolean;
1414
+ /** Longest caption line, in characters. Defaults to 74. */
1415
+ captionLength?: number;
1416
+ /** Start a chapter at each scene that has a title. On by default. */
1417
+ chapters?: boolean;
1418
+ }
1419
+ /** Where one beat falls on the film's timeline, in seconds. */
1420
+ interface PlacedBeat {
1421
+ /** The first moment of the recording. */
1422
+ start: number;
1423
+ /** The last moment of the recording. */
1424
+ end: number;
1425
+ /** The end of the silence after it. */
1426
+ until: number;
1427
+ text: string;
1428
+ words: readonly NarrationWord[];
1429
+ }
1430
+ /** Split spoken text into caption lines: by sentence, then by length. */
1431
+ declare function captionLines(text: string, length?: number): string[];
1432
+ /** The clock of one scene. Every time is in film seconds. */
1433
+ declare class SceneClock {
1434
+ private readonly stage;
1435
+ readonly id: string;
1436
+ readonly start: number;
1437
+ readonly end: number;
1438
+ readonly beats: readonly PlacedBeat[];
1439
+ constructor(stage: Stage, id: string, start: number, end: number, beats: readonly PlacedBeat[]);
1440
+ /** When the voice says a phrase. Pass a beat index to search one beat only. Throws if the phrase is not spoken. */
1441
+ cue(phrase: string, beat?: number): {
1442
+ start: number;
1443
+ end: number;
1444
+ };
1445
+ /** Build when the voice starts a phrase. `offset` moves it, in seconds. */
1446
+ on(phrase: string, build: () => void, offset?: number, beat?: number): this;
1447
+ /** Build when the voice finishes a phrase. */
1448
+ after(phrase: string, build: () => void, offset?: number, beat?: number): this;
1449
+ /** Build when a beat starts. */
1450
+ onBeat(index: number, build: () => void, offset?: number): this;
1451
+ /** Build at a time counted from the start of the scene. */
1452
+ at(seconds: number, build: () => void): this;
1453
+ /** Fade nodes out just before the scene ends, so the next picture starts on a clean frame. */
1454
+ clear(nodes: readonly Node[], lead?: number, duration?: number): this;
1455
+ }
1456
+ /** The timeline of a whole narration. */
1457
+ declare class Narration {
1458
+ readonly scenes: readonly SceneClock[];
1459
+ /** The end of the last scene, in seconds. Hold the film at least this long, or the voice is cut. */
1460
+ readonly duration: number;
1461
+ readonly lead: number;
1462
+ readonly gap: number;
1463
+ constructor(stage: Stage, timing: NarrationTiming, options?: NarrationOptions);
1464
+ /** The clock of one scene. */
1465
+ scene(id: string): SceneClock;
1466
+ /** Where every beat's recording starts, in order, for the script that mixes the sound. */
1467
+ placements(): {
1468
+ scene: string;
1469
+ beat: number;
1470
+ start: number;
1471
+ end: number;
1472
+ }[];
1473
+ }
1474
+ /**
1475
+ * Lay a measured narration on the stage. Each scene gets a clock with phrase cues.
1476
+ * Captions and chapters are added to the film, so the MP4 carries them.
1477
+ */
1478
+ declare function narration(stage: Stage, timing: NarrationTiming, options?: NarrationOptions): Narration;
1479
+
1344
1480
  /**
1345
1481
  * 3D on the stage: a camera, meshes, curves, and points, all projected to paths
1346
1482
  * on every frame and drawn back to front. There is no GPU dependency, so the
@@ -1561,6 +1697,7 @@ declare class Vector3D extends Line3D {
1561
1697
  private readonly from3;
1562
1698
  private readonly to3;
1563
1699
  private readonly tipSize;
1700
+ private readonly tipBias;
1564
1701
  constructor(from: Reactive3, to: Reactive3, style?: Line3DStyle & {
1565
1702
  tip?: number;
1566
1703
  });
@@ -1577,6 +1714,8 @@ interface Points3DStyle {
1577
1714
  radius?: number;
1578
1715
  opacity?: number;
1579
1716
  onTop?: boolean;
1717
+ /** Nudge toward the camera so a point resting on a surface is not cut by it. */
1718
+ bias?: number;
1580
1719
  /** Soft ring around each point. */
1581
1720
  halo?: number;
1582
1721
  }
@@ -1675,5 +1814,5 @@ declare function label3d(content: string | Node, position: Reactive3, options?:
1675
1814
  offset?: Vec;
1676
1815
  }): Label3D;
1677
1816
 
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 };
1817
+ 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 };
1818
+ 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 {
@@ -221,7 +233,7 @@ interface DecimalOptions {
221
233
  /** A number readout that follows a function of the timeline, drawn fresh each frame. */
222
234
  declare function decimal(read: () => number, options?: DecimalOptions): Node;
223
235
 
224
- type FilmDiagnosticCode = 'film.off_canvas' | 'film.text_overlap' | 'film.text_crossed' | 'film.missing_glyph';
236
+ type FilmDiagnosticCode = 'film.off_canvas' | 'film.text_overlap' | 'film.text_crossed' | 'film.missing_glyph' | 'film.blank';
225
237
  interface FilmDiagnostic {
226
238
  code: FilmDiagnosticCode;
227
239
  severity: 'error' | 'warning';
@@ -241,14 +253,24 @@ interface FilmDiagnostic {
241
253
  text?: string;
242
254
  /** The second text involved in an overlap. */
243
255
  other?: string;
256
+ /**
257
+ * Set when a motion scan finds the problem only while something moves. `time` and `until` then
258
+ * bound the longest stretch. `spans` counts the separate stretches, and `seconds` is their total length.
259
+ */
260
+ motion?: {
261
+ spans: number;
262
+ seconds: number;
263
+ };
244
264
  }
245
265
  interface FilmCheckReport {
246
266
  ok: boolean;
247
267
  width: number;
248
268
  height: number;
249
269
  duration: number;
250
- /** The times that were inspected, in seconds. */
270
+ /** The moments at rest that were inspected, in seconds. */
251
271
  sampled: number[];
272
+ /** The number of frames that a motion scan inspected. */
273
+ frames?: number;
252
274
  diagnostics: FilmDiagnostic[];
253
275
  summary: {
254
276
  errors: number;
@@ -260,11 +282,22 @@ interface FilmCheckOptions extends CompileOverrides {
260
282
  times?: readonly number[];
261
283
  /** Add this many evenly spaced samples to the moments at rest. */
262
284
  samples?: number;
285
+ /**
286
+ * Also inspect every frame. A problem that appears only while something moves is a warning, because
287
+ * the check cannot tell a collision from one picture that replaces another. A stretch of 0.2 seconds
288
+ * or more with nothing visible is reported as `film.blank`.
289
+ */
290
+ motion?: boolean;
291
+ /**
292
+ * For a motion scan, the canvas y where the content starts. Marks above it, such as a heading that
293
+ * stays up, do not count as content when the scan looks for blank frames.
294
+ */
295
+ contentTop?: number;
263
296
  }
264
297
  /**
265
298
  * Inspect a film for layout defects: marks off the canvas, text on text, strokes
266
299
  * through text, and characters that no font can draw. It looks where the film comes to rest, because objects may
267
- * cross each other while moving. Runs anywhere, with no rendering.
300
+ * cross each other while moving. With `motion`, it also looks at every frame. Runs anywhere, with no rendering.
268
301
  */
269
302
  declare function checkFilm(film: FilmDefinition | CompiledFilm, options?: FilmCheckOptions): Promise<FilmCheckReport>;
270
303
 
@@ -1341,6 +1374,109 @@ declare function highlightSweep(target: Node | readonly Node[], options?: Highli
1341
1374
  mark: Node;
1342
1375
  };
1343
1376
 
1377
+ /** One spoken word, timed in seconds from the start of its beat. */
1378
+ interface NarrationWord {
1379
+ text: string;
1380
+ start: number;
1381
+ end: number;
1382
+ }
1383
+ /** One take of the voice: a sentence or a short paragraph. */
1384
+ interface NarrationBeat {
1385
+ /** The text that the voice speaks. Captions use it. */
1386
+ say: string;
1387
+ /** Measured length of the recording, in seconds. */
1388
+ duration: number;
1389
+ /** Silence after the beat, in seconds, for the viewer to think. */
1390
+ hold?: number;
1391
+ /** Word times, from the speech engine or from a transcription. Cues need them. */
1392
+ words?: readonly NarrationWord[];
1393
+ }
1394
+ interface NarrationScene {
1395
+ id: string;
1396
+ /** Chapter title. A scene without one does not start a chapter. */
1397
+ title?: string;
1398
+ beats: readonly NarrationBeat[];
1399
+ }
1400
+ interface NarrationTiming {
1401
+ scenes: readonly NarrationScene[];
1402
+ /** Seconds before the first word. `NarrationOptions.lead` overrides it. */
1403
+ lead?: number;
1404
+ /** Seconds of silence between scenes. `NarrationOptions.gap` overrides it. */
1405
+ gap?: number;
1406
+ }
1407
+ interface NarrationOptions {
1408
+ /** Seconds before the first word, for a logo or an opening picture. Defaults to 0.6. */
1409
+ lead?: number;
1410
+ /** Seconds of silence between scenes, for the picture to change. Defaults to 0.4. */
1411
+ gap?: number;
1412
+ /** Write a caption for each spoken line. On by default. */
1413
+ captions?: boolean;
1414
+ /** Longest caption line, in characters. Defaults to 74. */
1415
+ captionLength?: number;
1416
+ /** Start a chapter at each scene that has a title. On by default. */
1417
+ chapters?: boolean;
1418
+ }
1419
+ /** Where one beat falls on the film's timeline, in seconds. */
1420
+ interface PlacedBeat {
1421
+ /** The first moment of the recording. */
1422
+ start: number;
1423
+ /** The last moment of the recording. */
1424
+ end: number;
1425
+ /** The end of the silence after it. */
1426
+ until: number;
1427
+ text: string;
1428
+ words: readonly NarrationWord[];
1429
+ }
1430
+ /** Split spoken text into caption lines: by sentence, then by length. */
1431
+ declare function captionLines(text: string, length?: number): string[];
1432
+ /** The clock of one scene. Every time is in film seconds. */
1433
+ declare class SceneClock {
1434
+ private readonly stage;
1435
+ readonly id: string;
1436
+ readonly start: number;
1437
+ readonly end: number;
1438
+ readonly beats: readonly PlacedBeat[];
1439
+ constructor(stage: Stage, id: string, start: number, end: number, beats: readonly PlacedBeat[]);
1440
+ /** When the voice says a phrase. Pass a beat index to search one beat only. Throws if the phrase is not spoken. */
1441
+ cue(phrase: string, beat?: number): {
1442
+ start: number;
1443
+ end: number;
1444
+ };
1445
+ /** Build when the voice starts a phrase. `offset` moves it, in seconds. */
1446
+ on(phrase: string, build: () => void, offset?: number, beat?: number): this;
1447
+ /** Build when the voice finishes a phrase. */
1448
+ after(phrase: string, build: () => void, offset?: number, beat?: number): this;
1449
+ /** Build when a beat starts. */
1450
+ onBeat(index: number, build: () => void, offset?: number): this;
1451
+ /** Build at a time counted from the start of the scene. */
1452
+ at(seconds: number, build: () => void): this;
1453
+ /** Fade nodes out just before the scene ends, so the next picture starts on a clean frame. */
1454
+ clear(nodes: readonly Node[], lead?: number, duration?: number): this;
1455
+ }
1456
+ /** The timeline of a whole narration. */
1457
+ declare class Narration {
1458
+ readonly scenes: readonly SceneClock[];
1459
+ /** The end of the last scene, in seconds. Hold the film at least this long, or the voice is cut. */
1460
+ readonly duration: number;
1461
+ readonly lead: number;
1462
+ readonly gap: number;
1463
+ constructor(stage: Stage, timing: NarrationTiming, options?: NarrationOptions);
1464
+ /** The clock of one scene. */
1465
+ scene(id: string): SceneClock;
1466
+ /** Where every beat's recording starts, in order, for the script that mixes the sound. */
1467
+ placements(): {
1468
+ scene: string;
1469
+ beat: number;
1470
+ start: number;
1471
+ end: number;
1472
+ }[];
1473
+ }
1474
+ /**
1475
+ * Lay a measured narration on the stage. Each scene gets a clock with phrase cues.
1476
+ * Captions and chapters are added to the film, so the MP4 carries them.
1477
+ */
1478
+ declare function narration(stage: Stage, timing: NarrationTiming, options?: NarrationOptions): Narration;
1479
+
1344
1480
  /**
1345
1481
  * 3D on the stage: a camera, meshes, curves, and points, all projected to paths
1346
1482
  * on every frame and drawn back to front. There is no GPU dependency, so the
@@ -1561,6 +1697,7 @@ declare class Vector3D extends Line3D {
1561
1697
  private readonly from3;
1562
1698
  private readonly to3;
1563
1699
  private readonly tipSize;
1700
+ private readonly tipBias;
1564
1701
  constructor(from: Reactive3, to: Reactive3, style?: Line3DStyle & {
1565
1702
  tip?: number;
1566
1703
  });
@@ -1577,6 +1714,8 @@ interface Points3DStyle {
1577
1714
  radius?: number;
1578
1715
  opacity?: number;
1579
1716
  onTop?: boolean;
1717
+ /** Nudge toward the camera so a point resting on a surface is not cut by it. */
1718
+ bias?: number;
1580
1719
  /** Soft ring around each point. */
1581
1720
  halo?: number;
1582
1721
  }
@@ -1675,5 +1814,5 @@ declare function label3d(content: string | Node, position: Reactive3, options?:
1675
1814
  offset?: Vec;
1676
1815
  }): Label3D;
1677
1816
 
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 };
1817
+ 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 };
1818
+ 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 };