@autoaiai/aicut 0.1.11 → 0.1.13

package/skills/html2video/SKILL.md

@@ -1,290 +0,0 @@
----
-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

@@ -1,173 +0,0 @@
-# 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

@@ -1,145 +0,0 @@
-# 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.