@shotstack/cli 0.7.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shotstack/cli",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Command-line interface for the Shotstack video rendering API.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/shotstack/shotstack-cli",

package/skills/shotstack/SKILL.md

@@ -13,7 +13,9 @@ license: Apache-2.0
 
 This skill loads in **terminal-based AI agents** (Claude Code, Cursor, Codex CLI, Gemini CLI, etc.). All operations here are shell commands. There is no embedded UI, no iframe, no inline canvas, no MCP tool surface — only `shotstack` invocations from a terminal. To hand off to a human, run `shotstack studio <file>`; this opens the user's default browser to a `shotstack.studio` URL. Tell the user to click Render *in the browser tab*, not in any UI inside the terminal.
 
-Commands for the Shotstack video rendering API. `render` submits an Edit JSON and returns a render ID; `status` polls a render until done. `ingest` uploads your own local files (or fetches remote URLs) and hosts them so they can be referenced from an Edit. `validate` lints an Edit — run it before every render. `studio` opens an edit in the browser editor for a human to preview, tweak, and render.
+**Open-ended first render? Ask before composing.** If the ask doesn't state what the video is (subject, format or destination) — e.g. "render my first video", "make me a video", "set up Shotstack" — read [`references/onboarding.md`](references/onboarding.md) and ask its discovery questions, then WAIT for answers. Do not write an Edit first. An open-ended ask is not a specification, and a stray JSON file in the project doesn't make the user experienced. Compose without asking only when the user has stated what the video is, or explicitly says to just show anything.
+
+Commands for the Shotstack video rendering API. `render` submits an Edit JSON and returns a render ID; `status` polls a render until done. `ingest` uploads your own local files (or fetches remote URLs) and hosts them so they can be referenced from an Edit. `validate` lints an Edit — run it before every render. `studio` opens an edit in the browser editor for a human to preview, tweak, and render. `template list|get|create|update|delete` reads and writes templates saved to the account: `list` shows saved templates (id + name); `get <id>` fetches a saved template's Edit JSON (e.g. one the user designed in Studio) so you can render or remix it; `create <file> --name <name>` saves an edit as a new template; `update <id> <file>` overwrites one; `delete <id>` removes one.
 
 **Default loop — no API key required:** compose → `validate` (offline lint) → `studio` (browser preview). Only the API-backed commands (`render`, `status`, `ingest`) need a key. Reach for `render` when you specifically need a final MP4 exported in the cloud; reach for `studio` for everything else — it is the cheapest way to see an edit and the right default for any creative a human will review.
 
@@ -151,6 +153,7 @@ Authoritative sources, in order of preference:
 
 This skill ships sub-references for the gnarly bits:
 
+- [`references/onboarding.md`](references/onboarding.md) — first-render discovery interview for new users: what to ask, and how answers map to a first Edit
 - [`references/ingest.md`](references/ingest.md) — uploading local files (and fetching URLs) so they can be used in an Edit: the upload→render workflow, `--watch`, status values, supported types
 - [`references/timeline.md`](references/timeline.md) — track layering, transitions, background music via audio assets
 - [`references/positioning.md`](references/positioning.md) — coordinate model, `position`/`offset` (fraction of frame, +y up), clip bounding box & `fit`, text sizing, transform order

package/skills/shotstack/references/html5-snippets.md

@@ -21,6 +21,7 @@ Read [`html5.md`](html5.md) for the rules these obey. The non-negotiables:
 - **No `<canvas>`** — Studio capture serialises the DOM; canvas bitmaps come through empty. Use SVG or positioned DOM.
 - **No network.** gsap/anime/d3/lottie are preloaded; external `<script src>`, `fetch`, remote `<img>`, and remote fonts are all CSP-blocked — inline everything as `data:` URIs.
 - **Fonts:** `timeline.fonts[]` does **not** reach `html5` and remote `@font-face` is blocked. These snippets name a display font first but render in the `system-ui` fallback unless you inline the font as a `data:` `@font-face`.
+- **Use unique element IDs for GSAP targets, not `:nth-child` or compound CSS selectors.** Studio preview doesn't resolve `.parent:nth-child(n) .child` patterns; `#id` works everywhere. When animating repeated elements (list rows, bars, cards), generate a unique ID per item (`id="row0"`, `id="bar0"`) rather than relying on structural selectors.
 
 Coordinates below assume a **1080×1920 vertical** canvas; adjust `offset` for other sizes.
 

package/skills/shotstack/references/onboarding.md

@@ -0,0 +1,71 @@
+# First render: discovery interview
+
+**The gate: do not compose an Edit until the user has answered the questions
+below (or explicitly said "just show me anything").** Setting up the CLI and
+key can proceed; writing the video cannot.
+
+"Render my first video" is not a specification. It says nothing about the
+subject, the content, the format or where the video will go. Neither does
+"set up Shotstack". If any of those are unstated, ask. A first video is only
+useful when it matches what the user is actually trying to make, and a short
+interview gets there faster than guessing.
+
+Skip the interview only when the user has stated what the video is (e.g.
+"make a 9:16 promo from the images in ./assets with the tagline X"), or has
+declined to answer.
+
+## The interview
+
+Ask conversationally, batched into one or two messages, and wait for the
+reply. Skip any question the project already answers (e.g. a Next.js
+e-commerce app full of product images answers question 2).
+
+1. **What should the video do?** Social clips, product or listing videos,
+   personalised outreach, in-app content, something else? Listen for the job,
+   not the feature.
+2. **What content or data exists?** Images, footage, audio or brand assets in
+   the project or at URLs; structured data (CSV, JSON, database, CMS) that
+   could drive repeated or personalised videos.
+3. **Where will the videos go?** Destination decides format: 9:16 for
+   TikTok/Reels/Shorts, 1:1 or 4:5 for feeds, 16:9 for YouTube/web. When in
+   doubt for social, default to 1080x1920 (9:16).
+4. **One video or many?** Both make fine first renders, but the composition
+   differs: pipelines should use merge fields from the start.
+
+## From answers to a first render
+
+- Compose ONE Edit JSON that answers the four questions. Make it something
+  worth keeping, not a minimal demo.
+- Use the user's real assets when they exist (host local files first:
+  `shotstack ingest upload <file> --watch`, then reference the returned URL).
+  If nothing is to hand, build from the Shotstack asset library
+  (`references/asset-library.md`) and motion-graphic snippets
+  (`references/html5-snippets.md`), matched to their stated use case.
+- Use their brand where it exists: colours, fonts and logos from the project
+  or their site rather than an invented look. Follow the house motion
+  language (`references/motion.md`).
+- If they chose "many": add merge fields (`{{ placeholder }}`) for the parts
+  that vary per video, and show one render with sample values.
+- Loop: compose, then `shotstack validate`, then `shotstack render edit.json
+  --env stage --watch`.
+
+## Wrapping up
+
+- Give two links, always: the rendered MP4 and a Studio link (`shotstack
+  studio <file> --no-open`, include the printed shotstack.studio URL). The
+  Studio link lets the user tweak the design in the browser without touching
+  JSON; say so.
+- Describe what they have in plain terms: a reusable template, free stage
+  renders, the same JSON in production via `--env v1`, merge fields for the
+  parts that vary. Don't surface validator warnings or internal caveats
+  unless something is actually broken.
+- End by offering to take the next step towards what they said in the
+  interview, concretely, not a generic list. They wanted a data-driven
+  pipeline: offer to wire the template to their data source and render a
+  batch now. They mentioned their own footage: offer to upload it and swap it
+  in. One sharp offer beats five open-ended suggestions.
+
+## Tone
+
+Brisk, concrete and curious about the user's project. Batch questions, don't
+drip-feed. One good clarifying question beats three generic ones.

package/skills/shotstack/references/troubleshooting.md

@@ -13,6 +13,7 @@ Common errors and the fix for each. **Catch most of them before rendering:** `sh
 - Timeline renders but layers are wrong
 - "Invalid asset URL"
 - html5 clip is blank but render succeeded
+- html5 clip animates in the rendered MP4 but not in Studio preview
 - "Render failed" with no other detail
 - Render takes much longer than expected
 - Credits exhausted on stage environment
@@ -95,6 +96,17 @@ Two causes:
 
 A third variant: values stuck at `$0` or their initial state. This happens when `onUpdate` callbacks are used to mutate `textContent` — the seek harness doesn't fire `onUpdate`, so the DOM never updates. Bake final values into the HTML and animate opacity/transform instead. See `references/html5.md` → "The browser harness".
 
+## html5 clip animates in the rendered MP4 but not in Studio preview
+
+Studio preview and the cloud render use different capture mechanisms. The cloud render (puppeteer) properly handles all GSAP properties; Studio's client-side preview does not. This is a parity gap, not a render bug — the MP4 is the ground truth.
+
+Known differences:
+
+- **`:nth-child` and compound CSS selectors** as GSAP targets don't resolve in Studio preview. `.brow:nth-child(1) .bar` silently matches nothing; rows and bars stay in their initial state. Use unique element IDs (`#row0`, `#bar0`) instead — they work in both.
+- **`scale` / `scaleX` / `scaleY` transforms** don't animate in Studio preview. Elements starting at `scale(0)` or `scaleX(0)` stay invisible. Use `width` (for bars), `opacity`, or `y` transitions instead.
+
+If a clip looks wrong in Studio but the rendered MP4 is correct, don't waste credits re-rendering — check whether the JS uses structural selectors or scale transforms, and swap for ID-based targets and width/opacity animations.
+
 ## "Render failed" with no other detail
 
 `shotstack status <id> --output json` returns the full response including the error message. The `--watch` text view truncates.