softr-vibe-coding 2.14.5 → 2.15.1

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.15.1] - 2026-10-08
+- Release 2.15.1
+- softr-mcp: unicode escapes come back decoded on push
+
+## [2.15.0] - 2026-10-07
+- Release 2.15.0
+- Add the brand date picker reference
+
 ## [2.14.5] - 2026-10-07
 - Release 2.14.5
 - Document condition-based user groups over the MCP

package/README.md

@@ -261,16 +261,25 @@ softr-vibe-coding/
 │   │                                 # Imports, hook signatures, mutation shapes,
 │   │                                 # field mapping, component skeleton,
 │   │                                 # Softr navigation variables, container queries
-│   └── searchable-dropdown.md        # THE dropdown pattern for blocks
-│                                     # why native <select> and shadcn <Select> both
-│                                     # break in the shadow DOM, composedPath()
-│                                     # 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),
-│                                     # overflow-clipping ancestors: never clip a cell
-│                                     # holding a Combo, clip-aware drop-up + list
-│                                     # height, list-only scrolling (Sep 30 2026)
+│   ├── searchable-dropdown.md        # THE dropdown pattern for blocks
+│   │                                 # why native <select> and shadcn <Select> both
+│   │                                 # break in the shadow DOM, composedPath()
+│   │                                 # 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),
+│   │                                 # overflow-clipping ancestors: never clip a cell
+│   │                                 # holding a Combo, clip-aware drop-up + list
+│   │                                 # height, list-only scrolling (Sep 30 2026)
+│   └── date-picker.md                # THE date field for blocks: no native
+│                                     # <input type="date"> (its calendar is browser
+│                                     # UI no CSS reaches); the DatePicker kit (API +
+│                                     # full component), the kit-between-markers
+│                                     # convention + sync script, rollout lessons
+│                                     # (clipping, short modal bodies, textClass for
+│                                     # named containers, Escape, backdrop clicks,
+│                                     # deferred focus fix-up, Safari focus,
+│                                     # "yyyy-MM-dd" values), verification (Oct 7 2026)
 │
 ├── tools/                            # Bundled CLI scripts (run, not read)
 │   ├── get-airtable-base             # Full Airtable base schema export (bash + jq)

package/SKILL.md

@@ -95,13 +95,14 @@ 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). Opening a Combo moves focus into it (the search box, or the trigger on a click-only list), because Safari does not focus a clicked button. Escape on an open list closes only the list ([Move focus into the Combo when it opens](references/searchable-dropdown.md#move-focus-into-the-combo-when-it-opens))
+   - **No native date field** — no `<input type="date">`, `type="datetime-local"` or `type="month"` in a branded block: the browser draws its calendar pop-up, and no CSS reaches it. Use the module-scope `DatePicker` kit in [references/date-picker.md](references/date-picker.md), pasted verbatim between its marker lines (block-specific code, `textClass` included, stays outside them). Values stay `"yyyy-MM-dd"` strings, compared as strings. Same rules as the Combo: nothing between the field and its scroller clips, and Escape on an open calendar closes only the calendar
    - App page with Softr navigation: **no shadcn `<Dialog>` / `<Sheet>`** — its overlay is z-50, under Softr's top bar (z-index 800), and it portals out of the shadow root. Use the in-block modal (`fixed inset-0 z-[1000]`, rendered as a sibling of the block's `@container` wrapper, with its own Escape, focus trap, scroll lock and focus return) in [references/common-patterns.md → A modal above Softr's bars](references/common-patterns.md#a-modal-above-softrs-bars) (measured live 2026-10-06)
    - 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}>`
-   - **Deploying through the MCP:** `errors: null` on a push is not proof — compare the push result's `sourceSha256` with `shasum -a 256` of the file you sent, every byte counted, trailing newline included (Softr stores exactly what it receives; the one-byte drift we once blamed on it was a chunked read on our side). Prove deployed == disk *before* editing the same way, with `vibe_coding_block_get_code` and `includeCode: false`, so a Studio-side change is never overwritten. Fetch the full `sourceCode` only when a digest is missing or the hashes differ. Protocol in [references/softr-mcp.md → Verifying a push](references/softr-mcp.md#verifying-a-push--the-deployed-source-is-the-only-proof)
+   - **Deploying through the MCP:** `errors: null` on a push is not proof — compare the push result's `sourceSha256` with `shasum -a 256` of the file you sent, every byte counted, trailing newline included (Softr stores exactly the text that reaches it; the one-byte drift we once blamed on it was a chunked read on our side). No `\uXXXX` escapes in pushed source: they arrive decoded to the characters and the hashes differ, so write the characters themselves (with a comment saying why) or build them from code points (`String.fromCharCode(0x300)`); lone surrogates are the exception ([why](references/softr-mcp.md#unicode-escapes-come-back-decoded)). Prove deployed == disk *before* editing the same way, with `vibe_coding_block_get_code` and `includeCode: false`, so a Studio-side change is never overwritten. Fetch the full `sourceCode` only when a digest is missing or the hashes differ. Protocol in [references/softr-mcp.md → Verifying a push](references/softr-mcp.md#verifying-a-push--the-deployed-source-is-the-only-proof)
    - **Then check it in a browser.** Once the push checks pass, check rendering and behaviour in a fresh preview with saves blocked, per [references/browser-checks.md](references/browser-checks.md)
 
 ## What to Clarify
@@ -184,6 +185,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, Softr navigation variables (`--nav-height` etc.), container-query syntax | [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, focus moved into the Combo on open (Safari does not focus a clicked button) and Escape that closes only the list | [references/searchable-dropdown.md](references/searchable-dropdown.md) |
+| Any **date field** in a block — why `<input type="date">` can't carry a brand (its calendar is browser UI), the `DatePicker` kit (API, the full component), the kit-between-markers convention with a sync script for shared components, lessons from a 12-block rollout (clipping, short modal bodies, named containers and `textClass`, Escape, backdrop clicks, a modal's focus fix-up, Safari focus, `"yyyy-MM-dd"` values) and how to verify a block | [references/date-picker.md](references/date-picker.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, measuring the block's own width (not the window's), clearing Softr's sticky top bar and phone tab bar, an in-block modal above Softr's bars (instead of shadcn `Dialog`) | [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) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "softr-vibe-coding",
-  "version": "2.14.5",
+  "version": "2.15.1",
   "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/browser-checks.md

@@ -111,6 +111,10 @@ i.dispatchEvent(new Event('input', { bubbles: true }));
 i.dispatchEvent(new Event('change', { bubbles: true }));
 ```
 
+A block that uses the brand `DatePicker` ([date-picker.md](date-picker.md)) has no date input: the
+field is a button with a ref in `-i`. Click it, then click the day by its ref; each day is a button
+named like `Thursday, October 15, 2026`.
+
 ### 4. Block saves before any click, and prove it
 
 The preview writes to the live data

package/references/date-picker.md

@@ -0,0 +1,1107 @@
+# The brand date picker (`DatePicker`)
+
+**No native date field in a branded block.** `<input type="date">`, `type="datetime-local"` and
+`type="month"` open the browser's own calendar pop-up. That pop-up is browser UI, not page content,
+so no CSS reaches it, from the block or from the header code: it shows the browser's colours and
+fonts whatever the brand is. Use the `DatePicker` below instead. It draws its calendar in the
+block's own DOM, styled with the brand tokens, and takes and returns the same `"yyyy-MM-dd"`
+strings as the native field, so swapping one for the other changes nothing that is saved.
+
+| Option | Why it fails in a block, or doesn't |
+|---|---|
+| `<input type="date">` and friends | The calendar pop-up is the browser's: unstyled by any CSS, and different in Chrome, Safari and Firefox. |
+| shadcn `<Popover>` + `<Calendar>` | The Popover portals to `document.body`, outside the block's shadow root, like shadcn `<Select>` in [searchable-dropdown.md](searchable-dropdown.md) — so its styles would stay behind. Inferred from that same portal; not tried in a block. |
+| `DatePicker` (below) | Local DOM, brand-styled, keyboard grid, min / max, Today and Clear, clip-aware placement, `"yyyy-MM-dd"` in and out. |
+
+The kit picks a day. A time of day or a month-only value has no kit yet; build one on the same
+rules before adding the native field back.
+
+**Where it comes from.** On 2026-10-07 the Lane County Diaper Bank app (a Softr Database app with
+Softr's sidebar navigation) set out to replace all 21 native date fields across 12 blocks, after
+Leo flagged the browser calendar on the Reports page and again on Inventory's transaction history.
+The component was built once, checked in a React 18.2 shadow-root harness (22 checks, Chromium and
+macOS Firefox), pushed into the Reports and Volunteer Detail blocks first and checked there in a
+browser with saves blocked, then rolled out block by block, each reviewed before its push. The
+reviews produced the eight lessons below. Two of them (2 and 3) were faults in the component
+itself, fixed once in the kit and synced into every block; that sync is why the kit sits between
+markers.
+
+## The API
+
+Define it at **module scope**, never inside `Block()` (a component redefined per render remounts
+and loses focus, like the Combo).
+
+| Prop | Type | What it does |
+|---|---|---|
+| `id` | `string` | The trigger button's id. The calendar is `<id>-calendar`, the shown value `<id>-value`. |
+| `value` | `string` | `"yyyy-MM-dd"`, or `""` for none. A value that does not parse is shown as it is. |
+| `onChange` | `(next: string) => void` | Receives `"yyyy-MM-dd"`, or `""` from Clear. |
+| `min`, `max` | `string?` | `"yyyy-MM-dd"`. Days outside are dimmed and cannot be picked; the keyboard and the month arrows stop at them. |
+| `labelledBy` | `string?` | The label's id. The trigger is named by the label and the shown value, so it reads "Start date Oct 15, 2026". |
+| `describedBy` | `string?` | A hint or error message id, as on a text input. |
+| `placeholder` | `string?` | Shown while empty. Default `"Choose a date"`. |
+| `clearable` | `boolean?` | Adds a Clear button for optional dates. Default `false`. |
+| `disabled` | `boolean?` | Disables the trigger and closes an open calendar. |
+| `textClass` | `string?` | The trigger's text size classes. Default `"text-[16px] @min-[48rem]:text-[14px]"`; see lesson 3. |
+
+```tsx
+// A labelled field. The label keeps htmlFor: a click on it opens the calendar, as it focused the native field.
+<label id="start-label" htmlFor="start" className="mb-1.5 block text-[13px] font-medium">Start date</label>
+<DatePicker id="start" labelledBy="start-label" value={start} onChange={setStart} max={end} clearable />
+```
+
+Most blocks wrap it once, as they wrap their text inputs (a `DateField` with the label, or a
+`type="date"` branch in the block's own field component that renders `DatePicker` instead of an
+`<input>`). The wrapper lives outside the kit's markers, below.
+
+## The kit between markers
+
+A Vibe block is one file and cannot import another (Hard Constraint 22), so every block that uses
+the picker carries its own copy. Copies that are edited in place drift: a fix lands in the block
+that showed the bug and in no other. So the copy is never edited in a block. The convention:
+
+1. **One kit file in the project** holds the component, e.g. `Assets/Softr App/Shared/DatePicker.tsx`.
+   It is the only place the component is edited.
+2. **Each block pastes it verbatim, at module scope, between two marker lines.** The start line names
+   the kit file and the first 12 hex of its sha256:
+
+   ```tsx
+   // ===== DatePicker: verbatim copy of Shared/DatePicker.tsx sha256 4763ca393a6c - edit there, not here =====
+   /** DatePicker — brand-styled date field … (the kit file, byte for byte)
+   …
+   // ===== /DatePicker =====
+   ```
+
+3. **Anything block-specific stays outside the markers**: the `DateField` wrapper, the block's own
+   imports (merge the kit's three import lines into the block's), and every difference between blocks,
+   which goes through a prop (`textClass` exists for exactly that, lesson 3).
+4. **A fix is synced mechanically.** Edit the kit file, then rewrite every marked region from it and
+   check that none is left behind:
+
+   ```bash
+   cd "Assets/Softr App"   # the folder above the block folders; the marker records the kit path as given
+   python3 Shared/kit-sync.py sync  DatePicker Shared/DatePicker.tsx */*.jsx
+   python3 Shared/kit-sync.py check DatePicker Shared/DatePicker.tsx */*.jsx
+   ```
+
+   Each synced block is then a normal deploy: push it, prove the push by `sourceSha256`
+   ([softr-mcp.md → Verifying a push](softr-mcp.md#verifying-a-push--the-deployed-source-is-the-only-proof)),
+   re-apply its Action permissions (Hard Constraint 21: every save resets them) and update the
+   mirror's header date. The sha in the marker tells anyone reading a deployed block which kit it
+   carries without diffing 700 lines.
+
+`kit-sync.py` (stdlib Python, keep it beside the kit file; any component can use it — the first
+argument is the marker name):
+
+```python
+#!/usr/bin/env python3
+"""Keep a shared component pasted verbatim between marker lines in every block.
+
+  cd "Assets/Softr App"
+  python3 Shared/kit-sync.py check DatePicker Shared/DatePicker.tsx */*.jsx
+  python3 Shared/kit-sync.py sync  DatePicker Shared/DatePicker.tsx */*.jsx
+
+The kit's markers in a block (the start line names the kit file and the first 12 hex of its sha256):
+  // ===== DatePicker: verbatim copy of Shared/DatePicker.tsx sha256 f5753a191077 - edit there, not here =====
+  ...the kit file, byte for byte...
+  // ===== /DatePicker =====
+Blocks without the markers are skipped. check exits 1 when any copy differs from the kit; sync rewrites the
+copies that differ, and nothing outside the markers.
+"""
+import hashlib
+import re
+import sys
+
+
+def main():
+    if len(sys.argv) < 5 or sys.argv[1] not in ("check", "sync"):
+        sys.exit(__doc__)
+    mode, name, kit_path, blocks = sys.argv[1], sys.argv[2], sys.argv[3], sys.argv[4:]
+    with open(kit_path, encoding="utf-8", newline="") as f:  # newline="": bytes in, bytes out
+        kit = f.read()
+    if not kit.endswith("\n"):
+        sys.exit(kit_path + ": must end with a newline, or the end marker joins its last line")
+    sha = hashlib.sha256(kit.encode("utf-8")).hexdigest()[:12]
+    start_re = re.compile(r"^// ===== %s: verbatim copy of .*sha256 ([0-9a-f]+) .*=====\n" % re.escape(name), re.M)
+    end_re = re.compile(r"^// ===== /%s =====$" % re.escape(name), re.M)
+    start_line = "// ===== %s: verbatim copy of %s sha256 %s - edit there, not here =====\n" % (name, kit_path, sha)
+    bad = 0
+    for path in blocks:
+        with open(path, encoding="utf-8", newline="") as f:
+            src = f.read()
+        starts = list(start_re.finditer(src))
+        if not starts:
+            continue
+        end = end_re.search(src, starts[0].end())
+        if len(starts) > 1 or not end:
+            print("BROKEN " + path + ": " + ("two start markers" if end else "no end marker"))
+            bad += 1
+            continue
+        m = starts[0]
+        if src[m.end():end.start()] == kit and m.group(1) == sha:
+            print("ok     " + path)
+        elif mode == "check":
+            print("STALE  %s (marker %s, kit %s)" % (path, m.group(1), sha))
+            bad += 1
+        else:
+            with open(path, "w", encoding="utf-8", newline="") as f:
+                f.write(src[:m.start()] + start_line + kit + src[end.start():])
+            print("synced %s (%s -> %s)" % (path, m.group(1), sha))
+    sys.exit(1 if bad else 0)
+
+
+main()
+```
+
+Tested on 2026-10-07 on copies of two LCDB blocks: `check` passes against their kit, flags both as
+stale against a changed kit, `sync` rewrites only the marked region, and syncing back to the
+original kit gives a file byte-identical to the original block. Blocks without the markers are
+skipped.
+
+The same convention fits any shared component, the Combo in
+[searchable-dropdown.md](searchable-dropdown.md) included, whose "keep one canonical copy and port
+changes from there" it makes mechanical.
+
+## Lessons from the rollout
+
+**1. Nothing between the field and its scroller may clip.** The calendar is an absolute panel
+(`top-full` or `bottom-full`, `z-40`) inside the field's `relative` wrapper, in the block's own DOM,
+for the same reasons as the Combo's menu: a portal leaves the shadow root and its styles, and
+`position: fixed` breaks under any transformed ancestor
+([searchable-dropdown.md → Why not portal](searchable-dropdown.md#the-four-things-that-will-bite-you)).
+So every ancestor whose `overflow` is not `visible` clips it: `overflow-hidden`, `overflow-*-auto`,
+`truncate`, `line-clamp-*`. A card given `overflow-hidden` to clip its rounded corners cuts the
+calendar off at the card's edge. Same rule as Combo rule 1: no clipping class on anything that
+contains a date field; bound an over-wide child at the child. A scroller the field genuinely sits
+in (a modal body, a table scroller) is fine, because the placement measures it: the kit's
+`dpClipBox` walks every ancestor, out through the shadow host, as `comboClipBox` does.
+
+**2. In a short modal body, the calendar may scroll its trigger partly out of view.** The panel
+opens down when it fits below, up when it fits above. When it fits neither way, the box that cuts
+it off is scrolled by the smaller amount that makes room. When no scroll makes it fit, it opens
+down and scrolls the box as far as it can, and that limit is the trigger's **bottom** edge, not its
+top. The first version stopped at the trigger's top, to keep the whole field in view. In the
+family page's Add child modal, whose body is short and sized by its content, that left the
+calendar's Today / Clear row below the body's edge, cut off. Allowing the trigger to scroll
+partly away fixed it. Down is the fallback because what hangs past a scroller's bottom extends its
+scroll range, and what hangs past its top never does. The focused day is kept in view the same
+way: scroll the one clipping box, never `scrollIntoView` (it scrolls every ancestor, the page
+included), and issue the scroll from a `setTimeout` (Hard Constraint 17).
+
+**3. Blocks that size controls by named containers pass the text size in.** The trigger must
+look like the block's text inputs, text size included. The kit's default,
+`text-[16px] @min-[48rem]:text-[14px]`, matches inputs sized by the nearest container (16px on a
+narrow block, as inputs there must be so iOS does not zoom on focus). An unnamed `@min-[48rem]:`
+resolves against the nearest ancestor container, whatever its name, which need not be the
+container the block's own inputs are sized by.
+The family page sizes its fields by named containers (`@min-[48rem]/page:` on the page,
+`@min-[30rem]/panel:` inside its modal), and inside the modal the nearest container is the panel,
+which is at most 40rem wide, so the default never reached 14px: the date fields showed 16px text
+beside 14px inputs. The fix was a prop, not an edit inside the kit. Pass the input's own size
+classes, copied from the block's input class string, as a static string so Tailwind's scan finds
+them:
+
+```tsx
+<DatePicker … textClass="text-[16px] @min-[48rem]/page:text-[14px] @min-[30rem]/panel:text-[14px]" />
+```
+
+A block with no `@container` at all never matches the default's `@min-` class, so its trigger
+stays at 16px. Pass that block's own sizes too.
+
+**4. Escape on an open calendar closes only the calendar.** The panel's keydown handler (and the
+trigger's, while open) calls `e.preventDefault()` and `e.stopPropagation()`, closes the calendar
+and puts focus back on the trigger. An in-block modal listens for Escape on `document`
+([common-patterns.md → A modal above Softr's bars](common-patterns.md#a-modal-above-softrs-bars))
+and returns early on `defaultPrevented`; `stopPropagation` covers a document listener that does
+not check it. React's handler runs at the block's root, inside the shadow root, before the event
+reaches `document`. Without this, one Escape closes the calendar and the modal, or shows the modal's
+"Discard your changes?" prompt with the calendar still open. Same rule as the Combo's
+([Move focus into the Combo when it opens](searchable-dropdown.md#move-focus-into-the-combo-when-it-opens)).
+
+**5. A backdrop click while a calendar is open must not silently drop the form.** The calendar
+closes itself on `pointerdown` (a capture listener on `document`, read through `composedPath()`).
+The press continues, and its `click` lands on the modal's backdrop, which dismisses the modal. A
+form modal that dismisses without asking loses everything typed, for a click the user meant only
+to close a calendar. Two acceptable outcomes:
+
+- **Close only the calendar.** The modal records, at `pointerdown`, whether a calendar inside it
+  was open, and the backdrop's click returns early if so:
+
+  ```tsx
+  // In the modal's mount effect: registered before any calendar inside can open, so it runs before the
+  // calendar's own pointerdown close (capture listeners on one node run in registration order).
+  const onPointerDownCapture = () => {
+    pickerOpenAtDownRef.current = !!panel && !!panel.querySelector('[aria-haspopup="dialog"][aria-expanded="true"]');
+  };
+  document.addEventListener("pointerdown", onPointerDownCapture, true);
+  // …and in the effect's cleanup: document.removeEventListener("pointerdown", onPointerDownCapture, true);
+
+  // The backdrop:
+  onClick={() => {
+    if (pickerOpenAtDownRef.current) {
+      pickerOpenAtDownRef.current = false; // that press only closed the calendar
+      return;
+    }
+    dismissRef.current();
+  }}
+  ```
+
+  Read it at `pointerdown`, the event the calendar closes on: a `mousedown` listener may already find
+  it closed. A modal that also holds Combos (which close on `mousedown`) keeps its `mousedown` guard
+  for them as well.
+- **Ask.** The backdrop goes through the modal's dismiss request, which shows "Discard your
+  changes?" when anything was typed — the in-block modal's own rule for Escape, the X and Cancel.
+
+Either is fine. A backdrop that closes a dirty form without asking is not.
+
+**6. A modal's focus fix-up must wait one task.** Some in-block modals watch their panel with a
+`MutationObserver` and pull focus back to the panel when the focused control unmounts (Go back,
+Keep editing, a failed confirm), so Tab stays inside the dialog. The calendar closes on blur when
+Tab leaves it, so it unmounts in the middle of Tab's focus move. In Chromium, a synchronous
+`panel.focus()` from the observer at that moment cancels the move: Tab landed on the modal panel
+instead of the next field. Check one task later, and only refocus if focus really fell out:
+
+```tsx
+let observerTimer = 0;
+const observer = new MutationObserver(() => {
+  window.clearTimeout(observerTimer);
+  observerTimer = window.setTimeout(() => {
+    const a = root.activeElement as HTMLElement | null; // root = panel.getRootNode(): the shadow root
+    if (!panel.isConnected) return;
+    if (!a || a === document.body || !panel.contains(a)) panel.focus({ preventScroll: true });
+  }, 0);
+});
+observer.observe(panel, { childList: true, subtree: true });
+// cleanup: window.clearTimeout(observerTimer); observer.disconnect();
+```
+
+**7. Safari and macOS Firefox do not focus a clicked button.** Chrome does. So the kit never relies
+on the click: once the panel is placed, it moves focus itself to the active day (the selected day,
+else today, else the nearest day `min` / `max` allow), with `preventScroll`. On those browsers,
+focus would otherwise stay in the text field above the date field, and keys and Escape would go
+there. Two related details the kit handles: a blur with no `relatedTarget` (a click on nothing
+focusable, the window losing focus) is not a Tab out, so it leaves the calendar open for the
+click-outside listener to judge; and Chrome sends no `mousedown` for a disabled button (a dimmed
+day, Today out of range) but focuses the panel itself instead, so the panel hands that focus on to
+the active day. To reproduce Safari in any browser: focus a text field, call `.click()` on the
+trigger from the console (a synthetic click moves focus nowhere either), then read the block's
+shadow-root `activeElement`, which must be the day marked `data-dp-active="true"`.
+
+**8. Date-only values stay `"yyyy-MM-dd"` strings.** In, out, `min`, `max`:
+
+- **Compare as strings.** Zero-padded ISO days sort in date order, so `start <= end`,
+  `max={end}` and "not after today" need no `Date` at all.
+- **Load a stored date-only field by its first ten characters.** It arrives as midnight UTC
+  ([fields.md](../datasources/fields.md#date-only-fields-arrive-as-midnight-utc)), whose date part
+  is the intended day: `String(raw ?? "").slice(0, 10)`. Only for fields you know are date-only.
+- **Write the string back as it is.** That is what the native field sent, so the saved bytes don't
+  change (verify it, below).
+- **Display through a local date:** `toLocalDate()` from fields.md, or the kit's `dpParse`. Never
+  `new Date("yyyy-MM-dd")`, which is UTC midnight and a day early west of Greenwich.
+- **Today is the browser's local day:** `format(new Date(), "yyyy-MM-dd")`. Not
+  `new Date().toISOString().slice(0, 10)`, which is the UTC day: tomorrow, on a US evening.
+
+## Verifying a block
+
+**1. No native date field is left.** In the source, every hit of
+`grep -nE 'type="(date|datetime-local|month)"' <block files>` must be a prop on the block's own
+wrapper that renders the kit (`<FText type="date" …>`), never an `<input>`. Then in the preview,
+with every form and modal that holds a date field opened, the count across all shadow roots is 0
+([browser-checks.md](browser-checks.md) for the preview session and `eval`):
+
+```js
+(() => {
+  const roots = [...document.querySelectorAll('*')].map(e => e.shadowRoot).filter(Boolean);
+  const sel = 'input[type="date"], input[type="datetime-local"], input[type="month"]';
+  return roots.reduce((n, r) => n + r.querySelectorAll(sel).length, 0) + document.querySelectorAll(sel).length;
+})()
+```
+
+And `kit-sync.py check` passes, so every marked copy is the current kit.
+
+**2. Nothing clips or covers the open calendar.** Open the calendar in the tight spots: the last
+field of a modal body, a field low in a table scroller, near the window's right edge, at phone
+width (375px, above Softr's tab bar). Then hit-test points on the panel through the shadow root
+(`document.elementFromPoint` only returns the host):
+
+```js
+(() => {
+  const root = [...document.querySelectorAll('*')].map(e => e.shadowRoot).filter(Boolean)
+    .find(s => s.querySelector('[role="dialog"][id$="-calendar"]'));
+  if (!root) return 'no open calendar';
+  const panel = root.querySelector('[role="dialog"][id$="-calendar"]');
+  const r = panel.getBoundingClientRect();
+  const pts = { topLeft: [r.left + 6, r.top + 6], topRight: [r.right - 6, r.top + 6],
+                bottomLeft: [r.left + 6, r.bottom - 6], bottomRight: [r.right - 6, r.bottom - 6] };
+  for (const b of panel.querySelectorAll('button')) {
+    const t = b.textContent.trim();
+    if (t === 'Today' || t === 'Clear') { const q = b.getBoundingClientRect(); pts[t] = [q.left + q.width / 2, q.top + q.height / 2]; }
+  }
+  const out = {};
+  for (const [k, [x, y]] of Object.entries(pts)) { const el = root.elementFromPoint(x, y); out[k] = !!el && panel.contains(el); }
+  return JSON.stringify(out); // every value true; a false names the corner a clip or a bar covers
+})()
+```
+
+Wait a beat after opening: when the panel needs room, the placement scrolls a box from a
+`setTimeout`.
+
+**3. Escape order.** With real key presses (`ab press Escape`), in a modal with something typed in
+another field and the calendar open: the first Escape closes the calendar only (the modal is open,
+no discard prompt, focus is on the date field's trigger); the second Escape reaches the modal
+(it closes, or asks to discard). Then the backdrop case of lesson 5, and Tab out of the open calendar
+inside the modal: focus lands on the next field, not on the modal panel (lesson 6).
+
+**4. The saved value is byte-identical to the native version's.** Block saves first
+([browser-checks.md → Block saves before any click, and prove it](browser-checks.md#4-block-saves-before-any-click-and-prove-it)),
+pick a day, save, and read the aborted request's payload: the field holds the same string the native
+field sent for that day (`"2026-10-15"`, not a timestamp). Clear sends what an emptied native field
+sent, unless the block deliberately changed it (one LCDB block now saves a cleared optional date as
+`null`).
+
+## Re-skinning the kit
+
+The tokens sit in `DP_C` at the top, and the Tailwind class strings repeat some of them as literal
+hex, because a class string cannot read a constant (each string has a comment saying which hex is
+which token). Change both, with a find-and-replace per hex over the kit file:
+
+| Token | Kit value (LCDB) | Used for |
+|---|---|---|
+| `primary` | `#680058` | Selected day, today's ring, focus rings, Today button, the open trigger's border |
+| `primaryDeep` | `#4E0042` | Hover on the selected day |
+| `primaryTint` | `#F5EAF3` | Hover on Today |
+| `ink` | `#030712` | Text |
+| `muted` | `#6B7280` | Placeholder, weekday names, days of the next and previous month |
+| `canvas` | `#F3F4F6` | Hover on days and icon buttons |
+| `border` | `#D1D5DB` | Trigger and panel border |
+| `divider` | `#E5E7EB` | The rule above Today / Clear (inline only) |
+| `faint` | `#C4C8CF` | Days outside `min` / `max` |
+
+Also: `DP_FONT_BODY` (the trigger's value, as the block's text inputs) and `DP_FONT_DISPLAY` (the
+calendar), the trigger's height and radius in `DP_TRIGGER` (match the block's inputs), and
+`DP_SOFTR_TOP_BAR`: `0` as verified (LCDB has no top bar), `56` when the app shows Softr's sticky
+top bar, so the calendar never opens up under it (untested at 56; the bar heights are in
+[searchable-dropdown.md](searchable-dropdown.md#the-four-things-that-will-bite-you)). After a
+re-skin, the kit file's sha changes; sync it into every block.
+
+## The kit file
+
+Below is the whole kit, ready to save as the project's kit file. It is the LCDB kit (sha256
+`f5753a191077…`, deployed 2026-10-07) with its comments made client-neutral and `DP_SOFTR_TOP_BAR`
+added; at `0` it behaves exactly as deployed. This copy (sha256 `4763ca393a6c…`) passed the same
+22 harness checks in Chromium 149 on 2026-10-07; the Firefox run was not repeated for it.
+
+<details>
+<summary>DatePicker.tsx (694 lines)</summary>
+
+```tsx
+/** DatePicker — brand-styled date field for Softr Vibe Coding blocks, replacing native <input type="date">: its
+ * calendar pop-up is browser UI that no CSS reaches, so this one is drawn in the block's own DOM. Paste everything below
+ * this comment at MODULE scope (never inside Block()). From softr-vibe-coding references/date-picker.md: the Lane County
+ * Diaper Bank kit of 2026-10-07 (sha256 f5753a191077), comments generalized and DP_SOFTR_TOP_BAR added (0 = the
+ * verified behaviour). That kit passed 22 checks in a React 18.2 shadow-root harness with Tailwind v4 (Chromium 149 and
+ * macOS Firefox 157, TZ America/Los_Angeles, today fixed at 2026-10-07) and shipped in 12 blocks.
+ *
+ * Imports it needs (merge the names into the block's existing import lines):
+ *   import { useEffect, useLayoutEffect, useRef, useState } from "react";
+ *   import { CalendarDays, ChevronLeft, ChevronRight } from "lucide-react";
+ *   import { addDays, addMonths, addYears, format, startOfMonth, startOfWeek } from "date-fns";
+ *
+ * Usage:
+ *   <label id="start-label" htmlFor="start">Start date</label>
+ *   <DatePicker id="start" labelledBy="start-label" value={start} onChange={setStart} max={end} clearable />
+ * value, min and max are "yyyy-MM-dd" strings or ""; onChange(next) receives "yyyy-MM-dd", or "" from Clear.
+ * textClass sets the trigger's text size. The default suits blocks that size controls by the nearest container; a block
+ * that sizes them by named containers passes its own (e.g. "text-[16px] @min-[48rem]/page:text-[14px]").
+ * The label's htmlFor may stay: a click on the label opens the picker, as it focuses a native date field.
+ * Nothing between the field and the scroller it belongs to may clip (overflow-hidden, truncate, line-clamp): the
+ * calendar is an absolute panel in the block's DOM (softr-vibe-coding references/searchable-dropdown.md, rule 1).
+ */
+
+// Brand tokens this component uses (the project's DESIGN.md): a copy, because blocks cannot import each other (Hard
+// Constraint 22). Tailwind class strings repeat some as literal hex; each says which. Re-skin both.
+const DP_C = {
+  primary: "#680058",
+  primaryDeep: "#4E0042", // hover on primary
+  primaryTint: "#F5EAF3",
+  ink: "#030712",
+  muted: "#6B7280", // labels, weekday names, days of the next and previous month
+  canvas: "#F3F4F6", // hover on days and icon buttons
+  border: "#D1D5DB",
+  divider: "#E5E7EB",
+  faint: "#C4C8CF", // days outside min / max: dimmed, not selectable (not a text colour for anything to read)
+} as const;
+const DP_SHADOW_MENU = "0 8px 24px rgba(3,7,18,0.08)";
+const DP_FONT_BODY = "Verdana, Geneva, 'DejaVu Sans', Tahoma, sans-serif"; // the field's value, as in the text inputs
+const DP_FONT_DISPLAY = "'Poppins', ui-sans-serif, system-ui, sans-serif"; // the calendar: heading, days, buttons
+const DP_PANEL_REM = 18.5; // panel width: 296px, fits a 343px phone content column
+const DP_GAP = 4; // trigger to panel
+const DP_EDGE = 8; // room kept free at the edges of the strip the panel can paint into
+const DP_SOFTR_TAB_BAR = 57; // Softr's phone tab bar, window below 768px: measured 57px
+const DP_SOFTR_TOP_BAR = 0; // 56 when the app shows Softr's sticky top bar (window 768px and up); untested at 56
+const DP_WEEKDAYS = [
+  ["Su", "Sunday"],
+  ["Mo", "Monday"],
+  ["Tu", "Tuesday"],
+  ["We", "Wednesday"],
+  ["Th", "Thursday"],
+  ["Fr", "Friday"],
+  ["Sa", "Saturday"],
+] as const;
+
+// Days: a 36px circle in a ~39px column. Hover lives in classes (inline would beat it).
+// #680058 = DP_C.primary · #4E0042 = DP_C.primaryDeep · #030712 = DP_C.ink · #6B7280 = DP_C.muted
+// #F3F4F6 = DP_C.canvas · #C4C8CF = DP_C.faint
+const DP_DAY =
+  "mx-auto flex h-9 w-9 items-center justify-center rounded-full text-[14px] leading-none transition-colors focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-[#680058]";
+const DP_DAY_SELECTED = "bg-[#680058] font-semibold text-white hover:bg-[#4E0042]";
+const DP_DAY_TODAY = "font-semibold text-[#680058] hover:bg-[#F3F4F6]";
+const DP_DAY_IN = "text-[#030712] hover:bg-[#F3F4F6]";
+const DP_DAY_OUT = "text-[#6B7280] hover:bg-[#F3F4F6]";
+const DP_DAY_OFF = "cursor-default text-[#C4C8CF]";
+// Months in the month / year view: same states, as 44px pills.
+const DP_MONTH =
+  "flex h-11 w-full items-center justify-center rounded-full text-[14px] transition-colors focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-[#680058]";
+// Month arrows: 44px targets. aria-disabled (not disabled), so an arrow keeps focus when it reaches min or max.
+const DP_ICON_BTN =
+  "flex h-11 w-11 items-center justify-center rounded-full transition-colors hover:bg-[#F3F4F6] focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-[#680058] aria-disabled:cursor-default aria-disabled:opacity-35 aria-disabled:hover:bg-transparent";
+// The trigger is the blocks' text input: 44px. Its text size comes from the textClass prop: by default 16px below a
+// 48rem container (stops iOS zoom) and 14px from it.
+// #D1D5DB = DP_C.border · #680058 = DP_C.primary (focus border and ring; kept while the calendar is open)
+const DP_TRIGGER =
+  "flex h-11 w-full items-center justify-between gap-2 rounded-xl border border-[#D1D5DB] bg-white px-3 text-left transition-colors focus:border-[#680058] focus:outline-none focus:ring-2 focus:ring-[#680058]/25 aria-expanded:border-[#680058] aria-expanded:ring-2 aria-expanded:ring-[#680058]/25 disabled:cursor-not-allowed disabled:opacity-60";
+
+type DpPlace = { up: boolean; x: number; maxW: number | null; ready: boolean };
+
+// "yyyy-MM-dd" -> a local-midnight Date, or null. Never new Date("yyyy-MM-dd"): that is UTC midnight, a day early
+// west of Greenwich. Rejects impossible dates (2026-02-30) instead of rolling them over.
+function dpParse(s: string | null | undefined): Date | null {
+  const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(String(s ?? "").trim());
+  if (!m) return null;
+  const y = Number(m[1]);
+  const mo = Number(m[2]) - 1;
+  const day = Number(m[3]);
+  const d = new Date(2000, 0, 1);
+  d.setFullYear(y, mo, day); // setFullYear: years below 100 stay themselves
+  return d.getFullYear() === y && d.getMonth() === mo && d.getDate() === day ? d : null;
+}
+const dpIso = (d: Date) => format(d, "yyyy-MM-dd");
+const dpKey = (d: Date) => d.getFullYear() * 10000 + d.getMonth() * 100 + d.getDate(); // compare days, not times
+function dpToday() {
+  const n = new Date();
+  return new Date(n.getFullYear(), n.getMonth(), n.getDate());
+}
+function dpAllowed(d: Date, min: Date | null, max: Date | null) {
+  return (!min || dpKey(d) >= dpKey(min)) && (!max || dpKey(d) <= dpKey(max));
+}
+function dpClamp(d: Date, min: Date | null, max: Date | null) {
+  if (min && dpKey(d) < dpKey(min)) return min;
+  if (max && dpKey(d) > dpKey(max)) return max;
+  return d;
+}
+
+// The strip of screen the panel can paint into: the window (minus Softr's bars), cut down by every ancestor that
+// clips, as comboClipBox in searchable-dropdown.md. Also returns the boxes that set the top and bottom edges (null =
+// the window), for the nudge in dpPlace.
+function dpClipBox(node: HTMLElement) {
+  const phone = window.innerWidth < 768;
+  let top = phone ? 0 : DP_SOFTR_TOP_BAR;
+  let left = 0;
+  let right = window.innerWidth;
+  let bottom = window.innerHeight - (phone ? DP_SOFTR_TAB_BAR : 0);
+  let topEl: HTMLElement | null = null;
+  let bottomEl: HTMLElement | null = null;
+  let el: any = node;
+  while (el && el !== document.body && el !== document.documentElement) {
+    // clientHeight / clientWidth are 0 for the boxes overflow does not apply to (inline, display: contents)
+    if (el.clientHeight > 0 || el.clientWidth > 0) {
+      const cs = window.getComputedStyle(el);
+      const r = el.getBoundingClientRect();
+      if (cs.overflowY !== "visible") {
+        const t = r.top + el.clientTop; // the clip edge is the padding box: inside the border
+        const b = t + el.clientHeight; //  and above a horizontal scrollbar
+        if (t > top) {
+          top = t;
+          topEl = el;
+        }
+        if (b < bottom) {
+          bottom = b;
+          bottomEl = el;
+        }
+      }
+      if (cs.overflowX !== "visible") {
+        const l = r.left + el.clientLeft;
+        const rr = l + el.clientWidth;
+        if (l > left) left = l;
+        if (rr < right) right = rr;
+      }
+    }
+    // Where the parent chain ends at the shadow root, carry on from its host.
+    el = el.parentElement || (el.getRootNode ? (el.getRootNode() as any).host : null) || null;
+  }
+  return { top, bottom, left, right, topEl, bottomEl };
+}
+
+// Can this edge box (null = the window) be scrolled, and how far is it scrolled now?
+function dpScrollable(el: HTMLElement | null) {
+  return el
+    ? /(auto|scroll)/.test(window.getComputedStyle(el).overflowY)
+    : window.getComputedStyle(document.documentElement).overflowY !== "hidden";
+}
+
+// focus({ preventScroll: true }) does not reveal what it focuses. When the active day sits past the edge of the box
+// that clips it (a short modal body), scroll that one box just far enough; never scrollIntoView, which scrolls every
+// ancestor including the page.
+function dpKeepVisible(el: HTMLElement) {
+  const clip = dpClipBox(el);
+  const r = el.getBoundingClientRect();
+  if (r.bottom > clip.bottom - DP_EDGE && dpScrollable(clip.bottomEl)) {
+    const by = r.bottom - (clip.bottom - DP_EDGE);
+    if (clip.bottomEl) clip.bottomEl.scrollTop += by;
+    else window.scrollBy(0, by);
+  } else if (r.top < clip.top + DP_EDGE && dpScrollable(clip.topEl)) {
+    const by = clip.top + DP_EDGE - r.top;
+    if (clip.topEl) clip.topEl.scrollTop -= by;
+    else window.scrollBy(0, -by);
+  }
+}
+
+// Where the panel goes. Down when it fits below, else up when it fits above. When it fits neither way (a short modal
+// body, a small window), the box that cuts it off is nudged by the smaller scroll that makes it fit with the trigger
+// still in view: up into room above (only as far as that box is scrolled down), or down into room below. When no
+// nudge makes it fit: down, scrolled as far as the trigger allows, so the rest can be scrolled to (what hangs past a
+// scroller's bottom extends its scroll range; past its top it never does); with no scroller at all, the larger side.
+// Horizontally it hangs from the trigger's left edge and shifts left to stay inside the strip.
+function dpPlace(wrapper: HTMLElement, panelH: number) {
+  const clip = dpClipBox(wrapper);
+  const r = wrapper.getBoundingClientRect();
+  const below = clip.bottom - r.bottom - DP_GAP - DP_EDGE;
+  const above = r.top - clip.top - DP_GAP - DP_EDGE;
+  let up = below < panelH && above >= panelH;
+  let scroller: HTMLElement | Window | null = null;
+  let scrollBy = 0; // positive scrolls down (the content moves up)
+  if (below < panelH && above < panelH) {
+    const needUp = panelH - above; // scroll the top box back this far to make room above
+    const needDown = panelH - below; // scroll the bottom box on this far to make room below
+    const topScroll = clip.topEl ? clip.topEl.scrollTop : window.scrollY;
+    const canUp =
+      dpScrollable(clip.topEl) && topScroll >= needUp && r.bottom + needUp <= clip.bottom - DP_EDGE;
+    const canDown = dpScrollable(clip.bottomEl);
+    const downFits = canDown && r.top - needDown >= clip.top + DP_EDGE;
+    if (canUp && (!downFits || needUp <= needDown)) {
+      up = true;
+      scroller = clip.topEl || window;
+      scrollBy = -needUp;
+    } else if (canDown) {
+      up = false;
+      scroller = clip.bottomEl || window;
+      // Up to the trigger's bottom edge, not its top: in a short modal body the whole calendar then fits, and only
+      // part of the trigger scrolls out of view.
+      scrollBy = Math.max(0, Math.min(needDown, r.bottom - clip.top - DP_EDGE));
+    } else {
+      up = above > below;
+    }
+  }
+  const remPx = parseFloat(window.getComputedStyle(document.documentElement).fontSize) || 16;
+  const room = clip.right - clip.left - 2 * DP_EDGE;
+  const w = Math.min(DP_PANEL_REM * remPx, Math.max(256, room));
+  let x = 0;
+  if (r.left + w > clip.right - DP_EDGE) x = clip.right - DP_EDGE - w - r.left;
+  if (r.left + x < clip.left + DP_EDGE) x = clip.left + DP_EDGE - r.left;
+  return { up, x: Math.round(x), maxW: w < DP_PANEL_REM * remPx ? Math.floor(w) : null, scroller, scrollBy };
+}
+
+function DatePicker({
+  id,
+  value,
+  onChange,
+  placeholder = "Choose a date",
+  min,
+  max,
+  labelledBy,
+  describedBy,
+  clearable = false,
+  disabled = false,
+  textClass = "text-[16px] @min-[48rem]:text-[14px]",
+}: {
+  id: string;
+  value: string;
+  onChange: (next: string) => void;
+  placeholder?: string;
+  min?: string;
+  max?: string;
+  labelledBy?: string;
+  describedBy?: string;
+  clearable?: boolean;
+  disabled?: boolean;
+  textClass?: string;
+}) {
+  const rootRef = useRef<HTMLDivElement | null>(null);
+  const triggerRef = useRef<HTMLButtonElement | null>(null);
+  const panelRef = useRef<HTMLDivElement | null>(null);
+  const focusPending = useRef(false); // move focus to the active day / month after the next render
+  const triggerPointer = useRef(false); // a pointer press on the trigger is under way (its click toggles)
+  const [open, setOpen] = useState(false);
+  const [view, setView] = useState<"days" | "months">("days");
+  const [focusDate, setFocusDate] = useState<Date>(() => dpToday());
+  const [today, setToday] = useState<Date>(() => dpToday());
+  const [place, setPlace] = useState<DpPlace>({ up: false, x: 0, maxW: null, ready: false });
+
+  const selected = dpParse(value);
+  const minD = dpParse(min);
+  const maxD = dpParse(max);
+  const shown = selected ? format(selected, "MMM d, yyyy") : value; // an unreadable value is shown as it is
+  const dialogId = `${id}-calendar`;
+  const valueId = `${id}-value`;
+  const monthLabelId = `${id}-month`;
+
+  function openPicker() {
+    if (disabled) return;
+    const t = dpToday();
+    setToday(t);
+    // The selected day, else today, else the nearest day min / max allow.
+    setFocusDate(dpClamp(selected || t, minD, maxD));
+    setView("days");
+    setPlace({ up: false, x: 0, maxW: null, ready: false });
+    focusPending.current = true;
+    setOpen(true);
+  }
+  function closePicker(refocus: boolean) {
+    setOpen(false);
+    setView("days");
+    focusPending.current = false;
+    if (refocus) triggerRef.current?.focus({ preventScroll: true });
+  }
+  function pick(d: Date) {
+    if (!dpAllowed(d, minD, maxD)) return;
+    onChange(dpIso(d));
+    closePicker(true);
+  }
+  function moveTo(d: Date) {
+    focusPending.current = true;
+    setFocusDate(dpClamp(d, minD, maxD));
+  }
+
+  // Place the panel before it paints: measured hidden, then shown up or down, shifted to stay inside the strip.
+  useLayoutEffect(() => {
+    if (!open) return;
+    const wrap = rootRef.current;
+    const panel = panelRef.current;
+    if (!wrap || !panel) return;
+    const p = dpPlace(wrap, panel.offsetHeight);
+    setPlace({ up: p.up, x: p.x, maxW: p.maxW, ready: true });
+    if (p.scroller && p.scrollBy !== 0) {
+      const sc = p.scroller;
+      const by = p.scrollBy;
+      // Hard Constraint 17: programmatic scrolls go through setTimeout. Only this one box scrolls (no scrollIntoView).
+      window.setTimeout(() => {
+        if (sc === window) window.scrollBy(0, by);
+        else (sc as HTMLElement).scrollTop += by;
+      }, 0);
+    }
+  }, [open]);
+
+  // Move focus into the calendar on open, and onto the active day or month after keyboard moves and view changes.
+  // Done here, not by the click: Safari and macOS Firefox do not focus a clicked button, and a synthetic .click()
+  // moves focus nowhere. preventScroll: focusing must not scroll the page or a modal body.
+  useEffect(() => {
+    if (!open || !place.ready || !focusPending.current) return;
+    focusPending.current = false;
+    const el = panelRef.current?.querySelector('[data-dp-active="true"]') as HTMLElement | null;
+    if (!el) return;
+    el.focus({ preventScroll: true });
+    // After the placement's own scroll (queued first, so it runs first).
+    window.setTimeout(() => {
+      if (el.isConnected) dpKeepVisible(el);
+    }, 0);
+  });
+
+  // Click outside closes: pointerdown on the document, read through composedPath() because the shadow root
+  // retargets the event's target to the block's host.
+  useEffect(() => {
+    if (!open) return;
+    const onDown = (e: PointerEvent) => {
+      const root = rootRef.current;
+      if (!root) return;
+      const path = e.composedPath ? e.composedPath() : [];
+      if (path.indexOf(root) !== -1) return;
+      if (path.length === 0 && e.target && root.contains(e.target as Node)) return;
+      closePicker(false);
+    };
+    document.addEventListener("pointerdown", onDown, true);
+    return () => document.removeEventListener("pointerdown", onDown, true);
+  }, [open]);
+
+  // A window resize (a turned tablet) re-places the open panel.
+  useEffect(() => {
+    if (!open) return;
+    const onResize = () => {
+      const wrap = rootRef.current;
+      const panel = panelRef.current;
+      if (!wrap || !panel) return;
+      const p = dpPlace(wrap, panel.offsetHeight);
+      setPlace({ up: p.up, x: p.x, maxW: p.maxW, ready: true });
+    };
+    window.addEventListener("resize", onResize);
+    return () => window.removeEventListener("resize", onResize);
+  }, [open]);
+
+  useEffect(() => {
+    if (disabled && open) closePicker(false);
+  }, [disabled, open]);
+
+  // Keyboard on the day grid (WAI-ARIA date picker dialog). Enter and Space are the buttons' own clicks.
+  function onDayKey(e: React.KeyboardEvent) {
+    const d = focusDate;
+    let next: Date | null = null;
+    if (e.key === "ArrowLeft") next = addDays(d, -1);
+    else if (e.key === "ArrowRight") next = addDays(d, 1);
+    else if (e.key === "ArrowUp") next = addDays(d, -7);
+    else if (e.key === "ArrowDown") next = addDays(d, 7);
+    else if (e.key === "Home") next = startOfWeek(d, { weekStartsOn: 0 });
+    else if (e.key === "End") next = addDays(startOfWeek(d, { weekStartsOn: 0 }), 6);
+    else if (e.key === "PageUp") next = e.shiftKey ? addYears(d, -1) : addMonths(d, -1);
+    else if (e.key === "PageDown") next = e.shiftKey ? addYears(d, 1) : addMonths(d, 1);
+    else if (e.key === "Enter" && e.repeat) e.preventDefault(); // a held Enter that opened the picker must not pick
+    if (!next) return;
+    e.preventDefault();
+    moveTo(next);
+  }
+  function onMonthKey(e: React.KeyboardEvent) {
+    const d = focusDate;
+    let next: Date | null = null;
+    if (e.key === "ArrowLeft") next = addMonths(d, -1);
+    else if (e.key === "ArrowRight") next = addMonths(d, 1);
+    else if (e.key === "ArrowUp") next = addMonths(d, -3);
+    else if (e.key === "ArrowDown") next = addMonths(d, 3);
+    else if (e.key === "Home") next = addMonths(d, -d.getMonth());
+    else if (e.key === "End") next = addMonths(d, 11 - d.getMonth());
+    else if (e.key === "PageUp") next = addYears(d, -1);
+    else if (e.key === "PageDown") next = addYears(d, 1);
+    else if (e.key === "Enter" && e.repeat) e.preventDefault();
+    if (!next) return;
+    e.preventDefault();
+    moveTo(next);
+  }
+  function chooseMonth(m: number) {
+    // Same day of the month where it exists (addMonths clamps the 31st), inside min / max.
+    moveTo(addMonths(focusDate, m - focusDate.getMonth()));
+    setView("days");
+  }
+
+  // The month on show and the arrows' limits.
+  const monthStart = startOfMonth(focusDate);
+  const year = focusDate.getFullYear();
+  const prevOff =
+    view === "days"
+      ? !!minD && dpKey(addDays(monthStart, -1)) < dpKey(minD)
+      : !!minD && year - 1 < minD.getFullYear();
+  const nextOff =
+    view === "days"
+      ? !!maxD && dpKey(addMonths(monthStart, 1)) > dpKey(maxD)
+      : !!maxD && year + 1 > maxD.getFullYear();
+  function step(dir: -1 | 1) {
+    if (dir < 0 ? prevOff : nextOff) return;
+    const next = dpClamp(view === "days" ? addMonths(focusDate, dir) : addYears(focusDate, dir), minD, maxD);
+    setFocusDate(next); // a click on an arrow leaves focus on the arrow
+  }
+  const todayOff = !dpAllowed(today, minD, maxD);
+
+  const gridStart = startOfWeek(monthStart, { weekStartsOn: 0 });
+  const weeks: Date[][] = [];
+  for (let w = 0; w < 6; w++) {
+    const row: Date[] = [];
+    for (let i = 0; i < 7; i++) row.push(addDays(gridStart, w * 7 + i));
+    weeks.push(row);
+  }
+  const heading = view === "days" ? format(focusDate, "MMMM yyyy") : String(year);
+
+  return (
+    <div ref={rootRef} className="relative">
+      <button
+        ref={triggerRef}
+        id={id}
+        type="button"
+        disabled={disabled}
+        aria-haspopup="dialog"
+        aria-expanded={open}
+        aria-controls={dialogId}
+        aria-labelledby={labelledBy ? `${labelledBy} ${valueId}` : undefined}
+        aria-describedby={describedBy}
+        onPointerDown={() => {
+          triggerPointer.current = true;
+        }}
+        onClick={() => {
+          triggerPointer.current = false;
+          if (open) closePicker(true);
+          else openPicker();
+        }}
+        onKeyDown={(e) => {
+          triggerPointer.current = false;
+          if (!open && e.key === "ArrowDown") {
+            e.preventDefault();
+            openPicker();
+          } else if (open && e.key === "Escape") {
+            e.preventDefault();
+            e.stopPropagation();
+            closePicker(false);
+          }
+        }}
+        className={DP_TRIGGER + " " + textClass}
+        style={{ fontFamily: DP_FONT_BODY, color: shown ? DP_C.ink : DP_C.muted }}
+      >
+        <span id={valueId} className="min-w-0 truncate">
+          {shown || placeholder}
+        </span>
+        <CalendarDays
+          className="h-[18px] w-[18px] shrink-0"
+          style={{ color: open ? DP_C.primary : DP_C.muted }}
+          aria-hidden="true"
+        />
+      </button>
+
+      {open ? (
+        <div
+          ref={panelRef}
+          id={dialogId}
+          role="dialog"
+          aria-label="Choose a date"
+          tabIndex={-1}
+          onMouseDown={(e) => {
+            // A press on the padding or a weekday name leaves focus on the active day, so the keys keep working.
+            if (!(e.target as HTMLElement).closest("button")) e.preventDefault();
+          }}
+          onFocus={(e) => {
+            // Chrome sends no mousedown for a disabled button (a dimmed day, Today out of range) and focuses the
+            // panel itself instead: hand that focus on to the active day or month.
+            if (e.target !== e.currentTarget) return;
+            const el = e.currentTarget.querySelector('[data-dp-active="true"]') as HTMLElement | null;
+            el?.focus({ preventScroll: true });
+          }}
+          onKeyDown={(e) => {
+            if (e.key !== "Escape") return;
+            // Escape closes this calendar and nothing else: preventDefault for a surrounding modal that checks
+            // defaultPrevented, stopPropagation for any document listener that does not.
+            e.preventDefault();
+            e.stopPropagation();
+            closePicker(true);
+          }}
+          onBlur={(e) => {
+            // Tab or Shift+Tab out of the calendar closes it. A null relatedTarget (a click on nothing focusable,
+            // the window losing focus) is not a leave: clicks outside are the pointerdown listener's job.
+            const next = e.relatedTarget as Node | null;
+            if (!next || panelRef.current?.contains(next)) return;
+            if (next === triggerRef.current && triggerPointer.current) return; // the trigger's click will toggle
+            closePicker(false);
+          }}
+          className={`absolute z-40 w-[18.5rem] rounded-xl border bg-white p-3 outline-none ${
+            place.up ? "bottom-full mb-1" : "top-full mt-1"
+          }`}
+          style={{
+            left: place.x,
+            maxWidth: place.maxW ?? undefined,
+            visibility: place.ready ? "visible" : "hidden",
+            borderColor: DP_C.border,
+            boxShadow: DP_SHADOW_MENU,
+            fontFamily: DP_FONT_DISPLAY,
+            color: DP_C.ink,
+          }}
+        >
+          <div className="flex items-center justify-between">
+            <button
+              type="button"
+              aria-label={view === "days" ? `${heading}, choose month and year` : `${heading}, back to days`}
+              onClick={() => {
+                focusPending.current = true;
+                setView(view === "days" ? "months" : "days");
+              }}
+              // #F3F4F6 = DP_C.canvas · #680058 = DP_C.primary
+              className="-ml-1 inline-flex h-11 items-center gap-1 rounded-full pl-2.5 pr-2 text-[15px] font-semibold transition-colors hover:bg-[#F3F4F6] focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-[#680058]"
+            >
+              {heading}
+              <ChevronRight
+                className={`h-4 w-4 transition-transform ${view === "days" ? "rotate-90" : "-rotate-90"}`}
+                style={{ color: DP_C.muted }}
+                aria-hidden="true"
+              />
+            </button>
+            <div className="-mr-1.5 flex items-center">
+              <button
+                type="button"
+                aria-label={view === "days" ? "Previous month" : "Previous year"}
+                aria-disabled={prevOff || undefined}
+                onClick={() => step(-1)}
+                className={DP_ICON_BTN}
+              >
+                <ChevronLeft className="h-[18px] w-[18px]" aria-hidden="true" />
+              </button>
+              <button
+                type="button"
+                aria-label={view === "days" ? "Next month" : "Next year"}
+                aria-disabled={nextOff || undefined}
+                onClick={() => step(1)}
+                className={DP_ICON_BTN}
+              >
+                <ChevronRight className="h-[18px] w-[18px]" aria-hidden="true" />
+              </button>
+            </div>
+          </div>
+
+          {/* Announces the month as keys move through it; also the grid's name. */}
+          <div id={monthLabelId} aria-live="polite" className="sr-only">
+            {format(focusDate, "MMMM yyyy")}
+          </div>
+
+          {/* Both views are the same height, so switching never moves the panel. */}
+          <div className="mt-1 h-[16rem]">
+            {view === "days" ? (
+              <table
+                role="grid"
+                aria-labelledby={monthLabelId}
+                className="w-full table-fixed border-collapse"
+                onKeyDown={onDayKey}
+              >
+                <thead>
+                  <tr>
+                    {DP_WEEKDAYS.map(([short, long]) => (
+                      <th
+                        key={short}
+                        scope="col"
+                        abbr={long}
+                        className="h-7 p-0 text-center text-[12px] font-medium"
+                        style={{ color: DP_C.muted }}
+                      >
+                        {short}
+                      </th>
+                    ))}
+                  </tr>
+                </thead>
+                <tbody>
+                  {weeks.map((row, w) => (
+                    <tr key={w}>
+                      {row.map((d, i) => {
+                        const isSel = !!selected && dpKey(d) === dpKey(selected);
+                        const isToday = dpKey(d) === dpKey(today);
+                        const inMonth = d.getMonth() === focusDate.getMonth();
+                        const ok = dpAllowed(d, minD, maxD);
+                        const active = dpKey(d) === dpKey(focusDate);
+                        const tone = isSel
+                          ? DP_DAY_SELECTED
+                          : !ok
+                            ? DP_DAY_OFF
+                            : isToday
+                              ? DP_DAY_TODAY
+                              : inMonth
+                                ? DP_DAY_IN
+                                : DP_DAY_OUT;
+                        return (
+                          // Keyed by position, so a month change keeps the focused button in the DOM.
+                          <td key={i} role="gridcell" aria-selected={isSel} className="p-0 py-px text-center">
+                            <button
+                              type="button"
+                              tabIndex={active ? 0 : -1}
+                              data-dp-active={active ? "true" : undefined}
+                              disabled={!ok}
+                              aria-label={format(d, "EEEE, MMMM d, yyyy")}
+                              aria-current={isToday ? "date" : undefined}
+                              onClick={() => pick(d)}
+                              className={`${DP_DAY} ${tone}`}
+                              // Today: a 1px primary ring, inline so it does not rest on Tailwind's ring variables.
+                              style={isToday && !isSel && ok ? { boxShadow: `inset 0 0 0 1px ${DP_C.primary}` } : undefined}
+                            >
+                              {d.getDate()}
+                            </button>
+                          </td>
+                        );
+                      })}
+                    </tr>
+                  ))}
+                </tbody>
+              </table>
+            ) : (
+              <div
+                role="grid"
+                aria-label={`Months of ${year}`}
+                className="flex h-full flex-col justify-center gap-3"
+                onKeyDown={onMonthKey}
+              >
+                {[0, 1, 2, 3].map((r) => (
+                  <div key={r} role="row" className="grid grid-cols-3 gap-x-2">
+                    {[0, 1, 2].map((c) => {
+                      const m = r * 3 + c;
+                      const first = new Date(year, m, 1);
+                      const last = addDays(addMonths(first, 1), -1);
+                      const ok = (!minD || dpKey(last) >= dpKey(minD)) && (!maxD || dpKey(first) <= dpKey(maxD));
+                      const isSel = !!selected && selected.getFullYear() === year && selected.getMonth() === m;
+                      const isNow = today.getFullYear() === year && today.getMonth() === m;
+                      const active = focusDate.getMonth() === m;
+                      const tone = isSel ? DP_DAY_SELECTED : !ok ? DP_DAY_OFF : isNow ? DP_DAY_TODAY : DP_DAY_IN;
+                      return (
+                        <div key={m} role="gridcell" aria-selected={isSel}>
+                          <button
+                            type="button"
+                            tabIndex={active ? 0 : -1}
+                            data-dp-active={active ? "true" : undefined}
+                            disabled={!ok}
+                            aria-label={format(first, "MMMM yyyy")}
+                            aria-current={isNow ? "date" : undefined}
+                            onClick={() => chooseMonth(m)}
+                            className={`${DP_MONTH} ${tone}`}
+                            style={isNow && !isSel && ok ? { boxShadow: `inset 0 0 0 1px ${DP_C.primary}` } : undefined}
+                          >
+                            {format(first, "MMM")}
+                          </button>
+                        </div>
+                      );
+                    })}
+                  </div>
+                ))}
+              </div>
+            )}
+          </div>
+
+          <div className="mt-2 flex items-center justify-between border-t pt-2" style={{ borderColor: DP_C.divider }}>
+            <button
+              type="button"
+              disabled={todayOff}
+              onClick={() => pick(today)}
+              // #680058 = DP_C.primary · #F5EAF3 = DP_C.primaryTint
+              className="-ml-1 inline-flex h-10 items-center rounded-full px-3 text-[14px] font-semibold text-[#680058] transition-colors hover:bg-[#F5EAF3] focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-[#680058] disabled:cursor-default disabled:opacity-40 disabled:hover:bg-transparent"
+            >
+              Today
+            </button>
+            {clearable ? (
+              <button
+                type="button"
+                onClick={() => {
+                  onChange("");
+                  closePicker(true);
+                }}
+                // #6B7280 = DP_C.muted · #F3F4F6 = DP_C.canvas · #030712 = DP_C.ink · #680058 = DP_C.primary
+                className="-mr-1 inline-flex h-10 items-center rounded-full px-3 text-[14px] font-medium text-[#6B7280] transition-colors hover:bg-[#F3F4F6] hover:text-[#030712] focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-[#680058]"
+              >
+                Clear
+              </button>
+            ) : null}
+          </div>
+        </div>
+      ) : null}
+    </div>
+  );
+}
+```
+
+</details>
+
+## Checklist before shipping a date field
+
+- [ ] No `<input type="date">`, `datetime-local` or `month` in the block (source grep, then the DOM count)
+- [ ] The kit pasted verbatim between its markers, at module scope; `kit-sync.py check` passes
+- [ ] Block-specific code (wrapper, imports, `textClass`) outside the markers
+- [ ] No clipping class between the field and its scroller
+- [ ] Trigger text size matches the block's inputs (`textClass` where containers are named)
+- [ ] Escape closes only the calendar; the second Escape reaches the modal
+- [ ] Backdrop click with a calendar open: closes only the calendar, or asks to discard
+- [ ] A modal's focus fix-up deferred with `setTimeout(…, 0)`; Tab out of the calendar reaches the next field
+- [ ] Values are `"yyyy-MM-dd"` strings; compared as strings; displayed through a local date
+- [ ] The saved payload is the same string the native field sent

package/references/searchable-dropdown.md

@@ -10,9 +10,15 @@ the obvious choices:
 | 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, clip-aware drop-up. |
 
+The date field has the same problem with the same answer: `<input type="date">` hands its calendar
+to the browser, so a block uses the in-DOM `DatePicker` kit in [date-picker.md](date-picker.md),
+which follows rule 1 of item 4 below, the Escape rule and the focus-on-open rule of this page.
+
 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.
+project (e.g. `Assets/Softr App/Shared/combo.jsx`) and port changes from there. Pasting it
+verbatim between marker lines that carry its sha makes that port mechanical:
+[date-picker.md → The kit between markers](date-picker.md#the-kit-between-markers).
 
 ## The four things that will bite you
 

package/references/softr-mcp.md

@@ -280,7 +280,7 @@ reports neither field. With `includeCode: false`, `vibe_coding_block_get_code` r
 `sourceCode: null`. Verified live 2026-10-01: a deployed block's `sourceSha256` equalled the SHA-256
 of the exact source last pushed to it (taken from the push call), and the read came back at about
 1 KB for a 15 KB block. The same check showed that block's local mirror had picked up three comment
-edits since that push, which is exactly what step 1 below exists to catch. (The digest on push results is per Softr's release notes; no push of ours has shown it yet.)
+edits since that push, which is exactly what step 1 below exists to catch. (The digest on push results was first known from Softr's release notes; our own pushes have returned it since at least 2026-10-08.)
 Right after that release our client's copy of the tool definition did not declare `includeCode`, so
 the argument went out as the string `"false"` and the server still honoured it. Whatever the loaded
 definition says, check that `sourceCode` came back `null`.
@@ -308,10 +308,12 @@ definition says, check that `sourceCode` came back `null`.
 
 Matching hashes prove what Softr stored, not how the block behaves: for that, check it in a fresh preview with saves blocked, per [browser-checks.md](browser-checks.md).
 
-**Hash the exact bytes, trailing newline included.** Softr stores exactly what it receives: across
+**Hash the exact bytes, trailing newline included.** Softr stores exactly the text that reaches it: across
 112 push→fetch pairs between 2026-09-09 and 2026-09-30 the fetched
 `sourceCode` was byte- and MD5-identical to the text sent, including two pushes sent *without* a
-final newline and stored without one. The "deployed block is one byte shorter" we chased on
+final newline and stored without one. (One thing does not reach Softr as written: a `\uXXXX`
+escape in the source arrives decoded, see [below](#unicode-escapes-come-back-decoded).)
+The "deployed block is one byte shorter" we chased on
 2026-09-09 was our own read: an agent that reads a large file in chunks can drop the final
 newline (or a blank line at a chunk boundary) before transmission. A comparison that normalises
 the trailing newline hides exactly that class of error — so do not normalise anything; a mismatch
@@ -356,6 +358,41 @@ from the docs):
   (`application_get`) with the version's `createdAt` (`vibe_coding_block_list_versions`): on
   2026-09-01 a block we believed staged went live with a publish 28 minutes after it was saved.
 
+#### Unicode escapes come back decoded
+
+Verified 2026-10-08 on a large dashboard block pushed in stages with `vibe_coding_block_update_code`
+and `vibe_coding_block_update_code_search_replace`: exactly the calls whose text held a JavaScript
+`\uXXXX` escape came back with a `sourceSha256` that differed from the hash of the planned text. The
+block's accent-folding regex, `/[\u0300-\u036f]/g`, was stored with both escapes replaced by the
+characters themselves, two combining marks sitting raw between the brackets. `\d`, `\D` and `\s` in
+the same block arrived as written.
+
+The decoding happens somewhere between the tool call and storage (the client's JSON handling of
+the argument, or the server), not in Softr's compiler: the stored source text itself changed. It
+looks like the [encoding trap](#which-edit-tool-full-replace-vs-targeted-search-replace) above,
+reaching a backslash-u that was meant to stay in the source. The exception is a lone surrogate:
+`\udc00-\udfff` in the same regexes has no character form, and those pushes stored it unchanged.
+(The `\u{…}` form is untested; treat it the same.)
+
+**So: no `\uXXXX` in pushed source, lone surrogates aside.** Find them before a push with
+`grep -n '\\u[0-9a-fA-F]\{4\}' <file>`, then either:
+
+- **Write the characters themselves**, with a comment saying why, since combining marks and other
+  invisible characters cannot be read in an editor. Spell "backslash-u" out in that comment so it
+  holds no escape either. Check first that the character means the same raw in that spot: a range
+  of combining marks in a character class does (the block's regexes, escaped and raw, matched the
+  same set across all 65,536 BMP code points), but written raw, a `/` ends a regex literal, a `]`
+  closes a class, a backslash or quote changes the token, and U+2028/U+2029 are line terminators a
+  regex literal may not contain.
+- **Build it from code points** where a raw character is unwanted or unsafe:
+  `new RegExp("[" + String.fromCharCode(0x300) + "-" + String.fromCharCode(0x36f) + "]", "g")`,
+  created once at module scope. No backslash-u reaches the tool, so there is nothing to decode.
+  Strings likewise: `String.fromCharCode(0x2014)`, not `"\u2014"`.
+
+If a push has already stored the decoded form, applying the same replacement to the mirror brings
+the hashes back together; confirm the raw characters behave the same (first bullet) before calling
+it done.
+
 ### The array-argument rejection, and why it is a security issue
 
 **Several workspace-server tools take an array argument, and a call that sends it as a JSON *string*