feat(web): syntax highlighting on the code plates

A forty-line tokenizer for the three grammars the page actually ships
(Swift, the note block, one shell line) instead of a highlighter library.
Keywords take the accent, comments the muted ink; two new palette tokens
carry strings and types and clear 4.5:1 on paper-2 in both themes. Plain
tokens stay bare text, so the copied string and the a11y tree are unchanged.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: angusbezzina

web/scripts/contrast.mjs

@@ -117,6 +117,8 @@ const PAIRS = [
   ["neutral", "paper", 3.0, "hairline labels (large/decorative only)"],
   ["accent", "paper", 4.5, "section numbers, link underlines, error-free marks"],
   ["accent", "paper-2", 4.5, "accent inside the code block"],
+  ["syntax-string", "paper-2", 4.5, "string literals in the code block"],
+  ["syntax-type", "paper-2", 4.5, "type names in the code block"],
   ["accent-ink", "accent", 4.5, "the submit, and the sub-footer band"],
   ["focus", "paper", 3.0, "focus ring against the page"],
   ["focus", "paper-2", 3.0, "focus ring against a tinted field"],

web/src/components/CodeBlock.tsx

@@ -4,6 +4,7 @@ import { Check, Copy, X } from "lucide-react";
 import { Icon } from "./Icon";
 import { codeBlock } from "../copy";
 import { withCode } from "../markup";
+import { tokenize } from "../highlight";
 
 /**
  * A code sample in a typographic frame — a caption row above a hairline
@@ -94,7 +95,19 @@ export function CodeBlock({
       <ScrollArea.Root className="code__plate" type="auto">
         <ScrollArea.Viewport className="code__viewport" tabIndex={0}>
           <pre className="code__pre">
-            <code data-language={language}>{code}</code>
+            <code data-language={language}>
+              {/* Paint only: plain tokens stay bare text, so the string the
+               * tree exposes is exactly the one the copy button writes. */}
+              {tokenize(code, language).map((token, i) =>
+                token.kind === "plain" ? (
+                  token.text
+                ) : (
+                  <span key={i} className={`tok tok--${token.kind}`}>
+                    {token.text}
+                  </span>
+                ),
+              )}
+            </code>
           </pre>
         </ScrollArea.Viewport>
         <ScrollArea.Scrollbar className="code__scrollbar" orientation="horizontal">

web/src/highlight.ts

@@ -0,0 +1,93 @@
+/**
+ * Syntax highlighting for the five snippets on the page, and nothing more.
+ *
+ * Hand-rolled rather than a library: the page ships three Swift snippets, one
+ * note block and one shell line, and a general-purpose highlighter would be
+ * the largest thing in the bundle by a wide margin for the sake of maybe forty
+ * tokens. The grammars below are tuned to exactly what `copy.ts` contains; a
+ * construct they do not know falls through as plain text, never as a wrong
+ * colour.
+ *
+ * The one invariant worth a test: concatenating the tokens' text gives back
+ * the input byte for byte. Highlighting is paint, not content — the copy
+ * button and the accessibility tree both see the original string.
+ */
+
+export type TokenKind = "plain" | "keyword" | "type" | "string" | "comment" | "heading" | "field";
+
+export type Token = { kind: TokenKind; text: string };
+
+type Rule = { kind: TokenKind; re: RegExp };
+
+/**
+ * Swift. Keywords and compiler directives take the accent; capitalised
+ * identifiers read as types (which on this page they all are: modules,
+ * namespaces, views, sinks); strings and comments get their own inks.
+ */
+const swift: Rule[] = [
+  { kind: "comment", re: /\/\/[^\n]*/y },
+  { kind: "string", re: /"(?:[^"\\]|\\.)*"/y },
+  { kind: "keyword", re: /#(?:if|endif|else|elseif)\b|\b(?:import|let|var|func|struct|return|some|true|false|nil)\b/y },
+  // A type has a lowercase letter in it; an all-caps word (`DEBUG`) is a
+  // compilation condition and stays plain, as it does in Xcode.
+  { kind: "type", re: /\b[A-Z](?=[A-Za-z0-9_]*[a-z])[A-Za-z0-9_]*\b/y },
+  { kind: "plain", re: /[A-Za-z_][A-Za-z0-9_]*|\s+|./y },
+];
+
+/**
+ * The note block. A heading line, then `**Field**: value` lines, then the
+ * comment as prose. Quoted text inside a value (the element's label) reads as
+ * a string, the selector after the dash in the heading reads as a type: it is
+ * the identifier an agent greps for.
+ */
+const markdown: Rule[] = [
+  { kind: "heading", re: /^##[^\n]*/my },
+  { kind: "field", re: /^\*\*[^*\n]+\*\*:/my },
+  { kind: "string", re: /"(?:[^"\\]|\\.)*"/y },
+  { kind: "plain", re: /[^\n"*]+|./y },
+];
+
+/** One shell line: the command word is the keyword, its argument a path. */
+const sh: Rule[] = [
+  { kind: "comment", re: /#[^\n]*/y },
+  { kind: "keyword", re: /^\s*[a-z][\w-]*/my },
+  { kind: "string", re: /\S*\//y },
+  { kind: "plain", re: /\S+|\s+/y },
+];
+
+const grammars: Record<string, Rule[]> = { swift, markdown, sh };
+
+export function tokenize(code: string, language: string): Token[] {
+  const rules = grammars[language];
+  if (!rules) return [{ kind: "plain", text: code }];
+
+  const out: Token[] = [];
+  let i = 0;
+  while (i < code.length) {
+    let matched = false;
+    for (const { kind, re } of rules) {
+      re.lastIndex = i;
+      const m = re.exec(code);
+      if (m && m[0].length > 0) {
+        push(out, kind, m[0]);
+        i += m[0].length;
+        matched = true;
+        break;
+      }
+    }
+    if (!matched) {
+      // Unreachable while every grammar ends in a catch-all, but a silent
+      // infinite loop is the worst possible failure, so advance regardless.
+      push(out, "plain", code.charAt(i));
+      i += 1;
+    }
+  }
+  return out;
+}
+
+/** Merge adjacent tokens of one kind so the DOM carries as few spans as the text allows. */
+function push(out: Token[], kind: TokenKind, text: string) {
+  const last = out[out.length - 1];
+  if (last && last.kind === kind) last.text += text;
+  else out.push({ kind, text });
+}

web/src/styles/base.css

@@ -825,6 +825,32 @@ pre {
   font-size: inherit;
 }
 
+/* Syntax. Keywords take the accent the plate's border already wears, comments
+ * step back to the muted ink, and strings and types get the two inks added
+ * for them. Fields in the note block are bold ink rather than a colour: they
+ * are labels, and the eye should read across them to the value. */
+.tok--keyword,
+.tok--heading {
+  color: var(--color-accent);
+}
+
+.tok--heading,
+.tok--field {
+  font-weight: var(--weight-body-strong);
+}
+
+.tok--comment {
+  color: var(--color-muted);
+}
+
+.tok--string {
+  color: var(--color-syntax-string);
+}
+
+.tok--type {
+  color: var(--color-syntax-type);
+}
+
 /* Horizontal only — code overflows sideways, never down. `type="auto"` means
  * the bar exists only while there is something to scroll to. */
 .code__scrollbar {

web/src/styles/tokens.css

@@ -85,6 +85,13 @@
   --color-accent-ink: oklch(97.5% 0.008 78); /* text on an accent fill */
   --color-focus: oklch(45% 0.160 45);
   --color-error: oklch(47% 0.180 25);
+  /* Syntax inks for the code plates. Two, not a rainbow: the accent already
+   * carries keywords and the muted ink carries comments, so the only colours
+   * the grammar needs that the palette lacks are a string and a type. Both
+   * sit at the ink's weight, one cool and one green, and both clear 4.5:1 on
+   * paper-2 in each theme (see scripts/contrast.mjs). */
+  --color-syntax-string: oklch(42% 0.090 160);
+  --color-syntax-type: oklch(40% 0.100 250);
 
   /* GPU CLI's brand green, and the page's one borrowed colour. It exists so
    * the subfoot link hovers into the org's own ink rather than AnnotKit's,
@@ -209,6 +216,8 @@
   --color-accent-ink: oklch(19% 0.014 60); /* text on an accent fill */
   --color-focus: oklch(78% 0.130 55);
   --color-error: oklch(72% 0.150 25);
+  --color-syntax-string: oklch(80% 0.100 160);
+  --color-syntax-type: oklch(80% 0.085 240);
   --color-gpu: #19dc6a; /* the same brand value — see the light block */
 
   --tint-hairline: color-mix(in oklch, var(--color-ink) 14%, transparent);

web/tests/highlight.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from "vitest";
+import { tokenize } from "../src/highlight";
+import { agentNotes, install, mcpBridge } from "../src/copy";
+
+const snippets = [
+  ["swift", install.appKit.code],
+  ["swift", install.swiftUI.code],
+  ["swift", install.sink.code],
+  ["markdown", agentNotes.sample.code],
+  ["sh", mcpBridge.command.code],
+] as const;
+
+describe("the highlighter", () => {
+  it("gives back every snippet byte for byte", () => {
+    for (const [language, code] of snippets) {
+      expect(tokenize(code, language).map((t) => t.text).join("")).toBe(code);
+    }
+  });
+
+  it("leaves an unknown language alone", () => {
+    expect(tokenize("anything", "cobol")).toEqual([{ kind: "plain", text: "anything" }]);
+  });
+
+  it("reads the Swift it is given", () => {
+    const kinds = Object.fromEntries(
+      tokenize(install.appKit.code, "swift").map((t) => [t.text.trim(), t.kind]),
+    );
+    expect(kinds["import"]).toBe("keyword");
+    expect(kinds["#if"]).toBe("keyword");
+    expect(kinds["AnnotKit"]).toBe("type");
+    expect(kinds["DEBUG"]).toBe("plain");
+    expect(kinds["// floating toolbar; click a view, type a note"]).toBe("comment");
+  });
+
+  it("reads the note block", () => {
+    const tokens = tokenize(agentNotes.sample.code, "markdown");
+    expect(tokens[0]?.kind).toBe("heading");
+    expect(tokens.some((t) => t.kind === "field" && t.text === "**Timestamp**:")).toBe(true);
+    expect(tokens.some((t) => t.kind === "string" && t.text === '"Save"')).toBe(true);
+  });
+});