softr-vibe-coding 1.11.2 → 1.12.0

package/CHANGELOG.md

@@ -4,6 +4,11 @@ All notable changes to this skill are documented here. Versions follow [Semantic
 
 Entries from 1.3.1 onward are generated automatically from git commit subjects between version bumps (see `.github/workflows/publish.yml`). Entries before 1.3.1 were backfilled by hand from the existing commit history.
 
+## [1.12.0] - 2026-07-22
+- Bump to 1.12.0 — multi-datasource blocks, Airtable rating writability, dark-brand canvas + page-background anti-patterns
+- Document the Airtable rating field as writable (plain integer 0-max; 0 clears it, so AVERAGE formulas skip it) — it was absent from the Supported Fields table, which made it the main unknown when building a star-rating form. Add two dark-brand styling anti-patterns: a block on a dark brand MUST paint its own backgroundColor because custom-code-header's body rule doesn't cross the shadow-DOM boundary and a default Softr page is white, so white text/logos/buttons render invisibly on white (the existing don't-double-paint row assumed a light app and inverts here); and setting html,body alone doesn't change the page background because Softr paints the same fill on FOUR stacked layers — html, body, #page-content, and a class-less wrapper div inside it — so paint html then clear the duplicates, excluding the .softr-topbar subtree
+- Add datasources/multi-datasource.md — a block can now connect to SEVERAL data sources: datasource.define({alias: 'uuid'}) plus a from: parameter on every data hook (useRecords, useRecord, useLinkedRecords, useFieldOptions, useMetric, useChartData, useRecordCreate/Update/Delete; not useUpload/useCurrentRecordId, which are app-level). Omitting from: throws once >1 source is connected; with exactly one you can skip define entirely. The define() values must be INLINE STRING LITERALS — hoisting them into constants fails to compile with 'datasource.define() object values must be string literals', same static-analysis rule as q.select(). Ids are plain UUIDs, not the table id and not the ds_id_N placeholder shape in Softr's docs; obtain them by asking Studio's AI chat to WRITE CODE, never to recite a value — asked three times in prose for the same three connected tables it returned three different confidently-worded sets, once recycling another table's uuid. This supersedes the one-table-per-block limit: relax Hard Constraint #13 to one useRecords per DATASOURCE, reframe helper-blocks.md around genuinely cross-BLOCK jobs (triggering another block, sharing computed state) with the old rationale kept as history, and retarget the useLinkedRecords anti-pattern at a second datasource rather than a helper
+
 ## [1.11.2] - 2026-07-08
 - Bump to 1.11.2 — publish recordId-less useRecord note and input.textAsync correction
 - Correct input.textAsync in airtable-automations.md — it is not a real method in EITHER Airtable scripting environment; calling it in the Scripting Extension throws TypeError: input.textAsync is not a function. buttonsAsync is the only interactive runtime prompt; free-text values (e.g. an API key) go through an input.config({...}) setting at the top or a hardcoded constant. Also generalize the Automation Scripts bullet to "no interactive prompts".

package/README.md

@@ -204,7 +204,9 @@ softr-vibe-coding/
 │
 └── datasources/                      # Data source guides (loaded on demand)
     ├── overview.md                   # Comparison matrix, selection guide
-    ├── shared-patterns.md            # Index → reading, writing, fields
+    ├── shared-patterns.md            # Index → multi-datasource, reading, writing, fields
+    ├── multi-datasource.md           # Several data sources in ONE block: datasource.define(),
+    │                                 #   the from: parameter, getting the datasource UUIDs
     ├── reading.md                    # useRecords, filtering, sorting, pagination,
     │                                 # metrics, charts, current user (198 lines)
     ├── writing.md                    # Mutations, uploads, linked record format,
@@ -263,7 +265,7 @@ The skill enforces these automatically, but good to know:
 - No arrow functions in JSX callback props — use `function() {}`
 - Must use `export default function Block()`
 - Must wrap layout in `<div className="container py-6"><div className="content">`
-- Only ONE `useRecords` call per block (use helper blocks for multi-table)
+- Only ONE `useRecords` call per **datasource** — but a block can connect to several sources; declare them with `datasource.define()` and pass `from:` on every hook
 - `fetchNextPage` only inside `useEffect` — in render body causes infinite loops
 - All hooks declared before any conditional `return` — React error #310
 - Every field value rendered in JSX must pass through `getFieldValue()`

package/SKILL.md

@@ -141,6 +141,8 @@ Softr supports 14 data sources. **Before writing any data-fetching code, read th
 | SQL Database | [datasources/sql-database.md](datasources/sql-database.md) | `useRecords` + `q.select()` |
 | REST API | [datasources/rest-api.md](datasources/rest-api.md) | `useProxyFetch` + `useQuery` |
 
+**A block can connect to MORE THAN ONE of these at a time.** Declare them with `datasource.define({ alias: "uuid" })` and pass `from: ds.alias` on every data hook — read two tables and write to a third from a single block. Required reading before building anything multi-table: [datasources/multi-datasource.md](datasources/multi-datasource.md). (This replaces the old one-table-per-block limit and the invisible-helper-block workaround.)
+
 For shared data fetching patterns (useRecords, mutations, uploads, metrics, charts), see [datasources/shared-patterns.md](datasources/shared-patterns.md).
 
 For data source comparison and selection guidance, see [datasources/overview.md](datasources/overview.md).
@@ -151,7 +153,8 @@ For advanced patterns beyond data fetching, load the relevant reference when the
 
 | If the task involves... | Load reference |
 |---|---|
-| Cross-block communication, multi-table data access, invisible helper blocks, window globals, breadcrumbs | [references/helper-blocks.md](references/helper-blocks.md) |
+| Reading/writing **several tables from one block** — `datasource.define()`, the `from:` parameter, obtaining the datasource UUIDs (and why Studio's chat invents them) | [datasources/multi-datasource.md](datasources/multi-datasource.md) |
+| Cross-*block* communication, window globals, breadcrumbs, publishing shared computed state. *(Multi-table reads no longer need a helper — use a second datasource.)* | [references/helper-blocks.md](references/helper-blocks.md) |
 | Embedding third-party libraries with their own CSS (Leaflet, Mapbox, TinyMCE, Quill, FullCalendar) | [references/advanced-integrations.md](references/advanced-integrations.md) |
 | Debugging a broken block, checking patterns before delivery, full violation catalog | [references/anti-patterns.md](references/anti-patterns.md) |
 | Quick syntax check — import paths, hook signatures, mutation call shapes, field mapping | [references/quick-reference.md](references/quick-reference.md) |
@@ -446,9 +449,19 @@ Non-negotiable rules enforced by the Softr platform:
 10. **No optional chaining or nullish coalescing** — Softr's bundler fails on `?.` and `??`. Use:
     - `(user && user.email) || ""` instead of `user?.email ?? ""`
     - `(data && data.pages) ? data.pages.flatMap(function(p) { return p.items; }) : []`
+
+    ⚠️ **Possibly stale — do not relax on this note alone.** July 2026: a block scaffolded by Studio's own
+    AI assistant used `peopleData?.pages` and `status?.label` and rendered correctly in a published app,
+    which contradicts this rule. That's a single observation and the failure mode is a block that won't
+    compile, so the rule stands until someone re-tests it deliberately. Writing `&&` costs nothing and
+    works under either behaviour. If you confirm `?.` compiles reliably, update this constraint, the
+    self-validation checklist, and the Style Conventions note together.
 11. **Airtable: use column names, not fld... IDs** — See [datasources/airtable.md](datasources/airtable.md).
 12. **Record fields nested under `fields`** — Access via `record.fields.alias`, not `record.alias`.
-13. **ONE `useRecords` per block** — Filter client-side. Multiple `useMetric` calls OK.
+13. **ONE `useRecords` per datasource** — filter client-side rather than issuing several queries against
+    the same table. A block CAN connect to multiple data sources and call `useRecords` once per source;
+    declare them with `datasource.define()` and pass `from:` on every hook. See
+    [datasources/multi-datasource.md](datasources/multi-datasource.md). Multiple `useMetric` calls OK.
 14. **React functional components only** — No class components.
 15. **Do NOT `import React from 'react'`** — Use named imports for hooks.
 16. **No CSS modules or styled-components** — Tailwind only.
@@ -465,7 +478,7 @@ The conventions below improve consistency across the skill's examples but are NO
 - Prefer `function() {}` over arrow functions in JSX callbacks and component props
 - Field-value helper property priority: `label` -> `name` -> `title`
 
-If you're editing a block originally generated by Softr's AI assistant, you can convert to skill style for consistency or leave the AI's syntax as-is. Both produce a working block. Only `?.` and `??` (Hard Constraint #10) are actual bundler blockers — verified by direct experiment, April 2026.
+If you're editing a block originally generated by Softr's AI assistant, you can convert to skill style for consistency or leave the AI's syntax as-is. Both produce a working block. Only `?.` and `??` (Hard Constraint #10) are actual bundler blockers — verified by direct experiment, April 2026. *(But see the caveat on constraint #10: a Studio-scaffolded block using `?.` rendered fine in July 2026. Keep avoiding it until that's deliberately re-tested.)*
 
 ## Anti-Patterns Checklist
 

package/datasources/airtable.md

@@ -120,6 +120,7 @@ This script reads only **metadata**, never records. To inspect record contents i
 | Number               | Yes       | |
 | Date                 | Yes       | |
 | Checkbox             | Yes       | |
+| Rating               | Yes       | Star field. **Writable** — send a plain integer `0`–`max`; `0` clears it (Airtable treats a cleared rating as empty, so `AVERAGE` formulas skip it). Reads back as a number. Verified by direct experiment, July 2026: a create Action with three `rating` fields derived cleanly and wrote all three. |
 | Single Select        | Yes       | Returns as `{ label, id }` object. Use `getFieldValue()` helper to extract the label. |
 | Multiple Select      | Yes       | Array of `{ label, id }` objects |
 | Attachment           | Yes       | Array of `{ filename, id, type, url }` objects |

package/datasources/multi-datasource.md

@@ -0,0 +1,106 @@
+# Multiple Data Sources in One Block
+
+A Vibe Coding block can connect to **several data sources at once**. Declare them with
+`datasource.define()` and target one per hook with `from:`.
+
+This supersedes the old one-table-per-block limit. Blocks that needed a second table used to
+require an invisible helper block publishing to a `window` global — that workaround is no
+longer necessary for plain multi-table reads. See [../references/helper-blocks.md](../references/helper-blocks.md)
+for what helper blocks are still genuinely for.
+
+## The pattern
+
+```jsx
+import { datasource, useRecords, useRecordCreate, q } from "@/lib/datasource";
+
+var ds = datasource.define({
+  people: "74d2cbfd-f2cb-4f5c-82d9-0d3a0651e531",
+  shifts: "ec7a6311-f6c3-4c99-881d-aae308148716",
+  feedback: "52461ab9-9912-4e15-bcf4-8838d38c64ea",
+});
+
+var peopleSelect = q.select({ email: "Email", firstName: "First name" });
+var shiftSelect = q.select({ jobCode: "Job Code" });
+var feedbackCreateFields = q.select({ comments: "Comments", crewMember: "Crew Member" });
+
+export default function Block() {
+  var people = useRecords({ from: ds.people, select: peopleSelect, count: 20 });
+  var shifts = useRecords({ from: ds.shifts, select: shiftSelect, count: 5 });
+
+  var createFeedback = useRecordCreate({
+    from: ds.feedback,
+    fields: feedbackCreateFields,
+    onSuccess: function () { /* … */ },
+  });
+  // …
+}
+```
+
+**`from:` is required on every data hook once a block has more than one source.** Omitting it
+throws. With exactly one source you can skip `datasource.define` and omit `from` entirely —
+the hooks default to that source.
+
+Applies to: `useRecords`, `useRecord`, `useLinkedRecords`, `useFieldOptions`, `useMetric`,
+`useChartData`, `useRecordCreate`, `useRecordUpdate`, `useRecordDelete`.
+
+Does **not** apply to `useUpload` and `useCurrentRecordId` — those are app-level and take no `from`.
+
+## The values must be inline string literals
+
+Softr statically analyses `datasource.define()`, exactly like `q.select()`. Hoisting the ids
+into constants fails to compile:
+
+```jsx
+// WRONG — "datasource.define() object values must be string literals"
+var PEOPLE_DS_ID = "74d2cbfd-…";
+var ds = datasource.define({ people: PEOPLE_DS_ID });
+
+// CORRECT — literals, in place
+var ds = datasource.define({ people: "74d2cbfd-…" });
+```
+
+The error text is explicit, so this one fails fast rather than silently — but it's an easy
+reflex to hoist "magic strings" into named constants, and that reflex is wrong here.
+
+## Getting the datasource ids — ask for CODE, never for a value
+
+The id is a plain **UUID**. It is *not* the underlying table id (`tbl…` in Airtable), and not
+the `ds_id_1` shape used as a placeholder in Softr's own developer guide.
+
+**Studio's AI chat fabricates these when asked in prose.** Verified 2026-07-22: asked three
+times for the ids of the same three connected tables, it returned three different sets, once
+recycling a previously-mentioned table's uuid for a different table. All three answers were
+confidently worded. None were flagged as uncertain.
+
+Ask it to **write code** instead:
+
+```
+Write a datasource.define call covering every data source connected to this
+block, plus one useRecords per source. Output code only.
+```
+
+Code generation is bound to the block's real connections, so the ids come out correct — the
+same reason Softr's assistant reliably inlines select-option UUIDs when scaffolding a form but
+invents them when asked to recite one.
+
+**Then verify by running it.** The scaffold renders a list per source; if real rows appear
+under each heading, every alias maps to the table you think it does. A wrong uuid fails safe
+(it matches no datasource, so the block errors) — but a *swapped* pair of correct uuids does
+not, and only running it will catch that.
+
+## When you still want a helper block
+
+Multi-datasource removes the need for helpers as a *data-access* workaround. They remain the
+right tool for:
+
+- **Cross-block communication** — one block triggering or feeding another on the same page.
+- **Publishing computed state** — expensive derivations shared by several consumers.
+- **Rich foreign data via `useLinkedRecords`** — that hook still only returns `{id, title}`
+  and silently ignores extra fields in `select`. Reading the foreign table directly with its
+  own `from:` is now the simpler fix.
+
+## Worked example
+
+`crew-feedback-form.jsx` — a public feedback form that reads a person from **People** by an
+`email` URL param, resolves a **Shifts** record from a job-code param, and writes a row to
+**Feedback** linking both. One block, three sources, no helpers, no `window` globals.

package/datasources/reading.md

@@ -56,7 +56,9 @@ var isRefetching = result.isRefetching;
 var items = (data && data.pages) ? data.pages.flatMap(function(p) { return p.items; }) : [];
 ```
 
-**CRITICAL:** Only ONE `useRecords` call per block. Fetch all data in one call and filter client-side. Multiple `useMetric` calls ARE allowed.
+**CRITICAL:** Only ONE `useRecords` call **per datasource**. Fetch that table's data in one call and filter client-side. Multiple `useMetric` calls ARE allowed.
+
+A block can connect to **several data sources** and call `useRecords` once per source — declare them with `datasource.define()` and pass `from:` on every hook. See [multi-datasource.md](multi-datasource.md). (This replaces the old one-table-per-block limit; blocks no longer need an invisible helper block just to read a second table.)
 
 ### Loading All Records (Auto-Pagination)
 

package/datasources/shared-patterns.md

@@ -4,6 +4,7 @@ These patterns apply to all data sources that use `useRecords` + `q.select()` (e
 
 | Topic | Guide |
 |---|---|
+| **Multiple data sources in one block** — `datasource.define()`, the `from:` parameter, getting the datasource UUIDs | [multi-datasource.md](multi-datasource.md) |
 | Query builder, useRecords, useRecord, useLinkedRecords, filtering, sorting, pagination, current user, metrics, chart data | [reading.md](reading.md) |
 | Record mutations (create/update/delete), file uploads, linked record format, cross-table REST API writes | [writing.md](writing.md) |
 | `getFieldValue()` helper, field type shapes, record structure, debug utilities (Field Inspector, User Inspector) | [fields.md](fields.md) |

package/package.json

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

package/references/anti-patterns.md

@@ -15,6 +15,10 @@ Run through this catalog before delivering any block. Every row is a violation o
 | `q.select()` for REST API fields | Access raw API response directly |
 | Hardcoding API keys for connected API | Use `useProxyFetch` -- key stays server-side |
 | Using `q.select({})` to dump all fields on Softr Database | Returns record IDs with empty `fields: {}`. Look up field IDs in Studio's Data tab, or use the Softr DB REST API with `fieldNames=true` |
+| Building an invisible helper block + `window` globals just to read a second table | A block can connect to **multiple data sources**. Declare them with `datasource.define({ alias: "uuid" })` and pass `from: ds.alias` on every hook. One block instead of two, no page-order dependency, no mount-timing race. See [datasources/multi-datasource.md](../datasources/multi-datasource.md). Helper blocks remain correct for genuinely cross-*block* jobs (triggering another block, sharing computed state) — just not for plain multi-table reads |
+| Omitting `from:` on a hook when the block has more than one datasource | Throws at runtime. `from:` is optional ONLY when exactly one source is connected — then hooks default to it. Applies to `useRecords`, `useRecord`, `useLinkedRecords`, `useFieldOptions`, `useMetric`, `useChartData`, `useRecordCreate`, `useRecordUpdate`, `useRecordDelete`. NOT to `useUpload` / `useCurrentRecordId`, which are app-level |
+| Hoisting datasource ids into constants: `datasource.define({ people: PEOPLE_DS_ID })` | Fails to compile — *"datasource.define() object values must be string literals."* Softr statically analyses the call, same as `q.select()`. Keep the UUIDs **inline**: `datasource.define({ people: "74d2cbfd-…" })`. Fails fast with an explicit message, but hoisting magic strings is a strong reflex — resist it here |
+| Asking Studio's AI chat "what are the datasource IDs?" and pasting the answer | **It fabricates them.** Verified July 2026: asked three times for the same three connected tables, it gave three different UUID sets, once reusing a previously-mentioned table's uuid for a different table — all confidently worded, none hedged. Ask it to **write code** instead (*"write a datasource.define call covering every connected source, plus one useRecords per source, code only"*) — scaffolding is bound to the real connections. Then RUN it: real rows under each heading proves each alias maps where you think. A wrong uuid fails safe (matches nothing → error); a *swapped pair* of valid uuids does not |
 
 ## Mutations
 
@@ -60,7 +64,9 @@ Run through this catalog before delivering any block. Every row is a violation o
 | Emojis in UI | lucide-react icons only |
 | `[&_svg]:opacity-0` on SelectTrigger | `<style>` + `data-fix-chevron` attribute (Softr bundler limitation) |
 | Relying on `custom-code-header.html` (Softr → Settings → Custom Code → Code inside header) to apply brand fonts/colors INSIDE a Vibe Coding block | Vibe Coding blocks render inside a shadow DOM. CSS custom properties (`--brand-*`) pierce that boundary, but `html, body { font-family: ... !important }` rules **do not** — `<html>` and `<body>` don't exist inside the shadow root. Apply brand fonts/colors at the block's **own outermost wrapper** via inline style: `style={{ fontFamily: "'Manrope', system-ui, sans-serif", color: BRAND_INK }}` on the outer `<div>` so every descendant inherits brand defaults. Override per-element with explicit inline `fontFamily` (e.g., `"'Fraunces', Georgia, serif"` on h1/h2). Google `<link>` tags in the page head DO load `@font-face` globally — the fonts are available inside shadow DOM, they just need to be applied. |
-| Painting `backgroundColor: BRAND_CANVAS` on a Vibe Coding block's outer wrapper when `custom-code-header.html` already sets `body { background-color: var(--brand-canvas) !important }` | Don't double-paint. If the body bg is already the brand canvas, the block leaves its own backgroundColor unset and the page bg shows through. Painting the same color twice produces a visible seam — Softr's content wrapper sits between `<body>` and the Vibe Coding block, and the two backgrounds composite slightly differently due to sub-pixel rendering, transparency stacking, or wrapper paddings. Set fontFamily and color on the block's wrapper (those don't inherit cleanly through shadow DOM), but **leave backgroundColor unset** — let the page bg flow through. The exception: if the block needs a brand-tinted *section* (e.g., a card-style admin shell that's different from the page bg), paint that bg explicitly on its specific container, not on the outer wrapper. |
+| Painting `backgroundColor: BRAND_CANVAS` on a Vibe Coding block's outer wrapper when `custom-code-header.html` already sets `body { background-color: var(--brand-canvas) !important }` | Don't double-paint. If the body bg is already the brand canvas, the block leaves its own backgroundColor unset and the page bg shows through. Painting the same color twice produces a visible seam — Softr's content wrapper sits between `<body>` and the Vibe Coding block, and the two backgrounds composite slightly differently due to sub-pixel rendering, transparency stacking, or wrapper paddings. Set fontFamily and color on the block's wrapper (those don't inherit cleanly through shadow DOM), but **leave backgroundColor unset** — let the page bg flow through. The exception: if the block needs a brand-tinted *section* (e.g., a card-style admin shell that's different from the page bg), paint that bg explicitly on its specific container, not on the outer wrapper. **Second exception — DARK brands: see the next row.** |
+| Relying on the page background on a **dark** brand, and shipping a block whose own canvas is unpainted | The row above assumes a light app whose page bg is already correct. On a dark brand it inverts: `custom-code-header.html`'s `body { background-color: #000 !important }` does NOT cross the shadow-DOM boundary, and a default Softr page is white — so a block with white text, a white-only logo, or a white primary button renders **invisibly on white**. Verified July 2026: a black-canvas feedback form shipped with its wordmark and its Submit button both white-on-white; the button was there and clickable, just unseeable. On a dark brand, paint `backgroundColor` on the block's own outer wrapper AND set the Softr page background to the same value — two identical pure blacks composite with no seam, so the double-paint concern above doesn't bite. Painting it in the block also keeps it correct if the custom-code snippet is ever removed. |
+| Setting only `html, body { background }` in `custom-code-header.html` and expecting the app to change colour | Softr paints the same page fill on **four stacked layers**: `html`, `body`, `#page-content`, and a **class-less wrapper div** nested inside `#page-content`. Styling one gets covered by the ones above it, so `body` alone appears to do nothing. Paint the backdrop on `html`, then clear the duplicates: `body, #page-content { background: transparent }` plus `#page-content div:not(.softr-topbar):not(.softr-topbar *)`. The `:not()` exclusion is required — the nav renders inside `#page-content` and that id's specificity out-ranks `.softr-topbar` rules, so a blanket clear silently flattens the dropdown panel. Full recipe in [native-chrome-styling.md](native-chrome-styling.md). |
 | `document.getElementById(...)` / `document.querySelector(...)` to find an element inside the block — for example, a hidden `<input type="file">` triggered by a visible "Upload" button via `getElementById('myInput').click()` | Vibe Coding blocks render inside a shadow DOM. The global `document` traversal stops at the shadow boundary, so id/selector lookups for elements inside the block return `null`. The user-visible symptom is a control that does nothing — no error, no file picker, no focus, no scroll — because the chained `.click()` / `.focus()` / `.scrollIntoView()` was called on `null`. Use a **React `useRef`** instead: `var inputRef = useRef(null)`, then `<input ref={inputRef} />` and `<button onClick={function() { if (inputRef.current) inputRef.current.click(); }}>`. Refs hold direct node references and don't depend on DOM traversal, so they work regardless of which DOM tree the node lives in. This applies to every "trigger a hidden element" pattern: hidden file inputs, programmatic focus, scroll-into-view, `.click()` on a non-visible button. |
 | Using `window.addEventListener("beforeunload", ...)` as the only unsaved-changes guard in a form block | Softr is a SPA. Internal nav (Softr's nav bar, sidebar links, `<NavigationAction>`) changes the route via the client-side router — `beforeunload` only fires on full page unload (tab close, refresh, external link), so the warning silently misses every in-app navigation. Use `useNavigationBlocker(isDirty)` from `@/lib/use-navigation-blocker` instead; it covers SPA nav AND browser unload with one API. Softr's Vibe Coding bundler often wires this automatically when a form is detected as dirty — you only need to add it manually for advanced cases (multi-step forms, custom dirty tracking, blocking on non-form state). See [common-patterns.md](common-patterns.md#navigation-blocker-for-unsaved-changes). |
 | Targeting Softr's hashed build classes (e.g. `.f8f11e5_m9ntthp`) when restyling the native header/nav from `custom-code-header.html` | Softr regenerates the hash on every deploy, so the rule silently dies. Target stable hooks: `.softr-topbar`, `.softr-nav-link`, `.softr-nav-button`, `.softr-nav-logo`, `#topbar-root`; for dropdown menus (no `softr-*` class) use the Radix/ARIA attrs `[role="menu"]` / `[role="menuitem"]` / `[role="group"]` / `[aria-expanded="true"]`, scoped under `.softr-topbar`. The native header is Softr chrome (main document), not a block — it can't be built as a Vibe Coding block. See [native-chrome-styling.md](native-chrome-styling.md). |
@@ -88,4 +94,4 @@ Run through this catalog before delivering any block. Every row is a violation o
 | Helper publishes only raw records | Also publish computed `filterOptions` as separate globals |
 | Refactoring helper shape without updating consumers | Version namespace OR update all consumers in same commit |
 | Helper B placed above A when B depends on A | A must be above B -- Softr renders top-to-bottom |
-| Using `useLinkedRecords` for rich foreign data | It only returns `{id, title}` -- use a helper block instead |
+| Using `useLinkedRecords` for rich foreign data | It only returns `{id, title}` and silently ignores extra `select` fields. Connect the foreign table as a **second datasource** and read it with its own `useRecords({ from: ds.x })` — see [multi-datasource.md](../datasources/multi-datasource.md). (A helper block also works and is what older blocks do, but it's now the heavier option.) |

package/references/helper-blocks.md

@@ -5,6 +5,8 @@ Cross-block communication via `window` globals, the invisible helper block patte
 ## Table of Contents
 
 - [When You Need Helper Blocks](#when-you-need-helper-blocks)
+- [When you still need a helper block](#when-you-still-need-a-helper-block)
+- [The original rationale (historic)](#the-original-rationale-historic)
 - [Companion Field Helpers](#companion-field-helpers)
 - [Breadcrumb / Back Navigation](#breadcrumb--back-navigation)
 - [Multi-Table Access via Invisible Helper Blocks](#multi-table-access-via-invisible-helper-blocks)
@@ -17,11 +19,39 @@ Cross-block communication via `window` globals, the invisible helper block patte
 
 ## When You Need Helper Blocks
 
-A Vibe Coding block can only connect to **one source table**. When your main block needs data from a second table (e.g., a task detail block that also needs the Users table for a team picker), you cannot add another `useRecords` for a different table.
+> ⚠️ **Read this first — the main reason for helper blocks is gone.** A Vibe Coding block can now
+> connect to **multiple data sources** and read each one with its own `useRecords({ from: ds.x })`.
+> See [../datasources/multi-datasource.md](../datasources/multi-datasource.md). For a plain
+> "my block also needs data from a second table", **use a second datasource, not a helper block** —
+> it's one block instead of two, no `window` globals, no page-order dependency, no mount-timing races.
+>
+> Everything below still works, and the cross-block sections are still the right tool for the jobs
+> listed under "When you still need a helper block". Historic blocks built on this pattern don't
+> need rewriting.
 
-**Solution:** Drop an invisible helper block on the same Softr page, connected to the second table. It fetches records, publishes them to a `window` global, and dispatches a custom event. The main block reads the global and listens for updates. The helper returns `null` so it renders nothing in the published app.
+## When you still need a helper block
 
-`useLinkedRecords` always returns `{id, title}` only and silently ignores extra fields in `select`. This is the core reason the helper block pattern exists. If your task involves showing status, due dates, or any non-title field from a linked table, skip `useLinkedRecords` entirely and build a helper -- there is no other way to get those fields.
+Reach for one only when the job is genuinely cross-block, not merely cross-table:
+
+- **Cross-block communication** — one block triggering behaviour in another on the same page
+  (see [Triggering Actions in Other Blocks](#triggering-actions-in-other-blocks-bi-directional-events)).
+- **Publishing computed state** — an expensive derivation several consumer blocks share, computed once.
+- **Rich filter options** shared across multiple blocks on a page.
+
+`useLinkedRecords` still returns `{id, title}` only and silently ignores extra fields in `select`.
+That limitation is unchanged — but the fix is now a second datasource with its own `from:`, not a
+helper block.
+
+## The original rationale (historic)
+
+A Vibe Coding block used to connect to **one source table** only. When a block needed data from a
+second table (e.g., a task detail block that also needs the Users table for a team picker), you
+could not add another `useRecords` for a different table.
+
+**The workaround:** drop an invisible helper block on the same Softr page, connected to the second
+table. It fetches records, publishes them to a `window` global, and dispatches a custom event. The
+main block reads the global and listens for updates. The helper returns `null` so it renders nothing
+in the published app.
 
 Key rules:
 - The helper block must be on the **same Softr page** as the consumer -- `window` is page-scoped, globals don't cross pages.
@@ -367,4 +397,4 @@ For per-user saved filter views on a list page:
 | Refactoring helper shape without updating consumers | Version namespace OR update all consumers in same commit |
 | Helper B placed above A when B depends on A | A must be above B -- Softr renders top-to-bottom |
 | `useRef` for IDs consumed by `useMemo` | Use `useState` -- ref mutations don't trigger recomputation |
-| Using `useLinkedRecords` for rich foreign data | It only returns `{id, title}` -- use a helper block instead |
+| Using `useLinkedRecords` for rich foreign data | It only returns `{id, title}` and silently ignores extra `select` fields. Connect the foreign table as a **second datasource** and read it with its own `useRecords({ from: ds.x })` — see [multi-datasource.md](../datasources/multi-datasource.md). (A helper block also works and is what older blocks do, but it's now the heavier option.) |

package/references/quick-reference.md

@@ -5,8 +5,8 @@ Fast lookup for imports, hook signatures, field mapping syntax, and common patte
 ## Imports
 
 ```jsx
-// DATASOURCE
-import { useRecords, useRecord, useRecordCreate, useRecordUpdate, useRecordDelete,
+// DATASOURCE  (add `datasource` when the block connects to more than one source)
+import { datasource, useRecords, useRecord, useRecordCreate, useRecordUpdate, useRecordDelete,
          useCurrentRecordId, useLinkedRecords, useUpload, useMetric, useChartData,
          q, metric } from "@/lib/datasource";
 
@@ -41,6 +41,20 @@ var updateFields = q.select({ alias: "FIELD_ID" });  // writable only
 var createFields = q.select({ alias: "FIELD_ID" });  // writable only
 ```
 
+## Multiple datasources (static, outside component)
+
+```jsx
+var ds = datasource.define({           // values MUST be inline string literals
+  people: "74d2cbfd-f2cb-4f5c-82d9-0d3a0651e531",
+  shifts: "ec7a6311-f6c3-4c99-881d-aae308148716",
+});
+
+useRecords({ from: ds.people, select: select });   // `from:` required once >1 source
+```
+
+Ids are plain UUIDs. Get them by asking Studio's AI chat to **write code**, never to recite a
+value — it fabricates them in prose. Full detail: [../datasources/multi-datasource.md](../datasources/multi-datasource.md).
+
 ## Read
 
 ```jsx