@arraypress/covers 0.0.0-stage → 1.0.0

package/src/geometry.js

@@ -0,0 +1,187 @@
+/**
+ * Canvas size, lengths and anchoring.
+ *
+ * Lengths are pixels when given as numbers, or CSS-style viewport units as
+ * strings: `'6vmin'` (6% of the shorter side), `'4vw'`, `'4vh'`, `'5vmax'`.
+ * Defaults are written in these units, so a cover keeps its proportions at
+ * any output size.
+ *
+ * @module geometry
+ */
+
+/** Named aspect ratios, as `width / height`. */
+export const ASPECTS = Object.freeze({
+  '1:1': 1,
+  '16:9': 16 / 9,
+  '4:5': 4 / 5,
+  '3:2': 3 / 2,
+  '4:3': 4 / 3,
+  '2:1': 2,
+  '9:16': 9 / 16,
+  og: 1200 / 630,
+});
+
+/**
+ * Work out a cover's pixel size from `width`, `height` and `aspect`.
+ *
+ * - both `width` and `height` → used as given
+ * - one side + `aspect` → the other side follows
+ * - `aspect` only → 1200 wide (`'og'` is exactly 1200×630)
+ * - nothing → 1200×1200
+ *
+ * @param {{ width?: number, height?: number, aspect?: string | number }} opts
+ * @returns {{ width: number, height: number }} Integer pixel size.
+ * @throws {RangeError} On a non-positive size or an unreadable aspect.
+ *
+ * @example
+ * resolveSize({ aspect: '16:9' });            // { width: 1200, height: 675 }
+ * resolveSize({ height: 800, aspect: '3:2' }); // { width: 1200, height: 800 }
+ */
+export function resolveSize({ width, height, aspect } = {}) {
+  if (width && height) return checkSize(width, height);
+  const ratio = aspectRatio(aspect ?? (width || height ? undefined : '1:1'));
+  if (ratio == null) return checkSize(width ?? height ?? 1200, height ?? width ?? 1200);
+  if (height && !width) return checkSize(height * ratio, height);
+  return checkSize(width ?? 1200, (width ?? 1200) / ratio);
+}
+
+/**
+ * Parse an aspect: a named one, `'a:b'`, `'a/b'` or a number.
+ *
+ * @param {string | number | undefined} aspect
+ * @returns {number | undefined} `width / height`, or undefined when none was given.
+ * @throws {RangeError} On a string that isn't an aspect.
+ */
+export function aspectRatio(aspect) {
+  if (aspect == null) return undefined;
+  if (typeof aspect === 'number') {
+    if (aspect > 0) return aspect;
+    throw new RangeError(`Invalid aspect ${aspect}`);
+  }
+  if (Object.hasOwn(ASPECTS, aspect)) return ASPECTS[aspect];
+  const m = String(aspect).match(/^\s*(\d+(?:\.\d+)?)\s*[:/x]\s*(\d+(?:\.\d+)?)\s*$/);
+  if (m && +m[1] > 0 && +m[2] > 0) return +m[1] / +m[2];
+  throw new RangeError(`Invalid aspect "${aspect}". Use one of ${Object.keys(ASPECTS).join(', ')} or "w:h".`);
+}
+
+/**
+ * @param {number} w @param {number} h
+ * @returns {{ width: number, height: number }}
+ */
+function checkSize(w, h) {
+  const width = Math.round(w);
+  const height = Math.round(h);
+  if (!(width > 0 && height > 0) || width > 8192 || height > 8192) {
+    throw new RangeError(`Cover size must be 1–8192px per side, got ${width}×${height}`);
+  }
+  return { width, height };
+}
+
+/**
+ * Resolve a length to pixels.
+ *
+ * @param {number | string | undefined | null} value - Pixels, or `'Nvmin'` / `'Nvw'` / `'Nvh'` / `'Nvmax'`.
+ * @param {{ width: number, height: number }} canvas - The canvas size.
+ * @param {number | string} [fallback=0] - Used when `value` is undefined or null.
+ * @returns {number} Pixels.
+ * @throws {TypeError} On a string with an unknown unit.
+ *
+ * @example
+ * len('5vmin', { width: 1200, height: 630 });  // 31.5
+ * len(undefined, canvas, '6vmin');             // the default
+ */
+export function len(value, canvas, fallback = 0) {
+  const v = value ?? fallback;
+  if (typeof v === 'number') return v;
+  const m = String(v).match(/^\s*(-?\d*\.?\d+)\s*(vmin|vmax|vw|vh|px)?\s*$/);
+  if (!m) throw new TypeError(`Invalid length "${v}" (use px numbers or vmin/vmax/vw/vh)`);
+  const n = parseFloat(m[1]);
+  switch (m[2]) {
+    case 'vmin': return (n / 100) * Math.min(canvas.width, canvas.height);
+    case 'vmax': return (n / 100) * Math.max(canvas.width, canvas.height);
+    case 'vw': return (n / 100) * canvas.width;
+    case 'vh': return (n / 100) * canvas.height;
+    default: return n;
+  }
+}
+
+/** The nine anchors, as fractions of the free space along x and y. */
+const ANCHORS = Object.freeze({
+  'top-left': [0, 0], top: [0.5, 0], 'top-right': [1, 0],
+  left: [0, 0.5], center: [0.5, 0.5], right: [1, 0.5],
+  'bottom-left': [0, 1], bottom: [0.5, 1], 'bottom-right': [1, 1],
+});
+
+/**
+ * Place a box on the canvas.
+ *
+ * With `position` (fractions 0–1 of the canvas, the box's anchor point
+ * goes there), the margin is ignored. Otherwise the box sits at `anchor`
+ * inside the safe area (`margin` in from every edge). `offset` nudges it
+ * either way.
+ *
+ * @param {object} o
+ * @param {number} o.width - Box width.
+ * @param {number} o.height - Box height.
+ * @param {{ width: number, height: number }} o.canvas - The canvas.
+ * @param {import('./index.js').Anchor} [o.anchor='center'] - Where it sits.
+ * @param {number} [o.margin=0] - Safe margin in px.
+ * @param {{ x?: number, y?: number }} [o.position] - Explicit placement (fractions).
+ * @param {{ x?: number | string, y?: number | string }} [o.offset] - Extra shift (lengths).
+ * @returns {{ x: number, y: number }} The box's top-left corner.
+ * @throws {TypeError} On an unknown anchor.
+ */
+export function place({ width, height, canvas, anchor = 'center', margin = 0, position, offset }) {
+  const a = ANCHORS[anchor];
+  if (!a) throw new TypeError(`Unknown anchor "${anchor}". Use ${Object.keys(ANCHORS).join(', ')}.`);
+  let x;
+  let y;
+  if (position && (position.x != null || position.y != null)) {
+    x = (position.x ?? 0.5) * canvas.width - a[0] * width;
+    y = (position.y ?? 0.5) * canvas.height - a[1] * height;
+  } else {
+    x = margin + a[0] * (canvas.width - 2 * margin - width);
+    y = margin + a[1] * (canvas.height - 2 * margin - height);
+  }
+  return { x: x + len(offset?.x, canvas, 0), y: y + len(offset?.y, canvas, 0) };
+}
+
+/**
+ * The anchor's horizontal alignment (`'left'`, `'center'`, `'right'`).
+ *
+ * @param {import('./index.js').Anchor} anchor
+ * @returns {'left' | 'center' | 'right'} Alignment.
+ */
+export function anchorAlign(anchor = 'center') {
+  const fx = ANCHORS[anchor]?.[0] ?? 0.5;
+  return fx === 0 ? 'left' : fx === 1 ? 'right' : 'center';
+}
+
+/**
+ * The shared "design unit" for a canvas: the geometric mean of its sides.
+ * Type and margins scale with it, so a 1200×630 card and a 1200×1200
+ * square get proportionate (not identical) headlines.
+ *
+ * @param {{ width: number, height: number }} canvas
+ * @returns {number} Pixels.
+ */
+export function unit(canvas) {
+  return Math.sqrt(canvas.width * canvas.height);
+}
+
+/**
+ * Resolve a region (fractions of the canvas) to pixels.
+ *
+ * @param {{ x?: number, y?: number, width?: number, height?: number } | undefined} region
+ * @param {{ width: number, height: number }} canvas
+ * @returns {{ x: number, y: number, width: number, height: number }} Pixels.
+ */
+export function regionPx(region, canvas) {
+  const r = region ?? {};
+  return {
+    x: (r.x ?? 0) * canvas.width,
+    y: (r.y ?? 0) * canvas.height,
+    width: (r.width ?? 1 - (r.x ?? 0)) * canvas.width,
+    height: (r.height ?? 1 - (r.y ?? 0)) * canvas.height,
+  };
+}

package/src/grid.js

@@ -0,0 +1,41 @@
+/**
+ * Grid lines that break around content.
+ *
+ * @module grid
+ */
+
+import { num } from './svg.js';
+
+/**
+ * Path data for full-length grid lines at `xs` (columns) and `ys` (rows),
+ * each broken where it crosses one of the `gaps` rectangles, so a grid can
+ * pass behind content without running through it.
+ *
+ * @param {number[]} xs @param {number[]} ys
+ * @param {number} w @param {number} h
+ * @param {{ x: number, y: number, width: number, height: number }[]} gaps - Pixel rects.
+ * @returns {string} Path data.
+ */
+export function gridPath(xs, ys, w, h, gaps) {
+  const cut = (/** @type {number} */ len, /** @type {[number, number][]} */ holes) => {
+    const runs = [];
+    let at = 0;
+    for (const [a, b] of holes.filter(([a, b]) => b > 0 && a < len).sort((p, q) => p[0] - q[0])) {
+      if (a > at) runs.push([at, a]);
+      at = Math.max(at, b);
+    }
+    if (at < len) runs.push([at, len]);
+    return runs;
+  };
+  let d = '';
+  for (const y of ys) {
+    const holes = gaps.filter((g) => y >= g.y && y <= g.y + g.height).map((g) => /** @type {[number, number]} */ ([g.x, g.x + g.width]));
+    for (const [a, b] of cut(w, holes)) d += `M${num(a)} ${num(y)}H${num(b)}`;
+  }
+  for (const x of xs) {
+    const holes = gaps.filter((g) => x >= g.x && x <= g.x + g.width).map((g) => /** @type {[number, number]} */ ([g.y, g.y + g.height]));
+    for (const [a, b] of cut(h, holes)) d += `M${num(x)} ${num(a)}V${num(b)}`;
+  }
+  return d;
+}
+

package/src/handmade.js

@@ -0,0 +1,253 @@
+/**
+ * Hand-made layers: cut paper and hand-drawn lines.
+ *
+ * - `paper`    flat shapes with scissor-cut edges: the outline is resampled
+ *              into short straight cuts and each cut point nudged off the
+ *              line (seeded), so edges are irregular but never blurry.
+ * - `scribble` an icon re-drawn by hand (its outline flattened, wobbled with
+ *              smooth seeded noise and stroked at a varying width with round
+ *              caps), or a small node graph: a polyline with filled dots.
+ *
+ * @module handmade
+ */
+
+import { attrs, num, layerAttrs } from './svg.js';
+import { len, regionPx } from './geometry.js';
+import { toHex } from './color.js';
+import { resolveIcon, parseSvgIcon } from './icons.js';
+import { flattenBody, densify } from './flatten.js';
+
+/** Off-white paper. */
+export const PAPER = '#faf9f5';
+/** Near-black ink. */
+export const INK = '#141413';
+
+/**
+ * Smooth 1D value noise from a seeded stream: `noise(t)` in [-1, 1].
+ *
+ * @param {import('./rng.js').Rng} rng
+ * @returns {(t: number) => number}
+ */
+function noise1(rng) {
+  const knots = Array.from({ length: 64 }, () => rng.range(-1, 1));
+  return (t) => {
+    const i = Math.floor(t);
+    const f = t - i;
+    const a = knots[((i % 64) + 64) % 64];
+    const b = knots[(((i + 1) % 64) + 64) % 64];
+    const e = f * f * (3 - 2 * f);
+    return a + (b - a) * e;
+  };
+}
+
+/**
+ * Resample a closed outline into scissor cuts: points every `cut` px, each
+ * nudged by up to `wobble` px across the edge.
+ *
+ * @param {[number, number][]} outline - A closed polyline (first point not repeated).
+ * @param {number} cut - Cut length in px.
+ * @param {number} wobble - Max nudge in px.
+ * @param {import('./rng.js').Rng} rng
+ * @returns {string} Path data.
+ */
+function scissor(outline, cut, wobble, rng) {
+  const pts = densify([...outline, outline[0]], cut / 6);
+  /** @type {[number, number][]} */
+  const out = [];
+  let acc = cut;
+  for (let i = 1; i < pts.length; i++) {
+    acc += Math.hypot(pts[i][0] - pts[i - 1][0], pts[i][1] - pts[i - 1][1]);
+    if (acc >= cut * rng.range(0.6, 1.4)) {
+      acc = 0;
+      const [x0, y0] = pts[i - 1];
+      const [x1, y1] = pts[i];
+      const l = Math.hypot(x1 - x0, y1 - y0) || 1;
+      const k = rng.range(-wobble, wobble);
+      out.push([x1 + (-(y1 - y0) / l) * k, y1 + ((x1 - x0) / l) * k]);
+    }
+  }
+  return `M${out.map(([x, y]) => `${num(x)} ${num(y)}`).join('L')}Z`;
+}
+
+/**
+ * A shape's outline, centred on the origin.
+ *
+ * @param {string} kind - rect | square | circle | blob | arch | pill
+ * @param {number} w @param {number} h
+ * @param {import('./rng.js').Rng} rng
+ * @returns {[number, number][]}
+ */
+function outlineOf(kind, w, h, rng) {
+  const ellipse = (rx, ry, bump = 0) => {
+    const n = 72;
+    const wave = noise1(rng);
+    return Array.from({ length: n }, (_, i) => {
+      const a = (i / n) * Math.PI * 2;
+      const r = 1 + bump * wave((i / n) * 5);
+      return /** @type {[number, number]} */ ([Math.cos(a) * rx * r, Math.sin(a) * ry * r]);
+    });
+  };
+  if (kind === 'circle') return ellipse(w / 2, h / 2);
+  if (kind === 'blob') return ellipse(w / 2, h / 2, 0.16);
+  if (kind === 'pill') {
+    const r = Math.min(w, h) / 2;
+    const pts = [];
+    for (let i = 0; i <= 18; i++) { const a = -Math.PI / 2 + (i / 18) * Math.PI; pts.push([w / 2 - r + Math.cos(a) * r, Math.sin(a) * r]); }
+    for (let i = 0; i <= 18; i++) { const a = Math.PI / 2 + (i / 18) * Math.PI; pts.push([-w / 2 + r + Math.cos(a) * r, Math.sin(a) * r]); }
+    return /** @type {[number, number][]} */ (pts);
+  }
+  if (kind === 'arch') {
+    const r = w / 2;
+    const pts = [[w / 2, h / 2], [-w / 2, h / 2]];
+    for (let i = 0; i <= 24; i++) { const a = Math.PI + (i / 24) * Math.PI; pts.push([Math.cos(a) * r, -h / 2 + r + Math.sin(a) * r]); }
+    return /** @type {[number, number][]} */ (pts);
+  }
+  // rect / square: corners slightly off-true, as if cut by eye.
+  const j = () => rng.range(-0.04, 0.04) * Math.min(w, h);
+  return [[-w / 2 + j(), -h / 2 + j()], [w / 2 + j(), -h / 2 + j()], [w / 2 + j(), h / 2 + j()], [-w / 2 + j(), h / 2 + j()]];
+}
+
+/**
+ * The `paper` layer.
+ *
+ * @param {import('./index.js').PaperLayer} layer
+ * @param {import('./layers.js').RenderContext} ctx
+ * @returns {import('./layers.js').Markup}
+ */
+export function paper(layer, ctx) {
+  const { rng } = ctx;
+  const r = regionPx(layer.region ?? { x: 0.2, y: 0.2, width: 0.6, height: 0.6 }, ctx.canvas);
+  const fill = layer.color ? toHex(layer.color) : PAPER;
+  const kinds = layer.kind && layer.kind !== 'mixed' ? [layer.kind] : ['rect', 'blob', 'arch', 'square', 'circle', 'pill'];
+  const wob = layer.wobble ?? 0.5;
+
+  /** @type {{ kind: string, x: number, y: number, w: number, h: number, rot: number, color: string }[]} */
+  let items;
+  if (layer.items?.length) {
+    items = layer.items.map((it, i) => ({
+      kind: it.kind ?? kinds[i % kinds.length],
+      x: r.x + (it.x ?? 0.5) * r.width,
+      y: r.y + (it.y ?? 0.5) * r.height,
+      w: len(it.width ?? it.size, ctx.canvas, r.width * 0.4),
+      h: len(it.height ?? it.size, ctx.canvas, r.height * 0.4),
+      rot: it.rotate ?? rng.range(-4, 4),
+      color: it.color ? toHex(it.color) : fill,
+    }));
+  } else {
+    // A loose collage: cells of a small grid, each shape filling most of its cell.
+    const count = layer.count ?? 4;
+    const cols = Math.ceil(Math.sqrt(count));
+    const rows = Math.ceil(count / cols);
+    const cw = r.width / cols;
+    const ch = r.height / rows;
+    items = [];
+    for (let i = 0; i < count; i++) {
+      const kind = kinds[rng.int(0, kinds.length - 1)];
+      const sq = kind === 'square' || kind === 'circle';
+      const fw = cw * rng.range(0.72, 1.02);
+      const fh = sq ? Math.min(fw, ch * 1.02) : ch * rng.range(0.72, 1.02);
+      items.push({
+        kind,
+        x: r.x + cw * ((i % cols) + 0.5) + rng.range(-0.08, 0.08) * cw,
+        y: r.y + ch * (Math.floor(i / cols) + 0.5) + rng.range(-0.08, 0.08) * ch,
+        w: sq ? Math.min(fw, fh) : fw,
+        h: sq ? Math.min(fw, fh) : fh,
+        rot: rng.range(-5, 5),
+        color: fill,
+      });
+    }
+  }
+  const body = items.map((it) => {
+    const size = Math.min(it.w, it.h);
+    const d = scissor(outlineOf(it.kind, it.w, it.h, rng), Math.max(4, size * 0.09), wob * size * 0.018, rng);
+    return `<path${attrs({ d, fill: it.color, transform: `translate(${num(it.x)} ${num(it.y)}) rotate(${num(it.rot)})` })}/>`;
+  }).join('');
+  const a = attrs(layerAttrs(layer));
+  return { defs: '', body: a ? `<g${a}>${body}</g>` : body };
+}
+
+/**
+ * Stroke a polyline by hand: wobbled by smooth noise, drawn in short
+ * overlapping runs whose widths drift, with round caps.
+ *
+ * @param {[number, number][]} pts - Points in px.
+ * @param {object} o
+ * @param {number} o.width - Base stroke width.
+ * @param {number} o.amp - Wobble amplitude in px.
+ * @param {number} o.period - Wobble period in px.
+ * @param {string} o.color
+ * @param {import('./rng.js').Rng} o.rng
+ * @returns {string} Markup.
+ */
+function handLine(pts, { width, amp, period, color, rng }) {
+  const nx = noise1(rng);
+  const ny = noise1(rng);
+  const nw = noise1(rng);
+  const off = rng.range(0, 64);
+  let s = 0;
+  const moved = pts.map((p, i) => {
+    if (i) s += Math.hypot(p[0] - pts[i - 1][0], p[1] - pts[i - 1][1]);
+    return /** @type {[number, number, number]} */ ([p[0] + nx(off + s / period) * amp, p[1] + ny(off + s / period) * amp, s]);
+  });
+  let out = '';
+  const run = Math.max(3, Math.round(moved.length / Math.max(3, s / (period * 0.8))));
+  for (let i = 0; i < moved.length - 1; i += run) {
+    const chunk = moved.slice(i, Math.min(moved.length, i + run + 1));
+    const wdt = width * (0.82 + 0.3 * nw(off + chunk[0][2] / (period * 1.5)));
+    out += `<path${attrs({ d: `M${chunk.map(([x, y]) => `${num(x)} ${num(y)}`).join('L')}`, 'stroke-width': num(wdt) })}/>`;
+  }
+  return `<g${attrs({ fill: 'none', stroke: color, 'stroke-linecap': 'round', 'stroke-linejoin': 'round' })}>${out}</g>`;
+}
+
+/**
+ * The `scribble` layer.
+ *
+ * @param {import('./index.js').ScribbleLayer} layer
+ * @param {import('./layers.js').RenderContext} ctx
+ * @returns {import('./layers.js').Markup}
+ */
+export function scribble(layer, ctx) {
+  const { rng, width: w, height: h } = ctx;
+  const size = len(layer.size, ctx.canvas, '46vmin');
+  const cx = (layer.position?.x ?? 0.5) * w;
+  const cy = (layer.position?.y ?? 0.5) * h;
+  const color = layer.color ? toHex(layer.color) : PAPER;
+  const stroke = len(layer.stroke, ctx.canvas, '1.3vmin');
+  const wob = layer.wobble ?? 0.5;
+  let body = '';
+
+  if (layer.graph) {
+    const g = layer.graph === true ? {} : layer.graph;
+    const n = Math.max(2, Math.min(9, g.nodes ?? rng.int(4, 6)));
+    // Nodes on a jittered lattice so the graph spans the box without clumping.
+    const pts = Array.from({ length: n }, (_, i) => {
+      const a = (i / n) * Math.PI * 2 + rng.range(-0.5, 0.5);
+      const rr = size * 0.5 * rng.range(0.35, 1);
+      return /** @type {[number, number]} */ ([cx + Math.cos(a) * rr, cy + Math.sin(a) * rr]);
+    });
+    pts.sort((p, q) => p[0] - q[0]);
+    const path = [pts[0]];
+    for (let i = 1; i < n; i++) path.push(pts[i]);
+    const lines = [densify(path, size * 0.03)];
+    if (n > 3) lines.push(densify([pts[1], pts[n - 1]], size * 0.03));
+    for (const l of lines) body += handLine(l, { width: stroke, amp: wob * size * 0.006, period: size * 0.12, color, rng });
+    const r = stroke * (g.dot ?? 1.25);
+    body += pts.map(([x, y]) => `<circle${attrs({ cx: x, cy: y, r: r * rng.range(0.9, 1.15), fill: color })}/>`).join('');
+  } else {
+    const icon = layer.icon;
+    const data = typeof icon === 'string' && icon.trim().startsWith('<') ? parseSvgIcon(icon) : typeof icon === 'string' && icon ? resolveIcon(icon) : null;
+    const src = data ?? { body: `<path d="${SPARK_PATH}"/>`, viewBox: [0, 0, 24, 24] };
+    const [vx, vy, vw, vh] = src.viewBox;
+    const k = size / Math.max(vw, vh);
+    const flat = flattenBody(src.body, Math.max(vw, vh) / 90);
+    for (const line of flat.lines) {
+      const pts = line.map(([x, y]) => /** @type {[number, number]} */ ([cx + (x - vx - vw / 2) * k, cy + (y - vy - vh / 2) * k]));
+      body += handLine(pts, { width: stroke, amp: wob * size * 0.01, period: size * 0.16, color, rng });
+    }
+  }
+  const a = attrs(layerAttrs(layer));
+  return { defs: '', body: a ? `<g${a}>${body}</g>` : body };
+}
+
+/** The spark, as an outline to trace when no icon is given. */
+const SPARK_PATH = 'M12 2c.4 4.9 2.1 7.6 7 8.6l3 .4-3 .4c-4.9 1-6.6 3.7-7 8.6-.4-4.9-2.1-7.6-7-8.6L2 11l3-.4c4.9-1 6.6-3.7 7-8.6Z';

package/src/icons.js

@@ -0,0 +1,157 @@
+/**
+ * Icons: Iconify sets by name, or raw SVG.
+ *
+ * `'lucide:feather'` and `'simple-icons:github'` resolve through the
+ * `@iconify-json/<prefix>` package when it's installed (optional peer
+ * dependencies; any Iconify JSON set works the same way). A set can also be
+ * handed over directly with {@link registerIcons}, which is how to use
+ * icons without installing the packages, or in a bundler that can't
+ * resolve them.
+ *
+ * Raw input works too: an SVG string (its `viewBox` is read) or a bare
+ * path `d` with a `viewBox`.
+ *
+ * @module icons
+ */
+
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+
+/** @type {Map<string, IconSet>} */
+const sets = new Map();
+
+/**
+ * An Iconify JSON icon set (the shape of `@iconify-json/<prefix>/icons.json`).
+ *
+ * @typedef {object} IconSet
+ * @property {string} prefix
+ * @property {Record<string, { body: string, width?: number, height?: number, left?: number, top?: number }>} icons
+ * @property {Record<string, { parent: string, width?: number, height?: number }>} [aliases]
+ * @property {number} [width]
+ * @property {number} [height]
+ * @property {number} [left]
+ * @property {number} [top]
+ */
+
+/**
+ * A resolved icon.
+ *
+ * @typedef {object} IconData
+ * @property {string} body - Inner SVG markup.
+ * @property {[number, number, number, number]} viewBox - `[minX, minY, width, height]`.
+ */
+
+/**
+ * Register an Iconify icon set (for example the parsed
+ * `@iconify-json/lucide/icons.json`). Replaces any set with that prefix.
+ *
+ * @param {IconSet} set - The set.
+ * @returns {void}
+ *
+ * @example
+ * import lucide from '@iconify-json/lucide/icons.json' with { type: 'json' };
+ * registerIcons(lucide);
+ */
+export function registerIcons(set) {
+  if (!set?.prefix || typeof set.icons !== 'object') throw new TypeError('registerIcons() expects an Iconify JSON set ({ prefix, icons })');
+  sets.set(set.prefix, set);
+}
+
+/**
+ * Load a set by prefix: a registered one, else `@iconify-json/<prefix>`.
+ *
+ * @param {string} prefix - e.g. `'lucide'`.
+ * @returns {IconSet} The set.
+ * @throws {Error} When the set isn't registered or installed.
+ */
+function loadSet(prefix) {
+  let set = sets.get(prefix);
+  if (set) return set;
+  const pkg = `@iconify-json/${prefix}`;
+  let file;
+  try {
+    file = join(require.resolve(`${pkg}/package.json`, { paths: [process.cwd(), fileURLToPath(new URL('.', import.meta.url))] }), '..', 'icons.json');
+  } catch {
+    throw new Error(`Icon set "${prefix}" is not available. Install ${pkg}, or pass the set to registerIcons().`);
+  }
+  set = /** @type {IconSet} */ (JSON.parse(readFileSync(file, 'utf8')));
+  sets.set(prefix, set);
+  return set;
+}
+
+/**
+ * Resolve an Iconify name (`'prefix:name'`) to its markup and viewBox.
+ *
+ * @param {string} name - e.g. `'lucide:feather'`.
+ * @returns {IconData} The icon.
+ * @throws {Error} On a malformed name, a missing set or a missing icon.
+ *
+ * @example
+ * resolveIcon('lucide:feather').viewBox; // [0, 0, 24, 24]
+ */
+export function resolveIcon(name) {
+  const m = String(name).match(/^([a-z0-9-]+):([a-z0-9-]+)$/i);
+  if (!m) throw new Error(`Icon names look like "lucide:feather", got "${name}"`);
+  const set = loadSet(m[1]);
+  let key = m[2];
+  /** @type {{ width?: number, height?: number }} */
+  let size = {};
+  for (let hops = 0; !set.icons[key] && set.aliases?.[key] && hops < 8; hops++) {
+    const alias = set.aliases[key];
+    size = { width: size.width ?? alias.width, height: size.height ?? alias.height };
+    key = alias.parent;
+  }
+  const icon = set.icons[key];
+  if (!icon) throw new Error(`Icon "${name}" was not found in the ${m[1]} set`);
+  return {
+    body: icon.body,
+    viewBox: [
+      icon.left ?? set.left ?? 0,
+      icon.top ?? set.top ?? 0,
+      size.width ?? icon.width ?? set.width ?? 16,
+      size.height ?? icon.height ?? set.height ?? 16,
+    ],
+  };
+}
+
+/**
+ * Read a raw SVG string: its inner markup and viewBox. Scripts,
+ * `foreignObject` and event-handler attributes are dropped.
+ *
+ * @param {string} svg - An `<svg …>…</svg>` string.
+ * @returns {IconData} The icon.
+ * @throws {Error} When there's no `<svg>` element or no size.
+ */
+export function parseSvgIcon(svg) {
+  const open = svg.match(/<svg\b[^>]*>/i);
+  if (!open) throw new Error('Icon SVG must contain an <svg> element');
+  const tag = open[0];
+  const vb = tag.match(/viewBox\s*=\s*["']([^"']+)["']/i);
+  let viewBox;
+  if (vb) {
+    viewBox = vb[1].trim().split(/[\s,]+/).map(Number);
+  } else {
+    const w = parseFloat(tag.match(/\bwidth\s*=\s*["']([\d.]+)/i)?.[1] ?? '');
+    const h = parseFloat(tag.match(/\bheight\s*=\s*["']([\d.]+)/i)?.[1] ?? '');
+    if (!(w > 0 && h > 0)) throw new Error('Icon SVG needs a viewBox or width/height');
+    viewBox = [0, 0, w, h];
+  }
+  if (viewBox.length !== 4 || viewBox.some((n) => !Number.isFinite(n))) throw new Error('Icon SVG has an unreadable viewBox');
+
+  // Presentation attributes on the root (fill="none", stroke=…) apply to the body.
+  const inherited = [...tag.matchAll(/\b(fill|stroke|stroke-width|stroke-linecap|stroke-linejoin)\s*=\s*("[^"]*"|'[^']*')/gi)]
+    .map((m) => `${m[1]}=${m[2]}`)
+    .join(' ');
+  const start = svg.indexOf(tag) + tag.length;
+  const end = svg.lastIndexOf('</svg>');
+  let body = svg.slice(start, end > start ? end : undefined);
+  body = body
+    .replace(/<script\b[\s\S]*?<\/script>/gi, '')
+    .replace(/<foreignObject\b[\s\S]*?<\/foreignObject>/gi, '')
+    .replace(/\son[a-z]+\s*=\s*("[^"]*"|'[^']*')/gi, '');
+  return { body: inherited ? `<g ${inherited}>${body}</g>` : body, viewBox: /** @type {any} */ (viewBox) };
+}