@swiftbrowser/web 0.1.0

package/plugins/asset-catalogs.ts

@@ -0,0 +1,558 @@
+/**
+ * Serves every registered app's Xcode asset catalogs (the `*.xcassets`
+ * directories of its `AppSpec`) as one JSON manifest at `/catalog/<App>.json`
+ * plus the image files at `/catalog/<App>/<name>.<ext>` (dev server and
+ * `vite build`).
+ *
+ * The Swift side refers to catalog images and colors by name only
+ * (`Image("dough/plain-full")`, `Color("dough/plain-bg")`). The page fetches
+ * the manifest before loading the app (src/main.ts) so the layout engine
+ * knows every image's intrinsic size and the renderer can resolve the URL and
+ * the light/dark color values. See `AssetCatalog` in src/assets.ts.
+ *
+ * Catalog rules implemented here:
+ * - a folder whose `Contents.json` has `properties.provides-namespace: true`
+ *   prefixes everything inside with `<folder>/` (nested folders chain);
+ * - `<name>.imageset`: the `2x` entry is preferred (then `1x`, `3x`, then the
+ *   first entry with a file); points = pixels ÷ scale;
+ * - `<name>.symbolset`: an SVG drawn as a template (`kind: "symbol"`);
+ * - `<name>.colorset`: the entry without appearances is `light`, the one with
+ *   `luminosity: dark` is `dark`; idiom and contrast variants are ignored.
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+import type { Plugin } from 'vite';
+import { APP_NAME, type AppSpec } from '../node/apps.js';
+import {
+  CATALOG_DIR,
+  assetFileName,
+  assetFilePath,
+  type AssetCatalog,
+  type AssetColor,
+  type AssetImage,
+} from '../src/assets.js';
+
+export { CATALOG_DIR, catalogPath, assetFilePath } from '../src/assets.js';
+export type { AssetCatalog } from '../src/assets.js';
+
+/** One file the manifest refers to. */
+export interface CatalogFile {
+  /** Published path without a leading slash (`catalog/App/dough__plain-full.png`). */
+  fileName: string;
+  /** Absolute path of the source file on disk. */
+  source: string;
+  contentType: string;
+}
+
+export interface BuiltCatalog {
+  manifest: AssetCatalog;
+  /** Keyed by `fileName`. */
+  files: Map<string, CatalogFile>;
+  /** Entries that were skipped and why (the plugin logs them). */
+  warnings: string[];
+}
+
+const CONTENT_TYPES: Record<string, string> = {
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  webp: 'image/webp',
+  svg: 'image/svg+xml',
+};
+
+// ---------------------------------------------------------------------------
+// Contents.json shapes (only the fields read here)
+// ---------------------------------------------------------------------------
+
+interface FolderContents {
+  properties?: { 'provides-namespace'?: boolean };
+}
+interface ImageSetContents {
+  images?: { filename?: string; idiom?: string; scale?: string }[];
+}
+interface SymbolSetContents {
+  symbols?: { filename?: string; idiom?: string }[];
+}
+interface ColorSetContents {
+  colors?: {
+    idiom?: string;
+    appearances?: { appearance?: string; value?: string }[];
+    color?: {
+      'color-space'?: string;
+      components?: { red?: string; green?: string; blue?: string; alpha?: string };
+    };
+  }[];
+}
+
+function readJson<T>(file: string): T | null {
+  try {
+    return JSON.parse(readFileSync(file, 'utf8')) as T;
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Color components
+// ---------------------------------------------------------------------------
+
+/**
+ * One colorset component as a 0...1 value. Xcode writes hex (`"0xC2"`),
+ * floats (`"0.439"`, `"1.000"`) or 0...255 integers (`"255"`). A bare `"0"`
+ * or `"1"` has no decimal point but is taken as 0 / 1 (full), as Xcode never
+ * writes 1/255 that way.
+ */
+export function parseComponent(value: string | undefined, fallback = 1): number {
+  if (typeof value !== 'string') return fallback;
+  const text = value.trim();
+  if (/^0x[0-9a-f]+$/i.test(text)) return clamp01(parseInt(text.slice(2), 16) / 255);
+  if (/^-?\d+$/.test(text)) {
+    const n = parseInt(text, 10);
+    return clamp01(n > 1 ? n / 255 : n);
+  }
+  const n = Number(text);
+  return Number.isFinite(n) ? clamp01(n) : fallback;
+}
+
+function clamp01(v: number): number {
+  return Math.min(1, Math.max(0, v));
+}
+
+/** CSS `rgba(r, g, b, a)` for colorset components (r/g/b 0...255, a 0...1). */
+export function componentsToCSS(components: {
+  red?: string;
+  green?: string;
+  blue?: string;
+  alpha?: string;
+}): string {
+  const channel = (v: string | undefined): number => Math.round(parseComponent(v, 0) * 255);
+  const alpha = Math.round(parseComponent(components.alpha, 1) * 1000) / 1000;
+  return `rgba(${channel(components.red)}, ${channel(components.green)}, ${channel(components.blue)}, ${alpha})`;
+}
+
+/** The `light` / `dark` CSS colors of a colorset, or null when it has no usable entry. */
+export function parseColorSet(contents: ColorSetContents): AssetColor | null {
+  let light: string | undefined;
+  let dark: string | undefined;
+  for (const entry of contents.colors ?? []) {
+    const components = entry.color?.components;
+    if (!components) continue;
+    const appearances = entry.appearances ?? [];
+    // Contrast ("high") variants are not rendered; skip entries that carry one.
+    if (appearances.some((a) => a.appearance === 'contrast')) continue;
+    const luminosity = appearances.find((a) => a.appearance === 'luminosity')?.value;
+    const css = componentsToCSS(components);
+    if (luminosity === 'dark') dark ??= css;
+    else if (luminosity === undefined) light ??= css;
+  }
+  if (light === undefined) {
+    if (dark === undefined) return null;
+    light = dark;
+  }
+  return dark === undefined ? { light } : { light, dark };
+}
+
+// ---------------------------------------------------------------------------
+// Image dimensions
+// ---------------------------------------------------------------------------
+
+export interface PixelSize {
+  width: number;
+  height: number;
+}
+
+/**
+ * Pixel size of a PNG (IHDR), JPEG (the first SOF segment), WebP (VP8,
+ * VP8L or VP8X chunk) or SVG (`width`/`height` attributes, else `viewBox`);
+ * null for anything else.
+ */
+export function readImageSize(data: Buffer, ext: string): PixelSize | null {
+  switch (ext.toLowerCase()) {
+    case 'png':
+      return pngSize(data);
+    case 'jpg':
+    case 'jpeg':
+      return jpegSize(data);
+    case 'webp':
+      return webpSize(data);
+    case 'svg':
+      return svgSize(data.toString('utf8'));
+    default:
+      return null;
+  }
+}
+
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+function pngSize(data: Buffer): PixelSize | null {
+  if (data.length < 24 || !data.subarray(0, 8).equals(PNG_SIGNATURE)) return null;
+  if (data.toString('latin1', 12, 16) !== 'IHDR') return null;
+  return { width: data.readUInt32BE(16), height: data.readUInt32BE(20) };
+}
+
+/** RIFF/WEBP: the first chunk is VP8 (lossy), VP8L (lossless) or VP8X (extended). */
+function webpSize(data: Buffer): PixelSize | null {
+  if (data.length < 30 || data.toString('latin1', 0, 4) !== 'RIFF' || data.toString('latin1', 8, 12) !== 'WEBP') return null;
+  const chunk = data.toString('latin1', 12, 16);
+  if (chunk === 'VP8X') {
+    // 24-bit little-endian canvas width/height minus one at bytes 24 and 27.
+    const width = 1 + (data[24]! | (data[25]! << 8) | (data[26]! << 16));
+    const height = 1 + (data[27]! | (data[28]! << 8) | (data[29]! << 16));
+    return { width, height };
+  }
+  if (chunk === 'VP8L') {
+    if (data[20] !== 0x2f) return null;
+    const bits = data.readUInt32LE(21);
+    return { width: 1 + (bits & 0x3fff), height: 1 + ((bits >>> 14) & 0x3fff) };
+  }
+  if (chunk === 'VP8 ') {
+    // Key frame: 3-byte frame tag, start code 9d 01 2a, then 14-bit width and height.
+    if (data[23] !== 0x9d || data[24] !== 0x01 || data[25] !== 0x2a) return null;
+    return { width: data.readUInt16LE(26) & 0x3fff, height: data.readUInt16LE(28) & 0x3fff };
+  }
+  return null;
+}
+
+function jpegSize(data: Buffer): PixelSize | null {
+  if (data.length < 4 || data[0] !== 0xff || data[1] !== 0xd8) return null;
+  let offset = 2;
+  while (offset + 9 <= data.length) {
+    if (data[offset] !== 0xff) return null;
+    const marker = data[offset + 1] as number;
+    if (marker === 0xff) {
+      offset += 1; // padding
+      continue;
+    }
+    if (marker === 0xd8 || (marker >= 0xd0 && marker <= 0xd7) || marker === 0x01) {
+      offset += 2; // standalone markers without a length
+      continue;
+    }
+    const length = data.readUInt16BE(offset + 2);
+    // SOF0...SOF15 except DHT (C4), JPG (C8) and DAC (CC) hold the frame size.
+    const isSOF = marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc;
+    if (isSOF) {
+      return { height: data.readUInt16BE(offset + 5), width: data.readUInt16BE(offset + 7) };
+    }
+    if (marker === 0xda || marker === 0xd9) return null; // scan data / end: no SOF found
+    offset += 2 + length;
+  }
+  return null;
+}
+
+/** A CSS length from an SVG attribute, in px (pt is 4/3 px; other units are taken as px). */
+function svgLength(value: string | undefined): number | null {
+  if (!value) return null;
+  const match = /^\s*([0-9]*\.?[0-9]+)\s*([a-z%]*)\s*$/i.exec(value);
+  if (!match) return null;
+  const n = Number(match[1]);
+  if (!Number.isFinite(n) || n <= 0) return null;
+  if (match[2] === '%') return null;
+  return match[2]?.toLowerCase() === 'pt' ? (n * 4) / 3 : n;
+}
+
+function svgSize(text: string): PixelSize | null {
+  const open = /<svg\b[^>]*>/i.exec(text);
+  if (!open) return null;
+  const tag = open[0];
+  const attr = (name: string): string | undefined =>
+    new RegExp(`\\s${name}\\s*=\\s*["']([^"']*)["']`, 'i').exec(tag)?.[1];
+  const width = svgLength(attr('width'));
+  const height = svgLength(attr('height'));
+  if (width !== null && height !== null) return { width, height };
+  const viewBox = attr('viewBox');
+  if (viewBox) {
+    const parts = viewBox.trim().split(/[\s,]+/).map(Number);
+    const vw = parts[2];
+    const vh = parts[3];
+    if (parts.length === 4 && vw !== undefined && vh !== undefined && vw > 0 && vh > 0) {
+      // One explicit dimension with a viewBox: derive the other from the aspect ratio.
+      if (width !== null) return { width, height: (width * vh) / vw };
+      if (height !== null) return { width: (height * vw) / vh, height };
+      return { width: vw, height: vh };
+    }
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Catalog scanning
+// ---------------------------------------------------------------------------
+
+const SCALE_PREFERENCE = ['2x', '1x', '3x'];
+
+/** The image entry to publish for an imageset, with its numeric scale. */
+export function pickImage(contents: ImageSetContents): { filename: string; scale: number } | null {
+  const images = (contents.images ?? []).filter(
+    (image): image is { filename: string; idiom?: string; scale?: string } => typeof image.filename === 'string',
+  );
+  for (const scale of SCALE_PREFERENCE) {
+    const match = images.find((image) => image.scale === scale);
+    if (match) return { filename: match.filename, scale: parseInt(scale, 10) };
+  }
+  const first = images[0];
+  if (!first) return null;
+  const scale = first.scale ? parseInt(first.scale, 10) : 1;
+  return { filename: first.filename, scale: Number.isFinite(scale) && scale > 0 ? scale : 1 };
+}
+
+interface Scan {
+  app: string;
+  manifest: AssetCatalog;
+  files: Map<string, CatalogFile>;
+  warnings: string[];
+}
+
+function extensionOf(file: string): string {
+  return path.extname(file).slice(1).toLowerCase();
+}
+
+function addFile(scan: Scan, name: string, source: string, relativeToCatalog: string): AssetImage | null {
+  const ext = extensionOf(source);
+  const contentType = CONTENT_TYPES[ext];
+  if (!contentType) {
+    scan.warnings.push(`${relativeToCatalog}: unsupported image type .${ext}, skipped`);
+    return null;
+  }
+  const fileName = `${CATALOG_DIR}/${scan.app}/${assetFileName(name, ext)}`;
+  scan.files.set(fileName, { fileName, source, contentType });
+  return { src: assetFilePath(scan.app, name, ext), width: 0, height: 0, scale: 1, kind: 'image' };
+}
+
+function scanImageSet(scan: Scan, dir: string, name: string, label: string): void {
+  const contents = readJson<ImageSetContents>(path.join(dir, 'Contents.json'));
+  const picked = contents ? pickImage(contents) : null;
+  if (!picked) {
+    scan.warnings.push(`${label}: no image file listed in Contents.json, skipped`);
+    return;
+  }
+  const source = path.join(dir, picked.filename);
+  if (!existsSync(source)) {
+    scan.warnings.push(`${label}: ${picked.filename} is missing, skipped`);
+    return;
+  }
+  const entry = addFile(scan, name, source, label);
+  if (!entry) return;
+  const size = readImageSize(readFileSync(source), extensionOf(source));
+  if (!size) {
+    scan.warnings.push(`${label}: could not read the size of ${picked.filename}, skipped`);
+    scan.files.delete(`${CATALOG_DIR}/${scan.app}/${assetFileName(name, extensionOf(source))}`);
+    return;
+  }
+  entry.width = size.width / picked.scale;
+  entry.height = size.height / picked.scale;
+  entry.scale = picked.scale;
+  scan.manifest.images[name] = entry;
+}
+
+function scanSymbolSet(scan: Scan, dir: string, name: string, label: string): void {
+  const contents = readJson<SymbolSetContents>(path.join(dir, 'Contents.json'));
+  const filename = contents?.symbols?.find((s) => typeof s.filename === 'string')?.filename;
+  if (!filename) {
+    scan.warnings.push(`${label}: no symbol file listed in Contents.json, skipped`);
+    return;
+  }
+  const source = path.join(dir, filename);
+  if (!existsSync(source)) {
+    scan.warnings.push(`${label}: ${filename} is missing, skipped`);
+    return;
+  }
+  if (extensionOf(source) !== 'svg') {
+    scan.warnings.push(`${label}: a symbolset must hold an SVG, skipped`);
+    return;
+  }
+  const entry = addFile(scan, name, source, label);
+  if (!entry) return;
+  entry.kind = 'symbol';
+  // The layout engine sizes symbols from the font, so the size is informative only.
+  const size = readImageSize(readFileSync(source), 'svg');
+  if (size) {
+    entry.width = size.width;
+    entry.height = size.height;
+  }
+  scan.manifest.images[name] = entry;
+}
+
+function scanColorSet(scan: Scan, dir: string, name: string, label: string): void {
+  const contents = readJson<ColorSetContents>(path.join(dir, 'Contents.json'));
+  const color = contents ? parseColorSet(contents) : null;
+  if (!color) {
+    scan.warnings.push(`${label}: no color components in Contents.json, skipped`);
+    return;
+  }
+  scan.manifest.colors[name] = color;
+}
+
+/** Walk one directory of a catalog; `prefix` is the namespace so far (`dough/`). */
+function scanDirectory(scan: Scan, dir: string, prefix: string, label: string): void {
+  const entries = readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && !entry.name.startsWith('.'))
+    .sort((a, b) => a.name.localeCompare(b.name));
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    const ext = path.extname(entry.name);
+    const base = path.basename(entry.name, ext);
+    const name = prefix + base;
+    const entryLabel = `${label}/${entry.name}`;
+    switch (ext) {
+      case '.imageset':
+        scanImageSet(scan, full, name, entryLabel);
+        break;
+      case '.symbolset':
+        scanSymbolSet(scan, full, name, entryLabel);
+        break;
+      case '.colorset':
+        scanColorSet(scan, full, name, entryLabel);
+        break;
+      case '':
+      case undefined: {
+        // A plain folder: a namespace when its Contents.json says so.
+        const contents = readJson<FolderContents>(path.join(full, 'Contents.json'));
+        const namespaced = contents?.properties?.['provides-namespace'] === true;
+        scanDirectory(scan, full, namespaced ? `${name}/` : prefix, entryLabel);
+        break;
+      }
+      default:
+        // App icons, launch images, data sets, ...: not addressable from SwiftUI views.
+        break;
+    }
+  }
+}
+
+/** Every `*.xcassets` directory under `dir` (recursive, skipping hidden directories). */
+export function findAssetCatalogs(dir: string): string[] {
+  if (!existsSync(dir) || !statSync(dir).isDirectory()) return [];
+  const found: string[] = [];
+  const walk = (current: string): void => {
+    for (const entry of readdirSync(current, { withFileTypes: true })) {
+      if (!entry.isDirectory() || entry.name.startsWith('.')) continue;
+      const full = path.join(current, entry.name);
+      if (entry.name.endsWith('.xcassets')) found.push(full);
+      else if (entry.name !== 'node_modules') walk(full);
+    }
+  };
+  walk(dir);
+  return found.sort();
+}
+
+/**
+ * Build the manifest of `app` from the given `.xcassets` directories (later
+ * catalogs do not override earlier names: the first definition wins, with a
+ * warning for the duplicate).
+ */
+export function buildCatalog(app: string, catalogDirs: readonly string[]): BuiltCatalog {
+  if (!APP_NAME.test(app)) throw new Error(`Invalid app name: ${JSON.stringify(app)}`);
+  const scan: Scan = { app, manifest: { images: {}, colors: {} }, files: new Map(), warnings: [] };
+  for (const dir of catalogDirs) {
+    const partial: Scan = { app, manifest: { images: {}, colors: {} }, files: new Map(), warnings: scan.warnings };
+    scanDirectory(partial, dir, '', path.basename(dir));
+    for (const [name, image] of Object.entries(partial.manifest.images)) {
+      if (name in scan.manifest.images) {
+        scan.warnings.push(`${path.basename(dir)}: image "${name}" is already defined by another catalog, skipped`);
+        continue;
+      }
+      scan.manifest.images[name] = image;
+    }
+    for (const [name, color] of Object.entries(partial.manifest.colors)) {
+      if (name in scan.manifest.colors) {
+        scan.warnings.push(`${path.basename(dir)}: color "${name}" is already defined by another catalog, skipped`);
+        continue;
+      }
+      scan.manifest.colors[name] = color;
+    }
+    for (const [fileName, file] of partial.files) {
+      if (!scan.files.has(fileName)) scan.files.set(fileName, file);
+    }
+  }
+  // Drop files whose image was skipped or shadowed.
+  const referenced = new Set(Object.values(scan.manifest.images).map((image) => image.src.slice(1)));
+  for (const fileName of Array.from(scan.files.keys())) {
+    if (!referenced.has(fileName)) scan.files.delete(fileName);
+  }
+  return { manifest: scan.manifest, files: scan.files, warnings: scan.warnings };
+}
+
+/** The manifest of the app at `<examplesDir>/<App>` (all catalogs under it). */
+export function buildAppCatalog(examplesDir: string, app: string): BuiltCatalog {
+  return buildCatalog(app, findAssetCatalogs(path.join(examplesDir, app)));
+}
+
+export function catalogJson(catalog: AssetCatalog): string {
+  return JSON.stringify(catalog, null, 2) + '\n';
+}
+
+/** The app named by a manifest request URL (`/catalog/<App>.json`), or null. */
+export function catalogRequestApp(url: string): string | null {
+  const match = new RegExp(`^/${CATALOG_DIR}/([A-Za-z0-9_-]+)\\.json(?:\\?|$)`).exec(url);
+  return match?.[1] ?? null;
+}
+
+/** The app and published file name of an asset file request, or null. */
+export function catalogRequestFile(url: string): { app: string; fileName: string } | null {
+  const match = new RegExp(`^/${CATALOG_DIR}/([A-Za-z0-9_-]+)/([A-Za-z0-9_.-]+)(?:\\?|$)`).exec(url);
+  if (!match?.[1] || !match[2] || match[2].startsWith('.')) return null;
+  return { app: match[1], fileName: `${CATALOG_DIR}/${match[1]}/${match[2]}` };
+}
+
+/** The fields of an {@link AppSpec} the catalog plugin reads. */
+export type CatalogSpec = Pick<AppSpec, 'name' | 'catalogs'>;
+
+export function assetCatalogs(specs: readonly CatalogSpec[]): Plugin {
+  const byName = new Map(specs.map((spec) => [spec.name, spec]));
+
+  return {
+    name: 'swiftbrowser:asset-catalogs',
+    configureServer(server) {
+      const warned = new Set<string>();
+      // Rebuilt on every manifest request so edits to a catalog show up on
+      // reload; scanning a few directories is cheap.
+      const build = (spec: CatalogSpec): BuiltCatalog => {
+        const built = buildCatalog(spec.name, spec.catalogs);
+        for (const warning of built.warnings) {
+          if (warned.has(warning)) continue;
+          warned.add(warning);
+          server.config.logger.warn(`[asset-catalogs] ${spec.name}: ${warning}`, { timestamp: true });
+        }
+        return built;
+      };
+      server.middlewares.use((req, res, next) => {
+        const url = req.url ?? '';
+        const app = catalogRequestApp(url);
+        if (app !== null) {
+          const spec = byName.get(app);
+          if (!spec) {
+            res.statusCode = 404;
+            res.end();
+            return;
+          }
+          res.setHeader('Content-Type', 'application/json');
+          res.setHeader('Cache-Control', 'no-cache');
+          res.end(catalogJson(build(spec).manifest));
+          return;
+        }
+        const file = catalogRequestFile(url);
+        if (file === null) return next();
+        const spec = byName.get(file.app);
+        const entry = spec ? build(spec).files.get(file.fileName) : undefined;
+        if (!entry) {
+          res.statusCode = 404;
+          res.end();
+          return;
+        }
+        res.setHeader('Content-Type', entry.contentType);
+        res.setHeader('Cache-Control', 'no-cache');
+        res.end(readFileSync(entry.source));
+      });
+    },
+    generateBundle() {
+      for (const spec of specs) {
+        const built = buildCatalog(spec.name, spec.catalogs);
+        for (const warning of built.warnings) this.warn(`${spec.name}: ${warning}`);
+        this.emitFile({ type: 'asset', fileName: `${CATALOG_DIR}/${spec.name}.json`, source: catalogJson(built.manifest) });
+        for (const file of built.files.values()) {
+          this.emitFile({ type: 'asset', fileName: file.fileName, source: readFileSync(file.source) });
+        }
+      }
+    },
+  };
+}