@ranx729/ducktape-assets 0.0.0 → 1.0.0

package/AGENTS.md

@@ -0,0 +1,52 @@
+# 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
+
+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.
+
+Prefer flow 2 for anything that must survive unattended: copied files do not depend on any host.
+
+`ducktape.json`:
+
+```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 }
+  ]
+}
+```
+
+## 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.
+
+## 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
+
+| Set | Title | Summary | Assets | Licence | Repo |
+| --- | --- | --- | --- | --- | --- |
+| `illuminated-acanthus` | Illuminated acanthus | Red, blue and gold acanthus corners, dividers, frames, margin rods, sprigs and a muse figure in the style of a 15th-century Flemish illuminated border, AI-generated by adrian729 from style references for the Polyhymnia app. | 36 | CC-BY-4.0 | [repo](https://github.com/adrian729/ducktape-assets-illuminated-acanthus) |
+| `medieval-cutouts` | Medieval cutouts | A legacy collection of 41 painted cut-outs in a medieval manuscript style (animal and human musicians, drolleries, readers and single animals) whose origin was never recorded. | 41 | CC-BY-4.0 | [repo](https://github.com/adrian729/ducktape-assets-medieval-cutouts) |
+| `walters-w102` | Walters W.102 marginalia | Marginal creatures and scenes from Walters Art Museum W.102, a Flemish book of hours of around 1300 whose margins are filled with animal musicians, hybrids and small architectural vignettes. | 4 | CC0-1.0 | [repo](https://github.com/adrian729/ducktape-assets-walters-w102) |

package/README.md

@@ -1,3 +1,43 @@
-# @ranx729/ducktape-assets
+# Ducktape Assets
 
-Placeholder. See https://github.com/adrian729/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
+
+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.
+
+`ducktape.json`:
+
+```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 }
+  ]
+}
+```
+
+## 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.
+
+## 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
+
+| Set | Title | Summary | Assets | Licence | Repo |
+| --- | --- | --- | --- | --- | --- |
+| `illuminated-acanthus` | Illuminated acanthus | Red, blue and gold acanthus corners, dividers, frames, margin rods, sprigs and a muse figure in the style of a 15th-century Flemish illuminated border, AI-generated by adrian729 from style references for the Polyhymnia app. | 36 | CC-BY-4.0 | [repo](https://github.com/adrian729/ducktape-assets-illuminated-acanthus) |
+| `medieval-cutouts` | Medieval cutouts | A legacy collection of 41 painted cut-outs in a medieval manuscript style (animal and human musicians, drolleries, readers and single animals) whose origin was never recorded. | 41 | CC-BY-4.0 | [repo](https://github.com/adrian729/ducktape-assets-medieval-cutouts) |
+| `walters-w102` | Walters W.102 marginalia | Marginal creatures and scenes from Walters Art Museum W.102, a Flemish book of hours of around 1300 whose margins are filled with animal musicians, hybrids and small architectural vignettes. | 4 | CC0-1.0 | [repo](https://github.com/adrian729/ducktape-assets-walters-w102) |

package/bin/ducktape-assets.mjs

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { readFile } from 'node:fs/promises';
+import { copy } from '../src/copy.mjs';
+
+const [command, ...rest] = process.argv.slice(2);
+
+const HELP = `usage: ducktape-assets copy [--config ducktape.json] [--out dir]
+
+  --config   project config (default ducktape.json): { pin, out, assets: [ "set/id" | { id, formats?, max?, widths?, masters? } ] }
+  --out      destination (default: config "out", else src/assets/ducktape)
+  --index    local path or URL of index.json (default: the pin's package on jsDelivr)
+  --base     directory or URL laid out as <base>/<set>/<path> to read files from instead of the CDN`;
+
+if (!command || command === '--help' || command === '-h') {
+  console.log(HELP);
+} else if (command === 'copy') {
+  try {
+    const { values } = parseArgs({
+      args: rest,
+      options: { config: { type: 'string', default: 'ducktape.json' }, out: { type: 'string' }, index: { type: 'string' }, base: { type: 'string' } },
+    });
+    const config = JSON.parse(await readFile(values.config, 'utf8'));
+    const out = values.out ?? config.out ?? 'src/assets/ducktape';
+    const r = await copy({ config, out, index: values.index, base: values.base, log: (m) => console.log(m) });
+    console.log(`${r.copied} copied, ${r.skipped} up to date, manifest at ${out}/ducktape.manifest.json`);
+  } catch (e) {
+    console.error(`ducktape-assets: ${e.message}`);
+    process.exitCode = 1;
+  }
+} else {
+  console.error(`unknown command "${command}"; run with --help`);
+  process.exitCode = 2;
+}