@open-assets/open-assets 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ian MacCallum
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,564 @@
+# open-assets
+
+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.
+
+## Quick Start
+
+```bash
+# Install
+npm install --save-dev open-assets
+
+# Scaffold a new project
+npx open-assets init
+
+# Start the dev server
+npx open-assets dev
+```
+
+## Concepts
+
+open-assets uses a simple, unified data model. Every asset type follows the same structure: **N templates × M export sizes**.
+
+| Term | Definition |
+|------|-----------|
+| **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). |
+
+## End-to-End Screenshot Pipeline
+
+### 1. Initialize
+
+```bash
+npx open-assets init
+```
+
+Creates a `manifest.json`, sample HTML templates, and a `public/` directory for shared assets.
+
+### 2. Design with Claude Code
+
+Install the open-assets Claude skill, then prompt:
+
+```
+Now we want to make beautiful screenshots for this app. Install the open-assets
+skill from https://github.com/ianmaccallum/open-assets. Look at the marketing
+doc and demographics. Design 8 high-converting App Store screenshots that catch
+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.
+
+### 3. Preview
+
+```bash
+# With Tailwind
+concurrently "npx @tailwindcss/cli -i src/styles.css -o dist/styles.css --watch" "npx open-assets dev"
+
+# Without Tailwind
+npx open-assets dev
+```
+
+Opens a live preview UI at `http://localhost:3200` with zoom/pan controls and export buttons.
+
+### 4. Export
+
+```bash
+npx open-assets render --all
+```
+
+Exports every template at every configured export size into `./exports/`, organized as `exports/{collection}/{size}/{template}.png`.
+
+### 5. Upload to App Store Connect / Google Play
+
+Upload the exported PNGs to App Store Connect or Google Play Console. Each size subdirectory maps to a device size required by the store.
+
+## Generating Screenshots from UI Tests
+
+Capture real app screenshots via Playwright or XCTest, then use them inside your marketing screenshot templates:
+
+```bash
+# 1. Run UI tests to capture app screenshots into public/screenshots/
+npx playwright test --project=screenshots
+
+# 2. Export marketing screenshots with those captures embedded
+npx open-assets render --all
+```
+
+Reference captured screenshots in your HTML templates:
+```html
+<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:
+```json
+{
+  "command": "npx open-assets render --all"
+}
+```
+
+## CLI Commands
+
+### `open-assets dev [dir]`
+
+Start the dev server with a live preview UI and export controls.
+
+```bash
+open-assets dev                        # Use current directory
+open-assets dev ./screenshots          # Use a specific directory
+open-assets dev --port 4000            # Custom port (default: 3200)
+open-assets dev --host 0.0.0.0         # Bind to all interfaces (network access)
+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
+```
+
+Options:
+| Flag | Env Var | Default | Description |
+|------|---------|---------|-------------|
+| `-p, --port <port>` | `OPEN_ASSETS_PORT` | `3200` | Port to listen on |
+| `-H, --host <host>` | `OPEN_ASSETS_HOST` | `localhost` | Host to bind to |
+| `--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 |
+| `--static-dir <dirs...>` | — | — | Additional static directories to serve |
+| `--render-timeout <ms>` | `OPEN_ASSETS_RENDER_TIMEOUT` | `30000` | Puppeteer render timeout |
+
+### `open-assets render [dir]`
+
+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 --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
+```
+
+Options:
+| Flag | Env Var | Default | Description |
+|------|---------|---------|-------------|
+| `--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 |
+| `--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 |
+| `-o, --output <dir>` | `OPEN_ASSETS_OUTPUT` | `./exports` | Output directory |
+| `--manifest <path>` | `OPEN_ASSETS_MANIFEST` | `manifest.json` | Path to manifest 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 |
+| `-q, --quiet` | `OPEN_ASSETS_QUIET` | `false` | Suppress progress logs |
+
+**Selective export** — flags compose naturally:
+```bash
+# Single template at a single device size
+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
+
+# 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`
+```
+exports/
+  screenshots/
+    iphone-6.9/
+      01-hero.png
+      02-features.png
+    iphone-6.7/
+      01-hero.png
+      02-features.png
+  icon/
+    1024/
+      icon.png
+    180/
+      icon.png
+  logo/
+    svg/
+      logo.svg
+      logo-dark.svg
+    1024/
+      logo.png
+      logo-dark.png
+```
+
+### `open-assets list [dir]`
+
+List all collections and templates defined in the manifest.
+
+```bash
+open-assets list              # Pretty-print asset tree
+open-assets list --json       # Output as JSON
+```
+
+### `open-assets validate [dir]`
+
+Validate the manifest and check that all referenced source files exist.
+
+```bash
+open-assets validate          # Check current directory
+open-assets validate ./assets # Check specific directory
+```
+
+Returns exit code 1 if any errors are found — useful in CI pipelines.
+
+### `open-assets init [dir]`
+
+Scaffold a new project with a `manifest.json`, sample HTML templates, and a `public/` directory.
+
+```bash
+open-assets init              # Current directory
+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.
+
+```json
+{
+  "version": 1,
+  "name": "My App",
+  "publicDir": "public",
+  "command": "npx open-assets render --all",
+  "collections": [ ... ]
+}
+```
+
+### Root Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `version` | number | yes | Manifest schema version (`1`) |
+| `name` | string | yes | App display name |
+| `publicDir` | string | no | Directory for shared assets (auto-served by dev server) |
+| `command` | string | no | Export command for automation tools and CI |
+| `collections` | array | yes | Asset collection definitions |
+
+### Collection Schema (Unified)
+
+All collections follow the same structure. No `type` field needed.
+
+```json
+{
+  "id": "screenshots",
+  "label": "App Store Screenshots",
+  "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 }
+      ]
+    }
+  ],
+  "outputs": [
+    { "type": "xcode", "path": "../MyApp/Assets.xcassets/AppIcon.appiconset" }
+  ]
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | Unique collection identifier (used in CLI `--collection`) |
+| `label` | string | Display name in the collection selector |
+| `sourceSize` | object | `{ width, height }` — the dimensions templates are authored at |
+| `borderRadius` | number | Border radius for preview frames (px) |
+| `templates` | array | Source files to render |
+| `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 |
+| `customExport` | object | Optional `{ defaultWidth, defaultHeight }` for custom size UI |
+
+### Output Types
+
+| Type | Config | Description |
+|------|--------|-------------|
+| `xcode` | `{ "type": "xcode", "path": "..." }` | Render icon and write to Xcode asset catalog |
+| `copy-source` | `{ "type": "copy-source", "format": "svg" }` | Copy source files to export directory |
+
+### Example Collections
+
+**Screenshots** (8 templates × 4 iPhone sizes):
+```json
+{
+  "id": "screenshots",
+  "label": "App Store Screenshots",
+  "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" }
+  ],
+  "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 }
+      ]
+    }
+  ]
+}
+```
+
+**App Icon** (1 template × many Apple sizes + Xcode output):
+```json
+{
+  "id": "icon",
+  "label": "App Icon",
+  "sourceSize": { "width": 1024, "height": 1024 },
+  "borderRadius": 224,
+  "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 }
+      ]
+    }
+  ],
+  "outputs": [
+    { "type": "xcode", "path": "../MyApp/Assets.xcassets/AppIcon.appiconset" }
+  ]
+}
+```
+
+**Icon Explorations** (3 concept variants × preview sizes):
+```json
+{
+  "id": "icon-explorations",
+  "label": "Icon Explorations",
+  "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" }
+  ],
+  "exportSizes": [
+    {
+      "sizes": [
+        { "name": "1024", "label": "1024px", "width": 1024, "height": 1024 },
+        { "name": "512", "label": "512px", "width": 512, "height": 512 }
+      ]
+    }
+  ]
+}
+```
+
+**Logo** (3 variants + SVG source copy):
+```json
+{
+  "id": "logo",
+  "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 }
+      ]
+    }
+  ],
+  "outputs": [
+    { "type": "copy-source", "format": "svg" }
+  ]
+}
+```
+
+**OG Images** (social cards):
+```json
+{
+  "id": "og-images",
+  "label": "Social Cards",
+  "sourceSize": { "width": 1200, "height": 630 },
+  "templates": [
+    { "src": "src/og/default.html", "name": "default", "label": "Default OG" }
+  ],
+  "exportSizes": [
+    { "sizes": [{ "name": "og", "label": "OG Image", "width": 1200, "height": 630 }] }
+  ]
+}
+```
+
+**Favicons** (1 template × many sizes):
+```json
+{
+  "id": "favicon",
+  "label": "Favicons",
+  "sourceSize": { "width": 512, "height": 512 },
+  "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 }
+      ]
+    }
+  ]
+}
+```
+
+## Incremental Builds with manifest.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:
+
+```
+$ open-assets render --all
+  Skipping 01-hero at 1320x2868 (unchanged)
+  Rendering 03-new-screen at 1320x2868...
+    → exports/screenshots/iphone-6.9/03-new-screen.png
+
+Done. 1 asset(s) rendered, 1 skipped (unchanged) in 1.2s.
+```
+
+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`).
+
+## CI/CD with GitHub Actions
+
+Automatically export screenshots on push:
+
+```yaml
+name: Export Marketing Assets
+on:
+  push:
+    paths:
+      - 'marketing/screenshots/**'
+      - 'marketing/screenshots/manifest.json'
+jobs:
+  export:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npx open-assets validate
+      - run: npx open-assets render --all --json --quiet
+      - uses: actions/upload-artifact@v4
+        with:
+          name: screenshots
+          path: exports/
+```
+
+## Common Export Sizes
+
+| Platform | Label | Width | Height |
+|----------|-------|-------|--------|
+| App Store | iPhone 6.9" | 1320 | 2868 |
+| App Store | iPhone 6.7" | 1290 | 2796 |
+| App Store | iPhone 6.5" | 1284 | 2778 |
+| App Store | iPhone 6.1" | 1179 | 2556 |
+| App Store | iPad 12.9" | 2048 | 2732 |
+| Play Store | Phone | 1080 | 1920 |
+| Play Store | Phone (tall) | 1080 | 2400 |
+| Product Hunt | Gallery | 1270 | 760 |
+| Web | OG Image | 1200 | 630 |
+| Mac App Store | Retina | 2880 | 1800 |
+
+## File Structure Convention
+
+```
+project/
+  manifest.json
+  manifest.lock              # Auto-generated cache (gitignored)
+  public/                    # Shared assets (configured via publicDir)
+    logo-round.png
+    social/
+      youtube.svg
+    screenshots/             # Real app screenshots from UI tests
+      01-home.png
+  src/
+    styles.css               # Tailwind input
+    icon.html                # App icon template
+    logo.svg                 # Vector logo template
+    icons/                   # Icon concept explorations
+      concept-a.html
+      concept-b.html
+    screenshots/
+      01-hero.html
+      02-features.html
+    og/                      # OG image templates
+      default.html
+  dist/
+    styles.css               # Compiled Tailwind
+  exports/                   # Rendered output (gitignored)
+    screenshots/
+      iphone-6.9/
+        01-hero.png
+      iphone-6.7/
+    icon/
+      1024/
+        icon.png
+    logo/
+      svg/
+        logo.svg
+```
+
+## License
+
+MIT