reelkit-cli 0.10.0 → 0.10.2

package/skill/reference/styles.md

@@ -1,6 +1,6 @@
 ---
 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.
+description: Choose a visual language from the material or the user's direction, with restrained and showreel approaches and a catalog of look-specific techniques.
 ---
 
 # Choosing the look
@@ -9,8 +9,10 @@ Choose a visual language that fits the material and record it in the first scene
 
 Use the user's chosen direction. Otherwise recommend a fitting look with a short reason; use the catalogue as technique references, not a mandatory menu. Offer alternatives when requested. Ask only about consequential missing information.
 
+After choosing the look, use `reference/style-recipes.md` to connect its visible action, implementation, sound and review evidence. `reference/style-components.md` maps all reviewed shared components to their roles. The catalog's timing, palette and exclusions are defaults for the described treatment; real speech timing, supplied brand identity, the user's requested variation and the installed runtime take precedence.
+
 ## Two modes
-Every look belongs to one mode. The mode decides which rules in `reference/motion-design.md` bend.
+Restrained and showreel describe motion energy, not separate engines. Choose the energy by the shot's purpose; a mixed-media film can combine them while preserving its visual thread. The chosen treatment explains which craft defaults in `reference/motion-design.md` change.
 
 **Restrained** (product demos, explainers, anything that must feel expensive and calm)
 - One background, one hero colour or black and white, one face.
@@ -33,7 +35,7 @@ Each look is built from what the kit and the shared library already hold, so mos
 **When:** results, growth, a comparison, anything with figures from the narration. **How:** one figure or one chart per scene (search "statistic counter", "line chart", "bar chart", "pie chart", "radial gauge"); the number counts up and finishes before the scene's midpoint; a before and after sits side by side (search "comparison"). The payoff number gets the biggest move of the video. **Forbidden:** any figure that is not in the plan, two charts in one frame, decorative data.
 
 ### 3. Headline hits (showreel)
-**When:** an opener, a launch, a message of a few words that must stop the scroll. **How:** one or two words fill the frame (search "kinetic title"), hard cuts to a new full colour on the beat, each word entering a different way, and the whole message together at the end, held. The camera keeps a slow push the whole time. **Forbidden:** soft gradients, outlined words, a still frame before the final hold.
+**When:** an opener, a launch, a message of a few words that must stop the scroll. **How:** one or two words fill the frame (search "kinetic title"), selected hard cuts to a full colour on a musical or spoken event, and the whole message together at the end, held. Vary the entrance when it helps hierarchy; keep one motion language. A camera push is optional. **Avoid for this treatment:** gradients or outlines that soften the intended heavy graphic read, and motion that prevents reading the landing.
 
 ### 4. Cinematic story (restrained)
 **When:** a mood, a place, a story told by a voice. **How:** generated or reused pictures with a slow move across them, a film grade and grain over everything, a poster-style title to open (search "cinematic title"), a film overlay if it suits (`--kind overlay`, search "film"). Few words on screen; the captions carry the text. **Forbidden:** interface parts, bright accent colours, fast cuts.
@@ -51,7 +53,7 @@ Each look is built from what the kit and the shared library already hold, so mos
 **When:** a testimonial, an introduction, a creator talking, social proof. **How:** the person's name and role in a lower third (search "name lower third"), a quote card with its stars (search "quote testimonial"), a follow line to close (search "social handle", "cta button"). Quotes and names come from the user, word for word. **Forbidden:** an invented quote, rating or follower count.
 
 ### 9. Over footage (either mode)
-**When:** the user supplied their own video. **How:** the footage is the picture; graphics are guests. One overlay at a time, clear of the speaker's face; a small punch-in on each sentence's key word; lower thirds and callouts from the library; captions always. **Forbidden:** covering the face, a graphic left on screen after its sentence, zooms on footage that already has its own.
+**When:** the user supplied their own video. **How:** the footage is the picture; graphics support it. Keep the active graphic clear of the speaker's face; use a punch-in only for needed emphasis or framing, with lower thirds and callouts from the library. Honor the user's caption choice and use actual source-speech timings (`reference/studio-editing.md`). **Avoid:** covering the face, a graphic left after its purpose ends, zooms stacked on footage that already has its own.
 
 ### 10. Logo sting (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.
@@ -71,6 +73,8 @@ Each look is built from what the kit and the shared library already hold, so mos
 ## Your own
 Use the supplied message, actions, colours, duration and format. Ask only for consequential missing details or a reference that the choice depends on. 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.
 
+For morphing UI, particle words, cube worlds, text rings, children's-book cutaways, blueprint-to-product shots, exploded assembly, toon materials, layered posters, mixed-media narration, cutout depth and composited VFX, use the advanced rows 29 to 40 in `reference/style-recipes.md`. Select a local kit or external production route that can actually deliver the shot.
+
 ## 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.

package/skill/tests/studio.test.ts

@@ -0,0 +1,111 @@
+import { expect, test } from 'claude-code/testing'
+
+const DIR = '/work/demo'
+const PANE = { title: 'Reelkit', isFocused: false, bodyColumns: 100, placement: 'dock', scroll: { offset: 0, bodyRows: 40 }, view: {} } as const
+
+const FILES: Record<string, string> = {
+  [`${DIR}/reelkit.json`]: JSON.stringify({ name: 'demo', aspect: '9:16' }),
+  [`${DIR}/plan.json`]: JSON.stringify({
+    title: 'Demo film',
+    aspect: '9:16',
+    voiceId: 'v-1',
+    scenes: [
+      { id: 'hook', narration: 'First the hook lands.', treatment: 'motion-graphic', onScreenText: ['HOOK'] },
+      { id: 'proof', narration: 'Then the proof follows.', treatment: 'illustration', onScreenText: ['PROOF'] },
+    ],
+  }),
+  [`${DIR}/manifest.json`]: JSON.stringify({
+    fps: 30,
+    totalFrames: 240,
+    music: { key: 'assets/lib/music-a/track.mp3', bpm: 120, beatFrames: [0, 15, 30, 45] },
+    scenes: [
+      { id: 'hook', startFrame: 0, durationFrames: 90, words: [{ word: 'First', startSec: 0.1, endSec: 0.4 }] },
+      { id: 'proof', startFrame: 90, durationFrames: 150, words: [{ word: 'Then', startSec: 0.2, endSec: 0.5 }] },
+    ],
+  }),
+  [`${DIR}/assets/music.json`]: JSON.stringify({ key: 'assets/lib/music-a/track.mp3', title: 'Track A', durationSec: 20 }),
+  [`${DIR}/src/Badge.tsx`]: '// A round badge with one word in it. Use it to mark a claim.\nexport const Badge = () => null\n',
+}
+
+const entry = (name: string) => ({ name, kind: 'file' as const, size: 10, mtimeMs: 1000, isLink: false })
+
+// The engine beneath the mod: one project on disk, a render, and commands that answer from memory.
+type TestOn = Parameters<Extract<Parameters<typeof test>[1], (...args: never[]) => unknown>>[1]
+
+const project = (on: TestOn, written: Record<string, string>, ran: string[][]) => {
+  on('session.cwd', () => ({ value: DIR }))
+  on('clock.now', () => ({ value: 3600000 }))
+  on('ui.open', () => ({ value: { isPlaced: true as const } }))
+  on('fs.exists', (_$, e) => ({ value: e.path in FILES }))
+  on('fs.read', (_$, e) => {
+    const text = FILES[e.path]
+    if (text === undefined) throw new Error(`ENOENT ${e.path}`)
+    return { value: text }
+  })
+  on('fs.list', (_$, e) => ({ value: e.path === `${DIR}/src` ? [entry('Badge.tsx'), entry('Video.tsx')] : [] }))
+  on('fs.stat', (_$, e) => {
+    if (e.path !== `${DIR}/out/video.mp4`) throw new Error(`ENOENT ${e.path}`)
+    return { value: { kind: 'file' as const, size: 2097152, mtimeMs: 5000, isLink: false } }
+  })
+  on('fs.write', (_$, e) => {
+    written[e.path] = e.text
+    return { value: undefined }
+  })
+  on('process.run', (_$, e) => {
+    ran.push([...e.argv])
+    const stdout =
+      e.argv[0] === 'reelkit'
+        ? JSON.stringify({ ok: true, data: { items: [{ id: 'music-b', kind: 'music', title: 'Track B', description: 'Bright.', match: 0.8, meta: { bpm: 100 } }] } })
+        : ''
+    return { value: { exitCode: 0, stdout, stderr: '', isStdoutTruncated: false, isStderrTruncated: false } }
+  })
+}
+
+test('the pane shows the film as a timeline on every surface', async ($, on) => {
+  project(on, {}, [])
+  for (const surface of ['terminal', 'desktop', 'vscode', 'mobile'] as const) {
+    const ui = await $.ui.mount({ plugin: 'reelkit', surface, component: 'Pane', requestId: 'reelkit-studio', props: PANE })
+    await ui.press({ key: 'refresh' })
+    expect(await ui.find({ type: 'Text', text: /Demo film/ })).toBeDefined()
+    expect(await ui.find({ type: 'Text', text: /1\. hook/ })).toBeDefined()
+    if (surface === 'terminal') expect(await ui.find({ type: 'Text', text: /1 hook/ })).toBeDefined()
+    else expect(await ui.find({ type: 'Svg' })).toBeDefined()
+    await ui.press({ key: 'next' })
+    expect(await ui.find({ type: 'Text', text: /2\. proof/ })).toBeDefined()
+    await ui.press({ key: 'prev' })
+    await ui.unmount()
+  }
+})
+
+test('the tabs show the plan, the music and the components', async ($, on) => {
+  project(on, {}, [])
+  for (const surface of ['terminal', 'desktop'] as const) {
+    const ui = await $.ui.mount({ plugin: 'reelkit', surface, component: 'Pane', requestId: 'reelkit-studio', props: PANE })
+    await ui.press({ key: 'refresh' })
+    await ui.press({ key: 'tab-plan' })
+    expect((await ui.find({ type: 'Markdown' }))?.props.text).toContain('Then the proof follows.')
+    await ui.press({ key: 'tab-music' })
+    expect(await ui.find({ type: 'Text', text: /Track A/ })).toBeDefined()
+    await ui.press({ key: 'tab-components' })
+    expect(await ui.find({ type: 'Text', text: /round badge/ })).toBeDefined()
+    await ui.press({ key: 'tab-timeline' })
+    await ui.unmount()
+  }
+})
+
+test('the browser tab searches the library and the player page is written beside the render', async ($, on) => {
+  const written: Record<string, string> = {}
+  const ran: string[][] = []
+  project(on, written, ran)
+  const ui = await $.ui.mount({ plugin: 'reelkit', surface: 'desktop', component: 'Pane', requestId: 'reelkit-studio', props: PANE })
+  await ui.press({ key: 'refresh' })
+  await ui.press({ key: 'player' })
+  expect(written[`${DIR}/out/studio.html`]).toContain('video.mp4')
+  expect(ran.some(argv => argv[0] === 'open' && argv[1] === `${DIR}/out/studio.html`)).toBe(true)
+  await ui.press({ key: 'tab-browser' })
+  await ui.input({ key: 'query', text: 'bright' })
+  expect(ran.some(argv => argv.join(' ') === 'reelkit assets search bright --kind music --json')).toBe(true)
+  expect(await ui.find({ type: 'Text', text: /80% Track B/ })).toBeDefined()
+  await ui.press({ key: 'tab-timeline' })
+  await ui.unmount()
+})

package/skill/types/index.d.ts

@@ -0,0 +1,65 @@
+export type StudioTab = 'timeline' | 'plan' | 'music' | 'components' | 'browser'
+
+export type FilmScene = {
+  id: string
+  // Frames from the film's start, and the scene's own length in frames.
+  start: number
+  frames: number
+  narration: string
+  text: string[]
+  treatment: string
+  notes: string
+  // Seconds from the scene's start at which each spoken word begins.
+  words: number[]
+  // A small picture of the scene under out/.studio, when a preview frame exists.
+  thumb: string
+}
+
+export type FilmSound = { id: string; kind: string; title: string; path: string; seconds: number }
+
+export type FilmComponent = { name: string; path: string; about: string }
+
+export type Film = {
+  dir: string
+  name: string
+  title: string
+  aspect: string
+  fps: number
+  totalFrames: number
+  // True once manifest.json gave real timings; false while they are estimated from the plan.
+  isTimed: boolean
+  voice: string
+  pace: string
+  captions: string
+  scenes: FilmScene[]
+  music: { title: string; path: string; bpm: number; seconds: number; beats: number[] } | null
+  sounds: FilmSound[]
+  components: FilmComponent[]
+  userAssets: { id: string; kind: string; name: string; about: string }[]
+  render: { path: string; bytes: number; at: number } | null
+  previews: number
+  loadedAt: number
+}
+
+export type LibraryItem = { id: string; kind: string; title: string; about: string; match: number; detail: string }
+
+export type LibrarySearch = {
+  kind: string
+  query: string
+  status: 'idle' | 'busy' | 'done' | 'failed'
+  note: string
+  items: LibraryItem[]
+}
+
+declare module 'claude-code' {
+  interface PluginState {
+    reelkit: {
+      tab: StudioTab
+      film: Film | null
+      projects: string[]
+      scene: number
+      component: string
+      search: LibrarySearch
+    }
+  }
+}