retiam 2.0.1 → 2.0.3

package/dist/libs/explainer/example.d.ts

@@ -0,0 +1,3 @@
+import { LessonPlan, StyleInput } from './types';
+/** A small executable reference, to replace with the requested subject's construction. */
+export declare function createExampleLesson(style?: StyleInput): LessonPlan;

package/dist/libs/explainer/index.d.ts

@@ -0,0 +1,5 @@
+/** Teaching plans, visual profiles, narration cues, and a shared production clock. */
+export * from './plan';
+export * from './runtime';
+export * from './visuals';
+export * from './example';

package/dist/libs/explainer/index.js

@@ -0,0 +1,135 @@
+import { assertLesson as S, voiceKey as M, speechKey as y, compileLesson as E, resolveStyle as A } from "./plan.js";
+import { STYLE_PROFILES as ae, lessonCaptions as oe, validateLesson as se } from "./plan.js";
+import { CustomAnimation as x, TrackAnimation as q, Waiting as C, hex as v, Color as $, Excalidraw as z, Create as N, Tex as D, CENTER as L, Rate as k } from "retiam";
+import { TTS as T } from "retiam/tts";
+/*! Retiam: noncommercial use only unless separately licensed. See ../../LICENSE and ../../COMMERCIAL_LICENSE.md. Third-party notices: ../../THIRD_PARTY_NOTICES.md and ../../THIRD_PARTY_LICENSES.txt. */
+function Y(r, t, i = {}) {
+  S(t);
+  const u = (async () => {
+    const s = /* @__PURE__ */ new Map();
+    let a = i.prepared;
+    if (t.narration.enabled) {
+      const f = t.narration.provider ?? "msedge";
+      if (!a && !i.synthesize && T.provider.name !== (f === "msedge" ? "msedge-tts" : f))
+        throw new Error("Initialize and select the lesson narration provider, or provide prepared speech or a synthesize adapter.");
+      const c = r.audio;
+      if (a && a.voiceKey !== M(t))
+        throw new Error("Prepared narration uses different voice settings. Prepare narration again.");
+      a = a ?? { version: 1, voiceKey: M(t), assets: {} };
+      const p = t.beats.flatMap((e) => e.narration.map((o) => ({ beat: e.id, segment: o })));
+      let w = 0;
+      await Promise.all(Array.from({ length: Math.min(3, p.length) }, async () => {
+        for (; w < p.length; ) {
+          const e = p[w++], o = y(e.beat, e.segment.id);
+          let g;
+          if (i.prepared) {
+            const d = a.assets[o];
+            if (!d || d.text !== e.segment.text || (d.speechText ?? d.text) !== (e.segment.speechText ?? e.segment.text) || !d.url)
+              throw new Error(`Missing/stale prepared asset: ${o}.`);
+            const l = await fetch(d.url);
+            if (!l.ok)
+              throw new Error(`Narration asset ${d.url}: HTTP ${l.status}.`);
+            if (g = await c.context.decodeAudioData(await l.arrayBuffer()), Math.abs(g.duration * 1e3 - d.durationMs) > 120)
+              throw new Error(`Narration duration mismatch: ${o}.`);
+          } else {
+            const d = e.segment.speechText ?? e.segment.text, l = await (i.synthesize?.(d) ?? T.synthesize(d, { voice: t.narration.voice ?? (f === "msedge" ? "en-US-AndrewNeural" : void 0), speed: t.narration.speed, pitch: t.narration.pitch, volume: 1, displayText: e.segment.text, elevenlabs: t.narration.elevenlabs }));
+            a.assets[o] = { text: e.segment.text, speechText: e.segment.speechText, durationMs: l.durationMs, words: (l.wordBoundaries ?? []).map((n) => ({ text: n.text, offsetMs: n.offsetMs, durationMs: n.durationMs })) }, g = l.rawBuffer ? await c.context.decodeAudioData(l.rawBuffer.slice(0)) : l.toAudioBuffer(c.context);
+          }
+          s.set(o, g);
+        }
+      }));
+    }
+    const h = E(t, a, i.fps ?? 60), m = A(t.style);
+    return { plan: t, timeline: h, style: m, async run(f) {
+      const c = new Set(t.beats.map((e) => e.id));
+      for (const e of Object.keys(f))
+        if (!c.has(e))
+          throw new Error(`Unknown beat handler '${e}'.`);
+      const p = [];
+      for (const e of h.beats) {
+        const o = f[e.id];
+        if (!o)
+          throw new Error(`Missing beat handler '${e.id}'.`);
+        const g = (n) => {
+          const b = e.cues[n];
+          if (b === void 0)
+            throw new Error(`Unknown cue '${e.id}/${n}'.`);
+          return b;
+        }, d = o({ beat: e, durationMs: e.durationMs, style: m, cue: g, at: (n, b) => new x(() => {
+        }, { delay: g(n), duration: 1, onStart: b }) });
+        for (const n of d)
+          if (!Number.isFinite(n.delay) || !Number.isFinite(n.duration) || n.delay < 0 || n.duration < 0 || n.delay + n.duration > e.durationMs + 0.1)
+            throw new Error(`Animation exceeds beat '${e.id}' (${e.durationMs} ms).`);
+        const l = new q([...d, new C({ duration: e.durationMs })]);
+        l.delay = e.startMs, p.push(l);
+      }
+      const w = r.composer?.time ?? 0;
+      if (t.narration.enabled)
+        for (const e of h.beats)
+          for (const o of e.segments) {
+            const g = s.get(y(e.id, o.id));
+            r.audio.timeline.addClip(g, w + e.startMs + o.startMs, r.audio.voiceoverGain, { volume: t.narration.volume ?? 1, bus: "voiceover" }), r.audio.timeline.addVolumeAutomation("bgm", w + e.startMs + o.startMs, r.audio.bgmVolume * 0.25, 200), r.audio.timeline.addVolumeAutomation("bgm", w + e.startMs + o.startMs + o.durationMs, r.audio.bgmVolume, 200);
+          }
+      r.clearColor(v(m.background)), await r.play(new q(p));
+    } };
+  })();
+  return r.composer?.pendingTasks.push(u), u;
+}
+function J(r, t, i = "primary", u = !1) {
+  const s = t[i];
+  return r.setStroke(t.strokeWidth, v(s)), r.setFill(u ? v(s).alpha(0.18) : $.NONE), t.rough && r.toExcalidraw({ preset: "clean", stroke: s, strokeWidth: t.strokeWidth, roughness: t.roughness, fill: u ? s : "transparent", fillStyle: t.fillStyle, fillGap: 0.18, fillAlpha: 0.1, seed: 17, boil: !1 }), r;
+}
+function Q(r, t, i = 0, u = t.motion.drawMs) {
+  return t.rough ? z.createAnim(r, { delay: i, duration: u }) : new N(r, { delay: i, duration: u });
+}
+function X(r, t, i, u, s, a = {}) {
+  const h = new D(t, { fontSize: 0.42, anchor: L, fill: v(s.primary), opacity: 0 });
+  r.add(h);
+  let m, f;
+  return new x((c) => {
+    h.transform.position.set([m[0] + (f[0] - m[0]) * c, m[1] + (f[1] - m[1]) * c + (a.arc ?? 0.45) * Math.sin(Math.PI * c), m[2] + (f[2] - m[2]) * c]), h.setOpacity(Math.min(1, c * 8, (1 - c) * 8));
+  }, { delay: a.delay ?? 0, duration: a.duration ?? s.motion.moveMs, rate_func: k.smooth(), onStart: () => {
+    m = i(), f = u();
+  }, onComplete: () => r.remove(h) });
+}
+function Z(r, t = 0, i = 900, u = 0.1) {
+  let s;
+  return new x((a) => {
+    const h = 1 + u * Math.sin(Math.PI * a);
+    r.transform.setScale([s[0] * h, s[1] * h, s[2]]);
+  }, { delay: t, duration: i, rate_func: k.smooth(), onStart: () => {
+    const a = r.transform.getScale();
+    s = [a.x, a.y, a.z];
+  } });
+}
+const I = 1, P = "Why does area grow so fast?", B = "How a square's area changes when its side length doubles", F = "Curious beginners", H = "See why doubling both side lengths produces four unit squares.", K = "mathematical", O = { enabled: !1, provider: "msedge", voice: "en-US-AndrewNeural", speed: 1, pitch: "+0Hz", volume: 1 }, V = [], W = [{ id: "area-model", text: "A square of side two can be partitioned into four squares of side one.", sourceIds: [], illustrative: !0 }], j = [{ id: "predict", goal: "Invite a prediction before exposing the area.", visibleChange: "Draw one unit square and mark its side length.", focus: "The original square", minDurationMs: 4500, narration: [{ id: "question", text: "Here is one unit square. If we double its side length, what happens to its area?", pauseAfterMs: 900 }], cues: [{ id: "show", segment: "question" }] }, { id: "grow", goal: "Separate a change in side length from a change in area.", visibleChange: "Expand the outline while retaining the original square.", focus: "Both sides grow", minDurationMs: 5e3, narration: [{ id: "expand", text: "Let's double both sides. The original square still fits in the corner. How much new space have we made?", pauseAfterMs: 700 }], cues: [{ id: "expand", segment: "expand" }] }, { id: "count", goal: "Discover the four equal areas through decomposition.", visibleChange: "Reveal the three additional unit squares in sequence.", focus: "Four equal pieces", minDurationMs: 5e3, narration: [{ id: "reveal", text: "One here, another above, and one more in the corner. Together with our original square, that makes four." }], cues: [{ id: "reveal", segment: "reveal" }] }, { id: "connect", goal: "Connect the construction to the general area relationship.", visibleChange: "Keep all four pieces visible and reveal the equation below them.", focus: "Side length and area", minDurationMs: 4500, narration: [{ id: "insight", text: "Two times the side length gives four times the area. That's the square in side squared: two growing directions, multiplied together." }], cues: [{ id: "equation", segment: "insight" }] }], G = {
+  version: I,
+  title: P,
+  topic: B,
+  audience: F,
+  objective: H,
+  style: K,
+  narration: O,
+  sources: V,
+  claims: W,
+  beats: j
+};
+function ee(r = "mathematical") {
+  return { ...structuredClone(G), style: r };
+}
+export {
+  ae as STYLE_PROFILES,
+  S as assertLesson,
+  E as compileLesson,
+  ee as createExampleLesson,
+  Q as drawGeometry,
+  Z as emphasize,
+  oe as lessonCaptions,
+  Y as prepareLesson,
+  A as resolveStyle,
+  y as speechKey,
+  J as styleGeometry,
+  X as transferValue,
+  se as validateLesson,
+  M as voiceKey
+};

package/dist/libs/explainer/plan.d.ts

@@ -0,0 +1,12 @@
+import { LessonPlan, PreparedSpeech, CompiledLesson, Diagnostic } from './types';
+export * from './types';
+export { STYLE_PROFILES, resolveStyle } from './styles';
+export declare const speechKey: (beat: string, segment: string) => string;
+export declare const voiceKey: (plan: LessonPlan) => string;
+/** Structural checks do not claim that facts, visuals, or teaching quality are correct. */
+export declare function validateLesson(value: unknown): Diagnostic[];
+export declare function assertLesson(value: unknown): asserts value is LessonPlan;
+/** Compile one shared clock. Timing estimates are explicitly labeled until speech is prepared. */
+export declare function compileLesson(plan: LessonPlan, prepared?: PreparedSpeech, fps?: number): CompiledLesson;
+/** Cue groups never span a segment boundary or expose the answer during a prediction pause. */
+export declare function lessonCaptions(timeline: CompiledLesson, wordsPerCue?: number): string;

package/dist/libs/explainer/plan.js

@@ -0,0 +1,219 @@
+/*! Retiam: noncommercial use only unless separately licensed. See ../../LICENSE and ../../COMMERCIAL_LICENSE.md. Third-party notices: ../../THIRD_PARTY_NOTICES.md and ../../THIRD_PARTY_LICENSES.txt. */
+const w = { name: "Dijkstra-style mathematical explainer", background: "#0A1020", ink: "#ECF0F5", muted: "#74869C", primary: "#6CD5FF", secondary: "#F7CF73", font: "roboto", strokeWidth: 0.035, rough: !1, roughness: 0, fillStyle: "solid", motion: { drawMs: 1200, moveMs: 1400, holdMs: 700 }, accents: ["#65F0C4", "#FF879F", "#BA98FF", "#55DDE0"] }, x = { name: "Excalidraw whiteboard", background: "#FFFDF7", ink: "#263238", muted: "#7B858C", primary: "#1971C2", secondary: "#D46B08", font: "excalifont", strokeWidth: 0.04, rough: !0, roughness: 0.7, fillStyle: "hachure", motion: { drawMs: 1600, moveMs: 1500, holdMs: 900 }, accents: ["#1971C2", "#D46B08"] }, k = { name: "Minimal vector", background: "#F8FAFC", ink: "#17212B", muted: "#68788A", primary: "#2563EB", secondary: "#C2410C", font: "roboto", strokeWidth: 0.025, rough: !1, roughness: 0, fillStyle: "solid", motion: { drawMs: 900, moveMs: 1100, holdMs: 650 }, accents: ["#2563EB", "#C2410C"] }, E = { name: "Cinematic diagrams", background: "#080B18", ink: "#F4F1FF", muted: "#8290AA", primary: "#B79AFF", secondary: "#58E0CE", font: "roboto", strokeWidth: 0.04, rough: !1, roughness: 0, fillStyle: "solid", motion: { drawMs: 1500, moveMs: 2e3, holdMs: 1e3 }, accents: ["#B79AFF", "#58E0CE"] }, A = {
+  mathematical: w,
+  excalidraw: x,
+  minimal: k,
+  cinematic: E
+}, b = A;
+function F(i) {
+  const u = typeof i == "string" ? i : i?.extends;
+  if (!Object.hasOwn(b, u ?? ""))
+    throw new Error(`Unknown style '${u}'. Choose ${Object.keys(b).join(", ")} or extend one in the lesson JSON.`);
+  const e = b[u], s = typeof i == "string" ? {} : i;
+  for (const c of Object.keys(s))
+    if (c !== "extends" && !Object.hasOwn(e, c))
+      throw new Error(`Unknown style token '${c}'.`);
+  if (s.motion !== void 0 && (!s.motion || typeof s.motion != "object" || Array.isArray(s.motion)))
+    throw new Error("Style motion must be an object.");
+  for (const c of Object.keys(s.motion ?? {}))
+    if (!Object.hasOwn(e.motion, c))
+      throw new Error(`Unknown style motion token '${c}'.`);
+  const r = { ...e, ...s, motion: { ...e.motion, ...s.motion } };
+  for (const c of ["background", "ink", "muted", "primary", "secondary"])
+    if (!/^#[\da-f]{6}$/i.test(r[c]))
+      throw new Error(`Style ${c} must be a six-digit hex color.`);
+  if (!r.font?.trim() || !r.name?.trim() || typeof r.rough != "boolean" || !["solid", "hachure"].includes(r.fillStyle))
+    throw new Error("Invalid style font, name, rough flag, or fillStyle.");
+  if (!(r.strokeWidth > 0 && r.strokeWidth <= 0.5) || !(r.roughness >= 0 && r.roughness <= 3))
+    throw new Error("Invalid style strokeWidth or roughness.");
+  for (const [c, l] of Object.entries(r.motion))
+    if (!Number.isFinite(l) || l < 0)
+      throw new Error(`Invalid style motion.${c}.`);
+  if (!Array.isArray(r.accents) || !r.accents.length || r.accents.some((c) => !/^#[\da-f]{6}$/i.test(c)))
+    throw new Error("Style accents must contain hex colors.");
+  return { ...r, accents: [...r.accents] };
+}
+const y = /^[a-z][a-z0-9-]*$/, h = (i) => typeof i == "string" && i.trim().length > 0, g = (i) => i.toLowerCase().replace(/[^\p{L}\p{N}]/gu, ""), S = (i, u) => `${i}/${u}`, I = (i) => JSON.stringify({ provider: i.narration.provider ?? "msedge", voice: i.narration.voice ?? ((i.narration.provider ?? "msedge") === "msedge" ? "en-US-AndrewNeural" : null), speed: i.narration.speed ?? 1, pitch: i.narration.pitch ?? ((i.narration.provider ?? "msedge") === "msedge" ? "+0Hz" : null), elevenlabs: i.narration.elevenlabs });
+function D(i) {
+  const u = [], e = (t, o) => u.push({ path: t, message: o });
+  if (!i || typeof i != "object" || Array.isArray(i))
+    return [{ path: "$", message: "Expected a lesson object." }];
+  const s = i;
+  s.version !== 1 && e("version", "Expected version 1.");
+  for (const t of ["title", "topic", "audience", "objective"])
+    h(s[t]) || e(t, "Provide a nonempty string.");
+  try {
+    F(s.style);
+  } catch (t) {
+    e("style", t.message);
+  }
+  (!s.narration || typeof s.narration.enabled != "boolean") && e("narration.enabled", "Choose true or false."), s.narration?.speed !== void 0 && (!Number.isFinite(s.narration.speed) || s.narration.speed <= 0) && e("narration.speed", "Must be positive."), s.narration?.volume !== void 0 && (!Number.isFinite(s.narration.volume) || s.narration.volume < 0 || s.narration.volume > 1) && e("narration.volume", "Must be between 0 and 1."), s.narration?.voice !== void 0 && !h(s.narration.voice) && e("narration.voice", "Must be a voice ID.");
+  for (const t of ["provider", "pitch"])
+    s.narration?.[t] !== void 0 && !h(s.narration[t]) && e(`narration.${t}`, "Must be a nonempty string.");
+  s.narration?.provider === "elevenlabs" && !h(s.narration.voice) && e("narration.voice", "Choose an ElevenLabs voice ID so prepared speech identifies its speaker.");
+  const r = s.narration?.elevenlabs;
+  if (r !== void 0) {
+    const t = "narration.elevenlabs";
+    if (!r || typeof r != "object" || Array.isArray(r)) e(t, "Expected ElevenLabs synthesis settings.");
+    else {
+      const o = ["modelId", "voiceSettings", "languageCode", "seed", "previousText", "nextText", "applyTextNormalization", "pronunciationDictionaries"];
+      for (const n of Object.keys(r))
+        o.includes(n) || e(`${t}.${n}`, "Unknown synthesis setting. Pass credentials to provider.init(), not the lesson.");
+      for (const n of ["modelId", "languageCode"])
+        r[n] !== void 0 && !h(r[n]) && e(`${t}.${n}`, "Must be a nonempty string.");
+      for (const n of ["previousText", "nextText"])
+        r[n] !== void 0 && typeof r[n] != "string" && e(`${t}.${n}`, "Must be a string.");
+      r.seed !== void 0 && (!Number.isInteger(r.seed) || r.seed < 0 || r.seed > 4294967295) && e(`${t}.seed`, "Must be an integer from 0 to 4294967295."), r.applyTextNormalization !== void 0 && !["auto", "on", "off"].includes(r.applyTextNormalization) && e(`${t}.applyTextNormalization`, "Choose auto, on, or off.");
+      const a = r.voiceSettings;
+      if (a !== void 0)
+        if (!a || typeof a != "object" || Array.isArray(a)) e(`${t}.voiceSettings`, "Expected a settings object.");
+        else for (const [n, m] of Object.entries(a))
+          n === "useSpeakerBoost" ? typeof m != "boolean" && e(`${t}.voiceSettings.${n}`, "Must be a boolean.") : ["stability", "similarityBoost", "style", "speed"].includes(n) ? (!Number.isFinite(m) || m < (n === "speed" ? 0.7 : 0) || m > (n === "speed" ? 1.2 : 1)) && e(`${t}.voiceSettings.${n}`, n === "speed" ? "Must be between 0.7 and 1.2." : "Must be between 0 and 1.") : e(`${t}.voiceSettings.${n}`, "Unknown voice setting.");
+      r.pronunciationDictionaries !== void 0 && (!Array.isArray(r.pronunciationDictionaries) || r.pronunciationDictionaries.length > 3 || r.pronunciationDictionaries.some((n) => !n || !h(n.id) || n.versionId !== void 0 && !h(n.versionId))) && e(`${t}.pronunciationDictionaries`, "Provide at most three dictionary IDs with optional version IDs.");
+    }
+  }
+  const c = /* @__PURE__ */ new Set();
+  Array.isArray(s.sources) ? s.sources.forEach((t, o) => {
+    !t || !y.test(t.id) || c.has(t.id) || !h(t.title) ? e(`sources[${o}]`, "Provide a unique source ID and title.") : c.add(t.id);
+  }) : e("sources", "Provide a sources array; it may be empty for an illustrative construction.");
+  const l = (t, o) => {
+    if (!Array.isArray(t))
+      e(o, "Expected source IDs.");
+    else
+      for (const a of t)
+        c.has(a) || e(o, `Unknown source '${a}'.`);
+  }, p = /* @__PURE__ */ new Set();
+  if (s.claims !== void 0 && !Array.isArray(s.claims))
+    e("claims", "Expected an array.");
+  else
+    for (const [t, o] of (s.claims ?? []).entries()) {
+      if (!o || !y.test(o.id) || p.has(o.id) || !h(o.text)) {
+        e(`claims[${t}]`, "Provide a unique claim ID and text.");
+        continue;
+      }
+      p.add(o.id), l(o.sourceIds, `claims[${t}].sourceIds`), o.illustrative !== void 0 && typeof o.illustrative != "boolean" && e(`claims[${t}].illustrative`, "Must be a boolean."), !o.illustrative && !o.sourceIds?.length && e(`claims[${t}].sourceIds`, "Factual claims need a source; mark illustrative models explicitly.");
+    }
+  const v = /* @__PURE__ */ new Set();
+  return !Array.isArray(s.beats) || !s.beats.length ? (e("beats", "Provide at least one beat."), u) : (s.beats.forEach((t, o) => {
+    const a = `beats[${o}]`;
+    if (!t || !y.test(t.id) || v.has(t.id)) {
+      e(a, "Beat IDs must be unique lowercase identifiers.");
+      return;
+    }
+    v.add(t.id);
+    for (const f of ["goal", "visibleChange", "focus"])
+      h(t[f]) || e(`${a}.${f}`, "Describe the learning goal, visible event, and attention target.");
+    t.minDurationMs !== void 0 && (!Number.isFinite(t.minDurationMs) || t.minDurationMs < 0) && e(`${a}.minDurationMs`, "Must be nonnegative."), t.sourceIds !== void 0 && l(t.sourceIds, `${a}.sourceIds`);
+    const n = /* @__PURE__ */ new Map();
+    !Array.isArray(t.narration) || !t.narration.length ? e(`${a}.narration`, "Provide at least one spoken segment, also used for silent preview timing.") : t.narration.forEach((f, d) => {
+      if (!f || !y.test(f.id) || n.has(f.id) || !h(f.text)) {
+        e(`${a}.narration[${d}]`, "Provide a unique segment ID and nonempty spoken text.");
+        return;
+      }
+      n.set(f.id, f.text), f.speechText !== void 0 && !h(f.speechText) && e(`${a}.narration[${d}].speechText`, "Must be nonempty synthesis text."), f.pauseAfterMs !== void 0 && (!Number.isFinite(f.pauseAfterMs) || f.pauseAfterMs < 0) && e(`${a}.narration[${d}].pauseAfterMs`, "Must be nonnegative.");
+    });
+    const m = /* @__PURE__ */ new Set();
+    if (t.cues !== void 0 && !Array.isArray(t.cues))
+      e(`${a}.cues`, "Expected an array.");
+    else
+      for (const [f, d] of (t.cues ?? []).entries()) {
+        if (!d || !y.test(d.id) || m.has(d.id)) {
+          e(`${a}.cues[${f}]`, "Provide a unique cue ID.");
+          continue;
+        }
+        m.add(d.id), n.has(d.segment) || e(`${a}.cues[${f}].segment`, "Cue references an unknown narration segment."), d.phrase !== void 0 && (!h(d.phrase) || !g(n.get(d.segment) ?? "").includes(g(d.phrase))) && e(`${a}.cues[${f}].phrase`, "Phrase must occur in the specified spoken segment."), d.occurrence !== void 0 && (!Number.isSafeInteger(d.occurrence) || d.occurrence < 1) && e(`${a}.cues[${f}].occurrence`, "Must be a positive occurrence number."), d.offsetMs !== void 0 && (!Number.isFinite(d.offsetMs) || d.offsetMs < 0) && e(`${a}.cues[${f}].offsetMs`, "Must be nonnegative.");
+      }
+  }), u);
+}
+function C(i) {
+  const u = D(i);
+  if (u.length)
+    throw new Error(u.map((e) => `${e.path}: ${e.message}`).join(`
+`));
+}
+function N(i, u) {
+  const e = u.trim().split(/\s+/).map(g), s = [];
+  return i.forEach((r, c) => {
+    e.every((l, p) => g(i[c + p]?.text ?? "") === l) && s.push(c);
+  }), s;
+}
+function j(i, u, e = 60) {
+  if (C(i), !Number.isSafeInteger(e) || e < 1 || e > 240)
+    throw new Error("fps must be an integer from 1 to 240.");
+  if (i.narration.enabled && (!u || u.version !== 1 || !u.assets || typeof u.assets != "object" || u.voiceKey !== I(i)))
+    throw new Error("Narration is not prepared for these voice settings. Run retiam lesson prepare.");
+  let s = 0;
+  const r = [];
+  for (const c of i.beats) {
+    let l = 0;
+    const p = [];
+    for (const o of c.narration) {
+      const a = i.narration.enabled ? u.assets[S(c.id, o.id)] : void 0;
+      if (i.narration.enabled && (!a || a.text !== o.text || (a.speechText ?? a.text) !== (o.speechText ?? o.text)))
+        throw new Error(`Missing or stale audio: ${c.id}/${o.id}. Prepare narration again.`);
+      const n = a?.durationMs ?? Math.max(900, o.text.trim().split(/\s+/).length * 360);
+      if (!Number.isFinite(n) || n <= 0)
+        throw new Error(`Invalid speech duration: ${c.id}/${o.id}.`);
+      if (a && (!Array.isArray(a.words) || !a.words.length))
+        throw new Error(`Missing word timings: ${c.id}/${o.id}.`);
+      const m = a?.words ?? o.text.trim().split(/\s+/).map((d, $, M) => ({ text: d, offsetMs: n * $ / M.length, durationMs: n / M.length }));
+      let f = -1;
+      for (const d of m) {
+        if (!h(d.text) || !Number.isFinite(d.offsetMs) || !Number.isFinite(d.durationMs) || d.offsetMs < f - 0.1 || d.durationMs < 0 || d.offsetMs + d.durationMs > n + 1)
+          throw new Error(`Invalid word timings: ${c.id}/${o.id}.`);
+        f = d.offsetMs + d.durationMs;
+      }
+      p.push({ ...a, text: o.text, id: o.id, durationMs: n, words: m, startMs: l, pauseAfterMs: o.pauseAfterMs ?? 0 }), l += n + (o.pauseAfterMs ?? 0);
+    }
+    const v = Math.ceil(Math.max(c.minDurationMs ?? 0, l + 450) * e / 1e3 - 1e-8) * 1e3 / e, t = {};
+    for (const o of c.cues ?? []) {
+      const a = p.find((m) => m.id === o.segment);
+      let n = a.startMs;
+      if (o.phrase) {
+        const m = N(a.words, o.phrase);
+        if (m.length > 1 && o.occurrence === void 0)
+          throw new Error(`Ambiguous cue '${c.id}/${o.id}'; set occurrence.`);
+        const f = m[(o.occurrence ?? 1) - 1];
+        if (f === void 0)
+          throw new Error(`Unaligned cue '${c.id}/${o.id}': ${o.phrase}.`);
+        n += a.words[f].offsetMs;
+      }
+      if (n += o.offsetMs ?? 0, n > a.startMs + a.durationMs)
+        throw new Error(`Cue '${c.id}/${o.id}' falls outside its speech segment.`);
+      t[o.id] = n;
+    }
+    r.push({ id: c.id, startMs: s, durationMs: v, segments: p, cues: t }), s += v;
+  }
+  return { version: 1, timing: i.narration.enabled ? "recorded" : "estimated", fps: e, durationMs: s, beats: r };
+}
+function O(i, u = 8) {
+  if (!Number.isInteger(u) || u < 1)
+    throw new Error("wordsPerCue must be positive.");
+  const e = (c) => {
+    const l = Math.round(c);
+    return `${String(Math.floor(l / 36e5)).padStart(2, "0")}:${String(Math.floor(l / 6e4) % 60).padStart(2, "0")}:${String(Math.floor(l / 1e3) % 60).padStart(2, "0")},${String(l % 1e3).padStart(3, "0")}`;
+  };
+  let s = 0;
+  const r = [];
+  for (const c of i.beats)
+    for (const l of c.segments)
+      for (let p = 0; p < l.words.length; p += u) {
+        const v = l.words.slice(p, p + u), t = v.at(-1);
+        r.push(`${++s}
+${e(c.startMs + l.startMs + v[0].offsetMs)} --> ${e(c.startMs + l.startMs + t.offsetMs + t.durationMs)}
+${v.map((o) => o.text).join(" ")}
+`);
+      }
+  return r.join(`
+`);
+}
+export {
+  b as STYLE_PROFILES,
+  C as assertLesson,
+  j as compileLesson,
+  O as lessonCaptions,
+  F as resolveStyle,
+  S as speechKey,
+  D as validateLesson,
+  I as voiceKey
+};

package/dist/libs/explainer/runtime.d.ts

@@ -0,0 +1,24 @@
+import { Animation, Scene } from 'retiam';
+import { TTSAudioResult } from 'retiam/tts';
+import { LessonPlan, PreparedSpeech, CompiledLesson, CompiledBeat, StyleProfile } from './types';
+export interface BeatContext {
+    beat: CompiledBeat;
+    durationMs: number;
+    style: StyleProfile;
+    cue(id: string): number;
+    at(id: string, action: () => void): Animation;
+}
+export interface PreparedLesson {
+    plan: LessonPlan;
+    timeline: CompiledLesson;
+    style: StyleProfile;
+    /** Handlers build animations up front. Put state changes inside animations or at(). */
+    run(handlers: Record<string, (beat: BeatContext) => Animation[]>): Promise<void>;
+}
+export interface PrepareLessonOptions {
+    prepared?: PreparedSpeech;
+    fps?: number;
+    /** Optional adapter; defaults to the active retiam/tts provider. */
+    synthesize?: (text: string) => Promise<TTSAudioResult>;
+}
+export declare function prepareLesson(scene: Scene, plan: LessonPlan, options?: PrepareLessonOptions): Promise<PreparedLesson>;

package/dist/libs/explainer/styles.d.ts

@@ -0,0 +1,3 @@
+import { StyleId, StyleInput, StyleProfile } from './types';
+export declare const STYLE_PROFILES: Readonly<Record<StyleId, StyleProfile>>;
+export declare function resolveStyle(input: StyleInput): StyleProfile;

package/dist/libs/explainer/types.d.ts

@@ -0,0 +1,124 @@
+import { ElevenLabsGenerateOptions } from '../tts/core/types';
+/** A visual profile is independent of the topic and teaching sequence. */
+export type StyleId = 'mathematical' | 'excalidraw' | 'minimal' | 'cinematic';
+export interface StyleProfile {
+    name: string;
+    background: string;
+    ink: string;
+    muted: string;
+    primary: string;
+    secondary: string;
+    accents: string[];
+    font: string;
+    strokeWidth: number;
+    rough: boolean;
+    roughness: number;
+    fillStyle: 'solid' | 'hachure';
+    motion: {
+        drawMs: number;
+        moveMs: number;
+        holdMs: number;
+    };
+}
+export type StyleInput = StyleId | ({
+    extends: StyleId;
+} & Partial<Omit<StyleProfile, 'motion'>> & {
+    motion?: Partial<StyleProfile['motion']>;
+});
+export interface LessonSource {
+    id: string;
+    title: string;
+    url?: string;
+    note?: string;
+}
+export interface LessonClaim {
+    id: string;
+    text: string;
+    sourceIds: string[];
+    illustrative?: boolean;
+}
+export interface NarrationSegment {
+    id: string;
+    text: string;
+    /** Optional synthesis text with delivery tags; text remains clean for captions/cues. */
+    speechText?: string;
+    pauseAfterMs?: number;
+}
+/** Phrases are scoped to a segment. Repeated phrases require an explicit occurrence (1-based). */
+export interface LessonCue {
+    id: string;
+    segment: string;
+    phrase?: string;
+    occurrence?: number;
+    offsetMs?: number;
+}
+export interface LessonBeat {
+    id: string;
+    goal: string;
+    visibleChange: string;
+    focus: string;
+    minDurationMs?: number;
+    narration: NarrationSegment[];
+    cues?: LessonCue[];
+    sourceIds?: string[];
+}
+export interface LessonPlan {
+    version: 1;
+    title: string;
+    topic: string;
+    audience: string;
+    objective: string;
+    style: StyleInput;
+    narration: {
+        enabled: boolean;
+        provider?: string;
+        voice?: string;
+        speed?: number;
+        pitch?: string;
+        volume?: number;
+        elevenlabs?: ElevenLabsGenerateOptions;
+    };
+    sources: LessonSource[];
+    claims?: LessonClaim[];
+    beats: LessonBeat[];
+}
+export interface TimedWord {
+    text: string;
+    offsetMs: number;
+    durationMs: number;
+}
+export interface SpeechAsset {
+    text: string;
+    speechText?: string;
+    durationMs: number;
+    words: TimedWord[];
+    url?: string;
+}
+export interface PreparedSpeech {
+    version: 1;
+    voiceKey: string;
+    assets: Record<string, SpeechAsset>;
+}
+export interface CompiledSegment extends SpeechAsset {
+    id: string;
+    startMs: number;
+    pauseAfterMs: number;
+}
+export interface CompiledBeat {
+    id: string;
+    startMs: number;
+    durationMs: number;
+    segments: CompiledSegment[];
+    cues: Record<string, number>;
+}
+export interface CompiledLesson {
+    version: 1;
+    timing: 'recorded' | 'estimated';
+    fps: number;
+    durationMs: number;
+    beats: CompiledBeat[];
+}
+export interface Diagnostic {
+    path: string;
+    message: string;
+}

package/dist/libs/explainer/visuals.d.ts

@@ -0,0 +1,18 @@
+import { Animation, Entity, Scene, VectorEntity } from 'retiam';
+import { StyleProfile } from './types';
+export type LessonPoint = [
+    number,
+    number,
+    number
+];
+/** Apply a profile to geometry; text keeps readable glyphs and uses the profile's font. */
+export declare function styleGeometry<T extends VectorEntity>(entity: T, style: StyleProfile, role?: 'primary' | 'secondary' | 'ink', fill?: boolean): T;
+export declare function drawGeometry(entity: VectorEntity, style: StyleProfile, delay?: number, duration?: number): Animation;
+/** Move a value between representations while preserving its visual identity. */
+export declare function transferValue(scene: Scene, text: string, from: () => LessonPoint, to: () => LessonPoint, style: StyleProfile, options?: {
+    delay?: number;
+    duration?: number;
+    arc?: number;
+}): Animation;
+/** Attention without changing the object's persistent position or scale. */
+export declare function emphasize(entity: Entity, delay?: number, duration?: number, strength?: number): Animation;

package/dist/libs/tts/animations/Speak.d.ts

@@ -1,13 +1,17 @@
 import { Animation, AnimOptions, Entity, Scene } from 'retiam';
 import { Subtitles } from '../components/Subtitles';
-import { MsEdgeVoiceId, TTSAudioResult } from '../core/types';
+import { VoiceId, TTSAudioResult, ElevenLabsGenerateOptions } from '../core/types';
 export interface SpeakOptions extends AnimOptions {
-    /** Microsoft Edge neural voice ID for narration. */
-    voice?: MsEdgeVoiceId;
-    /** Speaking rate multiplier. Defaults to 1.0. */
+    /** Voice ID; omitted values use the active provider's default. */
+    voice?: VoiceId;
+    /** Speaking rate multiplier; omitted values inherit the provider default. */
     speed?: number;
     /** Pitch shift (for MsEdge TTS, e.g. "+0Hz", "+5st", "+10%"). */
     pitch?: string | number;
+    /** Clean subtitle text when speech contains delivery or pronunciation tags. */
+    displayText?: string;
+    /** Per-utterance ElevenLabs delivery and model overrides. */
+    elevenlabs?: ElevenLabsGenerateOptions;
     /** Optional Subtitles component to automatically synchronize closed captions. */
     subtitles?: Subtitles;
     /** Optional entity to animate with speaking micro-pulses. */
@@ -22,7 +26,7 @@ export interface SpeakOptions extends AnimOptions {
 /**
  * Retiam Animation for spoken narration.
  *
- * Synchronizes Microsoft Edge neural speech, voiceover auto-ducking
+ * Synchronizes speech from the active provider, voiceover auto-ducking
  * on Retiam's [[AudioManager]], timeline pacing, closed captions/subtitles, and entity micro-animations.
  *
  * @example
@@ -37,7 +41,7 @@ export interface SpeakOptions extends AnimOptions {
  */
 export declare class Speak extends Animation {
     readonly text: string;
-    readonly voice: string;
+    readonly voice?: string;
     readonly speed: number;
     readonly pitch?: string | number;
     readonly subtitles?: Subtitles;
@@ -46,6 +50,8 @@ export declare class Speak extends Animation {
     readonly duckingRatio: number;
     readonly volume: number;
     private _audioResult;
+    private _audioTask;
+    private readonly _synthesisOptions;
     private _isStarted;
     private _baseScale;
     constructor(text: string, options?: SpeakOptions);
@@ -64,7 +70,7 @@ export declare class Speak extends Animation {
 /**
  * High-level helper function to speak narration in a Retiam Scene.
  *
- * Synthesizes speech using Microsoft Edge neural TTS,
+ * Synthesizes speech using the active provider,
  * synchronizes subtitles, ducks background music, and pauses scene progression
  * for the duration of the audio.
  *

package/dist/libs/tts/components/TTSNarrationComponent.d.ts

@@ -1,10 +1,11 @@
 import { Component } from 'retiam';
-import { MsEdgeVoiceId, TTSAudioResult, TTSGenerateOptions, TTSPlaybackOptions } from '../core/types';
+import { VoiceId, TTSAudioResult, TTSGenerateOptions, TTSPlaybackOptions, ElevenLabsGenerateOptions } from '../core/types';
 export interface TTSNarrationOptions {
-    /** Preferred Microsoft Edge neural voice ID. */
-    voice?: MsEdgeVoiceId;
-    /** Default speaking rate. Defaults to 1.0. */
+    /** Voice ID; omitted values use the active provider's default. */
+    voice?: VoiceId;
+    /** Speaking rate override; omitted values inherit the provider default. */
     speed?: number;
+    elevenlabs?: ElevenLabsGenerateOptions;
     /** Whether to visually pulse the entity's scale during speech. Defaults to true. */
     animateSpeaking?: boolean;
     /** Scale pulse amplitude during speech (e.g. 0.06 = ±6% pulse). Defaults to 0.05. */
@@ -19,12 +20,13 @@ export interface TTSNarrationOptions {
 /**
  * Retiam ECS Component that empowers any visual Entity with voice narration capabilities.
  *
- * Features automatic Microsoft Edge neural speech synthesis,
+ * Features speech synthesis through the active provider,
  * voiceover ducking, and synchronized micro-interaction visual pulses while speaking.
  */
 export declare class TTSNarrationComponent extends Component {
-    voice: string;
-    speed: number;
+    voice?: string;
+    speed?: number;
+    elevenlabs?: ElevenLabsGenerateOptions;
     animateSpeaking: boolean;
     pulseAmplitude: number;
     pulseFrequency: number;