@open-assets/open-assets 0.1.11 → 0.2.0

package/README.md

@@ -1,9 +1,26 @@
-# open-assets
+<p align="center">
+  <img src="public/img/banner/1280/banner.png" alt="Open Assets" width="100%" />
+</p>
+
+# Open Assets
+
+The LLM first way to do graphics all from your git repo. 
 
 Dev server and export tool for app marketing assets. Like Storybook, but for marketing assets.
 
 Design your App Store screenshots, app icons, logos, OG images, favicons, and more in HTML/CSS/SVG, preview them live in the browser, and export pixel-perfect PNGs at any size — including directly into your Xcode project.
 
+## Examples
+
+<p><img src="public/img/examples/only-recipes-icon.png" width="14" height="14" /> <a href="https://onlyrecipes.app"><strong>Only Recipes</strong></a> (<a href="examples/only-recipes">examples</a>)</p>
+<img src="public/img/examples/only-recipes.png" alt="Only Recipes screenshots" width="100%" />
+
+<p><img src="public/img/examples/cat-iq-test-icon.png" width="14" height="14" /> <a href="https://apps.apple.com/us/app/cat-iq-test/id6759520249"><strong>Cat IQ Test</strong></a> (<a href="examples/cat-iq-test">examples</a>)</p>
+<img src="public/img/examples/cat-iq-test.png" alt="Cat IQ Test screenshots" width="100%" />
+
+<p><img src="public/img/examples/no-context-icon.png" width="14" height="14" /> <a href="https://nocontextbot.com"><strong>No Context Bot</strong></a> (<a href="examples/no-context">examples</a>)</p>
+<img src="public/img/examples/no-context.png" alt="No Context Bot screenshots" width="100%" />
+
 ## Installation
 
 ```bash
@@ -30,6 +47,22 @@ npx open-assets init
 npx open-assets dev
 ```
 
+## Shell Alias
+
+Add an alias to your shell profile for a shorter command:
+
+```bash
+echo 'alias oa="npx open-assets"' >> ~/.zshrc && source ~/.zshrc
+```
+
+Then use `oa` anywhere:
+
+```bash
+oa dev
+oa render --force
+oa init
+```
+
 ## Concepts
 
 open-assets uses a simple, unified data model. Every asset type follows the same structure: **N templates × M export sizes**.
@@ -39,7 +72,6 @@ open-assets uses a simple, unified data model. Every asset type follows the same
 | **Collection** | A named group of related assets sharing the same source size and export sizes. One tab in the dev UI. |
 | **Template** | A single source file (HTML or SVG) that produces one image per export size. |
 | **Export Size** | A named output dimension that templates are rendered at (e.g., "iPhone 6.9" → 1320×2868). |
-| **Platform** | Optional grouping label for related export sizes (e.g., "App Store", "Play Store"). |
 | **Source Size** | The dimensions the HTML template is authored at. Puppeteer scales from source → export size. |
 | **Output** | An optional post-render action (e.g., write to Xcode `.appiconset`, copy SVG source). |
 
@@ -51,7 +83,7 @@ open-assets uses a simple, unified data model. Every asset type follows the same
 npx open-assets init
 ```
 
-Creates a `manifest.json`, sample HTML templates, and a `public/` directory for shared assets.
+Creates a `assets.json`, sample HTML templates, and a `public/` directory for shared assets.
 
 ### 2. Design with Claude Code
 
@@ -74,13 +106,13 @@ your eye as you scroll. Use bold headlines with highlighted keywords, phone
 mockups with real app screenshots, and close with reviews + a CTA.
 ```
 
-Claude reads your `manifest.json` and `publicDir` to understand the project structure, then creates screenshot HTML files using the design patterns in the skill.
+Claude reads your `assets.json` and `publicDir` to understand the project structure, then creates screenshot HTML files using the design patterns in the skill.
 
 ### 3. Preview
 
 ```bash
 # With Tailwind
-concurrently "npx @tailwindcss/cli -i src/styles.css -o dist/styles.css --watch" "npx open-assets dev"
+concurrently "npx @tailwindcss/cli -i assets/styles.css -o dist/styles.css --watch" "npx open-assets dev"
 
 # Without Tailwind
 npx open-assets dev
@@ -91,7 +123,7 @@ Opens a live preview UI at `http://localhost:3200` with zoom/pan controls and ex
 ### 4. Export
 
 ```bash
-npx open-assets render --all
+npx open-assets render --force
 ```
 
 Exports every template at every configured export size into `./exports/`, organized as `exports/{collection}/{size}/{template}.png`.
@@ -109,7 +141,7 @@ Capture real app screenshots via Playwright or XCTest, then use them inside your
 npx playwright test --project=screenshots
 
 # 2. Export marketing screenshots with those captures embedded
-npx open-assets render --all
+npx open-assets render --force
 ```
 
 Reference captured screenshots in your HTML templates:
@@ -117,10 +149,10 @@ Reference captured screenshots in your HTML templates:
 <img src="../../public/screenshots/01-home.png" style="width: 100%; height: 100%; object-fit: cover;" />
 ```
 
-The `manifest.json` `command` field stores the export command so automation tools know what to run:
+The `assets.json` `command` field stores the export command so automation tools know what to run:
 ```json
 {
-  "command": "npx open-assets render --all"
+  "command": "npx open-assets render --force"
 }
 ```
 
@@ -139,7 +171,7 @@ open-assets dev --no-open              # Don't auto-open browser
 open-assets dev --quiet                # Suppress server logs
 open-assets dev --ci                   # CI mode (quiet + no browser)
 open-assets dev --static-dir ./shared  # Serve additional static directories
-open-assets dev --manifest config.json # Use a custom manifest filename
+open-assets dev --config config.json # Use a custom config filename
 ```
 
 Options:
@@ -150,7 +182,7 @@ Options:
 | `--no-open` | `OPEN_ASSETS_NO_OPEN` | — | Don't auto-open the browser |
 | `-q, --quiet` | `OPEN_ASSETS_QUIET` | `false` | Suppress server logs |
 | `--ci` | `CI` | `false` | CI mode: quiet + no browser |
-| `--manifest <path>` | `OPEN_ASSETS_MANIFEST` | `manifest.json` | Path to manifest file |
+| `--config <path>` | `OPEN_ASSETS_CONFIG` | `assets.json` | Path to config file |
 | `--static-dir <dirs...>` | — | — | Additional static directories to serve |
 | `--render-timeout <ms>` | `OPEN_ASSETS_RENDER_TIMEOUT` | `30000` | Puppeteer render timeout |
 
@@ -160,13 +192,11 @@ Render assets headlessly via the command line, without opening a browser.
 
 ```bash
 open-assets render                              # Render all collections at source size
-open-assets render --all                        # Export at EVERY configured size
+open-assets render --force                      # Export at every size, ignore cache
 open-assets render --collection screenshots     # Render a specific collection
 open-assets render --template 01-hero           # Render a single template
 open-assets render --size iphone-6.9            # Use a named export size
-open-assets render --platform "App Store"       # Render all sizes for a platform
 open-assets render --width 1320 --height 2868   # Custom size
-open-assets render --force                      # Re-render everything, ignore cache
 open-assets render -o ./build                   # Custom output directory
 open-assets render --json                       # Output results as JSON (for CI)
 open-assets render --quiet                      # Suppress progress logs
@@ -177,14 +207,12 @@ Options:
 |------|---------|---------|-------------|
 | `--collection <id>` | — | all | Render only the collection with this ID |
 | `--template <name>` | — | all | Render only the template with this name |
-| `--size <name>` | — | — | Use a named export size from manifest |
-| `--platform <name>` | — | — | Render only sizes for this platform |
+| `--size <name>` | — | — | Use a named export size from config |
 | `--width <px>` | — | — | Custom output width |
 | `--height <px>` | — | — | Custom output height |
-| `--all` | — | — | Export at every size defined in the manifest |
-| `--force` | — | — | Re-render all assets even if unchanged |
+| `-f, --force` | — | — | Export at every size and re-render all (ignores cache) |
 | `-o, --output <dir>` | `OPEN_ASSETS_OUTPUT` | `./exports` | Output directory |
-| `--manifest <path>` | `OPEN_ASSETS_MANIFEST` | `manifest.json` | Path to manifest file |
+| `--config <path>` | `OPEN_ASSETS_CONFIG` | `assets.json` | Path to config file |
 | `--parallel <count>` | `OPEN_ASSETS_PARALLEL` | `1` | Number of parallel renders |
 | `--render-timeout <ms>` | `OPEN_ASSETS_RENDER_TIMEOUT` | `30000` | Puppeteer render timeout |
 | `--json` | — | — | Output results as JSON |
@@ -196,13 +224,10 @@ Options:
 open-assets render --collection screenshots --template 01-hero --size iphone-6.9
 
 # One template at all device sizes
-open-assets render --collection screenshots --template 01-hero --all
+open-assets render --collection screenshots --template 01-hero --force
 
 # All templates at one device size
 open-assets render --collection screenshots --size iphone-6.9
-
-# All templates for a specific platform
-open-assets render --collection screenshots --platform "App Store"
 ```
 
 **Output structure**: `exports/{collection}/{size}/{template}.png`
@@ -231,7 +256,7 @@ exports/
 
 ### `open-assets list [dir]`
 
-List all collections and templates defined in the manifest.
+List all collections and templates defined in the config.
 
 ```bash
 open-assets list              # Pretty-print asset tree
@@ -240,7 +265,7 @@ open-assets list --json       # Output as JSON
 
 ### `open-assets validate [dir]`
 
-Validate the manifest and check that all referenced source files exist.
+Validate the config and check that all referenced source files exist.
 
 ```bash
 open-assets validate          # Check current directory
@@ -263,7 +288,7 @@ npx skills add https://github.com/Parra-Inc/open-assets --skill open-assets
 
 ### `open-assets init [dir]`
 
-Scaffold a new project with a `manifest.json`, sample HTML templates, and a `public/` directory.
+Scaffold a new project with a `assets.json`, sample HTML templates, and a `public/` directory.
 
 ```bash
 open-assets init              # Current directory
@@ -272,14 +297,14 @@ open-assets init ./my-assets  # Specific directory
 
 ## Manifest Format
 
-Your project needs a `manifest.json` at its root. This file defines the collections shown in the viewer and all export options.
+Your project needs a `assets.json` at its root. This file defines the collections shown in the viewer and all export options.
 
 ```json
 {
   "version": 1,
   "name": "My App",
   "publicDir": "public",
-  "command": "npx open-assets render --all",
+  "command": "npx open-assets render --force",
   "collections": [ ... ]
 }
 ```
@@ -305,19 +330,12 @@ All collections follow the same structure. No `type` field needed.
   "sourceSize": { "width": 440, "height": 956 },
   "borderRadius": 4,
   "templates": [
-    { "src": "src/screenshots/01-hero.html", "name": "01-hero", "label": "Hero" },
-    { "src": "src/screenshots/02-features.html", "name": "02-features", "label": "Features" }
-  ],
-  "exportSizes": [
-    {
-      "platform": "App Store",
-      "sizes": [
-        { "name": "iphone-6.9", "label": "iPhone 6.9\"", "width": 1320, "height": 2868 },
-        { "name": "iphone-6.7", "label": "iPhone 6.7\"", "width": 1290, "height": 2796 }
-      ]
-    }
+    { "src": "assets/screenshots/01-hero.html", "name": "01-hero", "label": "Hero" },
+    { "src": "assets/screenshots/02-features.html", "name": "02-features", "label": "Features" }
   ],
-  "outputs": [
+  "export": [
+    { "name": "iphone-6.9", "label": "iPhone 6.9\"", "size": { "width": 1320, "height": 2868 } },
+    { "name": "iphone-6.7", "label": "iPhone 6.7\"", "size": { "width": 1290, "height": 2796 } },
     { "type": "xcode", "path": "../MyApp/Assets.xcassets/AppIcon.appiconset" }
   ]
 }
@@ -333,14 +351,18 @@ All collections follow the same structure. No `type` field needed.
 | `templates[].src` | string | Path to HTML/SVG file (relative to project root) |
 | `templates[].name` | string | Filename for exports (used by `--template` flag) |
 | `templates[].label` | string | Display label |
-| `exportSizes` | array | Grouped export size definitions |
-| `exportSizes[].platform` | string | Optional grouping label |
-| `exportSizes[].sizes[]` | object | `{ name, label, width, height }` |
-| `outputs` | array | Optional post-render actions |
+| `export` | array | Array of export sizes and output actions |
+| `export[].name` | string | Size identifier (used by `--size` flag) |
+| `export[].label` | string | Display label |
+| `export[].size` | object | `{ width, height }` — output dimensions in pixels |
+| `export[].outFile` | string | Optional output path for this size (supports .png, .jpg) |
+| `export[].type` | string | Output action type (`xcode`, `copy-source`). Entries with `type` are post-render actions, not sizes |
 | `customExport` | object | Optional `{ defaultWidth, defaultHeight }` for custom size UI |
 
 ### Output Types
 
+Export entries with a `type` field are post-render actions (run with `--force`):
+
 | Type | Config | Description |
 |------|--------|-------------|
 | `xcode` | `{ "type": "xcode", "path": "..." }` | Render icon and write to Xcode asset catalog |
@@ -356,19 +378,14 @@ All collections follow the same structure. No `type` field needed.
   "sourceSize": { "width": 440, "height": 956 },
   "borderRadius": 4,
   "templates": [
-    { "src": "src/screenshots/01-hero.html", "name": "01-hero", "label": "Hero" },
-    { "src": "src/screenshots/02-import.html", "name": "02-import", "label": "Import" }
+    { "src": "assets/screenshots/01-hero.html", "name": "01-hero", "label": "Hero" },
+    { "src": "assets/screenshots/02-import.html", "name": "02-import", "label": "Import" }
   ],
-  "exportSizes": [
-    {
-      "platform": "App Store",
-      "sizes": [
-        { "name": "iphone-6.9", "label": "iPhone 6.9\"", "width": 1320, "height": 2868 },
-        { "name": "iphone-6.7", "label": "iPhone 6.7\"", "width": 1290, "height": 2796 },
-        { "name": "iphone-6.5", "label": "iPhone 6.5\"", "width": 1284, "height": 2778 },
-        { "name": "iphone-6.1", "label": "iPhone 6.1\"", "width": 1179, "height": 2556 }
-      ]
-    }
+  "export": [
+    { "name": "iphone-6.9", "label": "iPhone 6.9\"", "size": { "width": 1320, "height": 2868 } },
+    { "name": "iphone-6.7", "label": "iPhone 6.7\"", "size": { "width": 1290, "height": 2796 } },
+    { "name": "iphone-6.5", "label": "iPhone 6.5\"", "size": { "width": 1284, "height": 2778 } },
+    { "name": "iphone-6.1", "label": "iPhone 6.1\"", "size": { "width": 1179, "height": 2556 } }
   ]
 }
 ```
@@ -381,19 +398,12 @@ All collections follow the same structure. No `type` field needed.
   "sourceSize": { "width": 1024, "height": 1024 },
   "borderRadius": 224,
   "templates": [
-    { "src": "src/icon.html", "name": "icon", "label": "App Icon" }
+    { "src": "assets/icon.html", "name": "icon", "label": "App Icon" }
   ],
-  "exportSizes": [
-    {
-      "platform": "Apple",
-      "sizes": [
-        { "name": "1024", "label": "1024px", "width": 1024, "height": 1024 },
-        { "name": "180", "label": "180px", "width": 180, "height": 180 },
-        { "name": "120", "label": "120px", "width": 120, "height": 120 }
-      ]
-    }
-  ],
-  "outputs": [
+  "export": [
+    { "name": "1024", "label": "1024px", "size": { "width": 1024, "height": 1024 } },
+    { "name": "180", "label": "180px", "size": { "width": 180, "height": 180 } },
+    { "name": "120", "label": "120px", "size": { "width": 120, "height": 120 } },
     { "type": "xcode", "path": "../MyApp/Assets.xcassets/AppIcon.appiconset" }
   ]
 }
@@ -407,17 +417,13 @@ All collections follow the same structure. No `type` field needed.
   "sourceSize": { "width": 1024, "height": 1024 },
   "borderRadius": 224,
   "templates": [
-    { "src": "src/icons/concept-a.html", "name": "concept-a", "label": "Concept A" },
-    { "src": "src/icons/concept-b.html", "name": "concept-b", "label": "Concept B" },
-    { "src": "src/icons/seasonal-winter.html", "name": "seasonal-winter", "label": "Winter" }
+    { "src": "assets/icons/concept-a.html", "name": "concept-a", "label": "Concept A" },
+    { "src": "assets/icons/concept-b.html", "name": "concept-b", "label": "Concept B" },
+    { "src": "assets/icons/seasonal-winter.html", "name": "seasonal-winter", "label": "Winter" }
   ],
-  "exportSizes": [
-    {
-      "sizes": [
-        { "name": "1024", "label": "1024px", "width": 1024, "height": 1024 },
-        { "name": "512", "label": "512px", "width": 512, "height": 512 }
-      ]
-    }
+  "export": [
+    { "name": "1024", "label": "1024px", "size": { "width": 1024, "height": 1024 } },
+    { "name": "512", "label": "512px", "size": { "width": 512, "height": 512 } }
   ]
 }
 ```
@@ -429,20 +435,14 @@ All collections follow the same structure. No `type` field needed.
   "label": "Logo",
   "sourceSize": { "width": 940, "height": 940 },
   "templates": [
-    { "src": "src/logo.svg", "name": "logo", "label": "Logo" },
-    { "src": "src/logo-dark.svg", "name": "logo-dark", "label": "Dark" },
-    { "src": "src/wordmark.svg", "name": "wordmark", "label": "Wordmark" }
-  ],
-  "exportSizes": [
-    {
-      "sizes": [
-        { "name": "2048", "label": "2048px", "width": 2048, "height": 2048 },
-        { "name": "1024", "label": "1024px", "width": 1024, "height": 1024 },
-        { "name": "512", "label": "512px", "width": 512, "height": 512 }
-      ]
-    }
+    { "src": "assets/logo.svg", "name": "logo", "label": "Logo" },
+    { "src": "assets/logo-dark.svg", "name": "logo-dark", "label": "Dark" },
+    { "src": "assets/wordmark.svg", "name": "wordmark", "label": "Wordmark" }
   ],
-  "outputs": [
+  "export": [
+    { "name": "2048", "label": "2048px", "size": { "width": 2048, "height": 2048 } },
+    { "name": "1024", "label": "1024px", "size": { "width": 1024, "height": 1024 } },
+    { "name": "512", "label": "512px", "size": { "width": 512, "height": 512 } },
     { "type": "copy-source", "format": "svg" }
   ]
 }
@@ -455,10 +455,10 @@ All collections follow the same structure. No `type` field needed.
   "label": "Social Cards",
   "sourceSize": { "width": 1200, "height": 630 },
   "templates": [
-    { "src": "src/og/default.html", "name": "default", "label": "Default OG" }
+    { "src": "assets/og/default.html", "name": "default", "label": "Default OG" }
   ],
-  "exportSizes": [
-    { "sizes": [{ "name": "og", "label": "OG Image", "width": 1200, "height": 630 }] }
+  "export": [
+    { "name": "og", "label": "OG Image", "size": { "width": 1200, "height": 630 } }
   ]
 }
 ```
@@ -470,34 +470,24 @@ All collections follow the same structure. No `type` field needed.
   "label": "Favicons",
   "sourceSize": { "width": 512, "height": 512 },
   "templates": [
-    { "src": "src/favicon.html", "name": "favicon", "label": "Favicon" }
+    { "src": "assets/favicon.html", "name": "favicon", "label": "Favicon" }
   ],
-  "exportSizes": [
-    {
-      "platform": "Web",
-      "sizes": [
-        { "name": "512", "label": "512px", "width": 512, "height": 512 },
-        { "name": "192", "label": "192px", "width": 192, "height": 192 },
-        { "name": "32", "label": "32px", "width": 32, "height": 32 },
-        { "name": "16", "label": "16px", "width": 16, "height": 16 }
-      ]
-    },
-    {
-      "platform": "Apple",
-      "sizes": [
-        { "name": "apple-touch", "label": "Apple Touch Icon", "width": 180, "height": 180 }
-      ]
-    }
+  "export": [
+    { "name": "512", "label": "512px", "size": { "width": 512, "height": 512 } },
+    { "name": "192", "label": "192px", "size": { "width": 192, "height": 192 } },
+    { "name": "32", "label": "32px", "size": { "width": 32, "height": 32 }, "outFile": "public/favicon.png" },
+    { "name": "16", "label": "16px", "size": { "width": 16, "height": 16 } },
+    { "name": "apple-touch", "label": "Apple Touch Icon", "size": { "width": 180, "height": 180 }, "outFile": "public/apple-touch-icon.png" }
   ]
 }
 ```
 
-## Incremental Builds with manifest.lock
+## Incremental Builds with assets.lock
 
-The `render` command maintains a `manifest.lock` file that stores SHA256 checksums of each source HTML/SVG file. On subsequent renders, unchanged assets are skipped automatically:
+The `render` command maintains a `assets.lock` file that stores SHA256 checksums of each source HTML/SVG file. On subsequent renders, unchanged assets are skipped automatically:
 
 ```
-$ open-assets render --all
+$ open-assets render --force
   Skipping 01-hero at 1320x2868 (unchanged)
   Rendering 03-new-screen at 1320x2868...
     → exports/screenshots/iphone-6.9/03-new-screen.png
@@ -509,7 +499,7 @@ Use `--force` to re-render everything regardless of the cache.
 
 **Limitation**: Only source HTML/SVG files are checksummed. Changes to referenced assets (images in `publicDir`, compiled Tailwind CSS) won't trigger re-renders — use `--force` when those change.
 
-Add `manifest.lock` to your `.gitignore` (done automatically by `open-assets init`).
+Commit `assets.lock` to your repository so teammates and CI benefit from the cache.
 
 ## CI/CD with GitHub Actions
 
@@ -521,7 +511,7 @@ on:
   push:
     paths:
       - 'marketing/screenshots/**'
-      - 'marketing/screenshots/manifest.json'
+      - 'marketing/screenshots/assets.json'
 jobs:
   export:
     runs-on: ubuntu-latest
@@ -532,7 +522,7 @@ jobs:
           node-version: 20
       - run: npm ci
       - run: npx open-assets validate
-      - run: npx open-assets render --all --json --quiet
+      - run: npx open-assets render --force --json --quiet
       - uses: actions/upload-artifact@v4
         with:
           name: screenshots
@@ -558,15 +548,15 @@ jobs:
 
 ```
 project/
-  manifest.json
-  manifest.lock              # Auto-generated cache (gitignored)
+  assets.json
+  assets.lock              # Auto-generated cache (commit this)
   public/                    # Shared assets (configured via publicDir)
     logo-round.png
     social/
       youtube.svg
     screenshots/             # Real app screenshots from UI tests
       01-home.png
-  src/
+  assets/
     styles.css               # Tailwind input
     icon.html                # App icon template
     logo.svg                 # Vector logo template