Explainer videos and product demos made by your AI agent. Free and open source: a local voice (Kokoro), word timing (Whisper) and a canvas renderer turn a script into a narrated MP4.
JavaScript ai-agentsanimationcanvasclaude-codecodexexplainer-videoffmpegjavascriptkokoroproduct-demotext-to-speechvideo-generationwhisper
// The scene API. Every scene function receives a Stage `s` for one frame and
// draws the whole frame from scratch as a function of the scene time `s.t`.
// Elements take `at` (when they appear) and optional `out` (when they leave);
// the theme decides how they enter, and entering elements add sound effects.
import { clamp, lerp, ease, easeFn, rand01, noise1, hashStr, mulberry32, suggest, normWord, withAlpha, contrast, mixColor, opaque } from './util.js';
import { colorOf, tintOf, fontString } from './themes.js';
import { scalePath, quadD, polyD, pathLength, pointAt, parsePath, absolutize } from './pathdata.js';
import { layoutText, lineStartX } from './text.js';
import { clipFrame, clipURL } from './clips.js';
import { highlightLine, codeTokens, matchTokens, resolveCodeSteps, codeMorphState } from './code.js';
const DEFAULT_DUR = { draw: 0.9, write: 0.8, pop: 0.6, rise: 0.75, fade: 0.6, zoom: 0.75, drop: 0.75, grow: 1.0, none: 0.001, 'slide-left': 0.75, 'slide-right': 0.75, 'slide-up': 0.75, 'slide-down': 0.75 };
const ENTERS = ['draw', 'write', 'type', 'words', 'sync', 'pop', 'rise', 'fade', 'zoom', 'drop', 'grow', 'none', 'slide-left', 'slide-right', 'slide-up', 'slide-down'];
const EXITS = ['fade', 'pop', 'rise', 'drop', 'slide-left', 'slide-right', 'none'];
const BOLD = { display: undefined, body: 600, hand: undefined, mono: 700 };
export class SceneError extends Error {}
export class Stage {
constructor(engine, ctx, scene, t) {
this.engine = engine;
this.ctx = ctx;
this.scene = scene;
this.theme = engine.theme;
this.pen = engine.pen;
this.W = engine.W;
this.H = engine.H;
this.portrait = this.H > this.W;
// Platform formats (tiktok, reels, shorts...) keep content inside the part
// of the frame the app leaves free, so the center moves with it.
this.safe = engine.safeArea;
this.platform = Boolean(engine.config.safe);
this.cx = this.platform ? this.safe.x + this.safe.w / 2 : this.W / 2;
this.cy = this.platform ? this.safe.y + this.safe.h / 2 : this.H / 2;
// The center of the content area. With captions on it sits above the
// frame center; layout helpers center on it by default.
this._mid = { x: this.safe.x + this.safe.w / 2, y: this.safe.y + this.safe.h / 2 };
// pace > 1 makes animations shorter. Times stay real seconds of the
// scene, like s.t and the word cues, so `s.cue('word') + 0.3` keeps working.
this.pace = engine.timeline.pace || 1;
this.t = t;
this.T = scene.start + t;
this.dur = scene.dur;
this.end = scene.dur;
this.id = scene.id;
this.index = scene.index;
this.words = scene.words;
this.marks = scene.marks;
this.voice = scene.voice ? { start: scene.lead, end: scene.lead + scene.voice.dur } : { start: 0, end: 0 };
this.fps = engine.fps;
const tl = engine.timeline;
this.video = { duration: tl.duration, frames: tl.frames, fps: tl.fps, width: tl.width, height: tl.height, scenes: tl.scenes.length };
this.ease = ease;
this.lerp = lerp;
this.clamp = clamp;
this._ids = new Map();
this._kindSeq = Object.create(null);
this._suppress = 0;
this._camMoved = false;
}
// The UI kit for product demos (engine/ui.js): app cards, fields, buttons,
// a clicking cursor and serif headlines, in the colors from "brand".
get ui() {
if (!this._ui) {
if (!Stage.UI) throw new SceneError('the UI kit is not loaded');
this._ui = new Stage.UI(this);
}
return this._ui;
}
// ---------- time ----------
// Start time of the n-th time a word or phrase is spoken in this scene.
cue(word, n = 1) {
return this._cue(word, n).start;
}
cueEnd(word, n = 1) {
return this._cue(word, n).end;
}
_cue(word, n) {
const cjk = ['ja', 'zh'].includes(this.engine.config.language);
const want = (cjk ? [String(word)] : String(word).split(/\s+/)).map(normWord).filter(Boolean);
if (!want.length) throw new SceneError(`cue("${word}") is empty`);
const ws = this.words;
if (!ws.length) throw new SceneError(`cue("${word}"): scene "${this.id}" has no narration`);
const norms = ws.map((w) => normWord(w.text));
let seen = 0;
let found = null;
for (let i = 0; i + want.length <= norms.length; i++) {
let ok = true;
let end = i + want.length;
if (cjk) {
let phrase = norms[i];
while (phrase.length < want[0].length && end < norms.length) phrase += norms[end++];
ok = phrase === want[0];
} else {
for (let k = 0; k < want.length; k++) if (norms[i + k] !== want[k]) { ok = false; break; }
}
if (ok && ++seen === n && !found) found = { start: ws[i].start, end: ws[end - 1].end };
}
if (found) {
// A word spoken more than once silently means its first time; tell the check.
if (seen > 1 && n === 1 && this.engine.cueNotes) this.engine.cueNotes.push({ scene: this.id, word: String(word), count: seen });
return found;
}
const count = seen ? ` (it is spoken ${seen} time${seen > 1 ? 's' : ''})` : '';
const hint = suggest(want[0], [...new Set(norms)], 6).join(', ');
throw new SceneError(`cue("${word}"${n > 1 ? `, ${n}` : ''}) is not in the narration of scene "${this.id}"${count}. Close words: ${hint}`);
}
mark(name) {
if (!(name in this.marks)) {
const names = Object.keys(this.marks);
throw new SceneError(`mark("${name}") is not in scene "${this.id}". ${names.length ? 'Marks: ' + names.join(', ') : 'Add [#' + name + '] to the narration in script.md.'}`);
}
return this.marks[name];
}
// Accepts seconds, "#mark" or a spoken word/phrase.
time(v) {
if (typeof v === 'number') return v;
if (typeof v === 'string') return v.startsWith('#') ? this.mark(v.slice(1)) : this.cue(v);
if (v === undefined || v === null) return 0;
throw new SceneError(`a time must be seconds, a spoken word or "#mark", not ${JSON.stringify(v)}`);
}
// 0..1 progress of an animation that starts at `at` and lasts `dur`.
p(at, dur = 0.6, easing = 'inOut') {
const a = this.time(at);
return easeFn(easing)(clamp((this.t - a) / (dur / this.pace)));
}
since(at) {
return this.t - this.time(at);
}
between(a, b) {
return this.t >= this.time(a) && this.t < this.time(b);
}
rand(i = 0, seed = 0) {
return rand01(i, hashStr(this.id) + seed);
}
noise(x, seed = 0) {
return noise1(x, hashStr(this.id) + seed);
}
// Smooth idle drift, handy to keep a still element alive.
wiggle(amount = 6, speed = 0.6, seed = 0) {
const k = this.T * speed;
return { x: noise1(k, seed * 13 + 1) * amount, y: noise1(k, seed * 13 + 7) * amount };
}
color(name) {
return colorOf(this.theme, name);
}
tint(name) {
return tintOf(this.theme, name);
}
// ---------- layout ----------
row(n, o = {}) {
const width = o.width ?? this._w(0.72);
const x = o.x ?? this.cx;
if (n <= 1) return [x];
return Array.from({ length: n }, (_, i) => x - width / 2 + (width * i) / (n - 1));
}
col(n, o = {}) {
const height = o.height ?? (this.platform ? this.safe.h * 0.7 : Math.min(this.H * 0.56, this.safe.h * 0.8));
const y = o.y ?? this._mid.y;
if (n <= 1) return [y];
return Array.from({ length: n }, (_, i) => y - height / 2 + (height * i) / (n - 1));
}
grid(cols, rows, o = {}) {
const w = o.w ?? this.safe.w;
const h = o.h ?? this.safe.h;
const x0 = (o.x ?? this._mid.x) - w / 2;
const y0 = (o.y ?? this._mid.y) - h / 2;
const gap = o.gap ?? 24;
const cw = (w - gap * (cols - 1)) / cols;
const ch = (h - gap * (rows - 1)) / rows;
const cells = [];
for (let r = 0; r < rows; r++) for (let c = 0; c < cols; c++) cells.push({ x: x0 + c * (cw + gap) + cw / 2, y: y0 + r * (ch + gap) + ch / 2, w: cw, h: ch });
return cells;
}
// Geometry of an element registered with `id`, in scene coordinates.
get(id) {
const r = this._ids.get(id);
if (!r) throw new SceneError(`no element with id "${id}" has been drawn yet in scene "${this.id}". Draw it before referring to it.`);
return this._fromDesign(r);
}
// ---------- internals ----------
_seed(kind, o, label) {
if (o.seed !== undefined) return o.seed;
const n = (this._kindSeq[kind] = (this._kindSeq[kind] || 0) + 1);
return hashStr(`${this.id}:${o.id ?? `${kind}#${n}:${label ?? ''}`}`) % 100000 + 1;
}
_check(o, kind) {
if (o.enter && !ENTERS.includes(o.enter)) throw new SceneError(`${kind}: enter "${o.enter}" is not one of ${ENTERS.join(', ')}`);
if (o.exit && !EXITS.includes(o.exit)) throw new SceneError(`${kind}: exit "${o.exit}" is not one of ${EXITS.join(', ')}`);
}
_life(o, kind, extra = {}) {
this._check(o, kind);
const enter = o.enter ?? extra.enter ?? this.theme.enter[kind] ?? this.theme.enter.shape ?? 'fade';
const at = this.time(o.at ?? 0);
const out = o.out === undefined ? Infinity : this.time(o.out);
const base = o.dur ?? extra.dur ?? DEFAULT_DUR[enter] ?? 0.6;
const dur = extra.real ? base : base / this.pace;
this._record(kind, at, dur, o, extra);
if (this.engine.layoutLog && this._pendingBox) {
// The element's own scale and rotation, and parts drawn beside it
// (an icon's label), count for the camera.
let box = this._pendingBox;
const sc = o.scale ?? 1;
const rad = ((o.rotate ?? 0) * Math.PI) / 180;
if (sc !== 1 || rad) box = { ...box, w: (Math.abs(box.w * Math.cos(rad)) + Math.abs(box.h * Math.sin(rad))) * sc, h: (Math.abs(box.w * Math.sin(rad)) + Math.abs(box.h * Math.cos(rad))) * sc };
// _pendingExtra is already measured with the element's transform.
if (this._pendingExtra) box = unionBox(box, this._pendingExtra);
this._attach(kind, at, out, box, this._pendingInfo);
this._pendingBox = null;
this._pendingExtra = null;
this._pendingInfo = null;
}
if (this._suppress > 0) return null;
if (this.t < at) return null;
let q = 0;
if (this.t >= out) {
q = clamp((this.t - out) / ((o.outDur ?? 0.45) / this.pace));
if (q >= 1 || o.exit === 'none') return null;
}
const p = clamp((this.t - at) / dur);
if ((p < 1 && enter !== 'none') || (q > 0 && q < 1)) this.engine.moving = true;
return { p, q, at, dur, enter, exit: o.exit ?? 'fade', local: this.t - at };
}
_record(kind, at, dur, o, extra = {}) {
const rec = this.engine.recorder;
// Negative times mean "already on screen when the scene starts": no sound.
if (!rec || at < 0) return;
let sfx = o.sfx === undefined ? (extra.sfx === undefined ? this.theme.sfx[kind] : extra.sfx) : o.sfx;
if (this.engine.sfxMode === 'minimal' && o.sfx === undefined) sfx = null;
rec.push({ kind, at, dur, sfx: sfx || null, gain: o.sfxGain ?? extra.gain ?? 1, pitch: extra.pitch, sustain: extra.sustain, key: `${kind}|${Math.round(at * 1000)}|${o.id ?? extra.label ?? ''}|${extra.pitch ?? ''}` });
}
// Entrances move on a spring: they go a little past their place and settle
// back. They fade in quickly.
// `lift` is 1 while an element is arriving and 0 once it has landed;
// shadows use it to rise and settle.
_enterTransform(life) {
const p = life.p;
const E = ease.out(p);
const S = ease.spring(p);
const A = ease.out(clamp(p * 1.8));
let a = 1;
let s = 1;
let dx = 0;
let dy = 0;
let lift = 0;
switch (life.enter) {
case 'fade': a = E; s = lerp(0.975, 1, S); break;
case 'pop': s = lerp(0.6, 1, S); a = clamp(p * 3); lift = 1 - E; break;
case 'rise': dy = (1 - S) * 44; s = lerp(0.965, 1, S); a = A; lift = 1 - E; break;
case 'drop': dy = -(1 - S) * 60; a = clamp(p * 2.5); lift = 1 - E; break;
case 'zoom': s = lerp(1.3, 1, S); a = A; break;
case 'slide-left': dx = (1 - S) * 170; a = A; break;
case 'slide-right': dx = -(1 - S) * 170; a = A; break;
case 'slide-up': dy = (1 - S) * 170; a = A; break;
case 'slide-down': dy = -(1 - S) * 170; a = A; break;
default: break;
}
if (life.q > 0) {
const Q = ease.in(life.q);
switch (life.exit) {
case 'pop': s *= 1 - 0.45 * Q; a *= 1 - Q; break;
case 'rise': dy -= Q * 40; s *= 1 - 0.03 * Q; a *= 1 - Q; break;
case 'drop': dy += Q * 60; a *= 1 - Q; break;
case 'slide-left': dx -= Q * 170; a *= 1 - Q; break;
case 'slide-right': dx += Q * 170; a *= 1 - Q; break;
default: s *= 1 - 0.03 * Q; a *= 1 - Q;
}
}
return { a, s, dx, dy, lift };
}
// The look's shadow (or `fallback`), raised while the element drawn last
// is still arriving.
_shadow(tr = this._lastTr, fallback = null) {
const sh = this.theme.shadow || fallback;
if (!sh || !tr || !tr.lift) return sh;
const k = tr.lift;
return { ...sh, blur: sh.blur * (1 + 1.4 * k), y: (sh.y || 0) * (1 + 2 * k) };
}
_push(x, y, life, o) {
const ctx = this.ctx;
ctx.save();
const tr = this._enterTransform(life);
let fx = 0;
let fy = 0;
if (o.float) {
const w = this.wiggle(o.float, 0.5, hashStr(String(o.id ?? x + ':' + y)) % 97);
fx = w.x;
fy = w.y;
}
ctx.translate(x + tr.dx + fx, y + tr.dy + fy);
if (o.rotate) ctx.rotate((o.rotate * Math.PI) / 180);
const sc = (o.scale ?? 1) * tr.s;
if (sc !== 1) ctx.scale(sc, sc);
ctx.globalAlpha *= tr.a * (o.opacity ?? 1);
this._lastTr = tr;
return tr;
}
_drawProgress(life) {
if (life.enter !== 'draw') return { stroke: 1, fill: 1, text: 1 };
const p = life.p;
return { stroke: ease.inOut(clamp(p / 0.78)), fill: clamp((p - 0.42) / 0.58), text: clamp((p - 0.35) / 0.45) };
}
// Current transform relative to the render scale: local -> design pixels.
_matrix() {
const m = this.ctx.getTransform();
const s = this.engine.scale;
return new DOMMatrix([m.a / s, m.b / s, m.c / s, m.d / s, m.e / s, m.f / s]);
}
_register(id, x, y, w, h, shape = 'rect') {
const m = this._matrix();
const pts = [[x - w / 2, y - h / 2], [x + w / 2, y - h / 2], [x + w / 2, y + h / 2], [x - w / 2, y + h / 2]].map(([px, py]) => m.transformPoint(new DOMPoint(px, py)));
const xs = pts.map((p) => p.x);
const ys = pts.map((p) => p.y);
const box = { x: (Math.min(...xs) + Math.max(...xs)) / 2, y: (Math.min(...ys) + Math.max(...ys)) / 2, w: Math.max(...xs) - Math.min(...xs), h: Math.max(...ys) - Math.min(...ys), shape };
if (id !== undefined && id !== null) this._ids.set(String(id), box);
// While the camera is planned, the next _life call gives this box its
// timing.
if (this.engine.layoutLog) this._pendingBox = box;
return box;
}
// Records an element's place and timing for the automatic camera. x, y is
// the center in local coordinates.
_logLayout(kind, at, out, x, y, w, h) {
if (!this.engine.layoutLog) return;
this._attach(kind, at, out, this._designBox(x, y, w, h));
}
// A box inside an element drawn at (ax, ay), in scene coordinates, with
// the element's own scale and rotation, as _push draws it.
_elementBox(o, ax, ay, x, y, w, h) {
const sc = o.scale ?? 1;
const rad = ((o.rotate ?? 0) * Math.PI) / 180;
const m = this._matrix().translate(ax, ay).rotate((rad * 180) / Math.PI).scale(sc, sc);
const pts = [[x - w / 2, y - h / 2], [x + w / 2, y - h / 2], [x + w / 2, y + h / 2], [x - w / 2, y + h / 2]].map(([px, py]) => m.transformPoint(new DOMPoint(px - ax, py - ay)));
const xs = pts.map((p) => p.x);
const ys = pts.map((p) => p.y);
return { x: (Math.min(...xs) + Math.max(...xs)) / 2, y: (Math.min(...ys) + Math.max(...ys)) / 2, w: Math.max(...xs) - Math.min(...xs), h: Math.max(...ys) - Math.min(...ys) };
}
// The box around text drawn beside an element, like a chart's labels, for
// the camera: where the letters land, as the browser measures them. Each
// entry: { text, x, y, font, align, base } with canvas textAlign and
// textBaseline values.
_textExtent(entries) {
let x0 = Infinity;
let y0 = Infinity;
let x1 = -Infinity;
let y1 = -Infinity;
const ctx = this.ctx;
ctx.save();
for (const e of entries) {
if (!e.text) continue;
ctx.font = e.font;
ctx.textAlign = e.align ?? 'center';
ctx.textBaseline = e.base ?? 'middle';
const m = ctx.measureText(e.text);
x0 = Math.min(x0, e.x - m.actualBoundingBoxLeft - 2);
x1 = Math.max(x1, e.x + m.actualBoundingBoxRight + 2);
y0 = Math.min(y0, e.y - m.actualBoundingBoxAscent - 2);
y1 = Math.max(y1, e.y + m.actualBoundingBoxDescent + 2);
}
ctx.restore();
return x1 > x0 ? this._designBox((x0 + x1) / 2, (y0 + y1) / 2, x1 - x0, y1 - y0) : null;
}
_designBox(x, y, w, h) {
const m = this._matrix();
const pts = [[x - w / 2, y - h / 2], [x + w / 2, y - h / 2], [x + w / 2, y + h / 2], [x - w / 2, y + h / 2]].map(([px, py]) => m.transformPoint(new DOMPoint(px, py)));
const xs = pts.map((p) => p.x);
const ys = pts.map((p) => p.y);
return { x: (Math.min(...xs) + Math.max(...xs)) / 2, y: (Math.min(...ys) + Math.max(...ys)) / 2, w: Math.max(...xs) - Math.min(...xs), h: Math.max(...ys) - Math.min(...ys) };
}
// An element inside groups is only on screen while every group is.
_attach(kind, at, out, box, extra = null) {
for (const g of this._spans || []) {
at = Math.max(at, g.at);
out = Math.min(out, g.out);
}
if (out > at) this.engine.layoutLog.push({ kind, at, out, box, ...extra });
}
_fromDesign(box) {
const inv = this._matrix().inverse();
const c = inv.transformPoint(new DOMPoint(box.x, box.y));
const sx = Math.hypot(inv.a, inv.b);
const w = box.w * sx;
const h = box.h * sx;
return geom(c.x, c.y, w, h, box.shape);
}
_point(v) {
if (typeof v === 'string') return this.get(v);
if (Array.isArray(v)) return { x: v[0], y: v[1], w: 0, h: 0 };
if (v && typeof v.x === 'number') return { x: v.x, y: v.y, w: v.w || 0, h: v.h || 0, shape: v.shape };
throw new SceneError(`expected [x, y], {x, y} or an element id, got ${JSON.stringify(v)}`);
}
// Point on the edge of box `b` in the direction of `toward`, pushed out by gap.
_edge(b, toward, gap) {
const dx = toward.x - b.x;
const dy = toward.y - b.y;
if (!b.w && !b.h) {
const L = Math.hypot(dx, dy) || 1;
return { x: b.x + (dx / L) * gap, y: b.y + (dy / L) * gap };
}
const hw = b.w / 2 + gap;
const hh = b.h / 2 + gap;
if (b.shape === 'ellipse') {
const ang = Math.atan2(dy, dx);
return { x: b.x + Math.cos(ang) * hw, y: b.y + Math.sin(ang) * hh };
}
const k = Math.min(Math.abs(dx) > 1e-6 ? hw / Math.abs(dx) : Infinity, Math.abs(dy) > 1e-6 ? hh / Math.abs(dy) : Infinity);
return { x: b.x + dx * k, y: b.y + dy * k };
}
_logText(entry) {
const log = this.engine.textLog;
if (!log) return;
const m = this._matrix();
const pts = [[entry.x0, entry.y0], [entry.x1, entry.y0], [entry.x1, entry.y1], [entry.x0, entry.y1]].map(([px, py]) => m.transformPoint(new DOMPoint(px, py)));
const scale = Math.hypot(m.a, m.b);
log.push({
scene: this.id,
t: this.t,
text: entry.text,
x0: Math.min(...pts.map((p) => p.x)),
y0: Math.min(...pts.map((p) => p.y)),
x1: Math.max(...pts.map((p) => p.x)),
y1: Math.max(...pts.map((p) => p.y)),
size: entry.size * scale,
alpha: this.ctx.globalAlpha,
fg: entry.fg,
bg: entry.bg,
block: !!entry.block,
ui: entry.ui || 0,
zoomed: !!entry.zoomed,
});
}
// Layout problems found while drawing, reported by `check`.
_overflow(message) {
const log = this.engine.textLog;
if (log) log.push({ scene: this.id, t: this.t, problem: message });
}
_autoTextColor(fill, fallback) {
if (!fill || fill === 'none') return fallback;
fill = opaque(fill, this.theme.bg);
const light = this.theme.dark ? this.theme.ink : '#ffffff';
const dark = this.theme.dark ? '#0b1020' : this.theme.ink;
return contrast(fill, fallback) >= 3 ? fallback : contrast(fill, light) > contrast(fill, dark) ? light : dark;
}
// ---------- background and sound ----------
bg(color) {
const ctx = this.ctx;
ctx.save();
ctx.setTransform(this.engine.scale, 0, 0, this.engine.scale, 0, 0);
ctx.fillStyle = colorOf(this.theme, color, 'bg');
ctx.fillRect(0, 0, this.W, this.H);
ctx.restore();
}
sfx(name, at, o = {}) {
if (!this.engine.sfxNames.includes(name)) throw new SceneError(`sfx "${name}" does not exist. Sounds: ${this.engine.sfxNames.join(', ')}`);
const t = at === undefined ? this.t : this.time(at);
const rec = this.engine.recorder;
if (rec) rec.push({ kind: 'sfx', at: t, dur: o.dur ?? 0, sfx: name, gain: o.gain ?? 1, pitch: o.pitch, explicit: true, key: `sfx|${Math.round(t * 1000)}|${name}|${o.pitch ?? ''}` });
}
// ---------- camera and groups ----------
// keys: [{ at, x, y, zoom, dur }]. Call before drawing anything else.
camera(keys, o = {}) {
// A scene that moves its own camera gets no automatic camera.
if (this.engine.planning) this.engine.manualCamera = true;
const list = [{ at: 0, x: this.cx, y: this.cy, zoom: 1, dur: 0 }, ...keys.map((k) => ({ x: this.cx, y: this.cy, zoom: 1, dur: 1.1, ...k, at: this.time(k.at ?? 0) }))].sort((a, b) => a.at - b.at);
let cur = { ...list[0] };
if (o.shake) this.engine.moving = true;
for (let i = 1; i < list.length; i++) {
const k = list[i];
if (this.t < k.at) break;
const prev = cur;
const raw = (this.t - k.at) / Math.max(0.001, k.dur / this.pace);
if (raw > 0 && raw < 1) this.engine.moving = true;
const p = easeFn(k.ease ?? 'inOut')(clamp(raw));
cur = { x: lerp(prev.x, k.x, p), y: lerp(prev.y, k.y, p), zoom: lerp(prev.zoom, k.zoom, p), rotate: lerp(prev.rotate || 0, k.rotate || 0, p) };
}
const ctx = this.ctx;
this._camMoved = cur.zoom !== 1 || cur.x !== this.cx || cur.y !== this.cy || Boolean(cur.rotate) || Boolean(o.shake);
ctx.translate(this.cx, this.cy);
if (cur.rotate) ctx.rotate((cur.rotate * Math.PI) / 180);
ctx.scale(cur.zoom, cur.zoom);
ctx.translate(-cur.x, -cur.y);
if (o.shake) {
const w = this.wiggle(o.shake, 3);
ctx.translate(w.x, w.y);
}
return cur;
}
// Draws `fn` inside a moved/scaled/rotated group that can enter and leave
// as one piece. Times inside stay scene times.
group(o, fn) {
if (typeof o === 'function') [o, fn] = [{}, o];
const life = this._life(o, 'group', { enter: o.enter ?? 'none', sfx: null, dur: o.dur });
const planning = Boolean(this.engine.layoutLog);
if (planning) (this._spans ??= []).push({ at: this.time(o.at ?? 0), out: o.out === undefined ? Infinity : this.time(o.out) });
try {
if (!life || planning) {
if (!life) this._suppress++;
// The camera measures what a group holds where it rests, whether it
// is hidden, arriving or leaving at that moment.
if (planning) {
this.ctx.save();
this.ctx.translate(o.x ?? 0, o.y ?? 0);
if (o.rotate) this.ctx.rotate((o.rotate * Math.PI) / 180);
if ((o.scale ?? 1) !== 1) this.ctx.scale(o.scale, o.scale);
}
try { fn(this); } finally {
if (!life) this._suppress--;
if (planning) this.ctx.restore();
}
return;
}
this._push(o.x ?? 0, o.y ?? 0, life, o);
try { fn(this); } finally { this.ctx.restore(); }
} finally {
if (planning) this._spans.pop();
}
}
// While the camera is planned, runs a custom drawing once on a context
// that records how far its paths, shapes, text and images reach. It runs at
// its own place, scale and rotation, without its entrance or exit.
_measureDrawing(o, fn, life, random) {
const ctx = this.ctx;
const at = this.time(o.at ?? 0);
const out = o.out === undefined ? Infinity : this.time(o.out);
ctx.save();
ctx.translate(o.x ?? 0, o.y ?? 0);
if (o.rotate) ctx.rotate((o.rotate * Math.PI) / 180);
if (o.scale) ctx.scale(o.scale, o.scale);
const rec = boundsRecorder(ctx, this.engine.scale);
const saved = Math.random;
Math.random = random;
try {
fn(rec.proxy, life ? { ...life, p: 1, q: 0 } : { p: 1, q: 0, at, dur: 0.001, enter: 'none', exit: 'fade', local: Math.max(0, this.t - at) });
} catch {
// drawn for real later, where its errors are reported
} finally {
Math.random = saved;
ctx.restore();
}
const box = rec.box();
if (box) this._attach('custom', at, out, box);
}
// Points the camera at an element or a region from `at` until `out`. It
// draws nothing. target: an id drawn earlier, { x, y, w, h } (center and
// size) or [x, y, w, h].
focus(target, o = {}) {
const b = typeof target === 'string' ? this.get(target) : Array.isArray(target) ? { x: target[0], y: target[1], w: target[2], h: target[3] } : target;
if (!b || !Number.isFinite(b.x) || !Number.isFinite(b.y) || !(b.w > 0) || !(b.h > 0)) throw new SceneError('focus needs an element id, { x, y, w, h } or [x, y, w, h]');
if (this.engine.layoutLog) this._attach('focus', this.time(o.at ?? 0), o.out === undefined ? Infinity : this.time(o.out), this._designBox(b.x, b.y, b.w, b.h), { explicit: true });
}
// Custom drawing with the same timing rules: fn(ctx, life) where life.p is
// the 0..1 entrance progress and ctx is already moved to x, y.
// Math.random inside fn has its own sequence for each drawing, so its
// numbers do not depend on which other drawings are on screen.
draw(o, fn) {
if (typeof o === 'function') [o, fn] = [{}, o];
const life = this._life(o, 'custom', { enter: o.enter ?? 'none', sfx: o.sfx ?? null });
const random = mulberry32(this._seed('random', o));
if (this.engine.layoutLog) return this._measureDrawing(o, fn, life, random);
if (!life) return;
this._push(o.x ?? 0, o.y ?? 0, life, o);
const saved = Math.random;
Math.random = random;
try { fn(this.ctx, life); } finally {
Math.random = saved;
this.ctx.restore();
}
}
// ---------- text ----------
text(str, o = {}) {
return this._text(str, o, o.kind || 'text');
}
// A width of `f` times the frame, never wider than the platform safe area.
_w(f) {
return this.platform ? Math.min(this.W * f, this.safe.w) : this.W * f;
}
// A height `f` of the way down the frame (or down the safe area).
_y(f) {
return this.platform ? this.safe.y + this.safe.h * f : this.H * f;
}
title(str, o = {}) {
return this._text(str, { font: 'display', size: 104, y: this._y(0.44), maxWidth: this._w(0.82), lineHeight: 1.12, ...o }, 'title');
}
subtitle(str, o = {}) {
return this._text(str, { font: 'body', size: 46, color: 'muted', y: this._y(0.6), maxWidth: this._w(0.7), ...o }, 'text');
}
note(str, o = {}) {
return this._text(str, { size: 32, color: 'muted', ...o }, 'text');
}
_text(str, o, kind) {
const th = this.theme;
const ctx = this.ctx;
const role = o.font ?? 'body';
if (!th.fonts[role]) throw new SceneError(`font "${role}" is not one of display, body, hand, mono`);
const size = o.size ?? 48;
const weight = o.weight ?? (o.bold ? BOLD[role] ?? 700 : undefined);
const font = fontString(th, role, size, weight);
const align = o.align ?? 'center';
// Large text gets slightly tighter letter spacing in looks that set a
// tracking value.
const tracking = size >= 56 ? (th.fonts[role].tracking ?? 0) * size : 0;
// save() and restore() put the spacing back. Reading ctx.letterSpacing
// back is not reliable in Chrome.
ctx.save();
ctx.letterSpacing = `${tracking}px`;
let lay;
try {
lay = layoutText(ctx, { str: String(str), font, size, maxWidth: o.maxWidth ?? o.width ?? this._w(0.8), lineHeight: o.lineHeight ?? 1.24 });
} finally {
ctx.restore();
}
const x = o.x ?? this.cx;
const y = o.y ?? this.cy;
const left = align === 'left' ? x : align === 'right' ? x - lay.width : x - lay.width / 2;
const valign = o.valign ?? 'middle';
const top = valign === 'top' ? y : valign === 'bottom' ? y - lay.height : y - lay.height / 2;
const bx = left + lay.width / 2;
const by = top + lay.height / 2;
const pad = o.bg ? (o.padding ?? size * 0.45) : 0;
const g = geom(bx, by, lay.width + pad * 2, lay.height + pad * 2);
this._register(o.id, g.x, g.y, g.w, g.h);
const plain = String(str).replace(/\*/g, '');
const enter = o.enter ?? th.enter[kind] ?? 'fade';
let dur = o.dur;
if (dur === undefined) {
if (enter === 'write') dur = clamp(0.35 + plain.length * 0.028, 0.5, 1.8);
else if (enter === 'type') dur = plain.length / (o.cps ?? 28);
else if (enter === 'words') dur = Math.max(0.4, lay.count * 0.18);
}
let times = null;
// 'sync' follows the real word times; 'words' is spread over `dur`, which
// the pace shortens like every other animation.
if (enter === 'sync' || enter === 'words') times = this._wordTimes(lay, enter, o, enter === 'words' ? dur / this.pace : dur);
const life = this._life({ ...o, enter }, kind, { dur: enter === 'sync' ? Math.max(0.3, (times[times.length - 1] ?? 0) - this.time(o.at ?? 0) + 0.3) : dur, real: enter === 'sync', label: plain.slice(0, 40) });
if (!life) return g;
this._push(bx, by, life, o);
const color = colorOf(th, o.color, 'ink');
const accent = colorOf(th, o.mark ?? 'accent');
if (o.bg) {
const bgc = colorOf(th, o.bg === true ? 'surface' : o.bg);
this.pen.draw(ctx, { kind: 'rect', w: g.w, h: g.h, r: o.radius ?? Math.min(th.radius, g.h / 2) }, { fill: bgc, stroke: o.border ? colorOf(th, o.border) : 'none', width: 2, shadow: this._shadow(), seed: this._seed('textbg', o, plain), rough: false }, { stroke: 1, fill: 1 });
}
ctx.font = font;
ctx.textBaseline = 'alphabetic';
ctx.textAlign = 'left';
ctx.letterSpacing = `${tracking}px`;
const ox = -lay.width / 2;
const oy = -lay.height / 2;
const glow = th.stroke.glow && o.glow !== false && kind === 'title' ? th.stroke.glow : 0;
const drawWord = (w, lx, ly, alpha = 1, dy = 0) => {
ctx.fillStyle = w.accent ? accent : color;
if (glow && w.accent) {
ctx.shadowColor = withAlpha(accent, 0.55);
ctx.shadowBlur = glow;
}
const prev = ctx.globalAlpha;
if (alpha < 1) ctx.globalAlpha = prev * alpha;
ctx.fillText(w.text, lx, ly + dy);
ctx.globalAlpha = prev;
ctx.shadowBlur = 0;
};
if (life.enter === 'write') {
const widths = lay.lines.map((l) => l.width);
const total = widths.reduce((a, b) => a + b, 0) || 1;
let reveal = ease.inOutSine(life.p) * total;
lay.lines.forEach((line) => {
const lx0 = ox + lineStartX(line, lay.width, align);
const show = Math.min(line.width, reveal);
reveal -= line.width;
if (show <= 0) return;
ctx.save();
ctx.beginPath();
ctx.rect(lx0 - size, oy + line.y - lay.ascent - size * 0.3, show + size, lay.lineHeight + size * 0.5);
ctx.clip();
for (const w of line.words) drawWord(w, lx0 + w.x, oy + line.y);
ctx.restore();
});
} else if (life.enter === 'type') {
let chars = Math.floor(plain.length * clamp(life.local / Math.max(0.01, life.dur)) + 1e-6);
lay.lines.forEach((line) => {
const lx0 = ox + lineStartX(line, lay.width, align);
for (const w of line.words) {
if (chars <= 0) return;
const part = w.text.slice(0, chars);
drawWord({ ...w, text: part }, lx0 + w.x, oy + line.y);
chars -= w.text.length + 1;
}
});
} else if (times) {
lay.lines.forEach((line) => {
const lx0 = ox + lineStartX(line, lay.width, align);
for (const w of line.words) {
const k = clamp((this.t - times[w.index]) / (0.22 / this.pace));
if (k <= 0) continue;
drawWord(w, lx0 + w.x, oy + line.y, ease.out(k), (1 - ease.out(k)) * 14);
}
});
} else {
const a = life.enter === 'draw' ? this._drawProgress(life).text : 1;
lay.lines.forEach((line) => {
const lx0 = ox + lineStartX(line, lay.width, align);
for (const w of line.words) drawWord(w, lx0 + w.x, oy + line.y, a);
});
}
this._logText({ text: plain, x0: ox, y0: oy, x1: -ox, y1: -oy, size, fg: color, bg: o.bg ? colorOf(th, o.bg === true ? 'surface' : o.bg) : null });
ctx.restore();
return g;
}
_wordTimes(lay, enter, o, dur) {
const at = this.time(o.at ?? 0);
const flat = [];
lay.lines.forEach((l) => l.words.forEach((w) => flat.push(w)));
flat.sort((a, b) => a.index - b.index);
if (enter === 'words') return flat.map((w, i) => at + (i * dur) / Math.max(1, flat.length));
const norms = this.words.map((w) => normWord(w.text));
let ptr = 0;
while (ptr < this.words.length && this.words[ptr].start < at - 0.05) ptr++;
let last = at;
return flat.map((w) => {
const n = normWord(w.text);
for (let j = ptr; j < norms.length; j++) {
if (norms[j] === n) {
ptr = j + 1;
last = Math.max(last, this.words[j].start);
return last;
}
}
last += 0.12;
return last;
});
}
math(tex, o = {}) {
if (typeof tex !== 'string') throw new SceneError('math: use a fixed TeX string');
if (o.display !== undefined && typeof o.display !== 'boolean') throw new SceneError('math: display must be true or false');
if (o.align !== undefined && !['center', 'left'].includes(o.align)) throw new SceneError('math: align must be center or left');
const data = this.engine.mathData(tex, o.display ?? true, this.id, this.t);
if (data?.error) throw new SceneError(`math "${tex}": ${data.error}`);
const size = o.size ?? 72;
const unit = size / (data?.unitsPerEm ?? 1000);
const [vx, vy, vw, vh] = data?.viewBox ?? [0, -1000, 0, 1000];
const w = vw * unit;
const h = vh * unit;
const x = (o.x ?? this.cx) + (o.align === 'left' ? w / 2 : 0);
const y = o.y ?? this.cy;
this._register(o.id, x, y, w, h);
const g = geom(x, y, w, h);
const th = this.theme;
const life = this._life(o, 'text', { enter: th.enter.shape === 'draw' ? 'draw' : th.enter.text, label: tex });
if (!life || !data) return g;
const ctx = this.ctx;
const color = colorOf(th, o.color, 'ink');
this._push(x, y, life, o);
const draw = life.enter === 'draw' || life.enter === 'write';
const stroke = draw ? ease.inOut(clamp(life.p / 0.78)) : 1;
const fill = draw ? clamp((life.p - 0.78) / 0.22) : 1;
for (const d of data.paths) {
const path = scalePath(d, unit, -w / 2 - vx * unit, -h / 2 - vy * unit);
this.pen.draw(ctx, { kind: 'path', d: path }, { stroke: draw && life.p < 1 ? color : 'none', width: Math.max(0.7, size / 72), fill: color, rough: false }, { stroke, fill });
}
this._logText({ text: tex, x0: -w / 2, y0: -h / 2, x1: w / 2, y1: h / 2, size, fg: color, bg: null });
ctx.restore();
return g;
}
// ---------- shapes ----------
box(label, o = {}) {
if (label && typeof label === 'object') [o, label] = [label, label.label];
const th = this.theme;
const ctx = this.ctx;
const size = o.size ?? 44;
const role = o.font ?? 'body';
const font = fontString(th, role, size, o.weight ?? BOLD[role]);
const pad = o.padding ?? size * 0.62;
const maxW = o.w ? o.w - pad * 2 : o.maxWidth ?? 560;
const lay = label !== undefined && label !== null && label !== '' ? layoutText(ctx, { str: String(label), font, size, maxWidth: maxW, lineHeight: 1.15 }) : null;
const iconSize = o.icon ? o.iconSize ?? size * 1.55 : 0;
const gapIL = lay && o.icon ? size * 0.35 : 0;
const contentH = (lay ? lay.height : 0) + iconSize + gapIL;
const w = o.w ?? Math.max(o.minW ?? 0, (lay ? lay.width : 0) + pad * 2, iconSize + pad * 2);
const h = o.h ?? Math.max(o.minH ?? 0, contentH + pad * 1.4);
const x = o.x ?? this.cx;
const y = o.y ?? this.cy;
const shape = o.shape ?? 'rect';
this._register(o.id, x, y, w, h, shape === 'ellipse' || shape === 'circle' ? 'ellipse' : 'rect');
// A shape without words has no detail for the camera to move in on.
if (this.engine.layoutLog && !lay) this._pendingInfo = { bare: true };
const g = geom(x, y, w, h);
const plain = lay ? String(label).replace(/\*/g, '') : '';
const life = this._life(o, 'shape', { label: plain.slice(0, 40) || o.icon });
if (!life) return g;
this._push(x, y, life, o);
const prog = this._drawProgress(life);
const stroke = colorOf(th, o.stroke ?? o.color, 'ink');
const fill = o.fill !== undefined ? colorOf(th, o.fill) : o.color ? tintOf(th, o.color) : th.surface;
const spec = shape === 'ellipse' || shape === 'circle' ? { kind: 'ellipse', w, h } : { kind: 'rect', w, h, r: o.radius ?? th.radius };
this.pen.draw(ctx, spec, { stroke: o.border === false ? 'none' : stroke, width: o.width ?? th.stroke.width, fill, fillStyle: o.fillStyle, dashed: o.dashed, seed: this._seed('box', o, plain), shadow: this._shadow(), glow: o.glow ?? (th.stroke.glow && o.color ? th.stroke.glow : 0) }, prog);
const textColor = o.textColor ? colorOf(th, o.textColor) : this._autoTextColor(fill, th.ink);
const top = -contentH / 2;
const prevA = ctx.globalAlpha;
ctx.globalAlpha = prevA * prog.text;
if (o.icon) this._iconAt(o.icon, 0, top + iconSize / 2, iconSize, colorOf(th, o.iconColor ?? o.color, 'ink'), 1, this._seed('boxicon', o, o.icon), o.iconWeight);
if (lay) {
ctx.font = font;
ctx.textBaseline = 'alphabetic';
ctx.textAlign = 'left';
const ty = top + iconSize + gapIL;
const accent = colorOf(th, o.mark ?? 'accent');
for (const line of lay.lines) {
const lx = -lay.width / 2 + (lay.width - line.width) / 2;
for (const wd of line.words) {
ctx.fillStyle = wd.accent ? accent : textColor;
ctx.fillText(wd.text, lx + wd.x, ty + line.y);
}
}
this._logText({ text: plain, x0: -lay.width / 2, y0: ty, x1: lay.width / 2, y1: ty + lay.height, size, fg: textColor, bg: fill });
}
ctx.globalAlpha = prevA;
ctx.restore();
return g;
}
circle(o = {}) {
const r = o.r ?? 80;
return this.box(o.label, { ...o, shape: 'ellipse', w: r * 2, h: r * 2, padding: 0 });
}
line(points, o = {}) {
const th = this.theme;
const pts = points.map((p) => this._point(p)).map((p) => [p.x, p.y]);
const life = this._life(o, 'line', { enter: o.enter ?? 'draw' });
if (this.engine.layoutLog) {
const xs = pts.map((p) => p[0]);
const ys = pts.map((p) => p[1]);
// A line thick enough to read as a bar is a shape the camera keeps whole.
const thick = (o.width ?? th.stroke.width) >= 10;
this._logLayout(thick ? 'shape' : 'line', this.time(o.at ?? 0), o.out === undefined ? Infinity : this.time(o.out), (Math.min(...xs) + Math.max(...xs)) / 2, (Math.min(...ys) + Math.max(...ys)) / 2, Math.max(...xs) - Math.min(...xs), Math.max(...ys) - Math.min(...ys));
}
if (!life) return;
this.ctx.save();
const tr = this._enterTransform(life.enter === 'draw' ? { ...life, enter: 'none' } : life);
this.ctx.globalAlpha *= tr.a * (o.opacity ?? 1);
const prog = life.enter === 'draw' ? { stroke: ease.inOut(life.p), fill: 1 } : { stroke: 1, fill: 1 };
this.pen.draw(this.ctx, { kind: 'poly', points: pts, close: !!o.close }, { stroke: colorOf(th, o.color, 'ink'), width: o.width ?? th.stroke.width, fill: o.fill ? colorOf(th, o.fill) : undefined, dashed: o.dashed, seed: this._seed('line', o), single: true, glow: o.glow ?? 0 }, prog);
this.ctx.restore();
}
path(d, o = {}) {
const th = this.theme;
const life = this._life(o, 'line', { enter: o.enter ?? 'draw' });
if (this.engine.layoutLog) {
const pts = [];
for (const { c, v } of absolutize(parsePath(d))) {
if (c === 'A') pts.push([v[5], v[6]], [v[5] - v[0], v[6] - v[1]], [v[5] + v[0], v[6] + v[1]]);
else for (let i = 0; i + 1 < v.length; i += 2) pts.push([v[i], v[i + 1]]);
}
if (pts.length) {
const xs = pts.map((q) => q[0] + (o.x ?? 0));
const ys = pts.map((q) => q[1] + (o.y ?? 0));
// A closed or filled path is a shape; an open one is a line.
this._logLayout(/z/i.test(d) || o.fill ? 'shape' : 'line', this.time(o.at ?? 0), o.out === undefined ? Infinity : this.time(o.out), (Math.min(...xs) + Math.max(...xs)) / 2, (Math.min(...ys) + Math.max(...ys)) / 2, Math.max(...xs) - Math.min(...xs), Math.max(...ys) - Math.min(...ys));
}
}
if (!life) return;
this._push(o.x ?? 0, o.y ?? 0, life.enter === 'draw' ? { ...life, enter: 'none' } : life, o);
const prog = this._drawProgress(life);
this.pen.draw(this.ctx, { kind: 'path', d }, { stroke: colorOf(th, o.color, 'ink'), width: o.width ?? th.stroke.width, fill: o.fill ? colorOf(th, o.fill) : undefined, fillStyle: o.fillStyle, dashed: o.dashed, seed: this._seed('path', o), single: o.single ?? false, glow: o.glow ?? 0 }, prog);
this.ctx.restore();
}
// from/to: [x, y], {x, y} or an element id (the arrow then stops at its edge).
arrow(from, to, o = {}) {
const th = this.theme;
const A = this._point(from);
const B = this._point(to);
const gap = o.gap ?? 14;
const a = typeof from === 'string' ? this._edge(A, B, gap) : A;
const b = typeof to === 'string' ? this._edge(B, A, gap) : B;
if (typeof from === 'string' && typeof to !== 'string') Object.assign(a, this._edge(A, b, gap));
const bend = o.bend ?? 0;
const dx = b.x - a.x;
const dy = b.y - a.y;
const c = { x: (a.x + b.x) / 2 - dy * bend * 0.5, y: (a.y + b.y) / 2 + dx * bend * 0.5 };
const d = bend ? quadD([a.x, a.y], [c.x, c.y], [b.x, b.y]) : polyD([[a.x, a.y], [b.x, b.y]]);
const life = this._life(o, 'arrow', { enter: o.enter ?? 'draw', dur: o.dur ?? 0.7 });
if (this.engine.layoutLog) {
const xs = [a.x, b.x, c.x];
const ys = [a.y, b.y, c.y];
const at = this.time(o.at ?? 0);
const out = o.out === undefined ? Infinity : this.time(o.out);
this._logLayout('arrow', at, out, (Math.min(...xs) + Math.max(...xs)) / 2, (Math.min(...ys) + Math.max(...ys)) / 2, Math.max(...xs) - Math.min(...xs), Math.max(...ys) - Math.min(...ys));
// The line may run off the edge of a close-up, but its label is text,
// so the camera keeps it whole. A label outside the frame is never
// seen, so the camera leaves it alone.
if (o.label) {
const label = this._arrowLabel(o, d, a, b, bend);
const box = this._textExtent([{ text: String(o.label), x: label.x, y: label.y, font: label.font }]);
const seen = box.x + box.w / 2 > 0 && box.x - box.w / 2 < this.W && box.y + box.h / 2 > 0 && box.y - box.h / 2 < this.H;
if (seen) this._attach('label', at, out, box);
}
}
const result = { from: a, to: b, control: c };
if (!life) return result;
const ctx = this.ctx;
ctx.save();
const tr = this._enterTransform(life.enter === 'draw' ? { ...life, enter: 'none' } : life);
ctx.globalAlpha *= tr.a * (o.opacity ?? 1);
const color = colorOf(th, o.color, 'ink');
const width = o.width ?? th.stroke.width;
const prog = life.enter === 'draw' ? ease.inOut(life.p) : 1;
const seed = this._seed('arrow', o);
this.pen.draw(ctx, { kind: 'path', d }, { stroke: color, width, dashed: o.dashed, seed, single: true, glow: o.glow ?? 0 }, { stroke: prog, fill: 1 });
const head = o.head ?? 'end';
const hs = o.headSize ?? width * 3.2 + 12;
const L = pathLength(d);
const drawHead = (dist, dir) => {
const tip = pointAt(d, dist);
const back = pointAt(d, Math.max(0, Math.min(L, dist - dir * Math.min(12, L / 3))));
const ang = Math.atan2(tip.y - back.y, tip.x - back.x);
const s1 = [tip.x - hs * Math.cos(ang - 0.5), tip.y - hs * Math.sin(ang - 0.5)];
const s2 = [tip.x - hs * Math.cos(ang + 0.5), tip.y - hs * Math.sin(ang + 0.5)];
if (th.stroke.rough) {
this.pen.draw(ctx, { kind: 'poly', points: [s1, [tip.x, tip.y], s2] }, { stroke: color, width, seed: seed + 7, single: true, roughness: 0.6 }, { stroke: 1, fill: 1 });
} else {
this.pen.draw(ctx, { kind: 'poly', points: [s1, [tip.x, tip.y], s2], close: true }, { stroke: color, width: width * 0.6, fill: color, seed, glow: o.glow ?? 0 }, { stroke: 1, fill: 1 });
}
};
if (L > 1 && prog > 0.02) {
if (head === 'end' || head === 'both') drawHead(L * prog, 1);
if ((head === 'start' || head === 'both') && prog > 0.2) drawHead(0.001, -1);
}
if (o.label) {
const la = clamp((life.p - 0.55) / 0.35);
if (la > 0) {
const { x: lx, y: ly, w, size: ls, font } = this._arrowLabel(o, d, a, b, bend);
ctx.save();
ctx.globalAlpha *= la;
ctx.font = font;
ctx.fillStyle = colorOf(th, o.labelColor ?? o.color, 'muted');
ctx.textAlign = 'center';
ctx.textBaseline = 'middle';
ctx.fillText(String(o.label), lx, ly);
this._logText({ text: String(o.label), x0: lx - w / 2, y0: ly - ls / 2, x1: lx + w / 2, y1: ly + ls / 2, size: ls, fg: ctx.fillStyle, bg: null });
ctx.restore();
}
}
ctx.restore();
return result;
}
// Where an arrow's label goes: on the outer side of a curve, or above a
// straight arrow. x, y is the label's center.
_arrowLabel(o, d, a, b, bend) {
const mid = pointAt(d, pathLength(d) / 2);
let nx;
let ny;
const bx = mid.x - (a.x + b.x) / 2;
const by = mid.y - (a.y + b.y) / 2;
if (bend && Math.hypot(bx, by) > 1) {
nx = bx / Math.hypot(bx, by);
ny = by / Math.hypot(bx, by);
} else {
const dx = b.x - a.x;
const dy = b.y - a.y;
const len = Math.hypot(dx, dy) || 1;
nx = -dy / len;
ny = dx / len;
if (ny > 0 || (ny === 0 && nx > 0)) {
nx = -nx;
ny = -ny;
}
}
const off = o.labelOffset ?? 34;
const size = o.labelSize ?? 34;
const font = fontString(this.theme, o.labelFont ?? 'hand', size);
this.ctx.save();
this.ctx.font = font;
const w = this.ctx.measureText(String(o.label)).width;
this.ctx.restore();
// Further out when the label runs along the arrow's direction.
const extra = Math.abs(nx) * w * 0.5;
return { x: mid.x + nx * (off + extra), y: mid.y + ny * off, w, size, font };
}
connect(a, b, o = {}) {
return this.arrow(a, b, o);
}
// ---------- icons and images ----------
_iconPaths(name, size) {
const key = name + '@' + size;
let v = this.engine.iconCache.get(key);
if (!v) {
const src = this.engine.icons[name];
if (!src) throw new SceneError(`icon "${name}" does not exist. Try: ${iconSuggest(name, this.engine.icons, this.engine.iconTags).join(', ')}. Search with: explainroo icons <word>`);
const s = size / 24;
v = src.map((d) => scalePath(d, s, -size / 2, -size / 2));
this.engine.iconCache.set(key, v);
}
return v;
}
_iconAt(name, x, y, size, color, stroke = 1, seed = 1, weight) {
const paths = this._iconPaths(name, size);
const th = this.theme;
const ctx = this.ctx;
ctx.save();
ctx.translate(x, y);
const w = ((weight ?? 2) * size) / 24;
for (let i = 0; i < paths.length; i++) {
this.pen.draw(ctx, { kind: 'path', d: paths[i] }, { stroke: color, width: w, seed: seed + i, single: true, roughness: (th.stroke.roughness ?? 0) * 0.45 }, { stroke, fill: 1 });
}
ctx.restore();
}
icon(name, o = {}) {
const th = this.theme;
const size = o.size ?? 120;
const x = o.x ?? this.cx;
const y = o.y ?? this.cy;
const bgSize = o.bg ? size * (o.bgScale ?? 1.7) : size;
this._register(o.id, x, y, bgSize, bgSize, o.bg === 'square' ? 'rect' : o.bg ? 'ellipse' : 'rect');
// Nor has an icon without a label.
if (this.engine.layoutLog && !o.label) this._pendingInfo = { bare: true };
if (this.engine.layoutLog && o.label) {
// The label belongs to the icon for the camera, not for arrows.
const ls = o.labelSize ?? 36;
this.ctx.save();
this.ctx.font = fontString(th, o.labelFont ?? 'body', ls, BOLD[o.labelFont ?? 'body']);
const lw = this.ctx.measureText(String(o.label)).width;
this.ctx.restore();
this._pendingExtra = this._elementBox(o, x, y, x, y + bgSize / 2 + ls * 0.45 + ls / 2, lw, ls * 1.1);
}
this._iconPaths(name, size);
const life = this._life(o, 'icon', { label: name });
const g = geom(x, y, bgSize, bgSize);
if (!life) return g;
this._push(x, y, life, o);
const prog = this._drawProgress(life);
const color = colorOf(th, o.color, 'ink');
if (o.bg) {
const bgColor = o.bg === true || o.bg === 'circle' || o.bg === 'square' ? tintOf(th, o.color ?? th.accent) : colorOf(th, o.bg);
const spec = o.bg === 'square' ? { kind: 'rect', w: bgSize, h: bgSize, r: th.radius } : { kind: 'ellipse', w: bgSize, h: bgSize };
this.pen.draw(this.ctx, spec, { stroke: th.stroke.rough ? color : 'none', width: th.stroke.width * 0.8, fill: bgColor, seed: this._seed('iconbg', o, name), shadow: this._shadow() }, { stroke: prog.stroke, fill: prog.fill });
}
this._iconAt(name, 0, 0, size, color, prog.stroke, this._seed('icon', o, name), o.weight);
if (o.label) {
const ls = o.labelSize ?? 36;
const ctx = this.ctx;
ctx.save();
ctx.globalAlpha *= life.enter === 'draw' ? prog.text : 1;
ctx.font = fontString(th, o.labelFont ?? 'body', ls, BOLD[o.labelFont ?? 'body']);
ctx.fillStyle = colorOf(th, o.labelColor, 'ink');
ctx.textAlign = 'center';
ctx.textBaseline = 'top';
const ly = bgSize / 2 + ls * 0.45;
ctx.fillText(String(o.label), 0, ly);
const w = ctx.measureText(String(o.label)).width;
this._logText({ text: String(o.label), x0: -w / 2, y0: ly, x1: w / 2, y1: ly + ls, size: ls, fg: ctx.fillStyle, bg: null });
ctx.restore();
}
this.ctx.restore();
return g;
}
image(src, o = {}) {
const img = this.engine.image(src);
return this._picture(src, img, img.naturalWidth, img.naturalHeight, o);
}
clip(src, o = {}) {
const clip = this.engine.clip(src);
const from = o.from ?? 0;
const speed = o.speed ?? 1;
const volume = o.volume ?? 0;
for (const [name, value, lo, hi] of [['from', from, 0, Infinity], ['speed', speed, 0.25, 4], ['volume', volume, 0, 1]]) {
if (!Number.isFinite(value) || value < lo || value > hi) throw new SceneError(`clip ${name} must be ${name === 'from' ? 'a non-negative number' : `from ${lo} to ${hi}`}`);
}
const at = this.time(o.at ?? 0);
const out = o.out === undefined ? this.dur : Math.min(this.dur, this.time(o.out));
const end = o.loop ? out : Math.min(out, at + Math.max(0, clip.duration - from) / speed);
const n = this._clipSeq = (this._clipSeq || 0) + 1;
if (this.engine.recorder) this.engine.recorder.push({ kind: 'clip', key: `clip|${at}|${o.id ?? n}|${src}`, at, end, out, from, speed, loop: !!o.loop, volume, hasAudio: clip.hasAudio, duration: clip.duration, src: clip.src, url: clipURL('audio', clip.src) });
const frame = clipFrame(clip, this.t, { at, from, speed, loop: o.loop });
return this._picture(src, () => frame === null ? null : this.engine.clipImage(clip, frame), clip.width, clip.height, o);
}
_picture(src, source, naturalWidth, naturalHeight, o) {
const th = this.theme;
const ratio = naturalWidth / naturalHeight;
let w = o.w;
let h = o.h;
if (!w && !h) {
w = Math.min(this._w(0.6), naturalWidth);
h = w / ratio;
} else if (!h) h = w / ratio;
else if (!w) w = h * ratio;
const frame = o.frame ?? 'none';
if (!['none', 'browser', 'window', 'phone', 'card'].includes(frame)) throw new SceneError(`image frame must be none, browser, window, phone or card, not "${frame}"`);
const bar = frame === 'browser' || frame === 'window' ? Math.max(34, h * 0.075) : 0;
const cardPad = frame === 'card' ? Math.round(Math.min(w, h) * 0.035) + 8 : 0;
const fw = frame === 'phone' ? w + 28 : w + cardPad * 2;
const fh = frame === 'phone' ? h + 28 : h + bar + cardPad * 2;
const x = o.x ?? this.cx;
const y = o.y ?? this.cy;
this._register(o.id, x, y, fw, fh);
const life = this._life(o, 'image', { label: src });
const g = geom(x, y, fw, fh);
if (!life) return g;
this._push(x, y, life, o);
const ctx = this.ctx;
const r = o.radius ?? (frame === 'phone' ? 46 : th.radius);
if (frame === 'phone') {
this.pen.draw(ctx, { kind: 'rect', w: fw, h: fh, r: r + 10 }, { fill: '#111418', stroke: 'none', width: 0, shadow: this._shadow(undefined, { color: 'rgba(0,0,0,0.25)', blur: 30, y: 12 }), rough: false }, { stroke: 1, fill: 1 });
} else if (bar) {
this.pen.draw(ctx, { kind: 'rect', w: fw, h: fh, r }, { fill: th.dark ? '#1b2233' : '#ffffff', stroke: th.dark ? '#2b3550' : 'rgba(0,0,0,0.08)', width: 2, shadow: this._shadow(undefined, { color: 'rgba(0,0,0,0.18)', blur: 26, y: 10 }), rough: false }, { stroke: 1, fill: 1 });
const dots = ['#ff5f57', '#febc2e', '#28c840'];
dots.forEach((c, i) => {
ctx.fillStyle = c;
ctx.beginPath();
ctx.arc(-fw / 2 + bar * 0.55 + i * bar * 0.45, -fh / 2 + bar / 2, bar * 0.13, 0, Math.PI * 2);
ctx.fill();
});
if (frame === 'browser' && o.url) {
const pw = fw * 0.5;
this.pen.draw(ctx, { kind: 'rect', w: pw, h: bar * 0.58, r: bar * 0.29 }, { fill: th.dark ? '#111727' : '#f1f3f7', stroke: 'none', width: 0, rough: false }, { stroke: 1, fill: 1 });
ctx.save();
ctx.translate(0, -fh / 2 + bar / 2);
ctx.font = fontString(th, 'body', bar * 0.34);
ctx.fillStyle = th.dark ? '#aab4c8' : '#5b6474';
ctx.textAlign = 'center';
ctx.textBaseline = 'middle';
ctx.fillText(o.url, 0, 1);
ctx.restore();
}
} else if (frame === 'card') {
this.pen.draw(ctx, { kind: 'rect', w: fw, h: fh, r: r + cardPad / 2 }, { fill: th.dark ? th.surface : '#ffffff', stroke: th.stroke.rough ? th.ink : 'none', width: th.stroke.width * 0.8, shadow: this._shadow(undefined, { color: 'rgba(0,0,0,0.16)', blur: 24, y: 8 }), seed: this._seed('card', o, src), fillStyle: 'solid' }, { stroke: 1, fill: 1 });
} else if (o.shadow !== false && th.shadow) {
this.pen.draw(ctx, { kind: 'rect', w, h, r }, { fill: th.surface, stroke: 'none', width: 0, shadow: this._shadow(), rough: false }, { stroke: 1, fill: 1 });
}
const iy = frame === 'phone' ? 0 : bar / 2;
ctx.save();
const clip = new Path2D();
const ir = frame === 'phone' ? r : bar ? 0 : r;
clip.roundRect(-w / 2, iy - h / 2, w, h, bar ? [0, 0, r, r] : ir);
ctx.clip(clip);
const kb = o.kenburns ? 1 + 0.08 * clamp(this.t / Math.max(1, this.dur)) : 1;
const fit = o.fit ?? 'cover';
let dw = w;
let dh = h;
if (fit === 'cover') {
if (w / h > ratio) dh = w / ratio;
else dw = h * ratio;
} else if (fit === 'contain') {
if (w / h > ratio) dw = h * ratio;
else dh = w / ratio;
}
dw *= kb;
dh *= kb;
const img = typeof source === 'function' ? source() : source;
if (img) ctx.drawImage(img, -dw / 2, iy - dh / 2, dw, dh);
else {
ctx.fillStyle = th.surface;
ctx.fillRect(-w / 2, iy - h / 2, w, h);
}
ctx.restore();
if (o.border) {
this.pen.draw(ctx, { kind: 'rect', w, h, r }, { stroke: colorOf(th, o.border === true ? 'ink' : o.border), width: th.stroke.width, seed: this._seed('imgborder', o, src) }, { stroke: 1, fill: 1 });
}
ctx.restore();
return g;
}
// ---------- emphasis ----------
// type: underline | circle | box | highlight | strike | cross | bracket
annotate(target, o = {}) {
const th = this.theme;
const b = this._point(target);
const pad = o.padding ?? 14;
const type = o.type ?? 'underline';
const color = colorOf(th, o.color ?? 'accent');
const w = b.w + pad * 2;
const h = b.h + pad * 2;
const life = this._life(o, 'annotate', { enter: 'draw', dur: o.dur ?? (type === 'circle' ? 0.8 : 0.6), label: type });
if (!life) return;
const ctx = this.ctx;
ctx.save();
ctx.translate(b.x, b.y);
const prog = ease.inOut(life.p);
const qa = life.q > 0 ? 1 - ease.in(life.q) : 1;
ctx.globalAlpha *= qa;
const width = o.width ?? th.stroke.width * 1.1;
const seed = this._seed('annotate', o, type);
const style = { stroke: color, width, seed, single: type !== 'circle', roughness: (th.stroke.roughness ?? 1) * 0.9 };
switch (type) {
case 'underline': {
const yy = h / 2 - pad * 0.4;
this.pen.draw(ctx, { kind: 'path', d: `M${-w / 2} ${yy}Q0 ${yy + 8} ${w / 2} ${yy - 4}` }, style, { stroke: prog, fill: 1 });
break;
}
case 'circle': {
this.pen.draw(ctx, { kind: 'ellipse', w: w * 1.12, h: h * 1.25 }, { ...style, single: false }, { stroke: prog, fill: 1 });
break;
}
case 'box':
this.pen.draw(ctx, { kind: 'rect', w, h, r: th.stroke.rough ? 0 : th.radius }, style, { stroke: prog, fill: 1 });
break;
case 'strike':
this.pen.draw(ctx, { kind: 'poly', points: [[-w / 2, 4], [w / 2, -4]] }, style, { stroke: prog, fill: 1 });
break;
case 'cross':
this.pen.draw(ctx, { kind: 'poly', points: [[-w / 2, -h / 2], [w / 2, h / 2]] }, style, { stroke: clamp(prog * 2), fill: 1 });
this.pen.draw(ctx, { kind: 'poly', points: [[w / 2, -h / 2], [-w / 2, h / 2]] }, { ...style, seed: seed + 3 }, { stroke: clamp(prog * 2 - 1), fill: 1 });
break;
case 'bracket':
this.pen.draw(ctx, { kind: 'poly', points: [[-w / 2 + 16, -h / 2], [-w / 2, -h / 2], [-w / 2, h / 2], [-w / 2 + 16, h / 2]] }, style, { stroke: prog, fill: 1 });
break;
case 'highlight': {
ctx.globalCompositeOperation = th.dark ? 'screen' : 'multiply';
ctx.fillStyle = withAlpha(color, th.dark ? 0.3 : 0.38);
const hw = w * prog;
ctx.beginPath();
ctx.roundRect(-w / 2, -h / 2 + h * 0.08, hw, h * 0.84, 6);
ctx.fill();
break;
}
default:
throw new SceneError(`annotate type "${type}" is not one of underline, circle, box, highlight, strike, cross, bracket`);
}
ctx.restore();
}
// ---------- lists, numbers, charts ----------
list(items, o = {}) {
const th = this.theme;
const ctx = this.ctx;
const size = o.size ?? 50;
const x = o.x ?? (this.platform ? this.safe.x + this.safe.w * 0.06 : this.W * 0.2);
let y = o.y ?? this._y(0.3);
const width = o.width ?? this._w(0.62);
const gap = o.gap ?? size * 0.55;
const bullet = o.bullet ?? 'dot';
const indent = size * 1.25;
const base = this.time(o.at ?? 0);
const stagger = (o.stagger ?? 0.7) / this.pace;
const role = o.font ?? 'body';
const font = fontString(th, role, size, o.weight);
const out = [];
items.forEach((raw, i) => {
const it = typeof raw === 'string' ? { text: raw } : raw;
const at = it.at !== undefined ? this.time(it.at) : Array.isArray(o.at) ? this.time(o.at[i]) : base + i * stagger;
const lay = layoutText(ctx, { str: it.text, font, size, maxWidth: width - indent, lineHeight: 1.2 });
const cy = y + lay.height / 2;
const color = colorOf(th, it.color ?? o.color, 'ink');
const bcolor = colorOf(th, it.bulletColor ?? o.bulletColor ?? 'accent');
this._record('list', at, 0.4, { sfx: o.sfx }, { pitch: i, label: it.text.slice(0, 30) });
const bx = x + size * 0.45;
const by = y + lay.ascent - size * 0.32;
const life = this._life({ at, out: it.out ?? o.out, sfx: null }, 'list', { enter: 'pop', dur: 0.4 });
if (life) {
this._push(bx, by, life, {});
this._bullet(it.icon ?? bullet, i, size, bcolor);
ctx.restore();
}
out.push(this._text(it.text, { x: x + indent, y, valign: 'top', align: 'left', size, font: role, weight: o.weight, color: it.color ?? o.color, maxWidth: width - indent, lineHeight: 1.2, at: at + 0.12, out: it.out ?? o.out, enter: o.enter ?? th.enter.list, sfx: null, id: o.id ? `${o.id}.${i}` : undefined }, 'text'));
y += lay.height + gap;
});
return out;
}
_bullet(kind, i, size, color) {
const ctx = this.ctx;
const th = this.theme;
const r = size * 0.16;
switch (kind) {
case 'dot':
this.pen.draw(ctx, { kind: 'ellipse', w: r * 2.2, h: r * 2.2 }, { fill: color, stroke: color, width: 2, seed: 11 + i, fillStyle: 'solid' }, { stroke: 1, fill: 1 });
break;
case 'dash':
this.pen.draw(ctx, { kind: 'poly', points: [[-r * 1.6, 0], [r * 1.6, 0]] }, { stroke: color, width: th.stroke.width, seed: 11 + i, single: true }, { stroke: 1, fill: 1 });
break;
case 'number': {
ctx.font = fontString(th, 'display', size * 0.62);
ctx.fillStyle = color;
ctx.textAlign = 'center';
ctx.textBaseline = 'middle';
ctx.fillText(String(i + 1), 0, 2);
this.pen.draw(ctx, { kind: 'ellipse', w: size * 0.95, h: size * 0.95 }, { stroke: color, width: th.stroke.width * 0.8, seed: 21 + i }, { stroke: 1, fill: 1 });
break;
}
case 'check':
this._iconAt('check', 0, 0, size * 0.8, color, 1, 31 + i, 3);
break;
case 'arrow':
this._iconAt('arrow-right', 0, 0, size * 0.8, color, 1, 41 + i, 2.6);
break;
default:
this._iconAt(kind, 0, 0, size * 0.85, color, 1, 51 + i, 2.2);
}
}
number(value, o = {}) {
const th = this.theme;
const from = o.from ?? 0;
const dur = (o.dur ?? 1.4) / this.pace;
const at = this.time(o.at ?? 0);
const decimals = o.decimals ?? (Number.isInteger(value) && Number.isInteger(from) ? 0 : 1);
const steps = Math.min(18, Math.max(4, Math.round(dur * 10)));
for (let k = 0; k < steps; k++) {
const tau = 1 - Math.cbrt(1 - k / steps);
this._record('number', at + tau * dur, 0.05, { sfx: o.sfx, sfxGain: 0.8 - (0.4 * k) / steps }, { label: `${value}#${k}` });
}
const cp = ease.out(clamp((this.t - at) / dur));
const v = lerp(from, value, cp);
const fmt = (n) => {
const s = Math.abs(n).toFixed(decimals);
const [int, dec] = s.split('.');
const grouped = o.group === false ? int : int.replace(/\B(?=(\d{3})+(?!\d))/g, o.separator ?? ',');
return (n < 0 ? '-' : '') + grouped + (dec ? '.' + dec : '');
};
const str = `${o.prefix ?? ''}${fmt(v)}${o.suffix ?? ''}`;
return this._text(str, { font: 'display', size: 150, color: o.color ?? 'accent', ...o, at, sfx: null, enter: o.enter ?? th.enter.number ?? 'fade', dur: o.enterDur ?? 0.4, id: o.id }, 'number');
}
bars(data, o = {}) {
const th = this.theme;
const ctx = this.ctx;
const items = data.map((d, i) => (typeof d === 'number' ? { value: d } : d)).map((d, i) => ({ ...d, color: d.color ?? palette(th, i) }));
const x = o.x ?? this.cx;
const y = o.y ?? this.cy;
const w = o.w ?? this._w(0.56);
const h = o.h ?? (this.platform ? this.safe.h * 0.46 : this.H * 0.46);
const max = o.max ?? Math.max(...items.map((d) => d.value)) * 1.12;
const n = items.length;
const slot = w / n;
const bw = slot * (1 - (o.gapRatio ?? 0.36));
const base = y + h / 2;
const at = this.time(o.at ?? 0);
const stagger = (o.stagger ?? 0.22) / this.pace;
this._register(o.id, x, y, w, h);
if (this.engine.layoutLog) {
// The labels under the bars and the values on top count for the
// camera, not for arrows.
const format = o.format ?? ((v) => (Number.isInteger(v) ? String(Math.round(v)) : v.toFixed(1)));
const ls = o.labelSize ?? 34;
const vs = o.valueSize ?? 40;
const text = this._textExtent(items.flatMap((d, i) => {
const cx = x - w / 2 + slot * i + slot / 2;
const labels = d.label !== undefined ? [{ text: String(d.label), x: cx, y: base + 16, font: fontString(th, 'body', ls), base: 'top' }] : [];
const values = o.values !== false ? [{ text: `${o.prefix ?? ''}${format(d.value)}${o.suffix ?? ''}`, x: cx, y: base - (d.value / max) * h - 12, font: fontString(th, 'display', vs), base: 'bottom' }] : [];
return [...labels, ...values];
}));
// The axis reaches 20 pixels past the bars on each side.
const axis = this._designBox(x, y, w + 40 + th.stroke.width * 2, h + th.stroke.width * 2);
this._pendingExtra = text ? unionBox(axis, text) : axis;
}
// Each bar can have its own `at` (seconds, a spoken word or "#marker").
const barAt = items.map((d, i) => (d.at !== undefined ? this.time(d.at) : at + 0.3 / this.pace + i * stagger));
items.forEach((d, i) => this._record('chart', barAt[i], 0.8, { sfx: o.sfx }, { label: `bar${i}` }));
const axisLife = this._life({ at, out: o.out, sfx: null }, 'chart', { enter: 'draw', dur: 0.5 });
if (!axisLife) return geom(x, y, w, h);
const alpha = axisLife.q > 0 ? 1 - ease.in(axisLife.q) : 1;
ctx.save();
ctx.globalAlpha *= alpha;
this.pen.draw(ctx, { kind: 'poly', points: [[x - w / 2 - 20, base], [x + w / 2 + 20, base]] }, { stroke: colorOf(th, 'ink'), width: th.stroke.width, seed: this._seed('axis', o), single: true }, { stroke: ease.inOut(axisLife.p), fill: 1 });
items.forEach((d, i) => {
const t0 = barAt[i];
const g = ease.out(clamp((this.t - t0) / ((o.growDur ?? 0.9) / this.pace)));
const cx = x - w / 2 + slot * i + slot / 2;
const bh = (d.value / max) * h;
if (g > 0) {
ctx.save();
ctx.beginPath();
ctx.rect(cx - bw / 2 - 20, base - bh * g - 20, bw + 40, bh * g + 20);
ctx.clip();
ctx.translate(cx, base - bh / 2);
const color = colorOf(th, d.color);
this.pen.draw(ctx, { kind: 'rect', w: bw, h: bh, r: th.stroke.rough ? 0 : Math.min(12, bw / 4) }, { stroke: th.stroke.rough ? color : 'none', width: th.stroke.width, fill: th.dark && !th.stroke.rough ? color : th.stroke.rough ? color : color, fillStyle: o.fillStyle ?? (th.stroke.rough ? 'hachure' : 'solid'), seed: this._seed('bar', o, i) + i, glow: th.stroke.glow ? th.stroke.glow * 0.6 : 0 }, { stroke: 1, fill: 1 });
ctx.restore();
if (o.values !== false) {
ctx.save();
ctx.globalAlpha *= g;
const vs = o.valueSize ?? 40;
ctx.font = fontString(th, 'display', vs);
ctx.fillStyle = colorOf(th, 'ink');
ctx.textAlign = 'center';
ctx.textBaseline = 'bottom';
const val = (o.format ?? ((v) => (Number.isInteger(v) ? String(Math.round(v)) : v.toFixed(1))))(d.value * g);
const txt = `${o.prefix ?? ''}${val}${o.suffix ?? ''}`;
ctx.fillText(txt, cx, base - bh * g - 12);
ctx.restore();
}
}
if (d.label !== undefined) {
const ls = o.labelSize ?? 34;
ctx.save();
ctx.globalAlpha *= clamp((this.t - at) / (0.4 / this.pace));
ctx.font = fontString(th, 'body', ls);
ctx.fillStyle = colorOf(th, 'muted');
ctx.textAlign = 'center';
ctx.textBaseline = 'top';
ctx.fillText(String(d.label), cx, base + 16);
const lw = ctx.measureText(String(d.label)).width;
this._logText({ text: String(d.label), x0: cx - lw / 2, y0: base + 16, x1: cx + lw / 2, y1: base + 16 + ls, size: ls, fg: ctx.fillStyle, bg: null });
ctx.restore();
}
});
ctx.restore();
return geom(x, y, w, h);
}
lineChart(values, o = {}) {
const th = this.theme;
const ctx = this.ctx;
const x = o.x ?? this.cx;
const y = o.y ?? this.cy;
const w = o.w ?? this._w(0.6);
const h = o.h ?? (this.platform ? this.safe.h * 0.44 : this.H * 0.44);
const lo = o.min ?? Math.min(0, ...values);
const hi = o.max ?? Math.max(...values) * 1.1;
const pts = values.map((v, i) => [x - w / 2 + (w * i) / Math.max(1, values.length - 1), y + h / 2 - ((v - lo) / (hi - lo || 1)) * h]);
this._register(o.id, x, y, w, h);
if (this.engine.layoutLog) {
// The ends of the axes, the dots and the labels under the axis count
// for the camera, not for arrows.
const pad = 12 + th.stroke.width * 1.3;
const around = this._designBox(x, y, w + pad * 2, h + pad * 2);
const ls = o.labelSize ?? 30;
const text = o.labels && this._textExtent(o.labels.slice(0, pts.length).map((l, i) => ({ text: String(l), x: pts[i][0], y: y + h / 2 + 14, font: fontString(th, 'body', ls), base: 'top' })));
this._pendingExtra = text ? unionBox(around, text) : around;
}
const life = this._life(o, 'chart', { enter: 'draw', dur: o.dur ?? 1.6 });
if (!life) return geom(x, y, w, h);
ctx.save();
ctx.globalAlpha *= life.q > 0 ? 1 - ease.in(life.q) : 1;
const color = colorOf(th, o.color ?? 'accent');
const p = ease.inOut(life.p);
this.pen.draw(ctx, { kind: 'poly', points: [[x - w / 2, y - h / 2 - 10], [x - w / 2, y + h / 2], [x + w / 2 + 10, y + h / 2]] }, { stroke: colorOf(th, 'muted'), width: th.stroke.width * 0.7, seed: this._seed('axes', o), single: true }, { stroke: clamp(p * 3), fill: 1 });
if (o.area !== false) {
ctx.save();
ctx.globalAlpha *= clamp((life.p - 0.6) / 0.4) * 0.9;
ctx.beginPath();
ctx.moveTo(pts[0][0], y + h / 2);
pts.forEach((pt) => ctx.lineTo(pt[0], pt[1]));
ctx.lineTo(pts[pts.length - 1][0], y + h / 2);
ctx.closePath();
const gr = ctx.createLinearGradient(0, y - h / 2, 0, y + h / 2);
gr.addColorStop(0, withAlpha(color, 0.35));
gr.addColorStop(1, withAlpha(color, 0));
ctx.fillStyle = gr;
ctx.fill();
ctx.restore();
}
this.pen.draw(ctx, { kind: 'poly', points: pts }, { stroke: color, width: o.width ?? th.stroke.width * 1.3, seed: this._seed('series', o), single: true, glow: th.stroke.glow ?? 0 }, { stroke: p, fill: 1 });
if (o.dots !== false) {
pts.forEach((pt, i) => {
const k = clamp((p - i / Math.max(1, pts.length - 1)) * 6);
if (k <= 0) return;
ctx.save();
ctx.translate(pt[0], pt[1]);
ctx.scale(ease.outBack(k), ease.outBack(k));
this.pen.draw(ctx, { kind: 'ellipse', w: 18, h: 18 }, { fill: color, stroke: th.bg, width: 3, seed: i + 3, fillStyle: 'solid', rough: false }, { stroke: 1, fill: 1 });
ctx.restore();
});
}
if (o.labels) {
ctx.font = fontString(th, 'body', o.labelSize ?? 30);
ctx.fillStyle = colorOf(th, 'muted');
ctx.textAlign = 'center';
ctx.textBaseline = 'top';
o.labels.forEach((l, i) => {
if (i < pts.length) ctx.fillText(String(l), pts[i][0], y + h / 2 + 14);
});
}
ctx.restore();
return geom(x, y, w, h);
}
pie(data, o = {}) {
const th = this.theme;
const ctx = this.ctx;
const items = data.map((d, i) => (typeof d === 'number' ? { value: d } : d)).map((d, i) => ({ ...d, color: d.color ?? palette(th, i) }));
const x = o.x ?? this.cx;
const y = o.y ?? this.cy;
const r = o.r ?? 220;
const hole = (o.donut ?? 0) * r;
const total = items.reduce((a, d) => a + d.value, 0) || 1;
this._register(o.id, x, y, r * 2, r * 2, 'ellipse');
if (this.engine.layoutLog) {
// The outline of the slices and the labels around the pie count for
// the camera, not for arrows.
const ring = this._designBox(x, y, r * 2 + th.stroke.width * 4, r * 2 + th.stroke.width * 4);
const ls = o.labelSize ?? 32;
const lr = r + (o.labelOffset ?? 56);
let a0 = -Math.PI / 2;
const text = o.labels !== false && this._textExtent(items.map((d) => {
const full = (d.value / total) * Math.PI * 2;
const mid = a0 + full / 2;
a0 += full;
if (full <= 0.001) return {};
const text = d.label !== undefined ? `${d.label} ${Math.round((d.value / total) * 100)}%` : `${Math.round((d.value / total) * 100)}%`;
return { text, x: x + Math.cos(mid) * lr, y: y + Math.sin(mid) * lr, font: fontString(th, 'body', ls, BOLD.body), align: Math.cos(mid) > 0.2 ? 'left' : Math.cos(mid) < -0.2 ? 'right' : 'center', base: 'middle' };
}));
this._pendingExtra = text ? unionBox(ring, text) : ring;
}
const life = this._life(o, 'chart', { enter: 'grow', dur: o.dur ?? 1.2 });
if (!life) return geom(x, y, r * 2, r * 2);
ctx.save();
ctx.translate(x, y);
ctx.globalAlpha *= life.q > 0 ? 1 - ease.in(life.q) : 1;
const sweep = ease.inOut(life.p) * Math.PI * 2;
let a0 = -Math.PI / 2;
items.forEach((d, i) => {
const full = (d.value / total) * Math.PI * 2;
const a1 = a0 + Math.min(full, Math.max(0, sweep - (a0 + Math.PI / 2)));
if (a1 > a0 + 0.001) {
const color = colorOf(th, d.color);
const dd = wedgeD(r, hole, a0, a1);
this.pen.draw(ctx, { kind: 'path', d: dd }, { fill: color, stroke: th.stroke.rough ? color : th.bg, width: th.stroke.rough ? th.stroke.width : 4, fillStyle: o.fillStyle ?? (th.stroke.rough ? 'hachure' : 'solid'), seed: this._seed('slice', o, i) + i, rough: th.stroke.rough }, { stroke: 1, fill: 1 });
if (o.labels !== false && a1 - a0 >= full - 0.001) {
const mid = (a0 + a1) / 2;
const lr = r + (o.labelOffset ?? 56);
const ls = o.labelSize ?? 32;
const txt = d.label !== undefined ? `${d.label} ${Math.round((d.value / total) * 100)}%` : `${Math.round((d.value / total) * 100)}%`;
ctx.font = fontString(th, 'body', ls, BOLD.body);
ctx.fillStyle = colorOf(th, 'ink');
ctx.textAlign = Math.cos(mid) > 0.2 ? 'left' : Math.cos(mid) < -0.2 ? 'right' : 'center';
ctx.textBaseline = 'middle';
ctx.fillText(txt, Math.cos(mid) * lr, Math.sin(mid) * lr);
}
}
a0 += full;
});
ctx.restore();
return geom(x, y, r * 2, r * 2);
}
// ---------- code and terminal ----------
code(src, o = {}) {
const th = this.theme;
const ctx = this.ctx;
const C = th.code;
const size = o.size ?? 32;
const steps = Array.isArray(src) ? resolveCodeSteps(src, o, (v) => this.time(v)) : null;
if (steps) o = { ...o, at: o.at ?? steps[0].at };
const morph = steps ? codeMorphState(steps, this.t, o.morphDur ?? 0.8, this.pace) : null;
const lines = steps ? steps[morph.to].lines : String(src).replace(/\t/g, ' ').split('\n');
const firstLines = steps ? steps[0].lines : lines;
const lh = size * 1.5;
const pad = size * 0.9;
const barH = o.title === false ? 0 : size * 1.6;
const font = fontString(th, 'mono', size);
ctx.save();
ctx.font = font;
const charW = ctx.measureText('M').width;
ctx.restore();
const maxLines = steps ? Math.max(...steps.map((step) => step.lines.length)) : lines.length;
const numW = o.lineNumbers === false ? 0 : charW * (String(maxLines).length + 2);
const allLines = steps ? steps.flatMap((step) => step.lines) : lines;
const naturalW = Math.max(...allLines.map((l) => l.length)) * charW + numW + pad * 2;
const w = o.w ?? Math.min(this._w(0.86), naturalW);
const h = o.h ?? (morph ? morph.lines : lines.length) * lh + pad * 1.6 + barH;
const x = o.x ?? this.cx;
const y = o.y ?? this.cy;
this._register(o.id, x, y, w, h);
// The camera keeps the tallest step in view, not only the current one.
if (this.engine.layoutLog && steps && !o.h) this._register(undefined, x, y, w, Math.max(...steps.map((step) => step.lines.length)) * lh + pad * 1.6 + barH);
const at = this.time(o.at ?? 0);
const reveal = o.reveal ?? 'type';
const cps = (o.cps ?? 40) * this.pace;
const chars = firstLines.reduce((a, l) => a + l.length + 1, 0);
const typeDur = chars / cps;
const lineDelay = (o.lineDelay ?? 0.3) / this.pace;
const startText = at + 0.35 / this.pace;
if (reveal === 'type') this._record('code', startText, typeDur, { sfx: o.sfx }, { label: 'typing', sustain: true });
if (steps) steps.slice(1).forEach((step, i) => this._record('code', step.at, (o.morphDur ?? 0.8) / this.pace,
{ sfx: o.sfx === false || o.sfx === null ? false : undefined, sfxGain: 0.2 }, { sfx: 'whoosh', label: `morph${i + 2}` }));
const life = this._life({ ...o, sfx: null }, 'code', { dur: 0.5 });
if (this.engine.layoutLog) {
// Highlighted lines tell the camera where to look. The window is as
// tall as the step it shows, so each step has its own first line.
const focusLines = (list, from, until, rows) => {
const nums = (Array.isArray(list) ? list : list ? [list] : []).filter((n) => n >= 1 && n <= rows.length);
if (!nums.length) return;
const lineTop = y - (o.h ?? rows.length * lh + pad * 1.6 + barH) / 2 + barH + pad * 0.8;
// Whole lines across, with a little of the lines around them.
const y0 = lineTop + (Math.min(...nums) - 1) * lh - lh * 0.72;
const y1 = lineTop + Math.max(...nums) * lh + lh * 0.28;
const longest = Math.max(...rows.map((r) => r.length));
const x0 = x - w / 2 + pad;
const x1 = Math.min(x + w / 2 - pad, x0 + numW + longest * charW);
const box = this._elementBox(o, x, y, (x0 + x1) / 2, (y0 + y1) / 2, x1 - x0, y1 - y0);
this._attach('focus', from, until, box);
};
const out = o.out === undefined ? Infinity : this.time(o.out);
if (steps) steps.forEach((step, k) => focusLines(step.highlight, k ? step.at : this.time(o.highlightAt ?? at + 0.4 / this.pace), steps[k + 1]?.at ?? out, step.lines));
else focusLines(o.highlight, this.time(o.highlightAt ?? at + 0.4 / this.pace), out, lines);
}
if (!life) return geom(x, y, w, h);
this._push(x, y, life, o);
this.pen.draw(ctx, { kind: 'rect', w, h, r: Math.min(th.radius, 18) }, { fill: C.bg, stroke: th.stroke.rough ? C.border : 'none', width: th.stroke.width * 0.8, seed: this._seed('codebg', o), shadow: this._shadow(undefined, { color: 'rgba(0,0,0,0.2)', blur: 24, y: 10 }), rough: th.stroke.rough, fillStyle: 'solid' }, { stroke: 1, fill: 1 });
const left = -w / 2 + pad;
const top = -h / 2 + barH + pad * 0.8;
if (barH) {
['#ff5f57', '#febc2e', '#28c840'].forEach((c, i) => {
ctx.fillStyle = c;
ctx.beginPath();
ctx.arc(-w / 2 + pad * 0.8 + i * size * 0.8, -h / 2 + barH / 2 + 4, size * 0.2, 0, Math.PI * 2);
ctx.fill();
});
if (o.title) {
ctx.font = fontString(th, 'mono', size * 0.72);
ctx.fillStyle = C.comment;
ctx.textAlign = 'center';
ctx.textBaseline = 'middle';
ctx.fillText(String(o.title), 0, -h / 2 + barH / 2 + 4);
}
}
if (steps && morph.to) {
const drawHighlight = (step, alpha) => {
const hl = Array.isArray(step.highlight) ? step.highlight : step.highlight ? [step.highlight] : [];
ctx.save();
ctx.globalAlpha *= alpha;
ctx.fillStyle = C.highlight;
for (const n of hl) ctx.fillRect(-w / 2 + 6, top + (n - 1) * lh - lh * 0.22, w - 12, lh);
ctx.restore();
};
drawHighlight(steps[morph.from], 1 - morph.p);
drawHighlight(steps[morph.to], morph.p);
} else if (steps ? steps[0].highlight : o.highlight) {
const highlight = steps ? steps[0].highlight : o.highlight;
const hl = Array.isArray(highlight) ? highlight : [highlight];
const ha = clamp((this.t - this.time(o.highlightAt ?? at + 0.4 / this.pace)) / (0.4 / this.pace));
if (ha > 0) {
ctx.save();
ctx.globalAlpha *= ha;
ctx.fillStyle = C.highlight;
for (const n of hl) ctx.fillRect(-w / 2 + 6, top + (n - 1) * lh - lh * 0.22, w - 12, lh);
ctx.restore();
}
}
ctx.font = font;
ctx.textAlign = 'left';
ctx.textBaseline = 'top';
const room = w / 2 - pad * 0.5 - (left + numW);
(steps || [{ lines }]).forEach((step, n) => step.lines.forEach((line, i) => {
if (ctx.measureText(line).width > room) this._overflow(`code ${steps ? `step ${n + 1} ` : ''}line ${i + 1} ("${line.trim().slice(0, 40)}") is wider than its window; shorten it, lower size or raise w`);
}));
ctx.save();
ctx.beginPath();
ctx.rect(-w / 2, -h / 2, w, h);
ctx.clip();
if (steps && morph.to && morph.p < 1) {
const position = (tok, step) => ({ x: left + numW + ctx.measureText(step.lines[tok.row].slice(0, tok.column)).width, y: top + tok.row * lh });
const drawToken = (tok, pos, alpha) => {
if (alpha <= 0) return;
ctx.save();
ctx.globalAlpha *= alpha;
ctx.fillStyle = C[tok.type] ?? C.fg;
ctx.fillText(tok.text, pos.x, pos.y);
ctx.restore();
};
const before = codeTokens(steps[morph.from].lines, o.lang ?? 'js');
const after = codeTokens(lines, o.lang ?? 'js');
const pairs = matchTokens(before, after);
const keptBefore = new Set(pairs.map(([a]) => a));
const keptAfter = new Set(pairs.map(([, b]) => b));
for (const [a, b] of pairs) {
const start = position(before[a], steps[morph.from]);
const end = position(after[b], steps[morph.to]);
drawToken(after[b], { x: lerp(start.x, end.x, morph.p), y: lerp(start.y, end.y, morph.p) }, 1);
}
before.forEach((tok, i) => { if (!keptBefore.has(i)) drawToken(tok, position(tok, steps[morph.from]), morph.removed); });
after.forEach((tok, i) => { if (!keptAfter.has(i)) drawToken(tok, position(tok, steps[morph.to]), morph.added); });
if (numW) {
ctx.fillStyle = C.lineNo;
ctx.textAlign = 'right';
const oldCount = steps[morph.from].lines.length;
for (let i = 0; i < Math.max(oldCount, lines.length); i++) {
ctx.save();
ctx.globalAlpha *= i < Math.min(oldCount, lines.length) ? 1 : i < oldCount ? morph.removed : morph.added;
ctx.fillText(String(i + 1), left + numW - charW * 1.4, top + i * lh);
ctx.restore();
}
ctx.textAlign = 'left';
}
} else {
const activeReveal = morph?.to ? 'none' : reveal;
let budget = activeReveal === 'type' ? Math.floor((this.t - startText) * cps) : Infinity;
lines.forEach((line, i) => {
if (activeReveal === 'lines' && this.t < startText + i * lineDelay) return;
if (budget <= 0 && activeReveal === 'type') return;
const ly = top + i * lh;
if (numW) {
ctx.fillStyle = C.lineNo;
ctx.textAlign = 'right';
ctx.fillText(String(i + 1), left + numW - charW * 1.4, ly);
ctx.textAlign = 'left';
}
let cx = left + numW;
for (const tok of highlightLine(line, o.lang ?? 'js')) {
let txt = tok.text;
if (activeReveal === 'type') {
if (budget <= 0) break;
txt = txt.slice(0, budget);
budget -= txt.length;
}
ctx.fillStyle = C[tok.type] ?? C.fg;
ctx.fillText(txt, cx, ly);
cx += ctx.measureText(txt).width;
}
if (activeReveal === 'type') budget -= 1;
});
}
ctx.restore();
this._logText({ text: 'code', x0: -w / 2, y0: -h / 2, x1: w / 2, y1: h / 2, size, fg: C.fg, bg: C.bg, block: true });
ctx.restore();
return geom(x, y, w, h);
}
// lines: "$ command" or plain output strings, or { cmd, at } / { out, at, color }.
terminal(lines, o = {}) {
const th = this.theme;
const ctx = this.ctx;
const T = th.terminal;
const size = o.size ?? 32;
const lh = size * 1.55;
const pad = size * 0.9;
const barH = size * 1.5;
const items = lines.map((l) => (typeof l === 'string' ? (l.startsWith('$ ') ? { cmd: l.slice(2) } : { out: l }) : l));
const w = o.w ?? this._w(0.62);
const rows = items.reduce((n, it) => n + String(it.cmd ?? it.out ?? '').split('\n').length, 0);
const h = o.h ?? Math.max(rows, o.rows ?? 0) * lh + barH + pad * 1.6;
const x = o.x ?? this.cx;
const y = o.y ?? this.cy;
this._register(o.id, x, y, w, h);
const at = this.time(o.at ?? 0);
const cps = (o.cps ?? 22) * this.pace;
let clock = at + 0.5 / this.pace;
const timed = items.map((it) => {
const r = { ...it };
if (it.at !== undefined) clock = this.time(it.at);
r.start = clock;
if (it.cmd !== undefined) {
r.end = r.start + String(it.cmd).length / cps;
clock = r.end + (o.outputDelay ?? 0.35) / this.pace;
this._record('terminal', r.start, r.end - r.start, { sfx: o.sfx }, { label: String(it.cmd).slice(0, 20), sustain: true });
} else {
r.end = r.start;
clock = r.start + (o.lineGap ?? 0.25) / this.pace;
}
return r;
});
const life = this._life({ ...o, sfx: null }, 'terminal', { dur: 0.5, enter: o.enter ?? (th.enter.code === 'rise' ? 'rise' : 'fade') });
if (this.engine.layoutLog) {
// Each command with its output is a focus point while it is the
// newest thing in the terminal.
const out = o.out === undefined ? Infinity : this.time(o.out);
const lineTop = y - h / 2 + barH + pad * 0.8;
let row = 0;
const blocks = [];
for (const it of timed) {
const n = String(it.cmd ?? it.out ?? '').split('\n').length;
if (it.cmd !== undefined) blocks.push({ at: it.start, from: row, to: row + n });
else if (blocks.length) blocks[blocks.length - 1].to = row + n;
row += n;
}
if (blocks.length > 1) blocks.forEach((b, i) => {
const y0 = lineTop + b.from * lh - lh * 0.45;
const y1 = lineTop + b.to * lh - lh * 0.1;
this._attach('focus', b.at, blocks[i + 1]?.at ?? out, this._elementBox(o, x, y, x, (y0 + y1) / 2, w - pad * 2, y1 - y0));
});
}
if (!life) return geom(x, y, w, h);
this._push(x, y, life, o);
this.pen.draw(ctx, { kind: 'rect', w, h, r: Math.min(th.radius, 16) }, { fill: T.bg, stroke: th.stroke.rough ? th.ink : 'none', width: th.stroke.width * 0.8, seed: this._seed('termbg', o), shadow: this._shadow(undefined, { color: 'rgba(0,0,0,0.22)', blur: 26, y: 10 }), rough: th.stroke.rough, fillStyle: 'solid' }, { stroke: 1, fill: 1 });
ctx.save();
const clip = new Path2D();
clip.roundRect(-w / 2, -h / 2, w, barH, [Math.min(th.radius, 16), Math.min(th.radius, 16), 0, 0]);
ctx.fillStyle = T.bar;
ctx.fill(clip);
ctx.restore();
['#ff5f57', '#febc2e', '#28c840'].forEach((c, i) => {
ctx.fillStyle = c;
ctx.beginPath();
ctx.arc(-w / 2 + pad * 0.8 + i * size * 0.8, -h / 2 + barH / 2, size * 0.2, 0, Math.PI * 2);
ctx.fill();
});
ctx.font = fontString(th, 'mono', size * 0.7);
ctx.fillStyle = T.muted;
ctx.textAlign = 'center';
ctx.textBaseline = 'middle';
ctx.fillText(o.title ?? 'terminal', 0, -h / 2 + barH / 2);
ctx.font = fontString(th, 'mono', size);
ctx.textAlign = 'left';
ctx.textBaseline = 'top';
const left = -w / 2 + pad;
const promptW = ctx.measureText((o.prompt ?? '$') + ' ').width;
for (const it of timed) {
for (const part of String(it.cmd ?? it.out ?? '').split('\n')) {
const width = ctx.measureText(part).width + (it.cmd !== undefined ? promptW : 0);
if (width > w - pad * 2) this._overflow(`terminal line "${part.slice(0, 40)}" is wider than the terminal; shorten it, lower size or raise w`);
}
}
ctx.save();
ctx.beginPath();
ctx.rect(-w / 2, -h / 2, w, h);
ctx.clip();
let row = 0;
const top = -h / 2 + barH + pad * 0.8;
let cursor = null;
for (const it of timed) {
if (this.t < it.start) break;
if (it.cmd !== undefined) {
const n = Math.floor((this.t - it.start) * cps);
const txt = String(it.cmd).slice(0, n);
ctx.fillStyle = T.prompt;
ctx.fillText(o.prompt ?? '$', left, top + row * lh);
const pw = ctx.measureText((o.prompt ?? '$') + ' ').width;
ctx.fillStyle = T.fg;
ctx.fillText(txt, left + pw, top + row * lh);
cursor = { x: left + pw + ctx.measureText(txt).width, y: top + row * lh, typing: this.t < it.end };
row++;
} else {
for (const part of String(it.out).split('\n')) {
ctx.fillStyle = it.color ? colorOf(th, it.color) : T.fg;
ctx.fillText(part, left, top + row * lh);
row++;
}
cursor = { x: left, y: top + row * lh, typing: false };
}
}
if (cursor && (cursor.typing || Math.floor(this.T * 2) % 2 === 0)) {
ctx.fillStyle = T.fg;
ctx.globalAlpha *= 0.85;
ctx.fillRect(cursor.x + 4, cursor.y + size * 0.08, size * 0.55, size * 1.05);
}
ctx.restore();
this._logText({ text: 'terminal', x0: -w / 2, y0: -h / 2, x1: w / 2, y1: h / 2, size, fg: T.fg, bg: T.bg, block: true });
ctx.restore();
return geom(x, y, w, h);
}
// ---------- celebration ----------
burst(o = {}) {
const th = this.theme;
const at = this.time(o.at ?? 0);
const x = o.x ?? this.cx;
const y = o.y ?? this.cy;
this._record('burst', at, 0.6, o);
// Particle physics run on pace-scaled time, so a faster video bursts faster.
const k = (this.t - at) * this.pace;
if (k < 0 || k > (o.life ?? 2.2)) return;
const ctx = this.ctx;
const count = o.count ?? 42;
const colors = (o.colors ?? ['accent', 'yellow', 'blue', 'green', 'pink', 'purple']).map((c) => colorOf(th, c));
const rand = mulberry32(hashStr(`${this.id}:burst:${at}`));
ctx.save();
for (let i = 0; i < count; i++) {
const ang = -Math.PI / 2 + (rand() - 0.5) * Math.PI * 1.35 * (o.spread ?? 1);
const sp = (o.power ?? 1000) * (0.45 + rand() * 0.65);
const px = x + Math.cos(ang) * sp * k;
const py = y + Math.sin(ang) * sp * k + 0.5 * 1500 * k * k;
const rot = rand() * 6 + k * (rand() - 0.5) * 14;
const s = (o.size ?? 14) * (0.6 + rand() * 0.8);
ctx.globalAlpha = clamp(1 - (k - 1.1) / 1.0);
ctx.fillStyle = colors[i % colors.length];
ctx.save();
ctx.translate(px, py);
ctx.rotate(rot);
if (i % 3 === 0) {
ctx.beginPath();
ctx.arc(0, 0, s * 0.45, 0, Math.PI * 2);
ctx.fill();
} else ctx.fillRect(-s / 2, -s * 0.3, s, s * 0.6);
ctx.restore();
}
ctx.restore();
}
}
// Suggestions for a misspelled or renamed icon: names sharing its parts in any
// order ("help-circle" -> "circle-help"), then tag matches, then close spellings.
function iconSuggest(name, icons, tags = {}) {
const parts = String(name).toLowerCase().split(/[-_\s]+/).filter(Boolean);
const names = Object.keys(icons);
const score = (n) => {
const np = n.split('-');
let sc = 0;
for (const p of parts) {
if (np.includes(p)) sc += 3;
else if (n.includes(p)) sc += 1;
if ((tags[n] || []).some((t) => t === p || t === parts.join(' '))) sc += 2;
}
return sc - np.length * 0.1;
};
const ranked = names.map((n) => ({ n, sc: score(n) })).filter((x) => x.sc > 0.5).sort((a, b) => b.sc - a.sc).slice(0, 8).map((x) => x.n);
return ranked.length ? ranked : suggest(name, names, 8);
}
function geom(x, y, w, h, shape = 'rect') {
return { x, y, w, h, shape, left: x - w / 2, right: x + w / 2, top: y - h / 2, bottom: y + h / 2 };
}
function palette(th, i) {
const order = [th.accent, 'blue', 'green', 'yellow', 'purple', 'orange', 'teal', 'pink', 'red'];
const uniq = [...new Set(order)];
return uniq[i % uniq.length];
}
function wedgeD(r, hole, a0, a1) {
const f = (n) => Math.round(n * 100) / 100;
const large = a1 - a0 > Math.PI ? 1 : 0;
const p = (rad, a) => `${f(Math.cos(a) * rad)} ${f(Math.sin(a) * rad)}`;
if (a1 - a0 >= Math.PI * 2 - 0.001) a1 = a0 + Math.PI * 2 - 0.001;
if (!hole) return `M0 0L${p(r, a0)}A${f(r)} ${f(r)} 0 ${large} 1 ${p(r, a1)}Z`;
return `M${p(r, a0)}A${f(r)} ${f(r)} 0 ${large} 1 ${p(r, a1)}L${p(hole, a1)}A${f(hole)} ${f(hole)} 0 ${large} 0 ${p(hole, a0)}Z`;
}
export { mixColor };
// A drawing context that remembers the box everything drawn on it covers,
// in design pixels. Each fill, stroke, text or image counts on its own, and
// one that covers most of the frame is a background and does not count.
// Path2D objects cannot be looked into and are skipped.
export function boundsRecorder(ctx, scale, frame = null) {
let x0 = Infinity;
let y0 = Infinity;
let x1 = -Infinity;
let y1 = -Infinity;
let path = null;
const point = (x, y) => {
const m = ctx.getTransform();
return [(m.a * x + m.c * y + m.e) / scale, (m.b * x + m.d * y + m.f) / scale];
};
const grow = (b, x, y) => {
const [px, py] = point(x, y);
if (!Number.isFinite(px) || !Number.isFinite(py)) return;
b.x0 = Math.min(b.x0, px);
b.y0 = Math.min(b.y0, py);
b.x1 = Math.max(b.x1, px);
b.y1 = Math.max(b.y1, py);
};
const empty = () => ({ x0: Infinity, y0: Infinity, x1: -Infinity, y1: -Infinity });
let paused = 0;
const commit = (b) => {
if (paused || !b || !(b.x1 >= b.x0) || !(b.y1 >= b.y0)) return;
if (frame && (b.x1 - b.x0) * (b.y1 - b.y0) > frame.W * frame.H * 0.6) return;
x0 = Math.min(x0, b.x0);
y0 = Math.min(y0, b.y0);
x1 = Math.max(x1, b.x1);
y1 = Math.max(y1, b.y1);
};
// How far a stroke reaches past its outline: half the line width in the
// drawing's own units, through the full transform.
const widen = (b) => {
const m = ctx.getTransform();
const r = ctx.lineWidth / 2 / scale;
const kx = r * Math.hypot(m.a, m.c);
const ky = r * Math.hypot(m.b, m.d);
return { x0: b.x0 - kx, y0: b.y0 - ky, x1: b.x1 + kx, y1: b.y1 + ky };
};
const onPath = (fn) => (...a) => {
path ??= empty();
fn(path, ...a);
};
// For strokes: the segments of each subpath of the current path, so
// sharp corners and square ends can be measured. A segment keeps its
// ends and the control points that give its direction there.
let subs = [];
let sub = null;
const dir = (p, q) => {
const dx = q[0] - p[0];
const dy = q[1] - p[1];
const L = Math.hypot(dx, dy);
return L > 1e-9 ? [dx / L, dy / L] : null;
};
const begin = (p) => {
sub = { first: p, last: p, segs: [], closed: false };
subs.push(sub);
};
// A segment from the current point to `end`; `a` and `b` are its first
// and last control points. Without a current point a path starts at `a`.
const segment = (a, b, end) => {
if (!sub) begin(a);
const p0 = sub.last;
if (dir(p0, a) || dir(p0, b) || dir(p0, end)) sub.segs.push({ p0, a, b, p1: end });
sub.last = end;
};
const close = () => {
if (!sub) return;
segment(sub.first, sub.first, sub.first);
sub.closed = true;
begin(sub.first);
};
const line = (x, y) => {
const p = point(x, y);
segment(p, p, p);
};
// An arc as one segment, with its direction at both ends. Canvas draws a
// straight line to the arc's start first.
const arcSegment = (cx, cy, rx, ry, rot, a0, a1, ccw) => {
const full = ccw ? a0 - a1 >= Math.PI * 2 : a1 - a0 >= Math.PI * 2;
const end = full ? a0 : a1;
const sign = ccw ? -1 : 1;
const turn = (x, y) => [x * Math.cos(rot) - y * Math.sin(rot), x * Math.sin(rot) + y * Math.cos(rot)];
const at = (t) => { const [x, y] = turn(rx * Math.cos(t), ry * Math.sin(t)); return [cx + x, cy + y]; };
const tangent = (t) => turn(-rx * Math.sin(t) * sign, ry * Math.cos(t) * sign);
const s0 = at(a0);
const s1 = at(end);
const t0 = tangent(a0);
const t1 = tangent(end);
line(s0[0], s0[1]);
segment(point(s0[0] + t0[0], s0[1] + t0[1]), point(s1[0] - t1[0], s1[1] - t1[1]), point(s1[0], s1[1]));
};
// Turns a point from `point` back into the current transform's units.
const toLocal = () => {
const inv = ctx.getTransform().inverse();
if (![inv.a, inv.b, inv.c, inv.d, inv.e, inv.f].every(Number.isFinite)) return null;
return (p) => {
const q = inv.transformPoint(new DOMPoint(p[0] * scale, p[1] * scale));
return [q.x, q.y];
};
};
// Works out the corners and ends of a stroke in the current transform's
// units, where the line width applies, and adds them to the box.
const strokeEnds = (b) => {
const local = toLocal();
if (!local) return b;
const hw = ctx.lineWidth / 2;
const miter = ctx.lineJoin === 'miter' ? ctx.miterLimit : 0;
// A mitered corner sticks out along the line that splits the corner in
// half. Canvas cuts it off when the corner is sharper than the miter
// limit allows.
const join = (u, v, p) => {
const sinHalf = Math.sqrt(Math.max(0, (1 + u[0] * v[0] + u[1] * v[1]) / 2));
const ox = u[0] - v[0];
const oy = u[1] - v[1];
const L = Math.hypot(ox, oy);
if (sinHalf < 1e-6 || 1 / sinHalf > miter || L < 1e-9) return;
grow(b, p[0] + (ox / L) * (hw / sinHalf), p[1] + (oy / L) * (hw / sinHalf));
};
const cap = (p, d) => {
grow(b, p[0] + (d[0] - d[1]) * hw, p[1] + (d[1] + d[0]) * hw);
grow(b, p[0] + (d[0] + d[1]) * hw, p[1] + (d[1] - d[0]) * hw);
};
for (const sp of subs) {
const segs = sp.segs.map((g) => {
const [p0, a, c, p1] = [g.p0, g.a, g.b, g.p1].map(local);
return { p0, p1, d0: dir(p0, a) ?? dir(p0, c) ?? dir(p0, p1), d1: dir(c, p1) ?? dir(a, p1) ?? dir(p0, p1) };
}).filter((g) => g.d0 && g.d1);
const n = segs.length;
if (!n) continue;
if (miter) {
for (let i = 1; i < n; i++) join(segs[i - 1].d1, segs[i].d0, segs[i].p0);
if (sp.closed) join(segs[n - 1].d1, segs[0].d0, segs[0].p0);
}
if (ctx.lineCap === 'square' && !sp.closed) {
cap(segs[0].p0, [-segs[0].d0[0], -segs[0].d0[1]]);
cap(segs[n - 1].p1, segs[n - 1].d1);
}
}
return b;
};
const corners = (b, x, y, w, h) => {
grow(b, x, y);
grow(b, x + w, y);
grow(b, x, y + h);
grow(b, x + w, y + h);
};
const shape = (x, y, w, h) => {
const b = empty();
corners(b, x, y, w, h);
commit(b);
};
const text = (str, x, y, stroked = false) => {
const m = ctx.measureText(String(str));
const l = m.actualBoundingBoxLeft || 0;
const a = m.actualBoundingBoxAscent || 0;
const b = empty();
corners(b, x - l, y - a, l + (m.actualBoundingBoxRight || m.width), a + (m.actualBoundingBoxDescent || 0));
commit(stroked ? widen(b) : b);
};
const record = {
beginPath: () => {
path = null;
subs = [];
sub = null;
},
moveTo: onPath((b, x, y) => { grow(b, x, y); begin(point(x, y)); }),
lineTo: onPath((b, x, y) => { grow(b, x, y); line(x, y); }),
quadraticCurveTo: onPath((b, cx, cy, x, y) => { grow(b, cx, cy); grow(b, x, y); const c = point(cx, cy); segment(c, c, point(x, y)); }),
bezierCurveTo: onPath((b, a, c, d, e, x, y) => { grow(b, a, c); grow(b, d, e); grow(b, x, y); segment(point(a, c), point(d, e), point(x, y)); }),
// A line toward the corner (x1, y1) that turns along a circle onto the
// line toward (x2, y2), as canvas draws it.
arcTo: onPath((b, x1, y1, x2, y2, r) => {
grow(b, x1, y1);
grow(b, x2, y2);
const local = toLocal();
if (!sub || !local) return line(x1, y1);
const p0 = local(sub.last);
const u = dir([x1, y1], p0);
const v = dir([x1, y1], [x2, y2]);
const sin = u && v ? Math.abs(u[0] * v[1] - u[1] * v[0]) : 0;
if (!(r > 0) || sin < 1e-9) return line(x1, y1);
const d = r / Math.tan(Math.acos(clamp(u[0] * v[0] + u[1] * v[1], -1, 1)) / 2);
const t1 = [x1 + u[0] * d, y1 + u[1] * d];
const t2 = [x1 + v[0] * d, y1 + v[1] * d];
grow(b, t1[0], t1[1]);
grow(b, t2[0], t2[1]);
line(t1[0], t1[1]);
segment(point(x1, y1), point(x1, y1), point(t2[0], t2[1]));
}),
arc: onPath((b, x, y, r, a0, a1, ccw = false) => { corners(b, x - r, y - r, r * 2, r * 2); arcSegment(x, y, r, r, 0, a0, a1, ccw); }),
ellipse: onPath((b, x, y, rx, ry, rot, a0, a1, ccw = false) => { const r = Math.max(rx, ry); corners(b, x - r, y - r, r * 2, r * 2); arcSegment(x, y, rx, ry, rot, a0, a1, ccw); }),
// A rectangle is a closed path of its own, and the next one starts at
// its first corner.
rect: onPath((b, x, y, w, h) => {
corners(b, x, y, w, h);
begin(point(x, y));
line(x + w, y);
line(x + w, y + h);
line(x, y + h);
close();
}),
roundRect: onPath((b, x, y, w, h) => { corners(b, x, y, w, h); begin(point(x, y)); }),
closePath: close,
fill: (p) => { if (!(p instanceof Path2D)) commit(path); },
stroke: (p) => { if (!(p instanceof Path2D) && path) commit(strokeEnds(widen(path))); },
fillRect: shape,
// Mitered corners reach half the line width out on both sides; round
// and bevelled ones no further than the widened outline.
strokeRect: (x, y, w, h) => {
const b = empty();
const hw = ctx.lineWidth / 2;
if (ctx.lineJoin === 'miter') {
corners(b, Math.min(x, x + w) - hw, Math.min(y, y + h) - hw, Math.abs(w) + hw * 2, Math.abs(h) + hw * 2);
commit(b);
} else {
corners(b, x, y, w, h);
commit(widen(b));
}
},
fillText: (str, x, y) => text(str, x, y),
strokeText: (str, x, y) => text(str, x, y, true),
drawImage: (img, ...a) => {
if (a.length === 2) shape(a[0], a[1], img.width, img.height);
else if (a.length === 4) shape(a[0], a[1], a[2], a[3]);
else if (a.length === 8) shape(a[4], a[5], a[6], a[7]);
},
};
// Parts that report their own place and time (UI panels, headlines) and
// decoration (floating cards) are left out.
const pause = (on) => { paused += on ? 1 : -1; };
const proxy = new Proxy(ctx, {
get(target, prop) {
if (prop === '__inkPause') return pause;
const v = target[prop];
if (typeof v !== 'function') return v;
const note = record[prop];
return note ? (...args) => { note(...args); return v.apply(target, args); } : v.bind(target);
},
set(target, prop, value) {
target[prop] = value;
return true;
},
});
return { proxy, box: () => (x1 >= x0 && y1 >= y0 && (x1 > x0 || y1 > y0) ? { x: (x0 + x1) / 2, y: (y0 + y1) / 2, w: x1 - x0, h: y1 - y0 } : null) };
}
function unionBox(a, b) {
const x0 = Math.min(a.x - a.w / 2, b.x - b.w / 2);
const y0 = Math.min(a.y - a.h / 2, b.y - b.h / 2);
const x1 = Math.max(a.x + a.w / 2, b.x + b.w / 2);
const y1 = Math.max(a.y + a.h / 2, b.y + b.h / 2);
return { x: (x0 + x1) / 2, y: (y0 + y1) / 2, w: x1 - x0, h: y1 - y0 };
}