reelkit-cli 0.1.0 → 0.1.2

package/README.md

@@ -4,7 +4,7 @@ A CLI and a Claude skill for making short-form video. Claude plans the video and
 
 ## Requirements
 
-- Node 20 or newer
+- Node 22.12 or newer
 - ffmpeg
 - A Reelkit account (accounts open when the service launches)
 
@@ -61,7 +61,7 @@ reelkit render
 | `reelkit assets gen image` | Generate a scene's illustration |
 | `reelkit plan check` | Validate `plan.json` |
 | `reelkit check` | Check the composition without rendering |
-| `reelkit preview` | One test frame per scene |
+| `reelkit preview` | Two test frames per scene |
 | `reelkit render` | Render `out/video.mp4` |
 
 ## What is shared

package/package.json

@@ -1,17 +1,9 @@
 {
   "name": "reelkit-cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "CLI and Claude skill for making short-form video with a shared asset library.",
   "license": "MIT",
   "author": "Daniel Livshin",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Livshind15/reelkit.git"
-  },
-  "homepage": "https://github.com/Livshind15/reelkit#readme",
-  "bugs": {
-    "url": "https://github.com/Livshind15/reelkit/issues"
-  },
   "keywords": [
     "video",
     "short-form",
@@ -47,7 +39,7 @@
     "skill"
   ],
   "engines": {
-    "node": ">=20"
+    "node": ">=22.12"
   },
   "publishConfig": {
     "access": "public"
@@ -85,5 +77,6 @@
     "vitest": {
       "optional": true
     }
-  }
+  },
+  "homepage": "https://reelkit-kohl.vercel.app"
 }

package/skill/SKILL.md

@@ -25,8 +25,11 @@ For each file the user gives, look at it, then register it with a description of
 `reelkit assets upload ./logo.png --describe "Acme logo, white wordmark on blue"`
 Add `--footage` for a video the motion design should be laid over. User files stay on this machine.
 
-### 2. Plan
-Read `reference/scriptwriting.md` and `reference/scene-treatments.md`. Run `reelkit assets voices` and choose a voice that fits the idea, audience and language.
+### 2. Look
+Read `reference/styles.md` and agree the video's look with the user: one of its looks, or their own. If they already described what they want, match it and confirm in one sentence. Ask anything still open in one message, each question with a default. If any on-screen text will be Hebrew, read `reference/hebrew-rtl.md` now: it changes how words may enter and how lines are written.
+
+### 3. Plan
+Read `reference/scriptwriting.md` and `reference/scene-treatments.md`. Write the chosen look into the first scene's `notes`. Run `reelkit assets voices` and choose a voice that fits the idea, audience and language.
 
 Write `plan.json`:
 
@@ -59,19 +62,19 @@ Write `plan.json`:
 - `userAssetIds` lists the ids of the user's files shown in that scene.
 - `pace` is `slow`, `normal` or `fast`.
 
-Run `reelkit plan check`. Fix everything under "Fix these". Act on "Worth improving" unless you have a good reason not to.
+Run `reelkit plan check`; it prints the estimated length to tell the user. Fix everything under "Fix these". Act on "Worth improving" unless you have a good reason not to.
 
-**Checkpoint.** Show the user the title, the estimated length, and each scene's narration, on-screen text and one line on the visual. Wait for a clear yes. A question or a comment is not approval: answer it and ask again.
+**Checkpoint.** Show the user the look, the title, the estimated length, and each scene's narration, the exact on-screen text and one line on the visual, in plain words about what they will see. Wait for a clear yes. A question or a comment is not approval: answer it and ask again.
 
-### 3. Voice
+### 4. Voice
 `reelkit assets voiceover --all`. It records each scene and prints the real length of the video. If the user wants a different voice, change `voiceId` in `plan.json` and run it again with `--redo`.
 
-### 4. Images
+### 5. Images
 Read `reference/asset-reuse.md`. For each illustration scene, search first:
 `reelkit assets search "<what the scene needs>" --kind image`
 Each result starts with a match percentage: how likely it is good enough to reuse. Pull the best result (`reelkit assets pull <id> --scene <sceneId>`) when its match is 60% or more and, reading its description, it fits the scene. Otherwise generate: `reelkit assets gen image --scene <sceneId>`. Never give two scenes the same image.
 
-### 5. Composition
+### 6. Composition
 Read `reference/kit.md`, `reference/remotion-composition.md`, `reference/motion-design.md` and `reference/captions.md`.
 
 - Search the library before writing a component: `reelkit assets search "<what it shows>" --kind component`. To use one, `reelkit assets pull <id>`: it lands in `src/` and the command prints the import line and an example.
@@ -80,11 +83,13 @@ Read `reference/kit.md`, `reference/remotion-composition.md`, `reference/motion-
 - Write `src/Video.tsx` and any component files beside it. `Video.tsx` may import only `react`, `remotion`, `reelkit/kit` and sibling components (`./Name`).
 - `manifest.json` is the exact object passed to `Video` as the `manifest` prop. Media is referenced as `urls[path]`, where `path` is the file's path in the project, such as `urls[scene.voiceoverKey]` or `urls["assets/lib/<id>/clip.mp3"]`.
 
-Run `reelkit check` and fix every error until it passes. Then `reelkit preview` and look at each frame in `out/preview/`. Look for: text cut off or overflowing, text overlapping other text or the captions, text too small or too low-contrast for a phone, an empty or broken frame, content hidden behind another layer, and any number, price or quote on screen that is not in the plan. A frame is one moment: an element mid-animation is not a problem. Fix real problems and preview again.
+Run `reelkit check` and fix every error until it passes. Then `reelkit preview` (the first preview on a machine downloads a browser once and can take a minute) and look at every frame in `out/preview/`: each scene has two, `early` (30% into the scene) and `late` (90%), so look at both frames of each scene. Look for: text cut off or overflowing, text overlapping other text or the captions, text too small or too low-contrast for a phone, an empty or broken frame, content hidden behind another layer, and any number, price or quote on screen that is not in the plan. A frame is one moment: an element mid-animation is not a problem, but anything that should be fully on screen by the late frame and is not is. Fix real problems and preview again. Go round at least twice, and finish with the studio test in `reference/motion-design.md`.
+
+You only ever see frames, never the moving video, so the frames are your eyes: look at every one. And whoever built a video is the worst judge of it. If you can start a separate agent, give it only the user's original request and the preview frames (not your explanations) and ask for a score out of 100 per scene, a list of flaws, and a concrete fix for each, in numbers ("raise the title 60 px", "hold the label 0.4 s longer"). Fix, preview, and have the same reviewer look again until every scene passes 90. If two rounds leave a scene under 70, stop and show the user the gap instead of spending more rounds.
 
-**Checkpoint.** Show the user the preview frames. Wait for a clear yes. For changes, edit the code, `reelkit check`, `reelkit preview`, and show them again.
+**Checkpoint.** Show the user the preview frames (both of each scene). Wait for a clear yes. For changes, edit the code, `reelkit check`, `reelkit preview`, and show them again.
 
-### 6. Render
+### 7. Render
 `reelkit render`. Give the user the path it prints.
 
 If the render fails, read the error, fix the composition, and run `reelkit check` before rendering again.
@@ -96,6 +101,7 @@ If the render fails, read the error, fix the composition, and run `reelkit check
 - The user's own files are private. Do not pass `--share` unless they ask you to contribute a file.
 - Pass the user's facts through unchanged. Never invent a number, statistic, price or quote.
 - Keep components driven by props, not hardcoded, so they can be reused.
-- One stage at a time. Do not render before the user has approved the preview.
+- One stage at a time. Do not write composition code before the user has approved the plan, and do not render before they have approved the preview.
+- Never say a video is done without having looked at its frames and checked that the file exists.
 - If a command reports that a quota is used up, tell the user what ran out and when it resets. Do not work around it. A message that says to wait a minute or an hour ("Too many searches", "Too many uploads started") is a throttle, not a used-up quota: wait and retry once instead of stopping.
 - Reply in the user's language.

package/skill/reference/captions.md

@@ -23,7 +23,7 @@ Do not mix modes between scenes. Set `highlight` to the palette's hero colour (c
 
 ## Words per screen
 - `pop`: 1 to 3 words (`perLine` 1 to 3). Short words can share a screen.
-- `highlight` and `karaoke`: 3 to 5 words for vertical video, up to 6 for landscape.
+- `highlight` and `karaoke`: 3 to 5 words for vertical video, up to 6 for landscape. In Hebrew, at most 4.
 - Never show a full sentence at once. Word-level timing reads better than sentence captions.
 
 ## Timing
@@ -33,11 +33,16 @@ Do not mix modes between scenes. Set `highlight` to the palette's hero colour (c
 - No caption group should flash by in under about 0.25 seconds.
 
 ## Position and safe zone
-- Vertical video (1080 by 1920): keep captions at least 200 to 300 px above the bottom edge and 40 to 60 px from the sides; platform buttons and descriptions cover the rest. The component's `bottom` prop (a fraction of the height, default 0.16) controls this.
+- Vertical video (1080 by 1920): keep captions at least 200 to 300 px above the bottom edge and inside pixels 140 to 940 across (tall phones crop about 100 px from each side); platform buttons and descriptions cover the rest. The component's `bottom` prop (a fraction of the height, default 0.16) controls this.
 - Keep the top 150 to 200 px clear as well.
 - Captions must never overlap other on-screen text. If a scene has a low headline or a lower-third, raise `bottom` or move the graphic.
 - In footage mode, do not cover the subject's face.
 
+## Read them before you show them
+- Read every caption as part of its whole sentence, not word by word. A word that is spelled right but is the wrong word ("on" for "an", one Hebrew homophone for another) only shows up in context.
+- The captions must say what the narration says, letter for letter. Never tidy a user's wording in the caption alone.
+- A number, name or unusual word is where mistakes hide: check each one against the plan.
+
 ## Legibility
 - Heavy sans-serif weight, large: about 5.5 percent of the width for line captions, 7.5 percent for pop. The component sets these.
 - Contrast of at least 4.5 to 1 against whatever is behind. The component adds a dark outline and shadow; on very bright footage also dim the footage.

package/skill/reference/hebrew-rtl.md

@@ -0,0 +1,51 @@
+---
+name: hebrew-rtl
+description: Use whenever any text on screen is Hebrew - which faces to use, direction, how words may enter, punctuation and hyphens, line breaks, and what to check in the preview frames.
+---
+
+# Hebrew on screen
+
+Most broken Hebrew videos break in the same few ways. These rules are for text drawn by the composition; the narration and captions follow them too.
+
+## Faces
+- Set Hebrew in a Hebrew face from the kit (see `reference/kit.md`): `heebo`, `rubik`, `notoSansHebrew`, `assistant` and the display faces listed there. A Latin-only face silently falls back and the weights stop matching.
+- One Hebrew family for the whole video, two weights. Heavy weights (800, 900) for headlines; 500 to 700 for labels.
+- No faces that look antique, and no hollow outlined words: Hebrew letterforms lose their shape as outlines.
+- Small technical labels that are only Latin letters and digits ("W 612", "v2") may use a mono Latin face. Never set Hebrew in it.
+
+## Direction
+- Give every Hebrew text container `direction: "rtl"`. Without it the full stop, comma and exclamation mark jump to the wrong end of the line.
+- Digits and Latin words inside a Hebrew sentence order themselves when the base direction is RTL. A label that is entirely Latin or digits gets `direction: "ltr"`.
+- Everything laid out in reading order runs right to left: the first word on the right, the first list item on the right or top, tabs, chat bubbles, steps, and charts over time (the first day on the right).
+- **The exception:** progress bars, sliders, loading bars and media timelines still fill left to right, as every player does.
+- A typing effect adds characters in reading order; the caret sits at the left end of the text, where it grows.
+- Captions: pass `rtl` and a Hebrew `face` to the kit's captions.
+
+## How words enter
+- **No masked reveals.** A Hebrew word uncovered by a moving edge (a clip, a wipe, an overflow-hidden box it rises out of) reads for a moment as a row of dashes or as a different word, because so much of the letter's identity is in its top. The frame edge counts as a mask too: a word sliding in from off screen shows a lone letter first.
+- Enter whole words instead: a short rise (1 to 2 percent of the frame height) with opacity reaching 1 within two frames, or a scale down from slightly larger (at most 1.25 times) onto its place.
+- At most one word in three gets the big scale entrance. The rest rise, or widen with letter spacing, or slide a short distance from inside the frame.
+- Letter by letter: each letter appears whole, starting from the rightmost (the first one read).
+- This overrides the masked rise that `reference/motion-design.md` recommends for Latin headlines.
+
+## Hyphens and punctuation
+- **Never join two Hebrew words with a hyphen on screen**, in headlines, labels or interface text. Write the two words with a space.
+- No em dash and no en dash on screen. Use a comma, a full stop or a new line.
+- A prefix letter before a number or a Latin word ("ב-2026") is correct Hebrew, but on screen prefer wording that avoids it.
+- Quote the user's text exactly, letter for letter. Never "fix" spelling, add vowel points or swap a final letter.
+
+## Lines
+- Never let the renderer wrap a Hebrew line. Break lines yourself, by meaning, and give each line its own element with `whiteSpace: "nowrap"`.
+- In a stacked headline keep every line the same size; shrink the whole stack rather than one line.
+- Leave room: a word that fills the width should use about 90 percent of the safe width, so a camera push or a shake cannot push a letter out.
+
+## Text on a path or in a drawing
+- Text inside a scaled drawing blurs and distorts when the camera zooms. Keep labels in a layer above the drawing and compute their position from the camera.
+- Text on a curve or ring: render a preview frame and read it. Path text in RTL starts from the other end of the path than Latin text does, and a wrong offset makes it vanish rather than look wrong.
+
+## Check before you show
+1. Every word in the right order, right to left, spelled exactly as given.
+2. No hyphen between words, no long dash.
+3. No letter cut by the frame edge or by a mask, in the early frame or the late one.
+4. Progress bars fill left to right; everything else runs right to left.
+5. The full stop and exclamation mark sit at the left end of the last word.

package/skill/reference/motion-design.md

@@ -6,7 +6,7 @@ description: Use when deciding how a scene looks and moves - layout, typography,
 # Motion design guidelines
 
 ## The user's uploads
-`assets/index.json` lists the user's own files with a description of each. Show each one only in the scenes whose userAssetKeys include it, sized and framed for what it is: a logo small and clean on a plain area; a screenshot framed in a device or browser mockup (search the library with `reelkit assets search "phone mockup" --kind component`, then `reelkit assets pull <id>`, which puts it in `src/`; if none fits, build a simple rounded framed card); a product photo large, with KenBurnsImage or a rounded card. Never stretch a logo, never crop a screenshot's important part, and never invent a screen when a real one was supplied.
+`assets/index.json` lists the user's own files with a description of each. Ask for a logo as an SVG where the user has one: its edges stay sharp at any size, while a PNG softens when scaled up. Show each one only in the scenes whose userAssetKeys include it, sized and framed for what it is: a logo small and clean on a plain area; a screenshot framed in a device or browser mockup (search the library with `reelkit assets search "phone mockup" --kind component`, then `reelkit assets pull <id>`, which puts it in `src/`; if none fits, build a simple rounded framed card); a product photo large, with KenBurnsImage or a rounded card. Never stretch a logo, never crop a screenshot's important part, and never invent a screen when a real one was supplied.
 
 ## One system, start to end
 - One base colour, one text colour and **one hero colour**, kept for the whole video. Roughly 60 percent base, 30 percent secondary surfaces, 10 percent hero.
@@ -19,29 +19,42 @@ description: Use when deciding how a scene looks and moves - layout, typography,
 ## Layout
 - One focal point per scene. Everything else supports it.
 - Keep important content inside the middle 80 percent of the frame horizontally. On vertical video keep critical text in the middle 75 percent vertically: the platform's own buttons cover the top and bottom. Captions sit just above the bottom of that zone.
+- On a 1080 by 1920 reel that means text stays clear of the top 250 pixels, the bottom 350, and 80 on each side (140 for anything that must be read, since tall phones crop about 100 from each side), plus 140 on the right in the lower half, where the app's own buttons sit. Backgrounds and graphics may run to the edge. On square and wide video keep text 6 percent in from every side.
+- Zoom so that each state fills the frame. A small thing centred in an empty frame looks like a mistake.
 - Reuse the same margins in every scene.
 - Vary composition between scenes (centred, top-aligned, split) so the video is not one slide repeated.
 
 ## Typography
 - Headlines 7 to 10 percent of the frame width; supporting text 3.5 to 5 percent. Never smaller than 3 percent: it must read on a phone.
-- If any on-screen text is Hebrew, set it in one of the kit's Hebrew faces and give its container `direction: "rtl"`. The Latin faces have no Hebrew letters. Good pairings: `heebo` or `assistant` for everything; `secularOne` or `karantina` headlines over `assistant` body; `suezOne` or `frankRuhlLibre` for an editorial feel; `varelaRound` or `fredoka` for a friendly one.
+- A message the viewer must read is at least 90 pixels tall on a 1080 wide video. Hero words run from 220 to 520. Interface text inside a recreated interface and tiny decorative technical labels are exempt.
+- If any on-screen text is Hebrew, read `reference/hebrew-rtl.md` first. Set it in one of the kit's Hebrew faces and give its container `direction: "rtl"`. The Latin faces have no Hebrew letters. Good pairings: `heebo` or `assistant` for everything; `secularOne` or `karantina` headlines over `assistant` body; `suezOne` or `frankRuhlLibre` for an editorial feel; `varelaRound` or `fredoka` for a friendly one.
 - Short lines, broken by meaning, not by width. A title should fit on one line where it can.
-- Reveal text with a masked rise (translate up from behind an overflow-hidden box), word by word, about 2 frames apart. Avoid plain opacity fades for headlines.
+- Reveal Latin text with a masked rise (translate up from behind an overflow-hidden box), word by word, about 2 frames apart. Avoid plain opacity fades for headlines. Hebrew never uses a mask: its words enter whole (see `reference/hebrew-rtl.md`).
 
 ## Motion
 - **Springs, never linear moves and never cartoon bounce.** Use `spring()` with a damping high enough for a tiny overshoot at most. Presets (stiffness / damping): snappy UI 320 / 30, default containers 170 / 26, heavy type and logos 120 / 24.
+- A big move gets a small anticipation first: a few frames of pull the other way.
+- Exits are faster than entrances. An entrance takes about 0.1 to 0.25 seconds.
+- Linear motion is only for movement with no start or end inside the shot (a slow camera turn, a continuous scroll). Every entrance, exit and change of state is a spring.
+- **The camera is a group.** Put the whole scene inside one wrapper and move that: a slow push of 2 to 4 percent across a shot, on a softer spring than the content. Never scale text up by enlarging a container that holds it as an image; set the size so it stays sharp.
+- **Work on a grid.** Place every event on a fixed grid (half a second is a good default) or on the spoken words. Something happens on every grid step.
 - **One thing moves at a time.** Stagger related items by 4 to 8 frames rather than moving everything at once.
 - **Pace to speech.** One visible change per spoken beat, roughly every 0.4 to 1.2 seconds. Use the word timings in `s.words` to bring an element in on the frame its word starts, never before.
 - Something new should happen every 2 to 4 seconds, and something must move within the first half second of the video. No dead stretches.
 - **Rhythm is hit, hold, build.** A fast move, then a hold of about half a second where nothing new enters, then the next move. Constant motion reads amateur; contrast reads expensive. During a hold, settled elements keep their slow breathe.
 - **Nothing sits perfectly frozen for more than about a second.** After an element settles, keep a very slow drift or scale (1 to 2 percent over the scene) alive so the frame breathes.
-- Let an element finish animating and stay readable for at least 1.5 seconds before it leaves.
+- Let an element finish animating and stay readable for at least 1.5 seconds before it leaves. A label or phrase of more than one word stays at least 1.3 seconds; the closing title or message is held at least 1.5 seconds before the last frame. If the plan's length cannot fit that, lengthen the scene and tell the user.
 - Counters, progress bars and drawn lines finish before the scene's midpoint.
 - Text that swaps inside a container that is also changing size needs its own exit and enter timing, or old and new text overlap.
+- **Whatever a scene adds, the scene removes.** Every overlay, label and effect leaves when its moment ends. A leftover from an earlier scene is the most common thing a review finds.
+- **Show exactly what is being said.** Each visual belongs to its own sentence. A picture that fits only roughly is worse than plain type, and the same picture or clip never appears twice.
 
 ## Legibility over images and footage
 - Text over an image or footage needs help: a dim layer of 0.2 to 0.45 on the media, or a solid plate behind the text, plus a soft shadow.
 - In footage mode keep overlays to one graphic at a time, clear of the subject.
+- Talking to a still camera gets dull fast. Give each sentence one small punch-in on its most important word: 10 to 15 percent, on a spring, centred on the speaker's face, landing on the frame the word starts and resetting at the next sentence. Give the last sentence a slow 3 percent push instead. Do not add this over footage that already has zooms of its own (screen recordings from tools that zoom automatically): two zooms on top of each other make people dizzy.
+- Never let more than about 3 seconds of speech pass in footage with nothing new on screen.
+- A punch-in softens 1080 footage. If the user can still choose, suggest filming in 4K when zooms are planned.
 
 ## Truth on screen
 - Never show a number, quote, price, statistic or result that is not in the narration or on-screen text of the plan.
@@ -55,8 +68,31 @@ description: Use when deciding how a scene looks and moves - layout, typography,
 ## Shape of a 30 second video
 Hook (first 1.5 s: the boldest visual and claim) → context (one line, one visual) → body (three or four beats) → payoff (the result or number, the biggest animation of the video) → close (one action, calm).
 
+## Motion blur and speed
+- Do not fake blur on fast motion with a blur filter on everything. Keep a short blur (6 to 10 pixels for a few frames) for content swapping inside a container and for depth.
+- A whole word sliding hundreds of pixels in a frame leaves separate ghost copies. Give it a directional blur that follows its speed, or shorten the travel.
+
+## Weight on the page
+- Keep a scene under roughly 1,500 elements; beyond that draw on one canvas and redraw it each frame.
+- Compute heavy geometry once, outside the frame function, and only position it per frame.
+- Grain or paper texture is one static layer above everything, outside the camera group. Inside a zooming group it is slow and the grain swells into blotches.
+
 ## Banned, because they read as AI-made or cheap
+These hold unless the look chosen in `reference/styles.md` names an exception (a showreel look uses flat colour fields; the glowing-branches look uses glow on its lines).
+
 Flat solid backgrounds, opacity-only fades, everything entering at once, rainbow or multi-stop gradients on text and UI, particles and sparkles, glows on interface chrome, emoji as graphics, bouncy easing, gratuitous 3D flips, a centred title on a plain gradient, mixed icon styles, lorem ipsum, and anything that looks like a stock template.
 
+## The studio test
+Before showing anything, every answer is yes:
+1. There is one clear idea at each moment, and the eye knows where to look.
+2. Every move starts and ends on a spring, with a small anticipation before a big one.
+3. Nothing is frozen longer than the look allows, and nothing shakes without a reason.
+4. Every word reads at phone size, in the right order, uncut and not touching its neighbour.
+5. Every colour comes from the palette that was agreed; no shade crept in on the way.
+6. Nothing from the chosen look's forbidden list is on screen.
+7. It looks like a studio made it, not like a template or a slide deck.
+
 ## Check your own frames
-Run `reelkit preview`, then look at the frames in `out/preview/` as a harsh director would. Hunt for: text overlapping during a swap, text cut by the frame edge, type too small for a phone, a frame with nothing in it, and anything that looks like a template. Fix what is real, then check again.
+Go round at least twice: preview, fix, preview again. The first pass finds what is broken; the second finds what is merely weak. If the review shows that something in the approved plan cannot work (an ending too small in the frame), make the smallest change that fixes it and tell the user what changed and why; a different scene or different words goes back for approval.
+
+Run `reelkit preview`, then look at both frames of every scene in `out/preview/` (early at 30%, late at 90%) as a harsh director would. Hunt for: text overlapping during a swap, text cut by the frame edge, type too small for a phone, a frame with nothing in it, and anything that looks like a template. Fix what is real, then check again.

package/skill/reference/remotion-composition.md

@@ -10,6 +10,38 @@ description: Use when writing Video.tsx - the file rules, timing model and media
 - Extra component files are flat siblings, PascalCase, one component per file: `NumberBadge.tsx` exports `NumberBadge`. Import them in Video.tsx as `./NumberBadge`.
 - Video.tsx may import only `react`, `remotion`, `reelkit/kit` and sibling components. No other packages, no network, no file access, no `process`.
 
+## What the composition receives
+`Video` gets two props, `{ manifest, urls }` (type `VideoProps`, exported by `reelkit/kit`). `manifest` is the content of `manifest.json` in the project, rewritten by `reelkit assets voiceover`, `check`, `preview` and `render` from `plan.json` and the recorded voiceovers. It is not hand-edited. `urls` is separate: it is built at render time and is not in `manifest.json`.
+
+`manifest`:
+- `fps`: frames per second (30).
+- `width`, `height`: pixels. 1080x1920 for 9:16, 1920x1080 for 16:9, 1080x1080 for 1:1; in footage mode the footage's own size, scaled down to at most 1920 on its long side.
+- `totalFrames`: the length of the video in frames. Seconds are `totalFrames / fps`.
+- `footageKey`: only in footage mode, the project path of the footage; look it up as `urls[manifest.footageKey]`.
+- `scenes`: one entry per plan scene, in plan order, laid end to end.
+
+Each `scenes` entry:
+- `id`: the scene id from `plan.json`.
+- `startFrame`, `durationFrames`: frames on the whole video's timeline. A scene lasts its narration plus 0.4 s of breathing room, rounded up to a whole frame.
+- `voiceoverKey`: the project path of the narration audio.
+- `words`: one entry per spoken word, `{ word, startSec, endSec }`, in seconds from the start of that scene (not of the video, and not frames). Convert with `Math.round(sec * fps)` for a frame inside the scene; `<Captions words={s.words} />` takes them as they are.
+- `imageKey`: only on an illustration scene that has its image; the project path of the image.
+- `userAssetKeys`: project paths of the user's own files that the plan assigned to this scene (an empty array when none).
+
+`urls` maps a project path (every file under `assets/`, except `.json` files) to the address Remotion can load it from. Pass paths from the manifest, or one you pulled, such as `urls["assets/lib/<id>/clip.mp3"]`; never build an address yourself.
+
+```json
+{
+  "fps": 30, "width": 1080, "height": 1920, "totalFrames": 150,
+  "scenes": [
+    { "id": "a", "startFrame": 0, "durationFrames": 75, "voiceoverKey": "assets/vo-a.mp3",
+      "words": [{ "word": "Hello", "startSec": 0, "endSec": 0.4 }, { "word": "there", "startSec": 0.4, "endSec": 0.9 }],
+      "userAssetKeys": [] },
+    { "id": "b", "startFrame": 75, "durationFrames": 75, "voiceoverKey": "assets/vo-b.mp3", "words": [], "userAssetKeys": [] }
+  ]
+}
+```
+
 ## Timing
 - All timing comes from the manifest. Each scene has `startFrame` and `durationFrames`; wrap each scene's content in `<SceneFrame from={s.startFrame} durationInFrames={s.durationFrames}>`.
 - Inside a SceneFrame, `useCurrentFrame()` starts at 0 for that scene.

package/skill/reference/sound-design.md

@@ -12,7 +12,9 @@ A few well-placed sounds make motion feel real. Too many make a video tiring. Th
 - **Scene changes:** a short transition sound across the cut.
 - **Interface moments:** a notification arriving, a button tap, a tick appearing. A click, pop or chime.
 - **Build-ups:** a riser into the payoff or the final call to action.
-- Not every element. Two to four sounds per scene at most, and usually one.
+- Not every element. Two to four sounds per scene at most, and usually one. A sound on every movement sounds like a toy.
+- At most one whoosh or swish per scene, and quieter than the hits on purpose.
+- One deep sub or boom per scene at most, and one or two big impacts in the whole video, on its peak moments.
 
 ## Finding sounds
 1. `reelkit assets search "<description>" --kind sfx` with what you want to hear: "whoosh", "soft click", "notification pop", "riser", "camera shutter", "bass impact". Add "one-shot" or "short" to the query for one-shots.
@@ -30,6 +32,7 @@ A few well-placed sounds make motion feel real. Too many make a video tiring. Th
 - The voiceover plays at 1. Sound effects sit between 0.2 and 0.45. Impacts on the hook can go to 0.6.
 - Ambience and drone beds: 0.06 to 0.12.
 - Never let two loud sounds overlap. Stagger them.
+- When the same kind of sound repeats, grade it: the first at full level, the rest quieter.
 
 ## Fit
 - Match the sound to the look: soft pops and gentle whooshes for calm, friendly videos; glitches and bass hits for tech and high energy; camera and tape sounds for retro.

package/skill/reference/styles.md

@@ -0,0 +1,64 @@
+---
+name: styles
+description: Use before planning, to choose the video's look with the user - the two modes (restrained and showreel) and a catalogue of looks, each with when to use it, how it is built, and what it forbids.
+---
+
+# Choosing the look
+
+Pick one look for the whole video before writing the plan, and say it in the first scene's `notes`. A video that mixes looks reads as a template.
+
+If the user already described what they want, match it to a look and confirm in one sentence. Otherwise offer the catalogue below as a short numbered list with one line each, and include "your own: describe it, or send a picture or a link". Ask every open question in one message, each with a default, so the user can answer "defaults".
+
+## Two modes
+Every look belongs to one mode. The mode decides which rules in `reference/motion-design.md` bend.
+
+**Restrained** (product demos, explainers, anything that must feel expensive and calm)
+- One background, one hero colour or black and white, one face.
+- One object that changes shape instead of cuts. Content swaps inside it with a short blur, and each text has its own exit and entrance.
+- Forbidden: glows, gradients on interface parts, particles, mixed icon weights.
+
+**Showreel** (openers, announcements, anything that must stop the scroll)
+- Hard cuts on the beat between full-colour backgrounds; type that fills the frame. Flat solid colour fields are right here.
+- The camera never stops: a slow push, a degree or two of rotation, a short shake on each hit.
+- No frame sits still longer than a third of a second, except the final hold.
+- At most three full-screen flashes in any second, and never a red strobe. This is a safety rule, not a taste rule.
+
+## The catalogue
+
+### 1. One shape, many interfaces (restrained)
+**When:** a product or app should look polished. **How:** a single rounded shape morphs through button, loader, player, toggle, tabs and chart; its width, height and radius move together on one spring, and the leading edge of a slider or toggle moves on a faster spring than the trailing edge so it stretches. A pointer, if shown, drives values directly while it drags and springs back on release. **Forbidden:** a cut between states, more than one accent colour.
+
+### 2. Giant type on colour fields (showreel)
+**When:** an opener or a strong message of 3 to 6 words. **How:** one or two words per frame, a hard cut to a new full colour on each beat, each word entering a different way (a scale hit, widening from tight to wide, a short slide, a design-tool selection box that snaps on). End with the whole message together, held at least 1.5 seconds. **Forbidden:** soft gradients, outlined words, a still frame.
+
+### 3. A word made of particles (showreel)
+**When:** revealing a name or brand, or a closing wow. **How:** sample the word's pixels once, then move each particle between targets (word, sphere, swirl, word) as a function of the frame; draw on a canvas, not thousands of elements. The word must be readable again at the end and held half a second. **Forbidden:** per-frame randomness.
+
+### 4. A field of blocks (showreel)
+**When:** an energetic background behind a headline, or anything about data. **How:** a grid of blocks rising and falling as a travelling wave, one accent object moving across it, the headline on a dark soft patch above. All blocks jump on the last word. **Forbidden:** letting the background out-shout the text.
+
+### 5. Rings of words (showreel)
+**When:** a list of values, services or topics. **How:** each line of words bends into a ring; rings turn at different slow speeds inside one another with the title in the centre. Read every ring in a preview frame. **Forbidden:** more than about ten words, rings too small to read.
+
+### 6. Hand-drawn character (restrained)
+**When:** a personal, warm or funny message. **How:** a simple pencil character on paper; lines boil slightly by switching between two or three hand-offset versions every few frames (chosen by frame number, never at random), a speech bubble in a handwriting face. **Forbidden:** clean vector precision, more than two colours beside the pencil.
+
+### 7. Storybook explainer (restrained)
+**When:** teaching how something works, in 3 to 5 steps. **How:** flat illustration with rounded shapes, one dark outline colour, a paper background and faint static grain. The camera moves into the object and a round cutaway opens to show the inside, instead of cutting to a new scene. Each step gets a short label beside the action with a thin leader line, on screen at least 1.3 seconds; end on a 2 to 4 word title over the result. **Forbidden:** realistic shadows, strong gradients, labels covering the drawing.
+
+### 8. Glowing branches (showreel)
+**When:** AI, science, the moment an idea is born. **How:** lines of light that grow and fork like nerve cells, a spark running along them, on near-black. Glow is the look here, so it is allowed, on the lines only. **Forbidden:** glow on text, flashes above the limit.
+
+### 9. Sketch to object (restrained)
+**When:** showing how a physical thing is built. **How:** a pencil technical drawing draws itself line by line, gains colour and shade, then does what it was built to do. **Forbidden:** skipping the drawing stage; it is the point.
+
+### 10. Logo reveal (either mode)
+**When:** an opener or end card, from the user's own logo file. **How:** build toward the logo from its own shapes and colours and land on it exactly as supplied, held at least 1.5 seconds. **Forbidden:** redrawing, recolouring or stretching the logo; anyone else's logo or trademark.
+
+## Your own
+Ask what the message is, what happens on screen, the colours, the length and shape, and for an example if they have one. Choose the nearest look above as the technical base and write a four-line brief in the same shape (when, how, forbidden, structure). Show the brief with the plan at the checkpoint.
+
+## What every look shares
+- The plan checkpoint lists the exact words that will appear on screen and when. Fixing a list takes a minute; fixing a finished animation takes an hour.
+- Describe the look to the user in plain words about what they will see ("the title sits on a soft dark patch"), not in studio terms.
+- Only the user's own logos, pictures and faces. Never another company's logo or mark.

package/src/cli.ts

@@ -8,6 +8,7 @@ import { install } from "./commands/install";
 import { openInBrowser } from "./open";
 import { planCheck } from "./commands/plan";
 import type { Ctx, Result } from "./context";
+import { readFileSync } from "node:fs";
 
 const ctx: Ctx = {
   cwd: process.cwd(),
@@ -52,7 +53,9 @@ export function run<A extends unknown[]>(fn: (ctx: Ctx, ...args: A) => Promise<R
   };
 }
 
-export const program = new Command().name("reelkit").description("Make short-form video with a shared asset library.").option("--json", "print the result as JSON");
+// Read from the package itself, so the number can never drift from what was installed.
+const VERSION = (JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as { version: string }).version;
+export const program = new Command().name("reelkit").description("Make short-form video with a shared asset library.").version(VERSION, "-v, --version", "print the version").option("--json", "print the result as JSON");
 
 const auth = program.command("auth").description("Log in and out");
 auth.command("login").description("Log in to Reelkit: opens the login page in your browser").option("--start", "begin a login and return the link at once, without opening a browser (for an agent)").option("--finish", "finish a login begun with --start")
@@ -82,8 +85,8 @@ program.command("plan").description("Work with plan.json").command("check").desc
 
 program.command("check").description("Check the composition in src/ without rendering").action(run(check));
 program.command("install").description("Install the Reelkit skill into your coding agents").option("--agent <id>", "claude, codex, cursor, gemini, agents or all").option("--force", "reinstall even when up to date").action(run((ctx, opts) => install(ctx, opts)));
-program.command("preview").description("Render one test frame per scene into out/preview/").action(run((ctx) => preview(ctx)));
-program.command("render").description("Render the video to out/video.mp4").action(run(render));
+program.command("preview").description("Render two test frames per scene (at 30% and 90%) into out/preview/").action(run((ctx) => preview(ctx)));
+program.command("render").description("Render the video to out/video.mp4").action(run((ctx) => render(ctx)));
 
 // Parses argv and runs the chosen command. Importing this module parses nothing; bin/reelkit.mjs calls main.
 export async function main(argv: string[]): Promise<void> {

package/src/commands/build.ts

@@ -7,7 +7,7 @@ import type { AssetManifest } from "../pipeline/schema";
 import { buildManifest, missingAssets } from "../project/manifest";
 import { openProject, type Project } from "../project/project";
 import { mediaUrls, serveDir } from "../project/serve";
-import { bundleProject, disposeBundle, renderStills, renderVideo, writeEntry } from "../render/render";
+import { bundleProject, disposeBundle, ensureRenderBrowser, renderStills, renderVideo, writeEntry, type EnsureBrowser } from "../render/render";
 import { FILE_NAME, MAIN_FILE, staticCheck, typecheck } from "../render/validate";
 import { loadPlan } from "./plan";
 
@@ -59,9 +59,34 @@ async function withBundle<T>(project: Project, fn: (serveUrl: string, urls: Reco
   }
 }
 
+// The first render on a machine downloads about 90 MB with no other sign of life, so it is announced. Nothing is said
+// when the browser is already there. The lines go through ctx.log, which never writes to stdout.
+export async function ensureBrowserWithNotice(ctx: Ctx, ensure: EnsureBrowser = ensureRenderBrowser): Promise<void> {
+  let downloaded = false;
+  await ensure(() => {
+    downloaded = true;
+    ctx.log("Downloading the browser used for rendering (about 90 MB, one time)...");
+  });
+  if (downloaded) ctx.log("Downloaded the browser.");
+}
+
 const ffmpegToJpeg = (png: string, jpg: string) => exec("ffmpeg", ["-y", "-loglevel", "error", "-i", png, "-vf", "scale=540:-2", "-q:v", "5", jpg]).then(() => undefined);
 
-export async function preview(ctx: Ctx, deps: { toJpeg?: (png: string, jpg: string) => Promise<void> } = {}): Promise<Result> {
+type PreviewPoint = { sceneId: string; point: "early" | "late" | "middle"; frame: number; name: string };
+
+// Two frames per scene, at 30% and 90% of its length, so what enters late in a scene is seen as well as what opens it.
+// A scene under 4 frames has no room for two distinct frames and gets its middle one. The scene's number leads each name
+// so the files sort by scene order and then by time, whatever the scene ids are.
+export function previewPoints(scenes: { id: string; startFrame: number; durationFrames: number }[]): PreviewPoint[] {
+  return scenes.flatMap((s, i) => {
+    const at = (point: PreviewPoint["point"], offset: number): PreviewPoint => ({ sceneId: s.id, point, frame: s.startFrame + offset, name: `${String(i + 1).padStart(2, "0")}-${s.id}-${point}` });
+    if (s.durationFrames < 4) return [at("middle", Math.floor(s.durationFrames / 2))];
+    const inside = (share: number) => Math.min(s.durationFrames - 1, Math.round(s.durationFrames * share));
+    return [at("early", inside(0.3)), at("late", inside(0.9))];
+  });
+}
+
+export async function preview(ctx: Ctx, deps: { toJpeg?: (png: string, jpg: string) => Promise<void>; ensureBrowser?: EnsureBrowser } = {}): Promise<Result> {
   const toJpeg = deps.toJpeg ?? ffmpegToJpeg;
   const project = openProject(ctx.cwd);
   const { errors, manifest } = inspect(project);
@@ -69,37 +94,39 @@ export async function preview(ctx: Ctx, deps: { toJpeg?: (png: string, jpg: stri
   const dir = project.path("out/preview");
   rmSync(dir, { recursive: true, force: true });
   mkdirSync(dir, { recursive: true });
-  const mids = manifest.scenes.map((s) => ({ sceneId: s.id, frame: s.startFrame + Math.floor(s.durationFrames / 2) }));
+  const points = previewPoints(manifest.scenes);
   try {
     try {
-      await withBundle(project, (serveUrl, urls) => renderStills(serveUrl, { manifest, urls }, mids.map((m) => m.frame), dir));
+      await ensureBrowserWithNotice(ctx, deps.ensureBrowser);
+      await withBundle(project, (serveUrl, urls) => renderStills(serveUrl, { manifest, urls }, points.map((p) => p.frame), dir));
     } catch (e) {
       return failed([`Render failed: ${e instanceof Error ? e.message : String(e)}`]);
     }
-    const frames: { sceneId: string; path: string }[] = [];
+    const frames: { sceneId: string; point: PreviewPoint["point"]; path: string }[] = [];
     try {
-      for (const m of mids) {
+      for (const m of points) {
         // Shrunk to phone width: small enough to read cheaply, and what is unreadable here is unreadable on a phone.
-        const path = `out/preview/${m.sceneId}.jpg`;
+        const path = `out/preview/${m.name}.jpg`;
         await toJpeg(join(dir, `still-${m.frame}.png`), project.path(path));
-        frames.push({ sceneId: m.sceneId, path });
+        frames.push({ sceneId: m.sceneId, point: m.point, path });
       }
     } catch {
       return failed(["Could not write the preview frames: ffmpeg failed. Check that ffmpeg is installed (macOS: `brew install ffmpeg`) and run `reelkit preview` again."]);
     }
-    return { ok: true, data: { frames }, summary: `One frame per scene, taken at its midpoint:\n${frames.map((f) => `${f.sceneId}: ${f.path}`).join("\n")}` };
+    return { ok: true, data: { frames }, summary: `Two frames per scene, at 30% and at 90% of its length (a scene under 4 frames gets its middle one). Look at both frames of every scene:\n${frames.map((f) => `${f.sceneId} (${f.point}): ${f.path}`).join("\n")}` };
   } finally {
     // The full-size stills are only inputs; none stays behind however this ends.
     for (const f of readdirSync(dir)) if (/^still-\d+\.png$/.test(f)) rmSync(join(dir, f), { force: true });
   }
 }
 
-export async function render(ctx: Ctx): Promise<Result> {
+export async function render(ctx: Ctx, deps: { ensureBrowser?: EnsureBrowser } = {}): Promise<Result> {
   const project = openProject(ctx.cwd);
   const { errors, manifest } = inspect(project);
   if (!manifest) return failed(errors);
   const path = "out/video.mp4";
   try {
+    await ensureBrowserWithNotice(ctx, deps.ensureBrowser);
     await withBundle(project, (serveUrl, urls) => renderVideo(serveUrl, { manifest, urls }, project.path(path)));
   } catch (e) {
     return failed([`Render failed: ${e instanceof Error ? e.message : String(e)}`]);

package/src/commands/init.ts

@@ -15,7 +15,7 @@ export async function init(ctx: Ctx, name: string | undefined, opts: { aspect?:
   if (slug === "") return { ok: false, summary: "Give the project a name with letters or digits, for example: reelkit init launch-video" };
   const aspect = AspectSchema.safeParse(opts.aspect ?? "9:16");
   if (!aspect.success) return { ok: false, summary: `Unknown aspect "${opts.aspect}". Use 9:16, 16:9 or 1:1.` };
-  if (Number(process.versions.node.split(".")[0]) < 20) return { ok: false, summary: `Node 20 or newer is needed; this is ${process.versions.node}. Install a newer Node.` };
+  if (Number(process.versions.node.split(".")[0]) < 22) return { ok: false, summary: `Node 22 or newer is needed; this is ${process.versions.node}. Install a newer Node.` };
   try { await exec("ffmpeg", ["-version"]); } catch { return { ok: false, summary: "ffmpeg was not found. Install it (macOS: `brew install ffmpeg`) and run `reelkit init` again." }; }
 
   const dir = slug ? join(ctx.cwd, slug) : ctx.cwd;

package/src/commands/plan.ts

@@ -1,6 +1,6 @@
 import { client, type Ctx, type Result } from "../context";
 import { loadCredentials } from "../credentials";
-import { reviewPlan } from "../pipeline/review";
+import { estimateLength, reviewPlan } from "../pipeline/review";
 import { ScenePlanSchema, validatePlan, type ScenePlan } from "../pipeline/schema";
 import { FILES, issueLines, openProject, type Project } from "../project/project";
 
@@ -36,10 +36,13 @@ export async function planCheck(ctx: Ctx): Promise<Result> {
   const voiceIds = loadCredentials(ctx.env) ? (await client(ctx)("voices", {})).voices.map((v) => v.id) : undefined;
   const mustFix = validatePlan(parsed.data, { aspect: project.config().aspect, footage, assets, voiceIds });
   const shouldImprove = mustFix.length ? [] : reviewPlan(parsed.data, { footage });
+  const length = estimateLength(parsed.data);
+  const estimatedSeconds = Math.round(length.seconds);
   const lines = [
     mustFix.length ? `Fix these:\n- ${mustFix.join("\n- ")}` : "The plan is valid.",
+    `Estimated length: about ${estimatedSeconds}s (${length.words} words).`,
     ...(shouldImprove.length ? [`Worth improving:\n- ${shouldImprove.join("\n- ")}`] : []),
     ...(voiceIds ? [] : ["The voice was not checked because you are not logged in. Run `reelkit auth login`."]),
   ];
-  return { ok: mustFix.length === 0, data: { mustFix, shouldImprove }, summary: lines.join("\n") };
+  return { ok: mustFix.length === 0, data: { mustFix, shouldImprove, estimatedSeconds, words: length.words }, summary: lines.join("\n") };
 }

package/src/contract/index.ts

@@ -106,6 +106,7 @@ const Meter = z.object({ used: z.number(), limit: z.number() });
 export const MeSchema = z.object({
   userId: z.string(), handle: z.string(),
   quota: z.object({ voiceoverChars: Meter, images: Meter, resetsAt: z.string() }),
+  // How many of the user's own items are published in the shared library. An item still in review, or sent back, is not counted.
   contributions: z.number(),
 });
 

package/src/pipeline/review.ts

@@ -2,12 +2,17 @@ import { WORDS_PER_SEC, type AssetRecord, type ScenePlan } from "./schema";
 
 const words = (s: string) => s.trim().split(/\s+/).filter(Boolean).length;
 
+// The same estimate the length advice below is based on: narration words at the voice's usual pace.
+export function estimateLength(plan: ScenePlan): { words: number; seconds: number } {
+  const total = plan.scenes.reduce((n, s) => n + words(s.narration), 0);
+  return { words: total, seconds: total / WORDS_PER_SEC };
+}
+
 // Soft quality checks on a plan that already passes the hard rules in validatePlan.
 // These are things worth improving in the script; they never fail a video on their own.
 export function reviewPlan(plan: ScenePlan, ctx: { footage?: AssetRecord }): string[] {
   const issues: string[] = [];
-  const total = plan.scenes.reduce((n, s) => n + words(s.narration), 0);
-  const seconds = total / WORDS_PER_SEC;
+  const { words: total, seconds } = estimateLength(plan);
 
   if (!ctx.footage) {
     if (seconds < 20) issues.push(`The script runs about ${seconds.toFixed(0)}s (${total} words). Aim for 30 to 60 seconds.`);

package/src/render/render.ts

@@ -1,7 +1,7 @@
 import { mkdir, rm, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { bundle } from "@remotion/bundler";
-import { renderMedia, renderStill, selectComposition } from "@remotion/renderer";
+import { ensureBrowser, renderMedia, renderStill, selectComposition } from "@remotion/renderer";
 import type { VideoProps } from "../remotion/types";
 import { packageDir } from "./deps";
 import { KIT_INDEX, ROOT_FILE } from "./validate";
@@ -50,6 +50,13 @@ export async function disposeBundle(serveUrl: string): Promise<void> {
   if (/remotion-webpack-bundle-/.test(serveUrl)) await rm(serveUrl, { recursive: true, force: true });
 }
 
+// Makes sure Remotion's headless browser is installed. onDownload is called once, only when a download is about to begin.
+// Remotion's own progress bar is replaced because it writes to stdout, which --json keeps for the result alone.
+export type EnsureBrowser = (onDownload: () => void) => Promise<void>;
+export const ensureRenderBrowser: EnsureBrowser = async (onDownload) => {
+  await ensureBrowser({ onBrowserDownload: () => { onDownload(); return { version: null, onProgress: () => {} }; } });
+};
+
 const asInput = (props: VideoProps) => props as unknown as Record<string, unknown>;
 
 export async function renderStills(serveUrl: string, props: VideoProps, frames: number[], outDir: string) {

package/src/testing/conformance.ts

@@ -90,7 +90,8 @@ export function runConformance(name: string, start: (opts: StartOptions) => Prom
         expect((await put(up.uploadUrl, PNG, "image/png")).ok).toBe(true);
         const { item } = await mine("libraryCommit", { id: up.id });
         expect(item).toMatchObject({ id: up.id, kind: "image", visibility: "review" });
-        expect((await mine("me", {})).contributions).toBe(1);
+        // Contributions are the user's published items; one still waiting for review is not one yet.
+        expect((await mine("me", {})).contributions).toBe(0);
         // An item that is not published never appears, whoever searches.
         expect((await mine("librarySearch", { q: "zebra" })).items.map((i) => i.id)).not.toContain(up.id);
         expect((await other("librarySearch", { q: "zebra" })).items.map((i) => i.id)).not.toContain(up.id);
@@ -106,14 +107,13 @@ export function runConformance(name: string, start: (opts: StartOptions) => Prom
         const up = await mine("libraryUpload", upload({ shareable: false, title: "Hidden gecko", description: "hidden gecko" }));
         await put(up.uploadUrl, PNG, "image/png");
         expect((await mine("libraryCommit", { id: up.id })).item.visibility).toBe("private");
-        // Contributions are shared uploads only.
         expect((await mine("me", {})).contributions).toBe(0);
         expect((await mine("librarySearch", { q: "gecko" })).items.map((i) => i.id)).not.toContain(up.id);
         expect((await failure(other("libraryPull", { id: up.id }))).code).toBe("not_found");
         expect((await mine("libraryPull", { id: up.id })).item.id).toBe(up.id);
       });
 
-      it("an upload is not an item before commit, and committing twice counts once", async () => {
+      it("an upload is not an item before commit, and committing twice returns the same item", async () => {
         const mine = await as("user-up00005");
         const up = await mine("libraryUpload", upload());
         expect((await failure(mine("libraryCommit", { id: up.id }))).code).toBe("invalid_request");
@@ -121,7 +121,7 @@ export function runConformance(name: string, start: (opts: StartOptions) => Prom
         expect((await failure(mine("libraryPull", { id: up.id }))).code).toBe("not_found");
         const first = await mine("libraryCommit", { id: up.id });
         expect(await mine("libraryCommit", { id: up.id })).toEqual(first);
-        expect((await mine("me", {})).contributions).toBe(1);
+        expect((await mine("me", {})).contributions).toBe(0);
       });
 
       it("refuses a PUT of the wrong type or length, and commit then has nothing to commit", async () => {

package/src/testing/fake-api.ts

@@ -89,7 +89,8 @@ export async function startFakeApi(opts: { voiceoverCharLimit?: number; imageLim
       return {
         userId: userId ?? "u-test", handle: handleOf(userId ?? "u-test"),
         quota: { voiceoverChars: { used: m.chars, limit: limits.chars }, images: { used: m.images, limit: limits.images }, resetsAt: resetDate() },
-        contributions: m.uploads,
+        // What the user gave the shared library that was accepted: their own items that are published. One waiting for review does not count.
+        contributions: [...store.values()].filter((x) => x.owner === userId && x.committed && x.item.visibility === "published").length,
       };
     },
     // Search and the public library list published items only; nothing private or in review is ever found.