wand-kit 0.3.2 → 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/brands/next/tokens.json

@@ -34,6 +34,10 @@
       "hex": "C4C1CA",
       "from": "white @ 70% on violet200, lists inside dark cards"
     },
+    "secondDark": {
+      "hex": "9D99A8",
+      "from": "white @ 55% on violet300 - a title's quiet second tone on dark (5.7:1)"
+    },
     "footDark": {
       "hex": "888394",
       "from": "white @ 45% on violet300"
@@ -60,7 +64,11 @@
       "rule": "D5CEC2",
       "track": "D5CEC2",
       "surface": "EBE8E2",
-      "emphLabel": "B79A5E"
+      "emphLabel": "B79A5E",
+      "second": "7B7B79",
+      "secondSm": "686766",
+      "gradeLow": "261D3D",
+      "gradeHigh": "F1EFEB"
     },
     "dark": {
       "bg": "261D3D",
@@ -80,7 +88,11 @@
       "rule": "504666",
       "track": "504666",
       "surface": "3A314E",
-      "emphLabel": "C4C1CA"
+      "emphLabel": "C4C1CA",
+      "second": "9D99A8",
+      "secondSm": "BEBBC5",
+      "gradeLow": "261D3D",
+      "gradeHigh": "F1EFEB"
     }
   },
   "faces": {

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/" }
+  ]
+}