@supersuit/session-player 0.0.0-stage → 0.4.0

package/src/convert.mjs

@@ -0,0 +1,311 @@
+// Drafts a scenario from a Claude Code session transcript (~/.claude/projects/<dir>/<id>.jsonl).
+//
+// The hard part is telling what the PERSON typed from everything else that arrives as a
+// "user" line: tool results, skill bodies, task notifications, peer-session messages and
+// interrupt markers. Get that wrong and the replay shows the agent talking to itself.
+//
+// This drafts; it does not publish. Anonymizing people is the promote skill's job. What the
+// converter guarantees is a floor: no credential-shaped string and no home path survives,
+// and every edit it makes is written to `cuts`, so nothing is staged silently.
+
+import { FORMAT } from './scenario.mjs';
+import { deviceFromSession } from './device.mjs';
+
+const LONG_PASTE = 600;
+// Idle time is not work. A session's clock keeps running while a command hangs, the laptop
+// sleeps, or the person walks away, and an album release once read as six hours because one
+// folder check hung overnight (Gary, 2026-10-10: "There's no way that releasing the album
+// took 6 hours"). So: the agent's thinking before a step counts at most THINK_CAP, any one
+// step counts at most STEP_CAP, a command that timed out counts as no work, and a question
+// counts at most ASK_CAP of the person deciding. Everything removed is kept as `idleMs`.
+const THINK_CAP = 3 * 60_000;
+const STEP_CAP = 10 * 60_000;
+const ASK_CAP = 5 * 60_000;
+const timedOut = (data, text) => Boolean(data?.timedOutAfterMs) || /did not complete within its \d+s timeout/.test(text ?? '');
+const PASTE_KEEP = 280;
+
+export function parseSession(text) {
+  const out = [];
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue;
+    try { out.push(JSON.parse(line)); } catch { /* a torn line is skipped, never fatal */ }
+  }
+  return out;
+}
+
+const blocks = (m) => (typeof m?.content === 'string' ? [{ type: 'text', text: m.content }] : Array.isArray(m?.content) ? m.content : []);
+const textOf = (m) => blocks(m).filter((b) => b.type === 'text').map((b) => b.text).join('\n').trim();
+const isInterrupt = (o) => o.type === 'user' && /^\[Request interrupted by user/.test(textOf(o.message));
+
+function isHuman(o) {
+  if (o.type !== 'user' || o.isSidechain || o.isMeta || o.toolUseResult !== undefined) return false;
+  if (blocks(o.message).some((b) => b.type === 'tool_result')) return false;
+  const text = textOf(o.message);
+  if (!text) return false;
+  if (o.origin) return o.origin.kind === 'human';
+  // Sessions recorded before Claude Code wrote `origin`: anything machine-made starts with a tag or a bracket.
+  return !/^[<[]/.test(text);
+}
+
+// Credential shapes, and env-style assignments whose value looks like a secret.
+const SECRETS = [
+  /\b(sk-[A-Za-z0-9_-]{20,})/g,
+  /\b(gh[pousr]_[A-Za-z0-9]{30,})/g,
+  /\b(AIza[0-9A-Za-z_-]{30,})/g,
+  /\b(xox[abprs]-[A-Za-z0-9-]{10,})/g,
+  /\b[A-Z0-9_]*(?:KEY|TOKEN|SECRET|PASSWORD)[A-Z0-9_]*=(["']?)([A-Za-z0-9_\-./+]{16,})\1/g,
+];
+
+// Contact details: a scenario is shown to strangers, and an agent session is full of them
+// (every text-message approval names a number). Dates (2026-10-10), versions (4.259.1) and
+// counts (1,000) do not match: a phone needs 10 digits in 3-3-4 groups.
+const CONTACTS = [
+  [/[\w.+-]+@[\w-]+(?:\.[\w-]+)+/g, '[email removed]'],
+  [/(?<![\w.-])(?:\+?1[\s.-]?)?\(?\d{3}\)?[\s.-]?\d{3}[\s.-]?\d{4}(?![\w-]|\.\d)/g, '[phone removed]'],
+  [/(?<![\w.-])\+\d{11,15}(?![\w-])/g, '[phone removed]'],
+];
+
+function cleaner(home, cuts) {
+  const homeRe = home ? new RegExp(home.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'g') : null;
+  return (text, turn, where) => {
+    let s = String(text ?? '');
+    if (homeRe) s = s.replace(homeRe, '~');
+    for (const [re, mark] of CONTACTS) {
+      s = s.replace(re, () => {
+        cuts.push({ turn, what: where, reason: 'contact detail removed' });
+        return mark;
+      });
+    }
+    for (const re of SECRETS) {
+      s = s.replace(re, (m) => {
+        cuts.push({ turn, what: where, reason: 'credential removed' });
+        const eq = m.indexOf('=');
+        return eq > 0 && /[A-Z]/.test(m[0]) ? `${m.slice(0, eq + 1)}[removed]` : '[removed]';
+      });
+    }
+    return s;
+  };
+}
+
+const base = (p) => String(p).split('/').filter(Boolean).pop() ?? String(p);
+
+function stepFor(name, input = {}) {
+  switch (name) {
+    case 'Read': return { kind: 'read', label: `read ${base(input.file_path)}` };
+    case 'Write': return { kind: 'write', label: `wrote ${base(input.file_path)}` };
+    case 'Edit': case 'MultiEdit': case 'NotebookEdit': return { kind: 'edit', label: `edited ${base(input.file_path ?? input.notebook_path)}` };
+    case 'Grep': case 'Glob': return { kind: 'search', label: 'searched the files' };
+    case 'Skill': return { kind: `skill:${input.skill}`, label: `used ${input.skill}` };
+    case 'Agent': case 'Task': return { kind: `agent:${input.description}`, label: input.description || 'ran an agent' };
+    case 'Bash': return { kind: `bash:${input.description ?? input.command}`, label: input.description || 'ran a command' };
+    case 'WebFetch': case 'WebSearch': return { kind: 'web', label: 'read the web' };
+    case 'AskUserQuestion': return { kind: 'ask', label: 'asked a question' };
+    default: return { kind: `tool:${name}`, label: name.replace(/^mcp__[^_]+__/, '').replace(/_/g, ' ') };
+  }
+}
+
+const PLURAL = { read: (n) => `read ${n} files`, write: (n) => `wrote ${n} files`, edit: (n) => `edited ${n} files`, search: (n) => `searched the files ${n} times`, web: (n) => `read ${n} web pages` };
+
+function merge(steps) {
+  const out = [];
+  for (const s of steps) {
+    const last = out[out.length - 1];
+    if (last && last.kind === s.kind) {
+      last.count += 1; last.ms += s.ms; last.at = s.at;
+      if (s.idleMs) last.idleMs = (last.idleMs ?? 0) + s.idleMs;
+      continue;
+    }
+    out.push({ ...s, count: 1 });
+  }
+  return out.map(({ kind, ...s }) => (s.count > 1 && PLURAL[kind] ? { ...s, label: PLURAL[kind](s.count) } : s));
+}
+
+const HARNESS_NOTICE = /^\s*(You've hit your (weekly |session |daily )?limit|API Error:|Claude AI usage limit reached|Request timed out)/i;
+const URL_RE = /https:\/\/[^\s)>\]"'`]+/g;
+// A path the agent names in backticks is something it is pointing the person at.
+const PATH_RE = /`((?:~|\/)[^`\s]*\/[^`\s]+)`/g;
+// What a viewer counts as "made": a page, a picture, a sound, a document. Code, config and
+// folders are how the work got done, and they already show as steps. Counting every file
+// written put a session's tooling in the "made" list (Gary, 2026-10-10: "This session
+// definitely didn't make all these files").
+const DELIVERABLE = /\.(md|pdf|docx?|pptx?|key|xlsx?|csv|html?|png|jpe?g|gif|webp|svg|heic|wav|mp3|m4a|aac|flac|mp4|mov|webm|epub)$/i;
+
+// Tools that are harness plumbing rather than work a viewer would recognize. They are not
+// shown; their time is carried into the next real step so the clock still adds up.
+const PLUMBING = new Set(['ToolSearch', 'EnterWorktree', 'ExitWorktree', 'TaskOutput', 'TaskStop', 'TodoWrite', 'ListAgents', 'ScheduleWakeup']);
+
+export function convert(lines, opts = {}) {
+  const home = opts.home ?? process.env.HOME ?? '';
+  const cuts = [];
+  const clean = cleaner(home, cuts);
+
+  const results = new Map();
+  const resultText = new Map();
+  const resultData = new Map();
+  for (const o of lines) {
+    if (o.type !== 'user') continue;
+    for (const b of blocks(o.message)) {
+      if (b.type !== 'tool_result') continue;
+      results.set(b.tool_use_id, Date.parse(o.timestamp));
+      resultText.set(b.tool_use_id, typeof b.content === 'string' ? b.content : (b.content ?? []).map((c) => c.text ?? '').join('\n'));
+      resultData.set(b.tool_use_id, o.toolUseResult);
+    }
+  }
+
+  const turns = [];
+  const chapters = [];
+  const artifacts = [];
+  const seenArtifact = new Map();
+  // Claude Code writes two title streams that alternate line by line: the session's name
+  // (custom-title) and an automatic one (ai-title). Chapters follow the name when the
+  // session has one, else the automatic title; mixing them flips the chapter every line.
+  const titleType = lines.some((o) => o.type === 'custom-title') ? 'custom-title' : 'ai-title';
+  let title = null;
+  let pendingTitle = null;
+  let cursor = null;
+  let carry = { ms: 0, idle: 0 };
+  let interrupted = false;
+  let start = null;
+  let raw = [];
+  let sessionId = null;
+
+  const addArtifact = (turn, a, at) => {
+    const key = a.path ?? a.url;
+    if (seenArtifact.has(key)) return;
+    const id = `a${artifacts.length + 1}`;
+    seenArtifact.set(key, id);
+    artifacts.push({ id, ...a, turn: turn.id, at });
+    turn.artifacts.push(id);
+  };
+  const flush = () => {
+    const t = turns[turns.length - 1];
+    if (carry.ms && raw.length) raw[raw.length - 1].ms += carry.ms;
+    if (t) t.steps = merge(raw);
+    raw = [];
+    carry = { ms: 0, idle: 0 };
+  };
+
+  for (const o of lines) {
+    if (o.isSidechain) continue;
+    sessionId ??= o.sessionId ?? null;
+    if (o.type === 'custom-title' || o.type === 'ai-title') {
+      if (o.type !== titleType) continue;
+      const t = o.customTitle ?? o.aiTitle;
+      if (t && t !== title) { title = t; pendingTitle = t; }
+      continue;
+    }
+    if (isInterrupt(o)) { interrupted = true; continue; }
+
+    if (isHuman(o)) {
+      flush();
+      const ts = Date.parse(o.timestamp);
+      start ??= ts;
+      cursor = ts;
+      const id = `t${turns.length + 1}`;
+      // A slash command arrives wrapped in tags; show it as the person typed it.
+      let raw = textOf(o.message);
+      const cmd = raw.match(/<command-name>([^<]+)<\/command-name>/);
+      if (cmd) raw = [cmd[1].trim(), raw.match(/<command-args>([^<]*)<\/command-args>/)?.[1].trim()].filter(Boolean).join(' ');
+      let text = clean(raw, id, 'human');
+      if (text.length > LONG_PASTE) {
+        cuts.push({ turn: id, what: 'human', reason: 'long paste collapsed' });
+        text = `${text.slice(0, PASTE_KEEP).trimEnd()} [pasted ${text.length} characters]`;
+      }
+      const pasted = blocks(o.message).filter((b) => b.type === 'image' && b.source?.type === 'base64' && b.source.data)
+        .map((b, n) => ({ id: `pasted-${id}-${n + 1}`, src: `data:${b.source.media_type ?? 'image/png'};base64,${b.source.data}`, caption: 'pasted by the operator' }));
+      turns.push({ id, at: ts - start, human: { text, via: o.promptSource === 'voice' ? 'spoken' : 'typed', choices: [], ...(pasted.length ? { images: pasted } : {}) }, intervention: interrupted ? 'redirect' : null, steps: [], replies: [], artifacts: [] });
+      if (pendingTitle) { chapters.push({ title: pendingTitle, turn: id }); pendingTitle = null; }
+      interrupted = false;
+      continue;
+    }
+
+    const turn = turns[turns.length - 1];
+    if (!turn || o.type !== 'assistant') continue;
+    // Usage limits and API errors are the harness talking, not the agent; they also carry the
+    // operator's plan and time zone.
+    if (o.isApiErrorMessage || blocks(o.message).some((b) => b.type === 'text' && HARNESS_NOTICE.test(b.text))) {
+      cuts.push({ turn: turn.id, what: 'reply', reason: 'harness notice dropped' });
+      continue;
+    }
+    interrupted = false;
+    const ts = Date.parse(o.timestamp);
+    for (const b of blocks(o.message)) {
+      if (b.type === 'text' && b.text.trim()) {
+        const text = clean(b.text.trim(), turn.id, 'reply');
+        turn.replies.push({ text, at: ts - start });
+        cursor = Math.max(cursor, ts);
+        for (const url of text.match(URL_RE) ?? []) addArtifact(turn, { kind: 'link', title: url.replace(/^https:\/\//, '').replace(/[.,;:]+$/, ''), url: url.replace(/[.,;:]+$/, '') }, ts - start);
+        for (const [, path] of text.matchAll(PATH_RE)) if (DELIVERABLE.test(path)) addArtifact(turn, { kind: 'file', title: base(path), path }, ts - start);
+      } else if (b.type === 'tool_use') {
+        // Real tools return in well under a second; the time goes to the agent thinking
+        // before it calls them. So a step owns the whole gap since the previous step ended.
+        const end = Math.max(results.get(b.id) ?? ts, ts);
+        const think = Math.max(0, ts - cursor);
+        const runFor = end - ts;
+        const stalled = timedOut(resultData.get(b.id), resultText.get(b.id));
+        const cap = b.name === 'AskUserQuestion' ? ASK_CAP : STEP_CAP;
+        const counted = stalled ? 0 : Math.min(Math.min(think, THINK_CAP) + runFor + carry.ms, cap);
+        const idleMs = think + runFor + carry.ms + carry.idle - counted;
+        const ms = counted;
+        cursor = end;
+        carry = { ms: 0, idle: 0 };
+        if (PLUMBING.has(b.name)) { carry = { ms, idle: idleMs }; continue; }
+        const { kind, label } = stepFor(b.name, b.input);
+        const step = { kind, label: clean(label, turn.id, 'step'), tool: b.name, ms, at: end - start };
+        if (idleMs > 1000) { step.idleMs = idleMs; cuts.push({ turn: turn.id, what: 'step', reason: 'idle time removed', ms: idleMs }); }
+        if (stalled) step.stalled = true;
+        if (b.name === 'AskUserQuestion') {
+          // The agent stopped and the person decided: the clearest human-in-the-loop moment a
+          // session has. The whole board is kept, as the person saw it, so a replay can draw it.
+          const ask = askBoard(b.input, resultData.get(b.id), resultText.get(b.id) ?? '', (t) => clean(t, turn.id, 'step'));
+          Object.assign(step, { kind: `ask:${b.id}`, label: ask.questions[0]?.question ? `asked: ${ask.questions[0].question}` : 'asked a question', ask });
+        }
+        raw.push(step);
+        if (b.name === 'Write' && DELIVERABLE.test(b.input?.file_path ?? '')) addArtifact(turn, { kind: 'file', title: base(b.input.file_path), path: clean(b.input.file_path, turn.id, 'artifact') }, ts - start);
+      }
+    }
+  }
+  flush();
+  if (turns.length === 0) throw new Error('no human turns in this session: nothing to draft');
+
+  const first = lines.find((o) => o.timestamp && !o.isSidechain);
+  // Where it ran, when the transcript can tell (or the caller knows); left out otherwise.
+  const device = opts.device ?? deviceFromSession(lines);
+  return {
+    format: FORMAT,
+    id: opts.id ?? `session-${(sessionId ?? 'unknown').slice(0, 8)}`,
+    title: opts.title ?? title ?? turns[0].human.text.slice(0, 60),
+    persona: { name: 'the operator', role: '', blurb: '', ...opts.persona },
+    source: { kind: 'session', sessionId, date: first ? first.timestamp.slice(0, 10) : null, illustrative: false },
+    ...(device ? { device } : {}),
+    chapters,
+    turns,
+    artifacts,
+    cuts,
+  };
+}
+
+// One AskUserQuestion call as the board the person saw: every question, every option, the
+// answer (the option's label, or what they typed in Other), and whether they closed it.
+function askBoard(input, data, text, clean) {
+  const dismissed = typeof data === 'string' ? /rejected/i.test(data) : /doesn't want to proceed|rejected/i.test(text) && !data?.answers;
+  const answers = data && typeof data === 'object' && data.answers ? data.answers : {};
+  const questions = (input?.questions ?? []).map((q) => {
+    let answer = dismissed ? null : answers[q.question] ?? null;
+    if (answer == null && !dismissed) {
+      const esc = q.question.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+      answer = text.match(new RegExp(`"${esc}"="([^"]*)"`))?.[1] ?? null;
+    }
+    const options = (q.options ?? []).map((o) => ({ label: clean(o.label ?? ''), description: clean(o.description ?? '') }));
+    const chosen = answer == null ? null : (q.options ?? []).findIndex((o) => o.label === answer);
+    return {
+      header: clean(q.header ?? ''),
+      question: clean(q.question ?? ''),
+      multiSelect: Boolean(q.multiSelect),
+      options,
+      answer: answer == null ? null : clean(answer),
+      chosen: chosen == null || chosen < 0 ? null : chosen,
+    };
+  });
+  return { questions, dismissed };
+}

package/src/device.mjs

@@ -0,0 +1,105 @@
+// Which device the demo is drawn in. Three inputs decide it: the mode (auto, or forced by the
+// embedder, the URL or the viewer's own switch), what the viewer is holding (a phone, or a
+// desktop or tablet), and where the real session ran (the scenario's optional `device`).
+//
+// On a phone the demo IS the phone, so nothing is drawn around it. On a desktop it sits in an
+// iPhone, or a MacBook when the session ran on a Mac or the MacBook is forced. A MacBook forced
+// on a phone is never a laptop shrunk into a phone: it is a desktop-style window at phone
+// width, with a label that stays on screen saying what is simulated.
+
+export const MODES = ['auto', 'iphone', 'macbook'];
+export const DEVICES = ['iphone', 'macbook'];
+export const LABELS = { iphone: 'Simulating an iPhone', macbook: 'Simulating a MacBook' };
+
+export function normalizeMode(v) {
+  const m = String(v ?? '').trim().toLowerCase();
+  return MODES.includes(m) ? m : 'auto';
+}
+
+// frame: 'none' | 'iphone' | 'macbook' | 'macbook-compact'; label: what is simulated, or null.
+export function resolveDevice({ mode, viewer, device } = {}) {
+  const m = normalizeMode(mode);
+  const recorded = DEVICES.includes(device) ? device : 'iphone';
+  if (viewer === 'phone') return m === 'macbook' ? { frame: 'macbook-compact', label: LABELS.macbook } : { frame: 'none', label: null };
+  const d = m === 'auto' ? recorded : m;
+  return { frame: d, label: LABELS[d] };
+}
+
+// What the viewer is holding, from capability signals rather than width alone: a phone is a
+// touch device whose primary pointer is coarse (or that cannot hover) AND whose shorter side
+// is phone-sized. A narrow desktop window still has a mouse; an iPad (including iPadOS, which
+// reports itself as a Mac with touch points) is wide enough to be treated as a desktop, and is
+// held like a phone only in a narrow split view.
+export const PHONE_MAX = 700;
+export function classifyViewer({ width, height, coarse = false, hoverNone = false, maxTouchPoints = 0 } = {}) {
+  const touchFirst = coarse || (maxTouchPoints > 0 && hoverNone);
+  if (!touchFirst || !Number.isFinite(width)) return 'desktop';
+  const shorter = Number.isFinite(height) ? Math.min(width, height) : width;
+  return shorter < PHONE_MAX && width < 1000 ? 'phone' : 'desktop';
+}
+
+// The browser's signals, read now. Safe to call anywhere; outside a browser it is a desktop.
+export function readViewer(w = typeof window === 'undefined' ? null : window) {
+  if (!w) return 'desktop';
+  const mq = (q) => Boolean(w.matchMedia?.(q).matches);
+  return classifyViewer({
+    width: w.innerWidth, height: w.innerHeight,
+    coarse: mq('(pointer: coarse)'), hoverNone: mq('(hover: none)'),
+    maxTouchPoints: w.navigator?.maxTouchPoints ?? 0,
+  });
+}
+
+// Calls back whenever the answer may have changed: resize, rotation, a pointer plugged in.
+export function watchViewer(onChange, w = typeof window === 'undefined' ? null : window) {
+  if (!w) return () => {};
+  const fire = () => onChange(readViewer(w));
+  const queries = ['(pointer: coarse)', '(hover: none)'].map((q) => w.matchMedia?.(q)).filter(Boolean);
+  w.addEventListener('resize', fire);
+  w.addEventListener('orientationchange', fire);
+  for (const q of queries) q.addEventListener?.('change', fire);
+  return () => {
+    w.removeEventListener('resize', fire);
+    w.removeEventListener('orientationchange', fire);
+    for (const q of queries) q.removeEventListener?.('change', fire);
+  };
+}
+
+// Where a real session ran, when its transcript can say. Typed into an interactive terminal,
+// or the desktop app, on a Mac: a MacBook. Remote Control and SDK sessions could be a phone or
+// a browser, so they stay unset (the player then shows an iPhone).
+export function deviceFromSession(lines) {
+  const human = lines.filter((o) => o?.type === 'user' && o.origin?.kind === 'human');
+  if (!human.length) return undefined;
+  const onMac = (o) => /^\/Users\//.test(o.cwd ?? '');
+  const desk = human.filter((o) => onMac(o) && ((o.entrypoint === 'cli' && ['typed', 'queued'].includes(o.promptSource)) || o.entrypoint === 'claude-desktop'));
+  return desk.length * 2 > human.length ? 'macbook' : undefined;
+}
+
+// What Auto resolved to, for the hint beside it on the switch.
+export function autoHint({ viewer, device } = {}) {
+  const { frame } = resolveDevice({ mode: 'auto', viewer, device });
+  return frame === 'macbook' ? 'MacBook' : frame === 'iphone' ? 'iPhone' : 'this phone';
+}
+
+// The toast after a tap on the device switch: what is shown now, and why.
+export function deviceToast({ mode, viewer, device } = {}) {
+  const m = normalizeMode(mode);
+  const mac = device === 'macbook';
+  const onMac = 'this session ran in Claude Code on a Mac';
+  if (viewer === 'phone') {
+    if (m === 'macbook') return 'Now simulating a MacBook, in a window at phone width.';
+    return `${m === 'auto' ? 'Auto' : 'iPhone'}: you're on a phone, so the demo is the phone.`;
+  }
+  if (m === 'auto') return mac ? `Auto: showing a MacBook because ${onMac}.` : "Auto: showing an iPhone because you're on a desktop.";
+  if (m === 'macbook') return `Now simulating a MacBook: ${mac ? onMac : 'this session actually ran on a phone'}.`;
+  return mac ? 'Now simulating an iPhone: this session actually ran on a Mac.' : 'Now simulating an iPhone.';
+}
+
+export function autoplayToast(on) {
+  return on ? 'Autoplay: the session plays itself.' : "You're the human now: tap to send each message and make each call.";
+}
+
+// After the viewer picks on a board: the real person's choice, which is where the replay goes.
+export function choiceToast(person, verdict) {
+  return verdict.same ? `Same call as ${person}.` : `In the real session, ${person} chose ${verdict.real}.`;
+}

package/src/embed.mjs

@@ -0,0 +1,45 @@
+// <supersuit-simulator>: the simulator as a tag, for a page or a book that wants it inline
+// rather than in an iframe. The page supplies React through an import map (or a bundler).
+//
+//   <supersuit-simulator src="/simulator/scenarios" scenario="low-tide-tapes"
+//                        artifacts="off" timeline="off" autoplay="off" height="620px" device="auto"
+//                        speed="3" highlights moments steps="1"></supersuit-simulator>
+//   <script type="module">import { defineSimulatorElement } from '@supersuit/session-player/embed'; defineSimulatorElement();</script>
+//
+// `src` returns a JSON array of scenarios (or one scenario). Image paths in it resolve against
+// the page, so serve the scenario's assets/ folder beside it. Any page that cannot run modules
+// can use the iframe instead: <iframe src="<served>/embed?scenario=<id>&timeline=off">.
+
+export function propsFromAttributes(a) {
+  return {
+    src: a.src,
+    scenarioId: a.scenario || undefined,
+    artifacts: a.artifacts !== 'off',
+    timeline: a.timeline !== 'off',
+    autoplay: a.autoplay !== 'off',
+    height: a.height || undefined,
+    device: a.device || undefined,
+    start: a.start || undefined,
+    // The highlights cut (Wilson, 0.3.0): speed="3" highlights moments steps="1".
+    speed: Number(a.speed) || undefined,
+    highlights: a.highlights != null && a.highlights !== 'off',
+    moments: a.moments != null && a.moments !== 'off',
+    maxSteps: Number(a.steps) || undefined,
+  };
+}
+
+export function defineSimulatorElement(name = 'supersuit-simulator') {
+  if (typeof customElements === 'undefined' || customElements.get(name)) return;
+  customElements.define(name, class extends HTMLElement {
+    async connectedCallback() {
+      const attrs = Object.fromEntries([...this.attributes].map((x) => [x.name, x.value]));
+      const { src, ...props } = propsFromAttributes(attrs);
+      const [{ createElement }, { createRoot }, { SimulatorPlayer }] = await Promise.all([import('react'), import('react-dom/client'), import('./player.mjs')]);
+      const data = await (await fetch(src, { credentials: 'same-origin' })).json();
+      const scenarios = Array.isArray(data) ? data : [data];
+      this.root = createRoot(this);
+      this.root.render(createElement(SimulatorPlayer, { scenarios, ...props }));
+    }
+    disconnectedCallback() { this.root?.unmount(); }
+  });
+}

package/src/index.mjs

@@ -0,0 +1,7 @@
+export { FORMAT, validate, INTERVENTIONS, VIA, ARTIFACT_KINDS, SOURCE_KINDS } from './scenario.mjs';
+export { convert, parseSession } from './convert.mjs';
+export { tidy } from './tidy.mjs';
+export { recast } from './recast.mjs';
+export { bundle } from './bundle.mjs';
+export { allImages } from './scenario.mjs';
+export { resolveDevice, classifyViewer, normalizeMode, deviceFromSession, MODES, DEVICES } from './device.mjs';

package/src/playback.mjs

@@ -0,0 +1,126 @@
+// Turns a scenario into something watchable. A real session runs for hours and hundreds of
+// steps; a viewer gives it minutes. Nothing here changes what happened: condensed steps keep
+// their total time and count, and every decision the person made stays visible.
+
+const isAsk = (s) => Boolean(s.ask);
+// Decisions and anything the person was shown always stay visible.
+const isKept = (s) => isAsk(s) || Boolean(s.images?.length);
+
+export function condense(steps, max = 5) {
+  if (steps.length <= max + 1) return steps;
+  const keep = new Set(
+    steps.map((s, i) => [s, i]).filter(([s]) => !isKept(s)).sort((a, b) => b[0].ms - a[0].ms).slice(0, max).map(([, i]) => i),
+  );
+  const out = [];
+  let group = null;
+  steps.forEach((s, i) => {
+    if (keep.has(i) || isKept(s)) {
+      if (group) out.push(group);
+      group = null;
+      out.push(s);
+      return;
+    }
+    group ??= { label: '', tool: 'group', ms: 0, count: 0, group: true, at: s.at };
+    group.ms += s.ms;
+    group.count += s.count ?? 1;
+    group.at = s.at;
+  });
+  if (group) out.push(group);
+  for (const s of out) if (s.group) s.label = `${s.count} quick step${s.count === 1 ? '' : 's'}`;
+  return out;
+}
+
+// Playback time for a step, from its real time: log-scaled so a seven-minute download reads
+// as longer than a two-second read without making anyone wait seven minutes.
+export function pace(ms) {
+  return Math.round(Math.min(1600, 280 + 300 * Math.log10(1 + ms / 1000)));
+}
+
+export function duration(ms) {
+  if (ms < 1000) return 'under a second';
+  const s = Math.round(ms / 1000);
+  if (s < 60) return `${s} s`;
+  const m = Math.round(ms / 60000);
+  if (m < 60) return `${m} min`;
+  const h = Math.floor(ms / 3600000);
+  const rest = Math.round((ms - h * 3600000) / 60000);
+  return rest ? `${h} h ${rest} min` : `${h} h`;
+}
+
+export function summarize(sc) {
+  const all = sc.turns.flatMap((t) => t.steps);
+  return {
+    commands: sc.turns.length,
+    steps: all.filter((s) => !isAsk(s)).reduce((n, s) => n + (s.count ?? 1), 0),
+    agentMs: all.filter((s) => !isAsk(s)).reduce((n, s) => n + s.ms, 0),
+    decisions: all.filter(isAsk).length,
+    redirects: sc.turns.filter((t) => t.intervention).length,
+    artifacts: (sc.artifacts ?? []).length,
+    idleMs: all.reduce((n, s) => n + (s.idleMs ?? 0), 0),
+    decisionMs: all.filter(isAsk).reduce((n, s) => n + s.ms, 0),
+  };
+}
+
+// One entry per turn: the command the viewer sends, then the events that follow it in the
+// order they really happened, each with a playback offset `t`. `length` is the turn's
+// playback time.
+// A reply's first paragraph is its answer (the house style leads with it), so a highlights
+// cut can show only that and give the viewer time to read it rather than a fixed beat.
+export function lead(text) {
+  return String(text).split(/\n\s*\n/)[0].trim();
+}
+export function readMs(text) {
+  const words = String(text).trim().split(/\s+/).filter(Boolean).length;
+  return Math.max(900, Math.min(2800, 600 + 50 * words));
+}
+
+export function script(sc, { maxSteps = 5, speed = 1, leadOnly = false } = {}) {
+  const byId = new Map((sc.artifacts ?? []).map((a) => [a.id, a]));
+  return sc.turns.map((turn) => {
+    const steps = condense(turn.steps, maxSteps);
+    const items = [
+      ...steps.map((s) => ({ kind: 'step', real: s.at ?? turn.at, step: s })),
+      // A highlight shows where the turn landed: its last answer, not the progress notes before it.
+      ...(leadOnly ? [turn.replies[turn.highlight ?? turn.replies.length - 1]].filter(Boolean) : turn.replies).map((r) => ({ kind: 'reply', real: r.at, reply: leadOnly ? { ...r, text: lead(r.text) } : r })),
+      ...turn.artifacts.map((id) => byId.get(id)).filter(Boolean).map((a) => ({ kind: 'artifact', real: a.at ?? turn.at, artifact: a })),
+    ].map((e, i) => ({ ...e, i }));
+    // Stable by real time; within one instant, steps before replies before artifacts.
+    const rank = { step: 0, reply: 1, artifact: 2 };
+    items.sort((a, b) => a.real - b.real || rank[a.kind] - rank[b.kind] || a.i - b.i);
+    let t = 0;
+    const events = items.map(({ i, ...e }) => {
+      const at = t;
+      // speed shortens the work; reading time in a highlights cut is never sped up.
+      t += e.kind === 'step' ? Math.round(pace(e.step.ms) / speed) : e.kind === 'reply' ? (leadOnly ? readMs(e.reply.text) : Math.round(900 / speed)) : Math.round(500 / speed);
+      return { ...e, t: at };
+    });
+    return { id: turn.id, command: { text: turn.human.text, intervention: turn.intervention, images: turn.human.images }, events, length: t };
+  });
+}
+
+// What the person really did on one question of a board.
+export function realPick(q, dismissed) {
+  if (dismissed) return { kind: 'dismissed', index: null, label: 'closed it and typed instead' };
+  if (q.chosen != null) return { kind: 'option', index: q.chosen, label: q.options[q.chosen]?.label ?? q.answer };
+  return { kind: 'other', index: null, label: q.answer ?? '' };
+}
+
+// The viewer's pick against the real one. A recording has one path, so a different pick is
+// answered with what really happened, never with an invented branch.
+export function compare(q, dismissed, pick) {
+  const real = realPick(q, dismissed);
+  const same = pick.kind === real.kind && (real.kind !== 'option' || pick.index === real.index);
+  return { same, real: real.label };
+}
+
+// Frames for "saying" a command: words appear the way dictation lands, ending on the whole
+// command. Long pastes advance in larger jumps so no command takes more than ~40 frames.
+export function dictate(text) {
+  const words = String(text).trim().split(/\s+/).filter(Boolean);
+  if (!words.length) return [''];
+  const step = Math.max(1, Math.ceil(words.length / 40));
+  const frames = [];
+  for (let n = step; n < words.length; n += step) frames.push(words.slice(0, n).join(' '));
+  frames.push(String(text).trim());
+  return frames;
+}