--- name: carousel description: "Agent-authored workflow task: build slides for a carousel project — pick aspect-aware images via generate_image, position image and overlay elements on each slide, set base colors, and render to PNGs. Load this when you hit montaj/carousel in a workflow." step: true subskills: "editable-text" --- # Carousel Skill Use this skill whenever you are working on a `carousel` workflow project in montaj. --- ## 1 — What a carousel is A carousel is N still slides at one fixed aspect ratio, rendered to `slide_01.png` … `slide_NN.png` in `/render/`. There is no time axis, no audio, no video export. | Aspect | Constant | Resolution | Platform | |--------|----------|------------|----------| | `square` | `CAROUSEL_ASPECTS[0]` | 1080 × 1080 | Instagram square | | `portrait` | `CAROUSEL_ASPECTS[1]` | 1080 × 1350 | Instagram portrait (dominant in 2026) | | `vertical` | `CAROUSEL_ASPECTS[2]` | 1080 × 1920 | TikTok photo mode, Stories | The aspect is **locked at project creation** — Instagram and TikTok enforce uniformity across all slides in a carousel. Read it from `project.carousel.aspect`; read pixel dimensions from `project.settings.resolution` (`[width, height]`). Never attempt to change the aspect after init. Reference: `/Users/Sam/Work/ByCrux/dev/montaj/lib/types/carousel.py` — `CAROUSEL_ASPECTS`, `CAROUSEL_RESOLUTIONS`. --- ## Sub-skills | Name | Path | When to load | |------|------|--------------| | `editable-text` | `skills/editable-text/SKILL.md` | Before authoring any text overlay — defines the 9-prop contract the editor toolbar relies on. | --- ## 2 — Inputs you have - `project.editingPrompt` — the user's natural-language instruction for the whole carousel (e.g. "5-slide skincare routine, clean aesthetic, soft pastels"). - `project.assets` — list of reference images the user attached at intake or in the editor: `[{ id, src, type, name }]`. `src` is an absolute path (the file lives inside the project workspace directory). Pass these as `--ref-image` to `generate_image` when style consistency matters, or use them directly as image-element `src` values on slides. --- ## 3 — Slide schema ```jsonc // project.slides: Slide[] { "id": "uuid", // crypto.randomUUID() — never positional IDs "base_color": "#ffffff", // background fill shown wherever no image covers "elements": [ // z-order: bottom → top // Image element { "id": "uuid", "type": "image", "src": "assets/.png", // workspace-relative path; required "mediaId": "", // optional metadata, references org Media row "x": 0, "y": 0, "w": 1080, "h": 1080, "rotation": 0 }, // Overlay element { "id": "uuid", "type": "overlay", "overlay": { "template": "", // path or name returned by GET /api/overlays "props": { // overlay-specific knobs (text, color, animation timing, etc.) // DO NOT set offsetX / offsetY / scale here — they are forced to // identity at render time. Slide-side x/y/w/h/rotation own position. } }, "frame": 59, // static frame to render; default = overlay's // staticFrame export, or duration - 1 "x": 140, "y": 200, "w": 800, "h": 300, "rotation": 0 } ] } ``` `src` is the workspace-relative path the renderer reads from disk. `mediaId` is optional metadata — when present, it lets Hub's editor surface the filename, link back to the Media library row, and reason about provenance. The renderer ignores `mediaId`. When working from Hub, never write a presigned URL into `src`. The materialization machinery puts a workspace path there; Hub returns the workspace path from `hub.attach_media`. Key rules: - Use `crypto.randomUUID()` for every `id` on slides and elements. - Element ordering in `elements[]` is z-order, bottom → top. Put full-bleed images at index 0. - A "background" image is just an image element sized to the slide at index 0. No special background type exists. - Text and shapes are overlays, not dedicated element types. - `frame` selects which frame of an overlay's animation gets statically rendered. Default: the overlay's declared `staticFrame`, or `duration - 1` (end of entrance animation) when `staticFrame` is absent. Reference: `/Users/Sam/Work/ByCrux/dev/montaj/montaj_assets/render/templates/slide.jsx` — the React component that receives and renders this shape. --- ## 4 — Generating images Use the existing `generate_image` step (`/Users/Sam/Work/ByCrux/dev/montaj/steps/generate/generate_image.json`). Always generate at the project's native resolution so the image fills the slide without scaling artifacts. ```bash montaj generate-image \ --prompt "soft pastel background, skincare product flat lay, minimalist" \ --out /assets/slide1_bg.png \ --provider gemini \ --aspect-ratio "4:5" # match the project aspect: square → 1:1, portrait → 4:5, vertical → 9:16 ``` CLI signature summary: | Param | Required | Notes | |-------|----------|-------| | `--prompt` | yes | Describe the image | | `--out` | yes | Absolute path, `.png` | | `--provider` | no | `gemini` (default) or `openai` | | `--ref-image` | no, repeatable | Reference images from `project.assets` for style consistency | | `--aspect-ratio` | no | Gemini only. `1:1`, `4:5`, `9:16` — match the carousel aspect | | `--model` | no | Override the connector's default model | After generation, store the file under the project workspace (e.g. `/assets/`) and set the element's `src` to the relative path from the workspace root (e.g. `"assets/slide1_bg.png"`). --- ## 5 — Overlays Carousel overlays are **custom JSX written per project** — there is no built-in template library. Author each overlay you need (headline, subhead, callout, etc.) per the rules below. - For **text overlays** that the operator should be able to restyle from the editor toolbar (font / size / color / weight / case / alignment), follow `skills/editable-text/SKILL.md`. The canonical reference is `montaj_assets/render/templates/overlays/static-text/static-text.jsx`. - For **charts (`bar-chart`, `line-chart`, `pie-chart`)** — single-series bar, multi-series line, pie/donut. SVG-rendered via Recharts. Sized from the overlay element's w/h. - For **non-text overlays** (logos, decorative shapes, image-based overlays, stylized brand marks), follow `skills/write-overlay/SKILL.md` as before. Save the JSX under the project workspace (e.g. `/overlays/headline.jsx`) and reference it by absolute path in `overlay.template`. Carousel-specific rules layered on top of `write-overlay`: - **Position belongs to the slide, not the overlay.** Do not set `offsetX`, `offsetY`, or `scale` in `overlay.props` — the slide-side `x/y/w/h/rotation` always win, and the renderer forces those three fields to identity at render time (see `slide.jsx`). - **Pick the static frame explicitly.** Carousels render a single still frame from the overlay's animation. If the JSX module exports `staticFrame`, use that value. Otherwise default to `duration - 1` (the settled pose after any entrance animation). Always store the resolved value explicitly in `project.json` — do not rely on defaults. Reference: `/Users/Sam/Work/ByCrux/dev/montaj/docs/plans/2026-05-04-image-carousel.md` — Decisions section ("Overlay-coordinate precedence", "Static rendering of frame-driven overlays"). ### Typography for carousels Carousels carry full sentences and paragraphs — the viewer is *reading*, not glancing past a video frame. **Do NOT apply `write-overlay`'s "Go large / 96px floor" rule.** That rule is calibrated for short hooks (3–6 words) on 1080×1920 video with moving footage; it produces unreadable wall-of-text on a 1080×1080 carousel. Use these defaults instead, sized to the carousel's `resolution[0]` (1080 for square/portrait, 1080 for vertical): | Role | Short copy (≤ 40 chars) | Medium (40–80) | Long (80+) | |------|-------------------------|----------------|------------| | Hook headline (slide 1) | 64–80px | 44–56px | 32–44px | | Body / answer text (FAQ, captions in cards) | 28–34px | 24–28px | 22–26px | | Eyebrows, kickers, all-caps labels | 18–26px | 18–22px | 18–22px | | Footer / sign-off | 26–32px | 22–26px | 20–24px | Rules of thumb: - **Measure your headline first.** Long headlines (the typical Idea title — 60–90 chars) need *small* type at carousel sizes, not big type. A 78px headline wrapping to 6+ lines is broken, not bold. - **Card-bound body text** (text inside a solid background card with padding) can run smaller — the card provides contrast, so 22–24px reads cleanly. Free-floating text on top of a base color needs more weight — 26–30px. - **Line height 1.1–1.25** for headlines, **1.35–1.5** for body. Tight lines compress headlines; loose lines breathe body. - **Letter-spacing** stays near `normal` for body, slightly negative (`-0.5px` to `-1.5px`) for large headlines, slightly positive (`2–6px`) for small all-caps labels. - **One accent color max** per slide. Inherit accent / primary / fg / cream from the brand palette via overlay props — don't hardcode hex values that drift from `hub.get_brand`. If a slide's text doesn't fit at these sizes, the copy is too long for that slide — split it, don't shrink past the lower bound. The viewer's eye still has to land. ### HTTP / sidecar mode In CLI / headless mode, you author overlays by writing JSX files directly to `/overlays/.jsx`. In HTTP / sidecar mode, you don't have filesystem access — use the dedicated write endpoint instead: ``` PUT /api/projects/{id}/overlays/{name} Content-Type: text/plain Body: ``` Names are slug-only (`a-z`, `A-Z`, `0-9`, `_`, `-`, up to 64 chars); the server appends `.jsx`. PUT is idempotent — re-PUTting the same name overwrites. The written file lands at `/overlays/{name}.jsx` and is referenceable from slide elements exactly as in CLI mode. --- ## 6 — Persisting slide edits `PUT /api/projects/{id}` with the entire project body. The server writes `project.json` and SSE-broadcasts the updated state. ```bash # Example via curl (agent-side calls go through api.saveProject in the UI, # or direct HTTP from a script) curl -s -X PUT http://localhost:/api/projects/ \ -H "Content-Type: application/json" \ -d @project.json ``` Every save is a whole-project PUT. If streaming live drag/resize updates, debounce at ~100 ms trailing to avoid one PUT per pointer-move frame. --- ## 7 — Authoring overlays alongside images When a slide combines an image element with an overlay element, the overlay's transparent root div sits ON TOP of the image (z-order, bottom→top). The image is visible only where the overlay doesn't paint. The default `hook` overlay's text container has no `max-width`, so a long headline can span the full slide and visually obscure an image element placed on the right. Two rules: 1. Overlays designed to potentially share a slide with images should accept a `textMaxWidth` prop (CSS value, default `'100%'`). The text container applies it as `maxWidth`. When the agent composes a slide with an image, pass `textMaxWidth: '60%'` (or similar) on the overlay's props. 2. Position image elements on the side opposite the overlay's text alignment. For `align: 'top'` overlays, place images bottom. For left-aligned overlays (the default for hook), place images on the right. Brand-shipped overlays (`hook`, `faq_card`) follow this pattern. Author new overlays with `textMaxWidth` from day one. --- ## 8 — Render Set `project.status` to `"final"` via `PUT /api/projects/{id}` before running render — the render command requires it. ```bash montaj render /project.json ``` Output: `/render/slide_01.png` … `slide_NN.png` plus a `manifest.json` describing the run. The renderer (`render-carousel.js`) launches Puppeteer, bundles each slide's JSX via esbuild, screenshots at the project resolution, and writes PNGs. No ffmpeg, no audio, no video encoding. Pass `--out ` to write PNGs elsewhere; pass `--clean` to delete only prior `slide_*.png` + `manifest.json` without touching any coexisting video renders. Reference: `/Users/Sam/Work/ByCrux/dev/montaj/montaj_assets/render/render-carousel.js`. --- ## 9 — Status lifecycle ``` pending → (build slides) → final → render ``` New carousel projects start at `status: "pending"` — same as video projects. The pending status signals that this carousel is waiting on you (the agent) to do the initial build. Build and populate all slides, then: 1. `PUT /api/projects/{id}` with `status: "final"` (and the complete `slides` array). 2. `montaj render /project.json` The project is complete when `render/slide_01.png` … `slide_NN.png` exist.