softr-vibe-coding 2.9.0 → 2.10.0

package/CHANGELOG.md

@@ -4,6 +4,14 @@ 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.10.0] - 2026-09-30
+- Add the print-in-a-new-window rule and references/printing.md (verified live 2026-09-30)
+- Add right-edge placement and the schema-less workspace-tool correction (2026-09-30)
+
+## [2.9.1] - 2026-09-30
+- Add right-edge placement and the schema-less workspace-tool correction (2026-09-30)
+- Document dropdown clipping by overflow ancestors (verified live 2026-09-30)
+
 ## [2.9.0] - 2026-09-29
 - Add runtime facts verified live 2026-09-18
 

package/README.md

@@ -169,7 +169,7 @@ Create a contact form that creates records in our Airtable Contacts table
 softr-vibe-coding/
 ├── SKILL.md                          # Main skill
 │                                     # Workflow, code structure, visual baseline,
-│                                     # components, settings, 27 hard constraints
+│                                     # components, settings, 28 hard constraints
 │
 ├── ui-ux-guidelines.md               # Design reference
 │                                     # 26 sections: hierarchy, color, typography,
@@ -223,6 +223,13 @@ softr-vibe-coding/
 │   │                                 # MCP/CLI install (@latest npx + browser step),
 │   │                                 # extract → poll → findings → generate → write
 │   │                                 # flow, DESIGN.md anatomy, drift QA
+│   ├── printing.md                   # Printing from a block: ALWAYS a new window
+│   │                                 # with its own document (never window.print()
+│   │                                 # on the page, never an in-page print view) —
+│   │                                 # escaped HTML builder, pop-up-safe open from
+│   │                                 # the click, print once stylesheets, fonts and
+│   │                                 # images load, ?print=1 deep link, paper layout
+│   │                                 # (Sep 30 2026)
 │   ├── quick-reference.md            # Syntax cheat sheet
 │   │                                 # Imports, hook signatures, mutation shapes,
 │   │                                 # field mapping, component skeleton
@@ -232,7 +239,10 @@ softr-vibe-coding/
 │                                     # click-outside, A-Z inside the component,
 │                                     # multi-token filter, searchable BY DEFAULT
 │                                     # (bare = click-only; searchable={false} only
-│                                     # for a fixed enum being set — Sep 10 2026)
+│                                     # for a fixed enum being set — Sep 10 2026),
+│                                     # overflow-clipping ancestors: never clip a cell
+│                                     # holding a Combo, clip-aware drop-up + list
+│                                     # height, list-only scrolling (Sep 30 2026)
 │
 ├── tools/                            # Bundled CLI scripts (run, not read)
 │   ├── get-airtable-base             # Full Airtable base schema export (bash + jq)

package/SKILL.md

@@ -90,6 +90,8 @@ You generate complete, production-ready Softr Vibe Coding blocks as TypeScript R
    - Sequential multi-row saves use `await hook.mutateAsync(...)` per row, in order, with stop-on-failure + retry state — `mutateAsync` is fully supported on the current platform (verified 2026-08-25; the old ".mutate() only" Action-parser rule is gone — see [datasources/writing.md](datasources/writing.md)). Independent writes to **different tables** may run in parallel via `Promise.all`; drag/reassign UIs should be optimistic with an Undo toast — see [writing.md → Parallel writes across tables](datasources/writing.md#parallel-writes-across-tables-the-one-sanctioned-parallelism)
    - No hardcoded domains in links -- use relative paths (`/page?recordId=...`); same-page anchors written relative too (`/#section`)
    - **No `<select>` and no shadcn `<Select>`** — both break inside a block's shadow DOM (native hands the list to the OS; shadcn portals outside the shadow root and arrives unstyled). Use the `Combo` pattern in [references/searchable-dropdown.md](references/searchable-dropdown.md) — **searchable by default** for every framed filter or form field whatever the option count; `bare` inline editors are click-only; `searchable={false}` only on a short fixed enum the user is setting (a status, a location, a group-by)
+   - No clipping class (`overflow-hidden`, `overflow-*-auto`, `truncate`, `line-clamp-*`) on any element that contains a `Combo` — its panel is absolutely positioned in local DOM, so a clipping `<td>` cuts the menu to the row's height; bound an over-wide chip at the chip (`min-w-0 truncate`), and never `scrollIntoView` inside the panel. See [references/searchable-dropdown.md](references/searchable-dropdown.md#the-four-things-that-will-bite-you), item 4
+   - Any **Print** control opens a **new window with its own document** — `window.open` straight from the click, an escaped standalone HTML printout written into it, `print()` once its stylesheets, fonts and images are in, the button disabled until the data has fully loaded. No `window.print()` on the Softr page, no in-page print view (Hard Constraint 28). See [references/printing.md](references/printing.md)
    - Static block: no hardcoded user-visible copy — every string/image/link is an editable setting (see [references/editable-settings.md](references/editable-settings.md#granularity-doctrine-settings-first-static-blocks))
    - Array-setting rows keyed by **index**, never by a builder-editable field value
    - Media settings that may start empty (`src: ""`) gated with a conditional render or placeholder — never an unconditional `<img src={setting.src}>`
@@ -174,6 +176,7 @@ For advanced patterns beyond data fetching, load the relevant reference when the
 | 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) |
 | Any **dropdown / picker / combobox** in a block — why shadcn `<Select>` and native `<select>` both fail inside the shadow DOM, the `composedPath()` click-outside, sorting A→Z inside the component, multi-token filtering, **searchable by default** regardless of option count (`bare` inline editors click-only; `searchable={false}` only for a short fixed enum being set), the `bare` inline-editor variant | [references/searchable-dropdown.md](references/searchable-dropdown.md) |
+| **Printing** anything from a block — always a new window/tab holding its own document, never `window.print()` on the page or an in-page print view: the escaped HTML builder, pop-up-safe opening from the click, print-when-ready (stylesheets, fonts and images, capped), Print disabled until the data has loaded, the `?print=1` deep link from another page, paper layout (shared `<colgroup>`, `vertical-align: middle`, tick boxes) | [references/printing.md](references/printing.md) |
 | 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) |
 | The official **Softr MCP server** — Softr DB schema + full record/table/field/database CRUD (deletes included), field-level browsing of connected Airtable / Google Sheets / Notion / Supabase integrations, **creating, editing, versioning, and deploying Vibe Coding blocks directly** (`get_vibe_coding_docs`, `create_vibe_coding_block`, ...), app management/scaffolding, the **Softr Workflows** suite (26 tools, 418-node catalog), and **per-application MCP servers** | [references/softr-mcp.md](references/softr-mcp.md) |
@@ -603,6 +606,14 @@ Non-negotiable rules. Most are enforced by the Softr platform (compiler, validat
     one table merge into ONE UPDATE_RECORD action (field list = the union), filed under the table's
     FIRST connection even when a hook points at a second one. Point writes at the first connection.
     Verified live 2026-09-18. See [datasources/writing.md](datasources/writing.md#actions-register-per-table-not-per-hook-or-connection).
+28. **Print in a new window, never on the page [house]** -- A Print control opens a new window
+    (`window.open("", "_blank", …)`, synchronously in the click handler; a toast if it returns
+    `null`) and writes a standalone, escaped HTML printout into it, printed once its stylesheets,
+    fonts and images are in. Never `window.print()` on the Softr page: a block is page content in
+    a shadow root, so the page prints Softr's header, footer and every sibling block, and hiding
+    them takes global CSS across Softr's page structure as well as print CSS in the block. Never
+    an in-page "print view" either (Leo rejected it by name). Verified live 2026-09-30. See
+    [references/printing.md](references/printing.md).
 
 ## Style Conventions
 

package/package.json

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

@@ -74,6 +74,8 @@ Run through this catalog before delivering any block. Every row is a violation o
 | 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 |
+| `overflow-hidden`, `truncate`, `line-clamp-*` or `overflow-*-auto` on a container that holds a dropdown or popover — typically a `<td>` clipped so an over-wide status chip stops at its own column | **Symptom:** the menu opens cut to the height of its row or its scroller: one or two options showing, the rest unreachable by mouse. **Cause:** the `Combo` panel is `position: absolute` in the block's own DOM (a portal would leave the shadow root and lose its styles), and an absolutely positioned box is clipped by every ancestor whose `overflow` is not `visible`. `truncate` and `line-clamp-*` set `overflow: hidden`; `overflow-x-auto` turns `overflow-y` to `auto` as well. **Fix:** no clipping class between the Combo and the scroller it belongs to; bound the chip at the chip (`min-w-0 truncate` on the chip inside the flex trigger); measure the drop-up and the list height against the clipping ancestors, not the window. Hit in production 2026-09-30: three ROSIE item tables clipped the status cell as a 2px backstop, next to a comment claiming the menu was portaled — it had stopped being portaled when the tables moved from shadcn `<Select>` to `Combo`. See [searchable-dropdown.md](searchable-dropdown.md#the-four-things-that-will-bite-you), item 4 |
+| `el.scrollIntoView({ block: "nearest" })` to keep a dropdown's highlighted option in view (or a plain `focus()` on its search box) | **Symptom:** the table or the page jumps when a menu opens near an edge; inside a clipped cell the trigger itself scrolls out of view. **Cause:** `scrollIntoView` scrolls EVERY scrollable ancestor until the element shows, and `overflow: hidden` boxes are still scrollable from script; `focus()` scrolls ancestors the same way. **Fix:** scroll the list element only — compare the option's rect with the list's and adjust `list.scrollTop` — and focus with `{ preventScroll: true }`. Verified in Chromium 2026-09-30: `scrollIntoView` scrolled an `overflow: hidden` cell by 164px, the list-only scroll moved nothing outside the list. See [searchable-dropdown.md](searchable-dropdown.md#the-four-things-that-will-bite-you), item 4, rule 3 |
 | 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 |
@@ -89,6 +91,12 @@ Run through this catalog before delivering any block. Every row is a violation o
 | 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). |
 
+## Printing
+
+| Anti-Pattern | Correct Approach |
+|---|---|
+| Printing the Softr page — `window.print()` from a block, with or without `@media print` CSS to hide the rest — or an in-page "print view": the block switches itself to a print layout under the app chrome, with "Print again" / "Exit print view" buttons | **Symptom:** the paper carries Softr's header and footer, every sibling block and the block's own controls; or the user lands in a second screen of the block that they have to find their way out of — "a weird UI", which Leo rejected by name on 2026-09-30. **Cause:** a block is page content in a shadow root. The app chrome and the sibling blocks are outside it, so the block's own print CSS cannot hide them; that takes global Custom Code CSS aimed at Softr's page structure, which you do not control. A print view changes nothing about that: it still ends in `window.print()` on the same page. **Fix:** Print opens a new window holding its own document — `window.open("", "_blank", …)` synchronously in the click (a toast if it returns `null`), a standalone, escaped HTML printout written into it, `print()` once its stylesheets, fonts and images are in. From another page, the linking page opens the target with `?print=1` in a window of its own, and the target block replaces its own document with the printout. Verified live 2026-09-30. See [printing.md](printing.md) |
+
 ## Permissions
 
 | Anti-Pattern | Correct Approach |

package/references/common-patterns.md

@@ -515,4 +515,4 @@ function onKeyDown(e) {
 
 Make the rows themselves focusable too (`tabIndex={0}`, an `onKeyDown` that opens on Enter only when `event.target === event.currentTarget`, so an Enter on the anchor inside the row is not handled twice), and let `onMouseEnter` *and* `onFocus` both move the highlight onto the row — the highlight is the single answer to "which record does Enter open", whichever device last touched it. That is the shape `projects-table.jsx` shipped on 2026-09-10.
 
-Paint the highlighted row with the same colour the mouse hover gets (`data-active="true"` + `bg-[#FFF7EF]`) and scroll it into view when it moves (`querySelector('[data-active="true"]').scrollIntoView({ block: "nearest" })` in a `useEffect` on `activeIdx`) — the Combo in [searchable-dropdown.md](searchable-dropdown.md#one-flat-row-list-for-the-keyboard) does the same. Reset `active` to 0 whenever the query changes: the old index points at a row that may no longer be in the list. `autoFocus` is right only when the block *is* the page's reason to exist — an index page whose first act is always a search; on a page with content above the table, a focus steal scrolls the page to the box.
+Paint the highlighted row with the same colour the mouse hover gets (`data-active="true"` + `bg-[#FFF7EF]`) and scroll it into view when it moves (`querySelector('[data-active="true"]').scrollIntoView({ block: "nearest" })` in a `useEffect` on `activeIdx`). That is right here, because these rows are page content and the table's scroller and the page *should* move to them. Inside a dropdown it is wrong, and the Combo scrolls only its own list — see [searchable-dropdown.md](searchable-dropdown.md#the-four-things-that-will-bite-you), item 4, rule 3. Reset `active` to 0 whenever the query changes: the old index points at a row that may no longer be in the list. `autoFocus` is right only when the block *is* the page's reason to exist — an index page whose first act is always a search; on a page with content above the table, a focus steal scrolls the page to the box.

package/references/printing.md

@@ -0,0 +1,533 @@
+# Printing from a block — a window of its own
+
+**Print opens a new window (or tab) holding its own printout document. Always.** Never
+`window.print()` on the Softr page, and never an in-page "print view". This is the default for
+every Print, "printable version" or save-as-PDF control in a block, whatever the data source.
+Leo, 2026-09-30: "I don't want this print view, it needs a new tab opening", and as the default,
+"so it doesn't create a weird UI".
+
+A block is page *content*, rendered inside a shadow root, and that rules out both of the obvious
+ways to print:
+
+| Option | What ends up on paper |
+|---|---|
+| `window.print()` from the block | The whole Softr page: the app header, the footer, every sibling block, and the block's own buttons and filters. The block's CSS lives in its shadow root and cannot reach any of the rest. Hiding it takes global Custom Code CSS aimed at Softr's page structure, which you do not control ([native-chrome-styling.md](native-chrome-styling.md)), plus print CSS inside the block for its own controls: two stylesheets in two places. |
+| An in-page "print view" (the block switches itself to a print layout) | A second screen of the block, still under the app chrome, with its own "Print again" / "Exit print view" buttons: a mode the user has to find their way out of. It still prints through `window.print()`, so it inherits the whole row above. Leo rejected it by name. |
+| A new window holding its own document (this page) | The printout and nothing else. No chrome to hide, no print CSS, no siblings, and the same from any page. The one cost is a pop-up, and the click itself gets it past the blocker. |
+
+Four parts make it work: a **builder** that turns the view into one HTML string (1), a **click**
+that opens the window and writes the string into it (2), a **wait** so it prints only once fonts
+and images are in (3), and a **Print button that waits for the data** (4). Printing from *another*
+page adds the `?print=1` deep link (5). Then the paper layout (6), and gotchas and testing (7).
+
+**Verified live 2026-09-30** in a Softr preview: the button opens a separate window holding only
+the printout (no app header or footer, no controls), photos load before print fires, and the page
+behind it is untouched; a `?print=1` link opens a window that shows "Preparing the printout…" and
+then becomes the same printout; every table cell measured 0px off its row's middle. (The snippets
+are modern TS, per SKILL.md's Style Conventions, generalised from the var-style original that was
+verified.)
+
+## 1. The builder: one HTML string
+
+The printout is a complete HTML document, built as one string by module-scope functions. Three
+rules make it safe and self-sufficient.
+
+**Escape every interpolated value, text and attribute values alike.** The window that
+`window.open("")` returns is an `about:blank` page on the app's own origin, and a `?print=1`
+printout (section 5) *is* the app's page. Record text written in unescaped is markup: an
+`<img onerror=…>` in a vendor name runs as the signed-in user. Escape all five characters, `&`
+first. The builder's attributes are single-quoted (`src='…'`), so `'` is not optional:
+
+```tsx
+function escapeHtml(value: unknown): string {
+  return String(value ?? "")
+    .replace(/&/g, "&amp;") // first, or it re-escapes the four below
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+```
+
+Then every `${…}` in the builder is one of three things: `escapeHtml(…)`, a number the code
+computed, or a fragment built only from those two and literals (`printCellHtml(…)`, `colgroup`,
+`headRow`, `PRINT_STYLES`). Nothing else.
+
+**Bring your own styles and fonts.** The new document starts empty. Tailwind, shadcn, the lucide
+React icons, the app's fonts and the Custom Code header CSS all stay behind in the app, so a class
+like `text-sm` means nothing there. Write plain CSS into the printout's own `<style>`, load the
+brand font with its own `<link>` (DESIGN.md's Font URLs), and draw anything iconic as text or an
+inline SVG string.
+
+**The `<title>` is the PDF's file name.** "Save as PDF" names the file after it, so give it the
+context as well as the view: `Project name — List name`, not `Print`.
+
+```tsx
+/* One cell on paper: the label the row shows ON SCREEN for that column (formatted dates, "—" for
+   empty), as escaped HTML. The name cell carries the photo at 24px, or an empty square of the
+   same size where there is none, so the names keep one straight edge. Adapt to your row shape. */
+type PrintRow = { name: string; photoUrl: string; labels: Record<string, string> };
+
+function printCellHtml(row: PrintRow, key: string): string {
+  if (key === "name") {
+    const photo = row.photoUrl
+      ? `<img class='ph' src='${escapeHtml(row.photoUrl)}' alt=''>`
+      : "<span class='ph none'></span>";
+    return `<span class='item'>${photo}<span>${escapeHtml(row.name)}</span></span>`;
+  }
+  return escapeHtml(row.labels[key] || "—");
+}
+
+/* Plain CSS for a document with no Tailwind in it. Black text on white prints best; put the
+   brand colour (DESIGN.md) on the eyebrow and the heading only. Section 6 explains each rule. */
+const PRINT_STYLES = [
+  "body{font:12px Inter,Helvetica,Arial,sans-serif;color:#000;margin:24px}",
+  ".eyebrow{font-size:13px;font-weight:600;letter-spacing:0.75px;text-transform:uppercase;color:#111;margin:0 0 4px}",
+  "h1{font-size:18px;font-weight:600;color:#111;margin:0 0 2px}",
+  ".meta{font-size:11px;color:#333;margin:0 0 2px}",
+  ".meta.note{font-weight:600}",
+  ".grp{font-size:12px;font-weight:700;margin:14px 0 4px}",
+  "table{width:100%;table-layout:fixed;border-collapse:collapse;font-size:11px}",
+  "th{text-align:left;border-bottom:1px solid #DDD;padding:3px 4px;overflow-wrap:anywhere}",
+  "td{text-align:left;border-bottom:1px solid #DDD;padding:3px 4px;vertical-align:middle;overflow-wrap:anywhere}",
+  "tbody tr{break-inside:avoid}",
+  ".item{display:flex;align-items:center;gap:6px}",
+  ".ph{display:inline-block;flex:none;width:24px;height:24px;object-fit:cover;border:1px solid #DDD}",
+  ".ph.none{background:#F2F2F2;-webkit-print-color-adjust:exact;print-color-adjust:exact}",
+  ".chk{text-align:center}",
+  ".box{display:block;margin:0 auto;width:12px;height:12px;border:1px solid #000}",
+  ".notes{margin-top:18px;break-inside:avoid}",
+  ".notes-body{white-space:pre-wrap;font-size:12px}",
+  "@page{margin:14mm}",
+].join("");
+
+type PrintColumn = { key: string; label: string };
+type PrintContext = {
+  title: string; // the <title>: what "Save as PDF" names the file
+  eyebrow: string; // the context above the heading (the project, the client), or ""
+  heading: string;
+  meta: string[]; // plain-text lines under the heading, the print date first
+  filterNote: string; // "Filtered view — 12 of 40 items" while a search or filter is on, else ""
+  columns: PrintColumn[]; // the columns on show, in their on-screen order
+  widths: Record<string, number>; // on-screen widths by key; only the proportions matter
+  groups: { name: string; rows: PrintRow[] }[]; // one table per group; name "" when ungrouped
+  tickBox: boolean; // a title-less ☐ column at the end, to tick on paper
+  notes: string;
+  emptyText: string;
+};
+
+function buildPrintHtml(ctx: PrintContext): string {
+  const cols = ctx.columns;
+  const tick = ctx.tickBox ? 6 : 0; // the ☐ column's share of the width, in %
+  const total = cols.reduce((sum, c) => sum + (ctx.widths[c.key] || 100), 0);
+  const pct = (key: string) => (((ctx.widths[key] || 100) / total) * (100 - tick)).toFixed(2);
+  /* ONE <colgroup>, shared by every group's table. With table-layout:fixed, that is what lines
+     the columns up from one group to the next (section 6). */
+  const colgroup =
+    "<colgroup>" +
+    cols.map((c) => `<col style='width:${pct(c.key)}%'>`).join("") +
+    (tick ? `<col style='width:${tick}%'>` : "") +
+    "</colgroup>";
+  const headRow =
+    "<tr>" +
+    cols.map((c) => `<th>${escapeHtml(c.label)}</th>`).join("") +
+    (tick ? "<th aria-label='Done'></th>" : "") + // no title over the tick boxes
+    "</tr>";
+
+  const out: string[] = [];
+  out.push("<!doctype html><html><head><meta charset='utf-8'>");
+  out.push(`<title>${escapeHtml(ctx.title)}</title>`);
+  out.push(
+    "<link rel='stylesheet' href='https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700&display=swap'>"
+  );
+  out.push(`<style>${PRINT_STYLES}</style></head><body>`);
+  if (ctx.eyebrow) out.push(`<p class='eyebrow'>${escapeHtml(ctx.eyebrow)}</p>`);
+  out.push(`<h1>${escapeHtml(ctx.heading)}</h1>`);
+  ctx.meta.forEach((line) => out.push(`<p class='meta'>${escapeHtml(line)}</p>`));
+  if (ctx.filterNote) out.push(`<p class='meta note'>${escapeHtml(ctx.filterNote)}</p>`);
+
+  ctx.groups.forEach((group) => {
+    if (group.name) {
+      out.push(`<div class='grp'>${escapeHtml(group.name)} &middot; ${group.rows.length}</div>`);
+    }
+    out.push(`<table>${colgroup}<thead>${headRow}</thead><tbody>`);
+    group.rows.forEach((row) => {
+      out.push(
+        "<tr>" +
+          cols.map((c) => `<td>${printCellHtml(row, c.key)}</td>`).join("") +
+          (tick ? "<td class='chk'><span class='box'></span></td>" : "") +
+          "</tr>"
+      );
+    });
+    out.push("</tbody></table>");
+  });
+  if (ctx.groups.length === 0) out.push(`<p class='meta'>${escapeHtml(ctx.emptyText)}</p>`);
+
+  if (ctx.notes) {
+    out.push(
+      `<div class='notes'><div class='grp'>Notes</div><div class='notes-body'>${escapeHtml(ctx.notes)}</div></div>`
+    );
+  }
+  out.push("</body></html>");
+  return out.join("");
+}
+```
+
+**What goes on paper: the view as it stands.** Build the context inside `Block()` from the same
+derived values the screen renders (the columns on show, in their order, hidden ones left out; the
+same groups, sort and filters), so paper and screen cannot disagree. Two meta lines earn their
+place: the date, because a sheet outlives the day it was printed, and a line that says so when a
+search or filter is on. (A printout that is a different document by design, such as a packing slip
+or an invoice, builds its own content, but keeps every other rule on this page.)
+
+```tsx
+/* Inside Block(), next to the values it reads. */
+function printContext(): PrintContext {
+  return {
+    title: `${projectName} — ${listName}`,
+    eyebrow: projectName,
+    heading: listName,
+    meta: ["Printed " + format(new Date(), "MMM d, yyyy")],
+    filterNote: hasActiveFilter ? `Filtered view — ${shownRows.length} of ${rows.length} items` : "",
+    columns: visibleColumns,
+    widths: columnWidths,
+    groups: groups, // the grouped, sorted, filtered rows the table renders, as PrintRow
+    tickBox: true,
+    notes: notes.trim(),
+    emptyText: rows.length === 0 ? "Nothing on this list yet." : "No items match this filter.",
+  };
+}
+```
+
+## 2. Open it from the click
+
+```tsx
+function handlePrint() {
+  // FIRST, and synchronously: the click's user activation is what gets the window past the
+  // pop-up blocker. No await, .then() or setTimeout in front of this line.
+  const win = window.open("", "_blank", "width=900,height=700");
+  if (!win) {
+    toast.error("Your browser blocked the print window. Allow pop-ups for this site and try again.");
+    return;
+  }
+  writePrintout(win, buildPrintHtml(printContext()));
+}
+```
+
+- **Nothing asynchronous before `window.open`.** A browser lets a page open a window only while
+  the user's click is fresh. An `await` (fetching the data on click, say), a `.then()` or a
+  `setTimeout` in front of it spends that allowance, and the window is blocked some of the time,
+  in some browsers: the worst kind of bug to chase. Section 4 makes sure the data is already there
+  when the button can be pressed, so there is nothing to wait for.
+- **`null` means blocked.** Say how to fix it (the toast above) instead of failing silently.
+- **No `noopener` or `noreferrer` in the features.** With either one, `window.open` returns `null`
+  even though the window opened: there is no handle to write the printout into, and the code reads
+  the `null` as "blocked".
+- **`width` / `height` make it a pop-up window.** A features string like the one above makes
+  Chromium and Firefox open a separate window at that size; with no features string it is a new
+  tab. Either meets the rule. Pick one and make every Print in the app the same call, so every
+  Print behaves the same; nothing but discipline keeps two blocks alike (SKILL.md Hard
+  Constraint 22).
+- **The block that has the data writes the printout itself.** Do not route its own button through
+  `?print=1` (section 5): that reloads the whole app and every query in the new window to print
+  data this page already holds.
+
+## 3. Print only when it is ready
+
+```tsx
+/* Writes the printout into `win` and prints it once it is ready. `win` is a window of its own or,
+   for a ?print=1 open (section 5), this very window, whose page the printout then replaces.
+   Ready means the font stylesheets and every image have loaded or failed, and then the web fonts
+   are in: a print fired earlier comes out with empty squares where the photos go, or in the
+   fallback font. It never waits more than 4s, then gives the layout a 250ms beat, because some
+   browsers otherwise print a blank first page. */
+function writePrintout(win: Window, html: string) {
+  win.document.open();
+  win.document.write(html);
+  win.document.close();
+  win.focus();
+
+  let fired = false;
+  const fire = () => {
+    if (fired || win.closed) return;
+    fired = true;
+    window.setTimeout(() => {
+      if (!win.closed) win.print();
+    }, 250);
+  };
+  window.setTimeout(fire, 4000); // the cap: one slow or hung request never holds the print hostage
+
+  const settled = (el: HTMLElement) =>
+    new Promise((resolve) => {
+      el.addEventListener("load", resolve);
+      el.addEventListener("error", resolve); // a failed image or stylesheet must not hold it either
+    });
+  const waits: Promise<unknown>[] = [];
+  // The stylesheets too: document.fonts.ready does not wait for a font stylesheet still in flight.
+  win.document.querySelectorAll<HTMLLinkElement>("link[rel='stylesheet']").forEach((link) => {
+    if (!link.sheet) waits.push(settled(link));
+  });
+  Array.from(win.document.images).forEach((img) => {
+    if (!img.complete) waits.push(settled(img));
+  });
+  Promise.all(waits)
+    .then(() => win.document.fonts?.ready) // with the stylesheets in, this covers the font files
+    .then(fire, fire);
+}
+```
+
+- **Stylesheets and images first, then the fonts.** Those are what go missing on paper. The
+  stylesheet wait matters because `document.fonts.ready` only counts the fonts the document
+  already knows it needs. Measured in Chromium on 2026-09-30: with a font stylesheet taking 1.5s,
+  `fonts.ready` resolved at once and the print fired at 255ms; waiting for the `<link>` first held
+  the print until the font file had arrived. (The live-verified deployment waited on `fonts.ready`
+  and the images only. Photos usually arrive after the stylesheet, which hides the gap; without
+  photos, the brand font can miss the paper.)
+- **`fired` makes it print once**, whichever comes first: the cap or the waits.
+- **Guard `win.closed`.** The user can close the window during the wait.
+
+## 4. The Print button waits for the data
+
+A printout built before the data is in is a skeleton on paper, or worse, the first page of
+records, which looks complete. Keep Print disabled until every query has succeeded **and every
+page is fetched** (`hasNextPage` false on each; the auto-load-all effect in
+[../datasources/reading.md](../datasources/reading.md#loading-all-records-auto-pagination) is what
+gets it there), and say why on hover:
+
+```tsx
+const dataReady =
+  itemsResult.status === "success" &&
+  !itemsResult.hasNextPage &&
+  vendorsResult.status === "success" &&
+  !vendorsResult.hasNextPage;
+
+<button
+  type="button"
+  onClick={handlePrint}
+  disabled={!dataReady}
+  title={dataReady ? "Opens the printout in a new window" : "Loading…"}
+  className="inline-flex items-center gap-1.5 … disabled:cursor-wait disabled:opacity-60"
+>
+  <Printer className="h-4 w-4" />
+  Print
+</button>
+```
+
+If the printout reads anything else from state that arrives after the data, such as a saved
+layout or view settings hydrated from a record, add its ready flag to the same condition
+(`viewReady` in section 5).
+
+## 5. Printing from another page: `?print=1`
+
+A Print control on a page that does not hold the data (a card on an index page, say) needs the
+target page to build the printout. But a page that has just loaded cannot open a window (there is
+no user gesture, so the pop-up blocker stops it), and it must not `window.print()` itself (the
+rule at the top). So the two pages split the work.
+
+**The linking page opens the window, straight from the click**, pointed at the target page with a
+flag:
+
+```tsx
+<a
+  href={`/list?recordId=${encodeURIComponent(record.id)}&print=1`}
+  onClick={(e) => {
+    // A window of its own, the same call as every other Print. preventDefault ONLY when it
+    // opened: if a pop-up blocker returns null, the link still works, in this tab.
+    const win = window.open(e.currentTarget.href, "_blank", "width=900,height=700");
+    if (win) e.preventDefault();
+  }}
+  className="…"
+>
+  <Printer className="h-3.5 w-3.5" />
+  Print
+</a>
+```
+
+A real `<a href>` rather than a button, so the fallback costs nothing and the URL is a real one.
+Keep `noopener` out here too: `window.open` would return `null` although the window opened, the
+handler would not `preventDefault`, and the tab would navigate as well, giving two printouts.
+
+**The target block turns its own window into the printout.** It reads the flag once, shows a
+one-line holding state instead of its UI, and, once the data and anything else the printout reads
+are in, replaces its own document with the printout and prints:
+
+```tsx
+export default function Block() {
+  // Read once, at mount.
+  const [printOnLoad, setPrintOnLoad] = useState(() => {
+    try {
+      const p = new URLSearchParams(window.location.search).get("print");
+      return p === "1" || p === "true";
+    } catch (e) {
+      return false;
+    }
+  });
+
+  // … the data hooks, the auto-load-all effects, dataReady (section 4), anyQueryFailed (any of
+  //   them in status "error"), and viewReady if a saved layout is hydrated into state (drop it
+  //   from the effect below if there is none) …
+
+  /* Runs once: printOnLoad goes false first, so a later refetch cannot print a second time.
+     printContext is declared further down and reads values computed during the render; the
+     effect runs after the render, by which time they are all set. */
+  useEffect(() => {
+    if (!printOnLoad || !dataReady || !viewReady) return;
+    setPrintOnLoad(false);
+    writePrintout(window, buildPrintHtml(printContext()));
+  }, [printOnLoad, dataReady, viewReady]);
+
+  // … every other hook: ALL of them above the holding return below (Hard Constraint 19) …
+
+  if (printOnLoad) {
+    // This window exists only to become the printout: a holding line, never the full UI.
+    return (
+      <div className="container py-0">
+        <div className="content">
+          <div className="px-8 pt-10 pb-12 text-sm text-muted-foreground">
+            {anyQueryFailed
+              ? "Couldn't load this to print it. Reload this window to try again."
+              : "Preparing the printout…"}
+          </div>
+        </div>
+      </div>
+    );
+  }
+
+  // … the normal view …
+}
+```
+
+- **The ready flags are the effect's dependencies.** It has to run again each time one of them
+  flips; an empty dependency array runs it once, at mount, before any data exists.
+- **A holding line, not the full UI.** Rendering the normal view meanwhile flashes the whole app
+  (filters, buttons, a table filling in) for a second before it turns into paper.
+- **`writePrintout(window, …)` replaces the Softr page in that window.** `document.open()` clears
+  the app's DOM, header and footer included, and the printout is all that is left. Whatever React
+  renders after that goes into a root that is no longer in the document.
+- **The fallback.** If the linking page's pop-up was blocked, the link opened this URL in the
+  user's own tab, and the printout replaces the app there. The link still works; it is just less
+  graceful.
+
+## 6. Layout on paper
+
+The CSS in section 1 carries all of this; each rule is there for a reason.
+
+- **One `<colgroup>`, shared by every group's table, with `table-layout: fixed`.** A grouped view
+  prints as one table per group. With automatic layout each table sizes its columns to its own
+  content, and the columns zig-zag from one group to the next. A fixed layout takes its widths
+  from the `<col>` elements, and one shared `<colgroup>` gives every table the same ones.
+  Percentages in proportion to the on-screen widths keep the paper recognisable as the screen.
+- **`overflow-wrap: anywhere` on every cell**, so a long SKU or URL wraps inside its fixed column
+  instead of running into the next one.
+- **`vertical-align: middle` on every `td`.** A room or category that wraps to two lines otherwise
+  leaves the one-line values in its row hanging from the top. (Verified: every cell 0px off its
+  row's middle.)
+- **A tick-box column is a bordered block, centred:** `.box{display:block;margin:0 auto;…}` in a
+  `text-align:center` cell, under a title-less `<th>` that carries an `aria-label`. A block sits
+  on no text line, so no line-height can nudge it off the middle; an inline box sits on the text
+  baseline, and the line's descender space pushes it off-centre.
+- **`tbody tr { break-inside: avoid }`**, so a row never splits across two pages. The same for the
+  notes.
+- **Backgrounds do not print by default.** Browsers drop background colours and images unless the
+  user ticks "Background graphics". Where a background carries meaning (a placeholder square, a
+  status fill), set `-webkit-print-color-adjust: exact; print-color-adjust: exact` on it, and draw
+  photos as `<img>`, never as a CSS `background-image`.
+- **Images at a fixed size with `object-fit: cover`**, and an empty square of the same size where
+  a row has none, so the text beside them keeps one straight edge.
+- **`@page { margin: 14mm }`** is the margin on paper; the `body` margin is for the window on
+  screen.
+
+## 7. Gotchas and testing
+
+**Attachment URLs work as they are.** Softr Database attachment URLs are pre-signed links that
+carry their auth in the query string, so the new window loads them with no cookie or header
+(verified 2026-09-30); any file URL that needs no cookie behaves the same. They expire after a
+couple of hours and are re-signed on every fetch, so build the printout from what the block has
+just fetched, never from a URL saved earlier.
+
+**Capture the window with `page.waitForEvent("popup")`** (Playwright). The printout is a popup of
+the page that was clicked, for the Print button (`window.open("")`) and for a `?print=1` link on
+another page (`window.open(href)`) alike:
+
+```ts
+const [popup] = await Promise.all([
+  page.waitForEvent("popup"),
+  page.getByRole("button", { name: /print/i }).click(),
+]);
+
+// Replace print() before it fires, so no dialog blocks the run and the test sees when it fired.
+// For the Print button the document is already written by the time you hold the popup, and
+// print() comes at least 250ms later.
+await popup.evaluate(() => {
+  window.print = () => {
+    (window as any).__printedWithImages = Array.from(document.images).every((img) => img.complete);
+  };
+});
+await expect
+  .poll(() => popup.evaluate(() => (window as any).__printedWithImages), { timeout: 10_000 })
+  .toBe(true); // the 4s cap plus the 250ms beat is too close to the 5s default
+
+// A plain document: no shadow roots and no Softr chrome, so ordinary locators work.
+await expect(popup.locator(".softr-topbar")).toHaveCount(0);
+await expect(popup.locator("tbody tr")).toHaveCount(expectedRows);
+
+// Each tick box's centre against its row's.
+const offsets = await popup.evaluate(() =>
+  Array.from(document.querySelectorAll("tbody tr")).map((tr) => {
+    const row = tr.getBoundingClientRect();
+    const box = tr.querySelector(".box")!.getBoundingClientRect();
+    return Math.abs(box.top + box.height / 2 - (row.top + row.height / 2));
+  })
+);
+expect(Math.max(...offsets)).toBeLessThan(1);
+```
+
+For a `?print=1` link, click the link instead. That window loads the Softr page first, so wait
+for it to *become* the printout before asserting on it:
+`await expect(popup).toHaveTitle("Project name — List name")`. Stub `print` there once the Softr
+page has loaded (`await popup.waitForLoadState()`): `document.open()` keeps a `print` set on the
+window before it (checked in Chromium, 2026-09-30). The printout has no print-only CSS, so the
+window lays it out as the paper will; narrow it to about the paper's printable width (roughly
+700px for A4 or Letter at 14mm margins) to see the wrapping the paper gets.
+
+**Do not mock a popup printout's images or fonts with `route()`.** The Print button writes the
+printout in the same task that opens the window, so its first requests go out before Playwright
+has attached to the popup. With Playwright attached over CDP (seen 2026-09-30) they hang: no
+`request` event, the route handler never runs, the images stay pending, and the print falls
+through to the 4s cap, which looks exactly like a broken wait. Use real URLs or `data:` URLs in
+the popup, or mock on a page that loaded normally (the `?print=1` path), where routing works.
+
+**Preview links pin the app version they were minted on.** A `preview_app` session keeps serving
+the version it was opened on, so after pushing a change, mint a fresh preview link before you
+verify anything; otherwise you are testing the old Print. (What else a preview link is, and why
+it is never shared: [softr-mcp.md](softr-mcp.md#application-management-tools).)
+
+**A browser that is not painting does not run the page.** A hidden browser pane or a background
+tab fires no `requestAnimationFrame` and no IntersectionObserver callbacks, so anything that waits
+on them (a reveal-on-scroll, lazy content, a check timed off a frame) stalls there, and a check
+fails for reasons that have nothing to do with your code. Verify in a visible window or a
+headless browser.
+
+## Checklist before shipping a Print control
+
+- [ ] Print opens a window of its own: `window.open("", "_blank", …)`, first thing in the click
+      handler, nothing asynchronous before it. No `window.print()` on the Softr page, no in-page
+      print view
+- [ ] `null` → a toast telling the user to allow pop-ups; no `noopener` / `noreferrer` in the
+      features
+- [ ] The same `window.open` features string as every other Print in the app
+- [ ] Every interpolated value through `escapeHtml` (`& < > " '`, attribute values included)
+- [ ] The printout carries its own `<style>` (no Tailwind classes), its fonts' `<link>`, a
+      `<title>` with the context, and an `@page` margin
+- [ ] It prints once the stylesheets, fonts and images are in (capped at ~4s), after a 250ms
+      beat, with `win.closed` guarded
+- [ ] Print is disabled until every query has succeeded and every page is fetched (and any saved
+      layout is applied), with a `title` that says why
+- [ ] Printing from another page: the linking page opens the window (`preventDefault` only when
+      it opened); the target block shows "Preparing the printout…", then replaces its own
+      document once the ready flags are set, once
+- [ ] Paper: one shared `<colgroup>` + `table-layout: fixed`; `vertical-align: middle`;
+      `break-inside: avoid` on rows; `print-color-adjust: exact` where a background must print;
+      photos as fixed-size `<img>`
+- [ ] Verified on a freshly minted preview link, with the window captured by
+      `waitForEvent("popup")`

package/references/searchable-dropdown.md

@@ -8,13 +8,13 @@ the obvious choices:
 |---|---|
 | Native `<select>` | Hands the list to the OS. No keyword filter, none of your styling, and on macOS it paints a grey slab over the page. Fine for 5 options, unusable at 90. |
 | shadcn `<Select>` / `<Command>` | **Portals to `document.body`, which is outside the block's shadow root**, so the styles arrive stripped. It also cannot be searched. |
-| `Combo` (below) | Local DOM, brand-styled, keyword filter, A→Z, keyboard, create-new, drop-up. |
+| `Combo` (below) | Local DOM, brand-styled, keyword filter, A→Z, keyboard, create-new, clip-aware drop-up. |
 
 Copy the component into the block. A Vibe block is one self-contained file — there is no
 shared module to import, so each block carries its own copy. Keep one canonical copy in the
 project (e.g. `Assets/Softr App/Shared/combo.jsx`) and port changes from there.
 
-## The three things that will bite you
+## The four things that will bite you
 
 **1. Click-outside must use `composedPath()`, not `contains()`.**
 By the time a click reaches `document`, the shadow DOM has *retargeted* its `target` to the
@@ -44,6 +44,182 @@ single most common Vibe Coding bug and it looks like a platform fault.
 **3. `onMouseDown` on a row must `preventDefault()`.**
 Otherwise focus leaves the search input before the click resolves.
 
+**4. The panel is clipped by any ancestor whose `overflow` is not `visible`.**
+The panel is `position: absolute` inside the trigger's `relative` wrapper, in the block's own
+DOM, because it cannot portal out of the shadow root (see *Why not portal* below). Its
+containing block is that wrapper, so *every* ancestor whose `overflow` is `hidden`, `auto`,
+`scroll` or `clip` clips it, however far up. In Tailwind that is `overflow-hidden`,
+`overflow-auto`, `overflow-y-auto`, `overflow-x-auto` (an `overflow-x` of `hidden`, `auto` or
+`scroll` turns `overflow-y: visible` into `auto`, so it clips vertically too), `truncate` (it
+sets `overflow: hidden`) and `line-clamp-*` (so does that). A clipped `<td>` is the height of
+its row, and the menu opens inside it. Three rules follow.
+
+**Rule 1 — never put a clipping class on an element that contains a `Combo`:** a `<td>`, a
+card, a flex cell, anything between the Combo and the scroller it belongs to. If a chip or
+label inside the trigger can overflow, bound it at the chip: `truncate` (or `overflow-hidden`)
+plus `min-w-0` on the chip itself. The trigger is a flex row, and `min-w-0` is what lets a flex
+item shrink below its text — strictly redundant while the chip clips itself, load-bearing the
+moment the ellipsis moves to a span inside it. Clipping at the chip clips the chip. Clipping at
+the cell clips the menu.
+
+```jsx
+<td className="px-4">{/* no overflow class on the cell */}
+  <Combo
+    bare
+    triggerContent={<span className="min-w-0 truncate px-2" style={chipStyle}>{label}</span>}
+    …
+  />
+</td>
+```
+
+**Rule 2 — decide the drop-up and the list's height against the clipping ancestors, not the
+window.** `window.innerHeight - rect.bottom` cannot see scroll containers: a table with its own
+`max-height` + `overflow: auto` scroller, a dialog body with `overflow-y-auto`, a horizontally
+scrollable table wrapper. A row near the bottom of one of those opens its menu downward into
+the scroller's hidden area while the window still has plenty of room. Measure inside the strip
+the panel can actually paint into:
+
+```jsx
+var COMBO_LIST_MAX = 256; // the list's normal ceiling (max-h-64)
+var COMBO_LIST_MIN = 120; // the floor: below this, accept a clip rather than a useless list
+
+/* The strip of screen the panel can paint into: the viewport, cut down by every ancestor
+   that clips vertically. overflowY is enough on its own: an overflow-x of hidden, auto or
+   scroll already turns a visible overflow-y into auto in the computed style. */
+function comboClipBox(node) {
+  var top = 0;
+  var bottom = window.innerHeight;
+  var el = node;
+  while (el && el !== document.body && el !== document.documentElement) {
+    // clientHeight is 0 for the boxes overflow does not apply to (inline, display: contents)
+    if (el.clientHeight > 0 && window.getComputedStyle(el).overflowY !== "visible") {
+      var r = el.getBoundingClientRect();
+      var t = r.top + el.clientTop; // the clip edge is the padding box: inside the border
+      var b = t + el.clientHeight; //  and above a horizontal scrollbar
+      if (t > top) top = t;
+      if (b < bottom) bottom = b;
+    }
+    // Where the parent chain ends at the shadow root, carry on from its host.
+    el = el.parentElement || el.getRootNode().host || null;
+  }
+  return { top: top, bottom: bottom };
+}
+
+/* chrome = the panel's height outside the list: the search box and the borders. */
+function comboPlace(wrapper, chrome) {
+  var clip = comboClipBox(wrapper);
+  var r = wrapper.getBoundingClientRect();
+  var below = clip.bottom - r.bottom - 10; // the 2px gap to the trigger + 8px to spare
+  var above = r.top - clip.top - 10;
+  var up = below < chrome + COMBO_LIST_MAX && above > below;
+  var room = (up ? above : below) - chrome;
+  return { up: up, listMax: Math.max(COMBO_LIST_MIN, Math.min(COMBO_LIST_MAX, room)) };
+}
+```
+
+Call it when the panel opens, and give the list its height as an inline style in place of
+`max-h-64`:
+
+```jsx
+var [listMax, setListMax] = useState(COMBO_LIST_MAX);
+
+// in toggle(), before setOpen(true):
+if (rootRef.current) {
+  var place = comboPlace(rootRef.current, searchable ? 51 : 2);
+  setDropUp(place.up);
+  setListMax(place.listMax);
+}
+
+// the list:
+<div ref={listRef} role="listbox" className="overflow-y-auto py-1" style={{ maxHeight: listMax }}>
+  {/* rows */}
+</div>
+```
+
+Downward when the whole panel fits below, otherwise toward the larger side, with the list
+capped to the room it gets. `chrome` is the panel's height outside the list — about 51px with
+the search box (`p-2` around an `h-8` input, a 1px rule, the panel's two borders) and 2px
+without; measure yours if the panel differs. The fit test assumes a full-height list, so a
+three-option menu may flip up when it would have fit below, which costs nothing. The walk
+starts at the wrapper, whose own overflow would clip the panel too; it leaves the shadow root
+through its host, so a clipping container outside the block still counts; and it stops below
+`<body>`, because `body` and `html` hand their overflow to the viewport — their computed
+`overflow` can say `hidden` while they clip nothing. The four cases it has to get right: a row
+mid-way down a tall table scroller opens down; the last visible row of a scroller whose bottom
+edge is mid-window opens up, inside the scroller (the window-only rule opened it down, into
+the hidden part); a picker at the bottom of a dialog body opens up, inside the dialog; a filter
+row at the window's bottom edge opens up, as before. All four, plus a scroller outside the
+shadow root, checked in Chromium on 2026-09-30 on a test page — not yet in a deployed block.
+
+Rule 2 does not rescue a clipped cell. The cell is the height of its row, so neither side has
+room, the list falls to its 120px floor and is clipped anyway. Rule 1 is not optional.
+
+**The same box decides which edge the panel hangs from.** A panel hung from the trigger's left
+edge with `width: max-content` runs past the right edge of a table's scroll box when the trigger
+sits in the last column. In ROSIE the Location menu ran about 15px over, and the old
+`scrollIntoView` then slid the whole table sideways to reveal it. Measure the box's left and right
+edges as well (padding box, tested on `overflowX`), and when the room to the right of the trigger
+is short (under ~300px) and there is more to the left, anchor the panel with `right: 0` instead of
+`left: 0` and cap its `maxWidth` to the room on that side. Rows are a fixed height in this
+component, so the fit test can also count the real rows instead of assuming a full list, and a
+four-option menu near an edge stops flipping for room it will never use. ROSIE's
+`Shared/combo.jsx` (2026-09-30) is the worked version: one `comboClipBox` returning all four
+edges, one `comboPlacement` returning `{ up, right, listMax, maxW }`, deployed in twelve blocks.
+
+**Rule 3 — keep the active row visible by scrolling the list, never with `scrollIntoView`.**
+`scrollIntoView` scrolls *every* scrollable ancestor until the element shows, and an
+`overflow: hidden` box is still scrollable from script. In a clipped cell it scrolls the
+cell's content until the option shows, pushing the trigger out of view; near the edge of a
+table it scrolls whatever the menu hangs out of — the table's own scroller, the page — so the
+table jumps as the menu opens. Scroll the list element and nothing else:
+
+```jsx
+useEffect(
+  function () {
+    var list = listRef.current;
+    if (!open || !list) return;
+    var el = list.querySelector('[data-active="true"]');
+    if (!el) return;
+    var lr = list.getBoundingClientRect();
+    var er = el.getBoundingClientRect();
+    var viewTop = lr.top + list.clientTop; // inside the list's top border
+    var viewBottom = viewTop + list.clientHeight; // clientHeight excludes border and scrollbar
+    if (er.top < viewTop) list.scrollTop -= viewTop - er.top;
+    else if (er.bottom > viewBottom) list.scrollTop += er.bottom - viewBottom;
+  },
+  [open, activeIdx, query]
+);
+```
+
+Rects rather than `offsetTop`: a row's `offsetParent` is the nearest positioned ancestor,
+which is the panel, not the list, so `offsetTop` comes out too large by the search box's
+height unless the list is made `position: relative`. Rects need no such arrangement. The
+effect runs after the commit, outside the event cycle Hard Constraint 17's `setTimeout` is
+there to escape — the `scrollIntoView` it replaces ran from the same kind of effect and took
+effect. `focus()` scrolls ancestors the same way, so focus the search box with
+`inputRef.current.focus({ preventScroll: true })`.
+
+**Why not portal the panel, or make it `position: fixed`?** A portal to `document.body`
+leaves the shadow root, and the styles stay behind — the shadcn row at the top of this page.
+`position: fixed` inside the shadow root escapes the clipping only while no ancestor has a
+`transform`, `filter`, `perspective`, `contain` or `will-change`: any of those becomes the
+containing block for fixed descendants, and scroll-reveal animations on Softr pages commonly
+leave a transform behind (the same trap as the block-owned header in
+[static-blocks.md](static-blocks.md#block-owned-landing-page-header)). A fixed panel also stops
+moving with its trigger, so it has to be re-placed on every scroll. The clip-aware absolute
+panel has neither problem, which is why it is the design here.
+
+**The incident — ROSIE, 2026-09-30.** Three item tables put `overflow-hidden` on the `<td>`
+holding the status chip, as a backstop so the chip, 1–2px too wide at the column's narrowest
+drag width, would clip at its own column instead of painting over the next one. The comment
+beside it said the status menu was portaled to the body, so the clip could not reach it. That
+was true of the shadcn `<Select>` the tables used before and stopped being true when they moved
+to `Combo`; nobody re-checked. The menu opened inside the 48px cell: one and a half options
+showing, the chip scrolled out of view by `scrollIntoView`, the other six unreachable by
+mouse. The Location dropdown in the same rows kept working, because its cell had no overflow
+class. A 2px backstop cost the whole feature. A comment that says how a component renders is
+a claim to verify in the component, not in the comment.
+
 ## Sort A→Z *inside* the component
 
 Sorting at the call site gets forgotten. Do it in the component, with an opt-out:
@@ -125,16 +301,7 @@ than reaching past the wrapper.
 Build `rows` as a single array — the optional *clear* row, then the filtered options, then
 the optional *create* row — so arrow-key navigation has one index to walk. Clamp the active
 index (`Math.min(active, rows.length - 1)`): filtering shrinks the list under the highlight.
-
-## Drop up near the fold
-
-```jsx
-var r = rootRef.current.getBoundingClientRect();
-var below = window.innerHeight - r.bottom;
-setDropUp(below < 300 && r.top > below);
-```
-
-A filter row near the bottom of the viewport otherwise opens into nothing.
+Keep the highlighted row in view by scrolling the list only (rule 3 of item 4 above).
 
 ## Variants worth having
 
@@ -145,6 +312,9 @@ A filter row near the bottom of the viewport otherwise opens into nothing.
   ⚠ If any column width in your table is derived from the trigger's chrome, keep the
   chevron the SAME size in both variants. Shrinking it in `bare` silently changes those
   widths in a different file.
+  ⚠ A `bare` Combo sits in a table cell, which is exactly where `overflow-hidden` and
+  `truncate` get added. Keep them off the cell and bound the chip instead — rule 1 of item 4
+  in [The four things that will bite you](#the-four-things-that-will-bite-you).
 - **`triggerStyle`** — merged over the defaults, for a trigger that is part of the design
   (a chip painted in its own status colour) rather than a plain field.
 - **`onCreate(text)`** — offers `Add "<typed>"` when nothing matches. If creating the record
@@ -172,7 +342,12 @@ Everything else — the trigger, the card, the rows — stays flat.
 - [ ] Sorted A→Z inside the component, with `autoSort={false}` only where order is meaning
 - [ ] Multi-token filter
 - [ ] Searchable by default; `bare` is click-only; `searchable={false}` only on a short fixed enum the user is setting
-- [ ] Keyboard: ↑ ↓ Enter Esc Tab, active row scrolled into view
+- [ ] No overflow-clipping class (`overflow-hidden`, `overflow-*-auto`, `truncate`,
+      `line-clamp-*`) between the Combo and the scroller it belongs to; an over-wide chip
+      bounded at the chip (`min-w-0 truncate`)
+- [ ] Drop-up and list `maxHeight` measured against the clipping ancestors, not the window
+- [ ] Keyboard: ↑ ↓ Enter Esc Tab; the active row kept visible by scrolling the list only
+      (never `scrollIntoView`), and the search box focused with `preventScroll`
 - [ ] `aria-haspopup="listbox"`, `aria-expanded`, `role="listbox"` / `role="option"`,
       `aria-selected`, and an `aria-label` on the trigger
 - [ ] Loading and empty states (`"Nothing matches that."`)

package/references/softr-mcp.md

@@ -197,8 +197,15 @@ shapes, different payload type. The stringification happened on the client side,
 calls made while the tool definitions had not been loaded into the model's context (deferred
 schemas), so there was no type to serialise against. **Load the tool's schema before calling it,
 and pass arrays as arrays.** (Empty schemas are real on Softr's *per-application* MCP servers —
-every tool there is advertised as `{"type":"object"}` with a name-only description — but the
-workspace server is not affected.)
+every tool there is advertised as `{"type":"object"}` with a name-only description.)
+
+**Correction, 2026-09-30: the workspace server's tools can arrive schema-less too.** In one
+session every workspace tool loaded through ToolSearch showed only `{"type":"object"}` with a
+name-only description, and a `search_replace` call written with a real array was still sent as a
+string and rejected with the error above. Nothing was written, so the failure is safe, but no
+amount of care on the caller's side gets an array through a schema-less tool. Look at the
+loaded schema before relying on an array argument: if it has no `properties`, go straight to the
+fallback in the table — a full replace, one file per subagent for a large block, byte-verified.
 
 **Why the second row is a security problem, not an inconvenience.** Every code push resets the
 block's auto-registered Actions to Softr's defaults, and the default for a `genericActions`