wand-kit 0.3.3 → 0.5.0

package/brands/interim/lib/ttf.py

@@ -0,0 +1,169 @@
+"""
+ttf.py — the ~1% of TrueType that embed_fonts.py needs, with no fontTools.
+
+Reads `head` and `OS/2` for the fields an EOT header carries, and rewrites the
+`name` table so a face reports the family we address it by. Weight in this
+system is carried by the family name — `Geist SemiBold` regular, not `Geist`
+bold — so retagging is not cosmetic: without it PowerPoint resolves four of the
+five families to the same face.
+
+Everything else in the font is copied through untouched.
+"""
+
+import struct
+
+_HEAD_CHECKSUM_ADJ = 8      # offset of checkSumAdjustment within `head`
+_MAGIC = 0xB1B0AFBA
+
+
+class TTFError(ValueError):
+    pass
+
+
+class TTF:
+    def __init__(self, data):
+        if len(data) < 12:
+            raise TTFError("not a font: too short")
+        tag = data[:4]
+        if tag not in (b"\x00\x01\x00\x00", b"true", b"ttcf", b"OTTO"):
+            raise TTFError(f"unrecognised sfnt tag {tag!r}")
+        if tag == b"ttcf":
+            raise TTFError("font collections (.ttc) are not supported — pass a single face")
+        self.data = data
+        self.sfnt = tag
+        (num,) = struct.unpack(">H", data[4:6])
+        self.tables = {}
+        for i in range(num):
+            off = 12 + i * 16
+            t, csum, o, ln = struct.unpack(">4sIII", data[off:off + 16])
+            self.tables[t] = (o, ln, csum)
+
+    # -- reading -----------------------------------------------------------
+
+    def table(self, tag):
+        if isinstance(tag, str):
+            tag = tag.encode()
+        if tag not in self.tables:
+            raise TTFError(f"font has no {tag.decode()} table")
+        o, ln, _ = self.tables[tag]
+        return self.data[o:o + ln]
+
+    @property
+    def check_sum_adjustment(self):
+        return struct.unpack(">I", self.table("head")[8:12])[0]
+
+    @property
+    def os2(self):
+        """The OS/2 fields the EOT header needs."""
+        t = self.table("OS/2")
+        version = struct.unpack(">H", t[0:2])[0]
+        d = {
+            "version": version,
+            "usWeightClass": struct.unpack(">H", t[4:6])[0],
+            "panose": t[32:42],
+            "ulUnicodeRange": struct.unpack(">IIII", t[42:58]),
+            "fsSelection": struct.unpack(">H", t[62:64])[0],
+            # the font's own embedding permission; the EOT header must not claim more
+            "fsType": struct.unpack(">H", t[8:10])[0],
+        }
+        # code page ranges only exist from version 1
+        d["ulCodePageRange"] = struct.unpack(">II", t[78:86]) if version >= 1 and len(t) >= 86 else (0, 0)
+        return d
+
+    def names(self):
+        """{nameID: string} for the Windows/Unicode records, best effort."""
+        t = self.table("name")
+        count, storage = struct.unpack(">HH", t[2:6])
+        out = {}
+        for i in range(count):
+            p = 6 + i * 12
+            plat, enc, lang, nid, ln, off = struct.unpack(">HHHHHH", t[p:p + 12])
+            raw = t[storage + off: storage + off + ln]
+            try:
+                s = raw.decode("utf-16-be") if plat == 3 or (plat == 0) else raw.decode("latin-1")
+            except UnicodeDecodeError:
+                continue
+            out.setdefault(nid, s)
+        return out
+
+    # -- writing -----------------------------------------------------------
+
+    def retagged(self, family, subfamily, full, postscript):
+        """Return new font bytes with name IDs 1/2/4/6 replaced."""
+        replace = {1: family, 2: subfamily, 4: full, 6: postscript}
+        name = _rebuild_name(self.table("name"), replace)
+        return _reassemble(self, {b"name": name})
+
+
+def _rebuild_name(t, replace):
+    count, storage = struct.unpack(">HH", t[2:6])
+    records, strings, cursor = [], bytearray(), 0
+
+    for i in range(count):
+        p = 6 + i * 12
+        plat, enc, lang, nid, ln, off = struct.unpack(">HHHHHH", t[p:p + 12])
+        if nid in replace:
+            s = replace[nid]
+            raw = s.encode("utf-16-be") if plat in (0, 3) else s.encode("latin-1", "replace")
+        else:
+            raw = t[storage + off: storage + off + ln]
+        records.append((plat, enc, lang, nid, len(raw), cursor))
+        strings += raw
+        cursor += len(raw)
+
+    # sort order is required by the spec: platform, encoding, language, name
+    records.sort(key=lambda r: (r[0], r[1], r[2], r[3]))
+    head = struct.pack(">HHH", 0, len(records), 6 + len(records) * 12)
+    body = b"".join(struct.pack(">HHHHHH", *r) for r in records)
+    return head + body + bytes(strings)
+
+
+def _checksum(b):
+    if len(b) % 4:
+        b = b + b"\0" * (4 - len(b) % 4)
+    return sum(struct.unpack(f">{len(b)//4}I", b)) & 0xFFFFFFFF
+
+
+def _reassemble(font, overrides):
+    """Rewrite the whole sfnt with some tables replaced, fixing every offset,
+    every table checksum and the head checkSumAdjustment."""
+    tags = sorted(font.tables)
+    parts = {}
+    for t in tags:
+        parts[t] = overrides.get(t, font.table(t))
+
+    # head's checkSumAdjustment must be zero while the file checksum is taken
+    head = bytearray(parts[b"head"])
+    head[_HEAD_CHECKSUM_ADJ:_HEAD_CHECKSUM_ADJ + 4] = b"\0\0\0\0"
+    parts[b"head"] = bytes(head)
+
+    n = len(tags)
+    # binary-search fields the spec wants present; readers ignore them but
+    # validators complain when they are wrong
+    entry_selector = max(n.bit_length() - 1, 0)
+    search_range = (1 << entry_selector) * 16
+    out = bytearray(struct.pack(">4sHHHH", font.sfnt, n, search_range,
+                                entry_selector, n * 16 - search_range))
+
+    offset = 12 + n * 16
+    directory, body = bytearray(), bytearray()
+    for t in tags:
+        d = parts[t]
+        directory += struct.pack(">4sIII", t, _checksum(d), offset, len(d))
+        body += d
+        pad = (-len(d)) % 4
+        body += b"\0" * pad
+        offset += len(d) + pad
+
+    out += directory + body
+    adj = (_MAGIC - _checksum(bytes(out))) & 0xFFFFFFFF
+
+    head_off = struct.unpack(">I", out[12 + tags.index(b"head") * 16 + 8:
+                                       12 + tags.index(b"head") * 16 + 12])[0]
+    out[head_off + _HEAD_CHECKSUM_ADJ: head_off + _HEAD_CHECKSUM_ADJ + 4] = struct.pack(">I", adj)
+    return bytes(out)
+
+
+def load(path):
+    with open(path, "rb") as f:
+        return TTF(f.read())

package/brands/interim/lib/wandxml.py

@@ -0,0 +1,37 @@
+"""
+wandxml.py — XML parsing that works with nothing installed.
+
+The kit has to run wherever someone unzips it. `defusedxml` is the better
+parser and we use it when it's there, but requiring a pip install to get past
+Phase 0 means the engine is unusable in exactly the situation it was built for:
+a fresh container with a zip and a .pptx in it.
+
+The stdlib fallback is guarded against the one attack that matters for a parser
+pointed at an untrusted .pptx — entity expansion — by refusing any document with
+a DOCTYPE. Office files never have one.
+"""
+
+try:
+    from defusedxml import minidom as _md
+    HARDENED = True
+except ImportError:                                    # stdlib fallback
+    from xml.dom import minidom as _md
+    HARDENED = False
+
+
+class UnsafeXML(ValueError):
+    pass
+
+
+def parse(data):
+    """Parse .pptx part bytes (or str) into a minidom Document."""
+    probe = data[:8192]
+    if isinstance(probe, bytes):
+        probe = probe.decode("utf-8", "ignore")
+    if not HARDENED and ("<!DOCTYPE" in probe or "<!ENTITY" in probe):
+        raise UnsafeXML(
+            "document declares a DOCTYPE or ENTITY. Office parts never do. "
+            "Refusing to parse it with the stdlib parser — `pip install defusedxml` "
+            "if this file is genuinely trusted."
+        )
+    return _md.parseString(data)

package/brands/interim/tokens.json

@@ -0,0 +1,299 @@
+{
+ "_": "Canonical brand values of the interim wand.ai look, in the shape the studio kit reads (swatch, derived, roles, faces, shape, art). Two sources: the live site (build oval-mobile-20261020-r1, read 2026-10-21: its CSS custom properties, the hero's constants, the marks' colours) and the social design approved on this brand on 2026-10-22 (X header, LinkedIn banners, avatar), which wins where they differ: the dark ground, ink on dark, the display and phrase weights, the spark, the avatar's tile. BRAND.md documents usage; the `from` map says where each value sits.",
+ "name": "interim",
+ "title": "Wand, the interim website's brand (Geist, Newsreader)",
+ "source": {
+  "site": "https://wand.ai/",
+  "build": "oval-mobile-20261020-r1",
+  "read": "2026-10-21",
+  "files": [
+   "site.20261020-r1.css",
+   "scale-story.20261020-r1.css",
+   "wand-refinement-20261020.20261020-r1.css",
+   "chapter-navigation.20261020-r1.css",
+   "assets/wand-icon-dark-v4.svg",
+   "assets/wand-wordmark-light-violet.svg",
+   "scale-story.desktop-wheel-20261020-r4.js"
+  ],
+  "approved": {
+   "date": "2026-10-22",
+   "files": [
+    "X header 1500x500",
+    "LinkedIn banner 1584x396",
+    "LinkedIn company banner 1512x256",
+    "avatar 800",
+    "LinkedIn profile mock-up"
+   ],
+   "kept": "runs/2026-10-22-wand-og/ref",
+   "measured": "assets/social/composition.json",
+   "precedence": "the approved design wins over the site where they differ"
+  }
+ },
+ "swatch": {
+  "night": "0B0913",
+  "ground": "14101C",
+  "nightDeep": "08060D",
+  "nightSoft": "100C19",
+  "plum": "2D1D40",
+  "ink": "221B2D",
+  "paper": "FDFCF9",
+  "stone": "F5F3EF",
+  "lilac": "F2EAFA",
+  "lavender": "D6BFF5",
+  "violet": "C2A1EF",
+  "violetStrong": "6D41B3",
+  "phraseLight": "765098",
+  "eyebrowLight": "836494",
+  "muted": "6E6577",
+  "mutedLight": "B6ABCA",
+  "storyInk": "F4EEF8",
+  "storyText": "C1B5CD",
+  "storyMuted": "B5A6C5",
+  "storyDetail": "9C8DAB",
+  "emphasis": "D4BCE8",
+  "kicker": "C7B7D6",
+  "lineLight": "D8CEDF",
+  "spark": "C2A1EF",
+  "sparkOnLight": "765098",
+  "wordmarkOnLight": "240647",
+  "tile": "261D3D",
+  "white": "FFFFFF",
+  "inkDark": "F7F5F9"
+ },
+ "from": {
+  "night": "--night: the site's html ground, its hero and <meta theme-color>; no longer the brand's dark ground (see ground)",
+  "nightDeep": "--night-deep: the footer",
+  "nightSoft": "the mobile navigation, the product menu, .contact-next",
+  "plum": ".button-dark",
+  "ink": "--ink: body colour on light",
+  "paper": "--paper",
+  "stone": "--stone: the body ground",
+  "lilac": ".nav-cta ground; the editorial cards run #e9e0f1 to #f6f0fa",
+  "lavender": "--lavender",
+  "violet": "--violet: h1 em, h2 em on dark; the current nav item's underline",
+  "violetStrong": "--violet-strong",
+  "phraseLight": ".light-section h1 em, h2 em",
+  "eyebrowLight": ".eyebrow on light (chapter-navigation); 4.5:1 on stone by a hair under AA, so the kit's small muted text takes phraseLight",
+  "muted": "--muted: body text on light",
+  "mutedLight": "--muted-light",
+  "storyInk": ".scale-story --story-ink: the hero's text",
+  "storyText": ".scale-story-caption > p",
+  "storyMuted": ".scale-story --story-muted",
+  "storyDetail": ".scale-story-detail",
+  "emphasis": ".scale-story-title em: the hero's italic phrase",
+  "kicker": ".scale-story-kicker",
+  "lineLight": "the light sections' hairline (#d8cedf)",
+  "spark": "the approved wordmark and avatar: the spark is the phrase's violet (the site's spark was B6A2FF)",
+  "sparkOnLight": "the approved rule carried to the light ground: the spark is the phrase's colour (765098 on light; the site's was 6D4CF5)",
+  "wordmarkOnLight": "the letters in wand-wordmark-dark.svg",
+  "tile": "the approved avatar's disc (the site's favicon tile was 280845)",
+  "ground": "the approved social design (2026-10-22), flat on every export: the dark ground, in place of the site's night",
+  "inkDark": "the approved design's 'A new workforce.': ink on dark, in place of the site's story ink"
+ },
+ "derived": {
+  "hairlineDark": {
+   "hex": "322F39",
+   "from": "white @ 13% on the ground: --dark-line #ffffff21"
+  },
+  "strokeDark": {
+   "hex": "26232E",
+   "from": "white @ 8% on the ground: the card borders #ffffff14"
+  },
+  "surfaceDark": {
+   "hex": "21192E",
+   "from": "the site's dark card ground (#21192e)"
+  },
+  "paperDark": {
+   "hex": "191322",
+   "from": "cards on dark: the ground lifted as the site lifts nightSoft off night (+5, +3, +6)"
+  }
+ },
+ "glow": {
+  "_": "the hero's ambient light: the site's two radial gradients as hex + alpha, and its hairlines; a layout positions them",
+  "a": {
+   "hex": "B183EB",
+   "alpha": 0.09,
+   "from": "radial-gradient(ellipse at 75% 24%, #b183eb17, transparent 60%)"
+  },
+  "b": {
+   "hex": "654393",
+   "alpha": 0.094,
+   "from": "radial-gradient(ellipse at 88% 25%, #65439318, transparent 52%)"
+  },
+  "hairline": {
+   "hex": "FFFFFF",
+   "alpha": 0.13,
+   "from": "--dark-line: #ffffff21"
+  },
+  "kickerDot": {
+   "hex": "D8BBEE",
+   "halo": "CDA4EA",
+   "from": ".scale-story-kicker > span"
+  }
+ },
+ "roles": {
+  "light": {
+   "bg": "F5F3EF",
+   "paper": "FDFCF9",
+   "ink": "221B2D",
+   "text": "6E6577",
+   "soft": "6E6577",
+   "muted": "765098",
+   "accent": "6D41B3",
+   "accentText": "6D41B3",
+   "label": "765098",
+   "emph": "14101C",
+   "emphInk": "F4EEF8",
+   "emphText": "C1B5CD",
+   "emphAccent": "C2A1EF",
+   "stroke": "D8CEDF",
+   "rule": "D8CEDF",
+   "track": "D8CEDF",
+   "surface": "F2EAFA",
+   "emphLabel": "C7B7D6",
+   "second": "765098",
+   "secondSm": "765098",
+   "gradeLow": "14101C",
+   "gradeHigh": "F5F3EF"
+  },
+  "dark": {
+   "bg": "14101C",
+   "paper": "191322",
+   "ink": "F7F5F9",
+   "text": "C1B5CD",
+   "soft": "B5A6C5",
+   "muted": "9C8DAB",
+   "accent": "D4BCE8",
+   "accentText": "C2A1EF",
+   "label": "C7B7D6",
+   "emph": "2D1D40",
+   "emphInk": "F9F4FF",
+   "emphText": "C1B5CD",
+   "emphAccent": "C2A1EF",
+   "stroke": "26232E",
+   "rule": "322F39",
+   "track": "322F39",
+   "surface": "21192E",
+   "emphLabel": "C7B7D6",
+   "second": "C2A1EF",
+   "secondSm": "B5A6C5",
+   "gradeLow": "14101C",
+   "gradeHigh": "F5F3EF"
+  }
+ },
+ "faces": {
+  "display": {
+   "family": "Geist",
+   "weight": 500,
+   "tracking": 0,
+   "leading": 1.025,
+   "_": "approved 2026-10-22: Geist Medium, untracked (stems 17.6 units at 140, as exported). The site's hero title was Geist 450 at -0.063em; its leading, 1.025, stays, since the approved set shows no wrapped title (its lead and phrase sit 1.11 apart, a lockup the composition carries)",
+   "coverTracking": 0
+  },
+  "body": {
+   "family": "Geist",
+   "weight": 400,
+   "tracking": 0,
+   "leading": 1.6
+  },
+  "label": {
+   "family": "Geist",
+   "weight": 500,
+   "tracking": 0.11,
+   "leading": 1.5,
+   "caps": true
+  },
+  "phrase": {
+   "family": "Newsreader",
+   "weight": 500,
+   "italic": false,
+   "tracking": 0,
+   "artItalic": true,
+   "_": "approved 2026-10-22: Newsreader Medium, optical size 72, untracked, the italic on the pages that carry the art (the hero's phrase); roman elsewhere, as the site's h1 em. The site set it at 400, -0.049em"
+  },
+  "files": [
+   {
+    "family": "Geist",
+    "weight": 400,
+    "italic": false,
+    "file": "Geist-Regular.ttf",
+    "pptx": "Geist"
+   },
+   {
+    "family": "Geist",
+    "weight": 450,
+    "italic": false,
+    "file": "Geist-Book.ttf",
+    "pptx": "Geist Book"
+   },
+   {
+    "family": "Geist",
+    "weight": 500,
+    "italic": false,
+    "file": "Geist-Medium.ttf",
+    "pptx": "Geist Medium"
+   },
+   {
+    "family": "Geist",
+    "weight": 600,
+    "italic": false,
+    "file": "Geist-SemiBold.ttf",
+    "pptx": "Geist SemiBold"
+   },
+   {
+    "family": "Newsreader",
+    "weight": 400,
+    "italic": false,
+    "file": "Newsreader-Regular.ttf",
+    "pptx": "Newsreader"
+   },
+   {
+    "family": "Newsreader",
+    "weight": 400,
+    "italic": true,
+    "file": "Newsreader-Italic.ttf",
+    "pptx": "Newsreader"
+   },
+   {
+    "family": "Newsreader",
+    "weight": 500,
+    "italic": false,
+    "file": "Newsreader-Medium.ttf",
+    "pptx": "Newsreader Medium"
+   },
+   {
+    "family": "Newsreader",
+    "weight": 500,
+    "italic": true,
+    "file": "Newsreader-MediumItalic.ttf",
+    "pptx": "Newsreader Medium"
+   }
+  ],
+  "license": "Geist and Newsreader: SIL OFL 1.1, static instances of the Google Fonts variable sources (see fonts/LICENSE-FONTS.md)"
+ },
+ "shape": {
+  "radius": 1,
+  "cardStroke": 1,
+  "emphStroke": 0,
+  "artShade": 0,
+  "_": "artShade: the dark art pages carry no shade over their art, as the approved composition carries none over its trails and ring; the statement and closing art bake in the 30% the kit used to lay over them (tools/art.mjs)"
+ },
+ "art": {
+  "cover": "cover-art.png",
+  "coverPortrait": "cover-portrait-art.png",
+  "overlay": "cover-art.png",
+  "statement": "statement-art.png",
+  "closing": "closing-art.png",
+  "coverArt": "cover-art.png",
+  "divider": "divider-art.png",
+  "markOnLight": "spark-violet.png",
+  "markOnDark": "spark-lavender.png",
+  "wordmarkOnLight": "wordmark-on-light.png",
+  "wordmarkOnDark": "wordmark-on-dark.png",
+  "wordmarkSvgOnLight": "wordmark-on-light.svg",
+  "wordmarkSvgOnDark": "wordmark-on-dark.svg",
+  "mark": "mark.svg",
+  "avatar": "avatar.svg",
+  "composition": "social/composition.json"
+ }
+}

package/examples/social/social.json

@@ -0,0 +1,23 @@
+{
+  "name": "wand-social",
+  "brand": "interim",
+  "site": "Wand",
+  "line": { "lead": "A new workforce.", "phrase": "A new operating era." },
+  "upload": "https://wand.ai/assets/og/20261023/",
+  "cards": [
+    { "kind": "linkedin-banner" },
+    { "kind": "x-header" },
+    { "kind": "linkedin-company" },
+    { "kind": "share", "id": "wand-ai-share", "url": "https://wand.ai/", "title": "Wand AI", "type": "website",
+      "description": "Autonomous AI workers. One operating system for people and agents. The foundation for a new era of enterprise and national capacity.",
+      "alt": "Wand. A new workforce. A new operating era." },
+    { "kind": "share", "id": "open-agent-discovery-share", "url": "https://wand.ai/insights/open-agent-discovery-nandaindex.html",
+      "lead": "An Open Agentic Web", "phrase": "Needs Open Discovery", "type": "article",
+      "title": "An Open Agentic Web Needs Open Discovery | Wand AI",
+      "description": "Why interoperable agent discovery matters for the emerging agentic economy, and how NandaIndex complements governed AI workforces.",
+      "alt": "Wand. An Open Agentic Web Needs Open Discovery." },
+    { "kind": "square" },
+    { "kind": "avatar" },
+    { "kind": "icons", "upload": "/assets/20261022/" }
+  ]
+}

package/lib/audit.js

@@ -0,0 +1,142 @@
+/**
+ * lib/audit.js — how a page's link preview looks today, before anyone redraws it.
+ *
+ * The 2026-10-23 fix (runs/2026-10-23-wand-og-fix) began by reading the live
+ * pages: one image for every page, its words outside the centre square Slack
+ * keeps, small print that vanished in LinkedIn's compact card, an og:title that
+ * repeated the image, an em dash, no twitter tags. This reads the same things
+ * from any page and shows its image the way those feeds do.
+ *
+ *   node wand.js social --audit https://wand.ai/ https://wand.ai/insights/… [--out audit]
+ *   node wand.js social --audit saved-page.html --image its-og-image.png
+ *
+ * A chat with no web access gets a clear row saying so: save the page (and its
+ * image) and pass the files.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { browser } from "./engine.js";
+import { fetchTo, feedRows, wholeWithSquare, previewPage } from "./social.js";
+
+const LIMIT = 300 * 1024;
+const ENT = { amp: "&", quot: '"', apos: "'", lt: "<", gt: ">", nbsp: " ", mdash: "—", ndash: "–", rsquo: "’", lsquo: "‘", rdquo: "”", ldquo: "“", hellip: "…" };
+const decode = (s) => s.replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);/gi, (m, e) => e[0] === "#" ? String.fromCodePoint(e[1] === "x" || e[1] === "X" ? parseInt(e.slice(2), 16) : +e.slice(1)) : ENT[e.toLowerCase()] ?? m);
+
+/** The page's og: and twitter: tags (the first of each, as Slack reads them), how many twitter:card tags, and its <title>. */
+export function readTags(html) {
+  const tags = {}, count = {};
+  for (const [m] of html.matchAll(/<meta\b[^>]*>/gi)) {
+    const attr = {};
+    for (const [, k, , a, b] of m.matchAll(/([\w:-]+)\s*=\s*("([^"]*)"|'([^']*)')/g)) attr[k.toLowerCase()] = decode(a ?? b ?? "");
+    const key = (attr.property || attr.name || "").toLowerCase();
+    if (!/^(og|twitter):/.test(key) || attr.content == null) continue;
+    count[key] = (count[key] || 0) + 1;
+    if (!(key in tags)) tags[key] = attr.content;
+  }
+  const title = decode((/<title[^>]*>([\s\S]*?)<\/title>/i.exec(html) || [])[1] || "").trim();
+  return { tags, count, title };
+}
+
+/** Width, height and type from a PNG, JPEG, GIF or WebP's own header. */
+export function imageFacts(file) {
+  const b = fs.readFileSync(file), bytes = b.length;
+  if (b[0] === 0x89 && b.toString("ascii", 1, 4) === "PNG") return { type: "png", w: b.readUInt32BE(16), h: b.readUInt32BE(20), bytes };
+  if (b.toString("ascii", 0, 3) === "GIF") return { type: "gif", w: b.readUInt16LE(6), h: b.readUInt16LE(8), bytes };
+  if (b.toString("ascii", 8, 12) === "WEBP") {
+    const k = b.toString("ascii", 12, 16);
+    if (k === "VP8X") return { type: "webp", w: 1 + b.readUIntLE(24, 3), h: 1 + b.readUIntLE(27, 3), bytes };
+    if (k === "VP8L") { const v = b.readUInt32LE(21); return { type: "webp", w: (v & 0x3fff) + 1, h: ((v >> 14) & 0x3fff) + 1, bytes }; }
+    return { type: "webp", w: b.readUInt16LE(26) & 0x3fff, h: b.readUInt16LE(28) & 0x3fff, bytes };
+  }
+  if (b[0] === 0xff && b[1] === 0xd8) {
+    for (let i = 2; i < b.length - 9;) {
+      if (b[i] !== 0xff) { i++; continue; }
+      const m = b[i + 1], len = b.readUInt16BE(i + 2);
+      if (m >= 0xc0 && m <= 0xcf && ![0xc4, 0xc8, 0xcc].includes(m)) return { type: "jpeg", w: b.readUInt16BE(i + 7), h: b.readUInt16BE(i + 5), bytes };
+      i += 2 + len;
+    }
+    return { type: "jpeg", w: 0, h: 0, bytes };
+  }
+  return { type: "unknown", w: 0, h: 0, bytes };
+}
+
+const norm = (s) => String(s || "").toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
+/** A short name for a page: the last part of its path, or its host for a home page. */
+const slug = (t) => {
+  const u = /^https?:\/\//.test(t) ? new URL(t) : null, last = (u ? u.pathname : t).split("/").filter(Boolean).pop();
+  return norm((last || u?.hostname || "page").replace(/\.[a-z0-9]+$/i, "")).replace(/ /g, "-").slice(0, 40) || "page";
+};
+/** The image's words (its alt, less the brand's name) found again in the og:title: a preview that says them twice. */
+const repeats = (title, alt) => {
+  const words = (s) => norm(s).split(" ").filter((w) => w && !["wand", "ai", "a", "an", "the"].includes(w));
+  const t = new Set(words(title)), a = words(alt);
+  return a.length >= 3 && a.filter((w) => t.has(w)).length / a.length >= 0.8;
+};
+
+export async function audit(targets, { image = null, out = "audit" } = {}) {
+  if (!targets.length) throw new Error("usage: node wand.js social --audit <url | page.html> [more] [--image og-image.png] [--out audit]");
+  out = path.resolve(out); fs.mkdirSync(out, { recursive: true });
+  const rows = [], pages = [];
+  const row = (ok, gate, msg, warn = false) => rows.push({ ok, warn, gate, msg });
+  for (const t of targets) {
+    const id = slug(t), isUrl = /^https?:\/\//.test(t);
+    let html;
+    try {
+      if (isUrl) {
+        const r = await fetch(t, { signal: AbortSignal.timeout(15000), headers: { "user-agent": "Mozilla/5.0 (wand-kit link-preview audit)" } });
+        if (!r.ok) throw new Error(`answered ${r.status}`);
+        html = await r.text();
+      } else html = fs.readFileSync(path.resolve(t), "utf8");
+    } catch (e) {
+      row(false, id, `could not read ${t} from here (${e.cause?.code || e.message}). Save the page (File, Save As) and its og:image, then: --audit page.html --image image.png`);
+      continue;
+    }
+    const { tags, count, title } = readTags(html), p = { id, target: t, tags, title };
+    pages.push(p);
+    const want = ["og:title", "og:description", "og:url", "og:image", "og:image:width", "og:image:height", "og:image:type", "og:image:alt", "twitter:card", "twitter:title", "twitter:image"];
+    const missing = want.filter((k) => !tags[k]);
+    row(!!tags["og:image"] && !missing.length, `${id} tags`, tags["og:image"] ? (missing.length ? `missing ${missing.join(", ")}` : "every og: and twitter: tag a feed reads") : "no og:image: every feed shows a bare link", !!tags["og:image"] && missing.length > 0);
+    if ((count["twitter:card"] || 0) > 1) row(false, `${id} twitter:card`, `${count["twitter:card"]} twitter:card tags; Slack reads the first`, true);
+    const dash = Object.entries(tags).filter(([, v]) => /—/.test(v)).map(([k]) => k);
+    if (dash.length) row(false, `${id} dashes`, `em dash in ${dash.join(", ")}`, true);
+    if (repeats(tags["og:title"], tags["og:image:alt"])) row(false, `${id} title`, "og:title repeats the image's words, so the preview shows them twice", true);
+    // the image itself
+    const src = image && targets.length === 1 ? image : tags["og:image"] ? new URL(tags["og:image"], isUrl ? t : "https://example.com/").href : null;
+    if (tags["og:image"] && !/^https:\/\//.test(tags["og:image"])) row(false, `${id} image url`, `og:image is not an absolute https URL (${tags["og:image"]}); some feeds drop it`, true);
+    if (src) {
+      try {
+        p.png = await fetchTo(src, path.join(out, `live-${id}`), process.cwd());
+        const f = imageFacts(p.png); p.facts = f;
+        const ratio = f.h ? f.w / f.h : 0, notes = [];
+        if (f.bytes > LIMIT) notes.push("over 300 KB: WhatsApp shows no preview");
+        if (ratio && Math.abs(ratio / 1.905 - 1) > 0.05) notes.push(`${ratio.toFixed(2)}:1, not 1.91:1: feeds crop it`);
+        if (f.w && f.w < 1200) notes.push("under 1200 wide: soft on large cards");
+        row(!notes.length, `${id} image`, `${f.w} x ${f.h}, ${Math.round(f.bytes / 1024)} KB, ${f.type}${notes.length ? "; " + notes.join("; ") : ""}`, notes.length > 0);
+      } catch (e) { row(false, `${id} image`, `${e.message}`); }
+    }
+  }
+  // one picture for every page: nothing in it says what the link is
+  const imgs = pages.map((p) => p.tags["og:image"]).filter(Boolean);
+  if (pages.length > 1 && new Set(imgs).size < imgs.length) row(false, "pages", `${imgs.length - new Set(imgs).size + 1} pages share one og:image: each needs its own (an article its headline)`, true);
+
+  const shot = pages.filter((p) => p.png);
+  if (shot.length) {
+    const u = (f) => pathToFileURL(f).href;
+    const body = shot.map((p) => `<h2>${p.target}</h2>${feedRows(u(p.png), { title: p.tags["og:title"] || p.title, url: p.tags["og:url"] || p.target, description: p.tags["og:description"] })}${p.facts?.w ? wholeWithSquare(u(p.png), p.facts.w, p.facts.h) : ""}`).join("\n");
+    const pg = previewPage(body), htmlPath = path.join(out, "audit.html"), png = path.join(out, "audit.png");
+    fs.writeFileSync(htmlPath, pg.html);
+    const b = await browser(), v = await b.newPage({ viewport: { width: pg.w, height: 400 } });
+    await v.goto(pathToFileURL(htmlPath).href, { waitUntil: "load" });
+    await v.evaluate(() => Promise.all([...document.images].map((i) => (i.complete ? null : new Promise((r) => { i.onload = i.onerror = r; })))));
+    await v.screenshot({ path: png, fullPage: true });
+    await v.close();
+    row(true, "preview", path.relative(process.cwd(), png));
+  }
+  const ok = rows.every((r) => r.ok || r.warn);
+  console.log("");
+  for (const r of rows) console.log(`  ${r.ok ? " ok " : r.warn ? " -- " : "FAIL"}  ${r.gate.padEnd(34)} ${r.msg}`);
+  if (shot.length) console.log(`\n  review  ${path.relative(process.cwd(), path.join(out, "audit.png"))}, as the people scrolling past will see it:\n          does the dashed centre square (Slack's and WhatsApp's cut) hold the whole wordmark and the words?\n          in LinkedIn's compact card (128pt), can you read the line? is there small print that vanishes?\n          is the type the brand's, and does the image say what this page is?`);
+  console.log("");
+  return { ok, rows, pages };
+}