@kosdev-code/kos-asset-manager 0.0.1-next.20

package/bin/lib/declare-assets.mjs

@@ -0,0 +1,404 @@
+/**
+ * Derives a kondra.ui.assets declaration from a project's media directory.
+ */
+import { createHash } from 'node:crypto';
+import {
+  existsSync,
+  readFileSync,
+  readdirSync,
+  writeFileSync,
+} from 'node:fs';
+import { join, resolve } from 'node:path';
+
+const SOURCE_DIR = ['src', 'assets', 'media'];
+const ASSETS_ROOT = '/assets/media';
+const TYPES = {
+  '.avif': 'image/avif',
+  '.gif': 'image/gif',
+  '.jpeg': 'image/jpeg',
+  '.jpg': 'image/jpeg',
+  '.mp3': 'audio/mpeg',
+  '.mp4': 'video/mp4',
+  '.png': 'image/png',
+  '.svg': 'image/svg+xml',
+  '.wav': 'audio/wav',
+  '.webm': 'video/webm',
+  '.webp': 'image/webp',
+  '.woff2': 'font/woff2',
+};
+
+/**
+ * Patterns select assets by key so a set can be declared once instead of
+ * naming every file. `*` matches within a path segment, `**` across
+ * segments, and a pattern with no wildcard is a plain key.
+ */
+const matcher = (pattern) => {
+  const source = pattern
+    .split('**')
+    .map((part) =>
+      part
+        .split('*')
+        .map((literal) => literal.replace(/[.+?^${}()|[\]\\]/g, '\\$&'))
+        .join('[^/]*')
+    )
+    .join('.*');
+  return new RegExp(`^${source}$`);
+};
+
+const selectKeys = (keys, patterns) => {
+  const selected = [];
+  for (const pattern of patterns) {
+    const test = matcher(pattern);
+    const hits = keys.filter((key) => test.test(key));
+    if (hits.length === 0) {
+      console.warn(`kos-assets: nothing matches ${pattern}`);
+    }
+    for (const hit of hits) {
+      if (!selected.includes(hit)) selected.push(hit);
+    }
+  }
+  return selected;
+};
+
+/**
+ * Dimensions of an mp4, mov or m4v, read from its track header. The header
+ * ends with the display width and height as 16.16 fixed point, and audio
+ * tracks carry zeroes, so the first non-zero pair is the video.
+ */
+const measureIsoMedia = (buffer) => {
+  let at = 0;
+  while (at + 8 <= buffer.length) {
+    const found = buffer.indexOf('tkhd', at, 'ascii');
+    if (found < 4) return undefined;
+
+    const size = buffer.readUInt32BE(found - 4);
+    const end = found - 4 + size;
+    if (size < 16 || end > buffer.length) return undefined;
+
+    const width = buffer.readUInt32BE(end - 8) / 65536;
+    const height = buffer.readUInt32BE(end - 4) / 65536;
+    if (width > 0 && height > 0) {
+      return { width: Math.round(width), height: Math.round(height) };
+    }
+    at = found + 4;
+  }
+  return undefined;
+};
+
+/**
+ * Pixel dimensions of an image, read from its header. An unrecognised
+ * format is left unmeasured.
+ */
+const measure = (buffer, ext) => {
+  try {
+    if (ext === '.png' && buffer.length > 24) {
+      return { width: buffer.readUInt32BE(16), height: buffer.readUInt32BE(20) };
+    }
+    if (ext === '.gif' && buffer.length > 10) {
+      return { width: buffer.readUInt16LE(6), height: buffer.readUInt16LE(8) };
+    }
+    if (ext === '.jpg' || ext === '.jpeg') {
+      let at = 2;
+      while (at + 9 < buffer.length) {
+        if (buffer[at] !== 0xff) break;
+        const marker = buffer[at + 1];
+        const length = buffer.readUInt16BE(at + 2);
+        const isSof =
+          marker >= 0xc0 && marker <= 0xcf &&
+          marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc;
+        if (isSof) {
+          return {
+            height: buffer.readUInt16BE(at + 5),
+            width: buffer.readUInt16BE(at + 7),
+          };
+        }
+        at += 2 + length;
+      }
+      return undefined;
+    }
+    if (ext === '.webp' && buffer.length > 30) {
+      const chunk = buffer.toString('ascii', 12, 16);
+      if (chunk === 'VP8X') {
+        return {
+          width: buffer.readUIntLE(24, 3) + 1,
+          height: buffer.readUIntLE(27, 3) + 1,
+        };
+      }
+      if (chunk === 'VP8 ') {
+        return {
+          width: buffer.readUInt16LE(26) & 0x3fff,
+          height: buffer.readUInt16LE(28) & 0x3fff,
+        };
+      }
+      return undefined;
+    }
+    if (ext === '.mp4' || ext === '.mov' || ext === '.m4v') {
+      return measureIsoMedia(buffer);
+    }
+    if (ext === '.svg') {
+      const text = buffer.toString('utf8', 0, 2048);
+      const viewBox = /viewBox\s*=\s*["']\s*[\d.-]+[ ,]+[\d.-]+[ ,]+([\d.]+)[ ,]+([\d.]+)/.exec(text);
+      if (viewBox) {
+        return { width: Math.round(+viewBox[1]), height: Math.round(+viewBox[2]) };
+      }
+      const width = /\bwidth\s*=\s*["']([\d.]+)/.exec(text);
+      const height = /\bheight\s*=\s*["']([\d.]+)/.exec(text);
+      if (width && height) {
+        return { width: Math.round(+width[1]), height: Math.round(+height[1]) };
+      }
+    }
+  } catch {
+    // an unreadable header just means the asset goes unmeasured
+  }
+  return undefined;
+};
+
+const MARKER_FILE = '.kosassets';
+
+/**
+ * Key bindings declared beside the files they name. Sources are relative to
+ * the marker's folder, keys are absolute, so moving the folder changes no key.
+ *
+ *   # media/brand/.kosassets
+ *   brand/logo-primary = logos/primary.svg
+ *   brand/{name}       = *.svg
+ */
+const parseMarker = (contents) => {
+  const bindings = {};
+  for (const line of contents.split(/\r?\n/)) {
+    const text = line.replace(/#.*$/, '').trim();
+    if (!text) continue;
+
+    const at = text.indexOf('=');
+    if (at === -1) {
+      console.warn(`kos-assets: ignoring marker line without '=': ${text}`);
+      continue;
+    }
+    bindings[text.slice(0, at).trim()] = text.slice(at + 1).trim();
+  }
+  return bindings;
+};
+
+/** Every marker below the media directory, deepest first. */
+const readMarkers = (dir, prefix = '') => {
+  const found = [];
+  const marker = join(dir, MARKER_FILE);
+  if (existsSync(marker)) {
+    found.push({ dir: prefix, bindings: parseMarker(readFileSync(marker, 'utf8')) });
+  }
+  for (const item of readdirSync(dir, { withFileTypes: true })) {
+    if (item.isDirectory()) {
+      found.push(
+        ...readMarkers(join(dir, item.name), prefix ? `${prefix}/${item.name}` : item.name)
+      );
+    }
+  }
+  return found.sort((a, b) => b.dir.split('/').length - a.dir.split('/').length);
+};
+
+/**
+ * Key bindings pin a key to a file so the key survives the file moving.
+ * A binding's source is a path relative to the media directory, and may
+ * capture with {name} or span folders with **:
+ *
+ *   "brand/logo-primary": "logos/primary.svg"
+ *   "beverages/{name}":   "drinks/{name}.svg"
+ *   "video/globe":        "**\/globe.mp4"
+ */
+const bindingMatcher = (pattern) => {
+  const names = [];
+  let source = '';
+  const parts = pattern.split(/(\{[a-zA-Z][\w-]*\}|\*\*|\*)/);
+
+  for (const part of parts) {
+    if (part === '**') {
+      source += '.*';
+    } else if (part === '*') {
+      source += '[^/]*';
+    } else if (part.startsWith('{')) {
+      const name = part.slice(1, -1);
+      names.push(name);
+      source += '([^/]+)';
+    } else {
+      source += part.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
+    }
+  }
+  return { regex: new RegExp(`^${source}$`), names };
+};
+
+/**
+ * The key a file is bound to, or undefined when nothing claims it.
+ */
+const boundKey = (rel, bindings) => {
+  for (const [keyTemplate, pattern] of Object.entries(bindings)) {
+    const { regex, names } = bindingMatcher(pattern);
+    const match = regex.exec(rel);
+    if (!match) continue;
+
+    return names.reduce(
+      (key, name, index) => key.replaceAll(`{${name}}`, match[index + 1]),
+      keyTemplate
+    );
+  }
+  return undefined;
+};
+
+const fail = (message) => {
+  console.error(`kos-assets: ${message}`);
+  process.exit(1);
+};
+
+const readJson = (path) => JSON.parse(readFileSync(path, 'utf8'));
+
+const writeJson = (path, value) =>
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`);
+
+/**
+ * Every file below the media directory, with its path relative to it.
+ */
+const walk = (dir, prefix = '') =>
+  readdirSync(dir, { withFileTypes: true }).flatMap((item) => {
+    if (item.name.startsWith('.')) return [];
+    const rel = prefix ? `${prefix}/${item.name}` : item.name;
+    const child = join(dir, item.name);
+    return item.isDirectory() ? walk(child, rel) : [{ rel, file: child }];
+  });
+
+/**
+ * Build the assets block. Entries are derived from disk on every build;
+ * groups and preload flags are authored in .kos.json and carried through.
+ */
+const buildAssets = (projectRoot) => {
+  const mediaDir = resolve(projectRoot, ...SOURCE_DIR);
+  if (!existsSync(mediaDir)) {
+    return undefined;
+  }
+
+  const dotKos = resolve(projectRoot, '.kos.json');
+  const declared = existsSync(dotKos)
+    ? readJson(dotKos)?.kondra?.ui?.assets ?? {}
+    : {};
+
+  const bindings = declared.keys ?? {};
+  const markers = readMarkers(mediaDir);
+  const claimed = new Set();
+
+  // .kos.json wins, then the nearest marker, then the file's own path
+  const keyFor = (rel) => {
+    const central = boundKey(rel, bindings);
+    if (central) return central;
+
+    for (const marker of markers) {
+      if (marker.dir && !rel.startsWith(`${marker.dir}/`)) continue;
+      const relative = marker.dir ? rel.slice(marker.dir.length + 1) : rel;
+      const key = boundKey(relative, marker.bindings);
+      if (key) return key;
+    }
+    return undefined;
+  };
+
+  const entries = {};
+  for (const { rel, file } of walk(mediaDir)) {
+    const ext = rel.slice(rel.lastIndexOf('.')).toLowerCase();
+    const bound = keyFor(rel);
+    if (bound) claimed.add(bound);
+    const key = bound ?? rel.slice(0, rel.length - ext.length);
+    const contents = readFileSync(file);
+    entries[key] = {
+      path: rel,
+      type: TYPES[ext] ?? 'application/octet-stream',
+      size: contents.length,
+      hash: createHash('sha256').update(contents).digest('hex').slice(0, 16),
+      ...(measure(contents, ext) ?? {}),
+    };
+    if (declared.entries?.[key]?.preload) {
+      entries[key].preload = true;
+    }
+    const aliases = declared.entries?.[key]?.aliases;
+    if (aliases?.length) {
+      entries[key].aliases = aliases;
+    }
+  }
+
+  if (Object.keys(entries).length === 0) {
+    return undefined;
+  }
+
+  // a video shows the image that shares its key, so dropping a still beside
+  // a clip is all it takes to give it a thumbnail
+  for (const [key, entry] of Object.entries(entries)) {
+    if (!entry.type.startsWith('video/')) {
+      continue;
+    }
+    const declaredPoster = declared.entries?.[key]?.poster;
+    const paired =
+      declaredPoster ??
+      [`${key}-poster`, `${key}-still`].find((candidate) =>
+        entries[candidate]?.type?.startsWith('image/')
+      );
+    if (paired && entries[paired]) {
+      entry.poster = paired;
+      if (!entry.width && entries[paired].width) {
+        entry.width = entries[paired].width;
+        entry.height = entries[paired].height;
+      }
+    } else if (declaredPoster) {
+      console.warn(
+        `kos-assets: poster ${declaredPoster} for ${key} is not an asset`
+      );
+    }
+  }
+
+  // expand tag patterns onto the entries they select
+  const keys = Object.keys(entries);
+  for (const [tag, patterns] of Object.entries(declared.tags ?? {})) {
+    for (const key of selectKeys(keys, patterns)) {
+      entries[key].tags = [...(entries[key].tags ?? []), tag];
+    }
+  }
+
+  // expand group patterns into the keys they select
+  const groups = {};
+  for (const [group, patterns] of Object.entries(declared.groups ?? {})) {
+    groups[group] = selectKeys(keys, patterns);
+  }
+
+  for (const [key, pattern] of Object.entries(bindings)) {
+    if (!claimed.has(key) && !key.includes('{')) {
+      console.warn(`kos-assets: no file matches the binding ${key} = ${pattern}`);
+    }
+  }
+
+  const unknown = Object.keys(declared.entries ?? {}).filter(
+    (key) => !entries[key]
+  );
+  if (unknown.length > 0) {
+    console.warn(
+      `kos-assets: declared in .kos.json but not on disk: ${unknown.join(', ')}`
+    );
+  }
+
+  return {
+    root: ASSETS_ROOT,
+    entries,
+    ...(Object.keys(groups).length > 0 ? { groups } : {}),
+  };
+};
+
+export {
+  MARKER_FILE,
+  SOURCE_DIR,
+  ASSETS_ROOT,
+  TYPES,
+  parseMarker,
+  readMarkers,
+  bindingMatcher,
+  boundKey,
+  selectKeys,
+  measure,
+  measureIsoMedia,
+  walk,
+  readJson,
+  writeJson,
+  buildAssets,
+};

package/index.d.ts

@@ -0,0 +1,10 @@
+export * from './models/asset-entry';
+export * from './models/asset-context';
+export * from './models/asset-manager';
+export { registerAssetModels } from './registration';
+export { contextNames } from './runtime/assets';
+export { KosAssetProvider, KosAssetContext, useAssetManager, useKosAssetContext, } from './runtime/asset-provider';
+export { resolveAsset, wrapAsset, hasAsset, listAssets } from './runtime/resolve';
+export { preloadAssets, preloadDeclared, releaseAssets, } from './runtime/preload';
+export type { AssetSelector, PreloadOptions, PreloadProgress, ResolvedAsset, } from './runtime/types';
+//# sourceMappingURL=index.d.ts.map