wand-kit 0.3.3 → 0.5.0

package/lib/social.js

@@ -0,0 +1,366 @@
+/**
+ * lib/social.js — the social set, drawn from a brand's approved composition.
+ *
+ * A brand that carries one (`tokens.art.composition`: on the interim brand, the
+ * approved X header, LinkedIn banners and avatar measured into one artwork)
+ * draws its social images from it, not from a page: every format is a window
+ * onto the same art at one scale, so a banner, a share image and a profile
+ * photo are the approved design at that size, not an imitation of it. The
+ * brand's `lib/composition.mjs` writes each page; this renders them, reads each
+ * card's gate, and writes the PNGs, the share and icon tags, INSTALL.md (where
+ * each file goes and how to check it once it is live), a preview of each image
+ * where it will be seen, and a zip of the hand-over.
+ *
+ *   node wand.js social <social.json> [--brand interim]
+ *
+ * social.json:
+ *   { "name": "wand-social",
+ *     "site": "Wand",                                                               og:site_name, and the icons' app name
+ *     "line": { "lead": "A new workforce.", "phrase": "A new operating era." },   the words, unless a card names its own
+ *     "upload": "https://wand.ai/assets/og/20261023/",                              where the share images will live
+ *     "cards": [ { "kind": "linkedin-banner" }, { "kind": "x-header" }, { "kind": "linkedin-company" },
+ *                { "kind": "share", "id": "wand-ai-share", "url": "https://wand.ai/", "title": "Wand AI", "description": "...", "alt": "...",
+ *                  "before": "https://wand.ai/assets/og/wand-share.png" },                  the image live now, shown above the new one
+ *                { "kind": "share", "id": "article-share", "url": "...", "lead": "An Open Agentic Web", "phrase": "Needs Open Discovery", ... },
+ *                { "kind": "square" }, { "kind": "avatar" },
+ *                { "kind": "icons", "upload": "/assets/20261022/" },                       favicons, app icons, the manifest
+ *                { "kind": "profile-photo", "photo": "me-cutout.png" } ] }   a cut-out (transparent ground) over the banner's art
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+import { loadBrand } from "./brand.js";
+import { browser } from "./engine.js";
+
+const require = createRequire(import.meta.url);
+const LIMIT = 300 * 1024;           // WhatsApp drops a larger link preview
+export const KINDS = ["linkedin-banner", "x-header", "linkedin-company", "share", "square", "avatar", "profile-photo", "icons"];
+
+// the icon set from the brand's avatar: favicons are the disc on transparent; the apple-touch-icon and the manifest
+// icons are the disc's colour full bleed, because iOS and Android cut their own shape (runs/2026-10-22-wand-og)
+const ICONS = [["favicon-16", 16, "disc"], ["favicon-32", 32, "disc"], ["favicon-48", 48, "disc"],
+               ["apple-touch-icon", 180, "square"], ["icon-192", 192, "square"], ["icon-512", 512, "square"]];
+
+/**
+ * Draw a social set. `spec` is the path of a social.json, or the spec itself with `dir` naming where relative paths
+ * resolve and the output goes. `zip: false` and `quiet: true` are for callers that only want the files (library --check).
+ */
+export async function social(spec, { brand: brandOverride = null, dir = null, zip = true, quiet = false } = {}) {
+  const t0 = Date.now();
+  if (typeof spec === "string") { const file = path.resolve(spec); dir = path.dirname(file); spec = JSON.parse(fs.readFileSync(file, "utf8")); }
+  dir = path.resolve(dir || process.cwd());
+  const brandName = brandOverride || spec.brand || "interim";
+  const brand = loadBrand(brandName);
+  if (!brand.tokens.art.composition) throw new Error(`the ${brandName} brand has no approved social composition (the interim brand has one); for social cards on it, use --surface og or square`);
+  const { composition } = await import(pathToFileURL(path.join(brand.dir, "lib", "composition.mjs")).href);
+  const C = composition(brand.dir), F = C.comp.formats;
+  const out = path.join(dir, brandOverride && brandOverride !== (spec.brand || "interim") ? `out-${brandOverride}` : "out");
+  const work = path.join(out, "work");
+  fs.rmSync(out, { recursive: true, force: true }); fs.mkdirSync(work, { recursive: true });
+  const name = spec.name || path.basename(dir);
+  const line = spec.line || {};
+  const mode = spec.mode || "dark";
+  const log = quiet ? () => {} : console.log;
+
+  const pages = [], rows = [];
+  for (const [i, card] of (spec.cards || []).entries()) {
+    if (!KINDS.includes(card.kind)) throw new Error(`card ${i + 1}: unknown kind "${card.kind}" (one of ${KINDS.join(", ")})`);
+    const id = card.id || card.kind;
+    if (card.kind === "icons") { pages.push({ card, id, icons: true }); continue; }
+    const f = F[card.kind === "profile-photo" ? "avatar" : card.kind];
+    const text = { lead: card.lead || line.lead, phrase: card.phrase || line.phrase };
+    let html;
+    if (card.kind === "avatar") {
+      html = avatarPage(fs.readFileSync(path.join(brand.dir, "assets", brand.tokens.art.avatar), "utf8"), f);
+    } else if (card.kind === "profile-photo") {
+      // the banner's art behind the profile photo's circle, continued below the banner's edge, the cut-out over it
+      const b = F["linkedin-banner"], p = b.profile, r = (p.d * b.w) / 2 / b.s;
+      const cx = (p.cx * b.w) / b.s + b.x0, cy = (p.cy * b.h) / b.s + b.y0;
+      if (card.photo && !fs.existsSync(path.resolve(dir, card.photo))) throw new Error(`card ${i + 1}: photo ${card.photo} not found`);
+      html = C.page({ id, w: f.w, h: f.h, s: f.w / (2 * r), x0: cx - r, y0: cy - r, mode, lockup: false, photo: card.photo ? path.resolve(dir, card.photo) : null });
+    } else if (card.kind === "share") {
+      html = C.page({ id, w: f.w, h: f.h, mode, ...C.window(f, f.window), set: { ...f.set, ...(card.set || {}) }, text, rules: f.rules });
+    } else if (card.kind === "square") {
+      // the art's right half on its diagonal, the lockup in the corner it leaves, every part at one scale
+      const [bx0, by0, bx1, by1] = C.comp.ring.box, x0 = (bx0 + bx1) / 2 - f.ringCentre[0] / f.s, y0 = (by0 + by1) / 2 - f.ringCentre[1] / f.s;
+      const wm = C.comp.lockup.wordmark, P = C.paths(mode), sparkTop = wm.top + ((P.sparkTop - P.lettersTop) * wm.height) / P.lettersH;
+      html = C.page({ id, w: f.w, h: f.h, s: f.s, x0, y0, mode, text, rules: f.rules,
+        lockup: { dx: x0 + f.lockupAt[0] / f.s - C.comp.lockup.lead.inkLeft, dy: y0 + f.lockupAt[1] / f.s - sparkTop } });
+    } else {
+      html = C.page({ id, w: f.w, h: f.h, s: f.s, x0: f.x0, y0: f.y0, mode, text, lockup: f.lockup || {}, ring: f.ring || {}, rules: f.rules });
+    }
+    const htmlPath = path.join(work, `${id}.html`);
+    fs.writeFileSync(htmlPath, html);
+    pages.push({ card, id, f, htmlPath, png: path.join(out, `${id}-${f.w}x${f.h}.png`) });
+  }
+
+  const b = await browser();
+  for (const p of pages) {
+    if (p.icons) { rows.push(await icons(b, p, { brand, out, site: spec.site })); continue; }
+    const page = await b.newPage({ viewport: { width: p.f.w, height: p.f.h }, deviceScaleFactor: p.f.scale || 1 });
+    const errors = []; page.on("pageerror", (e) => errors.push(String(e)));
+    await page.goto(pathToFileURL(p.htmlPath).href, { waitUntil: "load" });
+    await page.waitForSelector("#gate", { state: "attached", timeout: 30000 });
+    p.gate = JSON.parse(await page.$eval("#gate", (e) => e.textContent));
+    await page.screenshot({ path: p.png, clip: { x: 0, y: 0, width: p.f.w, height: p.f.h } });
+    // a share image over WhatsApp's limit goes as a JPEG at high quality instead: the same picture, a quarter the bytes
+    if (p.card.kind === "share" && fs.statSync(p.png).size > LIMIT) {
+      const jpg = p.png.replace(/\.png$/, ".jpg");
+      await page.screenshot({ path: jpg, type: "jpeg", quality: 92, clip: { x: 0, y: 0, width: p.f.w, height: p.f.h } });
+      fs.rmSync(p.png); p.png = jpg;
+    }
+    await page.close();
+    p.files = [p.png];
+    const kb = Math.round(fs.statSync(p.png).size / 1024), over = p.card.kind === "share" && kb * 1024 > LIMIT;
+    const size = `${p.f.w * (p.f.scale || 1)} x ${p.f.h * (p.f.scale || 1)}, ${kb} KB`;
+    rows.push({ ok: p.gate.ok && !errors.length && !over, gate: p.id, msg: p.gate.ok ? `${size}${p.gate.lockup ? `, type ${p.gate.typePx}px` : ""}${errors.length ? `; console: ${errors[0]}` : ""}${over ? "; over 300 KB" : ""}` : p.gate.reasons.join("; ") });
+  }
+
+  // the tags, one block a page for the share images, absolute https URLs, one twitter:card; then the icons' block
+  const shares = pages.filter((p) => p.card.kind === "share"), iconSet = pages.find((p) => p.icons);
+  if (shares.length || iconSet) {
+    const missing = shares.filter((p) => !p.card.url || !p.card.title);
+    for (const p of shares) p.tags = shareTags(p, { upload: spec.upload, site: spec.site, line });
+    const blocks = [...shares.map((p) => p.tags), ...(iconSet ? [iconSet.tags] : [])];
+    fs.writeFileSync(path.join(out, "head-tags.html"), blocks.join("\n"));
+    const dash = shares.filter((p) => /—/.test(`${p.card.title} ${p.card.description} ${p.card.alt}`));
+    if (shares.length) rows.push({ ok: !missing.length && !dash.length, warn: !dash.length, gate: "tags", msg: dash.length ? `em dash in the tags of ${dash.map((p) => p.id).join(", ")}` : missing.length ? `${missing.map((p) => p.id).join(", ")}: no url or title, so its tags are placeholders` : `head-tags.html, ${shares.length} page${shares.length === 1 ? "" : "s"}${spec.upload ? "" : " (set `upload` for the image URLs)"}` });
+  }
+
+  // the image each page shares today, if the spec names it: shown above the new one, so the change is visible
+  for (const p of shares.filter((q) => q.card.before)) {
+    try { p.before = await fetchTo(p.card.before, path.join(work, `before-${p.id}`), dir); }
+    catch (e) { rows.push({ ok: false, warn: true, gate: "before", msg: `${p.id}: ${e.message}` }); }
+  }
+
+  // each image where it is seen: a profile, the feeds' crops of a share image, a square, an avatar, the icons
+  const sheet = path.join(out, "preview.png");
+  const ph = previewHtml(pages, F);
+  fs.writeFileSync(path.join(work, "preview.html"), ph.html);
+  const pv = await b.newPage({ viewport: { width: ph.w, height: 400 }, deviceScaleFactor: 1 });
+  await pv.goto(pathToFileURL(path.join(work, "preview.html")).href, { waitUntil: "load" });
+  await pv.evaluate(() => Promise.all([...document.images].map((i) => (i.complete ? null : new Promise((r) => { i.onload = i.onerror = r; })))));
+  await pv.screenshot({ path: sheet, fullPage: true });
+  await pv.close();
+
+  // the hand-over: where each file goes and how to check it once live, then everything in one zip
+  fs.writeFileSync(path.join(out, "INSTALL.md"), install(pages, { upload: spec.upload, brand: brand.name, out }));
+  const files = pages.flatMap((p) => p.files || []);
+  let zipPath = null;
+  if (zip) {
+    const stamp = new Date().toISOString().slice(0, 10).replace(/-/g, "");
+    zipPath = path.join(out, `${name}-${stamp}.zip`);
+    const JSZip = require("jszip"), z = new JSZip();
+    for (const f of [...files, ...["head-tags.html", "INSTALL.md", "preview.png"].map((x) => path.join(out, x)).filter((x) => fs.existsSync(x))]) z.file(path.relative(out, f), fs.readFileSync(f));
+    fs.writeFileSync(zipPath, await z.generateAsync({ type: "nodebuffer", compression: "DEFLATE" }));
+  }
+  rows.push({ ok: true, gate: "renders", msg: `${files.length} file${files.length === 1 ? "" : "s"} in ${path.relative(process.cwd(), out)}/, ${path.relative(process.cwd(), sheet)}, INSTALL.md${zipPath ? `, ${path.basename(zipPath)}` : ""}` });
+
+  const report = { ok: rows.every((r) => r.ok || r.warn), rows, brand: brand.name, name, out, zip: zipPath,
+    images: pages.map((p) => ({ id: p.id, kind: p.card.kind, png: p.png || null, files: p.files || [], tags: p.tags || null, gate: p.gate || null })), ms: Date.now() - t0 };
+  fs.writeFileSync(path.join(work, "report.json"), JSON.stringify(report, null, 1));
+  log("");
+  for (const r of rows) log(`  ${r.ok ? " ok " : r.warn ? " -- " : "FAIL"}  ${r.gate.padEnd(16)} ${r.msg}`);
+  log(`\n  ${pages.length} social cards, ${brand.name} brand, ${((Date.now() - t0) / 1000).toFixed(1)}s`);
+  // what no gate sees: read the preview the way the people scrolling past will
+  log(`\n  review  ${path.relative(process.cwd(), sheet)}, as a creative director:\n          at LinkedIn's compact size (the 128pt card), do the wordmark and the words still read? is there anything too small to?\n          does Slack's square keep the whole lockup? does the phrase end where the trails' dots meet it?\n          is the ring whole and clear of the words? on the profiles, is the lockup clear of the photo's circle?`);
+  log(report.ok ? "" : "\n  FAILED — fix the rows marked FAIL\n");
+  return report;
+}
+
+const text0 = (card, line) => ["Wand.", card.lead || line.lead, card.phrase || line.phrase].filter(Boolean).join(" ");
+const esc = (t) => String(t ?? "").replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
+
+/** One page's share block: og and twitter tags with the image's absolute URL, type, size and alt. */
+function shareTags({ card, png, f }, { upload, site, line }) {
+  const img = (upload || "https://example.com/og/") + path.basename(png), alt = card.alt || text0(card, line);
+  return `<!-- ${card.url || "the page's URL"} -->
+<meta property="og:type" content="${card.type || (card.url && /\/$/.test(card.url) ? "website" : "article")}">
+${site ? `<meta property="og:site_name" content="${esc(site)}">\n` : ""}<meta property="og:title" content="${esc(card.title)}">
+<meta property="og:description" content="${esc(card.description)}">
+<meta property="og:url" content="${esc(card.url)}">
+<meta property="og:image" content="${img}">
+<meta property="og:image:secure_url" content="${img}">
+<meta property="og:image:type" content="image/${png.endsWith(".jpg") ? "jpeg" : "png"}">
+<meta property="og:image:width" content="${f.w}">
+<meta property="og:image:height" content="${f.h}">
+<meta property="og:image:alt" content="${esc(alt)}">
+<meta name="twitter:card" content="summary_large_image">
+<meta name="twitter:title" content="${esc(card.title)}">
+<meta name="twitter:description" content="${esc(card.description)}">
+<meta name="twitter:image" content="${img}">
+<meta name="twitter:image:alt" content="${esc(alt)}">
+`;
+}
+
+/** The avatar: the brand's avatar.svg full bleed, its disc as the square, since every platform cuts its own circle. */
+function avatarPage(svg, f) {
+  const body = svg.replace(/<circle ([^>]*)fill="(#[0-9a-fA-F]{6})"\s*\/>/, (m, a, fill) => `<rect width="100%" height="100%" fill="${fill}"/>`);
+  return `<!doctype html><html><head><meta charset="utf-8"><style>html,body{margin:0}svg{display:block;width:${f.w}px;height:${f.h}px}</style></head><body>${body}
+<script type="application/json" id="gate">{"ok":true,"reasons":[]}</script></body></html>`;
+}
+
+/**
+ * The icon set from the brand's avatar.svg into out/icons/: PNGs at each size, favicon.ico (16, 32 and 48, PNG
+ * inside), favicon.svg, site.webmanifest; and the <link> block every page carries, kept for head-tags.html.
+ */
+async function icons(b, p, { brand, out, site }) {
+  const svg = fs.readFileSync(path.join(brand.dir, "assets", brand.tokens.art.avatar), "utf8");
+  const dir = path.join(out, "icons"); fs.mkdirSync(dir, { recursive: true });
+  const ground = brand.roles.dark.bg, disc = (svg.match(/<circle [^>]*fill="#([0-9a-fA-F]{6})"/) || [])[1];
+  if (!disc) throw new Error("icons: the brand's avatar.svg has no disc (a <circle> with a fill)");
+  const files = {};
+  for (const [name, size, shape] of ICONS) {
+    const body = shape === "disc" ? svg : svg.replace(/<circle [^>]*fill="(#[0-9a-fA-F]{6})"\s*\/>/, '<rect width="100%" height="100%" fill="$1"/>');
+    const page = await b.newPage({ viewport: { width: size, height: size }, deviceScaleFactor: 1 });
+    await page.setContent(`<!doctype html><html><head><style>html,body{margin:0;background:transparent}svg{display:block;width:${size}px;height:${size}px}</style></head><body>${body}</body></html>`);
+    const f = path.join(dir, `${name}.png`);
+    await page.screenshot({ path: f, omitBackground: shape === "disc", clip: { x: 0, y: 0, width: size, height: size } });
+    await page.close();
+    files[name] = f;
+  }
+  const ico = path.join(dir, "favicon.ico");
+  fs.writeFileSync(ico, icoFile([16, 32, 48].map((s) => ({ size: s, png: fs.readFileSync(files[`favicon-${s}`]) }))));
+  const fav = path.join(dir, "favicon.svg");
+  fs.writeFileSync(fav, svg.trim() + "\n");
+  const manifest = path.join(dir, "site.webmanifest");
+  fs.writeFileSync(manifest, JSON.stringify({ name: site || "Wand", short_name: site || "Wand",
+    icons: [192, 512].map((s) => ({ src: `icon-${s}.png`, sizes: `${s}x${s}`, type: "image/png" })),
+    theme_color: `#${ground}`, background_color: `#${ground}`, display: "standalone" }, null, 2) + "\n");
+  const base = p.card.upload || "/";
+  p.tags = `<!-- every page: the icons (the files in icons/, uploaded to ${base}) -->
+<link rel="icon" href="${base}favicon.ico" sizes="32x32">
+<link rel="icon" type="image/svg+xml" href="${base}favicon.svg">
+<link rel="apple-touch-icon" href="${base}apple-touch-icon.png">
+<link rel="manifest" href="${base}site.webmanifest">
+`;
+  p.files = [ico, fav, ...Object.values(files), manifest];
+  p.png = files["icon-512"];
+  const kb = Math.round(p.files.reduce((a, f) => a + fs.statSync(f).size, 0) / 1024);
+  return { ok: true, gate: p.id, msg: `${p.files.length} files in icons/ (favicon.ico 16/32/48, favicon.svg, ${ICONS.map((i) => i[1]).join(", ")} px, site.webmanifest), ${kb} KB` };
+}
+
+/** An .ico holding PNGs, which every browser since IE 11 reads: a 6-byte header, a 16-byte entry each, the files. */
+function icoFile(images) {
+  const head = Buffer.alloc(6 + 16 * images.length);
+  head.writeUInt16LE(0, 0); head.writeUInt16LE(1, 2); head.writeUInt16LE(images.length, 4);
+  let at = head.length;
+  images.forEach(({ size, png }, i) => {
+    const o = 6 + 16 * i;
+    head.writeUInt8(size >= 256 ? 0 : size, o); head.writeUInt8(size >= 256 ? 0 : size, o + 1);
+    head.writeUInt16LE(1, o + 4); head.writeUInt16LE(32, o + 6);
+    head.writeUInt32LE(png.length, o + 8); head.writeUInt32LE(at, o + 12);
+    at += png.length;
+  });
+  return Buffer.concat([head, ...images.map((x) => x.png)]);
+}
+
+/** A file or an https URL, copied to `to` (+ its extension); the path it landed at. */
+export async function fetchTo(src, to, dir = process.cwd()) {
+  if (/^https?:\/\//.test(src)) {
+    let r;
+    try { r = await fetch(src, { signal: AbortSignal.timeout(15000), headers: { "user-agent": "Mozilla/5.0 (wand-kit social preview)" } }); }
+    catch (e) { throw new Error(`could not fetch ${src} from here (${e.cause?.code || e.name}); save it and pass the file instead`); }
+    if (!r.ok) throw new Error(`${src} answered ${r.status}`);
+    const buf = Buffer.from(await r.arrayBuffer()), f = `${to}${ext(buf)}`;
+    fs.writeFileSync(f, buf); return f;
+  }
+  const p = path.resolve(dir, src);
+  if (!fs.existsSync(p)) throw new Error(`${src} not found`);
+  const f = `${to}${path.extname(p) || ext(fs.readFileSync(p))}`;
+  fs.copyFileSync(p, f); return f;
+}
+
+const ext = (buf) => (buf[0] === 0x89 && buf[1] === 0x50 ? ".png" : buf[0] === 0xff && buf[1] === 0xd8 ? ".jpg" : buf.slice(8, 12).toString() === "WEBP" ? ".webp" : buf.slice(0, 3).toString() === "GIF" ? ".gif" : ".img");
+
+/** Where each kind goes, and how to know it worked. One file a hand-over carries, so the person uploading needs nothing else. */
+function install(pages, { upload, brand, out }) {
+  const has = (k) => pages.filter((p) => p.card.kind === k);
+  const name = (p) => (p.files || []).map((f) => `\`${path.relative(out, f)}\``).join(", ");
+  const s = [`# Installing the social set`, ``, `Drawn on the ${brand} brand from its approved composition by wand-kit. \`preview.png\` shows each image where it will be seen. Nothing here is verified until it is live: check each place after uploading.`, ``];
+  const one = (title, list, steps) => { if (list.length) s.push(`## ${title}`, ``, `${list.map(name).join(", ")}`, ``, ...steps, ``); };
+  one("LinkedIn profile banner", has("linkedin-banner"), ["- LinkedIn, your profile: the pencil on the banner, Upload, then Apply. LinkedIn shows it at 1584 x 396; the file is twice that so it stays sharp.", "- On a phone the banner is cut at the sides and the photo sits elsewhere; the lockup is placed for the desktop profile."]);
+  one("X header", has("x-header"), ["- X, Edit profile: the header image. X shows 1500 x 500 and trims a little from the top and bottom on phones."]);
+  one("LinkedIn company page banner", has("linkedin-company"), ["- The company page, as an admin: Edit page, Header, upload. LinkedIn shows it at 1128 x 191."]);
+  one("Profile picture", [...has("avatar"), ...has("profile-photo")], ["- Upload the square; every platform cuts its own circle. The profile photo that continues the banner lines up on LinkedIn's desktop profile."]);
+  one("Square post", has("square"), ["- A 1080 x 1080 post for LinkedIn, X or Instagram."]);
+  if (has("share").length) {
+    const urls = has("share").map((p) => p.card.url).filter(Boolean);
+    s.push(`## Share images (link previews)`, ``, `${has("share").map(name).join(", ")}, and \`head-tags.html\``, ``,
+      `1. Upload the images to ${upload ? `\`${upload}\`` : "a new folder on the site"}. Always a new folder or file name: every platform caches an image by its URL, so a replaced file at the same address keeps showing the old one.`,
+      `2. Paste each page's block from \`head-tags.html\` into that page's \`<head>\`, replacing the \`og:\` and \`twitter:\` tags there now. The og:title does not repeat the image's words.`,
+      `3. LinkedIn: Post Inspector re-reads the page on every inspect.${urls.map((u) => `\n   - https://www.linkedin.com/post-inspector/inspect/${encodeURIComponent(u)}`).join("")}`,
+      `4. WhatsApp and Facebook: the Sharing Debugger, Scrape Again.${urls.map((u) => `\n   - https://developers.facebook.com/tools/debug/?q=${encodeURIComponent(u)}`).join("")}`,
+      `5. Slack: paste each link in a message to yourself once its cache (about 30 minutes) has passed. X fetches a link it has not seen.`,
+      ``, `A post made before the change may keep its old preview; a new share takes the new image. Which card a platform shows (large, or LinkedIn's compact one in a post with text) is its choice: the images are built to read in both.`, ``);
+  }
+  const ic = has("icons");
+  if (ic.length) s.push(`## Site icons`, ``, `Everything in \`icons/\`, and the icon block in \`head-tags.html\``, ``,
+    `1. Upload the files in \`icons/\` to \`${ic[0].card.upload || "/"}\`.`, `2. Paste the icon block from \`head-tags.html\` into every page's \`<head>\`, replacing the icon and manifest links there now.`,
+    `3. Browsers keep a favicon for a long time: check in a private window, and add the site to a phone's home screen to see the app icon.`, ``);
+  return s.join("\n");
+}
+
+const FEEDS_CSS = `.row{display:flex;gap:20px;margin-bottom:16px;align-items:flex-start}
+.li{display:flex;gap:16px;background:#fff;color:#191919;border:1px solid #e0dfdc;border-radius:10px;padding:14px;width:470px}
+.li img{width:128px;height:72px;object-fit:cover;border-radius:8px}.li span{display:block;color:#666;margin-top:6px}
+.slack{display:flex;gap:14px;background:#1a1d21;border:1px solid #35373b;border-radius:8px;padding:14px;width:470px}
+.slack p{color:#d1d2d3;margin:6px 0 0;font-size:13px}.slack img{width:80px;height:80px;object-fit:cover;border-radius:6px;flex:none}
+.x img{width:470px;height:235px;object-fit:cover;border-radius:16px;display:block}
+.wa{display:flex;gap:12px;align-items:center;background:#d9fdd3;color:#111;border-radius:10px;padding:10px;width:470px}.wa img{width:72px;height:72px;object-fit:cover;border-radius:6px}
+.whole{position:relative;width:600px}.whole img{display:block;width:600px}.whole i{position:absolute;top:0;bottom:0;border:2px dashed #ffd400;box-sizing:border-box}`;
+const PAGE_CSS = `body{margin:0;padding:24px 40px 40px;background:#3c3c3c;font:15px/1.4 -apple-system,Helvetica,Arial,sans-serif;color:#eee;width:1000px}
+h2{font-size:14px;font-weight:600;margin:26px 0 10px;color:#ddd}h3{font-size:13px;font-weight:500;margin:12px 0 8px;color:#bbb}`;
+
+/** A share image as the feeds show it: LinkedIn's compact card, Slack's square, X's 2:1, WhatsApp's thumbnail. */
+export function feedRows(src, { title, url, description }) {
+  const host = (url || "").replace(/^https?:\/\//, "").split("/")[0] || "site";
+  return `<div class="row"><div class="li"><img src="${src}"><div><b>${esc(title)}</b><span>${esc(host)}</span></div></div>
+<div class="slack"><div><b>${esc(title)}</b><p>${esc(description || "")}</p></div><img src="${src}"></div></div>
+<div class="row"><div class="x"><img src="${src}"></div><div class="wa"><img src="${src}"><b>${esc(title)}</b></div></div>`;
+}
+
+/** The image whole, its centre square outlined: what Slack's and WhatsApp's cut keeps. */
+export function wholeWithSquare(src, w, h) {
+  const k = 600 / w, side = Math.min(w, h) * k;
+  return `<div class="whole"><img src="${src}"><i style="left:${(600 - side) / 2}px;width:${side}px"></i></div>`;
+}
+
+export const previewPage = (body, w = 1080) => ({ w, html: `<!doctype html><html><head><meta charset="utf-8"><style>${PAGE_CSS}\n${FEEDS_CSS}
+.profile{position:relative;background:#fff;border-radius:10px;overflow:hidden}.banner{display:block}
+.avatar{position:absolute;border-radius:50%;box-shadow:0 0 0 5px #fff}
+.tab{display:inline-flex;gap:8px;align-items:center;background:#dee1e6;color:#222;border-radius:8px 8px 0 0;padding:8px 14px;margin-right:12px}
+.home{display:inline-block;text-align:center;color:#ddd;font-size:12px;margin-right:16px}.home img{display:block;border-radius:22%;margin-bottom:6px}
+</style></head><body>${body}</body></html>` });
+
+/** One page showing each image where it lands: a LinkedIn and an X profile, and a share image in the feeds that cut and shrink it. */
+function previewHtml(pages, F) {
+  const u = (p) => pathToFileURL(p).href;
+  const find = (k) => pages.find((p) => p.card.kind === k);
+  const photo = find("profile-photo") || find("avatar");
+  const parts = [];
+  // where each platform puts the profile photo on its banner: LinkedIn's measured on a desktop profile, X's from its layout
+  const AT = { "linkedin-banner": F["linkedin-banner"].profile, "x-header": { cx: 0.1, cy: 1, d: 0.15 } };
+  const profile = (p, label, w) => {
+    const f = F[p.card.kind], h = (w * f.h) / f.w, pr = AT[p.card.kind];
+    const d = pr.d * w, cx = pr.cx * w, cy = pr.cy * h;
+    return `<h2>${label}</h2><div class="profile" style="width:${w}px;height:${h + d * 0.62}px"><img class="banner" src="${u(p.png)}" style="width:${w}px;height:${h}px">${photo ? `<img class="avatar" src="${u(photo.png)}" style="width:${d}px;height:${d}px;left:${cx - d / 2}px;top:${cy - d / 2}px">` : ""}</div>`;
+  };
+  for (const k of ["linkedin-banner", "x-header"]) { const p = find(k); if (p) parts.push(profile(p, k === "x-header" ? "X profile" : "LinkedIn profile, desktop", 1000)); }
+  const co = find("linkedin-company"); if (co) parts.push(`<h2>LinkedIn company page</h2><img class="banner" src="${u(co.png)}" style="width:1000px">`);
+  for (const p of pages.filter((q) => q.card.kind === "share")) {
+    const meta = { title: p.card.title || p.id, url: p.card.url, description: p.card.description };
+    parts.push(`<h2>Share image: ${p.id}</h2>`);
+    if (p.before) parts.push(`<h3>Live now</h3>${feedRows(u(p.before), meta)}<h3>New</h3>`);
+    parts.push(feedRows(u(p.png), meta), wholeWithSquare(u(p.png), p.f.w, p.f.h));
+  }
+  const sq = find("square"); if (sq) parts.push(`<h2>Square</h2><img src="${u(sq.png)}" style="width:420px;border-radius:12px">`);
+  const ic = pages.find((p) => p.icons);
+  if (ic) {
+    const f = (n) => u(path.join(path.dirname(ic.png), n));
+    parts.push(`<h2>Icons</h2><div><span class="tab"><img src="${f("favicon-16.png")}" width="16" height="16">Wand</span><span class="tab"><img src="${f("favicon-32.png")}" width="32" height="32">32 px</span></div>
+<div style="margin-top:16px"><span class="home"><img src="${f("apple-touch-icon.png")}" width="60" height="60">iPhone</span><span class="home"><img src="${f("icon-192.png")}" width="64" height="64" style="border-radius:50%">Android</span></div>`);
+  }
+  return previewPage(parts.join("\n"));
+}