@supersuit/session-player 0.0.0-stage → 0.4.0

package/src/scenario.mjs

@@ -0,0 +1,80 @@
+// The scenario format: one persona, the commands they give, the work that follows, the
+// artifacts it makes, every moment they stepped in, and a record of every cut. The player
+// reads this and nothing else, so a scenario that validates is one the player can show.
+
+export const FORMAT = 'supersuit-simulator/1';
+export const INTERVENTIONS = [null, 'redirect', 'correct', 'approve', 'decide'];
+export const VIA = ['typed', 'spoken', 'tapped'];
+// `other`: something real that has no file or link, like a release submitted to a store.
+export const ARTIFACT_KINDS = ['file', 'link', 'other'];
+export const SOURCE_KINDS = ['session', 'persona'];
+// Where the real session ran, when known. Optional: a scenario without it is shown as an iPhone.
+export const SCENARIO_DEVICES = ['iphone', 'macbook'];
+
+const isObj = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const isStr = (v) => typeof v === 'string' && v.length > 0;
+const isMs = (v) => Number.isFinite(v) && v >= 0;
+
+export function validate(s) {
+  if (!isObj(s)) return ['scenario must be an object'];
+  const p = [];
+  if (s.format !== FORMAT) p.push(`format must be ${FORMAT}, got ${JSON.stringify(s.format)}`);
+  for (const k of ['id', 'title']) if (!isStr(s[k])) p.push(`${k} is required`);
+  if (!isObj(s.persona) || !isStr(s.persona.name)) p.push('persona.name is required');
+  if (!isObj(s.source) || !SOURCE_KINDS.includes(s.source.kind)) p.push(`source.kind must be one of ${SOURCE_KINDS.join(', ')}`);
+  if (s.device != null && !SCENARIO_DEVICES.includes(s.device)) p.push(`device must be one of ${SCENARIO_DEVICES.join(', ')}, got ${JSON.stringify(s.device)}`);
+
+  const artifactIds = new Set();
+  for (const a of s.artifacts ?? []) {
+    if (!isStr(a.id)) { p.push('an artifact has no id'); continue; }
+    if (artifactIds.has(a.id)) p.push(`duplicate artifact id ${a.id}`);
+    artifactIds.add(a.id);
+    if (!ARTIFACT_KINDS.includes(a.kind)) p.push(`artifact ${a.id}: kind must be one of ${ARTIFACT_KINDS.join(', ')}`);
+    if (!isStr(a.title)) p.push(`artifact ${a.id}: title is required`);
+  }
+
+  const turns = Array.isArray(s.turns) ? s.turns : [];
+  if (turns.length === 0) p.push('a scenario needs at least one turn');
+  const turnIds = new Set();
+  for (const t of turns) {
+    const id = t?.id ?? '?';
+    if (turnIds.has(id)) p.push(`duplicate turn id ${id}`);
+    turnIds.add(id);
+    if (!isMs(t.at)) p.push(`turn ${id}: at must be a non-negative number of ms`);
+    if (!isObj(t.human) || !isStr(t.human.text)) p.push(`turn ${id}: human.text is required`);
+    else if (!VIA.includes(t.human.via)) p.push(`turn ${id}: human.via must be one of ${VIA.join(', ')}`);
+    if (!INTERVENTIONS.includes(t.intervention)) p.push(`turn ${id}: intervention must be one of ${INTERVENTIONS.map(String).join(', ')}`);
+    for (const st of t.steps ?? []) {
+      if (!isStr(st.label)) p.push(`turn ${id}: a step has no label`);
+      if (!isMs(st.ms)) p.push(`turn ${id}: step "${st.label}" ms must be a non-negative number`);
+    }
+    for (const a of t.artifacts ?? []) if (!artifactIds.has(a)) p.push(`turn ${id}: unknown artifact ${a}`);
+  }
+  for (const c of s.chapters ?? []) if (!turnIds.has(c.turn)) p.push(`chapter "${c.title}" points at unknown turn ${c.turn}`);
+  if (s.close != null) {
+    // The close card says only what was measured: an edge block is the counter's output, so
+    // its parts must add up to its total, and nothing in it is an estimate.
+    if (!isObj(s.close)) p.push('close must be an object');
+    else if (s.close.edge) {
+      const L = s.close.edge.layers ?? {};
+      const sum = ['fueled', 'encoded', 'built', 'retired'].reduce((n, k) => n + (Number(L[k]) || 0), 0);
+      if (sum !== s.close.edge.total) p.push(`close: edge total ${s.close.edge.total} is not the sum of its four counts (${sum})`);
+    }
+  }
+  for (const img of allImages(s)) if (!isStr(img.src) || !isStr(img.id)) p.push(`an image is missing its id or src (${JSON.stringify(img).slice(0, 80)})`);
+  return p;
+}
+
+// Every image a scenario carries, wherever it sits: pasted with a command, shown on a step,
+// or on one option of a board. One walker so tidy, recast, bundle and validate agree.
+export function allImages(s) {
+  const out = [];
+  for (const t of s.turns ?? []) {
+    out.push(...(t.human?.images ?? []));
+    for (const st of t.steps ?? []) {
+      out.push(...(st.images ?? []));
+      for (const q of st.ask?.questions ?? []) for (const o of q.options ?? []) if (o.image) out.push(o.image);
+    }
+  }
+  return out;
+}

package/src/serve.mjs

@@ -0,0 +1,57 @@
+// A small local server for watching scenarios in a browser: the player page, the scenarios,
+// and the player's own modules. React loads from esm.sh, so the page needs no build.
+// Local and tailnet viewing only; a public page serves scenarios through a gated route.
+
+import { createServer as httpServer } from 'node:http';
+import { readFileSync, readdirSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
+
+const SRC = fileURLToPath(new URL('.', import.meta.url));
+
+export function page({ title = 'Supersuit Session demo', embed = false, react = 'https://esm.sh/react@19', reactDom = 'https://esm.sh/react-dom@19/client?deps=react@19' } = {}) {
+  // The embed page is bare (no margin, transparent) so an <iframe> in any page or book shows
+  // only the simulator; its switches come from the iframe's query string.
+  const body = embed ? 'html,body{margin:0;padding:0;background:transparent}body{margin:0;padding:0;background:transparent}' : 'html,body{margin:0;background:#F6E7C5}body{padding:16px 12px}@media(max-width:480px){body{padding:8px 6px}}';
+  return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover">
+<title>${title}</title>
+<meta property="og:title" content="${title}">
+<meta property="og:description" content="Step into someone's day and watch the work get done.">
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link href="https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..144,600&display=swap" rel="stylesheet">
+<script type="importmap">{"imports":{"react":"${react}","react-dom/client":"${reactDom}"}}</script>
+<style>${body}</style>
+</head><body><div id="root"></div>
+<script type="module">
+import { createElement as h } from 'react';
+import { createRoot } from 'react-dom/client';
+import { SimulatorPlayer } from './src/player.mjs';
+const scenarios = await (await fetch('./scenarios.json')).json();
+const q = new URLSearchParams(location.search);
+createRoot(document.getElementById('root')).render(h(SimulatorPlayer, {
+  scenarios, scenarioId: q.get('scenario') ?? undefined, height: q.get('height') ?? undefined, autoplay: q.get('autoplay') !== 'off', artifacts: q.get('artifacts') !== 'off', timeline: q.get('timeline') !== 'off', device: q.get('device') ?? undefined, start: q.get('start') ?? undefined, speed: Number(q.get('speed')) || undefined, highlights: q.has('highlights'), moments: q.has('moments'), maxSteps: Number(q.get('steps')) || undefined,
+}));
+</script></body></html>`;
+}
+
+export function createServer({ scenarios, assetsRoot }) {
+  const modules = new Set(readdirSync(SRC).filter((f) => f.endsWith('.mjs')));
+  return httpServer((req, res) => {
+    const path = new URL(req.url, 'http://x').pathname;
+    const send = (code, type, body) => { res.writeHead(code, { 'content-type': type, 'cache-control': 'no-store' }); res.end(body); };
+    if (path === '/' || path === '/index.html') return send(200, 'text/html; charset=utf-8', page({ title: scenarios.length === 1 ? scenarios[0].title : undefined }));
+    if (path === '/embed') return send(200, 'text/html; charset=utf-8', page({ embed: true }));
+    if (path === '/scenarios.json') return send(200, 'application/json', JSON.stringify(scenarios));
+    const a = assetsRoot && path.match(/^\/assets\/([\w-]+)\/([\w.-]+\.(?:png|jpe?g|webp|gif))$/i);
+    if (a) {
+      const file = join(assetsRoot, 'assets', a[1], a[2]);
+      const type = { png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', webp: 'image/webp', gif: 'image/gif' }[a[2].split('.').pop().toLowerCase()];
+      try { return send(200, type, readFileSync(file)); } catch { return send(404, 'text/plain', 'not found'); }
+    }
+    const m = path.match(/^\/src\/([\w-]+\.mjs)$/);
+    if (m && modules.has(m[1])) return send(200, 'text/javascript; charset=utf-8', readFileSync(join(SRC, m[1])));
+    return send(404, 'text/plain', 'not found');
+  });
+}

package/src/tidy.mjs

@@ -0,0 +1,105 @@
+// Cleans what the person typed for display, without putting words in their mouth.
+//
+// People type fast to an agent: "ckise" for close, "simkltaneouslf". A viewer should read
+// what they meant, so a reviewer (a person, or the promote skill's agent) hands in fixes.
+// The guard is what keeps this honest: a fix may correct spelling and punctuation, never
+// rewrite the command, so any fix that moves too far from the original is refused. The
+// original stays in `human.raw` and every change is recorded in `cuts`.
+
+const MAX_CHANGE = 0.45;
+
+// Screenshot and image paths in a command mean "this picture"; the path itself is noise
+// and can leak a username or a temp folder.
+const IMAGE_PATH = /(['"]?)(?:~|\/)[^'"\n]*?\.(?:png|jpe?g|gif|heic|webp)\1/gi;
+
+function distance(a, b) {
+  const prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    let diag = prev[0];
+    prev[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const up = prev[j];
+      prev[j] = Math.min(prev[j] + 1, prev[j - 1] + 1, diag + (a[i - 1] === b[j - 1] ? 0 : 1));
+      diag = up;
+    }
+  }
+  return prev[b.length];
+}
+
+export function tidy(scenario, fixes = {}) {
+  const sc = structuredClone(scenario);
+  const { artifacts: curation, images, close, ...textFixes } = fixes;
+  fixes = textFixes;
+  const ids = new Set(sc.turns.map((t) => t.id));
+  for (const id of Object.keys(fixes)) if (!ids.has(id)) throw new Error(`fix for unknown turn ${id}`);
+  if (curation) curate(sc, curation, ids);
+  if (images) attach(sc, images);
+  // The close card's facts come from tools, not from the reviewer's memory: `edge` is
+  // end-a-session's edge-earned output for this session, `freed` a catalog row.
+  if (close) sc.close = close;
+  for (const t of sc.turns) {
+    const original = t.human.raw ?? t.human.text;
+    let text = t.human.text.replace(IMAGE_PATH, () => {
+      sc.cuts.push({ turn: t.id, what: 'human', reason: 'local path replaced' });
+      return '[screenshot]';
+    });
+    const fix = fixes[t.id];
+    if (fix != null) {
+      const base = text.toLowerCase();
+      const ratio = distance(base, fix.toLowerCase()) / Math.max(base.length, 1);
+      // Very short commands ("ckise" -> "close") change a large share by nature; allow two edits.
+      if (ratio > MAX_CHANGE && distance(base, fix.toLowerCase()) > 2) throw new Error(`fix for ${t.id} changes too much of what was said (${Math.round(ratio * 100)}%): fix spelling, do not rewrite`);
+      if (fix !== text) sc.cuts.push({ turn: t.id, what: 'human', reason: 'typo fixed' });
+      text = fix;
+    }
+    if (text !== t.human.text) { t.human.raw = original; t.human.text = text; }
+  }
+  return sc;
+}
+
+// The transcript cannot see everything a session made (a release submitted through a web
+// form leaves no link) and sometimes names things that were not made. The reviewer decides.
+function curate(sc, { drop = [], add = [] }, turnIds) {
+  for (const id of drop) {
+    if (!sc.artifacts.some((a) => a.id === id)) throw new Error(`cannot drop unknown artifact ${id}`);
+    sc.artifacts = sc.artifacts.filter((a) => a.id !== id);
+    for (const t of sc.turns) t.artifacts = t.artifacts.filter((a) => a !== id);
+    sc.cuts.push({ turn: null, what: id, reason: 'artifact dropped by reviewer' });
+  }
+  let n = sc.artifacts.reduce((m, a) => Math.max(m, Number(a.id.replace(/\D/g, '')) || 0), 0);
+  for (const a of add) {
+    if (!turnIds.has(a.turn)) throw new Error(`artifact "${a.title}" names unknown turn ${a.turn}`);
+    const id = `a${++n}`;
+    const turn = sc.turns.find((t) => t.id === a.turn);
+    sc.artifacts.push({ id, ...a, at: a.at ?? turn.at });
+    turn.artifacts.push(id);
+    sc.cuts.push({ turn: a.turn, what: id, reason: 'artifact added by reviewer' });
+  }
+}
+
+// What the person saw is often an image the transcript only names through a loop variable
+// (covers opened in Preview, a comparison sheet in a temp folder), so the reviewer points at
+// it: on a step ("step": part of its label), on a board option ("question" + "option"), or on
+// the command itself ("human": true). Matching is by substring, and a miss is refused.
+function attach(sc, images) {
+  for (const img of images) {
+    const turn = sc.turns.find((t) => t.id === img.turn);
+    if (!turn) throw new Error(`image ${img.id} names unknown turn ${img.turn}`);
+    const entry = { id: img.id, src: img.src, ...(img.caption ? { caption: img.caption } : {}) };
+    if (img.human) { (turn.human.images ??= []).push(entry); continue; }
+    if (img.question) {
+      const step = turn.steps.find((s) => s.ask?.questions.some((q) => q.question.includes(img.question)));
+      const q = step?.ask.questions.find((qq) => qq.question.includes(img.question));
+      if (!q) throw new Error(`no question matching "${img.question}" in ${img.turn}`);
+      if (img.option) {
+        const o = q.options.find((oo) => oo.label.includes(img.option));
+        if (!o) throw new Error(`no option matching "${img.option}" in "${q.question.slice(0, 40)}"`);
+        o.image = entry;
+      } else (step.images ??= []).push(entry);
+      continue;
+    }
+    const step = turn.steps.find((s) => s.label.includes(img.step ?? '\u0000'));
+    if (!step) throw new Error(`no step matching "${img.step}" in ${img.turn}`);
+    (step.images ??= []).push(entry);
+  }
+}