pr-docent 0.1.0 → 0.2.0

package/scripts/short-prompt.md

@@ -0,0 +1,63 @@
+You are writing a PR Docent short for pull request {{PR}}: a 30-45 second vertical explainer,
+played with narration in the reviewer's browser, for teammates who will not read the code, such as
+planners and people on other teams. It shows no code. Each scene is a simple picture of the idea
+(a flow, a before-and-after, a structure, or a few points) that builds up while one sentence is
+read aloud and subtitled.
+
+## Inputs
+
+- `{{OUT}}/tour.json`: the reviewers' tour of this PR. Start from it; it already knows what
+  matters and why.
+- `{{OUT}}/pr.json`: the PR's title, body and head commit.
+- `{{OUT}}/pr.diff` and the changed files in the current directory, if you need to check a detail.
+
+## Output
+
+Write the short to `{{OUT}}/short.json`, then run
+
+    node {{TOOLS}}/scripts/check-short.mjs {{OUT}}/short.json {{PR}}
+
+and fix every problem it reports until it prints `OK`. Then stop. Use these absolute paths as
+written and do not change directory: `{{OUT}}/short.json` is the only file you may write.
+
+## Format
+
+Write every text in the short in {{LANGUAGE}}: the title, hook, headlines, narration, labels,
+items and outro. The example below only shows the shape.
+
+```json
+{
+  "version": 1,
+  "pr": { "owner": "...", "repo": "...", "number": 0 },
+  "title": "Short title",
+  "hook": "One sentence on what changes and why",
+  "scenes": [
+    { "kind": "compare", "headline": "What changes", "narration": "One sentence",
+      "before": { "label": "Before", "items": ["..."] }, "after": { "label": "After", "items": ["..."] } },
+    { "kind": "flow", "headline": "How it works", "narration": "One sentence",
+      "steps": [{ "icon": "📝", "label": "Short name", "detail": "One-line detail", "status": "same" },
+                { "icon": "🤖", "label": "...", "detail": "...", "status": "new" }],
+      "links": ["Label on the arrow"] },
+    { "kind": "structure", "headline": "Where it fits", "narration": "One sentence",
+      "groups": [{ "label": "Layer or module", "items": [{ "icon": "📦", "label": "...", "status": "changed" }] }] },
+    { "kind": "points", "headline": "Remember", "narration": "One sentence",
+      "points": [{ "icon": "✅", "text": "Short point" }] }
+  ],
+  "outro": "One sentence on the impact or what to check"
+}
+```
+
+## Rules
+
+- Write in {{LANGUAGE}}. Plain words a non-developer understands: what changes for users, data,
+  operations or the team. Name a component only when the picture needs it, and call it by what
+  it does ("the tour checker", "the payment module") rather than by a class or file name.
+- 2 to 4 scenes that tell one story, usually: what changes (compare) → how it works (flow or
+  structure) → what it means (points). Pick the kinds that fit this PR; do not force all four.
+- Mark what this PR adds as `"status": "new"` and what it modifies as `"changed"`; leave the rest
+  as `"same"` so the eye goes to the change.
+- Keep it small enough for a phone: flow 2-5 steps, compare 1-3 items per side, structure 1-3
+  groups and at most 8 items, points 2-3. Headlines at most 24 characters, labels at most 16,
+  details at most 24, every sentence (hook, narration, outro) one sentence of at most 80.
+- One emoji per icon, chosen to be recognisable at a glance.
+- Never invent behaviour the PR does not have.

package/scripts/tour-prompt.md

@@ -16,7 +16,7 @@ code while they listen, so the tour must say what to look at and why, in reading
 
 Write the tour to `{{OUT}}/tour.json`, then run
 
-    node {{TOOLS}}/scripts/check-tour.mjs {{OUT}}/tour.json {{OUT}}/pr.diff {{PR}}
+    node {{TOOLS}}/scripts/check-tour.mjs {{OUT}}/tour.json {{OUT}}/pr.diff {{PR}} --guidelines {{OUT}}/guidelines.md
 
 and fix every problem it reports until it prints `OK`. Then stop. Do not post comments or
 change any other file. Use these absolute paths as written and do not change directory:
@@ -24,16 +24,19 @@ change any other file. Use these absolute paths as written and do not change dir
 
 ## Format
 
+Write every text in the tour in {{LANGUAGE}}: the title, the summaries, chapter titles, notes,
+review points and skipped reasons. The example below only shows the shape.
+
 ```json
 {
   "version": 1,
   "pr": { "owner": "...", "repo": "...", "number": 0 },
-  "title": "한 줄 제목",
-  "summary": "PR이 무엇을 왜 바꾸는지 2~4문장",
+  "title": "One-line title",
+  "summary": "What the PR changes and why, in 2-4 sentences",
   "chapters": [
     {
-      "title": "1. 챕터 제목",
-      "summary": "한 문장",
+      "title": "1. Chapter title",
+      "summary": "One sentence",
       "steps": [
         {
           "file": "path/from/repo/root.kt",
@@ -41,26 +44,37 @@ change any other file. Use these absolute paths as written and do not change dir
           "side": "right",
           "level": "focus",
           "note": [
-            { "text": "이 문장이 설명하는 줄을 가리킵니다.", "lines": [41, 45] },
-            { "text": "다음 문장은 다른 줄을 가리킵니다.", "lines": [50, 58] }
+            { "text": "This sentence points at the lines it talks about.", "lines": [41, 45] },
+            { "text": "The next sentence points at other lines.", "lines": [50, 58] }
           ],
-          "point": "리뷰어가 확인할 구체적인 질문"
+          "point": "A specific question for the reviewer to check"
         }
       ]
     }
   ],
-  "skipped": [{ "file": "package-lock.json", "reason": "의존성 잠금 파일" }]
+  "skipped": [{ "file": "package-lock.json", "reason": "dependency lock file" }]
 }
 ```
 
 ## Rules
 
+Be brief. Reviewers listen while they look at the code, so every sentence must earn its place.
+The checker enforces these limits for this diff ({{CHANGED_LINES}} changed lines):
+- At most {{MAX_STEPS}} steps in total.
+- At most {{SENTENCES_PER_STEP}} sentences per step, each at most {{SENTENCE_CHARS}} characters.
+- `point`: one question, at most {{POINT_CHARS}} characters.
+- `summary`: at most {{SUMMARY_CHARS}} characters; each chapter `summary`: at most
+  {{CHAPTER_SUMMARY_CHARS}}.
+
 Coverage and order
-- Every changed file must be visited by a step or listed in `skipped` with a reason
-  (lock files, generated code, snapshots, pure renames, binaries).
+- Every changed file must be visited by a step or listed in `skipped` with a short reason.
+- Make steps only for changes a reviewer must think about. Put trivial changes in `skipped`
+  instead of steps: comment or doc-comment edits, imports, docs, test fixtures that pass values
+  through, lock files, generated code, renames, binaries. A file can have a step for its real
+  change and nothing for its trivial ones.
+- Merge neighbouring changes that make one point into one step; never repeat a step.
 - Order chapters the way a person should read the change, not by file path: what changes and
-  why, then the core logic, then how it is wired in, then tests and docs.
-- A large file may need several steps; a trivial one may share a chapter with related files.
+  why, then the core logic, then how it is wired in, then tests.
 
 Lines
 - `lines` are line numbers in the new file (`"side": "right"`, the default). Use
@@ -72,13 +86,16 @@ Lines
   step as a whole.
 
 Notes are spoken aloud
-- Write in {{LANGUAGE}}. One or two short sentences per note entry, 2-5 entries per step.
-- Say what the code does and why it matters for the change; do not read the code out.
+- Write in {{LANGUAGE}}. One sentence per note entry, one idea per sentence.
+- Say why the change matters: intent, risk, or how it connects to other code. Do not restate
+  what the code plainly shows ("adds a parameter", "imports X", "updates the comment").
 - Avoid symbols, brackets and long lists that sound bad in speech. Name identifiers as written.
 
 Levels and review points
 - `focus`: where a bug would hurt or a design decision is made; at most about a third of the
-  steps. `skim`: worth a look. `skip`: can be skipped safely (formatting, boilerplate).
-- `point` is a concrete question for the reviewer, grounded in the code you read: an edge case,
-  a failure mode, a contract another caller relies on. Leave it out when there is nothing real
-  to check. Never invent problems.
+  steps. `skim`: worth a look.
+- `point` is one concrete question for the reviewer, grounded in the code you read: an edge
+  case, a failure mode, a contract another caller relies on. Leave it out when there is nothing
+  real to check. Never invent problems.
+
+{{GUIDELINES}}

package/src/diff.js

@@ -43,16 +43,20 @@ export function visibleLines(diffText) {
 
 /**
  * Problems that would make the tour point at the wrong place or skip part of the PR:
- * files outside the diff, lines not shown on the page, beats outside their step, and
- * changed files the tour neither visits nor skips.
+ * files outside the diff, lines not shown on the page, beats outside their step, repeated
+ * steps, and changed files the tour neither visits nor skips.
  */
 export function checkTour(tour, files) {
   const errors = [];
   const visited = new Set();
+  const seen = new Set();
   tour.chapters.forEach((chapter, c) =>
     chapter.steps.forEach((step, s) => {
       const where = `chapters[${c}].steps[${s}] (${step.file})`;
       visited.add(step.file);
+      const key = `${step.file}|${step.side}|${step.lines}`;
+      if (seen.has(key)) errors.push(`${where}: repeats an earlier step on the same lines`);
+      seen.add(key);
       const file = files.get(step.file);
       if (!file) return errors.push(`${where}: file is not changed in this pull request`);
       const shown = file[step.side];
@@ -80,6 +84,18 @@ export function checkTour(tour, files) {
   return errors;
 }
 
+/** Added plus removed lines, which sets how long a tour of the diff may be. */
+export function changedLineCount(diffText) {
+  let count = 0;
+  let inHunk = false;
+  for (const line of String(diffText).split("\n")) {
+    if (line.startsWith("diff --git ")) inHunk = false;
+    else if (line.startsWith("@@")) inHunk = true;
+    else if (inHunk && (line.startsWith("+") || line.startsWith("-"))) count++;
+  }
+  return count;
+}
+
 function range([start, end]) {
   return Array.from({ length: end - start + 1 }, (_, i) => start + i);
 }

package/src/guidelines.js

@@ -0,0 +1,102 @@
+// How long a generated tour may be, and a repository's own instructions for it.
+// Pure functions — no DOM, no chrome.*, no file system.
+//
+// A repository can add .github/pr-docent.md. Its optional front matter overrides the limits,
+// and the rest is appended to the generator's instructions:
+//
+//   ---
+//   maxSteps: 5
+//   sentenceChars: 100
+//   ---
+//   Use the domain terms 원장, 안분 and 파생 라인. Always mark migrations as focus.
+
+import { flattenSteps, splitSentences } from "./tour.js";
+
+export const GUIDELINES_PATH = ".github/pr-docent.md";
+
+export const DEFAULT_LIMITS = {
+  maxSteps: null, // null: 3 + 1 per 25 changed lines, at most 20
+  sentencesPerStep: 3,
+  sentenceChars: 80,
+  pointChars: 120,
+  summaryChars: 200,
+  chapterSummaryChars: 60,
+};
+
+/** { limits, instructions, errors } from the text of .github/pr-docent.md (or "" when absent). */
+export function parseGuidelines(text) {
+  const limits = { ...DEFAULT_LIMITS };
+  const errors = [];
+  const match = String(text ?? "").match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+  for (const line of match ? match[1].split(/\r?\n/) : []) {
+    if (!line.trim() || line.trim().startsWith("#")) continue;
+    const [, key, value] = line.replace(/\s+#.*$/, "").match(/^\s*(\w+)\s*:\s*(.*?)\s*$/) ?? [];
+    if (!key || !(key in DEFAULT_LIMITS)) errors.push(`Unknown setting: ${line.trim()}`);
+    else if (!/^\d+$/.test(value) || Number(value) < 1) errors.push(`${key} must be a positive whole number`);
+    else limits[key] = Number(value);
+  }
+  const instructions = String(text ?? "").slice(match ? match[0].length : 0).trim();
+  return { limits, instructions, errors };
+}
+
+/** How many steps a tour of a diff with [changedLines] added or removed lines may have. */
+export function stepBudget(changedLines, limits = DEFAULT_LIMITS) {
+  return limits.maxSteps ?? Math.min(20, 3 + Math.ceil(changedLines / 25));
+}
+
+/** Problems that make a tour wordier than the limits allow. */
+export function checkBrevity(tour, { changedLines, limits = DEFAULT_LIMITS }) {
+  const errors = [];
+  const steps = flattenSteps(tour);
+  const budget = stepBudget(changedLines, limits);
+  if (steps.length > budget) {
+    errors.push(`${steps.length} steps for ${changedLines} changed lines; at most ${budget}. Merge related steps and list trivial changes (comments, imports, docs, pass-through code) in "skipped".`);
+  }
+  if (tour.summary.length > limits.summaryChars) errors.push(`summary is ${tour.summary.length} characters; at most ${limits.summaryChars}`);
+  tour.chapters.forEach((chapter, c) => {
+    if (chapter.summary.length > limits.chapterSummaryChars) {
+      errors.push(`chapters[${c}].summary is ${chapter.summary.length} characters; at most ${limits.chapterSummaryChars}`);
+    }
+    chapter.steps.forEach((step, s) => {
+      const where = `chapters[${c}].steps[${s}] (${step.file})`;
+      const sentences = step.beats.flatMap((beat) => splitSentences(beat.text).map((x) => x.text));
+      if (sentences.length > limits.sentencesPerStep) {
+        errors.push(`${where}: ${sentences.length} sentences; at most ${limits.sentencesPerStep}. Keep only what the code doesn't already say.`);
+      }
+      for (const sentence of sentences) {
+        if (sentence.length > limits.sentenceChars) {
+          errors.push(`${where}: a sentence is ${sentence.length} characters; at most ${limits.sentenceChars}: "${sentence.slice(0, 30)}…"`);
+        }
+      }
+      if (step.point.length > limits.pointChars) {
+        errors.push(`${where}: point is ${step.point.length} characters; at most ${limits.pointChars}. Ask one question.`);
+      }
+    });
+  });
+  return errors;
+}
+
+/**
+ * The generator's instructions: [template] (scripts/tour-prompt.md) with the paths, the limits
+ * for this diff and the repository's own instructions filled in.
+ */
+export function buildPrompt(template, { pr, out, tools, language, changedLines, guidelinesText = "" }) {
+  const { limits, instructions } = parseGuidelines(guidelinesText);
+  const vars = {
+    PR: pr,
+    OUT: out,
+    TOOLS: tools,
+    LANGUAGE: language,
+    CHANGED_LINES: changedLines,
+    MAX_STEPS: stepBudget(changedLines, limits),
+    SENTENCES_PER_STEP: limits.sentencesPerStep,
+    SENTENCE_CHARS: limits.sentenceChars,
+    POINT_CHARS: limits.pointChars,
+    SUMMARY_CHARS: limits.summaryChars,
+    CHAPTER_SUMMARY_CHARS: limits.chapterSummaryChars,
+    GUIDELINES: instructions
+      ? `## Repository guidelines (${GUIDELINES_PATH})\n\nThese come from the repository and take precedence over the rules above.\n\n${instructions}\n`
+      : "",
+  };
+  return template.replace(/{{(\w+)}}/g, (match, name) => (name in vars ? String(vars[name]) : match));
+}

package/src/short-scenes.js

@@ -0,0 +1,127 @@
+// How a short looks: the scene markup and styles shared by the extension's live player and the
+// MP4 renderer, so a short looks the same in both. Pure string building — no DOM, no chrome.*.
+// Everything is laid out on a 1080x1920 frame (.short-frame) that players scale to fit.
+
+import { revealSteps } from "./short.js";
+
+export const FRAME_WIDTH = 1080;
+export const FRAME_HEIGHT = 1920;
+
+/** The opening card, the picture scenes, and the closing card. */
+export function sceneList(short) {
+  return [
+    { kind: "card", headline: short.title, narration: short.hook, opening: true },
+    ...short.scenes,
+    { kind: "card", headline: short.title, narration: short.outro, opening: false },
+  ];
+}
+
+/** How many elements [scene] reveals one at a time (cards show all at once). */
+export function sceneSteps(scene) {
+  return scene.kind === "card" ? 1 : revealSteps(scene);
+}
+
+/**
+ * Where to start reading [text] to land near [fraction] of the way through it: the start of the
+ * word there, since speech can only start at a character offset and a cut word sounds broken.
+ */
+export function wordStartAt(text, fraction) {
+  const at = Math.floor(Math.min(Math.max(fraction, 0), 1) * text.length);
+  if (at >= text.length) return 0;
+  const space = text.lastIndexOf(" ", at);
+  return space < 0 ? 0 : space + 1;
+}
+
+const esc = (value) => String(value ?? "").replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c]);
+
+/** Classes for the [i]th element when [shown] are visible: hidden until its turn, lit when it arrives. */
+const reveal = (i, shown) => (i >= shown ? " hidden" : i === shown - 1 ? " current" : "");
+
+function diagram(scene, shown, changedLabel) {
+  const badge = (status) => (status === "new" ? '<em class="tag new">NEW</em>' : status === "changed" ? `<em class="tag changed">${esc(changedLabel)}</em>` : "");
+  if (scene.kind === "flow") {
+    return `<div class="flow">${scene.steps.map((step, i) => `
+      ${i > 0 ? `<div class="arrow${reveal(i, shown)}">${scene.links[i - 1] ? `<span>${esc(scene.links[i - 1])}</span>` : ""}</div>` : ""}
+      <div class="node ${step.status}${reveal(i, shown)}"><div class="ico">${esc(step.icon)}</div>
+        <div><b>${esc(step.label)}${badge(step.status)}</b>${step.detail ? `<small>${esc(step.detail)}</small>` : ""}</div></div>`).join("")}</div>`;
+  }
+  if (scene.kind === "compare") {
+    const side = (value, cls, i) => `<div class="side ${cls}${reveal(i, shown)}"><p class="side-label">${esc(value.label)}</p>
+      <ul>${value.items.map((item) => `<li>${esc(item)}</li>`).join("")}</ul></div>`;
+    return `<div class="compare">${side(scene.before, "before", 0)}<div class="arrow${reveal(1, shown)}"></div>${side(scene.after, "after", 1)}</div>`;
+  }
+  if (scene.kind === "structure") {
+    return `<div class="structure">${scene.groups.map((group, i) => `
+      <div class="group${reveal(i, shown)}"><p class="group-label">${esc(group.label)}</p><div class="chips">${group.items.map((item) =>
+        `<span class="chip ${item.status}">${item.icon ? `${esc(item.icon)} ` : ""}${esc(item.label)}${badge(item.status)}</span>`).join("")}</div></div>`).join("")}</div>`;
+  }
+  if (scene.kind === "points") {
+    return `<div class="points">${scene.points.map((point, i) => `
+      <div class="point${reveal(i, shown)}"><div class="ico">${esc(point.icon || "•")}</div><p>${esc(point.text)}</p></div>`).join("")}</div>`;
+  }
+  return "";
+}
+
+/** The inside of a .short-frame for [scene] with [shown] of its elements visible. */
+export function sceneMarkup(scene, { short, shown }) {
+  const { owner, repo, number } = short.pr;
+  const changedLabel = /[가-힣]/.test(JSON.stringify(short)) ? "수정" : "Changed";
+  const main = scene.kind === "card"
+    ? `<div class="card"><p class="repo">${esc(scene.opening ? `${owner}/${repo} #${number}` : `github.com/${owner}/${repo}/pull/${number}`)}</p><h1>${esc(scene.headline)}</h1></div>`
+    : `<h2>${esc(scene.headline)}</h2><div class="stage">${diagram(scene, shown, changedLabel)}</div>`;
+  return `<header>PR Docent <span>· ${esc(`${owner}/${repo} #${number}`)}</span></header>
+    <main>${main}</main>
+    <footer><p class="subtitle">${esc(scene.narration)}</p></footer>`;
+}
+
+export const SHORT_CSS = `
+  .short-frame, .short-frame * { box-sizing: border-box; margin: 0; padding: 0; }
+  .short-frame { width: ${FRAME_WIDTH}px; height: ${FRAME_HEIGHT}px; overflow: hidden; display: flex; flex-direction: column;
+    background: linear-gradient(160deg, #161b22 0%, #0d1117 55%, #1f1235 100%); color: #f0f6fc;
+    font-family: -apple-system, "Apple SD Gothic Neo", "Malgun Gothic", "Noto Sans KR", sans-serif; word-break: keep-all; }
+  .short-frame header { padding: 64px 72px 0; font-size: 30px; color: #a78bfa; font-weight: 700; }
+  .short-frame header span { color: #8b949e; font-weight: 500; }
+  .short-frame main { flex: 1; display: flex; flex-direction: column; padding: 0 72px; }
+  .short-frame .card { margin: auto 0; }
+  .short-frame .card .repo { font-size: 34px; color: #8b949e; margin-bottom: 28px; }
+  .short-frame .card h1 { font-size: 80px; line-height: 1.25; font-weight: 800; }
+  .short-frame h2 { padding-top: 56px; font-size: 66px; line-height: 1.25; font-weight: 800; color: #f0f6fc; }
+  .short-frame .stage { flex: 1; display: flex; align-items: center; justify-content: center; }
+  .short-frame .hidden { opacity: 0; }
+  .short-frame .current { box-shadow: 0 0 0 4px rgba(167, 139, 250, .55), 0 0 48px rgba(130, 80, 223, .55); }
+  .short-frame .node, .short-frame .side, .short-frame .group, .short-frame .point, .short-frame .arrow { transition: opacity .45s ease, box-shadow .45s ease; }
+  .short-frame .tag { font-style: normal; margin-left: 14px; font-size: 22px; padding: 4px 12px; border-radius: 999px; vertical-align: middle; }
+  .short-frame .tag.new { background: #8250df; } .short-frame .tag.changed { background: #9a6700; }
+  .short-frame .ico { font-size: 60px; width: 80px; text-align: center; flex: none; }
+  .short-frame .flow { width: 100%; display: flex; flex-direction: column; align-items: center; }
+  .short-frame .node { width: 100%; border-radius: 28px; padding: 28px 36px; background: #161b22; border: 3px solid #30363d; display: flex; gap: 26px; align-items: center; }
+  .short-frame .node b { display: block; font-size: 44px; }
+  .short-frame .node small { display: block; font-size: 30px; color: #8b949e; margin-top: 6px; }
+  .short-frame .node.new { border-color: #8250df; background: rgba(130, 80, 223, .14); }
+  .short-frame .node.changed { border-color: #bf8700; background: rgba(191, 135, 0, .12); }
+  .short-frame .arrow { height: 76px; width: 6px; background: #484f58; position: relative; margin: 6px 0 14px; flex: none; }
+  .short-frame .arrow::after { content: ""; position: absolute; bottom: -10px; left: -12px; border: 15px solid transparent; border-top-color: #484f58; }
+  .short-frame .arrow.current { box-shadow: none; }
+  .short-frame .arrow span { position: absolute; left: 32px; top: 18px; white-space: nowrap; font-size: 28px; color: #8b949e; }
+  .short-frame .compare { width: 100%; display: flex; flex-direction: column; align-items: center; }
+  .short-frame .side { width: 100%; border-radius: 28px; padding: 34px 40px; border: 3px solid #30363d; background: #161b22; }
+  .short-frame .side.before { opacity: .75; } .short-frame .side.before.hidden { opacity: 0; }
+  .short-frame .side.after { border-color: #8250df; background: rgba(130, 80, 223, .14); }
+  .short-frame .side-label { font-size: 32px; font-weight: 700; color: #a78bfa; margin-bottom: 16px; }
+  .short-frame .side.before .side-label { color: #8b949e; }
+  .short-frame .side li { list-style: none; font-size: 42px; line-height: 1.5; font-weight: 600; }
+  .short-frame .side li::before { content: "· "; color: #8b949e; }
+  .short-frame .structure { width: 100%; display: flex; flex-direction: column; gap: 34px; }
+  .short-frame .group { border-radius: 28px; padding: 30px 34px; border: 3px dashed #30363d; }
+  .short-frame .group-label { font-size: 32px; font-weight: 700; color: #8b949e; margin-bottom: 18px; }
+  .short-frame .chips { display: flex; flex-wrap: wrap; gap: 16px; }
+  .short-frame .chip { font-size: 38px; font-weight: 700; padding: 16px 26px; border-radius: 20px; background: #161b22; border: 3px solid #30363d; }
+  .short-frame .chip.new { border-color: #8250df; background: rgba(130, 80, 223, .16); }
+  .short-frame .chip.changed { border-color: #bf8700; background: rgba(191, 135, 0, .12); }
+  .short-frame .points { width: 100%; display: flex; flex-direction: column; gap: 30px; }
+  .short-frame .point { display: flex; gap: 26px; align-items: center; border-radius: 28px; padding: 34px 36px; background: #161b22; border: 3px solid #30363d; }
+  .short-frame .point p { font-size: 46px; line-height: 1.35; font-weight: 700; }
+  .short-frame footer { padding: 0 64px 96px; }
+  .short-frame .subtitle { background: rgba(13, 17, 23, .86); border: 2px solid #8250df; border-radius: 28px; padding: 30px 40px;
+    font-size: 42px; line-height: 1.4; font-weight: 700; text-align: center; }
+`;

package/src/short.js

@@ -0,0 +1,158 @@
+// Shorts: a 30-45 second vertical video that explains a pull request to teammates who won't
+// review it (planners, other teams) with pictures instead of code. Written from the PR's tour,
+// rendered by the local host. Pure functions — no DOM, no chrome.*, no file system.
+//
+// A short (version 1):
+// {
+//   "version": 1,
+//   "pr": { "owner": "...", "repo": "...", "number": 42 },
+//   "title": "...", "hook": "What changes and why, in one sentence.",   // the opening card
+//   "scenes": [ ...one of the kinds below... ],
+//   "outro": "What it means or what to watch for, in one sentence."      // the closing card
+// }
+// Every scene has "headline" (a few words, shown large) and "narration" (read aloud, subtitled).
+//   flow:      "steps": [{ "icon", "label", "detail", "status" }], "links": ["label between steps", ...]
+//   compare:   "before": { "label", "items": [...] }, "after": { "label", "items": [...] }
+//   structure: "groups": [{ "label", "items": [{ "icon", "label", "status" }] }]
+//   points:    "points": [{ "icon", "text" }]
+// status is "new", "changed" or "same" (default) and marks what this pull request adds or changes.
+
+export const SHORT_LIMITS = {
+  minScenes: 2, maxScenes: 4, titleChars: 40, headlineChars: 24, sentenceChars: 80,
+  labelChars: 16, detailChars: 24, itemChars: 28, pointChars: 32,
+};
+export const SCENE_KINDS = ["flow", "compare", "structure", "points"];
+const STATUSES = ["new", "changed", "same"];
+
+const text = (value) => (typeof value === "string" ? value.trim() : "");
+
+/** Validates and normalizes raw JSON. Returns { short, errors }; short is null when there are errors. */
+export function parseShort(raw) {
+  const errors = [];
+  const fail = (message) => errors.push(message);
+  if (!raw || typeof raw !== "object") return { short: null, errors: ["Short must be a JSON object"] };
+  if (raw.version !== 1) fail(`Unsupported short version: ${raw.version}`);
+  const pr = raw.pr || {};
+  if (!pr.owner || !pr.repo || !Number.isInteger(pr.number)) fail("pr.owner, pr.repo and pr.number are required");
+  for (const field of ["title", "hook", "outro"]) if (!text(raw[field])) fail(`${field} is required`);
+  if (!Array.isArray(raw.scenes)) fail("scenes must be a list");
+
+  const scenes = (raw.scenes || []).map((scene, i) => {
+    const where = `scenes[${i}]`;
+    const kind = scene?.kind;
+    if (!SCENE_KINDS.includes(kind)) fail(`${where}.kind must be one of ${SCENE_KINDS.join(", ")}`);
+    if (!text(scene?.headline)) fail(`${where}.headline is required`);
+    if (!text(scene?.narration)) fail(`${where}.narration is required`);
+    const status = (value, at) => {
+      const s = value ?? "same";
+      if (!STATUSES.includes(s)) fail(`${at}.status must be one of ${STATUSES.join(", ")}`);
+      return s;
+    };
+    const list = (value, at) => {
+      if (!Array.isArray(value) || value.length === 0) fail(`${at} must be a non-empty list`);
+      return Array.isArray(value) ? value : [];
+    };
+    const base = { kind, headline: text(scene?.headline), narration: text(scene?.narration) };
+    if (kind === "flow") {
+      const steps = list(scene.steps, `${where}.steps`).map((step, s) => ({
+        icon: text(step?.icon), label: text(step?.label), detail: text(step?.detail), status: status(step?.status, `${where}.steps[${s}]`),
+      }));
+      steps.forEach((step, s) => !step.label && fail(`${where}.steps[${s}].label is required`));
+      return { ...base, steps, links: (Array.isArray(scene.links) ? scene.links : []).map(text) };
+    }
+    if (kind === "compare") {
+      const side = (value, name) => ({ label: text(value?.label), items: list(value?.items, `${where}.${name}.items`).map(text) });
+      return { ...base, before: side(scene.before, "before"), after: side(scene.after, "after") };
+    }
+    if (kind === "structure") {
+      const groups = list(scene.groups, `${where}.groups`).map((group, g) => ({
+        label: text(group?.label),
+        items: list(group?.items, `${where}.groups[${g}].items`).map((item, j) => ({
+          icon: text(item?.icon), label: text(item?.label), status: status(item?.status, `${where}.groups[${g}].items[${j}]`),
+        })),
+      }));
+      return { ...base, groups };
+    }
+    if (kind === "points") {
+      return { ...base, points: list(scene.points, `${where}.points`).map((point) => ({ icon: text(point?.icon), text: text(point?.text) })) };
+    }
+    return base;
+  });
+
+  if (errors.length) return { short: null, errors };
+  return {
+    short: { version: 1, pr: { owner: pr.owner, repo: pr.repo, number: pr.number }, title: text(raw.title), hook: text(raw.hook), scenes, outro: text(raw.outro) },
+    errors: [],
+  };
+}
+
+/** Problems that would make the video long or crowded on a phone screen. */
+export function checkShort(short, limits = SHORT_LIMITS) {
+  const errors = [];
+  const tooLong = (value, max, where) => {
+    if (value.length > max) errors.push(`${where} is ${value.length} characters; at most ${max}: "${value.slice(0, 24)}…"`);
+  };
+  const count = (n, min, max, where) => {
+    if (n < min || n > max) errors.push(`${where}: ${n}; use ${min}-${max}`);
+  };
+  count(short.scenes.length, limits.minScenes, limits.maxScenes, "scenes (the opening and closing cards come on top)");
+  tooLong(short.title, limits.titleChars, "title");
+  tooLong(short.hook, limits.sentenceChars, "hook");
+  tooLong(short.outro, limits.sentenceChars, "outro");
+  short.scenes.forEach((scene, i) => {
+    const where = `scenes[${i}] (${scene.kind})`;
+    tooLong(scene.headline, limits.headlineChars, `${where} headline`);
+    tooLong(scene.narration, limits.sentenceChars, `${where} narration`);
+    if (scene.kind === "flow") {
+      count(scene.steps.length, 2, 5, `${where} steps`);
+      scene.steps.forEach((step, s) => {
+        tooLong(step.label, limits.labelChars, `${where} steps[${s}].label`);
+        tooLong(step.detail, limits.detailChars, `${where} steps[${s}].detail`);
+      });
+      if (scene.links.length > scene.steps.length - 1) errors.push(`${where}: ${scene.links.length} links for ${scene.steps.length} steps; at most one between each pair`);
+      scene.links.forEach((link, l) => tooLong(link, limits.labelChars, `${where} links[${l}]`));
+    } else if (scene.kind === "compare") {
+      for (const name of ["before", "after"]) {
+        tooLong(scene[name].label, limits.labelChars, `${where} ${name}.label`);
+        count(scene[name].items.length, 1, 3, `${where} ${name}.items`);
+        scene[name].items.forEach((item, j) => tooLong(item, limits.itemChars, `${where} ${name}.items[${j}]`));
+      }
+    } else if (scene.kind === "structure") {
+      count(scene.groups.length, 1, 3, `${where} groups`);
+      count(scene.groups.reduce((n, g) => n + g.items.length, 0), 1, 8, `${where} items in all groups`);
+      scene.groups.forEach((group, g) => {
+        tooLong(group.label, limits.labelChars, `${where} groups[${g}].label`);
+        group.items.forEach((item, j) => tooLong(item.label, limits.labelChars, `${where} groups[${g}].items[${j}].label`));
+      });
+    } else if (scene.kind === "points") {
+      count(scene.points.length, 2, 3, `${where} points`);
+      scene.points.forEach((point, p) => tooLong(point.text, limits.pointChars, `${where} points[${p}]`));
+    }
+  });
+  return errors;
+}
+
+/** How many elements a scene reveals one at a time while its sentence is read. */
+export function revealSteps(scene) {
+  if (scene.kind === "flow") return scene.steps.length;
+  if (scene.kind === "compare") return 2;
+  if (scene.kind === "structure") return scene.groups.length;
+  if (scene.kind === "points") return scene.points.length;
+  return 1;
+}
+
+/** The short for [pr] among the code blocks of the PR's comments, or null (like findTourInBlocks). */
+export function findShortInBlocks(blocks, { owner, repo, number }) {
+  let found = null;
+  for (const text of blocks) {
+    let raw;
+    try {
+      raw = JSON.parse(text);
+    } catch {
+      continue;
+    }
+    const forThisPr = raw?.version === 1 && raw.pr?.owner === owner && raw.pr?.repo === repo && raw.pr?.number === number;
+    if (forThisPr && Array.isArray(raw.scenes) && typeof raw.hook === "string") found = raw;
+  }
+  return found;
+}