@bycrux/montaj-skills 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bycrux/montaj-skills",
-  "version": "0.1.0",
+  "version": "0.2.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
+        }
+      ]
+    }
   ]
 }
 ```
@@ -100,6 +103,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,7 @@ 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.
 
 ## What to Log
 

package/skills/write-overlay.md

@@ -66,7 +66,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.
 
@@ -111,6 +111,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], { extrapolateRight: 'clamp' })
+  const slideY   = interpolate(frame, [0, 10], [40, 0], { extrapolateRight: 'clamp' })
+
+  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 +181,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
+        }
+      ]
+    }
   ]
 }
 ```
@@ -446,29 +504,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 +637,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.