softr-vibe-coding 2.15.2 → 2.16.0

package/references/browser-checks.md

@@ -5,7 +5,11 @@ How to check a deployed block's rendering and behaviour in a Softr preview with
 agent-browser v0.38.1 on macOS (Node 22) against a real Softr preview; only the commands under
 [Untested but promising](#untested-but-promising) were not run. [Testing Custom Code header
 CSS](#testing-custom-code-header-css) was verified 2026-10-05, except where it says otherwise, and
-[the client's time zone](#1-the-clients-time-zone) on 2026-10-08.
+[the client's time zone](#1-the-clients-time-zone) on 2026-10-08. The served-build proof in step 2,
+the measuring and sizes rules in step 4, the create-save guard in step 6, [Forcing
+states](#forcing-states) and [Exports and printouts](#exports-and-printouts) come from one
+end-to-end QA pass of a 15-block app on 2026-10-08 (LCDB QA pass); a snippet marked as a sketch was
+run on a local test page, not on a Softr preview.
 
 ## When to use it
 
@@ -13,8 +17,11 @@ After a push has passed the hash check in
 [softr-mcp.md → Verifying a push](softr-mcp.md#verifying-a-push--the-deployed-source-is-the-only-proof).
 The hash proves what Softr stored; a browser shows what it does: the layout at a given width, what
 a control does, what a Save would send. **Not for data checks** (read records through the MCP or the
-API), and **not for logged-in Studio or Airtable work**, which needs the user's own session and so
-belongs to the user's own Chrome tool.
+API; to compare a page's figures with those reads, see
+[qa-playbook.md → Checking numbers against the database](qa-playbook.md#checking-numbers-against-the-database)),
+and **not for logged-in Studio or Airtable work**, which needs the user's own session and so
+belongs to the user's own Chrome tool. For a whole QA pass, in the order to run it, start at
+[qa-playbook.md](qa-playbook.md); this file holds the browser mechanics it links to.
 
 ## Tool choice and why
 
@@ -62,7 +69,7 @@ Run every check in the time zone of the app's users, never the machine's. A head
 the zone of the computer it runs on, and a date-only value arrives as midnight UTC
 ([fields.md → Date-only fields arrive as midnight UTC](../datasources/fields.md#date-only-fields-arrive-as-midnight-utc)):
 a block that parses it with `new Date()` or `parseISO` shows the right day east of UTC and the day
-before west of it. On 2026-10-08 three blocks of an app for Oregon had passed checks run in
+before west of it. On 2026-10-08 three blocks of an app for Pacific-time users had passed checks run in
 Europe/Athens (UTC+3) while showing their users in America/Los_Angeles every date-only value a day
 early. A test-data load found it, not the checks.
 
@@ -107,7 +114,7 @@ ab() { TZ=America/Los_Angeles agent-browser --session softr-check "$@"; }   # st
 ab open '<previewUrl>' >/dev/null      # once per session: sets the preview cookie
 ab set viewport 1280 900
 ab open 'https://<subdomain>.preview.softr.app/<page>?recordId=<recordId>&autoUser=true'
-ab wait --load networkidle             # works on Softr previews
+ab wait --load networkidle             # works on Softr previews, but not while a route aborts the block's reads (below)
 ab wait 2500                           # 2000–3000 ms more, so the block's data hooks can load
 ```
 
@@ -115,6 +122,39 @@ ab wait 2500                           # 2000–3000 ms more, so the block's dat
 this one carries a sign-in token, hence `/dev/null`. The direct URL then loads the app itself, not
 the toolbar shell that frames it, so `document` in `eval` is the app's.
 
+**Do not wait for `networkidle` while a route aborts the block's reads** ([Forcing
+states](#forcing-states)). The data hooks keep retrying, and the call did not return before the
+shell's 120 s timeout (LCDB QA pass, 2026-10-08). Poll instead: fixed `ab wait 3000` steps, each
+followed by an `eval` that looks for the expected text inside the shadow root. A selector-based wait
+does not cross the shadow root (see Gotchas), so it cannot be the fallback.
+
+**Prove which build the page loaded before you judge a change.** A fresh preview link, the
+`version=` number in its URL and a press of the refresh button are not proof. The block's script
+loads from `https://assets.softr-files.com/applications/<app>/vibe-coding/<page>/<block>/<versionId>/index.js`:
+the page id, then the block id, then the `versionId` the push returned. That is the id in the served
+script URL, **not** the id `vibe_coding_block_list_versions` shows for the same save (that tool
+answers NOT_FOUND for a build id): report both, and use the first to prove what is served. Find the
+URL in the page's resource timing, fetch that `index.js`, and count a string only the old build has
+and one only the new build has (save it as a file and run it with `ab eval --stdin <`, step 4):
+
+```js
+(async () => {
+  const u = performance.getEntriesByType('resource').map(r => r.name)
+    .find(n => n.includes('/vibe-coding/') && n.includes('<blockId>'));
+  if (!u) return 'script not found: the block has not loaded yet';
+  const t = await (await fetch(u)).text();
+  return JSON.stringify({ versionId: u.split('/').slice(-2, -1)[0],
+    old: t.split('<old string>').length - 1, now: t.split('<new string>').length - 1 });
+})()
+```
+
+`versionId` must equal the push result's, and `old` must be 0 and `now` at least 1 (the snippet ran
+on a local test page with the same URL shape, not on a preview). **Never text-search the whole page
+HTML for the string:** Softr also inlines the block's source, comments included, so an old string
+can still match inside a comment that is never shown (LCDB QA pass, 2026-10-08: a search of the
+page matched a code comment; the served `index.js` held "Reload the page and try again." once and
+the removed "Refreshing" zero times).
+
 ### 3. Reaching into the block
 
 A block renders inside a shadow root, which CSS selectors and `find` locators do not cross.
@@ -123,9 +163,26 @@ and checkboxes as `[ref=eN]`, and `ab fill @eN '…'` and `ab click @eN` act ins
 the ref out in the same shell call, so the readout never enters your context:
 
 ```bash
-REF=$(ab snapshot -i | grep -o 'textbox "Search by[^[]*\[ref=e[0-9]*' | head -1 | grep -o 'e[0-9]*$'); ab fill "@$REF" 'term'
+REF=$(ab snapshot -i | grep -F 'textbox "Search by' | grep -o 'ref=e[0-9]*' | head -1 | cut -d= -f2); ab fill "@$REF" 'term'
 ```
 
+Match the role and name with `grep -F`, then pull out `ref=e[0-9]*`: a readout line can carry other
+attributes before the ref (`[expanded=false, ref=e12]`), and a pattern that expects `[ref=` right
+after the name misses it.
+
+- **Hit-test before a coordinate click, in two parts.** `document.elementFromPoint(x, y)` must
+  return the block's host: anything else means something of Softr's (the phone tab bar, the top
+  bar) covers the point. Then `root.elementFromPoint(x, y)`, with the root found in step 4, must
+  return the element you mean, such as the modal backdrop and not the panel. The second call alone
+  ignores a fixed light-DOM bar on top, so a phone-size test that uses only it passes under the tab
+  bar (LCDB QA pass, 2026-10-08).
+- **A backdrop has no accessible name, so no ref.** Pick a point outside the panel that the hit test
+  shows is the backdrop, then send the whole press and release the backdrop's guards listen to:
+  `ab mouse move X Y`, `ab mouse down`, `ab mouse up` (LCDB QA pass, 2026-10-08: a backdrop click
+  with a calendar open closed only the calendar).
+- **A removed control is proven by searching every shadow root** for its text, `aria-label`, `title`
+  and icon class, not `document`, which finds nothing inside a block.
+
 ### 4. Measuring with `eval`
 
 `ab eval "<expr>"`, or `ab eval --stdin < check.js` for anything longer. An async IIFE is awaited,
@@ -157,6 +214,60 @@ A block that uses the brand `DatePicker` ([date-picker.md](date-picker.md)) has
 field is a button with a ref in `-i`. Click it, then click the day by its ref; each day is a button
 named like `Thursday, October 15, 2026`.
 
+**Measuring rules.** Measure every claim instead of eyeballing it; each of these once turned a wrong
+"pass" into a finding (LCDB QA pass, 2026-10-08).
+
+- **Prove the console capture on every load.** Run `ab console --clear` and `ab errors --clear`
+  before each `open`, then log a probe after it (`ab eval "console.error('probe')"`) and see it
+  listed. An empty console proves nothing until the probe shows.
+- **Numbers, not looks.** A label is on one line when its height equals one line. "No sideways
+  scroll" is `scrollWidth - clientWidth` of 0 on the document, the block and every scroller. Touch
+  targets are 44px or more on phones. Save a screenshot to disk at every size.
+- **Open every expandable row first.** A card in a grid widened the whole page by 163px at 375, and
+  only after a history row was opened.
+- **Past the edge is not always overflow.** Walk up to the element's clipping ancestor before
+  calling it a defect: a screen-reader-only table inside `overflow: hidden` is fine.
+- **An error must sit inside its dialog scroller's edges.** Compare its box with the scroller's top
+  and bottom. A check that only looked for the text passed while the error sat 21px below the fold
+  at 1280×800.
+- **Measure a toast itself**, not the toaster list that holds it.
+- **A ShadowRoot has no `innerText`.** It threw a TypeError; use
+  `[...root.children].map(c => c.innerText).join('\n')`. `root.textContent` works but runs words
+  together.
+- **Make every lookup require its match.** A loose `aria-label` pattern matched "Download monthly
+  trend as CSV" and compared nothing. Count rows by link `href`, not by a label that some widths
+  hide (a "Last pickup" label found 3 of 10 rows at 1280).
+- **Read figures from the root's text with a regex** (`textContent` plus a regex or `lastIndexOf`),
+  not from a snapshot: far smaller on data pages.
+- **Sample fast states with a 25 ms recorder.** An interval that logs a button's text and disabled
+  flag, started from an idle page: a snapshot or screenshot can trigger Softr's refetch on window
+  focus and show the busy state early.
+- **To find what moved the page**, wrap `window.scrollBy` and log its arguments, `scrollY` and a
+  timestamp. To check Escape order, add a spy on the document's bubbling `keydown`.
+- **Truncation, placeholders and text under a close button:** `scrollWidth > clientWidth` everywhere
+  a message shows (a 100-character message was cut to "This line was not saved: the app c…"), canvas
+  `measureText` for a placeholder, and `Range.getClientRects` for header text under an absolutely
+  placed close button.
+- **Softr pages set `scroll-behavior: smooth` on `html`** (seen in the preview). A coordinate click
+  below the fold does nothing and raises no error, and a measurement taken during a scroll reads
+  mid-animation. Scroll with `behavior: 'instant'` in one `eval` and measure in the next.
+- **A top-level `const` in `eval` stays in the page**, so a second run throws "already been
+  declared". Keep the IIFE, or assign helpers to `window`.
+
+**Sizes.** Check blocks at 1280×900, 1024×768 and 375×812, and modals also at 1280×600 and a
+568×320 landscape phone (a date picker lost 5–7px in dialogs at 1280×600 and a third of its day
+buttons on the landscape phone; nothing at the usual sizes showed it). Beside a sidebar, a block in
+a 1024 window is only about 730–745px wide (measure it), which is under 48rem: a block whose
+container queries switch at 48rem shows its phone layout on a tablet. Loop in zsh with two
+variables, and print `innerWidth` each time so a shot that did not resize is caught:
+
+```bash
+for W H in 1280 900 1024 768 375 812; do ab set viewport $W $H; ab wait 1200; ab eval "innerWidth + 'x' + innerHeight"; done
+```
+
+CSS and container queries follow `set viewport`. A window `resize` handler did not run after it
+once, so dispatch `new Event('resize')` after each change to be sure.
+
 ### 5. Date-only values against the stored ones
 
 On every block that shows a date-only field, compare a few shown days with the stored ones, in
@@ -192,7 +303,32 @@ the client's zone ([step 1](#1-the-clients-time-zone)):
   another field.
 - **A "today" taken as the UTC day is wrong only part of the day.**
   `new Date().toISOString().slice(0, 10)` is tomorrow from 5 pm in Los Angeles (4 pm in winter), so
-  a morning check misses it: look for it in the source instead.
+  a morning check misses it: look for it in the source instead, and run the "today" checks inside
+  that window on purpose.
+  - **When:** while UTC is already on another day than the client. West of UTC that is from the
+    zone's offset before midnight until midnight (17:00 to 24:00 in Los Angeles in summer, 16:00 in
+    winter). East of UTC it is from midnight until the offset (00:00 to 03:00 in Athens). Log the
+    client's local time with each check (`TZ=America/Los_Angeles date`). A check at 00:50 in Los
+    Angeles cannot show the bug, because both days agree (LCDB QA pass, 2026-10-08: two write-pass
+    runs at 00:50 saved the right dates and still proved nothing about this class).
+  - **What first:** form date defaults, "no later than today" limits, this-month figures, ages, and
+    stamps in printouts and exports. A CSV "Generated" line read 2026-10-08T05:49Z while the client's
+    clock said 22:49 on the 7th.
+  - **Work out the expected labels from the page's own clock**, never hard-code them: read
+    `new Date()` in the page and derive "Oct 1 to 7" from it. A label computed per render shows a
+    day rollover only on the next render, so a test across local midnight needs a second render.
+  - **Check rows dated the 1st of a month on purpose.** A one-day-early bug moves them into the
+    month before, in per-month charts, "this month" counts and intake buckets. Find them with the
+    MCP's `database_search_records` and OR conditions (`date IS 2026-10-01`, `IS 2026-09-01`, …), then
+    see which bar or count each lands in.
+  - **A block that shows no dates still gets a short date check.** Prove it from three sides: its
+    data sources have no DATETIME field, its code never reads the clock (`new Date`, `Date.now`) or
+    formats a date, and no rendered tab shows date-like text (a regex for month names,
+    `yyyy-mm-dd`, `m/d/yyyy`, "today", "ago" and four-digit years) or a native date input.
+  - **Get more rows on screen with a broad search.** A list that opens on 8 rows showed 25 with a
+    common 4-digit search (part of many phone numbers), so a date check compares more records.
+  - To reach a moment you cannot wait for (month end, year end, a clock change), fake the page clock:
+    [Forcing states](#forcing-states).
 
 ### 6. Block saves before any click, and prove it
 
@@ -214,9 +350,26 @@ A `useRecordUpdate` save goes out as a PATCH, with the record ID in the path (se
 PATCH https://<subdomain>.preview.softr.app/v1/datasource/applications/<app>/pages/<page>/blocks/<block>/datasources/<ds>/records-trigger/<recordId>
 ```
 
-Only this update endpoint is verified. Before clicking a create or delete control, learn its URL
-with `ab network requests` where a write is harmless, never on client data, and block that pattern
-too. Do not assume `*records-trigger*` covers it.
+A create goes out the same way as a POST to `…/records-trigger/new`, and the one `*records-trigger*`
+route blocked updates and creates alike (a live write pass and a blocked-create check, 2026-10-08).
+Deletes are still unverified: before clicking a delete control, learn its URL with
+`ab network requests` where a write is harmless, never on client data, and block that pattern too.
+Do not assume `*records-trigger*` covers it. The URL shapes are in
+[softr-mcp.md → What the server enforces on a block's data endpoints](softr-mcp.md#what-the-server-enforces-on-a-blocks-data-endpoints).
+
+- **Re-probe the guard after every page load**, with the two `fetch` lines above. A guard you
+  proved once is not one you proved for this page.
+- **Clear the request log before a click**, so that the read after it belongs to that click:
+  `ab network requests --clear`, click, then `ab network requests --filter records-trigger`. The
+  log otherwise survives page loads and redirects (it outlived a create's redirect), so an old
+  entry is not a new save.
+- **A run-wide proof needs the log kept.** If you never clear it, one filtered read at the end
+  shows that the whole run wrote nothing. Clearing per click loses that, so keep each per-click
+  read, or do not clear.
+- **At the end, summarise every non-GET request by method and endpoint**, not only
+  `records-trigger`. A block's reads are POSTs to `…/datasources/<name>/records`, so count them by
+  URL with `records-trigger` left out, never by method. A clean run showed 332 POSTs, all reads,
+  and nothing on `records-trigger`.
 
 ### 7. Click, then read what it sent
 
@@ -225,21 +378,260 @@ again: `updatedAt` and the field should be unchanged. The aborted request is sti
 see the payload without it reaching the server:
 
 ```bash
+ab network requests --clear                    # before the click
 ab network requests --filter records-trigger   # lists the save, with its id
 ab network request <id> --json                 # method: PATCH, postData: {"context":{…},"fields":{"<fieldId>":"2026-10-15"}}
 ```
 
+Read the body and URL from `postData`. An aborted save has no response, because nothing reached the
+server. For requests that complete, `--json` carries a `responseBody` field (reads, and saves in a
+write pass), though one run saw none for a save. So prove every save by reading the row back through
+the MCP, not from the logged response.
+
+- **Test a double tap with a real double click**, not two `element.click()` calls in one task. Two
+  scripted clicks in one task slipped past a guard held only in React state and sent two writes
+  that no user can send, while a real double click sent one (LCDB QA pass, 2026-10-08). Send the
+  real thing at a point you have hit-tested ([step 3](#3-reaching-into-the-block)):
+  `ab mouse move X Y`, then `ab mouse down`, `ab mouse up`, `ab mouse down`, `ab mouse up`; it sent
+  one write on a preview. The shorter form is `ab dblclick @<ref>`, run on a preview dialog in the
+  second round. Then read the code for the guard: it is set before the first `await` and held in a
+  ref as well as state.
+- **Force-click a control that should be disabled** and count the writes sent. A click that prints
+  "Done" proves nothing: `ab click` reports success on a disabled control and does nothing.
+- **Prove a lock by the payload and by `el.matches(':disabled')`.** Inputs inside a disabled
+  fieldset still report `.disabled === false`, and `fill` on one changes only the page's copy.
+- **After a failed save, change the form and press Retry**, then compare the retried request body
+  with what the screen shows. The retry sent the values from the first click while the form showed
+  new ones.
+- **Prove a leave-the-page guard** by dispatching `new Event('beforeunload', { cancelable: true })`
+  and reading `defaultPrevented`; without `cancelable` it is always false. The event fires on tab
+  close, reload and outside links, **not** on an in-app link such as the sidebar, so a guard for
+  those needs `useNavigationBlocker` ([common-patterns.md](common-patterns.md#navigation-blocker-for-unsaved-changes)).
+
 ### 8. Screenshots and cleanup
 
 ```bash
-ab screenshot ./empty-1280.png         # ✓ Screenshot saved to …   (--full for the whole page)
-ab network unroute
+ab screenshot "$PWD/empty-1280.png"    # ✓ Screenshot saved to …   (an absolute path: see below)
+ab network unroute '<pattern>'         # one pattern at a time; the bare form is the very last step
 ab close                               # ✓ Browser closed (no process left behind)
 ```
 
 Give a path; without one, it writes to a temp directory. A saved screenshot costs no tokens until
 someone opens it; one shown inline costs about 1.5k. Left alone, the daemon exits after an hour idle.
 
+- **Use an absolute path.** A relative path resolves against the daemon's working directory, not
+  your shell's, and failed with "No such file or directory". Pass a scratch folder, so that nothing
+  lands in the project root.
+- **Avoid `--full` on app pages.** It drew the sticky sidebar in the middle of the page. Scroll the
+  part into view (`ab scrollintoview <ref>`), wait a beat for the smooth scroll to end, and take a
+  viewport shot.
+- **Unroute by pattern, never bare, until the last click is done.** A bare `ab network unroute`
+  also removes the write guard. Remove a forced-state route with the same pattern you added it with.
+
+## Forcing states
+
+Failed reads, slow saves, odd values and month ends rarely show up in normal use, so put them on
+screen on purpose. None of these changes data: each is a browser-only trick. But the write guard
+([step 6](#6-block-saves-before-any-click-and-prove-it)) must be in place in every session, and a new
+session starts without it. **Verified 2026-10-08** with agent-browser 0.38.1 against a real preview
+(LCDB QA pass); the two scripts and the route patterns are the ones that pass used.
+
+### A fake clock
+
+`--init-script` runs a script before the page's own code. It goes on the command that starts a new
+session, so use a fresh session name, keep the time zone from [step 1](#1-the-clients-time-zone), and
+give the script path in full (an absolute path: [step 8](#8-screenshots-and-cleanup)):
+
+```bash
+TZ=America/Los_Angeles agent-browser --session clock-check --init-script "$PWD/clock.js" open 'about:blank' >/dev/null
+```
+
+A new session starts with no routes and no preview cookie. Point `ab` at it, open the preview link in
+it ([step 2](#2-session-preview-cookie-page)), then add and prove the write guard (step 6) before
+any click.
+
+`clock.js` replaces `window.Date` with one shifted by a fixed offset. `Date.now()`, `new Date()` and
+`Date()` move; `new Date(x)`, `Date.parse` and `Date.UTC` stay real:
+
+```js
+(() => { if (window.__fakeClock) return; window.__fakeClock = true;
+  const RealDate = Date, offset = RealDate.parse('2026-10-31T23:30:00-07:00') - RealDate.now();
+  function FakeDate(...a) {
+    if (!(this instanceof FakeDate)) return new RealDate(RealDate.now() + offset).toString();
+    return a.length === 0 ? new RealDate(RealDate.now() + offset) : new RealDate(...a);
+  }
+  FakeDate.prototype = RealDate.prototype; FakeDate.now = () => RealDate.now() + offset;
+  FakeDate.parse = RealDate.parse; FakeDate.UTC = RealDate.UTC;
+  Object.defineProperty(FakeDate, 'name', { value: 'Date' });
+  window.Date = FakeDate;
+})();
+```
+
+The script runs again on every full page load, so the clock restarts at the target there and runs
+on from it (read off the script, not measured). Moments worth testing in Los Angeles: Oct 31 at 23:30 (UTC is already Nov 1),
+Dec 31 at 22:00 (UTC is already the new year), the first Monday of January, and the day after a
+clock change. Every "this month" label held in the pass, and the year-end report showed "-0 items
+out" for an empty year, a bug no real-time check would have reached.
+
+**Reach a save-time check the UI blocks** by shifting the page clock just before Save. When a date
+picker disables future days, pick today, set `window.Date` one day behind, click Save, then restore
+it: the "no future date" guard fires and no request is sent.
+
+### Hold a save in flight
+
+To test double taps and "Saving" states, a script that wraps `window.fetch` can log every
+`records-trigger` call and then reject it after 6 s, so nothing reaches the server (add and prove the
+write guard in this session too). Start the session with it, as above:
+
+```js
+(() => { if (window.__hang) return; window.__hang = true; window.__writes = [];
+  const real = window.fetch.bind(window);
+  window.fetch = function (input, init) {
+    const url = typeof input === 'string' ? input : (input && input.url) || '';
+    if (/records-trigger/.test(url)) {
+      window.__writes.push({ m: (init && init.method) || 'GET', u: url.replace(/^.*\/datasources\//, ''),
+        b: String((init && init.body) || '').slice(0, 400) });
+      return new Promise((_, rej) => setTimeout(() => rej(new TypeError('Failed to fetch')), 6000));
+    }
+    return real(input, init);
+  };
+})();
+```
+
+Read `window.__writes` afterwards. In the pass, five blocks each sent exactly one write on a double
+tap, with the button disabled while it waited. Click as [step 7](#7-click-then-read-what-it-sent) says.
+
+**Fail only some requests** with the same wrapper: reject from the Nth request to one read URL on
+(the 4th and later reads of one table), and check that no page shows a figure built from half the
+data. The same idea fails the Nth write.
+
+### Fail reads by route
+
+A block's reads are POSTs to `…/v1/datasource/applications/<app>/pages/<page>/blocks/<block>/datasources/<name>/records`,
+where `<name>` is the name in `datasource.define`. None of these patterns matches the
+`records-trigger` save URLs, so the write guard stays in place:
+
+```bash
+ab network route '*/blocks/<blockId>/datasources/*/records' --abort   # every read of one block
+ab network route '*/datasources/<name>/records' --abort               # one read
+ab network route '*/datasources/<name>/records/*' --abort             # a single-record read (…/records/<id>)
+ab network unroute '<the same pattern>'                               # never bare: see step 8
+```
+
+- **Say which reads you broke.** A detail page's single-record read ends in `/records/<id>`, which the
+  list pattern does not match: with the list pattern the lists failed while the profile still loaded.
+- **Prove the route with a `fetch` to the exact URL** before you reload, as for the write guard.
+- **The error state comes only after the hooks' retries**: 6 to 20 s in the pass. Hold the abort until
+  it shows, sampling at 3, 6, 9, 12 and 20 s; letting go early lets a retry succeed. Do
+  not wait for `networkidle` (step 2).
+- **Find the block's root by text present in both states**, such as the h1: the normal text is gone
+  in the error state.
+- **A busy "Try again" shows only after the data has loaded once.** With no data yet, the error
+  state disappears while Try again re-reads, because the data library resets the read to loading.
+  Load the page, add the route, then trigger a background re-read without a click:
+  `window.dispatchEvent(new Event('visibilitychange')); window.dispatchEvent(new Event('focus'))`.
+  It refetched on one block and not on another (probably only once the data is stale). If nothing
+  re-reads, abort the read, reload, wait for the error (about 11 s), then install the fetch patch,
+  unroute, and press Try again.
+- **Test Try again by failing every read, restoring them, pressing it once, and then checking every
+  section.** A Try again that re-reads only the main list leaves the other failed reads failed:
+  after it, every row said "No children on record" and the duplicate check ran with no children.
+  Start the state recorder from an idle page ([step 4](#4-measuring-with-eval)).
+
+### Serve a changed read
+
+To put a state on screen that the data lacks, answer a read with an edited copy of a real one. Copy
+a captured response with `ab network request <id> --json` (its `responseBody` field), edit it, and
+serve it:
+
+```bash
+ab network route '*/datasources/<name>/records' --body "$(cat fake.json)"
+```
+
+- **Keep Softr's shape.** On Softr Database that is `{total, limit, offset, items, empty, complete: true}`;
+  `complete: true` stops the paging.
+- **Serve every empty-like value:** `null`, `''`, `0`, and the field missing. A threshold served as
+  null showed "Threshold 2,000 (default)"; every threshold served as -999999 showed the new empty
+  text; one block got negative stock and an empty product list the same way. No data changed.
+- **Pick values where the old and the new behaviour differ**, so the check proves the setting was
+  read. Remove the route with `unroute` on the same pattern, and prove it is gone by seeing real values.
+- **The first route registered for a URL wins.** A mock added after an abort on the same URL never
+  answers.
+- **Change a setting only in page memory or in a served read, never in the table.** A monthly cap of
+  12 was set to 2 in the page's memory to open its warning windows; the Settings table was never touched.
+
+### "Saved, but a line failed"
+
+To reach the state where a record saved and one of its lines did not, stub `window.fetch` for the one
+create URL (a sketch, run on a local test page, not on a preview):
+
+```js
+(() => {
+  window.__realFetch = window.__realFetch || window.fetch.bind(window);   // a second run would wrap the stub
+  window.fetch = (input, init) => {
+    const url = typeof input === 'string' ? input : (input && input.url) || '';
+    if (/\/records-trigger\/new$/.test(url) /* && the create you mean: match its body, or count calls */)
+      return Promise.resolve(new Response(JSON.stringify({ record: { id: 'qa-fake-1', fields: {} } }),
+        { status: 200, headers: { 'content-type': 'application/json' } }));
+    return window.__realFetch(input, init);
+  };
+})()
+```
+
+Return `{ record: { id, fields } }` with a JSON `content-type`. For the create, `network route --body`
+was not enough: it sends no content type and the Softr SDK refused the response (reads served with
+`--body` worked, above). Keep the original `fetch` in a global first, because a second run
+otherwise leaves `window.fetch` undefined. Keep the `*records-trigger*` abort behind the stub, so the
+stubbed create is the only one that answers and every other write is still blocked. The footer then
+read "The allotment is saved, but 2 size lines are not", Close and Retry worked, and the
+tables were unchanged afterwards.
+
+## Exports and printouts
+
+A headless run gets neither a download nor a pop-up window, so capture them in the page. Both
+sketches ran on a local test page, not on a preview.
+
+**A CSV.** Before the click, stub `URL.createObjectURL` to keep the Blob and
+`HTMLAnchorElement.prototype.click` to do nothing, then click the export and read the Blob:
+
+```js
+window.__csvs = [];
+URL.createObjectURL = b => { window.__csvs.push(b); return 'blob:stub'; };
+HTMLAnchorElement.prototype.click = () => {};
+// click Export, then read it in an async IIFE (a top-level `await` is a SyntaxError in `ab eval`):
+(async () => JSON.stringify([await window.__csvs[0].text(),
+  [...new Uint8Array(await window.__csvs[0].arrayBuffer(), 0, 3)].map(x => x.toString(16))]))()
+//   ["<the CSV text>",["ef","bb","bf"]]   ef,bb,bf = the BOM
+```
+
+`Blob.text()` drops a UTF-8 BOM, so check the BOM through `arrayBuffer()`. A "Generated" line read
+UTC (05:49Z on the 8th while the client's clock said 22:49 on the 7th); after the fix it read the
+local time with its offset.
+
+**A printout.** The Print control opens a window of its own ([printing.md](printing.md)). Replace
+`window.open` with a hidden iframe that stands in for the print window, count its `print()` calls,
+and measure the printout's cells in it, 700px wide for roughly A4 or Letter at 14mm margins:
+
+```js
+window.__prints = 0;
+window.open = () => {
+  const f = document.createElement('iframe');
+  f.style.cssText = 'position:fixed;top:0;left:0;width:700px;height:900px;border:0;visibility:hidden';
+  document.body.appendChild(f);
+  f.contentWindow.print = () => { window.__prints++; };
+  window.__printWin = f.contentWindow;
+  return f.contentWindow;
+};
+// click Print, wait about 5 s, then measure inside window.__printWin.document:
+// [...window.__printWin.document.querySelectorAll('td')].map(td => [td.scrollWidth, td.clientWidth])
+```
+
+The wait is longer than a beat: [printing.md §3](printing.md#3-print-only-when-it-is-ready)
+holds `print()` until the stylesheets, fonts and images are in (capped at about 4 s), plus 250 ms, so
+an earlier read finds `__prints` still 0. A cell that never wraps overflows its column without any
+error; one month label longer than its column was found this way. For the Playwright pop-up route,
+see [printing.md → Gotchas and testing](printing.md#7-gotchas-and-testing).
+
 ## Testing Custom Code header CSS
 
 CSS in **Settings → Custom Code → Code inside header** applies to every page of the app, and the
@@ -399,20 +791,41 @@ on the published app, logged out.
 - **zsh does not word-split.** `AB="agent-browser --session x"; $AB open …` fails with "command not
   found": use the function. Agent shells usually keep no functions or variables between calls, so
   define `ab`, and grep any ref, in the call that uses them; the browser lives on in the daemon.
+  The same slip in a viewport loop (`set -- $vp`, or `ab set viewport $vp`) left every shot at 1280
+  in more than ten checks of one pass: see Sizes in step 4.
+- **More shell slips that spoil a run.** zsh: `echo ====` fails with "== not found" and stops the
+  chain (quote it), a function named like an alias will not define, and `"$d[^[]…"` inside a
+  double-quoted pattern is read as an array subscript. macOS: there is no `timeout`, `sed -i` needs
+  `''` (patch with Python instead), and a stray `cat > file` inside a multi-line command waits for
+  input until the call times out at 120 s: run hash loops from a script file, with `< /dev/null`.
 - **Selectors stop at the shadow root.** `ab fill 'input[placeholder^="…"]' 'x'` gives
   `✗ Element not found`, and `find` locators fail the same way (upstream issue
   vercel-labs/agent-browser#1266, open since April 2026). Use refs, or `eval`.
-- **Refs change on every page load.** Grep again after each `open` or reload.
+- **Refs change on every page load, and on any DOM change.** Grep again after each `open` or reload,
+  take the ref from a snapshot in the same command as the click, and take a second snapshot after
+  opening a dialog or a list (the first can miss it). A new row's list may need a second open before
+  its option refs appear. While an `aria-modal` dialog is open, `snapshot -i` lists only the dialog.
+- **Grep by the role the markup really has.** A segmented control built from radio inputs reads as
+  `radio "X"`, not `tab`.
+- **`fill` has traps.** On a number input that holds text it appends ("-3" then "2.5" gave "-32.5").
+  `fill ''` empties the input but leaves React's state on the old value. `fill` with an empty ref
+  types into whatever has focus. Inside a disabled fieldset only the page's copy changes. A fill also
+  changed a field behind an open modal, so close dialogs before row checks. Set a value with the
+  native setter plus `input` and `change` events (step 4), then type with `ab keyboard type`.
+- **Select-all is unreliable headless.** `Meta+a` failed in one run and `Control+a` in another: use
+  the native setter. An in-app browser pane's `type` action inserts text without key events, so it
+  can make a correct control look broken.
 - **Readouts are huge on data pages.** A table-heavy page measured 268 KB in full, 197 KB with `-c`
   and 164 KB with `-i` (or `-i -c`), about 40k tokens: `-i` keeps table cells as context for the
   buttons in them. A small page was 5.8 KB, 2.9 KB with `-i`. Never print one on a data page: grep
   it, or write it to a file.
-- **Saves are PATCH, and the record ID is in the path.** A guard on POST misses them, and so does one
-  that looks for the record ID in the body; that one once let a write through. Match the URL, never
-  the method or the body.
+- **Updates are PATCH, creates are POST, and an update's record ID is in the path.** A guard on POST
+  misses updates, and so does one that looks for the record ID in the body; that one once let a
+  write through. Match the URL, never the method or the body.
 - **Plain `ab network request <id>` printed only the URL** of the blocked save. Add `--json`.
 - **A preview serves the version it was minted on.** After every push, mint a fresh one with
-  `application_preview` and open it again before checking anything.
+  `application_preview` and open it again before checking anything, then prove which build loaded
+  (step 2).
 - **The preview URL is a sign-in token.** Never share it ([why](softr-mcp.md#application-management-tools)).
 - **Attachment URLs are re-signed on every read:** compare by id, filename and size, never by URL.
 
@@ -429,8 +842,9 @@ In agent-browser's docs, **not yet tried against a Softr preview**. Try one befo
 
 - `ab pdf <path>`: to check a print layout ([printing.md](printing.md#7-gotchas-and-testing) has
   the verified Playwright route).
-- `--init-script <path>` (before the first navigation) or `ab addinitscript <js>` (at runtime): for
-  example, to stub `window.print` before load.
+- `ab addinitscript <js>` (at runtime, on a session that is already open): for example, to stub
+  `window.print` before load. The `--init-script <path>` flag at session start is verified: see
+  [Forcing states](#forcing-states).
 - `ab screenshot --if-changed`: skips a screenshot that matches the last one.
 - `ab diff snapshot`: compares the current readout with the last one.
 - `ab a11y`: the built-in axe-core accessibility audit.