@ranx729/ducktape-assets 0.0.0 → 1.1.0

package/src/copy.mjs

@@ -0,0 +1,152 @@
+// Pick-and-copy flow: fetch exactly the chosen files into the project, verify their sha256, write ducktape.manifest.json.
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { createResolver } from './resolver.mjs';
+import { fsManifestLoader } from './node.mjs';
+
+const isUrl = (s) => /^https?:\/\//.test(s);
+const sha256 = (buf) => createHash('sha256').update(buf).digest('hex');
+const ASC = (a, b) => a.w - b.w;
+
+/** Read a location that is either an http(s) URL or a local path. */
+async function load(loc) {
+  if (isUrl(loc)) {
+    let last;
+    for (let i = 0; i < 3; i++) {
+      try {
+        const res = await fetch(loc);
+        if (!res.ok) throw new Error(`HTTP ${res.status}`);
+        return Buffer.from(await res.arrayBuffer());
+      } catch (e) {
+        last = e;
+      }
+    }
+    throw new Error(`${loc}: ${last.message}`);
+  }
+  return readFile(loc.replace(/^file:\/\//, ''));
+}
+
+const normalize = (a) => (typeof a === 'string' ? { id: a } : a);
+
+/** The chosen files of one ladder: formats, then `widths` (smallest rung >= each, never upscale), then `max`. */
+function chooseLadder(ladder, spec) {
+  const formats = spec.formats ?? ['avif', 'webp', 'svg'];
+  const out = {};
+  for (const fmt of formats) {
+    const v = ladder?.[fmt];
+    if (!v) continue;
+    if (!Array.isArray(v)) {
+      out[fmt] = v;
+      continue;
+    }
+    const l = [...v].sort(ASC);
+    let sel = spec.widths ? [...new Set(spec.widths.map((w) => l.find((f) => f.w >= w) ?? l[l.length - 1]))] : l;
+    if (spec.max) sel = sel.filter((f) => f.w <= spec.max);
+    if (!sel.length) sel = [l[0]];
+    out[fmt] = sel.sort(ASC);
+  }
+  return out;
+}
+
+/** What to copy for one asset, grouped by role. Masters come from the masters package. */
+export function chooseFiles(asset, assetId, spec) {
+  // `masters: true` alone means "I encode my own images": only the master is copied. Add formats, widths or max to
+  // get ladder files as well.
+  const wantsLadder = !spec.masters || spec.formats || spec.widths || spec.max;
+  const ladderSpec = wantsLadder ? spec : { ...spec, formats: [] };
+  const roles = { sources: chooseLadder(asset.sources, ladderSpec) };
+  if (asset.render?.tile?.rotated) roles.rotated = chooseLadder(asset.render.tile.rotated, ladderSpec);
+  if (asset.render?.frame?.atlas) roles.atlas = chooseLadder(asset.render.frame.atlas, ladderSpec);
+  if (spec.masters) roles.master = { package: 'masters', ...(asset.master ?? { path: `masters/${assetId}.webp` }) };
+  return roles;
+}
+
+/** The authored geometry of an asset without the generated ladders: what a build script needs to place it. */
+function geometryOf(asset) {
+  const r = asset.render ?? {};
+  const out = {};
+  if (r.image) out.image = {};
+  if (r.tile) out.tile = { axis: r.tile.axis, period: r.tile.period ?? 1 };
+  if (r.frame) out.frame = { slice: r.frame.slice, ...(r.frame.slicePx ? { slicePx: r.frame.slicePx } : {}), ...(r.frame.corner ? { corner: r.frame.corner } : {}) };
+  return out;
+}
+
+/**
+ * @param {object} o
+ * @param {{pin?: string, out?: string, assets: Array<string|object>}} o.config
+ * @param {string} o.out        Destination directory.
+ * @param {string} [o.index]    Local path or URL of index.json. Default: the pin's package on jsDelivr.
+ * @param {string} [o.base]     Directory or URL laid out as `<base>/<set>/<path>` to read files from instead of the CDN (tests, mirrors).
+ */
+export async function copy({ config, out, index, base, log = () => {} }) {
+  if (!index) {
+    if (!config.pin) throw new Error('config needs a "pin" like "@ranx729/ducktape-assets@1.0.0" (or pass --index)');
+    index = `https://cdn.jsdelivr.net/npm/${config.pin}/index.json`;
+  }
+  const indexJson = JSON.parse(await load(index));
+  const resolver = createResolver({ index: indexJson, base, loadManifest: isUrl(index) ? undefined : fsManifestLoader(index) });
+
+  const plan = new Map(); // local relative path -> { url, sha256, bytes }
+  const summary = {};
+  for (const spec of config.assets.map(normalize)) {
+    const { setId, assetId, asset, manifest, entry } = await resolver.get(spec.id);
+    const roles = chooseFiles(asset, assetId, spec);
+    const local = (file) => `${setId}/${file.path}`;
+    const place = (file) => {
+      plan.set(local(file), { url: resolver.url(file, setId), sha256: file.sha256 });
+      return { w: file.w, h: file.h, path: local(file) };
+    };
+    const files = {};
+    for (const [role, v] of Object.entries(roles)) {
+      if (v.path) files[role] = place(v);
+      else files[role] = Object.fromEntries(Object.entries(v).map(([fmt, f]) => [fmt, Array.isArray(f) ? f.map(place) : place(f)]));
+    }
+    const master = asset.master ?? null;
+    summary[spec.id] = {
+      set: setId,
+      version: entry.version,
+      title: asset.title,
+      description: asset.description,
+      type: asset.type,
+      width: asset.width,
+      height: asset.height,
+      // The master may be capped below the native size; coordinates measured on it must say so.
+      ...(master ? { master: { width: master.w, height: master.h } } : {}),
+      transparent: asset.transparent ?? null,
+      thumbhash: asset.thumbhash,
+      render: geometryOf(asset),
+      ...(asset.components ? { components: Object.fromEntries(Object.entries(asset.components).map(([k, c]) => [k, { width: c.width, height: c.height, ...(c.description ? { description: c.description } : {}) }])) } : {}),
+      license: asset.license ?? manifest.license.artwork,
+      attribution: asset.attribution ?? manifest.attribution ?? '',
+      files,
+    };
+  }
+
+  let copied = 0, skipped = 0;
+  const queue = [...plan.entries()];
+  const worker = async () => {
+    for (let item; (item = queue.shift()); ) {
+      const [rel, { url, sha256: want }] = item;
+      const dest = join(out, rel);
+      const have = await readFile(dest).then(sha256, () => null);
+      if (have === want) {
+        skipped++;
+        continue;
+      }
+      const buf = await load(url);
+      const got = sha256(buf);
+      if (got !== want) throw new Error(`${url}: sha256 mismatch (expected ${want}, got ${got})`);
+      await mkdir(dirname(dest), { recursive: true });
+      await writeFile(dest, buf);
+      copied++;
+      log(`copied ${rel}`);
+    }
+  };
+  await Promise.all(Array.from({ length: 6 }, worker));
+
+  await mkdir(out, { recursive: true });
+  const manifest = { schema: 1, pin: config.pin ?? null, assets: summary };
+  await writeFile(join(out, 'ducktape.manifest.json'), JSON.stringify(manifest, null, 2) + '\n');
+  return { copied, skipped, files: [...plan.keys()].sort(), manifest };
+}

package/src/generate.mjs

@@ -0,0 +1,200 @@
+// Generates the index package's data and docs from the published manifests of every set.
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { fileUrl } from './urls.mjs';
+
+const REPO = 'https://github.com/adrian729';
+
+export function indexEntry(manifest, { status = 'active' } = {}) {
+  const mastersCdn = manifest.cdn.replace(`${manifest.package}@`, `${manifest.mastersPackage}@`);
+  return {
+    version: manifest.version,
+    package: manifest.package,
+    parts: manifest.parts ?? [],
+    mastersPackage: manifest.mastersPackage,
+    mastersParts: manifest.mastersParts ?? [],
+    cdn: manifest.cdn,
+    mastersCdn,
+    assets: Object.keys(manifest.assets).length,
+    license: { artwork: manifest.license.artwork },
+    contentHash: manifest.contentHash,
+    status,
+  };
+}
+
+function ladderUrls(entry, setId, ladder) {
+  const out = {};
+  for (const [fmt, v] of Object.entries(ladder ?? {})) {
+    out[fmt] = Array.isArray(v)
+      ? Object.fromEntries([...v].sort((a, b) => a.w - b.w).map((f) => [f.w, fileUrl(entry, f, { setId })]))
+      : fileUrl(entry, v, { setId });
+  }
+  return out;
+}
+
+const DESCRIPTIVE = ['title', 'description', 'type', 'categories', 'subjects', 'colors', 'facing', 'view', 'composition', 'period', 'region', 'style', 'group', 'status', 'usage_notes', 'display_width'];
+const MEASURED = ['width', 'height', 'transparent', 'palette', 'thumbhash', 'resolutionLimited'];
+
+export function catalogEntry(setId, manifest, entry, assetId, asset) {
+  const e = { id: `${setId}/${assetId}`, set: setId, asset: assetId };
+  for (const k of [...DESCRIPTIVE, ...MEASURED]) if (asset[k] !== undefined && asset[k] !== null) e[k] = asset[k];
+  const r = asset.render ?? {};
+  e.render = {};
+  if (r.image) e.render.image = {};
+  if (r.tile) e.render.tile = { axis: r.tile.axis, period: r.tile.period };
+  if (r.frame) e.render.frame = { corner: r.frame.corner, slice: r.frame.slice };
+  e.license = asset.license ?? manifest.license.artwork;
+  e.attribution = asset.attribution ?? manifest.attribution ?? '';
+  e.urls = ladderUrls(entry, setId, asset.sources);
+  if (r.tile?.rotated) e.urls.rotated = ladderUrls(entry, setId, r.tile.rotated);
+  if (r.frame?.atlas) e.urls.atlas = ladderUrls(entry, setId, r.frame.atlas);
+  return e;
+}
+
+/**
+ * @param {object} o
+ * @param {Array<{setId: string, manifest: object, status?: string, repo?: string}>} o.manifests  Every set; the catalog is rebuilt from scratch.
+ * @param {object} [o.previous]  Previous index.json: its generatedAt is kept when the sets did not change.
+ * @param {string} [o.generatedAt]
+ * @returns {{index, catalog, sets, readme, agents}}
+ */
+export function generateIndex({ manifests, previous, generatedAt } = {}) {
+  const list = [...manifests].sort((a, b) => a.setId.localeCompare(b.setId));
+  const sets = {};
+  const entries = {};
+  for (const { setId, manifest, status } of list) {
+    sets[setId] = indexEntry(manifest, { status });
+    entries[setId] = manifest;
+  }
+  const unchanged = previous && JSON.stringify(previous.sets) === JSON.stringify(sets);
+  const stamp = unchanged ? previous.generatedAt : generatedAt ?? new Date().toISOString();
+  const index = { schema: 1, generatedAt: stamp, sets };
+  const assets = list.flatMap(({ setId, manifest }) =>
+    Object.entries(manifest.assets)
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([assetId, asset]) => catalogEntry(setId, manifest, sets[setId], assetId, asset)),
+  );
+  const catalog = { schema: 1, generatedAt: stamp, assets };
+  const setFiles = Object.fromEntries(list.map(({ setId, manifest }) => [setId, manifest]));
+  return { index, catalog, sets: setFiles, readme: readme(list), agents: agents(list) };
+}
+
+const cell = (s) => String(s ?? '').replace(/\|/g, '\\|').replace(/\n/g, ' ');
+
+function table(list) {
+  const rows = list.map(({ setId, manifest, repo }) => {
+    const r = repo ?? `${REPO}/ducktape-assets-${setId}`;
+    return `| \`${setId}\` | ${cell(manifest.title)} | ${cell(manifest.summary)} | ${Object.keys(manifest.assets).length} | ${cell(manifest.license.artwork)} | [repo](${r}) |`;
+  });
+  return ['| Set | Title | Summary | Assets | Licence | Repo |', '| --- | --- | --- | --- | --- | --- |', ...rows].join('\n');
+}
+
+const FLOWS = `1. **Paste a URL.** Any HTML, CSS or Markdown references one file on jsDelivr, for example \`https://cdn.jsdelivr.net/npm/@ranx729/ducktape-assets-walters-w102@1.2.0/webp/rabbit-church-bells-512.webp\`. Only that file is transferred. \`catalog.json\` lists the exact URL of every width and format, so nothing has to be guessed.
+2. **Pick and copy.** Keep a small \`ducktape.json\` listing the asset ids you want, with optional widths, formats and \`masters: true\`. \`npx @ranx729/ducktape-assets copy\` fetches exactly those files into the project (default \`src/assets/ducktape/\`), verifies every SHA-256 against the manifest, and writes \`ducktape.manifest.json\` beside them with type, dimensions (native and of the capped master), transparency, render geometry (tile axis, frame slice), thumbhash, licence and attribution per asset. \`masters: true\` alone copies only the lossless master (for apps that encode their own images); add \`formats\`, \`widths\` or \`max\` to copy ladder files as well. Re-running is idempotent.
+3. **Resolve in code.** \`npm i @ranx729/ducktape-assets\` installs metadata and a resolver, zero images. \`assets.image(id, { width })\` returns \`src\`, \`srcset\`, \`sizes\`, width, height, thumbhash, licence, \`attribution\`, and \`file\` / \`files\` (path, bytes and sha256 of every referenced rung, for scripts that record or verify what they use). Bytes come from the CDN at request time, or from flow 2 when \`base\` points at the copied directory.
+
+Build-time recipe in Node, offline, no network:
+
+\`\`\`js
+import { createNodeResolver } from '@ranx729/ducktape-assets/node';
+const assets = await createNodeResolver({ formats: ['webp'] });
+const img = await assets.image('walters-w102/rabbit-church-bells', { width: 256, dpr: 1 });
+// img.src is the smallest rung at or above 256 px (never upscaled); img.file.sha256 and img.file.bytes are the publisher's.
+// For an exact 2x pick ask for width 512 with dpr 1; the default dpr 3 returns the whole range for a srcset.
+\`\`\``;
+
+const CONFIG = `\`\`\`json
+{
+  "pin": "@ranx729/ducktape-assets@3.4.0",
+  "out": "src/assets/ducktape",
+  "assets": [
+    "walters-w102/rabbit-church-bells",
+    { "id": "numbered-plate/stepped-ribbon", "formats": ["avif", "webp"], "max": 1024 },
+    { "id": "illuminated-acanthus/divider-center", "masters": true }
+  ]
+}
+\`\`\``;
+
+const URLS = `\`https://cdn.jsdelivr.net/npm/@ranx729/ducktape-assets-<set>@<version>/<format>/<asset>-<w>.<ext>\`
+
+Exact-version URLs are immutable and cached for a year. Large sets are split into volume packages (\`…-<set>-part2\`); the catalog, the resolver and the copy command emit the right URL, so a consumer never notices the split.`;
+
+function readme(list) {
+  return `# Ducktape Assets
+
+Find an asset here, use it in under a minute. This package is metadata and a build-time resolver: it never contains an image. It is generated; do not edit it by hand.
+
+## Three ways to use an asset
+
+${FLOWS}
+
+\`ducktape.json\`:
+
+${CONFIG}
+
+## URLs
+
+${URLS}
+
+## Files
+
+- \`catalog.json\`: every asset with id, title, description, type, categories, subjects, colours, size, render capabilities, thumbhash, licence, attribution and the exact URL of each width and format.
+- \`sets/<set>.json\`: the published manifest of each set (hashes, bytes, components, volume packages).
+- \`index.json\`: the pinned version, packages and CDN base of each set.
+
+## Sets
+
+${table(list)}
+`;
+}
+
+function agents(list) {
+  return `# Ducktape Assets for agents
+
+Generated. Use these rules; do not edit this file by hand.
+
+## Finding an asset
+
+- Search \`catalog.json\` (one grep finds an asset and its URL). Ids are \`<set>/<asset>\`.
+- Read \`sets/<set>.json\` only for what the catalog leaves out (hashes, bytes, components, parts).
+
+## Using an asset
+
+${FLOWS}
+
+Prefer flow 2 for anything that must survive unattended: copied files do not depend on any host.
+
+\`ducktape.json\`:
+
+${CONFIG}
+
+## URLs
+
+${URLS}
+
+## Rules
+
+- Honour the licence block: show the \`attribution\` line when the asset's licence requires it.
+- Never use \`@latest\` or range URLs; always an exact version from \`index.json\` or \`catalog.json\`.
+- Never put a master on a page. Masters are for re-encoding in a build.
+- Images are decorative by default (\`alt=""\`); use \`description\` when the image carries meaning.
+- Always set the \`width\` and \`height\` attributes; the resolver returns them.
+
+## Sets
+
+${table(list)}
+`;
+}
+
+/** Write the generated files of a generateIndex() result into `dir`. */
+export async function writeIndex(dir, { index, catalog, sets, readme, agents }) {
+  const json = (v) => JSON.stringify(v, null, 2) + '\n';
+  await mkdir(join(dir, 'sets'), { recursive: true });
+  await Promise.all([
+    writeFile(join(dir, 'index.json'), json(index)),
+    writeFile(join(dir, 'catalog.json'), json(catalog)),
+    writeFile(join(dir, 'README.md'), readme),
+    writeFile(join(dir, 'AGENTS.md'), agents),
+    ...Object.entries(sets).map(([id, m]) => writeFile(join(dir, 'sets', `${id}.json`), json(m))),
+  ]);
+}

package/src/node.mjs

@@ -0,0 +1,21 @@
+// Node-only helpers. Kept apart so the resolver stays browser-safe.
+import { readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createResolver } from './resolver.mjs';
+
+/** loadManifest for createResolver: reads `sets/<set>.json` beside a local index.json. */
+export function fsManifestLoader(indexPath) {
+  const dir = dirname(indexPath);
+  return async (setId) => JSON.parse(await readFile(join(dir, 'sets', `${setId}.json`), 'utf8'));
+}
+
+/**
+ * A resolver over the data shipped in this package (or a local copy of it), with no network at all:
+ * the index and every set manifest are read from disk, so build scripts work offline and get the same
+ * hashes and bytes the publisher recorded. Options are those of createResolver plus `indexPath`.
+ */
+export async function createNodeResolver({ indexPath = fileURLToPath(new URL('../index.json', import.meta.url)), ...options } = {}) {
+  const index = JSON.parse(await readFile(indexPath, 'utf8'));
+  return createResolver({ index, loadManifest: fsManifestLoader(indexPath), ...options });
+}

package/src/resolver.mjs

@@ -0,0 +1,248 @@
+// Build-time resolver. Pure functions over index.json and per-set manifests; no DOM, no dependencies.
+import { fileUrl, packageCdn } from './urls.mjs';
+import { selectRungs, pickByDimension, dprList, maxOf } from './rungs.mjs';
+import { thumbHashToDataUrl } from './thumbhash.mjs';
+
+const MIME = { avif: 'image/avif', webp: 'image/webp', png: 'image/png', jpeg: 'image/jpeg', svg: 'image/svg+xml' };
+const mime = (fmt) => MIME[fmt] ?? `image/${fmt}`;
+const esc = (s) => String(s).replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+const cssUrl = (u) => `url("${u.replace(/"/g, '%22')}")`;
+const attrs = (o) =>
+  Object.entries(o)
+    .filter(([, v]) => v !== false && v != null)
+    .map(([k, v]) => (v === true ? k : `${k}="${esc(v)}"`))
+    .join(' ');
+
+async function getJson(url) {
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`${url}: HTTP ${res.status}`);
+  return res.json();
+}
+
+/**
+ * @param {object} [options]
+ * @param {object|string} [options.index]  index.json object, or its URL. Default: the index.json shipped in this package.
+ * @param {string} [options.base]          Self-hosted tree (`<base>/<set>/<path>`), e.g. the output of the copy command.
+ * @param {string[]} [options.formats]     Preference order. The last one present is the <img> fallback.
+ * @param {Record<string,string>} [options.pin]  Per-set version override, { setId: '1.2.0' }.
+ * @param {number|number[]} [options.dpr]  Highest density of interest (default 3).
+ * @param {(setId: string, ctx: {entry: object, cdn: string}) => Promise<object>} [options.loadManifest]
+ *        Default fetches `<cdn>manifest.json`. In Node, `fsManifestLoader` from `@ranx729/ducktape-assets/node` reads sets/<set>.json.
+ */
+export function createResolver({ index, base, formats = ['avif', 'webp'], pin = {}, dpr, loadManifest } = {}) {
+  let idx = index && typeof index === 'object' ? index : null;
+  let idxPromise;
+  const manifests = new Map();
+
+  function getIndex() {
+    idxPromise ??= (async () => {
+      if (idx) return idx;
+      idx =
+        typeof index === 'string'
+          ? await getJson(index)
+          : (await import('../index.json', { with: { type: 'json' } })).default;
+      return idx;
+    })();
+    return idxPromise;
+  }
+
+  const splitId = (id) => {
+    const i = id.indexOf('/');
+    if (i < 1 || i === id.length - 1) throw new Error(`asset id must be "<set>/<asset>", got "${id}"`);
+    return [id.slice(0, i), id.slice(i + 1)];
+  };
+
+  async function entryOf(setId) {
+    const entry = (await getIndex()).sets[setId];
+    if (!entry) throw new Error(`unknown set "${setId}"`);
+    return entry;
+  }
+
+  const urlOf = (entry, file, setId) => fileUrl(entry, file, { setId, base, version: pin[setId] });
+
+  function manifestOf(setId) {
+    if (!manifests.has(setId)) {
+      manifests.set(
+        setId,
+        (async () => {
+          const entry = await entryOf(setId);
+          const cdn = packageCdn(entry, undefined, pin[setId] ?? entry.version);
+          const m = await (loadManifest ? loadManifest(setId, { entry, cdn }) : getJson(`${cdn}manifest.json`));
+          return m;
+        })(),
+      );
+    }
+    return manifests.get(setId);
+  }
+
+  /** Everything known about one asset: { id, setId, assetId, entry, manifest, asset }. */
+  async function get(id) {
+    const [setId, assetId] = splitId(id);
+    const entry = await entryOf(setId);
+    const manifest = await manifestOf(setId);
+    const asset = manifest.assets[assetId];
+    if (!asset) throw new Error(`unknown asset "${id}"`);
+    return { id, setId, assetId, entry, manifest, asset };
+  }
+
+  /** Synchronous; the index must already be loaded (any awaited call loads it) unless `base` is set. */
+  function url(file, setId) {
+    if (!setId) throw new Error('url(file, setId): setId is required');
+    if (!base && !idx) throw new Error('index not loaded yet; await any resolver call first or pass index');
+    return urlOf(idx?.sets[setId], file, setId);
+  }
+
+  const licenseOf = ({ asset, manifest }) => ({ ...manifest.license, artwork: asset.license ?? manifest.license.artwork });
+  const attributionOf = ({ asset, manifest }) => asset.attribution ?? manifest.attribution ?? '';
+
+  async function image(id, { width, sizes, dpr: d, placeholder = true } = {}) {
+    const ctx = await get(id);
+    const { setId, entry, asset } = ctx;
+    const maxDpr = maxOf(d ?? dpr, 3);
+    const sources = [];
+    const files = [];
+    const fileOf = (fmt, r) => ({ format: fmt, url: urlOf(entry, r, setId), path: r.path, width: r.w, height: r.h, bytes: r.bytes, sha256: r.sha256, ...(r.package ? { package: r.package } : {}) });
+    let fallback;
+    let fallbackFmt;
+    for (const fmt of formats) {
+      const ladder = asset.sources?.[fmt];
+      if (!Array.isArray(ladder) || !ladder.length) continue;
+      const sel = selectRungs(ladder, width, { maxDpr });
+      sources.push({ type: mime(fmt), srcset: sel.rungs.map((r) => `${urlOf(entry, r, setId)} ${r.w}w`).join(', ') });
+      files.push(...sel.rungs.map((r) => fileOf(fmt, r)));
+      fallback = sel;
+      fallbackFmt = fmt;
+    }
+    if (!fallback) throw new Error(`${id}: none of the formats ${formats.join(', ')} is available`);
+    const out = {
+      src: urlOf(entry, fallback.src, setId),
+      srcset: sources[sources.length - 1].srcset,
+      sources,
+      // The chosen files with their bytes and sha256, for build scripts that record or verify what they reference.
+      // `file` is the one behind `src`; `files` lists every rung of every format in the srcsets.
+      file: fileOf(fallbackFmt, fallback.src),
+      files,
+      sizes: sizes ?? (width ? `${width}px` : '100vw'),
+      width: asset.width,
+      height: asset.height,
+      thumbhash: asset.thumbhash,
+      alt: '',
+      description: asset.description,
+      license: licenseOf(ctx),
+      attribution: attributionOf(ctx),
+      resolutionLimited: Boolean(width && asset.width < width),
+    };
+    if (placeholder && asset.thumbhash) out.placeholderDataUrl = thumbHashToDataUrl(asset.thumbhash);
+    if (asset.sources?.svg) out.svg = urlOf(entry, asset.sources.svg, setId);
+    return out;
+  }
+
+  /** `<picture>` markup. `extra` is added to the <img>. */
+  function picture(img, extra = {}) {
+    const lead = img.sources.slice(0, -1);
+    const style = [img.placeholderDataUrl && `background: url(${img.placeholderDataUrl}) center / cover`, extra.style]
+      .filter(Boolean)
+      .join('; ');
+    const { style: _s, ...rest } = extra;
+    const tag = `<img ${attrs({ src: img.src, srcset: img.srcset, sizes: img.sizes, width: img.width, height: img.height, alt: img.alt, ...rest, style: style || null })}>`;
+    if (!lead.length) return tag;
+    const srcs = lead.map((s) => `  <source ${attrs({ type: s.type, srcset: s.srcset, sizes: img.sizes })}>`);
+    return `<picture>\n${srcs.join('\n')}\n  ${tag}\n</picture>`;
+  }
+
+  /** `<link rel="preload">` for an above-the-fold image, in the most preferred format. */
+  function preload(img) {
+    const s = img.sources[0];
+    return `<link ${attrs({ rel: 'preload', as: 'image', type: s.type, href: img.src, imagesrcset: s.srcset, imagesizes: img.sizes, fetchpriority: 'high' })}>`;
+  }
+
+  /** image-set() candidates over the preferred formats, one entry per (format, density), deduplicated by URL. */
+  function imageSet(entry, setId, ladder, key, thickness, dprs, geom) {
+    const parts = [];
+    let ref;
+    for (const fmt of formats) {
+      const files = ladder?.[fmt];
+      if (!Array.isArray(files) || !files.length) continue;
+      const seen = new Set();
+      for (const x of dprs) {
+        const f = pickByDimension(files, key, geom(x));
+        ref ??= f;
+        const u = urlOf(entry, f, setId);
+        if (seen.has(u)) continue;
+        seen.add(u);
+        parts.push(`${cssUrl(u)} type("${mime(fmt)}") ${x}x`);
+      }
+    }
+    return { set: parts.length ? `image-set(${parts.join(', ')})` : null, ref };
+  }
+
+  /** CSS declarations for a repeating border (`render.tile`). Prefers the SVG of the chosen ladder. */
+  async function tile(id, { axis, thickness, dpr: d } = {}) {
+    const { setId, entry, asset } = await get(id);
+    const t = asset.render?.tile;
+    if (!t) throw new Error(`${id} has no render.tile`);
+    axis ??= t.axis;
+    const ladder = axis === t.axis ? asset.sources : t.rotated;
+    const key = axis === 'x' ? 'h' : 'w'; // thickness dimension in the displayed orientation
+    thickness ??= t.axis === 'x' ? asset.height : asset.width;
+    let image, ref;
+    if (ladder?.svg) {
+      ref = ladder.svg;
+      image = cssUrl(urlOf(entry, ref, setId));
+    } else {
+      ({ set: image, ref } = imageSet(entry, setId, ladder, key, thickness, dprList(d ?? dpr, [1, 2]), (x) => thickness * x));
+    }
+    if (!image) throw new Error(`${id}: no ${axis}-axis ladder in formats ${formats.join(', ')}`);
+    const len = Math.round(thickness * (axis === 'x' ? ref.w / ref.h : ref.h / ref.w) * 100) / 100;
+    return [
+      `background-image: ${image};`,
+      `background-repeat: ${axis === 'x' ? 'round no-repeat' : 'no-repeat round'};`,
+      `background-size: ${axis === 'x' ? `${len}px ${thickness}px` : `${thickness}px ${len}px`};`,
+    ].join('\n');
+  }
+
+  /** `border-image` rule for a frame (`render.frame`): the atlas rung whose slice region covers `thickness` at each density. */
+  async function frame(id, { thickness, dpr: d } = {}) {
+    const { setId, entry, asset } = await get(id);
+    const f = asset.render?.frame;
+    if (!f) throw new Error(`${id} has no render.frame`);
+    // Composed atlases record one percentage; ready-made frames record four (top right bottom left) because a uniform
+    // pixel slice is a different share of the width and of the height. The CSS value and the coverage maths follow.
+    const slice = f.slice;
+    const sliceCss = typeof slice === 'number' ? `${slice}%` : `${slice.top}% ${slice.right}% ${slice.bottom}% ${slice.left}%`;
+    const sliceW = typeof slice === 'number' ? slice : slice.left; // share of the atlas width that must cover `thickness`
+    const atlas = f.atlas;
+    const dprs = dprList(d ?? dpr, [1, 2, 3]);
+    const smallest = Object.values(atlas).find(Array.isArray)?.[0];
+    thickness ??= smallest ? Math.round((smallest.w * sliceW) / 100) : 16;
+    // the slice region (sliceW% of the atlas width) must map onto `thickness` css px at density x
+    const need = (x) => (thickness * x * 100) / sliceW;
+    let value;
+    if (atlas.svg) value = cssUrl(urlOf(entry, atlas.svg, setId));
+    else value = imageSet(entry, setId, atlas, 'w', thickness, dprs, need).set;
+    if (!value) throw new Error(`${id}: no atlas in formats ${formats.join(', ')}`);
+    const fmt = formats.find((x) => atlas[x]?.length);
+    const atlasSrcset = fmt
+      ? [...new Set(dprs.map((x) => pickByDimension(atlas[fmt], 'w', need(x))))]
+          .map((r) => `${urlOf(entry, r, setId)} ${r.w}w`)
+          .join(', ')
+      : '';
+    const css = [`border-style: solid;`, `border-width: ${thickness}px;`, `border-image: ${value} ${sliceCss} round;`].join('\n');
+    return { css, slice, sliceCss, atlasSrcset };
+  }
+
+  /** Paths of the files the copy command writes for an asset (all rungs), for flows that import local files. */
+  async function local(id, { dir = '' } = {}) {
+    const { setId, assetId, asset } = await get(id);
+    const at = (file) => [dir.replace(/\/+$/, ''), setId, file.path].filter(Boolean).join('/');
+    const ladderPaths = (l) =>
+      l && Object.fromEntries(Object.entries(l).map(([k, v]) => [k, Array.isArray(v) ? v.map((f) => ({ w: f.w, h: f.h, path: at(f) })) : { w: v.w, h: v.h, path: at(v) }]));
+    const files = { sources: ladderPaths(asset.sources) };
+    if (asset.render?.tile?.rotated) files.rotated = ladderPaths(asset.render.tile.rotated);
+    if (asset.render?.frame?.atlas) files.atlas = ladderPaths(asset.render.frame.atlas);
+    files.master = at(asset.master ?? { path: `masters/${assetId}.webp` });
+    return { id, width: asset.width, height: asset.height, thumbhash: asset.thumbhash, files };
+  }
+
+  return { image, picture, preload, tile, frame, local, url, get, index: getIndex, manifest: manifestOf };
+}

package/src/rungs.mjs

@@ -0,0 +1,34 @@
+// Rung selection. Pure functions over ladders: arrays of { w, h, path, ... }.
+
+const asc = (key) => (a, b) => a[key] - b[key];
+
+/**
+ * From the smallest rung >= width up to the smallest rung >= width * maxDpr, never upscaling
+ * (a missing rung falls back to the top one). `src` is the smallest rung >= width * srcDpr.
+ * Without a width the whole ladder is returned and `src` is the largest rung up to 1024.
+ */
+export function selectRungs(ladder, width, { maxDpr = 3, srcDpr = 2 } = {}) {
+  const l = [...ladder].sort(asc('w'));
+  const top = l[l.length - 1];
+  if (!width) return { rungs: l, src: [...l].reverse().find((r) => r.w <= 1024) ?? l[0] };
+  const lo = l.find((r) => r.w >= width) ?? top;
+  const hi = l.find((r) => r.w >= width * maxDpr) ?? top;
+  const rungs = l.filter((r) => r.w >= lo.w && r.w <= hi.w);
+  const src = l.find((r) => r.w >= width * Math.min(srcDpr, maxDpr)) ?? top;
+  return { rungs, src };
+}
+
+/** Smallest file whose `key` dimension ('w' or 'h') covers `need` (half a pixel of tolerance), else the largest. */
+export function pickByDimension(files, key, need) {
+  const l = [...files].sort(asc(key));
+  return l.find((f) => f[key] >= need - 0.5) ?? l[l.length - 1];
+}
+
+/** Normalise a dpr option: a number n means 1..n, an array is used as given. */
+export function dprList(d, fallback) {
+  const v = d ?? fallback;
+  if (Array.isArray(v)) return [...new Set(v)].sort((a, b) => a - b);
+  return Array.from({ length: Math.max(1, Math.ceil(v)) }, (_, i) => i + 1);
+}
+
+export const maxOf = (d, fallback) => Math.max(...dprList(d, fallback));