ui exporting and docgen testing

soleprint/common/slice/cli/__init__.py

@@ -10,6 +10,7 @@ The command line — every command slices have, and nothing else.
     slice      write every slice a run file lists (only what is stale)
     check      the same, writing nothing: exit 1 if anything is stale
     plexus     build one self-contained page from a plexus (make dist)
+    reference  the UI reference page of spr's /docs, generated from common/ui/src
     selftest   this package's own suite
 
 Library modules beside this package hold no command-line code; selftest asserts
@@ -25,6 +26,7 @@ COMMANDS = {
     "slice": ("slice", "write every slice a run file lists"),
     "check": ("slice", "the same, writing nothing — exit 1 if stale"),
     "plexus": ("plexus", "build a plexus: one self-contained page"),
+    "reference": ("reference", "the UI reference page of spr's docs, from common/ui/src"),
     "selftest": ("selftest", "this package's own suite"),
 }
 

soleprint/common/slice/cli/reference.py

@@ -0,0 +1,63 @@
+"""
+    python3 -m common.slice reference              the ui-reference page of spr's /docs, from common/ui/src
+    python3 -m common.slice reference --check      write nothing; exit 1 if stale, edited or unreconciled
+    python3 -m common.slice reference --spots      every spot a note can go, one per line
+    python3 -m common.slice reference --scaffold   an empty stub for every spot without a note
+    python3 -m common.slice reference --force      overwrite a generated file that was edited by hand
+
+The page is generated; the notes in common/ui/notes are not. See reference.py for
+why the two are kept apart, and for the measure each build ends with. To read it,
+`make docs` — the one command that launches spr's docs site.
+"""
+
+import argparse
+
+from .. import reference as docs
+from .common import PROG, Abort
+
+
+def main(argv, command=None) -> int:
+    p = argparse.ArgumentParser(prog=f"{PROG} reference")
+    p.add_argument("--check", action="store_true", help="Write nothing; exit 1 if anything is off.")
+    p.add_argument("--spots", action="store_true", help="List every spot a note can go.")
+    p.add_argument("--scaffold", action="store_true", help="Write a stub note for every empty spot.")
+    p.add_argument("--force", action="store_true", help="Overwrite a hand-edited generated file.")
+    args = p.parse_args(argv)
+
+    rel = docs.SITE.relative_to(docs.graph.COMMON.parent.parent)
+    notes_rel = docs.NOTES.relative_to(docs.graph.COMMON.parent.parent)
+
+    if args.spots or args.scaffold:
+        inv = docs.inventory()
+        if args.spots:
+            have = docs.load_notes()
+            for spot in docs.spots(inv):
+                mark = "written" if have.get(spot) else "stub" if spot in have else "-"
+                print(f"{spot:<22} {mark:<8} {notes_rel}/{spot}.md")
+        if args.scaffold:
+            made = docs.scaffold(inv)
+            print(f"{len(made)} stub(s) written" + (f": {', '.join(made)}" if made else ""))
+        return 0
+
+    res = docs.build(write=not args.check, force=args.force)
+    for name in res.edited:
+        print(f"  EDITED  {rel}/{name} — changed by hand since the last build"
+              + ("; overwritten (--force)" if args.force and not args.check else "; left alone"))
+    for name in (res.written if not args.check else res.stale):
+        print(f"  {'wrote ' if not args.check else 'STALE '}  {rel}/{name}")
+    for name in res.unchanged:
+        print(f"  ok      {rel}/{name}")
+    for name in res.removed:
+        print(f"  {'removed' if not args.check else 'GONE   '} {rel}/{name} — no longer generated")
+    print()
+    for ok, msg in res.reconciled:
+        print(f"  {'ok  ' if ok else 'FAIL'}  {msg}")
+
+    if res.edited and not args.force:
+        raise Abort(f"{len(res.edited)} generated file(s) edited by hand — move the text into "
+                    f"{notes_rel}/, or rerun with --force to discard it")
+    if args.check and not res.ok:
+        raise Abort(f"the ui reference is not current — run: make reference (in common/ui)")
+    if not all(ok for ok, _ in res.reconciled):
+        raise Abort("the reference does not reconcile with what was read")
+    return 0

soleprint/common/slice/reference.py

@@ -0,0 +1,454 @@
+"""
+The UI framework's reference, generated from its source into spr's docs site.
+
+    python3 -m common.slice reference        (from soleprint/; or make reference in common/ui)
+    make docs                                 serves it, with the rest of spr's docs
+
+It is a page of the `/docs` minisite (`docs/data/en/ui-reference.md`), because in
+soleprint `make docs` always means one thing: launch that site. A component does
+not grow a second documentation tree of its own.
+
+The same bargain docgen makes, done here without docgen — docgen is a copy-out
+tool with its own release cycle, and a library's reference should not wait on it:
+
+**The source is read, never described.** Every prop, model, emit, slot, file,
+package and token in the reference comes from graph.py and surface.py reading
+common/ui/src. A prop that is removed leaves the reference on the next build.
+
+**One format in the middle.** `inventory.json` is the only thing extraction
+produces; the reference is rendered from it and nothing else. It has docgen's
+three keys (`meta`, `nodes`, `edges`), stable ids, a closed `kind` vocabulary per
+node, and no visual information at all — so the web view that comes later, or
+docgen itself, reads the same file instead of re-reading the source.
+
+**Both ends are measured.** The larder says what came in — files seen, read, and
+failed **by name**; the book says what came out, and is reconciled against it.
+"33 files in, 34 exports documented, nothing lost" is a fact. A clean reference
+over an incomplete read is a lie by omission.
+
+**Generated base, hand-written notes.** Prose only a person can write — why a
+thing exists, what replaced what, who actually uses it — lives in
+`common/ui/notes/<spot>.md`, beside the library, and is placed above its spot on every build. A note whose
+spot is gone is reported and fails the check; it is never dropped.
+
+**A rebuild replaces exactly what the last one wrote.** `docs/.generated.json`
+records every generated file and its hash. A generated file edited by hand is
+refused, not overwritten, until `--force` — the same rule a slice's dest keeps.
+"""
+
+import hashlib
+import json
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from ..theme import bake
+from . import graph, surface, tokens
+
+SITE = graph.COMMON.parent.parent / "docs"          # spr's /docs minisite
+PAGE = "data/en/ui-reference.md"                      # its id in topics.json: ui-reference
+INVENTORY = "data/ui-inventory.json"
+MANIFEST = "data/.ui-reference.generated.json"
+NOTES = graph.COMMON / "ui" / "notes"
+SCHEMA_VERSION = "1"
+
+# The groups the library is laid out in, and what a file in each one is. A file
+# at the top of src/ is the library's own plumbing: barrel and stylesheets.
+KINDS = {
+    "components": "component",
+    "renderers": "renderer",
+    "datasources": "datasource",
+    "composables": "composable",
+    "plugins": "plugin",
+}
+ORDER = list(KINDS) + [""]
+
+STUB = "<!-- note: {spot} — write below this line, or replace it; a stub renders nothing -->\n"
+SPOTS_FIXED = ("_intro", "larder", "contents", "types", "tokens", "book", "_end")
+
+
+# ── extraction → inventory ────────────────────────────────────────────────────
+
+def _group(rel: str) -> str:
+    return rel.split("/", 1)[0] if "/" in rel else ""
+
+
+def _kind(rel: str) -> str:
+    if "/" not in rel:
+        return "stylesheet" if rel.endswith(".css") else "barrel"
+    return KINDS.get(_group(rel), "module")
+
+
+def _bindings(nodes: dict) -> dict[str, list[str]]:
+    """Library file -> the plain parts derived from it, read from each part's header.
+
+    A part says where it came from in its own header ("Derived from
+    common/ui/src/components/Panel.vue"), so the link is kept by the part,
+    not by a table here that would go stale.
+    """
+    by_base = {}
+    for rel in nodes:
+        by_base.setdefault(rel.rsplit("/", 1)[-1], []).append(rel)
+    out: dict[str, set] = {}
+    for name in bake.load_parts():
+        text = ""
+        for ext in ("css", "js"):
+            p = bake.PARTS / f"{name}.{ext}"
+            if p.exists():
+                t = p.read_text()
+                text += t[: t.find("*/")] if "*/" in t else ""
+        found = set(re.findall(r"common/ui/src/([\w./-]+\.(?:vue|ts|css))", text))
+        m = re.search(r"Derived from ([^\n]*(?:\n \*[^\n]*){0,2})", text)
+        if m:
+            for base in re.findall(r"\b([A-Za-z]\w*\.(?:vue|ts|css))\b", m.group(1)):
+                if len(by_base.get(base, [])) == 1:
+                    found.add(by_base[base][0])
+        for rel in found:
+            if rel in nodes:
+                out.setdefault(rel, set()).add(name)
+    return {k: sorted(v) for k, v in out.items()}
+
+
+def inventory(src: Path = graph.SRC) -> dict:
+    """The one document everything else is rendered from."""
+    nodes = graph.load(src)
+    exports = graph.barrel(src, nodes)
+    surfaces = surface.load(src)
+    bindings = _bindings(nodes)
+    library = tokens.source(None)
+    theme = tokens.source("soleprint")
+
+    seen = sorted(p.relative_to(src).as_posix() for p in src.rglob("*")
+                  if p.is_file() and not graph.SKIP & set(p.relative_to(src).parts))
+    failed = [{"name": rel, "error": f"no reader for {Path(rel).suffix or 'a file with no suffix'}"}
+              for rel in seen if rel not in nodes]
+    failed += [{"name": s.file, "error": s.error} for s in surfaces.values() if s.error]
+
+    out_nodes, edges = [], []
+    for rel, n in sorted(nodes.items()):
+        s = surfaces.get(rel)
+        attrs = {"path": rel, "bytes": n.size, "group": _group(rel)}
+        if s and s.summary:
+            attrs["summary"] = s.summary
+        if s and rel.endswith(".vue"):
+            attrs["props"] = [vars(p) for p in s.props]
+            attrs["models"] = [vars(m) for m in s.models]
+            attrs["emits"] = [vars(e) for e in s.emits]
+            attrs["slots"] = list(s.slots)
+        if s and s.declarations:
+            attrs["declarations"] = [{"kind": k, "name": nm, "doc": d} for k, nm, d in s.declarations]
+        if s and s.error:
+            attrs["error"] = s.error
+        out_nodes.append({"id": f"file:{rel}", "kind": _kind(rel), "label": rel.rsplit("/", 1)[-1],
+                          "parent": None, "attrs": attrs})
+        for target in sorted(n.imports):
+            edges.append({"source": f"file:{rel}", "target": f"file:{target}", "kind": "imports", "attrs": {}})
+        for pkg in sorted({graph.package_of(p) for p in n.packages}):
+            edges.append({"source": f"file:{rel}", "target": f"package:{pkg}", "kind": "requires", "attrs": {}})
+        for tok in sorted(n.tokens):
+            edges.append({"source": f"file:{rel}", "target": f"token:{tok}", "kind": "reads", "attrs": {}})
+
+    for e in exports:
+        closure, _ = graph.select([e.name], [], exports, nodes)
+        out_nodes.append({"id": f"export:{e.name}", "kind": "type" if e.is_type else "export",
+                          "label": e.name, "parent": f"file:{e.file}",
+                          "attrs": {"file": e.file, "local": e.local,
+                                    "closure": sorted(closure),
+                                    "packages": graph.dependencies(closure, nodes),
+                                    "tokens": sorted(graph.tokens_read(closure, nodes)),
+                                    "bytes": sum(nodes[f].size for f in closure)}})
+
+    for pkg, version in sorted(graph.dependencies(set(nodes), nodes).items()):
+        out_nodes.append({"id": f"package:{pkg}", "kind": "package", "label": pkg,
+                          "parent": None, "attrs": {"version": version}})
+
+    names = set(library.table) | set().union(*(n.tokens for n in nodes.values()))
+    for name in sorted(names):
+        lib, thm = tokens.resolved(library, name), tokens.resolved(theme, name)
+        out_nodes.append({"id": f"token:{name}", "kind": "token", "label": name, "parent": None,
+                          "attrs": {"library": lib, "theme": thm}})
+
+    for rel, parts in sorted(bindings.items()):
+        for part in parts:
+            if not any(n["id"] == f"part:{part}" for n in out_nodes):
+                out_nodes.append({"id": f"part:{part}", "kind": "part", "label": part, "parent": None,
+                                  "attrs": {"path": f"common/theme/parts/{part}"}})
+            edges.append({"source": f"part:{part}", "target": f"file:{rel}", "kind": "binds", "attrs": {}})
+
+    larder = {"kind": "vue-library", "identity": "common/ui/src", "unit": "file",
+              "seen": len(seen), "failed": failed,
+              "extra": {"exports": sum(1 for e in exports if not e.is_type),
+                        "types": sum(1 for e in exports if e.is_type)}}
+    return {"meta": {"source": "common/ui/src", "schema_version": SCHEMA_VERSION,
+                     "generator": "common.slice docs", "larder": larder},
+            "nodes": out_nodes, "edges": edges}
+
+
+# ── the book measure: what came out, reconciled against what came in ──────────
+
+def reconcile(inv: dict, notes: dict[str, str]) -> list[tuple[bool, str]]:
+    larder = inv["meta"]["larder"]
+    read = larder["seen"] - len([f for f in larder["failed"] if f["error"].startswith("no reader")])
+    files = [n for n in inv["nodes"] if n["id"].startswith("file:")]
+    values = [n for n in inv["nodes"] if n["kind"] == "export"]
+    types = [n for n in inv["nodes"] if n["kind"] == "type"]
+    vue = [n for n in files if n["attrs"]["path"].endswith(".vue")]
+    unparsed = [n["attrs"]["path"] for n in vue if "error" in n["attrs"]]
+    orphans = sorted(set(notes) - set(spots(inv)))
+    return [
+        (read == len(files), f"{read} file(s) read produced {len(files)} file node(s)"),
+        (len(values) == larder["extra"]["exports"] and len(types) == larder["extra"]["types"],
+         f"{len(values)} export(s) and {len(types)} type(s) in the barrel, each with a node"),
+        (not unparsed, f"{len(vue) - len(unparsed)} of {len(vue)} component(s) have their surface read"
+         + (f" — not: {', '.join(unparsed)}" if unparsed else "")),
+        (not orphans, "every note lands on a spot" if not orphans
+         else f"{len(orphans)} note(s) with no spot: {', '.join(orphans)}"),
+    ]
+
+
+# ── notes ─────────────────────────────────────────────────────────────────────
+
+def spots(inv: dict) -> list[str]:
+    """Every place a note can go. Exports by name; the fixed sections by role."""
+    named = [n["label"] for n in inv["nodes"] if n["kind"] == "export"]
+    return list(SPOTS_FIXED[:3]) + named + list(SPOTS_FIXED[3:])
+
+
+def load_notes(notes_dir: Path = NOTES) -> dict[str, str]:
+    """spot -> the note's text. A stub (only the scaffold comment) counts as empty."""
+    out = {}
+    if notes_dir.is_dir():
+        for p in sorted(notes_dir.glob("*.md")):
+            body = re.sub(r"<!--.*?-->", "", p.read_text(), flags=re.S).strip()
+            out[p.stem] = body
+    return out
+
+
+def scaffold(inv: dict, notes_dir: Path = NOTES) -> list[str]:
+    """Write an empty stub for every spot that has no note. Never overwrites."""
+    notes_dir.mkdir(parents=True, exist_ok=True)
+    made = []
+    for spot in spots(inv):
+        p = notes_dir / f"{spot}.md"
+        if not p.exists():
+            p.write_text(STUB.format(spot=spot))
+            made.append(spot)
+    return made
+
+
+# ── the reference ─────────────────────────────────────────────────────────────
+
+def _cell(text) -> str:
+    return str(text).replace("|", "\\|").replace("\n", " ") if text not in (None, "") else "—"
+
+
+def _code(text) -> str:
+    return f"`{_cell(text)}`" if text not in (None, "") else "—"
+
+
+def render(inv: dict, notes: dict[str, str]) -> str:
+    by_id = {n["id"]: n for n in inv["nodes"]}
+    out_edges: dict[str, list] = {}
+    for e in inv["edges"]:
+        out_edges.setdefault(e["source"], []).append(e)
+    binds: dict[str, list] = {}
+    for e in inv["edges"]:
+        if e["kind"] == "binds":
+            binds.setdefault(e["target"], []).append(by_id[e["source"]]["label"])
+    larder = inv["meta"]["larder"]
+    read = larder["seen"] - len([f for f in larder["failed"] if f["error"].startswith("no reader")])
+
+    L = []
+
+    def note(spot):
+        if notes.get(spot):
+            L.extend([notes[spot], ""])
+
+    L += ["# common/ui — reference", "",
+          "> Generated from `common/ui/src` by `make reference` in common/ui "
+          "(`python3 -m common.slice reference`).",
+          "> Do not edit this page: the next build replaces it. Prose goes in "
+          "`soleprint/common/ui/notes/<spot>.md`,",
+          "> and `make reference-spots` lists every spot.", ""]
+    note("_intro")
+
+    L += ["## What came in", ""]
+    note("larder")
+    L += [f"`{larder['identity']}` — **{larder['seen']} file(s) seen, {read} read, "
+          f"{len(larder['failed'])} failed**; {larder['extra']['exports']} exports and "
+          f"{larder['extra']['types']} types in the barrel.", ""]
+    if larder["failed"]:
+        L += ["| file | why it is not (fully) read |", "| --- | --- |"]
+        L += [f"| `{f['name']}` | {_cell(f['error'])} |" for f in larder["failed"]]
+        L.append("")
+
+    exports = [n for n in inv["nodes"] if n["kind"] == "export"]
+    L += ["## Contents", ""]
+    note("contents")
+    L += ["What each export costs a consumer that takes it: the files it pulls in, the packages it",
+          "brings, and whether a plain-HTML part exists for it (`common/theme/parts`).", "",
+          "| export | kind | file | pulls in | packages | size | plain part |",
+          "| --- | --- | --- | --- | --- | --- | --- |"]
+    for n in exports:
+        a = n["attrs"]
+        f = by_id[f"file:{a['file']}"]
+        pulls = ", ".join(p.rsplit("/", 1)[-1] for p in a["closure"] if p != a["file"]) or "—"
+        L.append(f"| [`{n['label']}`](#{n['label'].lower()}) | {f['kind']} | `{a['file']}` | {pulls} | "
+                 f"{', '.join(a['packages']) or '—'} | {a['bytes'] / 1024:.1f} KB | "
+                 f"{', '.join(binds.get(f['id'], [])) or '—'} |")
+    L.append("")
+
+    for group in ORDER:
+        members = [n for n in exports if _group(n["attrs"]["file"]) == group]
+        if not members:
+            continue
+        L += [f"## {group.capitalize() if group else 'Library'}", ""]
+        for n in members:
+            a = n["attrs"]
+            f = by_id[f"file:{a['file']}"]
+            fa = f["attrs"]
+            L += [f"### {n['label']}", ""]
+            if fa.get("summary"):
+                L += [fa["summary"], ""]
+            note(n["label"])
+            meta = [f"`{a['file']}` · {a['bytes'] / 1024:.1f} KB with its closure",
+                    f"packages: {', '.join(f'`{p}` {v}' for p, v in a['packages'].items()) or 'none'}"]
+            if binds.get(f["id"]):
+                meta.append("plain part: " + ", ".join(f"`{p}`" for p in binds[f["id"]]))
+            L += [" · ".join(meta), ""]
+            if fa.get("error"):
+                L += [f"**Not fully read:** {fa['error']}", ""]
+            if fa.get("props"):
+                L += ["| prop | type | required | default | |", "| --- | --- | --- | --- | --- |"]
+                L += [f"| `{p['name']}` | {_code(p['type'])} | {'yes' if p['required'] else 'no'} | "
+                      f"{_code(p['default'])} | {_cell(p['doc'])} |" for p in fa["props"]]
+                L.append("")
+            if fa.get("models"):
+                L += ["| v-model | type | default |", "| --- | --- | --- |"]
+                L += [f"| `v-model:{m['name']}` | {_code(m['type'])} | {_code(m['default'])} |"
+                      for m in fa["models"]]
+                L.append("")
+            if fa.get("emits"):
+                L += ["| emits | payload | |", "| --- | --- | --- |"]
+                L += [f"| `{e['name']}` | {_code(e['type'])} | {_cell(e['doc'])} |" for e in fa["emits"]]
+                L.append("")
+            if fa.get("slots"):
+                L += ["slots: " + ", ".join(f"`#{s}`" for s in fa["slots"]), ""]
+            # A .ts export's own doc comment (a class or function's) is its
+            # description; an SFC's is the file summary, already printed above.
+            for d in (d for d in fa.get("declarations", []) if d["name"] == a["local"]):
+                if d["doc"] and d["doc"] != fa.get("summary"):
+                    L += [d["doc"], ""]
+            if a["tokens"]:
+                L += ["reads: " + " ".join(f"`{t}`" for t in a["tokens"]), ""]
+
+    types = [n for n in inv["nodes"] if n["kind"] == "type"]
+    L += ["## Types", ""]
+    note("types")
+    L += ["Types ride with the file that declares them: taking the export takes its types.", "",
+          "| type | declared in | |", "| --- | --- | --- |"]
+    for n in types:
+        f = by_id[f"file:{n['attrs']['file']}"]
+        decl = next((d for d in f["attrs"].get("declarations", []) if d["name"] == n["attrs"]["local"]), None)
+        L.append(f"| `{n['label']}` | `{n['attrs']['file']}` | {_cell(decl['kind'] if decl else '')} |")
+    L.append("")
+
+    toks = [n for n in inv["nodes"] if n["kind"] == "token"]
+    readers: dict[str, list] = {}
+    for e in inv["edges"]:
+        if e["kind"] == "reads":
+            readers.setdefault(e["target"], []).append(by_id[e["source"]]["label"])
+    L += ["## Tokens", ""]
+    note("tokens")
+    L += ["Every custom property the library defines or reads. `library` is `src/tokens.css`, what",
+          "Vue consumers render today; `theme` is the contract plain pages use",
+          "(`common/theme/tokens.css` + `themes/soleprint.css`). A row where the two differ is a",
+          "visible change for a consumer that switches.", "",
+          "| token | library | theme | read by |", "| --- | --- | --- | --- |"]
+    for n in toks:
+        a = n["attrs"]
+        flag = " ⚠" if a["library"] and a["theme"] and a["library"] != a["theme"] else ""
+        who = ", ".join(sorted(set(readers.get(n["id"], [])))) or "*nobody*"
+        L.append(f"| `{n['label']}`{flag} | {_code(a['library'])} | {_code(a['theme'])} | {who} |")
+    L.append("")
+
+    L += ["## What came out", ""]
+    note("book")
+    kinds: dict[str, int] = {}
+    for n in inv["nodes"]:
+        kinds[n["kind"]] = kinds.get(n["kind"], 0) + 1
+    ekinds: dict[str, int] = {}
+    for e in inv["edges"]:
+        ekinds[e["kind"]] = ekinds.get(e["kind"], 0) + 1
+    L += ["nodes: " + " · ".join(f"{v} {k}" for k, v in sorted(kinds.items())),
+          "", "edges: " + " · ".join(f"{v} {k}" for k, v in sorted(ekinds.items())), ""]
+    L += [f"- {'ok  ' if ok else '**FAIL**'} {msg}" for ok, msg in reconcile(inv, notes)]
+    L.append("")
+    note("_end")
+    return "\n".join(L).rstrip() + "\n"
+
+
+# ── writing, and checking without writing ─────────────────────────────────────
+
+@dataclass
+class Result:
+    written: list = field(default_factory=list)
+    unchanged: list = field(default_factory=list)
+    stale: list = field(default_factory=list)
+    edited: list = field(default_factory=list)
+    removed: list = field(default_factory=list)
+    reconciled: list = field(default_factory=list)
+
+    @property
+    def ok(self) -> bool:
+        return not self.stale and not self.edited and all(ok for ok, _ in self.reconciled)
+
+
+def _sha(text: str) -> str:
+    return hashlib.sha256(text.encode()).hexdigest()
+
+
+def outputs(inv: dict, notes: dict[str, str]) -> dict[str, str]:
+    return {INVENTORY: json.dumps(inv, indent=2, sort_keys=True) + "\n",
+            PAGE: render(inv, notes)}
+
+
+def build(docs: Path = SITE, *, write: bool, force: bool = False, src: Path = graph.SRC,
+          notes_dir: Path = NOTES) -> Result:
+    inv = inventory(src)
+    notes = load_notes(notes_dir)
+    files = outputs(inv, notes)
+    res = Result(reconciled=reconcile(inv, notes))
+    manifest = docs / MANIFEST
+    previous = json.loads(manifest.read_text()).get("files", {}) if manifest.exists() else {}
+
+    for name, text in files.items():
+        path = docs / name
+        on_disk = path.read_text() if path.exists() else None
+        if on_disk is not None and name in previous and _sha(on_disk) != previous[name]:
+            # Somebody edited a generated file. That text would be lost on the
+            # next build, so it is named and refused rather than overwritten.
+            res.edited.append(name)
+            if not force:
+                continue
+        if on_disk == text:
+            res.unchanged.append(name)
+            continue
+        res.stale.append(name)
+        if write:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(text)
+            res.written.append(name)
+
+    gone = [n for n in previous if n not in files and (docs / n).exists()]
+    res.removed = gone
+    if write and (not res.edited or force):
+        for n in gone:
+            (docs / n).unlink()
+        manifest.parent.mkdir(parents=True, exist_ok=True)
+        manifest.write_text(json.dumps({"generator": "common.slice reference",
+                                        "files": {n: _sha(t) for n, t in files.items()}},
+                                       indent=2, sort_keys=True) + "\n")
+        if res.written:
+            res.stale = []
+    return res

soleprint/common/slice/selftest.py

@@ -11,15 +11,19 @@ regression are marked (design), and they are the ones to keep if anything is cut
     a vendored slice fails on any spr word              no --force past the scrub
     a hand edit in dest is refused, not overwritten     drift is reported both ways
     a vendored slice needs an explicit notice           the tool never picks licensing
+    a surface that does not parse is a failure by name  the reference never thins silently
+    a generated doc edited by hand is refused           the notes, not the output, hold prose
 """
 
 import ast
+import json
 import re
 import sys
 import tempfile
 from pathlib import Path
 
-from . import css, graph, manifest, names, plexus, runfile, scan, slices, tokens
+from . import css, graph, manifest, names, plexus, runfile, scan, slices, surface, tokens
+from . import reference as docs
 
 HERE = Path(__file__).resolve().parent
 PASS, FAIL = [], []
@@ -257,6 +261,67 @@ def main() -> int:
     else:
         print("  skip meetus snapshot not on this machine")
 
+    section("the surface (what the ui reference is generated from)")
+    surf = surface.load()
+    panel = surf["components/Panel.vue"]
+    check("Panel's props, in order", [m.name for m in panel.props] == ["title", "status", "maximizable"],
+          [m.name for m in panel.props])
+    check("... with required-ness and withDefaults defaults",
+          panel.props[0].required and not panel.props[1].required and panel.props[2].default == "true")
+    check("... a doc comment lands on its prop", panel.props[1].doc.startswith("Omit to show"))
+    check("a defineModel is a v-model with its default",
+          [(m.name, m.type, m.default) for m in panel.models] == [("maximized", "boolean", "false")])
+    check("named and default slots are found", panel.slots == ["actions", "default", "overlay"], panel.slots)
+    check("quoted and colon-named emits parse (VideoPlayer)",
+          {"update:currentTime", "ended"} <= {e.name for e in surf["components/VideoPlayer.vue"].emits})
+    check("a file doc comment is its summary, a prop's is not",
+          surf["components/VideoPlayer.vue"].summary.startswith("Agnostic") and not panel.summary)
+    check("a .ts file's exports are declarations",
+          ("abstract class", "DataSource") in [(k, n) for k, n, _ in surf["datasources/DataSource.ts"].declarations])
+    broken = [s.file for s in surf.values() if s.error]
+    check("(design) every component in the library parses", not broken, broken)
+    with tempfile.TemporaryDirectory() as t:
+        bad = Path(t) / "Broken.vue"
+        bad.write_text("<script setup lang=\"ts\">\ndefineProps<{ title: string\n</script>\n")
+        check("(design) a surface that does not parse is recorded by name, not dropped",
+              surface.read(bad, "Broken.vue").error is not None)
+
+    section("the ui reference")
+    inv = docs.inventory()
+    check("the inventory is deterministic: two builds, one document", inv == docs.inventory())
+    visual = {"color", "colour", "fill", "stroke", "shape", "x", "y", "width", "height", "position"}
+    keys = {k for n in inv["nodes"] for k in n["attrs"]}
+    check("no visual keys in the inventory — style belongs to whoever renders it",
+          not keys & visual, sorted(keys & visual))
+    ids = [n["id"] for n in inv["nodes"]]
+    check("node ids are unique", len(ids) == len(set(ids)))
+    check("every edge points at a node", all(e["source"] in ids and e["target"] in ids for e in inv["edges"]))
+    check("the reference reconciles with what was read, on spr's own tree",
+          all(ok for ok, _ in docs.reconcile(inv, {})), docs.reconcile(inv, {}))
+    check("a note for a spot that does not exist fails the reconcile",
+          not all(ok for ok, _ in docs.reconcile(inv, {"NoSuchExport": "text"})))
+    check("Panel's plain parts are found from the parts' own headers",
+          {e["source"] for e in inv["edges"] if e["kind"] == "binds" and e["target"] == "file:components/Panel.vue"}
+          == {"part:panel", "part:maximize"})
+    with tempfile.TemporaryDirectory() as t:
+        d = Path(t)
+        page = d / docs.PAGE
+        first = docs.build(d, write=True)
+        check("a first build writes the page and the inventory into the docs site",
+              set(first.written) == {docs.PAGE, docs.INVENTORY} and (d / docs.MANIFEST).exists())
+        check("a second build changes nothing", not docs.build(d, write=True).written)
+        check("--check on a current build passes", docs.build(d, write=False).ok)
+        page.write_text(page.read_text() + "\nhand edit\n")
+        edited = docs.build(d, write=True)
+        check("(design) a generated doc edited by hand is refused, not overwritten",
+              edited.edited == [docs.PAGE] and "hand edit" in page.read_text())
+        forced = docs.build(d, write=True, force=True)
+        check("... and --force discards it", "hand edit" not in page.read_text()
+              and docs.PAGE in forced.written)
+    check("the page is listed in the docs site's sidebar",
+          any(t.get("id") == "ui-reference" for t in json.loads(
+              (docs.SITE / "data" / "topics.json").read_text())))
+
     section("the split")
     offenders = []
     for path in HERE.rglob("*.py"):

soleprint/common/slice/surface.py

@@ -0,0 +1,219 @@
+"""
+What each file of common/ui/src offers a consumer: props, models, emits, slots,
+and the declarations a .ts file exports.
+
+graph.py answers "what does this file need". This answers "what does it give",
+and between them they are everything the reference in common/ui/docs says —
+read out of the source, so the reference cannot describe a prop that is gone.
+
+Same method as graph.py and for the same reason: patterns, not a TypeScript
+parser. The library writes its surface one way — `defineProps<{…}>()`, optionally
+inside `withDefaults(…, {…})`, `defineEmits<{…}>()`, `defineModel<T>('name', …)`,
+`<slot name="…">` — and the selftest pins what each of those must yield. A file
+whose macros are there but do not parse is **recorded as a failure, by name**,
+never dropped: a component with its props silently missing reads as a component
+with no props, and that is the lie a reference must not tell.
+"""
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from . import graph
+
+DOC = re.compile(r"/\*\*(.*?)\*/", re.S)
+SLOT = re.compile(r"<slot\b([^>]*)/?>")
+SLOT_NAME = re.compile(r"""\bname\s*=\s*["']([^"']+)["']""")
+MODEL = re.compile(
+    r"defineModel\s*<\s*(?P<type>[^>]+?)\s*>\s*\(\s*(?:['\"](?P<name>[\w:-]+)['\"])?"
+    r"\s*(?:,\s*\{(?P<opts>[^}]*)\})?\s*\)")
+EXPORT_DECL = re.compile(
+    r"(?:(?P<doc>/\*\*(?:(?!\*/).)*\*/)\s*)?"
+    r"^export\s+(?P<abstract>abstract\s+)?(?P<kind>class|function|interface|type|const)\s+"
+    r"(?P<name>[A-Za-z_]\w*)", re.S | re.M)
+
+
+@dataclass
+class Member:
+    """One prop, emit or model."""
+
+    name: str
+    type: str
+    required: bool = True
+    default: str | None = None
+    doc: str = ""
+
+
+@dataclass
+class Surface:
+    """What one file offers."""
+
+    file: str
+    props: list = field(default_factory=list)
+    models: list = field(default_factory=list)
+    emits: list = field(default_factory=list)
+    slots: list = field(default_factory=list)
+    declarations: list = field(default_factory=list)   # (kind, name, doc)
+    summary: str = ""                                  # first doc paragraph, if any
+    error: str | None = None
+
+
+def _doc_text(raw: str) -> str:
+    lines = [ln.strip().lstrip("*").strip() for ln in raw.strip("/*").splitlines()]
+    return " ".join(ln for ln in lines if ln).strip()
+
+
+def _balanced(text: str, start: int, open_ch="{", close_ch="}") -> int:
+    """Index just past the bracket that closes the one at `start`, or -1."""
+    depth = 0
+    for i in range(start, len(text)):
+        c = text[i]
+        if c == open_ch:
+            depth += 1
+        elif c == close_ch:
+            depth -= 1
+            if depth == 0:
+                return i + 1
+    return -1
+
+
+def _split_top(text: str, seps=",\n;") -> list[str]:
+    """Split on separators that are not nested in brackets or quotes."""
+    out, depth, quote, cur = [], 0, None, []
+    for c in text:
+        if quote:
+            cur.append(c)
+            if c == quote:
+                quote = None
+            continue
+        if c in "'\"`":
+            quote = c
+        elif c in "([{<":
+            depth += 1
+        elif c in ")]}>":
+            depth -= 1
+        if c in seps and depth == 0:
+            out.append("".join(cur))
+            cur = []
+        else:
+            cur.append(c)
+    out.append("".join(cur))
+    return out
+
+
+def _members(body: str) -> list[Member]:
+    """The members of a type literal: `/** doc */ name?: type`, one per entry."""
+    out, pending_doc = [], ""
+    # Doc comments are pulled out first and attached to the member after them.
+    pieces = re.split(r"(/\*\*.*?\*/)", body, flags=re.S)
+    for piece in pieces:
+        if piece.startswith("/**"):
+            pending_doc = _doc_text(piece)
+            continue
+        for chunk in _split_top(piece):
+            chunk = re.sub(r"//[^\n]*", "", chunk).strip()
+            if not chunk:
+                continue
+            m = re.match(r"""^['"]?([\w:-]+)['"]?\s*(\?)?\s*:\s*(.+)$""", chunk, re.S)
+            if not m:
+                continue
+            out.append(Member(name=m.group(1), type=" ".join(m.group(3).split()),
+                              required=not m.group(2), doc=pending_doc))
+            pending_doc = ""
+    return out
+
+
+def _defaults(text: str) -> dict[str, str]:
+    """`{ a: 1, b: () => [] }` → {"a": "1", "b": "() => []"}, values as written."""
+    out = {}
+    for chunk in _split_top(text.strip()[1:-1], seps=",\n"):
+        chunk = chunk.strip()
+        m = re.match(r"^['\"]?([\w-]+)['\"]?\s*:\s*(.+)$", chunk, re.S)
+        if m:
+            out[m.group(1)] = " ".join(m.group(2).split())
+    return out
+
+
+def _macro_body(script: str, macro: str) -> tuple[str | None, int]:
+    """The `{…}` type literal of `macro<{…}>()`, and where it ends."""
+    m = re.search(macro + r"\s*<\s*\{", script)
+    if not m:
+        return None, -1
+    start = m.end() - 1
+    end = _balanced(script, start)
+    if end < 0:
+        return None, -1
+    return script[start + 1:end - 1], end
+
+
+def read(path: Path, rel: str) -> Surface:
+    text = path.read_text()
+    s = Surface(file=rel)
+    script, _ = graph.code_of(path, text)
+
+    for m in EXPORT_DECL.finditer(script):
+        kind = ("abstract class" if m.group("abstract") else m.group("kind"))
+        s.declarations.append((kind, m.group("name"), _doc_text(m.group("doc") or "")))
+
+    # A file's summary is a doc comment with nothing but imports before it. The
+    # first doc comment is not enough: in Panel.vue it belongs to a prop.
+    lead = DOC.search(script)
+    if lead:
+        before = re.sub(r"^\s*import\b[^\n]*$", "", script[:lead.start()], flags=re.M)
+        if not before.strip():
+            first = _doc_text(lead.group(0))
+            s.summary = first.split(". ")[0].rstrip(".") + "."
+
+    if path.suffix != ".vue":
+        return s
+
+    if "defineProps" in script:
+        body, end = _macro_body(script, "defineProps")
+        if body is None:
+            s.error = "defineProps is present but its type literal did not parse"
+        else:
+            s.props = _members(body)
+            # withDefaults(defineProps<{…}>(), { … }) — the defaults follow `)`.
+            tail = script[end:]
+            dm = re.match(r"\s*>\s*\(\s*\)\s*,\s*\{", tail)
+            if dm and "withDefaults" in script[:end]:
+                d_start = end + dm.end() - 1
+                d_end = _balanced(script, d_start)
+                if d_end > 0:
+                    defaults = _defaults(script[d_start:d_end])
+                    for p in s.props:
+                        if p.name in defaults:
+                            p.default = defaults[p.name]
+
+    if "defineEmits" in script:
+        body, _ = _macro_body(script, "defineEmits")
+        if body is None:
+            s.error = (s.error + "; " if s.error else "") + \
+                "defineEmits is present but its type literal did not parse"
+        else:
+            s.emits = _members(body)
+
+    for m in MODEL.finditer(script):
+        opts = m.group("opts") or ""
+        dflt = re.search(r"default\s*:\s*([^,}]+)", opts)
+        s.models.append(Member(name=m.group("name") or "modelValue", type=m.group("type").strip(),
+                               required=bool(re.search(r"required\s*:\s*true", opts)),
+                               default=dflt.group(1).strip() if dflt else None))
+
+    template = re.sub(r"<script\b.*?</script>|<style\b.*?</style>", "", text, flags=re.S)
+    for m in SLOT.finditer(template):
+        name = SLOT_NAME.search(m.group(1))
+        slot = name.group(1) if name else "default"
+        if slot not in s.slots:
+            s.slots.append(slot)
+    return s
+
+
+def load(src: Path = graph.SRC) -> dict[str, Surface]:
+    """Every .vue/.ts file's surface, keyed like graph.load()."""
+    out = {}
+    for p in sorted(src.rglob("*")):
+        rel = p.relative_to(src).as_posix()
+        if p.is_file() and p.suffix in (".vue", ".ts") and not graph.SKIP & set(p.relative_to(src).parts):
+            out[rel] = read(p, rel)
+    return out

soleprint/common/ui/Makefile

@@ -0,0 +1,83 @@
+# common/ui — the Vue binding of spr's UI contract.
+#
+# Paths are derived from where this file sits. The logic lives in pnpm and in
+# common/slice, never here: every target is one line.
+#
+#   make install        node_modules, offline when the store has it
+#   make check          everything that must be green before a change here lands
+#   make docs           launch spr's docs site, open at this library's reference —
+#                       in soleprint, `make docs` always launches the /docs minisite
+#   make reference      regenerate that reference page from src/ (never hand-edited)
+#   make reference-spots   every place a hand-written note (notes/) can go
+#   make slices         what a consumer can take, and what each piece pulls in
+#
+# This folder is also copied whole into consumers by ctrl/spr.py. There, the
+# pnpm targets still work; the docs/reference/slices/parts targets need spr around them
+# and say so instead of failing with a traceback.
+
+HERE      := $(patsubst %/,%,$(dir $(abspath $(lastword $(MAKEFILE_LIST)))))
+SOLEPRINT := $(abspath $(HERE)/../..)
+PY        ?= python3
+PNPM      ?= pnpm
+SLICE     := cd $(SOLEPRINT) && $(PY) -m common.slice
+IN_SPR    := $(wildcard $(HERE)/../slice/__init__.py)
+
+# The one guard every spr-side target shares: a copy of this folder elsewhere has
+# no common/slice beside it.
+need-spr = $(if $(IN_SPR),,$(error $@ needs spr around this folder — docs, reference, slices and parts live in spr, not in a copy))
+
+.DEFAULT_GOAL := help
+.PHONY: help install typecheck test build check docs reference reference-check reference-spots reference-scaffold slices parts-check clean
+
+help:  ## List every target
+	@echo "common/ui — the Vue binding of spr's UI contract"
+	@echo
+	@grep -E '^[a-z-]+:.*?## .*$$' $(MAKEFILE_LIST) \
+	  | awk 'BEGIN{FS=":.*?## "}{printf "  \033[1m%-19s\033[0m %s\n", $$1, $$2}'
+
+install:  ## node_modules (pnpm, offline when the store already has it)
+	cd $(HERE) && $(PNPM) install --prefer-offline
+
+typecheck:  ## vue-tsc over src/
+	cd $(HERE) && $(PNPM) typecheck
+
+test:  ## vitest
+	cd $(HERE) && $(PNPM) test
+
+build:  ## dist/soleprint-ui.js + dist/style.css (the whole-library bundle; consumers take slices)
+	cd $(HERE) && $(PNPM) build
+
+check: typecheck test reference-check parts-check  ## typecheck, test, reference current, parts agree with their sources
+	@echo "common/ui: all green"
+
+docs:  ## launch spr's docs site (the /docs minisite), open at #ui-reference
+	$(need-spr)
+	@echo "the UI reference: http://localhost:$${DOCS_PORT:-8080}/#ui-reference"
+	bash $(SOLEPRINT)/../ctrl/docs.sh serve
+
+reference:  ## regenerate the ui-reference page from src/ (refuses to overwrite a hand edit; FORCE=1 to discard it)
+	$(need-spr)
+	$(SLICE) reference $(if $(FORCE),--force)
+
+reference-check:  ## the page current, no hand edits, every note on a spot — writes nothing
+	$(need-spr)
+	$(SLICE) reference --check
+
+reference-spots:  ## every spot a note (notes/) can go, and which have one
+	$(need-spr)
+	$(SLICE) reference --spots
+
+reference-scaffold:  ## an empty stub in notes/ for every spot without a note (never overwrites)
+	$(need-spr)
+	$(SLICE) reference --scaffold
+
+slices:  ## what can be sliced, and what each export or part pulls in
+	$(need-spr)
+	$(SLICE) list
+
+parts-check:  ## the plain parts in common/theme still agree with the files here they came from
+	$(need-spr)
+	cd $(SOLEPRINT) && $(PY) common/theme/bake.py --check >/dev/null && echo "parts: agree with their sources; pages current"
+
+clean:  ## remove dist/
+	rm -rf $(HERE)/dist

soleprint/common/ui/notes/FrameRenderer.md

@@ -0,0 +1,4 @@
+**Known bug:** box colours by confidence are returned as `'var(--conf-high)'` strings and
+handed to a canvas `strokeStyle`. Canvas does not resolve custom properties, so those
+boxes draw in the context's previous colour. That is why the "Tokens" table shows the
+`--conf-*` tokens as read by nobody: in effect, they are not.

soleprint/common/ui/notes/LogRenderer.md

@@ -0,0 +1,4 @@
+Virtual scroll, and the only one in any of the apps: rows outside the viewport are not
+rendered, and auto-scroll pauses while the reader scrolls up. mts's long lists and mpr's
+React side render every row instead. `rowHeight` and `autoScroll` have never been passed
+by a consumer; the defaults are what is proven.

soleprint/common/ui/notes/Panel.md

@@ -0,0 +1,12 @@
+The one component everything uses — 13 instances in mpr, 7 across mts's two apps.
+
+**Maximize came from mts.** mts's copy grew `v-model:maximized` and `maximizable` while
+spr's stood still, and it was brought upstream on 2026-09-22 — the framework spec's own
+rule ("a second application finds the holes") working as written. The reason it is the
+panel's job and not the video's is in the source: a fullscreen `<video>` paints over the
+panel's actions and overlays.
+
+**`#actions` is where panel buttons go.** mts fills it in 6 of 7 panels; mpr fills it in
+none and absolutely-positions buttons inside the body instead. The slot is the answer.
+**`#overlay` is filled by no consumer**; it stays for the interaction plugins, which have
+no consumer either.

soleprint/common/ui/notes/ParameterEditor.md

@@ -0,0 +1,5 @@
+Schema-driven: the same field list a pipeline stage declares renders its sliders. Two
+gaps, both fixed in the plain binding (`params` part) and not yet here: a field with
+`options` (an enum) renders **nothing**, because only `int`/`float` and `bool` are
+filtered for; and the `reset` event is declared but never emitted — mpr wires a handler
+to it that cannot fire.

soleprint/common/ui/notes/SSEDataSource.md

@@ -0,0 +1,10 @@
+One stream, many typed events: panels subscribe with `on(type, handler)` to the event
+types they draw, and the stream ends with a terminal `done`. `status` uses the same four
+words as a panel's dot, so wiring one to the other needs no mapping.
+
+Two things the code does not do, both learned from mpr. **It does not throttle**: at a few
+hundred events a second, a handler that writes to the DOM per event stalls — the plain
+binding's `feed` part adds `onFrame()` (one call per animation frame, newest payload) for
+exactly this, and a Vue consumer has to coalesce the same way. **Nobody unsubscribes**:
+`on()` returns an unsubscribe function and every call site in mpr drops it, which only
+works because its panels live as long as the page.

soleprint/common/ui/notes/SplitPane.md

@@ -0,0 +1,4 @@
+The real layout primitive. Every app lays itself out with nested splits — mpr three
+deep — and none uses `LayoutGrid`. `sizeMode="ratio"` is the common case (all of mts);
+`"px"` pins a sidebar (mpr). `resizable: false` has never been passed by anyone: a split
+that cannot move is a flex row.

soleprint/common/ui/notes/TimeSeriesRenderer.md

@@ -0,0 +1,3 @@
+One of the only two exports that bring a package (`uplot`, with its stylesheet), and the
+reason a chart cannot be a plain part: baking uplot into every standalone page is the
+bundle this library refuses to be. A page that needs a real chart is a served page.

soleprint/common/ui/notes/VideoPlayer.md

@@ -0,0 +1,2 @@
+mts's, and only mts uses it. It came upstream with its `#overlay` slot on 2026-09-22.
+It deliberately does no fullscreen of its own: put it in a `Panel` and maximize that.

soleprint/common/ui/notes/_end.md

@@ -0,0 +1,18 @@
+## Where it stands
+
+- **Done:** the reference is generated and checked; slices are cut per consumer with a
+  two-way drift check; mts's additions (maximize, the video overlay) are upstream.
+- **Behind:** the copies in mpr, unt and nvi date from 2026-04 and lack maximize,
+  `VideoPlayer`, `base.css` and `theme.css`. Their `.spr` stamp names a commit that no
+  longer exists. Replacing each with a slice is the next step for each.
+- **Open:** one token definition instead of two (three, counting docgen's style slots);
+  the `connecting` status the panel cannot show; `--accent`, which nvi and doocus read and
+  nothing defines; the `FrameRenderer` colour bug; `ParameterEditor`'s enum fields.
+
+## Rebuilding this
+
+`make reference` in `common/ui`. `make check` fails when this page is stale, when a
+generated file was edited by hand, or when a note no longer has its spot. Extraction reads the
+source with patterns, not a TypeScript parser; `common/slice/selftest.py` pins what the
+patterns must find, so one that stops matching fails the suite rather than thinning this
+page.

soleprint/common/ui/notes/_intro.md

@@ -0,0 +1,42 @@
+## What this is
+
+A panel framework, not a dashboard: boxes with a title and a status light, splits that
+resize, a feed that pushes typed events, and renderers for what arrives. It was built for
+high-frequency operational views — a minimal Grafana — and every piece below exists
+because an app needed it.
+
+**The contract is the framework; Vue is one binding of it.** The contract is four things:
+the token names, the element layer (`base.css`), the class names (`.panel`,
+`.panel-header`, `.split-pane`, …) and the status words. Those are not whole yet: a feed
+reports `idle`, `connecting`, `live`, `error`, while the panel's dot shows `idle`,
+`live`, `processing`, `error` — so `connecting` has no dot, and a consumer has to map it
+by hand. That is a gap in the contract, listed below. `common/theme/parts` is the second
+binding: the same contract as plain CSS and JS, for pages that must open from a file with
+no build. docgen's site is not a binding yet: it bakes its colours from its own style
+slots, a third token vocabulary.
+
+## The layers, as use shaped them
+
+| layer | what | the evidence |
+| --- | --- | --- |
+| contract | tokens, element layer, class names, status words | every consumer reads `tokens.css`; four apps pasted their own `base.css` before it shipped here |
+| chrome | `Panel` (+ maximize), `SplitPane`, `ParameterEditor`, `VideoPlayer` | `Panel` and `SplitPane` are the only exports all five consumers use; nested splits, not `LayoutGrid`, turned out to be the layout |
+| feed | `DataSource`, `SSEDataSource` | one stream, typed events, a terminal `done` |
+| renderers | `LogRenderer`, `TableRenderer`, `FrameRenderer`, `TimeSeriesRenderer`, `GraphRenderer` | opt-in; the only two external packages arrive through these |
+| app state | not here | mpr keeps its own Pinia stores; `pinia` is imported nowhere in this library |
+| delivery | slices, not this whole folder | see below |
+
+## How to take it
+
+Not as this folder. A consumer takes a **slice**: the closure of the exports it uses,
+as readable source, with a barrel exporting only those and a `tokens.css` cut down to
+what is read — `make ui scan <app>` computes it, `ctrl/ui.sh slice <run file>` writes it,
+and `check` reports drift both ways. The "Contents" table is the price list.
+
+## How this document is made
+
+Everything outside these notes is generated from `src/` by `make reference` (in
+`common/ui`), so a prop that is removed disappears from here on the next build. The notes
+are the only hand-written part, one file per spot in `soleprint/common/ui/notes/`; a note
+whose spot disappears fails `make check`. `make docs` — anywhere in soleprint — launches
+this site.

soleprint/common/ui/notes/contents.md

@@ -0,0 +1,16 @@
+**Who uses what**, measured 2026-09-22 with `make ui scan <app>` over the five apps that
+consume this library. It is the one table here that is not generated — the apps live
+outside this repository — so re-run the scan before trusting a row.
+
+| export | mpr detection | mts meetus | mts doocus | unt | nvi |
+| --- | --- | --- | --- | --- | --- |
+| `Panel`, `SplitPane` | ✓ | ✓ | ✓ | ✓ | ✓ |
+| `LogRenderer` | ✓ | | | ✓ | |
+| `VideoPlayer` | | ✓ | | | |
+| `ParameterEditor`, `ResizeHandle`, all renderers but Log, `SSEDataSource`, `useRegistry`, `useEditorExecution` | ✓ | | | | |
+| `LayoutGrid`, `StaticDataSource`, `useDataSource`, `BBoxDrawPlugin`, `CrosshairPlugin` | | | | | |
+
+The last row has **no users at all**. Those exports stay in the library — they are
+small and a slice never carries them unless asked — but nothing should be built on them
+as if they were proven. `ResizeHandle` is imported by mpr and never rendered: it is what
+`SplitPane` replaced.

soleprint/common/ui/notes/tokens.md

@@ -0,0 +1,10 @@
+**There are two definitions, and the ⚠ rows are where they disagree.** `src/tokens.css`
+is the library's own, dark-only; the theme contract in `common/theme` derives the same
+names from its own palette. They agree on every colour but `--surface-3` and on neither
+font stack. A Vue slice uses the library's values by default so swapping a consumer's
+copy for a slice changes no pixel; `theme = "soleprint"` opts into the contract, and
+that is a visible change. Retiring the library's file in favour of the contract is the
+open question — it changes what every current consumer renders.
+
+"read by nobody" means no stylesheet in the library reads it. Apps read tokens directly
+too — `make ui scan` reports between 14 and 23 per app — and a slice carries those.