@bycrux/montaj-skills 0.2.0 → 0.3.1

package/contract.md

@@ -42,9 +42,11 @@ Never save from a stale cached body. The operator may be editing the project con
 
 These verbs are sufficient for the Phase-1 domain skills:
 
-- **select-takes** — run step `crop_spec`, run step `virtual_to_original`; read the project.
+- **select-takes** — run step `crop_spec`, run step `virtual_to_original`; read the project; write a file (the trim spec comes back inline from `waveform_trim` and must be on disk before `crop_spec` can take it as `--input`).
 - **overlay** — read the project; save the project (delta); load skill `write-overlay`.
-- **write-overlay** — save the project (delta); write a file (the JSX); reference asset paths via written/read files.
+- **write-overlay** — save the project (delta); write a file (the JSX); run step `sample_overlay` (the end-of-authoring measure pass, required for any overlay that declares `googleFonts`); reference asset paths via written/read files.
 - **image-search** — run step `search_images`, run step `fetch_image`; write a file / read a file.
 
 If a future domain skill needs an operation not on this list, extend this contract first — do not let a domain skill invent its own transport-specific phrasing.
+
+**This list is a starting index, not the final word.** It has drifted from the skill bodies before: `select-takes`'s "write a file" and `write-overlay`'s `sample_overlay` were both required by their skills and missing here. Anyone deriving the operations a workflow needs must confirm against the skill body itself — a set derived from this list alone can silently omit something the skill genuinely requires.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bycrux/montaj-skills",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "private": false,
   "type": "module",
   "files": [

package/skills/overlay.md

@@ -45,7 +45,7 @@ If the prompt says "no overlays" — write nothing. Don't add an opening hook an
 - **Go large** — 96–160px is a starting point, not a ceiling. If it looks a little too big, it's probably right. Small text gets scrolled past.
 - **No backgrounds** — avoid dark cards, frosted panels, and semi-transparent boxes unless the prompt asks for them. A text shadow (`textShadow: '0 2px 16px rgba(0,0,0,0.9)'`) is enough to ensure legibility on any footage without boxing the text in.
 - **Covering the face is fine** — text is more important than an unobstructed view of the speaker. Don't shrink or reposition text just to avoid the face.
-- **Match the energy of the speech** — fast, punchy delivery gets tight entrance animations (4–6 frames). Slower, deliberate speech gets a smoother slide or fade (10–15 frames).
+- **Match the energy of the speech** — fast, punchy delivery gets tight entrance animations (about 0.13–0.2s: `Math.round(fps * 0.13)` to `Math.round(fps * 0.2)`). Slower, deliberate speech gets a smoother slide or fade (about 0.33–0.5s). Never hardcode frame counts; projects can be 24, 30 or 60fps.
 - **Use color sparingly** — one accent color maximum. White text with a colored word or icon reads better than multi-color text.
 - **Avoid the bottom ~350px** — that's where captions render and where platform UI lives (TikTok progress bar, Instagram controls). Keep `bottom` values above 350px, or use `top`-anchored placement instead.
 - **Avoid the right ~200px** — TikTok and Instagram stack action buttons (like, comment, share, follow) down the right edge. Don't push text or icons into that zone.
@@ -91,6 +91,8 @@ For multiple non-overlapping overlays, add them to the same track. For simultane
 
 Follow save discipline: **read the project**, merge the updated `tracks` array into the fresh state, then **save the project (delta)**.
 
+When this is the last editorial pass before the render, the project must be `final` before the render will run — see skill `native` → "Project lifecycle — status, and the render gate".
+
 ## Rules
 
 - **Use icons, not emojis** — `Ph.*` (Phosphor) or `FaIcon` with `FaSolid`/`FaBrands` (Font Awesome). Both are available as globals — no imports needed. Only use emojis if the prompt asks.

package/skills/select-takes.md

@@ -122,6 +122,8 @@ Run step `virtual_to_original` with `{"input": "spec.json", "inverse": true, "ti
 
 An ordered list of `_selected.json` trim spec paths — one per selected section, in narrative order. These become the inputs to `rm_fillers`, and the keeps that survive it become the `tracks[0]` items the render engine assembles.
 
+When this is the last editorial pass before the render, the project must be `final` before the render will run — see skill `native` → "Project lifecycle — status, and the render gate".
+
 ## What to Log
 
 Before writing specs, log your decisions clearly:

package/skills/write-overlay.md

@@ -7,6 +7,8 @@ description: "Write a custom JSX overlay component and add it to the project's o
 
 An overlay is a React component rendered frame-by-frame by Puppeteer, composited over the footage at a specific timestamp. All overlays are custom JSX — there are no built-in templates.
 
+> **Read [MOTION.md](MOTION.md) alongside this file whenever the overlay actually moves.** This file covers getting an overlay on screen correctly; MOTION.md covers making it move like someone designed it — the easing catalog (`interpolate` is strictly linear and has no easing option, which is why untutored overlays look flat), directional motion blur, per-character stagger, the no-dead-air rule, and how to verify motion by measurement instead of by eye. Every technique in it was rendered through the real sandbox before it was written down.
+
 ---
 
 ## Execution context
@@ -28,21 +30,24 @@ Custom overlay JSX runs in a sandboxed evaluator. All identifiers below are inje
 | `THREE` | namespace | All [Three.js](https://threejs.org) primitives — `THREE.Vector3`, `THREE.MathUtils`, etc. Only reach for it when you genuinely need 3D — see "3D / Three.js" section. |
 | `Canvas` | component | [@react-three/fiber](https://r3f.docs.pmnd.rs) Canvas. **Always pass `frameloop="never"`** and mount a `useThreeFrame()` child — see "3D / Three.js" section. |
 | `useThreeFrame` | hook | Bridges r3f to Montaj's frame-stepped renderer. Mount exactly once inside any `<Canvas>`. |
+| `useCanvas2DFrame` | hook | Drives a plain `CanvasRenderingContext2D` from `frame` — for pixel-level 2D drawing HTML/CSS can't do (per-pixel effects, arbitrary paths, `drawImage` compositing). See "2D Canvas" section. |
 
 **No imports.** All `import` statements are stripped before evaluation. Do not import anything — use the globals above instead.
 
+**Never hardcode frame counts; projects can be 24, 30 or 60fps.** A literal like `[0, 10]` means a different real-world duration on every project — 10 frames is 0.33s at 30fps but 0.17s at 60fps, so an overlay copied between projects (or a 30fps example copied into a 60fps project, which is the current default) plays at the wrong speed. Always derive the frame count from `fps`: `Math.round(fps * 0.33)` for "about a third of a second," not `10`.
+
 ### Top-level vs component-body
 
 **All calls to `interpolate`, `spring`, and any read of `frame`, `fps`, `duration`, or `props` must be inside the component function body.** The module's top-level code runs before the render shim sets up these globals — calling them outside a function will throw `interpolate is not defined` and crash the entire render.
 
 ```jsx
 // WRONG — crashes at render time
-const opacity = interpolate(frame, [0, 10], [0, 1])
+const opacity = interpolate(frame, [0, Math.round(fps * 0.33)], [0, 1])
 export default function Hook() { ... }
 
 // CORRECT — inside the component, runs each frame
 export default function Hook() {
-  const opacity = interpolate(frame, [0, 10], [0, 1])
+  const opacity = interpolate(frame, [0, Math.round(fps * 0.33)], [0, 1])
   return <div style={{ opacity }}>...</div>
 }
 ```
@@ -74,8 +79,8 @@ The default aesthetic is **plain bold text directly on video** — no card, no b
 // overlays/hook.jsx — plain text on video, no background
 
 export default function Hook() {
-  const progress = interpolate(frame, [0, 8], [0, 1], { extrapolateRight: 'clamp' })
-  const slideY   = interpolate(frame, [0, 10], [40, 0], { extrapolateRight: 'clamp' })
+  const progress = interpolate(frame, [0, Math.round(fps * 0.27)], [0, 1])
+  const slideY   = interpolate(frame, [0, Math.round(fps * 0.33)], [40, 0])
 
   return (
     <div style={{
@@ -124,8 +129,8 @@ A control appears for each of those that is present (non-null) on `props`; anyth
 ```jsx
 // Editable Hook — every text property is adjustable in the panel.
 export default function Hook() {
-  const progress = interpolate(frame, [0, 8], [0, 1], { extrapolateRight: 'clamp' })
-  const slideY   = interpolate(frame, [0, 10], [40, 0], { extrapolateRight: 'clamp' })
+  const progress = interpolate(frame, [0, Math.round(fps * 0.27)], [0, 1])
+  const slideY   = interpolate(frame, [0, Math.round(fps * 0.33)], [40, 0])
 
   return (
     <div style={{ position: 'absolute', bottom: 180, left: 48, right: 48, opacity: progress, transform: `translateY(${slideY}px)` }}>
@@ -215,7 +220,7 @@ The most reliable way to use frosted-glass / blurred card backgrounds is to **pu
 ```jsx
 // overlays/card-bg.jsx
 // Just a frosted card that fades in. No children that animate opacity.
-const opacity = interpolate(frame, [0, 8], [0, 1], { extrapolateRight: 'clamp' })
+const opacity = interpolate(frame, [0, Math.round(fps * 0.27)], [0, 1])
 
 export default function CardBg() {
   return (
@@ -270,19 +275,23 @@ background: 'rgba(10,10,10,0.88)'  // solid dark — visually similar, no GPU la
 Maps a frame number to any output value. Clamps at both ends by default.
 
 ```jsx
-// Fade in over frames 0–15
-const opacity = interpolate(frame, [0, 15], [0, 1])
-
-// Fade in then out
-const fadeIn  = interpolate(frame, [0, 15], [0, 1])
-const fadeOut = interpolate(frame, [duration - 15, duration], [1, 0])
+// Fade in over the first ~0.5s
+const holdIn = Math.round(fps * 0.5)
+const opacity = interpolate(frame, [0, holdIn], [0, 1])
+
+// Fade in then out, each over ~0.5s
+const holdOut = Math.round(fps * 0.5)
+const fadeIn  = interpolate(frame, [0, holdIn], [0, 1])
+const fadeOut = interpolate(frame, [duration - holdOut, duration], [1, 0])
 const opacity = Math.min(fadeIn, fadeOut)
 
-// Slide in from left
-const x = interpolate(frame, [0, 20], [-200, 0], { extrapolateRight: 'clamp' })
+// Slide in from left over ~0.67s
+const x = interpolate(frame, [0, Math.round(fps * 0.67)], [-200, 0])
 ```
 
-Options: `extrapolate`, `extrapolateLeft`, `extrapolateRight` — each `'clamp'` (default) or `'extend'`.
+One option: `extrapolate` — `'clamp'` (default) or `'extend'`. That is the whole options object; the runtime destructures `{ extrapolate = 'clamp' }` and ignores everything else. Earlier versions of this file used `extrapolateRight`, which does not exist and was silently dropped — harmless only because the default was already `'clamp'`.
+
+**`interpolate` is strictly linear** — `interpolate(5, [0,10], [0,1])` is exactly `0.5`. There is no easing parameter. For eased motion, ease the normalised value first: see **[MOTION.md](MOTION.md)** for the easing catalog, directional motion blur, per-character stagger, and the no-dead-air rule.
 
 ### `spring({ frame, fps, mass?, stiffness?, damping?, initialVelocity? })`
 
@@ -475,6 +484,35 @@ Three.js + r3f add ~250 KB to an overlay segment's bundle after esbuild tree-sha
 
 ---
 
+## 2D Canvas
+
+For plain 2D drawing HTML/CSS can't do — per-pixel effects, arbitrary paths, `drawImage` compositing — overlay JSX can drive a `CanvasRenderingContext2D` via `useCanvas2DFrame`. Unlike Three.js, this needs no library and behaves identically in preview and render — there's no internal render loop to disable.
+
+```jsx
+export default function CanvasExample() {
+  const draw = (ctx, { frame, fps, duration }) => {
+    ctx.fillStyle = '#EFE3CE'
+    ctx.fillRect(0, 0, 1080, 1080)
+
+    const x = interpolate(frame, [0, duration], [0, 1080 - 120])
+    ctx.fillStyle = '#3b82f6'
+    ctx.fillRect(x, 480, 120, 120)
+  }
+
+  const ref = useCanvas2DFrame(draw, frame, fps, duration)
+
+  return <canvas ref={ref} width={1080} height={1080} style={{ position: 'absolute', inset: 0 }} />
+}
+```
+
+**`useCanvas2DFrame(draw, frame, fps, duration)` — always pass `frame`/`fps`/`duration` explicitly**, the same as `interpolate`/`spring`. It returns a ref to attach to a `<canvas>` element; `draw(ctx, { frame, fps, duration })` runs synchronously every time that ref is attached, which happens on every frame.
+
+**Draw the complete frame from scratch every call** — same rule as everywhere else in overlay JSX: same `frame` in, same pixels out. Don't rely on anything painted by a previous call still being there (start with a fill/clear, as in the example above).
+
+**One `<canvas>` per `useCanvas2DFrame` call.** Each call returns its own ref; don't share one ref across multiple canvases or call the hook conditionally.
+
+---
+
 ## Charts / Recharts
 
 Overlay JSX can use SVG-based charts via [Recharts](https://recharts.org). Available globals: `BarChart`, `Bar`, `LineChart`, `Line`, `PieChart`, `Pie`, `Cell`, `XAxis`, `YAxis`, `CartesianGrid`, `Tooltip`, `Legend`, `ResponsiveContainer`.
@@ -565,7 +603,7 @@ Assets (logos, images) are declared in `project.assets`. Reference them by passi
 
 ```jsx
 // overlays/logo.jsx
-const opacity = interpolate(frame, [0, 6], [0, 1])
+const opacity = interpolate(frame, [0, Math.round(fps * 0.2)], [0, 1])
 
 export default function Logo() {
   return (