vizmatic 0.6.0 → 0.7.0

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 (42) hide show
  1. package/README.md +18 -18
  2. package/assets/THIRD_PARTY_LICENSES.md +10 -1
  3. package/assets/licenses/satori-NOTICES.txt +688 -0
  4. package/dist/{chunk-RWF4VBUL.js → chunk-CJOXWJQA.js} +2 -1
  5. package/dist/chunk-MAHT32CE.js +79 -0
  6. package/dist/cli.js +4 -4
  7. package/dist/index.cjs +1044 -155
  8. package/dist/index.d.cts +440 -5
  9. package/dist/index.d.ts +440 -5
  10. package/dist/index.js +1003 -129
  11. package/dist/satori.cjs +27 -0
  12. package/dist/scene-browser-assets.js +1 -1
  13. package/dist/scene-browser.js +17 -17
  14. package/dist/scene-cli.js +1 -1
  15. package/dist/scene-layout.wasm +0 -0
  16. package/dist/stage-browser/dagre.esm-6F3RIGLP.js +6 -0
  17. package/dist/stage-browser/stage.js +1 -1
  18. package/dist/stage-export.cjs +10 -2
  19. package/dist/stage-export.d.cts +11 -1
  20. package/dist/stage-export.d.ts +11 -1
  21. package/dist/stage-export.js +8 -2
  22. package/examples/_teaching/categorical-tail-loss.ts +25 -0
  23. package/examples/_teaching/teaching-byte-diff.ts +48 -0
  24. package/examples/_teaching/teaching-routed-transfer.ts +35 -0
  25. package/examples/_teaching/teaching-token-history.ts +29 -0
  26. package/examples/_teaching/teaching-weighted-vector.ts +55 -0
  27. package/examples/films/attention.ts +2 -2
  28. package/examples/films/cache-miss.ts +3 -3
  29. package/examples/films/central-limit.ts +1 -1
  30. package/examples/films/complex-maps.ts +1 -1
  31. package/examples/films/deck-example.ts +5 -5
  32. package/examples/films/euler-circle.ts +2 -2
  33. package/examples/films/fourier-epicycles.ts +15 -3
  34. package/examples/films/gradient-descent.ts +1 -1
  35. package/examples/films/linear-maps.ts +1 -1
  36. package/examples/films/lorenz.ts +1 -1
  37. package/examples/films/pythagoras.ts +3 -3
  38. package/examples/films/taylor-series.ts +2 -2
  39. package/examples/films/vizmatic-title.ts +1 -1
  40. package/package.json +4 -4
  41. package/dist/chunk-JHHPLALU.js +0 -79
  42. package/dist/stage-browser/dagre.esm-N2NIVIAZ.js +0 -6
package/dist/index.js CHANGED
@@ -51,7 +51,7 @@ import {
51
51
  withRenderContext,
52
52
  wrapWithBrand,
53
53
  wrapWithWatermark
54
- } from "./chunk-RWF4VBUL.js";
54
+ } from "./chunk-CJOXWJQA.js";
55
55
  import {
56
56
  DEFAULT_DENSITY,
57
57
  DENSITY_NAMES,
@@ -1816,8 +1816,8 @@ function Sparkline({
1816
1816
  const h = height ?? d.f(18);
1817
1817
  const stroke = color ?? (tone ? getToneColor(tone, c) : c.textSecondary);
1818
1818
  const line = strokeWidth ?? d.w(1.5);
1819
- const finite5 = values.filter(Number.isFinite);
1820
- const low = min ?? Math.min(...finite5), high = max ?? Math.max(...finite5);
1819
+ const finite7 = values.filter(Number.isFinite);
1820
+ const low = min ?? Math.min(...finite7), high = max ?? Math.max(...finite7);
1821
1821
  const range = high - low || 1;
1822
1822
  const inset = endDot ? d.g(3) : line;
1823
1823
  const x = (index) => inset + (values.length <= 1 ? 0 : index / (values.length - 1) * (w - inset * 2));
@@ -3352,9 +3352,9 @@ function preferredSide(from, to) {
3352
3352
  return to.cy >= from.cy ? "bottom" : "top";
3353
3353
  }
3354
3354
  function routingAnchor(node, side, offset = 0.5) {
3355
- const bounds2 = box(node);
3356
- if (side === "left" || side === "right") return { x: bounds2[side], y: bounds2.top + node.height * offset };
3357
- return { x: bounds2.left + node.width * offset, y: bounds2[side] };
3355
+ const bounds4 = box(node);
3356
+ if (side === "left" || side === "right") return { x: bounds4[side], y: bounds4.top + node.height * offset };
3357
+ return { x: bounds4.left + node.width * offset, y: bounds4[side] };
3358
3358
  }
3359
3359
  function outward(point, side, distance) {
3360
3360
  return {
@@ -4598,14 +4598,14 @@ function GraphDiagram({
4598
4598
  if (!from || !to) return;
4599
4599
  const [fromSide, toSide] = chooseSides(from, to, flowIsHorizontal(edge));
4600
4600
  const coordinate = (node, side) => side === "left" || side === "right" ? node.cy : node.cx;
4601
- const add = (node, side, other, end) => {
4601
+ const add2 = (node, side, other, end) => {
4602
4602
  const key = `${node.id}\0${side}`;
4603
4603
  const list = sideUsers.get(key) ?? [];
4604
4604
  list.push({ key: `${index}\0${end}`, other: coordinate(other, side) + index * 1e-3, length: side === "left" || side === "right" ? node.height : node.width });
4605
4605
  sideUsers.set(key, list);
4606
4606
  };
4607
- add(from, fromSide, to, "from");
4608
- add(to, toSide, from, "to");
4607
+ add2(from, fromSide, to, "from");
4608
+ add2(to, toSide, from, "to");
4609
4609
  });
4610
4610
  for (const users of sideUsers.values()) {
4611
4611
  users.sort((left, right) => left.other - right.other);
@@ -5931,7 +5931,7 @@ function SequenceDiagram({
5931
5931
  const noteElements = rows.map((row, rowIndex) => {
5932
5932
  if (!row.item || !isNote(row.item)) return null;
5933
5933
  const note = row.item;
5934
- const bounds2 = sequenceNoteBounds(note, participantXs, resolvedWidth, noteWidth, padding);
5934
+ const bounds4 = sequenceNoteBounds(note, participantXs, resolvedWidth, noteWidth, padding);
5935
5935
  const tone = note.tone ?? "warm";
5936
5936
  const accent = note.muted ? c.textMuted : getToneColor(tone, c);
5937
5937
  return React8.createElement("div", {
@@ -5939,9 +5939,9 @@ function SequenceDiagram({
5939
5939
  "data-vizmatic-sequence-note": note.id ?? row.key,
5940
5940
  style: {
5941
5941
  position: "absolute",
5942
- left: bounds2.left,
5942
+ left: bounds4.left,
5943
5943
  top: rowCenter(rowIndex) - 17,
5944
- width: bounds2.width,
5944
+ width: bounds4.width,
5945
5945
  minHeight: 34,
5946
5946
  boxSizing: "border-box",
5947
5947
  display: "flex",
@@ -6149,10 +6149,10 @@ function validateSchema(schema, owner) {
6149
6149
  function schemaLabel(schema) {
6150
6150
  if (schema == null) return void 0;
6151
6151
  if (typeof schema === "string") return schema;
6152
- const prefix = [schema.name, schema.version].filter(Boolean).join(" ");
6152
+ const prefix2 = [schema.name, schema.version].filter(Boolean).join(" ");
6153
6153
  const fieldList = Array.isArray(schema.fields) ? schema.fields : Object.entries(schema.fields).map(([name, type]) => ({ name, type, required: false }));
6154
6154
  const fields = fieldList.map((field) => `${field.name}${field.type ? `: ${field.type}` : ""}${field.required ? " *" : ""}`).join(", ");
6155
- return [prefix, fields ? `{ ${fields} }` : void 0].filter(Boolean).join(" ");
6155
+ return [prefix2, fields ? `{ ${fields} }` : void 0].filter(Boolean).join(" ");
6156
6156
  }
6157
6157
  function detailWithSchema(detail, schema) {
6158
6158
  const renderedSchema = schemaLabel(schema);
@@ -7555,13 +7555,13 @@ function AxisPlot({
7555
7555
  opacity: path.opacity ?? 1
7556
7556
  })];
7557
7557
  }));
7558
- elements.push(...vectors.map((vector, index) => {
7559
- const color = vector.color ?? getToneColor(vector.tone ?? "blue", c);
7560
- const x1 = sx(vector.x1);
7561
- const y1 = sy(vector.y1);
7562
- const x2 = sx(vector.x2);
7563
- const y2 = sy(vector.y2);
7564
- if (vector.arrow) {
7558
+ elements.push(...vectors.map((vector2, index) => {
7559
+ const color = vector2.color ?? getToneColor(vector2.tone ?? "blue", c);
7560
+ const x1 = sx(vector2.x1);
7561
+ const y1 = sy(vector2.y1);
7562
+ const x2 = sx(vector2.x2);
7563
+ const y2 = sy(vector2.y2);
7564
+ if (vector2.arrow) {
7565
7565
  return VectorArrow({
7566
7566
  key: `axis-vector-${index}`,
7567
7567
  x1,
@@ -7569,9 +7569,9 @@ function AxisPlot({
7569
7569
  x2,
7570
7570
  y2,
7571
7571
  color,
7572
- strokeWidth: vector.strokeWidth,
7573
- arrowSize: vector.arrowSize,
7574
- opacity: vector.opacity
7572
+ strokeWidth: vector2.strokeWidth,
7573
+ arrowSize: vector2.arrowSize,
7574
+ opacity: vector2.opacity
7575
7575
  });
7576
7576
  }
7577
7577
  return VectorSegment({
@@ -7581,11 +7581,11 @@ function AxisPlot({
7581
7581
  x2,
7582
7582
  y2,
7583
7583
  color,
7584
- strokeWidth: vector.strokeWidth,
7585
- opacity: vector.opacity,
7586
- showStartDot: vector.showStartDot,
7587
- showEndDot: vector.showEndDot,
7588
- dotRadius: vector.dotRadius
7584
+ strokeWidth: vector2.strokeWidth,
7585
+ opacity: vector2.opacity,
7586
+ showStartDot: vector2.showStartDot,
7587
+ showEndDot: vector2.showEndDot,
7588
+ dotRadius: vector2.dotRadius
7589
7589
  });
7590
7590
  }));
7591
7591
  elements.push(...points.map((point, index) => SvgPoint({
@@ -9861,7 +9861,7 @@ function GeometryDiagram({
9861
9861
  width = 720,
9862
9862
  height = 440
9863
9863
  }) {
9864
- const bounds2 = geometryBounds(points);
9864
+ const bounds4 = geometryBounds(points);
9865
9865
  dimensions(width, height, "GeometryDiagram");
9866
9866
  labelText(title, "GeometryDiagram title", 32);
9867
9867
  bounded(segments, 256, "GeometryDiagram segments");
@@ -9909,10 +9909,10 @@ function GeometryDiagram({
9909
9909
  colorValue(angle.color, c.accent, `GeometryDiagram angle ${index} color`);
9910
9910
  });
9911
9911
  const padding = 80;
9912
- const maxRange = Math.max(bounds2.width, bounds2.height);
9912
+ const maxRange = Math.max(bounds4.width, bounds4.height);
9913
9913
  const scale = maxRange === 0 ? Math.min(width - padding * 2, height - padding * 2) : Math.min((width - padding * 2) / maxRange, (height - padding * 2) / maxRange);
9914
- const centerX = bounds2.minX / 2 + bounds2.maxX / 2;
9915
- const centerY = bounds2.minY / 2 + bounds2.maxY / 2;
9914
+ const centerX = bounds4.minX / 2 + bounds4.maxX / 2;
9915
+ const centerY = bounds4.minY / 2 + bounds4.maxY / 2;
9916
9916
  if (!Number.isFinite(centerX) || !Number.isFinite(centerY) || !Number.isFinite(scale) || scale <= 0) {
9917
9917
  throw new RangeError("GeometryDiagram coordinates cannot be mapped into the viewport.");
9918
9918
  }
@@ -11176,11 +11176,11 @@ function AttentionMatrix({
11176
11176
  const fullyMasked = mask?.[i].every((value) => !value) ?? false;
11177
11177
  if (Math.abs(total - (fullyMasked ? 0 : 1)) > 1e-6) throw new Error("Each visible attention row must sum to one");
11178
11178
  }
11179
- const labels = (input, count, prefix) => {
11179
+ const labels = (input, count, prefix2) => {
11180
11180
  if (input && (input.length !== count || input.some((value) => typeof value !== "string" || value.length > 24))) {
11181
11181
  throw new Error("Attention labels must match the matrix dimensions and contain at most 24 characters");
11182
11182
  }
11183
- return input ? [...input] : Array.from({ length: count }, (_, i) => `${prefix}${i + 1}`);
11183
+ return input ? [...input] : Array.from({ length: count }, (_, i) => `${prefix2}${i + 1}`);
11184
11184
  };
11185
11185
  const queryNames = labels(queryLabels, rows, "q");
11186
11186
  const keyNames = labels(keyLabels, columns, "k");
@@ -11869,16 +11869,16 @@ function cropFramePixels(pixels, canvasWidth, region) {
11869
11869
  }
11870
11870
  function deltaPixelFrame(frame, previous, enabled) {
11871
11871
  if (!enabled || !previous) return frame;
11872
- const bounds2 = changedBounds(previous, frame.pixels, frame.width, frame.height);
11873
- if (!bounds2 || bounds2.width === frame.width && bounds2.height === frame.height) return frame;
11872
+ const bounds4 = changedBounds(previous, frame.pixels, frame.width, frame.height);
11873
+ if (!bounds4 || bounds4.width === frame.width && bounds4.height === frame.height) return frame;
11874
11874
  return {
11875
11875
  ...frame,
11876
- x: bounds2.x,
11877
- y: bounds2.y,
11876
+ x: bounds4.x,
11877
+ y: bounds4.y,
11878
11878
  delta: true,
11879
- width: bounds2.width,
11880
- height: bounds2.height,
11881
- pixels: cropFramePixels(frame.pixels, frame.width, bounds2)
11879
+ width: bounds4.width,
11880
+ height: bounds4.height,
11881
+ pixels: cropFramePixels(frame.pixels, frame.width, bounds4)
11882
11882
  };
11883
11883
  }
11884
11884
  function encodeGif(frames, loop, deltaFrames) {
@@ -12304,12 +12304,12 @@ function normalizedOpacity(value, name = "Canvas opacity") {
12304
12304
  finite3(value, name);
12305
12305
  return Math.max(0, Math.min(1, value));
12306
12306
  }
12307
- function validateBounds(bounds2) {
12308
- finite3(bounds2.x, "Canvas x");
12309
- finite3(bounds2.y, "Canvas y");
12310
- positive2(bounds2.width, "Canvas width");
12311
- positive2(bounds2.height, "Canvas height");
12312
- nonnegative(bounds2.radius ?? 14, "Canvas radius");
12307
+ function validateBounds(bounds4) {
12308
+ finite3(bounds4.x, "Canvas x");
12309
+ finite3(bounds4.y, "Canvas y");
12310
+ positive2(bounds4.width, "Canvas width");
12311
+ positive2(bounds4.height, "Canvas height");
12312
+ nonnegative(bounds4.radius ?? 14, "Canvas radius");
12313
12313
  }
12314
12314
  function layoutTokenRow(values, options = {}) {
12315
12315
  const { advance = 24, gap = 16, minWidth = 64, paddingX = 17, width } = options;
@@ -12335,24 +12335,24 @@ function layoutTokenRow(values, options = {}) {
12335
12335
  return items;
12336
12336
  }
12337
12337
  function createCanvasComponents(painter) {
12338
- function fade(alpha2, draw) {
12339
- const amount2 = normalizedOpacity(alpha2);
12338
+ function fade(alpha3, draw) {
12339
+ const amount2 = normalizedOpacity(alpha3);
12340
12340
  if (amount2 > 0) painter.opacity(amount2, draw);
12341
12341
  }
12342
12342
  function panel(options, draw) {
12343
12343
  validateBounds(options);
12344
12344
  const { x, y, width, height, fill, stroke, radius = 14, padding = 10, id, scope = "container", opacity = 1 } = options;
12345
12345
  nonnegative(padding, "Canvas padding");
12346
- const alpha2 = normalizedOpacity(opacity);
12346
+ const alpha3 = normalizedOpacity(opacity);
12347
12347
  if (scope !== "container" && scope !== "label") throw new Error("Canvas scope must be container or label");
12348
12348
  let shape;
12349
- const paint = () => painter.opacity(alpha2, () => {
12349
+ const paint = () => painter.opacity(alpha3, () => {
12350
12350
  shape = painter.rect(x, y, width, height, fill, stroke, radius);
12351
12351
  if (draw) {
12352
- const bounds2 = { x, y, width, height, radius };
12352
+ const bounds4 = { x, y, width, height, radius };
12353
12353
  const scopeOptions = { padding, id };
12354
- if (scope === "label") painter.labelScope(bounds2, draw, scopeOptions);
12355
- else painter.container(bounds2, draw, scopeOptions);
12354
+ if (scope === "label") painter.labelScope(bounds4, draw, scopeOptions);
12355
+ else painter.container(bounds4, draw, scopeOptions);
12356
12356
  }
12357
12357
  });
12358
12358
  if (options.focusTarget && painter.target) painter.target(options.focusTarget, paint);
@@ -12407,11 +12407,11 @@ function createCanvasComponents(painter) {
12407
12407
  finite3(y, "Token row y");
12408
12408
  positive2(height, "Token height");
12409
12409
  finite3(reveal, "Token reveal");
12410
- const alpha2 = normalizedOpacity(opacity);
12410
+ const alpha3 = normalizedOpacity(opacity);
12411
12411
  const items = layoutTokenRow(values, options);
12412
12412
  const shapes = [];
12413
12413
  for (let index = 0; index < items.length; index += 1) {
12414
- const amount2 = Math.max(0, Math.min(1, reveal * items.length - index)) * alpha2;
12414
+ const amount2 = Math.max(0, Math.min(1, reveal * items.length - index)) * alpha3;
12415
12415
  if (amount2 <= 0) continue;
12416
12416
  const { text: label, x, width } = items[index];
12417
12417
  const shape = card({ ...style, label, x, y, width, height, opacity: amount2 });
@@ -12468,11 +12468,11 @@ function edgeDistance(shape, ux, uy) {
12468
12468
  return low;
12469
12469
  }
12470
12470
  function safeGap(shape, ux, uy, clearance, edge) {
12471
- const expanded = Math.min(
12471
+ const expanded2 = Math.min(
12472
12472
  ux === 0 ? Infinity : (shape.width / 2 + clearance) / Math.abs(ux),
12473
12473
  uy === 0 ? Infinity : (shape.height / 2 + clearance) / Math.abs(uy)
12474
12474
  );
12475
- return expanded - edge;
12475
+ return expanded2 - edge;
12476
12476
  }
12477
12477
  function createTeachingTransfer(painter) {
12478
12478
  return (options) => {
@@ -12528,7 +12528,7 @@ function layoutCellGrid(options) {
12528
12528
  if (![rows, columns, rows * columns].every(Number.isSafeInteger) || rows <= 0 || columns <= 0) {
12529
12529
  throw new Error("Grid rows and columns must be positive safe integers");
12530
12530
  }
12531
- const bounds2 = { x, y, width, height };
12531
+ const bounds4 = { x, y, width, height };
12532
12532
  const cells = Array.from({ length: rows }, (_, row) => Array.from({ length: columns }, (_2, column) => ({
12533
12533
  x: x + column * width / columns,
12534
12534
  y: y + row * height / rows,
@@ -12536,7 +12536,7 @@ function layoutCellGrid(options) {
12536
12536
  height: height / rows
12537
12537
  })));
12538
12538
  return {
12539
- bounds: bounds2,
12539
+ bounds: bounds4,
12540
12540
  cells,
12541
12541
  cell(row, column) {
12542
12542
  if (!Number.isSafeInteger(row) || !Number.isSafeInteger(column) || row < 0 || row >= rows || column < 0 || column >= columns) {
@@ -12671,9 +12671,9 @@ function createTeachingTimeline(painter) {
12671
12671
  if (!Number.isFinite(value) || value < lo || value > hi) throw new Error("Timeline point must lie inside the domain");
12672
12672
  return left + (value - lo) / (hi - lo) * plotWidth;
12673
12673
  };
12674
- const bounds2 = { x, y, width, height };
12675
- const result = { bounds: bounds2, time, point, lanes: /* @__PURE__ */ Object.create(null), intervals: /* @__PURE__ */ Object.create(null) };
12676
- painter.container(bounds2, () => {
12674
+ const bounds4 = { x, y, width, height };
12675
+ const result = { bounds: bounds4, time, point, lanes: /* @__PURE__ */ Object.create(null), intervals: /* @__PURE__ */ Object.create(null) };
12676
+ painter.container(bounds4, () => {
12677
12677
  lanes.forEach((lane, index) => target(lane.focusTarget, () => {
12678
12678
  const top = y + index * (laneHeight + laneGap);
12679
12679
  const track = { x: left - 2, y: top + labelHeight, width: plotWidth + 4, height: barHeight };
@@ -12900,11 +12900,11 @@ function createFocusDirector(painter, options = {}) {
12900
12900
  }
12901
12901
  function createTeachingFocus(painter) {
12902
12902
  function focusFrame(options) {
12903
- const { bounds: bounds2, strength, color = "#63DEEC", padding = 8, clip } = options;
12904
- if (![bounds2.x, bounds2.y, bounds2.width, bounds2.height, strength, padding].every(Number.isFinite) || bounds2.width <= 0 || bounds2.height <= 0 || padding < 0 || strength < 0 || strength > 1) throw new Error("Invalid focus frame geometry or strength");
12903
+ const { bounds: bounds4, strength, color = "#63DEEC", padding = 8, clip } = options;
12904
+ if (![bounds4.x, bounds4.y, bounds4.width, bounds4.height, strength, padding].every(Number.isFinite) || bounds4.width <= 0 || bounds4.height <= 0 || padding < 0 || strength < 0 || strength > 1) throw new Error("Invalid focus frame geometry or strength");
12905
12905
  if (strength === 0) return;
12906
12906
  const corners = (offset) => {
12907
- const x = bounds2.x - offset, y = bounds2.y - offset, w = bounds2.width + offset * 2, h = bounds2.height + offset * 2;
12907
+ const x = bounds4.x - offset, y = bounds4.y - offset, w = bounds4.width + offset * 2, h = bounds4.height + offset * 2;
12908
12908
  const corner = Math.min(24, w / 4, h / 4);
12909
12909
  return [[x, y, 1, 1], [x + w, y, -1, 1], [x, y + h, 1, -1], [x + w, y + h, -1, -1]].map(([cx, cy, sx, sy]) => [{ x: cx + sx * corner, y: cy }, { x: cx, y: cy }, { x: cx, y: cy + sy * corner }]);
12910
12910
  };
@@ -12928,31 +12928,874 @@ function createTeachingFocus(painter) {
12928
12928
  return { focusFrame };
12929
12929
  }
12930
12930
 
12931
+ // src/teaching-vector.ts
12932
+ var clamp4 = (value) => Math.max(0, Math.min(1, value));
12933
+ var cleanZero = (value) => value === 0 ? 0 : value;
12934
+ function finite4(value, name) {
12935
+ if (!Number.isFinite(value)) throw new Error(`${name} must be finite`);
12936
+ return value;
12937
+ }
12938
+ function vector(values, dimensions2, name) {
12939
+ if (values.length !== dimensions2) throw new Error(`${name} must have ${dimensions2} coordinates`);
12940
+ return values.map((value) => cleanZero(finite4(value, name)));
12941
+ }
12942
+ function add(left, right) {
12943
+ return left.map((value, index) => cleanZero(finite4(value + right[index], "Weighted vector sum")));
12944
+ }
12945
+ function weightedVectorState(options) {
12946
+ const progress = clamp4(finite4(options.progress, "Weighted vector progress"));
12947
+ const dimensions2 = options.initial?.length ?? options.terms[0]?.values.length ?? 0;
12948
+ if (!dimensions2) throw new Error("Weighted vectors require at least one coordinate; an empty sum needs an initial vector");
12949
+ const initial = options.initial ? vector(options.initial, dimensions2, "Initial vector") : Array(dimensions2).fill(0);
12950
+ const ids = /* @__PURE__ */ new Set();
12951
+ let prefix2 = [...initial];
12952
+ const position2 = progress * options.terms.length;
12953
+ const completedCount = Math.min(options.terms.length, Math.floor(position2));
12954
+ const terms = options.terms.map((term, index) => {
12955
+ if (typeof term.id !== "string" || !term.id.trim() || term.id !== term.id.trim() || ids.has(term.id)) {
12956
+ throw new Error("Weighted vector terms require distinct nonempty IDs without surrounding whitespace");
12957
+ }
12958
+ ids.add(term.id);
12959
+ const label = term.label ?? term.id;
12960
+ if (typeof label !== "string" || !label.trim()) throw new Error("Weighted vector labels must be nonempty");
12961
+ const weight = finite4(term.weight, "Vector weight");
12962
+ const values = vector(term.values, dimensions2, `Vector ${term.id}`);
12963
+ const contribution = values.map((value) => cleanZero(finite4(weight * value, "Weighted vector contribution")));
12964
+ const start = [...prefix2], end = add(start, contribution);
12965
+ prefix2 = end;
12966
+ const fraction = clamp4(position2 - index);
12967
+ const status = fraction === 1 ? "completed" : index === completedCount && progress < 1 ? "current" : "pending";
12968
+ const applied = contribution.map((value) => cleanZero(value * fraction));
12969
+ return {
12970
+ ...term,
12971
+ label,
12972
+ values,
12973
+ weight,
12974
+ status,
12975
+ progress: fraction,
12976
+ contribution,
12977
+ applied,
12978
+ start,
12979
+ end,
12980
+ currentEnd: add(start, applied),
12981
+ zero: contribution.every((value) => value === 0)
12982
+ };
12983
+ });
12984
+ const completedSum = completedCount ? [...terms[completedCount - 1].end] : [...initial];
12985
+ const current = terms.find((term) => term.status === "current") ?? null;
12986
+ return {
12987
+ progress,
12988
+ dimensions: dimensions2,
12989
+ initial,
12990
+ terms,
12991
+ completedCount,
12992
+ current,
12993
+ completedSum,
12994
+ sum: current ? [...current.currentEnd] : [...completedSum],
12995
+ total: [...prefix2]
12996
+ };
12997
+ }
12998
+ function positive4(value, name) {
12999
+ if (finite4(value, name) <= 0) throw new Error(`${name} must be positive`);
13000
+ }
13001
+ function bounds2(value, name) {
13002
+ finite4(value.x, `${name} x`);
13003
+ finite4(value.y, `${name} y`);
13004
+ positive4(value.width, `${name} width`);
13005
+ positive4(value.height, `${name} height`);
13006
+ }
13007
+ function createTeachingVectorAccumulation(painter) {
13008
+ return (options) => {
13009
+ const state = weightedVectorState(options);
13010
+ const {
13011
+ plot,
13012
+ ledger,
13013
+ projection,
13014
+ fontSize = 28,
13015
+ color = "#63DEEC",
13016
+ restColor = "#8D9CB9",
13017
+ completedOpacity = 0.45,
13018
+ width = 4,
13019
+ endpointRadius = 5,
13020
+ revealTotal = false,
13021
+ totalLabel = "Accumulated vector",
13022
+ format = (value) => String(Number(value.toPrecision(4)))
13023
+ } = options;
13024
+ bounds2(plot.bounds, "Vector plot");
13025
+ bounds2(ledger, "Vector ledger");
13026
+ positive4(fontSize, "Vector font size");
13027
+ positive4(width, "Vector stroke width");
13028
+ positive4(endpointRadius, "Vector endpoint radius");
13029
+ finite4(completedOpacity, "Completed vector opacity");
13030
+ if (completedOpacity < 0 || completedOpacity > 1) throw new Error("Completed vector opacity must lie between zero and one");
13031
+ const [x0, x1] = plot.xDomain, [y0, y1] = plot.yDomain;
13032
+ for (const value of [x0, x1, y0, y1]) finite4(value, "Vector plot domain");
13033
+ if (x1 <= x0 || y1 <= y0) throw new Error("Vector plot domains must increase");
13034
+ const sx = plot.bounds.width / (x1 - x0), sy = plot.bounds.height / (y1 - y0);
13035
+ if (!Number.isFinite(sx) || !Number.isFinite(sy) || sx <= 0 || sy <= 0 || Math.abs(sx - sy) > Math.max(sx, sy) * 1e-9) {
13036
+ throw new Error("Weighted vector drawing requires equal-unit plot geometry");
13037
+ }
13038
+ if (state.dimensions !== 2 && !projection) throw new Error("Weighted vector drawing requires 2D values or an explicit projection");
13039
+ if (projection && !projection.label.trim()) throw new Error("Vector projection requires a visible declaration");
13040
+ const rowHeight = fontSize * 2.5, headerHeight = fontSize * 1.6;
13041
+ if (ledger.height < headerHeight + state.terms.length * rowHeight + fontSize * 1.8) {
13042
+ throw new Error("Vector ledger height must contain the identities, contributions and result");
13043
+ }
13044
+ const point = (values) => {
13045
+ const projected = projection ? projection.point([...values]) : values;
13046
+ if (projected.length !== 2) throw new Error("Vector projection must return exactly two coordinates");
13047
+ const [x, y] = projected;
13048
+ finite4(x, "Projected vector x");
13049
+ finite4(y, "Projected vector y");
13050
+ if (x < x0 || x > x1 || y < y0 || y > y1) throw new Error("Vector endpoints must lie inside the declared plot domains");
13051
+ const p = plot.point(x, y);
13052
+ finite4(p.x, "Vector endpoint x");
13053
+ finite4(p.y, "Vector endpoint y");
13054
+ const expectedX = finite4(plot.bounds.x + (x - x0) * sx, "Declared vector endpoint x");
13055
+ const expectedY = finite4(plot.bounds.y + plot.bounds.height - (y - y0) * sy, "Declared vector endpoint y");
13056
+ const tolerance = Math.max(1, Math.abs(expectedX), Math.abs(expectedY), plot.bounds.width, plot.bounds.height) * 1e-9;
13057
+ if (Math.abs(p.x - expectedX) > tolerance || Math.abs(p.y - expectedY) > tolerance) {
13058
+ throw new Error("Vector plot mapping must match its declared equal-unit transform");
13059
+ }
13060
+ return p;
13061
+ };
13062
+ const segments = [];
13063
+ for (const term of state.terms) {
13064
+ const from = point(term.start);
13065
+ point(term.end);
13066
+ const to = point(term.currentEnd);
13067
+ if (term.status !== "pending") segments.push({
13068
+ id: term.id,
13069
+ status: term.status,
13070
+ from,
13071
+ to,
13072
+ zero: Math.hypot(to.x - from.x, to.y - from.y) < 1e-9
13073
+ });
13074
+ }
13075
+ const endpoint2 = point(state.sum);
13076
+ const vectorText = (values) => `(${values.map(format).join(", ")})`;
13077
+ const target = (id, draw) => painter.target ? painter.target(id, draw) : draw();
13078
+ const paintedTerms = state.terms.map((term, index) => ({
13079
+ term,
13080
+ index,
13081
+ input: `${term.label}: ${format(term.weight)} \xD7 ${vectorText(term.values)}`,
13082
+ detail: term.status === "pending" ? "pending" : `${term.status}: ${vectorText(term.applied)}`
13083
+ }));
13084
+ const totalText = `${totalLabel}: ${revealTotal ? vectorText(state.sum) : "?"}`;
13085
+ for (const segment of segments) {
13086
+ const term = state.terms.find((term2) => term2.id === segment.id);
13087
+ const ink = term.color ?? color;
13088
+ target(term.id, () => painter.opacity(term.status === "completed" ? completedOpacity : 1, () => {
13089
+ if (segment.zero) painter.circle(segment.to.x, segment.to.y, endpointRadius, "transparent", ink, width);
13090
+ else painter.arrow(segment.from.x, segment.from.y, segment.to.x, segment.to.y, ink, width);
13091
+ }));
13092
+ }
13093
+ if (revealTotal) {
13094
+ const mark = () => {
13095
+ painter.circle(endpoint2.x, endpoint2.y, endpointRadius * 1.5, color);
13096
+ };
13097
+ if (options.totalTarget) target(options.totalTarget, mark);
13098
+ else mark();
13099
+ }
13100
+ painter.labelScope(ledger, () => {
13101
+ painter.text(
13102
+ projection ? `Projection: ${projection.label}` : "Weighted contributions",
13103
+ ledger.x + 12,
13104
+ ledger.y + fontSize,
13105
+ fontSize * 0.85,
13106
+ restColor
13107
+ );
13108
+ for (const { term, index, input, detail } of paintedTerms) target(term.id, () => {
13109
+ const ink = term.color ?? color;
13110
+ const y = ledger.y + headerHeight + index * rowHeight;
13111
+ painter.text(input, ledger.x + 12, y + fontSize, fontSize, term.status === "pending" ? restColor : ink);
13112
+ painter.text(detail, ledger.x + 12, y + fontSize * 1.9, fontSize * 0.8, restColor);
13113
+ });
13114
+ const result = () => {
13115
+ painter.text(
13116
+ totalText,
13117
+ ledger.x + 12,
13118
+ ledger.y + headerHeight + state.terms.length * rowHeight + fontSize,
13119
+ fontSize,
13120
+ revealTotal ? color : restColor
13121
+ );
13122
+ };
13123
+ if (options.totalTarget) target(options.totalTarget, result);
13124
+ else result();
13125
+ }, { padding: 4 });
13126
+ return { state, segments, endpoint: endpoint2 };
13127
+ };
13128
+ }
13129
+
13130
+ // src/teaching-categorical-sampling.ts
13131
+ function categoricalSampling(options) {
13132
+ if (options.normalization !== "probabilities" && options.normalization !== "weights") throw new Error("Sampling requires an explicit mass normalization contract");
13133
+ if (!options.categories.length) throw new Error("Sampling needs at least one category");
13134
+ const ids = /* @__PURE__ */ new Set();
13135
+ let total = 0;
13136
+ for (const category of options.categories) {
13137
+ if (!category.id || ids.has(category.id) || !category.label.trim()) throw new Error("Sampling category IDs must be unique and labels nonempty");
13138
+ if (!Number.isFinite(category.mass) || category.mass < 0) throw new Error("Sampling masses must be finite and nonnegative");
13139
+ ids.add(category.id);
13140
+ total += category.mass;
13141
+ }
13142
+ if (!Number.isFinite(total) || total <= 0) throw new Error("Sampling total mass must be finite and positive");
13143
+ if (options.normalization === "probabilities" && Math.abs(total - 1) > 1e-12) throw new Error("Sampling probabilities must sum to one within 1e-12");
13144
+ let cumulative = 0;
13145
+ let lastPositive = 0;
13146
+ options.categories.forEach((category, index) => {
13147
+ if (category.mass > 0) lastPositive = index;
13148
+ });
13149
+ const categories = options.categories.map((category, index) => {
13150
+ const lower = cumulative, probability = category.mass / total;
13151
+ cumulative = index === lastPositive ? 1 : Math.min(1, cumulative + probability);
13152
+ if (category.mass > 0 && (probability === 0 || cumulative <= lower)) throw new Error("Positive category is too small for cumulative floating-point precision");
13153
+ return { ...category, probability, lower, upper: cumulative, count: 0, empiricalProbability: null };
13154
+ });
13155
+ ids.clear();
13156
+ const draws = options.draws.map((draw) => {
13157
+ if (!draw.id || ids.has(draw.id)) throw new Error("Sampling draw IDs must be nonempty and unique");
13158
+ if (!Number.isFinite(draw.uniform) || draw.uniform < 0 || draw.uniform >= 1) throw new Error("Supplied uniform draws must be finite inside [0, 1)");
13159
+ ids.add(draw.id);
13160
+ const categoryIndex = categories.findIndex((category) => category.mass > 0 && draw.uniform >= category.lower && draw.uniform < category.upper);
13161
+ if (categoryIndex < 0) throw new Error("Supplied draw could not be represented by the normalized intervals");
13162
+ categories[categoryIndex].count += 1;
13163
+ return { ...draw, categoryId: categories[categoryIndex].id, categoryIndex };
13164
+ });
13165
+ if (draws.length) categories.forEach((category) => {
13166
+ category.empiricalProbability = category.count / draws.length;
13167
+ });
13168
+ return { inputTotal: total, normalization: options.normalization, categories, draws };
13169
+ }
13170
+ var COLORS2 = ["#79A6FF", "#FF8DC3", "#63DEEC", "#FFCE73", "#A6DF91"];
13171
+ function createTeachingCategoricalSampling(painter) {
13172
+ return (options) => {
13173
+ const model = categoricalSampling(options);
13174
+ const { x, y, width, height, fontSize = 28, color = "#DEE7F5", trackColor = "#18283B", visibleDraws = 0, drawProgress = 0, showEmpirical = false, formatProbability = (value) => value.toFixed(3) } = options;
13175
+ if (![x, y, x + width, y + height, fontSize].every(Number.isFinite) || fontSize <= 0 || width <= 0 || height <= 0) throw new Error("Sampling needs finite positive bounds and font size");
13176
+ if (!Number.isInteger(visibleDraws) || visibleDraws < 0 || visibleDraws > model.draws.length) throw new Error("Visible sample count must be an integer inside the supplied draw count");
13177
+ if (!Number.isFinite(drawProgress) || drawProgress < 0 || drawProgress > 1 || visibleDraws === model.draws.length && drawProgress !== 0) throw new Error("Sampling progress must be inside [0, 1] for an available next draw");
13178
+ if (showEmpirical && visibleDraws !== model.draws.length) throw new Error("Empirical reveal requires every supplied sample to be retained");
13179
+ const columns = options.columns ?? Math.max(1, Math.min(8, model.draws.length));
13180
+ if (!Number.isInteger(columns) || columns < 1) throw new Error("Sampling columns must be a positive integer");
13181
+ const railWidth = fontSize * 2, contentWidth = width - railWidth;
13182
+ const gap = fontSize * 0.5, cellWidth = (contentWidth - 4 - (columns - 1) * gap) / columns, cellHeight = fontSize * 1.9;
13183
+ const legendColumns = Math.min(3, model.categories.length), legendRows = Math.ceil(model.categories.length / legendColumns), legendHeight = legendRows * fontSize * 1.7;
13184
+ const bandY = y + fontSize * 4, bandHeight = fontSize * 1.3, legendY = bandY + bandHeight + fontSize * 1.5;
13185
+ const captionY = legendY + legendHeight + fontSize * 0.5, poolY = captionY + fontSize * 3.3, rows = Math.ceil(model.draws.length / columns), empiricalY = poolY + Math.max(1, rows) * (cellHeight + gap) + fontSize * 2;
13186
+ if (cellWidth < fontSize * 2 || contentWidth / legendColumns < fontSize * 5 || empiricalY + bandHeight + fontSize * 1.7 > y + height) throw new Error("Sampling bounds cannot fit probability labels, sample IDs and empirical strip");
13187
+ const inset = fontSize * 0.22 + 2, stripX = x + inset, stripWidth = contentWidth - inset * 2;
13188
+ const point = (u) => stripX + u * stripWidth;
13189
+ const categoryColor = (index) => model.categories[index].color ?? COLORS2[index % COLORS2.length];
13190
+ const target = (id, draw) => id && painter.target ? painter.target(id, draw) : draw();
13191
+ const label = (value, bounds4, align = "left", ink = color, size = fontSize) => painter.labelScope(bounds4, () => painter.text(value, align === "center" ? bounds4.x + bounds4.width / 2 : align === "right" ? bounds4.x + bounds4.width : bounds4.x, bounds4.y + size * 1.05, size, ink, align), { padding: 0 });
13192
+ const strip = (top, empirical) => {
13193
+ painter.rect(stripX, top, stripWidth, bandHeight, trackColor, void 0, 0);
13194
+ let cumulative = 0;
13195
+ model.categories.forEach((category, index) => {
13196
+ const probability = empirical ? category.empiricalProbability ?? 0 : category.probability;
13197
+ const left = cumulative;
13198
+ cumulative += probability;
13199
+ if (probability > 0) target(category.focusTarget, () => painter.rect(point(left), top, stripWidth * probability, bandHeight, categoryColor(index), void 0, 0));
13200
+ });
13201
+ };
13202
+ const sampleBounds = model.draws.map((_draw, index) => ({ x: x + 2 + index % columns * (cellWidth + gap), y: poolY + Math.floor(index / columns) * (cellHeight + gap), width: cellWidth, height: cellHeight }));
13203
+ const shapes = [];
13204
+ painter.container({ x, y, width, height }, () => {
13205
+ label(options.normalization === "weights" ? "Original probabilities \xB7 normalized supplied weights" : "Original probabilities \xB7 supplied distribution", { x, y, width: contentWidth, height: fontSize * 1.6 });
13206
+ strip(bandY, false);
13207
+ label("0", { x, y: bandY + bandHeight + 2, width: fontSize * 2, height: fontSize * 1.2 }, "left", color, fontSize * 0.8);
13208
+ label("1", { x: x + contentWidth - fontSize * 2, y: bandY + bandHeight + 2, width: fontSize * 2, height: fontSize * 1.2 }, "right", color, fontSize * 0.8);
13209
+ model.categories.forEach((category, index) => {
13210
+ const bounds4 = { x: x + index % legendColumns * contentWidth / legendColumns, y: legendY + Math.floor(index / legendColumns) * fontSize * 1.7, width: contentWidth / legendColumns - gap, height: fontSize * 1.5 };
13211
+ target(category.focusTarget, () => label(`${category.label}: ${formatProbability(category.probability)}`, bounds4, "left", categoryColor(index)));
13212
+ });
13213
+ label(`Supplied samples \xB7 ${visibleDraws} retained / ${model.draws.length}`, { x, y: poolY - fontSize * 1.8, width: contentWidth, height: fontSize * 1.5 });
13214
+ for (let index = 0; index < visibleDraws; index += 1) target(options.sampleFocusTarget, () => {
13215
+ const draw = model.draws[index], bounds4 = sampleBounds[index];
13216
+ shapes.push(painter.rect(bounds4.x, bounds4.y, bounds4.width, bounds4.height, trackColor, categoryColor(draw.categoryIndex), 4));
13217
+ label(draw.id, bounds4, "center", categoryColor(draw.categoryIndex));
13218
+ });
13219
+ if (drawProgress > 0 && visibleDraws < model.draws.length) target(options.sampleFocusTarget, () => {
13220
+ const draw = model.draws[visibleDraws], destination = sampleBounds[visibleDraws], landed = drawProgress >= 0.4;
13221
+ const from = { x: point(draw.uniform), y: bandY - fontSize * 1.2 }, onBand = { x: point(draw.uniform), y: bandY + bandHeight / 2 };
13222
+ const progress = landed ? (drawProgress - 0.4) / 0.6 : drawProgress / 0.4;
13223
+ const destinationPoint = { x: destination.x + destination.width / 2, y: destination.y + destination.height / 2 };
13224
+ const railX = x + width - inset;
13225
+ const route = landed ? [onBand, from, { x: railX, y: from.y }, { x: railX, y: destinationPoint.y }, destinationPoint] : [from, onBand];
13226
+ const lengths = route.slice(1).map((point2, index) => Math.hypot(point2.x - route[index].x, point2.y - route[index].y));
13227
+ let remaining = progress * lengths.reduce((sum, length) => sum + length, 0);
13228
+ let marker = route[route.length - 1];
13229
+ for (let index = 0; index < lengths.length; index += 1) {
13230
+ const length = lengths[index];
13231
+ if (remaining <= length && length > 0) {
13232
+ const ratio = remaining / length;
13233
+ marker = { x: route[index].x + (route[index + 1].x - route[index].x) * ratio, y: route[index].y + (route[index + 1].y - route[index].y) * ratio };
13234
+ break;
13235
+ }
13236
+ remaining -= length;
13237
+ }
13238
+ const ink = landed ? categoryColor(draw.categoryIndex) : color;
13239
+ painter.circle(marker.x, marker.y, fontSize * 0.22, ink, trackColor, 3);
13240
+ const caption = `${landed ? "Copy" : "Draw"} ${draw.id} \xB7 supplied u=${draw.uniform.toFixed(3)}`;
13241
+ label(caption, { x, y: captionY, width: contentWidth, height: fontSize * 1.3 }, "left", ink, fontSize * 0.8);
13242
+ });
13243
+ if (showEmpirical) {
13244
+ label(model.draws.length ? "Empirical frequencies \xB7 supplied sample only" : "No samples \xB7 empirical distribution undefined", { x, y: empiricalY - fontSize * 1.7, width: contentWidth, height: fontSize * 1.5 });
13245
+ if (model.draws.length) {
13246
+ strip(empiricalY, true);
13247
+ const text = model.categories.map((category) => `${category.label}: ${category.count}/${model.draws.length}`).join(" \xB7 ");
13248
+ label(text, { x, y: empiricalY + bandHeight + fontSize * 0.25, width: contentWidth, height: fontSize * 1.3 }, "left", color, fontSize * 0.8);
13249
+ }
13250
+ }
13251
+ }, { padding: 0 });
13252
+ return { model, sampleBounds, shapes, point, visibleDraws };
13253
+ };
13254
+ }
13255
+
13256
+ // src/teaching-routed-transfer.ts
13257
+ function finite5(value, name) {
13258
+ if (!Number.isFinite(value)) throw new Error(`${name} must be finite`);
13259
+ }
13260
+ function nonnegative3(value, name) {
13261
+ finite5(value, name);
13262
+ if (value < 0) throw new Error(`${name} must be nonnegative`);
13263
+ }
13264
+ function bounds3(value, name) {
13265
+ for (const field of ["x", "y", "width", "height"]) finite5(value[field], `${name} ${field}`);
13266
+ if (value.width <= 0 || value.height <= 0) throw new Error(`${name} dimensions must be positive`);
13267
+ finite5(value.x + value.width, `${name} right edge`);
13268
+ finite5(value.y + value.height, `${name} bottom edge`);
13269
+ }
13270
+ function identifier(id, name) {
13271
+ if (typeof id !== "string" || !id.trim()) throw new Error(`${name} must be a nonempty ID`);
13272
+ }
13273
+ function alpha2(value) {
13274
+ finite5(value, "Routed transfer opacity");
13275
+ return Math.max(0, Math.min(1, value));
13276
+ }
13277
+ function expanded(box2, clearance) {
13278
+ return { left: box2.x - clearance, top: box2.y - clearance, right: box2.x + box2.width + clearance, bottom: box2.y + box2.height + clearance };
13279
+ }
13280
+ function lengthOf(points) {
13281
+ let sum = 0;
13282
+ for (let i = 1; i < points.length; i++) sum += Math.hypot(points[i].x - points[i - 1].x, points[i].y - points[i - 1].y);
13283
+ return sum;
13284
+ }
13285
+ function trimLeads(points, amount2) {
13286
+ const length = lengthOf(points);
13287
+ if (length <= 2 * amount2) throw new Error("endpoint spacing leaves no positive-length clear transfer");
13288
+ const result = [pointAlongSamples(points, amount2 / length)];
13289
+ let distance = 0;
13290
+ for (let i = 1; i < points.length; i++) {
13291
+ distance += Math.hypot(points[i].x - points[i - 1].x, points[i].y - points[i - 1].y);
13292
+ if (distance > amount2 + 1e-6 && distance < length - amount2 - 1e-6) result.push(points[i]);
13293
+ }
13294
+ result.push(pointAlongSamples(points, 1 - amount2 / length));
13295
+ return result;
13296
+ }
13297
+ function parameters(options) {
13298
+ identifier(options.id, "Routed transfer ID");
13299
+ identifier(options.source.id, "Routed transfer source");
13300
+ identifier(options.target.id, "Routed transfer target");
13301
+ if (options.source.id === options.target.id) throw new Error("Routed transfer source and target IDs must differ");
13302
+ bounds3(options.source.shape, "Routed transfer source");
13303
+ bounds3(options.target.shape, "Routed transfer target");
13304
+ bounds3(options.corridor, "Routed transfer corridor");
13305
+ const ids = /* @__PURE__ */ new Set([options.source.id, options.target.id]);
13306
+ for (const obstacle of options.obstacles) {
13307
+ identifier(obstacle.id, "Routed transfer obstacle");
13308
+ if (ids.has(obstacle.id)) throw new Error(`Duplicate routed transfer object ID: ${obstacle.id}`);
13309
+ ids.add(obstacle.id);
13310
+ bounds3(obstacle.bounds, `Routed transfer obstacle ${obstacle.id}`);
13311
+ }
13312
+ const width = options.width ?? 3, margin = options.margin ?? 2;
13313
+ nonnegative3(width, "Routed transfer width");
13314
+ if (width === 0) throw new Error("Routed transfer width must be positive");
13315
+ nonnegative3(margin, "Routed transfer margin");
13316
+ if (options.progress !== void 0) finite5(options.progress, "Routed transfer progress");
13317
+ if (options.marker && options.progress === void 0) throw new Error("Routed transfer marker requires progress");
13318
+ const radius = options.marker?.radius ?? 7, strokeWidth = options.marker?.strokeWidth ?? 3;
13319
+ nonnegative3(radius, "Routed transfer marker radius");
13320
+ if (radius === 0) throw new Error("Routed transfer marker radius must be positive");
13321
+ nonnegative3(strokeWidth, "Routed transfer marker stroke width");
13322
+ const markerInk = options.progress === void 0 ? 0 : radius + (options.marker?.stroke ? strokeWidth / 2 : 0);
13323
+ const clearance = Math.max(width / 2, markerInk) + margin;
13324
+ const opacity = Math.min(alpha2(options.source.opacity), alpha2(options.target.opacity), alpha2(options.opacity ?? 1));
13325
+ return { width, margin, radius, strokeWidth, clearance, opacity };
13326
+ }
13327
+ function planTeachingRoutedTransfer(options) {
13328
+ const { clearance } = parameters(options);
13329
+ const fail = (reason) => {
13330
+ throw new Error(`Cannot route transfer ${options.id} (${options.source.id} \u2192 ${options.target.id}): ${reason}`);
13331
+ };
13332
+ const guard = clearance + 0.01, corridor = options.corridor;
13333
+ if (corridor.width <= 2 * guard || corridor.height <= 2 * guard) fail("corridor is too small for the requested ink clearance");
13334
+ const origin = { x: corridor.x + guard, y: corridor.y + guard };
13335
+ const toLocal = (shape) => {
13336
+ const x = shape.x - origin.x, y = shape.y - origin.y;
13337
+ finite5(x, "Routed transfer local x");
13338
+ finite5(y, "Routed transfer local y");
13339
+ return { x: Number(x.toFixed(6)), y: Number(y.toFixed(6)), width: shape.width, height: shape.height };
13340
+ };
13341
+ const endpoints = [options.source, options.target];
13342
+ const nodes = endpoints.map((endpoint2) => {
13343
+ const b = toLocal(endpoint2.shape);
13344
+ return { id: endpoint2.id, cx: b.x + b.width / 2, cy: b.y + b.height / 2, width: b.width, height: b.height };
13345
+ });
13346
+ const obstacles = options.obstacles.map((obstacle) => expanded(toLocal(obstacle.bounds), 0));
13347
+ const result = routeOrthogonalGraph(nodes, [{ from: options.source.id, to: options.target.id, fromSide: options.source.side, toSide: options.target.side }], corridor.width - 2 * guard, corridor.height - 2 * guard, guard, 14, obstacles);
13348
+ const raw = result.routes.get(0);
13349
+ if (!raw) return fail(result.failures[0]?.reason ?? "no legal route was returned");
13350
+ const points = (() => {
13351
+ try {
13352
+ return trimLeads(raw, guard).map((point) => ({ x: point.x + origin.x, y: point.y + origin.y }));
13353
+ } catch (error) {
13354
+ return fail(error instanceof Error ? error.message : String(error));
13355
+ }
13356
+ })();
13357
+ const occupied = [...endpoints.map((endpoint2) => expanded(endpoint2.shape, clearance)), ...options.obstacles.map((obstacle) => expanded(obstacle.bounds, clearance))];
13358
+ for (const point of points) {
13359
+ if (point.x < corridor.x + clearance || point.x > corridor.x + corridor.width - clearance || point.y < corridor.y + clearance || point.y > corridor.y + corridor.height - clearance) fail("route ink leaves the permitted corridor");
13360
+ }
13361
+ for (let i = 1; i < points.length; i++) {
13362
+ if (occupied.some((obstacle) => routingSegmentBlocked(points[i - 1], points[i], obstacle))) fail("a complete route segment violates object clearance");
13363
+ }
13364
+ const immutable = Object.freeze(points.map((point) => Object.freeze(point)));
13365
+ return {
13366
+ id: options.id,
13367
+ source: options.source,
13368
+ target: options.target,
13369
+ points: immutable,
13370
+ length: lengthOf(immutable),
13371
+ clearance,
13372
+ positionAt(progress) {
13373
+ finite5(progress, "Routed transfer progress");
13374
+ return pointAlongSamples(immutable, Math.max(0, Math.min(1, progress)));
13375
+ }
13376
+ };
13377
+ }
13378
+ function createTeachingRoutedTransfer(painter) {
13379
+ return (options) => {
13380
+ const { width, radius, strokeWidth, opacity } = parameters(options);
13381
+ if (opacity === 0) return null;
13382
+ const route = planTeachingRoutedTransfer(options), color = options.color ?? "#63DEEC";
13383
+ const paint = () => painter.opacity(opacity, () => {
13384
+ painter.path(route.points, { id: `${options.id}:route`, color, width });
13385
+ if (options.progress !== void 0 && options.progress > 0 && options.progress < 1) {
13386
+ const point = route.positionAt(options.progress);
13387
+ painter.circle(point.x, point.y, radius, options.marker?.fill ?? color, options.marker?.stroke, strokeWidth);
13388
+ }
13389
+ });
13390
+ if (painter.target) painter.target(options.focusTarget ?? options.id, paint);
13391
+ else paint();
13392
+ return route;
13393
+ };
13394
+ }
13395
+
13396
+ // src/teaching-byte-diff.ts
13397
+ function compareByteSequences(before, after) {
13398
+ if (!(before instanceof Uint8Array) || !(after instanceof Uint8Array)) {
13399
+ throw new Error("Byte comparison requires two Uint8Arrays");
13400
+ }
13401
+ const left = Array.from(before), right = Array.from(after);
13402
+ let commonPrefix = 0, commonSuffix = 0;
13403
+ while (commonPrefix < Math.min(left.length, right.length) && left[commonPrefix] === right[commonPrefix]) commonPrefix++;
13404
+ while (commonSuffix < Math.min(left.length, right.length) - commonPrefix && left[left.length - commonSuffix - 1] === right[right.length - commonSuffix - 1]) commonSuffix++;
13405
+ const columns = [];
13406
+ const add2 = (oldOffset, newOffset) => {
13407
+ const oldByte = oldOffset === null ? null : { offset: oldOffset, value: left[oldOffset] };
13408
+ const newByte = newOffset === null ? null : { offset: newOffset, value: right[newOffset] };
13409
+ const kind = !oldByte ? "insert" : !newByte ? "delete" : oldByte.value === newByte.value ? "equal" : "replace";
13410
+ columns.push({ id: `before:${oldOffset ?? "none"}|after:${newOffset ?? "none"}`, kind, before: oldByte, after: newByte });
13411
+ };
13412
+ for (let offset = 0; offset < commonPrefix; offset++) add2(offset, offset);
13413
+ const leftMiddle = left.length - commonPrefix - commonSuffix;
13414
+ const rightMiddle = right.length - commonPrefix - commonSuffix;
13415
+ for (let offset = 0; offset < Math.max(leftMiddle, rightMiddle); offset++) {
13416
+ add2(offset < leftMiddle ? commonPrefix + offset : null, offset < rightMiddle ? commonPrefix + offset : null);
13417
+ }
13418
+ for (let offset = 0; offset < commonSuffix; offset++) {
13419
+ add2(left.length - commonSuffix + offset, right.length - commonSuffix + offset);
13420
+ }
13421
+ return {
13422
+ algorithm: "common-prefix/suffix with positional middle",
13423
+ beforeLength: left.length,
13424
+ afterLength: right.length,
13425
+ commonPrefix,
13426
+ commonSuffix,
13427
+ equal: left.length === right.length && commonPrefix === left.length,
13428
+ columns
13429
+ };
13430
+ }
13431
+ function escapedByte(value) {
13432
+ if (!Number.isInteger(value) || value < 0 || value > 255) throw new Error("A byte must be an integer from 0 through 255");
13433
+ if (value === 0) return "\\0";
13434
+ if (value === 9) return "\\t";
13435
+ if (value === 10) return "\\n";
13436
+ if (value === 13) return "\\r";
13437
+ if (value === 32) return "space";
13438
+ if (value === 92) return "\\\\";
13439
+ if (value >= 33 && value <= 126) return String.fromCharCode(value);
13440
+ return `\\x${value.toString(16).padStart(2, "0").toUpperCase()}`;
13441
+ }
13442
+ function byteDifferenceState(options) {
13443
+ if (!Number.isFinite(options.scanProgress)) throw new Error("Byte scan progress must be finite");
13444
+ const comparison = compareByteSequences(options.before, options.after);
13445
+ const progress = Math.max(0, Math.min(1, options.scanProgress));
13446
+ const scannedColumns = Math.floor(progress * comparison.columns.length);
13447
+ return {
13448
+ comparison,
13449
+ progress,
13450
+ scannedColumns,
13451
+ scanComplete: progress === 1,
13452
+ verdict: options.revealVerdict ? comparison.equal ? "equal" : "different" : null
13453
+ };
13454
+ }
13455
+ function layoutByteDifference(options) {
13456
+ const { x, y, width, height, fontSize = 28, maxColumns = 10 } = options;
13457
+ if (![x, y, width, height, fontSize, x + width, y + height].every(Number.isFinite) || width <= 0 || height <= 0 || fontSize <= 0) {
13458
+ throw new Error("Byte strip bounds and font size must be finite with positive dimensions");
13459
+ }
13460
+ if (fontSize < 24) throw new Error("Byte strip font size must be at least 24 px for checked label padding");
13461
+ if (!Number.isSafeInteger(maxColumns) || maxColumns < 1) throw new Error("Byte window size must be a positive safe integer");
13462
+ const state = byteDifferenceState(options), all = state.comparison.columns;
13463
+ const start = options.startColumn ?? Math.max(0, state.comparison.commonPrefix - 2);
13464
+ if (!Number.isSafeInteger(start) || start < 0 || start > all.length || all.length > 0 && start === all.length) {
13465
+ throw new Error("Byte window start is outside the alignment");
13466
+ }
13467
+ const columns = all.slice(start, start + maxColumns), count = Math.max(1, columns.length);
13468
+ const gutter = fontSize * 5.2, cellWidth = (width - gutter) / count;
13469
+ const longest = Math.max(5, ...columns.flatMap((column) => [column.before, column.after].map((byte) => byte ? String(byte.offset).length + 1 : 5)));
13470
+ if (cellWidth < fontSize * 0.65 * longest + 12 || height < fontSize * 10) {
13471
+ throw new Error("Byte strip cannot fit its byte labels and offsets");
13472
+ }
13473
+ const headerHeight = fontSize * 1.7, footerHeight = fontSize * 1.7, rowHeight = (height - headerHeight - footerHeight) / 2;
13474
+ if (cellWidth <= 4 || rowHeight <= 4 || gutter - 8 <= 8 || headerHeight <= 8 || footerHeight <= 8 || rowHeight * 0.3 <= 8) {
13475
+ throw new Error("Byte strip cannot fit positive cell insets and checked label padding");
13476
+ }
13477
+ const cells = columns.map((column, index) => ({
13478
+ column,
13479
+ alignmentIndex: start + index,
13480
+ beforeBounds: { x: x + gutter + index * cellWidth, y: y + headerHeight, width: cellWidth, height: rowHeight },
13481
+ afterBounds: { x: x + gutter + index * cellWidth, y: y + headerHeight + rowHeight, width: cellWidth, height: rowHeight }
13482
+ }));
13483
+ return {
13484
+ ...state,
13485
+ bounds: { x, y, width, height },
13486
+ cells,
13487
+ gutter,
13488
+ headerHeight,
13489
+ footerHeight,
13490
+ rowHeight,
13491
+ omittedLeading: start,
13492
+ omittedTrailing: all.length - start - columns.length
13493
+ };
13494
+ }
13495
+ function createTeachingByteDifference(painter) {
13496
+ return (options) => {
13497
+ const layout = layoutByteDifference(options);
13498
+ const {
13499
+ x,
13500
+ y,
13501
+ width,
13502
+ height,
13503
+ fontSize = 28,
13504
+ fill = "#101820",
13505
+ stroke = "#516376",
13506
+ textColor = "#E9EFFF",
13507
+ mutedColor = "#91A3B8",
13508
+ scanColor = "#63DEEC",
13509
+ changeColor = "#F4D477",
13510
+ beforeLabel = "Before",
13511
+ afterLabel = "After"
13512
+ } = options;
13513
+ const label = (value, bounds4, size, color = textColor) => painter.labelScope(bounds4, () => {
13514
+ painter.text(value, bounds4.x + bounds4.width / 2, bounds4.y + bounds4.height / 2 + size * 0.34, size, color, "center", "mono");
13515
+ }, { padding: 4 });
13516
+ painter.container(layout.bounds, () => {
13517
+ label(
13518
+ "Prefix/suffix alignment; positional middle; not minimum edits",
13519
+ { x, y, width, height: layout.headerHeight },
13520
+ fontSize * 0.63,
13521
+ mutedColor
13522
+ );
13523
+ for (const [row, name] of [beforeLabel, afterLabel].entries()) {
13524
+ label(name, { x, y: y + layout.headerHeight + row * layout.rowHeight, width: layout.gutter - 8, height: layout.rowHeight }, fontSize * 0.72);
13525
+ }
13526
+ for (const cell of layout.cells) {
13527
+ const visited = cell.alignmentIndex < layout.scannedColumns;
13528
+ const color = visited ? cell.column.kind === "equal" ? mutedColor : changeColor : stroke;
13529
+ for (const [byte, bounds4] of [[cell.column.before, cell.beforeBounds], [cell.column.after, cell.afterBounds]]) {
13530
+ painter.rect(bounds4.x + 2, bounds4.y + 2, bounds4.width - 4, bounds4.height - 4, fill, color, 0);
13531
+ label(byte ? `@${byte.offset}` : "none", { ...bounds4, height: bounds4.height * 0.3 }, fontSize * 0.65, mutedColor);
13532
+ label(
13533
+ byte ? byte.value.toString(16).padStart(2, "0").toUpperCase() : "--",
13534
+ { ...bounds4, y: bounds4.y + bounds4.height * 0.3, height: bounds4.height * 0.35 },
13535
+ fontSize,
13536
+ visited ? textColor : mutedColor
13537
+ );
13538
+ label(
13539
+ byte ? escapedByte(byte.value) : "no byte",
13540
+ { ...bounds4, y: bounds4.y + bounds4.height * 0.65, height: bounds4.height * 0.35 },
13541
+ fontSize * 0.7,
13542
+ mutedColor
13543
+ );
13544
+ }
13545
+ }
13546
+ if (!layout.cells.length) {
13547
+ for (const row of [0, 1]) label("empty", {
13548
+ x: x + layout.gutter,
13549
+ y: y + layout.headerHeight + row * layout.rowHeight,
13550
+ width: width - layout.gutter,
13551
+ height: layout.rowHeight
13552
+ }, fontSize, mutedColor);
13553
+ }
13554
+ const scanPosition = layout.progress * layout.comparison.columns.length - layout.omittedLeading;
13555
+ if (layout.cells.length && scanPosition >= 0 && scanPosition <= layout.cells.length) {
13556
+ const cellWidth = layout.cells[0].beforeBounds.width;
13557
+ const cursor = Math.max(1, Math.min(width - layout.gutter - 1, scanPosition * cellWidth));
13558
+ painter.rect(
13559
+ x + layout.gutter + cursor - 1,
13560
+ y + layout.headerHeight - 7,
13561
+ 2,
13562
+ 5,
13563
+ scanColor,
13564
+ void 0,
13565
+ 0
13566
+ );
13567
+ }
13568
+ const verdict = layout.verdict === null ? "Verdict held" : layout.verdict === "equal" ? "Bytes equal" : "Bytes differ";
13569
+ label(
13570
+ `${layout.omittedLeading} columns before window; ${layout.omittedTrailing} after \xB7 ${verdict}`,
13571
+ { x, y: y + height - layout.footerHeight, width, height: layout.footerHeight },
13572
+ fontSize * 0.66,
13573
+ layout.verdict === null ? mutedColor : textColor
13574
+ );
13575
+ }, { padding: 0 });
13576
+ return layout;
13577
+ };
13578
+ }
13579
+
13580
+ // src/teaching-token-history.ts
13581
+ function tokens(input, name) {
13582
+ if (!Array.isArray(input)) throw new Error(`Token history ${name} must be an array`);
13583
+ return Object.freeze(input.map((item) => {
13584
+ if (!item || typeof item.id !== "string" || !item.id.trim() || item.id !== item.id.trim()) {
13585
+ throw new Error("Token occurrence IDs must be nonempty without surrounding whitespace");
13586
+ }
13587
+ if (!(typeof item.token === "string" && item.token.trim()) && !(typeof item.token === "number" && Number.isSafeInteger(item.token) && item.token >= 0)) {
13588
+ throw new Error("History tokens require nonempty text or a nonnegative safe integer vocabulary ID");
13589
+ }
13590
+ return Object.freeze({ id: item.id, token: item.token });
13591
+ }));
13592
+ }
13593
+ function equal(left, right) {
13594
+ return left.id === right.id && left.token === right.token;
13595
+ }
13596
+ function prefix(part, whole, name) {
13597
+ if (part.length > whole.length || part.some((token, index) => !equal(token, whole[index]))) {
13598
+ throw new Error(`Token history ${name} must preserve the exact ordered occurrence prefix`);
13599
+ }
13600
+ }
13601
+ function tokenHistoryState(options) {
13602
+ const prompt = tokens(options.prompt, "prompt"), accepted = tokens(options.accepted, "accepted");
13603
+ const processed = tokens(options.processed, "processed"), emitted = tokens(options.emitted, "emitted");
13604
+ const history = Object.freeze([...prompt, ...accepted]);
13605
+ if (new Set(history.map((token) => token.id)).size !== history.length) {
13606
+ throw new Error("Token history requires distinct occurrence IDs, including repeated vocabulary tokens");
13607
+ }
13608
+ prefix(processed, history, "processed");
13609
+ prefix(emitted, accepted, "emitted");
13610
+ if (accepted.length && processed.length < prompt.length) throw new Error("Accepted output requires the complete processed prompt");
13611
+ if (accepted.length && processed.length < prompt.length + accepted.length - 1) {
13612
+ throw new Error("Ordinary decoding permits at most one accepted token awaiting processing");
13613
+ }
13614
+ const phase = options.phase ?? "resident";
13615
+ if (!["resident", "dropped", "replay"].includes(phase)) throw new Error("Unknown token history phase");
13616
+ if (phase === "replay" && options.replayProgress === void 0) throw new Error("Replay requires explicit progress");
13617
+ const replayProgress = options.replayProgress ?? 0;
13618
+ if (!Number.isFinite(replayProgress) || replayProgress < 0 || replayProgress > 1) {
13619
+ throw new Error("Replay progress must be finite between zero and one");
13620
+ }
13621
+ const position2 = replayProgress * processed.length;
13622
+ const completed = phase === "resident" ? processed.length : phase === "dropped" ? 0 : Math.floor(position2);
13623
+ const fraction = position2 - Math.floor(position2);
13624
+ const moving = phase === "replay" && fraction > 0 && completed < processed.length ? Object.freeze({ token: processed[completed], position: completed, progress: fraction }) : null;
13625
+ return Object.freeze({
13626
+ prompt,
13627
+ accepted,
13628
+ processed,
13629
+ emitted,
13630
+ history,
13631
+ phase,
13632
+ replayProgress,
13633
+ kv: Object.freeze(processed.slice(0, completed)),
13634
+ pendingAccepted: Object.freeze(accepted.filter((_, index) => prompt.length + index >= processed.length)),
13635
+ moving
13636
+ });
13637
+ }
13638
+ function assertTokenHistoryTransition(before, after) {
13639
+ before = tokenHistoryState(before);
13640
+ after = tokenHistoryState(after);
13641
+ prefix(before.prompt, after.prompt, "prompt transition");
13642
+ if (before.prompt.length !== after.prompt.length) throw new Error("A request prompt cannot change during its history");
13643
+ prefix(before.accepted, after.accepted, "accepted transition");
13644
+ prefix(before.emitted, after.emitted, "emitted transition");
13645
+ if (before.phase !== "resident" || after.phase !== "resident") {
13646
+ if (before.accepted.length !== after.accepted.length || before.emitted.length !== after.emitted.length) {
13647
+ throw new Error("Drop and replay transitions cannot sample or emit new output");
13648
+ }
13649
+ prefix(before.processed, after.processed, "replay target");
13650
+ if (before.processed.length !== after.processed.length) throw new Error("Replay must rebuild the retained processed prefix");
13651
+ } else if (after.processed.length < before.processed.length) {
13652
+ throw new Error("Resident processed history cannot shrink without an explicit drop or replay");
13653
+ }
13654
+ }
13655
+ function createTeachingTokenHistory(painter) {
13656
+ return (options) => {
13657
+ const state = tokenHistoryState(options);
13658
+ const { x, y, width, height, fontSize = 28, gap = 8, labelWidth = 245, focusPrefix } = options;
13659
+ if (![x, y, x + width, y + height, width, height, fontSize, gap, labelWidth].every(Number.isFinite) || width <= 0 || height <= 0 || fontSize <= 0 || gap < 0 || labelWidth <= 0) {
13660
+ throw new Error("Token history drawing bounds and sizes must be finite and positive");
13661
+ }
13662
+ const columns = Math.max(1, state.history.length), top = fontSize * 1.9, bottom = fontSize * 2;
13663
+ const cellWidth = (width - labelWidth - gap * (columns - 1) - 4) / columns;
13664
+ const laneHeight = (height - top - bottom) / 5, cellHeight = laneHeight - gap;
13665
+ if (cellWidth < fontSize * 2.2 || cellHeight < fontSize * 1.6 || labelWidth < fontSize * 5) {
13666
+ throw new Error("Token history bounds must fit its occurrence columns and five readable lanes");
13667
+ }
13668
+ const color = {
13669
+ prompt: "#7FA7FF",
13670
+ accepted: "#92E28C",
13671
+ processed: "#63DEEC",
13672
+ kv: "#63DEEC",
13673
+ emitted: "#92E28C",
13674
+ pending: "#FFD75E",
13675
+ empty: "#586278",
13676
+ text: "#F2EFE6",
13677
+ fill: "#141820",
13678
+ ...options.colors
13679
+ };
13680
+ const lanes = [
13681
+ { id: "prompt", label: "Prompt", tokens: state.prompt, offset: 0 },
13682
+ { id: "accepted", label: "Accepted output", tokens: state.accepted, offset: state.prompt.length },
13683
+ { id: "processed", label: "Processed prefix", tokens: state.processed, offset: 0 },
13684
+ { id: "kv", label: "Resident KV", tokens: state.kv, offset: 0 },
13685
+ { id: "emitted", label: "Already delivered", tokens: state.emitted, offset: state.prompt.length }
13686
+ ];
13687
+ const pending = new Set(state.pendingAccepted.map((token) => token.id));
13688
+ const bounds4 = { x, y, width, height };
13689
+ const target = (id, draw) => {
13690
+ if (id && painter.target) painter.target(id, draw);
13691
+ else draw();
13692
+ };
13693
+ const cell = (position2, row) => ({
13694
+ x: x + labelWidth + 1 + position2 * (cellWidth + gap),
13695
+ y: y + top + row * laneHeight,
13696
+ width: cellWidth,
13697
+ height: cellHeight
13698
+ });
13699
+ const paintToken = (token, shape, stroke, fill = color.fill) => {
13700
+ painter.rect(shape.x, shape.y, shape.width, shape.height, fill, stroke, 7);
13701
+ painter.labelScope(shape, () => painter.text(
13702
+ String(token.token),
13703
+ shape.x + shape.width / 2,
13704
+ shape.y + shape.height / 2 + fontSize * 0.34,
13705
+ fontSize,
13706
+ color.text,
13707
+ "center",
13708
+ "mono"
13709
+ ), { padding: 5 });
13710
+ };
13711
+ painter.container(bounds4, () => {
13712
+ for (let position2 = 0; position2 < state.history.length; position2 += 1) {
13713
+ const shape = cell(position2, 0);
13714
+ painter.labelScope({ ...shape, y, height: top }, () => painter.text(
13715
+ `position ${position2}`,
13716
+ shape.x + shape.width / 2,
13717
+ y + fontSize,
13718
+ fontSize * 0.7,
13719
+ color.empty,
13720
+ "center"
13721
+ ), { padding: 3 });
13722
+ }
13723
+ lanes.forEach((lane, row) => target(focusPrefix ? `${focusPrefix}-${lane.id}` : void 0, () => {
13724
+ const labelBounds = { x, y: y + top + row * laneHeight, width: labelWidth - gap, height: cellHeight };
13725
+ painter.labelScope(labelBounds, () => painter.text(
13726
+ lane.label,
13727
+ x + 5,
13728
+ labelBounds.y + cellHeight / 2 + fontSize * 0.34,
13729
+ fontSize * 0.82,
13730
+ color[lane.id]
13731
+ ), { padding: 3 });
13732
+ for (let position2 = 0; position2 < columns; position2 += 1) {
13733
+ const shape = cell(position2, row), token = lane.tokens[position2 - lane.offset];
13734
+ if (token) {
13735
+ const isPending = lane.id === "accepted" && pending.has(token.id);
13736
+ target(
13737
+ isPending && focusPrefix ? `${focusPrefix}-pending` : void 0,
13738
+ () => paintToken(token, shape, isPending ? color.pending : color[lane.id], lane.id === "processed" ? "transparent" : color.fill)
13739
+ );
13740
+ } else painter.rect(shape.x, shape.y, shape.width, shape.height, "transparent", color.empty, 7);
13741
+ }
13742
+ }));
13743
+ if (state.moving) {
13744
+ const from = cell(state.moving.position, 2), to = cell(state.moving.position, 3);
13745
+ const progress = state.moving.progress;
13746
+ const settle = Math.max(0, (progress - 0.65) / 0.35);
13747
+ const grow = Math.max(0, (progress - 0.8) / 0.2);
13748
+ const copyWidth = Math.min(from.width, fontSize * 3);
13749
+ const copyHeight = Math.min(from.height, fontSize * 1.8);
13750
+ const movingWidth = copyWidth + (from.width - copyWidth) * grow;
13751
+ const movingHeight = copyHeight + (from.height - copyHeight) * grow;
13752
+ const startInset = Math.min(7, from.width - copyWidth);
13753
+ const startCenterX = from.x + startInset + copyWidth / 2;
13754
+ const centerX = startCenterX + (from.x + from.width / 2 - startCenterX) * settle;
13755
+ const centerY = from.y + from.height / 2 + (to.y - from.y) * progress;
13756
+ const moving = { x: centerX - movingWidth / 2, y: centerY - movingHeight / 2, width: movingWidth, height: movingHeight };
13757
+ target(focusPrefix ? `${focusPrefix}-replay` : void 0, () => paintToken(state.moving.token, moving, color.kv));
13758
+ }
13759
+ const pendingText = state.pendingAccepted.map((token) => String(token.token)).join(", ");
13760
+ const message = state.phase === "replay" ? "Replay rebuilds KV; no sampling or delivery" : state.phase === "dropped" ? "KV released; accepted and delivered history retained" : pendingText ? `Accepted but unprocessed: ${pendingText}` : "All accepted positions are processed";
13761
+ painter.labelScope({ x, y: y + height - bottom, width, height: bottom }, () => painter.text(
13762
+ message,
13763
+ x + width / 2,
13764
+ y + height - fontSize * 0.6,
13765
+ fontSize * 0.82,
13766
+ state.phase === "replay" ? color.kv : color.pending,
13767
+ "center"
13768
+ ), { padding: 3 });
13769
+ }, { padding: 0 });
13770
+ return state;
13771
+ };
13772
+ }
13773
+
12931
13774
  // src/teaching-canvas.ts
12932
13775
  var INK = "#8D9CB9";
12933
13776
  var ACCENT = "#63DEEC";
12934
13777
  var PANEL = "#18283B";
12935
- function finite4(value, name) {
13778
+ function finite6(value, name) {
12936
13779
  if (!Number.isFinite(value)) throw new Error(`${name} must be finite`);
12937
13780
  }
12938
- function positive4(value, name) {
12939
- finite4(value, name);
13781
+ function positive5(value, name) {
13782
+ finite6(value, name);
12940
13783
  if (value <= 0) throw new Error(`${name} must be positive`);
12941
13784
  }
12942
13785
  function boundsOf(options) {
12943
- finite4(options.x, "Teaching x");
12944
- finite4(options.y, "Teaching y");
12945
- positive4(options.width, "Teaching width");
12946
- positive4(options.height, "Teaching height");
13786
+ finite6(options.x, "Teaching x");
13787
+ finite6(options.y, "Teaching y");
13788
+ positive5(options.width, "Teaching width");
13789
+ positive5(options.height, "Teaching height");
12947
13790
  return { x: options.x, y: options.y, width: options.width, height: options.height };
12948
13791
  }
12949
13792
  function amount(value, name = "Teaching progress") {
12950
- finite4(value, name);
13793
+ finite6(value, name);
12951
13794
  return Math.max(0, Math.min(1, value));
12952
13795
  }
12953
13796
  function domainOf(domain, name) {
12954
- finite4(domain[0], `${name} start`);
12955
- finite4(domain[1], `${name} end`);
13797
+ finite6(domain[0], `${name} start`);
13798
+ finite6(domain[1], `${name} end`);
12956
13799
  if (domain[1] <= domain[0] || !Number.isFinite(domain[1] - domain[0])) {
12957
13800
  throw new Error(`${name} must have a finite positive span`);
12958
13801
  }
@@ -12961,54 +13804,54 @@ function domainOf(domain, name) {
12961
13804
  function createTeachingCanvas(painter) {
12962
13805
  const components = createCanvasComponents(painter);
12963
13806
  function axes(options) {
12964
- let bounds2 = boundsOf(options);
13807
+ let bounds4 = boundsOf(options);
12965
13808
  const xDomain = domainOf(options.xDomain, "Plot x domain");
12966
13809
  const yDomain = domainOf(options.yDomain, "Plot y domain");
12967
13810
  if (options.equalUnits) {
12968
13811
  const xSpan = xDomain[1] - xDomain[0];
12969
13812
  const ySpan = yDomain[1] - yDomain[0];
12970
- const pixelsPerUnit = Math.min(bounds2.width / xSpan, bounds2.height / ySpan);
13813
+ const pixelsPerUnit = Math.min(bounds4.width / xSpan, bounds4.height / ySpan);
12971
13814
  const width2 = xSpan * pixelsPerUnit;
12972
13815
  const height2 = ySpan * pixelsPerUnit;
12973
- bounds2 = boundsOf({
12974
- x: bounds2.x + (bounds2.width - width2) / 2,
12975
- y: bounds2.y + (bounds2.height - height2) / 2,
13816
+ bounds4 = boundsOf({
13817
+ x: bounds4.x + (bounds4.width - width2) / 2,
13818
+ y: bounds4.y + (bounds4.height - height2) / 2,
12976
13819
  width: width2,
12977
13820
  height: height2
12978
13821
  });
12979
13822
  }
12980
- const { x, y, width, height } = bounds2;
13823
+ const { x, y, width, height } = bounds4;
12981
13824
  const { color = INK, gridColor, fontSize = 28, xTicks = [], yTicks = [], formatX = String, formatY = String } = options;
12982
- positive4(fontSize, "Axis font size");
12983
- xTicks.forEach((tick) => finite4(tick, "Axis x tick"));
12984
- yTicks.forEach((tick) => finite4(tick, "Axis y tick"));
13825
+ positive5(fontSize, "Axis font size");
13826
+ xTicks.forEach((tick) => finite6(tick, "Axis x tick"));
13827
+ yTicks.forEach((tick) => finite6(tick, "Axis y tick"));
12985
13828
  const plot = {
12986
- bounds: bounds2,
13829
+ bounds: bounds4,
12987
13830
  xDomain,
12988
13831
  yDomain,
12989
13832
  point(px, py) {
12990
- finite4(px, "Plot point x");
12991
- finite4(py, "Plot point y");
13833
+ finite6(px, "Plot point x");
13834
+ finite6(py, "Plot point y");
12992
13835
  const point = {
12993
13836
  x: x + (px - xDomain[0]) / (xDomain[1] - xDomain[0]) * width,
12994
13837
  y: y + height - (py - yDomain[0]) / (yDomain[1] - yDomain[0]) * height
12995
13838
  };
12996
- finite4(point.x, "Mapped point x");
12997
- finite4(point.y, "Mapped point y");
13839
+ finite6(point.x, "Mapped point x");
13840
+ finite6(point.y, "Mapped point y");
12998
13841
  return point;
12999
13842
  }
13000
13843
  };
13001
13844
  for (const tick of xTicks) {
13002
13845
  if (tick < xDomain[0] || tick > xDomain[1]) continue;
13003
13846
  const point = plot.point(tick, yDomain[0]);
13004
- if (gridColor) painter.path([{ x: point.x, y }, { x: point.x, y: y + height }], { color: gridColor, width: 1, clip: bounds2 });
13847
+ if (gridColor) painter.path([{ x: point.x, y }, { x: point.x, y: y + height }], { color: gridColor, width: 1, clip: bounds4 });
13005
13848
  painter.line(point.x, y + height, point.x, y + height + 7, color, 2);
13006
13849
  painter.text(formatX(tick), point.x, y + height + 36, fontSize, color, "center");
13007
13850
  }
13008
13851
  for (const tick of yTicks) {
13009
13852
  if (tick < yDomain[0] || tick > yDomain[1]) continue;
13010
13853
  const point = plot.point(xDomain[0], tick);
13011
- if (gridColor) painter.path([{ x, y: point.y }, { x: x + width, y: point.y }], { color: gridColor, width: 1, clip: bounds2 });
13854
+ if (gridColor) painter.path([{ x, y: point.y }, { x: x + width, y: point.y }], { color: gridColor, width: 1, clip: bounds4 });
13012
13855
  painter.line(x - 7, point.y, x, point.y, color, 2);
13013
13856
  painter.text(formatY(tick), x - 18, point.y + 9, fontSize, color, "right");
13014
13857
  }
@@ -13020,7 +13863,7 @@ function createTeachingCanvas(painter) {
13020
13863
  }
13021
13864
  function curve(options) {
13022
13865
  const { plot, points, color, width = 4, progress = 1 } = options;
13023
- positive4(width, "Curve width");
13866
+ positive5(width, "Curve width");
13024
13867
  const mapped = points.map((point) => plot.point(point.x, point.y));
13025
13868
  const visible = tracePolyline(mapped, progress);
13026
13869
  if (visible.length > 1) painter.path(visible, { color, width, clip: plot.bounds });
@@ -13028,10 +13871,10 @@ function createTeachingCanvas(painter) {
13028
13871
  }
13029
13872
  function scatter(options) {
13030
13873
  const { plot, points, color = ACCENT, radius = 7, opacity = 1 } = options;
13031
- positive4(radius, "Scatter radius");
13032
- const alpha2 = amount(opacity, "Scatter opacity");
13874
+ positive5(radius, "Scatter radius");
13875
+ const alpha3 = amount(opacity, "Scatter opacity");
13033
13876
  const projected = points.map((point) => {
13034
- positive4(point.radius ?? radius, "Scatter point radius");
13877
+ positive5(point.radius ?? radius, "Scatter point radius");
13035
13878
  return {
13036
13879
  ...plot.point(point.x, point.y),
13037
13880
  radius: point.radius ?? radius,
@@ -13040,8 +13883,8 @@ function createTeachingCanvas(painter) {
13040
13883
  };
13041
13884
  });
13042
13885
  const shapes = [];
13043
- if (alpha2 === 0) return shapes;
13044
- painter.opacity(alpha2, () => {
13886
+ if (alpha3 === 0) return shapes;
13887
+ painter.opacity(alpha3, () => {
13045
13888
  for (const point of projected) {
13046
13889
  if (!point.inDomain) continue;
13047
13890
  shapes.push(painter.circle(point.x, point.y, point.radius, point.color));
@@ -13050,26 +13893,26 @@ function createTeachingCanvas(painter) {
13050
13893
  return shapes;
13051
13894
  }
13052
13895
  function bars(options) {
13053
- const bounds2 = boundsOf(options);
13054
- const { x, y, width, height } = bounds2;
13896
+ const bounds4 = boundsOf(options);
13897
+ const { x, y, width, height } = bounds4;
13055
13898
  const { values, labels, colors: colors2, color = ACCENT, progress = 1, showValues = false, format = String, fontSize = 28, gap = 20 } = options;
13056
- positive4(fontSize, "Bar font size");
13057
- finite4(gap, "Bar gap");
13899
+ positive5(fontSize, "Bar font size");
13900
+ finite6(gap, "Bar gap");
13058
13901
  if (gap < 0) throw new Error("Bar gap must be nonnegative");
13059
13902
  values.forEach((value) => {
13060
- finite4(value, "Bar value");
13903
+ finite6(value, "Bar value");
13061
13904
  if (value < 0) throw new Error("Bar values must be nonnegative");
13062
13905
  });
13063
13906
  if (labels && labels.length !== values.length) throw new Error("Bar labels must match values");
13064
13907
  if (colors2 && colors2.length !== values.length) throw new Error("Bar colors must match values");
13065
13908
  const maximumValue = values.reduce((maximum2, value) => Math.max(maximum2, value), 0);
13066
13909
  const maximum = options.max ?? (maximumValue || 1);
13067
- positive4(maximum, "Bar maximum");
13910
+ positive5(maximum, "Bar maximum");
13068
13911
  if (maximum < maximumValue) throw new Error("Bar maximum must contain every value");
13069
13912
  const reveal = amount(progress);
13070
- if (!values.length) return { bars: [], slots: [], bounds: bounds2 };
13913
+ if (!values.length) return { bars: [], slots: [], bounds: bounds4 };
13071
13914
  const barWidth = (width - gap * (values.length - 1)) / values.length;
13072
- positive4(barWidth, "Bar width after gaps");
13915
+ positive5(barWidth, "Bar width after gaps");
13073
13916
  const shapes = [];
13074
13917
  const slots = [];
13075
13918
  values.forEach((value, index) => {
@@ -13080,28 +13923,28 @@ function createTeachingCanvas(painter) {
13080
13923
  if (labels) painter.text(labels[index], left + barWidth / 2, y + height + 38, fontSize, INK, "center");
13081
13924
  if (showValues && reveal > 0) painter.text(format(value), left + barWidth / 2, y + height - barHeight - 14, fontSize, colors2?.[index] ?? color, "center");
13082
13925
  });
13083
- return { bars: shapes, slots, bounds: bounds2 };
13926
+ return { bars: shapes, slots, bounds: bounds4 };
13084
13927
  }
13085
13928
  function flowGraph(options) {
13086
13929
  const { nodes, edges, stroke = ACCENT, fill = PANEL, textColor = "#FFFFFF", padding = 12 } = options;
13087
- finite4(padding, "Flow node padding");
13930
+ finite6(padding, "Flow node padding");
13088
13931
  if (padding < 0) throw new Error("Flow node padding must be nonnegative");
13089
13932
  const descriptors = /* @__PURE__ */ Object.create(null);
13090
13933
  for (const node of nodes) {
13091
13934
  if (!node.id || Object.hasOwn(descriptors, node.id)) throw new Error("Flow node IDs must be nonempty and unique");
13092
- const bounds2 = boundsOf(node);
13093
- positive4(node.fontSize ?? 30, "Flow node font size");
13094
- finite4(node.radius ?? 14, "Flow node radius");
13935
+ const bounds4 = boundsOf(node);
13936
+ positive5(node.fontSize ?? 30, "Flow node font size");
13937
+ finite6(node.radius ?? 14, "Flow node radius");
13095
13938
  if ((node.radius ?? 14) < 0) throw new Error("Flow node radius must be nonnegative");
13096
- descriptors[node.id] = { ...bounds2, radius: node.radius ?? 14 };
13939
+ descriptors[node.id] = { ...bounds4, radius: node.radius ?? 14 };
13097
13940
  }
13098
13941
  for (const edge of edges) {
13099
13942
  if (!Object.hasOwn(descriptors, edge.from) || !Object.hasOwn(descriptors, edge.to)) throw new Error("Flow edge must reference existing nodes");
13100
13943
  if (edge.from === edge.to) throw new Error("Flow edges must connect distinct nodes");
13101
13944
  if (edge.progress !== void 0) amount(edge.progress);
13102
- if (edge.width !== void 0) positive4(edge.width, "Flow edge width");
13945
+ if (edge.width !== void 0) positive5(edge.width, "Flow edge width");
13103
13946
  for (const gap of [edge.gap, edge.fromGap, edge.toGap]) {
13104
- if (gap !== void 0) finite4(gap, "Flow edge gap");
13947
+ if (gap !== void 0) finite6(gap, "Flow edge gap");
13105
13948
  }
13106
13949
  }
13107
13950
  const target = (id, draw) => id && painter.target ? painter.target(id, draw) : draw();
@@ -13126,7 +13969,24 @@ function createTeachingCanvas(painter) {
13126
13969
  }
13127
13970
  return { nodes: descriptors, routes };
13128
13971
  }
13129
- return { axes, curve, scatter, bars, flowGraph, transfer: createTeachingTransfer(painter), grid: createTeachingGrid(painter), timeline: createTeachingTimeline(painter), allocation: createTeachingAllocation(painter), ...createTeachingValueChange(painter), ...createTeachingFocus(painter) };
13972
+ return {
13973
+ axes,
13974
+ curve,
13975
+ scatter,
13976
+ bars,
13977
+ flowGraph,
13978
+ transfer: createTeachingTransfer(painter),
13979
+ routedTransfer: createTeachingRoutedTransfer(painter),
13980
+ grid: createTeachingGrid(painter),
13981
+ timeline: createTeachingTimeline(painter),
13982
+ allocation: createTeachingAllocation(painter),
13983
+ vectorAccumulation: createTeachingVectorAccumulation(painter),
13984
+ categoricalSampling: createTeachingCategoricalSampling(painter),
13985
+ byteDifference: createTeachingByteDifference(painter),
13986
+ tokenHistory: createTeachingTokenHistory(painter),
13987
+ ...createTeachingValueChange(painter),
13988
+ ...createTeachingFocus(painter)
13989
+ };
13130
13990
  }
13131
13991
 
13132
13992
  // src/teaching-cues.ts
@@ -14258,13 +15118,13 @@ function colorFromCss(value) {
14258
15118
  }
14259
15119
  function compositeOver(foreground, background) {
14260
15120
  if (foreground.alpha >= 1 || !background) return foreground;
14261
- const alpha2 = foreground.alpha + background.alpha * (1 - foreground.alpha);
14262
- if (alpha2 <= 0) return { r: 0, g: 0, b: 0, alpha: 0 };
15121
+ const alpha3 = foreground.alpha + background.alpha * (1 - foreground.alpha);
15122
+ if (alpha3 <= 0) return { r: 0, g: 0, b: 0, alpha: 0 };
14263
15123
  return {
14264
- r: (foreground.r * foreground.alpha + background.r * background.alpha * (1 - foreground.alpha)) / alpha2,
14265
- g: (foreground.g * foreground.alpha + background.g * background.alpha * (1 - foreground.alpha)) / alpha2,
14266
- b: (foreground.b * foreground.alpha + background.b * background.alpha * (1 - foreground.alpha)) / alpha2,
14267
- alpha: alpha2
15124
+ r: (foreground.r * foreground.alpha + background.r * background.alpha * (1 - foreground.alpha)) / alpha3,
15125
+ g: (foreground.g * foreground.alpha + background.g * background.alpha * (1 - foreground.alpha)) / alpha3,
15126
+ b: (foreground.b * foreground.alpha + background.b * background.alpha * (1 - foreground.alpha)) / alpha3,
15127
+ alpha: alpha3
14268
15128
  };
14269
15129
  }
14270
15130
  function isUnresolvedColor(value) {
@@ -14654,12 +15514,12 @@ function analyzeRenderedLayout(nodes, theme) {
14654
15514
  }
14655
15515
  return diagnostics;
14656
15516
  }
14657
- function analyzeWhitespaceBalance(bounds2, width, height, theme) {
15517
+ function analyzeWhitespaceBalance(bounds4, width, height, theme) {
14658
15518
  const gutters = {
14659
- left: bounds2.x,
14660
- right: width - bounds2.x - bounds2.width,
14661
- top: bounds2.y,
14662
- bottom: height - bounds2.y - bounds2.height
15519
+ left: bounds4.x,
15520
+ right: width - bounds4.x - bounds4.width,
15521
+ top: bounds4.y,
15522
+ bottom: height - bounds4.y - bounds4.height
14663
15523
  };
14664
15524
  const diagnostics = [];
14665
15525
  const horizontalDifference = Math.abs(gutters.left - gutters.right);
@@ -14671,7 +15531,7 @@ function analyzeWhitespaceBalance(bounds2, width, height, theme) {
14671
15531
  theme,
14672
15532
  message: `Horizontal gutters differ by ${Math.round(horizontalDifference)}px (${Math.round(gutters.left)}px left, ${Math.round(gutters.right)}px right).`,
14673
15533
  suggestion: "Recenter the composition, crop the canvas, or use the open space intentionally.",
14674
- location: { x: bounds2.x, y: bounds2.y, width: bounds2.width, height: bounds2.height }
15534
+ location: { x: bounds4.x, y: bounds4.y, width: bounds4.width, height: bounds4.height }
14675
15535
  });
14676
15536
  }
14677
15537
  if (verticalDifference > 48 && verticalDifference / height > 0.12) {
@@ -14681,7 +15541,7 @@ function analyzeWhitespaceBalance(bounds2, width, height, theme) {
14681
15541
  theme,
14682
15542
  message: `Vertical gutters differ by ${Math.round(verticalDifference)}px (${Math.round(gutters.top)}px top, ${Math.round(gutters.bottom)}px bottom).`,
14683
15543
  suggestion: "Recenter the composition, crop the canvas, or use the open space intentionally.",
14684
- location: { x: bounds2.x, y: bounds2.y, width: bounds2.width, height: bounds2.height }
15544
+ location: { x: bounds4.x, y: bounds4.y, width: bounds4.width, height: bounds4.height }
14685
15545
  });
14686
15546
  }
14687
15547
  return diagnostics;
@@ -15150,19 +16010,28 @@ export {
15150
16010
  analyzeAnimationCadence,
15151
16011
  arcSwap,
15152
16012
  assertDensity,
16013
+ assertTokenHistoryTransition,
16014
+ byteDifferenceState,
15153
16015
  cameraSvgTransform,
15154
16016
  canvas,
16017
+ categoricalSampling,
15155
16018
  checkFrame,
15156
16019
  colors,
16020
+ compareByteSequences,
15157
16021
  compositeColor,
15158
16022
  createCanvasComponents,
15159
16023
  createCueTrack,
15160
16024
  createFocusDirector,
15161
16025
  createPlotArea,
15162
16026
  createPolylineMorph,
16027
+ createTeachingByteDifference,
15163
16028
  createTeachingCanvas,
16029
+ createTeachingCategoricalSampling,
15164
16030
  createTeachingFocus,
16031
+ createTeachingRoutedTransfer,
16032
+ createTeachingTokenHistory,
15165
16033
  createTeachingValueChange,
16034
+ createTeachingVectorAccumulation,
15166
16035
  cropPixels,
15167
16036
  cropRgbImage,
15168
16037
  cropRgbRaster,
@@ -15181,6 +16050,7 @@ export {
15181
16050
  dotProduct,
15182
16051
  encodeRgbPng,
15183
16052
  entropy,
16053
+ escapedByte,
15184
16054
  estimateTextWidth,
15185
16055
  evaluateSceneSource,
15186
16056
  flattenRgbImage,
@@ -15210,6 +16080,7 @@ export {
15210
16080
  interpolateCamera,
15211
16081
  keyframe,
15212
16082
  layoutAllocation,
16083
+ layoutByteDifference,
15213
16084
  layoutCellGrid,
15214
16085
  layoutTokenRow,
15215
16086
  lerpArray,
@@ -15222,6 +16093,7 @@ export {
15222
16093
  normalizeWatermark,
15223
16094
  parallel,
15224
16095
  parseDensity,
16096
+ planTeachingRoutedTransfer,
15225
16097
  pointAlongPath,
15226
16098
  prepareScene,
15227
16099
  projectWorldPoint,
@@ -15256,6 +16128,7 @@ export {
15256
16128
  statusColor,
15257
16129
  styles,
15258
16130
  sumForces,
16131
+ tokenHistoryState,
15259
16132
  toneGradients,
15260
16133
  tracePolyline,
15261
16134
  transposeMatrix,
@@ -15265,6 +16138,7 @@ export {
15265
16138
  valueChangeState,
15266
16139
  videoFrameSchedule,
15267
16140
  waveValue,
16141
+ weightedVectorState,
15268
16142
  withColorAlpha,
15269
16143
  withDensity,
15270
16144
  wrapWithBrand,