creator-editing-studio 1.2.0 → 1.2.2

package/template/scripts/takes.mjs

@@ -0,0 +1,424 @@
+#!/usr/bin/env node
+/**
+ * Best-take selection: one messy take in, one clean cut plan out.
+ *
+ *   npm run takes -- <words.json> [--media <video>] [--script <script.md>]
+ *                    [--project <name>] [--out <file>] [--fps 30]
+ *                    [--similar 0.72] [--window 90] [--gap-max 0.6] [--gap-keep 0.25]
+ *
+ * WHAT IT IS FOR. A talking head is full of second attempts. Somebody fumbles, stops, says the
+ * sentence again, and both versions end up in the cut — so a human watches the whole thing to
+ * find them. This finds them instead, keeps the better one, and proves afterwards that none are
+ * left.
+ *
+ * THE SPEECH IS THE TRUTH, NOT THE SCRIPT. An earlier version of this file anchored to the
+ * written script: every script sentence got one span and anything unmatched was dropped. It
+ * threw away six passages of real material on the first take it was pointed at — lines the
+ * speaker improvised on the day and meant to keep, including "you don't have to put the brief
+ * into the brief file". A repeat that survives is visible and fixable; a good line silently
+ * deleted is neither. So the default here is inverted:
+ *
+ *     KEEP EVERYTHING, UNLESS IT IS A SECOND ATTEMPT AT SOMETHING ELSE THAT IS KEPT.
+ *
+ * Nothing has to justify its existence. A script, if there is one, is only a checker: it reports
+ * lines that never got said and breaks ties between close takes. It can never remove anything,
+ * and most people filming to camera do not have one.
+ *
+ * WHAT IT WRITES  work/<project>/<stem>.takes.json
+ *   keep[]      {from, to, units}  source seconds to use, in order
+ *   groups[]    every retake cluster, which attempt won and why the others lost
+ *   dropped[]   what went, with the reason
+ *   checks{}    verification, all of which must pass
+ */
+import {existsSync, mkdirSync, readFileSync, writeFileSync} from 'node:fs';
+import {basename, dirname, join} from 'node:path';
+import {decodePcm} from './lib/media.mjs';
+
+/* ------------------------------------------------------------------------ args */
+
+const args = process.argv.slice(2);
+const flag = (name, fallback) => {
+  const i = args.indexOf(`--${name}`);
+  return i === -1 ? fallback : args[i + 1];
+};
+const positional = args.filter((a, i) => !a.startsWith('--') && !String(args[i - 1] ?? '').startsWith('--'));
+
+const wordsPath = positional[0];
+if (!wordsPath) {
+  console.error('usage: npm run takes -- <words.json> [--media <video>] [--script <script.md>]');
+  process.exit(1);
+}
+
+const FPS = Number(flag('fps', 30));
+/** How alike two passages must be before they count as attempts at the same thing. */
+const SIMILAR = Number(flag('similar', 0.72));
+/** Retakes happen close together. Two matching sentences minutes apart are both wanted. */
+const WINDOW = Number(flag('window', 90));
+/** A silence longer than this is dead air and gets collapsed. */
+const GAP_MAX = Number(flag('gap-max', 0.6));
+/** ...down to this. Not zero: speech with every gap removed sounds like a machine. */
+const GAP_KEEP = Number(flag('gap-keep', 0.25));
+/**
+ * Breathing room kept either side of a kept passage.
+ *
+ * 150ms, not the 60 an earlier version used. Below about 120 the cut lands close enough to the
+ * first phoneme to clip it, and the join reads as abrupt even when every word is intact.
+ */
+const PAD = 0.15;
+
+/* ------------------------------------------------------------------- the words */
+
+const key = (t) => t.toLowerCase().replace(/['‘’]/g, '').replace(/[^a-z0-9]/g, '');
+
+const words = JSON.parse(readFileSync(wordsPath, 'utf8')).words.filter((w) => w.start != null && w.end != null);
+if (words.length < 10) {
+  console.error('Not enough timed words to work with.');
+  process.exit(1);
+}
+
+/**
+ * Cues that announce a retake out loud.
+ *
+ * When someone says one of these, the passage BEFORE it was abandoned — they are telling you so.
+ * Cheaper and more certain than any similarity measure.
+ */
+const RESTART_CUES = [
+  'let me redo that', 'let me try that again', 'one more time', 'sorry let me',
+  'can i do that again', 'take two', 'scratch that', 'let me say that again',
+  'start again', 'i will say that again',
+];
+
+/* --------------------------------------------------------------- units of speech
+ * A unit is one spoken thought: it ends where the speaker put a full stop, or where they left a
+ * gap long enough to be a boundary rather than a breath. Working in units rather than fixed word
+ * counts means a retake is compared against the whole thought it replaced. */
+
+const units = [];
+{
+  let start = 0;
+  for (let i = 0; i < words.length; i++) {
+    const w = words[i];
+    const next = words[i + 1];
+    const gapAfter = next ? next.start - w.end : Infinity;
+    const endsSentence = /[.?!]$/.test(w.word);
+    if (endsSentence || gapAfter > 0.7 || i === words.length - 1) {
+      const span = words.slice(start, i + 1);
+      if (span.length) {
+        units.push({
+          index: units.length,
+          startIndex: start,
+          endIndex: i,
+          from: span[0].start,
+          to: span[span.length - 1].end,
+          text: span.map((x) => x.word).join(' '),
+          keys: span.map((x) => key(x.word)).filter(Boolean),
+          confidence: span.reduce((a, x) => a + (x.score ?? 0.8), 0) / span.length,
+          complete: endsSentence,
+          worstGap: span.slice(1).reduce((m, x, k) => Math.max(m, x.start - span[k].end), 0),
+        });
+      }
+      start = i + 1;
+    }
+  }
+}
+
+/* -------------------------------------------------------------- energy and pace */
+
+/**
+ * Loudness per unit, so a flat read can lose to a committed one.
+ *
+ * Optional: without --media there is no audio to measure and the score simply does without it,
+ * rather than the tool refusing to run.
+ */
+let rmsOf = () => null;
+const mediaPath = flag('media', null);
+if (mediaPath && existsSync(mediaPath)) {
+  const RATE = 22050;
+  const pcm = decodePcm(mediaPath, RATE);
+  if (pcm) {
+    rmsOf = (from, to) => {
+      const a = Math.max(0, Math.floor(from * RATE));
+      const b = Math.min(pcm.length, Math.ceil(to * RATE));
+      if (b <= a) return null;
+      let sum = 0;
+      for (let i = a; i < b; i++) sum += pcm[i] * pcm[i];
+      return Math.sqrt(sum / (b - a));
+    };
+  }
+}
+
+for (const u of units) {
+  u.seconds = u.to - u.from;
+  u.wordsPerSecond = u.keys.length / Math.max(0.3, u.seconds);
+  u.rms = rmsOf(u.from, u.to);
+}
+
+const median = (xs) => {
+  const s = xs.filter((x) => x != null).sort((a, b) => a - b);
+  return s.length ? s[Math.floor(s.length / 2)] : null;
+};
+const medianRms = median(units.map((u) => u.rms));
+const medianPace = median(units.map((u) => u.wordsPerSecond)) ?? 3;
+
+/* ------------------------------------------------------------------ similarity */
+
+/** Longest common subsequence length — tolerant of an inserted stumble or a swapped word. */
+const lcs = (a, b) => {
+  const prev = new Array(b.length + 1).fill(0);
+  const cur = new Array(b.length + 1).fill(0);
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      cur[j] = a[i - 1] === b[j - 1] ? prev[j - 1] + 1 : Math.max(prev[j], cur[j - 1]);
+    }
+    for (let j = 0; j <= b.length; j++) prev[j] = cur[j];
+  }
+  return prev[b.length];
+};
+
+/**
+ * How alike two units are, measured against the SHORTER one.
+ *
+ * Against the shorter, because an abandoned start — "so the main reason, so the main reason is
+ * that…" — is a short fragment entirely contained in the full attempt. Measured against the
+ * longer it would score low and be kept; against the shorter it scores 1.0 and is correctly
+ * recognised as the same thought, begun twice.
+ */
+const similarity = (a, b) => {
+  if (!a.keys.length || !b.keys.length) return 0;
+  const shorter = Math.min(a.keys.length, b.keys.length);
+  // Short units match each other on function words alone — "give it three things" against
+  // "this is the time you give it that" shares "give it" and scores 0.5 on a four-word unit.
+  // Below five words there is not enough signal to call anything a retake.
+  if (shorter < 5) return 0;
+  const overlap = lcs(a.keys, b.keys);
+  // And the overlap has to be real words, not two articles and a pronoun.
+  if (overlap < 4) return 0;
+  return overlap / shorter;
+};
+
+/* ---------------------------------------------------------------------- groups */
+
+const groupOf = new Array(units.length).fill(-1);
+const groups = [];
+
+/**
+ * Grouping is against a representative, never transitive.
+ *
+ * Chaining members together — A matches B, B matches C, so group them all — merges passages that
+ * have nothing to do with each other as soon as one ambiguous unit sits between them. It put
+ * "give it three things" in the same group as "they just won't really feel like you". A unit
+ * joins a group only if it is similar to that group's FIRST member, which keeps a group to one
+ * thought said more than once.
+ */
+for (let i = 0; i < units.length; i++) {
+  if (groupOf[i] !== -1) continue;
+  const members = [i];
+  for (let j = i + 1; j < units.length; j++) {
+    if (groupOf[j] !== -1) continue;
+    if (units[j].from - units[i].to > WINDOW) break;
+    if (similarity(units[i], units[j]) < SIMILAR) continue;
+    members.push(j);
+  }
+  if (members.length < 2) continue;
+  groups.push({members});
+  for (const m of members) groupOf[m] = groups.length - 1;
+}
+
+/** A spoken cue abandons whatever came immediately before it. */
+const abandoned = new Set();
+for (const u of units) {
+  const flat = u.keys.join(' ');
+  if (!RESTART_CUES.some((c) => flat.includes(c.replace(/[^a-z0-9 ]/g, '')))) continue;
+  const prev = units[u.index - 1];
+  if (prev) abandoned.add(prev.index);
+}
+
+/* --------------------------------------------------------------------- scoring */
+
+/**
+ * One number per attempt.
+ *
+ * Completeness dominates — a finished sentence beats a smoother fragment every time. Everything
+ * else nudges. The tie-break at the end is deliberate and matches how people actually record:
+ * they repeat a line until they are happy, so the last attempt is usually the keeper.
+ */
+const score = (u) => {
+  let s = 0;
+  s += u.complete ? 6 : 0;
+  s += Math.min(u.keys.length / 12, 1) * 3;
+  s += u.confidence * 2;
+  s -= Math.max(0, u.worstGap - 0.45) * 3;
+  if (abandoned.has(u.index)) s -= 20;
+  // Pace: too fast reads as rushed, too slow as laboured. Either direction costs the same.
+  s -= Math.min(2, Math.abs(u.wordsPerSecond - medianPace) / Math.max(0.8, medianPace) * 2);
+  // Energy, only when there was audio to measure.
+  if (u.rms != null && medianRms) s += Math.max(-1.5, Math.min(1.5, (u.rms / medianRms - 1) * 2));
+  return s;
+};
+
+for (const u of units) u.score = score(u);
+
+/* ------------------------------------------------------- optional script checker
+ * A script never removes anything. It reports lines that were never said, and nudges a tie
+ * toward whichever attempt is closest to what was written. */
+
+const scriptPath = flag('script', null);
+let scriptMissing = [];
+if (scriptPath && existsSync(scriptPath)) {
+  const raw = readFileSync(scriptPath, 'utf8');
+  const body = /^---\s*$/m.test(raw) ? raw.split(/^---\s*$/m).slice(1).join('\n') : raw;
+  const lines = body
+    .replace(/<!--[\s\S]*?-->/g, '')
+    .replace(/^#.*$/gm, '')
+    .replace(/`[^`]*`/g, ' ')
+    .split(/(?<=[.?!])\s+/)
+    .map((s) => s.replace(/\s+/g, ' ').trim())
+    .filter((s) => s.split(/\s+/).length >= 4);
+
+  for (const line of lines) {
+    const lk = line.split(/\s+/).map(key).filter(Boolean);
+    const best = Math.max(0, ...units.map((u) => lcs(lk, u.keys) / Math.max(1, lk.length)));
+    if (best < 0.6) scriptMissing.push({text: line, bestMatch: Number(best.toFixed(2))});
+  }
+  // Closest-to-script wins a close call, but only by a little.
+  for (const g of groups) {
+    for (const m of g.members) {
+      const u = units[m];
+      const best = Math.max(0, ...lines.map((l) => lcs(l.split(/\s+/).map(key).filter(Boolean), u.keys) / Math.max(1, u.keys.length)));
+      u.score += best * 1.2;
+    }
+  }
+}
+
+/* ----------------------------------------------------------------- the decision */
+
+const drop = new Set();
+const groupReport = [];
+
+for (const g of groups) {
+  const members = [...new Set(g.members)].sort((a, b) => a - b);
+  let winner = members[0];
+  for (const m of members) {
+    const a = units[m];
+    const b = units[winner];
+    // Within a hair of each other, the later one wins.
+    if (a.score > b.score + 0.3 || (Math.abs(a.score - b.score) <= 0.3 && a.from > b.from)) winner = m;
+  }
+  for (const m of members) if (m !== winner) drop.add(m);
+  groupReport.push({
+    kept: {at: Number(units[winner].from.toFixed(2)), text: units[winner].text.slice(0, 90), score: Number(units[winner].score.toFixed(2))},
+    dropped: members.filter((m) => m !== winner).map((m) => ({
+      at: Number(units[m].from.toFixed(2)),
+      text: units[m].text.slice(0, 90),
+      score: Number(units[m].score.toFixed(2)),
+    })),
+  });
+}
+for (const i of abandoned) drop.add(i);
+
+const kept = units.filter((u) => !drop.has(u.index));
+
+/* ------------------------------------------------------------- building the plan
+ * Consecutive survivors become one span, so the cut is not chopped at every sentence. A gap
+ * between spans is collapsed only when it is longer than a breath — and a pause in front of a
+ * short line is usually deliberate, so those are left alone. */
+
+const keep = [];
+for (const u of kept) {
+  const last = keep[keep.length - 1];
+  if (last && u.startIndex === last.endIndex + 1 && u.from - last.to < GAP_MAX) {
+    last.to = u.to;
+    last.endIndex = u.endIndex;
+    last.units.push(u.index);
+  } else {
+    keep.push({from: u.from, to: u.to, startIndex: u.startIndex, endIndex: u.endIndex, units: [u.index]});
+  }
+}
+
+for (const k of keep) {
+  k.from = Math.max(0, k.from - PAD);
+  k.to += PAD;
+}
+for (let i = 1; i < keep.length; i++) {
+  if (keep[i].from < keep[i - 1].to) {
+    const mid = (keep[i].from + keep[i - 1].to) / 2;
+    keep[i - 1].to = mid;
+    keep[i].from = mid;
+  }
+}
+
+/** Gaps between spans, after the cut: long dead air collapsed, deliberate beats kept. */
+const gaps = [];
+for (let i = 1; i < keep.length; i++) {
+  const gap = keep[i].from - keep[i - 1].to;
+  const nextIsShort = units[keep[i].units[0]].keys.length <= 6;
+  const target = gap > GAP_MAX && !nextIsShort ? GAP_KEEP : gap;
+  gaps.push({after: i - 1, was: Number(gap.toFixed(2)), becomes: Number(target.toFixed(2)), keptAsBeat: target === gap && gap > GAP_MAX});
+}
+
+const dropped = [...drop].sort((a, b) => a - b).map((i) => ({
+  from: Number(units[i].from.toFixed(2)),
+  to: Number(units[i].to.toFixed(2)),
+  reason: abandoned.has(i) ? 'announced-retake' : 'retake',
+  text: units[i].text.slice(0, 110),
+}));
+
+/* ----------------------------------------------------------------- verification */
+
+const survivors = kept;
+const stillAlike = [];
+for (let i = 0; i < survivors.length; i++) {
+  for (let j = i + 1; j < survivors.length; j++) {
+    if (survivors[j].from - survivors[i].to > WINDOW) break;
+    if (similarity(survivors[i], survivors[j]) >= SIMILAR) {
+      stillAlike.push({
+        a: Number(survivors[i].from.toFixed(2)),
+        b: Number(survivors[j].from.toFixed(2)),
+        text: survivors[j].text.slice(0, 70),
+      });
+    }
+  }
+}
+
+const keptSeconds = keep.reduce((a, k) => a + (k.to - k.from), 0);
+const sourceSeconds = words[words.length - 1].end - words[0].start;
+const checks = {
+  noRepeatsLeft: stillAlike.length === 0,
+  units: units.length,
+  retakeGroups: groups.length,
+  unitsDropped: drop.size,
+  spans: keep.length,
+  keptSeconds: Number(keptSeconds.toFixed(2)),
+  sourceSeconds: Number(sourceSeconds.toFixed(2)),
+  energyScored: medianRms != null,
+};
+
+/* ---------------------------------------------------------------------- output */
+
+const stem = basename(wordsPath).replace(/\.?words\.json$|\.json$/, '') || 'take';
+const project = flag('project', null);
+const outPath = flag('out', null) ?? (project ? join('work', project, `${stem}.takes.json`) : join(dirname(wordsPath), `${stem}.takes.json`));
+mkdirSync(dirname(outPath), {recursive: true});
+writeFileSync(outPath, JSON.stringify({fps: FPS, gapMax: GAP_MAX, gapKeep: GAP_KEEP, pad: PAD, checks, keep, gaps, groups: groupReport, dropped, scriptMissing}, null, 2));
+
+console.log(outPath);
+console.log(`  ${checks.units} units, ${checks.retakeGroups} retake group(s), ${checks.unitsDropped} dropped`);
+console.log(`  ${checks.keptSeconds}s kept of ${checks.sourceSeconds}s (${((keptSeconds / sourceSeconds) * 100).toFixed(0)}%) in ${checks.spans} span(s)`);
+console.log(`  energy scoring: ${checks.energyScored ? 'on' : 'off (pass --media to enable)'}`);
+if (groupReport.length) {
+  console.log('\n  retakes dropped:');
+  for (const g of groupReport.slice(0, 8)) {
+    for (const d of g.dropped) console.log(`    ${String(d.at).padStart(7)}s  "${d.text}"`);
+  }
+}
+const beats = gaps.filter((g) => g.keptAsBeat).length;
+if (beats) console.log(`\n  ${beats} long pause(s) kept as deliberate beats before a short line.`);
+if (scriptPath) {
+  console.log(`\n  script check: ${scriptMissing.length} line(s) never said`);
+  for (const m of scriptMissing.slice(0, 6)) console.log(`    - "${m.text.slice(0, 68)}"`);
+}
+if (stillAlike.length) {
+  console.error(`\n${stillAlike.length} near-duplicate(s) still in the cut:`);
+  for (const s of stillAlike.slice(0, 8)) console.error(`  ${s.a}s and ${s.b}s — "${s.text}"`);
+  process.exit(1);
+}

package/template/src/components/CommandCard.tsx

@@ -0,0 +1,228 @@
+import React from 'react';
+import {useCurrentFrame, useVideoConfig} from 'remotion';
+import {COLOR, FONT, PALETTE, RADIUS, SHADOW, SPACE, TYPE, WEIGHT} from '../design/tokens';
+import {EASE} from '../design/motion';
+import {progress} from '../lib/animate';
+
+/**
+ * A command, typed out, as a designed graphic rather than a screen recording.
+ *
+ * Why this exists instead of zooming into the capture: the connect command carries the buyer's
+ * licence key, and the key IS the URL — anyone who can read it has a free studio. Blurring it in
+ * the capture is fragile, because the chat scrolls and the bubble moves, so a static mask misses
+ * it and a tracked one drifts. Rebuilding the command as type means there is nothing to miss: the
+ * key is never on screen in the first place, it is drawn as a redaction by design.
+ *
+ * It also reads better. A 1080p capture punched in to fill a 1920 frame is soft; this is sharp at
+ * any zoom, in the brand's own colours, and the Mac and Windows variants can sit side by side,
+ * which is impossible with one person's screen.
+ *
+ * MONOSPACE IS A DELIBERATE EXCEPTION. The design system says one family at every weight, and that
+ * holds everywhere except here: a command is code, and proportional type makes a URL ambiguous at
+ * exactly the moment someone is trying to read one. Nowhere else in the system gets this.
+ */
+
+export const MONO = 'ui-monospace, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace';
+
+export type Segment =
+  /** Ordinary command text. */
+  | {kind: 'plain'; text: string}
+  /** Flags and switches — dimmed, because nobody needs to read them to follow along. */
+  | {kind: 'flag'; text: string}
+  /** The part that matters, in the accent. */
+  | {kind: 'accent'; text: string}
+  /**
+   * A secret. Never pass the real value: `text` is only used for its LENGTH, so the redaction
+   * is the right width. Pass dummy characters.
+   */
+  | {kind: 'redacted'; text: string; label?: string};
+
+const COLOR_FOR: Record<Segment['kind'], string> = {
+  plain: PALETTE.stone100,
+  flag: PALETTE.stone400,
+  accent: COLOR.accent,
+  redacted: 'transparent',
+};
+
+/** How long the typing takes, from how much there is to type. Long commands do not crawl. */
+const typeFrames = (chars: number, fps: number) => Math.round((chars / 42) * fps);
+
+const Redaction: React.FC<{width: number; label?: string}> = ({width, label}) => (
+  <span
+    style={{
+      position: 'relative',
+      display: 'inline-flex',
+      alignItems: 'center',
+      justifyContent: 'center',
+      width,
+      height: '1.15em',
+      verticalAlign: 'middle',
+      borderRadius: RADIUS.sm / 2,
+      // Accent at low alpha, not a grey smear: it reads as a deliberate mark rather than a mistake.
+      backgroundColor: `${PALETTE.lime400}2e`,
+      border: `2px solid ${PALETTE.lime400}66`,
+    }}
+  >
+    <span
+      style={{
+        fontFamily: FONT.sans,
+        fontSize: '0.56em',
+        fontWeight: WEIGHT.semibold,
+        letterSpacing: '0.08em',
+        textTransform: 'uppercase',
+        color: COLOR.accent,
+        whiteSpace: 'nowrap',
+      }}
+    >
+      {label ?? 'your key'}
+    </span>
+  </span>
+);
+
+export const CommandCard: React.FC<{
+  segments: Segment[];
+  /** Frame the card lands on. Typing starts once it has settled. */
+  at: number;
+  /** Shown in the title bar. Omit for a card that is the same on both platforms. */
+  platform?: 'windows' | 'mac';
+  /** Replaces the platform chip — e.g. "same on Mac and Windows". */
+  note?: string;
+  fontSize?: number;
+  width?: number;
+}> = ({segments, at, platform, note, fontSize = 34, width}) => {
+  const frame = useCurrentFrame();
+  const {fps} = useVideoConfig();
+
+  // The card arrives, THEN types. Typing while the card is still moving reads as two
+  // competing animations and the eye does not know where to settle.
+  const land = progress(frame, at, Math.round(0.4 * fps), EASE.out);
+
+  const total = segments.reduce((n, s) => n + s.text.length, 0);
+  const typed = progress(frame, at + Math.round(0.3 * fps), typeFrames(total, fps), EASE.inOut);
+  const shown = Math.floor(typed * total);
+
+  // A caret that blinks only once typing has finished, the way a real prompt does.
+  const done = typed >= 1;
+  const caretOn = !done || Math.floor((frame / fps) * 2) % 2 === 0;
+
+  let consumed = 0;
+
+  return (
+    <div
+      style={{
+        width,
+        maxWidth: '100%',
+        borderRadius: RADIUS.md,
+        backgroundColor: PALETTE.ink900,
+        boxShadow: SHADOW.pop,
+        overflow: 'hidden',
+        opacity: land,
+        transform: `translateY(${(1 - land) * 28}px)`,
+      }}
+    >
+      <div
+        style={{
+          display: 'flex',
+          alignItems: 'center',
+          gap: SPACE[2],
+          padding: `${SPACE[2]}px ${SPACE[3]}px`,
+          backgroundColor: PALETTE.ink800,
+          borderBottom: `2px solid ${PALETTE.ink700}`,
+        }}
+      >
+        {[PALETTE.stone600, PALETTE.stone600, PALETTE.stone600].map((c, i) => (
+          <span key={i} style={{width: 14, height: 14, borderRadius: RADIUS.pill, backgroundColor: c}} />
+        ))}
+        <span style={{flex: 1}} />
+        <span
+          style={{
+            fontFamily: FONT.sans,
+            fontSize: TYPE.eyebrow.size * 0.62,
+            fontWeight: WEIGHT.medium,
+            letterSpacing: TYPE.eyebrow.tracking,
+            textTransform: 'uppercase',
+            color: note ? COLOR.accent : PALETTE.stone400,
+          }}
+        >
+          {note ?? (platform === 'mac' ? 'macOS' : platform === 'windows' ? 'Windows' : '')}
+        </span>
+      </div>
+
+      <div
+        style={{
+          padding: `${SPACE[4]}px ${SPACE[4]}px ${SPACE[4]}px`,
+          fontFamily: MONO,
+          fontSize,
+          lineHeight: 1.65,
+          letterSpacing: '-0.01em',
+          color: PALETTE.stone100,
+          wordBreak: 'break-word',
+        }}
+      >
+        {segments.map((seg, i) => {
+          const start = consumed;
+          consumed += seg.text.length;
+          const visible = Math.max(0, Math.min(seg.text.length, shown - start));
+          if (visible === 0) return null;
+
+          if (seg.kind === 'redacted') {
+            // Reveal the redaction as one block once typing reaches it, rather than growing it
+            // character by character, which would look like the secret is being drawn in.
+            const w = seg.text.length * fontSize * 0.6;
+            return <Redaction key={i} width={w} label={seg.label} />;
+          }
+
+          return (
+            <span key={i} style={{color: COLOR_FOR[seg.kind]}}>
+              {seg.text.slice(0, visible)}
+            </span>
+          );
+        })}
+        <span
+          style={{
+            display: 'inline-block',
+            width: fontSize * 0.55,
+            height: '1.05em',
+            marginLeft: 4,
+            verticalAlign: 'text-bottom',
+            backgroundColor: COLOR.accent,
+            opacity: caretOn ? 1 : 0,
+          }}
+        />
+      </div>
+    </div>
+  );
+};
+
+/* ------------------------------------------------------------------ the real commands */
+
+/**
+ * The connect line. Identical on Mac and Windows, which is worth SAYING rather than showing
+ * twice: a Mac viewer watching a Windows walkthrough is waiting to find out what is different
+ * for them, and "nothing, here" is the answer that keeps them watching.
+ */
+export const CONNECT_SEGMENTS: Segment[] = [
+  {kind: 'plain', text: 'claude mcp add '},
+  {kind: 'flag', text: '--scope user --transport http '},
+  {kind: 'accent', text: 'creator-editing-os'},
+  {kind: 'plain', text: ' https://creator-editing-os.mahipal-231.workers.dev/mcp/'},
+  {kind: 'redacted', text: 'XXXX-XXXX-XXXX-XXXX'},
+];
+
+/** Where the two platforms genuinely differ: installing Node when it is missing. */
+export const NODE_INSTALL = {
+  windows: [
+    {kind: 'plain', text: 'winget install '},
+    {kind: 'accent', text: 'OpenJS.NodeJS.LTS'},
+  ] as Segment[],
+  mac: [
+    {kind: 'plain', text: 'brew install '},
+    {kind: 'accent', text: 'node'},
+  ] as Segment[],
+};
+
+/** And where the studio lands. */
+export const STUDIO_PATH = {
+  windows: [{kind: 'plain', text: 'C:\\Users\\you\\'}, {kind: 'accent', text: 'VideoStudio'}] as Segment[],
+  mac: [{kind: 'plain', text: '/Users/you/'}, {kind: 'accent', text: 'VideoStudio'}] as Segment[],
+};