@navipartner/demo-video 0.7.0 → 0.7.2

package/skills/np-demo-video/look.md

@@ -1,103 +1,166 @@
 # The look
 
-Every NaviPartner demo video should look and feel the same, in order of importance for the visuals:
+Every NaviPartner demo video should look and feel the same. They are made
+for serious buyers: operators and owners choosing a system for their shops,
+restaurants and venues. They watch to understand, so a video is brisk where
+nothing is happening and gives information the time it needs. In order of
+importance:
 
-1. **The product tells the story; text only frames it.** No caption pills
-   over the UI. Words appear on their own cards *between* the chapters, never
-   on top of the app.
-2. **Calm, purposeful camera.** It moves between shots, never during the
-   action: one smooth push-in on the area where the chapter's action and its
-   result happen, held steady through the clicks, then back out. It never
-   chases the cursor, and there are no hard cuts inside a chapter.
-3. **Soft, light, branded.** A pale brand-tinted background, a floating app
-   window, serif statements, and one brand colour used boldly once or twice.
-4. **Real-looking data.** Believable names, orders and products in the
-   customer's language and market. Never "Test item 1".
+1. **The product tells the story; text frames it.** Words live on their own
+   cards *between* the chapters, never over the live app. A card may hold a
+   snapshot of what its chapter achieves beside the words: the app, captured,
+   not a mock-up.
+2. **No dead time.** Setup happens behind cards, only values that show
+   something are typed, and every beat is there so the viewer sees
+   something. Never rushed: results and cards stay up long enough to read.
+3. **Purposeful camera.** Every page opens wide, on the whole window. The
+   camera pushes in only where the action would be too small to read, and
+   then only after the viewer has seen where they are. It moves between
+   shots, never during the action, never chases the cursor, and there are no
+   hard cuts inside a chapter.
+4. **Soft, light, branded.** A pale brand-tinted background, a floating app
+   window, big serif statements, and the brand colour used boldly.
+5. **Believable data.** The most real-looking records the e2e mocks have.
+   Never "Test item 1" on screen when the story can type a better value.
 
-## Structure
+## Two kinds of video
 
-A video is a sequence of **chapters**. Each chapter is one idea the viewer
-should remember.
+A story says which it is (`"kind"`, default `showcase`). The beats are the
+same in both; the shape differs.
+
+| | Showcase | Feature clip |
+|---|---|---|
+| Shows | the app's main journey, from start to the moment of value (the primary story is always one) | one feature: "see the new split-bill button" |
+| For | the website, a sales meeting, a buyer comparing systems | release news, a LinkedIn post, a customer update |
+| Length | 45–90 s | 15–30 s |
+| Shape | open card, 2–4 chapters of 10–20 s, a payoff, end card | open card naming the feature, one chapter, end card |
+| Open and end cards | up to 3.5 s | up to 2.5 s |
+
+`check` keeps a feature clip to one chapter and a showcase to four, and
+prints how long the story will run.
+
+### Showcase
 
 ```
-open card      2–4 s   eyebrow "Introducing" + wordmark/logo; tagline fades in
-┌ statement    2–3 s   "A customer *scans* their basket."
-│ demo         10–25 s the app doing exactly that, camera following
-└ payoff       3–5 s   optional: what just happened, as a fact
+open card      ≤ 3.5 s  logo + what the product does for the buyer + a snapshot of the result
+┌ chapter card ~2–4 s   "Pay *by card*." + the benefit in one line, beside a snapshot of the result
+│ demo         10–20 s  the app doing exactly that, ending on the result
+└ payoff       ~3–4 s   optional: the result just shown, as a fact
 … 2–4 chapters …
-tagline        2–3 s   one line on brand colour: "Checkout that runs itself."
-end card       3–5 s   logo + tagline, still
+end card       ≤ 3.5 s  logo + the promise, or the next step
+```
+
+### Feature clip
+
+```
+open card      ≤ 2.5 s  logo + "New: …" + a snapshot of the feature
+┌ chapter card ~2–3 s   the feature's statement + what it does for the customer
+│ demo         8–15 s   straight to the feature; all setup behind the card
+end card       ≤ 2.5 s  logo + where it is available
 ```
 
-- 30 s is enough for one chapter, 60–95 s for three or four. Length follows
-  the chapters. Don't pad, don't cram.
-- The first chapter's statement lands by second 6. The hook is the
-  open card plus the first statement, and nothing else.
-- A chapter ends wide (the whole window), so the next card has something to
-  dissolve from.
+- **The first seconds carry brand and product.** The open card shows the
+  logo and a snapshot of the result (a showcase) or of the feature (a clip),
+  so a viewer who stops after two seconds has seen both.
+- Setup the viewer needn't watch (a language dialog, a cookie banner,
+  opening a tab) happens behind the card before it, never on screen.
+- Length follows the chapters: don't pad, don't cram.
 
-## Text cards
+## Cards
 
 | Card | Text | Look |
 |---|---|---|
-| Open | eyebrow `Introducing` (small sans, grey) · brand wordmark/logo · tagline | pale background, centred |
-| Statement | ≤ 7 words naming what the next chapter shows, sentence case, ends with a full stop, **one word or phrase in italic** (the action or its result): "Pay *by card*." | dark serif on pale background |
-| Payoff | the result just shown as heading; sub-line states the concrete fact the app showed: "64,50 kr. by card." | white serif on full-bleed brand colour |
-| Stat | a number + what it counts: "60+ integrations" | pale, optional logo grid |
-| Tagline | the product's promise in ≤ 5 words | brand colour or pale, alternating |
-| End | logo + one-line tagline | pale, held still |
-
-- **Typeface:** the brand's fonts. For NaviPartner that's **Merriweather** for
-  headings (its italic is the emphasis word) and **Work Sans** for eyebrows and
-  sub-lines.
-  At 1080p: logo ~110 px tall equivalent, statements ~70 px, sub-lines
-  ~18–22 px.
-- **Tone:** plain, confident, present tense. No exclamation marks except
-  inside a quoted customer line. No "seamless", "revolutionary" or
-  "effortless".
-- **Truth:** every fact on a card must be visible in the video itself (the
-  price shown, the receipt that appears), checked by an `expectText`. No
-  invented durations or customer statistics. Stat cards only state real
-  product facts, such as the number of payment methods the app supports.
+| Open | eyebrow (`Introducing`, or `New` for a clip) · brand logo · one line on what it does for the buyer · a snapshot of the result | pale |
+| Chapter | the statement and the benefit (below), beside a snapshot of the result when there is one | pale and brand colour alternate, chapter by chapter |
+| Payoff | the result just shown; the sub-line states the fact the app showed: "64,50 kr. by card." | full-bleed brand colour |
+| End | logo + the product's promise, or the next step: "Book a demo at navipartner.com." | pale, held still |
+
+A **chapter card** has two lines of words, and no eyebrow: chapter numbers
+and topic labels don't help in a film this short.
+
+1. **Statement:** ≤ 7 words naming what the chapter shows, in its own verb,
+   sentence case, ending with a full stop, **one word or phrase in italic**
+   (the action or its result): "Pay *by card*."
+2. **Benefit:** one sub-line, ideally ≤ 12 words, saying what it does for
+   the customer as something the chapter then shows. An outcome, not a
+   feature name, and a specific value when the app shows one: "Tap, insert
+   or phone: the terminal takes it all."
+
+**Text and UI on one card.** A card shows a snapshot of the result beside
+the words when there is something visual to show: the finished pass, the
+receipt, the "Paid" screen. The words go left, the snapshot right, in the
+same rounded window and soft shadow as the app. It is the app, captured by
+`check`, never a mock-up. A chapter that ends on a toast or a number stays
+text only, centred.
+
+- **Typeface:** the brand's fonts. For NaviPartner: **Merriweather** for
+  statements (its italic is the emphasis word), **Work Sans** for eyebrows
+  and sub-lines. At 1080p: statements 116 px (92 px beside a snapshot),
+  sub-lines 40 px (36 px), the open card's eyebrow 28 px spaced capitals,
+  logo 720 px wide.
+- **Tone:** plain, confident, present tense, for a professional audience.
+  No exclamation marks except inside a quoted customer line. No "seamless",
+  "revolutionary" or "effortless".
+- **Truth:** every fact on a card is visible in the video (the price shown,
+  the receipt that appears), checked by an `expectText`. No invented
+  durations or customer statistics.
 - **Never on a card:** testids, barcodes, internal names or any other code.
-- **Reading time:** a card stays up at least 1 s plus ~0.3 s a word.
+- **Reading time:** a card stays up 0.5 s plus ~0.25 s a word of its
+  statement and ~0.2 s a word of its sub-line (an eyebrow's words 0.12 s),
+  at least 1.6 s. The open and end cards stay at most 3.5 s in a showcase
+  and 2.5 s in a clip, unless the story asks for more. Setup behind a card
+  that takes longer holds it up: `check` says so.
 
 ## Transitions
 
-- **Blur dissolve** everywhere. Text blurs in from ~12 px to sharp over
-  ~500 ms. A card hands over to the app by blurring out while the app blurs in
-  behind it (~700 ms).
-- Into a payoff card: the brand colour washes over the wide app (~600 ms),
-  then the heading blurs in.
-- Card to card: the old words blur out first (~300 ms), then the new ones
-  blur in, so two headings never show at once.
+- **Blur dissolve** everywhere. A card's words blur in from ~12 px to sharp
+  over ~500 ms, one after the other: statement, snapshot, sub-line. A
+  card hands over to the app by fading out (~600 ms) while the app sharpens
+  behind it.
+- Card to card: the old words blur out first (~240 ms), then the new ones
+  blur in, so two statements never show at once.
 - No slides, wipes, spins, or zoom-punch transitions.
 
 ## Camera
 
-- **Wide shot:** the app floats in the middle of the frame at ~90 % width.
-  Small corner radius, soft long shadow, no browser chrome.
-- **Push in once per shot** on the area that holds the control *and* what it
-  changes, to scale **1.4–1.8** (never past 2: tighter loses the context and
-  softens the picture). The UI should fill the frame and read on a phone.
+- **Wide is the default.** The app floats in the middle of the frame at
+  ~90 % width, with a small corner radius, a soft long shadow and no browser
+  chrome. A wide shot whose text reads (16 px or more on the 1080p frame)
+  needs no push-in.
+- **A page never opens zoomed.** Every chapter opens wide when its card
+  dissolves, and so does every new screen. When a push-in is needed, the
+  whole window is seen first (the engine holds it ~0.8 s), then the camera
+  moves in.
+- **Push in only where it's needed:** where the text is too small to read
+  wide (`check` asks for it), or to read a result. Frame the control *and*
+  what it changes, and no tighter than it takes to read (scale 1.3–1.8,
+  never past 2: tighter loses the context and softens the picture). A live
+  preview that the action changes belongs in the shot.
 - **Hold steady through the action.** The clicks happen inside the shot; the
   camera doesn't move with them. At most two push-ins a chapter.
 - **Show the result.** When an action changes something outside the shot (a
   row added at the top, a new screen), pull out right after it. A push-in
   that shows a button pressed and nothing happening is the worst shot.
-- **Each move eases in and out** (engine: 1200 ms,
-  `cubic-bezier(0.65, 0, 0.35, 1)`), then settles 300 ms before anything
-  happens. Hold ≥ 1.5 s on anything the viewer must read.
-- Every chapter opens wide: the engine resets the camera behind each card.
+- **End on the result.** The last shot of a chapter frames what it achieved
+  (the pass with its wallet badge, the receipt), held long enough to read,
+  then the card covers it.
+- **Each move eases in and out** (engine: 900 ms,
+  `cubic-bezier(0.65, 0, 0.35, 1)`), then settles 150 ms before anything
+  happens.
 
 ## Cursor
 
-- A small standard arrow, used sparingly. It appears for the clicks and drags
-  a person would make. It glides on a gentle curve, easing in and out
-  (550–1100 ms by distance), and doesn't pulse, ripple or jerk.
-- **A beat around every click:** it rests on the control (220 ms, its hover
+- A small standard arrow, used for the clicks and drags a person would make.
+  It glides on a gentle curve, easing in and out (400–800 ms by distance),
+  and doesn't pulse, ripple or jerk.
+- **A beat around every click:** it rests on the control (160 ms, its hover
   state shows), presses (110 ms, the pressed state shows), and the app's
-  reaction plays (650 ms) before anything else happens.
+  reaction plays: 450 ms, then until the app has settled (a toast after a
+  save, a preview redrawn), up to a second more.
+- **Every control the viewer sees used gets the cursor**, a colour picker or
+  an upload as much as a button: an adapter action names its control, and
+  the cursor goes there and rests before it acts.
+- Typing runs at ~45 ms a character.
 - Between actions it rests where it doesn't cover what the viewer should
   read.
 - If the UI animates by itself (an order total updating, a status changing),
@@ -108,10 +171,10 @@ end card       3–5 s   logo + tagline, still
 - **Background:** white tinted ~5–8 % with the brand's primary colour, with
   one or two very soft radial blooms. Never a busy wallpaper, and never
   dark mode.
-- **Brand colour:** the full-bleed payoff and tagline cards are the brand
-  colour. The brand's logo and wordmark are on the open and end cards. The
-  app itself is shown in the customer's branding (their kiosk looks like
-  their kiosk).
+- **Brand colour:** payoffs and every other chapter card are full-bleed
+  brand colour. The brand's logo is on the open and end cards. The app
+  itself is shown in its tenant's branding (their kiosk looks like their
+  kiosk).
 - **Brand:** NaviPartner's (below). A pitch draft (linear.md) swaps in a
   customer's researched logo, colours and fonts, following the same roles.
 
@@ -122,23 +185,23 @@ These values are taken from navipartner.com and the official logo
 
 | Role | Value |
 |---|---|
-| Primary: full-bleed payoff and tagline cards, italic emphasis word, background tint | `#1F5494` |
-| Navy: logo wordmark, statement headings on pale cards | `#123A7E` |
+| Primary: brand cards, italic emphasis word, the open card's eyebrow, background tint | `#1F5494` |
+| Navy: logo wordmark, statements on pale cards | `#123A7E` |
 | Light blue: the logo's "NAVI" mark, soft background bloom, sparingly | `#729FD3` |
-| Text: sub-lines and eyebrows | `#232323`; muted `#707070` |
+| Text: sub-lines | `#232323`; muted `#707070` |
 | Pale background base | `#F8F8F8` / `#FFFFFF` |
 | Heading font | Merriweather 400/700, italic for the emphasis word |
 | Body font | Work Sans 400/600/700 |
 | Logo | official two-colour SVG: `#729FD3` mark + `#123A7E` wordmark, on pale backgrounds only. On `#1F5494`, use it all white. |
 
 A NaviPartner pale card is `#F8F8F8` with a `#1F5494` tint at ~5 % and one
-`#729FD3` bloom, with the heading in navy and the italic word in primary. A
-brand card is full-bleed `#1F5494` with the heading in white Merriweather and
-the sub-line in white Work Sans at 80 % opacity.
+`#729FD3` bloom, with the statement in navy and the italic word in primary.
+A brand card is full-bleed `#1F5494` with the statement in white
+Merriweather and the sub-line in white Work Sans at ~85 % opacity.
 
 Keep the two brand layers apart. The cards and background use the video's
 brand (NaviPartner, or the customer's). What's inside the app window is the
-kiosk's tenant branding from the adapter's brand file.
+app's tenant branding from the adapter.
 
 ## Sound
 
@@ -152,5 +215,42 @@ the whole story.
   This is used for the website and the LinkedIn feed.
 - **Portrait kiosk apps** (food order 1080×1920) float centred in the 16:9
   frame, and the camera pushes in the same way.
-- 1:1 / 9:16 cuts for SoMe come later. Keep card text inside the central
-  1080×1080 area so a square crop still works.
+- 1:1 / 9:16 cuts for SoMe come later. Text-only cards keep their words
+  inside the central 1080×1080 area; a card with a snapshot will stack it
+  under the words there.
+
+## Where these rules come from
+
+Researched October 2026. Apple-style ads composite their UI in afterwards;
+we film the real app, so we borrow their discipline (one message per shot,
+the product as the hero), not their technique.
+
+- **Showcase length and pace.** Wistia's data on 1.1 million videos: product
+  and explainer videos keep over half their viewers up to a few minutes,
+  with the steepest drop after two; put what matters early. B2B launch
+  videos run 30–60 s, explainers 60–90 s. A buyer can follow a slower video
+  that carries real information, so cut dead time, not information.
+  ([Wistia](https://wistia.com/blog/optimal-video-length),
+  [Flowjam](https://www.flowjam.com/blog/b2b-saas-launch-video))
+- **Feature clips and the first seconds.** In feeds, attention is decided in
+  the first 2–3 seconds; brand in the first 5 (Google's ABCD) or 2
+  (LinkedIn: a visible logo lifts click-through 17%), and lead with the
+  product in use, not only a logo (Meta). Short ads do best around 15–30 s.
+  ([Think with Google](https://thinkwithgoogle.com/_qs/documents/8472/ABCD_Complete_V7b_HR_1.pdf),
+  [LinkedIn via Storykit](https://storykit.io/blog/linkedin-video-ads-best-practices),
+  [Meta via Cinerads](https://www.cinerads.com/blog/meta-ads-video-creative-best-practices))
+- **Silent by design.** About 80 % of LinkedIn video and 85 % of Facebook
+  video is watched without sound, so the cards carry every claim.
+- **What goes on a card.** One idea per scene with one supporting line; the
+  benefit a viewer grasps fastest beats the feature's name; specific numbers
+  beat vague claims; short labels hold viewers.
+  ([Nemo](https://www.nemovideo.com/blog/kinetic-typography-product-ads),
+  [Arcade, 14 million demo sessions](https://www.arcade.software/post/2026-arcade-benchmarks))
+- **Reading time.** Netflix allows at most 20 characters a second, text up
+  0.83–7 s; the BBC works to about 0.3 s a word. Our cards are read faster
+  than subtitles (0.25 s a statement word, 0.2 s a sub-line word): the viewer
+  isn't also following speech.
+  ([Netflix](https://backlothelp.netflix.com/hc/en-us/articles/219375728))
+- **Camera.** Screen Studio's "Focused" motion settles quickly so UI can be
+  read; that is the model: quick moves, then stillness.
+  ([Screen Studio](https://screen.studio/guide/animations))

package/skills/np-demo-video/reference.md

@@ -1,4 +1,4 @@
-# Reference: adapter, story and brand fields
+# Reference: adapter, story, brand and check
 
 ## Adapter (`<app>/demo/demo.config.ts`)
 
@@ -7,9 +7,10 @@ the mocks booted the app), `viewport` (default 1728×972; a portrait kiosk is
 scaled to fit) and `setup(page, { brand })`, which runs the app's e2e mocks
 **unchanged** and lays the brand over the response that carries it.
 Optional: `actions` (app steps such as a barcode scan), `idleTimeoutSeconds`,
-`locale`, `timezone`, and `brandNeeds`: the `config` keys and asset slots `setup` uses, each a
-description (where it shows, what shape) or `{ what, optional: true }`. A
-brand without a need that isn't optional fails `check`.
+`locale`, `timezone`, and `brandNeeds`: the `config` keys and asset slots
+`setup` uses, each a description (where it shows, what shape) or
+`{ what, optional: true }`. A brand without a need that isn't optional fails
+`check`.
 
 ```ts
 import { defineDemo, overlayResponse } from "@navipartner/demo-video";
@@ -42,30 +43,88 @@ export default defineDemo({
 
 ## Story (`<app>/demo/stories/<name>.json`)
 
-`app`, `description`, optional `primary`, `title`, `closing`, `steps`.
-
-- **Steps:** `click` `type` `press` `zoom` `frame` `zoomOut` `park` `waitFor`
-  `expectText` `hold` `card`, plus the adapter's actions as
-  `{ "do": "<action>", …params }`. `target` is a testid or any Playwright
-  selector (`role=button[name=/pay/i]`); `nth` picks among matches (-1 =
-  last). Clicks wait until their target stops moving.
-- **Cards** (`card`, `title`, `closing`): `eyebrow` (≤ 4 words), `heading`
-  (≤ 8, `*word*` in italic, once), `sub` (≤ 16), `logo`, `style` (`pale` |
-  `brand`), `seconds` (a minimum: a card stays up long enough to read).
-  Cards that follow each other hand over directly. A number on a card must be
-  checked by an `expectText` in the story.
-- **Camera:** `zoom` (`target`, `scale` 1.3–2) pushes in on that element's
-  area; `frame` (`targets`: 2–4 testids or `{ target, nth }`, optional
-  `maxScale` 1.3–2, default 1.8) pushes in as far as all of them fit, and
-  fails if they only fit wide; `zoomOut` (`park`) pulls back. A `click` keeps the camera unless it
-  has its own `"zoom"`. At most two push-ins a chapter, and a zoom needs
-  something done or read in its shot. A click target must be inside the
-  current shot, and what a zoomed click changes must be in the shot or shown
-  by the next step (a `zoomOut`, or a zoom that frames it). Every chapter
-  opens wide.
-- **Timing:** `hold` ≤ 6 s; `type` `perCharMs` ≥ 40. The engine adds the
-  beats around clicks, the camera's settle and a linger before each card.
-  Holds may not add up past the app's idle timeout.
+`app`, `description`, optional `kind` (`showcase`, the default, or
+`feature`), `primary` (a showcase), `title`, `closing`, `steps`.
+
+| Step | Fields |
+|---|---|
+| `click` | `target`, `nth`, `zoom` (push in on it first, 1.3–2), `behindCard` |
+| `type` | `target`, `nth`, `text`, `perCharMs` (≥ 40, default 45), `replace` (clear the field first; without it the text goes at its end), `behindCard` |
+| `press` | `key`, `behindCard` |
+| `zoom` | `target`, `nth`, `scale` (1.3–2) |
+| `frame` | `targets` (2–4 testids or `{ target, nth }`), `maxScale` (1.3–2, default 1.8) |
+| `zoomOut` | `park` (rest the cursor too) |
+| `park` | rests the cursor in empty space |
+| `waitFor` | `target`, `nth`, `hidden`, `timeout` (s), `behindCard` |
+| `expectText` | `target`, `nth`, `text`, `contains`, `timeout` (s) |
+| `hold` | `seconds` (≤ 6) |
+| `card` | see Cards |
+
+Plus the adapter's actions as `{ "do": "<action>", …params }`. `target` is a
+testid or any Playwright selector (`role=button[name=/pay/i]`); `nth` picks
+among matches (-1 = last). Clicks wait until their target stops moving.
+
+**Cards** (`card`, `title`, `closing`): `heading` (≤ 7 words, `*word*` in
+italic, once), `sub` (≤ 16 words; a chapter card's benefit ≤ 10), `logo`,
+`style` (`pale` | `brand`; chapter cards without one alternate, pale first),
+`seconds` (a minimum: a card stays up long enough to read), and on `title`
+and `closing` only, `eyebrow` (≤ 4 words). `title` may `show` an element
+too: a snapshot of it as it last looks in the story, beside the logo. A `card` step may `show` an element
+(a testid or `{ target, nth }`): a snapshot of it beside the words, as it
+last looks in the chapter after the card (on a payoff, as the card comes up).
+Cards that follow each other hand over directly. A number on a card must be
+checked by an `expectText` in the story.
+
+**Behind a card:** `behindCard` steps right after a card (or at the very
+start, behind the title card) run while the card covers the app, with no
+cursor and no camera. `click`, `type`, `press`, `waitFor` and adapter
+actions take it; never a push-in, since every chapter opens wide. A card stays up until what's behind
+it is done: `check` names a card whose setup outlasts its reading time.
+
+**Camera rules** (`check` enforces them): every page opens wide, and a
+push-in from the wide shot comes after the whole window has been seen. At
+most two push-ins a chapter, and a push-in needs something done or read in
+its shot. A control a step uses must be inside the current shot. What it
+changes (watched from the press to the app settling: typing's preview, a
+toast, a restyle) must be in the shot or shown by the next step (a
+`zoomOut`, or a zoom that frames it). A wide shot whose text is under 16 px
+on the frame, where the controls and what they change would fit a push-in
+of 1.4 or more, needs one.
+
+**Adapter actions** may name the control they use (`target(params)`); the
+cursor then goes there and rests, and the camera rules apply as for a
+click. Without one, an action has no cursor and only a short beat after
+it.
+
+**Timing:** the engine adds the beats around clicks, the camera's settle and
+a linger before each card (look.md has the numbers). Holds may not add up
+past the app's idle timeout. A passing `check` prints the story's estimated
+length against its kind's range (`seconds` and `kind` in `--json`).
+
+## What `check` says, and the fix
+
+| It says | Fix |
+|---|---|
+| `"x" is outside the shot …` | `zoomOut` first, or frame an area that holds everything the shot uses |
+| `clicking / typing in / using "x" changes y, which is outside the shot …` | `zoomOut` right after, or frame the control with what it changes |
+| `"x" is used in the wide shot, where its text is N px, too small to read …` | `frame` the controls and what they change (the engine pushes in after a wide beat); or, if it's setup, `behindCard` |
+| `N camera push-ins in one chapter` | Push in once on the chapter's area and hold steady |
+| `… only fit in the wide shot` | Stay wide, or frame things that sit together |
+| `a zoom with nothing in its shot` | Remove it, or act or read something in it |
+| `zoom 2.4; use 1.3–2` | Zoom less: context reads better and stays sharp |
+| `behindCard only right after a card` | Move the step to just after a card, or drop `behindCard` |
+| `"x" (show) never appears in the chapter …` | Show an element the chapter ends on |
+| `cards between chapters have no eyebrow` | Remove it: the statement and sub-line carry the chapter |
+| `… shows the same snapshot` | Show each result once: on the open card or on a chapter card |
+| `title.show: "x" never appears in the story` | Show an element the story reaches: its result, or the feature |
+| `kind: a feature clip shows one feature, in one chapter` | Cut it to the feature's one chapter, or make it a showcase |
+| `N chapters; a showcase has at most 4` | Make a second story |
+| `kind: the primary story … is a showcase` | Drop `"kind": "feature"` from the primary story |
+| `"…" looks like a testid-like name / barcode / code` | Cards are for people: say it in words |
+| `"38" isn't shown by an expectText` | Quote only values an `expectText` checks |
+| `the card announces a chapter in which nothing is done` | Follow it with the steps it describes (setup behind the card doesn't count) |
+| `… names a brand or extends a story` | Remove it: a customer's branding is @Linear's, a translation is a story of its own |
+| `…/demo/brands isn't used` | Delete the folder: repos keep no brands |
 
 ## Brand (the engine's `navipartner`, or one a pitch draft builds)
 
@@ -73,8 +132,8 @@ export default defineDemo({
 - `config`: opaque to the engine, the keys the app's branding API reads
   (`primaryColor`, …). An adapter may also read `config.demoData`: names
   for the mock's products, keyed by the mock's barcodes (prices and flows
-  stay the mock's). It takes `demoData` out before it
-  overlays the branding.
+  stay the mock's). It takes `demoData` out before it overlays the
+  branding.
 - `assets`: slot → file, e.g. `{ "logo": "navipartner/logo.svg" }`
 - `video`: `primary`, `ink`, `accent`, `text`, `headingFont`, `bodyFont`,
   optional `fontsUrl`, `logo` (asset slot)