reelkit-cli 0.10.0 → 0.10.2

package/README.md

@@ -25,6 +25,16 @@ reelkit auth login
 
 It installs for every agent it finds on your machine. Name one with `--agent claude`, or use `--agent all`. `reelkit init` and `reelkit auth login` keep the installed skill up to date on their own; set `REELKIT_NO_AUTO_INSTALL=1` to turn that off.
 
+## Studio pane in Claude Code
+
+In Claude Code 2.1.287 or newer the installed skill is also a mod: a Reelkit pane opens beside the conversation when a project is in reach (`/reelkit-studio` opens it by hand, `/reelkit-studio my-video` on a named project). It has five tabs:
+
+- **Timeline**: scene clips with a filmstrip, on-screen text, the voice with a mark per word and the music with its beats. **Play with timeline** opens `out/studio.html` in your browser, the render playing over that timeline with a draggable playhead, zoom and frame-by-frame keys.
+- **Plan**, **Music**, **Components**: what the project holds, read from its files.
+- **Browser**: search the shared library; **Use** hands the pick to Claude.
+
+The pane only reads the project. Its buttons write a request into the prompt for you to send. The mod lives in `skill/hooks`; check it with `claude plugin validate skill` and `claude plugin test skill`.
+
 ## Use
 
 Ask Claude to make a video. The skill takes it from there. To drive it by hand:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reelkit-cli",
-  "version": "0.10.0",
+  "version": "0.10.2",
   "description": "CLI and Claude skill for making short-form video with a shared asset library.",
   "license": "MIT",
   "author": "Daniel Livshin",

package/skill/.claude-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+  "name": "reelkit",
+  "version": "0.1.0",
+  "description": "Reelkit studio: a pane with the film's timeline, plan, music, components and the library, and a browser player for the render.",
+  "author": { "name": "Daniel Livshin" },
+  "types": "./types/index.d.ts"
+}

package/skill/SKILL.md

@@ -11,7 +11,11 @@ Read the material before choosing a treatment. Own routine editing decisions and
 
 For footage, talking heads, screen recordings, mixed media, or an open creative brief, read `reference/studio-editing.md`. It explains how to choose the approach and what this CLI can actually edit. For final verification and platform variants, read `reference/delivery-review.md`.
 
-This skill targets `reelkit-cli` 0.10.0 and its HyperFrames kit. Check the installed version with `reelkit --version`; in a source checkout, invoke its `bin/reelkit.mjs` with Node. Use the matching CLI before authoring with `reelkit/frame`.
+For image or video cutouts, editable Blender product shots, custom 3D materials, or native Higgsfield motion workflows beyond the kit, read `reference/higgsfield-production.md`. It maps the external tools, their connection requirements and the inspected media handoff back to Reelkit.
+
+To implement a chosen style, read its row in `reference/style-recipes.md` for action, timing, sound and proof. `reference/style-components.md` maps the shared components and built-in kit to shot roles; inspect the selected source before using its props.
+
+This skill targets `reelkit-cli` 0.10.2 and its HyperFrames kit. Check the installed version with `reelkit --version`; in a source checkout, invoke its `bin/reelkit.mjs` with Node. Use the matching CLI before authoring with `reelkit/frame`.
 
 Every command takes `--json` for machine-readable output and exits non-zero with a one-line reason when something is wrong. Read the reason and act on it.
 
@@ -108,6 +112,7 @@ Read `reference/hyperframes-composition.md` for the seekable HyperFrames timing
 - **Fit the picture to the voice** (narrated films; the whole method is in `reference/voice-sync.md`). The voice is the clock: write the narration first, record it (step 4), and only then place visuals from the real word times with `onWord(s, "word")` (the frame to start an entrance so it lands on its word; `wordFrame` is the word's own frame, `onWordBeat` lets it land on a beat only within 3 frames after the word). Never count words by hand. One visual event per stressed word and at most one every 0.5 s; the thing a word names is on screen within 3 frames of the word starting, never before the previous sentence ends; numbers count up to finish on their word; a list ticks on each item's word; scene changes fall in the gaps between sentences, never inside one; the last word of a sentence is held for the gap, not longer; sound effects for a word's visual sit under the voice at 0.3 or less. `reelkit check` fails on a word the scene never says, and `reelkit preview` renders a frame 4 frames after each word you timed: each of those should already show the thing that word names.
 - Choose the music before you write the composition, and read `reference/beat-sync.md`: `reelkit assets search "<mood and tempo>" --kind music`, then `reelkit assets pull <id> --music`. Scene changes then land on its beat by themselves; bring each element in on a beat inside a scene as that file shows.
 - 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.
+- When the brief is open ("make it impressive", a launch film, a showreel) and you want to see how others asked for such a video, search the prompt gallery: `reelkit assets search "<kind of video>" --kind prompt`, then `reelkit assets pull <id>` to read the whole prompt in `prompts/`. These are other people's prompts with their author and source: borrow the structure (what they specified: length, beats, style, constraints), never the wording, and never show one in the film. Prompts appear only with `--kind prompt`.
 - Read `reference/sound-design.md`, then find the few sounds the video needs: `reelkit assets search "whoosh" --kind sfx`, `reelkit assets pull <id>`. The pull prints how to reference the file.
 - For a brand reveal, a transformation, or a shot with real depth, read `reference/brand-motion.md` and `reference/three-d.md`. Choose the move by what it explains, preserve the supplied identity, and share its event frames with the sound cues. Keep reading-heavy shots in 2D; a requested brand film or showreel may use several purposeful 3D moments.
 - For what sits behind the whole film (a video, a picture that changes, or an animated ground), read `reference/backgrounds.md`; pick one ground and keep it.
@@ -128,6 +133,16 @@ Verify the finished export using `reference/delivery-review.md`; previews alone
 
 If the render fails, read the error, fix the composition, and run `reelkit check` before rendering again.
 
+## The studio pane
+
+In Claude Code 2.1.287 or newer this skill also loads a mod (`hooks/register.tsx`, read `reference/studio-pane.md` before changing it). It opens a Reelkit pane beside the conversation whenever a project is in reach, and `/reelkit-studio [project folder]` opens it by hand. The pane reads the project's files and follows your `reelkit` commands and edits, so it is current after each step:
+
+- **Timeline**: the film as an editor's timeline (scene clips with a filmstrip from the preview frames, on-screen text, the voice with a mark per word, the music with its beats) and the selected scene's narration. **Play with timeline** writes `out/studio.html` and opens it in the browser: the render playing over the same timeline, with a playhead to drag, zoom, and frame and scene keys. Before a render it steps through the preview frames.
+- **Plan**, **Music**, **Components**: the plan as written, the track, voice and sound effects, and each component in `src/` with its description and source.
+- **Browser**: searches the shared library by kind.
+
+The pane never changes the project by itself. Its buttons (Edit this scene, Change the plan, Use, Render) write a request into the prompt for the user to finish or send; treat such a request as any other from the user. After a preview or a render, tell the user in one line that the pane shows it and that **Play with timeline** plays it.
+
 ## Rules
 
 - Search before generating. Reuse beats regenerate.

package/skill/THIRD_PARTY.md

@@ -1,6 +1,6 @@
 # Third-party sources
 
-Some guidance in these skills, and some starter-kit components, are adapted from three open-source motion-design skills. The first two target a different renderer (HTML pages captured with Playwright), so their engines, scripts and workflows are not used here; only renderer-independent design principles were taken and rewritten for Remotion.
+Some guidance in these skills, and some starter-kit components, are adapted from three open-source motion-design skills. The first two target a different renderer (HTML pages captured with Playwright), so their engines, scripts and workflows are not used here; only renderer-independent design principles were taken and rewritten for Reelkit’s HyperFrames adapter.
 
 - **Barty-Bart/motion-graphics** (`skills/motion-broll`), MIT License, Copyright (c) 2026 Bart.
   https://github.com/Barty-Bart/motion-graphics
@@ -21,7 +21,7 @@ Used in: `motion-design`, `hyperframes-composition`, `scriptwriting`, `scene-tre
 
 ## The 3D typeface
 
-- **Inter** (Bold weight), by the Inter Project Authors (https://github.com/rsms/inter), SIL Open Font License 1.1. It is the one typeface bundled for the kit's `Text3D`, converted to three.js's typeface JSON (the Latin letters, digits, punctuation and a few symbols) and kept as data in `src/remotion/kit/inter-bold-typeface.ts`. The three npm package ships no typeface files, so the glyph outlines were taken from the Inter font files in the `@fontsource/inter` package; the outlines are unchanged apart from scaling to 1000 units to the em. The licence text, as shipped with that package:
+- **Inter** (Bold weight), by the Inter Project Authors (https://github.com/rsms/inter), SIL Open Font License 1.1. It is the one typeface bundled for the kit's `Text3D`, converted to three.js's typeface JSON (the Latin letters, digits, punctuation and a few symbols) and kept as data in `src/hyperframes/kit/inter-bold-typeface.ts`. The three npm package ships no typeface files, so the glyph outlines were taken from the Inter font files in the `@fontsource/inter` package; the outlines are unchanged apart from scaling to 1000 units to the em. The licence text, as shipped with that package:
 
 ```
 Copyright 2016 The Inter Project Authors (https://github.com/rsms/inter) Inter-Italic[opsz,wght].ttf: Copyright 2016 The Inter Project Authors (https://github.com/rsms/inter)
@@ -120,3 +120,35 @@ OTHER DEALINGS IN THE FONT SOFTWARE.
 ```
 
 The 3D layer depends on `three` (MIT) and `@react-three/fiber` (MIT). Rendering uses `@hyperframes/engine` (Apache-2.0). Fonts are bundled locally from Fontsource; each family retains its original font licence in its installed package.
+
+## Additional production references
+
+The style recipes and external-production guide summarize the project owner’s supplied CapCut studio-editing reference and reviewed official Higgsfield and HyperFrames documentation. They adapt relevant craft and identify runtime boundaries; external editor code and services are not bundled. Sources: https://higgsfield.ai/skills, https://higgsfield.ai/plugins/blender, https://github.com/heygen-com/hyperframes/tree/main/skills.
+
+## Art-style catalog
+
+`reference/art-styles.md` adapts the fifteen style films and prompts in **Vincentwei1021/mg-styles-15**, https://github.com/VincentWei1021/mg-styles-15. The motion recipes are translated for Reelkit rather than bundling the original renderer. Its MIT notice follows:
+
+```
+MIT License
+
+Copyright (c) 2026 Vincentwei1021
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```

package/skill/hooks/hooks.json

@@ -0,0 +1 @@
+{ "modules": ["./register.tsx"] }

package/skill/hooks/player.ts

@@ -0,0 +1,278 @@
+import type { Film } from '../types'
+
+/**
+ * The page the pane opens in a browser, written to out/studio.html beside the render: the film playing over an editor's timeline with a
+ * ruler, clips, text, voice and music lanes, a playhead to drag, zoom, and keys. Before a render exists it steps through the preview frames.
+ */
+export function playerHtml(film: Film): string {
+  const data = {
+    title: film.title,
+    aspect: film.aspect,
+    fps: film.fps,
+    seconds: film.totalFrames / film.fps,
+    isTimed: film.isTimed,
+    hasVideo: film.render !== null,
+    videoStamp: film.render?.at ?? 0,
+    music: film.music,
+    scenes: film.scenes.map((scene, index) => ({
+      id: scene.id,
+      start: scene.start / film.fps,
+      length: scene.frames / film.fps,
+      narration: scene.narration,
+      text: scene.text,
+      notes: scene.notes,
+      treatment: scene.treatment,
+      words: scene.words,
+      stem: `preview/${String(index + 1).padStart(2, '0')}-${scene.id}-`,
+    })),
+  }
+  const json = JSON.stringify(data).replace(/</g, '\\u003c')
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Reelkit studio</title>
+<style>
+  :root { --bg:#0f1013; --panel:#17181d; --lane:#1e2026; --line:#2a2c35; --ink:#eceef4; --dim:#8b8d98; --accent:#c8f55a; }
+  * { box-sizing:border-box; }
+  html,body { height:100%; margin:0; background:var(--bg); color:var(--ink); font:13px/1.45 -apple-system,"Segoe UI",Helvetica,Arial,sans-serif; }
+  body { display:grid; grid-template-rows:minmax(0,1fr) auto auto; }
+  .top { display:grid; grid-template-columns:minmax(0,1fr) 320px; min-height:0; }
+  .stage { display:flex; align-items:center; justify-content:center; padding:16px; min-height:0; }
+  .stage video, .stage img { max-width:100%; max-height:100%; border-radius:10px; background:#000; box-shadow:0 10px 40px rgba(0,0,0,.5); }
+  .stage .none { color:var(--dim); text-align:center; max-width:340px; }
+  .side { background:var(--panel); border-left:1px solid var(--line); padding:16px; overflow:auto; }
+  .side h1 { font-size:15px; margin:0 0 2px; }
+  .side .meta { color:var(--dim); margin-bottom:14px; }
+  .side h2 { font-size:11px; letter-spacing:.08em; text-transform:uppercase; color:var(--dim); margin:16px 0 4px; }
+  .side p { margin:0; white-space:pre-wrap; unicode-bidi:plaintext; }
+  .chips span { display:inline-block; background:#3b2a66; color:#d6c9ff; border-radius:5px; padding:1px 7px; margin:0 4px 4px 0; unicode-bidi:plaintext; }
+  .bar { display:flex; align-items:center; gap:12px; padding:8px 14px; background:var(--panel); border-top:1px solid var(--line); }
+  .bar button { background:#262830; color:var(--ink); border:1px solid var(--line); border-radius:7px; padding:5px 11px; font:inherit; cursor:pointer; }
+  .bar button:hover { background:#30333d; }
+  .bar button.play { background:var(--accent); color:#111; border-color:transparent; font-weight:600; min-width:64px; }
+  .bar .time { font-variant-numeric:tabular-nums; min-width:120px; }
+  .bar .grow { flex:1; }
+  .bar label { color:var(--dim); display:flex; align-items:center; gap:6px; }
+  .bar .keys { color:var(--dim); font-size:12px; }
+  .tl { background:var(--panel); border-top:1px solid var(--line); display:grid; grid-template-columns:64px minmax(0,1fr); height:228px; }
+  .names { padding-top:26px; color:var(--dim); font-size:12px; }
+  .names div { padding-left:12px; display:flex; align-items:center; }
+  .scroll { overflow-x:auto; overflow-y:hidden; position:relative; }
+  .inner { position:relative; height:100%; min-width:100%; }
+  .ruler { height:26px; position:relative; border-bottom:1px solid var(--line); cursor:pointer; }
+  .ruler i { position:absolute; top:0; bottom:0; border-left:1px solid var(--line); padding:5px 0 0 4px; color:var(--dim); font-style:normal; font-size:11px; font-variant-numeric:tabular-nums; }
+  .lane { position:relative; margin-top:6px; background:var(--lane); border-radius:5px; }
+  .h-video { height:70px; } .h-text { height:24px; } .h-voice { height:30px; } .h-music { height:24px; }
+  .clip { position:absolute; top:0; bottom:0; border-radius:6px; overflow:hidden; cursor:pointer; background-size:auto 100%; background-repeat:repeat-x; outline:1px solid rgba(0,0,0,.4); }
+  .clip b { position:absolute; left:0; right:0; bottom:0; padding:1px 6px; background:rgba(0,0,0,.55); font-weight:600; font-size:11px; white-space:nowrap; overflow:hidden; text-overflow:ellipsis; }
+  .clip.on { outline:2px solid #fff; z-index:1; }
+  .chip { position:absolute; top:0; bottom:0; border-radius:5px; padding:3px 6px; font-size:11px; white-space:nowrap; overflow:hidden; text-overflow:ellipsis; background:#3b2a66; color:#d6c9ff; unicode-bidi:plaintext; }
+  .vo { position:absolute; top:0; bottom:0; border-radius:5px; background:#0f3d3a; }
+  .vo u { position:absolute; width:2px; border-radius:1px; background:#2dd4bf; top:50%; transform:translateY(-50%); }
+  .mu { position:absolute; top:0; bottom:0; left:0; border-radius:5px; background:#1e2a5a; color:#aeb8ff; font-size:11px; padding:4px 7px; white-space:nowrap; overflow:hidden; }
+  .mu u { position:absolute; bottom:0; width:1px; height:6px; background:#7c8cff; }
+  .head { position:absolute; top:0; bottom:0; width:0; border-left:2px solid #fff; pointer-events:none; z-index:3; }
+  .head:before { content:""; position:absolute; top:14px; left:-7px; border:6px solid transparent; border-top:9px solid #fff; }
+  @media (max-width:760px) { .top { grid-template-columns:1fr; } .side { display:none; } .bar .keys { display:none; } }
+</style>
+</head>
+<body>
+<div class="top">
+  <div class="stage" id="stage"></div>
+  <aside class="side">
+    <h1 id="title"></h1>
+    <div class="meta" id="meta"></div>
+    <h2>Scene</h2><p id="scene"></p>
+    <h2>Narration</h2><p id="narration"></p>
+    <h2>On screen</h2><div class="chips" id="chips"></div>
+    <h2>Direction</h2><p id="notes"></p>
+  </aside>
+</div>
+<div class="bar">
+  <button class="play" id="play">Play</button>
+  <button id="prev" title="Previous scene">|◀</button>
+  <button id="next" title="Next scene">▶|</button>
+  <span class="time" id="time"></span>
+  <span class="grow"></span>
+  <span class="keys">Space play · ←/→ one frame · Shift+←/→ one second · J/K scene</span>
+  <label>Zoom <input type="range" id="zoom" min="1" max="12" step="0.25" value="1"></label>
+</div>
+<div class="tl">
+  <div class="names">
+    <div style="height:76px">Video</div><div style="height:30px">Text</div><div style="height:36px">Voice</div><div style="height:30px">Music</div>
+  </div>
+  <div class="scroll" id="scroll">
+    <div class="inner" id="inner">
+      <div class="ruler" id="ruler"></div>
+      <div class="lane h-video" id="lv"></div>
+      <div class="lane h-text" id="lt"></div>
+      <div class="lane h-voice" id="lo"></div>
+      <div class="lane h-music" id="lm"></div>
+      <div class="head" id="head"></div>
+    </div>
+  </div>
+</div>
+<script id="film" type="application/json">${json}</script>
+<script>
+(function () {
+  var F = JSON.parse(document.getElementById('film').textContent);
+  var $ = function (id) { return document.getElementById(id); };
+  var COLORS = ['#2563eb', '#7c3aed', '#db2777', '#ea580c', '#059669', '#0891b2'];
+  var total = Math.max(0.1, F.seconds);
+  var zoom = 1, now = 0, playing = false, last = 0, picked = -1;
+  var video = null, still = null;
+
+  var fmt = function (s) { s = Math.max(0, s); return Math.floor(s / 60) + ':' + (s % 60).toFixed(2).padStart(5, '0'); };
+  var el = function (tag, cls, text) { var n = document.createElement(tag); if (cls) n.className = cls; if (text !== undefined) n.textContent = text; return n; };
+  var sceneAt = function (t) {
+    for (var i = F.scenes.length - 1; i >= 0; i--) if (t >= F.scenes[i].start - 0.0005) return i;
+    return 0;
+  };
+
+  $('title').textContent = F.title;
+  $('meta').textContent = F.aspect + ' · ' + fmt(total) + ' · ' + F.scenes.length + ' scenes' + (F.isTimed ? '' : ' · estimated timings');
+
+  if (F.hasVideo) {
+    video = el('video');
+    video.src = 'video.mp4?v=' + F.videoStamp;
+    video.playsInline = true;
+    video.addEventListener('play', function () { playing = true; paint(); });
+    video.addEventListener('pause', function () { playing = false; paint(); });
+    video.addEventListener('click', toggle);
+    video.addEventListener('timeupdate', function () { now = video.currentTime; paint(); });
+    $('stage').appendChild(video);
+  } else {
+    still = el('img');
+    still.alt = 'Preview frame';
+    still.addEventListener('error', function () {
+      if (still.dataset.tried !== '1') { still.dataset.tried = '1'; still.src = still.src.replace('-late.jpg', '-early.jpg'); return; }
+      still.replaceWith(el('div', 'none', 'Nothing is rendered yet. Run reelkit preview for frames or reelkit render for the film, then open this page again.'));
+    });
+    $('stage').appendChild(still);
+  }
+
+  function width() { return Math.max(1, $('scroll').clientWidth * zoom); }
+  function px(t) { return (t / total) * width(); }
+
+  function build() {
+    var w = width();
+    $('inner').style.width = w + 'px';
+    var ruler = $('ruler'); ruler.textContent = '';
+    var steps = [0.1, 0.25, 0.5, 1, 2, 5, 10, 15, 30, 60];
+    var step = 120;
+    for (var k = 0; k < steps.length; k++) if (px(steps[k]) >= 64) { step = steps[k]; break; }
+    for (var t = 0; t <= total + 0.0001; t += step) {
+      var mark = el('i', '', px(t) > w - 44 ? '' : fmt(t)); mark.style.left = px(t) + 'px'; ruler.appendChild(mark);
+    }
+    var lv = $('lv'), lt = $('lt'), lo = $('lo'), lm = $('lm');
+    lv.textContent = lt.textContent = lo.textContent = lm.textContent = '';
+    F.scenes.forEach(function (s, i) {
+      var left = px(s.start) + 1, wide = Math.max(3, px(s.length) - 2);
+      var clip = el('div', 'clip' + (i === picked ? ' on' : ''));
+      clip.style.left = left + 'px'; clip.style.width = wide + 'px';
+      clip.style.backgroundColor = COLORS[i % COLORS.length];
+      clip.style.backgroundImage = 'url("' + s.stem + 'late.jpg"), url("' + s.stem + 'early.jpg")';
+      clip.appendChild(el('b', '', (i + 1) + ' ' + s.id));
+      clip.addEventListener('click', function (e) { e.stopPropagation(); seek(s.start + 0.001); });
+      lv.appendChild(clip);
+      if (s.text.length) {
+        var chip = el('div', 'chip', s.text.join('  ·  ')); chip.style.left = left + 'px'; chip.style.width = wide + 'px'; lt.appendChild(chip);
+      }
+      if (s.narration) {
+        var vo = el('div', 'vo'); vo.style.left = left + 'px'; vo.style.width = wide + 'px'; vo.title = s.narration;
+        s.words.forEach(function (sec, n) {
+          var bar = el('u'); bar.style.left = (px(sec) - 1) + 'px'; bar.style.height = (8 + ((n * 7 + i * 3) % 5) * 4) + 'px'; vo.appendChild(bar);
+        });
+        lo.appendChild(vo);
+      }
+    });
+    if (F.music) {
+      var length = F.music.seconds > 0 ? Math.min(F.music.seconds, total) : total;
+      var mu = el('div', 'mu', '♪ ' + F.music.title + (F.music.bpm ? ' · ' + Math.round(F.music.bpm) + ' BPM' : ''));
+      mu.style.width = px(length) + 'px';
+      F.music.beats.forEach(function (sec) { if (sec > length) return; var tick = el('u'); tick.style.left = px(sec) + 'px'; mu.appendChild(tick); });
+      lm.appendChild(mu);
+    }
+    paint();
+  }
+
+  function paint() {
+    $('head').style.left = px(now) + 'px';
+    $('time').textContent = fmt(now) + ' / ' + fmt(total);
+    $('play').textContent = playing ? 'Pause' : 'Play';
+    var i = sceneAt(now);
+    if (i === picked) return;
+    picked = i;
+    var s = F.scenes[i];
+    var clips = $('lv').children;
+    for (var k = 0; k < clips.length; k++) clips[k].classList.toggle('on', k === i);
+    if (!s) return;
+    $('scene').textContent = (i + 1) + '. ' + s.id + '  ·  ' + fmt(s.start) + ' to ' + fmt(s.start + s.length) + (s.treatment ? '  ·  ' + s.treatment : '');
+    $('narration').textContent = s.narration || 'No narration.';
+    var chips = $('chips'); chips.textContent = '';
+    s.text.forEach(function (line) { chips.appendChild(el('span', '', line)); });
+    if (!s.text.length) chips.textContent = 'None.';
+    $('notes').textContent = s.notes || 'None.';
+    if (still) { still.dataset.tried = ''; still.src = s.stem + 'late.jpg'; }
+  }
+
+  function follow() {
+    var box = $('scroll'), at = px(now);
+    if (at < box.scrollLeft + 40 || at > box.scrollLeft + box.clientWidth - 40) box.scrollLeft = Math.max(0, at - box.clientWidth / 3);
+  }
+
+  function seek(t) {
+    now = Math.min(total, Math.max(0, t));
+    if (video) video.currentTime = now;
+    paint(); follow();
+  }
+
+  function toggle() {
+    if (video) { if (video.paused) video.play(); else video.pause(); return; }
+    playing = !playing; last = performance.now();
+    if (playing && now >= total - 0.01) now = 0;
+    paint();
+  }
+
+  function frame(stamp) {
+    if (video) { if (!video.paused) { now = video.currentTime; paint(); follow(); } }
+    else if (playing) {
+      now += (stamp - last) / 1000; last = stamp;
+      if (now >= total) { now = total; playing = false; }
+      paint(); follow();
+    }
+    requestAnimationFrame(frame);
+  }
+
+  function pointerTime(e) {
+    var box = $('inner').getBoundingClientRect();
+    return ((e.clientX - box.left) / box.width) * total;
+  }
+  var dragging = false;
+  $('inner').addEventListener('pointerdown', function (e) { dragging = true; $('inner').setPointerCapture(e.pointerId); seek(pointerTime(e)); });
+  $('inner').addEventListener('pointermove', function (e) { if (dragging) seek(pointerTime(e)); });
+  $('inner').addEventListener('pointerup', function () { dragging = false; });
+  $('play').addEventListener('click', toggle);
+  $('prev').addEventListener('click', function () { var i = sceneAt(now); var s = F.scenes[now - F.scenes[i].start > 0.3 ? i : Math.max(0, i - 1)]; seek(s.start + 0.001); });
+  $('next').addEventListener('click', function () { var s = F.scenes[Math.min(F.scenes.length - 1, sceneAt(now) + 1)]; seek(s.start + 0.001); });
+  $('zoom').addEventListener('input', function (e) { zoom = Number(e.target.value); build(); follow(); });
+  window.addEventListener('resize', build);
+  window.addEventListener('keydown', function (e) {
+    if (e.target && e.target.tagName === 'INPUT') return;
+    if (e.code === 'Space') { e.preventDefault(); toggle(); }
+    else if (e.key === 'ArrowLeft') seek(now - (e.shiftKey ? 1 : 1 / F.fps));
+    else if (e.key === 'ArrowRight') seek(now + (e.shiftKey ? 1 : 1 / F.fps));
+    else if (e.key === 'j' || e.key === 'J') $('prev').click();
+    else if (e.key === 'k' || e.key === 'K') $('next').click();
+  });
+
+  build();
+  requestAnimationFrame(frame);
+})();
+</script>
+</body>
+</html>
+`
+}

package/skill/hooks/project.ts

@@ -0,0 +1,227 @@
+
+import type { Film, FilmComponent, FilmScene, FilmSound } from '../types'
+
+// What the loader needs of the engine, handed over as plain functions: a hooks module keeps `$` itself in its own file.
+type Entry = { name: string; kind: 'file' | 'dir' | 'other'; size: number; mtimeMs: number }
+
+export type Host = {
+  read: (path: string) => Promise<string>
+  list: (path: string) => Promise<Entry[]>
+  exists: (path: string) => Promise<boolean>
+  stat: (path: string) => Promise<Omit<Entry, 'name'>>
+  run: (argv: string[], timeoutMs?: number) => Promise<{ exitCode: number }>
+  cwd: () => Promise<string>
+  now: () => Promise<number>
+}
+
+type Loose = Record<string, any>
+
+const MARK = 'reelkit.json'
+const THUMBS = 'out/.studio'
+
+export const join = (...parts: string[]): string => parts.join('/').replace(/\/{2,}/g, '/')
+export const baseName = (path: string): string => path.replace(/\/+$/, '').split('/').pop() ?? path
+const parent = (path: string): string => path.replace(/\/+$/, '').split('/').slice(0, -1).join('/') || '/'
+const round = (n: number, digits = 2): number => Number(n.toFixed(digits))
+
+async function readJson(host: Host, path: string): Promise<Loose | undefined> {
+  try {
+    return JSON.parse(await host.read(path)) as Loose
+  } catch {
+    return undefined
+  }
+}
+
+const isProject = (host: Host, dir: string): Promise<boolean> => host.exists(join(dir, MARK)).catch(() => false)
+
+// The project a path belongs to: the nearest folder at or above it that holds reelkit.json.
+export async function projectOf(host: Host, path: string): Promise<string | undefined> {
+  let dir = path
+  for (let depth = 0; depth < 6 && dir !== '/' && dir !== ''; depth += 1) {
+    if (await isProject(host, dir)) return dir
+    dir = parent(dir)
+  }
+  return undefined
+}
+
+// The projects in reach of the session: the one the working directory is in, then the ones directly under it, newest first.
+export async function findProjects(host: Host): Promise<string[]> {
+  const cwd = await host.cwd()
+  const own = await projectOf(host, cwd)
+  const entries = await host.list(cwd).catch(() => [])
+  const dirs = entries.filter(one => one.kind === 'dir' && !one.name.startsWith('.') && one.name !== 'node_modules').slice(0, 80)
+  const found = await Promise.all(
+    dirs.map(async one => {
+      const dir = join(cwd, one.name)
+      if (!(await isProject(host, dir))) return undefined
+      const stat = await host.stat(join(dir, 'plan.json')).catch(() => undefined)
+      return { dir, at: stat?.mtimeMs ?? 0 }
+    }),
+  )
+  const below = found
+    .filter((one): one is { dir: string; at: number } => one !== undefined)
+    .sort((a, b) => b.at - a.at)
+    .map(one => one.dir)
+  return [...new Set([...(own ? [own] : []), ...below])].slice(0, 12)
+}
+
+// The length a scene will have before the voice is recorded: its `seconds`, or its narration read at a normal pace.
+const estimateSeconds = (scene: Loose): number => {
+  if (typeof scene.seconds === 'number') return scene.seconds
+  const words = String(scene.narration ?? '').split(/\s+/).filter(Boolean).length
+  return Math.max(1.5, words / 2.6 + 0.3)
+}
+
+// What a component shows: the comment written just above its export, else the nearest comment above the first export, else the file's first.
+const aboutOf = (source: string, name: string): string => {
+  const clean = (lines: string): string => lines.replace(/^\s*(\/\/|\/\*+|\*\/|\*)\s?/gm, '').replace(/\s+/g, ' ').trim().slice(0, 240)
+  const above = (anchor: RegExp): string => {
+    const at = source.search(anchor)
+    if (at < 0) return ''
+    const before = source.slice(0, at).split('\n').slice(0, -1)
+    const block: string[] = []
+    while (before.length && /^\s*(\/\/|\/\*|\*)/.test(before[before.length - 1] ?? '')) block.unshift(before.pop() ?? '')
+    return clean(block.join('\n'))
+  }
+  const own = above(new RegExp(`^export (?:default )?(?:const|function) ${name}\\b`, 'm'))
+  if (own) return own
+  const first = above(/^export (?:default )?(?:const|function) /m)
+  if (first) return first
+  return clean(/^(?:\/\/[^\n]*\n)+/m.exec(source)?.[0] ?? '')
+}
+
+async function loadComponents(host: Host, dir: string): Promise<FilmComponent[]> {
+  const entries = await host.list(join(dir, 'src')).catch(() => [])
+  const files = entries.filter(one => one.kind === 'file' && /\.tsx$/.test(one.name) && one.name !== 'Video.tsx').slice(0, 24)
+  return Promise.all(
+    files.map(async one => {
+      const path = join(dir, 'src', one.name)
+      const source = await host.read(path).catch(() => '')
+      const name = one.name.replace(/\.tsx$/, '')
+      return { name, path, about: aboutOf(source, name) }
+    }),
+  )
+}
+
+// One small picture per scene, cut from the preview frames, so the timeline can show a filmstrip. Skipped where no tool can scale a picture.
+async function makeThumbs(host: Host, dir: string, ids: string[]): Promise<Record<string, string>> {
+  const frames = await host.list(join(dir, 'out/preview')).catch(() => [])
+  if (frames.length === 0) return {}
+  await host.run(['mkdir', '-p', join(dir, THUMBS)]).catch(() => undefined)
+  const made = await host.list(join(dir, THUMBS)).catch(() => [])
+  const pairs = await Promise.all(
+    ids.map(async (id, index) => {
+      const stem = `${String(index + 1).padStart(2, '0')}-${id}-`
+      const frame = frames.find(one => one.name === `${stem}late.jpg`) ?? frames.find(one => one.name === `${stem}early.jpg`)
+      if (!frame) return undefined
+      const target = join(dir, THUMBS, `${id}.jpg`)
+      const old = made.find(one => one.name === `${id}.jpg`)
+      if (old && old.mtimeMs >= frame.mtimeMs) return [id, target] as const
+      const source = join(dir, 'out/preview', frame.name)
+      const scaled = await host.run(['ffmpeg', '-y', '-loglevel', 'error', '-i', source, '-vf', 'scale=-2:120', '-q:v', '8', target], 20000)
+        .catch(() => undefined)
+      if (scaled?.exitCode === 0) return [id, target] as const
+      const sipped = await host.run(['sips', '-Z', '120', source, '--out', target], 20000).catch(() => undefined)
+      return sipped?.exitCode === 0 ? ([id, target] as const) : undefined
+    }),
+  )
+  return Object.fromEntries(pairs.filter((one): one is readonly [string, string] => one !== undefined))
+}
+
+// Everything the pane shows about one project, read from its files: the plan, the measured timings, the sound, the components, the render.
+export async function loadFilm(host: Host, dir: string): Promise<Film | null> {
+  const [mark, plan, manifest, music, library, index] = await Promise.all([
+    readJson(host, join(dir, MARK)),
+    readJson(host, join(dir, 'plan.json')),
+    readJson(host, join(dir, 'manifest.json')),
+    readJson(host, join(dir, 'assets/music.json')),
+    readJson(host, join(dir, 'assets/library.json')),
+    readJson(host, join(dir, 'assets/index.json')),
+  ])
+  if (!mark) return null
+  const fps = typeof manifest?.fps === 'number' ? manifest.fps : 30
+  const planned: Loose[] = Array.isArray(plan?.scenes) ? plan.scenes : []
+  const timed: Loose[] = Array.isArray(manifest?.scenes) ? manifest.scenes : []
+  const ids: string[] = (planned.length ? planned : timed).map(one => String(one.id))
+  const thumbs = await makeThumbs(host, dir, ids).catch(() => ({}) as Record<string, string>)
+
+  let cursor = 0
+  const scenes: FilmScene[] = ids.slice(0, 24).map(id => {
+    const p = planned.find(one => one.id === id) ?? {}
+    const m = timed.find(one => one.id === id)
+    const start = typeof m?.startFrame === 'number' ? m.startFrame : cursor
+    const frames = typeof m?.durationFrames === 'number' ? m.durationFrames : Math.round(estimateSeconds(p) * fps)
+    cursor = start + frames
+    const words: Loose[] = Array.isArray(m?.words) ? m.words : []
+    return {
+      id,
+      start,
+      frames,
+      narration: String(p.narration ?? '').slice(0, 600),
+      text: (Array.isArray(p.onScreenText) ? p.onScreenText : []).map(String).slice(0, 4),
+      treatment: String(p.treatment ?? ''),
+      notes: String(p.notes ?? '').slice(0, 400),
+      words: words.slice(0, 60).map(one => round(Number(one.startSec) || 0)),
+      thumb: thumbs[id] ?? '',
+    }
+  })
+  const totalFrames = typeof manifest?.totalFrames === 'number' ? manifest.totalFrames : cursor
+
+  const sounds: FilmSound[] = Object.entries((library ?? {}) as Record<string, Loose>)
+    .filter(([, one]) => one && typeof one === 'object' && typeof one.path === 'string')
+    .map(([id, one]) => ({
+      id,
+      kind: String(one.kind ?? ''),
+      title: String(one.title ?? id),
+      path: String(one.path),
+      seconds: round(Number(one.meta?.durationSec) || 0),
+    }))
+    .slice(0, 60)
+
+  const musicKey = String(music?.key ?? manifest?.music?.key ?? '')
+  const beatFrames: number[] = Array.isArray(manifest?.music?.beatFrames) ? manifest.music.beatFrames : []
+  const beats = beatFrames.length
+    ? beatFrames.map(frame => round(frame / fps))
+    : (Array.isArray(music?.beats) ? (music.beats as number[]) : []).map(one => round(one))
+
+  const [components, render, previews] = await Promise.all([
+    loadComponents(host, dir),
+    host.stat(join(dir, 'out/video.mp4')).catch(() => undefined),
+    host.list(join(dir, 'out/preview')).catch(() => []),
+  ])
+  const users: Loose[] = Array.isArray(index) ? index : []
+
+  return {
+    dir,
+    name: String(mark.name ?? baseName(dir)),
+    title: String(plan?.title ?? mark.name ?? baseName(dir)),
+    aspect: String(plan?.aspect ?? mark.aspect ?? '9:16'),
+    fps,
+    totalFrames,
+    isTimed: timed.length > 0,
+    voice: String(plan?.voice ?? plan?.voiceId ?? ''),
+    pace: String(plan?.pace ?? ''),
+    captions: String(plan?.captions ?? manifest?.captions ?? ''),
+    scenes,
+    music: musicKey
+      ? {
+          title: String(music?.title ?? sounds.find(one => one.path === musicKey)?.title ?? baseName(parent(musicKey))),
+          path: musicKey,
+          bpm: round(Number(manifest?.music?.bpm ?? music?.bpm) || 0, 1),
+          seconds: round(Number(music?.durationSec) || 0),
+          beats: beats.slice(0, 400),
+        }
+      : null,
+    sounds,
+    components,
+    userAssets: users.slice(0, 30).map(one => ({
+      id: String(one.id ?? ''),
+      kind: String(one.kind ?? ''),
+      name: String(one.filename ?? ''),
+      about: String(one.description ?? '').slice(0, 200),
+    })),
+    render: render?.kind === 'file' ? { path: join(dir, 'out/video.mp4'), bytes: render.size, at: render.mtimeMs } : null,
+    previews: previews.filter(one => /\.jpg$/.test(one.name)).length,
+    loadedAt: await host.now(),
+  }
+}