@nodegx/mcp 0.2.0 → 0.2.2

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nodegx-mcp-bundles",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "private": true,
   "description": "Build metadata for the bundled CLIs beside it. See build-cloud-bundle.mjs: @noodl/platform reads it."
 }

package/dist/render-harness/data/node-catalog-enriched.json

@@ -5355,14 +5355,16 @@
         "runtimeBehavior": "Ports are mirrored from the targeted cloud function component by the editor's CloudFunctionAdapter. The `function` input (edit-only) lists every component that contains a `noodl.cloud.request` node — cloud function components live under the `/#__cloud__/` sheet, and the parameter stores the component name without that prefix. Each name in the Request node's `params` list becomes an `in-<name>` input; each name in the Response nodes' `params` lists becomes an `out-<name>` output. All are type '*'; an authoring tool must read the target component's Request/Response `params` to know which ports exist.",
         "examples": [
           "fn-cloud-function-roundtrip",
-          "fn-aggregate-stats-function"
+          "fn-aggregate-stats-function",
+          "fn-play-audio-a-cloud-function-returns"
         ],
         "patterns": [
           "Button `onClick` → `call`, `out-<name>` → visual inputs: the request/response cycle for an action the client must not perform itself.",
           "`done` → a Query Records fetch action: refresh client data after a server-side write."
         ],
         "antiPatterns": [
-          "Wiring `out-` outputs somewhere without also handling `failure` leaves errors invisible — surface `error` in the UI or react to `failure`."
+          "Wiring `out-` outputs somewhere without also handling `failure` leaves errors invisible — surface `error` in the UI or react to `failure`.",
+          "Putting a new WAV header around audio a function returns, or re-encoding it: an API's audio is almost always a finished file (audio/wav, audio/mpeg), and wrapping it again plays its header as a click and anything after the samples as loud static. Return the base64 and its MIME type, and play it as it came; only audio/L16 or audio/pcm is raw samples (example fn-play-audio-a-cloud-function-returns)."
         ],
         "relatedNodes": [
           "noodl.cloud.request",
@@ -69597,7 +69599,8 @@
         "runtimeBehavior": "Each name in the `params` stringlist becomes a runtime-registered input (stored as `pm-<name>`, type '*') collected into the success reply. Declared port groups make the ports conditional on `status`: `params` (and its `pm-` inputs) exist while status is 'success' or unset, `errorMessage` exists while status is 'failure'. CloudFunctionAdapter mirrors the union of all Response nodes' `params` onto the browser-side caller as `out-<name>` outputs.",
         "examples": [
           "fn-cloud-function-roundtrip",
-          "fn-aggregate-stats-function"
+          "fn-aggregate-stats-function",
+          "fn-play-audio-a-cloud-function-returns"
         ],
         "patterns": [
           "Two Response nodes — one with status 'success', one with status 'failure' and an `errorMessage` — triggered from the two branches of a Condition: explicit success/failure replies.",
@@ -82118,9 +82121,9 @@
             {
               "id": "call_stats",
               "type": "CloudFunction2",
-              "label": "Call TaskStats",
+              "label": "Call Task Stats",
               "parameters": {
-                "function": "TaskStats"
+                "function": "Cloud Functions/Task Stats"
               }
             }
           ],
@@ -82140,7 +82143,7 @@
           ]
         },
         {
-          "name": "/Cloud Functions/Task Stats",
+          "name": "/#__cloud__/Cloud Functions/Task Stats",
           "nodes": [
             {
               "id": "fn_request",
@@ -82271,9 +82274,9 @@
             {
               "id": "call_add",
               "type": "CloudFunction2",
-              "label": "Call AddNumbers",
+              "label": "Call Add Numbers",
               "parameters": {
-                "function": "AddNumbers"
+                "function": "Cloud Functions/Add Numbers"
               }
             }
           ],
@@ -82305,7 +82308,7 @@
           ]
         },
         {
-          "name": "/Cloud Functions/Add Numbers",
+          "name": "/#__cloud__/Cloud Functions/Add Numbers",
           "nodes": [
             {
               "id": "fn_request",
@@ -82361,6 +82364,236 @@
         }
       ]
     },
+    {
+      "id": "fn-play-audio-a-cloud-function-returns",
+      "title": "Speak a phrase: text-to-speech in a cloud function, played in the page as it came",
+      "description": "A text-to-speech (TTS) API is called from a cloud function, so its key stays on the server, and the page plays what comes back. Three decisions matter. First, the key is a NAME: Secret reads GEMINI_API_KEY from the backend's secrets, the Function sends it in the x-goog-api-key header (never in the URL, which ends up in logs), and the key is never a port value the page can see. Second, and the one that is easy to get wrong: the audio an API returns today is almost always a FINISHED FILE (WAV, MP3 or OGG, with its own header, and sometimes extra chunks after the samples), so the cloud function passes the base64 and its MIME type through untouched and the page plays it as it is. Only a MIME type that says raw samples (audio/L16 or audio/pcm, which older Gemini text-to-speech returned) needs a WAV header put around it. Wrapping a finished file in a second header plays its first header as a click and anything after the samples as half a second of loud static. Gemini's current text-to-speech model returns audio/wav, so the wrap branch does not run for it. Third, failures stay readable: a script that threw answers through a failure Response with its own message, and a missing secret answers with a fixed sentence, because the Secret's own error names a server path the page should not show. Playback is a Function calling `new Audio(...)`, run from the call's Done; the call starts from a press, so the browser allows sound. In this function the value inputs have Run On Value Change unticked, because a signal runs each Function.",
+      "demonstrates": [
+        "CloudFunction2",
+        "noodl.cloud.request",
+        "noodl.cloud.secret",
+        "noodl.cloud.response",
+        "JavaScriptFunction"
+      ],
+      "components": [
+        {
+          "name": "/Phrase Screen",
+          "nodes": [
+            {
+              "id": "root",
+              "type": "Group",
+              "label": "Screen",
+              "parameters": {
+                "flexDirection": "column"
+              },
+              "children": [
+                "phrase_input",
+                "say_btn",
+                "status_text"
+              ]
+            },
+            {
+              "id": "phrase_input",
+              "type": "net.noodl.controls.textinput",
+              "label": "Phrase",
+              "parent": "root",
+              "parameters": {
+                "placeholder": "Bonjour"
+              }
+            },
+            {
+              "id": "say_btn",
+              "type": "net.noodl.controls.button",
+              "label": "Say it",
+              "parent": "root",
+              "parameters": {
+                "label": "Say it"
+              }
+            },
+            {
+              "id": "status_text",
+              "type": "Text",
+              "label": "What went wrong",
+              "parent": "root"
+            },
+            {
+              "id": "call_speak",
+              "type": "CloudFunction2",
+              "label": "Call Speak",
+              "parameters": {
+                "function": "Speak"
+              }
+            },
+            {
+              "id": "play",
+              "type": "JavaScriptFunction",
+              "label": "Play it as it came",
+              "parameters": {
+                "functionScript": "const audio = Inputs.audio;\nconst mimeType = String(Inputs.mimeType || 'audio/mpeg');\nif (!audio) return;\n\n// A finished file (audio/wav, audio/mpeg, audio/ogg ...) plays exactly as it came.\nlet url = 'data:' + mimeType + ';base64,' + audio;\n\n// Only raw 16-bit samples need a WAV header around them.\nif (/^audio\\/(l16|pcm)/i.test(mimeType)) {\n  const rate = Number((/rate=(\\d+)/i.exec(mimeType) || [])[1]) || 24000;\n  const samples = Uint8Array.from(atob(audio), (c) => c.charCodeAt(0));\n  const wav = new DataView(new ArrayBuffer(44 + samples.length));\n  const text = (at, s) => [...s].forEach((ch, i) => wav.setUint8(at + i, ch.charCodeAt(0)));\n  text(0, 'RIFF'); wav.setUint32(4, 36 + samples.length, true); text(8, 'WAVE');\n  text(12, 'fmt '); wav.setUint32(16, 16, true); wav.setUint16(20, 1, true); wav.setUint16(22, 1, true);\n  wav.setUint32(24, rate, true); wav.setUint32(28, rate * 2, true); wav.setUint16(32, 2, true); wav.setUint16(34, 16, true);\n  text(36, 'data'); wav.setUint32(40, samples.length, true);\n  new Uint8Array(wav.buffer, 44).set(samples);\n  let bytes = '';\n  new Uint8Array(wav.buffer).forEach((b) => (bytes += String.fromCharCode(b)));\n  url = 'data:audio/wav;base64,' + btoa(bytes);\n}\n\nawait new Audio(url).play();",
+                "runOnChange-in-audio": false,
+                "runOnChange-in-mimeType": false
+              }
+            }
+          ],
+          "connections": [
+            {
+              "fromId": "phrase_input",
+              "fromProperty": "onTextChanged",
+              "toId": "call_speak",
+              "toProperty": "in-text"
+            },
+            {
+              "fromId": "say_btn",
+              "fromProperty": "onClick",
+              "toId": "call_speak",
+              "toProperty": "call"
+            },
+            {
+              "fromId": "call_speak",
+              "fromProperty": "out-audio",
+              "toId": "play",
+              "toProperty": "in-audio"
+            },
+            {
+              "fromId": "call_speak",
+              "fromProperty": "out-mimeType",
+              "toId": "play",
+              "toProperty": "in-mimeType"
+            },
+            {
+              "fromId": "call_speak",
+              "fromProperty": "done",
+              "toId": "play",
+              "toProperty": "run"
+            },
+            {
+              "fromId": "call_speak",
+              "fromProperty": "error",
+              "toId": "status_text",
+              "toProperty": "text"
+            }
+          ]
+        },
+        {
+          "name": "/#__cloud__/Speak",
+          "nodes": [
+            {
+              "id": "speak_request",
+              "type": "noodl.cloud.request",
+              "label": "Say this",
+              "parameters": {
+                "params": "text"
+              }
+            },
+            {
+              "id": "speak_key",
+              "type": "noodl.cloud.secret",
+              "label": "GEMINI_API_KEY",
+              "parameters": {
+                "name": "GEMINI_API_KEY"
+              }
+            },
+            {
+              "id": "speak_tts",
+              "type": "JavaScriptFunction",
+              "label": "Ask for the audio, pass it through",
+              "parameters": {
+                "functionScript": "const key = Inputs.key;\nconst text = String(Inputs.text || '');\nif (!key || !text) return;\n\nconst model = 'gemini-3.8-flash-tts';\nconst response = await fetch('https://generativelanguage.googleapis.com/v1beta/models/' + model + ':generateContent', {\n  method: 'POST',\n  headers: { 'content-type': 'application/json', 'x-goog-api-key': key },\n  body: JSON.stringify({\n    contents: [{ parts: [{ text }] }],\n    generationConfig: {\n      responseModalities: ['AUDIO'],\n      speechConfig: { voiceConfig: { prebuiltVoiceConfig: { voiceName: 'Kore' } } }\n    }\n  })\n});\nconst body = await response.json();\nif (!response.ok) throw new Error((body.error && body.error.message) || 'Text-to-speech refused the request');\n\nconst part = body.candidates && body.candidates[0] && body.candidates[0].content && body.candidates[0].content.parts[0];\nconst audio = part && part.inlineData;\nif (!audio || !audio.data) throw new Error('Text-to-speech sent no audio');\n\n// Pass the audio through exactly as it came: do not decode it, re-encode it or add a header here.\nOutputs.audio = audio.data;\nOutputs.mimeType = audio.mimeType;",
+                "runOnChange-in-key": false,
+                "runOnChange-in-text": false
+              }
+            },
+            {
+              "id": "speak_ok",
+              "type": "noodl.cloud.response",
+              "label": "The audio, and what kind it is",
+              "parameters": {
+                "params": "audio,mimeType"
+              }
+            },
+            {
+              "id": "speak_failed",
+              "type": "noodl.cloud.response",
+              "label": "Why not",
+              "parameters": {
+                "status": "failure"
+              }
+            },
+            {
+              "id": "speak_not_set_up",
+              "type": "noodl.cloud.response",
+              "label": "Not set up yet",
+              "parameters": {
+                "status": "failure",
+                "errorMessage": "Speech is not set up yet: add GEMINI_API_KEY to the backend's secrets."
+              }
+            }
+          ],
+          "connections": [
+            {
+              "fromId": "speak_request",
+              "fromProperty": "receive",
+              "toId": "speak_key",
+              "toProperty": "fetch"
+            },
+            {
+              "fromId": "speak_request",
+              "fromProperty": "pm-text",
+              "toId": "speak_tts",
+              "toProperty": "in-text"
+            },
+            {
+              "fromId": "speak_key",
+              "fromProperty": "value",
+              "toId": "speak_tts",
+              "toProperty": "in-key"
+            },
+            {
+              "fromId": "speak_key",
+              "fromProperty": "done",
+              "toId": "speak_tts",
+              "toProperty": "run"
+            },
+            {
+              "fromId": "speak_key",
+              "fromProperty": "failure",
+              "toId": "speak_not_set_up",
+              "toProperty": "send"
+            },
+            {
+              "fromId": "speak_tts",
+              "fromProperty": "out-audio",
+              "toId": "speak_ok",
+              "toProperty": "pm-audio"
+            },
+            {
+              "fromId": "speak_tts",
+              "fromProperty": "out-mimeType",
+              "toId": "speak_ok",
+              "toProperty": "pm-mimeType"
+            },
+            {
+              "fromId": "speak_tts",
+              "fromProperty": "success",
+              "toId": "speak_ok",
+              "toProperty": "send"
+            },
+            {
+              "fromId": "speak_tts",
+              "fromProperty": "error",
+              "toId": "speak_failed",
+              "toProperty": "errorMessage"
+            },
+            {
+              "fromId": "speak_tts",
+              "fromProperty": "failure",
+              "toId": "speak_failed",
+              "toProperty": "send"
+            }
+          ]
+        }
+      ]
+    },
     {
       "id": "fn-send-notification-email",
       "title": "Cloud function that sends an email notification",

package/dist/render-harness/drive-steps.js

@@ -492,6 +492,122 @@ var require_src = __commonJS({
   // viewport height with content laid out past it is clipped; a page that is
   // simply short has nothing past it. That difference is the whole of
   // \`clipped-page\`, and neither number alone can tell them apart.
+  // P112-OWN019-LAPTOPGAPS (R39) \u2014 where the INK is, not where the boxes are. Richard on RL1's laptop page: a
+  // feature number in a Columns "1 4" row had a fifth of the page to itself, ~215 px of nothing before its title;
+  // L1's pricing toggle and price sat ~260 px left of their centred heading. Every box there is well-formed \u2014 the
+  // number's column box abuts the title's \u2014 so the measure is each child's ink: the union of its shown text runs
+  // (a Range, so a full-width text block counts only as far as its words reach) and its painted boxes. Desktop only:
+  // that is where a row has room to open a hole. Raw numbers here; the judgement is summarise's.
+  const layout = { rowGaps: [], drifts: [] };
+  // (The API guard is for the fake DOMs the unit suites hand this expression; every browser has both.)
+  if (vw >= 1024 && typeof document.createRange === 'function' && typeof document.createTreeWalker === 'function') {
+    const shown = new Set(visible);
+    const textInk = [];
+    const range = document.createRange();
+    const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);
+    for (let n = walker.nextNode(); n; n = walker.nextNode()) {
+      if (!n.textContent.trim() || !shown.has(n.parentElement)) continue;
+      range.selectNodeContents(n);
+      const r = range.getBoundingClientRect();
+      if (r.width > 0 && r.height > 0) textInk.push({ node: n, r });
+    }
+    const PAINTED_TAGS = ['IMG', 'SVG', 'CANVAS', 'VIDEO', 'INPUT', 'TEXTAREA', 'SELECT', 'BUTTON', 'svg'];
+    const paintedInk = visible
+      .filter((el) => {
+        if (PAINTED_TAGS.includes(el.tagName)) return true;
+        const cs = styleOf(el);
+        const bg = cs.backgroundColor;
+        return (bg && bg !== 'transparent' && !/rgba\\([^)]*,\\s*0\\)$/.test(bg)) || cs.backgroundImage !== 'none' || parseFloat(cs.borderTopWidth) > 0;
+      })
+      .map((el) => ({ el, r: el.getBoundingClientRect() }))
+      .filter((p) => p.r.width > 0 && p.r.height > 0 && p.r.width < vw * 0.98);
+    const inkOf = (el) => {
+      let l = Infinity, t = Infinity, rr = -Infinity, b = -Infinity, text = '';
+      const take = (r) => { l = Math.min(l, r.left); t = Math.min(t, r.top); rr = Math.max(rr, r.right); b = Math.max(b, r.bottom); };
+      for (const x of textInk) if (el.contains(x.node)) { take(x.r); if (!text) text = x.node.textContent.trim().slice(0, 50); }
+      for (const p of paintedInk) if (el === p.el || el.contains(p.el)) take(p.r);
+      return l === Infinity ? null : { left: l, top: t, right: rr, bottom: b, width: rr - l, height: b - t, text };
+    };
+    const ROW_GAP_MIN_PX = 160;
+    for (const parent of visible) {
+      const kids = [...parent.children].filter((k) => shown.has(k));
+      if (kids.length < 2) continue;
+      const pr = parent.getBoundingClientRect();
+      if (pr.width < 600) continue;
+      const inks = kids.map(inkOf).filter(Boolean);
+      if (inks.length < 2) continue;
+      // Side by side: consecutive by left edge, overlapping vertically, the second starting after the first ends.
+      const byLeft = [...inks].sort((a, b) => a.left - b.left);
+      for (let i = 1; i < byLeft.length; i++) {
+        const a = byLeft[i - 1], b = byLeft[i];
+        const overlap = Math.min(a.bottom, b.bottom) - Math.max(a.top, b.top);
+        const gap = b.left - a.right;
+        if (overlap <= 0 || gap < ROW_GAP_MIN_PX) continue;
+        layout.rowGaps.push({ cls: cls(parent), gap: round(gap), rowWidth: round(pr.width), tallest: round(Math.max(a.height, b.height)), left: a.text, right: b.text });
+      }
+      // Stacked, each starting below the one before, and the parts of ONE section: every part under 240 px tall (a
+      // page whose children are whole sections compared section against section \u2014 measured on L1 and GL1, s5). The
+      // section's axis is set by a centred part among its first two (its heading, usually); L1's pricing is just
+      // two parts, a centred heading block and a toggle-and-price group ~260 px left of it.
+      const byTop = [...inks].sort((a, b) => a.top - b.top);
+      if (!byTop.every((k, i) => i === 0 || k.top >= byTop[i - 1].bottom - 2)) continue;
+      // Two or more tall parts, not one: RL1's waitlist is eyebrow, heading, line and a 290 px form card in ONE group,
+      // and "any part > 240" skipped it \u2014 Richard saw the eyebrow off the centred heading (s6). A page of sections
+      // has many tall children; a section with one card has one.
+      if (byTop.filter((k) => k.height > 240).length > 1) continue;
+      const centre = pr.left + pr.width / 2;
+      const offOf = (k) => k.left + k.width / 2 - centre;
+      const centred = byTop.filter((k) => Math.abs(offOf(k)) <= 12 && k.width < pr.width * 0.9);
+      if (!centred.some((k) => byTop.indexOf(k) < 2)) continue;
+      for (const k of byTop) {
+        if (Math.abs(offOf(k)) > 40 && k.width < pr.width * 0.8) {
+          layout.drifts.push({ cls: cls(parent), offBy: round(offOf(k)), sectionWidth: round(pr.width), text: k.text, centredText: centred[0].text });
+        }
+      }
+    }
+  }
+
+  // P112-OWN019-LETTEREDGE \u2014 words hard against the edge of the box that frames them. Richard on TL2's hero: seven
+  // outlined day chips, each letter pressed to its chip's left edge. The chip Group centred its child the way CSS
+  // would, but a Text stretches to its Group's width and sets its letters left, so the centring moved nothing. The
+  // frame is the nearest of the text's first four ancestors with a border or a fill (a page-wide band is not a frame,
+  // nor an inline highlight); the reading is the gap between the words' own ink (a Range) and the frame's inner left
+  // and right edges. Every width: a chip is a chip on a phone too. Raw numbers here; the judgement is summarise's.
+  layout.edgeTexts = [];
+  const EDGE_TEXT_MAX_GAP = 3;
+  if (typeof document.createRange === 'function' && typeof document.createTreeWalker === 'function') {
+    const shown = new Set(visible);
+    const range = document.createRange();
+    const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);
+    const framed = (el) => {
+      const cs = styleOf(el);
+      if (cs.display === 'inline') return false;
+      const bg = cs.backgroundColor;
+      return (bg && bg !== 'transparent' && !/rgba\\([^)]*,\\s*0\\)$/.test(bg)) || cs.backgroundImage !== 'none' ||
+        parseFloat(cs.borderLeftWidth) > 0 || parseFloat(cs.borderRightWidth) > 0;
+    };
+    const frames = new Set();
+    for (let n = walker.nextNode(); n; n = walker.nextNode()) {
+      const text = n.textContent.trim();
+      if (!text || !shown.has(n.parentElement)) continue;
+      let frame = null;
+      for (let e = n.parentElement, i = 0; e && e !== document.body && i < 4; e = e.parentElement, i++) {
+        if (framed(e)) { frame = e; break; }
+      }
+      if (!frame || frames.has(frame)) continue;
+      const fr = frame.getBoundingClientRect();
+      if (fr.width < 16 || fr.width >= vw * 0.98) continue;
+      range.selectNodeContents(n);
+      const r = range.getBoundingClientRect();
+      if (!(r.width > 0 && r.height > 0)) continue;
+      const fcs = styleOf(frame);
+      const left = r.left - (fr.left + (parseFloat(fcs.borderLeftWidth) || 0));
+      const right = fr.right - (parseFloat(fcs.borderRightWidth) || 0) - r.right;
+      frames.add(frame);
+      if (Math.min(left, right) < EDGE_TEXT_MAX_GAP) layout.edgeTexts.push({ cls: cls(frame), text: text.slice(0, 50), left: round(left), right: round(right), frameWidth: round(fr.width), frameHeight: round(fr.height) });
+    }
+  }
+
   const contentBottom = visible.reduce((lowest, el) => {
     const r = el.getBoundingClientRect();
     return r.width > 0 && r.height > 0 && r.bottom > lowest ? r.bottom : lowest;
@@ -499,6 +615,7 @@ var require_src = __commonJS({
 
   return {
     lists,
+    layout,
     // FLD-012 AC3 \u2014 the SIZE of the population every rule below is computed over, and the number of
     // elements the visibility correction took out of it. Reported directly because a rule's finding
     // count can move for several reasons at once, and 'the fix changed what is measured' is a
@@ -637,9 +754,24 @@ var require_src = __commonJS({
        */
       SingleGround: "single-ground",
       NoImagery: "no-imagery",
-      NoDisplayType: "no-display-type"
+      NoDisplayType: "no-display-type",
+      /**
+       * P112-OWN019-LAPTOPGAPS (R39, Richard 2026-10-14). On a laptop, two things side by side in one row with a hole
+       * between their ink — RL1's feature number given a fifth of the page by a Columns "1 4" row, L1's text and card
+       * pushed to the row's two edges. A warning: a hole can be meant, and the screenshots are the arbiter.
+       */
+      RowGap: "row-gap",
+      /** P112-OWN019-LAPTOPGAPS — a section that centres its heading and leaves another part off that centre (L1's price). */
+      AlignmentDrift: "alignment-drift",
+      /**
+       * P112-OWN019-LETTEREDGE (Richard 2026-10-15, TL2's hero). Words within 3 px of the inner left or right edge of the
+       * box that frames them (a border or a fill) — a letter in an outlined chip set left because its Text stretched.
+       */
+      TextAgainstEdge: "text-against-edge"
     };
     var SEVERITY_ORDER = { error: 0, warning: 1, info: 2 };
+    var ROW_GAP_MIN_TALLEST = 48;
+    var ROW_GAP_MIN_SHARE = 0.12;
     var POVERTY_FINDINGS = [RenderFinding.SingleGround, RenderFinding.NoImagery, RenderFinding.NoDisplayType];
     function isPovertyFinding(finding) {
       return Boolean(finding) && POVERTY_FINDINGS.indexOf(finding.code) !== -1;
@@ -855,6 +987,43 @@ var require_src = __commonJS({
             evidence: v.grounds.values
           });
         }
+        if (isDesktop && v.layout) {
+          const gaps = (v.layout.rowGaps || []).filter((g) => (g.left || g.right) && g.tallest >= ROW_GAP_MIN_TALLEST && g.gap >= g.rowWidth * ROW_GAP_MIN_SHARE);
+          const seen2 = /* @__PURE__ */ new Set();
+          for (const g of gaps) {
+            const key = `${g.left}|${g.right}`;
+            if (seen2.has(key) || seen2.size >= 3) continue;
+            seen2.add(key);
+            add({
+              code: RenderFinding.RowGap,
+              severity: "warning",
+              viewport: name,
+              message: `"${g.left}" and "${g.right}" sit side by side with ${g.gap}px of empty space between them (${Math.round(g.gap / g.rowWidth * 100)}% of the ${g.rowWidth}px row). A label or number beside text reads as one thing at its own width with a small gap \u2014 a row Group, the label at its natural width and the text growing \u2014 not a column given a share of the page (Columns widths are proportions); two parts pushed to a wide row's edges leave the same hole: give the row a max width and a gap. Look at this width's screenshot.`,
+              evidence: g
+            });
+          }
+          const drifts = (v.layout.drifts || []).slice(0, 3);
+          for (const d of drifts) {
+            add({
+              code: RenderFinding.AlignmentDrift,
+              severity: "warning",
+              viewport: name,
+              message: `This section centres "${d.centredText}", but "${d.text}" sits ${Math.abs(d.offBy)}px ${d.offBy < 0 ? "left" : "right"} of that centre. One section, one alignment: centre the rest too, or align everything to the same left edge. Look at this width's screenshot.`,
+              evidence: d
+            });
+          }
+        }
+        const edges = v.layout && v.layout.edgeTexts || [];
+        if (edges.length) {
+          const named = edges.slice(0, 3).map((e) => `"${e.text}" ${Math.max(0, Math.min(e.left, e.right))}px from the ${e.left <= e.right ? "left" : "right"} edge of its ${e.frameWidth}\xD7${e.frameHeight}px box`);
+          add({
+            code: RenderFinding.TextAgainstEdge,
+            severity: "warning",
+            viewport: name,
+            message: `${plural(edges.length, "text sits", "texts sit")} hard against the edge of the outlined or filled box that frames ${edges.length === 1 ? "it" : "them"}: ${named.join("; ")}. Centring a Group does not centre a Text's letters \u2014 the Text stretches to the Group's width and sets them left \u2014 so give the Text textAlignX: center, or give the box padding. Look at this width's screenshot.`,
+            evidence: edges.slice(0, 6)
+          });
+        }
         if (v.consoleErrors && v.consoleErrors.length) {
           add({
             code: RenderFinding.ConsoleError,
@@ -964,6 +1133,7 @@ var require_render_report = __commonJS({
     var WS_MODULE = HARNESS_PATHS.WS_MODULE.path;
     var {
       DEFAULT_VIEWPORTS,
+      NAMED_VIEWPORTS,
       DESKTOP_WIDTH,
       RenderFinding,
       SEVERITY_ORDER,
@@ -1499,7 +1669,7 @@ var require_render_report = __commonJS({
     }
     function parseViewports2(spec) {
       if (!spec) return DEFAULT_VIEWPORTS;
-      const known = new Map(DEFAULT_VIEWPORTS.map((v) => [v.name, v]));
+      const known = new Map(NAMED_VIEWPORTS.map((v) => [v.name, v]));
       return spec.split(",").map((token) => {
         const trimmed = token.trim();
         if (known.has(trimmed)) return known.get(trimmed);
@@ -2312,10 +2482,12 @@ function locateExpression(target) {
     if (all.length === 0) return { found: false, matched: 0 };
     let last;
     for (const el of all) {
-      el.scrollIntoView({ block: 'center', inline: 'center' });
+      // 'instant': under \`html { scroll-behavior: smooth }\` a plain scrollIntoView glides, the rect below is read
+      // before it arrives, and every target off screen was refused as off screen (P112-OWN019-TAPHOLD, L1's page).
+      el.scrollIntoView({ block: 'center', inline: 'center', behavior: 'instant' });
       const r = el.getBoundingClientRect();
       const x = r.left + r.width / 2, y = r.top + r.height / 2;
-      if (x < 0 || y < 0 || x >= innerWidth || y >= innerHeight) { last = { x, y, offscreen: true, wouldHit: 'nothing (off screen)' }; continue; }
+      if (x < 0 || y < 0 || x >= innerWidth || y >= innerHeight) { last = { x, y, offscreen: true, wouldHit: 'nothing (off screen)', target: describe(el) }; continue; }
       // Lent pointer-events for the one measurement: elementFromPoint skips an element that has none.
       const before = el.style.pointerEvents;
       el.style.pointerEvents = 'auto';
@@ -2540,6 +2712,20 @@ async function runSteps(page, steps, { outDir, stubs = routeStubs(page), network
     const value = JSON.parse(last);
     return value && typeof value === "object" ? { ...value, settledMs: Date.now() - t0 } : value;
   };
+  const SCROLLS = `(() => { const a = [scrollX, scrollY]; for (const e of document.querySelectorAll('*')) if (e.scrollTop || e.scrollLeft) a.push(e.scrollTop, e.scrollLeft); return a.join(','); })()`;
+  const scrollSettled = async () => {
+    const t0 = Date.now();
+    let last = await evaluate(SCROLLS);
+    let moved = false;
+    for (let same = 0; same < 2 && Date.now() - t0 < 2e3; ) {
+      await frames();
+      const next = await evaluate(SCROLLS);
+      if (next === last) same++;
+      else same = 0, moved = true;
+      last = next;
+    }
+    return moved ? { scrolledMs: Date.now() - t0, still: Date.now() - t0 >= 2e3 } : null;
+  };
   const press = async (target) => {
     let p = await evaluate(locateExpression(target));
     for (let i = 0; i < 20 && !p.found; i++) {
@@ -2576,6 +2762,11 @@ async function runSteps(page, steps, { outDir, stubs = routeStubs(page), network
         row.pressed = p.target;
         if (p.matched > 1) row.matched = p.matched;
         await frames();
+        const glide = await scrollSettled();
+        if (glide) {
+          row.scrolledMs = glide.scrolledMs;
+          if (glide.still) row.stillScrolling = true;
+        }
       } else if (verb === "type") {
         if (typeof step.type !== "string") throw new UsageError(`Step ${i + 1}: type takes a string.`);
         if (step.into !== void 0) await press(step.into);
@@ -2629,27 +2820,40 @@ async function runSteps(page, steps, { outDir, stubs = routeStubs(page), network
         row.url = await evaluate("location.pathname + location.hash");
       } else if (verb === "watch") {
         const w = step.watch && typeof step.watch === "object" ? step.watch : {};
-        if (w.look === void 0) throw new UsageError(`Step ${i + 1}: watch takes { look: T }.`);
-        const forMs = Math.min(1e4, Math.max(100, Number(step.for_ms ?? 1500)));
-        const expr = lookExpression(w.look);
+        if (w.look === void 0) throw new UsageError(`Step ${i + 1}: watch takes { look: T } or { look: [T, T, \u2026] }.`);
+        const unknown = Object.keys(w).filter((k) => !["look", "for_ms", "expect"].includes(k));
+        if (unknown.length) throw new UsageError(`Step ${i + 1}: watch does not take ${unknown.map((k) => JSON.stringify(k)).join(", ")} \u2014 it takes look, for_ms and expect.`);
+        if (step.expect !== void 0 && w.expect !== void 0) throw new UsageError(`Step ${i + 1}: give watch one expect, beside it or inside it, not both.`);
+        const forMs = Math.min(1e4, Math.max(100, Number(step.for_ms ?? w.for_ms ?? 1500)));
+        const expect = step.expect !== void 0 ? step.expect : w.expect;
+        const many = Array.isArray(w.look);
+        const targets = many ? w.look : [w.look];
+        if (targets.length === 0 || targets.length > 8) throw new UsageError(`Step ${i + 1}: watch looks at 1 to 8 targets.`);
+        const expr = `Promise.all([${targets.map((t) => lookExpression(t)).join(", ")}])`;
         const keyOf = (v) => v && typeof v === "object" ? JSON.stringify({ text: v.text, visible: v.visible, backgroundName: v.backgroundName, colorName: v.colorName, opacity: v.opacity === void 0 ? void 0 : Math.round(v.opacity * 10) / 10 }) : "null";
-        const states = [];
+        const states = targets.map(() => []);
         const t0 = Date.now();
         while (Date.now() - t0 <= forMs) {
-          const v = await evaluate(expr);
+          const vs = await evaluate(expr);
           const at = Date.now() - t0;
-          const last = states[states.length - 1];
-          if (last && last.key === keyOf(v)) last.until = at;
-          else states.push({ key: keyOf(v), from: at, until: at, look: v && typeof v === "object" ? { text: v.text, visible: v.visible, backgroundName: v.backgroundName, colorName: v.colorName, opacity: v.opacity } : null });
+          vs.forEach((v, k) => {
+            const list = states[k];
+            const last = list[list.length - 1];
+            if (last && last.key === keyOf(v)) last.until = at;
+            else list.push({ key: keyOf(v), from: at, until: at, look: v && typeof v === "object" ? { text: v.text, visible: v.visible, backgroundName: v.backgroundName, colorName: v.colorName, opacity: v.opacity } : null });
+          });
           await wait(25);
         }
-        row.value = states.map(({ from, until, look }) => ({ from, until, look }));
-        const never = step.expect && typeof step.expect === "object" ? step.expect.never : void 0;
+        const shown = (list) => list.map(({ from, until, look }) => ({ from, until, look }));
+        row.value = many ? targets.map((t, k) => ({ target: t, states: shown(states[k]) })) : shown(states[0]);
+        const never = expect && typeof expect === "object" ? expect.never : void 0;
         if (never && typeof never === "object") {
-          const hit = states.find((st) => st.look && Object.keys(never).every((k) => matches(st.look[k], never[k])));
-          if (hit) {
-            row.ok = false;
-            row.error = `${JSON.stringify(never)} was seen from ${hit.from} to ${hit.until} ms: ${JSON.stringify(hit.look)}`;
+          for (let k = 0; k < targets.length && row.ok; k++) {
+            const hit = states[k].find((st) => st.look && Object.keys(never).every((key) => matches(st.look[key], never[key])));
+            if (hit) {
+              row.ok = false;
+              row.error = `${many ? `${JSON.stringify(targets[k])}: ` : ""}${JSON.stringify(never)} was seen from ${hit.from} to ${hit.until} ms: ${JSON.stringify(hit.look)}`;
+            }
           }
         }
       } else if (verb === "viewport") {