feat(ui): cut an overlong lead at its first clause, not just its first period

Leading with "the first sentence" assumed a first sentence is short. It
often is not: 530 of the 1,709 run past 200 characters, the longest is
615, because these descriptions pack the whole scope into one sentence
behind a colon or a dash. "The bathroom rough-in check, in four numbers:
15 in from a fixture centerline to any side wall, partition, vanity, or
other obstruction; 30 in center to center between ..." is the wall of
text the rule was meant to prevent.

leadSentence() cuts a sentence over 160 characters at its first real
clause boundary, so that tile now leads with "The bathroom rough-in
check, in four numbers." Median lead 158 -> 102 characters; leads over
200, 530 -> 112. Nothing is dropped: where the lead is a clause-cut
summary, the detail below the answer carries the whole description
rather than starting mid-sentence in lower case. Verified across all
1,709 tiles that lead + detail still reconstruct the full text.

Also fixes a defect in the placeholder priming from 23be32b: on a tile
whose fields carry defaults, priming computed off those defaults and
painted a verdict before the reader had entered anything ("PASSES the
IPC 405.3.1 clearances entered" on open). Blank-vs-filled was the wrong
test. What matters is whether an answer was already on its way in -- a
deep link's input events, or a click on the example button -- so that is
what the restore now keys on.

Verified all five open paths: plain open, ?example=1, deep link,
default-prefilled tile, and clicking "Test with example".

Co-Authored-By: Claude Opus 5 <[email protected]>

Author: clay-good

app.js

@@ -8,7 +8,7 @@
 // when the user opens a tool.
 import { verifyManifestIntegrity } from "./integrity.js";
 import { parseHashRoute } from "./routing.js";
-import { firstSentence, restOfDescription } from "./text-lead.js";
+import { leadSentence, restOfDescription } from "./text-lead.js";
 
 // Recents (utility 120) was removed in v11; see specs/spec-v11.md.
 
@@ -1724,7 +1724,7 @@ function renderToolView(id, params) {
   // remainder goes below the answer, as `detail`.
   const lead = document.createElement("p");
   lead.className = "view-desc";
-  lead.textContent = firstSentence(tool.desc);
+  lead.textContent = leadSentence(tool.desc);
   view.appendChild(lead);
 
   const notice = document.createElement("div");

scripts/build-shells.mjs

@@ -24,7 +24,7 @@ import { existsSync } from "node:fs";
 import { resolve, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { CITATIONS } from "../citations.js";
-import { firstSentence, restOfDescription } from "../text-lead.js";
+import { leadSentence, restOfDescription } from "../text-lead.js";
 
 const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const DIST = resolve(ROOT, "dist");
@@ -111,7 +111,7 @@ function escapeHtml(s) {
 // word boundary; the full description is on the tile page the row links to.
 const GROUP_ROW_CAP = 150;
 function rowSummary(desc) {
-  const s = firstSentence(desc);
+  const s = leadSentence(desc);
   if (s.length <= GROUP_ROW_CAP) return s;
   const cut = s.slice(0, GROUP_ROW_CAP);
   const sp = cut.lastIndexOf(" ");
@@ -479,7 +479,7 @@ function tileShell(tool, tools, groupNames, relatedMap, examples) {
     '    </ol>',
     '  </nav>',
     `  <h1 class="shell-h1">${escapeHtml(tool.name)}</h1>`,
-    `  <p class="shell-lead">${escapeHtml(firstSentence(tool.desc))}</p>`,
+    `  <p class="shell-lead">${escapeHtml(leadSentence(tool.desc))}</p>`,
     '  <p class="shell-run">',
     // `?example=1` makes renderToolView load the same worked example this page
     // prints, so a reader who just read "awg 12 -> 24.4 A" lands on a

text-lead.js

@@ -38,9 +38,34 @@ export function firstSentence(desc) {
   return s;
 }
 
-// The description minus its first sentence, or "" when there is only one.
+// An opening sentence is not automatically a short one: 530 of them run past
+// 200 characters and the longest is 615, because these descriptions pack the
+// whole scope into one sentence behind a colon or a dash ("The bathroom
+// rough-in check, in four numbers: 15 in from a fixture centerline to ...").
+// A lead like that is the wall of text the one-sentence rule was meant to
+// avoid. So when the sentence runs long, cut it at its first real clause
+// boundary and let the full text carry the rest below the answer.
+const LEAD_CAP = 160;
+const CLAUSE = /(: | -- |; )/g;
+
+export function leadSentence(desc) {
+  const s = firstSentence(desc);
+  if (s.length <= LEAD_CAP) return s;
+  CLAUSE.lastIndex = 0;
+  let m;
+  while ((m = CLAUSE.exec(s))) {
+    if (m.index >= MIN_LEAD) return s.slice(0, m.index).replace(/[,;:\s-]+$/, "") + ".";
+  }
+  return s;
+}
+
+// The prose that belongs below the answer. When the lead is the whole opening
+// sentence, that is everything after it. When the lead is a clause-cut summary
+// of a longer sentence, it is the whole description: a Details block has to
+// read as prose, and starting one mid-sentence in lower case reads as a bug.
 export function restOfDescription(desc) {
   const s = String(desc).trim();
-  const lead = firstSentence(s);
-  return s.slice(lead.length).trim();
+  const sentence = firstSentence(s);
+  if (leadSentence(s) !== sentence) return s;
+  return s.slice(sentence.length).trim();
 }

ui-fields.js

@@ -156,12 +156,25 @@ export function attachExampleButton(host, fillFn) {
   btn.type = "button";
   btn.className = "example-btn";
   btn.textContent = "Test with example";
-  btn.addEventListener("click", fillFn);
   host.insertBefore(btn, host.firstChild);
+  // Whether an answer was already on its way in before priming started. A
+  // deep-linked tile gets real input events from applyHashState, and the
+  // ?example=1 path clicks this button -- both are meant to show a result.
+  // Anything else opens without one. Capture phase, so a renderer that fires
+  // non-bubbling events is still seen.
+  let seeded = false;
+  const mark = () => { seeded = true; };
+  btn.addEventListener("click", () => { mark(); fillFn(); });
+  host.addEventListener("input", mark, true);
+  host.addEventListener("change", mark, true);
   // Deferred: many tiles attach the button before they build their fields,
   // and the view applies deep-linked values right after the renderer returns.
   // A microtask runs after both, still before the first paint.
-  queueMicrotask(() => primeExamplePlaceholders(host, fillFn));
+  queueMicrotask(() => {
+    host.removeEventListener("input", mark, true);
+    host.removeEventListener("change", mark, true);
+    primeExamplePlaceholders(host, fillFn, seeded);
+  });
   return btn;
 }
 
@@ -172,19 +185,19 @@ export function attachExampleButton(host, fillFn) {
 // rendered fields, copy what it wrote into placeholders, and put every field
 // back exactly as it was. Fields that already hold a value -- a tile default or
 // a deep-linked one -- keep it and get no placeholder.
-function primeExamplePlaceholders(host, fillFn) {
+function primeExamplePlaceholders(host, fillFn, seeded) {
   // The view can already be gone by the time the microtask runs -- a fast
   // hash change, or a catalog-wide sweep. Priming a detached region is pure
   // cost, so skip it.
   if (host.isConnected === false) return;
   const els = Array.from(host.querySelectorAll("input, select, textarea"));
   if (!els.length) return;
   const before = els.map((el) => ({ el, value: el.value, checked: el.checked }));
-  // A tile opened blank must still read blank once priming is done. A tile
-  // opened with deep-linked or default values is meant to show its answer, so
-  // leave that answer alone.
-  const startedBlank = before.every((snap) => !isTextish(snap.el) || !snap.value);
-  const restoreOutputs = startedBlank ? snapshotOutputs(host) : () => {};
+  // A tile that was not going to show an answer must not start showing one.
+  // That includes tiles whose fields carry defaults: computing off a default
+  // nobody chose would put a confident verdict on screen before the reader has
+  // typed anything.
+  const restoreOutputs = seeded ? () => {} : snapshotOutputs(host);
   try {
     fillFn();
   } catch {
@@ -213,16 +226,17 @@ function primeExamplePlaceholders(host, fillFn) {
     el.dispatchEvent(new Event("change", { bubbles: false }));
   }
   // The filler's compute is debounced, so it lands well after the restore
-  // above. Watch the answer region and undo any write until it settles: a tile
-  // opened blank has to stay blank, and reverting inside the observer callback
-  // means no intermediate frame is ever painted or observable.
-  const stillBlank = () => before.every((snap) => !isTextish(snap.el) || !snap.el.value);
-  restoreOutputs(stillBlank);
+  // above. Watch the answer region and undo any write until it settles;
+  // reverting inside the observer callback means no intermediate frame is ever
+  // painted or observable. Once a field differs from what priming put back,
+  // the reader has typed and the answer on screen is theirs.
+  const untouched = () => before.every((snap) => snap.el.value === snap.value && snap.el.checked === snap.checked);
+  restoreOutputs(untouched);
   const out = outputRegionFor(host);
-  if (startedBlank && out && typeof MutationObserver === "function") {
-    const obs = new MutationObserver(() => restoreOutputs(stillBlank));
+  if (!seeded && out && typeof MutationObserver === "function") {
+    const obs = new MutationObserver(() => restoreOutputs(untouched));
     obs.observe(out, { childList: true, subtree: true, characterData: true });
-    setTimeout(() => { restoreOutputs(stillBlank); obs.disconnect(); }, DEBOUNCE_MS * 4);
+    setTimeout(() => { restoreOutputs(untouched); obs.disconnect(); }, DEBOUNCE_MS * 4);
   }
 }
 
@@ -236,7 +250,7 @@ function outputRegionFor(host) {
 }
 
 // Capture the answer region's current text so priming can put it back. The
-// returned restore takes a predicate: once the reader has typed something, the
+// returned restore takes a predicate: once the reader has changed a field, the
 // answer on screen is theirs and must be left alone. Returns a no-op when the
 // tile has no sibling output region.
 function snapshotOutputs(host) {
@@ -245,8 +259,8 @@ function snapshotOutputs(host) {
   const leaves = Array.from(out.querySelectorAll("*"))
     .filter((el) => !el.firstElementChild)
     .map((el) => ({ el, text: el.textContent }));
-  return (stillBlank) => {
-    if (stillBlank && !stillBlank()) return;
+  return (untouched) => {
+    if (untouched && !untouched()) return;
     for (const leaf of leaves) {
       if (leaf.el.textContent !== leaf.text) leaf.el.textContent = leaf.text;
     }