softr-vibe-coding 1.7.0 → 1.9.0

package/CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes to this skill are documented here. Versions follow [Semantic
 
 Entries from 1.3.1 onward are generated automatically from git commit subjects between version bumps (see `.github/workflows/publish.yml`). Entries before 1.3.1 were backfilled by hand from the existing commit history.
 
+## [1.9.0] - 2026-06-04
+- Bundle get-softr-database CLI script for schema export; document in SKILL.md, softr-database.md, fields.md
+- Bump publish workflow to Node 24-based action majors — actions/checkout@v4 -> @v6, actions/setup-node@v4 -> @v6 (clears the Node 20 deprecation; GitHub forces Node 20 actions to Node 24 on 2026-06-16). No version bump, so this run skips publish.
+
+## [1.8.0] - 2026-06-04
+- Expand references/native-chrome-styling.md to the full native shell — add Footer (semantic <footer> target + 160px/overflow-wrap contact-column email-wrap fix), floating "island" header/footer treatment, and Page background (Softr stacks the same fill on html/body/#page-content/inner-wrapper, so paint on html + clear the stack, EXCLUDING the .softr-topbar subtree so the dropdown panel survives) + a Console background-finder snippet; broaden SKILL.md Reference Guides row + README; add anti-patterns row for the page-background stacking; bump to 1.8.0
+
 ## [1.7.0] - 2026-06-04
 - Add references/native-chrome-styling.md — restyle Softr's native header/top bar/nav/dropdowns via global Custom Code CSS (target stable .softr-* / ARIA-Radix selectors instead of regenerated f8f11e5_* hashes, the dropdown column-grid blank-space fix, icon/label color-inherit, restyle-vs-replace tradeoffs); add SKILL.md scope note + Reference Guides row; add two anti-patterns rows; update README; bump to 1.7.0
 

package/README.md

@@ -18,7 +18,7 @@ This Claude skill teaches Claude Code how to generate complete, polished Softr V
 - **All 14 Softr data sources** — Airtable, Softr Database, Google Sheets, HubSpot, Notion, Coda, monday.com, SmartSuite, ClickUp, Xano, Supabase, BigQuery, SQL Database, and REST API — each with field mapping, rate limits, and gotchas
 - **Helper blocks & cross-block patterns** — Invisible helper blocks for multi-table access via `window` globals + `CustomEvent`, `useWindowData` hook, breadcrumb navigation, saved views architecture
 - **Advanced integrations** — Shadow DOM CSS isolation for third-party libraries (Leaflet, Mapbox, TinyMCE, Quill, FullCalendar)
-- **Native header styling** — re-skin Softr's native top bar, nav, and dropdown menus via global Custom Code CSS (stable selectors vs. hashed classes, the dropdown blank-space grid fix, restyle-vs-replace) — distinct from blocks
+- **Native shell styling** — re-skin Softr's native top bar, **footer**, nav, dropdowns, and **page background** via global Custom Code CSS (stable selectors vs. hashed classes, floating "island" header/footer, the dropdown grid fix, the multi-layer page-background stacking, restyle-vs-replace) — distinct from blocks
 - **UI/UX design guidelines** — 26 sections covering visual hierarchy, color, typography, spacing, motion design, accessibility, responsive patterns, and an AI slop anti-pattern checklist
 - **Self-validation** — Claude checks for Softr bundler compatibility (no optional chaining, correct imports, container wrappers, `getFieldValue()` wrapping, hooks ordering) before delivering code
 - **Premium visual baseline** — Every block ships polished from v1: gradient backgrounds, card elevation, loading skeletons, empty states, error states
@@ -185,9 +185,10 @@ softr-vibe-coding/
 │   │                                 # install, scope limitations)
 │   ├── advanced-integrations.md      # Shadow DOM CSS isolation (69 lines)
 │   │                                 # Leaflet, Mapbox, TinyMCE, Quill, FullCalendar
-│   ├── native-chrome-styling.md      # Restyle Softr's native header/nav/dropdowns
-│   │                                 # via global Custom Code CSS — stable selectors,
-│   │                                 # dropdown grid blank-space fix, restyle vs replace
+│   ├── native-chrome-styling.md      # Restyle Softr's native shell (header, footer,
+│   │                                 # nav, dropdowns, page background) via global
+│   │                                 # Custom Code CSS — stable selectors, floating
+│   │                                 # islands, dropdown grid fix, multi-layer page-bg
 │   ├── anti-patterns.md              # Categorized violation catalog (86 lines)
 │   │                                 # Data access, mutations, hooks, layout,
 │   │                                 # permissions, helper blocks

package/SKILL.md

@@ -86,7 +86,7 @@ When the user describes their block, figure out which of these areas apply and a
 
 - **Data source type**: Is it Airtable, Softr Database, REST API, or another source? This determines the data fetching approach. **Load the relevant data source guide** from the [datasources/](datasources/) directory before writing code.
 - **Data source fields**: For Airtable/Softr Database, you need actual field IDs. For REST APIs, you access the raw API response directly. If the user doesn't know field IDs:
-  - For **Softr Database**, the cleanest path is the **Softr Database MCP server** — ask whether they have it installed (`claude mcp list` shows it as `softr` or similar). If yes, query schema directly with the MCP tools instead of asking for paste-ins. If no, fall back to asking them to paste the `tablespace-with-tables` network response (DevTools -> Network -> filter that string while on Studio's Data tab) — the JSON contains every field ID, type, and dropdown option UUID. Optionally tell them they can install the MCP once with `claude mcp add --transport http softr https://mcp.softr.io/mcp` for future sessions. Full MCP details in [references/softr-database-mcp.md](references/softr-database-mcp.md); fallback paste-in workflows in [datasources/fields.md](datasources/fields.md#field-inspector-block).
+  - For **Softr Database**, the cleanest path is the **Softr Database MCP server** — ask whether they have it installed (`claude mcp list` shows it as `softr` or similar). If yes, query schema directly with the MCP tools instead of asking for paste-ins. If no, the next-best option is the bundled **`get-softr-database` CLI script** — tell the user to run `python3 ~/.claude/skills/softr-vibe-coding/tools/get-softr-database.py <database_id>` (it prompts for their Softr API key and exports the full schema to `~/Desktop/softr-database-<id>-<timestamp>.json` — Python stdlib only, nothing to install) and paste the resulting JSON into chat. As a final fallback, ask them to paste the `tablespace-with-tables` network response (DevTools -> Network -> filter that string while on Studio's Data tab) — same JSON content, different acquisition path. Optionally tell them they can install the MCP once with `claude mcp add --transport http softr https://mcp.softr.io/mcp` for future sessions. Full MCP details in [references/softr-database-mcp.md](references/softr-database-mcp.md); CLI script details in [datasources/softr-database.md](datasources/softr-database.md#bundled-cli-script-get-softr-database); fallback paste-in workflows in [datasources/fields.md](datasources/fields.md#field-inspector-block).
   - For **Airtable** and other sources where empty `q.select({})` works, suggest the Field Inspector block.
 - **Brand colors**: Already resolved in Step 1 (Detect the brand source). Don't re-ask. The brand source is one of:
   - **Project's `./DESIGN.md`** (recommended for client work — produced by the `building-design-md` skill)
@@ -157,7 +157,7 @@ For advanced patterns beyond data fetching, load the relevant reference when the
 | Small reusable patterns — `localStorage` cross-page state, clipboard copy button | [references/common-patterns.md](references/common-patterns.md) |
 | Writing Airtable Automation Scripts / Scripting Extension scripts / Airtable formulas — companion to Softr blocks for cross-table cascades and computed values | [references/airtable-automations.md](references/airtable-automations.md) |
 | AI-assisted Softr DB schema discovery / field-ID lookup / record reads via the official Softr MCP server (sibling to the in-block `useRecords` workflow) | [references/softr-database-mcp.md](references/softr-database-mcp.md) |
-| Restyling Softr's **native header / top bar / nav / dropdown menus** (not a block — it's Softr chrome, done with global Custom Code CSS): stable selectors vs. hashed classes, the dropdown blank-space grid fix, restyle-vs-replace tradeoffs | [references/native-chrome-styling.md](references/native-chrome-styling.md) |
+| Restyling Softr's **native shell — header / footer / nav / dropdowns / page background** (not a block; it's Softr chrome, done with global Custom Code CSS): stable selectors vs. hashed classes, floating "island" header+footer, the dropdown blank-space grid fix, the multi-layer page-background stacking, restyle-vs-replace | [references/native-chrome-styling.md](references/native-chrome-styling.md) |
 
 ## Code Structure
 

package/bin/cli.js

@@ -10,7 +10,7 @@ var SETTINGS_FILE = path.join(os.homedir(), '.claude', 'settings.json');
 var PACKAGE_ROOT = path.resolve(__dirname, '..');
 
 var SKILL_FILES = ['SKILL.md', 'ui-ux-guidelines.md', 'README.md', 'LICENSE'];
-var SKILL_DIRS = ['references', 'datasources'];
+var SKILL_DIRS = ['references', 'datasources', 'tools'];
 
 var HOOK_COMMAND = 'npx -y --prefer-online ' + SKILL_NAME + '@latest sync';
 

package/datasources/fields.md

@@ -111,15 +111,17 @@ export default function Block() {
 
 1. **Softr Database MCP server (recommended for AI-assisted workflows)** -- if you're collaborating with an AI assistant (Claude Code, Claude Desktop, Cursor, ChatGPT, Mistral) to write Vibe Coding blocks, the official Softr MCP server is the cleanest path. The AI calls schema/list-fields tools directly against your workspace and reads back every field's `id`, `name`, `type`, and dropdown option UUIDs -- no copy-paste, no transcription errors. Full setup, scopes, and scope limitations (Softr DB only -- does NOT cover Airtable / external sources) in [../references/softr-database-mcp.md](../references/softr-database-mcp.md).
 
-2. **Network inspector (full schema in one shot, no MCP needed)** -- in Studio's Data tab with browser DevTools open, filter Network requests by `tablespace-with-tables`. The Response JSON contains every table's complete schema, including:
+2. **`get-softr-database` CLI script (bundled, no MCP needed)** -- a Python CLI bundled with this skill at `~/.claude/skills/softr-vibe-coding/tools/get-softr-database.py`. Exports the full schema (every table, every field, all dropdown option UUIDs) to `~/Desktop/softr-database-<id>-<timestamp>.json`. Run with `python3 ~/.claude/skills/softr-vibe-coding/tools/get-softr-database.py <database_id>` (prompts for API key) or set `SOFTR_API_KEY=xxx` env var to skip the prompt. Stdlib only, no `pip install`. Best when you want a portable JSON dump for sharing in chat, archiving, or diffing across schema versions. Full usage in [softr-database.md](softr-database.md#bundled-cli-script-get-softr-database).
+
+3. **Network inspector (full schema in one shot, no MCP needed)** -- in Studio's Data tab with browser DevTools open, filter Network requests by `tablespace-with-tables`. The Response JSON contains every table's complete schema, including:
    - Each field's `id`, `name`, `type`, and `options`
    - For dropdown / SELECT fields: the full `choices` array with every option's `id` (UUID), `label`, and `color`
 
    Use this when scaffolding a block that needs many field IDs at once, or to look up dropdown option UUIDs needed for write payloads. **When working with an AI assistant without the MCP installed**, paste this JSON response into the chat -- second-best way to share accurate field IDs and dropdown UUIDs in one shot.
 
-3. **Inline in Studio (one field at a time)** -- in the Data tab, click a field's name to open its edit drawer. The field ID appears next to the "Field name" label (e.g. `ID: 37fts`). Fastest for spot-checking a single field.
+4. **Inline in Studio (one field at a time)** -- in the Data tab, click a field's name to open its edit drawer. The field ID appears next to the "Field name" label (e.g. `ID: 37fts`). Fastest for spot-checking a single field.
 
-4. **Softr Database REST API with `fieldNames=true`** -- runtime inspection from inside a Vibe Coding block (internal-portal blocks only, since this exposes a PAT in client code):
+5. **Softr Database REST API with `fieldNames=true`** -- runtime inspection from inside a Vibe Coding block (internal-portal blocks only, since this exposes a PAT in client code):
 
 ```jsx
 import { useEffect, useState } from "react";

package/datasources/softr-database.md

@@ -24,11 +24,62 @@ q.select({ name: "First Name" })
 Find field IDs in this order of preference:
 
 1. **Softr Database MCP** (recommended when working with an AI assistant) — the AI calls schema/list-fields tools directly. See [../references/softr-database-mcp.md](../references/softr-database-mcp.md).
-2. **Network inspector** — DevTools -> Network -> filter `tablespace-with-tables` for the full schema including dropdown option UUIDs. Paste the JSON into chat to share with an AI when the MCP isn't installed.
-3. **Inline in Studio** — click a field's name in the Data tab; the ID appears in the field-edit drawer.
+2. **`get-softr-database` CLI script (bundled)** — a Python CLI bundled with this skill at `~/.claude/skills/softr-vibe-coding/tools/get-softr-database.py`. Exports the full schema (every table, field, dropdown option UUID) to `~/Desktop/softr-database-<id>-<timestamp>.json`. Stdlib only, no `pip install`. See [Bundled CLI script](#bundled-cli-script-get-softr-database) below.
+3. **Network inspector** — DevTools -> Network -> filter `tablespace-with-tables` for the full schema including dropdown option UUIDs. Paste the JSON into chat to share with an AI when the MCP isn't installed.
+4. **Inline in Studio** — click a field's name in the Data tab; the ID appears in the field-edit drawer.
 
 The generic Field Inspector pattern with empty `q.select({})` does NOT work for Softr Database — see [fields.md](fields.md#field-inspector-block).
 
+## Bundled CLI script: `get-softr-database`
+
+A Python CLI bundled with this skill that exports a complete Softr Tables database schema (every table, every field, all dropdown option UUIDs) to a timestamped JSON file on your Desktop. Stdlib only — no `pip install` required.
+
+**Script location after `npx softr-vibe-coding@latest init`:**
+
+```
+~/.claude/skills/softr-vibe-coding/tools/get-softr-database.py
+```
+
+**Run it directly:**
+
+```bash
+python3 ~/.claude/skills/softr-vibe-coding/tools/get-softr-database.py <database_id>
+```
+
+It prompts for your Softr API key (input hidden via `getpass`). To skip the prompt entirely, pass via env var:
+
+```bash
+SOFTR_API_KEY=xxx python3 ~/.claude/skills/softr-vibe-coding/tools/get-softr-database.py <database_id>
+```
+
+Run with no args to be prompted for both the database ID and API key.
+
+**Output:** `~/Desktop/softr-database-<databaseId>-<YYYYMMDD-HHMMSS>.json` containing:
+
+```json
+{
+  "exportedAt": "...",
+  "source": "https://tables-api.softr.io/api/v1",
+  "databaseId": "...",
+  "database": { /* full database metadata */ },
+  "tableCount": N,
+  "fieldCount": M,
+  "tables": [ /* every table with its full fields[] array */ ]
+}
+```
+
+**Optional alias** for a shorter command. Add to your `~/.zshrc` or `~/.bashrc`:
+
+```bash
+alias get-softr-database='python3 ~/.claude/skills/softr-vibe-coding/tools/get-softr-database.py'
+```
+
+After `source ~/.zshrc`, just run `get-softr-database <database_id>` from anywhere.
+
+**Get your Softr API key:** Softr workspace settings → API keys → create a new key with read access to the target database.
+
+**When to use vs the MCP:** the MCP server is better for AI-assisted workflows (the assistant calls schema tools directly without any user action). This CLI script is better when you want a portable JSON file — for sharing in chat, archiving alongside your project, diffing across schema versions, or pasting a single big blob into Claude. The two approaches don't conflict; many projects use both.
+
 ## Supported Fields
 
 | Field Type     | Writable | Notes |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "softr-vibe-coding",
-  "version": "1.7.0",
+  "version": "1.9.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"
@@ -11,6 +11,7 @@
     "ui-ux-guidelines.md",
     "references/",
     "datasources/",
+    "tools/",
     "LICENSE",
     "README.md",
     "CHANGELOG.md"

package/references/anti-patterns.md

@@ -65,6 +65,7 @@ Run through this catalog before delivering any block. Every row is a violation o
 | 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). |
 | Softr nav dropdown panel shows a tall blank gap below the items, and `height: auto` won't shrink it | The items sit in a CSS grid Softr sets to `grid-auto-flow: column` with pre-sized empty row tracks (`grid-template-rows: 60px 60px…`). Override the flow on `.softr-topbar [role="menu"] [role="group"]`: `grid-auto-flow: row !important; grid-template-rows: none !important; grid-auto-rows: auto !important` (leave `grid-template-columns` to preserve the menu width). Verified June 2026. See [native-chrome-styling.md](native-chrome-styling.md). |
+| Setting the page background on `body` (or any single element) — it appears to do nothing | Softr paints the SAME page fill on `html`, `body`, `#page-content`, AND a deeper class-less wrapper div, stacked — so styling one gets covered. Paint your backdrop on `html`, then clear the duplicates above it: `body`, `#page-content`, and `#page-content div` — but EXCLUDE the header subtree with `:not(.softr-topbar):not(.softr-topbar *)` (it renders inside `#page-content`, and `#page-content`'s id specificity would otherwise flatten the dropdown panel). Verified June 2026. See [native-chrome-styling.md](native-chrome-styling.md). |
 
 ## Permissions
 

package/references/native-chrome-styling.md

@@ -1,6 +1,8 @@
-# Styling Softr's Native Chrome (Header / Top Bar / Nav / Dropdowns)
+# Styling Softr's Native Shell (Header · Footer · Page Background) via Custom Code
 
-**This is NOT about Vibe Coding blocks.** Softr's top bar, navigation, and its dropdown menus are *native chrome* — configured in Softr Studio and rendered in the **main document**, not inside a block's shadow DOM. You **cannot** build or replace the global header 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 bar 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 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 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.
 
 > **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.)
 
@@ -100,9 +102,115 @@ Center each item's text and drop the empty description slot Softr reserves:
 .softr-topbar [role="menu"] [role="menuitem"] div:empty { display: none !important; }
 ```
 
+## Floating "island" header
+
+To turn a full-bleed bar into a floating, rounded "island" (inset from the edges): make the sticky root + Softr's Studio wrappers transparent so only the bar paints, then constrain + round + shadow the bar itself.
+
+```css
+/* The sticky root and its Studio wrappers paint full-width — clear them so only the
+   bar shows, floating over the page. */
+#topbar-root,
+#topbar-root > div,
+#topbar-root > div > div { background: transparent !important; }
+
+#topbar-root { padding: 24px 16px 0 !important; }   /* gap above + at the sides */
+
+.softr-topbar {
+  max-width: 1200px !important;
+  margin: 0 auto !important;          /* center the island */
+  border-radius: 22px !important;
+  box-shadow: 0 12px 30px rgba(0, 0, 0, 0.28) !important;
+}
+
+/* Optional: group the nav cluster toward the right-of-center */
+.softr-topbar [role="menubar"] { justify-content: flex-end !important; }
+```
+
+## Footer
+
+**The native footer has NO `softr-*` class — only `f8f11e5_*` hashes.** Target the semantic **`<footer>`** element instead. Safe: Vibe Coding blocks are shadow-DOM isolated, so `footer { … }` reaches only Softr's native footer, never a block.
+
+```css
+footer {
+  max-width: 1200px !important;
+  margin: 24px auto !important;            /* inset → elevated "island" card */
+  border-radius: 22px !important;
+  background-color: #02006C !important;    /* e.g. navy, to match a navy header island */
+  color: #FFFFFF !important;
+  box-shadow: 0 14px 34px rgba(0, 0, 0, 0.18) !important;
+}
+footer * { color: inherit !important; }    /* recolor all footer text/links white in one shot */
+```
+
+**Footer contact column wraps the email mid-word.** Softr pins that column to a fixed `width: 160px` with `overflow-wrap: break-word`, so a long email splits across lines. Fix by no-wrapping the links (target by their stable `tel:` / `mailto:` href) and letting the column grow to content:
+
+```css
+footer a[href^="tel:"],
+footer a[href^="mailto:"] { white-space: nowrap !important; }
+footer [role="list"],
+footer [role="list"] > div,
+footer [role="list"] > div > div {
+  width: auto !important;
+  min-width: max-content !important;
+  max-width: none !important;
+}
+```
+
+## 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."
+
+**Pattern: 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:
+      soft glow + faint dot-grid + base gradient. background-image order = top→bottom. */
+html {
+  background-color: #F0F3FC !important;   /* fallback base */
+  background-image:
+    radial-gradient(75rem 42rem at 50% -12%, rgba(155, 35, 208, 0.08), transparent 60%),  /* glow */
+    radial-gradient(rgba(2, 0, 108, 0.045) 1px, transparent 1.6px),                        /* dot-grid */
+    linear-gradient(180deg, #E7EAFB 0%, #F2F4FD 45%, #FAFBFF 100%) !important;             /* gradient */
+  background-size: 100% 100%, 24px 24px, 100% 100% !important;
+  background-repeat: no-repeat, repeat, no-repeat !important;
+  background-attachment: fixed !important;   /* calm while content scrolls */
+}
+
+/* 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. */
+body,
+#page-content { background-color: transparent !important; background-image: none !important; }
+#page-content div:not(.softr-topbar):not(.softr-topbar *) {
+  background-color: transparent !important;
+  background-image: none !important;
+}
+```
+
+**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.)
+
 ## Finding the element to target
 
-DevTools can't right-click a menu that closes on blur. Freeze it: in the Console run `setTimeout(function () { debugger; }, 4000)`, open the menu within 4s, then — paused — element-pick the panel and read the **Computed** tab to see which element holds a fixed `height` / `grid-template-rows`. Resume with the ▶ button. ("Emulate a focused page" in the Elements `:hov` menu is a lighter alternative for blur-close menus.)
+**Transient menus** (close on blur) — DevTools can't right-click them. Freeze: in the Console run `setTimeout(function () { debugger; }, 4000)`, open the menu within 4s, then — paused — element-pick the panel and read the **Computed** tab. Resume with the ▶ button. ("Emulate a focused page" in the Elements `:hov` menu is a lighter alternative.)
+
+**Which element paints a background** — the element-picker keeps grabbing a *transparent* overlay sitting on top, so scan instead. Paste this in the Console; it lists `html`, `body`, and every large element with a real background color (tag / id / class / color / size), so you can spot the actual painter and its stable hook:
+
+```js
+(function () {
+  var hits = [];
+  var all = document.querySelectorAll('html, body, body *');
+  for (var i = 0; i < all.length; i++) {
+    var el = all[i], bg = getComputedStyle(el).backgroundColor, r = el.getBoundingClientRect();
+    if (bg !== 'rgba(0, 0, 0, 0)' && bg !== 'transparent' &&
+        (el === document.documentElement || el === document.body || (r.width > 1200 && r.height > 400))) {
+      hits.push({ tag: el.tagName.toLowerCase(), id: el.id || '',
+        cls: (typeof el.className === 'string' ? el.className : ''),
+        bg: bg, size: Math.round(r.width) + 'x' + Math.round(r.height) });
+    }
+  }
+  console.table(hits);
+})();
+```
 
 ## Restyle vs. replace
 

package/tools/get-softr-database.py

@@ -0,0 +1,145 @@
+#!/usr/bin/env python3
+"""
+get-softr-database
+==================
+Export a full Softr Tables database **schema** (every table, every field, and all
+of their details) to a timestamped JSON file on your Desktop.
+
+What it does
+------------
+Given a Softr API key and a database ID, it calls two endpoints:
+
+    GET /api/v1/databases/{id}           -> database metadata
+    GET /api/v1/databases/{id}/tables    -> all tables, each with its full
+                                            `fields` array (type, options,
+                                            choices, formulas, AI settings, ...)
+
+and writes the combined result to:
+
+    ~/Desktop/softr-database-<databaseId>-<YYYYMMDD-HHMMSS>.json
+
+Usage
+-----
+    get-softr-database                      # prompts for DB ID, then API key (hidden)
+    get-softr-database <database_id>        # prompts only for the API key
+    SOFTR_API_KEY=xxx get-softr-database <database_id>   # fully non-interactive
+
+The API key may also be supplied via the SOFTR_API_KEY environment variable, so
+it never has to be typed (or stored) in plain text.
+
+Only the Python standard library is used — no `pip install` required.
+"""
+
+import os
+import sys
+import json
+import getpass
+import datetime
+import urllib.request
+import urllib.error
+
+API_BASE = "https://tables-api.softr.io/api/v1"
+TIMEOUT_SECONDS = 60
+
+
+def api_get(path, api_key):
+    """GET a Softr Tables API path and return the parsed JSON body."""
+    req = urllib.request.Request(
+        API_BASE + path,
+        headers={
+            "Softr-Api-Key": api_key,
+            "Content-Type": "application/json",
+        },
+        method="GET",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=TIMEOUT_SECONDS) as resp:
+            return json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as e:
+        body = e.read().decode("utf-8", "replace")
+        hint = ""
+        if e.code in (401, 403):
+            hint = "\n  (Check that the API key is correct and has access to this database.)"
+        elif e.code == 404:
+            hint = "\n  (Check that the database ID is correct.)"
+        raise SystemExit(f"\n[x] HTTP {e.code} on GET {path}\n  {body}{hint}")
+    except urllib.error.URLError as e:
+        raise SystemExit(f"\n[x] Network error on GET {path}: {e.reason}")
+    except json.JSONDecodeError:
+        raise SystemExit(f"\n[x] Could not parse JSON response from GET {path}")
+
+
+def prompt_database_id():
+    if len(sys.argv) > 1 and sys.argv[1].strip():
+        return sys.argv[1].strip()
+    try:
+        value = input("Softr database ID: ").strip()
+    except (EOFError, KeyboardInterrupt):
+        raise SystemExit("\n[x] Cancelled.")
+    if not value:
+        raise SystemExit("[x] No database ID provided.")
+    return value
+
+
+def prompt_api_key():
+    value = os.environ.get("SOFTR_API_KEY", "").strip()
+    if value:
+        return value
+    try:
+        value = getpass.getpass("Softr API key (input hidden): ").strip()
+    except (EOFError, KeyboardInterrupt):
+        raise SystemExit("\n[x] Cancelled.")
+    if not value:
+        raise SystemExit("[x] No API key provided.")
+    return value
+
+
+def output_dir():
+    desktop = os.path.join(os.path.expanduser("~"), "Desktop")
+    return desktop if os.path.isdir(desktop) else os.path.expanduser("~")
+
+
+def main():
+    database_id = prompt_database_id()
+    api_key = prompt_api_key()
+
+    print(f"\n-> Fetching database {database_id} ...")
+    db = api_get(f"/databases/{database_id}", api_key).get("data", {}) or {}
+    print(f"   Database: {db.get('name', '(unknown)')}  "
+          f"({db.get('tablesCount', '?')} tables reported)")
+
+    print("-> Fetching tables and fields ...")
+    tables = api_get(f"/databases/{database_id}/tables", api_key).get("data", []) or []
+    total_fields = sum(len(t.get("fields", []) or []) for t in tables)
+    print(f"   Retrieved {len(tables)} tables, {total_fields} fields total.")
+
+    now = datetime.datetime.now()
+    payload = {
+        "exportedAt": now.isoformat(timespec="seconds"),
+        "source": API_BASE,
+        "databaseId": database_id,
+        "database": db,
+        "tableCount": len(tables),
+        "fieldCount": total_fields,
+        "tables": tables,
+    }
+
+    stamp = now.strftime("%Y%m%d-%H%M%S")
+    filename = f"softr-database-{database_id}-{stamp}.json"
+    path = os.path.join(output_dir(), filename)
+
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(payload, f, indent=2, ensure_ascii=False)
+
+    print(f"\n[ok] Saved schema to:\n     {path}")
+
+    # Brief per-table summary so the result is readable at a glance.
+    if tables:
+        print("\n     Tables:")
+        for t in tables:
+            print(f"       - {t.get('name', '(unnamed)')}: "
+                  f"{len(t.get('fields', []) or [])} fields")
+
+
+if __name__ == "__main__":
+    main()