@open-assets/open-assets 0.1.12 → 0.3.0

package/lib/server.mjs

@@ -146,7 +146,7 @@ export async function startServer(projectDir, options = {}, renderer) {
     // API: render screenshot (unified for all collection types)
     if (req.method === "POST" && pathname === "/api/render-screenshot") {
       try {
-        const { file, width, height, sourceW, sourceH } = JSON.parse(
+        const { file, width, height, sourceW, sourceH, background } = JSON.parse(
           await readBody(req)
         );
         if (!file || !width || !height) {
@@ -158,7 +158,7 @@ export async function startServer(projectDir, options = {}, renderer) {
         const sw = sourceW || width;
         const sh = sourceH || height;
         log(`Rendering ${file} at ${width}x${height} (source ${sw}x${sh})...`);
-        const buffer = await renderScreenshot(projectDir, file, width, height, sw, sh);
+        const buffer = await renderScreenshot(projectDir, file, width, height, sw, sh, { background });
         res.writeHead(200, {
           "Content-Type": "image/png",
           "Content-Length": buffer.length,
@@ -181,7 +181,8 @@ export async function startServer(projectDir, options = {}, renderer) {
           res.writeHead(404, { "Content-Type": "application/json" });
           return res.end(JSON.stringify({ ok: false, error: "Collection not found" }));
         }
-        const output = col.outputs?.[outputIndex || 0];
+        const outputs = (col.export || []).filter((e) => e.type);
+        const output = outputs[outputIndex || 0];
         if (!output) {
           res.writeHead(404, { "Content-Type": "application/json" });
           return res.end(JSON.stringify({ ok: false, error: "Output not found" }));
@@ -245,30 +246,50 @@ export async function startServer(projectDir, options = {}, renderer) {
     res.end();
   });
 
-  server.listen(port, host, () => {
-    log();
-    log(`  open-assets dev server`);
-    log(`  ───────────────────────`);
-    log(`  Local:   http://${host}:${port}`);
-    if (host === "0.0.0.0") {
-      log(`  Network: http://<your-ip>:${port}`);
-    }
-    log(`  Project: ${projectDir}`);
-    if (staticDirs.length > 0) {
-      log(`  Static:  ${staticDirs.join(", ")}`);
-    }
-    log();
-  });
+  const maxRetries = 10;
+  let currentPort = port;
+  let resolved = false;
+
+  const actualPort = await new Promise((resolvePort) => {
+    function tryListen() {
+      server.once("error", (err) => {
+        if (err.code === "EADDRINUSE") {
+          if (currentPort - port >= maxRetries) {
+            console.error(`Error: Ports ${port}–${currentPort} are all in use.`);
+            process.exit(1);
+          }
+          currentPort++;
+          server.close(() => tryListen());
+          return;
+        }
+        throw err;
+      });
 
-  server.on("error", (err) => {
-    if (err.code === "EADDRINUSE") {
-      console.error(`Error: Port ${port} is already in use.`);
-      console.error(`Try a different port: open-assets dev --port ${port + 1}`);
-      process.exit(1);
+      server.listen(currentPort, host, () => {
+        if (resolved) return;
+        resolved = true;
+        const displayHost = host === "0.0.0.0" ? "localhost" : host;
+        if (currentPort !== port) {
+          log();
+          log(`  Port ${port} is in use, using ${currentPort} instead.`);
+        }
+        log();
+        log(`  Open Assets is running on http://${displayHost}:${currentPort}`);
+        log();
+        log(`  Project: ${projectDir}`);
+        if (staticDirs.length > 0) {
+          log(`  Static:  ${staticDirs.join(", ")}`);
+        }
+        log();
+        resolvePort(currentPort);
+      });
     }
-    throw err;
+
+    tryListen();
   });
 
+  return { port: actualPort };
+
   function cleanup() {
     for (const w of watchers) w.close();
     for (const client of sseClients) client.end();

package/lib/validate.mjs

@@ -1,6 +1,7 @@
 import { existsSync } from "fs";
 import { resolve } from "path";
-import { flatSizes } from "./manifest.mjs";
+import { flatSizes, flatOutputs } from "./manifest.mjs";
+import { loadLocalizations, getLocales } from "./localization.mjs";
 
 /**
  * Validate a config object and check that referenced files exist.
@@ -12,6 +13,8 @@ import { flatSizes } from "./manifest.mjs";
  */
 export function validateConfig(manifest, projectDir) {
   const checks = [];
+  const missingTemplates = [];
+  const emptyCollections = [];
   let errors = 0;
 
   const ok = (msg) => checks.push({ ok: true, message: msg });
@@ -31,7 +34,7 @@ export function validateConfig(manifest, projectDir) {
     ok(`${manifest.collections.length} collection(s) defined`);
   } else {
     fail("Missing or empty 'collections' array");
-    return { checks, errors };
+    return { checks, errors, missingTemplates, emptyCollections };
   }
 
   // Check each collection
@@ -54,6 +57,7 @@ export function validateConfig(manifest, projectDir) {
 
     if (!col.templates || col.templates.length === 0) {
       fail(`Collection "${col.id}" has no templates`);
+      emptyCollections.push({ collectionId: col.id });
     } else {
       for (const template of col.templates) {
         if (!template.src) {
@@ -65,6 +69,11 @@ export function validateConfig(manifest, projectDir) {
           ok(`${template.src} exists`);
         } else {
           fail(`${template.src} not found`);
+          missingTemplates.push({
+            collectionId: col.id,
+            templateSrc: template.src,
+            templateName: template.name || template.label,
+          });
         }
       }
     }
@@ -74,17 +83,41 @@ export function validateConfig(manifest, projectDir) {
       ok(`Collection "${col.id}" has ${sizes.length} export size(s)`);
     }
 
-    // Validate outputs
-    if (col.outputs) {
-      for (const output of col.outputs) {
-        if (!output.type) {
-          fail(`Collection "${col.id}" has an output without 'type'`);
-        } else {
-          ok(`Output: ${output.type}`);
+    // Validate localizations if configured
+    if (col.localizations) {
+      const l10nPath = resolve(projectDir, col.localizations);
+      if (!existsSync(l10nPath)) {
+        fail(`Collection "${col.id}" localizations file not found: ${col.localizations}`);
+      } else {
+        try {
+          const l10nData = loadLocalizations(projectDir, col.localizations);
+          if (!l10nData.sourceLanguage) {
+            fail(`Collection "${col.id}" localizations missing "sourceLanguage"`);
+          }
+          if (!l10nData.strings || Object.keys(l10nData.strings).length === 0) {
+            fail(`Collection "${col.id}" localizations has no strings defined`);
+          } else {
+            const locales = getLocales(l10nData, col.locales);
+            ok(`Collection "${col.id}" localizations: ${Object.keys(l10nData.strings).length} key(s), ${locales.length} locale(s)`);
+            if (col.locales) {
+              const missing = col.locales.filter((l) => !locales.includes(l));
+              for (const m of missing) {
+                fail(`Collection "${col.id}" requests locale "${m}" but it is not defined in ${col.localizations}`);
+              }
+            }
+          }
+        } catch (err) {
+          fail(`Collection "${col.id}" localizations error: ${err.message}`);
         }
       }
     }
+
+    // Validate outputs (export entries with a type field)
+    const outputs = flatOutputs(col);
+    for (const output of outputs) {
+      ok(`Output: ${output.type}`);
+    }
   }
 
-  return { checks, errors };
+  return { checks, errors, missingTemplates, emptyCollections };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-assets/open-assets",
-  "version": "0.1.12",
+  "version": "0.3.0",
   "description": "Dev server and export tool for app screenshots, icons, and logos. Like Storybook for marketing assets.",
   "type": "module",
   "bin": {
@@ -39,7 +39,7 @@
     "access": "public"
   },
   "scripts": {
-    "assets": "node bin/open-assets.mjs render --all -o ./public/img",
+    "assets": "node bin/open-assets.mjs render --force -o ./public/img",
     "test": "node --experimental-vm-modules node_modules/.bin/jest",
     "release": "./scripts/release.sh"
   },

package/public/viewer.html

@@ -254,46 +254,46 @@
         const sh = col.sourceSize.height;
         const hasMultipleTemplates = col.templates.length > 1;
 
-        // Outputs (e.g., Xcode)
-        if (col.outputs) {
-          for (let i = 0; i < col.outputs.length; i++) {
-            const output = col.outputs[i];
-            if (output.type === 'xcode') {
-              const sectionLabel = document.createElement('div');
-              sectionLabel.className = 'section-label';
-              sectionLabel.textContent = 'Xcode';
-              exportDropdown.appendChild(sectionLabel);
-
-              const btn = document.createElement('button');
-              btn.innerHTML = 'Export to Xcode <span class="dim">.appiconset</span>';
-              btn.addEventListener('click', () => runOutput(col.id, i));
-              exportDropdown.appendChild(btn);
-
-              exportDropdown.appendChild(document.createElement('hr'));
-            } else if (output.type === 'copy-source') {
-              const sectionLabel = document.createElement('div');
-              sectionLabel.className = 'section-label';
-              sectionLabel.textContent = output.format.toUpperCase();
-              exportDropdown.appendChild(sectionLabel);
-
-              // SVG download for each template
-              for (const template of col.templates) {
-                if (template.src.endsWith('.' + output.format)) {
-                  const btn = document.createElement('button');
-                  const displayName = hasMultipleTemplates ? template.label : `Download ${output.format.toUpperCase()}`;
-                  btn.innerHTML = `${displayName} <span class="dim">${output.format}</span>`;
-                  btn.addEventListener('click', () => downloadSource(template));
-                  exportDropdown.appendChild(btn);
-                }
+        // Outputs (e.g., Xcode, copy-source) — export entries with a type field
+        const allExports = col.export || [];
+        const outputs = allExports.filter(e => e.type);
+        for (let i = 0; i < outputs.length; i++) {
+          const output = outputs[i];
+          if (output.type === 'xcode') {
+            const sectionLabel = document.createElement('div');
+            sectionLabel.className = 'section-label';
+            sectionLabel.textContent = 'Xcode';
+            exportDropdown.appendChild(sectionLabel);
+
+            const btn = document.createElement('button');
+            btn.innerHTML = 'Export to Xcode <span class="dim">.appiconset</span>';
+            btn.addEventListener('click', () => runOutput(col.id, i));
+            exportDropdown.appendChild(btn);
+
+            exportDropdown.appendChild(document.createElement('hr'));
+          } else if (output.type === 'copy-source') {
+            const sectionLabel = document.createElement('div');
+            sectionLabel.className = 'section-label';
+            sectionLabel.textContent = output.format.toUpperCase();
+            exportDropdown.appendChild(sectionLabel);
+
+            // SVG download for each template
+            for (const template of col.templates) {
+              if (template.src.endsWith('.' + output.format)) {
+                const btn = document.createElement('button');
+                const displayName = hasMultipleTemplates ? template.label : `Download ${output.format.toUpperCase()}`;
+                btn.innerHTML = `${displayName} <span class="dim">${output.format}</span>`;
+                btn.addEventListener('click', () => downloadSource(template));
+                exportDropdown.appendChild(btn);
               }
-
-              exportDropdown.appendChild(document.createElement('hr'));
             }
+
+            exportDropdown.appendChild(document.createElement('hr'));
           }
         }
 
-        // Export sizes
-        const sizes = col.export || [];
+        // Export sizes (entries without a type field)
+        const sizes = allExports.filter(e => !e.type);
         if (sizes.length > 0) {
           const sectionLabel = document.createElement('div');
           sectionLabel.className = 'section-label';

package/skills/open-assets/SKILL.md

@@ -15,14 +15,13 @@ open-assets is a dev server and export tool for app marketing assets — screens
 open-assets dev
 
 # Or with Tailwind
-concurrently "npx @tailwindcss/cli -i src/styles.css -o dist/styles.css --watch" "open-assets dev"
+concurrently "npx @tailwindcss/cli -i assets/styles.css -o dist/styles.css --watch" "open-assets dev"
 
 # Headless render
 open-assets render --collection screenshots --size iphone-6.9
-open-assets render --collection icon --all
-open-assets render --all
-open-assets render --template 01-hero --all
-open-assets render --force  # ignore cache, re-render everything
+open-assets render --collection icon --force
+open-assets render --force
+open-assets render --template 01-hero --force
 ```
 
 ## Concepts
@@ -44,7 +43,7 @@ The `assets.json` at the project root defines all asset collections. All collect
   "version": 1,
   "name": "App Display Name",
   "publicDir": "public",
-  "command": "npx open-assets render --all",
+  "command": "npx open-assets render --force",
   "collections": [
     {
       "id": "unique-id",
@@ -52,12 +51,11 @@ The `assets.json` at the project root defines all asset collections. All collect
       "sourceSize": { "width": 440, "height": 956 },
       "borderRadius": 4,
       "templates": [
-        { "src": "src/screenshots/01-hero.html", "name": "01-hero", "label": "Hero" }
+        { "src": "assets/screenshots/01-hero.html", "name": "01-hero", "label": "Hero" }
       ],
       "export": [
         { "name": "iphone-6.9", "label": "iPhone 6.9\"", "size": { "width": 1320, "height": 2868 } }
       ],
-      "outputs": [],
       "customExport": { "defaultWidth": 1320, "defaultHeight": 2868 }
     }
   ]
@@ -73,12 +71,13 @@ The `assets.json` at the project root defines all asset collections. All collect
 | `sourceSize` | object | `{ width, height }` — dimensions templates are authored at |
 | `borderRadius` | number | Border radius for preview frames (px) |
 | `templates` | array | Source files: `{ src, name, label }` |
-| `export` | array | Export sizes: `[{ name, label, size: { width, height }, outFile? }]` |
-| `outputs` | array | Post-render actions (optional) |
+| `export` | array | Export sizes and output actions. Entries with a `type` field are post-render actions |
 | `customExport` | object | Custom size defaults for UI (optional) |
 
 ### 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 |
@@ -94,8 +93,8 @@ The `assets.json` at the project root defines all asset collections. All collect
   "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" }
+    { "src": "assets/screenshots/01-hero.html", "name": "01-hero", "label": "Hero" },
+    { "src": "assets/screenshots/02-features.html", "name": "02-features", "label": "Features" }
   ],
   "export": [
     { "name": "iphone-6.9", "label": "iPhone 6.9\"", "size": { "width": 1320, "height": 2868 } },
@@ -112,13 +111,13 @@ The `assets.json` at the project root defines all asset collections. All collect
   "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" }
   ],
   "export": [
     { "name": "1024", "label": "1024px", "size": { "width": 1024, "height": 1024 } },
-    { "name": "180", "label": "180px", "size": { "width": 180, "height": 180 } }
-  ],
-  "outputs": [{ "type": "xcode", "path": "../MyApp/Assets.xcassets/AppIcon.appiconset" }]
+    { "name": "180", "label": "180px", "size": { "width": 180, "height": 180 } },
+    { "type": "xcode", "path": "../MyApp/Assets.xcassets/AppIcon.appiconset" }
+  ]
 }
 ```
 
@@ -130,8 +129,8 @@ The `assets.json` at the project root defines all asset collections. All collect
   "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": "assets/icons/concept-a.html", "name": "concept-a", "label": "Concept A" },
+    { "src": "assets/icons/concept-b.html", "name": "concept-b", "label": "Concept B" }
   ],
   "export": [
     { "name": "1024", "label": "1024px", "size": { "width": 1024, "height": 1024 } }
@@ -146,14 +145,14 @@ The `assets.json` at the project root defines all asset collections. All collect
   "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": "assets/logo.svg", "name": "logo", "label": "Logo" },
+    { "src": "assets/logo-dark.svg", "name": "logo-dark", "label": "Dark" }
   ],
   "export": [
     { "name": "1024", "label": "1024px", "size": { "width": 1024, "height": 1024 } },
-    { "name": "512", "label": "512px", "size": { "width": 512, "height": 512 } }
-  ],
-  "outputs": [{ "type": "copy-source", "format": "svg" }]
+    { "name": "512", "label": "512px", "size": { "width": 512, "height": 512 } },
+    { "type": "copy-source", "format": "svg" }
+  ]
 }
 ```
 
@@ -164,7 +163,7 @@ The `assets.json` at the project root defines all asset collections. All collect
   "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" }
   ],
   "export": [
     { "name": "og", "label": "OG Image", "size": { "width": 1200, "height": 630 } }
@@ -181,7 +180,7 @@ The `assets.json` at the project root defines all asset collections. All collect
 | `open-assets dev [dir]` | Start dev server with live preview and export UI |
 | `open-assets render [dir]` | Render assets headlessly via CLI |
 | `open-assets list [dir]` | List all collections and templates in the config |
-| `open-assets validate [dir]` | Validate assets.json and check referenced files exist |
+| `open-assets validate [dir]` | Validate assets.json and check referenced files exist. Use `--fix` to interactively remove missing templates |
 | `open-assets init [dir]` | Scaffold a new assets.json and example assets |
 | `open-assets add collection [dir]` | Add a new collection (from presets or custom) |
 | `open-assets add template [dir]` | Add a new template to an existing collection |
@@ -195,15 +194,15 @@ The `assets.json` at the project root defines all asset collections. All collect
 | `--collection <id>` | Render only the collection with this ID |
 | `--template <name>` | Render only the template with this name |
 | `--size <name>` | Use a named export size from config |
-| `--all` | Export at every size defined in the config |
-| `--force` | Re-render all assets even if unchanged |
+| `--locale <code>` | Render only this locale (e.g. `en`, `ar`, `ja`) |
+| `-f, --force` | Export at every size and re-render all (ignores cache) |
 | `-o, --output <dir>` | Output directory (default: `./exports`) |
 | `--json` | Output results as JSON |
 | `-q, --quiet` | Suppress progress logs |
 
 Flags compose naturally:
 - `--collection screenshots --template 01-hero --size iphone-6.9` → single template, single size
-- `--collection screenshots --template 01-hero --all` → one template, all sizes
+- `--collection screenshots --template 01-hero --force` → one template, all sizes
 - `--collection screenshots --size iphone-6.9` → all templates, one size
 
 ### add commands
@@ -337,19 +336,145 @@ The `render` command maintains a `assets.lock` file with SHA256 checksums of sou
 
 Note: only source HTML/SVG files are checksummed. Changes to referenced assets (images in publicDir, compiled CSS) will not trigger re-renders — use `--force` when those change.
 
+## Localization (i18n)
+
+Collections can be localized so that templates render in multiple languages. When localizations are configured, each template is rendered once per locale, producing locale-specific exports with proper text direction (LTR/RTL).
+
+### Localizations file
+
+Create a JSON file (iOS `.xcstrings`-inspired format) that maps string keys to per-locale values:
+
+```json
+{
+  "sourceLanguage": "en",
+  "strings": {
+    "hero_title": {
+      "localizations": {
+        "en": { "value": "Track your tax days" },
+        "ar": { "value": "تتبع أيام الضرائب الخاصة بك" },
+        "ja": { "value": "税金の日を追跡する" },
+        "de": { "value": "Verfolge deine Steuertage" }
+      }
+    },
+    "day_count_label": {
+      "localizations": {
+        "en": { "value": "You have {{n:183}} days remaining" },
+        "ar": { "value": "لديك {{n:183}} يوم متبقي" },
+        "de": { "value": "Sie haben {{n:183}} Tage übrig" }
+      }
+    }
+  }
+}
+```
+
+**Number formatting:** Use `{{n:NUMBER}}` inside localized values for locale-aware number formatting (e.g., `1,234` in English, `1.234` in German). Numbers are formatted using `Intl.NumberFormat` for the target locale.
+
+### Wiring localizations to a collection
+
+Add `localizations` (path to the JSON file) and optionally `locales` (filter to specific locales) to a collection in `assets.json`:
+
+```json
+{
+  "id": "screenshots",
+  "label": "App Store Screenshots",
+  "sourceSize": { "width": 440, "height": 956 },
+  "localizations": "localizations.json",
+  "locales": ["en", "ar", "ja", "de"],
+  "templates": [
+    { "src": "assets/screenshots/01-hero.html", "name": "01-hero", "label": "Hero" }
+  ],
+  "export": [
+    { "name": "iphone-6.9", "label": "iPhone 6.9\"", "size": { "width": 1320, "height": 2868 } }
+  ]
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `localizations` | string | Path to the localizations JSON file (relative to project root) |
+| `locales` | string[] | Optional filter — render only these locales. Omit to render all locales in the file. |
+
+### Using placeholders in templates
+
+Templates use `{{key}}` mustache-style placeholders that get replaced with localized values before rendering:
+
+```html
+<h1>{{hero_title}}</h1>
+<p>{{day_count_label}}</p>
+```
+
+The source language values serve as the default/fallback content visible during development. At render time, placeholders are substituted with the localized value for each target locale.
+
+### RTL support
+
+Right-to-left locales (Arabic, Hebrew, Persian, Urdu, etc.) are automatically detected. For RTL locales, the renderer sets `dir="rtl"` and `lang` on the `<html>` element before taking the screenshot.
+
+**Design templates with RTL in mind:**
+- Use `logical` CSS properties (`margin-inline-start` instead of `margin-left`, `padding-inline-end` instead of `padding-right`)
+- Use flexbox `gap` instead of directional margins between items
+- Avoid hardcoded `text-align: left` — use `text-align: start` instead
+- For layouts that must flip in RTL, use `[dir="rtl"]` CSS selectors:
+  ```css
+  .arrow { transform: rotate(0deg); }
+  [dir="rtl"] .arrow { transform: rotate(180deg); }
+  ```
+
+### Output structure with locales
+
+When localizations are active, locale codes are inserted into the output path:
+
+```
+exports/
+  screenshots/
+    en/
+      iphone-6.9/
+        01-hero.png
+    ar/
+      iphone-6.9/
+        01-hero.png
+    ja/
+      iphone-6.9/
+        01-hero.png
+```
+
+With `outFile`, use the `{locale}` template variable:
+```json
+{ "outFile": "output/{locale}/{template}.png" }
+```
+
+### CLI
+
+```bash
+# Render all locales for a collection
+open-assets render --collection screenshots --force
+
+# Render only Arabic
+open-assets render --collection screenshots --force --locale ar
+
+# Render a single template in Japanese
+open-assets render --collection screenshots --template 01-hero --locale ja --force
+```
+
+### Locale fallback order
+
+When resolving a string for a locale:
+1. Exact match (e.g., `es-419`)
+2. Base language (e.g., `es`)
+3. Source language (e.g., `en`)
+
 ## File Structure Convention
 
 ```
 project/
   assets.json
-  assets.lock          # Auto-generated, add to .gitignore
+  assets.lock          # Auto-generated cache (commit this)
   public/                # Shared assets (images, logos, icons, photos)
     logo-round.png
     social/
       youtube.svg
     screenshots/         # Real app screenshots for use in templates
       01.png
-  src/
+  assets/
     styles.css           # Tailwind input
     icon.html            # App icon template
     icons/               # Icon concept explorations