@autoaiai/aicut 0.1.7 → 0.1.11

package/skills/html2video/SKILL.md

@@ -0,0 +1,290 @@
+---
+name: html2video
+description: "Turn a web article URL into a polished 1920x1080 edited video (MP4) — code-driven editing with AICUT, not AI video generation. Use this whenever the user wants an article, blog post, research page or changelog made into a video, or says 文章转视频, 网页转视频, 把这篇做成视频, article-to-video, url-to-video, or asks for an explainer or montage cut of written content. It harvests the page's real structure, full-resolution figures and design tokens, mines the content for what matters (including the caveats most tools skip), commits to a reviewable storyboard.json, then renders through a hardened Chinese-typography shot library. Has a 口播 (spoken) mode — ask for 口播, 配音稿, a narration script or voice-over and it re-times the cut to speech and writes a recordable script with timecodes. Also use it to re-render or retune an existing storyboard.json, adjust crops or pacing, or pull stills. Runs in AICUT: the film is film.html, a page per shot, drawn by `aicut look` and `aicut render`."
+license: MIT
+source: "cclank/lanshu-html2video-skill"
+---
+
+# html2video
+
+## Running it in AICUT
+
+AICUT's film is `film.html`: it cuts pages, footage, pictures and sound together on tracks. A page is a web page that
+sets `window.film = { frame(t) }` and draws that moment — no framework, no build step, no composition object, no
+`registerRoot`. Five shots are five pages cut together, not one page that changes scene, so each shot stays trimmable
+and replaceable in Studio.
+
+```sh
+npx -y @autoaiai/aicut@latest          # the manual: the format and the commands, always current
+npx -y @autoaiai/aicut@latest open .   # make this folder a film and print Studio's address
+npx -y @autoaiai/aicut@latest look     # a contact sheet of the whole film, its sound, and a determinism check
+npx -y @autoaiai/aicut@latest look 4.5 # one frame, full size — look at the PNG, not at the code
+npx -y @autoaiai/aicut@latest render   # the MP4, beside film.html
+```
+
+Run the manual before the first film: it is authoritative for the format, and this skill is about the method above it.
+
+Where the words below name another program's part, it becomes this:
+
+| elsewhere | in AICUT |
+|---|---|
+| composition, timeline, project file | `film.html`; tracks and clips inside it |
+| a scene, a sequence, a slide | a page (`pages/<name>.html`) cut onto a track |
+| `useCurrentFrame()`, `interpolate()` | `frame(t)` — the picture depends only on `t`, never on state or `Date.now()` |
+| a still, a screengrab | `aicut look <t>` |
+| `render` / `build` / `export` | `aicut render` (the person can also export from Studio) |
+| a dev server, a preview window | `aicut open` and the Studio address it prints |
+
+Hard rules that hold whatever the method says: the picture depends only on `t`; every value in the person's prompt is
+binding; look at the frames `look` writes before saying a film is done.
+
+
+Produce a 1920x1080 H.264 video from a web article. Chinese output by default;
+English sources get translated during the reading stage.
+
+The hard part is not rendering. It is deciding what deserves to be on screen —
+and the thing that separates this from a slideshow is treating a page's figures
+and figure captions as primary material rather than decoration.
+
+## The pipeline
+
+```
+HARVEST ──→ READ ──→ STORYBOARD ──→ RENDER
+ scripts     you     storyboard.json   library
+```
+```
+Four stages, and the middle two are where the quality comes from. HARVEST and
+RENDER are deterministic and already written; READ and STORYBOARD are editorial
+judgement, which is your job.
+
+| Script | Does |
+|---|---|
+| `scripts/harvest.py` | URL to structured content, full-resolution figures, design tokens |
+| `scripts/render.mjs` | storyboard.json to MP4 (stages assets, subsets fonts, validates, renders) |
+| `scripts/build_fonts.mjs` | subsets the CJK faces to this board's characters (called by render.mjs) |
+| `scripts/sync.sh` | copies the engine from `assets/template/` into the runtime studio |
+
+All paths below are relative to this skill's directory. The render engine lives
+in `assets/template/` and runs from `~/.cache/html2video/studio/`, which is where
+`node_modules` is kept so it survives between runs.
+```
+
+## 1. HARVEST
+
+```bash
+python3 scripts/harvest.py --url "https://example.com/article" --out ./work/myrun
+```
+```
+Produces `work/myrun/harvest.json` plus `work/myrun/media/fig-NN.png`.
+
+Read `harvest.json` before doing anything else. Look at, in this order:
+
+1. **`figures[].caption`, and its `captionSource`.** When a page really uses
+   `<figcaption>`, each caption is a finding compressed into one sentence with its
+   illustration already attached — the densest editorial material available, and
+   the shortest path to a good video.
+
+   But check `captionSource` before trusting one. `figcaption` is authoritative;
+   `proximity` means the text merely followed the image and **may belong to a
+   different figure**; `none` means the page gave nothing. Many sites (Cloudflare's
+   blog, for one) wrap images in `<figure>` with no caption at all.
+
+   When it is `proximity` or `none`, **open the image and read the finding off the
+   chart** — its own embedded title is usually the best source. Re-author that as a
+   Chinese headline, and put the English original in `asset.sourceCaption`.
+2. **`figures[].intrinsic`** — how many pixels you have to spend. A figure at
+   2688px can be pushed into; one at 1590px cannot fill a 1920 frame at all.
+3. **`sections`** — the article's real spine, with nav noise already dropped.
+4. **`tokens`** — the site's actual colours and fonts, from a real browser.
+   `cssVars` often contains the brand palette by name.
+
+If the fetch looks thin, retry attached to a logged-in Chrome:
+```
+```bash
+python3 scripts/harvest.py --url URL --out DIR --cdp-url http://localhost:9222
+```
+
+## 2. READ
+
+This stage has no script because it is the judgement. Load
+[references/editorial.md](references/editorial.md) and work through it. In short:
+
+- state the core message in 40 Chinese characters or fewer
+- pick 3 to 5 supporting points and **order them by audience relevance, not by
+  where they appear in the article**
+- triage everything else: keep / simplify / visualise / omit
+- go looking for what the article half-buries — the limitation it admits, the
+  number that contradicts expectation, the one example that makes it click.
+  These are the moments other tools skip, and they are why a video is worth
+  watching rather than skimming.
+
+Write narrative headlines. "26% 的题目它知道自己在被测" beats "评测结果".
+
+## 3. STORYBOARD
+
+Author `work/myrun/storyboard.json`. The schema, every field's meaning, and a
+complete worked example are in
+[references/storyboard.md](references/storyboard.md). Shot-by-shot composition
+and motion specs are in [references/shots.md](references/shots.md).
+
+Three rules that the schema enforces, so it is cheaper to follow them than to
+fight them:
+
+- **Never author frames.** Scene length is a dimensionless `weight`; the solver
+  converts weights to frames while respecting a reading floor computed from your
+  text. Everything time-like inside a scene is normalised `0..1`.
+- **Crops are normalised rects in source-image space**, and a crop that would
+  need more pixels than the image has is rejected before rendering.
+- **Assets are local.** No URLs anywhere; the render never waits on the network.
+
+Then validate, which is much faster than rendering:
+
+```
+The validation report prints resolved scene durations, pixel headroom per asset,
+and character budgets. Fix everything it flags before rendering.
+```
+
+## 4. RENDER
+
+# full video
+node scripts/render.mjs --storyboard ./work/myrun --out ./myrun.mp4
+
+# one frame, for checking a layout
+node scripts/render.mjs --storyboard ./work/myrun --still 950
+
+# interactive preview
+node scripts/render.mjs --storyboard ./work/myrun --studio
+
+# 口播 mode: script only, no render
+node scripts/render.mjs --storyboard ./work/myrun --script
+
+### 口播 mode
+
+When the user asks for 口播 / a spoken version / a narration script, set
+`audio.mode: "voice"` and give **every** scene a `narration` line. That does three
+things, and the third is why this is a mode rather than an extra document:
+
+- writes `narration.md` — a recordable script with timecodes, what is on screen at
+  each moment, and a per-scene duration budget
+- **re-times the cut to speech** rather than to reading speed, so the script and
+  the video actually line up
+- relaxes the reading floor, since the viewer is listening rather than reading
+
+The video renders **silent** — you record over it. No TTS, no API key.
+
+The single rule that matters: **narration must not read the on-screen text aloud.**
+The screen says what it is; the narration says why, so what, and where it came from.
+Read [references/narration.md](references/narration.md) before writing any of it —
+it also covers trimming on-screen text, spoken syntax, and the `--sps` speech-rate
+flag.
+
+`render.mjs` stages assets, wraps props, subsets fonts, validates and renders in
+one step. Use it rather than calling `remotion` directly — see the props note in
+[references/pitfalls.md](references/pitfalls.md) for why.
+
+**Use `--concurrency 3` or lower** if a render dies with `Visited
+"http://localhost:3001/index.html" but got no response`. Measured on this
+machine: 8 parallel tabs against the system Chrome fails that way, 3 is stable.
+Stills always work because they run a single tab.
+
+## Iterating on the visuals
+
+This is the real work, and there is no automated substitute for looking at frames.
+
+Do not re-render the whole video to check a change. Pull stills at the middle of
+the scenes you touched:
+
+```
+The validation report prints each scene's start in **frames** and its duration in
+**seconds**, so mid-scene is `from + duration * fps / 2`. Look for, specifically:
+
+- text landing on top of a figure, or on a busy part of one
+- a headline competing with type that is already inside the figure
+- a crop that cuts a word, a chart title, or an axis label — for a chart this is
+  the most common problem, and the fix is `"fit": "contain"`
+- rules and dividers that have vanished (anything under 2px does, in video)
+- Chinese lines breaking mid-word — fix with an explicit `\n` in the text
+
+When a figure fights you, the answer is usually a different slot or fit, not a
+smaller font. A chart or schematic wants `"fit": "contain"` so nothing is cropped;
+a wide schematic wants `band`; a screenshot wants `inset`; a photograph wants
+`full` with `cover` and a push-in.
+
+Watch the overall shape too: if every figure ends up `contain` + `hold`, the middle
+of the video will read as slides. Give at least one figure that has the pixels for
+it a gentle `push-in`.
+```
+
+## Constraints that are not negotiable
+
+These come from Remotion's rendering model, and violating them produces videos
+that look fine in preview and break in the render:
+
+- **No CSS animations, transitions, or Tailwind `animate-*`.** Frames render
+  across parallel browser tabs that share no animation state, so anything not
+  driven by `useCurrentFrame()` flickers. Animate with `interpolate()`.
+- **`interpolate()` returns a number, never a string.** Wrap it in a template
+  literal for `translate`/`rotate`. And `translate` needs the two-value form:
+  a bare number is translateX only.
+- **`<Audio volume={(f) => …}>` receives audio-local frames**, not composition
+  frames. The music bed is mounted at frame 0 outside any Sequence so the two
+  coincide; keep it that way.
+- **A `cut` is the absence of a transition**, not a zero-frame one.
+
+The full list, with the reasoning and the failure each rule prevents, is in
+[references/pitfalls.md](references/pitfalls.md). Read it before editing the
+engine in `assets/template/src/`.
+
+## Typography
+
+Chinese in Remotion has one large trap: routing CJK through
+`@remotion/google-fonts` means about 101 unicode-range subsets times 9 weights,
+each its own `FontFace` and its own render-blocking `delayRender()` — hundreds of
+network fetches per frame tab. This skill instead subsets two variable faces
+locally with `pyftsubset` to exactly the characters the storyboard uses: about
+310 codepoints becomes ~125KB total, versus ~36MB, with zero network at render.
+
+The type scale, safe area, the exact character-per-line budgets and the CJK
+line-breaking rules are in [references/cjk-type.md](references/cjk-type.md).
+Read it before changing any font size.
+
+## Requirements
+
+Already present on this machine; listed so a failure is diagnosable.
+
+| Needs | For | Check |
+|---|---|---|
+| `bun` | runs baoyu-fetch during harvest | `bun -v` |
+| `agent-browser` | design tokens via getComputedStyle | `agent-browser --version` |
+| `pyftsubset` with brotli | font subsetting | `pyftsubset --help` |
+| `sips` | image dimensions (macOS built-in) | — |
+| Node 20+, Chrome | rendering | `node -v` |
+
+First run downloads two Noto CJK variable fonts (~37MB total) into
+`~/.cache/html2video/fonts/` and caches them permanently. If that download fails
+the skill falls back to a macOS system font and says so — text metrics then vary
+between machines, which breaks reproducible line breaking.
+
+No music ships with this skill, because shipping music means shipping a licence.
+Drop a file into the harvest directory and set `audio.bed` to its name; without
+one the video renders silent.
+
+## Resources
+
+- [references/editorial.md](references/editorial.md) — the READ stage: salience
+  mining, triage, narrative arcs, banned phrasing
+- [references/storyboard.md](references/storyboard.md) — schema field by field,
+  plus a full worked example from a real article
+- [references/shots.md](references/shots.md) — the ten shots: what each is for,
+  its composition, its motion
+- [references/cjk-type.md](references/cjk-type.md) — type scale, safe area,
+  character budgets, CJK line breaking, font subsetting
+- [references/narration.md](references/narration.md) — 口播 mode: writing a script
+  people can record, trimming on-screen text, how speech length is estimated
+- [references/pitfalls.md](references/pitfalls.md) — every constraint and
+  hard-won gotcha, with the failure it prevents
+
+## Source
+
+Rewritten for AICUT from [`cclank/lanshu-html2video-skill`](https://github.com/cclank/lanshu-html2video-skill)
+(MIT), SKILL.md. The method is that skill's own; the way it runs is AICUT's.

package/skills/html2video/references/cjk-type.md

@@ -0,0 +1,173 @@
+# Chinese typography for 1920x1080
+
+The existing `remotion-best-practices` guidance on video layout is prose-only and
+keyed to a 1080-wide *vertical* frame, so none of it transfers. These are the
+numbers for a 1920x1080 landscape frame, and they are derived rather than guessed.
+
+## Safe area and grid
+
+```
+SAFE     = { top: 96, right: 140, bottom: 128, left: 140 }
+CONTENT  = 1640 x 856
+GRID     = 12 columns x 100px + 11 gutters x 40px = 1640 exactly
+RHYTHM   = 8px   (every vertical gap is a multiple)
+```
+
+Bottom is deeper than top to reserve the caption band. With `--voice`,
+`bottom: 240` gives a 1640x744 content box and a caption band of
+`{ height: 168, bottom: 72 }`. Both insets sit outside the 5% title-safe rect
+(96 / 54), so nothing readable is at risk of being cropped by a player.
+
+`cols(n) = n*100 + (n-1)*40` — so `cols(7)` is 940, `cols(8)` 1080, `cols(9)` 1220,
+`cols(10)` 1360, `cols(12)` 1640. Use these for text box widths; do not invent
+widths.
+
+## Type scale
+
+Sizes derive from cap-height as a fraction of frame **height** — the real
+legibility invariant — then get about 12% more for CJK stroke density.
+
+| Role | px | weight | line-height | tracking | soft max | hard max |
+|---|---|---|---|---|---|---|
+| display | 128 | 600/700 | 1.18 | −0.01em | 10 | 12 |
+| headline | 96 | 700 | 1.22 | 0 | 14 | 17 |
+| statement | 72 | 600 | 1.30 | 0 | 18 | 22 |
+| sub | 52 | 500 | 1.45 | 0.01em | 26 | 31 |
+| caption | 44 | 400 | 1.55 | 0.02em | 30 | 36 |
+| label / eyebrow | 30 | 600 | 1.40 | 0.16em | — | — |
+| credit | 26 | 400 | 1.50 | 0.06em | — | — |
+| stat value | 240 | 700 tabular | 1.00 | −0.02em | — | — |
+| burned-in caption | 56 | 500 | 1.40 | 0.01em | 24 | 29 |
+
+### Why hardMax is exact, not an estimate
+
+Every CJK ideograph and every full-width punctuation mark in the Source Han
+lineage (Noto Sans SC, Noto Serif SC) has an advance width of **exactly 1.000em**
+at 1000 upem. So for a content width `Wc` and tracking `t`:
+
+```
+hardMax = floor(Wc / (px * (1 + t)))
+```
+
+With `Wc = 1640`: headline `floor(1640/96) = 17`, statement `floor(1640/72) = 22`,
+sub `floor(1640/(52*1.01)) = 31`, caption `floor(1640/(44*1.02)) = 36`. All match
+the table.
+
+**These are per the full content width.** A shot using a narrower box gets
+proportionally fewer characters, and this is the most common authoring mistake.
+Worked example: `FigureReveal` fits its headline in `cols(8)` = 1080px when
+full-bleed, so at 96px that is 11 characters per line, not 17 — a 22-character
+headline needs three lines and will fail the two-line budget. Check the box width
+in the shot before counting characters.
+
+`softMax` is the editorial target. Shorter lines read faster on screen, and a
+headline that fills every line to the hard limit reads as crowded even when it fits.
+
+## Fitting: `fitCJK`
+
+`@remotion/layout-utils` cannot do this job:
+
+- `fitText` is width-only (`withinWidth`) — no line count, no height budget.
+- `fitTextOnNLines` splits on `" "`, so a Chinese sentence is one token and it
+  shrinks the type until the whole sentence fits a single line.
+- `fillTextBox` accumulates `word + " "`, which is the same Latin assumption.
+
+`src/lib/type/fit-cjk.ts` replaces them with three deliberate differences:
+
+**1. Cluster on line-break rules, not spaces.** A cluster is one CJK character or
+one atomic Latin/technical run, so "Opus 4.6" and "4620x1410" never split.
+
+Kinsoku is enforced both ways:
+- 行頭禁則 (`NO_START`) — a closing bracket, comma or period may not begin a line,
+  so it gets pulled up onto the previous line (追い込み), tolerating one cluster of
+  overflow.
+- 行末禁則 (`NO_END`) — an opening bracket may not end a line, so it is pushed down
+  with the following cluster.
+
+**2. A discrete size ladder, not a binary search.** A search to 0.01px can land on
+a different value if `measureText` differs by a hair between Chrome builds — and a
+different size changes the *line breaks*, which is a visible jump between two
+renders of the same storyboard. Ladders are stable under metric noise and keep the
+type scale honest (steps, not 73.41px):
+
+```
+display    128 116 104 96 88
+headline    96  88  80 72 64
+statement   72  64  58 52 46
+sub         52  48  44 40 36
+caption     44  40  36 32
+```
+
+**3. Line count and block height are first-class.** Overflow at the smallest rung
+sets a flag, and `assertNoOverflow` turns it into a build failure naming the scene
+and field. A silently shrunk-past-legibility headline is the kind of thing that
+ships and then looks amateur.
+
+Two- and three-line blocks additionally get **balanced**: the cut points are
+re-chosen to even out line widths, ties breaking toward the earliest cut so the
+result is deterministic. Ragged-right looks accidental at display sizes.
+
+`Intl.Segmenter` is available and would keep two-character words intact, but it is
+**off by default** — ICU word-break data varies between Chrome builds, so the same
+storyboard could break differently on two machines. Per-character plus kinsoku is
+self-contained and provably identical everywhere.
+
+## Fonts
+
+Two variable faces, named for what they are rather than the role they play, because
+real sites pair them both ways round:
+
+```
+FONT_SANS  = "H2V Sans"   ← Noto Sans SC VF
+FONT_SERIF = "H2V Serif"  ← Noto Serif SC VF
+```
+
+`art.displayFace` and `art.bodyFace` are **independent**. Anthropic, for instance,
+sets headings in a sans (`anthropicSans` 700) and body copy in a serif
+(`anthropicSerif`) — collapsing that to one toggle loses the contrast that makes a
+site's typography recognisable. `fontFor(role, art)` treats `display`, `headline`
+and `statement` as display roles and everything else as body.
+
+### Why not `@remotion/google-fonts`
+
+`NotoSansSC` there exposes **101 subsets x 9 weights**, and Chinese does not live
+in a subset you can name — it is spread across subsets literally called `"[21]"`
+through `"[119]"`. `loadFont()` creates one `FontFace` and one render-blocking
+`delayRender()` per (style, weight, subset), so loading Chinese "properly" means
+200+ handles and 200+ CDN fetches **per frame tab**. That is the `delayRender`
+blow-up, the nondeterminism and the payload problem in one.
+
+### Local subsetting
+
+`scripts/build_fonts.mjs` runs `pyftsubset` over the two variable sources with
+exactly the codepoints the storyboard uses, plus a fixed base set (ASCII,
+full-width punctuation and brackets, full-width digits, arrows and marks).
+
+Measured on a real 95-second board: **311 unique codepoints (188 CJK) becomes
+125.7 KB total** — versus about 36 MB for the full faces. Zero network at render.
+
+`pyftsubset` preserves the `wght` axis through subsetting (verified: `fvar` survives
+as wght 100..900), so **two files cover every weight in the scale**. They are
+registered with `weight: "100 900"` and one `delayRender` handle for both.
+
+The base set is always included because CJK punctuation is full-width and
+metrically load-bearing — the hardMax numbers above assume a 1.000em advance, so a
+fallback glyph there would break layout, not merely look wrong.
+
+Sources are pinned by URL and cached in `~/.cache/html2video/fonts/` so every
+machine subsets from byte-identical input. If the download fails the script falls
+back to a macOS system font **and says so**: system fonts differ between OS
+versions, so line breaking is no longer reproducible.
+
+## Details worth the code
+
+**Hanging punctuation on pull quotes.** The opening 「 gets `marginLeft: "-1em"`.
+CJK quotation marks occupy a full 1em box, so without hanging it the quote looks
+visibly indented relative to everything else in the frame. This is the difference
+between "generated" and "set".
+
+**`whiteSpace: "pre"` on fitted lines.** Kinsoku attaches trailing spaces to
+clusters; letting them collapse shifts the line away from what was measured.
+
+**`fontVariantNumeric: "tabular-nums"`** on any animating number, so digits do not
+jitter as they change width.

package/skills/html2video/references/editorial.md

@@ -0,0 +1,145 @@
+# READ: deciding what belongs on screen
+
+This is the stage with no script, and the one that decides whether the video is
+worth watching. Everything downstream is execution.
+
+The method below builds on the local `baoyu-slide-deck` skill's analysis
+framework and content rules, adapted for a timeline rather than a deck.
+
+## Start from the figures, not the prose
+
+On a research or engineering page, a `<figcaption>` is a finding compressed into
+one sentence, with its illustration already attached. The author did the hardest
+editorial work for you. Naive extractors drop captions as decoration; this
+pipeline carries them through, and they are usually the shortest path to a good
+video.
+
+So read `harvest.json`'s `figures[]` first, and only then the prose. A figure plus
+its caption is already a shot.
+
+**But check `captionSource` before you believe a caption.** Only `figcaption` is
+authoritative — it came from the page's own `<figure>` markup. `proximity` means the
+text merely followed the image, and it is wrong more often than not: on one real
+article all three proximity captions were ordinary body prose, and one of them
+described the *next* chart. `none` means the page gave nothing at all, which is
+common — plenty of sites wrap images in `<figure>` with no caption.
+
+When it is `proximity` or `none`, **open the image and read the finding off it.** A
+chart's own embedded title is usually the best single sentence available; re-author
+that as a Chinese headline and keep the English in `asset.sourceCaption`. Treating an
+unverified caption as a finding is the one way this stage can produce something
+confidently wrong.
+
+## Find what the article half-buries
+
+This is the part that separates the output from every automated blog-to-video
+tool, and it is worth being deliberate about. Those tools optimise for coverage
+and end up producing marketing. Go looking for:
+
+- **The limitation the author admits.** Real work states what it cannot do. The
+  reference article's own caption says "NLAs can hallucinate. For instance, here
+  an NLA claims the context contained phrases like 'Wearing my white jacket' when
+  it did not." That is the most persuasive material on the page, precisely because
+  nobody promoting the work would lead with it. Promote it to act three.
+- **The number that contradicts expectation.** Not the biggest number — the one
+  that reframes. "26% on SWE-bench versus under 1% in real usage" is a story; "26%"
+  alone is a statistic.
+- **The one concrete example that makes it click.** A model planning to end a
+  couplet on "rabbit" teaches more than a paragraph defining activations.
+- **The mechanism, once.** Readers forgive not knowing how something works, but a
+  video that never shows the mechanism feels like an advert.
+
+If a page has none of these, it may not be worth a video. Say so rather than
+producing filler.
+
+## The spine
+
+**Core message, 40 Chinese characters or fewer.** If the viewer remembers one
+sentence, this is it. Write it before anything else; it becomes the outro.
+
+**Three to five supporting points, ordered by audience relevance — not by where
+they appear in the article.** Source order optimises for a reader who will finish;
+a video has to earn each next second. Reordering is the single highest-leverage
+editorial move available, and the reference board uses it: the hallucination
+caption sits mid-article and becomes the third-act turn.
+
+**Pick an arc** and put it in `meta.arc`:
+
+| Arc | Fits |
+|---|---|
+| `problem-solution` | a new tool or method |
+| `situation-complication-resolution` | an incident, a debugging story |
+| `what-why-how` | teaching a concept |
+| `past-present-future` | a shift over time |
+| `claim-evidence-implication` | research results |
+
+## Triage everything
+
+Four buckets, and be willing to use the fourth:
+
+- **Keep** — the core argument, unique data, a quotable sentence, an admitted limitation
+- **Simplify** — technical detail becomes a visual summary; five examples become the best one
+- **Visualise** — a table becomes a stat; a process becomes a diagram walk; a comparison becomes a split
+- **Omit** — tangential background, redundant examples, related-content blocks, anything the audience already knows
+
+A 95-second video from a 10,000-character article keeps maybe 8% of the words. The
+discipline is in the omitting.
+
+## Write for the frame, not the page
+
+**Narrative headlines.** A headline should make a claim, not label a section.
+
+| Weak | Strong |
+|---|---|
+| 评测结果 | 26% 的题目它知道自己在被测 |
+| 方法介绍 | 一个负责说，一个负责猜 |
+| 局限性 | NLA 也会编造 |
+
+**Never use these** — they mark generated copy and add nothing:
+
+深入探讨 · 让我们看看 · 带你了解 · 一探究竟 · 惊艳 · 革命性 · 颠覆 · 赋能 ·
+总而言之 · 综上所述 · dive into · explore · journey · in conclusion
+
+**One idea per frame.** If there is more to say it is another scene. Crowding is
+solved with time, not with a smaller font.
+
+**Translate, don't machine-translate.** Chinese lines have to land as Chinese. A
+faithful rendering of an English sentence is usually a bad Chinese headline —
+tighten it until it reads like it was written that way. Keep technical terms in
+their original form (NLA, SWE-bench, Opus 4.6); translating them costs precision
+and looks unserious. Keep the original figcaption in `asset.sourceCaption` for
+provenance regardless.
+
+## Map content to shots
+
+| Content | Shot |
+|---|---|
+| Opening, the subject and its source | `title` |
+| A single claim with nothing to compete | `statement` |
+| One number that reframes | `stat` |
+| A sentence worth quoting verbatim | `quote` |
+| A finding plus its figure | `figure` |
+| Two states of one thing | `compare` |
+| A mechanism with sequential parts | `diagram` |
+| The limitation, the "but" | `caveat` |
+| Three or four takeaways | `ladder` |
+| The core message, and credit | `outro` |
+
+Vary the shape. Four `figure` shots in a row read as a slideshow no matter how
+good each one is. Alternate figure-led and text-led scenes, and let the `caveat`
+inversion land as the structural break it is.
+
+Aim for 8 to 11 scenes at 85 to 100 seconds. Fewer than 6 feels thin; more than 12
+means the article should be two videos.
+
+## Then check yourself
+
+Before writing the storyboard, answer these:
+
+1. Does the first scene give a reason to watch the second?
+2. Is there a moment a viewer would screenshot?
+3. Does anything appear on screen that the audience already knew?
+4. Would the frame still make sense if seen for less than one second?
+5. Is the most persuasive fact on the page actually in the video?
+
+Question 5 is the one that usually fails.