@bycrux/montaj-skills 0.2.0 → 0.3.0

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.0",
   "private": false,
   "type": "module",
   "files": [

package/skills/overlay.md

@@ -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,6 +30,7 @@ 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.
 
@@ -74,8 +77,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, 8], [0, 1])
+  const slideY   = interpolate(frame, [0, 10], [40, 0])
 
   return (
     <div style={{
@@ -124,8 +127,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, 8], [0, 1])
+  const slideY   = interpolate(frame, [0, 10], [40, 0])
 
   return (
     <div style={{ position: 'absolute', bottom: 180, left: 48, right: 48, opacity: progress, transform: `translateY(${slideY}px)` }}>
@@ -215,7 +218,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, 8], [0, 1])
 
 export default function CardBg() {
   return (
@@ -279,10 +282,12 @@ const fadeOut = interpolate(frame, [duration - 15, duration], [1, 0])
 const opacity = Math.min(fadeIn, fadeOut)
 
 // Slide in from left
-const x = interpolate(frame, [0, 20], [-200, 0], { extrapolateRight: 'clamp' })
+const x = interpolate(frame, [0, 20], [-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 +480,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`.