@open-assets/open-assets 0.5.0 → 0.5.1

package/README.md

@@ -316,9 +316,18 @@ Options:
 | `-o, --output <dir>` | `OPEN_ASSETS_OUTPUT` | `./exports` | Output directory |
 | `--config <path>` | `OPEN_ASSETS_CONFIG` | `assets.json` | Path to config file |
 | `--render-timeout <ms>` | `OPEN_ASSETS_RENDER_TIMEOUT` | `30000` | Puppeteer render timeout |
+| — | `OPEN_ASSETS_CONCURRENCY` | auto | Templates rendered at once (see below) |
 | `--json` | — | — | Output results as JSON |
 | `-q, --quiet` | `OPEN_ASSETS_QUIET` | `false` | Suppress progress logs |
 
+**Concurrency**: each template is loaded once per locale and screenshotted at
+every export size from that single page load. A couple of templates render at a
+time, which is where the throughput ceiling sits: Chromium serializes the
+capture path, so extra workers queue behind each other instead of adding speed.
+The default is `min(cores - 1, 2)`. Raise `OPEN_ASSETS_CONCURRENCY` only if your
+templates are unusually slow to lay out relative to how long they take to
+capture, and measure before keeping the change.
+
 **Selective export**: flags compose naturally:
 ```bash
 # Single template at a single device size

package/lib/render.mjs

@@ -6,9 +6,41 @@ import { filterCollections, filterTemplates, resolveRenderSizes, flatOutputs } f
 import { computeExportChecksum } from "./lockfile.mjs";
 import { loadLocalizations, resolveStrings, getLocales, getDirection } from "./localization.mjs";
 
-// Renders overlap because per-image time is dominated by page load waits,
-// not CPU. Each in-flight unit holds one Puppeteer page.
-const CONCURRENCY = Math.max(1, Math.min(4, cpus().length - 1));
+// Chromium serializes the capture path, so a unit's screenshots cannot overlap
+// each other no matter how many workers ask. A second worker still pays off: it
+// navigates and lays out its page while the first is capturing. A third has
+// nothing left to hide, and each one past that adds a renderer process and a
+// full set of framebuffers while screenshot latency grows in proportion.
+//
+// Measured on a 10-core M-series Mac, 8 templates, median of 5 runs:
+//   4 App Store sizes  1:9.2s  2:9.4s  3:9.7s  4:9.6s  6:9.9s  8:10.4s
+//   1 small size       1:2.0s  2:1.8s  3:2.0s  4:2.0s  6:2.5s  8:3.5s
+const CONCURRENCY_CAP = 2;
+
+/**
+ * Pick how many render units run concurrently.
+ *
+ * The smallest of three ceilings wins: the work actually available, the CPU
+ * count (leaving a core for this process and Chromium's browser process), and
+ * the cap above. OPEN_ASSETS_CONCURRENCY overrides the result, which is the
+ * escape hatch for templates heavy enough to change the arithmetic.
+ *
+ * @param {unknown[]} units - Render units to be drained by the worker pool
+ * @param {{ override?: string|number, cores?: number }} [opts]
+ * @returns {number}
+ */
+export function resolveConcurrency(units, opts = {}) {
+  if (units.length === 0) return 1;
+
+  const raw = opts.override ?? process.env.OPEN_ASSETS_CONCURRENCY;
+  const override = parseInt(raw, 10);
+  if (Number.isFinite(override) && override > 0) {
+    return Math.min(override, units.length);
+  }
+
+  const cores = opts.cores ?? cpus().length;
+  return Math.max(1, Math.min(units.length, cores - 1, CONCURRENCY_CAP));
+}
 
 /**
  * @typedef {object} RenderDeps
@@ -307,7 +339,7 @@ export async function renderAssets(projectDir, manifest, options, deps, log) {
       };
 
       const workers = Array.from(
-        { length: Math.min(CONCURRENCY, units.length) },
+        { length: resolveConcurrency(units) },
         async () => {
           while (nextUnit < units.length && errors.length === 0) {
             const unit = units[nextUnit++];

package/lib/renderer.mjs

@@ -45,6 +45,10 @@ 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) {
@@ -52,7 +56,39 @@ async function acquirePage() {
     // Drop pages tied to a closed or replaced browser instance
     if (!page.isClosed() && page.browser() === browser) return page;
   }
-  return browser.newPage();
+  // 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 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) {
@@ -114,6 +150,7 @@ export async function renderVariants(
 ) {
   const page = await acquirePage();
   try {
+    await activatePage(page);
     const first = variants[0];
     await page.setViewport({
       width: first.width,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-assets/open-assets",
-  "version": "0.5.0",
+  "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": {

package/skills/open-assets/SKILL.md

@@ -201,6 +201,8 @@ Export entries with a `type` field are post-render actions that run after every
 | `--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` → one template, all sizes
@@ -208,7 +210,7 @@ Flags compose naturally:
 
 #### 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 several templates rendering in parallel. 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:
+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)