@open-assets/open-assets 0.4.0 → 0.5.1

package/lib/renderer.mjs

@@ -2,128 +2,291 @@ import { launch } from "puppeteer";
 import { resolve } from "path";
 import { writeFileSync, mkdirSync, readdirSync, unlinkSync } from "fs";
 
-let browser = null;
+// The browser is launched once per process and shared. Storing the launch
+// promise (not the instance) makes concurrent callers await the same launch
+// instead of racing to spawn duplicate Chromium processes.
+let browserPromise = null;
+
+// Pages are pooled and reused across renders: page.goto fully replaces the
+// document, and newPage()/close() cost 100-300ms per image in headless mode.
+const pagePool = [];
 
 async function getBrowser() {
-  if (!browser || !browser.connected) {
-    browser = await launch({ headless: true });
+  for (;;) {
+    if (!browserPromise) {
+      browserPromise = launch({
+        headless: true,
+        // Pages render concurrently; without these flags Chromium throttles
+        // timers and frames in non-active tabs, stalling background renders.
+        args: [
+          "--disable-background-timer-throttling",
+          "--disable-backgrounding-occluded-windows",
+          "--disable-renderer-backgrounding",
+        ],
+      }).catch((err) => {
+        browserPromise = null;
+        throw err;
+      });
+    }
+    const current = browserPromise;
+    const browser = await current;
+    if (browser.connected) return browser;
+    // Browser died; clear the cached promise (unless someone already
+    // replaced it) and relaunch.
+    if (browserPromise === current) browserPromise = null;
+  }
+}
+
+/**
+ * Pre-launch the shared browser so the first render doesn't pay the ~2s
+ * launch cost interactively.
+ */
+export function warmupBrowser() {
+  return getBrowser();
+}
+
+// CDP sessions used to keep pooled pages renderable while they sit in the
+// background. Keyed weakly so a closed page's session is not retained.
+const pageSessions = new WeakMap();
+
+async function acquirePage() {
+  const browser = await getBrowser();
+  while (pagePool.length > 0) {
+    const page = pagePool.pop();
+    // Drop pages tied to a closed or replaced browser instance
+    if (!page.isClosed() && page.browser() === browser) return page;
+  }
+  // Every page gets its own browser context, which puts it in its own window.
+  // Pages sharing a context are tabs in one window, and headless Chrome only
+  // drives the rendering pipeline for the active tab: the rest are frozen, so
+  // anything that waits on that pipeline (timers, document.fonts.ready,
+  // img.decode()) never settles and the render hangs until protocolTimeout.
+  const context = await browser.createBrowserContext();
+  const page = await context.newPage();
+  // Separate windows still compete for focus, so tell each page to consider
+  // itself focused. Without this a page can be treated as occluded and stall
+  // the same way a background tab does.
+  try {
+    const session = await page.createCDPSession();
+    await session.send("Emulation.setFocusEmulationEnabled", { enabled: true });
+    pageSessions.set(page, session);
+  } catch {
+    // Best-effort: the browser context already prevents the hard stall.
   }
-  return browser;
+  return page;
+}
+
+/**
+ * Assert that a page is in the "active" lifecycle state. Chromium may freeze a
+ * page that has been idle in the pool; a frozen page runs no timers, so the
+ * readiness barrier in settle() would never resolve.
+ */
+async function activatePage(page) {
+  const session = pageSessions.get(page);
+  if (!session) return;
+  try {
+    await session.send("Page.setWebLifecycleState", { state: "active" });
+  } catch {
+    // Best-effort; not all builds implement this on every target.
+  }
+}
+
+function releasePage(page) {
+  if (page && !page.isClosed()) pagePool.push(page);
 }
 
 export async function closeBrowser() {
-  if (browser) {
-    await browser.close();
-    browser = null;
+  pagePool.length = 0;
+  if (browserPromise) {
+    const pending = browserPromise;
+    browserPromise = null;
+    try {
+      const browser = await pending;
+      await browser.close();
+    } catch {
+      // Launch already failed; nothing to close.
+    }
   }
 }
 
 /**
- * Render an HTML file to an image buffer at the given dimensions.
- * Scales from sourceSize to target size via CSS zoom.
+ * Deterministic readiness barrier, replacing fixed sleeps: yields a macrotask
+ * (so MutationObserver-driven DOM updates like locale image swaps have run),
+ * forces a layout (so font loads triggered by first layout have started),
+ * then waits for fonts and image decodes. No frame waits here: rAF can stall
+ * indefinitely in a non-active tab, and the screenshot capture itself forces
+ * a fresh frame that flushes pending style and layout.
+ */
+async function settle(page) {
+  await page.evaluate(async () => {
+    await new Promise((r) => setTimeout(r, 0));
+    document.documentElement.getBoundingClientRect();
+    await document.fonts.ready;
+    const images = document.images ? Array.from(document.images) : [];
+    await Promise.all(images.map((img) => img.decode().catch(() => {})));
+  });
+}
+
+/**
+ * Render an HTML file at multiple sizes from a single navigation.
+ * The page is loaded (and localized) once; each variant re-applies
+ * viewport + CSS zoom and takes its own screenshot.
+ *
  * @param {string} projectDir
  * @param {string} htmlFile
- * @param {number} width
- * @param {number} height
  * @param {number} sourceW
  * @param {number} sourceH
- * @param {{ format?: "png"|"jpeg", quality?: number, background?: string, localization?: { strings: object, locale: string, direction: string } }} [options]
+ * @param {{ width: number, height: number, format?: "png"|"jpeg", quality?: number }[]} variants
+ * @param {{ background?: string, localization?: { strings: object, locale: string, direction: string }, timeout?: number }} [options]
+ * @returns {Promise<Buffer[]>} Screenshot buffers in variant order
  */
-export async function renderScreenshot(
+export async function renderVariants(
   projectDir,
   htmlFile,
-  width,
-  height,
   sourceW,
   sourceH,
+  variants,
   options = {}
 ) {
-  const b = await getBrowser();
-  const page = await b.newPage();
+  const page = await acquirePage();
+  try {
+    await activatePage(page);
+    const first = variants[0];
+    await page.setViewport({
+      width: first.width,
+      height: first.height,
+      deviceScaleFactor: 1,
+    });
 
-  const scale = Math.max(width / sourceW, height / sourceH);
+    const filePath = resolve(projectDir, htmlFile);
+    await page.goto(`file://${filePath}`, {
+      waitUntil: "load",
+      timeout: options.timeout || 30000,
+    });
 
-  await page.setViewport({ width, height, deviceScaleFactor: 1 });
+    // Inject localized strings and set lang before rendering
+    if (options.localization) {
+      const { strings, locale, direction } = options.localization;
+      await page.evaluate((strings, locale, dir) => {
+        // Set lang on root for font selection; do NOT set dir on root
+        // because it flips the entire CSS layout (flexbox, margins, etc.)
+        // which breaks fixed-pixel marketing layouts.
+        document.documentElement.lang = locale;
 
-  const filePath = resolve(projectDir, htmlFile);
-  await page.goto(`file://${filePath}`, { waitUntil: "networkidle0" });
-  await new Promise((r) => setTimeout(r, 500));
+        const formatter = new Intl.NumberFormat(locale);
 
-  // Inject localized strings and set lang/dir before rendering
-  if (options.localization) {
-    const { strings, locale, direction } = options.localization;
-    await page.evaluate((strings, locale, dir) => {
-      // Set lang on root for font selection; do NOT set dir on root
-      // because it flips the entire CSS layout (flexbox, margins, etc.)
-      // which breaks fixed-pixel marketing layouts.
-      document.documentElement.lang = locale;
+        function processValue(value) {
+          return value.replace(/\{\{n:(\d+(?:\.\d+)?)\}\}/g, (_, num) => {
+            return formatter.format(parseFloat(num));
+          });
+        }
 
-      const formatter = new Intl.NumberFormat(locale);
+        const walker = document.createTreeWalker(
+          document.documentElement,
+          NodeFilter.SHOW_TEXT
+        );
+        while (walker.nextNode()) {
+          const node = walker.currentNode;
+          let text = node.textContent;
+          let changed = false;
+          text = text.replace(/\{\{([a-zA-Z_][\w.]*)\}\}/g, (match, key) => {
+            if (strings[key] !== undefined) {
+              changed = true;
+              return processValue(strings[key]);
+            }
+            return match;
+          });
+          if (changed) {
+            node.textContent = text;
+            // Apply text direction on the parent element so RTL text
+            // renders correctly without flipping the overall page layout.
+            if (dir === "rtl") {
+              node.parentElement.dir = dir;
+            }
+          }
+        }
+      }, strings, locale, direction);
+    }
 
-      function processValue(value) {
-        return value.replace(/\{\{n:(\d+(?:\.\d+)?)\}\}/g, (_, num) => {
-          return formatter.format(parseFloat(num));
-        });
-      }
+    // Handle background: transparent by default for PNG, or use specified color
+    if (options.background) {
+      await page.evaluate((color) => {
+        document.documentElement.style.backgroundColor = color;
+      }, options.background);
+    }
 
-      const walker = document.createTreeWalker(
-        document.documentElement,
-        NodeFilter.SHOW_TEXT
-      );
-      while (walker.nextNode()) {
-        const node = walker.currentNode;
-        let text = node.textContent;
-        let changed = false;
-        text = text.replace(/\{\{([a-zA-Z_][\w.]*)\}\}/g, (match, key) => {
-          if (strings[key] !== undefined) {
-            changed = true;
-            return processValue(strings[key]);
-          }
-          return match;
-        });
-        if (changed) {
-          node.textContent = text;
-          // Apply text direction on the parent element so RTL text
-          // renders correctly without flipping the overall page layout.
-          if (dir === "rtl") {
-            node.parentElement.dir = dir;
+    await settle(page);
+
+    const buffers = [];
+    for (const variant of variants) {
+      const { width, height } = variant;
+      await page.setViewport({ width, height, deviceScaleFactor: 1 });
+
+      const scale = Math.max(width / sourceW, height / sourceH);
+      // Always assign zoom (clearing it at scale 1) so a previous variant's
+      // zoom can't leak into this one, and freeze animations at t=0 so the
+      // capture is deterministic. The screenshot's forced frame applies both.
+      await page.evaluate((zoom) => {
+        document.documentElement.style.zoom = zoom;
+        for (const anim of document.getAnimations()) {
+          try {
+            anim.pause();
+            anim.currentTime = 0;
+          } catch {
+            // Some animations (e.g. infinite transitions) can reject; skip.
           }
         }
-      }
-    }, strings, locale, direction);
-    await new Promise((r) => setTimeout(r, 200));
-  }
-
-  if (scale !== 1) {
-    await page.evaluate((z) => {
-      document.documentElement.style.zoom = z;
-    }, scale);
-    await new Promise((r) => setTimeout(r, 200));
-  }
+      }, scale === 1 ? "" : String(scale));
 
-  // Handle background: transparent by default for PNG, or use specified color
-  const bg = options.background;
-  if (bg) {
-    await page.evaluate((color) => {
-      document.documentElement.style.backgroundColor = color;
-    }, bg);
-  }
+      const format = variant.format || "png";
+      const screenshotOpts = {
+        type: format,
+        clip: { x: 0, y: 0, width, height },
+      };
+      if (format === "png" && !options.background) {
+        screenshotOpts.omitBackground = true;
+      }
+      if (format === "jpeg" && variant.quality) {
+        screenshotOpts.quality = variant.quality;
+      }
+      buffers.push(await page.screenshot(screenshotOpts));
+    }
 
-  const format = options.format || "png";
-  const screenshotOpts = {
-    type: format,
-    clip: { x: 0, y: 0, width, height },
-  };
-  if (format === "png" && !bg) {
-    screenshotOpts.omitBackground = true;
-  }
-  if (format === "jpeg" && options.quality) {
-    screenshotOpts.quality = options.quality;
+    return buffers;
+  } finally {
+    releasePage(page);
   }
+}
 
-  const buffer = await page.screenshot(screenshotOpts);
-
-  await page.close();
+/**
+ * Render an HTML file to an image buffer at the given dimensions.
+ * Scales from sourceSize to target size via CSS zoom.
+ * Single-variant wrapper around renderVariants.
+ * @param {string} projectDir
+ * @param {string} htmlFile
+ * @param {number} width
+ * @param {number} height
+ * @param {number} sourceW
+ * @param {number} sourceH
+ * @param {{ format?: "png"|"jpeg", quality?: number, background?: string, localization?: { strings: object, locale: string, direction: string }, timeout?: number }} [options]
+ */
+export async function renderScreenshot(
+  projectDir,
+  htmlFile,
+  width,
+  height,
+  sourceW,
+  sourceH,
+  options = {}
+) {
+  const [buffer] = await renderVariants(
+    projectDir,
+    htmlFile,
+    sourceW,
+    sourceH,
+    [{ width, height, format: options.format, quality: options.quality }],
+    options
+  );
   return buffer;
 }
 

package/lib/server.mjs

@@ -62,7 +62,7 @@ export async function startServer(projectDir, options = {}, renderer) {
   if (!renderer) {
     renderer = await import("./renderer.mjs");
   }
-  const { renderScreenshot, runXcodeOutput, closeBrowser } = renderer;
+  const { renderScreenshot, runXcodeOutput, closeBrowser, warmupBrowser } = renderer;
 
   const port = options.port || 3200;
   const host = options.host || "localhost";
@@ -159,7 +159,11 @@ 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})${localization ? ` [${localization.locale}]` : ''}...`);
-        const buffer = await renderScreenshot(projectDir, file, width, height, sw, sh, { background, localization });
+        const buffer = await renderScreenshot(projectDir, file, width, height, sw, sh, {
+          background,
+          localization,
+          timeout: options.renderTimeout,
+        });
         res.writeHead(200, {
           "Content-Type": "image/png",
           "Content-Length": buffer.length,
@@ -315,27 +319,31 @@ export async function startServer(projectDir, options = {}, renderer) {
     tryListen();
   });
 
-  return { port: actualPort };
-
   function cleanup() {
     for (const w of watchers) w.close();
     for (const client of sseClients) client.end();
     sseClients.clear();
   }
 
-  process.on("SIGINT", async () => {
+  const shutdown = async () => {
     cleanup();
     await closeBrowser();
     server.close();
     process.exit(0);
-  });
+  };
 
-  process.on("SIGTERM", async () => {
-    cleanup();
-    await closeBrowser();
-    server.close();
-    process.exit(0);
+  process.once("SIGINT", shutdown);
+  process.once("SIGTERM", shutdown);
+  server.on("close", () => {
+    process.removeListener("SIGINT", shutdown);
+    process.removeListener("SIGTERM", shutdown);
   });
 
-  return server;
+  // Pre-launch the shared browser in the background so the first interactive
+  // render doesn't pay the ~2s launch cost. Failures surface on first render.
+  if (typeof warmupBrowser === "function") {
+    Promise.resolve(warmupBrowser()).catch(() => {});
+  }
+
+  return { port: actualPort, server };
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@open-assets/open-assets",
-  "version": "0.4.0",
-  "description": "Dev server and export tool for app screenshots, icons, and logos. Like Storybook for marketing assets.",
+  "version": "0.5.1",
+  "description": "Screenshots, icons, and marketing assets, made a breeze in your git repo. Design in HTML/CSS/SVG, render at every size, export anywhere. Like Storybook for marketing assets.",
   "type": "module",
   "bin": {
     "open-assets": "bin/open-assets.mjs"
@@ -40,7 +40,7 @@
   },
   "scripts": {
     "assets": "node bin/open-assets.mjs render --force -o ./public/img",
-    "test": "node --experimental-vm-modules node_modules/.bin/jest",
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
     "release": "./scripts/release.sh"
   },
   "homepage": "https://openassets.dev",

package/skills/open-assets/SKILL.md

@@ -17,11 +17,12 @@ open-assets dev
 # Or with Tailwind
 concurrently "npx @tailwindcss/cli -i assets/styles.css -o dist/styles.css --watch" "open-assets dev"
 
-# Headless render
+# Headless render (incremental: unchanged templates are skipped via assets.lock)
+open-assets render                                      # everything, at every export size
+open-assets render --template log-out                   # one template only
+open-assets render --collection ui-icons               # one collection
 open-assets render --collection screenshots --size iphone-6.9
-open-assets render --collection icon --force
-open-assets render --force
-open-assets render --template 01-hero --force
+open-assets render --force                              # re-render everything, ignoring the cache
 ```
 
 ## Concepts
@@ -43,7 +44,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 --force",
+  "command": "npx open-assets render",
   "collections": [
     {
       "id": "unique-id",
@@ -76,7 +77,7 @@ The `assets.json` at the project root defines all asset collections. All collect
 
 ### Output Types
 
-Export entries with a `type` field are post-render actions (run with `--force`):
+Export entries with a `type` field are post-render actions that run after every render:
 
 | Type | Config | Description |
 |------|--------|-------------|
@@ -195,16 +196,35 @@ Export entries with a `type` field are post-render actions (run with `--force`):
 | `--template <name>` | Render only the template with this name |
 | `--size <name>` | Use a named export size from config |
 | `--locale <code>` | Render only this locale (e.g. `en`, `ar`, `ja`) |
-| `-f, --force` | Export at every size and re-render all (ignores cache) |
+| `-f, --force` | Re-render everything, ignoring the incremental cache |
 | `-o, --output <dir>` | Output directory (default: `./exports`) |
 | `--json` | Output results as JSON |
 | `-q, --quiet` | Suppress progress logs |
 
+Set `OPEN_ASSETS_CONCURRENCY` to change how many templates render at once. It defaults to `min(cores - 1, 2)`; higher values queue behind Chromium's capture path rather than going faster.
+
 Flags compose naturally:
 - `--collection screenshots --template 01-hero --size iphone-6.9` → single template, single size
-- `--collection screenshots --template 01-hero --force` → one template, all sizes
+- `--collection screenshots --template 01-hero` → one template, all sizes
 - `--collection screenshots --size iphone-6.9` → all templates, one size
 
+#### Performance: prefer targeted renders when iterating
+
+A plain `render` is incremental: unchanged templates are skipped via `assets.lock`, so it is usually fast. The renderer also loads each template once per locale and screenshots every export size from that single page load, with a couple of templates rendering concurrently. Still, `--force` re-renders **every collection** in `assets.json` (icons, splash, badges, screenshots, etc.), so when you're iterating on a single asset, scope the render:
+
+```bash
+# Iterating on one icon (fastest)
+open-assets render --template log-out
+
+# Iterating on one collection
+open-assets render --collection ui-icons
+
+# Re-render everything, ignoring the cache
+open-assets render --force
+```
+
+Rule of thumb: plain `render` is the default; it only re-renders what changed. Add `--template <name>` or `--collection <id>` to scope further. Reserve `--force` for when the cache must be bypassed: changed shared CSS, changed images in `publicDir`, or a rare global rebuild.
+
 ### add commands
 
 Interactive commands for managing the config without editing JSON by hand. All support `--config <path>` for custom config filenames.
@@ -330,6 +350,10 @@ Alternatively, add a new object to the `collections` array in `assets.json` manu
 | Web | OG Image | 1200 | 630 |
 | Mac App Store | Retina | 2880 | 1800 |
 
+## Version Control
+
+**Commit `assets.lock` and `exports/` to the repository. DO NOT gitignore them.** The lockfile enables incremental builds, and the exports are the final rendered assets that other parts of the project (Xcode asset catalogs, web builds, etc.) depend on. Only `dist/` (compiled Tailwind) should be gitignored.
+
 ## Incremental Builds (assets.lock)
 
 The `render` command maintains a `assets.lock` file with SHA256 checksums of source files. On subsequent renders, unchanged assets are skipped automatically. Use `--force` to re-render everything.
@@ -371,41 +395,29 @@ Create a JSON file (iOS `.xcstrings`-inspired format) that maps string keys to p
 
 ### 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`. You can also set `defaultLocalization` at the root level of `assets.json` to control which locale is selected by default in the dev server's locale picker (falls back to `sourceLanguage` from the localizations file, then `"en"`):
+Add `localizations` (path to the JSON file) and optionally `locales` (filter to specific locales) to a collection in `assets.json`:
 
 ```json
 {
-  "version": 1,
-  "name": "My App",
-  "defaultLocalization": "en",
-  "collections": [
-    {
-      "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 } }
-      ]
-    }
+  "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 |
 |-------|------|-------------|
-| `defaultLocalization` | string | Root-level. Default locale for the dev server locale picker. Falls back to `sourceLanguage` then `"en"`. |
 | `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. |
 
-### Dev server locale picker
-
-When a collection has `localizations` configured, the dev server shows a locale picker dropdown in the toolbar. Selecting a locale injects the localized strings into all template iframes in real time. The selected locale is also persisted in the URL (`?locale=ar`) and used for exports — exported PNGs will include the localized text for the active locale.
-
 ### Using placeholders in templates
 
 Templates use `{{key}}` mustache-style placeholders that get replaced with localized values before rendering:
@@ -458,13 +470,13 @@ With `outFile`, use the `{locale}` template variable:
 
 ```bash
 # Render all locales for a collection
-open-assets render --collection screenshots --force
+open-assets render --collection screenshots
 
 # Render only Arabic
-open-assets render --collection screenshots --force --locale ar
+open-assets render --collection screenshots --locale ar
 
 # Render a single template in Japanese
-open-assets render --collection screenshots --template 01-hero --locale ja --force
+open-assets render --collection screenshots --template 01-hero --locale ja
 ```
 
 ### Locale fallback order
@@ -479,7 +491,7 @@ When resolving a string for a locale:
 ```
 project/
   assets.json
-  assets.lock          # Auto-generated cache (commit this)
+  assets.lock          # Auto-generated cache — commit this
   public/                # Shared assets (images, logos, icons, photos)
     logo-round.png
     social/
@@ -500,7 +512,7 @@ project/
       default.html
   dist/
     styles.css           # Compiled Tailwind
-  exports/               # Rendered output (add to .gitignore)
+  exports/               # Rendered output — commit this
 ```
 
 ---