@bycrux/montaj-skills 0.1.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.1.0",
+  "version": "0.3.0",
   "private": false,
   "type": "module",
   "files": [

package/skills/image-search.md

@@ -44,6 +44,10 @@ Run step `fetch_image` with the following args. Downloads one HTTPS URL to a wor
 
 Output: `{ "path": "/abs/path/to/file.jpg" }`. Some hosts return `403` to non-browser fetches — if one fails, run step `fetch_image` with the next candidate instead of fighting it.
 
+> To register a fetched image into Hub Media (R2-backed, survives in the library), call
+> `hub.ingest_media({ projectId, items: [{ workspacePath: "<absolute fetch_image out path>" }] })`.
+> Do not hand-roll `create_media` + presigned PUT.
+
 ## Picking the right image
 
 Search returns more than you need. Before committing:

package/skills/overlay.md

@@ -64,22 +64,25 @@ See skill `write-overlay` for the full authoring reference.
 
 ### 5. Save overlays to the project
 
-Overlays live in `tracks[1+]` — overlay tracks in the unified tracks array. Each inner array is one track. Items in the same track cannot overlap in time; items in different tracks are z-ordered (higher indexes render on top). `tracks[0]` is always the primary footage track.
+Overlays live in `tracks[1+]` — overlay tracks in the unified tracks array. Each track is an object (`{id, items, ...}`); its `items` array holds the track's clips/overlays. Items in the same track cannot overlap in time; items in different tracks are z-ordered (higher indexes render on top). `tracks[0]` is always the primary footage track.
 
 ```json
 {
   "tracks": [
-    [],
-    [
-      {
-        "id": "ov-0",
-        "type": "overlay",
-        "src": "/abs/path/to/project/overlays/hook.jsx",
-        "props": { "text": "The source code got leaked" },
-        "start": 0.0,
-        "end": 3.0
-      }
-    ]
+    { "id": "trk-0", "items": [] },
+    {
+      "id": "trk-1",
+      "items": [
+        {
+          "id": "ov-0",
+          "type": "overlay",
+          "src": "/abs/path/to/project/overlays/hook.jsx",
+          "props": { "text": "The source code got leaked" },
+          "start": 0.0,
+          "end": 3.0
+        }
+      ]
+    }
   ]
 }
 ```
@@ -88,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.
@@ -100,6 +105,7 @@ Follow save discipline: **read the project**, merge the updated `tracks` array i
 - **Keep text short** — 2–6 words for lower-thirds, 4–8 for hooks. Short + large beats long + small
 - **Leave `offsetX`, `offsetY`, `scale` at defaults** (`0`, `0`, `1`) — the human positions overlays via the UI drag tool after preview
 - **Use assets from `project.assets`** — pass asset `src` paths as `props`, don't hardcode paths inside JSX
+- **Expose text styling as props** — a text overlay you want editable in the editor's properties panel must READ its font, size, weight, style, color, alignment, transform, and background from `props` (the nine standard text props) with sensible defaults, not hardcode them in the JSX. A hardcoded style shows no control in the panel. See skill `write-overlay` → "Make text overlays editable in the properties panel"
 
 ## Render Constraints
 

package/skills/select-takes.md

@@ -6,7 +6,7 @@ step: true
 
 # Select Takes
 
-`montaj/select_takes` is an agent-authored task — no CLI step, no API call. You reason across all clip transcripts and make editorial decisions. The output is a set of cropped trim specs ready for `rm_fillers` and `concat`.
+`montaj/select_takes` is an agent-authored task — no CLI step, no API call. You reason across all clip transcripts and make editorial decisions. The output is a set of cropped trim specs ready for `rm_fillers`. Nothing joins them into a file: the surviving keeps become `tracks[0]` items with their own `inPoint`/`outPoint`, and the render engine assembles them in one pass at the end.
 
 ## Core Purpose
 
@@ -82,11 +82,15 @@ For each flagged seam, fix it by trimming the crop window of whichever section i
 
 **This check is required before writing any spec files.** Seam problems cannot be caught by any automated step downstream.
 
-### 9. Crop the trim specs — do NOT call `trim`
+### 9. Crop the trim specs — never encode an intermediate
 
-For each selected take, load the trim spec JSON produced by the preceding `waveform_trim` step for that clip. Crop it to the selected take's virtual-timeline window using the `crop_spec` step.
+For each selected take, the trim spec JSON comes back **inline** (on stdout / in the step result) from the preceding `waveform_trim` step — it is NOT written to disk automatically. The `crop_spec` step requires an on-disk file (its `--input` argument). Before calling `crop_spec`, write the inline spec to the project scratch dir using the `write_file` tool (e.g. save it as `<clip>_spec.json`), then pass that path as `crop_spec`'s `input`.
 
-**Never call the `trim` step.** That encodes an intermediate video file and breaks the single-encode chain. Cropping the spec keeps the original source file all the way through to `concat`.
+Crop the written spec to the selected take's virtual-timeline window using the `crop_spec` step.
+
+**Never encode an intermediate video file here.** There is no `trim` step to call, and reaching for `materialize_cut` at this point would break the single-encode chain for no gain. Cropping the spec keeps `tracks[0].items[*].src` pointing at the original source all the way through to the final render, which is what lets the operator re-trim any cut later without losing quality — and what keeps each item's `proxySrc` valid, since a proxy covers the original file.
+
+**Note:** the `input` path in all `crop_spec` calls below must point to a spec file you've written to disk via `write_file` first (see above).
 
 Run step `crop_spec` with `{"input": "/path/IMG_4893_spec.json", "keeps": [[8.5, 34.1]]}` → returns `{"path": "/path/IMG_4893_spec_cropped.json"}` (single window).
 
@@ -116,7 +120,9 @@ Run step `virtual_to_original` with `{"input": "spec.json", "inverse": true, "ti
 
 ### 10. Output
 
-An ordered list of `_selected.json` trim spec paths — one per selected section, in narrative order. These become the inputs to `rm_fillers` and ultimately `concat`.
+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
 

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.
 
@@ -66,7 +69,7 @@ export default function List() {
 
 ## Writing the JSX
 
-> **Carousel text overlays follow a stricter contract.** For carousel projects, every text-bearing overlay must accept its font size, family, weight, style, color, alignment, transform, and background as props with string defaults — see skill `editable-text`. The "go large — for video" guidance below, and the hardcoded-style style of the `Hook` example, **do not apply** to carousel editable-text overlays.
+> **Expose text styling as props to make an overlay editable.** A text overlay is only restyleable in the editor's properties panel for the props it declares — see "Make text overlays editable in the properties panel" below, which applies to video overlays too. **Carousel text overlays follow a stricter, required version of that contract:** every text-bearing overlay must accept its font size, family, weight, style, color, alignment, transform, and background as props with string defaults — see skill `editable-text`. The "go large — for video" guidance below, and the hardcoded-style `Hook` example just under it, **do not apply** to carousel editable-text overlays.
 
 The default aesthetic is **plain bold text directly on video** — no card, no background, just a text shadow for legibility. Big text (96–160px) that covers the footage, including the speaker's face if needed.
 
@@ -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={{
@@ -111,6 +114,58 @@ Only add a card or background when the prompt explicitly asks, or when a specifi
 
 ---
 
+## Make text overlays editable in the properties panel
+
+The editor's right-hand properties panel (and the floating text toolbar) can restyle a text overlay **only for the props it actually declares**. It reads the nine standard text props off the item's `props` object:
+
+`text`, `fontSize`, `fontFamily`, `fontWeight`, `fontStyle`, `color`, `textAlign`, `textTransform`, `bgColor`
+
+A control appears for each of those that is present (non-null) on `props`; anything the overlay **hardcodes** in its JSX style instead of reading from `props` shows **no control at all**, and the operator can't change it. This is exactly why an overlay that writes `textTransform: 'uppercase'` straight into its style has no text-transform control in the editor.
+
+**So a text overlay you want a human to be able to restyle must READ its text styling from `props`, with sensible defaults — not hardcode it.** Same house style (big, bold, plain on video), just sourced from props:
+
+```jsx
+// Editable Hook — every text property is adjustable in the panel.
+export default function Hook() {
+  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)` }}>
+      <div style={{
+        fontFamily: props.fontFamily ?? 'Anton, Impact, sans-serif',
+        fontSize: props.fontSize ?? 120,
+        fontWeight: props.fontWeight ?? 900,
+        fontStyle: props.fontStyle ?? 'normal',
+        color: props.color ?? '#fff',
+        textAlign: props.textAlign ?? 'left',
+        textTransform: props.textTransform ?? 'uppercase',
+        background: props.bgColor ?? 'transparent',
+        lineHeight: 1.05, letterSpacing: '-1px',
+        textShadow: '0 2px 24px rgba(0,0,0,0.9), 0 0 60px rgba(0,0,0,0.5)',
+      }}>
+        {props.text}
+      </div>
+    </div>
+  )
+}
+```
+
+Declare those same values in the item's `props` too, so the panel opens on the real values rather than blank controls:
+
+```json
+"props": {
+  "text": "She built an AI employee",
+  "fontSize": 120, "fontFamily": "Anton, Impact, sans-serif",
+  "fontWeight": 900, "fontStyle": "normal", "color": "#ffffff",
+  "textAlign": "left", "textTransform": "uppercase", "bgColor": "transparent"
+}
+```
+
+This now applies to **video** text overlays, not just carousel slides — the video editor has the same properties panel. For the full contract (types and validation) see skill `editable-text`. A non-text overlay (logo, image card, chart) has no text props to expose; the same principle still holds for whatever a human would want to tweak — pass it through `props`, don't bury it in the JSX.
+
+---
+
 ## Splitting background from content across tracks
 
 The most reliable way to use frosted-glass / blurred card backgrounds is to **put the background on a separate, lower track** and the animated content on a higher track. The render pipeline composites tracks in order, so the content renders on top.
@@ -129,25 +184,31 @@ The most reliable way to use frosted-glass / blurred card backgrounds is to **pu
 ```json
 {
   "tracks": [
-    [],
-    [
-      {
-        "id": "ov-card-bg",
-        "type": "overlay",
-        "src": "/path/overlays/card-bg.jsx",
-        "start": 2.0,
-        "end": 6.0
-      }
-    ],
-    [
-      {
-        "id": "ov-card-content",
-        "type": "overlay",
-        "src": "/path/overlays/card-content.jsx",
-        "start": 2.0,
-        "end": 6.0
-      }
-    ]
+    { "id": "trk-0", "items": [] },
+    {
+      "id": "trk-1",
+      "items": [
+        {
+          "id": "ov-card-bg",
+          "type": "overlay",
+          "src": "/path/overlays/card-bg.jsx",
+          "start": 2.0,
+          "end": 6.0
+        }
+      ]
+    },
+    {
+      "id": "trk-2",
+      "items": [
+        {
+          "id": "ov-card-content",
+          "type": "overlay",
+          "src": "/path/overlays/card-content.jsx",
+          "start": 2.0,
+          "end": 6.0
+        }
+      ]
+    }
   ]
 }
 ```
@@ -157,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 (
@@ -221,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? })`
 
@@ -417,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`.
@@ -446,29 +538,32 @@ Place overlay items in `tracks[1+]` in `project.json`. Each item must have `type
 ```json
 {
   "tracks": [
-    [],
-    [
-      {
-        "id": "ov-hook",
-        "type": "overlay",
-        "src": "/abs/path/to/project/overlays/hook.jsx",
-        "start": 0.0,
-        "end": 3.0,
-        "props": {
-          "text": "She built an AI employee"
+    { "id": "trk-0", "items": [] },
+    {
+      "id": "trk-1",
+      "items": [
+        {
+          "id": "ov-hook",
+          "type": "overlay",
+          "src": "/abs/path/to/project/overlays/hook.jsx",
+          "start": 0.0,
+          "end": 3.0,
+          "props": {
+            "text": "She built an AI employee"
+          }
+        },
+        {
+          "id": "ov-logo",
+          "type": "overlay",
+          "src": "/abs/path/to/project/overlays/logo.jsx",
+          "start": 0.0,
+          "end": 999.0,
+          "props": {
+            "logoSrc": "/abs/path/to/project/assets/logo.png"
+          }
         }
-      },
-      {
-        "id": "ov-logo",
-        "type": "overlay",
-        "src": "/abs/path/to/project/overlays/logo.jsx",
-        "start": 0.0,
-        "end": 999.0,
-        "props": {
-          "logoSrc": "/abs/path/to/project/assets/logo.png"
-        }
-      }
-    ]
+      ]
+    }
   ]
 }
 ```
@@ -576,7 +671,12 @@ Common overlay set for a social reel:
 
 **Write all of your overlay JSX first. Then sample them in a single batch pass — do not sample after each file.** Per-file sampling stalls authoring and spins up a fresh Puppeteer process each time; one pass at the end over the finished set is faster and just as safe, since nothing downstream consumes an overlay until you save the project with the whole batch.
 
-Once every JSX file is written, loop over them in one pass — for each JSX file, **run step `sample_overlay`** with args `{ path, measure: true, googleFonts, props }`:
+Once every JSX file is written, loop over them in one pass — for each JSX file, **run step `sample_overlay`** with args `{ overlay, out, measure: true, google_fonts, props }`:
+
+- `overlay` — absolute path to the JSX file
+- `out` — absolute path where the step writes the sample PNG (required)
+- `google_fonts` — the overlay's declared `googleFonts` value (snake_case step arg)
+- `props` — representative props for the overlay
 
 Pass each overlay's declared `googleFonts` (and representative `props`) so the step measures with the real render-time font — see the Syne case study below.