@kolkrabbi/kol-component 0.228.0 → 0.230.0

package/src/organisms/DocumentEditor.jsx

@@ -32,7 +32,8 @@ import { readDraft, writeDraft, clearDraft } from '../utilities/localDrafts.js'
  * @param {string}   name            the file's name (edit) or a starting name (new)
  * @param {string}   kind            markdown · text · json · yaml · code · svg (edit); new picks it
  * @param {string}   text            the saved text; `null` while it loads
- * @param {number}   savedAt         epoch ms of the saved file — a draft older than this is ignored
+ * @param {number}   savedAt         epoch ms of the saved file — a draft older than this is ignored; `null` = never
+ *                                    saved (a blank note, 2026-09-29) and the status says so instead of "Saved"
  * @param {Object}   draft           `{ bucket, key }` — where the draft lives; omit for no drafts
  * @param {Function} onSave          `(text) => Promise` — edit mode
  * @param {Function} onCreate        `({ name, text }) => Promise` — new mode; the name carries the extension
@@ -42,7 +43,7 @@ import { readDraft, writeDraft, clearDraft } from '../utilities/localDrafts.js'
  * @param {Function} onPickAsset     `() => Promise<{ name, url, contentType } | null>` — a consumer's own picker instead
  * @param {Function} onClose
  * @param {boolean}  inline          render IN the page, filling its container, instead of over it (the notes
- *                                   page, media-shell 2026-09-26: the editor is the page's content there,
+ *                                   page, media-hub 2026-09-26: the editor is the page's content there,
  *                                   not a window over a list). No scrim, no Escape-to-close; the X still closes
  */
 const TYPES = [
@@ -94,10 +95,10 @@ export default function DocumentEditor({
     }
     if (text == null) return
     const d = draft ? readDraft(draft.bucket, draft.key) : null
-    const useDraft = d && d.at > savedAt && d.text !== text
+    const useDraft = d && d.at > (savedAt ?? 0) && d.text !== text
     setBase(text)
     setValue(useDraft ? d.text : text); latest.current = useDraft ? d.text : text
-    setStatus(useDraft ? 'Draft restored — not saved to the file' : 'Saved')
+    setStatus(useDraft ? 'Draft restored — not saved to the file' : savedAt === null ? 'Not saved yet' : 'Saved')
     if (d && !useDraft && draft) clearDraft(draft.bucket, draft.key)
   }, [text]) // eslint-disable-line react-hooks/exhaustive-deps
 
@@ -110,7 +111,7 @@ export default function DocumentEditor({
   useEffect(() => () => flush(), []) // eslint-disable-line react-hooks/exhaustive-deps
   const change = (next) => {
     setValue(next); latest.current = next
-    setStatus(isNew ? 'Not created yet' : next === base ? 'Saved' : 'Edited — not saved')
+    setStatus(isNew ? 'Not created yet' : next === base ? (savedAt === null ? 'Not saved yet' : 'Saved') : 'Edited — not saved')
     clearTimeout(timer.current)
     timer.current = setTimeout(flush, DRAFT_PAUSE)
   }
@@ -197,7 +198,7 @@ export default function DocumentEditor({
             <ViewToggle variant="text" viewMode={view} onViewChange={setView} options={views} />
             {md && (onPickAsset || assets?.length > 0) && <Button variant="nav" size="sm" iconLeft="image" onClick={attach} aria-pressed={picking}>Attach</Button>}
             {!isNew && value !== base && value != null && <Button variant="nav" size="sm" onClick={revert}>Revert</Button>}
-            <Button variant="secondary" size="sm" onClick={save} disabled={!dirty}>{isNew ? 'Create' : 'Save'}</Button>
+            <Button size="sm" onClick={save} disabled={!dirty}>{isNew ? 'Create' : 'Save'}</Button>
           </span>
         )}>
         {/* the window's own caps, inline — Tailwind does not generate arbitrary values from package source */}
@@ -229,7 +230,7 @@ export default function DocumentEditor({
                 )}
                 {value == null
                   ? <p className="kol-mono-12 text-fg-48">Loading…</p>
-                  : <Textarea variant="filled" size="md" rows={18} axis="vertical" className="w-full flex-1 kol-mono-12"
+                  : <Textarea variant="filled" size="sm" rows={18} axis="vertical" className="w-full flex-1"
                       value={md ? parts.body : value} onChange={(e) => (md ? setBody(e.target.value) : change(e.target.value))}
                       spellCheck={kind === 'markdown' || kind === 'text'} aria-label="Document text"
                       placeholder={md ? 'Write in markdown — # heading, **bold**, - list' : ''} />}

package/src/organisms/MediaLibrary.jsx

@@ -16,6 +16,7 @@ import MediaViewer from './MediaViewer.jsx'
 import { MediaLibraryBrowse, MediaLibraryLibrary } from './MediaLibraryPages.jsx'
 import MediaLibraryExplorer from './MediaLibraryExplorer.jsx'
 import { SettingsChipRow, chipCls } from './SettingsPanel.jsx'
+import { filterMedia } from '../utilities/mediaSearch.js'
 
 /**
  * MediaLibrary — a browser over an object bucket, in two views over one
@@ -343,10 +344,7 @@ export function MediaLibraryProvider({
     const kindCounts = files.reduce((acc, o) => { acc[o.kind] = (acc[o.kind] || 0) + 1; return acc }, {})
     const kindsPresent = Object.keys(kindCounts).sort().map((k) => ({ value: k, label: KIND_LABEL[k] ?? k, count: kindCounts[k] }))
 
-    const q = search.trim().toLowerCase()
-    const filtered = files.filter(
-      (o) => (kinds.size === 0 || kinds.has(o.kind)) && (!q || o.displayKey.toLowerCase().includes(q)),
-    )
+    const filtered = filterMedia(files.filter((o) => kinds.size === 0 || kinds.has(o.kind)), search, { nameOf: (o) => o.displayKey })
     const sorted = sortFiles(filtered, sort)
 
     const page = pageSize || Infinity
@@ -783,7 +781,7 @@ function LibraryViewer({ index, onIndexChange, onClose, onPick }) {
       actions={(item, i) => (
         <>
           {onPick && <Button size="sm" onClick={() => onPick(viewable[i])}>Use</Button>}
-          <Button variant="secondary" size="sm" onClick={() => copy(item.url)}>
+          <Button size="sm" onClick={() => copy(item.url)}>
             {copied === item.url ? 'Copied' : 'Copy URL'}
           </Button>
         </>

package/src/organisms/MediaLibraryExplorer.jsx

@@ -29,7 +29,10 @@ import useMediaQuery from '../hooks/useMediaQuery.js'
  *                              Ignored while typing and with ⌘ / Ctrl / ⌥ held
  * @param {boolean}  phoneTabs  below 768 the surface is three tabs — Browse · Files · Kinds (Kinds only
  *                              with `onKinds`); a tab picks the view, Kinds opens the overview and leaves
- *                              the surface where it was
+ *                              the surface where it was. OFF in the apps since 2026-09-29 (the `···` menu
+ *                              carries view, sort and File formats, as the Files app does); KEPT for a
+ *                              phone-first consumer whose browse surfaces are destinations of their own —
+ *                              a repo that routes Browse and Files as pages wants them one tap apart
  * @param {Function} onKinds    opens the app's file-formats overview (K, the Kinds tab)
  */
 const TABS = [
@@ -88,6 +91,7 @@ export default function MediaLibraryExplorer({ view, onViewChange, defaultView,
     <MediaLibraryBrowse
       {...pageProps}
       {...tabProps}
+      onKinds={onKinds}
       view={current}
       onViewChange={setView}
     />

package/src/organisms/MediaLibraryPages.jsx

@@ -18,9 +18,11 @@ import ContentRow from '../molecules/ContentRow.jsx'
 import SortControls from '../molecules/SortControls.jsx'
 import SearchInput from '../molecules/SearchInput.jsx'
 import MobileTabBar, { TABBAR_H } from '../molecules/MobileTabBar.jsx'
+import { filterMedia, rankMedia } from '../utilities/mediaSearch.js'
+import { useMasthead, mastheadTitleClass } from '../utilities/masthead.js'
 import { MenuItem, MenuDropdownItem, MenuDropdownDivider } from '../molecules/MenuItem.jsx'
 import { Tooltip } from '../utilities/Popover.jsx'
-import ContextMenu, { useContextMenu } from '../utilities/ContextMenu.jsx'
+import ContextMenu, { useContextMenu } from '../molecules/ContextMenu.jsx'
 import useMarquee from '../hooks/useMarquee.js'
 import useLongPress from '../hooks/useLongPress.js'
 import useMediaQuery from '../hooks/useMediaQuery.js'
@@ -116,6 +118,7 @@ export const SETTINGS_BASE = {
   filters: false, // the filter bar above the body; off until asked for
   rowColumns: false, // row view's Date/Size columns + their header; off, a row is just its name
   rowColumnWidths: { ...ROW_COL_DEFAULTS }, // px, dragged on the header's own dividers
+  countLine: 'auto', // 'auto' | 'on' | 'off' — the `N folders · N files · size` line under the body; auto = on at a desk, off on a phone or a touch device (apps review 2026-09-29)
 }
 
 /* THE FOUR VIEWS (the merge, user 2026-09-22: "they both just display files"). Columns and rows
@@ -684,7 +687,7 @@ export function MediaInspector({ files, index, onClose, onPrev, onNext, mediaUrl
   )
 }
 
-/* THE DISPLAY SETTINGS AS DATA (media-shell, user 2026-09-26: "missing settings sidebar? … or are
+/* THE DISPLAY SETTINGS AS DATA (media-hub, user 2026-09-26: "missing settings sidebar? … or are
  * we saying the shell has settings different from media?"). The rows were hard-wired JSX inside this
  * drawer, so an app page could not show them and a second settings system grew beside it. Now ONE
  * builder: this drawer renders it, and an app renders the same rows on its settings page and its own
@@ -730,6 +733,8 @@ export function mediaSettingsSections({ settings, onChange, profile }) {
         render: () => <SettingsChoice options={SORT_OPTIONS} value={settings.sortBy} onChange={(v) => set({ sortBy: v })} /> },
       { label: 'Direction', align: 'fill',
         render: () => <SettingsChoice options={[{ value: 'asc', label: '↓ Asc' }, { value: 'desc', label: '↑ Desc' }]} value={settings.sortDir} onChange={(v) => set({ sortDir: v })} /> },
+      { label: 'Count line', align: 'fill',
+        render: () => <SettingsChoice options={[{ value: 'auto', label: 'Auto' }, { value: 'on', label: 'On' }, { value: 'off', label: 'Off' }]} value={settings.countLine ?? 'auto'} onChange={(v) => set({ countLine: v })} /> },
     ] },
   ]
 }
@@ -873,6 +878,8 @@ function TrashPanel({ trash, onClose, run, confirm }) {
 }
 
 function LibraryHeader({ title, buckets, bucketId, appRoot, onBucket, bucketMeta, writable, headerActions, onSettings, onTrash, onHome, headerTrailing }) {
+  /* the app's masthead voice when a Shell sets one (2026-09-29), else the display voice as before */
+  const titleCls = mastheadTitleClass(useMasthead(), 'kol-sans-display-03')
   /* ONE BUCKET, NO DROPDOWN (user 2026-09-22) — a picker with one thing in it chooses nothing. */
   const options = buckets.length > 1 ? [{ value: 'all', label: `${title} · all` }, ...buckets.map((b) => ({ value: b.id, label: b.label }))] : []
   /* THE WORDMARK IS THE HOME BUTTON when `onHome` is given (user 2026-09-21: "it should reload,
@@ -883,10 +890,10 @@ function LibraryHeader({ title, buckets, bucketId, appRoot, onBucket, bucketMeta
     <header className="flex items-baseline justify-between gap-4">
       {onHome ? (
         <button type="button" onClick={onHome}
-          className="kol-sans-display-03 min-w-0 truncate text-left cursor-pointer transition-opacity hover:opacity-64"
+          className={`${titleCls} min-w-0 truncate text-left cursor-pointer transition-opacity hover:opacity-64`}
           aria-label={`${title} — back to the top`}>{title}</button>
       ) : (
-        <h1 className="kol-sans-display-03 min-w-0 truncate">{title}</h1>
+        <h1 className={`${titleCls} min-w-0 truncate`}>{title}</h1>
       )}
       <div className="flex items-center gap-2 min-w-0">
         {options.length > 0 && <Dropdown className="min-w-0 max-w-[45vw] md:w-48 md:max-w-none" value={appRoot ? 'all' : bucketId} onChange={onBucket} options={options} />}
@@ -918,7 +925,7 @@ function LibraryHeader({ title, buckets, bucketId, appRoot, onBucket, bucketMeta
   )
 }
 
-/* `columnHeight: 'fill'` — THE BROWSER TAKES WHAT IS LEFT OF THE WINDOW (media-shell, user 2026-09-26:
+/* `columnHeight: 'fill'` — THE BROWSER TAKES WHAT IS LEFT OF THE WINDOW (media-hub, user 2026-09-26:
  * "why isnt the browser in media shell using available height like media does?"). apps/media had it
  * as a hand-measured `calc(100dvh - 212px)` — its header, gaps and padding, counted once — so the same
  * tool one shell over got the 528 base. Measured instead: the window, less the view's own top, less
@@ -1043,6 +1050,14 @@ export function MediaLibraryBrowse({
    * the consumer's — a repo whose surfaces are routes wires its router here.
    * No tabs, no pill, and the page is exactly what it was. */
   tabs, activeTab, onTabChange,
+  /* `onKinds` — opens the app's file-formats overview. Given, the phone's `···` menu carries it
+   * under view and sort (apps review 2026-09-29: the Files app keeps everything in its `…`, and
+   * the Kinds tab was the only reason the phone had a tab bar). */
+  onKinds,
+  /* `onOpenSettings` — the gear HANDS OVER to the host (apps review 2026-09-29: three settings in
+   * media-hub, "two too many"). Given, the gear calls it and this page opens no drawer of its own —
+   * inside a Hub the Hub's Settings is the one place. Absent, the gear opens the drawer as always. */
+  onOpenSettings,
   /* `bucketLevel` — keep title → bucket → folders with ONE bucket (kol-client-olina 2026-09-23).
    * Absent, a one-bucket consumer collapses the level as ruled 2026-09-03. */
   bucketLevel = false,
@@ -1230,7 +1245,7 @@ export function MediaLibraryBrowse({
     const tooBig = (o.size ?? 0) > EDIT_CAP
     return (
       <div className="flex items-center gap-3">
-        <Button variant="secondary" size="sm" iconLeft="edit" disabled={tooBig} onClick={() => openEditor(o)}>Edit</Button>
+        <Button size="sm" iconLeft="edit" disabled={tooBig} onClick={() => openEditor(o)}>Edit</Button>
         {tooBig && <span className="kol-mono-12 text-fg-48">Over 1 MB — too large to edit here</span>}
         {!tooBig && draftKeys.has(o.key) && <span className="kol-mono-12 text-fg-48">Unsaved draft</span>}
       </div>
@@ -1755,6 +1770,10 @@ export function MediaLibraryBrowse({
    * stack there; the row view had no phone form and drew the desktop list and its preview pane
    * squeezed into 390 — 35px of rows with no names. Same query, same breakpoint as the columns. */
   const phone = useMediaQuery('(max-width: 767px)')
+  /* THE COUNT LINE'S AUTO (apps review 2026-09-29): a desk reads it, a phone spends a line on it */
+  const coarse = useMediaQuery('(pointer: coarse)')
+  const countLine = settings.countLine ?? 'auto'
+  const showCount = countLine === 'on' || (countLine === 'auto' && !phone && !coarse)
   const setView = (v) => {
     onViewChange?.(v)
     setSettings({
@@ -1816,13 +1835,13 @@ export function MediaLibraryBrowse({
    * when a file under it matches and ColumnBrowser's own partition does the
    * rest. One view, rather than a flat results list nobody asked for. Sort
    * orders the files the way the wall already sorts its own. */
-  const q = query.trim().toLowerCase()
+  const q = query.trim()
   /* SEGMENTS HIDE WHEN FOLDED, in every view (user 2026-09-23: *"we can just by default hide the
    * segments, if they serve no practical purpose"*). A `.ts` chunk cannot play on its own — its
    * stream's `.m3u8` beside it is the thing you open. The fold used to reach only the grid, so the
    * columns and rows listed every chunk. */
   const listed = useMemo(() => (settings.foldSegments ? objects.filter((o) => !isSegment(o.key)) : objects), [objects, settings.foldSegments])
-  const searched = useMemo(() => (q ? listed.filter((o) => o.key.toLowerCase().includes(q)) : listed), [listed, q])
+  const searched = useMemo(() => filterMedia(listed, q), [listed, q])
   const sortedObjects = useMemo(
     () => sortObjects(searched, settings.sortBy, settings.sortDir),
     [searched, settings.sortBy, settings.sortDir],
@@ -2205,10 +2224,7 @@ export function MediaLibraryBrowse({
   /* The palette's own ruling (2026-08-01) is that Enter COMMITS the query rather than navigating
    * to whatever happened to be first — so `onExpand` is where a committed query lands, and here
    * that means the top hit. Arrow-then-Enter and a click go through `onSelect`, same jump. */
-  const searchResults = (searchQuery.trim()
-    ? objects.filter((o) => o.key.toLowerCase().includes(searchQuery.trim().toLowerCase()))
-    : objects
-  ).slice(0, 50).map((o) => ({
+  const searchResults = rankMedia(objects, searchQuery, { limit: 50 }).map((o) => ({
     id: o.key,
     label: o.key.split('/').pop(),
     hint: o.key.slice(0, o.key.lastIndexOf('/') + 1) || 'the bucket root',
@@ -2230,7 +2246,7 @@ export function MediaLibraryBrowse({
     if (isSystemFile(o.key)) return false
     if ((q.tags ?? []).some((t) => !(o.tags ?? []).includes(t))) return false
     if ((q.kinds ?? []).length && !q.kinds.includes(kindOf(o))) return false
-    if (q.text && !o.key.toLowerCase().includes(q.text.toLowerCase())) return false
+    if (q.text && !filterMedia([o], q.text).length) return false
     return true
   }).map((o) => ({ ...o, kind: kindOf(o), poster: posterFor(o.key, keySet), displayKey: o.key })) : null
   const body = (filtered) => (smartMatches
@@ -2244,7 +2260,7 @@ export function MediaLibraryBrowse({
       <LibraryHeader title={title} buckets={buckets} bucketId={bucketMeta.id} appRoot={atTitleRoot} bucketMeta={bucketMeta} writable={writable} headerActions={headerActions} headerTrailing={headerTrailing} onTrash={trash ? () => setTrashOpen(true) : undefined}
         onHome={goTitleRoot}
         onBucket={(v) => { if (v === 'all') goTitleRoot(); else { setAppRoot(false); switchBucket(v) } }}
-        onSettings={() => setSettingsOpen(true)} />
+        onSettings={onOpenSettings ?? (() => setSettingsOpen(true))} />
 
       {/* THE BANNER SLOT — anything that must sit directly under the header and above the body.
         * The upload drop zone is why it exists: a consumer rendering it AFTER the page put it
@@ -2368,6 +2384,7 @@ export function MediaLibraryBrowse({
             label={<Icon name="more" size={16} />}
             caret={false}
             align="end"
+            size="sm"
             buttonClassName="shrink-0 px-2"
           >
             {({ close }) => (
@@ -2403,6 +2420,12 @@ export function MediaLibraryBrowse({
                     {opt.label}
                   </MenuDropdownItem>
                 ))}
+                {onKinds && (
+                  <>
+                    <MenuDropdownDivider />
+                    <MenuDropdownItem onClick={() => { onKinds(); close() }} shortcut="K">File formats</MenuDropdownItem>
+                  </>
+                )}
               </div>
             )}
           </MenuItem>
@@ -2486,7 +2509,7 @@ export function MediaLibraryBrowse({
           * slider at its right end, bare: no glyph, no readout (Finder's). */}
         {atTitleRoot && !single ? (
           <div className="flex items-center justify-between gap-4 h-4">
-          <p className="kol-mono-12 text-fg-48">
+          <p className="kol-mono-12 text-fg-48" hidden={!showCount}>
             {atTop ? '1 folder' : `${bucketList.length} ${bucketList.length === 1 ? 'bucket' : 'buckets'}`}
             {folderTree && ` · ${Object.values(folderTree).reduce((n, t) => n + (t.files ?? 0), 0)} files · ${formatSize(Object.values(folderTree).reduce((n, t) => n + (t.bytes ?? 0), 0))}`}
           </p>
@@ -2496,12 +2519,12 @@ export function MediaLibraryBrowse({
           /* ONE LINE'S HEIGHT, like the other views' count line — the slider is 24px tall and made
            * this row 8px taller than the fill budget, so the page scrolled by that much */
           <div className="flex items-center justify-between gap-4 h-4">
-            <p className="kol-mono-12 text-fg-48">
+            <p className="kol-mono-12 text-fg-48" hidden={!showCount}>
               {!settings.flat && folders.length > 0 && `${folders.length} folder${folders.length > 1 ? 's' : ''} · `}{wallFiles.length} {wallFiles.length === 1 ? 'file' : 'files'} · {formatSize(wallFiles.reduce((n, o) => n + (o.size ?? 0), 0))}
             </p>
             {sizeSlider}
           </div>
-        ) : (
+        ) : showCount && (
           <p className="kol-mono-12 text-fg-48">
             {folders.length > 0 && `${folders.length} folder${folders.length > 1 ? 's' : ''} · `}
             {rawFiles.length} {rawFiles.length === 1 ? 'file' : 'files'} · {formatSize(totalBytes)}

package/src/organisms/SectionCards.jsx

@@ -36,7 +36,7 @@ import { minHeightClass } from './sectionHeights.js'
  * @param {boolean}  [fullBleed=false]  the FILL breaks the page gutter while the content keeps it —
  *   the family's shared breakout (`sectionBleed.js`, SectionFamilyFullBleed, kol-website 2026-08-31).
  *   Any member of this family can be a filled surface, and a filled surface inside `.kol-page` has its
- *   colour clipped by the gutter on mobile. Viewport-relative, so unlike `.kol-full-bleed` it does not
+ *   color clipped by the gutter on mobile. Viewport-relative, so unlike `.kol-full-bleed` it does not
  *   over-bleed in a parent with no gutter of its own. The section's horizontal padding re-insets the
  *   CONTENT, so only the fill moves. Default false — nothing renders differently until it is passed.
  * @param {string}    sectionClassName · wrapperClassName · cardsWrapperClassName · actionsClassName · headerClassName · headerTextWidthClass  layout seams

package/src/organisms/SectionCta.jsx

@@ -30,7 +30,7 @@ import { minHeightClass } from './sectionHeights.js'
  * @param {boolean}  [fullBleed=false]  the FILL breaks the page gutter while the content keeps it —
  *   the family's shared breakout (`sectionBleed.js`, SectionFamilyFullBleed, kol-website 2026-08-31).
  *   Any member of this family can be a filled surface, and a filled surface inside `.kol-page` has its
- *   colour clipped by the gutter on mobile. Viewport-relative, so unlike `.kol-full-bleed` it does not
+ *   color clipped by the gutter on mobile. Viewport-relative, so unlike `.kol-full-bleed` it does not
  *   over-bleed in a parent with no gutter of its own. The section's horizontal padding re-insets the
  *   CONTENT, so only the fill moves. Default false — nothing renders differently until it is passed.
  * @param {string}    className     extra classes on the section

package/src/organisms/SectionFaq.jsx

@@ -21,7 +21,7 @@ import { minHeightClass } from './sectionHeights.js'
  * @param {boolean}  [fullBleed=false]  the FILL breaks the page gutter while the content keeps it —
  *   the family's shared breakout (`sectionBleed.js`, SectionFamilyFullBleed, kol-website 2026-08-31).
  *   Any member of this family can be a filled surface, and a filled surface inside `.kol-page` has its
- *   colour clipped by the gutter on mobile. Viewport-relative, so unlike `.kol-full-bleed` it does not
+ *   color clipped by the gutter on mobile. Viewport-relative, so unlike `.kol-full-bleed` it does not
  *   over-bleed in a parent with no gutter of its own. The section's horizontal padding re-insets the
  *   CONTENT, so only the fill moves. Default false — nothing renders differently until it is passed.
  * @param {string}    className · innerClassName  layout seams

package/src/organisms/SectionNewsletter.jsx

@@ -60,7 +60,7 @@ import { minHeightClass } from './sectionHeights.js'
  * @param {boolean}   [fullBleed=false]  the FILL breaks the page gutter while the content keeps it
  *   (SectionNewsletterFullBleed, kol-website 2026-08-31). This card is a filled surface inside
  *   `.kol-page`, so the gutter clipped its background and left strips of page down both sides of the
- *   colour. Fill and content padding are the same box, so a consumer could not bleed one without
+ *   color. Fill and content padding are the same box, so a consumer could not bleed one without
  *   dragging the other out with it. The breakout literal is SectionHero's, character for character —
  *   two organisms in one family must not invent two ways to leave a gutter. The section's own
  *   `px-5 sm:px-8` then re-insets the content, so only the fill moves.

package/src/organisms/SettingsPanel.jsx

@@ -196,14 +196,17 @@ export const chipCls = (on) => `${CHIP_CLS} ${on ? 'kol-control--filled' : 'text
  * @param {Array|Set} selected
  * @param {Function} onToggle (value) => void
  * @param {string} noun      the trigger's noun (default 'kinds')
+ * @param {string} variant   passed to the Dropdown like `SettingsChoice`'s — unset inherits the page's
+ *                           tone. It was hard-coded `primary` until 2026-09-29, so on a sunken settings
+ *                           page it was the one lighter dropdown in the section.
  */
-export function SettingsMulti({ options = [], selected = [], onToggle, noun = 'kinds', tone = 'default', size = 'sm', className = '' }) {
+export function SettingsMulti({ options = [], selected = [], onToggle, noun = 'kinds', tone = 'default', size = 'sm', variant, className = '' }) {
   const on = selected instanceof Set ? selected : new Set(selected)
   const opts = [
     { value: '__summary', label: `${on.size} of ${options.length} ${noun}` },
     ...options.map((o) => ({ value: o.value, label: `${on.has(o.value) ? '✓ ' : ''}${o.label ?? String(o.value)}` })),
   ]
-  return <Dropdown size={size} variant="primary" tone={tone} value="__summary" options={opts} onChange={(v) => (v === '__summary' ? null : onToggle?.(v))} className={`w-full ${className}`.trim()} />
+  return <Dropdown size={size} variant={variant} tone={tone} value="__summary" options={opts} onChange={(v) => (v === '__summary' ? null : onToggle?.(v))} className={`w-full ${className}`.trim()} />
 }
 
 /**

package/src/organisms/ShortcutsOverlay.jsx

@@ -46,13 +46,15 @@ import SettingsSections from './SettingsSections.jsx'
 const isSectioned = (list) => Array.isArray(list?.[0]?.items)
 
 /* A shortcut as a settings ROW: the label on the left, the combo as the row's
- * value. `labelWidth="auto"` makes the label yield and the combo hug — a combo
- * is one token by nature and must not wrap. */
+ * value. `labelWidth="auto"` makes the label yield and the combo hug. A combo
+ * holds on one line from `sm` up; below it, it wraps under its label (LabeledControl stacks) — media's
+ * combos are sentences ("Drag from empty space (rows: …"), and held on one line
+ * they pushed the sheet past both edges of a phone (apps review, 2026-09-29). */
 const toRow = ({ label, combo, keys }) => ({
   label,
   align: 'fill',
   labelWidth: 'auto',
-  value: <span className="text-fg-32 kol-helper-12 whitespace-nowrap">{combo ?? keys}</span>,
+  value: <span className="text-fg-32 kol-helper-12 sm:whitespace-nowrap">{combo ?? keys}</span>,
 })
 
 export default function ShortcutsOverlay({ shortcuts = [], onClose }) {
@@ -86,7 +88,9 @@ export default function ShortcutsOverlay({ shortcuts = [], onClose }) {
          * editor's is six sections — ran past both edges of the viewport with no way to reach the
          * rest. Capped to the window less a margin, scrolling inside. */
         className="kol-shortcuts-panel text-fg-64 kol-helper-12 bg-oq-04 flex flex-col gap-6 overflow-y-auto"
-        style={{ padding: 24, borderRadius: 4, maxHeight: 'calc(100dvh - 48px)' }}
+        /* and the window's WIDTH too (apps review, 2026-09-29): nothing capped it, so the widest
+         * row set the sheet's width and a phone showed its middle third */
+        style={{ padding: 24, borderRadius: 4, maxHeight: 'calc(100dvh - 48px)', maxWidth: 'calc(100vw - 32px)' }}
         onClick={(e) => e.stopPropagation()}
       >
         <SettingsSections

package/src/organisms/sectionBleed.js

@@ -7,7 +7,7 @@
  *
  * WHY IT IS A FILLED-SECTION PROBLEM, not a newsletter one. Any member of the
  * family can be a filled surface, and a filled surface inside `.kol-page` has its
- * colour clipped by the page gutter on mobile — strips of page down both sides of
+ * color clipped by the page gutter on mobile — strips of page down both sides of
  * the fill. Reported once per organism until the prop is shared.
  *
  * NOT `.kol-full-bleed`: that escape is CONTAINER-relative, so on an organism

package/src/utilities/ErrorBoundary.jsx

@@ -61,7 +61,7 @@ export default class ErrorBoundary extends Component {
 
           <div className="flex gap-4 justify-center flex-wrap">
             <Button variant="primary" onClick={this.handleReset}>Try again</Button>
-            <Button variant="secondary" href={this.props.homeHref ?? '/'}>Go home</Button>
+            <Button href={this.props.homeHref ?? '/'}>Go home</Button>
           </div>
         </div>
       </div>

package/src/utilities/FullscreenOverlay.jsx

@@ -1,6 +1,6 @@
 import { useEffect, useRef } from 'react'
 import { pushLayer, popLayer, isTopLayer } from './layerStack.js'
-import CloseButton from './CloseButton.jsx'
+import CloseButton from '../atoms/CloseButton.jsx'
 
 /**
  * FullscreenOverlay — the scrim + centred sheet every overlay in the repo

package/src/utilities/LoaderOverlay.jsx

@@ -8,7 +8,7 @@ import FullscreenOverlay from './FullscreenOverlay.jsx'
  * `loader` slot — as the overlay content. Being mounted IS being visible;
  * the parent removes this element to dismiss.
  *
- * The loader is a SLOT, not a built-in: inject a curtain (e.g. `<ColorLoader/>`
+ * The loader is a SLOT, not a built-in: inject a curtain (e.g. `<IntroLoader/>`
  * from `@kolkrabbi/kol-foundry`) via `loader` and wire its completion callback
  * yourself. The slot is mounted in a `fixed inset-0` box that escapes
  * FullscreenOverlay's centered, `--kol-container-max`-width sheet so the loader
@@ -16,7 +16,7 @@ import FullscreenOverlay from './FullscreenOverlay.jsx'
  * With neither, the loader slot renders nothing (the overlay still works).
  *
  * @param {ReactNode} children overlay content, centered (takes precedence)
- * @param {ReactNode} loader   full-screen loading curtain, e.g. foundry's ColorLoader
+ * @param {ReactNode} loader   full-screen loading curtain, e.g. foundry's IntroLoader
  */
 export default function LoaderOverlay({ children, loader }) {
   return (

package/src/utilities/Popover.jsx

@@ -7,6 +7,7 @@ import {
   flip as flipMw,
   shift as shiftMw,
   size as sizeMw,
+  hide as hideMw,
   FloatingPortal,
   FloatingFocusManager,
   useClick,
@@ -101,6 +102,7 @@ export function usePopover({
    * external DOM node (e.g. a parent container ref) instead of wiring
    * `setReference` onto the trigger. Used by TypeBlockToolbar to anchor
    * to its TypeFrame parent. */
+  middleware.push(hideMw({ strategy: 'referenceHidden' })) // last — it reads the final position
   const data = useFloating({
     open,
     onOpenChange,
@@ -110,6 +112,13 @@ export function usePopover({
     elements: referenceElement ? { reference: referenceElement } : undefined,
   })
 
+  /* A PANEL FOLLOWS ITS TRIGGER OUT OF SIGHT (2026-09-30 — docs/menus: an open menu painted over
+   * the sticky header when its trigger scrolled under it, and floated at the page's foot when it
+   * scrolled away). The panel is portalled to <body>, so no scroll container can clip it; `hide`
+   * reports when the trigger is clipped, and the panel hides with it. */
+  const hidden = data.middlewareData.hide?.referenceHidden
+  const floatingStyles = hidden ? { ...data.floatingStyles, visibility: 'hidden' } : data.floatingStyles
+
   const interactions = useInteractions([
     useClick(data.context, { enabled: click }),
     useHover(data.context, { enabled: hover, delay: hoverDelay, move: false }),
@@ -118,7 +127,7 @@ export function usePopover({
     useRole(data.context, { role }),
   ])
 
-  return { ...data, ...interactions, open }
+  return { ...data, floatingStyles, ...interactions, open }
 }
 
 /**

package/src/utilities/masthead.js

@@ -0,0 +1,39 @@
+import { createContext, useContext } from 'react'
+
+/**
+ * masthead — ONE APP, ONE MASTHEAD (apps review 2026-09-29, ruling D3). media-hub wore MEDIA in the
+ * display voice on Browse and a mono title + description on its Hub pages: two headers in one app,
+ * because each page picked its own. The voice is now the app's, set ONCE on the Shell
+ * (`AppShell masthead`) and read by every page inside it — `PageHeader` (and so `CatalogPage`,
+ * `HubHome`, `SettingsScaffold`) and the media tool's own title.
+ *
+ *   display   the default — "uppercase sans like media" (the user, 2026-09-29): the display voice,
+ *             UPPERCASE as a role (03-typography § Casing — case rides the call site, not the class),
+ *             no description line
+ *   mono      the Hub's older look — a mono title with its description under it
+ *
+ * Outside a Shell there is no context and every header renders exactly as its props say, so a
+ * site page is untouched. A page may still pass `masthead` itself (a Catalog with no Shell).
+ */
+export const MASTHEADS = {
+  display: { voice: 'sans', size: 'md', subtitle: false, upper: true },
+  mono: { voice: 'mono', size: 'sm', subtitle: true, upper: false },
+}
+
+/* the title role per voice and size — PageHeader's ladder, here so a tool's own title reads it too */
+export const TITLE_ROLES = {
+  sans: { sm: 'kol-sans-heading-03', md: 'kol-sans-display-03', lg: 'kol-sans-display-02' },
+  mono: { sm: 'kol-mono-heading-03', md: 'kol-mono-display-03', lg: 'kol-mono-display-02' },
+}
+
+export const MastheadContext = createContext(null)
+
+/** the masthead in effect — the page's own `masthead` prop, else the Shell's, else null */
+export function useMasthead(own) {
+  const shell = useContext(MastheadContext)
+  const name = own ?? shell
+  return name && MASTHEADS[name] ? { name, ...MASTHEADS[name] } : null
+}
+
+/** the title class a masthead gives — for a tool that draws its own title (media's LibraryHeader) */
+export const mastheadTitleClass = (m, fallback) => (m ? `${TITLE_ROLES[m.voice][m.size]}${m.upper ? ' uppercase' : ''}` : fallback)

package/src/utilities/mediaSearch.js

@@ -0,0 +1,41 @@
+/**
+ * mediaSearch — the media library's search, on the KOL engine (`@kolkrabbi/kol-search`).
+ *
+ * Four places in the media pages each ran their own `key.toLowerCase().includes(q)` — the browse
+ * filter, the ⌘K palette, the smart-folder text match, the picker's filter (apps review,
+ * 2026-09-29). One helper now, so the media search speaks the same language as every other KOL
+ * search: several words must ALL match, `-word` must not, `"a phrase"`, `tag:x` / `#x`,
+ * `kind:image` / `is:video`, `after:2026-09-01`. A plain substring still finds what it found.
+ *
+ * An object becomes an engine item: its file name is the title (ranked first), the whole key is a
+ * keyword (so a folder name in the path still matches), its tags and kind are facets, its upload
+ * date the date.
+ */
+import { createIndex, search } from '@kolkrabbi/kol-search'
+import { kindOf } from './mediaKinds.js'
+
+const toItem = (o, nameOf) => ({
+  id: o.key,
+  title: nameOf ? nameOf(o) : o.key.slice(o.key.lastIndexOf('/') + 1) || o.key,
+  keywords: [o.key],
+  tags: o.tags ?? [],
+  kind: o.kind ?? kindOf(o),
+  date: o.uploaded ? String(o.uploaded).slice(0, 10) : undefined,
+  o,
+})
+
+/** ranked hits, best first — the palette's order. `nameOf(o)` overrides the title (a display key). */
+export function rankMedia(objects, query, { nameOf, limit } = {}) {
+  const q = String(query ?? '').trim()
+  if (!q) return limit ? objects.slice(0, limit) : objects
+  const index = createIndex(objects.map((o) => toItem(o, nameOf)), { facets: ['kind', 'tags'], smart: ['kind'] })
+  return search(index, q, { limit }).results.map((r) => r.item.o)
+}
+
+/** the matches in their ORIGINAL order — for views that sort on their own afterwards. */
+export function filterMedia(objects, query, opts) {
+  const q = String(query ?? '').trim()
+  if (!q) return objects
+  const hit = new Set(rankMedia(objects, q, opts))
+  return objects.filter((o) => hit.has(o))
+}

package/src/utilities/searchItems.js

@@ -0,0 +1,30 @@
+/**
+ * searchItems — any list of objects, searched by the KOL engine (`@kolkrabbi/kol-search`).
+ *
+ * `ContentFilters` ran `String(item[key]).toLowerCase().includes(q)` over its `searchKeys` — one more
+ * private engine (apps review 2026-09-29: *"one engine with tiers not endless individual engines each
+ * slightly different"*). Through this, every catalog searches the same way: several words must ALL
+ * match, `-word` must not, `"a phrase"`, `tag:x` / `#x` against the item's `tags`. A single word still
+ * finds everything the substring found.
+ *
+ * The FIRST search key is the title (ranked highest); the rest are keywords. The items come back in
+ * THEIR order — a catalog sorts itself.
+ */
+import { createIndex, search } from '@kolkrabbi/kol-search'
+
+const list = (v) => (Array.isArray(v) ? v : v == null || v === '' ? [] : [v])
+
+export function filterItems(items, query, { keys = ['title'] } = {}) {
+  const q = String(query ?? '').trim()
+  if (!q) return items
+  const [first, ...rest] = keys
+  const index = createIndex(items.map((item, i) => ({
+    id: i,
+    title: String(item[first] ?? ''),
+    keywords: rest.flatMap((k) => list(item[k])).map(String),
+    tags: list(item.tags).map(String),
+    item,
+  })), { facets: ['tags'], smart: [] })
+  const hit = new Set(search(index, q).results.map((r) => r.item.item))
+  return items.filter((it) => hit.has(it))
+}

package/src/utilities/tone.js

@@ -4,7 +4,7 @@
  *
  *   primary · secondary · inverted · outline · ghost · grey · sunken
  *
- * `secondary` paints the PAGE SURFACE and `inverted` the text colour as fill
+ * `secondary` paints the PAGE SURFACE and `inverted` the text color as fill
  * (tone-secondary-is-inverse, 2026-09-03; user: "that tone should be called
  * secondary. What is currently secondary should be called inverted") — 0.134.0
  * had lifted `secondary` from Button's variant, which was already an inverse.