softr-vibe-coding 2.13.3 → 2.13.5

package/references/native-chrome-styling.md

@@ -1,16 +1,17 @@
-# Styling Softr's Native Shell (Header · Footer · Page Background) via Custom Code
+# Styling Softr's Native Shell (Header · Sidebar · Footer · Page Background · App Frame) via Custom Code
 
-**This is NOT about Vibe Coding blocks.** Softr's top bar, navigation, dropdown menus, footer, and the page background are part of the *native app shell* — configured in Softr Studio and rendered in the **main document**, not inside a block's shadow DOM. You **cannot** build or replace the native chrome itself as a Vibe Coding block. To re-skin it, add **CSS to Settings → Custom Code → Code inside header** (the same place brand fonts/tokens live — house convention keeps that CSS in a `custom-code-header.html` file in the project folder and pastes it into the setting; you author it from the project's DESIGN.md tokens, since dembrandt supplies the palette and webfont URLs but generates no Softr-ready CSS — see [dembrandt.md](dembrandt.md#authoring-custom-code-headerhtml-from-designmd)). Pure CSS — no markup, no JS — and the native chrome stays in place, so Softr's auth-aware nav (account menu, sign-out, user-group gating) keeps working. (Separate pattern, different problem: a landing page with the native header **hidden** can carry a block-owned in-block header — see [Restyle vs. replace vs. block-owned header](#restyle-vs-replace-vs-block-owned-header).)
+**This is NOT about Vibe Coding blocks.** Softr's top bar, sidebar, phone tab bar, navigation, dropdown menus, footer, and the page background are part of the *native app shell* — configured in Softr Studio and rendered in the **main document**, not inside a block's shadow DOM. You **cannot** build or replace the native chrome itself as a Vibe Coding block. To re-skin it, add **CSS to Settings → Custom Code → Code inside header** (the same place brand fonts/tokens live — house convention keeps that CSS in a `custom-code-header.html` file in the project folder and pastes it into the setting; you author it from the project's DESIGN.md tokens, since dembrandt supplies the palette and webfont URLs but generates no Softr-ready CSS — see [dembrandt.md](dembrandt.md#authoring-custom-code-headerhtml-from-designmd)). Pure CSS — no markup, no JS — and the native chrome stays in place, so Softr's auth-aware nav (account menu, sign-out, user-group gating) keeps working. (Separate pattern, different problem: a landing page with the native header **hidden** can carry a block-owned in-block header — see [Restyle vs. replace vs. block-owned header](#restyle-vs-replace-vs-block-owned-header).)
 
-This doc covers the **header / nav / dropdowns**, the **footer**, the **floating "island" treatment** for both, and the **page background** — which is trickier than it looks, because Softr stacks the same fill on several layers.
+This doc covers the **header / nav / dropdowns**, the **footer**, the **floating "island" treatment** for both, the **page background** — which is trickier than it looks, because Softr stacks the same fill on several layers — and the **app frame**: in an app with Softr's sidebar navigation, painting around the top bar and sidebar so the content reads as one sheet inside them ([App frame](#app-frame-navigation-layout)).
 
-> **Mirror of the block rule.** Global `custom-code-header.html` CSS reaches native chrome (main document) but **not** blocks (shadow DOM). Inside a block you apply brand styles inline; for native chrome you apply them with this global CSS. (See [anti-patterns.md](anti-patterns.md) for the block side.)
+> **Mirror of the block rule.** Global `custom-code-header.html` CSS reaches native chrome (main document) but **not** blocks (shadow DOM). Inside a block you apply brand styles inline; for native chrome you apply them with this global CSS. (See [anti-patterns.md](anti-patterns.md) for the block side.) Of a Vibe block it reaches only the **host `<div>`**, which sits in the main document — that is how the app frame makes a block's background transparent — never anything inside the shadow root. Native Softr blocks render in the main document, so it reaches them whole.
 
 ## Selector discipline — the #1 rule
 
-Softr's rendered markup carries two kinds of classes:
+Softr's rendered markup carries two kinds of names:
 
 - **Hashed build classes** like `f8f11e5_m9ntthp` — **NEVER target these.** Softr regenerates the hash on every deploy, so your rules silently die.
+- **Hashed CSS variables** like `--_5f91d6c_vnohg20` — same rule: **never target them and never `var()` them.** Softr's theme colours reach the page through these (the sidebar fill, the theme background), so when you need a theme value, copy it by hand and keep it in your own token ([App frame](#app-frame-navigation-layout) does this). The prefix belongs to a **native block package**, not to the app: on 2026-10-05 the prefixes carried a leading underscore, `_5f91d6c_` on the navigation and 404 blocks and `_03ef538_` on the Account settings (user-accounts) block; the June 2026 notes recorded `f8f11e5_` without one. Don't hard-code a prefix either; it regenerates with the hash.
 - **Stable hooks** — target these instead:
 
 | Element | Stable selector |
@@ -22,8 +23,24 @@ Softr's rendered markup carries two kinds of classes:
 | Nav buttons / dropdown triggers | `.softr-nav-button` |
 | Overflow "…" trigger | `.softr-nav-category` |
 | Active / current link | `.softr-nav-link[data-active="true"]` |
+| Active-link underline | `.softr-nav-link::before` — a 2px bar 41px down the 56px bar (verified live 2026-10-05) |
 | Open dropdown trigger | `.softr-nav-button[aria-expanded="true"]` |
 
+**Navigation-layout shell** — apps whose Studio navigation puts a sidebar beside the content (seen in one such app's `featureFlags` as `navigationLayout: true`; whether the flag marks sidebar apps is untested, so test for `.softr-sidebar` instead). All verified live 2026-10-05:
+
+| Element | Stable selector | Notes |
+|---|---|---|
+| Page grid | `#page-content` (classes `content spr-content-root`) | CSS grid: `grid-template-areas: "topbar topbar" "sidebar main" "bottombar bottombar"`, `grid-template-columns: auto minmax(0, 1fr)`. Children: the three roots below, the navigation placeholder and `#main-content` |
+| Top bar root | `#topbar-root` | grid-area `topbar`; sticky, top 0, z-index 800; the bar is 56px tall |
+| Sidebar root | `#sidebar-root` | sticky, top 56px, z-index 1 (static on phones). **Also present on phones, empty and 0px wide** — scope rules on `.softr-sidebar`, never on this id |
+| Sidebar | `.softr-sidebar[data-testid="sidebar"]` | Paints the Studio theme colour. `[data-open="true"]` 280px by default; `[data-open="false"]` 57px, collapsed from the top-bar toggle |
+| Sidebar resize handle | `.softr-sidebar > [role="separator"]` | Drag range 200–360px (`aria-valuemin` / `aria-valuemax`). Softr already keeps it at opacity 0 until hover — no CSS needed to hide it |
+| Sidebar toggle | the top-bar `<button>` holding a visually hidden span "Toggle sidebar" | No `aria-label` and no `softr-*` class; find it by that text in scripts and tests |
+| Phone tab bar root | `#bottombar-root` | sticky (not fixed), z-index 800. Also present on desktop, 0px tall |
+| Phone tab bar | `ul.softr-bottombar[data-testid="bottombar"]` | Only below a 768px window. White; items are `a.softr-nav-link[data-active]`, plus buttons that open dialogs (`aria-haspopup="dialog"`) |
+| Content column | `main#main-content` | grid-area `main`; `display: flex; flex-direction: column; min-height: 100dvh`; transparent. Every block's wrapper is a child of it |
+| Navigation placeholder | `.spr-navigation-placeholder` | The nav block's own node, 0×0; its UI renders into the three roots, so there is nothing to style here |
+
 **Dropdown menus have NO `softr-*` class** — they're **Radix UI**, so target ARIA / Radix attributes (stable across deploys):
 
 | Element | Stable selector |
@@ -75,7 +92,8 @@ Scope dropdown rules under `.softr-topbar` (Softr renders the header menu *insid
 
 - **Nav font defaults to Inter.** Your brand `@font-face`/`<link>` loads globally, but the bar's `font-family` is set on Softr's classes — you must target `.softr-nav-link` / `.softr-nav-button` to change it.
 - **Icon + label color** comes from Softr's classes, so a plain `color:` on the link often doesn't take — use the `* { color: inherit !important }` trick above (SVGs use `currentColor`, so they follow too).
-- **Custom code renders on the PUBLISHED app only — not in the Studio editor.** The header looks unchanged in the builder; always verify on the live app.
+- **Header custom code renders on the published app AND in Softr's preview — not in the Studio editor.** The preview half is verified live 2026-10-05: a fresh preview load, with nothing injected, applied the app-level header code (seen after a publish; whether the preview shows a pasted but unpublished change is untested — inject it instead, see [browser-checks.md](browser-checks.md#testing-custom-code-header-css)). The editor canvas is still not known to render it: the header looks unchanged in the builder, so check in preview or on the live app.
+- **Confirm the code is live from the page source (verified live 2026-10-05).** The published page's HTML carries the app-level code as `appCustomHeaderCode: "…"` inside `SoftrPageRenderer.render({…})` — an unquoted key in an inline script, not a JSON key, so search for `appCustomHeaderCode:` without quotes around the key. `appCustomHeaderCode: ""` means nothing is published. Every page carries it, `/login` and a 404 page too, so a logged-out fetch of the published app is enough. `pageCustomHeaderCode` sits beside it: **page-level** header code also exists, so check it too when a page behaves differently from the rest. To test CSS before it is pasted, see [browser-checks.md](browser-checks.md#testing-custom-code-header-css).
 - **Account avatar on a dark bar:** Softr's logged-in account button can blend into a dark bar — give it a contrasting ring if you darken the surface.
 
 ## Gotcha: dropdown panel has a tall blank gap below the items
@@ -188,14 +206,26 @@ Two details worth copying:
   never appears under the logo or the social glyphs, and use `currentColor` so the footer's own colour
   rules keep working untouched.
 
-Same caveat as everything else here: **it renders on the published app only.** The Studio editor keeps
-showing the old arrangement, which reads exactly like "the script did not run."
+Same caveat as everything else here: **it does not render in the Studio editor.** The editor keeps
+showing the old arrangement, which reads exactly like "the script did not run." Check on the published
+app (Softr's preview applies header code too; verified for CSS after a publish on 2026-10-05, not for a script).
 
 ## Page background
 
-**The trickiest one — Softr paints the SAME fill on FOUR stacked layers:** `html`, `body`, `#page-content` (stable id; classes `content spr-content-root`), AND a deeper **class-less wrapper div** nested a few levels inside `#page-content`. Style any one layer and the ones above cover it — this is why setting `body` alone appears to "do nothing."
+**The trickiest one — Softr paints the SAME fill, the Studio theme background, on several stacked layers.** Measured live 2026-10-05:
+
+| Layer | What paints it |
+|---|---|
+| `html`, `body` | the theme background |
+| `#page-content` (stable id; classes `content spr-content-root`) | Softr's `.spr-content-root { background-color: … }` rule |
+| every Vibe block host, `div[data-role="vibe-block-root"]` — it has no class: most likely the "class-less wrapper div" the June 2026 notes found (inferred; that app was not re-measured) | the block's compiled `@layer base { :host { background-color: var(--background) } }`, where `--background` maps to the theme background through a hashed variable. Not `!important`, so a main-document rule on the host wins |
+| a native block's outer `<section>` | an inline hashed variable holding the theme background |
+
+`main#main-content` itself is transparent. Style any one layer and the ones above cover it — this is why setting `body` alone appears to "do nothing", and why a block that sets no background still shows the theme white over a coloured `body`.
+
+> **App with Softr's sidebar navigation? Use [App frame](#app-frame-navigation-layout), not this recipe.** The clear below hits every `div` inside `#page-content`. `.softr-sidebar` is one of them and paints the theme colour, so it would lose its fill too (inferred from the DOM and specificity, not injected). And native blocks' outer `<section>`s are not divs, so they keep painting the theme white.
 
-**Pattern: paint the backdrop on the bottom layer (`html`), then clear the duplicate fills off everything stacked above it.**
+**Pattern (top-bar apps): paint the backdrop on the bottom layer (`html`), then clear the duplicate fills off everything stacked above it.**
 
 ```css
 /* 1. Paint the backdrop on the bottom layer. A layered "combo" reads premium:
@@ -212,8 +242,8 @@ html {
 }
 
 /* 2. Clear the duplicate fills stacked above <html> so the backdrop shows through —
-      but EXCLUDE the header subtree (see gotcha). The inner content wrapper is
-      class-less and nested deep, so clear ALL divs inside #page-content. */
+      but EXCLUDE the header subtree (see gotcha). The block hosts are class-less
+      divs nested inside #page-content, so clear ALL divs inside it. */
 body,
 #page-content { background-color: transparent !important; background-image: none !important; }
 #page-content div:not(.softr-topbar):not(.softr-topbar *) {
@@ -222,7 +252,122 @@ body,
 }
 ```
 
-**Gotcha — don't clear the header into oblivion.** The header (`#topbar-root` → `.softr-topbar`, *including its dropdown panel*) renders **inside** `#page-content`, so a blanket `#page-content div { background: transparent }` flattens the dropdown's white panel too. And `#page-content`'s **id specificity (1,0,1) out-specifies** class/attr rules like `.softr-topbar [role="menu"]` (0,2,0) — so the clear wins silently and your earlier menu styling vanishes. Always exclude the header subtree: `:not(.softr-topbar):not(.softr-topbar *)`. (Cards are shadow-DOM blocks → their backgrounds are untouched; the footer is a `<footer>`, not a div → safe.)
+**Gotcha — don't clear the header into oblivion.** The header (`#topbar-root` → `.softr-topbar`, *including its dropdown panel*) renders **inside** `#page-content`, so a blanket `#page-content div { background: transparent }` flattens the dropdown's white panel too. And `#page-content`'s **id specificity (1,0,1) out-specifies** class/attr rules like `.softr-topbar [role="menu"]` (0,2,0) — so the clear wins silently and your earlier menu styling vanishes. Always exclude the header subtree: `:not(.softr-topbar):not(.softr-topbar *)`.
+
+**What the div clear reaches.** Each Vibe block's **host** div — that is what removes the block's theme white — but nothing inside its shadow root, so a block's own cards and panels keep the fills the block sets. It never reaches native blocks' outer `<section>`s, which keep painting the theme background; the outer-section rule in [App frame](#app-frame-navigation-layout) is the fix (untested outside a sidebar app). The footer is a `<footer>`, not a div → safe.
+
+## App frame (navigation layout)
+
+**When:** the app uses Softr's **sidebar navigation** (top bar + sidebar from a 768px window, a tab bar below it) and should read as **one application**, not as blocks stacked on a white page. The bars' theme colour wraps the content as a frame, and the content becomes one paper **sheet** whose top-left corner curves in under the top bar and the sidebar.
+
+**The method: the header CSS paints the frame and the sheet; blocks paint nothing.** Leave the top bar and sidebar exactly as the theme draws them. Nothing needs hiding: the top bar has no border or shadow, and the sidebar's inner border is transparent (verified live 2026-10-05). The CSS extends the bars' colour to `html`, `body` and `#page-content`, turns `#main-content` into the sheet, and makes block hosts transparent. Each block on such a page is full-bleed, sets no background of its own and lays out by its own width — the block side is in [SKILL.md](../SKILL.md#app-pages-beside-softr-navigation). The header CSS cannot reach inside a block, so a block's own cards and borders are still set in the block.
+
+### DOM and variables (verified live 2026-10-05)
+
+The shell selectors are in the [navigation-layout table](#selector-discipline--the-1-rule) above. Below `#main-content`:
+
+- A Vibe block: `#main-content > div[data-block="vibe-coding-…"] > div[data-block-id] > div[data-role="vibe-block-root"]`. The last div is the **host**, with an open shadow root.
+- A native block: `#main-content > div#<block id> > div > section` for the Account settings block; the 404 block is one level shallower (see the caveats).
+
+Variables Softr sets on `:root`:
+
+| Variable | Top bar + sidebar (window ≥ 768px) | Phone (window < 768px) |
+|---|---|---|
+| `--sticky-nav-height` | `56px` | empty |
+| `--softr-sidebar-width` | `280px`; `57px` collapsed (drag handle range 200–360) | empty |
+| `--softr-bottombar-height` | empty (blocks read 0px) | `calc(0px + 55px)` — the raw token, not a computed length |
+
+Each Vibe host maps them for the block: `--nav-height: var(--sticky-nav-height, 0px)`, `--sidebar-width: var(--softr-sidebar-width, 0px)`, `--bottombar-height: var(--softr-bottombar-height, 0px)` (the block-side table: [quick-reference.md → Softr navigation variables](quick-reference.md#softr-navigation-variables)). Blocks use those inside CSS `calc()` ([common-patterns.md](common-patterns.md#clear-softrs-sticky-bars)). The variable says 55px for the tab bar; the rendered bar measured 57px tall.
+
+**The layout switches on the window width, exactly at 768px:** 767px gives the phone tab bar, 768px gives the top bar and sidebar.
+
+### The recipe
+
+Paste into Settings → Custom Code → Code inside header (every page). That setting takes HTML, so the rules go inside a `<style>` element, as below. Rule order matters: keep it as written.
+
+```html
+<style>
+/* App frame. Pages with Softr's navigation: the bars' colour becomes a frame around one content sheet.
+   Pages without it (Log in, Sign up, 404) match none of these rules and keep Softr's own colours. */
+:root {
+  --app-frame: #A85935;   /* a COPY of the Studio theme colour of the top bar + sidebar (hashed vars can't be
+                             referenced). Change it by hand whenever the theme colour changes in Studio. */
+  --app-sheet: #FBF8F3;   /* the app's paper colour (e.g. the DESIGN.md surface) */
+  --app-radius: 24px;     /* the corner where the sheet meets the frame */
+}
+
+/* 1. Any page with Softr navigation (sidebar OR phone tab bar): one paper surface. */
+html:has(.softr-sidebar, .softr-bottombar),
+html:has(.softr-sidebar, .softr-bottombar) body,
+#page-content:has(.softr-sidebar, .softr-bottombar) {
+  background-color: var(--app-sheet) !important;
+}
+
+/* ...and blocks stop painting the theme background on top of it:
+   - Vibe block hosts: their compiled :host { background-color: var(--background) } is not !important.
+     This scoped form is UNTESTED as written. The line verified live was the unscoped
+     #main-content [data-role="vibe-block-root"], which also applies on pages without navigation.
+   - Native blocks: the OUTER <section> only, so their nested cards, list items and form groups keep their
+     fills. Nesting depth differs per native block; check yours (see the caveats). */
+#page-content:has(.softr-sidebar, .softr-bottombar) [data-role="vibe-block-root"],
+#page-content:has(.softr-sidebar, .softr-bottombar) #main-content > div > div > section {
+  background-color: transparent !important;
+}
+
+/* 2. With the sidebar (window ≥ 768px): the frame colour behind everything.
+   Same specificity as rule 1, so it MUST come after it; phones (tab bar only) keep the paper. */
+html:has(.softr-sidebar),
+html:has(.softr-sidebar) body,
+#page-content:has(.softr-sidebar) {
+  background-color: var(--app-frame) !important;
+}
+
+/* The content column becomes the sheet. Softr's own min-height: 100dvh fills short pages. */
+#page-content:has(.softr-sidebar) > #main-content {
+  background-color: var(--app-sheet) !important;
+  border-top-left-radius: var(--app-radius);
+}
+
+/* 3. The pinned inverse corner. #main-content's own radius scrolls away with the page; this one rides
+   the sticky #sidebar-root (its containing block), so it stays under the top bar while the content
+   scrolls and follows the sidebar's width. Guarded by :has(.softr-sidebar) because #sidebar-root
+   also exists on phones, empty and 0px wide. */
+#sidebar-root:has(.softr-sidebar)::after {
+  content: "";
+  position: absolute;
+  top: 0;
+  left: 100%;
+  width: var(--app-radius);
+  height: var(--app-radius);
+  background: radial-gradient(circle at 100% 100%,
+    transparent calc(var(--app-radius) - 0.5px),   /* the -0.5px stop: anti-aliased edge, no seam */
+    var(--app-frame) var(--app-radius));
+  pointer-events: none;                             /* never blocks clicks on the sheet */
+}
+</style>
+```
+
+### Caveats
+
+- **Decide where the menu lives first.** If the Studio menu items sit in the top bar, `.softr-sidebar` renders as an empty coloured column, and the frame reads as a blank strip (seen live 2026-10-05). For the full "app" look, put the menu in the sidebar in Studio; that variant was not built or seen, so check it.
+- **The frame colour is a hand copy.** The bars paint the Studio theme colour (e.g. `#A85935`) through hashed variables, so `--app-frame` cannot reference it. Read it off the page, `getComputedStyle(document.querySelector('.softr-sidebar')).backgroundColor`, rather than taking the DESIGN.md primary: the two can differ, and in the verified app they did. If the theme colour changes in Studio and `--app-frame` does not, the frame and the bars split.
+- **Rule order.** Rule 2 has the same specificity as rule 1. Put it first and sidebar pages lose the frame.
+- **The Vibe-host rule's scope.** The live code used the unscoped `#main-content [data-role="vibe-block-root"]`, which applies on every page. That is harmless where the page behind the block is the same theme background (inferred; no page without navigation but with a Vibe block was tested). The recipe scopes it like every other rule; that exact form is untested.
+- **Native blocks' outer section.** The child path `#main-content > div > div > section` matches the DOM measured on the Account settings block, but it was never re-injected in that form: the descendant form `#main-content section` was injected there and turned the section transparent. Nesting depth differs per native block: the 404 block's section sits one level shallower (`#main-content > div > section`), which does not matter there (no navigation). For each native block type on a navigation page, check the depth first; fall back to the descendant form only after checking the block holds no nested `<section>`s. **Side effect:** on navigation pages this overrides a background colour set on purpose in a native block's Style settings. A no-CSS alternative, setting the Studio theme background to the sheet colour, is untested.
+- **Phones (window < 768px).** Softr renders no top bar and no sidebar, only the tab bar: white, with the active item in the theme colour. Only rule 1 matches, so the page is paper throughout with no frame and no corner (the guarded `::after` computes `content: none`); `#main-content` stays transparent and the paper is on `html`, `body` and `#page-content`. Without the guard the `::after` still renders on phones, where `#sidebar-root` is static, so it is placed against the page: likely off the right edge, adding sideways scroll (seen in a mock, not on Softr). Restyling the tab bar to match the frame is untested.
+- **Tablets.** The bars appear from a 768px window. With the sidebar open, the content column there is only 488px wide (711px collapsed), so a block's window breakpoints fire for a column far narrower than the window. Blocks must size by their own width: [SKILL.md](../SKILL.md#app-pages-beside-softr-navigation), [common-patterns.md](common-patterns.md#measure-the-block-not-the-window).
+- **Collapsed and resized sidebar.** The top-bar toggle collapses the sidebar to 57px (`data-open="false"`, `--softr-sidebar-width: 57px`), and the corner follows it (measured at left 280px open, 57px collapsed). Drag-resizing (200–360px) was not tested; that the corner follows is inferred from `left: 100%`. In one headless run the collapsed state carried over to later checks (seen once; it may persist per browser).
+- **Stacking.** `#topbar-root` and `#bottombar-root` sit at z-index 800 and `#sidebar-root` at 1; block content scrolls under the top bar. A block's own sticky pane or header must clear the bars: [common-patterns.md](common-patterns.md#clear-softrs-sticky-bars). A block's modal must sit above them: no stacking context lies between a block and the page, so a fixed layer in a block at z-index 50 (shadcn's `Dialog` overlay) stays under the top bar, and one at 801 or more covers the top bar and sidebar (measured live 2026-10-06); use the in-block modal in [common-patterns.md → A modal above Softr's bars](common-patterns.md#a-modal-above-softrs-bars). Softr already sets `#main-content [data-block] { scroll-margin-top: var(--sticky-nav-height, 0px) }`, so a fragment jump to a block's outer wrapper (`div[data-block]`, with a page-assigned id such as `ai1`; the host sits two levels inside it) clears the top bar (the rule is read from Softr's CSS; a jump was not tested). Softr's floating "Made with Softr" badge (`div.made-with-softr`, fixed, z-index 1, 296px from the left beside a 280px sidebar) floats over the bottom left of the content on desktop and phones (seen in the preview). It is controlled by the app's badge setting (`showMadeWithBadge` in the page source; `false` after a later publish of the same app), so turn it off there rather than with CSS.
+- **`:has()` support.** Every scoped rule needs `:has()`: Safari 15.4+, Chrome 105+, Firefox 121+ (a reviewer's judgement, not tested on each browser). A browser without it drops those rules and shows Softr's default colours (inferred).
+
+### How the frame was verified
+
+Verified 2026-10-05 on a demo app with Softr's navigation layout. First by injecting the project's `<style>` (the recipe above, except that its Vibe-host rule was the unscoped form) into the preview and measuring computed backgrounds, the sheet's radius and the `::after` position at 1440, 1280, 1024, 900, 768, 767 and 390px windows, with the sidebar open and collapsed; the corner was cropped at rest and scrolled, with no seam. Then live, after the code was pasted into Code inside header and published:
+
+- **Preview, fresh load, nothing injected.** At 1024px with the sidebar open: frame on `html`, `body` and `#page-content`; `#main-content` the sheet with a 24px corner; Vibe hosts transparent; the corner `::after` at left 280px. At 375px (after a mobile emulation and a reload): tab bar only, paper throughout, no corner. No sideways scroll at either width.
+- **Published, logged out.** `/login` and a 404 page loaded the code and kept `html`, `body` and `#page-content` white, with no top bar, sidebar or tab bar. This is the real test of the `:has()` scoping.
+
+How to run these checks: [browser-checks.md](browser-checks.md#testing-custom-code-header-css).
 
 ## Finding the element to target
 
@@ -247,12 +392,16 @@ body,
 })();
 ```
 
+In an app with Softr's sidebar, lower the `1200`: the content column is the window minus the sidebar (1160px at a 1440px window), so block hosts and native sections drop out of the list otherwise.
+
 ## Restyle vs. replace vs. block-owned header
 
 **Restyle the native bar (recommended):** robust, global, keeps Softr's auth-aware nav (account menu, user-group-gated items) and stays editable in Studio.
 
+**Paint around the bars (apps with sidebar navigation):** leave the top bar and sidebar exactly as the Studio theme draws them, and extend their colour around a content sheet: `html`, `body` and `#page-content` take the bars' colour, `#main-content` becomes one paper sheet with a rounded corner tucked under both bars, and blocks paint nothing behind themselves. Choose it when the app uses Softr's top bar + sidebar and should read as one application rather than blocks on a white page. It keeps everything restyling keeps (auth-aware nav, Studio editing) and touches no nav markup. It can sit beside a restyle only if `--app-frame` matches the colour the restyled bars then paint (untested combination). Recipe, scoping and caveats: [App frame](#app-frame-navigation-layout).
+
 **Replace it** (hide `#topbar-root`, inject a fully custom HTML/JS header globally): only if you need structure the native nav can't do — e.g. multi-column mega-menus with icon cards. It's **fragile**: you lose Softr's logged-in account menu + user-group gating, you must re-init the JS on every SPA route change (Softr swaps pages without a full reload), and the custom header won't render in the Studio editor. Steer users to restyle unless the structure genuinely requires replacement.
 
 **Block-owned header (landing pages only):** on a marketing/landing page where the native header is **hidden in Studio**, a full-bleed hero block can render its own `<header>` with `position: fixed` — fixed elements inside a block's shadow root still anchor to the viewport, and window scroll listeners work from block code. Proven by Softr Studio AI's own hero output (2026-08-31), and the official user guide lists "a page header" as a supported static layout. How the replace-option caveats transfer: **per-page only** and **no auth-aware nav / user-group gating** carry over (same losses as replacing globally — it's for public landing pages, not logged-in app pages); **"won't render in the Studio editor" does NOT** (a Vibe-block header renders in Studio like any block); **"manual SPA re-init" does not apply** (React owns the block's lifecycle). Two caveats of its own: don't ship it on a page where the native `#topbar-root` is still visible (the z-index contest between the block's header and the native sticky bar is untested — hide one), and it exists only on pages containing the block. Full pattern, mobile-nav requirement, and caveat set: [static-blocks.md](static-blocks.md#block-owned-landing-page-header).
 
-Decision order: restyle when the native structure suffices → block-owned header for landing pages that hide native chrome → global replacement only when a logged-in app needs structure the native nav can't do.
+Decision order: restyle when the native structure suffices (or paint around the bars when a sidebar app should read as one application) → block-owned header for landing pages that hide native chrome → global replacement only when a logged-in app needs structure the native nav can't do.

package/references/quick-reference.md

@@ -255,6 +255,42 @@ useNavigationBlocker(function() { return dirtyRef.current; });
 
 Catches BOTH Softr's in-app SPA navigation (nav bar, sidebar, `<NavigationAction>`) AND browser unload (tab close, refresh, external links). A plain `window.addEventListener("beforeunload", ...)` does NOT catch Softr's in-app nav. See [common-patterns.md](common-patterns.md#navigation-blocker-for-unsaved-changes).
 
+## Softr navigation variables
+
+Softr sets these on the page's `:root` when the app uses its sidebar / top-bar navigation; the Vibe host's `:host` maps them for the block, each with a `0px` fallback (measured live 2026-10-05; phone = below a 768px window).
+
+| Page (`:root`, header CSS) | Block (Vibe host) | Desktop / tablet (≥ 768px window) | Phone (< 768px window) |
+|---|---|---|---|
+| `--sticky-nav-height` | `--nav-height` | `56px` (sticky top bar) | not set → host `0px` |
+| `--softr-sidebar-width` | `--sidebar-width` | `280px` open, `57px` collapsed (drag handle 200–360px) | not set → host `0px` |
+| `--softr-bottombar-height` | `--bottombar-height` | host `0px` | `calc(0px + 55px)` (sticky tab bar; the rendered bar measured 57px) |
+
+```tsx
+style={{ top: "calc(var(--nav-height, 0px) + 16px)", maxHeight: "calc(100dvh - var(--nav-height, 0px) - 32px)" }}
+```
+
+- **Use them only inside CSS `calc()`.** In JS, `getComputedStyle(...).getPropertyValue("--bottombar-height")` hands back the token string (`calc(0px + 55px)` on phones), so `parseFloat` gives `NaN` (the string is measured; the `NaN` is reasoned, not run).
+- The same `:host` rule maps `--background`, `--font-family-sans` / `--font-family-serif` and `--container-max-width` onto Softr's hashed theme variables (`--_5f91d6c_…`), which is why an unpainted block still paints the Studio theme background (verified 2026-10-05). Never reference the hashed names: the prefix is per Softr block package and has changed before.
+- How blocks use them: [SKILL.md → App pages beside Softr navigation](../SKILL.md#app-pages-beside-softr-navigation) and [common-patterns.md → Clear Softr's sticky bars](common-patterns.md#clear-softrs-sticky-bars). The page side (header CSS, the `:root` values): [native-chrome-styling.md → App frame (navigation layout)](native-chrome-styling.md#app-frame-navigation-layout).
+
+## Container queries
+
+Lay a block out by its OWN width when it sits beside Softr's sidebar (57–360px of the window). Softr's Tailwind compiles container variants (verified live 2026-10-05):
+
+```tsx
+<div className="@container">                                    {/* the container: a wrapper */}
+  <div className="px-4 @min-[40rem]:px-6 @min-[64rem]:px-10">   {/* resolves against the wrapper's width */}
+    <div className="grid grid-cols-2 @min-[52rem]:grid-cols-4">…</div>
+    <section className="@container …">                          {/* a pane: its children follow the pane */}
+      <div className="text-[20px] @min-[24rem]:text-[24px]">…</div>
+    </section>
+  </div>
+</div>
+```
+
+- A container query never resolves against the element that carries `@container`, only against the nearest ancestor container — so put `@container` on a wrapper.
+- Beside a sidebar, no `sm:` / `md:` / `lg:` for layout: they fire on the window. Full rules and worked thresholds: [SKILL.md → App pages beside Softr navigation](../SKILL.md#app-pages-beside-softr-navigation). When CSS can't decide, [measure the block](common-patterns.md#measure-the-block-not-the-window).
+
 ## Component Skeleton
 
 ```jsx
@@ -277,3 +313,5 @@ export default function Block() {
   );
 }
 ```
+
+App pages beside Softr's sidebar navigation, inside a frame the header code paints, drop these wrappers for the full-bleed `@container` shell: [SKILL.md → App pages beside Softr navigation](../SKILL.md#app-pages-beside-softr-navigation).

package/references/searchable-dropdown.md

@@ -151,6 +151,32 @@ the hidden part); a picker at the bottom of a dialog body opens up, inside the d
 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.
 
+**On app pages with Softr navigation, the strip doesn't reach the window's edges either.**
+Softr's bars sit over the page, outside the block: from a 768px window, a 56px sticky top bar;
+below it, a sticky tab bar at the bottom, 57px as rendered (Softr's variable says 55px; both bars
+z-index 800, measured live 2026-10-05). The walk above starts the strip at `0` and
+`window.innerHeight`, so a trigger just under the top bar
+can open its menu up and under the bar, and on a phone a menu can open down behind the tab bar.
+That clash is inferred from the measurements, not seen. Start the strip inside the bars (an
+untested variant):
+
+```jsx
+var SOFTR_TOP_BAR = 56; // Softr's sticky top bar, window 768px and up
+var SOFTR_TAB_BAR = 57; // Softr's phone tab bar, window below 768px: measured 57px; its variable says 55px
+
+function comboClipBox(node) {
+  var phone = window.innerWidth < 768; // Softr's own switch: 767px = tab bar, 768px = top bar
+  var top = phone ? 0 : SOFTR_TOP_BAR;
+  var bottom = window.innerHeight - (phone ? SOFTR_TAB_BAR : 0);
+  // … the ancestor walk, unchanged
+}
+```
+
+On a page without Softr navigation (log in, a landing page) the top offset only makes the
+panel open upward a little less readily. The same bar heights apply to any other room check
+or window scroll in a block:
+[common-patterns.md → Clear Softr's sticky bars](common-patterns.md#clear-softrs-sticky-bars).
+
 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.
 
@@ -345,7 +371,8 @@ Everything else — the trigger, the card, the rows — stays flat.
 - [ ] 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
+- [ ] Drop-up and list `maxHeight` measured against the clipping ancestors, not the window, and
+      on app pages inside Softr's top bar and phone tab bar
 - [ ] 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"`,

package/references/softr-mcp.md

@@ -50,8 +50,8 @@ map below was checked against the tool lists the server delivered on 2026-09-30
 **The Workflows tools have since followed** (when exactly is not known; first seen 2026-10-05). The 2026-10-05 roster delivered all 28 as `workflow_*`:
 `workflow_create`, `workflow_get`, `workflow_list`, `workflow_publish`, `workflow_update_node_inputs`,
 `workflow_get_node_specifications`, `workflow_list_node_types`, `workflow_test_node` and the rest,
-i.e. area first, then the old verb and object. [Workflows](#workflows) below still lists the
-pre-rename names. Translate them that way. That roster had no `get_workspace_integrations`;
+i.e. area first, then the old verb and object. [Workflows](#workflows) below uses the new names
+(re-checked against the live roster 2026-10-06: all 28 present). That roster had no `get_workspace_integrations`;
 `integration_list` covers it.
 
 Most new names are the old words reordered. These are the ones you would not guess:
@@ -195,7 +195,7 @@ For block-building work you need **Applications & Forms: Full access** (to creat
 
 ## Vibe coding block tools
 
-Before writing any block code through the MCP, call `vibe_coding_block_get_docs` — it returns the current version of the [Vibe Coding Developer Guide](https://docs.softr.io/vibe-coding-developer-guide), which is the authority on hook signatures if it and this skill ever disagree.
+Before writing any block code through the MCP, call `vibe_coding_block_get_docs` — it returns the current version of the [Vibe Coding Developer Guide](https://docs.softr.io/vibe-coding-developer-guide), which is the authority on hook signatures if it and this skill ever disagree. On runtime *behaviour* the guide's prose can lag a live capture, and where it does this skill says so: the guide still describes `useRecords({ enabled })` as a way to defer loading (checked 2026-10-06), while a 2026-09-18 network capture showed `useRecords` fetching anyway ([reading.md](../datasources/reading.md#userecords-ignores-enabled-false)). Trust the capture until a newer one says otherwise.
 
 | Group | Tools |
 |---|---|
@@ -250,9 +250,13 @@ context. Keep the local mirror in step mechanically rather than by hand:
    sent, which is what makes it usable here: on this path you never see the merged file yourself.
 
 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
+Softr's side (`"\u2014"` 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 comparison
 fails on every non-ASCII character.
+The same decoding happens to an agent's own tool-call arguments: a `\u2014` typed into a
+file-writing tool lands on disk as `—` (it put a wrong example into this very paragraph
+twice, 2026-09-18 and 2026-10-06). When a file must hold a literal backslash-u sequence, build the
+backslash at runtime (`chr(92)` in Python) and check the bytes afterwards.
 
 **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
@@ -421,13 +425,17 @@ preserves explicitly set permissions across a recompile, so every recompile need
    the call errors rather than lying, but an agent that batches calls can easily miss which one failed.
 5. If any action is still broader than intended (typically ADD_RECORD at `ALL_USERS`), **report it
    and let the builder decide.** Check the page's own VIEW permission first with
-   `application_page_get_permissions`, because that is what sets the severity:
+   `application_page_get_permissions`, because that is what sets the severity, and report the
+   block's own Visibility with it (`vibe_coding_block_get_settings`): it gates the block's reads
+   and sets ADD_RECORD's default (2026-10-05), but whether it refuses writes on its own is untested
+   ([below](#what-the-server-enforces-on-a-blocks-data-endpoints)):
    - **Page VIEW is gated** (e.g. `LOGGED_IN_USERS`) — an anonymous visitor cannot load the page at
      all, so exploiting the open action means calling its endpoint directly, and the realistic worst
      case is junk records rather than data exposure or deletion. Housekeeping: worth fixing on the
      next Studio pass, not worth holding a release for.
-   - **Page VIEW is `ALL_USERS`** — the action permission is the only gate left. That is a genuine
-     hole and deserves to be called one.
+   - **Page VIEW is `ALL_USERS`** — the action permission is the only gate known to hold on writes
+     (the block's Visibility may also refuse them; untested). That is a genuine hole and deserves
+     to be called one.
 
    Report page, block, action type, data source and current group; say which of the two cases applies;
    note that a human sets them on the block's Actions tab in Studio. Then stop — **do not unilaterally
@@ -438,8 +446,10 @@ preserves explicitly set permissions across a recompile, so every recompile need
    **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
+   refuses outsiders too: on 2026-10-05 a replayed PATCH from outside the block's group got 403
+   ([hubspot.md](../datasources/hubspot.md#writing)). The block and its actions were both limited to
+   that group, so which rule refused it is not known, and whether page VIEW alone gates writes is
+   untested. 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.
@@ -462,14 +472,14 @@ Both edit paths recompile, so both reset Action permissions either way (Hard Con
 *Verified live 2026-09-18 (Softr Database; draft preview, "Preview as" different users, requests
 captured from the app iframe); the block-visibility row verified 2026-10-05 (HubSpot; preview link,
 impersonated users, direct POSTs).* 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:
+`/blocks/<blockId>/datasources/<connection>/records` for lists, `/records/<id>` for one record —
+and these are the gates that actually exist on them (`<connection>` was recorded as the connection's id in the 2026-09-18 Softr Database capture and seen as its alias in a 2026-10-05 HubSpot capture; unresolved, and it only matters when reading a network log):
 
 | 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 block's Visibility** (`predefinedUserGroup` + `customUserGroupIds`; `vibe_coding_block_set_visibility`) | **Yes.** A viewer outside the block's group gets the same **403**, on list and by-id, even where the page lets them in. The body reads like a write error on a read: "You cannot add or edit a record because either the block/action visibility rules, user group conditions, or the user/record data in the datasource has changed." Per block: the same table on an ungated block stays open. Five code pushes left the setting intact |
-| **The connection's Source conditions** (Source tab / `vibe_coding_block_set_data_source_record_filters`) | **Yes — and they are the only server-side ROW gate** |
+| **The connection's Source conditions** (Source tab / `vibe_coding_block_set_data_source_record_filters`) | **Yes — and they are the only server-side ROW gate.** A by-id request for a record the condition excludes answers differently per backend: **HTTP 200 with an empty body** on Softr Database (2026-09-18), **404** on HubSpot (2026-10-05). Treat both as "not found" |
 | 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)) |
 
@@ -506,7 +516,8 @@ verified on HubSpot on 2026-10-05, the same way.* There are two forms, and **the
   field in this form (Leo set it in the Source tab, and it read back that way), and the same form
   works when written with `vibe_coding_block_set_data_source_record_filters`.
   **It fails closed:** a user whose field is empty, or who has no record in the users' data source,
-  gets 0 rows, and a by-id request for a record outside the condition returns 404.
+  gets 0 rows, and a by-id request for a record outside the condition returns 404 (on HubSpot;
+  Softr Database answers HTTP 200 with an empty body).
 - **Use AND between rules.** With one rule OR and AND behave the same, but a second rule added
   under OR widens access (2026-10-05).
 - **The braced user-field spellings fail.** On 2026-09-18, on Softr Database, eleven spellings were
@@ -726,13 +737,13 @@ Softr Workflows are automations built from trigger + action nodes, and the MCP c
 
 | Group | Tools |
 |---|---|
-| Workflow lifecycle | `create_workflow`, `get_workflow`, `get_workflow_url`, `list_workflows`, `rename_workflow`, `update_workflow_configuration`, `publish_workflow`, `unpublish_workflow`, `test_workflow` |
-| Node management | `add_node`, `add_branch_node`, `create_branch`, `delete_node`, `duplicate_node`, `rename_node`, `reorder_node`, `reorder_multiple_nodes`, `replace_node`, `replace_trigger_node`, `update_node_inputs`, `update_node_note`, `update_node_continue_on_error`, `update_node_retry` |
-| Discovery / testing | `list_node_types`, `get_node_specifications`, `get_dynamic_input_options`, `test_node`, `get_node_output` |
+| Workflow lifecycle | `workflow_create`, `workflow_get`, `workflow_get_url`, `workflow_list`, `workflow_rename`, `workflow_update_configuration`, `workflow_publish`, `workflow_unpublish`, `workflow_test` |
+| Node management | `workflow_add_node`, `workflow_add_branch_node`, `workflow_create_branch`, `workflow_delete_node`, `workflow_duplicate_node`, `workflow_rename_node`, `workflow_reorder_node`, `workflow_reorder_multiple_nodes`, `workflow_replace_node`, `workflow_replace_trigger_node`, `workflow_update_node_inputs`, `workflow_update_node_note`, `workflow_update_node_continue_on_error`, `workflow_update_node_retry` |
+| Discovery / testing | `workflow_list_node_types`, `workflow_get_node_specifications`, `workflow_get_dynamic_input_options`, `workflow_test_node`, `workflow_get_node_output` |
 
-These are the names as of 2026-10-01. By 2026-10-05 the server delivered them as `workflow_*`
-(`create_workflow` → `workflow_create`, `update_node_inputs` → `workflow_update_node_inputs`); see
-[the rename note](#tool-names--the-2026-10-01-rename).
+These are the current names (live roster, 2026-10-06). Until 2026-10-01 they had no `workflow_`
+prefix (`create_workflow` → `workflow_create`), and older notes, including project docs, still use
+those; see [the rename note](#tool-names--the-2026-10-01-rename).
 
 **The node catalog is huge** — live-enumerated 2026-08-31: **418 node types (58 triggers + 360 actions) across 56 applications.** The parts that matter most for this skill:
 
@@ -756,13 +767,13 @@ These are the names as of 2026-10-01. By 2026-10-05 the server delivered them as
 
 **Build-loop findings (verified live 2026-09-01, first end-to-end production build — 10 workflows):**
 
-- **`create_workflow` instantiates an OLD version of the trigger node.** Immediately call `replace_trigger_node` with the **same trigger type** — the replacement lands at the current version with the current inputs. Example: `updateField` on `SOFTR_TABLES_RECORD_UPDATED` (fire only when a specific field changed) only exists at v1.2.0; the version `create_workflow` instantiates doesn't have it.
-- **FILTER node conditions are set via `update_node_inputs` with inputName `"condition"`** — the value is an `{operator, conditions: [...]}` object. The condition is stored on the FILTER node's **outgoing path**, the same way the Studio builder wires it.
-  - **The official MCP docs disagree:** "Branch and filter conditions can't be set through MCP yet ... deciding what sends a run down each path is something you finish in the builder" (docs.softr.io/mcp/workflows, checked 2026-10-05).
-  - **What stands on each side:** our 2026-09-01 build did set them this way. The FILTER spec today declares `inputs: {}`, but live FILTER nodes still keep their condition on the outgoing path, so the empty spec does not refute the mechanism.
-  - **Until it's re-checked:** after setting a condition over MCP, read the workflow back (`workflow_get`) and confirm the path condition is there. If it isn't, finish the condition in the builder.
+- **`workflow_create` instantiates an OLD version of the trigger node.** Immediately call `workflow_replace_trigger_node` with the **same trigger type** — the replacement lands at the current version with the current inputs. Example: `updateField` on `SOFTR_TABLES_RECORD_UPDATED` (fire only when a specific field changed) only exists at v1.2.0; the version `workflow_create` instantiates doesn't have it.
+- **A FILTER condition written over MCP is inert — set it in Studio** (corrected 2026-10-06; this bullet used to say the MCP writes it). `workflow_update_node_inputs` with inputName `"condition"` accepts an `{operator, conditions: [...]}` object and stores it in the node's `inputs.condition`, a field the engine does not read. The engine evaluates the condition on the FILTER node's **outgoing path** (the `paths` entry whose `fromActionId` is the filter), and only the Studio builder writes that. **A filter built over MCP passes every run.** A 2026-09-19 audit of this very build showed it three ways: the one workflow actually running had empty `inputs` and its whole condition on the path; two others, edited in Studio afterwards, held one condition in `inputs.condition` and a different one on the path, so Studio reads and writes only the path.
+  - **The official MCP docs agree:** "Branch and filter conditions can't be set through MCP yet ... deciding what sends a run down each path is something you finish in the builder" (docs.softr.io/mcp/workflows, checked 2026-10-05), and the FILTER spec declares `inputs: {}`. BRANCH conditions were not tested separately here; treat them the same way.
+  - **How to build one:** add the FILTER over MCP if that is convenient, then open it in Studio, set its clauses and save. Never trust `inputs.condition` as a record of what the filter does; it can disagree with the path.
+  - **How to check one:** read the workflow back with `workflow_get` and find the `paths` entry whose `fromActionId` is the filter; the condition must be there. FILTER nodes cannot be run with `workflow_test_node`, so this read-back is the only check before a real run.
 - **`LOOP_ACTION_GROUP`'s `loopVariables.items` must reference a plain array**, e.g. `$.records` — a `[*]` projection (e.g. `$.records[*].fields.X`) is rejected by the validator. Per-item references **inside** the loop use `{loopActionGroup.<id>:::loopVariables.items.fields.<fieldId>}` (use the bracket form for ids that start with a digit).
-- **`update_node_inputs` batches validate against the STORED node state**, not the batch-in-progress — an update that depends on another update in the same batch fails validation. Split dependent updates into sequential calls.
+- **`workflow_update_node_inputs` batches validate against the STORED node state**, not the batch-in-progress — an update that depends on another update in the same batch fails validation. Split dependent updates into sequential calls.
 - **Test-safety rules** (which `testRunMode` means what in practice):
   - Record-**write** nodes (`SOFTR_TABLES_UPDATE_RECORD` etc.) are `REAL_ONLY` — **never test them against a production workspace**; the test performs the real write.
   - `SOFTR_SEND_EMAIL` is `MOCK_AND_REAL` — **always pass `mode: "mock"`**.

package/references/static-blocks.md

@@ -37,9 +37,11 @@ SKILL.md's Premium Visual Baseline (gradient wrapper, icon-in-rounded-square hea
 
 **`container`/`content` wrappers are optional platform behavior, not platform-enforced.** Per the official developer guide: "By default, block occupies full width of the page but special classes - `container` and `content` are **available** to constrain the width [of content to match app's max width settings]" (emphasis added). The wrappers remain the strong default for app/content blocks that sit next to native blocks (width consistency — that's their whole purpose). Static marketing blocks legitimately skip them so backgrounds, images, and decorative shapes run edge-to-edge.
 
+App pages are the other full-bleed case. Beside Softr's sidebar / top-bar navigation, inside a frame the app's header code paints, an app block drops the wrappers too — but it also paints no background and lays out by its own width with container queries. That case has its own rules: [SKILL.md → App pages beside Softr navigation](../SKILL.md#app-pages-beside-softr-navigation).
+
 When you go full-bleed:
 
-- **Own your horizontal gutters** — the responsive padding ramp `px-6 md:px-12 lg:px-16` on the content container is the Studio-verified shape.
+- **Own your horizontal gutters** — the responsive padding ramp `px-6 md:px-12 lg:px-16` on the content container is the Studio-verified shape. It steps on the WINDOW width, which suits a full-width marketing page and not a block beside Softr's sidebar: there the block is 57–360px narrower than the window (744px wide at a 1024px window with the sidebar open, measured 2026-10-05), so use the container-query shell from the app-page section instead.
 - **Own your inner max-widths** — constrain the copy column yourself (`lg:max-w-[46%]`, `max-w-[430px]` on body text).
 - **`overflow-hidden` on the block root** if decorative shapes offset off-canvas (prevents horizontal scroll).
 - **Record the choice** in the placement comment so future edits and reviews know it's deliberate:
@@ -77,7 +79,7 @@ The caveat set — state these in any block that ships its own header:
 
 1. **Per-page only.** The header exists solely on pages containing this block. Every page of a multi-page site needs either this block or the native header, or navigation disappears.
 2. **No auth-aware nav logic.** You forfeit Softr's account menu and user-group-gated items — nav items are plain `<NavigationAction>`s. Fine for public landing pages; wrong for logged-in app pages. For the login CTA, use the auth-aware swap (`useCurrentUser()` → "Sign in" vs "Dashboard") from [common-patterns.md](common-patterns.md#auth-aware-header-cta).
-3. **Don't ship both headers on one page.** The z-index outcome against a visible native `#topbar-root` (sticky, main document) is untested — hide the native header on this page, or don't use the pattern.
+3. **Don't ship both headers on one page.** The z-index outcome against a visible native `#topbar-root` (sticky, z-index 800 in the main document — measured 2026-10-05) is untested — hide the native header on this page, or don't use the pattern.
 4. **Keep transforms/filters off the header's ancestors.** `position: fixed` anchors to the viewport ONLY while no ancestor establishes a containing block — a `transform`, `filter`, `perspective`, or `will-change` on the block root (e.g. an entrance animation) silently converts the "fixed" header to absolute and lets `overflow-hidden` clip it. Leaf-element transforms (`hover:-translate-y-[1px]` on buttons) are fine. Verify in the **published app**, not just the Studio canvas.
 5. **Mobile nav is mandatory.** `hidden md:flex` on the nav with no fallback means nav items simply don't exist on phones (Studio AI ships exactly this bug). Pair the pattern with a shadcn `Sheet`-based mobile menu (hamburger → drawer listing the same `navItems` array) — the component is on the platform roster.
 6. **Landmark hygiene.** Shadow DOM does NOT hide landmarks from assistive tech, and Softr's native chrome uses semantic elements. On a page with native chrome visible, a block's own `<header>`/`<main>` creates duplicate banner/main landmarks — use plain `<div>`s there. Reserve `<header>`/`<main>` for pages where the native chrome is hidden and the block genuinely IS the page chrome.
@@ -89,8 +91,9 @@ The wider decision (restyle native vs replace globally vs block-owned) is laid o
 Heroes pair with same-page sections via hash links (nav "Capabilities" → `#capabilities` further down).
 
 - **Write anchor destinations RELATIVE**, per Hard Constraint 20: `/#capabilities` or `/page#section`. A Studio-generated hero shipped its CTA configured as the absolute self-domain form (`https://<app>.softr.app/#capabilities`, observed in the Settings pane 2026-08-31) — rewrite that form; hardcoded domains break on custom-domain publish and between staging/production.
-- **A URL fragment cannot target an element inside a Vibe block's shadow root** — fragment lookup stops at the shadow boundary (same family as the documented `getElementById` anti-pattern). Anchors must target something in the main document: the block/section host. Softr has a native anchor-link mechanism targeting blocks — **verify live which fragment a Vibe Coding block answers to** before promising exact syntax to a user.
-- **In-block scrolling** (scroll to a section inside the same block) uses refs + `scrollIntoView` with the `setTimeout(fn, 0)` rule (Hard Constraint 17), not fragments.
+- **A URL fragment cannot target an element inside a Vibe block's shadow root** — fragment lookup stops at the shadow boundary (same family as the documented `getElementById` anti-pattern). Anchors must target something in the main document: the block/section host. Softr has a native anchor-link mechanism targeting blocks — **verify live which fragment a Vibe Coding block answers to** before promising exact syntax to a user. (Seen 2026-10-05: a Vibe block's outer wrapper in the main document is `#main-content > div[data-block="vibe-coding-…"]` with a page-assigned id such as `ai1`; whether a fragment for that id jumps to it is untested.)
+- **The sticky top bar is already cleared for a jump to a block's outer wrapper.** Softr's page CSS gives that wrapper (`#main-content > div[data-block]`, the element with the page-assigned id, previous bullet) `#main-content [data-block] { scroll-margin-top: var(--sticky-nav-height, 0px) }`, so a fragment jump to it should stop below the 56px top bar (rule read from the page CSS 2026-10-05; the jump itself untested). The Vibe host two levels inside it carries no `data-block`, and nothing does that for content inside the block.
+- **In-block scrolling** (scroll to a section inside the same block) uses refs + `scrollIntoView` with the `setTimeout(fn, 0)` rule (Hard Constraint 17), not fragments. It must add the top-bar offset itself, or the target lands under the sticky bar — for example `scroll-margin-top: calc(var(--nav-height, 0px) + 16px)` on the target (standard CSS, untested in a block). See [common-patterns.md → Clear Softr's sticky bars](common-patterns.md#clear-softrs-sticky-bars).
 
 ## Harvesting Studio-AI marketing blocks