@open-assets/open-assets 0.1.12 → 0.3.0

package/lib/lockfile.mjs

@@ -1,6 +1,6 @@
 import { readFileSync, writeFileSync, existsSync } from "fs";
 import { createHash } from "crypto";
-import { resolve, join } from "path";
+import { resolve, join, dirname } from "path";
 
 const LOCK_FILENAME = "assets.lock";
 
@@ -27,25 +27,77 @@ export function writeLockfile(projectDir, lockData) {
   writeFileSync(lockPath, JSON.stringify(lockData, null, 2) + "\n");
 }
 
+/**
+ * Extract local file dependencies referenced by an HTML file.
+ * Parses src="...", href="...", and url(...) references, filtering out
+ * remote URLs and returning only paths that exist on disk.
+ * Returns a sorted, deduplicated array of absolute paths.
+ */
+export function extractLocalDeps(filePath) {
+  if (!existsSync(filePath)) return [];
+  const content = readFileSync(filePath, "utf-8");
+  const dir = dirname(filePath);
+
+  const refs = new Set();
+  const srcHrefPattern = /(?:src|href)=["']([^"']+)["']/gi;
+  const cssUrlPattern = /url\(["']?([^"')]+)["']?\)/gi;
+
+  for (const pattern of [srcHrefPattern, cssUrlPattern]) {
+    let match;
+    while ((match = pattern.exec(content)) !== null) {
+      refs.add(match[1]);
+    }
+  }
+
+  const localPaths = [];
+  for (const ref of refs) {
+    if (/^(https?:\/\/|data:|\/\/|#)/.test(ref)) continue;
+    if (!ref) continue;
+    const abs = resolve(dir, ref);
+    if (existsSync(abs)) {
+      localPaths.push(abs);
+    }
+  }
+
+  return [...new Set(localPaths)].sort();
+}
+
 /**
  * Compute SHA256 checksum of a file's contents.
+ * For .html files, includes the content of all local dependencies
+ * (images, SVGs, etc.) referenced via src/href/url() attributes.
  * Returns "sha256:<hex>" or null if file doesn't exist.
  */
 export function computeChecksum(filePath) {
   if (!existsSync(filePath)) return null;
   const content = readFileSync(filePath);
+
+  if (filePath.endsWith(".html")) {
+    const deps = extractLocalDeps(filePath);
+    if (deps.length > 0) {
+      const hash = createHash("sha256");
+      hash.update(content);
+      for (const dep of deps) {
+        hash.update("\0");
+        hash.update(readFileSync(dep));
+      }
+      return `sha256:${hash.digest("hex")}`;
+    }
+  }
+
   const hash = createHash("sha256").update(content).digest("hex");
   return `sha256:${hash}`;
 }
 
 /**
- * Check if an asset variant is up-to-date based on its stored checksum.
- * Returns true if the stored checksum matches and the output file exists.
+ * Check if an asset variant is up-to-date based on its stored checksums.
+ * Returns true if both source and export config checksums match and the output file exists.
  */
-export function isUpToDate(lockData, assetKey, variantKey, currentChecksum, outputPath) {
+export function isUpToDate(lockData, assetKey, variantKey, currentChecksum, outputPath, exportChecksum) {
   const entry = lockData.assets?.[assetKey]?.[variantKey];
   if (!entry) return false;
   if (entry.sourceChecksum !== currentChecksum) return false;
+  if (exportChecksum && entry.exportChecksum !== exportChecksum) return false;
   if (!existsSync(resolve(outputPath))) return false;
   return true;
 }
@@ -53,13 +105,36 @@ export function isUpToDate(lockData, assetKey, variantKey, currentChecksum, outp
 /**
  * Record an export in the lockfile data (in memory — call writeLockfile to persist).
  */
-export function recordExport(lockData, assetKey, variantKey, checksum, outputPath) {
+export function recordExport(lockData, assetKey, variantKey, checksum, outputPath, exportChecksum) {
   if (!lockData.assets[assetKey]) {
     lockData.assets[assetKey] = {};
   }
-  lockData.assets[assetKey][variantKey] = {
+  const entry = {
     sourceChecksum: checksum,
     outputPath,
     exportedAt: new Date().toISOString(),
   };
+  if (exportChecksum) {
+    entry.exportChecksum = exportChecksum;
+  }
+  lockData.assets[assetKey][variantKey] = entry;
+}
+
+/**
+ * Compute a checksum for the export configuration of a variant.
+ * Captures size dimensions, outFile path, and locale so that config changes trigger re-export.
+ */
+export function computeExportChecksum(entry, locale) {
+  const config = {
+    width: entry.size.width,
+    height: entry.size.height,
+  };
+  if (entry.outFile) {
+    config.outFile = entry.outFile;
+  }
+  if (locale) {
+    config.locale = locale;
+  }
+  const hash = createHash("sha256").update(JSON.stringify(config)).digest("hex");
+  return `sha256:${hash}`;
 }

package/lib/manifest.mjs

@@ -2,10 +2,17 @@ import { existsSync, readFileSync, writeFileSync } from "fs";
 import { resolve } from "path";
 
 /**
- * Get all export sizes from a collection.
+ * Get all export sizes from a collection (entries without a type field).
  */
 export function flatSizes(collection) {
-  return collection.export || [];
+  return (collection.export || []).filter((e) => !e.type);
+}
+
+/**
+ * Get all output actions from a collection (entries with a type field).
+ */
+export function flatOutputs(collection) {
+  return (collection.export || []).filter((e) => e.type);
 }
 
 /**
@@ -77,7 +84,7 @@ export function filterTemplates(templates, templateName) {
 /**
  * Determine which sizes to render for a collection given CLI options.
  * @param {object} collection - The collection from the config
- * @param {{ width?: string|number, height?: string|number, size?: string, all?: boolean, platform?: string }} opts
+ * @param {{ width?: string|number, height?: string|number, size?: string, force?: boolean, platform?: string }} opts
  * @returns {{ sizes: object[], warning?: string }}
  */
 export function resolveRenderSizes(collection, opts = {}) {
@@ -109,7 +116,7 @@ export function resolveRenderSizes(collection, opts = {}) {
     };
   }
 
-  if (opts.all) {
+  if (opts.force) {
     const sizes = flatSizes(collection);
     return { sizes };
   }

package/lib/render.mjs

@@ -1,6 +1,8 @@
 import { resolve, join } from "path";
 import { mkdirSync, writeFileSync, copyFileSync, existsSync } from "fs";
-import { filterCollections, filterTemplates, resolveRenderSizes } from "./manifest.mjs";
+import { filterCollections, filterTemplates, resolveRenderSizes, flatOutputs } from "./manifest.mjs";
+import { computeExportChecksum } from "./lockfile.mjs";
+import { loadLocalizations, resolveStrings, getLocales, getDirection } from "./localization.mjs";
 
 /**
  * @typedef {object} RenderDeps
@@ -10,8 +12,8 @@ import { filterCollections, filterTemplates, resolveRenderSizes } from "./manife
  * @property {(projectDir: string) => object} readLockfile
  * @property {(projectDir: string, data: object) => void} writeLockfile
  * @property {(filePath: string) => string|null} computeChecksum
- * @property {(lockData: object, assetKey: string, variantKey: string, checksum: string, outputPath: string) => boolean} isUpToDate
- * @property {(lockData: object, assetKey: string, variantKey: string, checksum: string, outputPath: string) => void} recordExport
+ * @property {(lockData: object, assetKey: string, variantKey: string, checksum: string, outputPath: string, exportChecksum?: string) => boolean} isUpToDate
+ * @property {(lockData: object, assetKey: string, variantKey: string, checksum: string, outputPath: string, exportChecksum?: string) => void} recordExport
  */
 
 /**
@@ -24,11 +26,11 @@ import { filterCollections, filterTemplates, resolveRenderSizes } from "./manife
  * @param {string} [options.tag] - Filter by tag
  * @param {string} [options.template] - Filter by template name/label
  * @param {string} [options.size] - Named export size
+ * @param {string} [options.locale] - Filter to a single locale
  * @param {string} [options.format] - Output format override (png or jpg)
  * @param {string|number} [options.width] - Custom width
  * @param {string|number} [options.height] - Custom height
- * @param {boolean} [options.all] - Export at all sizes
- * @param {boolean} [options.force] - Re-render even if unchanged
+ * @param {boolean} [options.force] - Export at all sizes and re-render (ignores cache)
  * @param {string} [options.output] - Output directory path
  * @param {boolean} [options.quiet] - Suppress logs
  * @param {RenderDeps} deps - Injected dependencies
@@ -67,7 +69,7 @@ export async function renderAssets(projectDir, manifest, options, deps, log) {
       width: options.width,
       height: options.height,
       size: options.size,
-      all: options.all,
+      force: options.force,
     });
 
     if (warning) {
@@ -80,115 +82,176 @@ export async function renderAssets(projectDir, manifest, options, deps, log) {
       continue;
     }
 
-    const useSubDirs = sizesToRender.length > 1 || options.all;
+    // Resolve locales for this collection
+    let locales = [null]; // null = no localization
+    let localizations = null;
 
-    for (const entry of sizesToRender) {
-      const w = entry.size.width;
-      const h = entry.size.height;
+    if (col.localizations) {
+      localizations = loadLocalizations(projectDir, col.localizations);
+      locales = getLocales(localizations, col.locales);
+      if (options.locale) {
+        locales = locales.filter((l) => l === options.locale);
+        if (locales.length === 0) {
+          _log(`  Warning: locale "${options.locale}" not found in collection "${col.id}", skipping`);
+          continue;
+        }
+      }
+    }
 
-      const sizeDir = useSubDirs
-        ? join(outputDir, col.id, entry.name)
-        : join(outputDir, col.id);
-      mkdirSync(sizeDir, { recursive: true });
+    const singleTemplate = templates.length === 1;
+    const multipleSizes = sizesToRender.length > 1 || options.force;
+    // Single-template collections use flat layout with entry.name as filename
+    // Multi-template collections use subdirs per size
+    const useSubDirs = multipleSizes && !singleTemplate;
+    const hasLocales = locales.length > 0 && locales[0] !== null;
 
-      if (sizesToRender.length > 1) {
-        _log(`\n  ${entry.label} (${w}x${h})`);
-      }
+    for (const locale of locales) {
+      const strings = locale ? resolveStrings(localizations, locale) : null;
+      const direction = locale ? getDirection(locale) : null;
+      const localization = locale ? { strings, locale, direction } : undefined;
 
-      for (const template of templates) {
-        // Determine output format from outFile extension or default to png
-        const outExt = entry.outFile
-          ? entry.outFile.split(".").pop().toLowerCase()
-          : "png";
-        const format = outExt === "jpg" || outExt === "jpeg" ? "jpeg" : "png";
-        const defaultExt = format === "jpeg" ? "jpg" : "png";
-
-        const outPath = entry.outFile
-          ? resolve(projectDir, entry.outFile.replace(/\{template\}/g, template.name))
-          : join(sizeDir, `${template.name}.${defaultExt}`);
-
-        const assetKey = `${col.id}/${template.name}`;
-        const variantKey = entry.name;
-        const srcPath = resolve(projectDir, template.src);
-        const checksum = deps.computeChecksum(srcPath);
-
-        // Skip if unchanged
-        if (
-          !options.force &&
-          checksum &&
-          deps.isUpToDate(lockData, assetKey, variantKey, checksum, outPath)
-        ) {
-          _log(
-            `  Skipping ${template.name} at ${w}x${h} (unchanged)`
-          );
-          skipped++;
-          continue;
-        }
+      if (locale) {
+        _log(`\n  Locale: ${locale} (${direction})`);
+      }
 
-        _log(
-          `  Rendering ${template.name} at ${w}x${h}...`
-        );
+      for (const entry of sizesToRender) {
+        const w = entry.size.width;
+        const h = entry.size.height;
 
-        const isSvg = template.src.endsWith(".svg");
-        if (isSvg && w === sourceW && h === sourceH) {
-          copyFileSync(srcPath, outPath.replace(`.${defaultExt}`, ".svg"));
+        // Build output directory: insert locale level when localizations are active
+        let sizeDir;
+        if (hasLocales) {
+          sizeDir = useSubDirs
+            ? join(outputDir, col.id, locale, entry.name)
+            : join(outputDir, col.id, locale);
+        } else {
+          sizeDir = useSubDirs
+            ? join(outputDir, col.id, entry.name)
+            : join(outputDir, col.id);
         }
+        mkdirSync(sizeDir, { recursive: true });
 
-        // Ensure output directory exists when using outFile
-        if (entry.outFile) {
-          mkdirSync(resolve(projectDir, join(outPath, "..")), { recursive: true });
+        if (sizesToRender.length > 1) {
+          _log(`\n  ${entry.label} (${w}x${h})`);
         }
 
-        const buffer = await deps.renderScreenshot(
-          projectDir,
-          template.src,
-          w,
-          h,
-          sourceW,
-          sourceH,
-          { format }
-        );
-        writeFileSync(outPath, buffer);
-        results.push({
-          collection: col.id,
-          template: template.name,
-          path: outPath,
-          width: w,
-          height: h,
-          size: buffer.length,
-        });
-        if (checksum) {
-          deps.recordExport(lockData, assetKey, variantKey, checksum, outPath);
+        for (const template of templates) {
+          // Determine output format from outFile extension or default to png
+          const outExt = entry.outFile
+            ? entry.outFile.split(".").pop().toLowerCase()
+            : "png";
+          const format = outExt === "jpg" || outExt === "jpeg" ? "jpeg" : "png";
+          const defaultExt = format === "jpeg" ? "jpg" : "png";
+
+          // Single-template: use entry.name as filename (e.g. logo-1024.png)
+          // Multi-template: use template.name as filename (e.g. 01-hero.png)
+          const fileName = singleTemplate && multipleSizes
+            ? `${entry.name}.${defaultExt}`
+            : `${template.name}.${defaultExt}`;
+
+          let outPath;
+          if (entry.outFile) {
+            let resolved = entry.outFile.replace(/\{template\}/g, template.name);
+            if (locale) {
+              resolved = resolved.replace(/\{locale\}/g, locale);
+            }
+            outPath = resolve(projectDir, resolved);
+          } else {
+            outPath = join(sizeDir, fileName);
+          }
+
+          // Asset key and variant key include locale for cache isolation
+          const assetKey = locale
+            ? `${col.id}/${locale}/${template.name}`
+            : `${col.id}/${template.name}`;
+          const variantKey = entry.name;
+          const srcPath = resolve(projectDir, template.src);
+          const checksum = deps.computeChecksum(srcPath);
+          const exportCksum = computeExportChecksum(entry, locale);
+
+          // Skip if unchanged
+          if (
+            !options.force &&
+            checksum &&
+            deps.isUpToDate(lockData, assetKey, variantKey, checksum, outPath, exportCksum)
+          ) {
+            _log(
+              `  Skipping ${template.name}${locale ? ` [${locale}]` : ""} at ${w}x${h} (unchanged)`
+            );
+            skipped++;
+            continue;
+          }
+
+          _log(
+            `  Rendering ${template.name}${locale ? ` [${locale}]` : ""} at ${w}x${h}...`
+          );
+
+          const isSvg = template.src.endsWith(".svg");
+          if (isSvg && w === sourceW && h === sourceH) {
+            copyFileSync(srcPath, outPath.replace(`.${defaultExt}`, ".svg"));
+          }
+
+          // Ensure output directory exists when using outFile
+          if (entry.outFile) {
+            mkdirSync(resolve(projectDir, join(outPath, "..")), { recursive: true });
+          }
+
+          const buffer = await deps.renderScreenshot(
+            projectDir,
+            template.src,
+            w,
+            h,
+            sourceW,
+            sourceH,
+            { format, background: col.background, localization }
+          );
+          writeFileSync(outPath, buffer);
+          results.push({
+            collection: col.id,
+            template: template.name,
+            locale: locale || undefined,
+            path: outPath,
+            width: w,
+            height: h,
+            size: buffer.length,
+          });
+          if (checksum) {
+            deps.recordExport(lockData, assetKey, variantKey, checksum, outPath, exportCksum);
+          }
+          _log(`    → ${outPath}`);
         }
-        _log(`    → ${outPath}`);
       }
     }
 
     // Handle outputs (xcode, copy-source, etc.)
-    if (col.outputs && options.all) {
-      for (const output of col.outputs) {
+    const outputs = flatOutputs(col);
+    if (outputs.length > 0 && options.force) {
+      for (const output of outputs) {
         if (output.type === "xcode") {
           _log(`\n  Exporting to Xcode: ${output.path}`);
           const path = await deps.runXcodeOutput(projectDir, col, output);
           results.push({ collection: col.id, type: "xcode", path });
         } else if (output.type === "copy-source") {
           const format = output.format || "svg";
-          const copyDir = join(outputDir, col.id, format);
+          const copyDir = join(outputDir, col.id);
           mkdirSync(copyDir, { recursive: true });
-          for (const template of templates) {
-            if (template.src.endsWith(`.${format}`)) {
-              const srcPath = resolve(projectDir, template.src);
-              const destPath = join(copyDir, `${template.name}.${format}`);
-              if (existsSync(srcPath)) {
-                copyFileSync(srcPath, destPath);
-                results.push({
-                  collection: col.id,
-                  template: template.name,
-                  type: `copy-${format}`,
-                  path: destPath,
-                });
-                _log(`    → ${destPath}`);
-              }
+          const matchingTemplates = templates.filter((t) => t.src.endsWith(`.${format}`));
+          for (const template of matchingTemplates) {
+            const srcPath = resolve(projectDir, template.src);
+            // Use entry name when single match, template name when multiple
+            const baseName = output.name && matchingTemplates.length === 1
+              ? output.name
+              : template.name;
+            const destPath = join(copyDir, `${baseName}.${format}`);
+            if (existsSync(srcPath)) {
+              copyFileSync(srcPath, destPath);
+              results.push({
+                collection: col.id,
+                template: template.name,
+                type: `copy-${format}`,
+                path: destPath,
+              });
+              _log(`    → ${destPath}`);
             }
           }
         }

package/lib/renderer.mjs

@@ -1,6 +1,6 @@
 import { launch } from "puppeteer";
 import { resolve } from "path";
-import { writeFileSync, mkdirSync } from "fs";
+import { writeFileSync, mkdirSync, readdirSync, unlinkSync } from "fs";
 
 let browser = null;
 
@@ -27,7 +27,7 @@ export async function closeBrowser() {
  * @param {number} height
  * @param {number} sourceW
  * @param {number} sourceH
- * @param {{ format?: "png"|"jpeg", quality?: number }} [options]
+ * @param {{ format?: "png"|"jpeg", quality?: number, background?: string, localization?: { strings: object, locale: string, direction: string } }} [options]
  */
 export async function renderScreenshot(
   projectDir,
@@ -49,6 +49,51 @@ export async function renderScreenshot(
   await page.goto(`file://${filePath}`, { waitUntil: "networkidle0" });
   await new Promise((r) => setTimeout(r, 500));
 
+  // 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;
+
+      const formatter = new Intl.NumberFormat(locale);
+
+      function processValue(value) {
+        return value.replace(/\{\{n:(\d+(?:\.\d+)?)\}\}/g, (_, num) => {
+          return formatter.format(parseFloat(num));
+        });
+      }
+
+      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);
+    await new Promise((r) => setTimeout(r, 200));
+  }
+
   if (scale !== 1) {
     await page.evaluate((z) => {
       document.documentElement.style.zoom = z;
@@ -56,11 +101,22 @@ export async function renderScreenshot(
     await new Promise((r) => setTimeout(r, 200));
   }
 
+  // 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 = 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;
   }
@@ -82,14 +138,39 @@ export async function runXcodeOutput(projectDir, collection, outputConfig) {
 
   const outputDir = resolve(projectDir, outputConfig.path);
   mkdirSync(outputDir, { recursive: true });
-  const outputPath = resolve(outputDir, "AppIcon.png");
 
   const sw = collection.sourceSize.width;
   const sh = collection.sourceSize.height;
+  const filename = "AppIcon.png";
+  const outputPath = resolve(outputDir, filename);
+
+  // Remove stale images that don't match the current output filename
+  for (const entry of readdirSync(outputDir)) {
+    if (entry !== filename && /\.(png|jpg|jpeg)$/i.test(entry)) {
+      unlinkSync(resolve(outputDir, entry));
+    }
+  }
 
   const buffer = await renderScreenshot(projectDir, template.src, sw, sh, sw, sh);
   writeFileSync(outputPath, buffer);
 
+  const contentsJson = {
+    images: [
+      {
+        filename,
+        idiom: "universal",
+        platform: "ios",
+        size: `${sw}x${sh}`,
+      },
+    ],
+    info: {
+      author: "xcode",
+      version: 1,
+    },
+  };
+  const contentsPath = resolve(outputDir, "Contents.json");
+  writeFileSync(contentsPath, JSON.stringify(contentsJson, null, 2) + "\n");
+
   console.log(`Updated: ${outputPath}`);
   return outputPath;
 }