mosaic-headless 1.11.2 → 1.13.0

package/data/node-type-notes.csv

@@ -0,0 +1,5 @@
+type,note
+component-instance,"Swept as COMMIT_500, which is what a BARE one does. The node's type is not `component-instance` but `component-instance/<componentID>` - the factory splits on that slash and a bare one has no id to read. With a real component it commits and renders; see sweep_components.py."
+component-internal,"The component's content hangs under THIS node, in the `node/component/<id>` key of a componentDocumentInstance. `component-root` looks like the parent and accepts no children."
+component-root,"Accepts no children. It frames the component's preview document, not its content."
+loop,"COMMIT_500 on a bare page: the loop needs a query context that a plain document does not provide."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mosaic-headless",
-  "version": "1.11.2",
+  "version": "1.13.0",
   "description": "AI-agent skill: build Mosaic Pro (Nextend) WordPress sites by writing the underlying data model directly - 23 custom tables, no visual editor, no DOM. Every node type, style property and node property swept against a live install and asserted on the delivered HTML and compiled CSS. Installs into Claude Code, Cursor, Codex CLI, Gemini CLI, Copilot, Continue, Windsurf and Claude.ai.",
   "keywords": [
     "wordpress",

package/references/data-model.md

@@ -93,3 +93,41 @@ takes variations from there.
 That is why the same visual change can be made in two very different places, and
 why writing a style onto a node directly is usually the wrong move: the class is
 the unit of reuse, and the collection/variable tables are the token layer beneath it.
+
+
+## Components: one definition, many places
+
+Three tables (`components`, `component_documents`, `component_categories`), four
+node types and eighteen REST routes. Driven end to end by
+`tools/sweep_components.py`; every claim here was measured, and none of it is
+guessable from the route list.
+
+```
+1  create      adminComponentsEditorInstance, commit a `component` record
+               parentType MUST be "componentCategory" - Page, Block and Part exist
+               out of the box, and no other parent type is accepted at all.
+               parentType:"" gives HTTP 500, "Parent type not supported"
+
+2  heal        GET componentDocumentInstance/<id>
+               the FIRST call 404s and creates the document; the second returns it,
+               healed into body / component-external / component-root / document
+
+3  fill        commit into the SAME instance, under the `component-internal` node
+               in its `node/component/<id>` key.
+               NOT componentNodeEditorInstance - `isCommitAllowed()` returns false
+               there and the commit is refused with "Not allowed!" and a 500, even
+               though that is the instance which shows you the tree.
+               NOT component-root either - it accepts no children
+
+4  instance    on a page, a node whose TYPE carries the component's id:
+                   type: "component-instance/<componentID>"
+               `ComponentInstanceElementTypeFactory` splits on that slash. A bare
+               `component-instance` has no id for `$flags[0]` and fatals, which is
+               the entire reason it is COMMIT_500 in node-verification.csv
+```
+
+Verified on a live page: two instances of one component, both rendered, the
+component's own text present twice from a single definition. Edit the component and
+every instance changes - which is the whole point, and the reason a real site should
+use these rather than repeating a tree.
+

package/sites/_moksa.py

@@ -1935,7 +1935,12 @@ PLATE = section("plate", [wrap("mk-plate-in", [
                 [T("p", "01", fontFamily=DISPLAY, fontSize="132px",
                    fontWeight="600", lineHeight=".82", letterSpacing="-0.05em",
                    color="rgba(0,0,0,0)",
-                   customStyles="-webkit-text-stroke:1px " + RULE_INK + ";",
+                   # RULE_INK at 42% measured 2.64:1 on the panel, and a 132px
+                   # numeral is large text, which needs 3.0. This is the lightest
+                   # stroke that clears it. It was invisible until the audit
+                   # learned to read `-webkit-text-stroke-color` instead of
+                   # giving up at a transparent `color`.
+                   customStyles="-webkit-text-stroke:1px rgba(22,24,28,.52);",
                    _t={"fontSize": "104px"}, _m={"fontSize": "68px"})]),
             box("mk-plate-t", {}, [
                 mono("PLATE 01 — POSITION", size="10px", color="--mk-accent-ink",

package/sites/moksa.json

@@ -5351,7 +5351,7 @@
                    "lineHeight": ".82",
                    "letterSpacing": "-0.05em",
                    "color": "rgba(0,0,0,0)",
-                   "customStyles": "-webkit-text-stroke:1px rgba(22,24,28,.42);"
+                   "customStyles": "-webkit-text-stroke:1px rgba(22,24,28,.52);"
                   },
                   "_t": {
                    "fontSize": "104px"

package/tools/mo.py

@@ -104,6 +104,21 @@ def table(headers, body, gap=2):
         print(sep.join(c.ljust(width[i]) for i, c in enumerate(r)).rstrip())
 
 
+def wrap(text: str, width: int) -> list[str]:
+    """Break on spaces. Slicing every N characters splits words in half, which in a
+    note about `component-instance/<componentID>` is actively misleading."""
+    out, line = [], ""
+    for word in (text or "").split():
+        if line and len(line) + 1 + len(word) > width:
+            out.append(line)
+            line = word
+        else:
+            line = (line + " " + word) if line else word
+    if line:
+        out.append(line)
+    return out
+
+
 def matches(text: str, needle: str | None) -> bool:
     return needle is None or needle.lower() in (text or "").lower()
 
@@ -119,6 +134,14 @@ def type_record(name: str) -> dict:
             name, ("\ndid you mean: " + ", ".join(near[:8])) if near else ""))
 
     v = index("node-verification", "type").get(name, {})
+    # A sweep outcome is what happened to ONE probe. Where that number is true but
+    # misleading on its own, the note says why - `component-instance` is COMMIT_500
+    # only because a bare one has no component id in its type.
+    note = ""
+    try:
+        note = index("node-type-notes", "type").get(name, {}).get("note", "")
+    except SystemExit:
+        note = ""
     p = index("placement-rules", "type").get(name, {})
     d = index("default-children", "type").get(name, {})
 
@@ -148,6 +171,7 @@ def type_record(name: str) -> dict:
         "edition": t.get("edition"),
         "outcome": v.get("outcome"),
         "outcome_note": OUTCOME_NOTE.get(v.get("outcome"), ""),
+        "note": note,
         "safe_to_commit": v.get("outcome") not in UNSAFE,
         "detail": v.get("detail"),
         "rendered_tag": v.get("rendered_tag"),
@@ -207,6 +231,9 @@ def cmd_type(a):
         print("verdict   : %s" % flag)
         if rec["detail"]:
             print("failure   : %s" % rec["detail"])
+        if rec["note"]:
+            for i, line in enumerate(wrap(rec["note"], 74)):
+                print("%-11s %s" % ("note      :" if i == 0 else "", line))
         if rec["rendered_tag"]:
             print("renders as: <%s>%s" % (
                 rec["rendered_tag"],
@@ -244,6 +271,96 @@ def cmd_type(a):
     emit(rec, render)
 
 
+def cmd_params(a):
+    """Everything that can be SET on one node type, in one answer.
+
+    This is the question you actually have in front of an editor: not "does this
+    type exist" but "what may I put on it, in what shape, and which of those have
+    been seen to work". It is four tables joined - node properties by the data
+    class, the universal style surface, the style states that reach this type, and
+    the placement rule - because the answer is not in any one of them.
+
+    Mosaic differs from a widget-based builder here in a way worth stating: the
+    STYLE surface is universal. Every element takes the same 98 style properties;
+    what varies per type is the DATA properties and which node-type-scoped states
+    apply. So the style half of this output is the same for every type, and that
+    is a fact about the platform rather than a shortcut taken here."""
+    rec = type_record(a.name)
+    prop_status = {r["property"]: r for r in rows("node-property-verification")}
+    sv = index("style-verification", "property")
+    shapes = index("style-value-shapes", "property")
+    ver = index("style-state-verification", "state")
+
+    states = []
+    for r in rows("style-states"):
+        v = ver.get(r["state"], {})
+        if r["scope"] == "global" or v.get("host") == a.name:
+            states.append({"state": r["state"], "scope": r["scope"],
+                           "selector": r["selector_template"],
+                           "status": v.get("status", "base state"
+                                           if r["state"] == "&" else "")})
+
+    style = []
+    for r in rows("style-properties"):
+        v = sv.get(r["property"], {})
+        style.append({"property": r["property"], "group": r["group"],
+                      "css": v.get("css_property", ""),
+                      "status": v.get("status", ""),
+                      "shape": shapes.get(r["property"], {}).get("shape", ""),
+                      "accepted_values": split(r["accepted_values"])})
+
+    payload = {"type": a.name, "safe_to_commit": rec["safe_to_commit"],
+               "note": rec["note"], "data_properties": rec["properties"],
+               "style_properties": style, "states": states,
+               "placement_rule": rec["placement_rule"],
+               "allowed_children": rec["allowed_children"]}
+
+    def render():
+        head("%s - everything settable" % a.name)
+        print("verdict   : %s%s"
+              % ("SAFE" if rec["safe_to_commit"] else "UNSAFE TO COMMIT",
+                 "  (%s)" % rec["outcome"] if rec["outcome"] else ""))
+        if rec["note"]:
+            for i, line in enumerate(wrap(rec["note"], 74)):
+                print("%-11s %s" % ("note      :" if i == 0 else "", line))
+
+        print("\nDATA properties (%d) - these vary by type"
+              % len(rec["properties"]))
+        table(["property", "shared", "verified", "accepted values"],
+              [[p["property"], "yes" if p["inherited_from"] else "",
+                (prop_status.get(p["property"]) or {}).get("status", ""),
+                ", ".join(p["accepted_values"])[:44]]
+               for p in rec["properties"]])
+
+        usable = [s for s in states if s["status"] in ("COMPILED", "base state")]
+        print("\nSTATES reaching this type (%d usable of %d)"
+              % (len(usable), len(states)))
+        table(["state", "scope", "swept", "selector"],
+              [[s["state"], s["scope"], s["status"], s["selector"][:44]]
+               for s in states])
+
+        ok = [p for p in style if p["status"] == "COMPILED"]
+        grouped = [p for p in style if p["group"]]
+        print("\nSTYLE properties: %d in the surface, %d measured COMPILED,"
+              " %d belong to a group and are INERT set on their own."
+              "\nThe style surface is UNIVERSAL in Mosaic - it is the same "
+              "for every type."
+              % (len(style), len(ok), len(grouped)))
+        if a.style:
+            table(["property", "group", "css", "swept", "shape"],
+                  [[p["property"], p["group"], p["css"], p["status"],
+                    p["shape"][:30]] for p in style])
+        else:
+            print("(pass --style to list them, or `mo.py style` for the same "
+                  "table on its own)")
+
+        print("\nCHILDREN  : rule=%s%s" % (rec["placement_rule"],
+              ("  " + ", ".join(rec["allowed_children"]))
+              if rec["allowed_children"] else ""))
+
+    emit(payload, render)
+
+
 def cmd_types(a):
     ver = index("node-verification", "type")
     out = []
@@ -655,6 +772,12 @@ def main():
     p = add("type", cmd_type, "one node type, fully joined")
     p.add_argument("name")
 
+    p = add("params", cmd_params,
+            "EVERYTHING settable on one type: data, style, states, placement")
+    p.add_argument("name")
+    p.add_argument("--style", action="store_true",
+                   help="list all 98 style properties too, not just count them")
+
     p = add("check", cmd_check, "exit 1 if any named type is unsafe or unknown")
     p.add_argument("names", nargs="+")
 

package/tools/sweep_components.py

@@ -0,0 +1,215 @@
+#!/usr/bin/env python3
+"""Drive Mosaic's component system end to end, and check every step.
+
+    python tools/sweep_components.py --config c.json --post 20 --slug probe-lab
+    python tools/sweep_components.py --config c.json --post 20 --slug probe-lab \
+        --csv data/component-verification.csv
+
+Components are how a Mosaic site stops repeating itself: build a card once, place it
+in twenty documents, edit the one and all twenty change. Three tables, four node
+types and eighteen REST routes serve it, and this skill had never touched any of
+them - `component-instance` sat in `node-verification.csv` as COMMIT_500, which is
+true and useless, because it only says what happens when you commit one WRONG.
+
+Four things had to be found out, and none is guessable:
+
+1.  **A component must hang off a `componentCategory`.** `parentType:""` gives
+    `Uncaught Exception: Parent type not supported` and an HTTP 500. Three
+    categories exist out of the box - Page, Block, Part - and the manager accepts
+    no other parent type at all.
+
+2.  **The component's document is created lazily by the first GET.** Ask for
+    `componentDocumentInstance/<id>` immediately after creating the component and it
+    is a 404; ask again and it is there, healed into body / component-external /
+    component-root / document.
+
+3.  **`componentNodeEditorInstance` is READ ONLY.** Its `isCommitAllowed()` returns
+    `false`, so a commit there is refused with `Not allowed!` and an HTTP 500 - even
+    though it is the instance that shows you the tree you want to edit. The writable
+    one is `componentDocumentInstance`, and the content goes under the
+    `component-internal` node in its `node/component/<id>` key. `component-root`
+    looks like the obvious parent and accepts no children at all.
+
+4.  **An instance's node type carries the component's ID.** Not
+    `type: "component-instance"` but `type: "component-instance/<componentID>"` -
+    `ComponentInstanceElementTypeFactory` splits on that slash, which is why a bare
+    one fatals: there is no id for `$flags[0]` to read.
+
+Every step below is asserted against the row that came back or the HTML the site
+served, and the run ends by placing two instances and counting the component's own
+text in the delivered page - because one instance rendering proves less than two.
+"""
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import os
+import sys
+import time
+import urllib.error
+import urllib.request
+import uuid
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from build_page import Surface, flatten  # noqa: E402
+from build_site import bind_page, build_shell  # noqa: E402
+from sweep_node_types import Client, envelopes, exceptions_of, unwrap  # noqa: E402
+
+MARKER = "COMPONENT PROBE — REUSED"
+
+
+def card(attr):
+    """What the component contains. Deliberately something with a border and a
+    string, so both the CSS and the text can be looked for in the delivered page."""
+    return {"type": "div", "data": {"attrID": attr},
+            "style": {"&": {"_": {"paddingTop": "18px", "paddingBottom": "18px",
+                                  "paddingLeft": "20px", "paddingRight": "20px",
+                                  "customStyles":
+                                      "border:1px solid rgb(214,214,206);"}}},
+            "children": [
+                {"type": "text",
+                 "data": {"tagName": "p", "attrID": attr + "-t"},
+                 "style": {"&": {"_": {"fontSize": "13px",
+                                       "letterSpacing": "0.16em"}}},
+                 "text": MARKER}]}
+
+
+def fetch(url):
+    sep = "&" if "?" in url else "?"
+    req = urllib.request.Request(
+        "%s%s_v=%d" % (url, sep, int(time.time() * 1000)),
+        headers={"User-Agent": "Mozilla/5.0", "Cache-Control": "no-cache"})
+    try:
+        with urllib.request.urlopen(req, timeout=90) as r:
+            return r.read().decode("utf-8", "replace")
+    except urllib.error.HTTPError as e:
+        return e.read().decode("utf-8", "replace")
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--config", required=True)
+    ap.add_argument("--post", type=int, required=True)
+    ap.add_argument("--slug", required=True)
+    ap.add_argument("--csv")
+    a = ap.parse_args()
+
+    cfg = json.load(open(a.config, encoding="utf-8"))
+    client, surface = Client(cfg), Surface()
+    rows, failed = [], 0
+
+    def step(name, ok, detail):
+        nonlocal failed
+        rows.append([name, "PASS" if ok else "FAIL", detail])
+        print("  %-28s %-5s %s" % (name, "PASS" if ok else "FAIL", detail))
+        if not ok:
+            failed += 1
+
+    # ── 1. the categories a component may hang from ──────────────────────────
+    inst = unwrap(client.get("adminComponentsEditorInstance"),
+                  "adminComponentsEditorInstance")
+    cats = inst.get("componentCategory") or []
+    step("categories exist", bool(cats),
+         ", ".join((r.get("data") or {}).get("name", "?") for r in cats)
+         or "none - a component has nothing to hang from")
+    if not cats:
+        sys.exit(1)
+
+    # ── 2. creating one, correctly parented ──────────────────────────────────
+    cid = str(uuid.uuid4())
+    resp = client.commit("adminComponentsEditorInstance", envelopes(inst),
+                         {"component": [{"newRevisionRecord": {
+                             "ID": cid, "parentType": "componentCategory",
+                             "parentID": cats[0]["ID"], "ordering": "a0",
+                             "status": "publish", "revision": "", "version": "",
+                             "name": "Probe Card", "path": ""},
+                             "originalRevisionRecord": None}]})
+    err = exceptions_of(resp)
+    inst2 = unwrap(client.get("adminComponentsEditorInstance"),
+                   "adminComponentsEditorInstance")
+    mine = [r for r in (inst2.get("component") or []) if r["ID"] == cid]
+    step("component created", bool(mine) and not err,
+         "parented to %r" % (cats[0].get("data") or {}).get("name")
+         if mine else "rejected: %s" % (err or "row never appeared"))
+
+    # ── 3. the document heals on first read ──────────────────────────────────
+    instance = "componentDocumentInstance/%s" % cid
+    first = client.get(instance)
+    doc = unwrap(client.get(instance), "componentDocumentInstance")
+    ckey = "node/component/%s" % cid
+    internal = next((n for n in doc.get(ckey, [])
+                     if n["type"] == "component-internal"), None)
+    step("document healed", internal is not None,
+         "first GET %s, second gave component-internal"
+         % ("404'd" if "_httperror" in first else "succeeded"))
+    if internal is None:
+        sys.exit(1)
+
+    # ── 4. content goes under component-internal, via the WRITABLE instance ──
+    recs = flatten(card("cmp-card"), internal["ID"], cid, surface, False,
+                   parent_type="component-internal")
+    for r in recs:
+        r["documentType"], r["documentID"] = "component", cid
+    resp = client.commit(instance, envelopes(doc),
+                         {ckey: [{"newRevisionRecord": r,
+                                  "originalRevisionRecord": None} for r in recs]})
+    err = exceptions_of(resp)
+    doc2 = unwrap(client.get(instance), "componentDocumentInstance")
+    types = sorted({n["type"] for n in doc2.get(ckey, [])})
+    step("component filled", "div" in types and not err,
+         "tree is %s" % ", ".join(types))
+
+    # ── 5. the read-only instance refuses the same write ─────────────────────
+    # A negative control: this is the endpoint that LOOKS like the right one, and
+    # the difference between the two is not visible from the route list.
+    ro = "componentNodeEditorInstance/%s" % cid
+    rodoc = unwrap(client.get(ro), "componentNodeEditorInstance")
+    ro_resp = client.commit(ro, envelopes(rodoc), {ckey: [
+        {"newRevisionRecord": dict(recs[0], ID=str(uuid.uuid4())),
+         "originalRevisionRecord": None}]})
+    refused = "_httperror" in ro_resp or bool(exceptions_of(ro_resp))
+    step("read-only instance refuses", refused,
+         "componentNodeEditorInstance rejected the same commit"
+         if refused else "it ACCEPTED a write it documents as not allowed")
+
+    # ── 6. two instances on a real page, and the page must show both ─────────
+    master = build_shell(client, cfg, {"pages": [], "shell": {}}, surface)
+    template = bind_page(client, cfg, master, a.slug, a.post)
+    tinst = "templateDocumentInstance/%s/%s" % (master, template)
+    tdoc = unwrap(client.get(tinst), "templateDocumentInstance")
+    tkey = "node/template/%s" % template
+    root = next(n for n in tdoc[tkey] if n["type"] == "template-internal")
+    base = {"parentType": "node", "parentID": root["ID"], "status": "publish",
+            "revision": "", "version": "", "documentType": "template",
+            "documentID": template}
+    place = [{"newRevisionRecord": dict(base, ID=str(uuid.uuid4()),
+                                        ordering="a%d" % i,
+                                        type="component-instance/%s" % cid,
+                                        data={"attrID": "cmp-use-%d" % i}),
+              "originalRevisionRecord": None} for i in range(2)]
+    resp = client.commit(tinst, envelopes(tdoc), {tkey: place})
+    err = exceptions_of(resp)
+    step("instances committed", not err, err or "type carries the component id")
+
+    html = fetch("%s/%s/" % (cfg["base"].rstrip("/"), a.slug))
+    ids = html.count('id="cmp-use-')
+    body = html.count(MARKER)
+    step("both instances rendered", ids == 2,
+         "%d instance elements in the delivered HTML" % ids)
+    step("component content reused", body == 2,
+         "the component's own text appears %d times from ONE definition" % body)
+
+    print("\n%d of %d checks passed" % (len(rows) - failed, len(rows)))
+    print("COMPONENT_ID=%s" % cid)
+    if a.csv:
+        with open(a.csv, "w", newline="", encoding="utf-8") as fh:
+            w = csv.writer(fh)
+            w.writerow(["step", "result", "detail"])
+            w.writerows(rows)
+        print("wrote", a.csv)
+    sys.exit(1 if failed else 0)
+
+
+if __name__ == "__main__":
+    main()

package/tools/verify_browser.py

@@ -403,14 +403,43 @@ PROBE = r"""
     // rgba(0,0,0,0) as pure black - which then scores a perfect contrast ratio
     // against any light ground. That is a blind spot scoring itself as a pass, so
     // it gets its own finding instead: the check cannot run here, and says so.
-    const rgba = (cs.color.match(/[\d.]+/g) || []).map(Number);
+    let rgba = (cs.color.match(/[\d.]+/g) || []).map(Number);
+    let paintedBy = '';
     if (rgba.length === 4 && rgba[3] < 0.05) {
-      out.audit.push({check: 'TEXT_CLIP', level: 'warn', node: id,
-                      detail: 'color is ' + cs.color + '; painted by ' +
-                              (cs.backgroundClip === 'text' ? 'background-clip:text'
-                                                            : 'something else') +
-                              ' - contrast NOT checked here',
-                      sample: own.slice(0, 24)});
+      // The colour is transparent, but the glyphs are not: something else is
+      // painting them. Reporting "cannot check" here was the tool declining to
+      // look one property further. Both of the ways this page does it are
+      // readable from the computed style.
+      const stops = [];
+      if (cs.backgroundClip === 'text' || cs.webkitBackgroundClip === 'text') {
+        // every colour stop in the gradient; the worst one is what decides
+        for (const m of (cs.backgroundImage || '').matchAll(
+               /rgba?\(([^)]+)\)/g)) {
+          const v = m[1].split(',').map(Number);
+          if (v.length >= 3) stops.push(v);
+        }
+        if (stops.length) paintedBy = 'background-clip:text';
+      }
+      const strokeW = parseFloat(cs.webkitTextStrokeWidth) || 0;
+      if (!stops.length && strokeW > 0) {
+        const v = (cs.webkitTextStrokeColor.match(/[\d.]+/g) || []).map(Number);
+        if (v.length >= 3) { stops.push(v); paintedBy = 'text-stroke'; }
+      }
+      if (stops.length) {
+        // the worst stop is the one that decides whether the string is readable
+        let worst = null, wr = Infinity;
+        for (const v of stops) {
+          const c = over(v.slice(0, 3), bgOf(el), v.length === 4 ? v[3] : 1);
+          const r = ratio(c, bgOf(el));
+          if (r < wr) { wr = r; worst = c; }
+        }
+        rgba = worst.concat([1]);
+      } else {
+        out.audit.push({check: 'TEXT_CLIP', level: 'warn', node: id,
+                        detail: 'color is ' + cs.color + ' and nothing readable is '
+                              + 'painting it - contrast NOT checked here',
+                        sample: own.slice(0, 24)});
+      }
     }
     const bg0 = bgOf(el);
     const fg = over(rgba.slice(0, 3), bg0,
@@ -421,7 +450,8 @@ PROBE = r"""
       const need = large ? 3.0 : 4.5;
       if (r < need) out.audit.push({
         check: 'CONTRAST', level: r < need - 1 ? 'error' : 'warn', node: id,
-        detail: r.toFixed(2) + ':1 against its background, needs ' + need,
+        detail: r.toFixed(2) + ':1 against its background, needs ' + need
+              + (paintedBy ? ' (painted by ' + paintedBy + ', worst stop)' : ''),
         sample: own.slice(0, 24)});
     }
 
@@ -541,6 +571,10 @@ def main():
     ap.add_argument("--site", required=True)
     ap.add_argument("--csv", help="the computed-value table")
     ap.add_argument("--audit", help="the design-audit findings")
+    ap.add_argument("--ack", default=os.path.join(
+        os.path.dirname(os.path.abspath(__file__)), "..", "data",
+        "design-audit-acknowledged.csv"),
+        help="findings reviewed and accepted, with the reason for each")
     ap.add_argument("--shots")
     ap.add_argument("--page", help="only this slug")
     a = ap.parse_args()
@@ -617,6 +651,26 @@ def main():
                 print("    %-4s %-22s %-16s declared %-18s got %s"
                       % (r[1], r[2][:22], r[3], r[4][:18], r[5][:34]))
 
+    # A finding that is correct by design and will never be fixed should not sit
+    # in the same bucket as one nobody has looked at yet - a list where most
+    # entries are permanent is a list people stop reading. So they are
+    # ACKNOWLEDGED rather than suppressed: the acknowledgement lives in the
+    # repository beside the data, every one carries a written reason, and the
+    # count is still printed. Nothing is dropped; it is only separated from what
+    # nobody has looked at.
+    acks = []
+    if a.ack and os.path.exists(a.ack):
+        with open(a.ack, encoding="utf-8", newline="") as fh:
+            acks = list(csv.DictReader(fh))
+
+    def acknowledged(finding):
+        for row in acks:
+            if (row["check"] == finding["check"]
+                    and (finding.get("node") or "").startswith(
+                        row["node_prefix"])):
+                return row["reason"]
+        return None
+
     # Audit findings collapse across breakpoints: the same headline reported at three
     # widths is one defect, not three, and printing it three times buries the others.
     seen: dict[tuple, dict] = {}
@@ -624,13 +678,29 @@ def main():
         key = (f["check"], f.get("node", ""), f.get("detail", ""))
         seen.setdefault(key, dict(f, breakpoints=[]))["breakpoints"].append(
             f["breakpoint"])
-    audit = sorted(seen.values(), key=lambda f: (f["level"] != "error", f["check"]))
+    audit = sorted(seen.values(),
+                   key=lambda f: (f["level"] != "error", f["check"]))
+    for f in audit:
+        why = acknowledged(f)
+        if why:
+            f["level"], f["ack"] = "ack", why
     errors = [f for f in audit if f["level"] == "error"]
+    open_warns = [f for f in audit if f["level"] == "warn"]
+    acked = [f for f in audit if f["level"] == "ack"]
     hard += len(errors)
 
-    print("\ndesign audit  (%d findings: %d error, %d warn)"
-          % (len(audit), len(errors), len(audit) - len(errors)))
+    print("\ndesign audit  (%d findings: %d error, %d unreviewed warn, "
+          "%d acknowledged)"
+          % (len(audit), len(errors), len(open_warns), len(acked)))
+    for f in acked[:6]:
+        print("  ack   %-22s %-26s %s"
+              % (f["check"], (f.get("node") or "")[:26], f["ack"][:64]))
+    if len(acked) > 6:
+        print("  ack   ... %d more under the same acknowledgement"
+              % (len(acked) - 6))
     for f in audit[:40]:
+        if f["level"] == "ack":
+            continue
         print("  %-5s %-22s %-26s %s"
               % (f["level"], f["check"], (f.get("node") or "")[:26],
                  f.get("detail", "")))
@@ -653,20 +723,21 @@ def main():
     if a.audit:
         with open(a.audit, "w", newline="", encoding="utf-8") as fh:
             w = csv.writer(fh)
-            w.writerow(["url", "breakpoints", "check", "level", "node", "detail",
-                        "sample"])
+            w.writerow(["url", "breakpoints", "check", "level", "node",
+                        "detail", "sample", "acknowledged_because"])
             for f in audit:
                 w.writerow([f["url"], ",".join(f["breakpoints"]), f["check"],
                             f["level"], f.get("node", ""), f.get("detail", ""),
-                            f.get("sample", "")])
+                            f.get("sample", ""), f.get("ack", "")])
         print("wrote %s (%d findings)" % (a.audit, len(audit)))
 
     # "clean" was overstating it once the audit began reporting blind spots as
     # warnings. A run carrying two labelled unknowns is not a run carrying none, and
     # the summary line is the part people read.
     print("\n%s" % (("PASS - every comparable declaration is what the browser "
-                     "computed; 0 audit errors, %d warnings"
-                     % (len(audit) - len(errors)))
+                     "computed; 0 audit errors, %d unreviewed warnings, "
+                     "%d acknowledged"
+                     % (len(open_warns), len(acked)))
                     if not hard else
                     "FAIL - %d overridden declarations, %d audit errors"
                     % (counts.get("OVERRIDDEN", 0), len(errors))))