@open-assets/open-assets 0.1.11 → 0.1.12

package/README.md

@@ -1,4 +1,10 @@
-# 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.
 
@@ -30,6 +36,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 --all
+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 +61,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 +72,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,7 +95,7 @@ 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
 
@@ -117,7 +138,7 @@ 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"
@@ -139,7 +160,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 +171,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 |
 
@@ -164,7 +185,6 @@ open-assets render --all                        # Export at EVERY configured siz
 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
@@ -177,14 +197,13 @@ 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 |
+| `--all` | — | — | Export at every size defined in the config |
 | `--force` | — | — | Re-render all assets even if unchanged |
 | `-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 |
@@ -200,9 +219,6 @@ open-assets render --collection screenshots --template 01-hero --all
 
 # 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 +247,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 +256,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 +279,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,7 +288,7 @@ 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
 {
@@ -308,14 +324,9 @@ All collections follow the same structure. No `type` field needed.
     { "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 }
-      ]
-    }
+  "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 } }
   ],
   "outputs": [
     { "type": "xcode", "path": "../MyApp/Assets.xcassets/AppIcon.appiconset" }
@@ -333,9 +344,11 @@ 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 }` |
+| `export` | array | Flat array of export size definitions |
+| `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) |
 | `outputs` | array | Optional post-render actions |
 | `customExport` | object | Optional `{ defaultWidth, defaultHeight }` for custom size UI |
 
@@ -359,16 +372,11 @@ All collections follow the same structure. No `type` field needed.
     { "src": "src/screenshots/01-hero.html", "name": "01-hero", "label": "Hero" },
     { "src": "src/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 } }
   ]
 }
 ```
@@ -383,15 +391,10 @@ All collections follow the same structure. No `type` field needed.
   "templates": [
     { "src": "src/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 }
-      ]
-    }
+  "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 } }
   ],
   "outputs": [
     { "type": "xcode", "path": "../MyApp/Assets.xcassets/AppIcon.appiconset" }
@@ -411,13 +414,9 @@ All collections follow the same structure. No `type` field needed.
     { "src": "src/icons/concept-b.html", "name": "concept-b", "label": "Concept B" },
     { "src": "src/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 } }
   ]
 }
 ```
@@ -433,14 +432,10 @@ All collections follow the same structure. No `type` field needed.
     { "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 }
-      ]
-    }
+  "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 } }
   ],
   "outputs": [
     { "type": "copy-source", "format": "svg" }
@@ -457,8 +452,8 @@ All collections follow the same structure. No `type` field needed.
   "templates": [
     { "src": "src/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 } }
   ]
 }
 ```
@@ -472,29 +467,19 @@ All collections follow the same structure. No `type` field needed.
   "templates": [
     { "src": "src/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
@@ -509,7 +494,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`).
+Add `assets.lock` to your `.gitignore` (done automatically by `open-assets init`).
 
 ## CI/CD with GitHub Actions
 
@@ -521,7 +506,7 @@ on:
   push:
     paths:
       - 'marketing/screenshots/**'
-      - 'marketing/screenshots/manifest.json'
+      - 'marketing/screenshots/assets.json'
 jobs:
   export:
     runs-on: ubuntu-latest
@@ -558,8 +543,8 @@ jobs:
 
 ```
 project/
-  manifest.json
-  manifest.lock              # Auto-generated cache (gitignored)
+  assets.json
+  assets.lock              # Auto-generated cache (gitignored)
   public/                    # Shared assets (configured via publicDir)
     logo-round.png
     social/