tosijs-floorplan 0.3.0 → 0.5.0

package/src/index.ts

@@ -69,6 +69,23 @@ export interface SchematicRecord {
    * ("3") or bound ("3 ⟷ app.qty"). tosijs emits it as a bound prop; the
    * declared field gives plain-DOM producers the same home */
   value?: string
+  /** the producer's ASSERTION that this element can be acted on — for
+   * producers that cannot introspect handlers (React delegates at a root;
+   * vanilla addEventListener is not enumerable from page script). A binding
+   * framework never needs it: `on` and two-way bindings already say so.
+   * Asserting is truth-telling; fabricating `on` to unlock the styling
+   * would be a lie in the payload. (issue #3, haltija) */
+  interactive?: boolean
+  /** the producer's assertion that text goes in here — the DOM-side
+   * counterpart of contentEditable/two-way bindings (issue #3) */
+  editable?: boolean
+  /** the producer WITHHELD facts about this element (tosijs 1.11.0's
+   * secret regions: a magic-link token lives in the href, so neither
+   * label nor href is published). Drawn with a `[withheld]` caption when
+   * nothing else names it, and the legend says redacted — "this link has
+   * no destination" and "its destination was withheld" are different
+   * facts (issue #15) */
+  secret?: boolean
   [boundProp: string]: unknown
 }
 
@@ -165,25 +182,98 @@ export interface SchematicLegendEntry {
   /** interactive element below the target-size floor, e.g.
    * "18×13 — below 24×24 (WCAG 2.5.8)" */
   undersized?: string
+  /** the producer withheld facts about this record (`secret: true`) —
+   * a missing href here means "withheld", not "no destination" */
+  redacted?: boolean
 }
 
 export interface SchematicResult {
   svg: string
   legend: SchematicLegendEntry[]
+  /** set when the map draws affordance-shaped boxes but NO record carries
+   * any affordance evidence: "nothing here is actionable" and "the
+   * producer couldn't tell" are different statements, and a consumer
+   * acting on the first when the truth is the second is the
+   * confident-wrong-answer case (issue #3). Also rides the svg's <desc>. */
+  note?: string
 }
 
 // strip provenance from a bound-value string: "shown ⟷ path" → "shown"
 // (empty when the binding holds no value yet); a plain string (no arrow)
-// is a live-but-unbound value and passes through whole
+// is a live-but-unbound value and passes through whole.
+// The STRUCTURAL arrow is the LAST one in the string — the surface appends
+// it, so everything before it is data, and data can carry arrow tokens
+// (forged, or from a producer older than tosijs 1.8.0, which neutralizes
+// them at the source). A renderer consumes maps it did not generate, so it
+// parses defensively: split at the last arrow, and neutralize any arrow
+// left INSIDE the shown value (geometry over glyphs — a rare glyph must
+// never ride a caption run, and a fake arrow must never read as structure).
 const shownValue = (v: unknown): string | undefined => {
   if (typeof v !== 'string') return undefined
-  for (const arrow of [BOUND_TWO_WAY, BOUND_TO_DOM]) {
-    const at = v.indexOf(arrow)
-    if (at >= 0) return v.slice(0, at).trim()
-  }
-  return v
+  const at = Math.max(v.lastIndexOf(BOUND_TWO_WAY), v.lastIndexOf(BOUND_TO_DOM))
+  return neutralizeArrows(at >= 0 ? v.slice(0, at).trim() : v)
+}
+
+// arrow tokens inside record data must neither ride a caption run
+// (geometry over glyphs) nor read as structure — neutralized the same way
+// tosijs ≥1.8.0 does at the source
+const neutralizeArrows = (s: string): string =>
+  s.replaceAll(BOUND_TWO_WAY, '<->').replaceAll(BOUND_TO_DOM, '<-')
+
+// is this string a live two-way binding? Only the arrow in STRUCTURAL
+// position (last) counts — a ⟷ buried inside the data must not confer an
+// affordance (a drawing that lies about what the page can do is worse than
+// no drawing).
+const boundTwoWay = (v: unknown): boolean => {
+  if (typeof v !== 'string') return false
+  const at = v.lastIndexOf(BOUND_TWO_WAY)
+  return at >= 0 && at > v.lastIndexOf(BOUND_TO_DOM)
 }
 
+// fields the surface NEVER appends a binding arrow to: identity, naming,
+// hints, destinations. In these, any arrow is data (or forgery) — the
+// last-occurrence rule only protects fields that actually receive an
+// appended binding, so these are excluded from the binding scan entirely
+// (0.4.0 review B1: a lone forged arrow in a never-bindable field is
+// always in "last = structural" position).
+const NEVER_BOUND = new Set([
+  'tag', 'id', 'part', 'role', 'label', 'placeholder', 'type',
+  'description', 'href', 'ref', 'image',
+])
+const hasTwoWayBinding = (w: SchematicRecord): boolean =>
+  Object.entries(w).some(
+    ([key, v]) => !NEVER_BOUND.has(key) && boundTwoWay(v)
+  )
+
+// the two kinds of affordance evidence, split once and shared by the
+// renderer AND the exported predicate — three independently edited copies
+// of this logic is how the renderer and tosijs's audit drifted into
+// contradicting each other (issue #4); parity is now by construction
+const hasActEvidence = (w: SchematicRecord): boolean =>
+  w.on != null ||
+  w.interactive === true ||
+  (typeof w.href === 'string' && w.href !== '')
+const hasEditEvidence = (w: SchematicRecord): boolean =>
+  w.editable === true || w.contentEditable === true || hasTwoWayBinding(w)
+
+// can this producer SEE wiring at all? Any handler, any assertion, any
+// provenance arrow — including a display-only ⟵ — proves it can (#10: a
+// read-only dashboard from a binding framework is not a blind map, it's a
+// sighted map of a page with nothing actionable on it)
+const hasCapabilityEvidence = (w: SchematicRecord): boolean =>
+  w.on != null ||
+  w.interactive === true ||
+  w.editable === true ||
+  // arrows count only in bindable fields — an arrow in a never-bindable
+  // identity/name field is page content (possibly forged), and must not
+  // fabricate capability any more than it fabricates a binding
+  Object.entries(w).some(
+    ([key, v]) =>
+      !NEVER_BOUND.has(key) &&
+      typeof v === 'string' &&
+      (v.includes(BOUND_TWO_WAY) || v.includes(BOUND_TO_DOM))
+  )
+
 /**
  * An element's page-coordinate bounds (the same space describe() records) —
  * the natural `within` argument for a region-scoped schematic.
@@ -198,6 +288,100 @@ export const boundsOf = (element: Element): SchematicBounds => {
   }
 }
 
+// structure behind affordances — a LIST CONTAINER is ground too: it's
+// wired (the collection binds here), but its items are the affordances.
+// EVIDENCE BEATS CONTAINER ROLE (#7): an element that is both container
+// and control (a list-bound <select> carrying its own two-way value, a
+// list div with handlers) is an affordance wearing a list, not ground —
+// classifying it structural silenced error-severity audit findings.
+const isGround = (w: SchematicRecord): boolean =>
+  w.structural === true ||
+  (w.list != null && !hasActEvidence(w) && !hasEditEvidence(w))
+
+/**
+ * "Can I act here?" — the single implementation of the interactivity
+ * predicate, exported so audits (tosijs's auditAccessibility) consume THIS
+ * rather than keeping a drifting copy (issue #4: the two had already
+ * reached contradictory verdicts on the same element). Evidence, any of:
+ * handlers (`on`), a link destination (`href` — a link IS an affordance),
+ * `contentEditable`, a two-way binding in structural position, or the
+ * producer's own `interactive`/`editable` assertion (issue #3). Ground
+ * (structure, list containers) is never interactive.
+ */
+export const isInteractive = (w: SchematicRecord): boolean =>
+  !isGround(w) && (hasActEvidence(w) || hasEditEvidence(w))
+
+/** the WCAG 2.5.8 audit floor (24×24, the AA minimum) — one constant so
+ * the option default and the exported rule cannot drift */
+export const TARGET_SIZE_DEFAULT = 24
+
+/**
+ * The WCAG 2.5.8 target-size rule, exported for the same reason as
+ * `isInteractive` (issue #4): one implementation, geometry judged where the
+ * geometry lives. Returns the measured finding string (the legend fact) or
+ * null. Embodies the settled exemptions: toggles (user-agent-sized); links
+ * plausibly sized by VISIBLE text — the WCAG inline exception as far as
+ * pure geometry can honour it, which is: has text, and the box is WIDER
+ * than tall, the shape text layout produces (issue #2 caught the earlier
+ * text-only rule exempting 16×16 icon links that happened to carry a
+ * label; an accessible name alone never sizes a box, and a square box was
+ * not sized by its text); and supersession by any producer-supplied flag
+ * whose kind mentions `target` — a producer with DOM access (computed
+ * display, parent text nodes) computes the real exception and ships the
+ * finding via `flags`; that is the INTENDED path for DOM producers, and
+ * the built-in never double-marks over it.
+ */
+/** flag kinds that claim to BE a target-size finding, and therefore
+ * supersede the built-in audit when the renderer honours producer flags.
+ * An explicit set, not a substring match: `includes('target')` let
+ * 'target-ok' — or any kind merely mentioning the word — silently stand
+ * the audit down (#8). Covers both producers' kinds in the wild
+ * (haltija: 'target', 'smallTarget'; tosijs auditFlags: 'target-size'). */
+export const TARGET_FLAG_KINDS: ReadonlySet<string> = new Set([
+  'target',
+  'target-size',
+  'targetsize',
+  'target_size',
+  'smalltarget',
+])
+
+export const targetSizeFinding = (
+  w: SchematicRecord,
+  targetSize = TARGET_SIZE_DEFAULT,
+  { honorProducerFlags = false } = {}
+): string | null => {
+  if (targetSize <= 0 || w.bounds == null || !isInteractive(w)) return null
+  const { width, height } = w.bounds
+  // hidden is not small (#9): a 0×0 (or unlaid-out) element is not a
+  // target too small to hit — the guard lives here so callers passing raw
+  // wiring don't each grow their own copy
+  if (width <= 0 || height <= 0) return null
+  if (w.type === 'checkbox' || w.type === 'radio') return null
+  if (
+    w.tag === 'a' &&
+    typeof w.text === 'string' &&
+    w.text !== '' &&
+    width > height
+  ) {
+    return null
+  }
+  // supersession is a DRAWING concern — no double bars for one finding —
+  // so it is opt-in (#8): schematic() passes true; an audit consuming this
+  // rule wants the geometry verdict regardless of what the producer drew
+  if (
+    honorProducerFlags &&
+    Array.isArray(w.flags) &&
+    w.flags.some(
+      (f) => typeof f?.kind === 'string' && TARGET_FLAG_KINDS.has(f.kind.toLowerCase())
+    )
+  ) {
+    return null
+  }
+  return width < targetSize || height < targetSize
+    ? `${width}×${height} — below ${targetSize}×${targetSize} (WCAG 2.5.8)`
+    : null
+}
+
 const intersects = (a: SchematicBounds, b: SchematicBounds): boolean =>
   a.x < b.x + b.width &&
   b.x < a.x + a.width &&
@@ -227,6 +411,14 @@ const FLAG_COLORS: Record<string, string> = {
   info: '#888888',
 }
 
+// severity comes from producer JSON, so it can be anything — including
+// 'constructor', which a bare index would resolve up the prototype chain
+// into a function serialized straight into a fill attribute
+const flagColor = (severity: unknown): string =>
+  typeof severity === 'string' && Object.hasOwn(FLAG_COLORS, severity)
+    ? FLAG_COLORS[severity]
+    : FLAG_COLORS.warn
+
 // greedy word-wrap: captions should USE vertical room, not truncate with
 // space to spare (a <p> that wraps on the real page has the same height
 // here). Returns at most maxLines lines, each at most maxChars long;
@@ -271,7 +463,7 @@ export const schematic = (
     fontSize = 11,
     within,
     index: showIndex = false,
-    targetSize = 24,
+    targetSize = TARGET_SIZE_DEFAULT,
     legendNote = true,
     decorate,
   } = options
@@ -328,14 +520,35 @@ export const schematic = (
     } ${maxY - minY}" width="${maxX - minX}" height="${maxY - minY}">`,
   ]
   // structure behind affordances: dotted outlines the eye (and the raster)
-  // reads as grouping, not controls. A LIST CONTAINER is ground too — it's
-  // wired (the collection binds here, and the JSON record says so), but its
-  // items are the affordances; drawing it solid would read as actionable.
-  const ground = (w: (typeof boxes)[number]): boolean =>
-    w.structural === true || (w.list != null && w.on == null)
+  // reads as grouping, not controls (isGround, module level — the exported
+  // predicates share it).
   const drawOrder = [...boxes].sort(
-    (a, b) => Number(ground(b)) - Number(ground(a))
+    (a, b) => Number(isGround(b)) - Number(isGround(a))
   )
+  // NO AFFORDANCE EVIDENCE ANYWHERE: for a producer that cannot introspect
+  // handlers (issue #3), every record answers "can I act here?" with no —
+  // silently, which is the confident-wrong-answer failure. "Nothing here is
+  // actionable" and "I couldn't tell" are different statements; when the
+  // map draws non-ground boxes but not one record carries any evidence, the
+  // result says so instead of letting silence claim the first.
+  // evidence is judged over the WHOLE wiring, not the drawn subset: a
+  // `within` crop of a map whose evidence lies outside the region is not a
+  // blind map, it's a blind REGION of a sighted one (review follow-up).
+  // And CAPABILITY evidence counts (#10): a producer that emits handlers
+  // or provenance arrows anywhere demonstrably can see wiring — absence of
+  // affordance is then a fact about the page, not the producer's eyes.
+  const blind =
+    boxes.some((w) => !isGround(w)) &&
+    !description.wiring.some(isInteractive) &&
+    !description.wiring.some(hasCapabilityEvidence)
+  const note = blind
+    ? 'no record carries affordance evidence (on, href, contentEditable, ' +
+      'a two-way binding, or an interactive/editable assertion), and none ' +
+      'shows the producer can see wiring at all (no handler, assertion, ' +
+      'or provenance arrow anywhere) — "nothing here is actionable" is ' +
+      'NOT established; a producer that cannot introspect handlers ' +
+      'should assert `interactive`/`editable` per record (see README)'
+    : undefined
   for (const w of drawOrder) {
     const index = description.wiring.indexOf(w)
     const pinOffsetX = w.viewportFixed === true ? minX + pad : 0
@@ -363,9 +576,24 @@ export const schematic = (
     //   back to its placeholder in italics (a hint must not read as content)
     // - everything else: label, then text, then value
     const toggle = w.type === 'checkbox' || w.type === 'radio'
+    // fail-closed means malformed errs toward WITHHOLDING (review F1): a
+    // truthy non-boolean secret (secret: 1 from mangled producer JSON)
+    // must scrub, not leak — every redaction gate shares this coercion
+    const secret = Boolean(w.secret)
     let caption: string
     let hint = false
-    if (isContainer) {
+    if (secret) {
+      // FAIL-CLOSED redaction (0.5.0 review G1 + round-2 B1): a secret
+      // record's withholdable facts — label, text, value, placeholder,
+      // href, and image (the captured pixels are the highest-bandwidth
+      // fact of all) — never reach the drawing, even when a producer bug
+      // left them in
+      // the record. `redacted` must never co-occur with the facts it
+      // claims were withheld; the marker is all a secret record says.
+      // (Assigned BEFORE the choke point so a forged arrow in `tag`
+      // still neutralizes — review R1.)
+      caption = `<${w.tag}> [withheld]`
+    } else if (isContainer) {
       caption = String(w.label ?? '')
     } else if (toggle) {
       caption = String(w.label ?? '')
@@ -398,18 +626,18 @@ export const schematic = (
           `<${w.tag}>`
       )
     }
-    const structural = ground(w)
-    // the affordance grammar, explicit: BOLD outline = wired to act (has
-    // handlers); a trailing ⟷ on the caption = editable here (two-way
-    // binding), added when the caption is a label that would otherwise
-    // hide it. Solid = affordance, dotted = structure.
-    const actable = !structural && w.on != null
-    const editable =
-      !structural &&
-      (w.contentEditable === true ||
-        Object.values(w).some(
-          (v) => typeof v === 'string' && v.includes(BOUND_TWO_WAY)
-        ))
+    // EVERY caption source (label, placeholder, href, tag fallback — not
+    // just the text/value paths shownValue serves) is neutralized here, at
+    // one choke point: the 0.4.0 review's B1 found the arrow defense
+    // bypassed by exactly the sources this line now covers
+    caption = neutralizeArrows(caption)
+    const structural = isGround(w)
+    // the affordance grammar, explicit: BOLD outline = wired to act —
+    // handlers, a link destination (href: a link IS an affordance, 0.4.0),
+    // or the producer's `interactive` word. The ↔ badge = editable here.
+    // Solid = affordance, dotted = structure.
+    const actable = !structural && hasActEvidence(w)
+    const editable = !structural && hasEditEvidence(w)
     const fill = structural
       ? 'none'
       : w.style != null
@@ -423,7 +651,10 @@ export const schematic = (
     // embedded media first: pixels the producer captured, drawn in place —
     // everything else (state geometry, captions, badges) reads over it
     const drawImage =
-      !structural && typeof w.image === 'string' && w.image.startsWith('data:')
+      !structural &&
+      !secret && // B1: withheld pixels never draw
+      typeof w.image === 'string' &&
+      w.image.startsWith('data:')
     // CRAMPED: the box can't legibly carry its dress — draw it bare (shape,
     // state geometry, emphasis, focus) with an auto stamp pointing into the
     // legend, where the metadata actually lives. Toggles are exempt from
@@ -432,35 +663,13 @@ export const schematic = (
       !structural && (height < minLabelHeight || width < fontSize * 3)
     // UNDERSIZED: an interactive element below the target-size floor is a
     // usability defect in its own right (WCAG 2.5.8: 24×24 AA; 44/48 is the
-    // platform touch bar) — toggles exempt as user-agent-sized controls
-    const interactive =
-      !structural &&
-      (w.on != null || w.contentEditable === true ||
-        Object.values(w).some(
-          (v) => typeof v === 'string' && v.includes(BOUND_TWO_WAY)
-        ))
-    // WCAG 2.5.8 exempts inline targets sized by their text — flagging
-    // prose links fires on every paragraph, and a check that cries wolf
-    // gets ignored, taking the real findings with it. A pure renderer
-    // can't see computed display, so: a link WITH text is presumed
-    // text-sized and exempt (icon links — an <a> wrapping an <svg>, no
-    // text — stay flagged). Producers with DOM access compute this
-    // properly and ship it via `flags`, which also SUPERSEDES the built-in
-    // audit here: no double amber bars for the same finding.
-    const producerTargetFlag =
-      Array.isArray(w.flags) &&
-      w.flags.some((f) => f.kind.toLowerCase().includes('target'))
-    const textSizedLink =
-      w.tag === 'a' && typeof w.text === 'string' && w.text !== ''
-    const undersized =
-      targetSize > 0 &&
-      interactive &&
-      !producerTargetFlag &&
-      !textSizedLink &&
-      !(w.type === 'checkbox' || w.type === 'radio') &&
-      (width < targetSize || height < targetSize)
-        ? `${width}×${height} — below ${targetSize}×${targetSize} (WCAG 2.5.8)`
-        : undefined
+    // platform touch bar). The whole rule — the interactivity predicate,
+    // the toggle and inline-link exemptions, producer-flag supersession —
+    // lives in the exported targetSizeFinding (issue #4: one
+    // implementation, shared with tosijs's audit).
+    const undersized = targetSizeFinding(w, targetSize, {
+      honorProducerFlags: true,
+    })
     const emphasis = structural
       ? ' stroke-dasharray="1 3" stroke-linecap="round" opacity="0.45"'
       : w.disabled === true
@@ -517,22 +726,27 @@ export const schematic = (
     // the LEFT edge — the unclaimed slot — plus the first flag's label
     if (!cramped && !structural && Array.isArray(w.flags) && w.flags.length > 0) {
       w.flags.forEach((flag, at) => {
-        const color = FLAG_COLORS[flag.severity ?? 'warn'] ?? FLAG_COLORS.warn
+        // kind is producer JSON too (#12) — same defence severity gets
         parts.push(
           `<rect x="${x + at * 3}" y="${y}" width="3" height="${height}" ` +
-            `fill="${color}" data-flag="${esc(flag.kind)}"/>`
+            `fill="${flagColor(flag?.severity)}" ` +
+            `data-flag="${esc(typeof flag?.kind === 'string' ? flag.kind : '')}"/>`
         )
       })
       const first = w.flags[0]
-      if (first.label && height >= minLabelHeight) {
-        const flagColor = FLAG_COLORS[first.severity ?? 'warn'] ?? FLAG_COLORS.warn
+      // producer JSON to the last line (R2): flags:[null] and non-string
+      // labels must not take down the render — same defence the forEach got
+      if (typeof first?.label === 'string' && first.label !== '' && height >= minLabelHeight) {
         parts.push(
           `<rect x="${x + w.flags.length * 3 + 1}" y="${y + height - 9}" ` +
             `width="${first.label.length * 4.5 + 2}" height="8" ` +
             `fill="white" opacity="0.85"/>`,
           `<text x="${x + w.flags.length * 3 + 2}" y="${y + height - 2}" ` +
-            `font-size="7" font-family="monospace" fill="${flagColor}">` +
-            `${esc(first.label)}</text>`
+            `font-size="7" font-family="monospace" ` +
+            `fill="${flagColor(first.severity)}">` +
+            // the drawn label is a text RUN (neutralize: rare glyphs tofu);
+            // the legend's copy of flags stays verbatim, per the spec
+            `${esc(neutralizeArrows(first.label))}</text>`
         )
       }
     }
@@ -638,12 +852,17 @@ export const schematic = (
     // a destination is always legend-worthy: it never fits a caption
     // legibly, and it's the fact an agent acts on ("goes to Y", not
     // "says X")
-    if (typeof w.href === 'string' && w.href !== '' && !structural) {
+    if (
+      typeof w.href === 'string' &&
+      w.href !== '' &&
+      !structural &&
+      !secret // G1: a withheld destination never reaches the legend
+    ) {
       elided.href = w.href
     }
     if (cramped || truncated) {
       if (shownCaption !== '' && !toggle) elided.caption = caption
-      const heldValue = shownValue(w.value)
+      const heldValue = secret ? undefined : shownValue(w.value)
       if (heldValue) elided.value = heldValue
       if (cramped) {
         if (editable) elided.editable = true
@@ -656,7 +875,12 @@ export const schematic = (
     if (w.invalid === true && cramped) elided.invalid = true
     if (w.disabled === true && cramped) elided.disabled = true
     if (undersized != null) elided.undersized = undersized
+    // redaction ALWAYS rides the legend, structural included: redacted is
+    // a fact about the record, not a drawing concern — the consumer
+    // reading "no href" must be able to tell withheld from absent (#15)
+    if (secret) elided.redacted = true
     const inLegend =
+      elided.redacted != null ||
       elided.caption != null ||
       elided.href != null ||
       elided.value != null ||
@@ -711,20 +935,27 @@ export const schematic = (
         `details in legend — match by stamped number</text>`
     )
   }
+  const descBits: string[] = []
+  if (legend.length > 0) {
+    descBits.push(
+      `${description.wiring.length} records; ${legend.length} ` +
+        'legend entries carry metadata the drawing could not — pair this ' +
+        'image with its legend JSON (schematic().legend), matched by the ' +
+        'stamped number / data-record index.'
+    )
+  }
+  if (note != null) descBits.push(note)
   parts[0] =
     `<svg xmlns="http://www.w3.org/2000/svg" viewBox="${minX} ${minY} ${
       maxX - minX
     } ${maxY - minY + footerExtra}" width="${maxX - minX}" height="${
       maxY - minY + footerExtra
     }">` +
-    (legend.length > 0
-      ? `<desc>${description.wiring.length} records; ${legend.length} ` +
-        'legend entries carry metadata the drawing could not — pair this ' +
-        'image with its legend JSON (schematic().legend), matched by the ' +
-        'stamped number / data-record index.</desc>'
-      : '')
+    (descBits.length > 0 ? `<desc>${esc(descBits.join(' '))}</desc>` : '')
   parts.push('</svg>')
-  return { svg: parts.join(''), legend }
+  const result: SchematicResult = { svg: parts.join(''), legend }
+  if (note != null) result.note = note
+  return result
 }
 
 /** the string-only form — schematic().svg, kept for drop-in compatibility */