softr-vibe-coding 2.1.2 → 2.3.0

package/references/common-patterns.md

@@ -1,12 +1,19 @@
 # Common Patterns
 
-Small reusable patterns that come up across Vibe Coding blocks but don't warrant their own reference file. Each is a copy-pasteable snippet. The snippets below use legacy var-style (`var`, `function() {}`), which remains valid — write new blocks in modern TS (see SKILL.md Style Conventions).
+Small reusable patterns that come up across Vibe Coding blocks but don't warrant their own reference file. Each is a copy-pasteable snippet. The first three snippets use legacy var-style (`var`, `function() {}`), which remains valid; the newer patterns use modern TS — both compile (see SKILL.md Style Conventions).
+
+**Browser environment note.** Vibe blocks render in a shadow root in the MAIN document — not an iframe — so window-level APIs behave normally from block code: `window.scrollY` reflects the real page scroll, window-level events (scroll, resize, keydown) fire, `localStorage`/`navigator.clipboard`/`window.history` all work. Standard `useEffect` add/remove-listener with cleanup is the right shape for event-driven UI; use `{ passive: true }` for scroll/touch listeners. (SKILL.md Hard Constraint 17's `setTimeout` rule applies to ISSUING programmatic scrolls only, not to listening.)
 
 ## Table of Contents
 
 - [Cross-Page State with localStorage + URL Parameters](#cross-page-state-with-localstorage--url-parameters)
 - [Clipboard Copy Button](#clipboard-copy-button)
 - [Navigation Blocker for Unsaved Changes](#navigation-blocker-for-unsaved-changes)
+- [Scroll-Condensing Fixed Header (Landing-Page Hero)](#scroll-condensing-fixed-header-landing-page-hero)
+- [Auth-Aware Header CTA](#auth-aware-header-cta)
+- [Edge-Fade Image Mask (Editorial Hero)](#edge-fade-image-mask-editorial-hero)
+- [Decorative Background Blobs (Editorial Layering)](#decorative-background-blobs-editorial-layering)
+- [Dot-Separated Inline List](#dot-separated-inline-list)
 
 ## Cross-Page State with localStorage + URL Parameters
 
@@ -161,3 +168,127 @@ The hook automatically handles:
 - Blocks where you want to block on something other than form dirtiness (e.g., a pending background upload).
 
 **Asking Softr to add the blocker automatically:** when generating or refining a form block in the Vibe Coding editor, you can prompt with "Block the navigation when the form is dirty" and Softr will wire `useNavigationBlocker` for you — useful when you don't want to write the import + hook call yourself.
+
+## Scroll-Condensing Fixed Header (Landing-Page Hero)
+
+For block-owned landing headers (see [static-blocks.md](static-blocks.md#block-owned-landing-page-header) for when this pattern applies and its caveat set): the header starts tall and transparent, then condenses to a translucent, blurred bar once the page scrolls. Verified pattern from Studio-AI output, 2026-08-31 (renders live; scroll behavior consistent with window-scrolled Softr pages).
+
+```tsx
+import { useState, useEffect } from "react";
+
+export default function Block() {
+  const [scrolled, setScrolled] = useState(false);
+
+  useEffect(() => {
+    const onScroll = () => setScrolled(window.scrollY > 24);
+    onScroll(); // sync immediately — Softr is a SPA, so the block can mount with a restored scroll offset
+    window.addEventListener("scroll", onScroll, { passive: true });
+    return () => window.removeEventListener("scroll", onScroll);
+  }, []);
+
+  return (
+    <header
+      className={`fixed top-0 left-0 right-0 z-50 flex items-center justify-between px-6 md:px-12 transition-all duration-300 ${
+        scrolled
+          ? "py-3 bg-[#FAF5EC]/85 backdrop-blur-md border-b border-[#E7DECD]"
+          : "py-6 bg-transparent border-b border-transparent"
+      }`}
+    >
+      {/* logo / nav / CTA */}
+    </header>
+  );
+}
+```
+
+Notes:
+
+- **The initial `onScroll()` call matters** — without it, a block mounting mid-page (SPA back-navigation with restored scroll) renders the transparent state over content.
+- **No throttle/rAF needed** — the handler sets a boolean; React skips re-renders when the value doesn't change.
+- **`backdrop-blur-md` works across the shadow-DOM boundary**: `backdrop-filter` operates on the composited backdrop (everything painted beneath the element in the viewport), so a block's translucent fixed header blurs other blocks' content scrolling under it. Requirements: the element needs a semi-transparent background for the blur to be visible, and `backdrop-filter` must sit on the fixed element itself — on an ancestor it creates a containing block that would re-anchor the fixed header. (Compositing claim is standard CSS; the blurred-over-content visual on a published Softr page is inferred, not screenshot-proven.)
+- This translucent-blur bar is a deliberate, single-surface exception to the anti-glassmorphism taste rule in ui-ux-guidelines.md — don't extend the treatment to cards/panels.
+- **Fixed-position fragility**: `position: fixed` anchors to the viewport only while no ancestor has a `transform`/`filter`/`perspective`/`will-change`. Keep those off the block root and the header's ancestors, and verify in the published app, not just the Studio canvas.
+
+## Auth-Aware Header CTA
+
+A landing header's "Sign in" button should swap for a logged-in destination. `useCurrentUser()` returns `null` when logged out (documented in [../datasources/reading.md](../datasources/reading.md)); verify whether it has a transient loading state before adding flicker handling — the docs only document `null`.
+
+```tsx
+import { useCurrentUser } from "@/lib/user";
+import { NavigationAction } from "@/components/navigation-action";
+import { Button } from "@/components/ui/button";
+
+// signInLink, dashboardLink: two useNavigationSetting hooks so both destinations stay builder-editable
+const user = useCurrentUser();
+
+<Button asChild>
+  {user ? (
+    <NavigationAction navigation={dashboardLink}>Dashboard</NavigationAction>
+  ) : (
+    <NavigationAction navigation={signInLink}>Sign in</NavigationAction>
+  )}
+</Button>
+```
+
+Default label is "Sign in" (the ui-ux-guidelines.md glossary term), not "Log in". This is the default for any block-owned landing header with a login button — Studio AI omits the swap; add it.
+
+## Edge-Fade Image Mask (Editorial Hero)
+
+Fade a photo's edges into the block background (no hard rectangle) with multiple gradient masks — one linear-gradient per edge to fade — combined by intersection. Renders fine inside the block's shadow DOM (verified from Studio output, 2026-08-31).
+
+```tsx
+// Module scope. Left edge fades into the background; bottom edge fades so the photo doesn't butt the block edge.
+const photoMask = {
+  WebkitMaskImage:
+    "linear-gradient(to right, rgba(0,0,0,0) 0%, rgba(0,0,0,0.35) 6%, rgba(0,0,0,1) 18%), linear-gradient(to bottom, rgba(0,0,0,1) 84%, rgba(0,0,0,0) 100%)",
+  WebkitMaskComposite: "source-in",
+  maskImage:
+    "linear-gradient(to right, rgba(0,0,0,0) 0%, rgba(0,0,0,0.35) 6%, rgba(0,0,0,1) 18%), linear-gradient(to bottom, rgba(0,0,0,1) 84%, rgba(0,0,0,0) 100%)",
+  maskComposite: "intersect",
+};
+
+<div className="absolute top-0 right-0 h-[92%] w-[58%]" style={photoMask}>
+  <img src={image.src} alt={image.alt} className="w-full h-full object-cover object-[62%_25%]" />
+</div>
+```
+
+**The trap: the two composite properties take DIFFERENT keyword vocabularies.** `-webkit-mask-composite` uses Porter-Duff names (`source-in`), standard `mask-composite` uses `intersect`. Setting only one property, or using the wrong vocabulary, silently loses the fade in one browser family — always set both, with each one's own keyword. Pairs naturally with `object-cover` + arbitrary `object-[x%_y%]` for the crop.
+
+## Decorative Background Blobs (Editorial Layering)
+
+Large soft shapes behind hero content. Three load-bearing gotchas, then the recipe:
+
+1. **`overflow-hidden` on the block root** — negatively-offset off-canvas shapes otherwise create horizontal scroll (this operationalizes ui-ux-guidelines.md §21's no-horizontal-overflow rule).
+2. **`pointer-events-none` on every decorative layer** — so they never intercept clicks on content.
+3. **vw sizing paired with px max-caps** — shapes scale with the viewport but don't balloon on ultrawide.
+
+```tsx
+<div className="relative overflow-hidden ...">
+  {/* decoration: z-0 */}
+  <div className="pointer-events-none absolute -top-[22%] -right-[10%] w-[62vw] h-[62vw] max-w-[900px] max-h-[900px] rounded-full bg-[#AE5E3D] z-0" />
+  {/* art layer (e.g. masked photo): z-[1] */}
+  {/* content: z-10 */}
+  <main className="relative z-10 ...">...</main>
+</div>
+```
+
+The z-0 / z-[1] / z-10 stack is block-internal layering — it complements (does not replace) the overlay z-scale in ui-ux-guidelines.md §7.
+
+## Dot-Separated Inline List
+
+Certifications, feature tags, meta rows: `GMP Manufacturing ● ISO 22716 ● Low MOQs`. Render separators LEADING (never trailing), keep the two gap values identical, and hide the glyphs from screen readers:
+
+```tsx
+<div className="flex flex-wrap items-center gap-x-8 gap-y-3">
+  {items.map((item, index) => (
+    <span key={index} className="flex items-center gap-x-8">
+      {index > 0 && <span aria-hidden="true" className="text-[7px] text-muted-foreground leading-none">●</span>}
+      <span>{item.label}</span>
+    </span>
+  ))}
+</div>
+```
+
+- **Two gap declarations, deliberately equal** — the container's `gap-x-8` spaces item→item, the item span's `gap-x-8` spaces dot→label; symmetry depends on the two values matching, so keep them identical (hoist to a shared constant if you touch them often). The real fix over Studio AI's emitted shape is the **leading**-separator guard (`index > 0`): Studio puts a trailing dot inside each item, which dangles alone at the end of a wrapped line, and its two gap values match only by accident.
+- **Keep `gap-y-*`** on the container for multi-line rhythm when the list wraps.
+- **If the list is expected to wrap often**, drop the dots and let the gap carry the rhythm — any inline separator looks orphaned at a line break.
+- `aria-hidden="true"` on the glyph — screen readers announce `●` as "black circle" otherwise.

package/references/editable-settings.md

@@ -0,0 +1,238 @@
+# Editable Settings — Hook Catalog, Granularity Doctrine, Undocumented Hooks & Types
+
+Editable settings are the hooks from `@/lib/editable-settings` that surface a block's content in Studio's **Content → Settings** pane, so builders (and clients) edit text, images, links, and lists **without re-prompting or touching code**. Softr's own pitch: "make simple text and image edits directly without re-prompting." This file is the deep-dive; SKILL.md keeps the compact signatures.
+
+**Provenance discipline.** Every behavior below is tagged either **[official]** (in Softr's Vibe Coding Developer Guide, re-fetchable via the MCP's `get_vibe_coding_docs`) or **[verified-undocumented]** (absent from the official guide but proven working — source and date given). Keep the tags when editing this file: they're what stops a future docs-based review from false-positiving working code (the same failure class as the useRecord-via-Studio-binding incident), and what tells you which behaviors could silently change under you since Softr never promised them.
+
+## Contents
+
+- [Hook catalog](#hook-catalog)
+- [Text hooks: useTextSetting and useLongTextSetting](#text-hooks-usetextsetting-and-uselongtextsetting)
+- [Media hooks: useImageSetting and useVideoSetting](#media-hooks-useimagesetting-and-usevideosetting)
+- [useVibeCodingBlockIconSetting](#usevibecodingblockiconsetting)
+- [useNavigationSetting](#usenavigationsetting)
+- [useBooleanSetting](#usebooleansetting)
+- [useArraySetting](#usearraysetting)
+- [Granularity doctrine: settings-first static blocks](#granularity-doctrine-settings-first-static-blocks)
+- [Naming conventions and the rename-resets-value gotcha](#naming-conventions-and-the-rename-resets-value-gotcha)
+- [Constraints recap](#constraints-recap)
+
+## Hook catalog
+
+| Hook | Returns | Status |
+|---|---|---|
+| `useTextSetting` | `string` | [official] |
+| `useLongTextSetting` | `string` (multi-line textarea in the pane) | [verified-undocumented] Studio-AI output, 2026-08-31 |
+| `useImageSetting` | `{ src, alt }` | [official] |
+| `useVideoSetting` | `{ src }` | [official] |
+| `useVibeCodingBlockIconSetting` | `{ icon }` (Lucide name) | [official] |
+| `useNavigationSetting` | navigation object (see below) | [official] |
+| `useBooleanSetting` | `boolean` | [official] |
+| `useArraySetting` | array of schema-shaped items | [official] — plus one [verified-undocumented] schema type |
+
+All hooks share the base options `{ name, label, initialValue }`; `useTextSetting` also takes `required` (optional, default false). `name` must be unique per block (Hard Constraint 5) and is the persistence key (see [the rename gotcha](#naming-conventions-and-the-rename-resets-value-gotcha)).
+
+## Text hooks: useTextSetting and useLongTextSetting
+
+```tsx
+import { useTextSetting, useLongTextSetting } from "@/lib/editable-settings";
+
+const title = useTextSetting({
+  name: "title",
+  label: "Title",
+  initialValue: "Welcome",
+  required: false,          // optional, default false
+});
+// Returns: string — single-line input in the Settings pane
+
+const description = useLongTextSetting({
+  name: "description",
+  label: "Description",
+  initialValue: "Formulation, manufacturing and packaging under one roof.",
+});
+// Returns: string — multi-line textarea with an expand control in the Settings pane
+```
+
+**Rule of thumb:** `useTextSetting` for single-line strings (labels, headings, CTA text, URLs); `useLongTextSetting` for paragraph-length copy (descriptions, testimonial bodies, bios).
+
+**[verified-undocumented]** `useLongTextSetting` is absent from the official developer guide (checked 2026-08-31) but is emitted by Softr's own Studio AI and renders a working multi-line textarea in the Settings pane (screenshot-verified on a live Studio block). Same options shape as `useTextSetting`; return type `string` is inferred from usage, not a published signature.
+
+**Newline gotcha — the one thing that makes it different in practice.** The pane's textarea lets builders enter line breaks, but HTML collapses `\n` to spaces. Render the value with `whitespace-pre-line` (or split on `\n` yourself) or the builder's paragraph breaks silently vanish:
+
+```tsx
+<p className="whitespace-pre-line text-muted-foreground">{description}</p>
+```
+
+Studio AI itself gets this wrong (renders the value in a plain `<p>`), so fix it when adopting Studio-generated code.
+
+## Media hooks: useImageSetting and useVideoSetting
+
+```tsx
+import { useImageSetting, useVideoSetting } from "@/lib/editable-settings";
+
+const image = useImageSetting({
+  name: "hero-image",
+  label: "Hero image",
+  initialValue: { src: "https://...", alt: "A hero image" },
+});
+// Returns: { src: string, alt: string }
+
+const video = useVideoSetting({
+  name: "intro-video",
+  label: "Intro video",
+  initialValue: { src: "https://example.com/video.mp4" },
+});
+// Returns: { src: string }
+```
+
+**Empty-src gating.** Blocks routinely ship with `initialValue: { src: "" }` so the builder uploads the real asset in the pane — the official docs' own array example seeds `image: { src: "", alt: "" }`, so the empty state is platform-normal. Never render an unconditional `<img src={image.src}>` against a possibly-empty setting: an empty-string `src` triggers React's re-download warning and shows a broken/empty band at whatever fixed height you gave it. Gate it, or render a same-size placeholder so the layout holds pre-upload:
+
+```tsx
+{image.src ? (
+  <img src={image.src} alt={image.alt} className="w-full h-[340px] object-cover" />
+) : (
+  <div className="w-full h-[340px] bg-muted" aria-hidden="true" />
+)}
+```
+
+**One setting, several renders.** A settings hook returns a plain value, so one `useImageSetting` may safely feed two sibling `<img>` elements with opposite visibility classes (desktop art-directed crop + mobile full-bleed). The builder still edits ONE image in the pane. See ui-ux-guidelines.md §21 (art-directed responsive images).
+
+## useVibeCodingBlockIconSetting
+
+```tsx
+import { useVibeCodingBlockIconSetting } from "@/lib/editable-settings";
+import { DynamicIcon } from "@/components/dynamic-icon";
+
+const { icon } = useVibeCodingBlockIconSetting({
+  name: "feature-icon",
+  label: "Feature icon",
+  initialValue: { icon: "trending-up" },   // kebab-case lucide-react name
+});
+
+<DynamicIcon name={icon} className="w-6 h-6" />
+```
+
+Returns `{ icon: string }`. Always render through `<DynamicIcon>` — never a manual lookup table.
+
+## useNavigationSetting
+
+```tsx
+import { useNavigationSetting } from "@/lib/editable-settings";
+import { NavigationAction } from "@/components/navigation-action";
+import { Button } from "@/components/ui/button";
+
+const cta = useNavigationSetting({
+  name: "primary-cta-link",
+  label: "Primary CTA link",
+  initialValue: { action: "OPEN_PAGE", destination: "/pricing", openIn: "SELF" },
+});
+
+<Button asChild>
+  <NavigationAction navigation={cta}>Request your quote</NavigationAction>
+</Button>
+```
+
+Value shapes per action type (full detail in SKILL.md's NavigationAction section; the official docs type `openIn` as `"SELF" | "TAB"` only — `"MODAL"` is validator-verified as a legal value per the error message quoted in [Constraints recap](#constraints-recap), and its restriction to `OPEN_PAGE` is inference from Studio behavior, not documented):
+
+- `OPEN_PAGE` — `destination` (page path) + `openIn` (`"SELF"` | `"TAB"` | `"MODAL"`)
+- `OPEN_URL` — `destination` (URL) + `openIn` (`"SELF"` | `"TAB"`)
+- `OPEN_CHAT` — no destination (mind the data-source-context gotcha in [anti-patterns.md](anti-patterns.md))
+- `TRIGGER_CUSTOM_WORKFLOW` — no destination; builder picks the workflow in Studio (workflow-side receiving end by name: the "Run Custom Workflow action triggered" trigger — name-based match, not wired live; see [softr-mcp.md](softr-mcp.md#workflows))
+
+**[verified-undocumented] `action` is accepted as optional.** Softr's setting validator accepts an initialValue with no `action` key — `{ destination: "/", openIn: "SELF" }` alone — and Studio's own AI emits exactly that shape (verified 2026-08-31: a Studio-generated block with three action-less `useNavigationSetting` initialValues, plus three more action-less link values inside an array setting, saved and rendered its Settings pane). Corroborating in-repo evidence that not every key is mandatory: the validator's own error message for `openIn` ends in *"if provided"* (see [anti-patterns.md](anti-patterns.md#editable-settings)). Two consequences:
+
+1. **When generating, keep emitting an explicit `action`** — deterministic, self-documenting, and click-time resolution of action-less values is unverified (presumably defaults to `OPEN_PAGE` for in-app paths, but that's inference).
+2. **When reviewing Studio-generated or existing blocks, do NOT flag a missing `action` as a defect.** It saves and renders fine.
+
+## useBooleanSetting
+
+```tsx
+import { useBooleanSetting } from "@/lib/editable-settings";
+
+const showHeader = useBooleanSetting({
+  name: "toggle-header",
+  label: "Toggle header",
+  initialValue: false,      // official docs note the default is true when omitted
+});
+// Returns: boolean
+```
+
+Use for show/hide sections, layout variants, feature toggles.
+
+## useArraySetting
+
+```tsx
+import { useArraySetting } from "@/lib/editable-settings";
+
+const navItems = useArraySetting({
+  name: "nav-items",
+  label: "Navigation items",
+  schema: {
+    label: { type: "text", label: "Label", initialValue: "Item" },
+    link: { type: "navigation", label: "Link", initialValue: { action: "OPEN_PAGE", destination: "/", openIn: "SELF" } },
+  },
+  initialValue: [
+    { label: "Capabilities", link: { action: "OPEN_PAGE", destination: "/#capabilities", openIn: "SELF" } },
+    { label: "Process", link: { action: "OPEN_PAGE", destination: "/#process", openIn: "SELF" } },
+  ],
+});
+```
+
+Returns an array of schema-shaped items, rendered in the Settings pane as **reorderable rows** with per-field editors and an "Add item" control. Use for nav menus, feature lists, testimonials, badges, footer link columns, FAQs.
+
+### Schema field types
+
+`"text"`, `"image"`, `"video"`, `"vibeCodingBlockIcon"` **[official]** — plus:
+
+**[verified-undocumented] `"navigation"`.** A `{ type: "navigation" }` schema entry renders a per-item link picker (page picker / URL / openIn) inside each row, and item values carry the `useNavigationSetting` value shape — pass them straight to `<NavigationAction navigation={item.link}>`. Verified 2026-08-31 via a Studio-AI-generated block whose Settings pane showed nav items as reorderable rows with rendered per-item link pickers. This unlocks fully builder-editable nav menus, footer link lists, and CTA collections; without it you'd be stuck hardcoding links or spawning N separate `useNavigationSetting` hooks. (Click-through of array-item links follows from the value shape being identical to top-level navigation settings consumed by the same component, but wasn't independently click-tested.)
+
+### Initial values: two layers
+
+- **Top-level `initialValue` array** seeds the rows the block starts with.
+- **Per-field `initialValue` inside the schema** is the default a field gets when the builder clicks **Add item**. It's optional [official — the docs' own example omits it on some fields], BUT:
+
+**Give `navigation`-typed schema entries a per-field `initialValue` (or guard the render).** A schema entry like `link: { type: "navigation", label: "Link" }` with no initialValue means every builder-added row starts with `link: undefined`, which flows straight into `<NavigationAction navigation={undefined}>` — behavior unverified (dead element at best). Either seed it in the schema (as in the example above) or guard: `{item.link && <NavigationAction navigation={item.link}>...</NavigationAction>}`.
+
+### Key array rows by index
+
+```tsx
+{navItems.map((item, index) => (
+  <NavigationAction key={index} navigation={item.link}>{item.label}</NavigationAction>
+))}
+```
+
+Never key by an editable field (`key={item.label}`). Builder-added rows all start at the schema default (`"Item"`, `"Certification"`, ...), so value keys duplicate **immediately** — broken reorder/update rendering in the pane's live preview is the default path, not an edge case. The official docs' own example keys by index; index keys are safe here because setting rows are stateless display rows fully re-rendered on every settings change. Studio's own AI gets this wrong (emits `key={item.label}`) — don't copy that part of Studio output.
+
+## Granularity doctrine: settings-first static blocks
+
+**For static/marketing blocks (heroes, page headers, pricing tables, testimonial bands, footers, FAQ sections): every user-visible string, image, and link is a setting by default. Hardcoded copy is the exception and needs a reason.** This is Softr's own generator's revealed philosophy — a Studio-emitted hero ships with 15 settings hooks and zero hardcoded user-visible copy — and it matches the official guidance ("Always use them for any text, images, icons, or lists that might change between block instances"). The payoff is the platform pitch itself: clients edit copy in **Content → Settings** without re-prompting, and one block template re-skins across client apps.
+
+The recurring patterns:
+
+- **Heading-line split** — one `useTextSetting` per visual line, joined with `<br />`, names suffixed `-line-1` / `-line-2` / `-line-3`. Gives builders line-break control without markup in a text field:
+
+  ```tsx
+  <h1>
+    {headingLine1}<br />{headingLine2}<br />{headingLine3}
+  </h1>
+  ```
+
+- **CTA pairing** — every call-to-action is TWO settings: `<x>-text` (`useTextSetting`) + `<x>-link` (`useNavigationSetting`). E.g. `primary-cta-text` / `primary-cta-link`, `login-button-text` / `login-button-link`.
+- **Repeated groups** — any repeated UI group (nav items, badges, certifications, logos) is a `useArraySetting`, not N individual hooks.
+
+For data-connected blocks the doctrine relaxes: record data comes from the datasource, and settings cover the frame around it (section headings, empty-state copy, CTA labels/links, toggles).
+
+## Naming conventions and the rename-resets-value gotcha
+
+**Convention:** kebab-case names describing the content's role — `logo-text`, `tagline`, `heading-line-1`, `primary-cta-text`, `nav-items`. Matches Studio AI's own output. (These conventions are for **setting names** only — the window-global and CustomEvent naming schemes in [helper-blocks.md](helper-blocks.md) are a different namespace; don't conflate them.)
+
+**Gotcha [official]:** the docs annotate `name` with *"unique identifier — changing this resets the value."* `name` is the persistence key: rename a setting in a later code edit and the builder's saved value silently resets to `initialValue`. **Treat setting names as stable API once a block is deployed** — a rename is silent builder-data loss, not a refactor.
+
+## Constraints recap
+
+The platform-enforced rules (Hard Constraints 5–7 in SKILL.md):
+
+- **Unique names** — no two setting hooks may share a `name`.
+- **No nested arrays in schemas** — for list-like text inside an array item, use a `"text"` field with a separator and split in code.
+- **`vibeCodingBlockIcon` never first** — don't put an icon field as the first field in an array schema.
+- **`openIn`** must be exactly `"SELF"`, `"TAB"`, or `"MODAL"` (validator-enforced — see [anti-patterns.md](anti-patterns.md#editable-settings)).

package/references/native-chrome-styling.md

@@ -1,6 +1,6 @@
 # Styling Softr's Native Shell (Header · Footer · Page Background) 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 them as a Vibe Coding block. To re-skin them, add **CSS to Settings → Custom Code → Code inside header** (the same place brand fonts/tokens live, i.e. the `custom-code-header.html` produced by `building-design-md`). 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.
+**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, i.e. the `custom-code-header.html` produced by `building-design-md`). 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.
 
@@ -212,8 +212,12 @@ body,
 })();
 ```
 
-## Restyle vs. replace
+## 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.
 
 **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.

package/references/quick-reference.md

@@ -15,8 +15,8 @@ import { datasource, useRecords, useRecord, useRecordCreate, useRecordUpdate, us
 // USER
 import { useCurrentUser } from "@/lib/user";
 
-// EDITABLE SETTINGS
-import { useTextSetting, useImageSetting, useVideoSetting, useArraySetting,
+// EDITABLE SETTINGS  (useLongTextSetting is undocumented officially but verified working 2026-08-31)
+import { useTextSetting, useLongTextSetting, useImageSetting, useVideoSetting, useArraySetting,
          useVibeCodingBlockIconSetting, useNavigationSetting,
          useBooleanSetting } from "@/lib/editable-settings";
 
@@ -201,10 +201,19 @@ var result2 = useMetric({ select: select, metric: metric.count() });
 ## Editable Settings
 
 ```jsx
-var title = useTextSetting({ name: "title", label: "Title", initialValue: "Hello" });
-var show = useBooleanSetting({ name: "toggle", label: "Show header", initialValue: false });
+var title = useTextSetting({ name: "title", label: "Title", initialValue: "Hello" });          // string
+var body = useLongTextSetting({ name: "body", label: "Body", initialValue: "..." });           // string; multi-line textarea — render with whitespace-pre-line
+var show = useBooleanSetting({ name: "toggle", label: "Show header", initialValue: false });   // boolean
+var items = useArraySetting({ name: "nav-items", label: "Nav items",
+  schema: { label: { type: "text", label: "Label", initialValue: "Item" },
+            link: { type: "navigation", label: "Link", initialValue: { action: "OPEN_PAGE", destination: "/", openIn: "SELF" } } },
+  initialValue: [/* seed rows */] });
+// Array schema types: "text" | "image" | "video" | "vibeCodingBlockIcon" | "navigation" (undocumented, verified 2026-08-31)
+// Key rendered array rows by INDEX, never by an editable field. Renaming a setting's `name` resets its saved value.
 ```
 
+Deep-dive (granularity doctrine, all hooks, gotchas): [editable-settings.md](editable-settings.md)
+
 ## Field Value Helper (getFieldValue)
 
 ```jsx
@@ -251,15 +260,17 @@ Catches BOTH Softr's in-app SPA navigation (nav bar, sidebar, `<NavigationAction
 export default function Block() {
   var result = useRecords({ select: select, count: 25 });
 
-  if (result.status === "pending") return <div className="container py-6"><div className="content">Loading...</div></div>;
-  if (result.status === "error") return <div className="container py-6"><div className="content">Error</div></div>;
+  if (result.status === "pending") return <div className="container py-0"><div className="content"><div className="py-3 px-8">Loading...</div></div></div>;
+  if (result.status === "error") return <div className="container py-0"><div className="content"><div className="py-3 px-8">Error</div></div></div>;
 
   var records = (result.data && result.data.pages) ? result.data.pages.flatMap(function(p) { return p.items; }) : [];
 
   return (
-    <div className="container py-6">
+    <div className="container py-0">
       <div className="content">
-        {/* UI */}
+        <div className="py-3 px-8">
+          {/* UI — inner wrapper owns vertical spacing; classes depend on placement (see SKILL.md Block Placement) */}
+        </div>
       </div>
     </div>
   );