cursedbelt 5.22.0 → 5.23.0

package/dist/react/media-gallery/galleryReturn.js

@@ -0,0 +1,221 @@
+/**
+ * Closing a file puts the grid back where you were — task 2255.
+ *
+ * Owner, 2026-09-28, after flix's "Back keeps your place": *"is a common enough need … I want it
+ * to be in cb … find other apps we have that have scrolling and similar issues where we can't
+ * go back to the right place like flix had"*.
+ *
+ * `MediaGallery` draws `DenseGalleryDetail` while a file is open and `DenseGalleryShell`
+ * otherwise. They are different trees, so closing a file — by ✕, by a deep link's Back
+ * (`useGalleryDeepLink`'s `?i=`), by deleting it — MOUNTS A NEW GRID, and its scroller starts
+ * at zero. Measured in Chromium before this (`e2e/gallery-return.spec.ts`, 240 tiles, scrolled
+ * to 3,000px): every close landed at scrollTop 0, at phone and desktop size, two hundred tiles
+ * from where you had been.
+ *
+ * 🔴 Why not `useScrollMemory`. That hook is per HISTORY ENTRY, and a gallery's open/close is
+ * a history entry only when its consumer deep-links it. An uncontrolled gallery closes with no
+ * navigation at all, so the memory has to live with the gallery — which is also what keeps
+ * every consumer from having to wire anything.
+ *
+ * Two rules, in order:
+ * 1. **The offset comes back** — the browse scroller's own `scrollTop` (the tile grid's
+ *    `.cbgd-grid`, or the table's `.cbgt-root`), recorded while you browse and put back when
+ *    the view returns, if it returns in the same grid/table mode. It retries each frame while
+ *    the virtualized track is still growing into the offset, and a touch, wheel, key or
+ *    pointer press cancels it — the viewer always wins.
+ * 2. **…then the last file SHOWN is on screen.** Stepping through twenty files moves you: the
+ *    place you are now is the last file the stage showed, not the one you opened. When that
+ *    file's tile is not visible after rule 1 it is brought to the middle of the scroller. A
+ *    tile that is already even partly visible is left alone — a grid that jumps a few pixels
+ *    under a tile you can see reads as a bug (the same limit the strip's reveal keeps).
+ *    A virtualized tile that is not mounted is found by arithmetic on the tiles that are:
+ *    their row pitch and column count place it, and the next frame centres it exactly.
+ */
+import { useEffect, useLayoutEffect, useRef } from 'react';
+/** The browse view's scroller in either view: the tile grid, or the table's frame. */
+const SCROLLER = '.cbgd-grid, .cbgt-root';
+/** Every tile and every table row carries its item's id under this attribute. */
+export const ITEM_ID_ATTR = 'data-item-id';
+/** How long a return may keep trying before it settles for what the scroller can hold. */
+const DEADLINE_MS = 1500;
+const CANCEL_EVENTS = ['wheel', 'touchstart', 'pointerdown', 'keydown'];
+export function useGalleryReturn({ rootRef, browsing, viewMode, shownId, displayIds, }) {
+    const saved = useRef(null);
+    const lastShown = useRef(null);
+    const restoring = useRef(false);
+    const wasBrowsing = useRef(browsing);
+    // Read through refs at fire time: they are inputs the return needs CURRENT, not triggers.
+    const modeRef = useRef(viewMode);
+    const idsRef = useRef(displayIds);
+    modeRef.current = viewMode;
+    idsRef.current = displayIds;
+    if (shownId)
+        lastShown.current = shownId;
+    // Record the browse scroller's offset while browsing. Capture phase, because `scroll` does
+    // not bubble and the scroller is whichever of the two views is mounted.
+    useEffect(() => {
+        const root = rootRef.current;
+        if (!browsing || !root)
+            return;
+        const onScroll = (event) => {
+            const target = event.target;
+            if (restoring.current || !(target instanceof HTMLElement) || !target.matches(SCROLLER))
+                return;
+            saved.current = { mode: modeRef.current, top: target.scrollTop };
+        };
+        root.addEventListener('scroll', onScroll, { capture: true, passive: true });
+        return () => root.removeEventListener('scroll', onScroll, { capture: true });
+    }, [browsing, rootRef]);
+    // A layout effect, so the offset is back before the returning grid is ever painted at zero.
+    // biome-ignore lint/correctness/useExhaustiveDependencies: `browsing` is the one trigger — a return is the moment it turns true. Everything else is read through refs above, on purpose: a re-sort or a new page of items must not replay a return.
+    useLayoutEffect(() => {
+        const returning = browsing && !wasBrowsing.current;
+        wasBrowsing.current = browsing;
+        if (!returning)
+            return;
+        const scroller = rootRef.current?.querySelector(SCROLLER);
+        if (!scroller)
+            return;
+        const target = saved.current?.mode === modeRef.current ? saved.current.top : null;
+        const revealId = lastShown.current;
+        if (target === null && !revealId)
+            return;
+        return returnTo(scroller, target, revealId, idsRef, () => {
+            restoring.current = false;
+            saved.current = { mode: modeRef.current, top: scroller.scrollTop };
+        }, restoring);
+    }, [browsing]);
+}
+/**
+ * Put `scroller` back at `target`, then bring `revealId`'s tile into view. Returns the cancel.
+ */
+function returnTo(scroller, target, revealId, idsRef, done, restoring) {
+    // Each phase gets its own deadline, so a list that never grows back into the offset still
+    // leaves the reveal its full budget.
+    let started = performance.now();
+    let frame = 0;
+    let phase = target === null ? 'reveal' : 'offset';
+    let finished = false;
+    restoring.current = true;
+    const finish = () => {
+        if (finished)
+            return;
+        finished = true;
+        cancelAnimationFrame(frame);
+        for (const type of CANCEL_EVENTS)
+            scroller.removeEventListener(type, finish);
+        done();
+    };
+    for (const type of CANCEL_EVENTS)
+        scroller.addEventListener(type, finish, { passive: true });
+    const tick = () => {
+        if (finished)
+            return;
+        const late = performance.now() - started > DEADLINE_MS;
+        if (phase === 'offset' && target !== null) {
+            scroller.scrollTop = target;
+            // Reached, or the list is simply shorter now (a filter, a delete): settle for its end.
+            if (Math.abs(scroller.scrollTop - target) < 1 || late) {
+                phase = 'reveal';
+                started = performance.now();
+            }
+            frame = requestAnimationFrame(tick);
+            return;
+        }
+        const ids = idsRef.current ?? [];
+        const index = revealId ? ids.indexOf(revealId) : -1;
+        if (index < 0 || late) {
+            finish();
+            return;
+        }
+        const tile = scroller.querySelector(`[${ITEM_ID_ATTR}="${cssEscape(revealId ?? '')}"]`);
+        const band = visibleBand(scroller);
+        if (tile) {
+            const box = tile.getBoundingClientRect();
+            const visible = box.bottom > band.top && box.top < band.bottom;
+            // Rule 2's limit: a tile you can already see is not moved — unless WE just jumped to an
+            // estimate of it, which is only ever close.
+            if (!visible || phase === 'centre')
+                scroller.scrollTop += centreDelta(box, band);
+            finish();
+            return;
+        }
+        // 🔴 Not mounted — but first make sure the VIRTUALIZER has caught up with the offset just
+        // set. The table re-windows on its own scroll state a render later, so for a frame or two
+        // after a jump it still holds the rows from the top; estimating off those would place a
+        // tile that is about to appear right where you are. Nothing mounted in the band = wait.
+        if (!mountedInBand(scroller, band)) {
+            frame = requestAnimationFrame(tick);
+            return;
+        }
+        // Truly windowed out. Place it by the tiles that ARE mounted.
+        const estimate = estimateTop(scroller, band, ids, index);
+        if (estimate === null) {
+            finish();
+            return;
+        }
+        scroller.scrollTop = estimate;
+        phase = 'centre';
+        frame = requestAnimationFrame(tick);
+    };
+    tick();
+    return () => {
+        if (finished)
+            return;
+        finished = true;
+        cancelAnimationFrame(frame);
+        for (const type of CANCEL_EVENTS)
+            scroller.removeEventListener(type, finish);
+        restoring.current = false;
+    };
+}
+/** The part of the scroller a person can see — below the table's sticky header, if any. */
+function visibleBand(scroller) {
+    const view = scroller.getBoundingClientRect();
+    const head = scroller.querySelector('thead');
+    const top = head ? Math.max(view.top, head.getBoundingClientRect().bottom) : view.top;
+    return { top, bottom: view.bottom };
+}
+/** Does any tile or row sit in the visible band — i.e. has the window caught up? */
+function mountedInBand(scroller, band) {
+    for (const el of scroller.querySelectorAll(`[${ITEM_ID_ATTR}]`)) {
+        const box = el.getBoundingClientRect();
+        if (box.bottom > band.top && box.top < band.bottom)
+            return true;
+    }
+    return false;
+}
+function centreDelta(box, band) {
+    return box.top + box.height / 2 - (band.top + band.bottom) / 2;
+}
+/**
+ * A `scrollTop` that centres the tile at `index`, derived from the mounted ones: the first
+ * mounted row gives the column count (only the LAST row of a grid can be short), and the next
+ * row down gives the pitch. A table is the same arithmetic with one column.
+ */
+function estimateTop(scroller, band, ids, index) {
+    const placed = [];
+    for (const el of scroller.querySelectorAll(`[${ITEM_ID_ATTR}]`)) {
+        const at = ids.indexOf(el.getAttribute(ITEM_ID_ATTR) ?? '');
+        if (at < 0)
+            continue;
+        const box = el.getBoundingClientRect();
+        placed.push({ index: at, top: box.top - band.top + scroller.scrollTop, height: box.height });
+    }
+    if (placed.length === 0)
+        return null;
+    placed.sort((a, b) => a.index - b.index);
+    const anchor = placed[0];
+    const cols = Math.max(1, placed.filter((p) => Math.abs(p.top - anchor.top) < 1).length);
+    const below = placed.find((p) => p.top - anchor.top >= 1);
+    const rowOf = (at) => Math.floor(at / cols);
+    const pitch = below ? (below.top - anchor.top) / (rowOf(below.index) - rowOf(anchor.index) || 1) : anchor.height;
+    const rows = rowOf(index) - rowOf(anchor.index);
+    const top = anchor.top + rows * pitch;
+    return Math.max(0, top + anchor.height / 2 - (band.bottom - band.top) / 2);
+}
+/** `CSS.escape` where it exists (every browser); ids are app-chosen strings. */
+function cssEscape(value) {
+    return typeof CSS !== 'undefined' && CSS.escape ? CSS.escape(value) : value.replace(/["\\]/g, '\\$&');
+}
+//# sourceMappingURL=galleryReturn.js.map

package/dist/react/media-gallery/galleryReturn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"galleryReturn.js","sourceRoot":"","sources":["../../../src/react/media-gallery/galleryReturn.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,OAAO,EAAkB,SAAS,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AAE3E,sFAAsF;AACtF,MAAM,QAAQ,GAAG,wBAAwB,CAAC;AAC1C,iFAAiF;AACjF,MAAM,CAAC,MAAM,YAAY,GAAG,cAAc,CAAC;AAC3C,0FAA0F;AAC1F,MAAM,WAAW,GAAG,IAAI,CAAC;AACzB,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,SAAS,CAAU,CAAC;AAejF,MAAM,UAAU,gBAAgB,CAAC,EAC/B,OAAO,EACP,QAAQ,EACR,QAAQ,EACR,OAAO,EACP,UAAU,GACW;IACrB,MAAM,KAAK,GAAG,MAAM,CAAuC,IAAI,CAAC,CAAC;IACjE,MAAM,SAAS,GAAG,MAAM,CAAgB,IAAI,CAAC,CAAC;IAC9C,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAChC,MAAM,WAAW,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC;IACrC,0FAA0F;IAC1F,MAAM,OAAO,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC;IACjC,MAAM,MAAM,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC;IAClC,OAAO,CAAC,OAAO,GAAG,QAAQ,CAAC;IAC3B,MAAM,CAAC,OAAO,GAAG,UAAU,CAAC;IAC5B,IAAI,OAAO;QAAE,SAAS,CAAC,OAAO,GAAG,OAAO,CAAC;IAEzC,2FAA2F;IAC3F,wEAAwE;IACxE,SAAS,CAAC,GAAG,EAAE;QACb,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC;QAC7B,IAAI,CAAC,QAAQ,IAAI,CAAC,IAAI;YAAE,OAAO;QAC/B,MAAM,QAAQ,GAAG,CAAC,KAAY,EAAQ,EAAE;YACtC,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;YAC5B,IAAI,SAAS,CAAC,OAAO,IAAI,CAAC,CAAC,MAAM,YAAY,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC;gBAAE,OAAO;YAC/F,KAAK,CAAC,OAAO,GAAG,EAAE,IAAI,EAAE,OAAO,CAAC,OAAO,EAAE,GAAG,EAAE,MAAM,CAAC,SAAS,EAAE,CAAC;QACnE,CAAC,CAAC;QACF,IAAI,CAAC,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;QAC5E,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;IAC/E,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC;IAExB,4FAA4F;IAC5F,oPAAoP;IACpP,eAAe,CAAC,GAAG,EAAE;QACnB,MAAM,SAAS,GAAG,QAAQ,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC;QACnD,WAAW,CAAC,OAAO,GAAG,QAAQ,CAAC;QAC/B,IAAI,CAAC,SAAS;YAAE,OAAO;QACvB,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,EAAE,aAAa,CAAc,QAAQ,CAAC,CAAC;QACvE,IAAI,CAAC,QAAQ;YAAE,OAAO;QACtB,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,EAAE,IAAI,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;QAClF,MAAM,QAAQ,GAAG,SAAS,CAAC,OAAO,CAAC;QACnC,IAAI,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO;QACzC,OAAO,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE;YACvD,SAAS,CAAC,OAAO,GAAG,KAAK,CAAC;YAC1B,KAAK,CAAC,OAAO,GAAG,EAAE,IAAI,EAAE,OAAO,CAAC,OAAO,EAAE,GAAG,EAAE,QAAQ,CAAC,SAAS,EAAE,CAAC;QACrE,CAAC,EAAE,SAAS,CAAC,CAAC;IAChB,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC;AACjB,CAAC;AAED;;GAEG;AACH,SAAS,QAAQ,CACf,QAAqB,EACrB,MAAqB,EACrB,QAAuB,EACvB,MAAoC,EACpC,IAAgB,EAChB,SAA+B;IAE/B,0FAA0F;IAC1F,qCAAqC;IACrC,IAAI,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;IAChC,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,KAAK,GAAmC,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC;IAClF,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,SAAS,CAAC,OAAO,GAAG,IAAI,CAAC;IAEzB,MAAM,MAAM,GAAG,GAAS,EAAE;QACxB,IAAI,QAAQ;YAAE,OAAO;QACrB,QAAQ,GAAG,IAAI,CAAC;QAChB,oBAAoB,CAAC,KAAK,CAAC,CAAC;QAC5B,KAAK,MAAM,IAAI,IAAI,aAAa;YAAE,QAAQ,CAAC,mBAAmB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC7E,IAAI,EAAE,CAAC;IACT,CAAC,CAAC;IACF,KAAK,MAAM,IAAI,IAAI,aAAa;QAAE,QAAQ,CAAC,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;IAE7F,MAAM,IAAI,GAAG,GAAS,EAAE;QACtB,IAAI,QAAQ;YAAE,OAAO;QACrB,MAAM,IAAI,GAAG,WAAW,CAAC,GAAG,EAAE,GAAG,OAAO,GAAG,WAAW,CAAC;QACvD,IAAI,KAAK,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;YAC1C,QAAQ,CAAC,SAAS,GAAG,MAAM,CAAC;YAC5B,uFAAuF;YACvF,IAAI,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC;gBACtD,KAAK,GAAG,QAAQ,CAAC;gBACjB,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;YAC9B,CAAC;YACD,KAAK,GAAG,qBAAqB,CAAC,IAAI,CAAC,CAAC;YACpC,OAAO;QACT,CAAC;QACD,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,IAAI,EAAE,CAAC;QACjC,MAAM,KAAK,GAAG,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACpD,IAAI,KAAK,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC;YACtB,MAAM,EAAE,CAAC;YACT,OAAO;QACT,CAAC;QACD,MAAM,IAAI,GAAG,QAAQ,CAAC,aAAa,CAAc,IAAI,YAAY,KAAK,SAAS,CAAC,QAAQ,IAAI,EAAE,CAAC,IAAI,CAAC,CAAC;QACrG,MAAM,IAAI,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;QACnC,IAAI,IAAI,EAAE,CAAC;YACT,MAAM,GAAG,GAAG,IAAI,CAAC,qBAAqB,EAAE,CAAC;YACzC,MAAM,OAAO,GAAG,GAAG,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC;YAC/D,wFAAwF;YACxF,4CAA4C;YAC5C,IAAI,CAAC,OAAO,IAAI,KAAK,KAAK,QAAQ;gBAAE,QAAQ,CAAC,SAAS,IAAI,WAAW,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;YACjF,MAAM,EAAE,CAAC;YACT,OAAO;QACT,CAAC;QACD,0FAA0F;QAC1F,0FAA0F;QAC1F,wFAAwF;QACxF,wFAAwF;QACxF,IAAI,CAAC,aAAa,CAAC,QAAQ,EAAE,IAAI,CAAC,EAAE,CAAC;YACnC,KAAK,GAAG,qBAAqB,CAAC,IAAI,CAAC,CAAC;YACpC,OAAO;QACT,CAAC;QACD,8DAA8D;QAC9D,MAAM,QAAQ,GAAG,WAAW,CAAC,QAAQ,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;QACzD,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;YACtB,MAAM,EAAE,CAAC;YACT,OAAO;QACT,CAAC;QACD,QAAQ,CAAC,SAAS,GAAG,QAAQ,CAAC;QAC9B,KAAK,GAAG,QAAQ,CAAC;QACjB,KAAK,GAAG,qBAAqB,CAAC,IAAI,CAAC,CAAC;IACtC,CAAC,CAAC;IAEF,IAAI,EAAE,CAAC;IACP,OAAO,GAAG,EAAE;QACV,IAAI,QAAQ;YAAE,OAAO;QACrB,QAAQ,GAAG,IAAI,CAAC;QAChB,oBAAoB,CAAC,KAAK,CAAC,CAAC;QAC5B,KAAK,MAAM,IAAI,IAAI,aAAa;YAAE,QAAQ,CAAC,mBAAmB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC7E,SAAS,CAAC,OAAO,GAAG,KAAK,CAAC;IAC5B,CAAC,CAAC;AACJ,CAAC;AAOD,2FAA2F;AAC3F,SAAS,WAAW,CAAC,QAAqB;IACxC,MAAM,IAAI,GAAG,QAAQ,CAAC,qBAAqB,EAAE,CAAC;IAC9C,MAAM,IAAI,GAAG,QAAQ,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;IAC7C,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,qBAAqB,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC;IACtF,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC;AACtC,CAAC;AAED,oFAAoF;AACpF,SAAS,aAAa,CAAC,QAAqB,EAAE,IAAU;IACtD,KAAK,MAAM,EAAE,IAAI,QAAQ,CAAC,gBAAgB,CAAc,IAAI,YAAY,GAAG,CAAC,EAAE,CAAC;QAC7E,MAAM,GAAG,GAAG,EAAE,CAAC,qBAAqB,EAAE,CAAC;QACvC,IAAI,GAAG,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,GAAG,IAAI,CAAC,MAAM;YAAE,OAAO,IAAI,CAAC;IAClE,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,WAAW,CAAC,GAAY,EAAE,IAAU;IAC3C,OAAO,GAAG,CAAC,GAAG,GAAG,GAAG,CAAC,MAAM,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AACjE,CAAC;AAED;;;;GAIG;AACH,SAAS,WAAW,CAAC,QAAqB,EAAE,IAAU,EAAE,GAAsB,EAAE,KAAa;IAC3F,MAAM,MAAM,GAAqD,EAAE,CAAC;IACpE,KAAK,MAAM,EAAE,IAAI,QAAQ,CAAC,gBAAgB,CAAc,IAAI,YAAY,GAAG,CAAC,EAAE,CAAC;QAC7E,MAAM,EAAE,GAAG,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,YAAY,CAAC,YAAY,CAAC,IAAI,EAAE,CAAC,CAAC;QAC5D,IAAI,EAAE,GAAG,CAAC;YAAE,SAAS;QACrB,MAAM,GAAG,GAAG,EAAE,CAAC,qBAAqB,EAAE,CAAC;QACvC,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,GAAG,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;IAC/F,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACrC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;IACzC,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,CAA4B,CAAC;IACpD,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IACxF,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;IAC1D,MAAM,KAAK,GAAG,CAAC,EAAU,EAAU,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC;IAC5D,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC;IACjH,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAChD,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,GAAG,IAAI,GAAG,KAAK,CAAC;IACtC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;AAC7E,CAAC;AAED,gFAAgF;AAChF,SAAS,SAAS,CAAC,KAAa;IAC9B,OAAO,OAAO,GAAG,KAAK,WAAW,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;AACxG,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt",
-	"version": "5.22.0",
+	"version": "5.23.0",
 	"license": "ISC",
 	"type": "module",
 	"description": "The React design system of the cursedbelt split — components, styles, theme. cursedbelt-core below it; server tier in cursedbelt-server.",
@@ -31,6 +31,7 @@
 			"./react/media/video-player",
 			"./react/pdf-viewer",
 			"./react/rich-text",
+			"./react/search-input",
 			"./react/spreadsheet",
 			"./react/workbook-viewer"
 		],
@@ -348,6 +349,12 @@
 			"source": "./src/react/components/ScrollArea.tsx",
 			"import": "./dist/react/components/ScrollArea.js"
 		},
+		"./react/search-input": {
+			"types": "./dist/react/components/SearchInput.d.ts",
+			"bun": "./src/react/components/SearchInput.tsx",
+			"source": "./src/react/components/SearchInput.tsx",
+			"import": "./dist/react/components/SearchInput.js"
+		},
 		"./react/secret-input": {
 			"types": "./dist/react/components/SecretInput.d.ts",
 			"bun": "./src/react/components/SecretInput.tsx",

package/src/demoFixture.spec.ts

@@ -101,8 +101,10 @@ describe('the e2e fixture exists', () => {
 		for (const spec of specs) {
 			const text = readFileSync(resolve(e2eDir, spec), 'utf8');
 			for (const [, url] of text.matchAll(/goto\('([^']+)'\)/g)) {
-				// '/' is index.html; '/table-layout.html' is that file in demo/.
-				const file = url === '/' ? 'index.html' : url.replace(/^\//, '');
+				// '/' is index.html; '/table-layout.html' is that file in demo/. A query or a hash
+				// (`/gallery-return.html?link`) picks a mode on the page, not a different file.
+				const path = url.replace(/[?#].*$/, '');
+				const file = path === '/' ? 'index.html' : path.replace(/^\//, '');
 				if (!existsSync(resolve(DEMO_ROOT, file))) missing.push(`${spec} → ${url}`);
 			}
 		}

package/src/react/components/SearchInput.spec.tsx

@@ -1,4 +1,6 @@
 import { afterEach, describe, expect, mock, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { createRef } from 'react';
 import { cleanup, fireEvent, render } from '@testing-library/react';
 import { SearchInput } from './SearchInput.js';
 
@@ -56,4 +58,59 @@ describe('SearchInput', () => {
     expect(badge(container)).toBeNull();
     expect(getByRole('searchbox').className).not.toContain('pr-9');
   });
+
+  test('no ✕ unless asked for — a box that never had one does not grow one', () => {
+    const { queryByRole } = render(<SearchInput value='the office' onChange={() => {}} />);
+    expect(queryByRole('button', { name: 'Clear search' })).toBeNull();
+  });
+
+  test('clearable: the ✕ appears with text, empties the box, and leaves the caret in it', () => {
+    const onChange = mock((_: string) => {});
+    const empty = render(<SearchInput value='' onChange={onChange} clearable />);
+    expect(empty.queryByRole('button', { name: 'Clear search' })).toBeNull();
+    empty.unmount();
+
+    const { getByRole } = render(<SearchInput value='report' onChange={onChange} clearable />);
+    const input = getByRole('searchbox');
+    expect(input.getAttribute('data-trailing')).toBe('1');
+    fireEvent.click(getByRole('button', { name: 'Clear search' }));
+    expect(onChange).toHaveBeenLastCalledWith('');
+    expect(document.activeElement).toBe(input);
+  });
+
+  test('badge and ✕ together: the field makes room for both', () => {
+    const { getByRole } = render(<SearchInput value='q3*report' onChange={() => {}} clearable />);
+    const input = getByRole('searchbox');
+    expect(input.getAttribute('data-trailing')).toBe('2');
+    expect(input.className).toContain('pr-16');
+  });
+
+  test("a ref and a data attribute reach the <input> — desk's ⌘F finds its field by one", () => {
+    const ref = createRef<HTMLInputElement>();
+    const { getByRole } = render(
+      <SearchInput ref={ref} value='' onChange={() => {}} data-find-field='true' clearable />,
+    );
+    const input = getByRole('searchbox');
+    expect(ref.current).toBe(input as HTMLInputElement);
+    expect(input.getAttribute('data-find-field')).toBe('true');
+  });
+
+  test('every element carries its plain `cbsi-` class beside its utilities', () => {
+    const { container, getByRole } = render(<SearchInput value='the*the' onChange={() => {}} clearable />);
+    expect(container.querySelector('.cbsi')).not.toBeNull();
+    expect(container.querySelector('svg.cbsi-icon')).not.toBeNull();
+    expect(getByRole('searchbox').className).toContain('cbsi-input');
+    expect(badge(container)?.className).toContain('cbsi-badge');
+    expect(container.querySelector('button.cbsi-clear')).not.toBeNull();
+  });
+
+  test('🔴 the stylesheet is imported by the component and every rule sits in `@layer base`', () => {
+    // An import nobody makes ships a look nobody sees; an unlayered rule would override a
+    // Tailwind app's `inputClassName` (see the stylesheet's header). Both are silent in a DOM test.
+    const source = readFileSync(new URL('./SearchInput.tsx', import.meta.url), 'utf8');
+    expect(source).toContain("import './searchInput.css';");
+    const css = readFileSync(new URL('./searchInput.css', import.meta.url), 'utf8').replace(/\/\*[\s\S]*?\*\//g, '');
+    const outside = css.replace(/@layer base\s*\{[\s\S]*\}\s*$/, '').trim();
+    expect(outside).toBe('');
+  });
 });

package/src/react/components/SearchInput.tsx

@@ -1,5 +1,5 @@
-import { Asterisk, Regex, Search, TriangleAlert } from 'lucide-react';
-import { useMemo } from 'react';
+import { Asterisk, Regex, Search, TriangleAlert, X } from 'lucide-react';
+import { useMemo, useRef } from 'react';
 import {
   parseSearchPattern,
   type SearchPattern,
@@ -8,6 +8,9 @@ import {
 import { cn } from '../lib/cn.js';
 import { Input, type InputProps } from './Input.js';
 import { Tooltip } from './Tooltip.js';
+// 🔴 The look travels with the component — see the stylesheet's header for why every rule in it
+// sits in `@layer base`, below the Tailwind utilities this file still carries.
+import './searchInput.css';
 
 export interface SearchInputProps extends Omit<InputProps, 'value' | 'onChange' | 'type'> {
   value: string;
@@ -25,6 +28,12 @@ export interface SearchInputProps extends Omit<InputProps, 'value' | 'onChange'
   className?: string;
   /** Classes for the `<input>` itself — colours, radius, text size. */
   inputClassName?: string;
+  /**
+   * Draw a ✕ that empties the box (and keeps the caret in it) while there is text to clear.
+   * Default `false`, so a box that never had one does not grow one. The browser's own ✕ on a
+   * `type="search"` field is hidden while this is on, so there is only ever one.
+   */
+  clearable?: boolean;
 }
 
 const PLAIN_ONLY: SearchSyntaxOptions = { wildcard: false, regex: false };
@@ -64,6 +73,13 @@ function badgeFor(pattern: SearchPattern) {
  * Parsing is the app's too: this component only DISPLAYS the pattern. An app
  * that filters in memory calls `createSearchMatcher(value, syntax)`; one that
  * queries a server parses there with the same options.
+ *
+ * ── In an app with no Tailwind ──────────────────────────────────────────────
+ * It draws from its own `searchInput.css` (5.23.0, task 2256), so import it by its
+ * own subpath, `cursedbelt/react/search-input`, rather than the `cursedbelt/react`
+ * barrel. Everything else a field needs passes straight to the `<input>`: `ref`,
+ * `autoFocus`, and any `data-*` attribute (desk's ⌘F finds its field by
+ * `data-find-field="true"`).
  */
 export function SearchInput({
   value,
@@ -74,43 +90,81 @@ export function SearchInput({
   inputClassName,
   placeholder = 'Search…',
   'aria-label': ariaLabel,
+  clearable = false,
+  ref,
   ...inputProps
 }: SearchInputProps) {
   const pattern = useMemo(() => parseSearchPattern(value, syntax === false ? PLAIN_ONLY : syntax), [value, syntax]);
   const badge = showSyntaxBadge ? badgeFor(pattern) : null;
   const invalid = pattern.kind === 'invalid';
+  const clear = clearable && value !== '';
+  const trailing = (badge ? 1 : 0) + (clear ? 1 : 0);
+  // Our own handle on the field, so the ✕ can put the caret back — merged with the caller's.
+  const own = useRef<HTMLInputElement | null>(null);
+  const setRef = (node: HTMLInputElement | null): void => {
+    own.current = node;
+    if (typeof ref === 'function') ref(node);
+    else if (ref) ref.current = node;
+  };
 
+  /*
+   * Every element carries BOTH its `cbsi-` class (the plain look, for an app with no Tailwind)
+   * and the Tailwind utilities it always had (the look a Tailwind app restyles through
+   * `className`/`inputClassName`). The stylesheet's header says why the two cannot fight.
+   */
   return (
-    <div className={cn('relative min-w-0', className)}>
+    <div className={cn('cbsi relative min-w-0', className)}>
       <Search
         aria-hidden
-        className='-translate-y-1/2 pointer-events-none absolute top-1/2 left-2.5 size-4 text-muted-foreground'
+        className='cbsi-icon -translate-y-1/2 pointer-events-none absolute top-1/2 left-2.5 size-4 text-muted-foreground'
       />
       <Input
         {...inputProps}
+        ref={setRef}
         type='search'
         value={value}
         onChange={(event) => onChange(event.target.value)}
         placeholder={placeholder}
         aria-label={ariaLabel ?? (typeof placeholder === 'string' ? placeholder : 'Search')}
         aria-invalid={invalid || undefined}
-        className={cn('pl-8', badge && 'pr-9', inputClassName)}
+        data-trailing={trailing || undefined}
+        data-clearable={clearable || undefined}
+        className={cn('cbsi-input pl-8', trailing === 1 && 'pr-9', trailing === 2 && 'pr-16', inputClassName)}
       />
-      {badge ? (
-        <Tooltip content={badge.tip} side='bottom' multiline>
-          <span
-            role='img'
-            aria-label={badge.label}
-            data-testid='search-syntax-badge'
-            data-kind={pattern.kind}
-            className={cn(
-              '-translate-y-1/2 absolute top-1/2 right-2 inline-flex size-6 items-center justify-center rounded-full',
-              invalid ? 'bg-destructive/15 text-destructive' : 'bg-accent/15 text-accent-strong',
-            )}
-          >
-            <badge.icon className='size-3.5' aria-hidden />
-          </span>
-        </Tooltip>
+      {trailing > 0 ? (
+        <span className='cbsi-trail -translate-y-1/2 absolute top-1/2 right-2 inline-flex items-center gap-1'>
+          {badge ? (
+            <Tooltip content={badge.tip} side='bottom' multiline>
+              <span
+                role='img'
+                aria-label={badge.label}
+                data-testid='search-syntax-badge'
+                data-kind={pattern.kind}
+                className={cn(
+                  'cbsi-badge inline-flex size-6 items-center justify-center rounded-full',
+                  invalid ? 'bg-destructive/15 text-destructive' : 'bg-accent/15 text-accent-strong',
+                )}
+              >
+                <badge.icon className='size-3.5' aria-hidden />
+              </span>
+            </Tooltip>
+          ) : null}
+          {clear ? (
+            <button
+              // guardrails-ignore no-raw-action-button: a 24px glyph INSIDE the field, styled by
+              // this component's own plain CSS (`.cbsi-clear`) so it draws without Tailwind.
+              type='button'
+              className='cbsi-clear'
+              aria-label='Clear search'
+              onClick={() => {
+                onChange('');
+                own.current?.focus();
+              }}
+            >
+              <X aria-hidden />
+            </button>
+          ) : null}
+        </span>
       ) : null}
     </div>
   );

package/src/react/components/searchInput.css

@@ -0,0 +1,179 @@
+/*
+ * SearchInput's own look, as plain CSS — so it draws in an app with NO Tailwind (desk), the way
+ * `activityBar.css` and `fileTree.css` let those two travel. Prefix `cbsi-`. Task 2256.
+ *
+ * 🔴 Everything here is inside `@layer base`, and that is the whole trick — read before editing.
+ *
+ * The component KEEPS its Tailwind utilities, because a Tailwind app restyles the field through
+ * them: flix passes `inputClassName="rounded-full bg-[var(--surface-1)] …"`. An UNLAYERED rule
+ * beats every layered one whatever its specificity, and Tailwind v4 puts utilities in
+ * `@layer utilities` — so a plain `.cbsi-input { border-radius: … }` would silently undo flix's
+ * `rounded-full`. In `@layer base` these rules sit BELOW utilities in every Tailwind app, in
+ * either load order: if Tailwind's `@layer theme, base, components, utilities` came first,
+ * `base` is second of four; if this file came first, `base` is registered first and Tailwind's
+ * statement appends the rest after it. Within `base`, a `.cbsi-` class out-ranks preflight's
+ * element selectors, and every value below is the value Tailwind already computes, so a
+ * Tailwind app draws exactly what it drew before this file existed.
+ *
+ * In an app without Tailwind this is the only author layer that matches these elements, so it
+ * is the look. Its tokens fall back to the plainer ones an app is most likely to bridge
+ * (`--border`, `--background`, `--foreground`, `--muted-foreground`, `--ring`, `--accent`,
+ * `--destructive`, `--radius-sm`) — desk answers those on `.cs-root`.
+ */
+
+@layer base {
+	.cbsi {
+		position: relative;
+		min-width: 0;
+	}
+
+	.cbsi-icon {
+		position: absolute;
+		top: 50%;
+		left: 0.625rem;
+		translate: 0 -50%;
+		width: 1rem;
+		height: 1rem;
+		pointer-events: none;
+		color: var(--muted-foreground);
+	}
+
+	/* The field — `fieldControlClass('md')`, written out. */
+	.cbsi-input {
+		box-sizing: border-box;
+		width: 100%;
+		height: var(--control-h-md, 36px);
+		margin: 0;
+		padding: 0 0.75rem 0 2rem;
+		border: 1px solid var(--field-border, var(--border));
+		border-radius: var(--field-radius, var(--radius-md, var(--radius-sm, 0.375rem)));
+		background-color: var(--field-bg, var(--background));
+		color: var(--field-fg, var(--foreground));
+		font: inherit;
+		font-size: 1rem;
+		line-height: 1.5rem;
+		outline: none;
+		appearance: none;
+	}
+
+	/* 16px on a phone keeps iOS from zooming on focus; 14px from `sm:` up, as `text-sm`. */
+	@media (min-width: 40rem) {
+		.cbsi-input {
+			font-size: 0.875rem;
+			line-height: 1.25rem;
+		}
+	}
+
+	/* DESIGN.md §5: 44px to a thumb. */
+	@media (pointer: coarse) {
+		.cbsi-input {
+			min-height: 2.75rem;
+		}
+	}
+
+	.cbsi-input::placeholder {
+		color: var(--field-placeholder, var(--muted-foreground));
+	}
+
+	.cbsi-input:focus-visible {
+		border-color: var(--field-ring, var(--ring));
+		box-shadow: 0 0 0 2px color-mix(in oklab, var(--field-ring, var(--ring)) 30%, transparent);
+	}
+
+	.cbsi-input[aria-invalid='true'] {
+		border-color: var(--field-error, var(--destructive));
+		box-shadow: 0 0 0 2px color-mix(in oklab, var(--field-error, var(--destructive)) 30%, transparent);
+	}
+
+	.cbsi-input:disabled {
+		cursor: not-allowed;
+		opacity: 0.5;
+	}
+
+	/* Room on the right for whatever sits there: a badge, a clear button, or both. */
+	.cbsi-input[data-trailing='1'] {
+		padding-right: 2.25rem;
+	}
+
+	.cbsi-input[data-trailing='2'] {
+		padding-right: 4rem;
+	}
+
+	/* A clearable box draws its own ✕, so the browser's must not draw a second one. */
+	.cbsi-input[data-clearable]::-webkit-search-cancel-button {
+		appearance: none;
+		display: none;
+	}
+
+	.cbsi-trail {
+		position: absolute;
+		top: 50%;
+		right: 0.5rem;
+		translate: 0 -50%;
+		display: inline-flex;
+		align-items: center;
+		gap: 0.25rem;
+	}
+
+	/* The badge: a filled capsule (DESIGN.md §3), accent while a syntax is in play. */
+	.cbsi-badge {
+		display: inline-flex;
+		align-items: center;
+		justify-content: center;
+		width: 1.5rem;
+		height: 1.5rem;
+		border-radius: 9999px;
+		background-color: color-mix(in oklab, var(--accent) 15%, transparent);
+		color: var(--accent-strong, var(--accent));
+	}
+
+	.cbsi-badge[data-kind='invalid'] {
+		background-color: color-mix(in oklab, var(--destructive) 15%, transparent);
+		color: var(--destructive);
+	}
+
+	.cbsi-badge svg {
+		width: 0.875rem;
+		height: 0.875rem;
+	}
+
+	.cbsi-clear {
+		position: relative;
+		display: inline-flex;
+		align-items: center;
+		justify-content: center;
+		width: 1.5rem;
+		height: 1.5rem;
+		margin: 0;
+		padding: 0;
+		border: 0;
+		border-radius: var(--radius-sm, 0.375rem);
+		background: transparent;
+		color: var(--muted-foreground);
+		cursor: pointer;
+	}
+
+	.cbsi-clear:hover {
+		color: var(--foreground);
+		background: var(--muted, color-mix(in oklab, var(--foreground) 8%, transparent));
+	}
+
+	.cbsi-clear:focus-visible {
+		outline: 2px solid var(--ring);
+		outline-offset: 1px;
+	}
+
+	/* The ✕ is 24px to the eye; to a thumb it reaches the 44px floor (DESIGN.md §5). */
+	@media (pointer: coarse) {
+		.cbsi-clear::after {
+			content: '';
+			position: absolute;
+			inset: -10px;
+		}
+	}
+
+	.cbsi-clear svg {
+		width: 0.75rem;
+		height: 0.75rem;
+	}
+}