reelkit-cli 0.10.0 → 0.10.3

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
+    }
+  }
+}

package/src/cli.ts

@@ -76,7 +76,7 @@ assets.command("upload <file>").description("Add one of your own files to this p
   .option("--background", "use this video or image as the ground behind the whole film (it stays on this machine)").option("--share", "also send it to the shared library").option("--kind <kind>", "library kind when sharing").option("--tags <tags>", "comma-separated tags when sharing")
   // Called with the arguments named: commander adds its own command object last, which must not be taken for the function's test hooks.
   .action(run((ctx, file: string, opts: Parameters<typeof assetsUpload>[2]) => assetsUpload(ctx, file, opts)));
-assets.command("search <query>").description("Search the shared library by meaning; each result shows how well it fits").option("--kind <kind>", "image, overlay, sfx, music, component or clip").option("--limit <n>", "how many results")
+assets.command("search <query>").description("Search the shared library by meaning; each result shows how well it fits").option("--kind <kind>", "image, overlay, sfx, music, component, clip or prompt (prompts other people used to make motion videos; found only with --kind prompt)").option("--limit <n>", "how many results")
   .action(run(assetsSearch));
 assets.command("pull <id>").description("Download a library item into this project").option("--scene <sceneId>", "use it as this scene's image or clip").option("--force", "replace a component file that already exists").option("--music", "make this music item the video's track (its tempo is measured and scene changes land on its beat)").option("--background", "make this clip, overlay or image the ground behind the film (with --scene: the ground of that scene, an image only)")
   .option("--layers", "with --scene and an image: right after it is pulled, cut the subject out as a layer (about 1 second of the cutout quota; the picture is sent to the Reelkit server)")

package/src/commands/assets.ts

@@ -292,6 +292,15 @@ export async function assetsPull(ctx: Ctx, id: string, opts: { scene?: string; f
     if (treatment === "clip" && pulled.item.kind !== "clip") return { ok: false, summary: `${id} is ${pulled.item.kind}, not a clip, so it cannot be scene ${opts.scene}'s clip.` };
     if (treatment !== "clip" && pulled.item.kind !== "image") return { ok: false, summary: `${id} is ${pulled.item.kind}, not an image, so it cannot be a scene's image.` };
   }
+  // A prompt is something to read, not something the film shows: it goes to prompts/, outside what the composition can reference.
+  if (pulled.item.kind === "prompt") {
+    if (opts.scene || opts.music || opts.background) return { ok: false, summary: `${id} is a prompt: text to read for ideas, not a picture, clip or track. Pull it with no option.` };
+    const path = `prompts/${id}.md`;
+    await download(pulled.url, project.path(path));
+    const by = typeof pulled.item.meta.handle === "string" ? ` by @${pulled.item.meta.handle}` : "";
+    const source = typeof pulled.item.meta.source === "string" ? ` Source: ${pulled.item.meta.source}` : "";
+    return { ok: true, data: { path, kind: "prompt" }, summary: `Pulled ${id} to ${path}: "${pulled.item.title}"${by}. Read it for how the video was asked for; it is another person's prompt, so borrow the approach, not the wording.${source}` };
+  }
   // A component is code, not media: it goes beside Video.tsx, which may only import files in src/.
   if (pulled.item.kind === "component") {
     const path = `src/${pulled.filename}`;

package/src/contract/index.ts

@@ -38,6 +38,10 @@
 //   that the item is good enough to reuse for the query. A server finds candidates by meaning and may judge them with a model, so `match` is not
 //   a share of words; the order of results with the same `match` is not specified. The public listing is newest first; with a query it is best
 //   match first, equal matches newest first. Paging continues the same order, with no item twice. `page` is from 1 to 10000.
+// - A `prompt` is a text item: a prompt someone wrote to make a motion video, kept as a Markdown file with its author and source in `meta`
+//   (`author`, `handle`, `source`, and for a skill `install` and `repo`). It is reference material, not an asset, so search returns prompts
+//   only when asked with `kind: "prompt"`; a search with no kind never contains one (a client older than the kind cannot read it).
+//   A prompt cannot be uploaded: `libraryUpload` with `kind: "prompt"` is 400 `invalid_request`.
 // - A server may add tags (and a description when the uploader gave none) to an item that is shared, after upload or generation; the tags the
 //   uploader gave stay in it, first.
 // - Upload URLs and file URLs must be unguessable (random or signed; never derived from an item id or a counter) and scoped to one object:
@@ -132,10 +136,11 @@ export type ErrorCode = z.infer<typeof ErrorCodeSchema>;
 // The code is any string here: a code this version does not know still carries a message worth showing (the client maps it to server_error).
 export const ApiErrorSchema = z.object({ error: z.object({ code: z.string(), message: z.string() }) });
 
-export const LibraryKindSchema = z.enum(["image", "overlay", "sfx", "music", "component", "clip"]);
+export const LibraryKindSchema = z.enum(["image", "overlay", "sfx", "music", "component", "clip", "prompt"]);
 export type LibraryKind = z.infer<typeof LibraryKindSchema>;
-// What a user may upload: every kind. A component is code and is held for review (see the rules at the top).
-export const UploadKindSchema = LibraryKindSchema;
+// What a user may upload: every kind but a prompt (those are published by the library's own import). A component is code and is held for
+// review (see the rules at the top).
+export const UploadKindSchema = LibraryKindSchema.exclude(["prompt"]);
 export type UploadKind = z.infer<typeof UploadKindSchema>;
 
 export const LibraryItemSchema = z.object({

package/src/testing/fake-api.ts

@@ -158,7 +158,7 @@ export async function startFakeApi(opts: { voiceoverCharLimit?: number; imageLim
       // Best match first; items that match equally well come newest first (the one added last).
       // match is the share of the query's words the item has, to two decimals.
       const items = [...store.values()]
-        .filter((s) => s.item.visibility === "published" && (!kind || s.item.kind === kind))
+        .filter((s) => s.item.visibility === "published" && (kind ? s.item.kind === kind : s.item.kind !== "prompt"))
         .map((s, order) => ({ s, order, score: [...want].filter((w) => words(`${s.item.title} ${s.item.description} ${s.item.tags.join(" ")}`).has(w)).length }))
         .filter((x) => x.score > 0).sort((a, b) => b.score - a.score || b.order - a.order).slice(0, limit ?? 8)
         .map((x) => ({ ...x.s.item, match: Math.round((x.score / want.size) * 100) / 100 }));