tosijs-floorplan 0.3.0 → 0.5.0

package/README.md

@@ -88,6 +88,9 @@ One flat record per wired element. Producers may add fields beyond these —
 | `required` | `boolean` | the field is required |
 | `disabled` | `boolean` | disabled right now |
 | `contentEditable` | `boolean` | an editable region — treated as an input field |
+| `interactive` | `boolean` | 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). Asserting is truth-telling; fabricating `on` to unlock the styling would be a lie in the payload. A binding framework never needs it |
+| `editable` | `boolean` | the producer's assertion that text goes in here — the DOM-side counterpart of `contentEditable` / a two-way binding |
+| `secret` | `boolean` | the producer **withheld** facts about this element (a secret-marked region: a token lives in the destination, so neither `label` nor `href` is published). **Fail-closed on the renderer side**: a secret record's label/text/value/placeholder/href/**image** never reach the drawing or the legend even if a producer bug leaves them in the record, and any truthy `secret` scrubs (malformed errs toward withholding) — it draws `<tag> [withheld]` and its legend entry says `redacted: true` (structural records included) — "no destination" and "destination withheld" are different facts |
 | `on` | `Record<string, string \| string[]>` | handlers by event type — a path when nameable, `ƒ` (or `ƒ name`) when not |
 | `list` | `{path, idPath?}` | this element renders a collection (drawn as *ground*, not figure) |
 | `structural` | `boolean` | structure, not affordance (headings, landmarks, containers) |
@@ -98,7 +101,58 @@ One flat record per wired element. Producers may add fields beyond these —
 **Provenance tokens** (exported as `BOUND_TO_DOM` / `BOUND_TWO_WAY`): a bound
 value reads `"<shown> <arrow> <path>"` — `⟵` means state flows to the DOM
 (display), `⟷` means two-way (a user-writable affordance). A plain string
-with no arrow is a live-but-unbound value.
+with no arrow is a live-but-unbound value. The **structural arrow is the
+LAST one in the string** — the surface appends it, so consumers must split
+at the last occurrence, and an arrow token buried inside the data confers
+nothing (the renderer parses defensively: it neutralizes interior arrows to
+`<->` / `<-` in every drawn text run and in the legend's *display* fields —
+`caption` and `value` are always neutralized — and never scans
+identity/name fields (`tag`, `id`, `part`, `role`, `label`, `placeholder`,
+`type`, `description`, `href`, `ref`, `image`) for bindings at all, since
+the surface never appends an arrow to those). Two legend fields are
+**verbatim, deliberately**: `href` is an opaque destination — rewriting
+bytes inside a URL corrupts the one fact an agent acts on — and `flags`
+are copied as the producer computed them. Consumers must never parse
+provenance from either (they are in the never-scanned set; an arrow there
+is data), and must not forward them into a caption-style text run without
+neutralizing first. **Producers whose record
+content derives from untrusted sources — any DOM extractor reading page
+content — MUST neutralize both tokens inside data at the source**, as
+tosijs ≥ 1.8.0 does. This is normative because of an honest residual: a
+forged arrow in *suffix* position on a bindable field (`"data ⟷ fake.path"`
+as the entire text) is structurally indistinguishable from a real binding —
+renderer-side defense ends where the format's own syntax begins. And the
+bindable set is **open by design** (bound props ride under their own keys),
+so the never-scanned list is a denylist over an open key set: any key a
+producer invents is bindable, and arrows in it are trusted as structure.
+The defense is narrowed, not closed — producer-side neutralization remains
+the actual perimeter (issue #11). The capability scan (below) likewise
+counts an arrow in **any position** within a bindable field: under the
+format's own last-occurrence parse, "contains an arrow" and "has a
+structural arrow" are equivalent for a lone token, so a position check
+would add no security — only the #11 perimeter does.
+
+**Producers that cannot introspect handlers** (React's synthetic delegation,
+Angular's compiler output, vanilla `addEventListener` — none enumerable from
+page script) assert the affordance instead: `interactive` / `editable`, per
+record. When a map draws affordance-shaped boxes but **no** record carries
+affordance evidence (no `on`, `href`, `contentEditable`, two-way binding, or
+assertion) **and none carries capability evidence either** — a handler, an
+assertion, or a provenance arrow in a bindable field *anywhere in the map*,
+display-only `⟵` included, proves the producer can see wiring (#10: a
+read-only dashboard from a binding framework is a sighted map of an inert
+page, not a blind map) — the result carries a `note`, and the svg's
+`<desc>` repeats it,
+because "nothing here is actionable" and "the producer couldn't tell" are
+different statements, and a consumer must never mistake the second for the
+first. Two caveats pin the semantics: **partial evidence does not establish
+the rest** — on a map where some records carry evidence, a record without
+any still means *unknown*, not *inert* (the note only marks the total-blindness
+case; non-introspecting producers should assert per actable record, not rely
+on the note); and **only `interactive: true` / `editable: true` are signal** —
+`false` is indistinguishable from absent and cannot veto evidence the record
+itself carries (`on`, `href`, a binding). "Introspected and found nothing"
+currently has no encoding; propose one via issue before relying on it.
 
 **The picture is not the whole payload.** The renderer is *allowed to omit*:
 captions and badges below legibility thresholds move to the legend, keyed by
@@ -115,7 +169,7 @@ checkbox sizes.
 
 | you see | it means |
 | --- | --- |
-| **bold outline** | wired to act (has handlers) |
+| **bold outline** | wired to act — handlers, a destination (`href`: a link IS an affordance), or the producer's `interactive` assertion |
 | `↔` badge, bottom-right | editable here (two-way binding, or contenteditable) |
 | caption ending `*` | required |
 | **red corner flag**, top-left | invalid *right now* — live ValidityState, the same truth `:invalid` styles |
@@ -133,14 +187,32 @@ checkbox sizes.
 | footer strip: "N elements with details in legend" | the image's confession that it isn't the whole map — fetch `schematic().legend` (a machine-readable `<desc>` says the same) |
 
 The target-size audit honours WCAG 2.5.8's **inline exception** as far as
-pure geometry can: a link *with text* is presumed sized by its text and is
-exempt (flagging prose links would fire on every paragraph — a check that
-cries wolf gets ignored, taking the real findings with it). An icon link —
-an `<a>` wrapping an `<svg>`, no text — stays flagged. A producer with DOM
-access can compute the exception *properly* (computed display + parent text
-nodes) and ship the finding via `flags`; a producer flag whose `kind`
-mentions `target` **supersedes** the built-in audit, so the two never
-double-mark.
+pure geometry can: a link is exempt when it has text **and its box is wider
+than tall** — the shape text layout produces (flagging prose links would
+fire on every paragraph — a check that cries wolf gets ignored, taking the
+real findings with it). Icon links stay flagged: an `<a>` wrapping an
+`<svg>` with no text, and equally a **square** icon link that happens to
+carry a label or a glyph — a 16×16 box was not sized by its text, whatever
+the text is (the text-only rule exempted exactly the header-row-of-icons
+case the check was built for; haltija's issue #2 caught it). A producer
+with DOM access computes the exception *properly* (computed display +
+parent text nodes) and ships the finding via `flags` — that is the
+**intended path** for DOM producers. A producer flag whose `kind` is one
+of the **target-claim kinds** (`TARGET_FLAG_KINDS`, case-insensitive:
+`target`, `target-size`, `targetsize`, `target_size`, `smalltarget`)
+**supersedes** the drawn audit, so the two never double-mark — an explicit
+set, because a substring match let `target-ok` stand the audit down (#8);
+new target-claim kinds are added to `TARGET_FLAG_KINDS` via an issue here,
+the same additive path as any other format change, and the set is
+read-only by contract.
+Supersession is a *drawing* concern and therefore **opt-in**:
+`targetSizeFinding` ignores producer flags by default (an audit wants the
+geometry verdict regardless of what got drawn); `schematic()` passes
+`honorProducerFlags: true`. Hidden is not small: zero-size records are
+never undersized (#9). Both rules are exported (`isInteractive`,
+`targetSizeFinding`) so audits share this implementation instead of
+keeping a drifting copy — and as of 0.5.0 they reproduce an audit's
+verdicts without consumer-side normalization (#7/#8/#9/#13).
 
 Captions tell the truth in priority order: a held **value** wins (as
 `label: value` when both are known), an empty control falls back to its
@@ -154,8 +226,11 @@ geometry genuinely runs out.
 
 | export | what |
 | --- | --- |
-| `schematic(description, options?)` | the renderer's primary form — returns `{ svg, legend }`: the drawing plus the metadata it could not legibly carry (cramped/truncated/undersized records), keyed by index/ref. **Pair every raster with its legend.** |
+| `schematic(description, options?)` | the renderer's primary form — returns `{ svg, legend, note? }`: the drawing, the metadata it could not legibly carry (cramped/truncated/undersized records, keyed by index/ref), and — when no record carries affordance evidence — the note saying so. **Pair every raster with its legend.** |
 | `schematicSVG(description, options?)` | `schematic().svg` — the string-only form; each `<g>` carries `data-record="<i>"` linking back to `description.wiring[i]` (the image as index) |
+| `isInteractive(record)` | "can I act here?" — the single implementation (handlers, `href`, `contentEditable`, a structural two-way binding, or the producer's assertion; ground never). Exported so audits consume it instead of keeping a drifting copy |
+| `targetSizeFinding(record, targetSize?, {honorProducerFlags?})` | the WCAG 2.5.8 rule with the settled exemptions (toggles, text-sized links, zero-size; producer-flag supersession only when honoured — the renderer's setting, not an audit's) — the measured legend fact, or `null` |
+| `TARGET_FLAG_KINDS` | the flag kinds that claim to *be* a target-size finding and may supersede the drawn audit |
 | `rasterizeSVG(svg, {scale})` | SVG → PNG Blob for vision encoders (browser canvas; under bun/node use `@resvg/resvg-js` — rasterize at 2× so labels OCR cleanly) |
 | `boundsOf(element)` | an element's page-coordinate bounds — the natural `within` argument |
 | `BOUND_TO_DOM`, `BOUND_TWO_WAY` | the provenance tokens |

package/dist/index.d.ts

@@ -83,6 +83,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;
 }
 /** the map: only `wiring` is read. The named optional fields are the
@@ -178,16 +195,65 @@ 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;
 }
 /**
  * An element's page-coordinate bounds (the same space describe() records) —
  * the natural `within` argument for a region-scoped schematic.
  */
 export declare const boundsOf: (element: Element) => SchematicBounds;
+/**
+ * "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 declare const isInteractive: (w: SchematicRecord) => boolean;
+/** 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 declare 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 declare const TARGET_FLAG_KINDS: ReadonlySet<string>;
+export declare const targetSizeFinding: (w: SchematicRecord, targetSize?: number, { honorProducerFlags }?: {
+    honorProducerFlags?: boolean | undefined;
+}) => string | null;
 export declare const schematic: (description: SchematicDescription, options?: SchematicOptions) => SchematicResult;
 /** the string-only form — schematic().svg, kept for drop-in compatibility */
 export declare const schematicSVG: (description: SchematicDescription, options?: SchematicOptions) => string;

package/dist/index.js

@@ -4,13 +4,33 @@ var BOUND_TWO_WAY = "⟷";
 var shownValue = (v) => {
   if (typeof v !== "string")
     return;
-  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);
+};
+var neutralizeArrows = (s) => s.replaceAll(BOUND_TWO_WAY, "<->").replaceAll(BOUND_TO_DOM, "<-");
+var boundTwoWay = (v) => {
+  if (typeof v !== "string")
+    return false;
+  const at = v.lastIndexOf(BOUND_TWO_WAY);
+  return at >= 0 && at > v.lastIndexOf(BOUND_TO_DOM);
 };
+var NEVER_BOUND = new Set([
+  "tag",
+  "id",
+  "part",
+  "role",
+  "label",
+  "placeholder",
+  "type",
+  "description",
+  "href",
+  "ref",
+  "image"
+]);
+var hasTwoWayBinding = (w) => Object.entries(w).some(([key, v]) => !NEVER_BOUND.has(key) && boundTwoWay(v));
+var hasActEvidence = (w) => w.on != null || w.interactive === true || typeof w.href === "string" && w.href !== "";
+var hasEditEvidence = (w) => w.editable === true || w.contentEditable === true || hasTwoWayBinding(w);
+var hasCapabilityEvidence = (w) => w.on != null || w.interactive === true || w.editable === true || Object.entries(w).some(([key, v]) => !NEVER_BOUND.has(key) && typeof v === "string" && (v.includes(BOUND_TWO_WAY) || v.includes(BOUND_TO_DOM)));
 var boundsOf = (element) => {
   const rect = element.getBoundingClientRect();
   return {
@@ -20,6 +40,32 @@ var boundsOf = (element) => {
     height: Math.round(rect.height)
   };
 };
+var isGround = (w) => w.structural === true || w.list != null && !hasActEvidence(w) && !hasEditEvidence(w);
+var isInteractive = (w) => !isGround(w) && (hasActEvidence(w) || hasEditEvidence(w));
+var TARGET_SIZE_DEFAULT = 24;
+var TARGET_FLAG_KINDS = new Set([
+  "target",
+  "target-size",
+  "targetsize",
+  "target_size",
+  "smalltarget"
+]);
+var targetSizeFinding = (w, targetSize = TARGET_SIZE_DEFAULT, { honorProducerFlags = false } = {}) => {
+  if (targetSize <= 0 || w.bounds == null || !isInteractive(w))
+    return null;
+  const { width, height } = w.bounds;
+  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;
+  }
+  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;
+};
 var intersects = (a, b) => a.x < b.x + b.width && b.x < a.x + a.width && a.y < b.y + b.height && b.y < a.y + a.height;
 var contains = (outer, inner) => inner.x >= outer.x && inner.y >= outer.y && inner.x + inner.width <= outer.x + outer.width && inner.y + inner.height <= outer.y + outer.height;
 var esc = (s) => s.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;");
@@ -29,6 +75,7 @@ var FLAG_COLORS = {
   warn: "#e6a700",
   info: "#888888"
 };
+var flagColor = (severity) => typeof severity === "string" && Object.hasOwn(FLAG_COLORS, severity) ? FLAG_COLORS[severity] : FLAG_COLORS.warn;
 var wrapCaption = (caption, maxChars, maxLines) => {
   if (maxLines <= 1 || caption.length <= maxChars) {
     return [caption.slice(0, maxChars + 2)];
@@ -64,7 +111,7 @@ var schematic = (description, options = {}) => {
     fontSize = 11,
     within,
     index: showIndex = false,
-    targetSize = 24,
+    targetSize = TARGET_SIZE_DEFAULT,
     legendNote = true,
     decorate
   } = options;
@@ -85,8 +132,9 @@ var schematic = (description, options = {}) => {
   const parts = [
     `<svg xmlns="http://www.w3.org/2000/svg" viewBox="${minX} ${minY} ${maxX - minX} ${maxY - minY}" width="${maxX - minX}" height="${maxY - minY}">`
   ];
-  const ground = (w) => w.structural === true || w.list != null && w.on == null;
-  const drawOrder = [...boxes].sort((a, b) => Number(ground(b)) - Number(ground(a)));
+  const drawOrder = [...boxes].sort((a, b) => Number(isGround(b)) - Number(isGround(a)));
+  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;
@@ -96,9 +144,12 @@ var schematic = (description, options = {}) => {
     const { width, height } = w.bounds;
     const isContainer = w.viewportFixed !== true && boxes.some((other) => other !== w && other.viewportFixed !== true && contains(w.bounds, other.bounds));
     const toggle = w.type === "checkbox" || w.type === "radio";
+    const secret = Boolean(w.secret);
     let caption;
     let hint = false;
-    if (isContainer) {
+    if (secret) {
+      caption = `<${w.tag}> [withheld]`;
+    } else if (isContainer) {
       caption = String(w.label ?? "");
     } else if (toggle) {
       caption = String(w.label ?? "");
@@ -115,18 +166,18 @@ var schematic = (description, options = {}) => {
     } else {
       caption = String(w.label ?? shownValue(w.text) ?? shownValue(w.value) ?? w.href ?? `<${w.tag}>`);
     }
-    const structural = ground(w);
-    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)));
+    caption = neutralizeArrows(caption);
+    const structural = isGround(w);
+    const actable = !structural && hasActEvidence(w);
+    const editable = !structural && hasEditEvidence(w);
     const fill = structural ? "none" : w.style != null ? w.style.background : "transparent";
     const stroke = !structural && w.style != null && w.style.borderColor !== TRANSPARENT ? w.style.borderColor : "currentColor";
     const color = w.style != null ? w.style.color : "currentColor";
-    const drawImage = !structural && typeof w.image === "string" && w.image.startsWith("data:");
+    const drawImage = !structural && !secret && typeof w.image === "string" && w.image.startsWith("data:");
     const cramped = !structural && (height < minLabelHeight || width < fontSize * 3);
-    const interactive = !structural && (w.on != null || w.contentEditable === true || Object.values(w).some((v) => typeof v === "string" && v.includes(BOUND_TWO_WAY)));
-    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;
+    const undersized = targetSizeFinding(w, targetSize, {
+      honorProducerFlags: true
+    });
     const emphasis = structural ? ' stroke-dasharray="1 3" stroke-linecap="round" opacity="0.45"' : w.disabled === true ? ' opacity="0.4"' : actable ? ' stroke-width="2"' : "";
     parts.push(`<g data-record="${index}"${w.ref != null ? ` data-ref="${esc(String(w.ref))}"` : ""}>`);
     if (w.type === "radio") {
@@ -149,13 +200,11 @@ var schematic = (description, options = {}) => {
     }
     if (!cramped && !structural && Array.isArray(w.flags) && w.flags.length > 0) {
       w.flags.forEach((flag, at) => {
-        const color2 = FLAG_COLORS[flag.severity ?? "warn"] ?? FLAG_COLORS.warn;
-        parts.push(`<rect x="${x + at * 3}" y="${y}" width="3" height="${height}" ` + `fill="${color2}" data-flag="${esc(flag.kind)}"/>`);
+        parts.push(`<rect x="${x + at * 3}" y="${y}" width="3" height="${height}" ` + `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;
-        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>`);
+      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(first.severity)}">` + `${esc(neutralizeArrows(first.label))}</text>`);
       }
     }
     if (undersized != null) {
@@ -194,13 +243,13 @@ var schematic = (description, options = {}) => {
     const elided = { index, tag: w.tag };
     if (w.ref != null)
       elided.ref = String(w.ref);
-    if (typeof w.href === "string" && w.href !== "" && !structural) {
+    if (typeof w.href === "string" && w.href !== "" && !structural && !secret) {
       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) {
@@ -219,7 +268,9 @@ var schematic = (description, options = {}) => {
       elided.disabled = true;
     if (undersized != null)
       elided.undersized = undersized;
-    const inLegend = elided.caption != null || elided.href != null || elided.value != null || elided.editable != null || elided.required != null || elided.flags != null || elided.invalid != null || elided.disabled != null || elided.undersized != null;
+    if (secret)
+      elided.redacted = true;
+    const inLegend = elided.redacted != null || elided.caption != null || elided.href != null || elided.value != null || elided.editable != null || elided.required != null || elided.flags != null || elided.invalid != null || elided.disabled != null || elided.undersized != null;
     if (inLegend)
       legend.push(elided);
     if (showIndex || w.ref != null || inLegend) {
@@ -245,9 +296,18 @@ var schematic = (description, options = {}) => {
   if (footerExtra > 0) {
     parts.push(`<text x="${minX + pad}" y="${maxY + 10}" font-size="8" ` + `font-family="monospace" fill="currentColor" opacity="0.75">` + `${legend.length} element${legend.length === 1 ? "" : "s"} with ` + `details in legend — match by stamped number</text>`);
   }
-  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>" : "");
+  const descBits = [];
+  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}">` + (descBits.length > 0 ? `<desc>${esc(descBits.join(" "))}</desc>` : "");
   parts.push("</svg>");
-  return { svg: parts.join(""), legend };
+  const result = { svg: parts.join(""), legend };
+  if (note != null)
+    result.note = note;
+  return result;
 };
 var schematicSVG = (description, options = {}) => schematic(description, options).svg;
 var rasterizeSVG = (svg, options = {}) => {
@@ -289,10 +349,14 @@ var rasterizeSVG = (svg, options = {}) => {
   });
 };
 export {
-  schematicSVG,
-  schematic,
-  rasterizeSVG,
-  boundsOf,
+  BOUND_TO_DOM,
   BOUND_TWO_WAY,
-  BOUND_TO_DOM
+  TARGET_FLAG_KINDS,
+  TARGET_SIZE_DEFAULT,
+  boundsOf,
+  isInteractive,
+  rasterizeSVG,
+  schematic,
+  schematicSVG,
+  targetSizeFinding
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tosijs-floorplan",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Render an agent-surface map (plain records) as a floorplan SVG — the affordance grammar as a pure, dependency-free function. No DOM, no framework. Formerly tosijs-schematic.",
   "type": "module",
   "license": "Apache-2.0",
@@ -27,6 +27,8 @@
   "scripts": {
     "build": "bun build src/index.ts --outdir dist --format esm && tsc -p tsconfig.json",
     "test": "bun test",
+    "typecheck": "tsc -p tsconfig.json --noEmit --emitDeclarationOnly false",
+    "stability": "bun tools/byte-stability.ts",
     "prepublishOnly": "bun test && bun run build"
   },
   "devDependencies": {