@issuegraph/editor 0.10.0 → 0.22.1

package/dist/audit/styles.js

@@ -33,6 +33,7 @@
  * There is no transition, no animation and no `@keyframes` here, and there is a
  * test that says so.
  */
+import { AUDIT_KIND_ATTRIBUTE } from "./panel.js";
 import { AUDIT_SEVERITY_ATTRIBUTE } from "./surface.js";
 export const auditStylesheet = `
 .ig-audit {
@@ -68,5 +69,432 @@ export const auditStylesheet = `
 [${AUDIT_SEVERITY_ATTRIBUTE}] {
   box-shadow: inset var(--ig-stroke-audit) 0 0 0 var(--ig-edge-serialize-with);
 }
+
+/* §17d'S PANEL. Note what it does NOT select on: ${AUDIT_SEVERITY_ATTRIBUTE},
+   whose rule immediately above is deliberately unqualified because it lands on a
+   row the VIEWER rendered. A chip wearing that attribute would draw the rail's
+   gold bar whatever hue the class table gave it, which is the four-hue mapping
+   below defeated by one attribute. Chips carry ${AUDIT_KIND_ATTRIBUTE}. */
+/* IT IS THE SELECTION'S PEER, NOT ITS HEADING, so it carries its own padding:
+   it is a sibling of .ig-inspector inside the zone rather than a child, and
+   that column's padding does not reach it.
+
+   IT DECLARES NO SIZE OF ITS OWN, AND THAT IS THE LAYERING. Issue 177 gave the
+   audit half the inspector column, scrolling itself past that — and since the
+   fourth class moved to ./refused.ts the half belongs to the REGION holding both
+   surfaces rather than to this panel. Either way it is a fact about SHARING A
+   COLUMN, not a fact about the panel, so it is declared by the composition that
+   owns the zone. See workspace/styles.ts.
+
+   The difference is reachable rather than theoretical: renderAuditPanel and
+   this stylesheet are both public exports, so a consumer can draw the panel
+   outside renderWorkspace. Capping it there would hide findings behind an inner
+   scrollbar with half the container left empty and no selection detail to
+   reserve the space for. A leaf that sized itself would be wrong in every
+   composition but one. */
+.ig-audit-panel {
+  border-bottom: var(--ig-stroke) solid var(--ig-line);
+  display: flex;
+  flex-direction: column;
+  font-family: var(--ig-font-ui);
+  gap: var(--ig-space-snug);
+  min-height: 0;
+  padding: var(--ig-space);
+}
+
+/* THE RING FOR THE PANEL'S OWN TAB STOP. Unscoped, unlike the sizing above,
+   because the tabindex is in this leaf's MARKUP and is therefore carried into
+   every composition: a focusable element that shows nothing on focus is a stop
+   a keyboard reader lands on blind, wherever it is drawn.
+
+   INSET, WHICH IS THE VIEWER'S OWN IDIOM for exactly this shape — its sheet
+   draws every focus ring at a negative offset. Drawn outward it would sit on
+   the panel's border box against the zone's edge and the column's own scroll,
+   where the top and bottom of the ring are the first thing clipped. */
+.ig-audit-panel:focus-visible {
+  outline: var(--ig-focus-ring) solid var(--ig-focus);
+  outline-offset: calc(var(--ig-focus-ring) * -1);
+}
+
+.ig-audit-panel-head {
+  align-items: center;
+  display: flex;
+  gap: var(--ig-space-tight);
+}
+
+/* THE GOLD IS THE AMBIENT MARK'S, not a fifth hue. §17d names one attention
+   colour and the rail bar already spends it; the panel head answering in the
+   same gold is what makes the count and the list read as one thing. */
+.ig-audit-mark {
+  color: var(--ig-edge-serialize-with);
+  font-size: var(--ig-font-size-small);
+}
+
+.ig-audit-panel-count {
+  color: var(--ig-edge-serialize-with);
+  font-family: var(--ig-font-mono);
+  font-size: var(--ig-font-size-small);
+  font-variant-numeric: tabular-nums;
+}
+
+.ig-audit-panel-heading {
+  color: var(--ig-edge-serialize-with);
+  font-weight: inherit;
+  margin: 0;
+  font-family: var(--ig-font-mono);
+  font-size: var(--ig-font-size-small);
+  letter-spacing: var(--ig-tracking-group);
+  text-transform: uppercase;
+}
+
+/* NO CAP ON THE LIST, AND THAT IS STILL RIGHT — the bound belongs to the PANEL
+   above, not here. Three caps were tried on this element (a fixed length, a
+   share of a flex column, that share measured on the right box) and each was
+   correct about the previous one's defect while the column stayed the thing
+   that could not be bounded from in here. It still cannot: the list has no
+   padding, so a scroll container here computes overflow-x to auto and clips the
+   focus ring on every card control. The panel carries the share and the
+   scrolling; see the rule above. */
+.ig-audit-list {
+  display: flex;
+  flex-direction: column;
+  gap: var(--ig-space-snug);
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+.ig-audit-card {
+  display: flex;
+  flex-direction: column;
+  gap: var(--ig-space-micro);
+}
+
+.ig-audit-chip {
+  align-self: flex-start;
+  border: var(--ig-stroke) solid var(--ig-line);
+  border-radius: var(--ig-radius-small);
+  font-family: var(--ig-font-mono);
+  font-size: var(--ig-font-size-pill);
+  padding: 0 var(--ig-space-tight);
+}
+
+.ig-audit-title {
+  color: var(--ig-text);
+  font-size: var(--ig-font-size);
+  margin: 0;
+}
+
+/* SENTENCE-LENGTH COPY TAKES --ig-text-body, NEVER --ig-text-muted. SPEC's
+   closing note measures muted at 4.65:1 on a plain surface and about 0.4 less
+   inside a tint, which drops it under AA — so muted is reserved there for short
+   mono labels, and a finding's detail is a sentence. */
+.ig-audit-detail {
+  color: var(--ig-text-body);
+  font-size: var(--ig-font-size-compact);
+  line-height: var(--ig-line-height);
+  margin: 0;
+}
+
+/* MUTED IS CORRECT HERE, ON THE SAME RULE .ig-audit-refused-source ends this
+   file with: the note above reserves muted for SHORT MONO LABELS, and a cycle's
+   walk is one — refs and separators, no prose. Length is not the test and could
+   not be: a large ring draws a long line, which is what the wrap below is for.
+   What muted is reserved AGAINST is sentence-length COPY. The detail rule one block up takes --ig-text-body because it IS a
+   sentence, so it is the wrong neighbour to copy.
+
+   break-word, NOT anywhere. A ref is a token worth keeping whole; the refused
+   block accepts mid-token breaks because it quotes arbitrary body text, and a
+   walk is a list of identifiers a reader has to be able to match against the
+   rail. */
+.ig-audit-walk {
+  color: var(--ig-text-muted);
+  font-family: var(--ig-font-mono);
+  font-size: var(--ig-font-size-compact);
+  line-height: var(--ig-line-height);
+  margin: 0;
+  overflow-wrap: break-word;
+}
+
+.ig-audit-show {
+  align-self: flex-start;
+  background: none;
+  border: var(--ig-stroke) solid var(--ig-line);
+  border-radius: var(--ig-radius-small);
+  color: var(--ig-text);
+  cursor: pointer;
+  font: inherit;
+  font-size: var(--ig-font-size-meta);
+  padding: var(--ig-space-micro) var(--ig-space-tight);
+}
+
+.ig-audit-show:hover {
+  border-color: var(--ig-accent);
+}
+
+.ig-audit-show:focus-visible {
+  outline: var(--ig-focus-ring) solid var(--ig-focus);
+  outline-offset: var(--ig-space-micro);
+}
+
+/* 17d'S REMEDIES. A row of them under the card's sentence.
+
+   THEY TAKE THE SAME CHROME AS .ig-audit-show DELIBERATELY. A remedy and the
+   navigation control beside it do the same KIND of thing — both publish a
+   selection and neither writes — so drawing the remedies louder would promise
+   an action they do not perform. 3's whole point is that the judgment stays
+   with the owner, and a button styled like a commit invites a click that is
+   not one.
+
+   WRAPS, because the stale card carries two of them inside a panel of fixed
+   width whose cards also indent. A row that cannot wrap pushes its second
+   control out of the panel, which is the shape the relationship row one sheet
+   over already had to solve. (Worded around two particular verbs on purpose:
+   acceptance scans this sheet's PROSE as well as its declarations for the
+   vocabulary of a remedy that acts by itself, and it cannot tell a comment
+   from a control. Both spellings of that idea are therefore unusable here,
+   including in a note explaining why.)
+
+   (The width itself is 3's number and lives in workspace/styles.ts, where the
+   overlay is positioned. Naming it here would put a length in a sheet whose
+   own guard reads comments as well as declarations - which is how this
+   paragraph was first written, and caught.) */
+.ig-audit-remedies {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--ig-space-tight);
+}
+
+.ig-audit-remedy {
+  background: none;
+  border: var(--ig-stroke) solid var(--ig-line);
+  border-radius: var(--ig-radius-small);
+  color: var(--ig-text);
+  cursor: pointer;
+  font: inherit;
+  font-size: var(--ig-font-size-meta);
+  padding: var(--ig-space-micro) var(--ig-space-tight);
+}
+
+.ig-audit-remedy:hover {
+  border-color: var(--ig-accent);
+}
+
+.ig-audit-remedy:focus-visible {
+  outline: var(--ig-focus-ring) solid var(--ig-focus);
+  outline-offset: var(--ig-space-micro);
+}
+
+/* 17d'S OWN ENTRY POINT - 'filter the rail to these' - in the panel head.
+
+   IT SITS AT THE END OF THE HEAD ROW, after the count and the heading, which is
+   where the frame draws it. margin-inline-start: auto rather than a width on
+   the heading, so the head stays one flex row whatever the host's word is.
+
+   aria-pressed IS STYLED, NOT JUST PUBLISHED. 2's ruling is that a filter
+   which is visibly on, states what it hides and clears in one click is not a
+   refusal - so 'visibly on' is a requirement here rather than a nicety. */
+.ig-audit-filter {
+  background: none;
+  border: var(--ig-stroke) solid var(--ig-line);
+  border-radius: var(--ig-radius-small);
+  color: var(--ig-text-muted);
+  cursor: pointer;
+  font: inherit;
+  font-size: var(--ig-font-size-meta);
+  margin-inline-start: auto;
+  padding: var(--ig-space-micro) var(--ig-space-tight);
+}
+
+.ig-audit-filter[aria-pressed='true'] {
+  border-color: var(--ig-accent);
+  color: var(--ig-accent);
+}
+
+.ig-audit-filter:focus-visible {
+  outline: var(--ig-focus-ring) solid var(--ig-focus);
+  outline-offset: var(--ig-space-micro);
+}
+
+/* ONE RULE PER CLASS, WRITTEN OUT, never through an intermediate property: the
+   viewer's own badge sheet records why — a \--ig-audit-hue\ set here and read
+   here names something no theme and no layout declares, and the token scan
+   exists to refuse exactly that.
+
+   THE TINTS ARE THE VIEWER'S RECIPE, not new numbers. \--ig-tint-fill\ and
+   \--ig-tint-border\ are what \.ig-badge[data-edge]\ already mixes an edge hue
+   with, and they are the frame's own chip wash to within a point.
+
+   THE TEXT IS THE BASE HUE. The frame lightens each chip's label a step off the
+   hue it tints with; those derivatives have no token, and a literal here is
+   refused by the scan two files over, so the label takes the hue itself. */
+.ig-audit-chip[${AUDIT_KIND_ATTRIBUTE}='cycle'] {
+  background: color-mix(in srgb, var(--ig-edge-blocked-by) var(--ig-tint-fill), transparent);
+  border-color: color-mix(in srgb, var(--ig-edge-blocked-by) var(--ig-tint-border), transparent);
+  color: var(--ig-edge-blocked-by);
+}
+
+.ig-audit-chip[${AUDIT_KIND_ATTRIBUTE}='stale-blocker'] {
+  background: color-mix(in srgb, var(--ig-edge-serialize-with) var(--ig-tint-fill), transparent);
+  border-color: color-mix(in srgb, var(--ig-edge-serialize-with) var(--ig-tint-border), transparent);
+  color: var(--ig-edge-serialize-with);
+}
+
+.ig-audit-chip[${AUDIT_KIND_ATTRIBUTE}='dead-duplicate-ref'] {
+  background: color-mix(in srgb, var(--ig-edge-duplicate-of) var(--ig-tint-fill), transparent);
+  border-color: color-mix(in srgb, var(--ig-edge-duplicate-of) var(--ig-tint-border), transparent);
+  color: var(--ig-edge-duplicate-of);
+}
+
+.ig-audit-chip[${AUDIT_KIND_ATTRIBUTE}='encoding-refused'] {
+  background: color-mix(in srgb, var(--ig-edge-blocked-by) var(--ig-tint-fill), transparent);
+  border-color: color-mix(in srgb, var(--ig-edge-blocked-by) var(--ig-tint-border), transparent);
+  color: var(--ig-edge-blocked-by);
+}
+
+/* ---- §17d's fourth class, drawn outside the panel (./refused.ts) ---- */
+
+/* NO SIZE OF ITS OWN, THE SAME ANSWER .ig-audit-panel GIVES ABOVE. This block
+   and that panel are the two members of .ig-audit-overlay, which is what the
+   inspector zone actually holds, and how much of the zone's single track that
+   region may take is a fact about SHARING A COLUMN rather than a fact about
+   either leaf. So the share is declared once by the composition that owns the
+   zone — see workspace/styles.ts, which bounds the region alone. */
+.ig-audit-refused {
+  display: flex;
+  flex-direction: column;
+  font-family: var(--ig-font-ui);
+  gap: var(--ig-space-snug);
+  min-height: 0;
+  padding: var(--ig-space);
+}
+
+/* THE RING FOR THIS BLOCK'S TAB STOP, unscoped for the reason the panel's is:
+   the tabindex is in this leaf's MARKUP, so it is carried into every
+   composition, and a focusable element that shows nothing on focus is a stop a
+   keyboard reader lands on blind. Inset, the viewer's idiom, so a ring at the
+   zone's edge is not the first thing the column's scroll clips. */
+.ig-audit-refused:focus-visible {
+  outline: var(--ig-focus-ring) solid var(--ig-focus);
+  outline-offset: calc(var(--ig-focus-ring) * -1);
+}
+
+/* THE SAME HEADING TREATMENT AS THE PANEL'S, because they are peers in one
+   column and §17d draws them as one section. A second treatment would say they
+   were two unrelated things. */
+.ig-audit-refused-heading {
+  color: var(--ig-edge-blocked-by);
+  font-family: var(--ig-font-mono);
+  font-size: var(--ig-font-size-small);
+  font-weight: inherit;
+  letter-spacing: var(--ig-tracking-group);
+  margin: 0;
+  text-transform: uppercase;
+}
+
+.ig-audit-refused-list {
+  display: flex;
+  flex-direction: column;
+  gap: var(--ig-space-snug);
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+/* THE CARD IS DRAWN, UNLIKE THE PANEL'S. The frame gives this one a surface and
+   a border because it sits alone rather than in a list of like items — it is
+   the one finding that is about an ISSUE rather than a relationship, and the
+   box is what says so. */
+.ig-audit-refused-card {
+  background: var(--ig-surface-2);
+  border: var(--ig-stroke) solid var(--ig-card-line);
+  border-radius: var(--ig-radius);
+  display: flex;
+  flex-direction: column;
+  gap: var(--ig-space-tight);
+  padding: var(--ig-space-tight);
+}
+
+.ig-audit-refused-head {
+  align-items: center;
+  display: flex;
+  gap: var(--ig-space-tight);
+}
+
+.ig-audit-refused-ref {
+  color: var(--ig-text);
+  font-family: var(--ig-font-mono);
+  font-size: var(--ig-font-size-meta);
+}
+
+/* ONE BLOCK, TWO LINES — the diagnostic and, under it, the line the reader
+   stopped on. pre-wrap because the source line is RAW BODY TEXT: it carries
+   its own leading space and its own length, and collapsing either would show a
+   reader something other than what is in their issue. overflow-wrap keeps a
+   long unbroken line inside the column instead of widening the track. */
+.ig-audit-refused-reason {
+  display: flex;
+  flex-direction: column;
+  font-family: var(--ig-font-mono);
+  font-size: var(--ig-font-size-meta);
+  gap: var(--ig-space-micro);
+  overflow-wrap: anywhere;
+  white-space: pre-wrap;
+}
+
+.ig-audit-refused-diagnostic {
+  color: var(--ig-text-body);
+}
+
+/* MUTED IS CORRECT HERE AND NOWHERE NEAR A SENTENCE. SPEC's closing note puts
+   muted under AA for sentence-length copy, which is why .ig-audit-detail
+   takes --ig-text-body — but this is a short mono quotation of the reader's own
+   input, the exact shape muted is reserved for, and the frame draws it a step
+   back from the diagnostic it belongs to. */
+.ig-audit-refused-source {
+  color: var(--ig-text-muted);
+}
+
+.ig-audit-refused-controls {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--ig-space-tight);
+}
+
+/* ONE TREATMENT FOR BOTH CONTROLS, THOUGH ONE IS AN ANCHOR AND ONE A BUTTON.
+   The element differs because what they DO differs — the link leaves the
+   document and must say so to assistive technology — but they sit side by side
+   in the frame as one pair of moves, and drawing them differently would imply a
+   difference in weight that §17d does not make. */
+.ig-audit-refused-open,
+.ig-audit-refused-rewrite {
+  align-items: center;
+  background: none;
+  border: var(--ig-stroke) solid var(--ig-line);
+  border-radius: var(--ig-radius-small);
+  color: var(--ig-text);
+  cursor: pointer;
+  display: inline-flex;
+  font: inherit;
+  font-size: var(--ig-font-size-meta);
+  gap: var(--ig-space-micro);
+  padding: var(--ig-space-micro) var(--ig-space-tight);
+  text-decoration: none;
+}
+
+.ig-audit-refused-open:hover,
+.ig-audit-refused-rewrite:hover {
+  border-color: var(--ig-accent);
+}
+
+.ig-audit-refused-open:focus-visible,
+.ig-audit-refused-rewrite:focus-visible {
+  outline: var(--ig-focus-ring) solid var(--ig-focus);
+  outline-offset: var(--ig-space-micro);
+}
+
+.ig-audit-refused-away {
+  color: var(--ig-text-muted);
+}
 `;
 //# sourceMappingURL=styles.js.map

package/dist/audit/styles.js.map

@@ -1 +1 @@
-{"version":3,"file":"styles.js","sourceRoot":"","sources":["../../src/audit/styles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAExD,MAAM,CAAC,MAAM,eAAe,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+B5B,wBAAwB;;;CAG1B,CAAC"}
+{"version":3,"file":"styles.js","sourceRoot":"","sources":["../../src/audit/styles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAExD,MAAM,CAAC,MAAM,eAAe,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+B5B,wBAAwB;;;;oDAIyB,wBAAwB;;;;kDAI1B,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA8PrD,oBAAoB;;;;;;iBAMpB,oBAAoB;;;;;;iBAMpB,oBAAoB;;;;;;iBAMpB,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsJpC,CAAC"}

package/dist/audit/surface.d.ts

@@ -17,10 +17,16 @@
  * ## Why the bar is CSS on an attribute rather than a drawn element
  *
  * The rows belong to `@issuegraph/viewer`, which stamps `KEY_ATTRIBUTE` on
- * them. Layer 2 composes layer 1 through its public surface, and the viewer's
- * markup primitive is deliberately not on it — so an overlay drawn from out
- * here would have to re-implement HTML escaping, which is duplication with an
- * injection shape rather than a mirror that merely drifts.
+ * them. Layer 2 composes layer 1 through its public surface, and rewriting a
+ * row's `class` from out here is reaching past that surface — so a bar drawn as
+ * an element would mean this layer assembling markup for a row it does not own.
+ *
+ * ONE CLAUSE OF THIS USED TO READ "and the viewer's markup primitive is
+ * deliberately not on it", and that was never true after `renderMarkup` was
+ * exported one pull request later. It is public, and five sibling leaves import
+ * it — `scale/render.ts`, `picker/render.ts`, `workspace/render.ts`,
+ * `reevaluate/render.ts`, `firstpass/render.ts`. The escaping was never what
+ * made the bar an attribute; OWNERSHIP OF THE ROW is, and that part stands.
  *
  * An attribute plus a stylesheet needs neither. {@link auditRowAttributes}
  * answers what an affected row carries, `./styles.ts` draws the bar from it,
@@ -30,10 +36,18 @@
  * ## Nothing here renders host text
  *
  * The only value that reaches the markup is a COUNT, and a count is a number.
- * That is a deliberate boundary rather than a happy accident: a finding's
- * `detail` is prose about issues a host supplied, so drawing it here would put
- * an escaper in a package whose seam says it may not have one. Findings travel
- * as data; whatever lists them owns their escaping.
+ * That is what makes {@link renderAuditHeader} safe while it concatenates by
+ * hand, and it is a boundary rather than a happy accident: a finding's `detail`
+ * is prose about issues a host supplied. Findings travel as data; whatever
+ * lists them owns their escaping.
+ *
+ * ## And `./panel.ts` is the lister that rule predicted
+ *
+ * §17d's findings list is drawn there, not here, and it owns its escaping the
+ * way every other leaf does — an `ElementSpec` tree the caller renders through
+ * the viewer's `renderMarkup`. So the rule above is unchanged rather than
+ * relaxed: this module still renders no host text, and the module that does
+ * builds no markup by hand.
  *
  * @see https://github.com/autnmy/issuegraph/blob/main/SPEC.md
  */
@@ -52,6 +66,16 @@ export declare const AUDIT_COUNT_ATTRIBUTE = "data-ig-audit-count";
  * matching on a class name that is a styling hook rather than a contract.
  */
 export declare const AUDIT_FILTER_ATTRIBUTE = "data-ig-audit-filter";
+/**
+ * The attribute marking the header's panel control.
+ *
+ * SEPARATE FROM THE FILTER, because §17d gives the header count exactly one
+ * job — *"always the same click"* — and `RULINGS.md` §3 says what that click
+ * does: the panel is *"a transient overlay anchored to the header count"*. The
+ * filter is drawn INSIDE the panel, where §17d draws it (*"filter the rail to
+ * these"*), so one control no longer carries two meanings.
+ */
+export declare const AUDIT_PANEL_ATTRIBUTE = "data-ig-audit-panel";
 /** What one affected row is told about itself. */
 export interface AuditRow {
     readonly ref: IssueRef;
@@ -105,8 +129,13 @@ export interface AuditOverlay {
  * Project findings onto the two things the ambient surface draws.
  *
  * Pure, and a function of the findings alone: it neither re-detects anything
- * nor reads the document, so the count on screen and the list behind it can
- * never disagree about what was found.
+ * nor reads the document, so the count on screen and what is drawn behind it
+ * can never disagree about what was found.
+ *
+ * "WHAT IS DRAWN" IS TWO SURFACES, NOT ONE. `./panel.ts` lists the three
+ * relationship classes and `./refused.ts` draws the fourth, so this count is a
+ * count of both together — which is why it stays every finding while the
+ * panel's own head counts only its cards. See {@link renderAuditHeader}.
  */
 export declare function auditOverlay(input: AuditInput): AuditOverlay;
 /**
@@ -137,8 +166,15 @@ export declare function auditFilterKeeps(overlay: AuditOverlay, ref: IssueRef):
  */
 export declare function heaviestRow(overlay: AuditOverlay, refs: readonly IssueRef[]): AuditRow | undefined;
 export interface AuditHeaderOptions {
-    /** Whether the filter is currently narrowing the rail. Defaults to `false`. */
-    readonly filtered?: boolean | undefined;
+    /**
+     * Whether §17d's overlay is open. Defaults to `false`.
+     *
+     * WAS `filtered`, AND THE SWAP IS THE RULING. This button used to toggle the
+     * rail filter; §3 makes it the panel's anchor instead, and the filter moves
+     * into the panel head. A host that bound to the old meaning gets a compile
+     * error rather than a control that silently does something else.
+     */
+    readonly open?: boolean | undefined;
 }
 /**
  * The persistent header count, as markup.
@@ -148,6 +184,12 @@ export interface AuditHeaderOptions {
  * that appears when there is bad news is a control the eye has to re-find, and
  * §17d's whole ask is that the audit never demands attention it has not earned.
  *
+ * IT COUNTS EVERY FINDING, ACROSS BOTH SURFACES THAT DRAW THEM. `./panel.ts`
+ * lists three classes and `./refused.ts` draws the fourth, and a reader works
+ * through all four — so splitting this number would hand them two to add up
+ * for one question. This one is in the workspace CHROME, beside both; the
+ * panel's own head is enclosed by its list and counts that list alone.
+ *
  * A `button` with `aria-pressed`, because a filter toggle is a toggle: it has
  * two states and a screen reader has to be able to say which one is on.
  */

package/dist/audit/surface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"surface.d.ts","sourceRoot":"","sources":["../../src/audit/surface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAGlD,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEzF;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,kBAAkB,CAAC;AAExD,kFAAkF;AAClF,eAAO,MAAM,qBAAqB,wBAAwB,CAAC;AAE3D;;;GAGG;AACH,eAAO,MAAM,sBAAsB,yBAAyB,CAAC;AAE7D,kDAAkD;AAClD,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC;IACvB;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,sEAAsE;IACtE,QAAQ,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,CAAC;IACtC,uCAAuC;IACvC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,gEAAgE;IAChE,QAAQ,CAAC,IAAI,EAAE,SAAS,QAAQ,EAAE,CAAC;IACnC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,QAAQ,KAAK,QAAQ,GAAG,SAAS,CAAC;IACzD,0DAA0D;IAC1D,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;CAC5C;AAMD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,YAAY,CAmE5D;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,YAAY,EACrB,GAAG,EAAE,QAAQ,GACZ,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAIlC;AAED,iFAAiF;AACjF,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAE9E;AAUD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,YAAY,EACrB,IAAI,EAAE,SAAS,QAAQ,EAAE,GACxB,QAAQ,GAAG,SAAS,CAQtB;AAED,MAAM,WAAW,kBAAkB;IACjC,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACzC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,GAAE,kBAAuB,GAAG,MAAM,CAYjG"}
+{"version":3,"file":"surface.d.ts","sourceRoot":"","sources":["../../src/audit/surface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAGlD,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEzF;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,kBAAkB,CAAC;AAExD,kFAAkF;AAClF,eAAO,MAAM,qBAAqB,wBAAwB,CAAC;AAE3D;;;GAGG;AACH,eAAO,MAAM,sBAAsB,yBAAyB,CAAC;AAE7D;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,wBAAwB,CAAC;AAE3D,kDAAkD;AAClD,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC;IACvB;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,sEAAsE;IACtE,QAAQ,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,CAAC;IACtC,uCAAuC;IACvC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,gEAAgE;IAChE,QAAQ,CAAC,IAAI,EAAE,SAAS,QAAQ,EAAE,CAAC;IACnC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,QAAQ,KAAK,QAAQ,GAAG,SAAS,CAAC;IACzD,0DAA0D;IAC1D,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;CAC5C;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,YAAY,CAmE5D;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,YAAY,EACrB,GAAG,EAAE,QAAQ,GACZ,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAIlC;AAED,iFAAiF;AACjF,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAE9E;AAUD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,YAAY,EACrB,IAAI,EAAE,SAAS,QAAQ,EAAE,GACxB,QAAQ,GAAG,SAAS,CAQtB;AAED,MAAM,WAAW,kBAAkB;IACjC;;;;;;;OAOG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,GAAE,kBAAuB,GAAG,MAAM,CAiBjG"}

package/dist/audit/surface.js

@@ -17,10 +17,16 @@
  * ## Why the bar is CSS on an attribute rather than a drawn element
  *
  * The rows belong to `@issuegraph/viewer`, which stamps `KEY_ATTRIBUTE` on
- * them. Layer 2 composes layer 1 through its public surface, and the viewer's
- * markup primitive is deliberately not on it — so an overlay drawn from out
- * here would have to re-implement HTML escaping, which is duplication with an
- * injection shape rather than a mirror that merely drifts.
+ * them. Layer 2 composes layer 1 through its public surface, and rewriting a
+ * row's `class` from out here is reaching past that surface — so a bar drawn as
+ * an element would mean this layer assembling markup for a row it does not own.
+ *
+ * ONE CLAUSE OF THIS USED TO READ "and the viewer's markup primitive is
+ * deliberately not on it", and that was never true after `renderMarkup` was
+ * exported one pull request later. It is public, and five sibling leaves import
+ * it — `scale/render.ts`, `picker/render.ts`, `workspace/render.ts`,
+ * `reevaluate/render.ts`, `firstpass/render.ts`. The escaping was never what
+ * made the bar an attribute; OWNERSHIP OF THE ROW is, and that part stands.
  *
  * An attribute plus a stylesheet needs neither. {@link auditRowAttributes}
  * answers what an affected row carries, `./styles.ts` draws the bar from it,
@@ -30,10 +36,18 @@
  * ## Nothing here renders host text
  *
  * The only value that reaches the markup is a COUNT, and a count is a number.
- * That is a deliberate boundary rather than a happy accident: a finding's
- * `detail` is prose about issues a host supplied, so drawing it here would put
- * an escaper in a package whose seam says it may not have one. Findings travel
- * as data; whatever lists them owns their escaping.
+ * That is what makes {@link renderAuditHeader} safe while it concatenates by
+ * hand, and it is a boundary rather than a happy accident: a finding's `detail`
+ * is prose about issues a host supplied. Findings travel as data; whatever
+ * lists them owns their escaping.
+ *
+ * ## And `./panel.ts` is the lister that rule predicted
+ *
+ * §17d's findings list is drawn there, not here, and it owns its escaping the
+ * way every other leaf does — an `ElementSpec` tree the caller renders through
+ * the viewer's `renderMarkup`. So the rule above is unchanged rather than
+ * relaxed: this module still renders no host text, and the module that does
+ * builds no markup by hand.
  *
  * @see https://github.com/autnmy/issuegraph/blob/main/SPEC.md
  */
@@ -51,13 +65,28 @@ export const AUDIT_COUNT_ATTRIBUTE = 'data-ig-audit-count';
  * matching on a class name that is a styling hook rather than a contract.
  */
 export const AUDIT_FILTER_ATTRIBUTE = 'data-ig-audit-filter';
+/**
+ * The attribute marking the header's panel control.
+ *
+ * SEPARATE FROM THE FILTER, because §17d gives the header count exactly one
+ * job — *"always the same click"* — and `RULINGS.md` §3 says what that click
+ * does: the panel is *"a transient overlay anchored to the header count"*. The
+ * filter is drawn INSIDE the panel, where §17d draws it (*"filter the rail to
+ * these"*), so one control no longer carries two meanings.
+ */
+export const AUDIT_PANEL_ATTRIBUTE = 'data-ig-audit-panel';
 const CLASS_ORDER = new Map(AUDIT_CLASSES.map((kind, index) => [kind, index]));
 /**
  * Project findings onto the two things the ambient surface draws.
  *
  * Pure, and a function of the findings alone: it neither re-detects anything
- * nor reads the document, so the count on screen and the list behind it can
- * never disagree about what was found.
+ * nor reads the document, so the count on screen and what is drawn behind it
+ * can never disagree about what was found.
+ *
+ * "WHAT IS DRAWN" IS TWO SURFACES, NOT ONE. `./panel.ts` lists the three
+ * relationship classes and `./refused.ts` draws the fourth, so this count is a
+ * count of both together — which is why it stays every finding while the
+ * panel's own head counts only its cards. See {@link renderAuditHeader}.
  */
 export function auditOverlay(input) {
     // IT RUNS THE AUDIT RATHER THAN ACCEPTING ONE. Taking a finding list made
@@ -183,16 +212,27 @@ export function heaviestRow(overlay, refs) {
  * that appears when there is bad news is a control the eye has to re-find, and
  * §17d's whole ask is that the audit never demands attention it has not earned.
  *
+ * IT COUNTS EVERY FINDING, ACROSS BOTH SURFACES THAT DRAW THEM. `./panel.ts`
+ * lists three classes and `./refused.ts` draws the fourth, and a reader works
+ * through all four — so splitting this number would hand them two to add up
+ * for one question. This one is in the workspace CHROME, beside both; the
+ * panel's own head is enclosed by its list and counts that list alone.
+ *
  * A `button` with `aria-pressed`, because a filter toggle is a toggle: it has
  * two states and a screen reader has to be able to say which one is on.
  */
 export function renderAuditHeader(overlay, options = {}) {
     const count = String(overlay.count);
-    const pressed = options.filtered === true;
+    const open = options.open === true;
     return [
         `<div class="ig-audit" ${AUDIT_COUNT_ATTRIBUTE}="${count}">`,
-        `<button type="button" class="ig-audit-toggle" aria-pressed="${String(pressed)}"`,
-        ` ${AUDIT_FILTER_ATTRIBUTE}>`,
+        // `aria-expanded`, NOT `aria-pressed`. The two say different things and the
+        // button's job changed underneath it: `pressed` describes a toggle that is
+        // ON — the old filter — while `expanded` describes a control that DISCLOSES
+        // something, which is what an overlay anchored here is. A reader told
+        // "pressed" would be waiting for a state, not for a panel.
+        `<button type="button" class="ig-audit-toggle" aria-expanded="${String(open)}"`,
+        ` ${AUDIT_PANEL_ATTRIBUTE}>`,
         `<span class="ig-audit-count">${count}</span>`,
         `<span class="ig-audit-label">audit</span>`,
         `</button>`,