@shotstack/cli 0.13.0 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shotstack/cli",
-  "version": "0.13.0",
+  "version": "0.15.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

@@ -15,9 +15,9 @@ This skill loads in **terminal-based AI agents** (Claude Code, Cursor, Codex CLI
 
 ## Check versions once per session
 
-This skill is version **0.13.0** and needs `@shotstack/cli` **0.13.0** or later. Before the first `shotstack` command in a session:
+This skill is version **0.15.0** and needs `@shotstack/cli` **0.15.0** or later. Before the first `shotstack` command in a session:
 
-1. Run `shotstack --version`. If it is older than 0.13.0, tell the user: what this skill documents, such as `analyze`, is missing until they run `npm install -g @shotstack/cli@latest`.
+1. Run `shotstack --version`. If it is older than 0.15.0, tell the user: what this skill documents, such as the html5 size steps from `ingest upload --watch`, is missing until they run `npm install -g @shotstack/cli@latest`.
 2. Run `npm view @shotstack/cli version`. If it is newer than this skill's version, tell the user an update is available and ask whether to install it. Only on a yes, run `npx skills update shotstack -y` and `npm install -g @shotstack/cli@latest`. Never update without asking. `npx skills check` is not a read-only check: it installs the update.
 
 If a check fails (no network, no npm, a sandbox), skip it and carry on.
@@ -90,6 +90,8 @@ SRC=$(shotstack ingest upload ./clip.mp4 --watch --output json | tail -n1 | jq -
 # …then reference "$SRC" as an asset.src in your Edit JSON and run `shotstack render`.
 ```
 
+This includes images and fonts for an `html5` page: put the URL in its `html` or `css`.
+
 The bare command (no `--watch`) returns only an `id`; the hosted `source` URL does not exist until ingestion is `ready`. Always `--watch` (or follow up with `shotstack ingest status <id> --watch`) when you need the URL.
 
 Other ingest subcommands: `ingest fetch <url>` (host a copy of a remote URL), `ingest status <id>`, `ingest list`, `ingest delete <id>`. **Read [`references/ingest.md`](references/ingest.md) for the full upload→render workflow, status values, and supported file types.**

package/skills/shotstack/references/beat-sync.md

@@ -18,8 +18,10 @@ Host a local file with `shotstack ingest upload <file> --watch`. Generate a trac
 
 Analysis is free, takes 15–30 s and reads the first 10 minutes of the track.
 
-It needs an API key (`shotstack login`). The `src` must be a direct, public link to an audio or video file: share pages and redirects are refused.
+The `src` must be a direct, public link to an audio or video file: share pages and redirects are refused.
 <!-- surface:cli -->
+It needs an API key (`shotstack login`).
+
 ```sh
 shotstack analyze https://shotstack-assets.s3.amazonaws.com/music/unminus/lit.mp3 --output json > map.json
 ```

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

@@ -102,7 +102,7 @@ What you can build inside one `html5` clip, listed by the effect you'd reach for
 - **WebGL, shaders, 3D models:** use CSS 2.5D and SVG filters.
 - **Video or audio inside the clip:** put footage and sound on other timeline tracks; `html5` is the graphics layer.
 - **Scroll, drag or pointer-driven animation:** capture is time-driven only.
-- **Remote fonts, images, scripts:** inline them as `data:` URIs.
+- **Remote scripts, and images or fonts you haven't ingested:** inline them as `data:` URIs. Images and fonts you ingested work by URL; see [`html5.md`](html5.md).
 
 ## Cost
 

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

@@ -16,8 +16,8 @@ Read [`html5.md`](html5.md) for the rules these obey. The non-negotiables:
 - **Size the clip to the content, not the canvas.** `html, body` pinned to the clip's `width`/`height`; place with `offset` (`{x:0,y:0}` is centred, `y` positive is up). Use **px**, never `vw`/`vh`/`%`.
 - **The body is transparent by default** — the clip composites over the layers below (only set an opaque background if you want one).
 - **Canvas only from the seek hook.** Draw canvas 2D inside `window.__shotstackSeek(ms)`, never in a `requestAnimationFrame` loop. WebGL is blank in the cloud render. SVG or positioned DOM is usually lighter.
-- **No network.** gsap (with its plugins), anime, d3 and 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`.
+- **No network.** gsap (with its plugins), anime, d3 and lottie are preloaded; external `<script src>`, `fetch`, remote `<img>`, and remote fonts are all CSP-blocked. Inline them as `data:` URIs, or use the URL of an image or font you ingested (see [`html5.md`](html5.md)).
+- **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 load the font, from an ingested font's URL or 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.
@@ -48,7 +48,7 @@ The reference entrance: opacity, blur and a 16 px rise settle **together** off o
 }
 ```
 
-`base` (0.6 s) entrance on `power3.out`, then a `hold` (1.5 s) settle. Swap `{{title}}` via top-level `merge[]`. `Clash Display` falls back to `system-ui` unless you inline it as a `data:` `@font-face` (see Fonts above).
+`base` (0.6 s) entrance on `power3.out`, then a `hold` (1.5 s) settle. Swap `{{title}}` via top-level `merge[]`. `Clash Display` falls back to `system-ui` unless you load it, from an ingested font's URL or a `data:` `@font-face` (see Fonts above).
 
 ---
 

package/skills/shotstack/references/html5.md

@@ -11,7 +11,7 @@ This is the **modern replacement for the deprecated `html` asset.** `html5` runs
 - Required and optional fields
 - Preloaded libraries
 - The browser harness (deterministic auto-seek)
-- Sandbox restrictions: no network, inline everything (incl. fonts)
+- Sandbox restrictions: no network; ingested images and fonts by URL, everything else inline
 - Sizing
 - 3D: what renders in preview and render
 - Worked example: animated lower-third (GSAP)
@@ -89,25 +89,59 @@ Frames are captured by **seeking** the animation to each timestamp, not by playi
 
 **Duration comes from the clip's `length`** — there's no animation-duration auto-detection. Size your animation to run within (or fill) the clip's `length`.
 
-## Sandbox restrictions: no network, inline everything
+## Sandbox restrictions: no network, ingested files by URL
 
 The iframe renders under a strict Content-Security-Policy (`default-src 'none'`), in both Studio preview and cloud render. Nothing is fetched from the network at render time:
 
 - **No external `<script src=>`.** Only the bundled GSAP/anime.js/D3/Lottie run (they're inlined for you). Another library would have to be inlined into your `js` — and must be seekable.
 - **No `fetch` / `XMLHttpRequest`** (`connect-src 'none'`). Bundle any data inline — e.g. the JS array in the bar-chart example.
-- **No remote images** (`img-src 'self' data: blob:`). Embed images as `data:` URIs. A `data:image/svg+xml` background is fine.
-- **No remote fonts** (`font-src 'self' data:`) — see below.
+- **No remote images** (`img-src 'self' data: blob:`), except images you ingested (below). Otherwise embed images as `data:` URIs. A `data:image/svg+xml` background is fine.
+- **No remote fonts** (`font-src 'self' data:`), except fonts you ingested (below). See *Fonts in HTML5*.
+
+### Images and fonts you ingested
+
+Reference an ingested image or font by its `source` URL, straight from `html` or `css`: an `<img src>`, a CSS `url()` or an `@font-face` `src`. Before capture the renderer fetches each file and inlines it, so the page itself still makes no request.
+
+<!-- surface:cli -->
+Upload with `shotstack ingest upload`, or host a copy of a URL with `shotstack ingest fetch`:
+
+```sh
+PHOTO=$(shotstack ingest upload ./hero.jpg --watch --output json | tail -n1 | jq -r .source)
+FONT=$(shotstack ingest upload ./Brand.woff2 --watch --output json | tail -n1 | jq -r .source)
+```
+<!-- /surface -->
+
+```css
+@font-face { font-family: 'Brand'; src: url(<FONT>) format('woff2'); }
+.hero { background: url(<PHOTO>) center / cover; }
+```
+
+- **Same account and environment only.** A file ingested on `stage` works in `stage` renders, not in `v1`, and another account's files are refused. Every other remote URL is still blocked.
+- **10 MiB per file, 25 MiB per page.** A file counts once for every place the page references it, so reference a large image once (a CSS class, say) and reuse the class.
+- **Size images to the clip.** A photo much larger than the clip makes a heavier page and a slower capture. If the source has a WebP rendition named `html5-512`, `html5-1024`, `html5-2048` or `html5-4096`, the renderer uses the smallest one that covers the clip's longest edge; otherwise it uses the original.
+<!-- surface:cli -->
+- `shotstack ingest upload --watch` and `ingest fetch --watch` request those renditions for an image and wait up to 60 s for them, so the `source` URL is all the page needs.
+<!-- /surface -->
+- **A file that can't be used fails the render**, for example one that's missing, too large, or not an image or font.
+- **Studio's preview doesn't load ingested files yet**, so they show as missing there. The render is unaffected.
+<!-- surface:cli -->
+- Until Studio supports them, check the page with `shotstack render <file> --env stage --watch`.
+<!-- /surface -->
 
 ### Fonts in HTML5
 
-`timeline.fonts[]` does **not** apply to `html5` assets (it loads fonts for `rich-text` / `rich-caption` only), and a remote `@font-face` URL (Google Fonts, etc.) is CSP-blocked. Two ways to get a custom font into an `html5` clip:
+`timeline.fonts[]` does **not** apply to `html5` assets (it loads fonts for `rich-text` / `rich-caption` only), and a remote `@font-face` URL (Google Fonts, etc.) is CSP-blocked. Three ways to get a custom font into an `html5` clip:
 
-1. **Inline it as a `data:` `@font-face`** — base64-encode the `.woff2` / `.ttf`:
+1. **Ingest it and use its URL** (see *Images and fonts you ingested*).
+   <!-- surface:cli -->
+   For a Google Font, `shotstack ingest fetch` the font file's `fonts.gstatic.com` URL and use the hosted copy.
+   <!-- /surface -->
+2. **Inline it as a `data:` `@font-face`** — base64-encode the `.woff2` / `.ttf`:
    ```css
    @font-face { font-family: 'Brand'; src: url('data:font/woff2;base64,<…>') format('woff2'); }
    .title { font-family: 'Brand', sans-serif; }
    ```
-2. **Use a system family** (`system-ui`, `Arial`, `Georgia`, …) — resolves with no load, but each machine picks its own font, so text in Studio's preview won't match the cloud render exactly. Embed a font whenever the text must match.
+3. **Use a system family** (`system-ui`, `Arial`, `Georgia`, …) — resolves with no load, but each machine picks its own font, so text in Studio's preview won't match the cloud render exactly. Embed a font whenever the text must match.
 
 An unresolved family silently falls back to the browser default — the render won't fail, but the text won't be your font. For a single styled line, a `rich-text` asset (which *does* use `timeline.fonts[]`; verified catalogue in `shared/agent-core.md`) is simpler than a `data:` font embed.
 

package/skills/shotstack/references/ingest.md

@@ -78,6 +78,18 @@ shotstack studio edit.json
 Remember `tracks[0]` is the **top** layer (see `shared/agent-core.md`), so the
 logo track sits above the video.
 
+## Images and fonts in an html5 page
+
+An `html5` page can use images and fonts you ingested by putting their
+`source` URLs in its `html` or `css` (`<img src>`, CSS `url()`, `@font-face`).
+The file must belong to the same account and environment as the render. Limits
+and details are in [`html5.md`](html5.md).
+
+With `--watch`, an image upload or fetch also requests smaller WebP copies
+(`html5-512` up to `html5-4096`, only those smaller than the image) and waits
+up to 60 s for them. They're listed under `outputs.renditions`; the renderer
+picks one for the clip size, so keep using the `source` URL.
+
 ## Fetch a remote URL instead of uploading
 
 If the media is already at a URL but you want Shotstack to host its own copy

package/skills/shotstack/shared/agent-core.md

@@ -168,8 +168,9 @@ Pick `output.resolution` (preset) OR `output.size.width`+`output.size.height` (c
 | `sd` | 1024×576 @ 25 |
 | `hd` | 1280×720 @ 25 (default) |
 | `1080` | 1920×1080 @ 25 |
+| `4k` | 3840×2160 @ 25 (Pro, Scale and Volume plans) |
 
-Custom sizes must be divisible by 2.
+Custom sizes must be divisible by 2, up to 3840px on each side (1920px for `gif`). Video can be up to 3840×2160 pixels in any shape, for example 2160×3840 for vertical 4K; larger sizes are rejected. Video above 1920×1080 pixels needs a plan that includes 4K.
 
 ## Merge fields
 
@@ -231,7 +232,7 @@ Use only the **current** asset types; the deprecated ones still parse but should
 | `audio` | Audio clip placed at a specific time on the timeline, or AI-generated speech or music from a `prompt`. |
 | `rich-text` | Styled text overlay with full typography control. **Use this instead of `text`/`html`/`title`.** |
 | `svg` | Vector graphics from raw SVG markup: `src` starts with `<svg`, never a URL or `data:` URI (the render fails). See **`svg` assets** below. |
-| `html5` | Self-contained HTML/CSS/JS page rendered in an iframe (motion graphics, charts, animated overlays). Preloads gsap with its plugins (SplitText, DrawSVG, MorphSVG, MotionPath, Flip and more), d3, anime and lottie. See `references/html5.md`. **Never use the deprecated `html` asset.** |
+| `html5` | Self-contained HTML/CSS/JS page rendered in an iframe (motion graphics, charts, animated overlays). Preloads gsap with its plugins (SplitText, DrawSVG, MorphSVG, MotionPath, Flip and more), d3, anime and lottie. Images and fonts: the URL of a file you ingested, or a `data:` URI; other remote URLs are blocked. See `references/html5.md`. **Never use the deprecated `html` asset.** |
 | `rich-caption` | Word-level animated captions sourced from audio, video, or subtitle files. See `references/caption.md`. |
 | `luma` | Luma matte for masking effects. |