docs(api): per-symbol pages, fuzzy search, deep token linking, hover cards

Rebuild the API Reference around one page per symbol and richer, verified content.

Pages & navigation
- One HTML page per symbol (kw-*, type-*, phase-*, screen-*, fn-*, annot-*, op-*)
  instead of a single scrolling page; namespace overview pages (ns-screen …
  ns-color) and a searchable index (api.html) with client-side fuzzy search.
- Sticky-header scroll offset (scroll-margin) so a jumped-to entry/param/color is
  never hidden, plus a flash highlight on the scrolled-to target.

Deep linking in every snippet & example
- Namespace members split: `Screen`→namespace page, `fill_rectangle`→method page;
  `Color`→palette page, `Charcoal`→its swatch — separately.
- Named arguments (`width:`) link to that parameter's anchor on the method page.
- Hover any token for a summary card built from the real API data (symbols.json).

Content & coverage
- Full authoritative surface documented from the compiler: every keyword, type,
  the 6 phases (Start/Input/FixedUpdate/Update/LateUpdate/Render, each its own
  page), all 22 annotations, namespace methods with parameter docs, builtins,
  the world_* reflection ABI, networking, operators — 155 symbols.
- Longer, clearer explanations; "model"/"model instance" terminology, not "entity";
  descriptive identifiers in every example (Position{column,row}, Velocity{delta_x,
  delta_y}, Health{current,maximum}, Player/Enemy) — no Pos/Seg/x/dx.
- Accuracy fixes from compiler ground-truth: world_count() takes no arg,
  world_query_next(property, cursor) arg order, event fields bind by name; dropped
  `when` and `module` (not in the self-hosted parser).

Tooling
- inventory.json + check.py: coverage guard (every symbol has a page), duplicate-
  token guard, and broken-link guard — fail CI so docs can't drift.
- validate.py: compiles every ```ludic example against bin/ludicc (158 compile).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

tools/docgen/assets/index.tmpl.html

@@ -0,0 +1,166 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>%(title)s</title>
+<meta name="description" content="%(desc)s">
+<meta property="og:title" content="%(ogt)s">
+<meta property="og:description" content="%(ogd)s">
+<meta property="og:type" content="website">
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;700&display=swap" rel="stylesheet">
+<style>
+%(css)s
+</style>
+</head>
+<body>
+<header class="nav">
+  <div class="wrap nav-in">
+    <a class="brand" href="#top"><span class="logo">L</span> %(brand)s</a>
+    <nav class="nav-links">%(navlinks)s
+      <a class="nav-cta" href="%(repo)s">Source ↗</a>
+    </nav>
+  </div>
+</header>
+
+<a id="top"></a>
+<section class="hero">
+  <div class="wrap hero-grid">
+    <div>
+      <span class="pill"><span class="dot"></span> %(pill)s</span>
+      <h1>%(title_pre)s <span class="accent">%(title_accent)s</span></h1>
+      <p class="lead">%(lead)s</p>
+      <div class="cta-row">
+        <a class="btn btn-primary" href="%(pcta_h)s">%(pcta_l)s</a>
+        <a class="btn btn-ghost" href="%(scta_h)s">%(scta_l)s</a>
+      </div>
+    </div>
+    <div class="code-card reveal">
+      <div class="code-top">
+        <span class="tl r"></span><span class="tl y"></span><span class="tl g"></span>
+        <span class="code-name">%(hero_name)s</span>
+      </div>
+      <pre data-lang="ludic">%(hero_code)s</pre>
+    </div>
+  </div>
+  <div class="wrap" style="margin-top:52px">
+    <div class="pipeline reveal">%(stages)s</div>
+    <p style="text-align:center;color:var(--muted);font-size:13.5px;margin:14px 0 0">%(pipenote)s</p>
+  </div>
+</section>
+
+<section id="features">
+  <div class="wrap">
+    <div class="sec-head reveal">
+      <div class="kicker">%(feat_kicker)s</div>
+      <h2>%(feat_title)s</h2>
+      <p>%(feat_intro)s</p>
+    </div>
+    <div class="feat-grid">%(feats)s</div>
+  </div>
+</section>
+
+<section id="showcase" style="padding-top:24px">
+  <div class="wrap">
+    <div class="sec-head reveal">
+      <div class="kicker">%(sc_kicker)s</div>
+      <h2>%(sc_title)s</h2>
+      <p>%(sc_intro)s</p>
+    </div>
+    <div class="tabs reveal" id="tabs"></div>
+    <div id="panels"></div>
+    <div class="showcase-note reveal"><span class="b">↳</span><span id="note"></span></div>
+  </div>
+</section>
+
+<section style="padding-top:24px">
+  <div class="wrap">
+    <div class="banner reveal">
+      <div>
+        <div class="kicker" style="color:var(--blue)">%(phil_kicker)s</div>
+        <h2>%(phil_title)s</h2>
+        %(phil_paras)s
+      </div>
+      <div class="stat-row">%(phil_stats)s</div>
+    </div>
+  </div>
+</section>
+
+<section id="start">
+  <div class="wrap">
+    <div class="sec-head reveal">
+      <div class="kicker">%(start_kicker)s</div>
+      <h2>%(start_title)s</h2>
+      <p>%(start_intro)s</p>
+    </div>
+    <div class="steps">
+      <div>%(steps)s</div>
+      <div class="term reveal">
+        <div class="code-top">
+          <span class="tl r"></span><span class="tl y"></span><span class="tl g"></span>
+          <span class="code-name">%(term_name)s</span>
+        </div>
+<pre>%(term)s</pre>
+      </div>
+    </div>
+  </div>
+</section>
+
+<section id="editors" style="padding-top:24px">
+  <div class="wrap">
+    <div class="sec-head reveal">
+      <div class="kicker">%(ed_kicker)s</div>
+      <h2>%(ed_title)s</h2>
+      <p>%(ed_intro)s</p>
+    </div>
+    <div class="editors reveal">%(eds)s</div>
+    <p style="margin-top:22px;color:var(--muted);font-size:14.5px">%(ed_note)s</p>
+  </div>
+</section>
+
+<footer>
+  <div class="wrap foot-in">
+    <div>
+      <div class="brand" style="margin-bottom:8px"><span class="logo">L</span> %(brand)s</div>
+      <div class="muted">%(tagline)s</div>
+    </div>
+    <nav class="foot-links">%(footlinks)s</nav>
+  </div>
+</footer>
+
+<script src="ludic-highlight.js"></script>
+<script>
+Ludic.highlightAll();
+const SAMPLES = %(samples)s;
+const tabsEl = document.getElementById("tabs");
+const panelsEl = document.getElementById("panels");
+const noteEl = document.getElementById("note");
+SAMPLES.forEach((s, idx)=>{
+  const t = document.createElement("button");
+  t.className = "tab" + (idx===0 ? " active" : "");
+  t.textContent = s.label;
+  t.onclick = ()=>select(idx);
+  tabsEl.appendChild(t);
+  const card = document.createElement("div");
+  card.className = "code-card panel-code" + (idx===0 ? " active" : "");
+  card.innerHTML =
+    '<div class="code-top"><span class="tl r"></span><span class="tl y"></span><span class="tl g"></span><span class="code-name">'
+    + s.name + '</span></div><pre>' + Ludic.highlight(s.code) + '</pre>';
+  panelsEl.appendChild(card);
+});
+function select(idx){
+  [...tabsEl.children].forEach((t,i)=>t.classList.toggle("active", i===idx));
+  [...panelsEl.children].forEach((p,i)=>p.classList.toggle("active", i===idx));
+  noteEl.textContent = SAMPLES[idx].note;
+}
+noteEl.textContent = SAMPLES[0].note;
+Ludic.installCards();
+const io = new IntersectionObserver((entries)=>{
+  entries.forEach(e=>{ if(e.isIntersecting){ e.target.classList.add("in"); io.unobserve(e.target); } });
+},{threshold:.12});
+document.querySelectorAll(".reveal").forEach(el=>io.observe(el));
+</script>
+</body>
+</html>

tools/docgen/assets/item.css

@@ -0,0 +1,139 @@
+  :root{
+    --bg:#0a0d18; --bg2:#0d1122; --panel:#12172b; --panel2:#151b32;
+    --line:#232b47; --line2:#2c3660; --text:#c9d2ea; --head:#f2f5ff; --muted:#8290b4;
+    --mint:#7cf5c4; --coral:#ff5d73; --violet:#c792ea; --blue:#82aaff; --amber:#f6c177;
+    --c-bg:#0b0f20; --c-comment:#5b6788; --c-key:#ff7eb6; --c-type:#7cf5c4;
+    --c-str:#f6c177; --c-num:#a6b8ff; --c-annot:#c792ea; --c-fn:#82aaff; --c-punc:#9aa6cc; --c-arg:#f6c177;
+    --radius:14px; --max:900px; --hdr:64px;
+  }
+  *{box-sizing:border-box}
+  html{scroll-behavior:smooth}
+  body{margin:0;background:
+      radial-gradient(1100px 600px at 82% -8%, rgba(124,245,196,.07), transparent 60%),
+      var(--bg);color:var(--text);
+    font-family:"Space Grotesk",system-ui,-apple-system,Segoe UI,Roboto,sans-serif;line-height:1.65;-webkit-font-smoothing:antialiased}
+  a{color:inherit;text-decoration:none}
+  code,pre,.mono{font-family:"JetBrains Mono",ui-monospace,SFMono-Regular,Menlo,monospace}
+  .wrap{max-width:var(--max);margin:0 auto;padding:0 24px}
+
+  header.nav{position:sticky;top:0;z-index:50;backdrop-filter:blur(10px);
+    background:rgba(10,13,24,.82);border-bottom:1px solid var(--line);height:var(--hdr)}
+  .nav-in{display:flex;align-items:center;gap:22px;height:var(--hdr)}
+  .brand{display:flex;align-items:center;gap:10px;font-weight:700;color:var(--head);font-size:18px}
+  .logo{width:26px;height:26px;border-radius:7px;display:grid;place-items:center;
+    background:linear-gradient(135deg,var(--mint),#3fd7a6);color:#06231a;font-weight:700;font-size:15px}
+  .nav-links{display:flex;gap:22px;margin-left:auto;align-items:center}
+  .nav-links a{color:var(--muted);font-size:14.5px;font-weight:500}
+  .nav-links a:hover{color:var(--head)}
+  .nav-cta{border:1px solid var(--line2);padding:8px 15px;border-radius:9px;color:var(--head)!important;background:var(--panel)}
+  .nav-cta:hover{border-color:var(--mint)}
+  @media(max-width:760px){.nav-links a:not(.nav-cta){display:none}}
+
+  /* code token colors + snippet links */
+  pre{margin:12px 0 0;padding:16px 18px;overflow:auto;font-size:13.5px;line-height:1.72;tab-size:2;
+    background:var(--c-bg);border:1px solid var(--line);border-radius:12px}
+  pre::-webkit-scrollbar{height:8px}
+  pre::-webkit-scrollbar-thumb{background:var(--line2);border-radius:6px}
+  .t-com{color:var(--c-comment);font-style:italic}
+  .t-key{color:var(--c-key)}.t-type{color:var(--c-type)}.t-str{color:var(--c-str)}
+  .t-num{color:var(--c-num)}.t-annot{color:var(--c-annot)}.t-fn{color:var(--c-fn)}
+  .t-punc{color:var(--c-punc)}.t-arg{color:var(--c-arg)}
+  a.tok{border-radius:3px;transition:background .12s,outline-color .12s}
+  a.tok:hover{background:rgba(124,245,196,.15);outline:1px solid rgba(124,245,196,.4)}
+
+  /* ---- item page ---- */
+  main.item{padding:30px 24px 90px;max-width:var(--max)}
+  .crumbs{font-size:13px;color:var(--muted);margin-bottom:20px}
+  .crumbs a:hover{color:var(--mint)}
+  .crumbs span{opacity:.6;margin:0 2px}
+  .crumbs .here{color:var(--text);opacity:1}
+  .item-head{display:flex;align-items:center;gap:12px;flex-wrap:wrap;scroll-margin-top:calc(var(--hdr) + 20px)}
+  .item-head h1{margin:0;font-size:clamp(26px,4vw,38px);color:var(--head);letter-spacing:-.5px;
+    font-family:"JetBrains Mono",monospace;font-weight:700}
+  .kind-badge{font-size:11px;font-weight:600;letter-spacing:1px;text-transform:uppercase;
+    padding:4px 9px;border-radius:7px;border:1px solid var(--line2);color:var(--muted);background:var(--panel)}
+  .kind-keyword{color:var(--c-key);border-color:rgba(255,126,182,.4)}
+  .kind-type{color:var(--c-type);border-color:rgba(124,245,196,.4)}
+  .kind-phase{color:var(--blue);border-color:rgba(130,170,255,.4)}
+  .kind-method,.kind-builtin{color:var(--c-fn);border-color:rgba(130,170,255,.4)}
+  .kind-annotation{color:var(--c-annot);border-color:rgba(199,146,234,.4)}
+  .kind-namespace{color:var(--amber);border-color:rgba(246,193,119,.4)}
+  .kind-operator{color:var(--muted)}
+  .sig{display:inline-block;margin:18px 0 4px;color:var(--c-fn);background:var(--c-bg);
+    border:1px solid var(--line);border-radius:9px;padding:9px 13px;font-size:14px}
+  .desc{margin-top:14px}
+  .desc p{margin:0 0 12px;font-size:16px;color:var(--text);max-width:720px}
+  .desc code{color:var(--amber);background:var(--panel);padding:1px 5px;border-radius:5px;font-size:13px}
+  .desc b{color:var(--head)}
+
+  .params,.examples,.related{margin-top:30px}
+  .params h2,.examples h2,.related h2{font-size:15px;text-transform:uppercase;letter-spacing:1.5px;
+    color:var(--muted);font-weight:600;margin:0 0 12px}
+  .param{display:flex;gap:14px;align-items:baseline;padding:10px 12px;border:1px solid var(--line);
+    border-radius:10px;background:var(--panel);margin-bottom:8px;scroll-margin-top:calc(var(--hdr) + 20px)}
+  .param .pname{color:var(--c-arg);font-size:13.5px;min-width:110px;flex:none}
+  .param .pdesc{color:var(--text);font-size:14.5px}
+  .param code{color:var(--amber);background:var(--c-bg);padding:1px 5px;border-radius:5px;font-size:12.5px}
+  .rel-row{display:flex;flex-wrap:wrap;gap:10px}
+  a.rel{font-family:"JetBrains Mono",monospace;font-size:13px;color:var(--text);background:var(--panel);
+    border:1px solid var(--line);border-radius:9px;padding:7px 12px}
+  a.rel:hover{border-color:var(--mint);color:var(--mint)}
+  a.back{display:inline-block;margin-top:34px;color:var(--muted);font-size:14px}
+  a.back:hover{color:var(--mint)}
+
+  /* namespace overview */
+  .ns-blurb{color:var(--muted);font-size:16px;max-width:720px;margin:14px 0 22px}
+  .ns-blurb code{color:var(--mint);background:rgba(124,245,196,.08);padding:1px 5px;border-radius:5px;font-size:13px}
+  .ns-methods{display:flex;flex-direction:column;gap:8px}
+  a.ns-method{display:flex;flex-direction:column;gap:4px;padding:12px 14px;border:1px solid var(--line);
+    border-radius:11px;background:var(--panel);transition:border-color .14s,transform .14s}
+  a.ns-method:hover{border-color:var(--mint);transform:translateX(2px)}
+  .nm-sig{color:var(--c-fn);font-size:13.5px}
+  .nm-tip{color:var(--muted);font-size:13.5px}
+
+  /* swatches (Color page) */
+  .swatch-group{margin-bottom:22px}
+  .swatch-group h3{margin:0 0 12px;font-size:13px;letter-spacing:1.5px;text-transform:uppercase;color:var(--muted)}
+  .swatch-row{display:grid;grid-template-columns:repeat(auto-fill,minmax(200px,1fr));gap:10px}
+  .swatch{display:flex;align-items:center;gap:10px;background:var(--panel);border:1px solid var(--line);
+    border-radius:9px;padding:8px 10px;scroll-margin-top:calc(var(--hdr) + 20px)}
+  .chip{width:24px;height:24px;border-radius:6px;flex:none;box-shadow:inset 0 0 0 1px rgba(255,255,255,.12)}
+  .cname{font-family:"JetBrains Mono",monospace;font-size:12px;color:var(--head);white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
+  .chex{margin-left:auto;font-family:"JetBrains Mono",monospace;font-size:11px;color:var(--muted)}
+
+  /* ---- api index + search ---- */
+  main.ref{padding:34px 24px 90px}
+  .ref-intro{margin-bottom:30px}
+  .ref-intro .kicker{font-size:13px;font-weight:600;letter-spacing:2px;text-transform:uppercase;color:var(--mint);margin-bottom:12px}
+  .ref-intro h1{font-size:clamp(30px,5vw,46px);margin:0 0 12px;color:var(--head);letter-spacing:-1px}
+  .ref-intro p{font-size:16px;color:var(--muted);max-width:720px;margin:0 0 20px}
+  .search{width:100%;max-width:560px;font-family:"JetBrains Mono",monospace;font-size:15px;color:var(--head);
+    background:var(--panel);border:1px solid var(--line2);border-radius:11px;padding:13px 16px;outline:none}
+  .search:focus{border-color:var(--mint);box-shadow:0 0 0 3px rgba(124,245,196,.12)}
+  .noresults{color:var(--muted);margin-top:16px}
+  .idx-sec{margin-top:40px;scroll-margin-top:calc(var(--hdr) + 20px)}
+  .idx-sec h2{font-size:22px;color:var(--head);margin:0 0 4px;letter-spacing:-.3px}
+  .sec-blurb{color:var(--muted);font-size:14.5px;margin:0 0 16px;max-width:720px}
+  .sec-blurb code{color:var(--mint);background:rgba(124,245,196,.08);padding:1px 5px;border-radius:5px;font-size:12.5px}
+  .idx-grid{display:grid;grid-template-columns:repeat(auto-fill,minmax(280px,1fr));gap:10px}
+  a.idx-item{display:flex;flex-direction:column;gap:3px;padding:11px 13px;border:1px solid var(--line);
+    border-radius:10px;background:var(--panel);transition:border-color .14s,transform .14s}
+  a.idx-item:hover{border-color:var(--mint);transform:translateY(-2px)}
+  a.idx-item code{color:var(--c-fn);font-size:13.5px}
+  a.idx-item span{color:var(--muted);font-size:13px;line-height:1.5}
+
+  /* ---- hover card ---- */
+  .hovercard{position:fixed;z-index:100;max-width:340px;background:var(--panel2);border:1px solid var(--line2);
+    border-radius:12px;padding:12px 14px;box-shadow:0 20px 50px -18px rgba(0,0,0,.8);pointer-events:none}
+  .hc-top{display:flex;align-items:center;gap:9px;margin-bottom:8px}
+  .hc-name{font-family:"JetBrains Mono",monospace;color:var(--head);font-weight:700;font-size:14px}
+  .hc-sig{display:block;color:var(--c-fn);background:var(--c-bg);border:1px solid var(--line);border-radius:7px;
+    padding:6px 9px;font-size:12px;margin-bottom:8px;white-space:pre-wrap}
+  .hc-tip{color:var(--text);font-size:13.5px;line-height:1.5}
+  .hc-foot{color:var(--muted);font-size:11.5px;margin-top:9px;letter-spacing:.3px}
+
+  /* ---- target flash ---- */
+  @keyframes ludicflash{0%{background:rgba(124,245,196,.28);box-shadow:0 0 0 3px rgba(124,245,196,.28)}
+    100%{background:transparent;box-shadow:0 0 0 3px transparent}}
+  .flash{animation:ludicflash 1.4s ease-out}
+  .item-head.flash h1{color:var(--mint)}

tools/docgen/assets/ludic-highlight.tmpl.js

@@ -1,132 +1,186 @@
 /* ============================================================================
- * ludic-highlight.js — the Ludic syntax highlighter for the docs site.
+ * ludic-highlight.js — the Ludic syntax highlighter + docs interactions.
  *
  * GENERATED FILE — do not edit by hand. The symbol tables below (keywords,
- * types, phases, namespace methods, builtins, annotations and their one-line
- * tips + anchors) are produced by tools/docgen/gen.py from the per-symbol
- * source files in docs/language/**. Add a symbol there and it is recognized,
- * colored, tipped and linked here automatically — nothing to maintain twice.
+ * types, phases, namespace methods + their parameter labels, builtins,
+ * annotations, namespaces, one-line tips, per-item page targets and hover-card
+ * data) are produced by tools/docgen/gen.py from the per-symbol source files in
+ * docs/language/**. Add a symbol there and it is recognized, colored, tipped,
+ * linked and card-previewed here automatically.
  *
- * Beyond coloring, every token the language defines becomes a link into the API
- * Reference (api.html): hover a keyword, a Screen.* call, a named color, a
- * builtin or a type and it points at the entry that explains it. Your own
- * symbols (functions, entities, fields) stay plain.
+ * In any code sample: every keyword/type/builtin/annotation links to its own
+ * page; `Screen.fill_rectangle` links `Screen` → the namespace page and
+ * `fill_rectangle` → the method page, separately; a named argument like
+ * `width:` links to that parameter on the method's page; `Color.Charcoal`
+ * links `Color` and `Charcoal` separately. Hovering any of them shows a summary
+ * card pulled from the real API data.
  * ========================================================================== */
 (function (global) {
   "use strict";
 
-  const SYMBOLS = /*__SYMBOLS__*/{};
-  const KEYWORDS   = SYMBOLS.keywords    || {};
-  const TYPES      = SYMBOLS.types       || {};
-  const PHASES     = SYMBOLS.phases      || {};
-  const BUILTINS   = SYMBOLS.builtins    || {};
-  const NSMETHODS  = SYMBOLS.nsmethods   || {};
-  const ANNOTS     = SYMBOLS.annotations || {};
-  const TIPS       = SYMBOLS.tips        || {};
-  const NAMESPACES = new Set(SYMBOLS.namespaces || []);
-  const COLORS_ANCHOR = SYMBOLS.colors_anchor || "colors";
-  const ANNOT_ANCHOR  = SYMBOLS.annotations_anchor || "annotations";
+  const S = /*__SYMBOLS__*/{};
+  const KEYWORDS = S.keywords || {}, TYPES = S.types || {}, PHASES = S.phases || {};
+  const BUILTINS = S.builtins || {}, NSMETHODS = S.nsmethods || {}, ANNOTS = S.annotations || {};
+  const NAMESPACES = S.namespaces || {}, TIPS = S.tips || {}, CARDS = S.cards || {};
 
-  function esc(s) {
-    return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
-  }
+  function esc(s){ return s.replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/>/g,"&gt;"); }
   const isIdStart = c => /[A-Za-z_]/.test(c);
   const isId = c => /[A-Za-z0-9_]/.test(c);
 
-  function link(href, tip, inner) {
-    const t = tip ? ' title="' + esc(tip) + '"' : "";
-    return '<a class="tok" href="' + href + '"' + t + ">" + inner + "</a>";
+  function link(href, id, tip, inner){
+    const t = tip ? ' title="'+esc(tip).replace(/"/g,"&quot;")+'"' : "";
+    const d = id ? ' data-id="'+id+'"' : "";
+    return '<a class="tok" href="'+href+'"'+d+t+'>'+inner+'</a>';
   }
 
-  function highlight(src) {
-    let out = "", i = 0;
-    const n = src.length;
-    while (i < n) {
-      const c = src[i];
-      // comment
-      if (c === "#") {
-        let j = i; while (j < n && src[j] !== "\n") j++;
-        out += '<span class="t-com">' + esc(src.slice(i, j)) + "</span>";
-        i = j; continue;
-      }
-      // string / char / interpolation (backtick)
-      if (c === '"' || c === "'" || c === "`") {
-        const q = c; let j = i + 1;
-        while (j < n && src[j] !== q) { if (src[j] === "\\") j++; j++; }
-        j = Math.min(j + 1, n);
-        out += '<span class="t-str">' + esc(src.slice(i, j)) + "</span>";
-        i = j; continue;
-      }
-      // annotation @Name
-      if (c === "@") {
-        let j = i + 1; while (j < n && isId(src[j])) j++;
-        const at = src.slice(i, j);
-        const anchor = ANNOTS[at] || ANNOT_ANCHOR;
-        const tip = TIPS[at] || "A compile-time annotation.";
-        out += link("api.html#" + anchor, tip,
-          '<span class="t-annot">' + esc(at) + "</span>");
-        i = j; continue;
-      }
-      // number (incl 0x hex)
-      if (/[0-9]/.test(c)) {
-        let j = i; while (j < n && /[0-9a-fA-FxX._]/.test(src[j])) j++;
-        out += '<span class="t-num">' + esc(src.slice(i, j)) + "</span>";
-        i = j; continue;
-      }
-      // identifier / keyword / type / namespace.member / builtin
-      if (isIdStart(c)) {
-        let j = i; while (j < n && isId(src[j])) j++;
-        const word = src.slice(i, j);
+  function highlight(src){
+    let out = "", i = 0; const n = src.length;
+    const stack = [];          // call-context stack for named-parameter linking
+    let pending = null;        // ctx to push at the next "("
+    const nextNonSpace = j => { while (j < n && src[j] === " ") j++; return j; };
 
-        // Namespace.member  (Screen.fill_rectangle, Color.Crimson, …)
-        if (NAMESPACES.has(word) && src[j] === "." && j + 1 < n && isIdStart(src[j + 1])) {
-          let k = j + 1; while (k < n && isId(src[k])) k++;
-          const member = src.slice(j + 1, k);
-          const key = word + "." + member;
-          let href, tip;
-          if (word === "Color") {
-            href = "api.html#" + COLORS_ANCHOR; tip = "Named color " + key + ".";
+    while (i < n){
+      const c = src[i];
+      if (c === "#"){ let j=i; while(j<n && src[j]!=="\n") j++; out+='<span class="t-com">'+esc(src.slice(i,j))+'</span>'; i=j; continue; }
+      if (c === '"' || c === "'" || c === "`"){ const q=c; let j=i+1; while(j<n && src[j]!==q){ if(src[j]==="\\") j++; j++; } j=Math.min(j+1,n); out+='<span class="t-str">'+esc(src.slice(i,j))+'</span>'; i=j; continue; }
+      if (c === "@"){ let j=i+1; while(j<n && isId(src[j])) j++; const at=src.slice(i,j); const id=ANNOTS[at];
+        if (id) out += link(id+".html", id, TIPS[at]||"A compile-time annotation.", '<span class="t-annot">'+esc(at)+'</span>');
+        else out += '<span class="t-annot">'+esc(at)+'</span>';
+        i=j; continue; }
+      if (/[0-9]/.test(c)){ let j=i; while(j<n && /[0-9a-fA-FxX._]/.test(src[j])) j++; out+='<span class="t-num">'+esc(src.slice(i,j))+'</span>'; i=j; continue; }
+
+      if (isIdStart(c)){
+        let j=i; while(j<n && isId(src[j])) j++; const word=src.slice(i,j);
+
+        // Namespace.member — link the two halves separately
+        if (NAMESPACES[word] && src[j]==="." && j+1<n && isIdStart(src[j+1])){
+          let k=j+1; while(k<n && isId(src[k])) k++; const member=src.slice(j+1,k);
+          const nsId=NAMESPACES[word];
+          out += link(nsId+".html", nsId, TIPS[word]||(word+" namespace"), '<span class="t-type">'+word+'</span>');
+          out += '<span class="t-punc">.</span>';
+          if (word === "Color"){
+            out += link("ns-color.html#"+member.toLowerCase(), "", "Named color "+word+"."+member+".", '<span class="t-fn">'+esc(member)+'</span>');
           } else {
-            href = "api.html#" + (NSMETHODS[key] || (word.toLowerCase() + "-" + member));
-            tip = TIPS[key] || key;
+            const key=word+"."+member, m=NSMETHODS[key];
+            if (m){
+              out += link(m.id+".html", m.id, TIPS[key]||key, '<span class="t-fn">'+esc(member)+'</span>');
+              if (src[nextNonSpace(k)]==="(") pending = {page:m.id, params:new Set(m.params||[])};
+            } else out += '<span class="t-fn">'+esc(member)+'</span>';
           }
-          const inner = '<span class="t-type">' + word + '</span><span class="t-punc">.</span><span class="t-fn">' + esc(member) + "</span>";
-          out += link(href, tip, inner);
-          i = k; continue;
+          i=k; continue;
         }
 
-        let k2 = j; while (k2 < n && src[k2] === " ") k2++;
-        const callish = src[k2] === "(";
-        if (KEYWORDS[word]) {
-          out += link("api.html#" + KEYWORDS[word], TIPS[word], '<span class="t-key">' + word + "</span>");
-        } else if (BUILTINS[word] && callish) {
-          out += link("api.html#" + BUILTINS[word], TIPS[word], '<span class="t-fn">' + word + "</span>");
-        } else if (TYPES[word]) {
-          out += link("api.html#" + TYPES[word], TIPS[word] || ("The " + word + " type."), '<span class="t-type">' + word + "</span>");
-        } else if (PHASES[word]) {
-          out += link("api.html#" + PHASES[word], "The " + word + " phase.", '<span class="t-type">' + word + "</span>");
-        } else if (callish) {
-          out += '<span class="t-fn">' + esc(word) + "</span>";
+        const ns = nextNonSpace(j);
+        const callish = src[ns] === "(";
+        const labelish = src[ns] === ":";
+        const top = stack.length ? stack[stack.length-1] : null;
+
+        if (KEYWORDS[word]){
+          out += link(KEYWORDS[word]+".html", KEYWORDS[word], TIPS[word], '<span class="t-key">'+word+'</span>');
+        } else if (BUILTINS[word] && callish){
+          const b=BUILTINS[word];
+          out += link(b.id+".html", b.id, TIPS[word], '<span class="t-fn">'+word+'</span>');
+          pending = {page:b.id, params:new Set(b.params||[])};
+        } else if (labelish && top && top.params.has(word)){
+          out += link(top.page+".html#param-"+word, "", "parameter: "+word, '<span class="t-arg">'+word+'</span>');
+        } else if (TYPES[word]){
+          out += link(TYPES[word]+".html", TYPES[word], TIPS[word]||("The "+word+" type."), '<span class="t-type">'+word+'</span>');
+        } else if (PHASES[word]){
+          out += link(PHASES[word]+".html", PHASES[word], TIPS[word]||("The "+word+" phase."), '<span class="t-type">'+word+'</span>');
+        } else if (callish){
+          out += '<span class="t-fn">'+esc(word)+'</span>';
         } else {
           out += esc(word);
         }
-        i = j; continue;
-      }
-      // punctuation
-      if (/[{}\[\]()=<>+\-*\/%,.:;!&|~]/.test(c)) {
-        out += '<span class="t-punc">' + esc(c) + "</span>";
-        i++; continue;
+        i=j; continue;
       }
+
+      if (c === "("){ stack.push(pending); pending=null; out+='<span class="t-punc">(</span>'; i++; continue; }
+      if (c === ")"){ stack.pop(); out+='<span class="t-punc">)</span>'; i++; continue; }
+      if (/[{}\[\]=<>+\-*\/%,.:;!&|~]/.test(c)){ out+='<span class="t-punc">'+esc(c)+'</span>'; i++; continue; }
       out += esc(c); i++;
     }
     return out;
   }
 
-  function highlightAll() {
-    document.querySelectorAll('pre[data-lang="ludic"]').forEach(pre => {
-      pre.innerHTML = highlight(pre.textContent);
-    });
+  function highlightAll(){
+    document.querySelectorAll('pre[data-lang="ludic"]').forEach(pre => { pre.innerHTML = highlight(pre.textContent); });
   }
 
-  global.Ludic = { highlight, highlightAll, SYMBOLS };
+  /* ---- hover cards ------------------------------------------------------- */
+  let cardEl = null, cardTimer = null;
+  function ensureCard(){
+    if (cardEl) return cardEl;
+    cardEl = document.createElement("div"); cardEl.className = "hovercard"; cardEl.hidden = true;
+    document.body.appendChild(cardEl); return cardEl;
+  }
+  function showCard(a){
+    const id = a.getAttribute("data-id"); if (!id) return;
+    const c = CARDS[id]; if (!c) return;
+    const el = ensureCard();
+    el.innerHTML = '<div class="hc-top"><span class="kind-badge kind-'+(c.kind||"").replace("namespace-method","method")+'">'
+      + (c.kind||"").replace("namespace-method","method") + '</span><span class="hc-name">'+esc(c.name||"")+'</span></div>'
+      + (c.sig ? '<code class="hc-sig">'+esc(c.sig)+'</code>' : "")
+      + '<div class="hc-tip">'+esc(c.tip||"")+'</div>'
+      + '<div class="hc-foot">'+esc(c.section||"")+' · click to open</div>';
+    el.hidden = false;
+    const r = a.getBoundingClientRect();
+    const cw = el.offsetWidth, ch = el.offsetHeight;
+    let left = r.left, top = r.bottom + 8;
+    if (left + cw > window.innerWidth - 12) left = window.innerWidth - cw - 12;
+    if (left < 12) left = 12;
+    if (top + ch > window.innerHeight - 12) top = r.top - ch - 8;
+    el.style.left = Math.max(12,left) + "px"; el.style.top = Math.max(12,top) + "px";
+  }
+  function hideCard(){ if (cardEl) cardEl.hidden = true; }
+  function installCards(){
+    document.addEventListener("mouseover", e => {
+      const a = e.target.closest && e.target.closest("a.tok[data-id]");
+      if (!a) return;
+      clearTimeout(cardTimer); cardTimer = setTimeout(()=>showCard(a), 130);
+    });
+    document.addEventListener("mouseout", e => {
+      const a = e.target.closest && e.target.closest("a.tok[data-id]");
+      if (a){ clearTimeout(cardTimer); hideCard(); }
+    });
+    window.addEventListener("scroll", hideCard, {passive:true});
+  }
+
+  /* ---- flash the scrolled-to target ------------------------------------- */
+  function flash(el){ if (!el) return; el.classList.remove("flash"); void el.offsetWidth; el.classList.add("flash"); }
+  function flashTarget(){
+    const go = () => {
+      const h = location.hash ? decodeURIComponent(location.hash.slice(1)) : "";
+      let el = h ? document.getElementById(h) : null;
+      if (!el) el = document.querySelector(".item-head") || document.getElementById("top");
+      flash(el);
+    };
+    if (document.readyState !== "loading") go(); else document.addEventListener("DOMContentLoaded", go);
+    window.addEventListener("hashchange", () => { const el = document.getElementById(decodeURIComponent(location.hash.slice(1))); flash(el); });
+  }
+
+  /* ---- fuzzy search on the API index ------------------------------------ */
+  function subseq(q, s){ let i=0; for (let k=0;k<s.length && i<q.length;k++) if (s[k]===q[i]) i++; return i===q.length; }
+  function installSearch(){
+    const box = document.getElementById("search"); if (!box) return;
+    const items = [...document.querySelectorAll(".idx-item")];
+    const secs = [...document.querySelectorAll(".idx-sec")];
+    const none = document.getElementById("noresults");
+    const run = () => {
+      const q = box.value.trim().toLowerCase();
+      let shown = 0;
+      items.forEach(it => {
+        const name = (it.getAttribute("data-name")||"").toLowerCase();
+        const tip = (it.getAttribute("data-tip")||"").toLowerCase();
+        const hit = !q || name.includes(q) || tip.includes(q) || subseq(q, name);
+        it.style.display = hit ? "" : "none"; if (hit) shown++;
+      });
+      secs.forEach(sec => { const any = [...sec.querySelectorAll(".idx-item")].some(i=>i.style.display!=="none"); sec.style.display = any ? "" : "none"; });
+      if (none) none.hidden = shown !== 0;
+    };
+    box.addEventListener("input", run);
+    box.addEventListener("keydown", e => { if (e.key === "Enter"){ const first = items.find(i=>i.style.display!=="none"); if (first) location.href = first.getAttribute("href"); } });
+  }
+
+  global.Ludic = { highlight, highlightAll, installCards, flashTarget, installSearch, SYMBOLS: S };
 })(window);

tools/docgen/assets/site.css

@@ -192,3 +192,18 @@
 
   .reveal{opacity:0;transform:translateY(16px);transition:opacity .6s ease, transform .6s ease}
   .reveal.in{opacity:1;transform:none}
+
+  /* hover-card + named-arg token (shared with the reference) */
+  .t-arg{color:var(--amber)}
+  .hovercard{position:fixed;z-index:100;max-width:340px;background:var(--panel2);border:1px solid var(--line2);
+    border-radius:12px;padding:12px 14px;box-shadow:0 20px 50px -18px rgba(0,0,0,.8);pointer-events:none}
+  .hc-top{display:flex;align-items:center;gap:9px;margin-bottom:8px}
+  .hc-name{font-family:"JetBrains Mono",monospace;color:var(--head);font-weight:700;font-size:14px}
+  .hc-sig{display:block;color:var(--c-fn);background:var(--c-bg);border:1px solid var(--line);border-radius:7px;
+    padding:6px 9px;font-size:12px;margin-bottom:8px;white-space:pre-wrap}
+  .hc-tip{color:var(--text);font-size:13.5px;line-height:1.5}
+  .hc-foot{color:var(--muted);font-size:11.5px;margin-top:9px;letter-spacing:.3px}
+  .kind-badge{font-size:11px;font-weight:600;letter-spacing:1px;text-transform:uppercase;padding:3px 7px;
+    border-radius:6px;border:1px solid var(--line2);color:var(--muted);background:var(--panel)}
+  .kind-keyword{color:var(--c-key)}.kind-type{color:var(--c-type)}.kind-phase{color:var(--blue)}
+  .kind-method,.kind-builtin{color:var(--c-fn)}.kind-annotation{color:var(--c-annot)}.kind-namespace{color:var(--amber)}