docs(quoteforge[cli]): document --safe-aspect

Author: lordvins226

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.6.0
+
+### Added
+- `--safe-aspect <ratio>` on `generate`/`slides`/`batch`: constrains the layout so all content
+  survives a center-crop toward the given ratio (e.g. `--safe-aspect 4:3`), for images embedded
+  in mismatched `object-fit: cover` containers. Opt-in; no effect when absent.
+
 ## 0.5.0
 
 ### Added
@@ -10,6 +17,9 @@
 - `--fit-content` (alias `--trim`) on `generate`/`slides`/`batch`, cropping the output to the
   content bounding box plus theme padding.
 
+### Fixed
+- Studio: `size: "custom"` cards and deck slides now render at their given dimensions in preview and export (previously blank).
+
 ### Changed
 - **Rendering change:** content is now vertically centered by default instead of distributed
   over the full canvas height. Existing cards re-render with content grouped. Add

README.md

@@ -79,13 +79,14 @@ quoteforge preview content/examples/manifesto-wiki.json
 ```
 quoteforge generate <file> [options]
 
-  -t, --theme <name>   Override theme
-  -s, --size <name>    Override size (see Size Reference below)
-  -o, --output <path>  Output file path
-  --scale <n>          Pixel ratio (default: 2)
-  --fit-content        Crop to content bounding box + theme padding
-  --open               Open output file after generation
-  --no-timestamp       Omit timestamp from filename
+  -t, --theme <name>      Override theme
+  -s, --size <name>       Override size (see Size Reference below)
+  -o, --output <path>     Output file path
+  --scale <n>             Pixel ratio (default: 2)
+  --safe-aspect <ratio>   Constrain content for center-crop (e.g. 16:9)
+  --fit-content           Crop to content bounding box + theme padding
+  --open                  Open output file after generation
+  --no-timestamp          Omit timestamp from filename
 ```
 
 **Examples:**
@@ -94,6 +95,7 @@ quoteforge generate <file> [options]
 quoteforge generate content/my-card.json
 quoteforge generate content/my-card.json --size facebook-post --theme dark-orange
 quoteforge generate content/my-card.json --no-timestamp --open
+quoteforge generate content/my-card.json --safe-aspect 16:9
 quoteforge generate content/my-card.json --fit-content
 ```
 
@@ -102,17 +104,18 @@ quoteforge generate content/my-card.json --fit-content
 ```
 quoteforge slides <file> [options]
 
-  -t, --theme <name>   Override theme for all slides
-  -s, --size <name>    Override size for all slides
-  -o, --output <dir>   Output directory
-  --slide <n>          Render only slide N (1-indexed), no ZIP
-  --no-zip             Skip ZIP creation
-  --no-counter         Disable counter overlay for all slides
-  --fit-content        Crop each slide to content bounding box + theme padding
-  --concurrency <n>    Parallel render workers (default: 4)
-  --zip-level <n>      ZIP compression level 0-9 (default: 6)
-  --scale <n>          Pixel ratio (default: 2)
-  --open               Open output folder after generation
+  -t, --theme <name>      Override theme for all slides
+  -s, --size <name>       Override size for all slides
+  -o, --output <dir>      Output directory
+  --slide <n>             Render only slide N (1-indexed), no ZIP
+  --no-zip                Skip ZIP creation
+  --no-counter            Disable counter overlay for all slides
+  --safe-aspect <ratio>   Constrain content for center-crop (e.g. 16:9)
+  --fit-content           Crop each slide to content bounding box + theme padding
+  --concurrency <n>       Parallel render workers (default: 4)
+  --zip-level <n>         ZIP compression level 0-9 (default: 6)
+  --scale <n>             Pixel ratio (default: 2)
+  --open                  Open output folder after generation
 ```
 
 **Examples:**
@@ -121,6 +124,7 @@ quoteforge slides <file> [options]
 quoteforge slides decks/intro-deck.json
 quoteforge slides decks/intro-deck.json --size facebook-square
 quoteforge slides decks/intro-deck.json --slide 3
+quoteforge slides decks/intro-deck.json --safe-aspect 16:9
 quoteforge slides decks/intro-deck.json --no-counter --theme light-minimal
 ```
 
@@ -179,12 +183,13 @@ quoteforge themes validate <file>                # Validate a theme file
 ```
 quoteforge batch <directory> [options]
 
-  -t, --theme <name>   Override theme for all files
-  -s, --size <name>    Override size for all files
-  -o, --output <dir>   Output directory
-  --fit-content        Crop each output to content bounding box + theme padding
-  --concurrency <n>    Parallel workers (default: 2)
-  --decks              Also process deck files into individual ZIPs
+  -t, --theme <name>      Override theme for all files
+  -s, --size <name>       Override size for all files
+  -o, --output <dir>      Output directory
+  --safe-aspect <ratio>   Constrain content for center-crop (e.g. 16:9)
+  --fit-content           Crop each output to content bounding box + theme padding
+  --concurrency <n>       Parallel workers (default: 2)
+  --decks                 Also process deck files into individual ZIPs
 ```
 
 ### `validate` — Validate content files

site/src/docs/cli.mdx

@@ -18,6 +18,42 @@ quoteforge generate card.json --fit-content    # crop to content, no surrounding
 
 When used with `slides`, the flag may produce slides with different heights (if content height varies per slide). This is intentional but worth noting in deck workflows. On a deck, `--fit-content` also drops the slide-counter overlay, which sits outside the content box.
 
+### `--safe-aspect`
+
+The `--safe-aspect <ratio>` flag constrains the layout so all content survives a center-crop toward the given ratio. This is useful when rendering cards for embedded display in mismatched `object-fit: cover` containers (e.g., a square card to be embedded in a 16:9 player or carousel).
+
+**Accepted ratio formats:**
+- `W:H` (e.g., `16:9`, `4:3`)
+- `WxH` (e.g., `16x9`)
+- Decimal (e.g., `1.78` for 16:9)
+
+**Recommendation:** pair `--safe-aspect` with `align: center` (the default). Do not combine with `--fit-content` (they have opposite intents: safe-aspect maintains full size, fit-content crops to content).
+
+**Example:** A square card (1080×1080) made safe for a 16:9 embed:
+
+1. Create a card with square dimensions (`size: "instagram-sq"`) and `align: "center"`:
+
+```json
+{
+  "template": "quote",
+  "theme": "dark-teal",
+  "size": "instagram-sq",
+  "align": "center",
+  "blocks": [
+    { "type": "headline", "parts": [{ "text": "Center-safe for 16:9", "style": "normal" }] },
+    { "type": "text", "content": "All content fits in the central 1920×1080 band, surviving center-crop to 16:9." }
+  ]
+}
+```
+
+2. Render it with `--safe-aspect 16:9`:
+
+```bash
+quoteforge generate card.json --safe-aspect 16:9
+```
+
+The output remains 1080×1080 but all content is constrained to the central 16:9 region (1080×607px). When embedded in a 16:9 container with `object-fit: cover`, the entire content box will remain visible.
+
 Options:
 
 | Flag | Default | Description |
@@ -26,6 +62,7 @@ Options:
 | `-s, --size <name>` | (from file) | Override size (e.g. `instagram-sq`) |
 | `-o, --output <path>` | `outputs/` | Output directory |
 | `--scale <n>` | `2` | Pixel ratio (1 or 2) |
+| `--safe-aspect <ratio>` | — | Constrain content to safe band for center-crop (e.g. `16:9`) |
 | `--fit-content` | — | Crop output to content bounding box + theme padding |
 | `--no-timestamp` | — | Don't append ISO timestamp to filename |
 | `--open` | — | Open the PNG after generation |
@@ -48,6 +85,7 @@ Options:
 | `--slide <n>` | — | Render only slide N (1-indexed), no ZIP |
 | `--no-zip` | — | Skip ZIP creation |
 | `--no-counter` | — | Disable counter overlay |
+| `--safe-aspect <ratio>` | — | Constrain content to safe band for center-crop (e.g. `16:9`) |
 | `--fit-content` | — | Crop each slide to content bounding box + theme padding |
 | `--concurrency <n>` | `4` | Parallel render workers |
 | `--scale <n>` | `2` | Pixel ratio |
@@ -61,7 +99,7 @@ Render every JSON file in a directory.
 quoteforge batch <dir> [options]
 ```
 
-Options include `--theme`, `--size`, `--output`, `--fit-content`, `--concurrency`, and `--decks` (to also process deck files).
+Options include `--theme`, `--size`, `--output`, `--safe-aspect`, `--fit-content`, `--concurrency`, and `--decks` (to also process deck files).
 
 ## `validate`