@ranx729/ducktape-assets 1.0.0 → 1.1.0

package/AGENTS.md

@@ -10,8 +10,18 @@ Generated. Use these rules; do not edit this file by hand.
 ## Using an asset
 
 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.
+```
 
 Prefer flow 2 for anything that must survive unattended: copied files do not depend on any host.
 

package/README.md

@@ -5,8 +5,18 @@ Find an asset here, use it in under a minute. This package is metadata and a bui
 ## Three ways to use an asset
 
 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.
+```
 
 `ducktape.json`: