@shotstack/cli 0.8.3 → 0.8.4

package/package.json

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

package/skills/shotstack/references/fonts.md

@@ -32,7 +32,11 @@ Load a font from a public URL via `timeline.fonts[]`, then reference its **file
 }
 ```
 
-The `font.family` value is the URL's filename without extension, and it **must** match the URL's basename exactly. For URL `https://fonts.gstatic.com/s/montserrat/v31/JTUSjIg1_i6t8kCHKm45xW5rygbi49c.ttf`, family = `JTUSjIg1_i6t8kCHKm45xW5rygbi49c`. If `family` and the URL basename diverge, the font silently fails to load.
+The `font.family` value is the URL's filename without extension, matched ignoring case (a `-Regular` or `-Bold` style suffix can also be dropped). For URL `https://fonts.gstatic.com/s/montserrat/v31/JTUSjIg1_i6t8kCHKm45xW5rygbi49c.ttf`, family = `JTUSjIg1_i6t8kCHKm45xW5rygbi49c`.
+
+The family name stored inside the font file also matches, but it isn't always the name on Google Fonts: a variable font whose default weight isn't Regular stores the weight too (Space Grotesk's file calls itself `Space Grotesk Light`). Prefer the filename, which can't differ from what you loaded.
+
+A `font.family` that matches nothing renders in Roboto without a render error. The exception is a lone entry in `timeline.fonts[]`, which is used whatever `font.family` says, so a wrong name stays hidden until a second font is added. `shotstack validate` warns on any `font.family` that isn't a built-in or a loaded filename.
 
 ## Verified font catalogue
 
@@ -77,9 +81,9 @@ These twelve fonts are pre-installed in the render engine and don't need a `time
 
 The renderer accepts both spaced (`Open Sans`) and concatenated (`OpenSans`) family names for these.
 
-## Why system fonts fail
+## Why system fonts don't work
 
-System fonts like `Arial`, `Helvetica`, `Times New Roman`, `Courier New`, etc. are **not installed** on the render engine. Using them produces a "Font not found" error at render time.
+System fonts like `Arial`, `Helvetica`, `Times New Roman`, `Courier New`, etc. are **not installed** on the render engine. Text set in them renders in Roboto, with no render error.
 
 **Wrong:**
 

package/skills/shotstack/references/svg.md

@@ -11,7 +11,7 @@ The `svg` asset type embeds raw SVG markup into a clip. Use it for vector shapes
 
 ## Required attributes
 
-Every SVG asset's `src` is raw markup (not a URL) and **must include all four** of:
+Every SVG asset's `src` is the markup itself, starting with `<svg`. A URL or `data:image/svg+xml` URI isn't accepted: Studio shows an empty placeholder and the render fails. (Data URIs belong inside `html5` assets only.) The markup **must include all four** of:
 
 - `xmlns="http://www.w3.org/2000/svg"`
 - `viewBox` defining the coordinate space

package/skills/shotstack/references/timeline.md

@@ -114,7 +114,7 @@ Custom fonts loaded from a URL, available to all `rich-text` and `rich-caption`
 }
 ```
 
-The `font.family` you reference in an asset must be the **basename of the file** (without `.ttf`/`.otf`/`.woff`).
+Reference a loaded font in `font.family` by the **basename of the file** (without `.ttf`/`.otf`/`.woff`). It always matches; a family that matches nothing renders in Roboto without an error.
 
 For the Montserrat URL above, `font.family` is `JTUSjIg1_i6t8kCHKm45xW5rygbi49c`.
 

package/skills/shotstack/references/troubleshooting.md

@@ -7,7 +7,7 @@ Common errors and the fix for each. **Catch most of them before rendering:** `sh
 - "Unknown property: alignment" / wrong property names
 - "Invalid option: expected one of top|middle|bottom"
 - Video looks stretched / squishing after rendering
-- "Font not found"
+- Text renders in Roboto instead of your font
 - Captions cover the whole frame
 - Clips flicker / "clips overlap" on one track
 - Timeline renders but layers are wrong
@@ -54,11 +54,11 @@ The Shotstack `fit` enum is **inverted from CSS**:
 
 **Fix:** use `fit: "crop"` (or omit `fit` — `crop` is the default) for the typical "scale and crop" behaviour you'd expect from CSS `object-fit: cover`.
 
-## "Font not found"
+## Text renders in Roboto instead of your font
 
-You used a font name that isn't in the built-in list and didn't load it via `timeline.fonts[]`.
+`font.family` didn't match any font, so the renderer fell back to Roboto without an error. Either the font isn't built in and wasn't loaded via `timeline.fonts[]`, or `family` doesn't match the loaded font: a typo, or a name that differs from the one stored in the font file.
 
-**Fix:** add the font URL to `timeline.fonts[]` and use the file basename as `family`. See `references/fonts.md`. If you really need a system font, use `Roboto` (built-in) as a substitute.
+**Fix:** add the font URL to `timeline.fonts[]` and use the file basename as `family`. `shotstack validate` flags a `family` that isn't a built-in or a loaded filename. See `references/fonts.md`. If you really need a system font, use `Roboto` (built-in) as a substitute.
 
 ## Captions cover the whole frame
 

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

@@ -222,7 +222,7 @@ Use only the **current** asset types; the deprecated ones still parse but should
 | `image` | Static image — `jpg`, `png`, `webp`, `gif`, `bmp`, `tiff`. |
 | `audio` | Audio clip placed at a specific time on the timeline. |
 | `rich-text` | Styled text overlay with full typography control. **Use this instead of `text`/`html`/`title`.** |
-| `svg` | Vector graphics from raw SVG markup. See `references/svg.md`. |
+| `svg` | Vector graphics from raw SVG markup: `src` starts with `<svg`, never a URL or `data:` URI (the render fails). See `references/svg.md`. |
 | `html5` | Self-contained HTML/CSS/JS page rendered in an iframe (motion graphics, charts, animated overlays). Preloads gsap/d3/anime/lottie. 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. |
@@ -264,7 +264,7 @@ One overlay is a `rich-text` job. **Several videos "in different styles" is not*
 
 ## Fonts
 
-Use **custom Google Fonts via `timeline.fonts[]`**. System fonts (`Arial`, `Helvetica`, `Times New Roman`) are NOT installed and will fail with "Font not found".
+Use **custom Google Fonts via `timeline.fonts[]`**. System fonts (`Arial`, `Helvetica`, `Times New Roman`) are NOT installed; text set in them renders in Roboto, with no render error.
 
 **CRITICAL: Do NOT construct or fabricate Google Fonts URLs from memory.** Google rotates them (`v26 → v31 → ...`) and the hash filenames change with each version. Any URL you reconstruct from training data is almost certainly a 404. **Use ONLY the verified entries below, copied verbatim.**
 
@@ -313,7 +313,7 @@ Variable fonts cover the full weight range (100–900) from a single URL — set
 }
 ```
 
-The `font.family` value MUST match the `family` column in the table above (it's the filename basename without `.ttf`). If `family` and the URL's basename don't match, the font will not load.
+Use the `family` column from the table above: the URL's filename without `.ttf`, matched ignoring case. The family name stored inside the font file also matches, but it isn't always the name on Google Fonts (Space Grotesk's file calls itself `Space Grotesk Light`), so the filename is the safe choice. A `font.family` that matches nothing renders in Roboto with no error. The exception is a lone entry in `timeline.fonts[]`, which is used whatever `font.family` says, so a wrong name only shows once a second font is added. `shotstack validate` warns on any `font.family` that isn't a built-in or a loaded filename.
 
 ## Top 5 mistakes