beecast_player/
lib.rs

1//! The first-party beecast player as a crate: clean-room, dependency-free
2//! asciicast (v1/v2/v3) player and VT100/xterm-subset terminal emulator. Consumers inline
3//! the two constants whole — a `<script>` element and a `<style>` element — and get the
4//! full player: parsing, emulation, headless controller, default controls, Web Component,
5//! chapter markers, keyboard control, and live-follow `append` for recordings that are
6//! still growing.
7//!
8//! The JS globals are `BeeCastVT` (DOM-free core), `BeeCastController` (headless playback),
9//! and `BeeCastPlayer` (DOM factory + `<beecast-player>`); this crate is the component's
10//! canonical home.
11
12/// The player bundle: `vt.js` (core) + `controller.js` (headless playback) + `player.js`
13/// (DOM view, Web Component, legacy factory). Inline it in one `<script>` element; it
14/// performs no network requests and loads no workers.
15pub const PLAYER_JS: &str =
16  concat!(include_str!("vt.js"), "\n", include_str!("controller.js"), "\n", include_str!("player.js"),);
17
18/// The player chrome and terminal palette. Semantic `--beecast-*` tokens are the stable
19/// theming surface; `--sp-*` is the terminal palette. Nothing is fetched (no fonts, no images).
20pub const PLAYER_CSS: &str = include_str!("player.css");
21
22#[cfg(test)]
23mod tests {
24  use super::*;
25
26  /// Every embedder's self-containment claim depends on the bundle itself: it must not
27  /// contain a literal `</script`, must not reference workers, and its CSS must not pull
28  /// fonts or images. Asserted here so a player change that breaks any of it fails loudly.
29  /// And the bundle must be the first-party clean-room player — no third-party code, and
30  /// therefore no third-party license, rides into any embedding page.
31  #[test]
32  fn player_bundle_is_inline_safe_and_first_party() {
33    assert!(!PLAYER_JS.contains("</script"), "bundle would terminate an inline <script>");
34    assert!(!PLAYER_JS.contains("<!--"), "bundle would enter the script double-escaped state");
35    assert!(!PLAYER_JS.to_lowercase().contains("worker"), "bundle must not load a worker sidecar");
36    assert!(!PLAYER_CSS.contains("url("), "player CSS must not fetch fonts/images");
37    assert!(PLAYER_JS.contains("BeeCastPlayer") && PLAYER_JS.contains("Clean-room implementation"));
38    assert!(PLAYER_JS.contains("BeeCastController"));
39    assert!(PLAYER_JS.contains("beecast-player"));
40    for banned in ["asciinema-player", "AsciinemaPlayer", "@license", "Apache"] {
41      assert!(!PLAYER_JS.contains(banned) && !PLAYER_CSS.contains(banned), "third-party marker '{banned}'");
42    }
43  }
44
45  /// Phase 0: the public surface must not shrink without an intentional change.
46  #[test]
47  fn public_api_surface_is_documented() {
48    for key in [
49      "BeeCastVT",
50      "BeeCastController",
51      "BeeCastPlayer",
52      "parseCast",
53      "appendCast",
54      "buildPacing",
55      "extendPacing",
56      "mapTime",
57      "create",
58      "getState",
59      "subscribe",
60      "setSpeed",
61      "publicMethods",
62      "supportedCssVariables",
63      "nonPublicFields",
64    ] {
65      assert!(PLAYER_JS.contains(key), "public surface missing {key}");
66    }
67    for token in
68      ["--beecast-color-surface", "--beecast-color-accent", "--beecast-color-focus", "--beecast-font-terminal"]
69    {
70      assert!(PLAYER_CSS.contains(token), "theme token missing {token}");
71    }
72  }
73
74  /// Behavior tests for the DOM-free core and headless controller, run under Node.
75  /// Skips silently when `node` is not installed — the structural assertions above still gate the bundle.
76  #[test]
77  fn vt_core_node_selftest() {
78    let dir = std::env::temp_dir().join(format!("beecast-vt-selftest-{}", std::process::id()));
79    std::fs::create_dir_all(&dir).unwrap();
80    let bundle = dir.join("player.js");
81    std::fs::write(&bundle, PLAYER_JS).unwrap();
82    let script = r#"
83const assert = require('assert');
84require(process.argv[2]);
85const VT = globalThis.BeeCastVT;
86const C = globalThis.BeeCastController;
87const P = globalThis.BeeCastPlayer;
88
89// ---- Phase 0: public keys --------------------------------------------------------------
90for (const k of ['parseCast','appendCast','buildPacing','extendPacing','mapTime','Term']) {
91  assert.strictEqual(typeof VT[k], 'function', 'BeeCastVT.' + k);
92}
93assert.strictEqual(typeof C.create, 'function');
94assert.strictEqual(typeof P.create, 'function');
95assert.ok(Array.isArray(P.publicMethods));
96for (const m of ['create','play','pause','toggle','seek','getCurrentTime','append','dispose']) {
97  assert.ok(P.publicMethods.includes(m), 'publicMethods missing ' + m);
98}
99assert.ok(P.nonPublicFields.includes('playing'));
100assert.ok(P.nonPublicFields.includes('pacedPos'));
101assert.ok(P.supportedCssVariables.includes('--beecast-color-accent'));
102
103// ---- VT core (existing coverage) -------------------------------------------------------
104let c = VT.parseCast('{"version":3,"term":{"cols":10,"rows":3}}\n# note\n[0.5,"o","hi"]\n[0.5,"m","chapter"]\n[1.0,"r","20x5"]\n');
105assert.strictEqual(c.cols, 10); assert.strictEqual(c.rows, 3);
106assert.strictEqual(c.events.length, 3);
107assert.strictEqual(c.duration, 2);
108
109c = VT.parseCast('{"version":2,"width":80,"height":24}\n[0.5,"o","a"]\n[2.0,"o","b"]\n');
110assert.strictEqual(c.duration, 2); assert.strictEqual(c.events[1].t, 2);
111
112c = VT.parseCast('{"version":1,"width":5,"height":2,"stdout":[[0.1,"x"],[0.2,"y"]]}');
113assert.strictEqual(c.cols, 5); assert.strictEqual(c.events.length, 2);
114
115c = VT.parseCast('{"version":3,"term":{"cols":10,"rows":3}}\n[1.0,"o","a"]\n');
116assert.strictEqual(VT.appendCast(c, '[0.5,"o",'), 0);
117assert.strictEqual(c.duration, 1);
118assert.strictEqual(VT.appendCast(c, '"b"]\n[0.5,"m","x"]\n'), 2);
119assert.strictEqual(c.duration, 2);
120assert.strictEqual(c.events.length, 3);
121assert.strictEqual(c.events[1].t, 1.5);
122
123c = VT.parseCast('{"version":2,"width":80,"height":24}\n[1.0,"o","a"]\n');
124VT.appendCast(c, '# noise\n{"version":2}\n[3.0,"o","b"]\n');
125assert.strictEqual(c.duration, 3); assert.strictEqual(c.events[1].t, 3);
126
127c = VT.parseCast('{"version":3,"term":{"cols":4,"rows":1}}\n[1.0,"o","hi"]\n[2.0,"o');
128assert.strictEqual(c.events.length, 1);
129VT.appendCast(c, '","yo"]\n');
130assert.strictEqual(c.events.length, 2); assert.strictEqual(c.duration, 3);
131
132c = VT.parseCast('{"version":1,"width":5,"height":2,"stdout":[[0.1,"x"]]}');
133assert.strictEqual(VT.appendCast(c, '[1.0,"o","y"]\n'), 0);
134
135const ev = [{t:1},{t:2}];
136const pacing = VT.buildPacing(ev, 2, null);
137ev.push({t:10});
138VT.extendPacing(pacing, ev, 2, 10);
139assert.strictEqual(pacing.pacedDuration, 10);
140assert.strictEqual(VT.mapTime(pacing.rec, pacing.paced, 10), 10);
141const limited = VT.buildPacing([{t:1}], 1, 2);
142VT.extendPacing(limited, [{t:1},{t:9}], 1, 9);
143assert.strictEqual(limited.pacedDuration, 3);
144assert.strictEqual(VT.mapTime(limited.paced, limited.rec, 3), 9);
145
146let t = new VT.Term(10, 3);
147t.write('hello\r\nworld');
148assert.deepStrictEqual(t.textLines(), ['hello', 'world', '']);
149t.write('\x1b[1;3Hga');
150assert.strictEqual(t.textLines()[0], 'hegao');
151t.write('\x1b[2J');
152assert.deepStrictEqual(t.textLines(), ['', '', '']);
153
154t = new VT.Term(10, 1);
155t.write('\x1b[31mred\x1b[0m ok');
156const runs = t.snapshot().rows[0];
157assert.strictEqual(runs[0].text, 'red'); assert.strictEqual(runs[0].fg, 1);
158t = new VT.Term(4, 1);
159t.write('\x1b[38;5;196mX\x1b[38;2;1;2;3mY');
160assert.strictEqual(t.snapshot().rows[0][0].fg, 196);
161assert.strictEqual(t.snapshot().rows[0][1].fg, '#010203');
162
163t = new VT.Term(3, 2);
164t.write('abc');
165assert.strictEqual(t.snapshot().cursor.y, 0);
166t.write('d');
167assert.deepStrictEqual(t.textLines(), ['abc', 'd']);
168
169t = new VT.Term(5, 4);
170t.write('aa\r\nbb\r\ncc\r\ndd');
171t.write('\x1b[2;3r\x1b[3;1H\n');
172assert.strictEqual(t.textLines()[0], 'aa');
173assert.strictEqual(t.textLines()[1], 'cc');
174assert.strictEqual(t.textLines()[3], 'dd');
175
176t = new VT.Term(5, 2);
177t.write('main');
178t.write('\x1b[?1049h\x1b[Halt');
179assert.strictEqual(t.textLines()[0], 'alt');
180t.write('\x1b[?1049l');
181assert.strictEqual(t.textLines()[0], 'main');
182
183t = new VT.Term(4, 1);
184t.write('\x1b(0qqx\x1b(B');
185assert.strictEqual(t.textLines()[0], '──│');
186t = new VT.Term(8, 1);
187t.write('\x1b]0;title\x07ok');
188assert.strictEqual(t.textLines()[0], 'ok');
189t.write('\x1b[?25l');
190assert.strictEqual(t.snapshot().cursor.visible, false);
191
192// ---- Phase 1: headless controller (no DOM) ---------------------------------------------
193function fakeClock() {
194  let now = 0;
195  const q = [];
196  return {
197    now: () => now,
198    requestAnimationFrame: (cb) => { q.push(cb); return q.length; },
199    cancelAnimationFrame: () => { q.length = 0; },
200    flush: (ms) => {
201      now += ms;
202      const batch = q.splice(0, q.length);
203      for (const cb of batch) cb(now);
204    },
205  };
206}
207
208const castText = '{"version":3,"term":{"cols":8,"rows":2}}\n[0,"o","hi"]\n[1.0,"o","!"]\n[1.0,"m","mid"]\n';
209const clock = fakeClock();
210const ctrl = C.create({
211  data: castText,
212  idleTimeLimit: 2,
213  speed: 1,
214  markers: [[0, 'start']],
215  clock: clock,
216});
217
218// Initial state
219let state = ctrl.getState();
220assert.strictEqual(state.status, 'idle');
221assert.strictEqual(state.currentTime, 0);
222assert.strictEqual(state.duration, 2);
223assert.strictEqual(state.speed, 1);
224assert.strictEqual(state.canAppend, true);
225assert.ok(state.markers.length >= 2); // sidecar + in-band
226assert.ok(state.markers.every(m => m.id && typeof m.time === 'number' && m.label != null));
227assert.ok(state.terminal.rows.length === 2);
228assert.strictEqual(state.dimensions.columns, 8);
229
230// Terminal snapshots are cached until output or resize dirties the terminal.
231let snapshotCalls = 0;
232const originalSnapshot = ctrl.term.snapshot;
233ctrl.term.snapshot = function () { snapshotCalls++; return originalSnapshot.call(this); };
234const cachedTerminal = ctrl.getState().terminal;
235assert.strictEqual(ctrl.getState().terminal, cachedTerminal);
236assert.strictEqual(snapshotCalls, 0, 'initial snapshot remains cached');
237ctrl.seek(1.5);
238const changedTerminal = ctrl.getState().terminal;
239assert.notStrictEqual(changedTerminal, cachedTerminal);
240assert.strictEqual(snapshotCalls, 1, 'events invalidate the cached snapshot once');
241assert.strictEqual(ctrl.getState().terminal, changedTerminal);
242assert.strictEqual(snapshotCalls, 1, 'unchanged state does not copy the terminal again');
243ctrl.seek(0);
244
245// subscribe delivers immediately and is removable
246const seen = [];
247const unsub = ctrl.subscribe((s, meta) => { seen.push(meta.type); });
248assert.ok(seen.includes('ready'));
249unsub();
250unsub(); // idempotent
251const n = seen.length;
252ctrl.setSpeed(2);
253// no more callbacks after unsubscribe
254assert.strictEqual(seen.length, n);
255
256// setSpeed does not rebuild terminal / changes state
257ctrl.setSpeed(1.5);
258assert.strictEqual(ctrl.getState().speed, 1.5);
259
260// play / pause / seek / getCurrentTime
261// First animation frame establishes lastTick (dt=0); the second advances the clock.
262ctrl.play();
263assert.strictEqual(ctrl.getState().status, 'playing');
264clock.flush(0);
265clock.flush(500); // 0.5s wall * 1.5 speed ≈ 0.75s paced
266assert.ok(ctrl.getCurrentTime() > 0);
267ctrl.pause();
268assert.strictEqual(ctrl.getState().status, 'paused');
269
270ctrl.seek(1.5);
271assert.ok(Math.abs(ctrl.getCurrentTime() - 1.5) < 1e-9);
272ctrl.seek(0);
273assert.ok(ctrl.getCurrentTime() < 1e-9);
274
275// toggle
276ctrl.toggle();
277assert.strictEqual(ctrl.getState().status, 'playing');
278ctrl.toggle();
279assert.strictEqual(ctrl.getState().status, 'paused');
280
281// replay after end
282ctrl.seek(2);
283ctrl.play();
284// playing from end rewinds
285assert.strictEqual(ctrl.getState().status, 'playing');
286assert.ok(ctrl.getCurrentTime() < 1e-6);
287
288// append live-follow at edge
289ctrl.pause();
290ctrl.seek(2);
291assert.ok(ctrl.getState().atLiveEdge);
292ctrl.append('[0.5,"o","more"]\n');
293assert.strictEqual(ctrl.getState().duration, 2.5);
294
295// Declared-live mode: parked mid-recording, setLive pins the playhead to the edge; an
296// append keeps it pinned (unconditionally — no positional check); a rewinding seek or
297// play() drops live; a seek TO the edge keeps it.
298ctrl.seek(1);
299ctrl.setLive(true);
300let live = ctrl.getState();
301assert.strictEqual(live.live, true);
302assert.ok(live.atLiveEdge, 'setLive parks at the edge');
303assert.ok(Math.abs(live.currentTime - live.duration) < 1e-9);
304ctrl.append('[0.5,"o","live"]\n');
305live = ctrl.getState();
306assert.strictEqual(live.live, true);
307assert.ok(Math.abs(live.currentTime - live.duration) < 1e-9, 'append keeps the pin');
308ctrl.seek(live.duration); // to the edge: still live
309assert.strictEqual(ctrl.getState().live, true);
310const liveEvents = [];
311const unsubLive = ctrl.subscribe((st, meta) => { liveEvents.push(meta.type); });
312ctrl.seek(0.5); // a rewind: live drops, with a livechange event
313assert.strictEqual(ctrl.getState().live, false);
314assert.ok(liveEvents.includes('livechange'));
315unsubLive();
316ctrl.setLive(true);
317ctrl.play(); // play from the parked edge is a rewind: live drops
318assert.strictEqual(ctrl.getState().live, false);
319ctrl.pause();
320
321// getState is a snapshot (mutating returned markers does not corrupt internal list)
322const s1 = ctrl.getState();
323s1.markers.push({ id: 'x', time: 99, type: 'chapter', label: 'x' });
324assert.ok(ctrl.getState().markers.every(m => m.id !== 'x'));
325
326// dispose makes commands no-ops
327ctrl.dispose();
328ctrl.play();
329ctrl.seek(1);
330ctrl.append('[1,"o","z"]\n');
331assert.strictEqual(ctrl.getState().status, 'idle');
332
333// Marker object form + tuple compatibility
334const c2 = C.create({
335  data: '{"version":3,"term":{"cols":4,"rows":1}}\n[0,"o","a"]\n',
336  markers: [{ time: 0, label: 'A', type: 'chapter' }, [1, 'B']],
337  clock: fakeClock(),
338});
339const marks = c2.getState().markers;
340assert.strictEqual(marks[0].label, 'A');
341assert.strictEqual(marks[1].label, 'B');
342c2.dispose();
343
344// Source type text
345const c3 = C.create({
346  source: { type: 'text', data: '{"version":3,"term":{"cols":4,"rows":1}}\n[0,"o","z"]\n' },
347  clock: fakeClock(),
348});
349assert.strictEqual(c3.getState().duration, 0);
350c3.dispose();
351
352// Discrete events survive playback: seek/speedchange/durationchange/markerchange emitted
353// WHILE PLAYING must each reach subscribers with their own meta type — timeupdate
354// coalescing must never swallow them.
355const clock4 = fakeClock();
356const c4 = C.create({ data: castText, idleTimeLimit: 2, clock: clock4 });
357const types = [];
358c4.subscribe(function (s, meta) { types.push(meta.type); });
359c4.play();
360clock4.flush(0);
361clock4.flush(200);
362assert.ok(types.includes('timeupdate'), 'timeupdate flows while playing');
363assert.strictEqual(c4.getState().status, 'playing');
364c4.seek(1.5, { origin: 'api' });
365assert.ok(types.includes('seek'), 'seek delivered while playing, saw: ' + types.join(','));
366c4.append('[5,"o","tail"]\n');
367assert.ok(types.includes('durationchange'), 'durationchange delivered while playing');
368c4.setSpeed(2);
369assert.ok(types.includes('speedchange'), 'speedchange delivered while playing');
370c4.setMarkers([[0.5, 'half']]);
371assert.ok(types.includes('markerchange'), 'markerchange delivered');
372assert.strictEqual(c4.getState().markers.filter(m => m.source === 'integration').length, 1);
373c4.dispose();
374
375console.log('vt selftest OK');
376"#;
377    let spawned = std::process::Command::new("node")
378      .arg("-")
379      .arg(&bundle)
380      .stdin(std::process::Stdio::piped())
381      .stdout(std::process::Stdio::piped())
382      .stderr(std::process::Stdio::piped())
383      .spawn();
384    let Ok(mut child) = spawned else {
385      let _ = std::fs::remove_dir_all(&dir);
386      return; // no node on this machine — the structural tests above still ran
387    };
388    use std::io::Write;
389    child.stdin.take().unwrap().write_all(script.as_bytes()).unwrap();
390    let out = child.wait_with_output().unwrap();
391    let _ = std::fs::remove_dir_all(&dir);
392    assert!(
393      out.status.success() && String::from_utf8_lossy(&out.stdout).contains("vt selftest OK"),
394      "vt selftest failed:\nstdout: {}\nstderr: {}",
395      String::from_utf8_lossy(&out.stdout),
396      String::from_utf8_lossy(&out.stderr)
397    );
398  }
399}
beecast_player/lib.rs

beecast_player/
lib.rs
