softr-vibe-coding 2.5.1 → 2.6.0

package/CHANGELOG.md

@@ -4,6 +4,12 @@ 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.6.0] - 2026-09-09
+- Drag-to-reorder: the pattern, the shadow-DOM hit-test trap, and two affordance rules
+
+## [2.5.2] - 2026-09-09
+- Permission finding is advisory, not a veto — report severity and leave the call to the builder
+
 ## [2.5.1] - 2026-09-09
 - The Action-permission reset has a failure mode that leaves blocks publicly writable — verify, never assume
 

package/SKILL.md

@@ -555,8 +555,11 @@ Non-negotiable rules. Most are enforced by the Softr platform (compiler, validat
     can itself fail with no fallback (see the array-argument quirk in
     [references/softr-mcp.md](references/softr-mcp.md#the-array-argument-serialization-quirk-and-why-it-is-a-security-issue)).
     A push that returns `errors: null` can still have left public write access on the block.
-    **If any action is still `ALL_USERS`, do not publish** -- surface the list and have a human set it
-    in Studio.
+    **If any action is still `ALL_USERS`, report it WITH its severity and let the builder decide.**
+    Check the page's own VIEW permission first (`get_page_permissions`): a page gated to logged-in
+    users makes an open action housekeeping, a public page makes it a real hole. Surface the list
+    either way -- page, block, action type, data source -- and note that a human sets them on the
+    block's Actions tab. Do not unilaterally block a publish; it is not your app.
 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

package/package.json

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

@@ -39,7 +39,7 @@ Run through this catalog before delivering any block. Every row is a violation o
 | 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 the permission-restore call as done because you issued it | Read the permissions back with `get_vibe_coding_block_settings` and confirm each one changed. `set_vibe_coding_block_action_visibility` can fail outright on the array-argument serialization quirk, and it has **no fallback** — the default for a `genericActions` ADD_RECORD is `ALL_USERS`, so a routine push silently leaves the block publicly writable while returning `errors: null`. Verified live 2026-09-09: four ADD_RECORD actions left open across two blocks. **Do not publish** until they read `LOGGED_IN_USERS`; escalate to a human with Studio access |
+| Treating the permission-restore call as done because you issued it | Read the permissions back with `get_vibe_coding_block_settings` and confirm each one changed. `set_vibe_coding_block_action_visibility` can fail outright on the array-argument serialization quirk, and it has **no fallback** — the default for a `genericActions` ADD_RECORD is `ALL_USERS`, so a routine push silently leaves the block publicly writable while returning `errors: null`. Verified live 2026-09-09: four ADD_RECORD actions left open across two blocks. Report the list with its severity — check the page's VIEW permission with `get_page_permissions`, since a logged-in-gated page makes this housekeeping while a public page makes it a real hole — and let the builder decide whether it holds their release. A human sets them on the block's Actions tab |
 | 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) |
 
@@ -68,6 +68,7 @@ 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 |
+| `document.elementFromPoint(x, y)` to hit-test during a drag or custom pointer interaction | It returns the block's shadow **host**, not the element under the cursor — same boundary that stops `getElementById` and URL-fragment lookup. Either call it on the shadow root (`ref.current.getRootNode().elementFromPoint(x, y)`) or, better, keep refs to the candidate elements and compare `getBoundingClientRect()` yourself: rects need no shadow-root plumbing and work identically when the block is later reused elsewhere |
 | 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 |

package/references/common-patterns.md

@@ -14,6 +14,7 @@ Small reusable patterns that come up across Vibe Coding blocks but don't warrant
 - [Edge-Fade Image Mask (Editorial Hero)](#edge-fade-image-mask-editorial-hero)
 - [Decorative Background Blobs (Editorial Layering)](#decorative-background-blobs-editorial-layering)
 - [Dot-Separated Inline List](#dot-separated-inline-list)
+- [Drag-to-Reorder Rows](#drag-to-reorder-rows)
 
 ## Cross-Page State with localStorage + URL Parameters
 
@@ -292,3 +293,102 @@ Certifications, feature tags, meta rows: `GMP Manufacturing ● ISO 22716 ● Lo
 - **Keep `gap-y-*`** on the container for multi-line rhythm when the list wraps.
 - **If the list is expected to wrap often**, drop the dots and let the gap carry the rhythm — any inline separator looks orphaned at a line break.
 - `aria-hidden="true"` on the glyph — screen readers announce `●` as "black circle" otherwise.
+
+
+## Drag-to-Reorder Rows
+
+Reordering a list by dragging, written against a Softr block's constraints. Four of the five decisions
+below are non-obvious, and each one is a bug if you get it wrong.
+
+```jsx
+var [drag, setDrag] = useState(null);            // { from, over } while dragging, else null
+var [optimisticOrder, setOptimisticOrder] = useState(null);  // ids, post-drop, pre-refetch
+var rowElsRef = useRef([]);
+
+/* The pointer is CAPTURED, so no other element receives enter/leave — rects are the only
+   thing that can answer "what is under the cursor". Compare against each row's MIDPOINT so
+   the row you are over is the one that yields. */
+function dropIndex(count, clientY) {
+  for (var i = 0; i < count; i++) {
+    var el = rowElsRef.current[i];
+    if (!el) continue;
+    var r = el.getBoundingClientRect();
+    if (clientY < r.top + r.height / 2) return i;
+  }
+  return count - 1;
+}
+```
+
+The handle — never the whole row, so text selection and the row's own buttons keep working:
+
+```jsx
+<span
+  role="button"
+  aria-label={"Drag to reorder " + row.name}
+  className="touch-none select-none"          // or the browser scrolls instead of dragging
+  style={{ cursor: "grab" }}
+  onPointerDown={function (e) {
+    e.preventDefault();
+    try { e.currentTarget.setPointerCapture(e.pointerId); } catch (err) {}
+    setDrag({ from: index, over: index });
+  }}
+  onPointerMove={function (e) {
+    if (!drag) return;
+    var over = dropIndex(rows.length, e.clientY);
+    if (over !== drag.over) setDrag({ from: drag.from, over: over });
+  }}
+  onPointerUp={function () {
+    if (!drag) return;
+    var from = drag.from, to = drag.over;
+    setDrag(null);
+    if (from !== to) {
+      var next = rows.slice();
+      next.splice(to, 0, next.splice(from, 1)[0]);
+      applyOrder(next);
+    }
+  }}
+  onPointerCancel={function () { setDrag(null); }}
+>
+  <GripVertical className="h-3.5 w-3.5" />
+</span>
+```
+
+**Pointer capture, not mouse events.** Capture makes the handle the target of every move and of the up
+*wherever the pointer travels*, and obliges the browser to send `pointercancel` if it takes the pointer
+away. Without it, a drag released over another application never delivers its up and the row stays
+stuck mid-drag until a reload.
+
+**Measure rects, don't listen for `onPointerEnter` on each row.** While the pointer is captured, no
+other element gets enter/leave at all, so per-row handlers silently never fire. And
+`document.elementFromPoint` is not the escape hatch — inside a block it returns the shadow host (see
+[anti-patterns.md](anti-patterns.md#layout--styling)).
+
+**Draw the insertion line with an INSET box-shadow, never a border.** A real 2px border grows the row
+by 2px and shoves every row below it down a notch, so the list crawls under the pointer as the target
+changes:
+
+```jsx
+style={Object.assign({}, ROW_STYLE, isTarget
+  ? (drag.over < drag.from
+      ? { boxShadow: "inset 0 2px 0 0 " + ACCENT }     // landing above
+      : { boxShadow: "inset 0 -2px 0 0 " + ACCENT })   // landing below
+  : null)}
+```
+
+**Renumber the whole run — never swap a pair.** A swap cannot express "drop three rows up", and on a
+nullable order field it corrupts the sort: positions start null, so numbering only the two rows that
+moved leaves the rest null, and any "nulls last" comparator then throws every untouched row to the
+bottom the moment the user switches to that sort. Write `position = i + 1` for every row whose slot
+actually changed. The first reorder on a fresh list costs N writes; later ones cost the distance
+travelled.
+
+**Hold an optimistic order until the refetch lands.** The position writes are in flight while the
+records still carry their OLD numbers, so re-sorting on those throws the row back to where it was
+dragged from for a beat — which reads as the drag having failed. Apply `optimisticOrder` ahead of both
+sorts and clear it when the refetch resolves. Writes stay sequential (`await mutateAsync` per row, in
+order, stop on first failure — see [../datasources/writing.md](../datasources/writing.md#sequential-multi-row-writes-mutateasync));
+on failure, clear the override and refetch, because a half-applied renumber is worse than none.
+
+**Only gate the drag on permissions, not on a sort mode.** If the list has an alternative sort, let the
+drag switch to manual order rather than disabling the handle — see the disabled-control note in
+[../ui-ux-guidelines.md](../ui-ux-guidelines.md#26-finishing-touches).

package/references/softr-mcp.md

@@ -138,8 +138,29 @@ actions open across two blocks.
 3. **Read the permissions back with `get_vibe_coding_block_settings` and confirm each one actually
    changed.** A successful-looking sequence is not evidence; the failure is an argument rejection, so
    the call errors rather than lying, but an agent that batches calls can easily miss which one failed.
-4. If any action is still `ALL_USERS`, **do not publish.** Report the exact list — page, block, action
-   type, data source — and have a human set them on the block's Actions tab in Studio.
+4. If any action is still `ALL_USERS`, **report it and let the builder decide.** Check the page's own
+   VIEW permission first with `get_page_permissions`, because that is what sets the severity:
+   - **Page VIEW is gated** (e.g. `LOGGED_IN_USERS`) — an anonymous visitor cannot load the page at
+     all, so exploiting the open action means calling its endpoint directly, and the realistic worst
+     case is junk records rather than data exposure or deletion. Housekeeping: worth fixing on the
+     next Studio pass, not worth holding a release for.
+   - **Page VIEW is `ALL_USERS`** — the action permission is the only gate left. That is a genuine
+     hole and deserves to be called one.
+
+   Report page, block, action type, data source and current group; say which of the two cases applies;
+   note that a human sets them on the block's Actions tab in Studio. Then stop — **do not unilaterally
+   block the publish.** It is not your app, and the person whose app it is needs the finding and the
+   severity, not a veto.
+
+   One caveat worth stating: page visibility and action permissions are *separate* gates, and whether
+   Softr enforces page VIEW on the action endpoint itself is unverified here. The reason to treat a
+   gated page as low-severity is the practical difficulty and low blast radius, not a proof that the
+   action is unreachable. Say that plainly rather than implying the action is safe.
+
+   **Calibration matters.** This guidance read "do not publish" in v2.5.1 and immediately fired at
+   maximum severity on a logged-in-gated app where the real exposure was junk records. A warning that
+   cannot distinguish housekeeping from a breach gets tuned out, and then it is worth nothing on the
+   day it matters.
 
 Do not improvise around a rejection. `update_vibe_coding_block_settings` is not a substitute: its schema
 is equally empty, it writes far more than one permission, and guessing its payload risks clobbering the

package/ui-ux-guidelines.md

@@ -719,6 +719,8 @@ Actively check for and reject these fingerprints of generic AI-generated interfa
 - **Relative timestamps:** "2 hours ago" via `date-fns/formatDistanceToNow`
 - **Truncate long text** with `truncate` or `line-clamp-2`, full value in `Tooltip`
 - **Sticky headers** for long tables
+- **Never render an affordance you have not wired.** A grip glyph that does not drag, a chevron that does not sort, a card that looks clickable and is not — the signifier IS the promise, and an unfulfilled one reads as a broken feature, not a missing one. Either wire it or delete it. (Observed 2026-09-09: a `GripVertical` shipped as decoration on every row of a reorderable list; users reported the list as "can't be reordered", not as "missing drag".)
+- **A control that is disabled by default is indistinguishable from a broken one.** If the only explanation lives in a `title` tooltip, nobody reads it — they file a bug. When a control depends on a mode the user has not chosen yet, prefer making the action *switch the mode and proceed* over greying it out. Disable only for genuine impossibility (permissions, first row can't move up), and when you do, say why in visible text rather than on hover. (Same 2026-09-09 report: reorder arrows were disabled until you switched the sort to Manual, which nothing on screen told you.)
 
 ---