@ranx729/ducktape-assets 1.0.0 → 1.2.0

package/src/generate.mjs

@@ -90,8 +90,18 @@ function table(list) {
 }
 
 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 dimensions, thumbhash, licence and attribution per asset. 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 and licence. Bytes come from the CDN at request time, or from flow 2 when \`base\` points at the copied directory.`;
+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
 {

package/src/node.mjs

@@ -1,9 +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

@@ -100,19 +100,28 @@ export function createResolver({ index, base, formats = ['avif', 'webp'], pin =
     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,
@@ -197,13 +206,17 @@ export function createResolver({ index, base, formats = ['avif', 'webp'], pin =
     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 * slice) / 100) : 16;
-    // the slice region (slice% of the atlas) must map onto `thickness` css px at density x
-    const need = (x) => (thickness * x * 100) / slice;
+    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;
@@ -214,8 +227,8 @@ export function createResolver({ index, base, formats = ['avif', 'webp'], pin =
           .map((r) => `${urlOf(entry, r, setId)} ${r.w}w`)
           .join(', ')
       : '';
-    const css = [`border-style: solid;`, `border-width: ${thickness}px;`, `border-image: ${value} ${slice}% round;`].join('\n');
-    return { css, slice, atlasSrcset };
+    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. */