softr-vibe-coding 2.4.2 → 2.5.0

package/CHANGELOG.md

@@ -4,6 +4,9 @@ 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.
 
+## [2.5.0] - 2026-09-09
+- Cross-block and cross-page consistency: the failure mode where every block looks correct alone
+
 ## [2.4.2] - 2026-09-01
 - softr-mcp.md: Workflows build/publish loop verified end to end 2026-09-01 (10 production workflows built live via MCP), replacing the not-yet-exercised hedge with build-loop findings: create_workflow instantiates an OLD trigger node version — immediately replace_trigger_node with the same type for current inputs (updateField on SOFTR_TABLES_RECORD_UPDATED only exists at v1.2.0); FILTER conditions set via update_node_inputs inputName "condition" ({operator, conditions} object stored on the outgoing path like the builder); LOOP_ACTION_GROUP loopVariables.items must be a plain array like $.records — [*] projections rejected by the validator, per-item refs inside the loop via {loopActionGroup.<id>:::loopVariables.items.fields.<fieldId>} (bracket form for digit-leading ids); update_node_inputs batches validate against STORED node state so dependent updates split into sequential calls; test-safety doctrine — record-write nodes REAL_ONLY (never test against production), SOFTR_SEND_EMAIL always mode:"mock", triggers/GET_RECORDS REAL_ONLY but read-only-safe. Plus: workspace update_field on SELECT silently drops added choices (echoes old set, no error) — add choices in Studio or let allowToAddNewChoice auto-create on first unknown-label write; joins the allowMultipleEntries silent-ignore
 

package/README.md

@@ -291,7 +291,8 @@ The skill enforces these automatically, but good to know (verified live against
 - Create payloads are **flat**; update payloads are `{ recordId, fields: {...} }` — asymmetric by design
 - `mutateAsync` is fully supported — it's the tool for sequential multi-row saves
 - SELECT fields write by option **label string**; linked records write as arrays of record-id strings
-- Every code recompile resets the block's auto-registered Actions to default permissions — tighten permissions after the last redeploy
+- Every code recompile resets the block's auto-registered Actions to default permissions — tighten permissions after the last redeploy, and note there is **no cosmetic-edit exemption**: an edit that changes only a comment resets them too
+- **Blocks cannot import each other**, so two blocks that must look alike will drift — each one looks correct in isolation while the set does not. Repeated page chrome (back button, title, primary action) must sit at the same offset on every page, and a loading skeleton must track the REST state of whatever it stands in for
 - No `import React from 'react'` — use named imports (`import { useState } from "react"`)
 - Must use `export default function Block()`
 - Wrap layout in `<div className="container py-0"><div className="content">` for app/content blocks (house convention for width alignment with native blocks) — the platform default is actually full width, so full-bleed marketing blocks (heroes, banners, footers) legitimately omit the wrappers and own their gutters

package/SKILL.md

@@ -222,6 +222,25 @@ Blocks rarely live alone — most Softr pages stack 2–4 blocks vertically, oft
 1. **"Should the detail page have a back button?"** — if yes, always wire one. Use the back-navigation pattern in [references/helper-blocks.md](references/helper-blocks.md#breadcrumb--back-navigation): `window.history.back()` for users with history, plus a fallback URL for users who arrived via shared link.
 2. **"What page should the back button fall back to when there's no history?"** — this is a separate question, easy to skip but important. Don't default silently; ask. If the user doesn't have a listing page yet, default to `/` and leave a `// TODO: update fallback when /jobs (or similar) exists` comment so it can be updated later.
 
+**Chrome that repeats across pages must land in the SAME place on every page [house].** A back button,
+a page title, a primary action -- anything the user meets on more than one screen -- is a cross-page
+contract, not a per-block decision. Before adding one, open the blocks that already have it and copy
+the exact offset; when you change it, change it everywhere in the same edit. Verified the hard way
+2026-09-09: an item-detail back button carried an extra `mt-6` that the project-header back button did
+not, so it sat 24px lower, and the mismatch only surfaced when a user moved between the two pages in
+one session. **No amount of reading a single block reveals this** -- each block looks correct alone,
+which is exactly why it needs to be a standing rule rather than a review item.
+
+Two habits make it survive:
+
+- **Let the wrapper's padding be the ONLY thing positioning repeated chrome.** Give the back button
+  `mb-4` (space below it) and no top margin, so its offset is the wrapper's top padding and nothing
+  else. One number per page then governs the position, and pages can only drift if their wrappers do.
+- **Loading skeletons repeat the chrome too.** A skeleton standing in for a page that has a back button
+  needs that button's placeholder at the same offset as the real one, or the button visibly jumps the
+  moment the record arrives. Change both in the same edit -- see §12 of
+  [ui-ux-guidelines.md](ui-ux-guidelines.md).
+
 **Persist the answer as a grep-able comment at the top of the generated file** so future edits know the spacing assumptions and can be updated consistently:
 
 ```jsx
@@ -323,6 +342,16 @@ Adjust the top gradient color to complement the user's brand.
 
 **Arbitrary values compile in full** — the platform's Tailwind build is JIT, so the whole arbitrary-value syntax works, including opacity modifiers on arbitrary hex (`bg-[#FAF5EC]/85`), variant + arbitrary + opacity combined (`hover:bg-[#6E7A5C]/10`), negative arbitrary values (`-top-[22%]`, `hover:-translate-y-[1px]`), arbitrary object-position (`object-[62%_25%]`), arbitrary z (`z-[1]`), and vw sizing (verified 2026-08-31 from rendering Studio-AI output). Classes must be **static source strings** — never template-interpolate (`` bg-[${x}] ``); JIT extracts classes by static scan (standard-Tailwind inference, not Softr-verified). When to reach for them vs. the scale: see the editorial lane in [ui-ux-guidelines.md](ui-ux-guidelines.md) §7. (This covers arbitrary *values* and standard variants; arbitrary *selector* variants like `[&_svg]:` have at least one known bundler failure — see the SelectTrigger row in [references/anti-patterns.md](references/anti-patterns.md#layout--styling).)
 
+**A brand colour you use BOTH ways exists twice, and the two copies drift silently.** Arbitrary values
+are resolved at build time, so a class string can never read your `C.accent` constant. A card styled
+with Tailwind (`border-[#3B1F2B] hover:border-[#54594F]`) and its loading skeleton styled inline
+(`style={{ border: "1px solid " + C.accent }}`) therefore hold the same colour in two places that no
+compiler will ever reconcile, and nothing fails when they disagree -- it just looks wrong. Verified
+2026-09-09: a card's rest border was changed and its skeleton's was not, so the whole grid visibly
+re-outlined itself the instant the data arrived. Two habits keep it honest: write the hex-to-token
+mapping in a comment beside the class string (`#3B1F2B = C.accent`), and prefer the runtime token
+wherever inline `style` is already in play, so only one of the two copies is ever a literal.
+
 **Font classes:** `font-heading`, `font-sans`, `font-mono`
 
 **Conditional classNames:** `import { cn } from "@/lib/utils";` — template-literal conditionals (`` className={`base ${cond ? "a" : "b"}`} ``) are equally valid (Studio AI emits them); prefer `cn()` when merging many groups or de-duplicating conflicting classes.
@@ -517,6 +546,21 @@ Non-negotiable rules. Most are enforced by the Softr platform (compiler, validat
     auto-registered Actions to **default permissions**. Do the Actions-tab permission tightening pass
     only after the LAST redeploy, and re-check it after any future one. Verified live 2026-08-25
     across a 15-block deployment. See [datasources/writing.md](datasources/writing.md#how-actions-work-studios-actions-tab).
+    **Any save counts, including one whose only change is a comment** -- there is no "cosmetic edit"
+    exemption; a `search_replace` that rewrites nothing but a code comment rebuilds the Actions exactly
+    like a full rewrite does (verified live 2026-09-09, on two blocks at once). Re-check permissions
+    after EVERY push.
+22. **Blocks cannot import each other -- cross-block consistency is discipline, not architecture [house]**
+    -- Every block compiles standalone. There is no shared module, no design-system import, nothing that
+    makes two blocks stay alike. Two blocks that must look the same WILL drift, and the drift usually
+    hides in the *mechanism* rather than the value: verified 2026-09-09, a report card and a saved-list
+    card that were supposed to be identical had ended up hovering by two different mechanisms (Tailwind
+    `hover:` variants on one, React `useState` on the other), so a change to either could never reach
+    the other. Neither block looked wrong on its own -- that is the whole problem. When a treatment is
+    deliberately shared across blocks: name it in a comment in BOTH files, list the exact tokens that
+    are shared, and promise nothing beyond them (the class strings usually differ in layout and padding,
+    and do not need to match). The same rule governs repeated page chrome -- see **Block Placement &
+    Page Spacing**.
 
 ## Style Conventions
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "softr-vibe-coding",
-  "version": "2.4.2",
+  "version": "2.5.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

@@ -38,6 +38,7 @@ Run through this catalog before delivering any block. Every row is a violation o
 | Wrapping a `useRecordCreate` payload in `{ fields: {...} }` (copied from an update call) | Create payloads are **FLAT** — `createRecord.mutate({ name: "Jane" })`. Only update payloads nest: `{ recordId, fields: {...} }`. The asymmetry is by design (verified 2026-08-25) |
 | Passing a data hook's options through a variable or wrapper function: `useRecords(buildOpts())` | **Fails to compile** — the options object must be an inline literal at the call site (verified live 2026-08-25; hit in production, fixed by making the wrapper take the hook's *result* instead). Share `q.select` mappings between hooks, never whole options objects |
 | Tightening Actions-tab permissions before the block's final redeploy | Every code recompile **resets the auto-registered Actions to default permissions** (verified live 2026-08-25). Tighten permissions after the LAST redeploy, and re-check after any future one |
+| Assuming a comment-only edit is "safe" and leaves Action permissions alone | There is no cosmetic-edit exemption. Any save recompiles, and every recompile rebuilds the Actions at default visibility — a `search_replace` changing nothing but a code comment resets them exactly like a rewrite (verified live 2026-09-09, on two blocks at once). Re-check after EVERY push, including cosmetic ones |
 | Treating Studio's Actions tab as a separately-managed configuration to keep in sync with code | Actions auto-derive from your `useRecordCreate`/`useRecordUpdate`/`useRecordDelete` + `q.select` on every save. The Actions tab is a read-only inspector; there is no manual delete control. To change an Action, change the code |
 | One alias in a write-side `q.select` referencing a renamed / non-existent Airtable column | Softr's Action parser silently rejects the **entire** create/update Action — not just the bad alias. Symptoms: Studio's Actions tab shows "No actions used in this block yet", `createRecord.enabled` / `updateRecord.enabled` stays `false`, `.mutate()` calls dispatch but resolve immediately to "not yet ready". Every OTHER field in the same `q.select()` is also lost, even the ones that map cleanly. Diagnostic: bisect the `q.select` — strip down to a known-good minimal set, confirm the Action appears in Studio, then add fields back in halves until it drops out. The culprit is in the last half added. Once narrowed to a single field, grep its name against the freshest Airtable schema export to catch the rename / trailing-space / case-mismatch. Verified 2026-05-21: a `"Photos"` column on Wigs was renamed to `"Before Photos"`, the helper that wrote `photos: "Photos"` had its entire Action disabled even though 11 other fields in the same `q.select` were fine. See [datasources/airtable.md](../datasources/airtable.md#maintainability-gotcha) |
 
@@ -66,6 +67,9 @@ Run through this catalog before delivering any block. Every row is a violation o
 | Hardcoded domain in navigation | Relative paths: `/task-details?recordId=...` |
 | Placing a `<NavigationAction navigation={{ action: "OPEN_CHAT" }}>` Ask-AI button on a block that has no data source connected | Connect the block to the data source the AI should read from in Studio's Source tab. Softr's AI pulls context from the **block that triggered the chat**, not from the page — a button-only helper block with no data source causes `chat/prepare` → HTTP 500 ("Failed to prepare AI assistant") even though the chat UI opens fine. The block doesn't need to read or write records itself; the connection is purely for AI context. Verified by direct experiment, May 2026 |
 | Emojis in UI | lucide-react icons only |
+| Positioning repeated page chrome (back button, title, primary action) per-block, without checking the pages that already have it | Chrome the user meets on more than one screen is a cross-page contract. Copy the exact offset from the blocks that already ship it, and change every page in one edit. Let the wrapper's padding be the only thing positioning it — `mb-4` and NO top margin on a back button — so one number per page governs it. Verified 2026-09-09: an extra `mt-6` sat one detail page's back button 24px lower than another's, and **each block looked correct in isolation**. See SKILL.md's Block Placement section |
+| A loading skeleton carrying a different border / offset from the component it stands in for | The skeleton must track the component's REST state (border colour, padding, chrome offsets), never its hover state. If they disagree the layout visibly re-draws the instant data lands — the exact thing a skeleton exists to prevent. Verified 2026-09-09 twice in one session: a card grid re-outlined itself on load, and a back button jumped 24px. See [ui-ux-guidelines.md](../ui-ux-guidelines.md) §12 |
+| `focus-visible:` on a card or row that only *contains* buttons | The container is a plain `<div>` and never takes focus, so it is dead CSS. Use `focus-within:` on the container (pairs with its `hover:` treatment) and keep `focus-visible:ring-2` on the button/link itself |
 | `[&_svg]:opacity-0` on SelectTrigger | `<style>` + `data-fix-chevron` attribute (Softr bundler limitation) |
 | Relying on `custom-code-header.html` (Softr → Settings → Custom Code → Code inside header) to apply brand fonts/colors INSIDE a Vibe Coding block | Vibe Coding blocks render inside a shadow DOM. CSS custom properties (`--brand-*`) pierce that boundary, but `html, body { font-family: ... !important }` rules **do not** — `<html>` and `<body>` don't exist inside the shadow root. Apply brand fonts/colors at the block's **own outermost wrapper** via inline style: `style={{ fontFamily: "'Manrope', system-ui, sans-serif", color: BRAND_INK }}` on the outer `<div>` so every descendant inherits brand defaults. Override per-element with explicit inline `fontFamily` (e.g., `"'Fraunces', Georgia, serif"` on h1/h2). Google `<link>` tags in the page head DO load `@font-face` globally — the fonts are available inside shadow DOM, they just need to be applied. |
 | Painting `backgroundColor: BRAND_CANVAS` on a Vibe Coding block's outer wrapper when `custom-code-header.html` already sets `body { background-color: var(--brand-canvas) !important }` | Don't double-paint. If the body bg is already the brand canvas, the block leaves its own backgroundColor unset and the page bg shows through. Painting the same color twice produces a visible seam — Softr's content wrapper sits between `<body>` and the Vibe Coding block, and the two backgrounds composite slightly differently due to sub-pixel rendering, transparency stacking, or wrapper paddings. Set fontFamily and color on the block's wrapper (those don't inherit cleanly through shadow DOM), but **leave backgroundColor unset** — let the page bg flow through. The exception: if the block needs a brand-tinted *section* (e.g., a card-style admin shell that's different from the page bg), paint that bg explicitly on its specific container, not on the outer wrapper. **Second exception — DARK brands: see the next row.** |

package/references/native-chrome-styling.md

@@ -156,6 +156,41 @@ footer [role="list"] > div > div {
 }
 ```
 
+## Relocating footer nodes, not just restyling them
+
+CSS alone cannot move an element to a **different parent**. `order` only reorders siblings, so a
+"put the Website / Terms links down on the copyright line" request — where the links and the copyright
+live in different containers — needs a small JS relocation job in the same Custom Code block, not more
+selectors.
+
+The shape that works:
+
+1. Build one flex row, insert it where the copyright currently sits.
+2. Move the copyright node into it, then the link nodes after it.
+3. Hide the container the links vacated **only if it is now genuinely empty** — check for remaining
+   element children rather than assuming, or you will blank a container that still holds something.
+4. Run it BEFORE any job that measures height (a footer-compacting pass, a sticky offset calculation);
+   those must see the final arrangement or they measure the old one.
+
+```js
+/* relocate, then compact — order matters: compactFooter() measures height */
+relocateFooterLinks();
+compactFooter();
+```
+
+Two details worth copying:
+
+- **Truncate rather than wrap.** A relocated row should ellipsise under width pressure
+  (`min-width:0` on the flex children plus `text-overflow:ellipsis`), never stack — a footer row that
+  reflows to two lines at an awkward width looks broken in a way a clipped label does not.
+- **Scope hover underlines away from logos and icons.** An `::after` underline scaled from
+  `transform-origin:50%` gives a centre-out grow; gate it with `:not(:has(svg)):not(:has(img))` so it
+  never appears under the logo or the social glyphs, and use `currentColor` so the footer's own colour
+  rules keep working untouched.
+
+Same caveat as everything else here: **it renders on the published app only.** The Studio editor keeps
+showing the old arrangement, which reads exactly like "the script did not run."
+
 ## 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."

package/references/softr-mcp.md

@@ -83,6 +83,33 @@ Before writing any block code through the MCP, call `get_vibe_coding_docs` — i
 
 Editable settings via MCP are the same fields as the block's **Content → Settings** panel; sort and record filters are the same as the **Source** tab. Duplicating from a version is the safe way to try an alternative — the original keeps working while you experiment on the copy.
 
+### Which edit tool: full replace vs. targeted search-replace
+
+`update_vibe_coding_block_code` sends the whole file; `update_vibe_coding_block_code_search_replace`
+sends only the fragments that change. This is not just a bandwidth choice — it changes what can go wrong.
+
+**Reach for search-replace when ONE source file is deployed to SEVERAL blocks.** Datasource UUIDs are
+per BLOCK, not per table, so a file living on two pages needs a different `datasource.define()` pair in
+each. A full replace overwrites that pair and forces a manual swap on every single push — the classic
+way to point a project page at the company page's data. Targeted replacements never touch lines you did
+not name, so **each block keeps its own pair and the swap step disappears entirely** (verified
+2026-09-09 across a report block deployed to two pages). It is also the safer option on large files:
+retransmitting ~100KB verbatim to change one class string is its own corruption risk.
+
+**Reach for the full replace when the change is structural** — reordering JSX, moving logic between
+components, adding a hook — where being sure of "the exact current text" of a dozen scattered fragments
+is harder than being sure of the whole file. Also use it when the local file is the source of truth and
+has drifted from the deployed block in ways you have not enumerated.
+
+**Caveat on the `operations` argument.** It is an array of `{search, replace}` objects. Some MCP clients
+serialize it as a JSON *string* instead, and the API rejects that with a Jackson error — `Cannot
+deserialize value of type java.util.ArrayList<java.util.Map<String,String>> from String value` (hit
+2026-09-09, mid-session, on a tool that had accepted the same shape minutes earlier). It is a client
+serialization quirk, not a bad request: if it will not take the array, fall back to the full replace
+rather than mangling the edit to fit.
+
+Both paths recompile, so both reset Action permissions either way (Hard Constraint 21).
+
 ## Adopting Studio-AI-generated code
 
 When you pull a Studio-AI-generated block via `get_vibe_coding_block_code` to adopt into a project repo as source of truth: its output renders fine but ships with predictable defects. **Functional patterns in Studio output are platform-support evidence** (it surfaces undocumented capabilities before the docs do — see SKILL.md's "Platform truth sources"); **its code hygiene is not a pattern to imitate.** Cleanup pass before committing:

package/ui-ux-guidelines.md

@@ -390,6 +390,15 @@ Vestibular disorders affect ~35% of adults over 40. Always respect `prefers-redu
 - Use `<Skeleton />` from shadcn/ui matching the final layout shape.
 - Pulsing animation is included by default.
 - Replace content progressively as data arrives.
+- **Match the component's REST state, not just its shape.** A skeleton stands in for a real card, so it
+  must carry that card's *resting* border, background and padding -- not its hover state, and not a
+  different border "because it is only a placeholder". When the two disagree the grid visibly re-draws
+  itself the instant data lands, which is the one thing a skeleton exists to prevent (observed live
+  2026-09-09: skeletons left on the old border colour after the cards moved to a new one).
+- **When an interactive element's resting style changes, change its skeleton in the same edit.** Nothing
+  links them -- in a Tailwind + inline-token codebase the colour is literally written twice.
+- **Skeletons repeat page chrome too.** If the page has a back button, breadcrumb or title above the
+  content, the skeleton needs those at the SAME offsets, or the chrome jumps when the record arrives.
 
 ### Perceived Performance:
 - **Optimistic UI**: Update the interface immediately, handle failures gracefully. Use for low-stakes actions (likes, filters); avoid for payments or destructive operations.
@@ -550,6 +559,7 @@ Avoid the "hero metric layout template" — big number, small label, supporting
 - **Landmark hygiene when a block ships page chrome**: shadow DOM does NOT hide landmarks from assistive tech, and Softr's native chrome uses semantic elements — so a block's own `<header>`/`<main>` on a page with native chrome creates duplicate banner/main landmarks. Use plain `<div>`s there; reserve `<header>`/`<main>` for pages where the native chrome is hidden.
 - Semantic HTML: `<button>` for actions, `<a>` for navigation, `<input>` for data.
 - **Focus rings:** Never `outline: none` without replacement. Always keep `focus-visible:ring-2`. Focus ring must be 2-3px thick, high contrast, offset from the element.
+- **`focus-within:` for containers, `focus-visible:` for the focusable element itself.** A card or row that *holds* buttons is usually a plain `<div>` and never takes focus, so `focus-visible:` on it is dead CSS that reads like an accessibility feature and does nothing. Use `focus-within:` there, so tabbing to a control inside the card lights the same affordance a mouse user gets from `hover:` -- and keep `focus-visible:ring-2` on the button or link itself. Whenever a card has a `hover:` treatment and contains tab stops, it wants the matching `focus-within:` variant.
 - Tables: proper `<thead>`, `<tbody>`, `<th scope="col">`.
 
 ---
@@ -699,6 +709,9 @@ Actively check for and reject these fingerprints of generic AI-generated interfa
 
 - **Smooth transitions:** `transition-all duration-200` on cards and rows
 - **Hover states on rows/cards:** `hover:bg-muted/50` for interactivity indication
+- **Rest and hover compete for the same colour, and the RESTING state wins.** If a card's resting border already uses your strongest colour, hover has nothing left to change to -- the answer is a *third* colour for hover, never demoting the resting state to free one up. A resting border is permanent and seen by everyone; a hover border exists only for whoever has a pointer on it. (Observed 2026-09-09: freeing the strong colour for hover left the cards reading as unbordered at rest.)
+- **Move hover in the same direction as the rest of the hover treatment.** If the background lightens on hover, the border should lighten too -- a border that hardens while the background softens reads as two effects fighting rather than one card lifting.
+- **Check border colours against the surface they actually sit on.** A hairline tuned for contrast *inside* a white card disappears where that card meets a coloured page ground; the same hex that reads correctly between table rows can be invisible at the card's outer edge.
 - **Auto-focus first field** when form opens (`autoFocus`)
 - **Escape to cancel** any modal, dialog, or inline edit
 - **Confirmation animation:** Brief `Check` icon in save button after success