@kolkrabbi/kol-component 0.68.0 → 0.69.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.68.0",
+  "version": "0.69.0",
   "description": "KOL design-system components — atoms through organisms, emitting canonical kol-* classes. Pairs with @kolkrabbi/kol-theme for styling.",
   "license": "MIT",
   "type": "module",

package/src/index.js

@@ -130,6 +130,7 @@ export { default as LoaderOverlay } from './utilities/LoaderOverlay.jsx'
 export { default as MediaLibrary, MediaLibraryProvider, useMediaLibrary, MediaPicker, MediaBrowser } from './organisms/MediaLibrary.jsx'
 export { default as MediaTileGallery } from './organisms/MediaTileGallery.jsx'
 export { default as MediaViewer } from './organisms/MediaViewer.jsx'
+export { default as SettingsPanel, SettingsRow, SettingsSwitch, SettingsChoice, SettingsChipRow, SettingsFooter } from './organisms/SettingsPanel.jsx'
 export { default as NewsletterBand } from './organisms/NewsletterBand.jsx'
 export { default as RecordManager } from './organisms/RecordManager.jsx'
 export { default as SpectrumGrid } from './organisms/SpectrumGrid.jsx'

package/src/molecules/CodeBlock.jsx

@@ -51,6 +51,15 @@ const syntaxTheme = (foregroundToken = 80) => ({
     display: 'block',
     borderRadius: 0,
     border: 'none',
+    /* THE BLOCK WRAPS (06-code-surface.md: Block · pre-wrap + overflow-x auto)
+     * and this is the one place that decides it. oneDark's code style carries
+     * `whiteSpace: 'pre'`, and react-syntax-highlighter spreads the theme's
+     * code style AFTER its own `wrapLongLines` pre-wrap — so the prop, the
+     * .kol-codeblock rule and customStyle all said wrap while the <code>
+     * computed `pre`, and every long line scrolled instead (measured on
+     * /stack/vcap at 393: block 359 wide, content 465–759, CodeBlockMobile-
+     * Overflow, kol-website 2026-08-25). */
+    whiteSpace: 'pre-wrap',
     color: `color-mix(in srgb, var(--kol-surface-on-primary) ${foregroundToken}%, transparent)`
   },
   comment: {
@@ -95,7 +104,11 @@ export default function CodeBlock({ children, code: codeProp, language: language
           wrapLines={true}
           wrapLongLines={true}
           PreTag="div"
+          /* `kol-codeblock-line` names each wrapped line so the theme can
+           * reserve the copy control's lane on the FIRST one when no chip row
+           * exists (kol-components-molecules.css). */
           lineProps={{
+            className: 'kol-codeblock-line',
             style: {
               border: 'none',
               background: 'transparent',

package/src/organisms/MediaLibrary.jsx

@@ -1,12 +1,16 @@
 import { createContext, useContext, useEffect, useMemo, useState } from 'react'
 import { Icon } from '@kolkrabbi/kol-icons'
 import Button from '../atoms/Button.jsx'
+import Divider from '../atoms/Divider.jsx'
+import Input from '../atoms/Input.jsx'
 import SegmentedToggle from '../atoms/SegmentedToggle.jsx'
+import ViewToggle from '../atoms/ViewToggle.jsx'
 import FullscreenOverlay from '../utilities/FullscreenOverlay.jsx'
 import MediaCard from '../molecules/MediaCard.jsx'
 import MediaRow from '../molecules/MediaRow.jsx'
 import ContentFilters from './ContentFilters.jsx'
 import MediaViewer from './MediaViewer.jsx'
+import { SettingsChipRow, chipCls } from './SettingsPanel.jsx'
 
 /**
  * MediaLibrary — a browser over an object bucket, in two views over one
@@ -21,20 +25,24 @@ import MediaViewer from './MediaViewer.jsx'
  * Same contract as kol-dashboards / kol-chess / kol-content.
  *
  * COMPOSED, NOT BUILT. Every part is an existing DS member:
- *   ContentFilters — filter groups, animated search, view toggle, N-of-M count
  *   MediaCard      — the grid tile (thumb · download chip · name · meta · actions)
  *   MediaRow       — the list row (thumb · name · date · size · actions)
  *   MediaViewer    — the lightbox, via its `actions` slot
+ *   ContentFilters — the PICKER's chrome (search, kind filter, view toggle, N-of-M)
  *   FullscreenOverlay — the picker's scrim, dismissal and close button
- * The first pass hand-rolled a tile grid and a folder row while MediaCard and
- * MediaRow — built from this same source in the 2026-07-03 sweep — sat unused.
  *
- * NAVIGATION IS FINDER'S LIST MODEL, not click-to-enter. Folders are rows in
- * the same list with a disclosure chevron and expand IN PLACE, so the parent
- * never leaves the screen and there is no breadcrumb stacked above a divider.
- * The path bar sits at the FOOT, where Finder puts it.
+ * NAVIGATION IS CLICK-TO-ENTER + BREADCRUMB (MediaLibraryReconcile, kol-r2b2
+ * 2026-08-26). The page variant is the read-only render of kol-r2b2's
+ * `FileList` — the one the user works in on media.kolkrabbi.io — so brand
+ * `/library` and media. are ONE picture: breadcrumb on top, a stats line
+ * (level · bucket · system files hidden), folder rows that ENTER a prefix,
+ * a bare toolbar (filter · search | Flat · view · sort with direction), a
+ * 260px tile grid, and `Show N more` paging. Finder's disclose-in-place tree
+ * (2026-08-01) is DROPPED, not kept as a variant — two navigation models in
+ * one organism is the fork this ticket exists to end. The picker keeps its
+ * ContentFilters chrome and its path bar at the foot; it navigates the same way.
  *
- * Read-only by design. Upload / rename / delete stay in kol-media-admin —
+ * Read-only by design. Upload / rename / delete / select stay in kol-r2b2 —
  * write auth does not belong in a browser-shipped package.
  */
 
@@ -203,71 +211,82 @@ function pairPosters(list) {
   })
 }
 
-/**
- * Flatten the bucket's flat key list into ONE ordered row list, folders and
- * files interleaved, honouring which folders are open. The list endpoint
- * returns keys with no `prefixes` key and `?delimiter=/` changes nothing
- * (probed 2026-08-01), so the tree is derived here — this function is the
- * whole navigation feature.
- */
-function buildRows(objects, expanded, sort) {
-  const childrenOf = new Map()
-  const folders = new Set()
-
-  for (const o of objects) {
-    const dir = folderOf(o.key)
-    if (dir) {
-      /* register every ancestor so a deep key materialises its whole chain */
-      const parts = dir.slice(0, -1).split('/')
-      for (let i = 0; i < parts.length; i += 1) folders.add(`${parts.slice(0, i + 1).join('/')}/`)
-    }
-    if (!childrenOf.has(dir)) childrenOf.set(dir, [])
-    childrenOf.get(dir).push(o)
+/* ── The prefix-scoped list ────────────────────────────────────────────────
+ * The list endpoint returns keys with no `prefixes` key and `?delimiter=/`
+ * changes nothing (probed 2026-08-01), so folders are derived here from the
+ * keys under the current prefix — this function is the whole navigation. */
+function foldersUnder(list, prefix) {
+  const names = new Set()
+  for (const o of list) {
+    const rest = o.key.slice(prefix.length)
+    const i = rest.indexOf('/')
+    if (i > 0) names.add(rest.slice(0, i))
   }
+  return [...names].sort().map((name) => ({ key: `${prefix}${name}/`, label: name }))
+}
 
-  const subFoldersOf = (prefix) =>
-    [...folders].filter((f) => folderOf(f.slice(0, -1)) === prefix).sort()
+const SORT_OPTIONS = [
+  { value: 'name', label: 'Name' },
+  { value: 'date', label: 'Date' },
+  { value: 'size', label: 'Size' },
+  { value: 'kind', label: 'Kind' },
+]
 
-  const sorted = (list) => {
-    const by = {
-      name: (a, b) => a.key.localeCompare(b.key),
-      date: (a, b) => String(b.uploaded ?? '').localeCompare(String(a.uploaded ?? '')),
-      size: (a, b) => (b.size ?? 0) - (a.size ?? 0),
-      kind: (a, b) => String(a.contentType ?? '').localeCompare(String(b.contentType ?? '')),
-    }
-    return [...list].sort(by[sort] ?? by.name)
-  }
+/* Chip labels — authored here, no text-transform (the kind key is the value). */
+const KIND_LABEL = {
+  image: 'Image', video: 'Video', audio: 'Audio', text: 'Text', code: 'Code',
+  playlist: 'Playlist', font: 'Font', archive: 'Archive', other: 'Other',
+}
 
-  const rows = []
-  const walk = (prefix, depth) => {
-    for (const f of subFoldersOf(prefix)) {
-      rows.push({ type: 'folder', key: f, label: fileName(f.slice(0, -1)) + '/', depth })
-      if (expanded.has(f)) walk(f, depth + 1)
-    }
-    for (const o of sorted(childrenOf.get(prefix) ?? [])) {
-      rows.push({ type: 'file', depth, ...o, displayKey: o.displayName ?? fileName(o.key) })
-    }
-  }
-  walk('', 0)
-  return rows
+/* Sortable-header semantics (FileList): arrow-down = ascending (A→Z, oldest
+ * first, smallest first); ties fall back to the name. */
+function sortFiles(files, { by, dir }) {
+  const d = dir === 'desc' ? -1 : 1
+  const name = (a, b) => a.displayKey.localeCompare(b.displayKey)
+  const cmp = {
+    name,
+    date: (a, b) => String(a.uploaded ?? '').localeCompare(String(b.uploaded ?? '')) || name(a, b),
+    size: (a, b) => (a.size ?? 0) - (b.size ?? 0) || name(a, b),
+    kind: (a, b) => a.kind.localeCompare(b.kind) || name(a, b),
+  }[by] ?? name
+  return [...files].sort((a, b) => d * cmp(a, b))
 }
 
 /**
- * MediaLibraryProvider — the headless core: one list call, client-side tree
- * derivation, the open-folder set and the sort key.
+ * MediaLibraryProvider — the headless core: one list call, then a
+ * PREFIX-SCOPED view over it: the folders directly under the prefix, the
+ * files at that level (or the whole subtree in `flat`), the kind allow-list,
+ * the search, the sort with direction, and paging.
  *
  * @param {object} client   `{ listMedia, mediaUrl, proxied? }` — required
  * @param {string|string[]} accept  'all' (default) = everything · one kind ·
  *   or an allow-list, `['image','video']`, which is what a picker wants.
  *   Kinds: image · video · audio · text · code · playlist · font · archive ·
  *   other. Browsing never filters by default.
+ * @param {number}  pageSize     rows mounted before `Show N more` (60; 0 = all)
+ * @param {object}  defaultSort  `{ by, dir }` — `{ by: 'date', dir: 'desc' }`
+ * @param {boolean} flat         start in flat mode (every object under the prefix)
  */
-export function MediaLibraryProvider({ client, accept = 'all', children }) {
+export function MediaLibraryProvider({
+  client,
+  accept = 'all',
+  pageSize = 60,
+  defaultSort = { by: 'date', dir: 'desc' },
+  flat: initialFlat = false,
+  children,
+}) {
   const [objects, setObjects] = useState([])
-  const [expanded, setExpanded] = useState(() => new Set())
-  const [sort, setSort] = useState('name')
   const [loading, setLoading] = useState(true)
   const [error, setError] = useState(null)
+  const [prefix, setPrefix] = useState('')
+  const [flat, setFlat] = useState(initialFlat)
+  const [sort, setSortState] = useState(defaultSort)
+  const [search, setSearch] = useState('')
+  const [kinds, setKinds] = useState(() => new Set())
+  /* Paging is keyed to WHAT is listed: prefix / flat / search / kinds change →
+   * back to one page, or walking into a folder would inherit the page count
+   * from the flat view you just left. Derived, not an effect. */
+  const [paging, setPaging] = useState({ id: null, visible: 0 })
 
   useEffect(() => {
     if (!client) return undefined
@@ -283,47 +302,97 @@ export function MediaLibraryProvider({ client, accept = 'all', children }) {
     return () => { cancelled = true; controller.abort() }
   }, [client])
 
-  const toggleFolder = (key) =>
-    setExpanded((prev) => {
+  /* click an inactive field → ascending; click the active one → flip */
+  const sortBy = (by) =>
+    setSortState((s) => (s.by === by ? { by, dir: s.dir === 'asc' ? 'desc' : 'asc' } : { by, dir: 'asc' }))
+  const toggleKind = (k) =>
+    setKinds((prev) => {
       const next = new Set(prev)
-      if (next.has(key)) next.delete(key)
-      else next.add(key)
+      if (next.has(k)) next.delete(k)
+      else next.add(k)
       return next
     })
 
   const value = useMemo(() => {
     const annotated = objects.map((o) => ({ ...o, kind: kindOf(o) }))
-    const systemCount = annotated.reduce((n, o) => n + (o.kind === 'system' ? 1 : 0), 0)
-
+    const scoped = prefix ? annotated.filter((o) => o.key.startsWith(prefix)) : annotated
+    const folders = foldersUnder(scoped, prefix)
+    /* level = the direct children; flat = every object under the prefix */
+    const level = flat ? scoped : scoped.filter((o) => !o.key.slice(prefix.length).includes('/'))
+    /* .DS_Store × 116 in the website bucket — dropped from the list, counted
+     * and reported: hiding them silently would be the same lie as the
+     * level-only totals were. */
+    const systemCount = level.reduce((n, o) => n + (o.kind === 'system' ? 1 : 0), 0)
     /* Fold before pairing: a poster must be matched against real image keys,
      * and resolution sets must be collapsed after that or the poster's own
      * width suffix would swallow it. */
-    const visible = foldResolutionSets(
-      pairPosters(foldHlsSegments(annotated.filter((o) => o.kind !== 'system'))),
+    const folded = foldResolutionSets(pairPosters(foldHlsSegments(level.filter((o) => o.kind !== 'system'))))
+    const files = folded
+      .filter(acceptsKind(accept))
+      .map((o) => ({ ...o, displayKey: o.displayName ?? (flat ? o.key.slice(prefix.length) : fileName(o.key)) }))
+
+    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 sorted = sortFiles(filtered, sort)
+
+    const page = pageSize || Infinity
+    const listId = `${prefix}|${flat}|${q}|${[...kinds].sort().join(',')}|${pageSize}`
+    const visible = paging.id === listId ? paging.visible : page
+    const shown = sorted.slice(0, visible)
+    const more = sorted.length - shown.length
 
-    const kept = visible.filter(acceptsKind(accept))
     /* The lightbox pages images and videos; a .json in that list is a broken
-     * frame with a next-arrow. Its index space is this list, not `files`. */
-    const viewable = kept.filter((o) => o.kind === 'image' || o.kind === 'video')
+     * frame with a next-arrow. Its index space is this list, not `sorted`. */
+    const viewable = sorted.filter((o) => o.kind === 'image' || o.kind === 'video')
+
+    const bucketFiles = annotated.reduce((n, o) => n + (o.kind === 'system' ? 0 : 1), 0)
+    const bucketBytes = annotated.reduce((n, o) => n + (o.size ?? 0), 0)
 
     return {
-      objects: kept,
-      rows: buildRows(kept, expanded, sort),
-      files: kept,
-      viewable,
-      kinds: [...new Set(kept.map((o) => o.kind))].sort(),
-      systemCount,
-      expanded,
-      toggleFolder,
+      objects: files,
+      files,
+      filtered,
+      sorted,
+      shown,
+      more,
+      pageSize: page,
+      showMore: () => setPaging({ id: listId, visible: visible + page }),
+      prefix,
+      setPrefix,
+      crumbs: prefix ? prefix.replace(/\/$/, '').split('/') : [],
+      folders,
+      flat,
+      setFlat,
+      kindsPresent,
+      kinds,
+      toggleKind,
+      search,
+      setSearch,
       sort,
-      setSort,
+      sortBy,
+      stats: {
+        folders: folders.length,
+        files: filtered.length,
+        rawFiles: files.length,
+        bytes: files.reduce((n, o) => n + (o.size ?? 0), 0),
+        bucketFiles,
+        bucketBytes,
+        atRoot: !prefix,
+        systemCount,
+        filtering: kinds.size > 0 || q.length > 0,
+      },
+      viewable,
       loading,
       error,
       mediaUrl: client?.mediaUrl ?? ((key) => key),
       proxied: client?.proxied ?? ((url) => url),
     }
-  }, [objects, expanded, sort, loading, error, accept, client])
+  }, [objects, prefix, flat, sort, search, kinds, paging, pageSize, loading, error, accept, client])
 
   return <MediaLibraryContext.Provider value={value}>{children}</MediaLibraryContext.Provider>
 }
@@ -336,27 +405,12 @@ export function useMediaLibrary() {
   return ctx
 }
 
-function withProvider(node, { client, accept }) {
+function withProvider(node, { client, accept, pageSize, defaultSort, flat }) {
   if (!client) return node
-  return <MediaLibraryProvider client={client} accept={accept}>{node}</MediaLibraryProvider>
-}
-
-/* Indentation per tree depth. A rem step rather than a magic pixel, and it
- * rides the spacing scale's 1rem rung. */
-const indent = (depth) => ({ paddingInlineStart: `calc(${depth} * var(--kol-spacing-4))` })
-
-function FolderRow({ row, open, onToggle }) {
   return (
-    <li
-      className="kol-media-folder"
-      style={indent(row.depth)}
-      onClick={onToggle}
-      aria-expanded={open}
-    >
-      <Icon name={open ? 'chevron-down' : 'chevron-right'} size={14} />
-      <Icon name="folder" size={16} />
-      <span className="kol-mono-12 text-emphasis flex-1">{row.label}</span>
-    </li>
+    <MediaLibraryProvider client={client} accept={accept} pageSize={pageSize} defaultSort={defaultSort} flat={flat}>
+      {node}
+    </MediaLibraryProvider>
   )
 }
 
@@ -429,151 +483,390 @@ function Thumb({ row, mediaUrl }) {
   )
 }
 
-/* Folders, then the tiles or rows. Shared by both views — the modal shell and
- * the pick action are the ONLY differences between them. */
-function LibraryBody({ rows, viewMode, onOpen, onPick }) {
-  const { expanded, toggleFolder, mediaUrl, loading, error, viewable } = useMediaLibrary()
+/* One folder, click-to-enter. `struck` = flat mode: the folder is bypassed
+ * but still navigable, so it stays and reads de-emphasised. Box in
+ * .kol-media-folder (kol-components-organisms.css). */
+function FolderRow({ folder, struck = false, onEnter }) {
+  return (
+    <li className="kol-media-folder" onClick={onEnter}>
+      <span className="flex h-8 w-8 shrink-0 items-center justify-center text-meta">
+        <Icon name="folder" size={18} />
+      </span>
+      <span className={`kol-mono-12 flex-1 ${struck ? 'line-through text-meta' : 'text-body'}`}>{folder.label}</span>
+      <Icon name="chevron-right" size={14} className="text-subtle" />
+    </li>
+  )
+}
+
+function FolderRows() {
+  const { folders, flat, setPrefix } = useMediaLibrary()
+  if (!folders.length) return null
+  return (
+    <ul className="kol-media-list">
+      {folders.map((f) => (
+        <FolderRow key={f.key} folder={f} struck={flat} onEnter={() => setPrefix(f.key)} />
+      ))}
+    </ul>
+  )
+}
+
+/* Breadcrumb — `root / seg / seg`, every crumb a step back. */
+function Breadcrumb({ className = '' }) {
+  const { crumbs, setPrefix } = useMediaLibrary()
+  return (
+    <div className={`flex items-center gap-1 kol-mono-12 text-meta ${className}`}>
+      <button type="button" className="hover:text-emphasis transition-colors" onClick={() => setPrefix('')}>root</button>
+      {crumbs.map((seg, i) => {
+        const to = `${crumbs.slice(0, i + 1).join('/')}/`
+        return (
+          <span key={to} className="flex items-center gap-1">
+            <span>/</span>
+            <button type="button" className="hover:text-emphasis transition-colors" onClick={() => setPrefix(to)}>{seg}</button>
+          </span>
+        )
+      })}
+    </div>
+  )
+}
+
+/* The stats line. Whole-bucket figures at root or in flat — the level-only
+ * line used to read "0 files · 0 B" at a B2 root: true of the level, a lie
+ * about the bucket. */
+function Stats() {
+  const { stats: s, flat } = useMediaLibrary()
+  return (
+    <p className="kol-mono-12 text-meta">
+      {s.folders > 0 && `${s.folders} folder${s.folders > 1 ? 's' : ''} · `}
+      {s.filtering && s.rawFiles !== s.files ? `${s.files} of ${s.rawFiles}` : s.rawFiles}
+      {' '}{s.rawFiles === 1 ? 'file' : 'files'} · {formatSize(s.bytes)}
+      {(s.atRoot || flat) && s.rawFiles !== s.bucketFiles && (
+        <span className="text-subtle">{'  ·  bucket: '}{s.bucketFiles} files · {formatSize(s.bucketBytes)}</span>
+      )}
+      {s.systemCount > 0 && (
+        <span className="text-subtle">{'  ·  '}{s.systemCount} system file{s.systemCount === 1 ? '' : 's'} hidden</span>
+      )}
+    </p>
+  )
+}
+
+/* Sort — label buttons; the active one carries the direction glyph. */
+function SortControls() {
+  const { sort, sortBy } = useMediaLibrary()
+  return (
+    <div className="flex items-center gap-4">
+      {SORT_OPTIONS.map((opt) => {
+        const active = sort.by === opt.value
+        return (
+          <button
+            key={opt.value}
+            type="button"
+            aria-pressed={active}
+            onClick={() => sortBy(opt.value)}
+            className={`kol-mono-12 flex items-center gap-1 transition-colors ${active ? 'text-emphasis' : 'text-meta hover:text-body'}`}
+          >
+            {opt.label}
+            {active && <Icon name={sort.dir === 'asc' ? 'arrow-down' : 'arrow-up'} size={10} />}
+          </button>
+        )
+      })}
+    </div>
+  )
+}
+
+/* The bare toolbar — filter · search on the left; Flat · view · sort on the
+ * right. No title: that is the consumer's page header. The icon buttons are
+ * DS Buttons on the nav rung (the box has an owner), `pressed` when the
+ * filter is open or narrowing. */
+function Toolbar({ viewMode, onViewMode }) {
+  const { search, setSearch, kindsPresent, kinds, toggleKind, flat, setFlat } = useMediaLibrary()
+  const [filterOpen, setFilterOpen] = useState(false)
+  const [searchOpen, setSearchOpen] = useState(false)
+
+  return (
+    <>
+      <div className="flex items-center justify-between gap-4">
+        <div className="flex items-center gap-2">
+          <Button
+            variant="nav"
+            size="sm"
+            iconOnly="filter"
+            iconSize={16}
+            quiet
+            pressed={filterOpen || kinds.size > 0}
+            aria-label="Toggle kind filter"
+            onClick={() => setFilterOpen((v) => !v)}
+          />
+          {searchOpen ? (
+            <Input
+              size="sm"
+              variant="outline"
+              width="200px"
+              value={search}
+              autoFocus
+              placeholder="search name…"
+              onChange={(e) => setSearch(e.target.value)}
+              onKeyDown={(e) => { if (e.key === 'Escape') { setSearch(''); setSearchOpen(false) } }}
+              onBlur={() => { if (!search) setSearchOpen(false) }}
+            />
+          ) : (
+            <Button
+              variant="nav"
+              size="sm"
+              iconOnly="search"
+              iconSize={16}
+              quiet
+              pressed={search.length > 0}
+              aria-label="Search"
+              onClick={() => setSearchOpen(true)}
+            />
+          )}
+        </div>
+        <div className="flex items-center gap-3">
+          <button
+            type="button"
+            aria-pressed={flat}
+            title="Show all files recursively"
+            onClick={() => setFlat(!flat)}
+            className={chipCls(flat)}
+          >
+            Flat
+          </button>
+          <ViewToggle viewMode={viewMode} onViewChange={onViewMode} variant="icon" />
+          <Divider variant="vertical" />
+          <SortControls />
+        </div>
+      </div>
+      {filterOpen && (
+        <div className="flex items-center gap-2">
+          <span className="kol-mono-12 text-subtle">Kind</span>
+          <SettingsChipRow options={kindsPresent} selected={kinds} onToggle={toggleKind} />
+        </div>
+      )}
+    </>
+  )
+}
+
+/* The tiles or the rows over ONE paged list — shared by the page and the
+ * picker; `onPick` is the only difference between them. */
+function FilesBody({ files, viewMode, onOpen, onPick }) {
+  const { mediaUrl, viewable, prefix, stats, more, pageSize, showMore } = useMediaLibrary()
   const [copied, copy] = useCopy()
 
-  if (error) return <p className="kol-helper-12 text-ui-error">Couldn’t load: {error}</p>
-  if (loading) return <p className="kol-helper-12 text-meta">Loading…</p>
-  if (rows.length === 0) return <p className="kol-helper-12 text-meta">Nothing here.</p>
+  if (files.length === 0) {
+    return (
+      <p className="kol-mono-12 text-meta">
+        {stats.filtering ? 'No files match.' : `No files${prefix ? ` in "${prefix}"` : ''} yet.`}
+      </p>
+    )
+  }
 
-  const files = rows.filter((r) => r.type === 'file')
   /* Index into `viewable`, which is what the lightbox pages — indexing into the
    * filtered rows meant a search narrowing the grid opened the wrong file. */
   const openerFor = (row) => {
     const i = viewable.findIndex((f) => f.key === row.key)
     return i < 0 ? undefined : () => onOpen(i)
   }
-
-  /* Copy hands over the full-size variant, not the thumbnail the tile loaded. */
+  /* Copy and download hand over the full-size variant, not the thumbnail. */
   const urlFor = (row) => mediaUrl(row.fullKey ?? row.key)
 
+  const thumbFor = (row) => {
+    const open = openerFor(row)
+    return (
+      <div
+        className={`w-full h-full flex items-center justify-center bg-fg-04 overflow-hidden${open ? ' cursor-zoom-in' : ''}`}
+        onClick={open}
+      >
+        <Thumb row={row} mediaUrl={mediaUrl} />
+      </div>
+    )
+  }
   const actionsFor = (row) => (
     <div className="flex items-center gap-2">
       {onPick && <Button size="sm" onClick={() => onPick(row)}>Use</Button>}
       <Button variant="secondary" size="sm" onClick={() => copy(urlFor(row))}>
         {copied === urlFor(row) ? 'Copied' : 'Copy URL'}
       </Button>
+      <Button variant="ghost" size="sm" iconOnly="download" iconSize={14} href={urlFor(row)} aria-label={`Download ${row.displayKey}`} />
     </div>
   )
+  const nameFor = (row) => <p className="kol-mono-12 text-body truncate" title={row.key}>{row.displayKey}</p>
+  const date = (row) => (row.uploaded ? String(row.uploaded).slice(0, 10) : '')
 
-  if (viewMode === 'list') {
-    return (
-      <ul className="kol-media-scroll kol-media-list">
-        {rows.map((row) =>
-          row.type === 'folder' ? (
-            <FolderRow key={row.key} row={row} open={expanded.has(row.key)} onToggle={() => toggleFolder(row.key)} />
-          ) : (
-            <div key={row.key} style={indent(row.depth)}>
-              <MediaRow
-                thumb={<Thumb row={row} mediaUrl={mediaUrl} />}
-                name={
-                  openerFor(row) ? (
-                    <button type="button" className="kol-mono-12 text-emphasis" onClick={openerFor(row)}>
-                      {row.displayKey}
-                    </button>
-                  ) : (
-                    <span className="kol-mono-12 text-emphasis">{row.displayKey}</span>
-                  )
-                }
-                date={row.uploaded ? String(row.uploaded).slice(0, 10) : ''}
-                size={formatSize(row.size)}
-                actions={actionsFor(row)}
-              />
-            </div>
-          ),
-        )}
-      </ul>
-    )
-  }
+  return (
+    <>
+      {viewMode === 'list' ? (
+        <ul className="kol-media-list">
+          {files.map((row) => (
+            <MediaRow
+              key={row.key}
+              thumb={thumbFor(row)}
+              name={nameFor(row)}
+              date={date(row)}
+              size={formatSize(row.size)}
+              actions={actionsFor(row)}
+            />
+          ))}
+        </ul>
+      ) : (
+        <ul className="kol-media-grid">
+          {files.map((row) => (
+            <MediaCard
+              key={row.key}
+              thumb={thumbFor(row)}
+              name={nameFor(row)}
+              meta={`${formatSize(row.size)}${date(row) ? ` · ${date(row)}` : ''}`}
+              downloadHref={urlFor(row)}
+              actions={actionsFor(row)}
+            />
+          ))}
+        </ul>
+      )}
+      {more > 0 && (
+        <button
+          type="button"
+          onClick={showMore}
+          className="kol-mono-12 text-meta hover:text-emphasis transition-colors self-start py-2"
+        >
+          Show {Math.min(more, pageSize)} more · {more} remaining
+        </button>
+      )}
+    </>
+  )
+}
+
+/* The lightbox is MediaViewer — the DS already has ONE fullscreen paged viewer
+ * and this is not a second one. Use / Copy URL ride its `actions` slot. */
+function LibraryViewer({ index, onIndexChange, onClose, onPick }) {
+  const { viewable, mediaUrl } = useMediaLibrary()
+  const [copied, copy] = useCopy()
+
+  /* Full-size in the lightbox — `key` is the thumbnail variant for folded sets. */
+  const media = viewable.map((o) => ({
+    url: mediaUrl(o.fullKey ?? o.key),
+    alt: fileName(o.key),
+    kind: o.kind === 'video' ? 'video' : 'image',
+    caption: `${o.displayName ?? fileName(o.key)} · ${formatSize(o.size)}`,
+  }))
 
   return (
-    <div className="kol-media-scroll">
-      <ul className="kol-media-list">
-        {rows.filter((r) => r.type === 'folder').map((row) => (
-          <FolderRow key={row.key} row={row} open={expanded.has(row.key)} onToggle={() => toggleFolder(row.key)} />
-        ))}
-      </ul>
-      <ul className="kol-media-grid">
-        {files.map((row) => (
-          <MediaCard
-            key={row.key}
-            thumb={
-              <div
-                className={openerFor(row) ? 'w-full h-full cursor-pointer' : 'w-full h-full'}
-                onClick={openerFor(row)}
-              >
-                <Thumb row={row} mediaUrl={mediaUrl} />
-              </div>
-            }
-            name={<p className="kol-mono-12 text-emphasis truncate">{row.displayKey}</p>}
-            meta={`${formatSize(row.size)}${row.uploaded ? ` · ${String(row.uploaded).slice(0, 10)}` : ''}`}
-            /* The set's largest variant, not the thumbnail the tile painted. */
-            downloadHref={mediaUrl(row.fullKey ?? row.key)}
-            actions={actionsFor(row)}
-          />
-        ))}
-      </ul>
-    </div>
+    <MediaViewer
+      open={index !== null}
+      media={media}
+      index={index ?? 0}
+      onIndexChange={onIndexChange}
+      onClose={onClose}
+      actions={(item, i) => (
+        <>
+          {onPick && <Button size="sm" onClick={() => onPick(viewable[i])}>Use</Button>}
+          <Button variant="secondary" size="sm" onClick={() => copy(item.url)}>
+            {copied === item.url ? 'Copied' : 'Copy URL'}
+          </Button>
+        </>
+      )}
+    />
   )
 }
 
-/* Finder puts the path at the window FOOT, not stacked above the content. The
- * hidden-system count rides the same bar — hiding 118 `.DS_Store` files without
- * saying so is the same silent drop this component was filed for. */
-function PathBar({ rows, systemCount }) {
-  const open = rows.filter((r) => r.type === 'folder' && r.depth > 0)
-  const trail = open.length ? open[open.length - 1].key.replace(/\/$/, '').split('/') : []
+/* ── The PAGE — FileList's read-only render ─────────────────────────────── */
+function BrowserShell({ onSelect }) {
+  const lib = useMediaLibrary()
+  const [viewMode, setViewMode] = useState('grid')
+  const [viewerIndex, setViewerIndex] = useState(null)
+
+  const pick = onSelect
+    ? (o) => onSelect(lib.mediaUrl(o.fullKey ?? o.key), { contentType: o.contentType, kind: o.kind })
+    : undefined
+
   return (
-    <div className="kol-media-pathbar">
-      <Icon name="folder" size={12} />
-      <span className="kol-helper-12 text-meta">root</span>
-      {trail.map((seg) => (
-        <span key={seg} className="flex items-center gap-1">
-          <Icon name="chevron-right" size={10} />
-          <span className="kol-helper-12 text-meta">{seg}</span>
-        </span>
-      ))}
-      {systemCount > 0 && (
-        <span className="kol-helper-12 text-meta ms-auto">
-          {systemCount} system file{systemCount === 1 ? '' : 's'} hidden
-        </span>
+    <div className="kol-media-browser gap-3">
+      <Breadcrumb />
+      <Stats />
+      {lib.error && <p className="kol-mono-12 text-ui-error">Couldn’t load: {lib.error}</p>}
+      {lib.loading && <p className="kol-mono-12 text-meta">Loading…</p>}
+      {!lib.loading && !lib.error && lib.stats.folders === 0 && lib.stats.rawFiles === 0 && (
+        <p className="kol-mono-12 text-meta">No files{lib.prefix ? ` in "${lib.prefix}"` : ''} yet.</p>
+      )}
+      <FolderRows />
+      {lib.stats.rawFiles > 0 && (
+        <div className="flex flex-col gap-3">
+          <Toolbar viewMode={viewMode} onViewMode={setViewMode} />
+          <Divider />
+          <FilesBody files={lib.shown} viewMode={viewMode} onOpen={setViewerIndex} onPick={pick} />
+        </div>
+      )}
+      {viewerIndex !== null && lib.viewable[viewerIndex] && (
+        <LibraryViewer
+          index={viewerIndex}
+          onIndexChange={setViewerIndex}
+          onClose={() => setViewerIndex(null)}
+          onPick={pick}
+        />
       )}
     </div>
   )
 }
 
+/* ── The PICKER — ContentFilters chrome, path bar at the foot ───────────── */
+
 const VIEW_OPTIONS = [
   { value: 'grid', icon: 'grid', label: 'Grid' },
   { value: 'list', icon: 'view-list', label: 'List' },
 ]
 
-/* Sort is a SegmentedToggle — the DS's joined N-way control. The first
- * pass hand-rolled four <button className="kol-helper-12"> instead. */
-const SORTS = [
-  { value: 'name', label: 'name' },
-  { value: 'date', label: 'date' },
-  { value: 'size', label: 'size' },
-  { value: 'kind', label: 'kind' },
-]
+/* The path at the FOOT of the picker card; the hidden-system count rides it —
+ * hiding 118 `.DS_Store` files without saying so is the same silent drop this
+ * component was filed for. */
+function PathBar() {
+  const { stats } = useMediaLibrary()
+  return (
+    <div className="kol-media-pathbar">
+      <Icon name="folder" size={12} />
+      <Breadcrumb />
+      {stats.systemCount > 0 && (
+        <span className="kol-helper-12 text-meta ms-auto">
+          {stats.systemCount} system file{stats.systemCount === 1 ? '' : 's'} hidden
+        </span>
+      )}
+    </div>
+  )
+}
 
-/* The chrome — ContentFilters owns the animated search, the filter groups, the
- * view toggle and the N-of-M count. It was hand-rolled as a static <Input> on
- * the first pass while this organism sat one import away. */
+function PickerBody({ items, viewMode, onOpen, onPick }) {
+  const { folders, flat, setPrefix, loading, error, more, pageSize, showMore } = useMediaLibrary()
+  if (error) return <p className="kol-helper-12 text-ui-error">Couldn’t load: {error}</p>
+  if (loading) return <p className="kol-helper-12 text-meta">Loading…</p>
+  const files = items.filter((r) => r.type !== 'folder')
+  const shownFolders = items.filter((r) => r.type === 'folder')
+  if (items.length === 0) return <p className="kol-helper-12 text-meta">Nothing here.</p>
+  return (
+    <div className="kol-media-scroll flex flex-col gap-3">
+      {shownFolders.length > 0 && (
+        <ul className="kol-media-list">
+          {shownFolders.map((f) => (
+            <FolderRow key={f.key} folder={f} struck={flat} onEnter={() => setPrefix(f.key)} />
+          ))}
+        </ul>
+      )}
+      <FilesBody files={files.slice(0, files.length - Math.max(0, more))} viewMode={viewMode} onOpen={onOpen} onPick={onPick} />
+      {void folders}{void pageSize}{void showMore}
+    </div>
+  )
+}
+
+/* The picker's chrome — ContentFilters owns the animated search, the kind
+ * filter, the view toggle and the N-of-M count; sort rides its header slot. */
 function LibraryChrome({ onOpen, onPick }) {
-  const { rows, sort, setSort, kinds, systemCount } = useMediaLibrary()
+  const { folders, sorted, sort, sortBy } = useMediaLibrary()
   const [viewMode, setViewMode] = useState('grid')
 
   const items = useMemo(
-    () => rows.map((r) => ({
-      ...r,
-      name: r.type === 'folder' ? r.label : r.displayKey,
-      kind: r.type === 'folder' ? 'folder' : r.kind,
-    })),
-    [rows],
+    () => [
+      ...folders.map((f) => ({ ...f, type: 'folder', name: f.label, kind: 'folder' })),
+      ...sorted.map((o) => ({ ...o, type: 'file', name: o.displayKey })),
+    ],
+    [folders, sorted],
   )
+  const kinds = useMemo(() => [...new Set(sorted.map((o) => o.kind))].sort(), [sorted])
 
   return (
     <>
@@ -587,60 +880,19 @@ function LibraryChrome({ onOpen, onPick }) {
         onViewModeChange={setViewMode}
         viewModeOptions={VIEW_OPTIONS}
         mutuallyExclusiveFilters={['kind']}
-        /* Derived — a hard-coded image/video/folder list is how the filter bar
-         * denied the existence of the audio and data the provider now keeps. */
         filterGroups={[{ label: 'Kind', key: 'kind', values: ['folder', ...kinds] }]}
         headerActions={
-          <SegmentedToggle
-            size="sm"
-            value={sort}
-            onChange={setSort}
-            options={SORTS}
-            ariaLabel="Sort by"
-          />
+          <SegmentedToggle size="sm" value={sort.by} onChange={sortBy} options={SORT_OPTIONS} ariaLabel="Sort by" />
         }
         renderItem={(filtered, mode) => (
-          <LibraryBody rows={filtered} viewMode={mode} onOpen={onOpen} onPick={onPick} />
+          <PickerBody items={filtered} viewMode={mode} onOpen={onOpen} onPick={onPick} />
         )}
       />
-      <PathBar rows={rows} systemCount={systemCount} />
+      <PathBar />
     </>
   )
 }
 
-/* The lightbox is MediaViewer — the DS already has ONE fullscreen paged viewer
- * and this is not a second one. Use / Copy URL ride its `actions` slot. */
-function LibraryViewer({ index, onIndexChange, onClose, onPick }) {
-  const { viewable, mediaUrl } = useMediaLibrary()
-  const [copied, copy] = useCopy()
-
-  /* Full-size in the lightbox — `key` is the thumbnail variant for folded sets. */
-  const media = viewable.map((o) => ({
-    url: mediaUrl(o.fullKey ?? o.key),
-    alt: fileName(o.key),
-    kind: o.kind === 'video' ? 'video' : 'image',
-    caption: `${o.displayName ?? fileName(o.key)} · ${formatSize(o.size)}`,
-  }))
-
-  return (
-    <MediaViewer
-      open={index !== null}
-      media={media}
-      index={index ?? 0}
-      onIndexChange={onIndexChange}
-      onClose={onClose}
-      actions={(item, i) => (
-        <>
-          {onPick && <Button size="sm" onClick={() => onPick(viewable[i])}>Use</Button>}
-          <Button variant="secondary" size="sm" onClick={() => copy(item.url)}>
-            {copied === item.url ? 'Copied' : 'Copy URL'}
-          </Button>
-        </>
-      )}
-    />
-  )
-}
-
 function PickerShell({ onClose, onPick }) {
   const { viewable, mediaUrl } = useMediaLibrary()
   const [viewerIndex, setViewerIndex] = useState(null)
@@ -676,34 +928,37 @@ function PickerShell({ onClose, onPick }) {
 /**
  * MediaLibrary — ONE component, two variants. The user's ruling 2026-08-01:
  * "arent different components, they are more like variants, same shit
- * different viewing." He is right — `page` and `modal` render the identical
- * body and differ only in the shell around it and whether picking closes.
- *
- * Variant is CONTAINER GEOMETRY ONLY, the ThemeToggle precedent: everything
- * else is a prop. `MediaBrowser` and `MediaPicker` survive below as thin
- * aliases so no call site breaks.
+ * different viewing." `page` and `modal` differ in the shell around the body
+ * and in whether picking closes.
  *
- * @param {string}   variant  'page' (in-flow, fills its box) | 'modal' (overlay)
+ * @param {string}   variant  'page' (in-flow, FileList's render) | 'modal' (overlay picker)
  * @param {boolean}  open     modal only — mounts the overlay
  * @param {object}   client   `{ listMedia, mediaUrl, proxied? }`; omit inside a provider
  * @param {string|string[]} accept  'all' (default) = everything · one kind · an
  *   allow-list `['image','video']`
+ * @param {number}   pageSize     rows mounted before `Show N more` (60; 0 = all)
+ * @param {object}   defaultSort  `{ by, dir }` (date desc)
+ * @param {boolean}  flat         start in flat mode
  * @param {Function} onClose  modal only — Esc, backdrop, close button
- * @param {Function} onSelect `(url, { contentType })`. In `modal` it also closes.
+ * @param {Function} onSelect `(url, { contentType, kind })`. In `modal` it also closes.
  */
 export default function MediaLibrary({
   variant = 'page',
   open = true,
   client,
   accept = 'all',
+  pageSize = 60,
+  defaultSort = { by: 'date', dir: 'desc' },
+  flat = false,
   onClose,
   onSelect = null,
 }) {
+  const opts = { client, accept, pageSize, defaultSort, flat }
   if (variant === 'modal') {
     if (!open) return null
-    return withProvider(<PickerShell onClose={onClose} onPick={onSelect} />, { client, accept })
+    return withProvider(<PickerShell onClose={onClose} onPick={onSelect} />, opts)
   }
-  return withProvider(<BrowserShell onSelect={onSelect} />, { client, accept })
+  return withProvider(<BrowserShell onSelect={onSelect} />, opts)
 }
 
 /** Alias — `MediaLibrary variant="modal"`. Kept so existing call sites and the
@@ -721,32 +976,8 @@ export function MediaPicker({ open, client, accept = 'all', onClose, onPick }) {
   )
 }
 
-function BrowserShell({ onSelect }) {
-  const { viewable, mediaUrl } = useMediaLibrary()
-  const [viewerIndex, setViewerIndex] = useState(null)
-
-  const pick = onSelect
-    ? (o) => onSelect(mediaUrl(o.fullKey ?? o.key), { contentType: o.contentType, kind: o.kind })
-    : undefined
-
-  return (
-    <div className="kol-media-browser">
-      <LibraryChrome onOpen={setViewerIndex} onPick={pick} />
-
-      {viewerIndex !== null && viewable[viewerIndex] && (
-        <LibraryViewer
-          index={viewerIndex}
-          onIndexChange={setViewerIndex}
-          onClose={() => setViewerIndex(null)}
-          onPick={pick}
-        />
-      )}
-    </div>
-  )
-}
-
 /** Alias — `MediaLibrary variant="page"`. Without `onSelect` the actions offer
- *  Copy URL only, which is the read-only page a brand book wants. */
-export function MediaBrowser({ client, accept = 'all', onSelect = null }) {
-  return <MediaLibrary variant="page" client={client} accept={accept} onSelect={onSelect} />
+ *  Copy URL + download only, which is the read-only page a brand book wants. */
+export function MediaBrowser({ client, accept = 'all', onSelect = null, ...rest }) {
+  return <MediaLibrary variant="page" client={client} accept={accept} onSelect={onSelect} {...rest} />
 }

package/src/organisms/SettingsPanel.jsx

@@ -0,0 +1,177 @@
+import Button from '../atoms/Button.jsx'
+import SegmentedToggle from '../atoms/SegmentedToggle.jsx'
+import ToggleSwitch from '../atoms/ToggleSwitch.jsx'
+import ShellDrawer from '../molecules/ShellDrawer.jsx'
+import FullscreenOverlay from '../utilities/FullscreenOverlay.jsx'
+
+/**
+ * SettingsPanel — a settings surface for the thing you are looking at: you
+ * change how a list looks WHILE looking at it, so it is a slide-over (or an
+ * overlay), never a route (SettingsPanel, kol-r2b2 2026-08-26 — the
+ * per-bucket display settings: kinds allow-list, structure, loading, layout).
+ *
+ * TWO PRESENTATIONS, ONE ANATOMY (the user's ask): `variant="drawer"` is a
+ * right-anchored sheet over a scrim, `variant="overlay"` the same panel
+ * centred. Only the shell differs; header · intro · sections · footer are the
+ * same nodes in both. Neither shell is built here — the drawer IS ShellDrawer
+ * (scrim, Escape, focus trap, scroll lock, focus return, the × control) and
+ * the overlay IS FullscreenOverlay (scrim, Escape, backdrop dismiss, scroll
+ * lock, the corner ×). The source had none of that: scrim click was the only
+ * exit, no Escape, no trap, no lock, and a hand-typed `rgba(0,0,0,0.6)` scrim
+ * where the DS already owned one.
+ *
+ * The CONTROLS are the DS controls, not the source's word-buttons: a switch
+ * row is `ToggleSwitch`, a choice row is `SegmentedToggle` — the source's
+ * segmented variant was flagged by the user as the thing to fix here, not to
+ * copy. Sections are the DS `Section` (pass `divided` on every one and the
+ * hairline lands between siblings on its own).
+ *
+ * Text casing is authored at the call site (no text-transform) — the source
+ * mixed `Show kinds` / `on` / `grid` in one panel; write them how they should read.
+ *
+ * @param {boolean}  open      mounted and shown (default true — the parent
+ *                             usually conditionally renders it)
+ * @param {'drawer'|'overlay'} variant  presentation
+ * @param {number|string} width  panel width (default 380)
+ * @param {string}   title     header line 1
+ * @param {string}   subtitle  header line 2 — the context, e.g. the bucket label
+ * @param {string}   intro     the one-line note under the header
+ * @param {Function} onClose   × · scrim · Escape
+ * @param {ReactNode} footer   the foot slot — `SettingsFooter` is the default shape
+ * @param {ReactNode} children the sections
+ */
+export default function SettingsPanel({
+  open = true,
+  variant = 'drawer',
+  width = 380,
+  title,
+  subtitle,
+  intro,
+  onClose,
+  footer,
+  children,
+  className = '',
+}) {
+  const header = (
+    <div className="flex min-w-0 flex-col">
+      {title && <span className="kol-mono-12 text-emphasis">{title}</span>}
+      {subtitle && <span className="kol-mono-10 text-meta">{subtitle}</span>}
+    </div>
+  )
+  const body = (
+    <>
+      {intro && <p className="kol-mono-10 text-meta">{intro}</p>}
+      <div className="flex flex-col gap-5">{children}</div>
+      {footer && <div className="mt-2">{footer}</div>}
+    </>
+  )
+
+  if (variant === 'overlay') {
+    if (!open) return null
+    return (
+      <FullscreenOverlay open onClose={onClose}>
+        {/* the corner × rides the sheet at --kol-spacing-3; the panel reserves
+          * that lane on top (the .kol-media-picker precedent) instead of the
+          * control moving */}
+        <div
+          className={`kol-overlay-panel flex flex-col gap-4 p-6 pt-12 ${className}`}
+          style={{ width: typeof width === 'number' ? `${width}px` : width, maxWidth: '100%', maxHeight: '85vh', overflowY: 'auto' }}
+        >
+          {header}
+          {body}
+        </div>
+      </FullscreenOverlay>
+    )
+  }
+
+  return (
+    <ShellDrawer open={open} onClose={onClose} side="right" width={width} header={header} className={className}>
+      <div className="flex flex-col gap-4">{body}</div>
+    </ShellDrawer>
+  )
+}
+
+/**
+ * SettingsRow — label + hint on the left, the control on the right. A GRID,
+ * not a flex pair: the source's `justify-between` let a long hint wrap UNDER
+ * the control and parked the control at the top of a two-line hint. Here the
+ * text column is `minmax(0, 1fr)` so it wraps inside itself, and the control
+ * centres on the row.
+ */
+export function SettingsRow({ label, hint, children }) {
+  return (
+    <div className="grid grid-cols-[minmax(0,1fr)_auto] items-center gap-x-6 py-1">
+      <div className="flex min-w-0 flex-col">
+        <span className="kol-mono-12 text-body">{label}</span>
+        {hint && <span className="kol-mono-10 text-meta">{hint}</span>}
+      </div>
+      <div className="shrink-0">{children}</div>
+    </div>
+  )
+}
+
+/** SettingsSwitch — the row's on/off control: the DS ToggleSwitch, bare, sm.
+ *  `disabledHint` rides `title` so a switch that cannot act says why. */
+export function SettingsSwitch({ on = false, onChange, disabled = false, disabledHint, label }) {
+  return (
+    <ToggleSwitch
+      size="sm"
+      checked={on}
+      onChange={onChange}
+      disabled={disabled}
+      title={disabled ? disabledHint : undefined}
+      aria-label={label}
+    />
+  )
+}
+
+/** SettingsChoice — the row's one-of-N control: the DS SegmentedToggle, sm.
+ *  Options are values or `{ value, label }`. */
+export function SettingsChoice({ options = [], value, onChange, ariaLabel }) {
+  const opts = options.map((o) => (o != null && typeof o === 'object' ? o : { value: o, label: String(o) }))
+  return <SegmentedToggle size="sm" value={value} onChange={onChange} options={opts} ariaLabel={ariaLabel} />
+}
+
+/* The toggle-chip pattern — `.kol-control` sm, filled when on, meta ink when
+ * off (ViewToggle's text variant wears the same string; MediaLibrary's kind
+ * chips too). ponytail: a `ControlChip` atom is the upgrade if a third
+ * consumer types this. */
+export const CHIP_CLS = 'kol-control kol-control-sm kol-mono-12'
+export const chipCls = (on) => `${CHIP_CLS} ${on ? 'kol-control--filled' : 'text-meta hover:text-emphasis'}`
+
+/**
+ * SettingsChipRow — a wrap of toggle chips with optional counts (an
+ * allow-list: every chip sets a default, never a gate).
+ * @param {Array}  options   [{ value, label, count? }]
+ * @param {Array|Set} selected  the values that are on
+ * @param {Function} onToggle  (value) => void
+ */
+export function SettingsChipRow({ options = [], selected = [], onToggle }) {
+  const on = selected instanceof Set ? selected : new Set(selected)
+  return (
+    <div className="flex flex-wrap gap-1">
+      {options.map((o) => (
+        <button
+          key={String(o.value)}
+          type="button"
+          aria-pressed={on.has(o.value)}
+          onClick={() => onToggle?.(o.value)}
+          className={chipCls(on.has(o.value))}
+        >
+          {o.label ?? String(o.value)}
+          {o.count > 0 && <span className="text-meta"> {o.count}</span>}
+        </button>
+      ))}
+    </div>
+  )
+}
+
+/** SettingsFooter — the state word and the reset action. */
+export function SettingsFooter({ customised = false, onReset, resetLabel = 'Reset to defaults' }) {
+  return (
+    <div className="flex items-center justify-between">
+      <span className="kol-mono-10 text-meta">{customised ? 'customised' : 'defaults'}</span>
+      {onReset && <Button variant="ghost" size="sm" onClick={onReset}>{resetLabel}</Button>}
+    </div>
+  )
+}

package/src/utilities/FullscreenOverlay.jsx

@@ -12,18 +12,41 @@ import Button from '../atoms/Button.jsx'
  * typographic multiplication sign standing in for a glyph the icon set has
  * always shipped.
  */
+const FOCUSABLE =
+  'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])'
+
 export default function FullscreenOverlay({ open, onClose, closeButton = true, children }) {
   const sheetRef = useRef(null)
 
+  /* Escape closes; Tab is TRAPPED in the sheet (SettingsPanel, 2026-08-26 —
+   * the same trap ShellDrawer carries; before this a Tab from the overlay
+   * walked into the page underneath). Focus moves into the sheet on open and
+   * back to the opener on close. */
   useEffect(() => {
     if (!open) return
-    const onKey = (e) => { if (e.key === 'Escape') onClose?.() }
+    const onKey = (e) => {
+      if (e.key === 'Escape') { onClose?.(); return }
+      if (e.key !== 'Tab') return
+      const sheet = sheetRef.current
+      if (!sheet) return
+      const nodes = sheet.querySelectorAll(FOCUSABLE)
+      if (!nodes.length) { e.preventDefault(); sheet.focus(); return }
+      const first = nodes[0]
+      const last = nodes[nodes.length - 1]
+      const active = document.activeElement
+      if (!sheet.contains(active)) { e.preventDefault(); first.focus() }
+      else if (e.shiftKey && (active === first || active === sheet)) { e.preventDefault(); last.focus() }
+      else if (!e.shiftKey && active === last) { e.preventDefault(); first.focus() }
+    }
     document.addEventListener('keydown', onKey)
     const prev = document.body.style.overflow
     document.body.style.overflow = 'hidden'
+    const prevFocus = document.activeElement
+    sheetRef.current?.focus()
     return () => {
       document.removeEventListener('keydown', onKey)
       document.body.style.overflow = prev
+      if (prevFocus instanceof HTMLElement) prevFocus.focus()
     }
   }, [open, onClose])
 
@@ -40,7 +63,7 @@ export default function FullscreenOverlay({ open, onClose, closeButton = true, c
 
   return (
     <div className="kol-overlay" role="dialog" aria-modal="true" onMouseDown={onBackdropClick}>
-      <div ref={sheetRef} className="kol-overlay-sheet">
+      <div ref={sheetRef} tabIndex={-1} className="kol-overlay-sheet outline-none">
         {closeButton && (
           <Button
             variant="outline"