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.cjs CHANGED
@@ -184,6 +184,7 @@ __export(stage_exports, {
184
184
  Line3D: () => Line3D,
185
185
  LineChart: () => LineChart,
186
186
  MatrixNode: () => MatrixNode,
187
+ Narration: () => Narration,
187
188
  NeuralNet: () => NeuralNet,
188
189
  Node: () => Node,
189
190
  NumberLine: () => NumberLine,
@@ -193,6 +194,7 @@ __export(stage_exports, {
193
194
  Points3D: () => Points3D,
194
195
  Scatter: () => Scatter,
195
196
  Scene3D: () => Scene3D,
197
+ SceneClock: () => SceneClock,
196
198
  Stage: () => Stage,
197
199
  StreamLines: () => StreamLines,
198
200
  Surface3D: () => Surface3D,
@@ -229,6 +231,7 @@ __export(stage_exports, {
229
231
  buildOps: () => buildOps,
230
232
  call: () => call,
231
233
  callout: () => callout,
234
+ captionLines: () => captionLines,
232
235
  chalk: () => chalk,
233
236
  checkFilm: () => checkFilm,
234
237
  circle: () => circle,
@@ -288,6 +291,7 @@ __export(stage_exports, {
288
291
  heatmap: () => heatmap,
289
292
  highlightSweep: () => highlightSweep,
290
293
  histogram: () => histogram,
294
+ image: () => image,
291
295
  indicate: () => indicate,
292
296
  infoBox: () => infoBox,
293
297
  invert: () => invert,
@@ -313,6 +317,7 @@ __export(stage_exports, {
313
317
  morphMatching: () => morphMatching,
314
318
  moveTo: () => moveTo,
315
319
  mul: () => mul,
320
+ narration: () => narration,
316
321
  neon: () => neon,
317
322
  neuralNet: () => neuralNet,
318
323
  notQuiteThere: () => notQuiteThere,
@@ -857,17 +862,17 @@ function reverseRing(r) {
857
862
  return { p: out, closed: r.closed };
858
863
  }
859
864
  function parseSvgPath(d) {
860
- const tokens3 = d.match(/[a-zA-Z]|[-+]?(?:\d+\.?\d*|\.\d+)(?:[eE][-+]?\d+)?/g);
861
- if (!tokens3) return [];
865
+ const tokens4 = d.match(/[a-zA-Z]|[-+]?(?:\d+\.?\d*|\.\d+)(?:[eE][-+]?\d+)?/g);
866
+ if (!tokens4) return [];
862
867
  const rings = [];
863
868
  let out = [];
864
869
  let i = 0, x = 0, y = 0, startX = 0, startY = 0;
865
870
  let lastCmd = "", lastCx = 0, lastCy = 0;
866
- const num = () => Number(tokens3[i++]);
871
+ const num = () => Number(tokens4[i++]);
867
872
  const flags = () => {
868
- const token = tokens3[i];
873
+ const token = tokens4[i];
869
874
  if (token.length > 1 && (token[0] === "0" || token[0] === "1") && !token.startsWith("0.") && !token.startsWith("1.")) {
870
- tokens3[i] = token.slice(1);
875
+ tokens4[i] = token.slice(1);
871
876
  return Number(token[0]);
872
877
  }
873
878
  i++;
@@ -881,8 +886,8 @@ function parseSvgPath(d) {
881
886
  if (out.length === 0) out.push(px, py);
882
887
  };
883
888
  let cmd = "";
884
- while (i < tokens3.length) {
885
- const token = tokens3[i];
889
+ while (i < tokens4.length) {
890
+ const token = tokens4[i];
886
891
  if (/^[a-zA-Z]$/.test(token)) {
887
892
  cmd = token;
888
893
  i++;
@@ -1885,8 +1890,8 @@ var Node = class _Node {
1885
1890
  let result = null;
1886
1891
  const path = this.get("path");
1887
1892
  if (path) result = pathBounds(transformPath(path, m));
1888
- const image = this.get("image");
1889
- if (image) result = unionBounds(result, boundsOfRect(m, image.width, image.height));
1893
+ const image2 = this.get("image");
1894
+ if (image2) result = unionBounds(result, boundsOfRect(m, image2.width, image2.height));
1890
1895
  if (this.draw) {
1891
1896
  const built = this.draw(clock.now);
1892
1897
  const list3 = built === null ? [] : Array.isArray(built) ? built : [built];
@@ -2889,8 +2894,8 @@ function walk(node, parent, screen, alpha, ops) {
2889
2894
  const m = mul(base, node.localMatrix());
2890
2895
  const path = node.get("path");
2891
2896
  if (path && path.length > 0) emit(node, path, m, opacity, ops);
2892
- const image = node.get("image");
2893
- if (image) ops.push({ kind: "image", image, matrix: m, alpha: opacity });
2897
+ const image2 = node.get("image");
2898
+ if (image2) ops.push({ kind: "image", image: image2, matrix: m, alpha: opacity });
2894
2899
  if (node.rawOps) node.rawOps(m, opacity, ops);
2895
2900
  if (node.draw) {
2896
2901
  const built = node.draw(clockNow());
@@ -4313,6 +4318,45 @@ function regularPolygon(sides, radius, style = {}) {
4313
4318
  }
4314
4319
  return polygon(points, style);
4315
4320
  }
4321
+ function intrinsicSize(src) {
4322
+ const match = /^data:image\/(png|gif|jpeg|jpg);base64,/.exec(src);
4323
+ if (!match || typeof atob !== "function") return null;
4324
+ let head;
4325
+ try {
4326
+ head = atob(src.slice(match[0].length, match[0].length + (match[1] === "jpeg" || match[1] === "jpg" ? 87384 : 44)));
4327
+ } catch {
4328
+ return null;
4329
+ }
4330
+ const byte = (i) => head.charCodeAt(i);
4331
+ 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;
4332
+ if (match[1] === "gif") return head.length >= 10 ? [byte(6) + byte(7) * 256, byte(8) + byte(9) * 256] : null;
4333
+ for (let i = 2; i + 9 < head.length; ) {
4334
+ if (byte(i) !== 255) return null;
4335
+ const marker = byte(i + 1);
4336
+ 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)];
4337
+ i += 2 + byte(i + 2) * 256 + byte(i + 3);
4338
+ }
4339
+ return null;
4340
+ }
4341
+ function image(src, options = {}) {
4342
+ const natural = intrinsicSize(src);
4343
+ let width = options.width, height = options.height;
4344
+ if (width === void 0 && height === void 0) {
4345
+ if (!natural) throw new Error("image() needs a width or a height when the picture is not a PNG, GIF, or JPEG data URL.");
4346
+ [width, height] = natural;
4347
+ } else if (width === void 0 || height === void 0) {
4348
+ if (!natural) throw new Error("image() needs both width and height when the picture is not a PNG, GIF, or JPEG data URL.");
4349
+ if (width === void 0) width = height * natural[0] / natural[1];
4350
+ else height = width * natural[1] / natural[0];
4351
+ }
4352
+ if (!(width > 0) || !(height > 0)) throw new Error("image() needs a positive width and height.");
4353
+ const picture = new Node().at(-width / 2, -height / 2);
4354
+ picture.base.image = { src, width, height };
4355
+ const out = new Node();
4356
+ out.add(picture);
4357
+ if (options.opacity !== void 0) out.opacity(options.opacity);
4358
+ return out;
4359
+ }
4316
4360
  function dot(radius = 9, color = "ink", style = {}) {
4317
4361
  return styled(new Node(circlePath(0, 0, radius)), style, { fill: color });
4318
4362
  }
@@ -4587,6 +4631,9 @@ var MIN_RESTING_MOMENTS = 5;
4587
4631
  var AUTO_SAMPLES = 12;
4588
4632
  var CUBIC_STEPS = 6;
4589
4633
  var CROSSING_ERROR_WIDTH = 2;
4634
+ var BLANK_ALPHA = 0.25;
4635
+ var BLANK_EDGE_SECONDS = 0.5;
4636
+ var BLANK_MIN_SECONDS = 0.2;
4590
4637
  var CROSSING_ERROR_CONTRAST = 2;
4591
4638
  var MIN_STROKE_CONTRAST = 1.6;
4592
4639
  var OPAQUE = 0.9;
@@ -4863,6 +4910,16 @@ function inspect(frame, time, zoomed, bleed) {
4863
4910
  }
4864
4911
  return findings;
4865
4912
  }
4913
+ function hasContent(frame, top) {
4914
+ return frame.ops.some((op) => {
4915
+ if (op.kind !== "path") return op.alpha >= BLANK_ALPHA;
4916
+ const filled = op.fill !== null && op.fillAlpha >= BLANK_ALPHA;
4917
+ const stroked = op.stroke !== null && op.strokeAlpha >= BLANK_ALPHA && op.strokeWidth > 0;
4918
+ if (!filled && !stroked) return false;
4919
+ const box = pathBounds(filled ? op.path : op.strokePath);
4920
+ return box !== null && box.y + box.height > top && box.y < frame.height && box.x + box.width > 0 && box.x < frame.width;
4921
+ });
4922
+ }
4866
4923
  async function checkFilm(film2, options = {}) {
4867
4924
  const compiled = isFilm(film2) ? await film2.compile(options) : film2;
4868
4925
  const times = options.times ? [...options.times] : restingMoments(compiled, options.samples ?? 0);
@@ -4883,6 +4940,57 @@ async function checkFilm(film2, options = {}) {
4883
4940
  }
4884
4941
  }
4885
4942
  }
4943
+ const frameCount = options.motion ? Math.max(1, Math.round(compiled.duration * compiled.fps)) : 0;
4944
+ const step = 1 / compiled.fps;
4945
+ if (options.motion) {
4946
+ const top = options.contentTop ?? 0;
4947
+ const moving = /* @__PURE__ */ new Map();
4948
+ const blanks = [];
4949
+ for (let index = 0; index < frameCount; index++) {
4950
+ const time = index * step;
4951
+ const frame = await frameAt(compiled, time);
4952
+ for (const finding of inspect(frame, time, zoomAt(compiled, time) !== 1, compiled.bleed)) {
4953
+ if (merged.has(finding.key)) continue;
4954
+ let runs = moving.get(finding.key);
4955
+ if (!runs) moving.set(finding.key, runs = []);
4956
+ const last = runs[runs.length - 1];
4957
+ if (last && last.to === index - 1) last.to = index;
4958
+ else runs.push({ from: index, to: index, first: finding });
4959
+ }
4960
+ const edge = time < BLANK_EDGE_SECONDS || time > compiled.duration - BLANK_EDGE_SECONDS;
4961
+ if (!edge && !hasContent(frame, top)) {
4962
+ const last = blanks[blanks.length - 1];
4963
+ if (last && last.to === index - 1) last.to = index;
4964
+ else blanks.push({ from: index, to: index });
4965
+ }
4966
+ }
4967
+ const seconds = (frames) => Math.round(frames * step * 100) / 100;
4968
+ for (const [key, runs] of moving) {
4969
+ const longest = runs.reduce((best, run2) => run2.to - run2.from > best.to - best.from ? run2 : best);
4970
+ const { key: _, ...finding } = longest.first;
4971
+ merged.set(key, {
4972
+ ...finding,
4973
+ severity: "warning",
4974
+ until: longest.to * step,
4975
+ stage: { x: 0, y: 0 },
4976
+ motion: { spans: runs.length, seconds: seconds(runs.reduce((sum, run2) => sum + run2.to - run2.from + 1, 0)) }
4977
+ });
4978
+ }
4979
+ for (const run2 of blanks) {
4980
+ const length = seconds(run2.to - run2.from + 1);
4981
+ if (length < BLANK_MIN_SECONDS) continue;
4982
+ merged.set(`film.blank:${run2.from}`, {
4983
+ code: "film.blank",
4984
+ severity: "warning",
4985
+ message: `Nothing is visible${top > 0 ? ` below y=${top}` : ""} for ${length} s.`,
4986
+ time: run2.from * step,
4987
+ until: run2.to * step,
4988
+ box: { x: 0, y: top, width: compiled.width, height: compiled.height - top },
4989
+ stage: { x: 0, y: 0 },
4990
+ motion: { spans: 1, seconds: length }
4991
+ });
4992
+ }
4993
+ }
4886
4994
  const round = (value) => Math.round(value * 100) / 100;
4887
4995
  const diagnostics = [...merged.values()].map((entry) => ({
4888
4996
  ...entry,
@@ -4901,6 +5009,7 @@ async function checkFilm(film2, options = {}) {
4901
5009
  height: compiled.height,
4902
5010
  duration: compiled.duration,
4903
5011
  sampled: times.map((time) => Math.round(time * 1e3) / 1e3),
5012
+ ...options.motion ? { frames: frameCount } : {},
4904
5013
  diagnostics,
4905
5014
  summary: { errors, warnings: diagnostics.length - errors }
4906
5015
  };
@@ -7094,7 +7203,7 @@ var CodeBlock = class extends Node {
7094
7203
  const font = fontFor("mono", 400);
7095
7204
  const scale = size / font.unitsPerEm;
7096
7205
  const advance = font.advance(font.glyphFor(48)) * scale;
7097
- const tokens3 = tokenize(source, options.language ?? "ts");
7206
+ const tokens4 = tokenize(source, options.language ?? "ts");
7098
7207
  const rows = source.split("\n");
7099
7208
  const gutter = options.lineNumbers ? (String(rows.length).length + 2) * advance : 0;
7100
7209
  const pad2 = options.padding ?? size * 0.9;
@@ -7126,7 +7235,7 @@ var CodeBlock = class extends Node {
7126
7235
  }
7127
7236
  const colors = { ...CODE_COLORS, ...options.colors };
7128
7237
  const column = /* @__PURE__ */ new Map();
7129
- for (const token of tokens3) {
7238
+ for (const token of tokens4) {
7130
7239
  const start = column.get(token.line) ?? 0;
7131
7240
  column.set(token.line, start + token.text.length);
7132
7241
  const entry = { ...token, glyphs: [] };
@@ -8483,9 +8592,9 @@ function fromSvg(source, options = {}) {
8483
8592
  const width = parseFloat(element.attrs["width"] ?? "0"), height = parseFloat(element.attrs["height"] ?? "0");
8484
8593
  const [x, y] = apply(m, parseFloat(element.attrs["x"] ?? "0") || 0, parseFloat(element.attrs["y"] ?? "0") || 0);
8485
8594
  const unit = matScale(m);
8486
- const image = { src: href, width, height };
8595
+ const image2 = { src: href, width, height };
8487
8596
  const node = new Node().at(x, y);
8488
- node.base.image = image;
8597
+ node.base.image = image2;
8489
8598
  node.base.sx = unit;
8490
8599
  node.base.sy = unit;
8491
8600
  if (opacity < 1) node.base.opacity = opacity;
@@ -8554,6 +8663,144 @@ function shiftPaint(paint, dx, dy) {
8554
8663
  return gradient;
8555
8664
  }
8556
8665
 
8666
+ // src/stage/narration.ts
8667
+ var tokens3 = (text2) => text2.toLowerCase().replace(/[^a-z0-9.]+/g, " ").split(" ").map((token) => token.replace(/^\.+|\.+$/g, "")).filter(Boolean);
8668
+ function captionLines(text2, length = 74) {
8669
+ const lines = [];
8670
+ for (const sentence of text2.match(/[^.?!]+(?:[.?!]+(?=\s|$)|\.\d[^.?!]*[.?!]?|$)/g) ?? []) {
8671
+ let line2 = "";
8672
+ for (const word of sentence.split(/\s+/).filter(Boolean)) {
8673
+ if (line2 && line2.length + word.length + 1 > length) {
8674
+ lines.push(line2);
8675
+ line2 = word;
8676
+ } else {
8677
+ line2 = line2 ? `${line2} ${word}` : word;
8678
+ }
8679
+ }
8680
+ if (line2) lines.push(line2);
8681
+ }
8682
+ return lines;
8683
+ }
8684
+ var SceneClock = class {
8685
+ constructor(stage, id, start, end, beats) {
8686
+ this.stage = stage;
8687
+ this.id = id;
8688
+ this.start = start;
8689
+ this.end = end;
8690
+ this.beats = beats;
8691
+ }
8692
+ stage;
8693
+ id;
8694
+ start;
8695
+ end;
8696
+ beats;
8697
+ /** When the voice says a phrase. Pass a beat index to search one beat only. Throws if the phrase is not spoken. */
8698
+ cue(phrase, beat) {
8699
+ const want = tokens3(phrase);
8700
+ if (want.length === 0) throw new Error(`narration: scene "${this.id}": a cue needs at least one word`);
8701
+ if (beat !== void 0 && !this.beats[beat]) throw new Error(`narration: scene "${this.id}" has no beat ${beat}`);
8702
+ const list3 = beat === void 0 ? this.beats : [this.beats[beat]];
8703
+ for (const placed of list3) {
8704
+ const spoken = placed.words.flatMap((word) => tokens3(word.text).map((token) => ({ token, start: word.start, end: word.end })));
8705
+ for (let i = 0; i + want.length <= spoken.length; i++) {
8706
+ if (want.every((token, j) => spoken[i + j].token === token)) {
8707
+ return { start: placed.start + spoken[i].start, end: placed.start + spoken[i + want.length - 1].end };
8708
+ }
8709
+ }
8710
+ }
8711
+ const where = beat === void 0 ? "" : ` in beat ${beat}`;
8712
+ throw new Error(`narration: scene "${this.id}": the voice never says "${phrase}"${where}`);
8713
+ }
8714
+ /** Build when the voice starts a phrase. `offset` moves it, in seconds. */
8715
+ on(phrase, build, offset = 0, beat) {
8716
+ this.stage.at(Math.max(0, this.cue(phrase, beat).start + offset), build);
8717
+ return this;
8718
+ }
8719
+ /** Build when the voice finishes a phrase. */
8720
+ after(phrase, build, offset = 0, beat) {
8721
+ this.stage.at(Math.max(0, this.cue(phrase, beat).end + offset), build);
8722
+ return this;
8723
+ }
8724
+ /** Build when a beat starts. */
8725
+ onBeat(index, build, offset = 0) {
8726
+ const beat = this.beats[index];
8727
+ if (!beat) throw new Error(`narration: scene "${this.id}" has no beat ${index}`);
8728
+ this.stage.at(Math.max(0, beat.start + offset), build);
8729
+ return this;
8730
+ }
8731
+ /** Build at a time counted from the start of the scene. */
8732
+ at(seconds, build) {
8733
+ this.stage.at(Math.max(0, this.start + seconds), build);
8734
+ return this;
8735
+ }
8736
+ /** Fade nodes out just before the scene ends, so the next picture starts on a clean frame. */
8737
+ clear(nodes, lead = 0.24, duration = 0.26) {
8738
+ this.stage.at(this.end - lead, () => this.stage.play(...nodes.map((node) => fade(node, 0, { duration }))));
8739
+ return this;
8740
+ }
8741
+ };
8742
+ var Narration = class {
8743
+ scenes;
8744
+ /** The end of the last scene, in seconds. Hold the film at least this long, or the voice is cut. */
8745
+ duration;
8746
+ lead;
8747
+ gap;
8748
+ constructor(stage, timing, options = {}) {
8749
+ this.lead = options.lead ?? timing.lead ?? 0.6;
8750
+ this.gap = options.gap ?? timing.gap ?? 0.4;
8751
+ if (!(this.lead >= 0) || !(this.gap >= 0)) throw new Error("narration: lead and gap must be zero or more seconds");
8752
+ const seen = /* @__PURE__ */ new Set();
8753
+ const scenes = [];
8754
+ let now = this.lead;
8755
+ let last = now;
8756
+ for (const scene of timing.scenes) {
8757
+ if (seen.has(scene.id)) throw new Error(`narration: two scenes are named "${scene.id}"`);
8758
+ seen.add(scene.id);
8759
+ const start = now;
8760
+ const beats = [];
8761
+ for (const beat of scene.beats) {
8762
+ if (!(beat.duration > 0)) throw new Error(`narration: scene "${scene.id}" has a beat without a measured duration: "${beat.say}"`);
8763
+ const hold = beat.hold ?? 0;
8764
+ beats.push({ start: now, end: now + beat.duration, until: now + beat.duration + hold, text: beat.say, words: beat.words ?? [] });
8765
+ now += beat.duration + hold;
8766
+ }
8767
+ scenes.push(new SceneClock(stage, scene.id, start, now, beats));
8768
+ if (options.chapters !== false && scene.title) stage.chapters.push({ title: scene.title, time: scenes.length === 1 ? 0 : start });
8769
+ if (options.captions !== false) {
8770
+ for (const beat of beats) {
8771
+ const lines = captionLines(beat.text, options.captionLength);
8772
+ const total = lines.reduce((sum, line2) => sum + line2.length, 0);
8773
+ let t0 = beat.start;
8774
+ for (const line2 of lines) {
8775
+ const t1 = t0 + (beat.end - beat.start) * line2.length / total;
8776
+ stage.captions.push({ t0, t1, text: line2 });
8777
+ t0 = t1;
8778
+ }
8779
+ }
8780
+ }
8781
+ last = now;
8782
+ now += this.gap;
8783
+ }
8784
+ this.scenes = scenes;
8785
+ this.duration = last;
8786
+ stage.at(last, () => {
8787
+ });
8788
+ }
8789
+ /** The clock of one scene. */
8790
+ scene(id) {
8791
+ const found = this.scenes.find((scene) => scene.id === id);
8792
+ if (!found) throw new Error(`narration: no scene "${id}". The scenes are: ${this.scenes.map((scene) => scene.id).join(", ")}`);
8793
+ return found;
8794
+ }
8795
+ /** Where every beat's recording starts, in order, for the script that mixes the sound. */
8796
+ placements() {
8797
+ return this.scenes.flatMap((scene) => scene.beats.map((beat, index) => ({ scene: scene.id, beat: index, start: beat.start, end: beat.end })));
8798
+ }
8799
+ };
8800
+ function narration(stage, timing, options = {}) {
8801
+ return new Narration(stage, timing, options);
8802
+ }
8803
+
8557
8804
  // src/stage/three/index.ts
8558
8805
  var read3 = (value) => typeof value === "function" ? value() : value;
8559
8806
  var normalize = (v) => {
@@ -9233,6 +9480,7 @@ var Vector3D = class extends Line3D {
9233
9480
  from3;
9234
9481
  to3;
9235
9482
  tipSize;
9483
+ tipBias;
9236
9484
  constructor(from, to2, style = {}) {
9237
9485
  super(from, () => {
9238
9486
  const a = read3(from), b = read3(to2);
@@ -9243,6 +9491,7 @@ var Vector3D = class extends Line3D {
9243
9491
  this.from3 = from;
9244
9492
  this.to3 = to2;
9245
9493
  this.tipSize = style.tip ?? 24;
9494
+ this.tipBias = style.onTop ? ON_TOP : style.bias ?? 0;
9246
9495
  }
9247
9496
  emit(view) {
9248
9497
  super.emit(view);
@@ -9261,7 +9510,7 @@ var Vector3D = class extends Line3D {
9261
9510
  const rgb = solidOf(this.get("stroke"));
9262
9511
  const color = view.fogged(rgb[0], rgb[1], rgb[2], depth);
9263
9512
  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]);
9264
- view.push(fillOp([ring2], color, alpha, null, 0, 0), depth + 0.01);
9513
+ view.push(fillOp([ring2], color, alpha, null, 0, 0), depth + 0.01 + this.tipBias);
9265
9514
  }
9266
9515
  };
9267
9516
  function vector3d(from, to2, style = {}) {
@@ -9284,7 +9533,7 @@ var Points3D = class extends Object3D {
9284
9533
  const trim = this.get("trimTo");
9285
9534
  const shown = Math.ceil(points.length * trim);
9286
9535
  const base = solidOf(this.get("fill"));
9287
- const bias = this.style.onTop ? ON_TOP : 0;
9536
+ const bias = this.style.onTop ? ON_TOP : this.style.bias ?? 0;
9288
9537
  for (let i = 0; i < shown; i++) {
9289
9538
  const point = points[i];
9290
9539
  if (!view.project(point[0], point[1], point[2])) continue;
@@ -9343,13 +9592,23 @@ var Trail3D = class extends Object3D {
9343
9592
  const fade2 = this.style.fade ?? (tail !== void 0 ? 0 : 1);
9344
9593
  const bias = this.style.onTop ? ON_TOP : this.style.bias ?? 0;
9345
9594
  const glow = (this.style.glow ?? 0) * view.scale;
9346
- const piece = Math.max(1, Math.ceil((i1 - i0) / 48));
9347
- for (let i = i0; i < i1; i += piece) {
9595
+ const moved = [];
9596
+ let last = null;
9597
+ for (let k = i0; k <= i1; k++) {
9598
+ const p = this.sample(k, rate);
9599
+ if (last && Math.abs(p[0] - last[0]) + Math.abs(p[1] - last[1]) + Math.abs(p[2] - last[2]) < 1e-9) continue;
9600
+ moved.push(p);
9601
+ last = p;
9602
+ }
9603
+ const span = moved.length - 1;
9604
+ if (span < 1) return;
9605
+ const piece = Math.max(1, Math.ceil(span / 48));
9606
+ for (let i = 0; i < span; i += piece) {
9348
9607
  const coords = [];
9349
9608
  let depth = 0;
9350
9609
  let scale = 0;
9351
- for (let k = i; k <= Math.min(i1, i + piece); k++) {
9352
- const p = this.sample(k, rate);
9610
+ for (let k = i; k <= Math.min(span, i + piece); k++) {
9611
+ const p = moved[k];
9353
9612
  if (!view.project(p[0], p[1], p[2])) continue;
9354
9613
  coords.push([view.px, view.py]);
9355
9614
  depth += view.pz;
@@ -9358,7 +9617,7 @@ var Trail3D = class extends Object3D {
9358
9617
  if (coords.length < 2) continue;
9359
9618
  depth /= coords.length;
9360
9619
  scale /= coords.length;
9361
- const fraction = (i + piece / 2 - i0) / (i1 - i0);
9620
+ const fraction = Math.min(1, (i + piece / 2) / span);
9362
9621
  const light = fade2 + (1 - fade2) * Math.pow(fraction, 1.6);
9363
9622
  const color = view.fogged(base[0], base[1], base[2], depth);
9364
9623
  view.push(strokeOp([chain(coords)], color, alpha * light, width * scale, glow, "butt"), depth + bias);
@@ -9558,6 +9817,7 @@ function label3d(content, position, options = {}) {
9558
9817
  Line3D,
9559
9818
  LineChart,
9560
9819
  MatrixNode,
9820
+ Narration,
9561
9821
  NeuralNet,
9562
9822
  Node,
9563
9823
  NumberLine,
@@ -9567,6 +9827,7 @@ function label3d(content, position, options = {}) {
9567
9827
  Points3D,
9568
9828
  Scatter,
9569
9829
  Scene3D,
9830
+ SceneClock,
9570
9831
  Stage,
9571
9832
  StreamLines,
9572
9833
  Surface3D,
@@ -9603,6 +9864,7 @@ function label3d(content, position, options = {}) {
9603
9864
  buildOps,
9604
9865
  call,
9605
9866
  callout,
9867
+ captionLines,
9606
9868
  chalk,
9607
9869
  checkFilm,
9608
9870
  circle,
@@ -9662,6 +9924,7 @@ function label3d(content, position, options = {}) {
9662
9924
  heatmap,
9663
9925
  highlightSweep,
9664
9926
  histogram,
9927
+ image,
9665
9928
  indicate,
9666
9929
  infoBox,
9667
9930
  invert,
@@ -9687,6 +9950,7 @@ function label3d(content, position, options = {}) {
9687
9950
  morphMatching,
9688
9951
  moveTo,
9689
9952
  mul,
9953
+ narration,
9690
9954
  neon,
9691
9955
  neuralNet,
9692
9956
  notQuiteThere,