@open-assets/open-assets 0.1.12 → 0.3.0

package/README.md

@@ -10,6 +10,17 @@ Dev server and export tool for app marketing assets. Like Storybook, but for mar
 
 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
@@ -48,7 +59,7 @@ Then use `oa` anywhere:
 
 ```bash
 oa dev
-oa render --all
+oa render --force
 oa init
 ```
 
@@ -101,7 +112,7 @@ Claude reads your `assets.json` and `publicDir` to understand the project struct
 
 ```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
@@ -112,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`.
@@ -130,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:
@@ -141,7 +152,7 @@ Reference captured screenshots in your HTML templates:
 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"
 }
 ```
 
@@ -181,12 +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 --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
@@ -200,8 +210,7 @@ Options:
 | `--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 config |
-| `--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 |
 | `--config <path>` | `OPEN_ASSETS_CONFIG` | `assets.json` | Path to config file |
 | `--parallel <count>` | `OPEN_ASSETS_PARALLEL` | `1` | Number of parallel renders |
@@ -215,7 +224,7 @@ 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
@@ -295,7 +304,7 @@ Your project needs a `assets.json` at its root. This file defines the collection
   "version": 1,
   "name": "My App",
   "publicDir": "public",
-  "command": "npx open-assets render --all",
+  "command": "npx open-assets render --force",
   "collections": [ ... ]
 }
 ```
@@ -321,14 +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" }
+    { "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 } },
-    { "name": "iphone-6.7", "label": "iPhone 6.7\"", "size": { "width": 1290, "height": 2796 } }
-  ],
-  "outputs": [
+    { "name": "iphone-6.7", "label": "iPhone 6.7\"", "size": { "width": 1290, "height": 2796 } },
     { "type": "xcode", "path": "../MyApp/Assets.xcassets/AppIcon.appiconset" }
   ]
 }
@@ -344,16 +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 |
-| `export` | array | Flat array of export size definitions |
+| `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) |
-| `outputs` | array | Optional post-render actions |
+| `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 |
@@ -369,8 +378,8 @@ 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" }
   ],
   "export": [
     { "name": "iphone-6.9", "label": "iPhone 6.9\"", "size": { "width": 1320, "height": 2868 } },
@@ -389,14 +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" }
   ],
   "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": [
+    { "name": "120", "label": "120px", "size": { "width": 120, "height": 120 } },
     { "type": "xcode", "path": "../MyApp/Assets.xcassets/AppIcon.appiconset" }
   ]
 }
@@ -410,9 +417,9 @@ 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" }
   ],
   "export": [
     { "name": "1024", "label": "1024px", "size": { "width": 1024, "height": 1024 } },
@@ -428,16 +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" }
+    { "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" }
   ],
   "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": [
+    { "name": "512", "label": "512px", "size": { "width": 512, "height": 512 } },
     { "type": "copy-source", "format": "svg" }
   ]
 }
@@ -450,7 +455,7 @@ 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" }
   ],
   "export": [
     { "name": "og", "label": "OG Image", "size": { "width": 1200, "height": 630 } }
@@ -465,7 +470,7 @@ 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" }
   ],
   "export": [
     { "name": "512", "label": "512px", "size": { "width": 512, "height": 512 } },
@@ -482,7 +487,7 @@ All collections follow the same structure. No `type` field needed.
 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
@@ -494,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 `assets.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
 
@@ -517,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
@@ -544,14 +549,14 @@ jobs:
 ```
 project/
   assets.json
-  assets.lock              # Auto-generated cache (gitignored)
+  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

package/bin/open-assets.mjs

@@ -63,7 +63,7 @@ program
 
     const { startServer } = await import("../lib/server.mjs");
     const port = parseInt(opts.port, 10);
-    startServer(projectDir, {
+    const { port: actualPort } = await startServer(projectDir, {
       port,
       host: opts.host,
       quiet: opts.quiet,
@@ -74,7 +74,8 @@ program
 
     if (opts.open) {
       const open = (await import("open")).default;
-      setTimeout(() => open(`http://${opts.host}:${port}`), 500);
+      const displayHost = opts.host === "0.0.0.0" ? "localhost" : opts.host;
+      setTimeout(() => open(`http://${displayHost}:${actualPort}`), 500);
     }
   });
 
@@ -88,10 +89,10 @@ program
   .option("--tag <tag>", "Render only collections with this tag")
   .option("--template <name>", "Render only the template with this name")
   .option("--size <name>", "Use a named export size from config")
+  .option("--locale <code>", "Render only this locale (e.g. en, ar, ja)")
   .option("--width <px>", "Output width in pixels (custom size)")
   .option("--height <px>", "Output height in pixels (custom size)")
-  .option("--all", "Export at every size defined in the config")
-  .option("--force", "Re-render all assets even if unchanged")
+  .option("-f, --force", "Export at every size and re-render all assets (ignores cache)")
   .option("-o, --output <dir>", "Output directory (env: OPEN_ASSETS_OUTPUT)", env("OPEN_ASSETS_OUTPUT", "./exports"))
   .option("--config <path>", "Path to config file (env: OPEN_ASSETS_CONFIG)", env("OPEN_ASSETS_CONFIG", "assets.json"))
   .option("--parallel <count>", "Number of parallel renders (env: OPEN_ASSETS_PARALLEL)", env("OPEN_ASSETS_PARALLEL", "1"))
@@ -189,8 +190,9 @@ program
   .description("Validate the assets.json and check that all referenced files exist")
   .argument("[dir]", "Project directory containing assets.json", ".")
   .option("--config <path>", "Path to config file", env("OPEN_ASSETS_CONFIG", "assets.json"))
+  .option("--fix", "Interactively fix issues (e.g. remove missing templates)")
   .action(async (dir, opts) => {
-    const { loadConfig } = await import("../lib/manifest.mjs");
+    const { loadConfig, saveConfig } = await import("../lib/manifest.mjs");
     const { validateConfig } = await import("../lib/validate.mjs");
 
     const projectDir = resolve(dir);
@@ -204,7 +206,7 @@ program
 
     console.log(`\n  Validating ${opts.config}...\n`);
 
-    const { checks, errors } = validateConfig(manifest, projectDir);
+    const { checks, errors, missingTemplates, emptyCollections } = validateConfig(manifest, projectDir);
 
     for (const check of checks) {
       console.log(`  ${check.ok ? "\u2713" : "\u2717"} ${check.message}`);
@@ -215,6 +217,58 @@ program
       console.log("  All checks passed.\n");
     } else {
       console.log(`  ${errors} error(s) found.\n`);
+
+      const fixable = missingTemplates.length > 0 || emptyCollections.length > 0;
+
+      if (fixable && opts.fix) {
+        const { createInterface } = await import("readline");
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        const ask = (question) =>
+          new Promise((resolve) => rl.question(question, (answer) => resolve(answer.trim().toLowerCase())));
+
+        let changes = 0;
+
+        for (const missing of missingTemplates) {
+          const answer = await ask(
+            `  Remove template "${missing.templateSrc}" from collection "${missing.collectionId}"? (y/N) `
+          );
+          if (answer === "y" || answer === "yes") {
+            const col = manifest.collections.find((c) => c.id === missing.collectionId);
+            if (col) {
+              col.templates = col.templates.filter((t) => t.src !== missing.templateSrc);
+              changes++;
+            }
+          }
+        }
+
+        // Include collections that were already empty plus ones emptied by template removal
+        const emptyIds = new Set(emptyCollections.map((e) => e.collectionId));
+        for (const col of manifest.collections) {
+          if (!col.templates || col.templates.length === 0) {
+            emptyIds.add(col.id);
+          }
+        }
+
+        for (const collectionId of emptyIds) {
+          const answer = await ask(
+            `  Remove empty collection "${collectionId}"? (y/N) `
+          );
+          if (answer === "y" || answer === "yes") {
+            manifest.collections = manifest.collections.filter((c) => c.id !== collectionId);
+            changes++;
+          }
+        }
+
+        rl.close();
+
+        if (changes > 0) {
+          saveConfig(projectDir, opts.config, manifest);
+          console.log(`\n  Updated ${opts.config} (${changes} fix(es) applied).\n`);
+        }
+      } else if (fixable) {
+        console.log(`  Run with --fix to remove missing templates and empty collections.\n`);
+      }
+
       process.exit(1);
     }
   });

package/lib/add.mjs

@@ -150,8 +150,8 @@ const COLLECTION_PRESETS = [
       { name: "800", label: "800px", size: { width: 800, height: 800 } },
       { name: "400", label: "400px", size: { width: 400, height: 400 } },
       { name: "200", label: "200px", size: { width: 200, height: 200 } },
+      { type: "copy-source", format: "svg" },
     ],
-    outputs: [{ type: "copy-source", format: "svg" }],
   },
   {
     value: "wordmark",
@@ -169,8 +169,8 @@ const COLLECTION_PRESETS = [
       { name: "1200x400", label: "Large", size: { width: 1200, height: 400 } },
       { name: "600x200", label: "Medium", size: { width: 600, height: 200 } },
       { name: "300x100", label: "Small", size: { width: 300, height: 100 } },
+      { type: "copy-source", format: "svg" },
     ],
-    outputs: [{ type: "copy-source", format: "svg" }],
   },
   {
     value: "feature-graphic",
@@ -223,7 +223,7 @@ export async function addCollection(projectDir, configName) {
   // 1. Choose from preset or custom
   const preset = await askSelect(rl, "Choose a collection type:", COLLECTION_PRESETS);
 
-  let id, label, sourceSize, borderRadius, format, tags, exportList, outputs, templateDir, templateName, templateLabel;
+  let id, label, sourceSize, borderRadius, format, tags, exportList, templateDir, templateName, templateLabel;
 
   if (preset.value === "custom") {
     // Custom collection
@@ -256,7 +256,9 @@ export async function addCollection(projectDir, configName) {
     exportList = [
       { name: `${sourceSize.width}x${sourceSize.height}`, label: "Source Size", size: { width: sourceSize.width, height: sourceSize.height } },
     ];
-    outputs = format === "svg" ? [{ type: "copy-source", format: "svg" }] : undefined;
+    if (format === "svg") {
+      exportList.push({ type: "copy-source", format: "svg" });
+    }
     templateDir = `src/${id}` === `src/${id}` && id.includes("/") ? `src` : (sourceSize.width === sourceSize.height ? "src" : `src/${id}`);
     templateDir = `src`;
     templateName = id;
@@ -270,7 +272,6 @@ export async function addCollection(projectDir, configName) {
     format = preset.format;
     tags = preset.tags;
     exportList = preset.export;
-    outputs = preset.outputs;
     templateDir = preset.templateDir;
     templateName = preset.templateName;
     templateLabel = preset.templateLabel;
@@ -310,7 +311,6 @@ export async function addCollection(projectDir, configName) {
     ],
     export: exportList,
   };
-  if (outputs) collection.outputs = outputs;
 
   manifest.collections.push(collection);
 

package/lib/init.mjs

@@ -641,7 +641,7 @@ export async function scaffoldProject(dir) {
   console.log("  Created assets.json");
 
   // Write .gitignore
-  writeFileSync(join(dir, ".gitignore"), "dist/\nexports/\nassets.lock\nnode_modules/\n");
+  writeFileSync(join(dir, ".gitignore"), "dist/\nexports/\nnode_modules/\n");
   console.log("  Created .gitignore");
 
   console.log();

package/lib/list.mjs

@@ -1,4 +1,4 @@
-import { flatSizes } from "./manifest.mjs";
+import { flatSizes, flatOutputs } from "./manifest.mjs";
 
 /**
  * Filter collections by tag. Returns filtered array.
@@ -47,17 +47,15 @@ export function formatCollectionList(manifest, collections) {
       lines.push(`  \u2022 ${template.label || template.name} \u2192 ${template.src}`);
     }
 
-    for (const entry of col.export || []) {
+    for (const entry of flatSizes(col)) {
       lines.push(`  \u21b3 ${entry.label} (${entry.size.width}\u00d7${entry.size.height})`);
     }
 
-    if (col.outputs) {
-      for (const output of col.outputs) {
-        if (output.type === "xcode") {
-          lines.push(`  \u21b3 Xcode: ${output.path}`);
-        } else if (output.type === "copy-source") {
-          lines.push(`  \u21b3 Copy source: ${output.format}`);
-        }
+    for (const output of flatOutputs(col)) {
+      if (output.type === "xcode") {
+        lines.push(`  \u21b3 Xcode: ${output.path}`);
+      } else if (output.type === "copy-source") {
+        lines.push(`  \u21b3 Copy source: ${output.format}`);
       }
     }
   }

package/lib/localization.mjs

@@ -0,0 +1,159 @@
+import { readFileSync, existsSync } from "fs";
+import { resolve } from "path";
+
+/**
+ * Locales that use right-to-left script direction.
+ * Includes base language codes — region variants (e.g. "ar-SA") are
+ * detected by matching the base language.
+ */
+const RTL_LANGUAGES = new Set([
+  "ar",  // Arabic
+  "he",  // Hebrew
+  "fa",  // Persian (Farsi)
+  "ur",  // Urdu
+  "yi",  // Yiddish
+  "ps",  // Pashto
+  "sd",  // Sindhi
+  "ku",  // Kurdish (Sorani)
+  "dv",  // Divehi (Maldivian)
+  "ug",  // Uyghur
+]);
+
+/**
+ * Check if a locale uses right-to-left text direction.
+ * Matches exact locale codes and base language (e.g. "ar-SA" → "ar").
+ */
+export function isRtl(locale) {
+  if (RTL_LANGUAGES.has(locale)) return true;
+  const base = locale.split("-")[0];
+  return RTL_LANGUAGES.has(base);
+}
+
+/**
+ * Get text direction for a locale: "rtl" or "ltr".
+ */
+export function getDirection(locale) {
+  return isRtl(locale) ? "rtl" : "ltr";
+}
+
+/**
+ * Load and parse a localizations JSON file (iOS .xcstrings-inspired format).
+ *
+ * Expected format:
+ * {
+ *   "sourceLanguage": "en",
+ *   "strings": {
+ *     "key_name": {
+ *       "localizations": {
+ *         "en": { "value": "Hello" },
+ *         "ar": { "value": "مرحبا" }
+ *       }
+ *     }
+ *   }
+ * }
+ */
+export function loadLocalizations(projectDir, localizationsPath) {
+  const fullPath = resolve(projectDir, localizationsPath);
+  if (!existsSync(fullPath)) {
+    throw new Error(`Localizations file not found: ${localizationsPath}`);
+  }
+  try {
+    return JSON.parse(readFileSync(fullPath, "utf-8"));
+  } catch (err) {
+    throw new Error(`Invalid JSON in ${localizationsPath}: ${err.message}`);
+  }
+}
+
+/**
+ * Resolve all localized string values for a given locale.
+ * Falls back: exact locale → base language → source language.
+ *
+ * Returns a flat { key: value } map.
+ */
+export function resolveStrings(localizations, locale) {
+  const strings = {};
+  const sourceLanguage = localizations.sourceLanguage || "en";
+
+  for (const [key, entry] of Object.entries(localizations.strings || {})) {
+    const l10ns = entry.localizations || {};
+    const value =
+      l10ns[locale]?.value ??
+      l10ns[locale.split("-")[0]]?.value ??
+      l10ns[sourceLanguage]?.value;
+    if (value !== undefined) {
+      strings[key] = value;
+    }
+  }
+
+  return strings;
+}
+
+/**
+ * Collect all unique locales defined across all string entries.
+ * If filterLocales is provided, returns only those that exist in the data.
+ * Results are sorted alphabetically.
+ */
+export function getLocales(localizations, filterLocales) {
+  const allLocales = new Set();
+  for (const entry of Object.values(localizations.strings || {})) {
+    for (const locale of Object.keys(entry.localizations || {})) {
+      allLocales.add(locale);
+    }
+  }
+
+  if (filterLocales && filterLocales.length > 0) {
+    return filterLocales.filter((l) => allLocales.has(l));
+  }
+
+  return [...allLocales].sort();
+}
+
+/**
+ * JavaScript snippet injected into the Puppeteer page to perform
+ * localization substitution on the live DOM.
+ *
+ * Replaces {{key}} placeholders in text nodes with localized values.
+ * Processes {{n:NUMBER}} patterns in values for locale-aware number formatting.
+ * Sets lang and dir attributes on <html>.
+ */
+export function buildLocalizationScript(strings, locale, direction) {
+  return `
+    (function() {
+      document.documentElement.lang = ${JSON.stringify(locale)};
+
+      const strings = ${JSON.stringify(strings)};
+      const locale = ${JSON.stringify(locale)};
+      const dir = ${JSON.stringify(direction)};
+      const formatter = new Intl.NumberFormat(locale);
+
+      function processValue(value) {
+        return value.replace(/\\{\\{n:(\\d+(?:\\.\\d+)?)\\}\\}/g, function(_, num) {
+          return formatter.format(parseFloat(num));
+        });
+      }
+
+      const walker = document.createTreeWalker(
+        document.documentElement,
+        NodeFilter.SHOW_TEXT
+      );
+      while (walker.nextNode()) {
+        var node = walker.currentNode;
+        var text = node.textContent;
+        var changed = false;
+        text = text.replace(/\\{\\{([a-zA-Z_][\\w.]*)\\}\\}/g, function(match, key) {
+          if (strings[key] !== undefined) {
+            changed = true;
+            return processValue(strings[key]);
+          }
+          return match;
+        });
+        if (changed) {
+          node.textContent = text;
+          if (dir === "rtl") {
+            node.parentElement.dir = dir;
+          }
+        }
+      }
+    })();
+  `;
+}