softr-vibe-coding 2.8.2 → 2.9.1

package/CHANGELOG.md

@@ -4,6 +4,13 @@ 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.1] - 2026-09-30
+- Add right-edge placement and the schema-less workspace-tool correction (2026-09-30)
+- Document dropdown clipping by overflow ancestors (verified live 2026-09-30)
+
+## [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,
@@ -229,7 +232,10 @@ softr-vibe-coding/
 │                                     # click-outside, A-Z inside the component,
 │                                     # multi-token filter, searchable BY DEFAULT
 │                                     # (bare = click-only; searchable={false} only
-│                                     # for a fixed enum being set — Sep 10 2026)
+│                                     # for a fixed enum being set — Sep 10 2026),
+│                                     # overflow-clipping ancestors: never clip a cell
+│                                     # holding a Combo, clip-aware drop-up + list
+│                                     # height, list-only scrolling (Sep 30 2026)
 │
 ├── tools/                            # Bundled CLI scripts (run, not read)
 │   ├── get-airtable-base             # Full Airtable base schema export (bash + jq)
@@ -239,9 +245,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")
@@ -86,6 +90,7 @@ You generate complete, production-ready Softr Vibe Coding blocks as TypeScript R
    - Sequential multi-row saves use `await hook.mutateAsync(...)` per row, in order, with stop-on-failure + retry state — `mutateAsync` is fully supported on the current platform (verified 2026-08-25; the old ".mutate() only" Action-parser rule is gone — see [datasources/writing.md](datasources/writing.md)). Independent writes to **different tables** may run in parallel via `Promise.all`; drag/reassign UIs should be optimistic with an Undo toast — see [writing.md → Parallel writes across tables](datasources/writing.md#parallel-writes-across-tables-the-one-sanctioned-parallelism)
    - No hardcoded domains in links -- use relative paths (`/page?recordId=...`); same-page anchors written relative too (`/#section`)
    - **No `<select>` and no shadcn `<Select>`** — both break inside a block's shadow DOM (native hands the list to the OS; shadcn portals outside the shadow root and arrives unstyled). Use the `Combo` pattern in [references/searchable-dropdown.md](references/searchable-dropdown.md) — **searchable by default** for every framed filter or form field whatever the option count; `bare` inline editors are click-only; `searchable={false}` only on a short fixed enum the user is setting (a status, a location, a group-by)
+   - No clipping class (`overflow-hidden`, `overflow-*-auto`, `truncate`, `line-clamp-*`) on any element that contains a `Combo` — its panel is absolutely positioned in local DOM, so a clipping `<td>` cuts the menu to the row's height; bound an over-wide chip at the chip (`min-w-0 truncate`), and never `scrollIntoView` inside the panel. See [references/searchable-dropdown.md](references/searchable-dropdown.md#the-four-things-that-will-bite-you), item 4
    - Static block: no hardcoded user-visible copy — every string/image/link is an editable setting (see [references/editable-settings.md](references/editable-settings.md#granularity-doctrine-settings-first-static-blocks))
    - Array-setting rows keyed by **index**, never by a builder-editable field value
    - Media settings that may start empty (`src: ""`) gated with a conditional render or placeholder — never an unconditional `<img src={setting.src}>`
@@ -556,7 +561,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 +579,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.1",
   "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) |
 
@@ -69,6 +74,8 @@ Run through this catalog before delivering any block. Every row is a violation o
 | Placing a `<NavigationAction navigation={{ action: "OPEN_CHAT" }}>` Ask-AI button on a block that has no data source connected | Connect the block to the data source the AI should read from in Studio's Source tab. Softr's AI pulls context from the **block that triggered the chat**, not from the page — a button-only helper block with no data source causes `chat/prepare` → HTTP 500 ("Failed to prepare AI assistant") even though the chat UI opens fine. The block doesn't need to read or write records itself; the connection is purely for AI context. Verified by direct experiment, May 2026 |
 | Emojis in UI | lucide-react icons only |
 | `document.elementFromPoint(x, y)` to hit-test during a drag or custom pointer interaction | It returns the block's shadow **host**, not the element under the cursor — same boundary that stops `getElementById` and URL-fragment lookup. Either call it on the shadow root (`ref.current.getRootNode().elementFromPoint(x, y)`) or, better, keep refs to the candidate elements and compare `getBoundingClientRect()` yourself: rects need no shadow-root plumbing and work identically when the block is later reused elsewhere |
+| `overflow-hidden`, `truncate`, `line-clamp-*` or `overflow-*-auto` on a container that holds a dropdown or popover — typically a `<td>` clipped so an over-wide status chip stops at its own column | **Symptom:** the menu opens cut to the height of its row or its scroller: one or two options showing, the rest unreachable by mouse. **Cause:** the `Combo` panel is `position: absolute` in the block's own DOM (a portal would leave the shadow root and lose its styles), and an absolutely positioned box is clipped by every ancestor whose `overflow` is not `visible`. `truncate` and `line-clamp-*` set `overflow: hidden`; `overflow-x-auto` turns `overflow-y` to `auto` as well. **Fix:** no clipping class between the Combo and the scroller it belongs to; bound the chip at the chip (`min-w-0 truncate` on the chip inside the flex trigger); measure the drop-up and the list height against the clipping ancestors, not the window. Hit in production 2026-09-30: three ROSIE item tables clipped the status cell as a 2px backstop, next to a comment claiming the menu was portaled — it had stopped being portaled when the tables moved from shadcn `<Select>` to `Combo`. See [searchable-dropdown.md](searchable-dropdown.md#the-four-things-that-will-bite-you), item 4 |
+| `el.scrollIntoView({ block: "nearest" })` to keep a dropdown's highlighted option in view (or a plain `focus()` on its search box) | **Symptom:** the table or the page jumps when a menu opens near an edge; inside a clipped cell the trigger itself scrolls out of view. **Cause:** `scrollIntoView` scrolls EVERY scrollable ancestor until the element shows, and `overflow: hidden` boxes are still scrollable from script; `focus()` scrolls ancestors the same way. **Fix:** scroll the list element only — compare the option's rect with the list's and adjust `list.scrollTop` — and focus with `{ preventScroll: true }`. Verified in Chromium 2026-09-30: `scrollIntoView` scrolled an `overflow: hidden` cell by 164px, the list-only scroll moved nothing outside the list. See [searchable-dropdown.md](searchable-dropdown.md#the-four-things-that-will-bite-you), item 4, rule 3 |
 | Positioning repeated page chrome (back button, title, primary action) per-block, without checking the pages that already have it | Chrome the user meets on more than one screen is a cross-page contract. Copy the exact offset from the blocks that already ship it, and change every page in one edit. Let the wrapper's padding be the only thing positioning it — `mb-4` and NO top margin on a back button — so one number per page governs it. Verified 2026-09-09: an extra `mt-6` sat one detail page's back button 24px lower than another's, and **each block looked correct in isolation**. See SKILL.md's Block Placement section |
 | A loading skeleton carrying a different border / offset from the component it stands in for | The skeleton must track the component's REST state (border colour, padding, chrome offsets), never its hover state. If they disagree the layout visibly re-draws the instant data lands — the exact thing a skeleton exists to prevent. Verified 2026-09-09 twice in one session: a card grid re-outlined itself on load, and a back button jumped 24px. See [ui-ux-guidelines.md](../ui-ux-guidelines.md) §12 |
 | `focus-visible:` on a card or row that only *contains* buttons | The container is a plain `<div>` and never takes focus, so it is dead CSS. Use `focus-within:` on the container (pairs with its `hover:` treatment) and keep `focus-visible:ring-2` on the button/link itself |

package/references/common-patterns.md

@@ -515,4 +515,4 @@ function onKeyDown(e) {
 
 Make the rows themselves focusable too (`tabIndex={0}`, an `onKeyDown` that opens on Enter only when `event.target === event.currentTarget`, so an Enter on the anchor inside the row is not handled twice), and let `onMouseEnter` *and* `onFocus` both move the highlight onto the row — the highlight is the single answer to "which record does Enter open", whichever device last touched it. That is the shape `projects-table.jsx` shipped on 2026-09-10.
 
-Paint the highlighted row with the same colour the mouse hover gets (`data-active="true"` + `bg-[#FFF7EF]`) and scroll it into view when it moves (`querySelector('[data-active="true"]').scrollIntoView({ block: "nearest" })` in a `useEffect` on `activeIdx`) — the Combo in [searchable-dropdown.md](searchable-dropdown.md#one-flat-row-list-for-the-keyboard) does the same. Reset `active` to 0 whenever the query changes: the old index points at a row that may no longer be in the list. `autoFocus` is right only when the block *is* the page's reason to exist — an index page whose first act is always a search; on a page with content above the table, a focus steal scrolls the page to the box.
+Paint the highlighted row with the same colour the mouse hover gets (`data-active="true"` + `bg-[#FFF7EF]`) and scroll it into view when it moves (`querySelector('[data-active="true"]').scrollIntoView({ block: "nearest" })` in a `useEffect` on `activeIdx`). That is right here, because these rows are page content and the table's scroller and the page *should* move to them. Inside a dropdown it is wrong, and the Combo scrolls only its own list — see [searchable-dropdown.md](searchable-dropdown.md#the-four-things-that-will-bite-you), item 4, rule 3. Reset `active` to 0 whenever the query changes: the old index points at a row that may no longer be in the list. `autoFocus` is right only when the block *is* the page's reason to exist — an index page whose first act is always a search; on a page with content above the table, a focus steal scrolls the page to the box.

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/searchable-dropdown.md

@@ -8,13 +8,13 @@ the obvious choices:
 |---|---|
 | Native `<select>` | Hands the list to the OS. No keyword filter, none of your styling, and on macOS it paints a grey slab over the page. Fine for 5 options, unusable at 90. |
 | shadcn `<Select>` / `<Command>` | **Portals to `document.body`, which is outside the block's shadow root**, so the styles arrive stripped. It also cannot be searched. |
-| `Combo` (below) | Local DOM, brand-styled, keyword filter, A→Z, keyboard, create-new, drop-up. |
+| `Combo` (below) | Local DOM, brand-styled, keyword filter, A→Z, keyboard, create-new, clip-aware drop-up. |
 
 Copy the component into the block. A Vibe block is one self-contained file — there is no
 shared module to import, so each block carries its own copy. Keep one canonical copy in the
 project (e.g. `Assets/Softr App/Shared/combo.jsx`) and port changes from there.
 
-## The three things that will bite you
+## The four things that will bite you
 
 **1. Click-outside must use `composedPath()`, not `contains()`.**
 By the time a click reaches `document`, the shadow DOM has *retargeted* its `target` to the
@@ -44,6 +44,182 @@ single most common Vibe Coding bug and it looks like a platform fault.
 **3. `onMouseDown` on a row must `preventDefault()`.**
 Otherwise focus leaves the search input before the click resolves.
 
+**4. The panel is clipped by any ancestor whose `overflow` is not `visible`.**
+The panel is `position: absolute` inside the trigger's `relative` wrapper, in the block's own
+DOM, because it cannot portal out of the shadow root (see *Why not portal* below). Its
+containing block is that wrapper, so *every* ancestor whose `overflow` is `hidden`, `auto`,
+`scroll` or `clip` clips it, however far up. In Tailwind that is `overflow-hidden`,
+`overflow-auto`, `overflow-y-auto`, `overflow-x-auto` (an `overflow-x` of `hidden`, `auto` or
+`scroll` turns `overflow-y: visible` into `auto`, so it clips vertically too), `truncate` (it
+sets `overflow: hidden`) and `line-clamp-*` (so does that). A clipped `<td>` is the height of
+its row, and the menu opens inside it. Three rules follow.
+
+**Rule 1 — never put a clipping class on an element that contains a `Combo`:** a `<td>`, a
+card, a flex cell, anything between the Combo and the scroller it belongs to. If a chip or
+label inside the trigger can overflow, bound it at the chip: `truncate` (or `overflow-hidden`)
+plus `min-w-0` on the chip itself. The trigger is a flex row, and `min-w-0` is what lets a flex
+item shrink below its text — strictly redundant while the chip clips itself, load-bearing the
+moment the ellipsis moves to a span inside it. Clipping at the chip clips the chip. Clipping at
+the cell clips the menu.
+
+```jsx
+<td className="px-4">{/* no overflow class on the cell */}
+  <Combo
+    bare
+    triggerContent={<span className="min-w-0 truncate px-2" style={chipStyle}>{label}</span>}
+    …
+  />
+</td>
+```
+
+**Rule 2 — decide the drop-up and the list's height against the clipping ancestors, not the
+window.** `window.innerHeight - rect.bottom` cannot see scroll containers: a table with its own
+`max-height` + `overflow: auto` scroller, a dialog body with `overflow-y-auto`, a horizontally
+scrollable table wrapper. A row near the bottom of one of those opens its menu downward into
+the scroller's hidden area while the window still has plenty of room. Measure inside the strip
+the panel can actually paint into:
+
+```jsx
+var COMBO_LIST_MAX = 256; // the list's normal ceiling (max-h-64)
+var COMBO_LIST_MIN = 120; // the floor: below this, accept a clip rather than a useless list
+
+/* The strip of screen the panel can paint into: the viewport, cut down by every ancestor
+   that clips vertically. overflowY is enough on its own: an overflow-x of hidden, auto or
+   scroll already turns a visible overflow-y into auto in the computed style. */
+function comboClipBox(node) {
+  var top = 0;
+  var bottom = window.innerHeight;
+  var el = node;
+  while (el && el !== document.body && el !== document.documentElement) {
+    // clientHeight is 0 for the boxes overflow does not apply to (inline, display: contents)
+    if (el.clientHeight > 0 && window.getComputedStyle(el).overflowY !== "visible") {
+      var r = el.getBoundingClientRect();
+      var t = r.top + el.clientTop; // the clip edge is the padding box: inside the border
+      var b = t + el.clientHeight; //  and above a horizontal scrollbar
+      if (t > top) top = t;
+      if (b < bottom) bottom = b;
+    }
+    // Where the parent chain ends at the shadow root, carry on from its host.
+    el = el.parentElement || el.getRootNode().host || null;
+  }
+  return { top: top, bottom: bottom };
+}
+
+/* chrome = the panel's height outside the list: the search box and the borders. */
+function comboPlace(wrapper, chrome) {
+  var clip = comboClipBox(wrapper);
+  var r = wrapper.getBoundingClientRect();
+  var below = clip.bottom - r.bottom - 10; // the 2px gap to the trigger + 8px to spare
+  var above = r.top - clip.top - 10;
+  var up = below < chrome + COMBO_LIST_MAX && above > below;
+  var room = (up ? above : below) - chrome;
+  return { up: up, listMax: Math.max(COMBO_LIST_MIN, Math.min(COMBO_LIST_MAX, room)) };
+}
+```
+
+Call it when the panel opens, and give the list its height as an inline style in place of
+`max-h-64`:
+
+```jsx
+var [listMax, setListMax] = useState(COMBO_LIST_MAX);
+
+// in toggle(), before setOpen(true):
+if (rootRef.current) {
+  var place = comboPlace(rootRef.current, searchable ? 51 : 2);
+  setDropUp(place.up);
+  setListMax(place.listMax);
+}
+
+// the list:
+<div ref={listRef} role="listbox" className="overflow-y-auto py-1" style={{ maxHeight: listMax }}>
+  {/* rows */}
+</div>
+```
+
+Downward when the whole panel fits below, otherwise toward the larger side, with the list
+capped to the room it gets. `chrome` is the panel's height outside the list — about 51px with
+the search box (`p-2` around an `h-8` input, a 1px rule, the panel's two borders) and 2px
+without; measure yours if the panel differs. The fit test assumes a full-height list, so a
+three-option menu may flip up when it would have fit below, which costs nothing. The walk
+starts at the wrapper, whose own overflow would clip the panel too; it leaves the shadow root
+through its host, so a clipping container outside the block still counts; and it stops below
+`<body>`, because `body` and `html` hand their overflow to the viewport — their computed
+`overflow` can say `hidden` while they clip nothing. The four cases it has to get right: a row
+mid-way down a tall table scroller opens down; the last visible row of a scroller whose bottom
+edge is mid-window opens up, inside the scroller (the window-only rule opened it down, into
+the hidden part); a picker at the bottom of a dialog body opens up, inside the dialog; a filter
+row at the window's bottom edge opens up, as before. All four, plus a scroller outside the
+shadow root, checked in Chromium on 2026-09-30 on a test page — not yet in a deployed block.
+
+Rule 2 does not rescue a clipped cell. The cell is the height of its row, so neither side has
+room, the list falls to its 120px floor and is clipped anyway. Rule 1 is not optional.
+
+**The same box decides which edge the panel hangs from.** A panel hung from the trigger's left
+edge with `width: max-content` runs past the right edge of a table's scroll box when the trigger
+sits in the last column. In ROSIE the Location menu ran about 15px over, and the old
+`scrollIntoView` then slid the whole table sideways to reveal it. Measure the box's left and right
+edges as well (padding box, tested on `overflowX`), and when the room to the right of the trigger
+is short (under ~300px) and there is more to the left, anchor the panel with `right: 0` instead of
+`left: 0` and cap its `maxWidth` to the room on that side. Rows are a fixed height in this
+component, so the fit test can also count the real rows instead of assuming a full list, and a
+four-option menu near an edge stops flipping for room it will never use. ROSIE's
+`Shared/combo.jsx` (2026-09-30) is the worked version: one `comboClipBox` returning all four
+edges, one `comboPlacement` returning `{ up, right, listMax, maxW }`, deployed in twelve blocks.
+
+**Rule 3 — keep the active row visible by scrolling the list, never with `scrollIntoView`.**
+`scrollIntoView` scrolls *every* scrollable ancestor until the element shows, and an
+`overflow: hidden` box is still scrollable from script. In a clipped cell it scrolls the
+cell's content until the option shows, pushing the trigger out of view; near the edge of a
+table it scrolls whatever the menu hangs out of — the table's own scroller, the page — so the
+table jumps as the menu opens. Scroll the list element and nothing else:
+
+```jsx
+useEffect(
+  function () {
+    var list = listRef.current;
+    if (!open || !list) return;
+    var el = list.querySelector('[data-active="true"]');
+    if (!el) return;
+    var lr = list.getBoundingClientRect();
+    var er = el.getBoundingClientRect();
+    var viewTop = lr.top + list.clientTop; // inside the list's top border
+    var viewBottom = viewTop + list.clientHeight; // clientHeight excludes border and scrollbar
+    if (er.top < viewTop) list.scrollTop -= viewTop - er.top;
+    else if (er.bottom > viewBottom) list.scrollTop += er.bottom - viewBottom;
+  },
+  [open, activeIdx, query]
+);
+```
+
+Rects rather than `offsetTop`: a row's `offsetParent` is the nearest positioned ancestor,
+which is the panel, not the list, so `offsetTop` comes out too large by the search box's
+height unless the list is made `position: relative`. Rects need no such arrangement. The
+effect runs after the commit, outside the event cycle Hard Constraint 17's `setTimeout` is
+there to escape — the `scrollIntoView` it replaces ran from the same kind of effect and took
+effect. `focus()` scrolls ancestors the same way, so focus the search box with
+`inputRef.current.focus({ preventScroll: true })`.
+
+**Why not portal the panel, or make it `position: fixed`?** A portal to `document.body`
+leaves the shadow root, and the styles stay behind — the shadcn row at the top of this page.
+`position: fixed` inside the shadow root escapes the clipping only while no ancestor has a
+`transform`, `filter`, `perspective`, `contain` or `will-change`: any of those becomes the
+containing block for fixed descendants, and scroll-reveal animations on Softr pages commonly
+leave a transform behind (the same trap as the block-owned header in
+[static-blocks.md](static-blocks.md#block-owned-landing-page-header)). A fixed panel also stops
+moving with its trigger, so it has to be re-placed on every scroll. The clip-aware absolute
+panel has neither problem, which is why it is the design here.
+
+**The incident — ROSIE, 2026-09-30.** Three item tables put `overflow-hidden` on the `<td>`
+holding the status chip, as a backstop so the chip, 1–2px too wide at the column's narrowest
+drag width, would clip at its own column instead of painting over the next one. The comment
+beside it said the status menu was portaled to the body, so the clip could not reach it. That
+was true of the shadcn `<Select>` the tables used before and stopped being true when they moved
+to `Combo`; nobody re-checked. The menu opened inside the 48px cell: one and a half options
+showing, the chip scrolled out of view by `scrollIntoView`, the other six unreachable by
+mouse. The Location dropdown in the same rows kept working, because its cell had no overflow
+class. A 2px backstop cost the whole feature. A comment that says how a component renders is
+a claim to verify in the component, not in the comment.
+
 ## Sort A→Z *inside* the component
 
 Sorting at the call site gets forgotten. Do it in the component, with an opt-out:
@@ -125,16 +301,7 @@ than reaching past the wrapper.
 Build `rows` as a single array — the optional *clear* row, then the filtered options, then
 the optional *create* row — so arrow-key navigation has one index to walk. Clamp the active
 index (`Math.min(active, rows.length - 1)`): filtering shrinks the list under the highlight.
-
-## Drop up near the fold
-
-```jsx
-var r = rootRef.current.getBoundingClientRect();
-var below = window.innerHeight - r.bottom;
-setDropUp(below < 300 && r.top > below);
-```
-
-A filter row near the bottom of the viewport otherwise opens into nothing.
+Keep the highlighted row in view by scrolling the list only (rule 3 of item 4 above).
 
 ## Variants worth having
 
@@ -145,6 +312,9 @@ A filter row near the bottom of the viewport otherwise opens into nothing.
   ⚠ If any column width in your table is derived from the trigger's chrome, keep the
   chevron the SAME size in both variants. Shrinking it in `bare` silently changes those
   widths in a different file.
+  ⚠ A `bare` Combo sits in a table cell, which is exactly where `overflow-hidden` and
+  `truncate` get added. Keep them off the cell and bound the chip instead — rule 1 of item 4
+  in [The four things that will bite you](#the-four-things-that-will-bite-you).
 - **`triggerStyle`** — merged over the defaults, for a trigger that is part of the design
   (a chip painted in its own status colour) rather than a plain field.
 - **`onCreate(text)`** — offers `Add "<typed>"` when nothing matches. If creating the record
@@ -172,7 +342,12 @@ Everything else — the trigger, the card, the rows — stays flat.
 - [ ] Sorted A→Z inside the component, with `autoSort={false}` only where order is meaning
 - [ ] Multi-token filter
 - [ ] Searchable by default; `bare` is click-only; `searchable={false}` only on a short fixed enum the user is setting
-- [ ] Keyboard: ↑ ↓ Enter Esc Tab, active row scrolled into view
+- [ ] No overflow-clipping class (`overflow-hidden`, `overflow-*-auto`, `truncate`,
+      `line-clamp-*`) between the Combo and the scroller it belongs to; an over-wide chip
+      bounded at the chip (`min-w-0 truncate`)
+- [ ] Drop-up and list `maxHeight` measured against the clipping ancestors, not the window
+- [ ] Keyboard: ↑ ↓ Enter Esc Tab; the active row kept visible by scrolling the list only
+      (never `scrollIntoView`), and the search box focused with `preventScroll`
 - [ ] `aria-haspopup="listbox"`, `aria-expanded`, `role="listbox"` / `role="option"`,
       `aria-selected`, and an `aria-label` on the trigger
 - [ ] Loading and empty states (`"Nothing matches that."`)

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
@@ -178,8 +197,15 @@ shapes, different payload type. The stringification happened on the client side,
 calls made while the tool definitions had not been loaded into the model's context (deferred
 schemas), so there was no type to serialise against. **Load the tool's schema before calling it,
 and pass arrays as arrays.** (Empty schemas are real on Softr's *per-application* MCP servers —
-every tool there is advertised as `{"type":"object"}` with a name-only description — but the
-workspace server is not affected.)
+every tool there is advertised as `{"type":"object"}` with a name-only description.)
+
+**Correction, 2026-09-30: the workspace server's tools can arrive schema-less too.** In one
+session every workspace tool loaded through ToolSearch showed only `{"type":"object"}` with a
+name-only description, and a `search_replace` call written with a real array was still sent as a
+string and rejected with the error above. Nothing was written, so the failure is safe, but no
+amount of care on the caller's side gets an array through a schema-less tool. Look at the
+loaded schema before relying on an array argument: if it has no `properties`, go straight to the
+fallback in the table — a full replace, one file per subagent for a large block, byte-verified.
 
 **Why the second row is a security problem, not an inconvenience.** Every code push resets the
 block's auto-registered Actions to Softr's defaults, and the default for a `genericActions`
@@ -211,10 +237,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 +259,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 +327,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: