retiam 2.0.1 → 2.0.2

package/dist/{index-B2sJBy4c.js → index-yQIdejOj.js}

@@ -1939,14 +1939,12 @@ class Nt {
       if (this._intervalAccumulator += t, this._intervalAccumulator < e && this.elapsed + this._intervalAccumulator < this.duration)
         return !1;
       const i = this._intervalAccumulator;
-      this._intervalAccumulator = 0, this._isStepping = !0;
-      try {
-        return this.update(i);
-      } finally {
-        this._isStepping = !1;
-      }
+      return this._intervalAccumulator = 0, this._advanceTimelineStep(i);
     }
-    this._isStepping = !0;
+    return this._advanceTimelineStep(t);
+  }
+  _advanceTimelineStep(t) {
+    !this._startFired && t >= Math.max(0, this.delay) && (this._startFired = !0, this.onStart?.()), this._isStepping = !0;
     try {
       return this.update(t);
     } finally {
@@ -17542,7 +17540,7 @@ const lp = {
   // --- NEW: Convert to a static async preload method ---
   static async preloadModel(t, e, i = "rt_hdr_alb_nrm") {
     if (!(this.modelState === "ready" && this.currentModel === i))
-      return this.modelState === "loading" ? this.loadPromise : (this.modelState = "loading", this.loadPromise = import("./main-D_G4uIju.js").then(async (r) => {
+      return this.modelState === "loading" ? this.loadPromise : (this.modelState = "loading", this.loadPromise = import("./main-BTk_9jtl.js").then(async (r) => {
         const n = typeof e.requestAdapterInfo == "function" ? await e.requestAdapterInfo() : e.info, s = lp[i];
         if (!s)
           throw new Error(`Unsupported OIDN model configured: ${i}`);
@@ -20087,7 +20085,7 @@ class gt {
             if (!i) continue;
             const T = g.toLowerCase();
             if (T.endsWith(".tif") || T.endsWith(".tiff")) {
-              const I = await (await fetch(g)).arrayBuffer(), C = await import("./UTIF-2Ear_0Uo.js").then((x) => x.U), m = C.default || C, p = m.decode(I);
+              const I = await (await fetch(g)).arrayBuffer(), C = await import("./UTIF-CN0-pEnd.js").then((x) => x.U), m = C.default || C, p = m.decode(I);
               if (typeof m.decodeImage == "function") m.decodeImage(I, p[0]);
               else if (typeof m.decodeImages == "function") m.decodeImages(I, p);
               else throw new Error("UTIF decode function not found.");
@@ -28560,7 +28558,7 @@ class Xn extends Pe {
     try {
       const e = t.toLowerCase();
       if (e.endsWith(".tif") || e.endsWith(".tiff")) {
-        const r = await (await fetch(t)).arrayBuffer(), n = await import("./UTIF-2Ear_0Uo.js").then((c) => c.U), s = n.default || n, A = s.decode(r);
+        const r = await (await fetch(t)).arrayBuffer(), n = await import("./UTIF-CN0-pEnd.js").then((c) => c.U), s = n.default || n, A = s.decode(r);
         if (typeof s.decodeImage == "function")
           s.decodeImage(r, A[0]);
         else if (typeof s.decodeImages == "function")
@@ -43033,10 +43031,14 @@ class UB {
     if (!(this.context.state === "running" || typeof window > "u"))
       return new Promise((t) => {
         const e = () => {
-          this.context.resume().catch(() => {
-          }).finally(() => t()), window.removeEventListener("pointerdown", e), window.removeEventListener("keydown", e), window.removeEventListener("click", e);
+          this.context.removeEventListener("statechange", i), window.removeEventListener("pointerdown", r), window.removeEventListener("keydown", r), window.removeEventListener("click", r), t();
+        }, i = () => {
+          this.context.state === "running" && e();
+        }, r = () => {
+          this.context.resume().then(i).catch(() => {
+          });
         };
-        window.addEventListener("pointerdown", e, { once: !0, passive: !0 }), window.addEventListener("keydown", e, { once: !0, passive: !0 }), window.addEventListener("click", e, { once: !0, passive: !0 });
+        this.context.addEventListener("statechange", i), window.addEventListener("pointerdown", r, { once: !0, passive: !0 }), window.addEventListener("keydown", r, { once: !0, passive: !0 }), window.addEventListener("click", r, { once: !0, passive: !0 }), i();
       });
   }
   /**

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,134 @@
+import { assertLesson as S, voiceKey as x, 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 v, TrackAnimation as q, Waiting as C, hex as b, Color as T, Excalidraw as $, Create as z, Tex as N, CENTER as D, Rate as k } from "retiam";
+import { TTS as L } 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 d = (async () => {
+    const s = /* @__PURE__ */ new Map();
+    let a = i.prepared;
+    if (t.narration.enabled) {
+      if (!a && !i.synthesize && (t.narration.provider ?? "msedge") !== "msedge")
+        throw new Error("Provide prepared speech or a synthesize adapter for this narration provider.");
+      const m = r.audio;
+      if (a && a.voiceKey !== x(t))
+        throw new Error("Prepared narration uses different voice settings. Prepare narration again.");
+      a = a ?? { version: 1, voiceKey: x(t), assets: {} };
+      const c = t.beats.flatMap((n) => n.narration.map((e) => ({ beat: n.id, segment: e })));
+      let w = 0;
+      await Promise.all(Array.from({ length: Math.min(3, c.length) }, async () => {
+        for (; w < c.length; ) {
+          const n = c[w++], e = y(n.beat, n.segment.id);
+          let u;
+          if (i.prepared) {
+            const o = a.assets[e];
+            if (!o || o.text !== n.segment.text || !o.url)
+              throw new Error(`Missing/stale prepared asset: ${e}.`);
+            const g = await fetch(o.url);
+            if (!g.ok)
+              throw new Error(`Narration asset ${o.url}: HTTP ${g.status}.`);
+            if (u = await m.context.decodeAudioData(await g.arrayBuffer()), Math.abs(u.duration * 1e3 - o.durationMs) > 120)
+              throw new Error(`Narration duration mismatch: ${e}.`);
+          } else {
+            const o = await (i.synthesize?.(n.segment.text) ?? L.synthesize(n.segment.text, { voice: t.narration.voice ?? "en-US-AndrewNeural", speed: t.narration.speed ?? 1, pitch: t.narration.pitch ?? "+0Hz", volume: 1 }));
+            a.assets[e] = { text: n.segment.text, durationMs: o.durationMs, words: (o.wordBoundaries ?? []).map((g) => ({ text: g.text, offsetMs: g.offsetMs, durationMs: g.durationMs })) }, u = o.rawBuffer ? await m.context.decodeAudioData(o.rawBuffer.slice(0)) : o.toAudioBuffer(m.context);
+          }
+          s.set(e, u);
+        }
+      }));
+    }
+    const l = E(t, a, i.fps ?? 60), h = A(t.style);
+    return { plan: t, timeline: l, style: h, async run(m) {
+      const c = new Set(t.beats.map((e) => e.id));
+      for (const e of Object.keys(m))
+        if (!c.has(e))
+          throw new Error(`Unknown beat handler '${e}'.`);
+      const w = [];
+      for (const e of l.beats) {
+        const u = m[e.id];
+        if (!u)
+          throw new Error(`Missing beat handler '${e.id}'.`);
+        const o = (f) => {
+          const p = e.cues[f];
+          if (p === void 0)
+            throw new Error(`Unknown cue '${e.id}/${f}'.`);
+          return p;
+        }, g = u({ beat: e, durationMs: e.durationMs, style: h, cue: o, at: (f, p) => new v(() => {
+        }, { delay: o(f), duration: 1, onStart: p }) });
+        for (const f of g)
+          if (!Number.isFinite(f.delay) || !Number.isFinite(f.duration) || f.delay < 0 || f.duration < 0 || f.delay + f.duration > e.durationMs + 0.1)
+            throw new Error(`Animation exceeds beat '${e.id}' (${e.durationMs} ms).`);
+        const M = new q([...g, new C({ duration: e.durationMs })]);
+        M.delay = e.startMs, w.push(M);
+      }
+      const n = r.composer?.time ?? 0;
+      if (t.narration.enabled)
+        for (const e of l.beats)
+          for (const u of e.segments) {
+            const o = s.get(y(e.id, u.id));
+            r.audio.timeline.addClip(o, n + e.startMs + u.startMs, r.audio.voiceoverGain, { volume: t.narration.volume ?? 1, bus: "voiceover" }), r.audio.timeline.addVolumeAutomation("bgm", n + e.startMs + u.startMs, r.audio.bgmVolume * 0.25, 200), r.audio.timeline.addVolumeAutomation("bgm", n + e.startMs + u.startMs + u.durationMs, r.audio.bgmVolume, 200);
+          }
+      r.clearColor(b(h.background)), await r.play(new q(w));
+    } };
+  })();
+  return r.composer?.pendingTasks.push(d), d;
+}
+function J(r, t, i = "primary", d = !1) {
+  const s = t[i];
+  return r.setStroke(t.strokeWidth, b(s)), r.setFill(d ? b(s).alpha(0.18) : T.NONE), t.rough && r.toExcalidraw({ preset: "clean", stroke: s, strokeWidth: t.strokeWidth, roughness: t.roughness, fill: d ? s : "transparent", fillStyle: t.fillStyle, fillGap: 0.18, fillAlpha: 0.1, seed: 17, boil: !1 }), r;
+}
+function Q(r, t, i = 0, d = t.motion.drawMs) {
+  return t.rough ? $.createAnim(r, { delay: i, duration: d }) : new z(r, { delay: i, duration: d });
+}
+function X(r, t, i, d, s, a = {}) {
+  const l = new N(t, { fontSize: 0.42, anchor: D, fill: b(s.primary), opacity: 0 });
+  r.add(l);
+  let h, m;
+  return new v((c) => {
+    l.transform.position.set([h[0] + (m[0] - h[0]) * c, h[1] + (m[1] - h[1]) * c + (a.arc ?? 0.45) * Math.sin(Math.PI * c), h[2] + (m[2] - h[2]) * c]), l.setOpacity(Math.min(1, c * 8, (1 - c) * 8));
+  }, { delay: a.delay ?? 0, duration: a.duration ?? s.motion.moveMs, rate_func: k.smooth(), onStart: () => {
+    h = i(), m = d();
+  }, onComplete: () => r.remove(l) });
+}
+function Z(r, t = 0, i = 900, d = 0.1) {
+  let s;
+  return new v((a) => {
+    const l = 1 + d * Math.sin(Math.PI * a);
+    r.transform.setScale([s[0] * l, s[1] * l, s[2]]);
+  }, { delay: t, duration: i, rate_func: k.smooth(), onStart: () => {
+    const a = r.transform.getScale();
+    s = [a.x, a.y, a.z];
+  } });
+}
+const P = 1, B = "Why does area grow so fast?", H = "How a square's area changes when its side length doubles", I = "Curious beginners", F = "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: P,
+  title: B,
+  topic: H,
+  audience: I,
+  objective: F,
+  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,
+  x 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,197 @@
+/*! 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 b = { 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"] }, k = { 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"] }, E = { 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"] }, F = { 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: b,
+  excalidraw: k,
+  minimal: E,
+  cinematic: F
+}, w = A;
+function x(n) {
+  const i = typeof n == "string" ? n : n?.extends;
+  if (!Object.hasOwn(w, i ?? ""))
+    throw new Error(`Unknown style '${i}'. Choose ${Object.keys(w).join(", ")} or extend one in the lesson JSON.`);
+  const e = w[i], r = typeof n == "string" ? {} : n;
+  for (const s of Object.keys(r))
+    if (s !== "extends" && !Object.hasOwn(e, s))
+      throw new Error(`Unknown style token '${s}'.`);
+  if (r.motion !== void 0 && (!r.motion || typeof r.motion != "object" || Array.isArray(r.motion)))
+    throw new Error("Style motion must be an object.");
+  for (const s of Object.keys(r.motion ?? {}))
+    if (!Object.hasOwn(e.motion, s))
+      throw new Error(`Unknown style motion token '${s}'.`);
+  const a = { ...e, ...r, motion: { ...e.motion, ...r.motion } };
+  for (const s of ["background", "ink", "muted", "primary", "secondary"])
+    if (!/^#[\da-f]{6}$/i.test(a[s]))
+      throw new Error(`Style ${s} must be a six-digit hex color.`);
+  if (!a.font?.trim() || !a.name?.trim() || typeof a.rough != "boolean" || !["solid", "hachure"].includes(a.fillStyle))
+    throw new Error("Invalid style font, name, rough flag, or fillStyle.");
+  if (!(a.strokeWidth > 0 && a.strokeWidth <= 0.5) || !(a.roughness >= 0 && a.roughness <= 3))
+    throw new Error("Invalid style strokeWidth or roughness.");
+  for (const [s, f] of Object.entries(a.motion))
+    if (!Number.isFinite(f) || f < 0)
+      throw new Error(`Invalid style motion.${s}.`);
+  if (!Array.isArray(a.accents) || !a.accents.length || a.accents.some((s) => !/^#[\da-f]{6}$/i.test(s)))
+    throw new Error("Style accents must contain hex colors.");
+  return { ...a, accents: [...a.accents] };
+}
+const M = /^[a-z][a-z0-9-]*$/, y = (n) => typeof n == "string" && n.trim().length > 0, v = (n) => n.toLowerCase().replace(/[^\p{L}\p{N}]/gu, ""), S = (n, i) => `${n}/${i}`, I = (n) => JSON.stringify({ provider: n.narration.provider ?? "msedge", voice: n.narration.voice ?? "en-US-AndrewNeural", speed: n.narration.speed ?? 1, pitch: n.narration.pitch ?? "+0Hz" });
+function C(n) {
+  const i = [], e = (t, d) => i.push({ path: t, message: d });
+  if (!n || typeof n != "object" || Array.isArray(n))
+    return [{ path: "$", message: "Expected a lesson object." }];
+  const r = n;
+  r.version !== 1 && e("version", "Expected version 1.");
+  for (const t of ["title", "topic", "audience", "objective"])
+    y(r[t]) || e(t, "Provide a nonempty string.");
+  try {
+    x(r.style);
+  } catch (t) {
+    e("style", t.message);
+  }
+  (!r.narration || typeof r.narration.enabled != "boolean") && e("narration.enabled", "Choose true or false."), r.narration?.speed !== void 0 && (!Number.isFinite(r.narration.speed) || r.narration.speed <= 0) && e("narration.speed", "Must be positive."), r.narration?.volume !== void 0 && (!Number.isFinite(r.narration.volume) || r.narration.volume < 0 || r.narration.volume > 1) && e("narration.volume", "Must be between 0 and 1."), r.narration?.voice !== void 0 && !y(r.narration.voice) && e("narration.voice", "Must be a voice ID.");
+  for (const t of ["provider", "pitch"])
+    r.narration?.[t] !== void 0 && !y(r.narration[t]) && e(`narration.${t}`, "Must be a nonempty string.");
+  const a = /* @__PURE__ */ new Set();
+  Array.isArray(r.sources) ? r.sources.forEach((t, d) => {
+    !t || !M.test(t.id) || a.has(t.id) || !y(t.title) ? e(`sources[${d}]`, "Provide a unique source ID and title.") : a.add(t.id);
+  }) : e("sources", "Provide a sources array; it may be empty for an illustrative construction.");
+  const s = (t, d) => {
+    if (!Array.isArray(t))
+      e(d, "Expected source IDs.");
+    else
+      for (const o of t)
+        a.has(o) || e(d, `Unknown source '${o}'.`);
+  }, f = /* @__PURE__ */ new Set();
+  if (r.claims !== void 0 && !Array.isArray(r.claims))
+    e("claims", "Expected an array.");
+  else
+    for (const [t, d] of (r.claims ?? []).entries()) {
+      if (!d || !M.test(d.id) || f.has(d.id) || !y(d.text)) {
+        e(`claims[${t}]`, "Provide a unique claim ID and text.");
+        continue;
+      }
+      f.add(d.id), s(d.sourceIds, `claims[${t}].sourceIds`), d.illustrative !== void 0 && typeof d.illustrative != "boolean" && e(`claims[${t}].illustrative`, "Must be a boolean."), !d.illustrative && !d.sourceIds?.length && e(`claims[${t}].sourceIds`, "Factual claims need a source; mark illustrative models explicitly.");
+    }
+  const h = /* @__PURE__ */ new Set();
+  return !Array.isArray(r.beats) || !r.beats.length ? (e("beats", "Provide at least one beat."), i) : (r.beats.forEach((t, d) => {
+    const o = `beats[${d}]`;
+    if (!t || !M.test(t.id) || h.has(t.id)) {
+      e(o, "Beat IDs must be unique lowercase identifiers.");
+      return;
+    }
+    h.add(t.id);
+    for (const c of ["goal", "visibleChange", "focus"])
+      y(t[c]) || e(`${o}.${c}`, "Describe the learning goal, visible event, and attention target.");
+    t.minDurationMs !== void 0 && (!Number.isFinite(t.minDurationMs) || t.minDurationMs < 0) && e(`${o}.minDurationMs`, "Must be nonnegative."), t.sourceIds !== void 0 && s(t.sourceIds, `${o}.sourceIds`);
+    const l = /* @__PURE__ */ new Map();
+    !Array.isArray(t.narration) || !t.narration.length ? e(`${o}.narration`, "Provide at least one spoken segment, also used for silent preview timing.") : t.narration.forEach((c, u) => {
+      if (!c || !M.test(c.id) || l.has(c.id) || !y(c.text)) {
+        e(`${o}.narration[${u}]`, "Provide a unique segment ID and nonempty spoken text.");
+        return;
+      }
+      l.set(c.id, c.text), c.pauseAfterMs !== void 0 && (!Number.isFinite(c.pauseAfterMs) || c.pauseAfterMs < 0) && e(`${o}.narration[${u}].pauseAfterMs`, "Must be nonnegative.");
+    });
+    const m = /* @__PURE__ */ new Set();
+    if (t.cues !== void 0 && !Array.isArray(t.cues))
+      e(`${o}.cues`, "Expected an array.");
+    else
+      for (const [c, u] of (t.cues ?? []).entries()) {
+        if (!u || !M.test(u.id) || m.has(u.id)) {
+          e(`${o}.cues[${c}]`, "Provide a unique cue ID.");
+          continue;
+        }
+        m.add(u.id), l.has(u.segment) || e(`${o}.cues[${c}].segment`, "Cue references an unknown narration segment."), u.phrase !== void 0 && (!y(u.phrase) || !v(l.get(u.segment) ?? "").includes(v(u.phrase))) && e(`${o}.cues[${c}].phrase`, "Phrase must occur in the specified spoken segment."), u.occurrence !== void 0 && (!Number.isSafeInteger(u.occurrence) || u.occurrence < 1) && e(`${o}.cues[${c}].occurrence`, "Must be a positive occurrence number."), u.offsetMs !== void 0 && (!Number.isFinite(u.offsetMs) || u.offsetMs < 0) && e(`${o}.cues[${c}].offsetMs`, "Must be nonnegative.");
+      }
+  }), i);
+}
+function D(n) {
+  const i = C(n);
+  if (i.length)
+    throw new Error(i.map((e) => `${e.path}: ${e.message}`).join(`
+`));
+}
+function j(n, i) {
+  const e = i.trim().split(/\s+/).map(v), r = [];
+  return n.forEach((a, s) => {
+    e.every((f, h) => v(n[s + h]?.text ?? "") === f) && r.push(s);
+  }), r;
+}
+function N(n, i, e = 60) {
+  if (D(n), !Number.isSafeInteger(e) || e < 1 || e > 240)
+    throw new Error("fps must be an integer from 1 to 240.");
+  if (n.narration.enabled && (!i || i.version !== 1 || !i.assets || typeof i.assets != "object" || i.voiceKey !== I(n)))
+    throw new Error("Narration is not prepared for these voice settings. Run retiam lesson prepare.");
+  let r = 0;
+  const a = [];
+  for (const s of n.beats) {
+    let f = 0;
+    const h = [];
+    for (const o of s.narration) {
+      const l = n.narration.enabled ? i.assets[S(s.id, o.id)] : void 0;
+      if (n.narration.enabled && (!l || l.text !== o.text))
+        throw new Error(`Missing or stale audio: ${s.id}/${o.id}. Prepare narration again.`);
+      const m = l?.durationMs ?? Math.max(900, o.text.trim().split(/\s+/).length * 360);
+      if (!Number.isFinite(m) || m <= 0)
+        throw new Error(`Invalid speech duration: ${s.id}/${o.id}.`);
+      if (l && (!Array.isArray(l.words) || !l.words.length))
+        throw new Error(`Missing word timings: ${s.id}/${o.id}.`);
+      const c = l?.words ?? o.text.trim().split(/\s+/).map((g, $, p) => ({ text: g, offsetMs: m * $ / p.length, durationMs: m / p.length }));
+      let u = -1;
+      for (const g of c) {
+        if (!y(g.text) || !Number.isFinite(g.offsetMs) || !Number.isFinite(g.durationMs) || g.offsetMs < u - 0.1 || g.durationMs < 0 || g.offsetMs + g.durationMs > m + 1)
+          throw new Error(`Invalid word timings: ${s.id}/${o.id}.`);
+        u = g.offsetMs + g.durationMs;
+      }
+      h.push({ ...l, text: o.text, id: o.id, durationMs: m, words: c, startMs: f, pauseAfterMs: o.pauseAfterMs ?? 0 }), f += m + (o.pauseAfterMs ?? 0);
+    }
+    const t = Math.ceil(Math.max(s.minDurationMs ?? 0, f + 450) * e / 1e3 - 1e-8) * 1e3 / e, d = {};
+    for (const o of s.cues ?? []) {
+      const l = h.find((c) => c.id === o.segment);
+      let m = l.startMs;
+      if (o.phrase) {
+        const c = j(l.words, o.phrase);
+        if (c.length > 1 && o.occurrence === void 0)
+          throw new Error(`Ambiguous cue '${s.id}/${o.id}'; set occurrence.`);
+        const u = c[(o.occurrence ?? 1) - 1];
+        if (u === void 0)
+          throw new Error(`Unaligned cue '${s.id}/${o.id}': ${o.phrase}.`);
+        m += l.words[u].offsetMs;
+      }
+      if (m += o.offsetMs ?? 0, m > l.startMs + l.durationMs)
+        throw new Error(`Cue '${s.id}/${o.id}' falls outside its speech segment.`);
+      d[o.id] = m;
+    }
+    a.push({ id: s.id, startMs: r, durationMs: t, segments: h, cues: d }), r += t;
+  }
+  return { version: 1, timing: n.narration.enabled ? "recorded" : "estimated", fps: e, durationMs: r, beats: a };
+}
+function O(n, i = 8) {
+  if (!Number.isInteger(i) || i < 1)
+    throw new Error("wordsPerCue must be positive.");
+  const e = (s) => {
+    const f = Math.round(s);
+    return `${String(Math.floor(f / 36e5)).padStart(2, "0")}:${String(Math.floor(f / 6e4) % 60).padStart(2, "0")}:${String(Math.floor(f / 1e3) % 60).padStart(2, "0")},${String(f % 1e3).padStart(3, "0")}`;
+  };
+  let r = 0;
+  const a = [];
+  for (const s of n.beats)
+    for (const f of s.segments)
+      for (let h = 0; h < f.words.length; h += i) {
+        const t = f.words.slice(h, h + i), d = t.at(-1);
+        a.push(`${++r}
+${e(s.startMs + f.startMs + t[0].offsetMs)} --> ${e(s.startMs + f.startMs + d.offsetMs + d.durationMs)}
+${t.map((o) => o.text).join(" ")}
+`);
+      }
+  return a.join(`
+`);
+}
+export {
+  w as STYLE_PROFILES,
+  D as assertLesson,
+  N as compileLesson,
+  O as lessonCaptions,
+  x as resolveStyle,
+  S as speechKey,
+  C 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,119 @@
+/** 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;
+    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;
+    };
+    sources: LessonSource[];
+    claims?: LessonClaim[];
+    beats: LessonBeat[];
+}
+export interface TimedWord {
+    text: string;
+    offsetMs: number;
+    durationMs: number;
+}
+export interface SpeechAsset {
+    text: 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;