softr-vibe-coding 2.13.3 → 2.13.5

package/references/anti-patterns.md

@@ -19,9 +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) |
+| "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/<connection>/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 and the block's own Visibility gate the endpoint (403 on list and by-id; block gate verified 2026-10-05), 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) |
+| `where: q.text("status")…` or `orderBy` naming an alias that is not in **that hook's own** `select` | Crashes the whole block at runtime — "Could not find an alias for subject \"undefined\"", Softr's "Oh snap" panel — though the push compiled clean (seen live 2026-09-18 on a `useMetric`). Aliases resolve per hook, not per connection: add the field to the hook's select (it then joins the connection's read payload). Hard Constraint 29; see [datasources/reading.md](../datasources/reading.md#filter-and-sort-aliases-must-be-in-the-same-hooks-select) |
 | `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
@@ -57,6 +58,7 @@ Run through this catalog before delivering any block. Every row is a violation o
 |---|---|
 | `field.toLowerCase()` on selects | `getFieldValue(field).toLowerCase()` |
 | `item.fields.formula === true` | Formula booleans: `=== "1"` |
+| `new Date(value)` / date-fns `format(new Date(value))` on a **date-only** field | Date-only values arrive as midnight UTC, so west of Greenwich they render one day early (verified 2026-09-18). Parse them with `toLocalDate()` — see [datasources/fields.md](../datasources/fields.md#date-only-fields-arrive-as-midnight-utc). Keep `new Date()` for real timestamps |
 
 ## Hooks & React
 
@@ -80,19 +82,24 @@ Run through this catalog before delivering any block. Every row is a violation o
 | `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 |
+| 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. Under container queries, find where a skeleton's text lines wrap by measuring at BLOCK widths with the real fonts: a padding change moves the wrap, and a skeleton keyed to the old width jumped when data landed (measured 2026-10-05 in headless Chromium, blocks 300–1400px wide). 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 |
 | `[&_svg]:opacity-0` on SelectTrigger | `<style>` + `data-fix-chevron` attribute (Softr bundler limitation) |
-| Relying on `custom-code-header.html` (Softr → Settings → Custom Code → Code inside header) to apply brand fonts/colors INSIDE a Vibe Coding block | Vibe Coding blocks render inside a shadow DOM. CSS custom properties (`--brand-*`) pierce that boundary, but `html, body { font-family: ... !important }` rules **do not** — `<html>` and `<body>` don't exist inside the shadow root. Apply brand fonts/colors at the block's **own outermost wrapper** via inline style: `style={{ fontFamily: "'Manrope', system-ui, sans-serif", color: BRAND_INK }}` on the outer `<div>` so every descendant inherits brand defaults. Override per-element with explicit inline `fontFamily` (e.g., `"'Fraunces', Georgia, serif"` on h1/h2). Google `<link>` tags in the page head DO load `@font-face` globally — the fonts are available inside shadow DOM, they just need to be applied. |
-| Painting `backgroundColor: BRAND_CANVAS` on a Vibe Coding block's outer wrapper when `custom-code-header.html` already sets `body { background-color: var(--brand-canvas) !important }` | Don't double-paint. If the body bg is already the brand canvas, the block leaves its own backgroundColor unset and the page bg shows through. Painting the same color twice produces a visible seam — Softr's content wrapper sits between `<body>` and the Vibe Coding block, and the two backgrounds composite slightly differently due to sub-pixel rendering, transparency stacking, or wrapper paddings. Set fontFamily and color on the block's wrapper (those don't inherit cleanly through shadow DOM), but **leave backgroundColor unset** — let the page bg flow through. The exception: if the block needs a brand-tinted *section* (e.g., a card-style admin shell that's different from the page bg), paint that bg explicitly on its specific container, not on the outer wrapper. **Second exception — DARK brands: see the next row.** |
-| Relying on the page background on a **dark** brand, and shipping a block whose own canvas is unpainted | The row above assumes a light app whose page bg is already correct. On a dark brand it inverts: `custom-code-header.html`'s `body { background-color: #000 !important }` does NOT cross the shadow-DOM boundary, and a default Softr page is white — so a block with white text, a white-only logo, or a white primary button renders **invisibly on white**. Verified July 2026: a black-canvas feedback form shipped with its wordmark and its Submit button both white-on-white; the button was there and clickable, just unseeable. On a dark brand, paint `backgroundColor` on the block's own outer wrapper AND set the Softr page background to the same value — two identical pure blacks composite with no seam, so the double-paint concern above doesn't bite. Painting it in the block also keeps it correct if the custom-code snippet is ever removed. |
-| Setting only `html, body { background }` in `custom-code-header.html` and expecting the app to change colour | Softr paints the same page fill on **four stacked layers**: `html`, `body`, `#page-content`, and a **class-less wrapper div** nested inside `#page-content`. Styling one gets covered by the ones above it, so `body` alone appears to do nothing. Paint the backdrop on `html`, then clear the duplicates: `body, #page-content { background: transparent }` plus `#page-content div:not(.softr-topbar):not(.softr-topbar *)`. The `:not()` exclusion is required — the nav renders inside `#page-content` and that id's specificity out-ranks `.softr-topbar` rules, so a blanket clear silently flattens the dropdown panel. Full recipe in [native-chrome-styling.md](native-chrome-styling.md). |
+| Relying on `custom-code-header.html` (Softr → Settings → Custom Code → Code inside header) to apply brand fonts/colors INSIDE a Vibe Coding block | Vibe Coding blocks render inside a shadow DOM. CSS custom properties (`--brand-*`) pierce that boundary, but `html, body { font-family: ... !important }` rules **do not** — `<html>` and `<body>` don't exist inside the shadow root. Apply brand fonts/colors at the block's **own outermost wrapper** via inline style: `style={{ fontFamily: "'Manrope', system-ui, sans-serif", color: BRAND_INK }}` on the outer `<div>` so every descendant inherits brand defaults. Override per-element with explicit inline `fontFamily` (e.g., `"'Fraunces', Georgia, serif"` on h1/h2). Google `<link>` tags in the page head DO load `@font-face` globally — the fonts are available inside shadow DOM, they just need to be applied. Give the header's font link an id (`<link id="brand-fonts" rel="stylesheet" href="…">`), and have each block append the same link to `document.head` only when `document.getElementById("brand-fonts")` finds nothing (the head is outside the shadow root, so this `document` lookup works). The block then works with or without the header code and never loads the fonts twice. Verified 2026-10-05: the header's link sat in `<head>` and the blocks skipped theirs. |
+| Painting `backgroundColor: BRAND_CANVAS` on a Vibe Coding block's outer wrapper to match a page colour that `custom-code-header.html` paints — or leaving it unset and expecting that page colour to show through | **An unpainted block does not let the page show through.** Its shadow host, `div[data-role="vibe-block-root"]`, paints the Studio theme background through the block's compiled `:host { background-color: var(--background) }` (in `@layer base`; `--background` maps to the theme's hashed background variable). Measured 2026-10-05: the host computes rgb(255,255,255) from its own compiled `:host` rule (read from the block's stylesheet), so it paints white whatever the page behind it is. It turns transparent only when header CSS clears the host: the app-frame rule `#main-content [data-role="vibe-block-root"] { background-color: transparent !important; }` (verified 2026-10-05; it wins because the `:host` rule is not `!important`), or, in a top-bar-only app, the page-background recipe's `#page-content div:not(.softr-topbar)…` clear, which hits the host too ([native-chrome-styling.md → Page background](native-chrome-styling.md#page-background)). The verified app-frame form is unscoped and applies on every page; the scoped form `#page-content:has(.softr-sidebar, .softr-bottombar) [data-role="vibe-block-root"]` is untested. With the host cleared, leave the block's outer wrapper unpainted too, so the header is the one painter of the page colour (older notes reported a seam from painting it twice; its cause was never measured). The header reaches the host but nothing inside the shadow root, so the block still paints its own cards and borders, and sets `fontFamily` and `color` on its wrapper (row above). Exception: a brand-tinted *section* that differs from the page (a card-style admin shell) paints its own container, not the outer wrapper. Recipe: [native-chrome-styling.md → App frame (navigation layout)](native-chrome-styling.md#app-frame-navigation-layout). **Dark brands: see the next row.** |
+| Relying on the page background on a **dark** brand, and shipping a block whose own canvas is unpainted | Same mechanism as the row above: whatever `custom-code-header.html` paints on `body` (`body { background-color: #000 !important }`), the block's host paints the Studio theme background, white by default — so a block with white text, a white-only logo, or a white primary button renders **invisibly on white**. Verified July 2026: a black-canvas feedback form shipped with its wordmark and its Submit button both white-on-white; the button was there and clickable, just unseeable. On a dark brand, paint `backgroundColor` on the block's own outer wrapper AND set the Studio theme background to the same value. The theme background is the no-CSS lever, because it is what the host's `--background` reads (measured 2026-10-05); changing it to fix a block is untested. Two identical pure blacks composite with no seam, so the double-paint concern above doesn't bite there, and painting it in the block also keeps it correct if the custom-code snippet is ever removed. |
+| Setting only `html, body { background }` in `custom-code-header.html` and expecting the app to change colour | Softr paints the page fill on several stacked layers, so styling one gets covered by the ones above it and `body` alone appears to do nothing. Measured 2026-10-05 in an app with Softr's sidebar: `html`, `body`, `#page-content` (Softr's own `.spr-content-root` rule), each Vibe block's shadow host `div[data-role="vibe-block-root"]` (most likely the "class-less wrapper div" of earlier notes, inferred; its `:host` rule paints the theme background, row above) and each native block's outer `<section>`. **Top bar only** (the June 2026 recipe): paint the backdrop on `html`, then clear `body, #page-content { background: transparent }` plus `#page-content div:not(.softr-topbar):not(.softr-topbar *)`. The `:not()` exclusion is required — the nav renders inside `#page-content` and that id's specificity out-ranks `.softr-topbar` rules, so a blanket clear silently flattens the dropdown panel. Full recipe in [native-chrome-styling.md](native-chrome-styling.md#page-background). **With Softr's sidebar or phone tab bar**, don't use that blanket `div` clear: `.softr-sidebar` is a div inside `#page-content` that paints the theme colour, so the clear would strip it too (inferred from the measured DOM, not injected), and it never reaches native blocks' `<section>`s. Name the layers instead, scoped to pages with navigation by `:has(.softr-sidebar, .softr-bottombar)` — see [native-chrome-styling.md → App frame (navigation layout)](native-chrome-styling.md#app-frame-navigation-layout) |
+| On an app page inside a header-painted frame: keeping Softr's `container` / `content` wrappers, a padded outer wrapper, and a rounded panel with its own background (`rounded-[20px] p-8` on the brand surface, or a gradient) | Users read it as cards floating on white: "building blocks on top of each other" (Leo, 2026-10-05, asking for one full-width application instead). Make the block **full-bleed and transparent**: no `container` / `content` wrappers (their gutters step on the WINDOW), no background on any wrapper, and one `@container` shell whose gutters follow the block's width — the shell, its measured paddings and the placement comment are in [SKILL.md → App pages beside Softr navigation](../SKILL.md#app-pages-beside-softr-navigation). Record the full-bleed choice in the `// BLOCK PLACEMENT:` comment and use the same shell on every app page, so the page header lands in the same place. The header code paints the frame and the sheet; the block still paints its own cards and borders. |
+| Window breakpoints (`sm:` / `md:` / `lg:`) for the layout of a block that sits beside Softr's sidebar | The sidebar takes 57px (collapsed) to 360px (dragged; 280px by default) of the window, so the block is far narrower than the window: 744px at a 1024px window, 488px at 768 with the sidebar open. `lg:` still fires at 1024 — measured 2026-10-05: a squeezed five-column chart row with cut-off labels. Lay out by the block's own width: `@container` on a root wrapper plus Tailwind v4 container variants (`@min-[52rem]:grid-cols-4`), which Softr's Tailwind 4.1.13 compiles (verified live 2026-10-05). A container query resolves against the nearest ANCESTOR container, never the element itself, so `@container` goes on a wrapper. For decisions CSS can't make, measure the block in JS — see [common-patterns.md → Measure the block, not the window](common-patterns.md#measure-the-block-not-the-window) |
+| `sticky top-4` (any `top-N`) on an element inside a block, on a page with Softr's top bar | Softr's `#topbar-root` is itself sticky (top 0, z-index 800, 56px tall), so the block's sticky element slides under it. Offset by the nav height the block host exposes, as an inline style: `style={{ top: "calc(var(--nav-height, 0px) + 16px)", maxHeight: "calc(100dvh - var(--nav-height, 0px) - 32px)" }}` (verified 2026-10-05: the list pane stuck at 72px). `--nav-height` is 56px with the top bar and falls back to 0px on phones, where the tab bar is `--bottombar-height`. JS that scrolls the window or fits a popover has to keep the bars clear too (inferred). See [common-patterns.md → Clear Softr's sticky bars](common-patterns.md#clear-softrs-sticky-bars) |
+| Reading the navigation variables in JS — `parseFloat(getComputedStyle(host).getPropertyValue("--bottombar-height"))` | They are unregistered custom properties, so JS gets the token string, not a length: on phones `--bottombar-height` reads `calc(0px + 55px)` (measured 2026-10-05). `parseFloat` of that is NaN (inferred, not run), and a fallback to 0 then hides the tab bar from the code. Use them only inside CSS `calc()`. Where JS needs a number (scroll insets, the room a popover has), take the bars' heights as constants (56px top bar; about 57px phone tab bar as rendered, though Softr's variable says 55px; switching at a 768px window) — see [common-patterns.md → Clear Softr's sticky bars](common-patterns.md#clear-softrs-sticky-bars). The shipped block's 72px (a bar plus about 16px) is a project choice, not a rule |
 | `document.getElementById(...)` / `document.querySelector(...)` to find an element inside the block — for example, a hidden `<input type="file">` triggered by a visible "Upload" button via `getElementById('myInput').click()` | Vibe Coding blocks render inside a shadow DOM. The global `document` traversal stops at the shadow boundary, so id/selector lookups for elements inside the block return `null`. The user-visible symptom is a control that does nothing — no error, no file picker, no focus, no scroll — because the chained `.click()` / `.focus()` / `.scrollIntoView()` was called on `null`. Use a **React `useRef`** instead: `var inputRef = useRef(null)`, then `<input ref={inputRef} />` and `<button onClick={function() { if (inputRef.current) inputRef.current.click(); }}>`. Refs hold direct node references and don't depend on DOM traversal, so they work regardless of which DOM tree the node lives in. This applies to every "trigger a hidden element" pattern: hidden file inputs, programmatic focus, scroll-into-view, `.click()` on a non-visible button. |
 | Inlining brand hexes at every point of use (the signature failure of Studio-AI-generated styling) | Hoist the palette to module-scope constants — `const BRAND = { terracotta: "#B4603D", ink: "#211C18" }` — and reference those. Inlined hexes drift into near-duplicates: observed live 2026-08 in one Studio-emitted hero, `#AE5E3D` vs `#B4603D` for the same terracotta and three near-identical near-blacks. The literals-only static-analysis rule applies ONLY to `datasource.define()` / `q.select()` / data-hook options — style objects and JS expressions use constants freely (the BRAND_INK/BRAND_CANVAS rows above and helper-blocks.md's `BRAND_PRIMARY` are existing house precedent). Constants reach the DOM via inline `style` or by choosing between STATIC class strings — never template-interpolated into arbitrary classes (`` bg-[${BRAND.x}] ``): Tailwind's JIT extracts classes by static source scan (standard-Tailwind inference, not Softr-verified) |
 | Using `window.addEventListener("beforeunload", ...)` as the only unsaved-changes guard in a form block | Softr is a SPA. Internal nav (Softr's nav bar, sidebar links, `<NavigationAction>`) changes the route via the client-side router — `beforeunload` only fires on full page unload (tab close, refresh, external link), so the warning silently misses every in-app navigation. Use `useNavigationBlocker(isDirty)` from `@/lib/use-navigation-blocker` instead; it covers SPA nav AND browser unload with one API. Softr's Vibe Coding bundler often wires this automatically when a form is detected as dirty — you only need to add it manually for advanced cases (multi-step forms, custom dirty tracking, blocking on non-form state). See [common-patterns.md](common-patterns.md#navigation-blocker-for-unsaved-changes). |
-| Targeting Softr's hashed build classes (e.g. `.f8f11e5_m9ntthp`) when restyling the native header/nav from `custom-code-header.html` | Softr regenerates the hash on every deploy, so the rule silently dies. Target stable hooks: `.softr-topbar`, `.softr-nav-link`, `.softr-nav-button`, `.softr-nav-logo`, `#topbar-root`; for dropdown menus (no `softr-*` class) use the Radix/ARIA attrs `[role="menu"]` / `[role="menuitem"]` / `[role="group"]` / `[aria-expanded="true"]`, scoped under `.softr-topbar`. The native header is Softr chrome (main document), not a block — it can't be built as a Vibe Coding block. (A landing page with the native header HIDDEN may instead ship a block-owned in-block header — see [static-blocks.md](static-blocks.md#block-owned-landing-page-header); that's a different pattern, not a rebuild of native chrome.) See [native-chrome-styling.md](native-chrome-styling.md). |
+| Targeting Softr's hashed build classes (e.g. `.f8f11e5_m9ntthp` in June 2026; the navigation block's prefix was `_5f91d6c_` by October) when restyling the native header/nav from `custom-code-header.html` | Softr regenerates the hash on every deploy, so the rule silently dies. Target stable hooks: `.softr-topbar`, `.softr-nav-link`, `.softr-nav-button`, `.softr-nav-logo`, `#topbar-root`; for dropdown menus (no `softr-*` class) use the Radix/ARIA attrs `[role="menu"]` / `[role="menuitem"]` / `[role="group"]` / `[aria-expanded="true"]`, scoped under `.softr-topbar`. The native header is Softr chrome (main document), not a block — it can't be built as a Vibe Coding block. (A landing page with the native header HIDDEN may instead ship a block-owned in-block header — see [static-blocks.md](static-blocks.md#block-owned-landing-page-header); that's a different pattern, not a rebuild of native chrome.) See [native-chrome-styling.md](native-chrome-styling.md). |
+| Taking the frame colour from Softr's hashed theme variables (`var(--_5f91d6c_vnohg20)`) or hashed classes in header CSS | The hash is set per native block package, not once per app — `_5f91d6c_` on the navigation block, `_03ef538_` on the user-accounts block (seen 2026-10-05) — and the theme variables carry the same prefix, so a rule that names one breaks when that package changes. Copy the Studio theme colour of the top bar and sidebar into your own token, e.g. `--app-frame: #A85935`, with a comment saying to update it when the theme changes. Copy the THEME colour (Studio's theme settings, or the rendered sidebar's computed background), not the brand primary from DESIGN.md: they differed (theme `#A85935`, DESIGN.md primary `#B4532A`; measured 2026-10-05). See [native-chrome-styling.md → App frame (navigation layout)](native-chrome-styling.md#app-frame-navigation-layout) |
 | Softr nav dropdown panel shows a tall blank gap below the items, and `height: auto` won't shrink it | The items sit in a CSS grid Softr sets to `grid-auto-flow: column` with pre-sized empty row tracks (`grid-template-rows: 60px 60px…`). Override the flow on `.softr-topbar [role="menu"] [role="group"]`: `grid-auto-flow: row !important; grid-template-rows: none !important; grid-auto-rows: auto !important` (leave `grid-template-columns` to preserve the menu width). Verified June 2026. See [native-chrome-styling.md](native-chrome-styling.md). |
-| Setting the page background on `body` (or any single element) — it appears to do nothing | Softr paints the SAME page fill on `html`, `body`, `#page-content`, AND a deeper class-less wrapper div, stacked — so styling one gets covered. Paint your backdrop on `html`, then clear the duplicates above it: `body`, `#page-content`, and `#page-content div` — but EXCLUDE the header subtree with `:not(.softr-topbar):not(.softr-topbar *)` (it renders inside `#page-content`, and `#page-content`'s id specificity would otherwise flatten the dropdown panel). Verified June 2026. See [native-chrome-styling.md](native-chrome-styling.md). |
+| Setting the page background on `body` (or any single element) — it appears to do nothing | Softr paints the page fill on several stacked layers, so styling one gets covered: `html`, `body`, `#page-content`, each Vibe block's host and each native block's outer `<section>` (measured 2026-10-05; the layer list is in the `html, body` row above). **Top bar only:** paint your backdrop on `html`, then clear the duplicates above it: `body`, `#page-content`, and `#page-content div` — but EXCLUDE the header subtree with `:not(.softr-topbar):not(.softr-topbar *)` (it renders inside `#page-content`, and `#page-content`'s id specificity would otherwise flatten the dropdown panel). Verified June 2026. See [native-chrome-styling.md](native-chrome-styling.md#page-background). **With Softr's sidebar,** that `div` clear would also strip `.softr-sidebar`'s fill (inferred) and never reaches native `<section>`s: use the scoped rules in [native-chrome-styling.md → App frame (navigation layout)](native-chrome-styling.md#app-frame-navigation-layout). |
 
 ## Printing
 

package/references/browser-checks.md

@@ -3,7 +3,8 @@
 How to check a deployed block's rendering and behaviour in a Softr preview with the
 [agent-browser](https://github.com/vercel-labs/agent-browser) CLI. **Verified 2026-10-01** with
 agent-browser v0.38.1 on macOS (Node 22) against a real Softr preview; only the commands under
-[Untested but promising](#untested-but-promising) were not run.
+[Untested but promising](#untested-but-promising) were not run. [Testing Custom Code header
+CSS](#testing-custom-code-header-css) was verified 2026-10-05, except where it says otherwise.
 
 ## When to use it
 
@@ -156,6 +157,160 @@ ab close                               # ✓ Browser closed (no process left beh
 Give a path; without one, it writes to a temp directory. A saved screenshot costs no tokens until
 someone opens it; one shown inline costs about 1.5k. Left alone, the daemon exits after an hour idle.
 
+## Testing Custom Code header CSS
+
+CSS in **Settings → Custom Code → Code inside header** applies to every page of the app, and the
+builder usually pastes it, not you. So test it in the preview before it is pasted, then prove what
+went live. **Verified 2026-10-05** on one app with Softr's top bar and sidebar, using the app-frame
+code in [native-chrome-styling.md → App frame (navigation layout)](native-chrome-styling.md#app-frame-navigation-layout)
+with its Vibe-host rule in the unscoped form (see step 4), with agent-browser and the desktop app's
+Browser pane; anything else is marked.
+
+**Where header code shows:** on the published app, and in the preview: after a paste and a publish,
+a fresh preview load applied it with nothing injected (verified 2026-10-05). Whether the preview
+shows header code that is pasted but not yet published is untested. The Studio editor canvas is not
+a test surface: header code is not known to render there.
+
+### 1. Before pasting: inject it into the preview
+
+Open the page as in [step 1](#1-session-preview-cookie-page), as the user whose navigation you are
+styling: on the preview origin run `fetch('/studio/impersonate/<softrUserId>')`, then open the page
+again ([how](softr-mcp.md#testing-as-any-app-user-without-logins--the-preview-as-switcher)). Then
+inject the file exactly as it will be pasted, tagged so that a re-run replaces it:
+
+```bash
+node -e '
+const h = require("fs").readFileSync("custom-code-header.html", "utf8");
+process.stdout.write(`(() => {
+  document.querySelectorAll("[data-hdr-test]").forEach(n => n.remove());
+  const t = document.createElement("template"); t.innerHTML = ${JSON.stringify(h)};
+  for (const n of [...t.content.children]) { n.setAttribute("data-hdr-test", ""); document.head.appendChild(n); }
+  return "injected";
+})()`);' > inject.js
+ab eval --stdin < inject.js            # "injected"
+```
+
+- The injected copy lasts until the next load: inject again after every `open` or reload. A width
+  change keeps it.
+- This tests the `<link>` and `<style>` parts. A `<script>` in the header is out of scope.
+- If an older version is already live, the preview carries it too and the injected copy only adds
+  to it, so a rule you deleted still applies. Remove the live `<style>` first, found by a token
+  only it contains (inferred, not run).
+- A Browser pane opened on the preview link shows the toolbar shell, with the app in the
+  same-origin `#preview-iframe`. Open the direct page URL instead, so that `document` is the app's.
+
+### 2. Measure; screenshots are the extra
+
+Computed values answer the question; a screenshot only illustrates it. A hidden pane times out on
+screenshots ([why](#tool-choice-and-why)) but measures fine, so measure first and take any
+screenshot with agent-browser, to disk. Save this as `measure.js`:
+
+```js
+(() => {
+  const q = s => document.querySelector(s), bg = e => e ? getComputedStyle(e).backgroundColor : 'none';
+  const main = q('#main-content'), sr = q('#sidebar-root'), a = sr ? getComputedStyle(sr, '::after') : null;
+  return JSON.stringify({
+    w: innerWidth, sidebar: !!q('.softr-sidebar'), tabBar: !!q('.softr-bottombar'),
+    html: bg(document.documentElement), body: bg(document.body), page: bg(q('#page-content')),
+    main: bg(main), radius: main ? getComputedStyle(main).borderTopLeftRadius : 'none',
+    host: bg(q('#main-content [data-role="vibe-block-root"]')),
+    corner: a ? a.content + ' @ ' + a.left : 'none',
+    overflowX: document.documentElement.scrollWidth - document.documentElement.clientWidth,
+  });
+})()
+```
+
+What the verified live code gave (2026-10-05; its Vibe-host rule was the unscoped
+`#main-content [data-role="vibe-block-root"]`, and the recipe's scoped form is untested):
+
+| Window | Navigation | `html`, `body`, `#page-content` | `#main-content` | `corner` |
+|---|---|---|---|---|
+| 768px and wider | top bar + sidebar | frame colour | sheet colour, 24px radius | `"" @ 280px` open, `"" @ 57px` collapsed |
+| 767px and narrower | phone tab bar | sheet colour | transparent (`rgba(0, 0, 0, 0)`), 0px radius; the paper is on `html`, `body` and `#page-content` | `none @ auto` |
+
+At the widths checked for it (1440, 1024 and 390/375) the Vibe host was `rgba(0, 0, 0, 0)` and
+there was no sideways scroll. On phones `#sidebar-root` is still in the DOM, empty, 0px wide and
+`position: static` (not sticky), which is why the corner rule is guarded with
+`:has(.softr-sidebar)`. Without the guard the `::after` still renders there and is placed against
+the page: likely off the right edge, adding sideways scroll (seen in a mock, not on Softr).
+
+### 3. The width sweep
+
+```bash
+for w in 1440 1280 1024 900 768 767 390; do ab set viewport $w 900; ab wait 1200; ab eval --stdin < measure.js; done
+```
+
+Then collapse the sidebar (the top bar's "Toggle sidebar" button, a ref from `snapshot -i`; it
+writes nothing) and measure 1024 and 768 again.
+
+- **767 / 768 is Softr's switch, to the pixel:** 767 gives the phone tab bar, 768 the top bar and
+  sidebar. At 768 with the sidebar open, a block gets 488px.
+- **A plain width change switches the layout live.** `ab set viewport` alone moved between sidebar
+  and tab bar; no reload needed.
+- **Reload after leaving a mobile-device emulation.** A pane loaded under a mobile preset (an
+  Android user agent and touch points, not just a width) kept the phone layout when widened to
+  1440, until a reload (seen 2026-10-05; most likely a device check at load, inferred).
+- **The collapsed sidebar stayed collapsed** at later widths in one headless run (seen once):
+  open it again, or expect 57px.
+
+### 4. Pages without navigation
+
+The recipe scopes its rules with `:has(.softr-sidebar, .softr-bottombar)`, so pages without Softr's
+navigation (log in, sign up, 404) should keep Softr's own colours.
+
+- **Before pasting:** inject on a 404 page in the preview (any path that does not exist): `html`
+  and `body` stayed rgb(255,255,255). A logged-in preview sends `/login` to the home page, so
+  `/login` cannot be checked there.
+- **Once pasted:** open `/login` and a 404 page on the published app, logged out. With the code
+  live, `html`, `body` and `#page-content` stayed white on both, with no top bar, sidebar or tab
+  bar (verified 2026-10-05).
+- **The Vibe-host rule depends on which form you have.** In the verified live code it was unscoped
+  (`#main-content [data-role="vibe-block-root"]`) and applied on these pages too; on a page without
+  navigation that holds a Vibe block it is probably invisible, because the page behind the block
+  is the same theme colour (inferred). The recipe scopes it with `:has(.softr-sidebar,
+  .softr-bottombar)`, so nothing should apply there (untested as written). Either way, no page
+  without navigation but with a Vibe block was tested: on one, check that the host keeps the
+  theme white.
+
+### 5. After the paste: prove what is live
+
+**A publish publishes everything.** Header code reaches the published app with a publish, and a
+publish also pushes every unpublished page live (seen 2026-10-05: unfinished pages went live with a
+header-code publish). Before asking anyone to publish header code, check what else is unpublished,
+and say so in the ask.
+
+Then fetch the published page and pull the code out. Softr carries it in an inline script as
+`appCustomHeaderCode: "…"`, an unquoted key inside `SoftrPageRenderer.render({…})`: JavaScript, not
+JSON, so read the string literal rather than parsing the object. `json.loads` read Softr's string on
+2026-10-05:
+
+```bash
+curl -sL 'https://<subdomain>.softr.app/' -o pub.html
+python3 - <<'EOF'
+import json, re
+s = open('pub.html').read()
+m = re.search(r'appCustomHeaderCode:\s*("(?:[^"\\]|\\.)*")', s)
+if not m: raise SystemExit('appCustomHeaderCode not found: wrong page, a redirect or an empty body; fetch / again')
+live = json.loads(m.group(1))
+mine = open('custom-code-header.html').read()
+rules = lambda t: re.sub(r'\s+', '', re.sub(r'<!--.*?-->|/\*.*?\*/', '', t, flags=re.S))
+print(len(live), 'bytes live;', 'rules match' if rules(live) == rules(mine) else 'RULES DIFFER')
+EOF
+#   1516 bytes live; rules match
+```
+
+- **Compare the rules, not the text.** The pasted copy can lose or shorten comments; it did on
+  2026-10-05, and the rules still matched.
+- **`pageCustomHeaderCode`** is the page-level header code, and `appCustomFooterCode` /
+  `pageCustomFooterCode` are the footers: check that they are empty, or hold what you expect.
+- **The page source opens with `<!-- Last Published: … -->`.** Check that it moved, so you are not
+  reading the previous publish.
+- The key is in every page's source, logged out too: it was the same on Home, `/login` and a 404
+  page.
+
+Then run the sweep again in a fresh preview with nothing injected, and the pages without navigation
+on the published app, logged out.
+
 ## Gotchas
 
 - **zsh does not word-split.** `AB="agent-browser --session x"; $AB open …` fails with "command not

package/references/common-patterns.md

@@ -17,6 +17,9 @@ Small reusable patterns that come up across Vibe Coding blocks but don't warrant
 - [Drag-to-Reorder Rows](#drag-to-reorder-rows)
 - [Create → open](#create--open)
 - [Clickable Row with an Inner Link](#clickable-row-with-an-inner-link)
+- [Measure the block, not the window](#measure-the-block-not-the-window)
+- [Clear Softr's sticky bars](#clear-softrs-sticky-bars)
+- [A modal above Softr's bars](#a-modal-above-softrs-bars)
 
 ## Cross-Page State with localStorage + URL Parameters
 
@@ -515,4 +518,223 @@ 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`). 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.
+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. On a page with Softr's top bar, a row scrolled in from above the window can land under the bar: give the rows a `scroll-margin-top` or scroll the window yourself, as in [Clear Softr's sticky bars](#clear-softrs-sticky-bars). 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.
+
+## Measure the block, not the window
+
+Beside Softr's sidebar navigation, the window over-reports the block's width by the width of the sidebar: 280px by default, 57px collapsed, 200 to 360px when dragged. Lay the block out by its own width. CSS container queries do most of it (`@container` on a wrapper, `@min-[NNrem]:` on what is inside it; see [ui-ux-guidelines.md → Breakpoint strategy](../ui-ux-guidelines.md#breakpoint-strategy)), so reach for CSS first. When a decision can't be made in CSS, measure the block in JS. Typical cases: rendering a different tree (list and detail side by side, or a phone flow with its own back control), or choosing how many chart ticks to draw.
+
+```tsx
+import { useLayoutEffect, useRef, useState } from "react";
+
+// Module scope, like any hook or component. The block's own width: the space Softr gives it.
+function useElementWidth(ref: { current: HTMLElement | null }) {
+  const [width, setWidth] = useState<number>(() => (typeof window !== "undefined" ? window.innerWidth : 1200));
+  // useLayoutEffect, not useEffect: measured before the first paint, so no frame is laid out at the window's width.
+  useLayoutEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    const update = () => setWidth(el.getBoundingClientRect().width);
+    update();
+    if (typeof ResizeObserver === "undefined") {
+      window.addEventListener("resize", update);
+      return () => window.removeEventListener("resize", update);
+    }
+    const ro = new ResizeObserver(update);
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, []);
+  return width;
+}
+
+export default function Block() {
+  const rootRef = useRef<HTMLDivElement>(null);
+  const width = useElementWidth(rootRef);
+  const wide = width >= 860; // 340px list + 20px gap + at least 440px of detail + padding
+  return (
+    <div ref={rootRef} className="@container">
+      {wide ? <ListAndDetail /> : <PhoneFlow />}
+    </div>
+  );
+}
+```
+
+- **`useLayoutEffect`, not `useEffect`.** A passive `useEffect` runs after the browser paints, so the first frame is laid out with the initial guess: the window's width. Beside a sidebar that guess is out by up to 360px, and the layout visibly flips. At a 1200px window with a 360px sidebar the block is 840px, but the first frame would paint the two-column skeleton and then switch to one column. `useLayoutEffect` measures and re-renders before the first paint. (A code-review finding, 2026-10-05; the fix shipped in two blocks.)
+- **Put the ref on the block's outer wrapper, and render that wrapper in every state, loading included.** The effect runs once, so a ref that attaches only after the data loads is never observed. Measure the wrapper, not an element whose width depends on the decision the width drives.
+- **Keep padding off the `@container` element** when CSS and JS both switch on width. Container queries read its content box and `getBoundingClientRect()` reads its border box. With no padding or border they are the same number, so `@min-[860px]:` and `width >= 860` agree.
+- The window `resize` listener is only the fallback for a browser without `ResizeObserver`. The observer also sees what a resize event never reports: the sidebar collapsing or being dragged while the window stays the same size.
+- Thresholds one app uses: a chart labels every other month below a 640px block, and list and detail sit side by side from an 860px block.
+
+## Clear Softr's sticky bars
+
+On a page with Softr navigation, Softr's bars live in the main document, outside the block, and the page scrolls under them (measured live 2026-10-05):
+
+| Bar | Shows at | Element | Height | Position |
+|---|---|---|---|---|
+| Top bar | a window of 768px and up | `#topbar-root` | 56px | sticky, top 0, z-index 800 |
+| Phone tab bar | a window below 768px | `#bottombar-root` | 57px rendered (`#bottombar-root` and its `ul` both measured 57px; Softr's variable says 55px) | sticky in the page grid's bottom row (not `fixed`), z-index 800 |
+
+The block host hands their sizes to block CSS. `--nav-height` is 56px with the top bar; on phones Softr leaves its own variable empty and the host's fallback gives 0px. `--bottombar-height` is `calc(0px + 55px)` on phones (2px short of the rendered bar) and 0px otherwise. `--sidebar-width` is 280px with the sidebar open, 57px collapsed and 0px on phones. The host maps them from Softr's `:root` variables `--sticky-nav-height`, `--softr-bottombar-height` and `--softr-sidebar-width`, each with a `0px` fallback (all measured live 2026-10-05). The variable table is in [quick-reference.md → Softr navigation variables](quick-reference.md#softr-navigation-variables); the whole page layout is in [native-chrome-styling.md → App frame (navigation layout)](native-chrome-styling.md#app-frame-navigation-layout).
+
+**Sticky elements inside a block.** A `sticky top-4` slides under the top bar. Offset it by the bar, and cap a sticky pane so its foot stays on screen:
+
+```tsx
+<section
+  className="sticky flex flex-col"
+  style={{
+    top: "calc(var(--nav-height, 0px) + 16px)",
+    maxHeight: "calc(100dvh - var(--nav-height, 0px) - 32px)", // 16px of air above and below
+  }}
+>
+```
+
+Measured live 2026-10-05 in the preview at a 1440px window: the pane's top sat at 72px (56 + 16). The mirror image for a phone, `bottom: calc(var(--bottombar-height, 0px) + 16px)`, is untested.
+
+**Scripted window scrolls and room checks.** JS sees the window, not the bars. Code that scrolls the window to bring something into view, or asks whether a popover has room above or below, must take the top bar (56px) off the top edge and, on phones, the tab bar (57px as rendered) off the bottom edge. Softr switches its navigation on the window width, so here the window is the right thing to test:
+
+```tsx
+const TOP_BAR = 56; // Softr's sticky top bar, window 768px and up
+const TAB_BAR = 57; // Softr's phone tab bar, window below 768px: measured 57px; --softr-bottombar-height says 55px
+const AIR = 16;
+
+// The strip of the window that Softr's bars leave visible.
+function visibleStrip() {
+  const phone = window.innerWidth < 768; // 767px = tab bar, 768px = top bar + sidebar
+  return {
+    top: (phone ? 0 : TOP_BAR) + AIR,
+    bottom: window.innerHeight - (phone ? TAB_BAR : 0) - AIR,
+  };
+}
+
+function keepInView(el: HTMLElement) {
+  const { top, bottom } = visibleStrip();
+  const r = el.getBoundingClientRect();
+  if (r.top < top) window.scrollBy(0, r.top - top);
+  else if (r.bottom > bottom) window.scrollBy(0, r.bottom - bottom);
+}
+
+// It issues a window scroll, so call it as setTimeout(() => keepInView(el), 0) (Hard Constraint 17).
+```
+
+The project this comes from hard-coded 72px (a bar plus 16px) at the top, and at the bottom wherever a tab bar could be. That number is a project choice; subtracting the bars is the rule. `visibleStrip` generalises it and is untested as written. A confirm strip that opens below a row, or a drop-up test, uses the same strip in place of `0` and `window.innerHeight`. For the dropdown, see [searchable-dropdown.md → rule 2](searchable-dropdown.md#the-four-things-that-will-bite-you).
+
+**Read the host variables only inside CSS `calc()`.** They are unregistered custom properties, so in JS `getComputedStyle(el).getPropertyValue(...)` returns the token that was set, not a length. `--nav-height` reads `56px` on desktop, but `--bottombar-height` reads `calc(0px + 55px)` on phones (both measured live 2026-10-05). `parseFloat` turns that into `NaN` (inferred, not run in a block), and a `|| 0` fallback would then scroll content under the tab bar without a sound. In CSS both forms work. In JS, use the bar heights above.
+
+**Fragment jumps are offset; inner scrolls are not.** Softr's page CSS gives every block's outer wrapper (`div[data-block]`, with a page-assigned id such as `ai1`; the Vibe host sits two levels inside it) `#main-content [data-block] { scroll-margin-top: var(--sticky-nav-height, 0px) }` (the rule was read from Softr's live page CSS on 2026-10-05; the jump itself is untested), so a URL fragment that targets that wrapper lands below the top bar. Nothing offsets a scroll to an element *inside* the block: `scrollIntoView` on a row or a section can put it at the window's top edge, under the bar. Give the target `scroll-margin-top: calc(var(--nav-height, 0px) + 16px)`, which `scrollIntoView` honours (untested in a block), or scroll the window with `keepInView`. A fragment can't reach inside the shadow root in the first place; see [static-blocks.md → Section anchors](static-blocks.md#section-anchors-on-landing-pages).
+
+## A modal above Softr's bars
+
+On an app page with Softr's navigation, shadcn's `Dialog` and `Sheet` don't work cleanly. Two things go wrong:
+
+- **It sits under the top bar.** shadcn's overlay is `z-50`; Softr's sticky `#topbar-root` is z-index 800. The top bar stays undimmed and clickable, and a tall modal slides under it. Measured live 2026-10-06 in the preview at 1440×900 with the top bar and sidebar: a `position: fixed` layer inside a block's shadow root at z-index 50 lost to the top bar (`document.elementFromPoint` inside the bar returned the bar); at z-index 801 and at 1000 the same layer covered the top bar and the sidebar. A walk up from the block host to `<html>` found no stacking context (every ancestor static / `auto`, no `transform`, `contain` or `container-type`), so a block's z-index competes directly with Softr's bars.
+- **It leaves the shadow root.** Radix portals the dialog to `document.body`, outside the block's shadow root, and the block's styles stay behind — the same reason shadcn `<Select>` is out ([searchable-dropdown.md](searchable-dropdown.md)).
+
+Render the modal in the block's own DOM instead. This is the reusable core of the record modal that shipped in the Partner Spotlight review block on 2026-10-06:
+
+```tsx
+import { useEffect, useRef } from "react";
+import { X } from "lucide-react";
+
+const FOCUSABLE =
+  'a[href], button:not([disabled]), input:not([disabled]):not([type="hidden"]), textarea:not([disabled]), video[controls], [tabindex]:not([tabindex="-1"])';
+
+// Module scope. onDismiss must itself refuse while a save runs (Escape and the backdrop call it too).
+function InBlockModal({ labelledBy, describedBy, onDismiss, dismissDisabled, children }: {
+  labelledBy: string; describedBy?: string; onDismiss: () => void; dismissDisabled?: boolean; children: React.ReactNode;
+}) {
+  const panelRef = useRef<HTMLDivElement | null>(null);
+  const dismissRef = useRef(onDismiss); // the latest handler; the listener is attached once per opening
+  dismissRef.current = onDismiss;
+
+  useEffect(() => {
+    const panel = panelRef.current;
+    // Inside a shadow root document.activeElement is the block's host; the root knows the real element.
+    const root: any = panel ? panel.getRootNode() : document;
+    const opener = (root.activeElement as HTMLElement | null) || null;
+
+    // Lock the page behind the modal; the stable gutter stops a sideways jump where scrollbars take space.
+    const html = document.documentElement;
+    const prevOverflow = html.style.overflow;
+    const prevGutter = html.style.getPropertyValue("scrollbar-gutter");
+    html.style.overflow = "hidden";
+    html.style.setProperty("scrollbar-gutter", "stable");
+    const focusTimer = window.setTimeout(() => panel?.focus({ preventScroll: true }), 0);
+
+    const onKey = (e: KeyboardEvent) => {
+      if (e.defaultPrevented || e.isComposing) return;
+      if (e.key === "Escape") { e.preventDefault(); dismissRef.current(); return; }
+      if (e.key !== "Tab" || !panel) return;
+      // Visible controls only: getClientRects() is empty for anything display: none.
+      const items = Array.from(panel.querySelectorAll<HTMLElement>(FOCUSABLE)).filter((el) => el.getClientRects().length > 0);
+      if (!items.length) { e.preventDefault(); panel.focus(); return; }
+      const current = root.activeElement as HTMLElement | null;
+      const inside = !!current && current !== panel && panel.contains(current);
+      const first = items[0], last = items[items.length - 1];
+      if (e.shiftKey && (!inside || current === first)) { e.preventDefault(); last.focus(); }
+      else if (!e.shiftKey && (!inside || current === last)) { e.preventDefault(); first.focus(); }
+    };
+    document.addEventListener("keydown", onKey);
+
+    return () => {
+      window.clearTimeout(focusTimer);
+      document.removeEventListener("keydown", onKey);
+      html.style.overflow = prevOverflow;
+      if (prevGutter) html.style.setProperty("scrollbar-gutter", prevGutter);
+      else html.style.removeProperty("scrollbar-gutter");
+      if (opener && opener !== panel && opener.isConnected) opener.focus({ preventScroll: true });
+    };
+  }, []);
+
+  return (
+    // z-[1000]: above Softr's top bar, sidebar and phone tab bar (all z-index 800 or below).
+    <div className="fixed inset-0 z-[1000] flex items-center justify-center p-2 sm:p-6">
+      <div aria-hidden="true" className="absolute inset-0 bg-gray-950/50" onClick={() => dismissRef.current()} />
+      <div
+        ref={panelRef}
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby={labelledBy}
+        aria-describedby={describedBy}
+        tabIndex={-1}
+        className="@container relative flex max-h-full w-full max-w-4xl flex-col overflow-hidden rounded-2xl bg-white shadow-2xl outline-none"
+      >
+        {children}
+        <button
+          type="button"
+          onClick={() => dismissRef.current()}
+          disabled={dismissDisabled}
+          aria-label="Close"
+          className="absolute right-3 top-3 rounded-lg p-2 text-gray-500 hover:bg-gray-100 disabled:pointer-events-none disabled:opacity-40"
+        >
+          <X className="h-4 w-4" />
+        </button>
+      </div>
+    </div>
+  );
+}
+
+export default function Block() {
+  // ... state, `active` record, `saving`, a `close` that returns early while saving ...
+  return (
+    <>
+      <div className="@container">{/* the block's page */}</div>
+      {/* A sibling of the @container wrapper, not a child of it. */}
+      {active && (
+        <InBlockModal labelledBy="modal-title" describedBy="modal-desc" onDismiss={close} dismissDisabled={saving}>
+          {/* header with id="modal-title" / id="modal-desc"; give it right padding (pr-12) for the X */}
+          {/* a scrolling body: min-h-0 flex-1 overflow-y-auto */}
+        </InBlockModal>
+      )}
+    </>
+  );
+}
+```
+
+- **Outside the block's `@container` wrapper.** `@container` sets `container-type: inline-size`, which brings layout containment, and containment on an ancestor can capture `position: fixed` (it becomes the fixed box's containing block). Render the modal as a sibling of that wrapper, then put `@container` on the panel so everything inside it sizes by the panel. The overlay itself is fixed to the window, so its own padding may use `sm:`.
+- **z-index 1000, not 50.** Anything from 801 up clears the bars; 1000 leaves room. It also keeps Softr's links out of reach while an edit is open.
+- **Focus lives in the shadow root.** Read the focused element from `panel.getRootNode().activeElement`; `document.activeElement` is only the block's host. The opener is captured on open, and focus goes back to it on close if it is still on the page.
+- **Saving.** Disable the X while a save runs, and make the dismiss handler return early while saving, because Escape and the backdrop call the same handler. In the shipped block that handler also asks before discarding unsaved edits.
+- **Scroll lock on `<html>`**, not `body`: the page scroller is the document. Restore both properties exactly as they were.
+- The shipped component also has `animate-in fade-in-0 zoom-in-95` on the panel and `backdrop-blur-[2px]` on the backdrop.
+
+**Status (2026-10-06).** Verified live, harness: the shipped component's exact source was bundled with `deno bundle` and mounted into a shadow root under `#main-content` on the live preview page, rendered with Softr's own React 18.2 (`window.__softr_React` / `window.__softr_ReactDOM`), 1440×900 window with top bar and sidebar. Passed: opens with focus on the panel; covers the top bar and the sidebar; the panel centres at 896px; Tab and Shift+Tab wrap both ways and skip hidden controls; Escape and the X do nothing while saving; Escape, the backdrop and the X close it; `overflow` and `scrollbar-gutter` are restored; focus returns to the opener. **Not yet seen:** the full review block opening the modal with real data — there was no Social Media Manager member to preview as. The trimmed version above was not run on its own. Phones (tab bar) untested.

package/references/dembrandt.md

@@ -73,7 +73,7 @@ dembrandt emits Google's DESIGN.md draft format (spec 0.4) `[official]`: YAML fr
 | `rounded` | `sm` / `md` / `lg` / `xl` radii, plus `none` (0) and `full` (pill) when observed `[official, emitter source]` |
 | `components` | `button-observed` / `input-observed` with backgroundColor, textColor, rounded, padding (buttons may add `height`) — values may reference other tokens (`"{rounded.lg}"`) |
 
-Body sections in order: `# Design System` → Overview → Colors → Typography → Layout (spacing scale + responsive breakpoints) → Elevation & Depth → Shapes → Components. Two body-only nuggets matter for Softr work `[behavior-tested]`:
+Body sections in order: `# Design System` → Overview → Colors → Typography → Layout (spacing scale + responsive breakpoints, which are the source site's window widths; for a Softr app with a sidebar, restate them as block widths, see below) → Elevation & Depth → Shapes → Components. Two body-only nuggets matter for Softr work `[behavior-tested]`:
 
 - **Font URLs** (in the Typography section): direct `.woff2` links to the site's real webfonts. The frontmatter `fontFamily` reports the *computed* value, which can be a generic fallback (`ui-sans-serif`) while the Font URLs reveal the actual brand font — cross-check before declaring the brand font, and use these URLs when authoring page-level `@font-face` CSS.
 - Motion tokens exist in dembrandt's JSON extraction but are **not** part of DESIGN.md `[official]` — don't expect an animation section.
@@ -82,7 +82,12 @@ Companion-skill note: the `building-design-md` skill (v2+) drives this same demb
 
 ## Authoring `custom-code-header.html` from DESIGN.md
 
-dembrandt generates **no Softr-ready CSS** — its only CSS export is a CLI-side Tailwind v4 `@theme` file (`--tailwind`), which Softr's Custom Code header has no use for. When the app needs global brand CSS in Softr's **Settings → Custom Code → Code inside header** (webfont loading, `--brand-*` custom properties, native-chrome restyling), the agent authors that CSS from the DESIGN.md: `<link>`/`@font-face` from the Font URLs, custom properties from `colors`. House convention keeps this CSS in a `custom-code-header.html` file in the project folder — see [native-chrome-styling.md](native-chrome-styling.md). The shadow-DOM rules are unchanged: that global CSS reaches native chrome but never the inside of a block ([anti-patterns.md](anti-patterns.md)).
+dembrandt generates **no Softr-ready CSS** — its only CSS export is a CLI-side Tailwind v4 `@theme` file (`--tailwind`), which Softr's Custom Code header has no use for. When the app needs global brand CSS in Softr's **Settings → Custom Code → Code inside header** (webfont loading, `--brand-*` custom properties, native-chrome restyling), the agent authors that CSS from the DESIGN.md: `<link>`/`@font-face` from the Font URLs, custom properties from `colors`. Give the font `<link>` an id that the blocks check before injecting their own copy, so the fonts load once with or without the header ([anti-patterns.md](anti-patterns.md), the custom-code-header font row). House convention keeps this CSS in a `custom-code-header.html` file in the project folder — see [native-chrome-styling.md](native-chrome-styling.md). The shadow-DOM rules are unchanged: that global CSS reaches native chrome but never the inside of a block ([anti-patterns.md](anti-patterns.md)).
+
+**Apps with Softr's sidebar navigation** need two things the extraction cannot know (measured on one app, 2026-10-05):
+
+- **Layout thresholds are block widths, not window breakpoints.** The sidebar takes 57–360px of the window (280px by default), so a block is 744px wide at a 1024px window and 488px at 768. Write DESIGN.md's Layout rules as block widths ("four figures per row from a 52rem block", not "from `md`"), because the blocks build them with container queries — see [SKILL.md → App pages beside Softr navigation](../SKILL.md#app-pages-beside-softr-navigation).
+- **The app frame needs its own tokens.** Record a frame colour that copies the Studio theme colour of the top bar and sidebar, e.g. `#A85935`, not the brand primary: on that app they differed (DESIGN.md primary `#B4532A`). Add the sheet colour the blocks sit on (often DESIGN.md's `surface`, which then describes the sheet the header paints, not a block background) and the sheet's corner radius (24px there). The header carries them as `--app-frame`, `--app-sheet` and `--app-radius` — recipe in [native-chrome-styling.md → App frame (navigation layout)](native-chrome-styling.md#app-frame-navigation-layout). Softr's own theme variables are hashed, so the header cannot reference them: when the theme colour changes in Studio, change `--app-frame` by hand.
 
 ## Optional: brand-drift QA with `compute_drift`
 

package/references/helper-blocks.md

@@ -83,7 +83,11 @@ function getLinkedItems(f) {
     if (x && typeof x === "object") return { id: x.id || "", title: x.label || x.name || x.title || "" };
     return { id: "", title: String(x) };
   }).filter(function(o) { return o.id || o.title; });
-  return [];
+  if (typeof f === "object") {            /* a single link arrives as one { id, label } object */
+    var t = f.label || f.name || f.title || "";
+    return (f.id || t) ? [{ id: f.id || "", title: t }] : [];
+  }
+  return [{ id: "", title: String(f) }];
 }
 ```
 
@@ -362,7 +366,7 @@ When you change a helper's output shape (e.g., `advisorOffice` from array to str
 1. Document the published shape as a comment at the top of the helper file and update all consumers in the same commit.
 2. Version the namespace (`__myapp_projects_v2`) -- old consumers keep reading v1 until migrated.
 
-Defensive consumers can use `Array.isArray(x) ? x.map(...) : x` when shape might vary, but don't lean on this -- it hides bugs.
+Defensive consumers can use `Array.isArray(x) ? x.map(...) : x` when shape might vary, but don't lean on this -- it hides bugs. (That is about the shape of a global *you* publish. Linked-record values read from Softr are different: they arrive as a single `{ id, label }` object or as an array, and must always be normalised -- see [fields.md](../datasources/fields.md).)
 
 ### useState, Not useRef, for IDs Consumed by useMemo