softr-vibe-coding 2.8.2 → 2.9.0

package/CHANGELOG.md

@@ -4,6 +4,9 @@ All notable changes to this skill are documented here. Versions follow [Semantic
 
 Entries from 1.3.1 onward are generated automatically from git commit subjects between version bumps (see `.github/workflows/publish.yml`). Entries before 1.3.1 were backfilled by hand from the existing commit history.
 
+## [2.9.0] - 2026-09-29
+- Add runtime facts verified live 2026-09-18
+
 ## [2.8.2] - 2026-09-10
 - Corrections on evidence: Softr never strips the trailing newline; the array-argument rejection was client-side stringification, not an empty server schema (2.8.2)
 

package/README.md

@@ -169,7 +169,7 @@ Create a contact form that creates records in our Airtable Contacts table
 softr-vibe-coding/
 ├── SKILL.md                          # Main skill
 │                                     # Workflow, code structure, visual baseline,
-│                                     # components, settings, 21 hard constraints
+│                                     # components, settings, 27 hard constraints
 │
 ├── ui-ux-guidelines.md               # Design reference
 │                                     # 26 sections: hierarchy, color, typography,
@@ -191,7 +191,10 @@ softr-vibe-coding/
 │   │                                 # Softr DB schema + record tools incl. deletes,
 │   │                                 # app management/scaffolding, Workflows suite
 │   │                                 # (26 tools, 418-node catalog), per-application
-│   │                                 # MCP servers, auth, permissions
+│   │                                 # MCP servers, auth, permissions; what the server
+│   │                                 # enforces on block data endpoints, "Preview as"
+│   │                                 # role testing, search-replace on 100KB+ blocks
+│   │                                 # (Sep 18 2026)
 │   ├── advanced-integrations.md      # Shadow DOM CSS isolation
 │   │                                 # Leaflet, Mapbox, TinyMCE, Quill, FullCalendar
 │   ├── native-chrome-styling.md      # Restyle Softr's native shell (header, footer,
@@ -239,9 +242,14 @@ softr-vibe-coding/
     ├── overview.md                   # Comparison matrix, selection guide
     ├── shared-patterns.md            # Index → multi-datasource, reading, writing, fields
     ├── multi-datasource.md           # Several data sources in ONE block: datasource.define(),
-    │                                 #   the from: parameter, getting the datasource UUIDs
+    │                                 #   the from: parameter, getting the datasource UUIDs,
+    │                                 #   select: as a module-scope identifier, the union-of-
+    │                                 #   selects read payload (a conditional select is not
+    │                                 #   privacy), Actions per table (Sep 18 2026)
     ├── reading.md                    # useRecords, filtering, sorting, pagination,
-    │                                 # metrics, charts, current user
+    │                                 # metrics, charts, current user; no detail-page
+    │                                 # auto-scoping, useRecords ignores enabled:false,
+    │                                 # server-side linked-record filters (Sep 18 2026)
     ├── writing.md                    # Mutations, sequential write queues, uploads,
     │                                 # linked record format, cross-table writes
     ├── fields.md                     # getFieldValue(), field type shapes, record

package/SKILL.md

@@ -69,6 +69,10 @@ You generate complete, production-ready Softr Vibe Coding blocks as TypeScript R
 
 6. **Self-validate before delivering.** Before presenting the code as complete, verify. (Data-hook items apply only to data-connected blocks; static marketing blocks swap in the checklist deltas from [references/static-blocks.md](references/static-blocks.md#workflow-deltas).)
    - Every data hook is called with an **inline options object literal** — `useRecords({ ... })` written through a variable or wrapper function fails to compile (verified live 2026-08-25). Share `q.select` mappings between hooks, never whole options objects
+   - Multi-datasource block: every `select:` / `fields:` value is a **plain module-scope identifier** — no ternary, no inline `q.select({...})` inside the hook options (the query returns `fields: {}`; Hard Constraint 24)
+   - Detail page: the record is fetched with `useRecord({ select, recordId, enabled: !!recordId })` using `useCurrentRecordId()`, and the code checks `data.id === recordId` before rendering — never `useRecords({ count: 1 })`, which returns the table's FIRST row (Hard Constraint 25)
+   - No list query relies on `enabled: false` — `useRecords` fetches anyway; conditional list queries live in a child component mounted only when needed, or carry a match-nothing `where` (Hard Constraint 26)
+   - No field is "hidden" from some viewers by a conditional / second `select` on the same connection — the browser receives the union of every read select on that connection (Hard Constraint 23)
    - All imports use named imports (no `import React from 'react'`)
    - `export default function Block()` is present
    - Container + content wrappers present (`<div className="container py-0"><div className="content">`) — OR a deliberate full-bleed layout recorded in the `// BLOCK PLACEMENT:` comment (see "Block Placement & Page Spacing")
@@ -556,7 +560,7 @@ Non-negotiable rules. Most are enforced by the Softr platform (compiler, validat
     restore worked. Softr's default for a `genericActions` ADD_RECORD is `ALL_USERS`, i.e. writable by
     logged-OUT visitors, and the MCP call that re-tightens it (`set_vibe_coding_block_action_visibility`)
     can itself fail with no fallback (see the array-argument quirk in
-    [references/softr-mcp.md](references/softr-mcp.md#the-array-argument-serialization-quirk-and-why-it-is-a-security-issue)).
+    [references/softr-mcp.md](references/softr-mcp.md#the-array-argument-rejection-and-why-it-is-a-security-issue)).
     A push that returns `errors: null` can still have left public write access on the block.
     **If any action is still `ALL_USERS`, report it WITH its severity and let the builder decide.**
     Check the page's own VIEW permission first (`get_page_permissions`): a page gated to logged-in
@@ -574,6 +578,31 @@ Non-negotiable rules. Most are enforced by the Softr platform (compiler, validat
     are shared, and promise nothing beyond them (the class strings usually differ in layout and padding,
     and do not need to match). The same rule governs repeated page chrome -- see **Block Placement &
     Page Spacing**.
+23. **One connection = one read payload; a conditional select is not privacy** -- the records
+    endpoint is per block + connection and returns the UNION of every field named by any READ
+    `q.select` on that connection, to every viewer. A second or ternary select "only for admins"
+    hides nothing. Put a private field on a **second connection of the same table** (allowed) read
+    only by a hook non-privileged browsers never run, or in a group-gated block. Page VIEW permission
+    is enforced on these endpoints, but on a page any logged-in user may view, every connected
+    datasource is readable by any logged-in user who crafts the request -- Source conditions are the
+    only server-side ROW gate. Verified live 2026-09-18. See
+    [datasources/multi-datasource.md](datasources/multi-datasource.md#one-connection--one-read-payload-the-union-of-its-selects).
+24. **Multi-datasource: `select:` is a plain module-scope identifier** -- a ternary
+    (`select: a ? X : Y`) cannot be attributed to a connection and the query returns `fields: {}`, no
+    error. Treat an inline `q.select({...})` inside hook options the same way: hoist it. Verified
+    live 2026-09-18.
+25. **No detail-page auto-scoping** -- the runtime sends `pageContext: null`;
+    `useRecords({ count: 1 })` returns the table's FIRST row, not the URL's record. Fetch detail
+    records with `useRecord({ select, recordId, enabled: !!recordId })` (`useCurrentRecordId()` does
+    return the URL's `recordId`) and verify `data.id === recordId` -- a null id falls back to a list
+    call. Verified live 2026-09-18. See [datasources/reading.md](datasources/reading.md#userecord----fetch-a-single-record).
+26. **`useRecords` ignores `enabled: false`** -- literal or variable, it fetches anyway. `useRecord`
+    honours it. Make a list query conditional by mounting it in a child component only when needed,
+    or with a match-nothing `where`. Verified live 2026-09-18.
+27. **Mutation Actions register per TABLE, not per connection** -- several `useRecordUpdate` hooks on
+    one table merge into ONE UPDATE_RECORD action (field list = the union), filed under the table's
+    FIRST connection even when a hook points at a second one. Point writes at the first connection.
+    Verified live 2026-09-18. See [datasources/writing.md](datasources/writing.md#actions-register-per-table-not-per-hook-or-connection).
 
 ## Style Conventions
 

package/datasources/fields.md

@@ -60,7 +60,7 @@ You'll see exactly which field is an object. Add `getFieldValue()` around it.
 | Date Range | `{ from: string, to: string }` |
 | Rating, Duration | `string or number or null` |
 | Select | `{ label: string, id: string }` |
-| Linked Record (via useRecord/useRecords) | `{ label: string, id: string }` |
+| Linked Record (via useRecord/useRecords) | `{ label: string, id: string }` — usually an array of these, but a link can arrive as a **single object** (verified live 2026-09-18); normalise with `Array.isArray(v) ? v : (v ? [v] : [])` |
 | Linked Record (via useLinkedRecords) | `{ id: string, title: string }` -- different! |
 | User, Created By, Updated By | `{ avatarUrl, id, name, email }` |
 | Attachment | `{ filename, id, type, url }` |

package/datasources/multi-datasource.md

@@ -64,6 +64,97 @@ var ds = datasource.define({ people: "74d2cbfd-…" });
 The error text is explicit, so this one fails fast rather than silently — but it's an easy
 reflex to hoist "magic strings" into named constants, and that reflex is wrong here.
 
+## `select:` must be a plain module-scope identifier
+
+*Verified live 2026-09-18 (Softr Database; probe block + network capture in a draft preview).*
+
+With more than one connection, Softr has to attribute every `q.select` to the connection it is
+used with. The observed behaviour says it does that statically, from the identifier you pass as
+`select:` (the mechanism is inferred; the outcome below is what was captured). An expression
+breaks the attribution:
+
+```jsx
+// WRONG — compiles, runs, and the query returns records with `fields: {}`. No error.
+var order = useRecord({ from: ds.orders, select: isAdmin ? adminSelect : publicSelect, recordId: id });
+
+// CORRECT — one module-scope identifier per hook
+var orderSelect = q.select({ title: "FIELD_ID1", status: "FIELD_ID2" });
+var order = useRecord({ from: ds.orders, select: orderSelect, recordId: id });
+```
+
+Treat an inline `q.select({...})` written inside the hook options the same way: hoist it to
+module scope and pass the identifier (the pattern at the top of this file already does). The
+same goes for a mutation hook's `fields:`.
+
+In a **single-datasource** block the same ternary *works* — there is nothing to attribute — but
+it behaves as a **union** of both branches, not a choice between them. Which is the next rule.
+
+## One connection = one read payload (the union of its selects)
+
+*Verified live 2026-09-18.*
+
+The records endpoint is per block + connection —
+`/blocks/<blockId>/datasources/<dataSourceId>/records` — and it returns the **UNION of every field
+named by any READ `q.select` attributed to that connection**. Two selects on one connection do
+NOT produce two payloads: every read hook on that connection gets all the fields, for every
+viewer.
+
+**So "request the private field only for admins" is not privacy.** A second select, or a ternary
+between a public and an admin select, still ships the private field to every browser that loads
+the block — it is simply not rendered. Anyone can read it in the network tab.
+
+What does *not* join the union: a mutation hook's `fields:` select. Write-only fields stay out of
+the read payload.
+
+**Remedy.** Connect the **same table a second time** — Softr allows it, and the second connection
+gets its own `dataSourceId` — and read the private field only through that connection, from a
+hook that non-privileged browsers never run:
+
+```jsx
+var ds = datasource.define({
+  orders: "11111111-…",        // everyone: public fields only
+  ordersAdmin: "22222222-…",   // same table, second connection: the private fields
+});
+
+var orderSelect = q.select({ title: "FIELD_ID1", status: "FIELD_ID2" });
+var orderAdminSelect = q.select({ internalNotes: "FIELD_ID9" });
+
+// Mounted by Block() ONLY when the viewer is an admin — so a non-admin browser never
+// issues the request. (`useRecord` honours `enabled: false`; `useRecords` does NOT —
+// see reading.md — which is why the gate is the mount, not an option.)
+function AdminNotes({ recordId }) {
+  var admin = useRecord({ from: ds.ordersAdmin, select: orderAdminSelect, recordId: recordId, enabled: !!recordId });
+  // …
+}
+```
+
+Or put the private field in a separate block whose visibility is group-gated.
+
+Know what this buys you. Not *rendering* the hook keeps the field out of ordinary browsers, but
+the endpoint still exists: page VIEW permission is enforced on it (a viewer who cannot view the
+page gets a 403), yet on a page any logged-in user may view, **every connected datasource is
+readable by any logged-in user who crafts the request**. A connection's **Source conditions are
+the only server-side ROW gate**; the only server-side gate on the *field* is a page or block the
+viewer cannot see. See [../references/softr-mcp.md](../references/softr-mcp.md#what-the-server-enforces-on-a-blocks-data-endpoints).
+
+Alias → field attribution is per connection, so two selects on different connections may reuse
+an alias name (`customer` on both) without colliding — including in `where` filters.
+
+## Mutation Actions register per TABLE, not per connection
+
+*Verified live 2026-09-18.*
+
+The second connection above is for **reads**. Actions are filed per table:
+
+- Several `useRecordUpdate` hooks on one table merge into **ONE `UPDATE_RECORD` action** whose
+  field list is the union of their `fields:` selects.
+- A hook pointed at the *second* connection of a table (`from: ds.ordersAdmin`) was still filed
+  under the **first** connection's `dataSourceId`.
+
+So **point every write at the table's first connection**, and expect one action per table and
+operation in `get_vibe_coding_block_settings` / the Actions tab — that is the row you re-tighten
+after each push. Details in [writing.md](writing.md#actions-register-per-table-not-per-hook-or-connection).
+
 ## Getting the datasource ids — ask for CODE, never for a value
 
 The id is a plain **UUID**. It is *not* the underlying table id (`tbl…` in Airtable), and not

package/datasources/reading.md

@@ -5,11 +5,11 @@ Fetching, filtering, sorting, pagination, metrics, charts, and current user.
 ## Table of Contents
 
 - [Query Builder](#query-builder)
-- [useRecords -- Fetch a Paginated List](#userecords----fetch-a-paginated-list)
-- [useRecord -- Fetch a Single Record](#userecord----fetch-a-single-record)
+- [useRecords -- Fetch a Paginated List](#userecords----fetch-a-paginated-list) — incl. [`enabled: false` is ignored](#userecords-ignores-enabled-false)
+- [useRecord -- Fetch a Single Record](#userecord----fetch-a-single-record) — the detail-page pattern; no auto-scoping
 - [useLinkedRecords -- Fetch Linked/Related Options](#uselinkedrecords----fetch-linkedrelated-options)
 - [useFieldOptions -- Fetch Single/Multi-Select Choices](#usefieldoptions----fetch-singlemulti-select-choices)
-- [Filtering](#filtering)
+- [Filtering](#filtering) — incl. [server-side linked-record filters](#filtering-by-a-linked-record-server-side)
 - [Sorting](#sorting)
 - [Current User](#current-user)
 - [Metrics](#metrics)
@@ -29,6 +29,15 @@ var select = q.select({
 });
 ```
 
+**Declare every `q.select` at module scope and pass it by identifier** (verified live 2026-09-18).
+In a multi-datasource block a `select:` that is a ternary (`select: a ? X : Y`) cannot be
+attributed to a connection and the query returns `fields: {}` with no error; treat an inline
+`q.select({...})` inside hook options the same way and hoist it. And a connection's read payload
+is the **union** of every read select on it — a second or conditional select never narrows what
+the browser receives, so it is not a privacy tool. Both rules, with the remedy, in
+[multi-datasource.md](multi-datasource.md#select-must-be-a-plain-module-scope-identifier).
+(The short inline `q.select` snippets below are single-datasource illustrations.)
+
 ## useRecords -- Fetch a Paginated List
 
 ```jsx
@@ -39,7 +48,7 @@ var result = useRecords({
   count: 6,           // records per page (default 6, max 100)
   where: q.text("name").contains("Alice"),  // optional filter
   orderBy: q.desc("createdAt"),             // optional sort
-  enabled: true,                            // optional, defer loading
+  enabled: true,                            // accepted, but `false` is IGNORED — see below
 });
 
 var data = result.data;
@@ -66,6 +75,33 @@ objects.
 
 A block can connect to **several data sources** and call `useRecords` once per source — declare them with `datasource.define()` and pass `from:` on every hook. See [multi-datasource.md](multi-datasource.md). (This replaces the old one-table-per-block limit; blocks no longer need an invisible helper block just to read a second table.)
 
+### `useRecords` ignores `enabled: false`
+
+*Verified live 2026-09-18 (network capture).* `useRecords({ ..., enabled: false })` **fetches
+anyway** — with a literal `false` and with a variable alike. `useRecord` is different: it honours
+`enabled: false` and issues no request. (`useLinkedRecords`, `useMetric` and `useChartData` were
+not probed — don't assume either behaviour for them.)
+
+So `enabled` cannot make a list query conditional, and it cannot keep a query away from viewers
+who should not run it. Two things that do work:
+
+```jsx
+// 1. Gate by MOUNT — put the hook in a child component and render it only when needed.
+function CommentsSection({ orderId }) {
+  var comments = useRecords({ from: ds.comments, select: commentSelect, count: 50,
+    where: q.array("order").hasAllOf([orderId]) });
+  // …
+}
+// in Block():  {canSeeComments && <CommentsSection orderId={recordId} />}
+
+// 2. Keep the hook mounted but give it a match-nothing `where` until it should load.
+var rows = useRecords({ select: select, count: 50,
+  where: q.text("email").is(email || "__no_match__") });
+```
+
+Option 1 is the only one that sends no request at all; option 2 still calls the endpoint and gets
+zero rows back. Remember the child must be defined at **module scope** (SKILL.md Self-validate).
+
 ### Loading All Records (Auto-Pagination)
 
 ```jsx
@@ -85,14 +121,45 @@ useEffect(function() {
 ```jsx
 import { useRecord, useCurrentRecordId, q } from "@/lib/datasource";
 
-var recordId = useCurrentRecordId(); // resolves from URL context, can be null
+var detailSelect = q.select({ title: "FIELD_ID1", description: "FIELD_ID2" });
+
+var recordId = useCurrentRecordId(); // the URL's `recordId` param — can be null
 var result = useRecord({
-  select: q.select({ title: "FIELD_ID1", description: "FIELD_ID2" }),
+  select: detailSelect,
   recordId: recordId,
+  enabled: !!recordId,               // honoured by useRecord: no id → no request
 });
+
+var record = result.data && result.data.id === recordId ? result.data : null; // trust only a matching id
 ```
 
-**`recordId` can be omitted when Softr Studio supplies the record context.** `useRecord({ select })` with no `recordId` loads the record the block is bound to via its data-source binding in Studio — verified by deployed block, July 2026 (an Airtable-backed stats block rendered live values this way). Keep `useCurrentRecordId()` + explicit `recordId` as the pattern for URL-driven detail pages (`/page?recordId=...`). When editing an existing **working** block that already omits `recordId`, leave the call shape as-is: adding an explicit `recordId` from `useCurrentRecordId()` can change behavior on pages whose URL carries no `recordId` param. Corollary for reviews: a recordId-less `useRecord` is NOT by itself a defect — check whether the block is deployed and loading data before flagging it.
+**There is NO detail-page auto-scoping (verified live 2026-09-18, Softr Database, network
+capture).** The runtime sends `pageContext: null` with the block's data requests — nothing tells
+the server which record the page is "about". Consequences:
+
+- `useRecords({ count: 1 })` on a detail page returns the **FIRST row of the table**, not the
+  URL's record. It looks right on the first record you test and wrong on every other.
+- `useCurrentRecordId()` **does** return the URL's `recordId`, and
+  `useRecord({ from, select, recordId })` fetches exactly that record (it hits `/records/<id>`).
+  That is the detail-page pattern — the only one.
+- `useRecord` with a **null / missing id falls back to a list call** and hands back whatever that
+  returns. So always pass `enabled: !!recordId` (`useRecord` honours `enabled: false` — no
+  request is made) and verify `data.id === recordId` before rendering or, worse, writing.
+
+**A recordId-less `useRecord` — what the older note here meant, and its limits.** This file used
+to say that `useRecord({ select })` with no `recordId` "loads the record the block is bound to
+via its data-source binding in Studio" (seen on one deployed Airtable-backed stats block, July
+2026, which rendered live values that way). Read that in the light of the capture above: no
+record context is sent, and a null-id `useRecord` falls back to a list call — so the likeliest
+explanation of the July block is that it was showing the list fallback's row, which is the
+"right" record only when the connection's Source conditions/sort leave exactly that row first.
+(That reading is an inference: the Airtable block was not re-probed, and the 2026-09-18 capture
+was on Softr Database.) Either way it is not a binding you can rely on, and never the way to
+build a detail page. The review corollary
+survives in a narrower form: a recordId-less `useRecord` in a **working, deployed** block is not
+by itself proof of a defect — check what it actually loads (and for which viewers) before
+flagging it, and when editing such a block, know that adding an explicit `recordId` changes what
+it loads on pages whose URL carries no `recordId` param.
 
 ## useLinkedRecords -- Fetch Linked/Related Options
 
@@ -189,6 +256,39 @@ where: q.and(
 )
 ```
 
+### Filtering by a linked record (server-side)
+
+*Verified live 2026-09-18 (Softr Database, network capture).* A linked-record field filters on
+the server with the array builder and the linked record's id — no need to load the whole child
+table and filter client-side:
+
+```jsx
+var commentSelect = q.select({ order: "LINK_FIELD_ID", body: "FIELD_ID2" });
+
+var comments = useRecords({
+  from: ds.comments,
+  select: commentSelect,
+  count: 50,
+  where: q.array("order").hasAllOf([orderId]),   // "order" = the link field's ALIAS
+});
+```
+
+On the wire the alias is resolved to the field id:
+`{ subject: <fieldId>, type: "ARRAY", operator: "HAS_ALL_OF", value: [orderId] }`. Alias → field
+attribution is **per datasource**, so two selects on different connections may use the same alias
+name for different fields and each filter still resolves against its own connection.
+
+`orderId` must be a real id when the hook runs — `useRecords` cannot be switched off with
+`enabled: false` ([above](#userecords-ignores-enabled-false)), so mount this query in a child
+component that only renders once the parent record has loaded.
+
+**Reading the link back:** a linked field can arrive as a **single `{ id, label }` object**, not
+only as an array of them. Normalise before you `.map()` or compare ids:
+
+```jsx
+var links = Array.isArray(v) ? v : (v ? [v] : []);
+```
+
 ## Sorting
 
 ```jsx

package/datasources/writing.md

@@ -31,6 +31,29 @@ implication: do the Actions-tab tightening pass only AFTER the last redeploy of
 re-check every tightened block after any future redeploy. Hit across a 15-block production
 deployment; treat it as standing platform behavior, not a one-off.
 
+### Actions register per TABLE, not per hook or connection
+
+*Verified live 2026-09-18 (Softr Database; probe block + network capture in a draft preview).*
+
+- **Several `useRecordUpdate` hooks on one table merge into ONE `UPDATE_RECORD` action** whose
+  field list is the UNION of all their `fields:` selects. Splitting a table's writes across hooks
+  ("one hook for the status, one for the admin-only fields") does not produce separately
+  permissionable actions — there is one action, and one visibility setting, per table and operation.
+  (What follows from that, deduced rather than separately tested: two user groups needing
+  different write rights on the same table cannot be expressed inside one block — use a second,
+  group-gated block, or a Softr Workflow that does the privileged write.)
+- **When the same table is connected twice** (the private-field pattern in
+  [multi-datasource.md](multi-datasource.md#one-connection--one-read-payload-the-union-of-its-selects)),
+  a mutation hook pointed at the SECOND connection was still filed under the FIRST connection's
+  `dataSourceId`. **Point writes at the table's first connection** and keep the second one
+  read-only, so the code says what the platform does.
+- A mutation hook's `fields:` select does **not** join the connection's read union — write-only
+  fields are not shipped to the browser by the records endpoint.
+
+Practical upshot for the post-push permission pass (see
+[softr-mcp.md](../references/softr-mcp.md#the-array-argument-rejection-and-why-it-is-a-security-issue)):
+expect one row per table + operation, and re-tighten that row.
+
 The `enabled` boolean on a mutation hook is a combined signal — it's `true` only when BOTH conditions are met:
 
 1. **The Action was successfully derived from the code** (parser side). Causes of failure here:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "softr-vibe-coding",
-  "version": "2.8.2",
+  "version": "2.9.0",
   "description": "Claude Code skill for generating production-ready Softr Vibe Coding blocks (JSX). Installs into ~/.claude/skills/ and auto-updates on each Claude Code session.",
   "bin": {
     "softr-vibe-coding": "./bin/cli.js"

package/references/anti-patterns.md

@@ -19,6 +19,10 @@ Run through this catalog before delivering any block. Every row is a violation o
 | Omitting `from:` on a hook when the block has more than one datasource | Throws at runtime. `from:` is optional ONLY when exactly one source is connected — then hooks default to it. Applies to `useRecords`, `useRecord`, `useLinkedRecords`, `useFieldOptions`, `useMetric`, `useChartData`, `useRecordCreate`, `useRecordUpdate`, `useRecordDelete`. NOT to `useUpload` / `useCurrentRecordId`, which are app-level. `useProxyFetch` has the same multi-datasource requirement but takes the alias as its **argument** — `useProxyFetch(ds.store)` — not as `from:` |
 | Hoisting datasource ids into constants: `datasource.define({ people: PEOPLE_DS_ID })` | Fails to compile — *"datasource.define() object values must be string literals."* Softr statically analyses the call, same as `q.select()`. Keep the UUIDs **inline**: `datasource.define({ people: "74d2cbfd-…" })`. Fails fast with an explicit message, but hoisting magic strings is a strong reflex — resist it here |
 | Asking Studio's AI chat "what are the datasource IDs?" and pasting the answer | **It fabricates them.** Verified July 2026: asked three times for the same three connected tables, it gave three different UUID sets, once reusing a previously-mentioned table's uuid for a different table — all confidently worded, none hedged. Ask it to **write code** instead (*"write a datasource.define call covering every connected source, plus one useRecords per source, code only"*) — scaffolding is bound to the real connections. Then RUN it: real rows under each heading proves each alias maps where you think. A wrong uuid fails safe (matches nothing → error); a *swapped pair* of valid uuids does not |
+| "Hiding" a private field from non-admins with a second `q.select`, or a ternary between a public and an admin select, on the SAME connection | **Not privacy.** The records endpoint is per block + connection (`/blocks/<id>/datasources/<dsId>/records`) and returns the UNION of every field named by any READ `q.select` on that connection — every viewer's browser receives the private field; it is merely not rendered (verified live 2026-09-18, network capture). A mutation hook's `fields:` select does not join the union. Fix: connect the **same table a second time** (allowed — it gets its own dataSourceId), read the private field only from that connection in a hook that non-privileged browsers never run (a child component mounted only for admins), or move it to a group-gated block. Server-side, page VIEW permission gates the endpoint and Source conditions gate ROWS; nothing else does. See [datasources/multi-datasource.md](../datasources/multi-datasource.md#one-connection--one-read-payload-the-union-of-its-selects) |
+| `select: isAdmin ? adminSelect : publicSelect` (or an inline `q.select({...})` in the hook options) in a **multi-datasource** block | The select cannot be attributed to a connection and the query returns records with `fields: {}` — no compile error, no runtime error, just empty fields (verified live 2026-09-18). `select:` / `fields:` must be a **plain module-scope identifier**. In a single-datasource block the ternary "works", but as a union of both branches (row above) — so it is never the tool it looks like. See [datasources/multi-datasource.md](../datasources/multi-datasource.md#select-must-be-a-plain-module-scope-identifier) |
+| `useRecords({ select, count: 1 })` on a detail page, expecting the page's record — or a `useRecord` with no / null `recordId` | There is **no detail-page auto-scoping**: the runtime sends `pageContext: null`, so `count: 1` returns the table's FIRST row, and a null-id `useRecord` falls back to a list call (verified live 2026-09-18). It passes a test on the first record and fails on every other. Use `useRecord({ from, select, recordId, enabled: !!recordId })` with `recordId = useCurrentRecordId()` (which does return the URL's `recordId`; the call hits `/records/<id>`), and verify `data.id === recordId` before rendering or writing. See [datasources/reading.md](../datasources/reading.md#userecord----fetch-a-single-record) |
+| `useRecords({ ..., enabled: false })` / `enabled: someFlag` to defer or withhold a list query | **`useRecords` ignores `enabled: false`** — literal or variable, it fetches anyway (verified live 2026-09-18). `useRecord` honours it. To make a list query conditional, mount the hook in a **child component rendered only when needed** (the only option that sends no request), or give it a match-nothing `where`. Never rely on `enabled` to keep a table away from viewers who should not load it. See [datasources/reading.md](../datasources/reading.md#userecords-ignores-enabled-false) |
 
 ## Mutations
 
@@ -40,6 +44,7 @@ Run through this catalog before delivering any block. Every row is a violation o
 | Tightening Actions-tab permissions before the block's final redeploy | Every code recompile **resets the auto-registered Actions to default permissions** (verified live 2026-08-25). Tighten permissions after the LAST redeploy, and re-check after any future one |
 | Assuming a comment-only edit is "safe" and leaves Action permissions alone | There is no cosmetic-edit exemption. Any save recompiles, and every recompile rebuilds the Actions at default visibility — a `search_replace` changing nothing but a code comment resets them exactly like a rewrite (verified live 2026-09-09, on two blocks at once). Re-check after EVERY push, including cosmetic ones |
 | Treating the permission-restore call as done because you issued it | Read the permissions back with `get_vibe_coding_block_settings` and confirm each one changed. `set_vibe_coding_block_action_visibility` can fail outright on the array-argument serialization quirk, and it has **no fallback** — the default for a `genericActions` ADD_RECORD is `ALL_USERS`, so a routine push silently leaves the block publicly writable while returning `errors: null`. Verified live 2026-09-09: four ADD_RECORD actions left open across two blocks. Report the list with its severity — check the page's VIEW permission with `get_page_permissions`, since a logged-in-gated page makes this housekeeping while a public page makes it a real hole — and let the builder decide whether it holds their release. A human sets them on the block's Actions tab |
+| Splitting one table's writes across several `useRecordUpdate` hooks (or across two connections of the same table) to get separately-permissioned Actions | Actions register per **TABLE**: the hooks merge into ONE UPDATE_RECORD action whose field list is the union, and a hook pointed at a second connection of the table is still filed under the FIRST connection's dataSourceId (verified live 2026-09-18). Point writes at the table's first connection; expect one action per table + operation when re-tightening permissions. See [datasources/writing.md](../datasources/writing.md#actions-register-per-table-not-per-hook-or-connection) |
 | Treating Studio's Actions tab as a separately-managed configuration to keep in sync with code | Actions auto-derive from your `useRecordCreate`/`useRecordUpdate`/`useRecordDelete` + `q.select` on every save. The Actions tab is a read-only inspector; there is no manual delete control. To change an Action, change the code |
 | One alias in a write-side `q.select` referencing a renamed / non-existent Airtable column | Softr's Action parser silently rejects the **entire** create/update Action — not just the bad alias. Symptoms: Studio's Actions tab shows "No actions used in this block yet", `createRecord.enabled` / `updateRecord.enabled` stays `false`, `.mutate()` calls dispatch but resolve immediately to "not yet ready". Every OTHER field in the same `q.select()` is also lost, even the ones that map cleanly. Diagnostic: bisect the `q.select` — strip down to a known-good minimal set, confirm the Action appears in Studio, then add fields back in halves until it drops out. The culprit is in the last half added. Once narrowed to a single field, grep its name against the freshest Airtable schema export to catch the rename / trailing-space / case-mismatch. Verified 2026-05-21: a `"Photos"` column on Wigs was renamed to `"Before Photos"`, the helper that wrote `photos: "Photos"` had its entire Action disabled even though 11 other fields in the same `q.select` were fine. See [datasources/airtable.md](../datasources/airtable.md#maintainability-gotcha) |
 

package/references/quick-reference.md

@@ -82,11 +82,12 @@ useRecords({
 ## Single Record (detail pages)
 
 ```jsx
-var recordId = useCurrentRecordId();
-var result = useRecord({ recordId: recordId, select: select });
+var recordId = useCurrentRecordId();   // the URL's recordId — can be null
+var result = useRecord({ recordId: recordId, select: select, enabled: !!recordId });
+var record = result.data && result.data.id === recordId ? result.data : null;
 ```
 
-`recordId` may be omitted when the block's Studio data binding supplies the record context (verified by deployed block, July 2026) — see [reading.md](../datasources/reading.md#userecord----fetch-a-single-record).
+There is **no detail-page auto-scoping** (verified live 2026-09-18): `useRecords({ count: 1 })` returns the table's FIRST row, and a null-id `useRecord` falls back to a list call — hence `enabled: !!recordId` (honoured by `useRecord`; **ignored by `useRecords`**) and the `data.id` check. The older "recordId may be omitted when Studio supplies the record context" note is qualified in [reading.md](../datasources/reading.md#userecord----fetch-a-single-record).
 
 ## Current User
 

package/references/softr-mcp.md

@@ -13,10 +13,10 @@ The official Softr MCP server (`https://mcp.softr.io/mcp`) gives an AI assistant
 - [What it covers](#what-it-covers)
 - [Connection and auth](#connection-and-auth)
 - [Permissions model](#permissions-model)
-- [Vibe coding block tools](#vibe-coding-block-tools)
+- [Vibe coding block tools](#vibe-coding-block-tools) — incl. [what the server enforces on a block's data endpoints](#what-the-server-enforces-on-a-blocks-data-endpoints)
 - [Adopting Studio-AI-generated code](#adopting-studio-ai-generated-code)
 - [Vibe coding gotchas (official)](#vibe-coding-gotchas-official)
-- [Application management tools](#application-management-tools)
+- [Application management tools](#application-management-tools) — incl. [testing as any user via "Preview as"](#testing-as-any-app-user-without-logins--the-preview-as-switcher)
 - [Browsing integrations (external data sources)](#browsing-integrations-external-data-sources)
 - [Softr Database tools](#softr-database-tools)
 - [Workflows](#workflows)
@@ -96,6 +96,23 @@ not name, so **each block keeps its own pair and the swap step disappears entire
 2026-09-09 across a report block deployed to two pages). It is also the safer option on large files:
 retransmitting ~100KB verbatim to change one class string is its own corruption risk.
 
+**Search-replace on a 100KB+ block — the working recipe (verified live 2026-09-18).** Sent a real
+array of `{ search, replace }` objects (not a JSON string — see
+[the array-argument rejection](#the-array-argument-rejection-and-why-it-is-a-security-issue)), the
+tool patches large blocks reliably, and nothing but the fragments passes through the model's
+context. Keep the local mirror in step mechanically rather than by hand:
+
+1. Prove deployed == disk first ([below](#verifying-a-push--the-deployed-source-is-the-only-proof)).
+2. Write the ops once, as data. Send them to the tool, and apply the **identical** ops to the local
+   mirror with a script that asserts each `search` occurs exactly once before replacing it.
+3. Several rounds of ops are fine — **byte-verify once at the end**: fetch `sourceCode`, compare to
+   the mirror, and a mismatch means an op landed differently on one side.
+
+One encoding trap: JSON `\uXXXX` escapes inside the ops are **decoded to the real characters** on
+Softr's side (`"—"` is stored as `—`). The mirror must therefore hold raw UTF-8 — apply the
+ops to it *after* JSON-decoding them, never as the escaped text, or the final byte comparison
+fails on every non-ASCII character.
+
 **Reach for the full replace when the change is structural** — reordering JSX, moving logic between
 components, adding a hook — where being sure of "the exact current text" of a dozen scattered fragments
 is harder than being sure of the whole file. Also use it when the local file is the source of truth and
@@ -121,7 +138,9 @@ unverified until you have pulled the source back down and compared it.
    --log-level=error --outfile=/dev/null`) plus eslint with `@babel/eslint-parser`. The bugs that
    actually bite Softr blocks are semantic — `useRecordUpdate({ select: … })` instead of `fields:`,
    an invented identifier — and the push is the first thing that reports them.
-3. Push the **entire** file.
+3. Push the **entire** file — or, for a targeted patch on a large block, send search-replace ops
+   and apply the identical ops to the mirror
+   ([recipe above](#which-edit-tool-full-replace-vs-targeted-search-replace)).
 4. **Fetch it back and compare again.** Identical, or you are not done: diff, fix, re-push.
 
 **Compare byte for byte, trailing newline included.** Softr stores exactly what it receives: across
@@ -140,7 +159,7 @@ expectation (disk for the first, disk-with-swap for the second). Never save the
 the local mirror — the mirror records which page it belongs to, and the block's header comment
 records the other page's pair. Search-replace would avoid the swap altogether
 ([above](#which-edit-tool-full-replace-vs-targeted-search-replace)) — when the client can send its
-array argument ([below](#the-array-argument-serialization-quirk-and-why-it-is-a-security-issue)).
+array argument ([below](#the-array-argument-rejection-and-why-it-is-a-security-issue)).
 
 **Do not read a 100KB block into a model's context to push it.** The full-replace tool takes the
 whole file as a string parameter, so the source has to pass through whatever is making the call. A
@@ -211,10 +230,15 @@ one push left four ADD_RECORD actions open across two blocks.
    block the publish.** It is not your app, and the person whose app it is needs the finding and the
    severity, not a veto.
 
-   One caveat worth stating: page visibility and action permissions are *separate* gates, and whether
-   Softr enforces page VIEW on the action endpoint itself is unverified here. The reason to treat a
-   gated page as low-severity is the practical difficulty and low blast radius, not a proof that the
-   action is unreachable. Say that plainly rather than implying the action is safe.
+   One caveat worth stating: page visibility and action permissions are *separate* gates. Page VIEW
+   **is** enforced on the block's datasource **records** endpoint (verified live 2026-09-18 — a
+   viewer who cannot view the page gets a 403 whose message names "block/action visibility rules";
+   see [below](#what-the-server-enforces-on-a-blocks-data-endpoints)). The *action* (write) endpoint
+   was not exercised separately; the message wording suggests the same gate covers it, but that part
+   is inference. So the reason to treat a gated page as low-severity is still the practical
+   difficulty and low blast radius — and note that "gated to logged-in users" keeps out anonymous
+   visitors only: any logged-in user can view that page, and therefore reach its endpoints. Say that
+   plainly rather than implying the action is safe.
 
    **Calibration matters.** This guidance read "do not publish" in v2.5.1 and immediately fired at
    maximum severity on a logged-in-gated app where the real exposure was junk records. A warning that
@@ -228,6 +252,34 @@ reverts the code along with the permissions, undoing the change you just pushed.
 
 Both edit paths recompile, so both reset Action permissions either way (Hard Constraint 21).
 
+### What the server enforces on a block's data endpoints
+
+*Verified live 2026-09-18 (Softr Database; draft preview, "Preview as" different users, requests
+captured from the app iframe).* A block's data lives behind per-connection endpoints —
+`/blocks/<blockId>/datasources/<dataSourceId>/records` for lists, `/records/<id>` for one record —
+and these are the gates that actually exist on them:
+
+| Gate | Enforced server-side? |
+|---|---|
+| **Page VIEW permission** | **Yes.** A viewer who cannot view the page gets **403** ("block/action visibility rules…") from the block's datasource endpoint — crafting the request by hand does not get around it |
+| **The connection's Source conditions** (Source tab / `set_vibe_coding_block_data_source_record_filters`) | **Yes — and they are the only server-side ROW gate** |
+| A `where` filter in the block's code | No — it is a request parameter the caller controls |
+| Which fields the block *renders*, a second / conditional `q.select`, `enabled: false` on `useRecords` | No — the endpoint returns the union of the connection's read selects to anyone allowed to call it (see [multi-datasource.md](../datasources/multi-datasource.md#one-connection--one-read-payload-the-union-of-its-selects)) |
+
+The consequence to design around: **on a page any logged-in user may view, every datasource
+connected to its blocks is readable by any logged-in user who crafts the request** — all rows the
+Source conditions allow, all fields the block's read selects name. A per-record access check in
+React ("is this viewer a party to this record?") shapes the UI; it is not access control. When rows
+must be private per user, put it in the Source conditions (e.g. a logged-in-user condition) or on a
+page only the right group can view. When a field must be private, a second connection of the table
+keeps it out of every ordinary browser's payload — but not away from a crafted request by someone
+who may view the page; for that it has to live on a page (or in a group-gated block) the viewer
+cannot see. (The verified 403 case was page VIEW; the message's "block/action visibility rules"
+wording suggests block visibility is checked the same way, which is inference.)
+
+This is also what makes the open-`ADD_RECORD` finding above severity-dependent on the page's VIEW
+permission rather than uniformly critical.
+
 ## Adopting Studio-AI-generated code
 
 When you pull a Studio-AI-generated block via `get_vibe_coding_block_code` to adopt into a project repo as source of truth: its output renders fine but ships with predictable defects. **Functional patterns in Studio output are platform-support evidence** (it surfaces undocumented capabilities before the docs do — see SKILL.md's "Platform truth sources"); **its code hygiene is not a pattern to imitate.** Cleanup pass before committing:
@@ -268,6 +320,37 @@ Combined with the database tools (`create_database` / `create_table` / `create_f
 
 > **preview_app links are auth tokens.** Per the server's own instructions, a preview link **signs its opener in as the user who requested it** and lasts about a day. Give it only to that user, and mint a fresh one with another `preview_app` call rather than re-sending an old link. Never paste a preview link into a shared channel.
 
+### Testing as any app user without logins — the "Preview as" switcher
+
+*Verified live 2026-09-18.* The `preview_app` link does not open the app directly: it opens a
+**toolbar shell** with a **"Preview as" user switcher**, and runs the draft app in an **iframe**
+whose URL carries `?autoUser=true`. That is a complete role-testing rig — every user group, no
+passwords, no test accounts to create:
+
+- The switcher is a **Choices.js** select listing the app's users. Picking one raises a
+  confirmation modal ("Ok, I understand"); after confirming, the app runs as that user, and the
+  choice persists per browser.
+- **With the Browser pane visible**, click through it like a person would.
+- **With the pane hidden, drive it by script** in the shell page: dispatch `mouseover` then
+  `mousedown` on `.choices__item--choice[data-value="<email>"]` (Choices.js acts on
+  `mousedown`, not `click`), then click
+  `#userConfirmationModal button.submit-btn`.
+- **To see what a block really sends and receives**, set `iframe.src` to the page under test and
+  wrap `iframe.contentWindow.fetch` immediately afterwards, recording each request body and
+  response. This is how the union-of-selects, `pageContext: null` and `enabled: false` findings in
+  [../datasources/](../datasources/) were established — read the wire, not the rendered UI.
+- Blocks render in shadow roots inside that iframe: read the DOM through
+  `iframe.contentDocument` and each block host's `shadowRoot`, not `document.querySelector`.
+
+> **The preview is wired to the LIVE datasource.** Anything clicked there — a Save, a status
+> change, a form submit — writes real records, as the previewed user. Keep preview sessions to
+> read-only checks unless the record is a marked test record, and never run a write path "just to
+> see" against client data.
+
+Limits: a page gated to a user group nobody belongs to cannot be previewed until someone is in the
+group, and these selectors are Softr's shell internals — observed, not documented, so re-inspect
+the shell if a selector stops matching rather than assuming the feature is gone.
+
 ## Browsing integrations (external data sources)
 
 An integration is an external data source connected once per workspace (the builder says "integrations", the tools say "data sources" — same thing). Five read-only tools drill down from workspace to fields; each level needs an ID from the level above: