@kolkrabbi/kol-component 0.230.0 → 0.232.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.230.0",
+  "version": "0.232.0",
   "description": "KOL design-system components — atoms through organisms, emitting canonical kol-* classes. Pairs with @kolkrabbi/kol-theme for styling.",
   "license": "MIT",
   "type": "module",
@@ -37,7 +37,7 @@
     "react-dom": "^18.3.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-icons": "^0.29.1"
+    "@kolkrabbi/kol-icons": "^0.31.0"
   },
   "files": [
     "src",

package/src/atoms/Kbd.jsx

@@ -0,0 +1,33 @@
+/**
+ * Kbd — a key cap: one key or chord (↵, ⌘K, Esc) shown as an affordance.
+ * Replaces the two hand-rolled <kbd> chips (SearchInput's shortcut hint and
+ * the palette footer) that had drifted apart (2026-09-30). A plate, so it
+ * takes oq — never fg (icons-use-oq law).
+ *
+ * aria-hidden by default: a cap is a hint beside a label, not the label.
+ *
+ * @param {'sm'|'md'} size  sm = inside a control (16px, helper-10) ·
+ *                          md = beside helper-12 text (20px)
+ * @param {string}    icon  kol-icons name drawn before the children — a key
+ *                          with a symbol (↵ `corner-down-left`, ⌘ `command`)
+ *                          is a GLYPH, never a typed character in the mono face
+ */
+import { Icon } from '@kolkrabbi/kol-icons'
+
+const SIZE = {
+  sm: 'h-4 min-w-4 px-1 kol-helper-10',
+  md: 'h-5 min-w-5 px-1.5 kol-helper-12',
+}
+
+export default function Kbd({ size = 'md', icon, className = '', children, ...rest }) {
+  return (
+    <kbd
+      aria-hidden="true"
+      className={`inline-flex items-center justify-center gap-0.5 shrink-0 rounded-[var(--kol-radius-xs)] bg-oq-08 text-oq-64 ${SIZE[size] ?? SIZE.md} ${className}`.trim()}
+      {...rest}
+    >
+      {icon && <Icon name={icon} size={12} />}
+      {children}
+    </kbd>
+  )
+}

package/src/index.js

@@ -59,6 +59,8 @@ export { default as SectionText } from './molecules/SectionText.jsx'
 export { default as SectionLabel } from './atoms/SectionLabel.jsx'
 export { default as SegmentedToggle } from './atoms/SegmentedToggle.jsx'
 export { default as Stepper } from './molecules/Stepper.jsx'
+export { default as Kbd } from './atoms/Kbd.jsx'
+export { default as OptionRow } from './molecules/OptionRow.jsx'
 export { default as Tag } from './atoms/Tag.jsx'
 export { default as Textarea } from './atoms/Textarea.jsx'
 export { default as ToggleBracket } from './atoms/ToggleBracket.jsx'

package/src/molecules/FieldRow.jsx

@@ -3,6 +3,7 @@ import { Icon } from '@kolkrabbi/kol-icons'
 import Input from '../atoms/Input'
 import { usePopover, PopoverPanel } from '../utilities/Popover'
 import Dropdown from './Dropdown'
+import OptionRow from './OptionRow.jsx'
 
 /**
  * FieldRow — one labeled field row in a record surface (lobby: RecordManager).
@@ -93,23 +94,23 @@ export function StatusChip({ value, options = [], onChange, variant = 'neutral',
           {norm.map(({ value: val, label }) => {
             return (
               <li key={val}>
-                <button
+                <OptionRow
+                  as="button"
                   type="button"
                   role="option"
                   aria-selected={val === value}
-                  className={`kol-helper-12 w-full text-left pr-3 py-2 bg-transparent border-0 cursor-pointer rounded-sm hover:bg-fg-08 inline-flex items-center ${val === value ? 'text-emphasis' : 'text-body'}`}
+                  size="sm"
+                  selected={val === value}
+                  className="w-full"
                   onClick={() => {
                     onChange?.(val)
                     setOpen(false)
                   }}
-                >
-                  {/* check column always reserved — labels align whether or
-                    * not a row carries the mark (reference grammar) */}
-                  <span className="inline-flex w-7 shrink-0 justify-center" aria-hidden="true">
-                    {val === value && <Icon name="check" size={12} />}
-                  </span>
-                  {label}
-                </button>
+                  /* check column always reserved — labels align whether or
+                   * not a row carries the mark (reference grammar) */
+                  leading={<span className="inline-flex w-4 justify-center">{val === value && <Icon name="check" size={12} />}</span>}
+                  label={label}
+                />
               </li>
             )
           })}

package/src/molecules/OptionRow.jsx

@@ -0,0 +1,82 @@
+/**
+ * OptionRow — one row in a list you move through: the palette's results, a browser's rows, a
+ * dropdown's options. Lifted out of ShellSearchOverlay (2026-09-30), where it was hand-rolled next to
+ * DropdownTagFilter's, FieldRow's and ColumnBrowser's own — four rows for one job.
+ *
+ * The box is the control's: `min-h` on the --kol-ctl-* ramp (22 · 26 · 32 · 40) with a 1px
+ * transparent ring, so a row lines up with the field or button beside it at the same size.
+ *
+ * States, strongest first:
+ *   active   — the keyboard cursor / hover: the tone fill, full ink
+ *   selected — the picked item: oq-08
+ *   trail    — on the path to the picked item (a browser's parent folders): oq-04
+ *
+ * Renders no role — the caller owns the list semantics (`role="option"`, `aria-selected`, ids)
+ * and passes them through `...rest`.
+ *
+ * @param {'xs'|'sm'|'md'|'lg'} size   the control ramp step
+ * @param {string}    icon     kol-icons name, drawn in oq (icons-use-oq law)
+ * @param {ReactNode} leading  anything else in the icon column (a check, a thumb) — wins over icon
+ * @param {ReactNode} label
+ * @param {ReactNode} hint     a second line under the label
+ * @param {ReactNode} trailing right-aligned (a shortcut, a count, a menu button)
+ * @param {string}    as       element to render (`div` · `button` · `li`)
+ * @param {boolean}   fill     false = the caller paints the state fills (ColumnBrowser's trail vs
+ *                             deepest-selection is decided in CSS by column); the ink still follows
+ * @param {boolean}   muted    a row that is there but not the point (fg-48)
+ *
+ * `ROW_HEIGHT` / `ROW_TYPE` are exported for a row that cannot take this anatomy (the media rows
+ * view's table row: twisty, drag hit, columns) — it still sits on the same ramp.
+ */
+import { Icon } from '@kolkrabbi/kol-icons'
+import { glyphSize } from '../hooks/glyphLadders.js'
+
+/* the box: min-height on the ramp, and a pad that lands one line of the step's type exactly on it —
+ * xs 2+1+16+1+2 = 22 · sm 4+1+16+1+4 = 26 · md 6+1+18+1+6 = 32 · lg 10+1+18+1+10 = 40 */
+export const ROW_HEIGHT = {
+  xs: 'min-h-[var(--kol-ctl-xs)] py-0.5',
+  sm: 'min-h-[var(--kol-ctl-sm)] py-1',
+  md: 'min-h-[var(--kol-ctl-md)] py-1.5',
+  lg: 'min-h-[var(--kol-ctl-lg)] py-2.5',
+}
+export const ROW_TYPE = { xs: 'kol-mono-12', sm: 'kol-mono-12', md: 'kol-mono-14', lg: 'kol-mono-14' }
+
+export default function OptionRow({
+  as: Tag = 'div',
+  size = 'md',
+  active = false,
+  selected = false,
+  trail = false,
+  fill: paints = true,
+  muted = false,
+  icon,
+  leading,
+  label,
+  hint,
+  trailing,
+  className = '',
+  children,
+  ...rest
+}) {
+  const lit = active || selected || trail
+  /* hover takes the active fill — the palette already moves `active` on hover; a list without a
+   * keyboard cursor gets the same look for free. `fill={false}` rows paint nothing (the columns) */
+  const bg = !paints ? '' : active
+    ? 'bg-[var(--kol-tone-bg,var(--kol-surface-secondary))]'
+    : `${selected ? 'bg-oq-08' : trail ? 'bg-oq-04' : ''} hover:bg-[var(--kol-tone-bg,var(--kol-surface-secondary))]`
+  const fill = `${bg} ${lit ? 'text-fg' : muted ? 'text-fg-48' : 'text-fg-80'}`
+  const lead = leading ?? (icon && <Icon name={icon} size={glyphSize(size)} />)
+  return (
+    <Tag
+      className={`flex items-center gap-2 px-4 border border-transparent ${ROW_HEIGHT[size] ?? ROW_HEIGHT.md} rounded-[var(--kol-radius-sm)] cursor-pointer text-left ${ROW_TYPE[size] ?? ROW_TYPE.md} transition-colors ${fill} ${className}`.trim()}
+      {...rest}
+    >
+      {lead && <span aria-hidden="true" className="flex shrink-0 text-oq-48">{lead}</span>}
+      <span className="flex flex-1 flex-col min-w-0">
+        <span className="truncate">{label ?? children}</span>
+        {hint && <span className="kol-mono-12 text-fg-48 truncate">{hint}</span>}
+      </span>
+      {trailing && <span className="flex shrink-0 items-center">{trailing}</span>}
+    </Tag>
+  )
+}

package/src/molecules/SearchInput.jsx

@@ -2,6 +2,7 @@ import { useEffect, useRef, useState } from 'react'
 import { toneClass } from '../utilities/tone.js'
 import { Icon } from '@kolkrabbi/kol-icons'
 import { glyphSize } from '../hooks/glyphLadders.js'
+import Kbd from '../atoms/Kbd.jsx'
 
 /**
  * SearchInput — controlled search field on the .kol-control shell. The
@@ -200,8 +201,10 @@ export default function SearchInput({
   const shellCls = [
     bare
       /* kol-control--bare: zero-chrome marker so the theme's coarse-pointer
-       * 16px floor covers this body plan too (OverlaySearchFieldZoomsIOS) */
-      ? 'kol-control--bare flex w-full gap-2.5 px-4 py-3'
+       * 16px floor covers this body plan too (OverlaySearchFieldZoomsIOS).
+       * Chrome off, geometry on: the size's padding + a transparent 1px ring
+       * land it on the 22 · 26 · 32 · 40 ladder like the shell (09-sizes) */
+      ? `kol-control--bare kol-control-${size} flex w-full border border-transparent gap-2`
       : `kol-control${variant ? ` kol-control--${variant}` : ''} kol-control-${size} gap-2${toneClass(tone) ? ` ${toneClass(tone)}` : ''}`,
     'items-center cursor-text',
     SIZE_TYPE[size],
@@ -225,7 +228,7 @@ export default function SearchInput({
     <label className={shellCls}>
       <span
         aria-hidden="true"
-        className={`flex items-center shrink-0 ${bare ? 'text-fg-48' : 'text-auto opacity-50'}`}
+        className={`flex items-center shrink-0 ${bare ? 'text-oq-48' : 'text-auto opacity-50'}`}
       >
         {/* ADJACENT — this glyph sits in the field's line box beside the query */}
         <Icon name="search" size={iconSize ?? glyphSize(size)} />
@@ -254,12 +257,10 @@ export default function SearchInput({
         </button>
       ) : shortcutHint ? (
         /* aria-hidden — affordance, not a label (same stance as Input's prefix/suffix) */
-        <kbd
-          aria-hidden="true"
-          className="inline-flex items-center justify-center shrink-0 h-4 min-w-4 px-1 rounded-[var(--kol-radius-xs)] bg-fg-08 kol-helper-10 text-fg-48"
-        >
-          {shortcutHint}
-        </kbd>
+        /* ⌘ is drawn, not typed — the mono face's ⌘ is the "drawn by a child" cap */
+        shortcutHint.startsWith('⌘')
+          ? <Kbd size="sm" icon="command">{shortcutHint.slice(1)}</Kbd>
+          : <Kbd size="sm">{shortcutHint}</Kbd>
       ) : null}
     </label>
   )

package/src/organisms/ColumnBrowser.jsx

@@ -3,6 +3,7 @@ import { Icon } from '@kolkrabbi/kol-icons'
 import KindPreview, { KIND_GLYPH } from '../molecules/KindPreview.jsx'
 import FileIcon from '../atoms/FileIcon.jsx'
 import RowMenuButton from '../molecules/RowMenuButton.jsx'
+import OptionRow from '../molecules/OptionRow.jsx'
 import { formatLength } from '../molecules/AudioPreview.jsx'
 import { kindOf as dsKindOf, KIND_LABEL as DS_KIND_LABEL } from '../utilities/mediaKinds.js'
 import useGrabEdge from '../hooks/useGrabEdge.js'
@@ -248,7 +249,7 @@ const ZONE_BOX = 44
  * without the stack: the columns pass none, so a desktop row is byte-identical
  * to what it was. */
 function Row({
-  icon, label, active, cursor = false, trailing, onClick, muted = false,
+  icon, label, active, cursor = false, trailing, onClick, muted = false, size = 'md',
   indent = 0, meta, zones = false, thumb, onDisclose, disclosed, onContextMenu, drop, dropFiles, markKey,
 }) {
   const [over, setOver] = useState(false)
@@ -273,6 +274,30 @@ function Row({
       drop.onDrop(drop.path)
     },
   } : {}
+  /* THE DESKTOP ROW IS AN OptionRow (2026-09-30) — the palette's row, on the control ramp, so a size
+   * setting scales height, glyph and type together. The fills stay this file's CSS (trail vs the
+   * deepest column's selection is decided by column there, and hover/cursor paint nothing — the
+   * 2026-09-02 ruling), so `fill={false}`. The `zones` row below is the phone's and keeps its own. */
+  if (!zones) return (
+    <OptionRow
+      as="li"
+      size={size}
+      fill={false}
+      selected={active}
+      muted={muted && !cursor}
+      icon={icon}
+      label={label}
+      hint={meta}
+      trailing={<>{trailing}<RowMenuButton onOpen={onContextMenu} className="-my-2 -mr-2" /></>}
+      onContextMenu={onContextMenu}
+      {...dropProps}
+      data-marquee-key={markKey}
+      data-drop-over={over || undefined}
+      className={`kol-column-browser-row${active ? ' is-selected' : ''}${cursor ? ' is-cursor' : ''}`}
+      onClick={onClick}
+      style={indent ? { paddingLeft: `calc(var(--kol-spacing-4) + ${indent} * var(--kol-spacing-5))` } : undefined}
+    />
+  )
   return (
     <li
       onContextMenu={onContextMenu}
@@ -521,6 +546,9 @@ export default function ColumnBrowser({
   /* `folderIcon(path)` — the glyph a folder row wears (default `folder`). The media pages mark a
    * bucket — a SOURCE, not a prefix — with `database` (user 2026-09-23). */
   folderIcon,
+  /* `rowSize` — the desktop rows' step on the control ramp (xs · sm · md · lg = 22 · 26 · 32 · 40),
+   * height, glyph and type together (user 2026-09-30). md matches the search field. */
+  rowSize = 'md',
   /* THE TWO SEAMS THE MOBILE TICKET'S RULINGS POINT AT (ColumnBrowserMobileViews,
    * kol-r2b2 2026-09-03). Both are questions the DS must not answer for a
    * consumer, so neither is computed here:
@@ -1006,6 +1034,7 @@ export default function ColumnBrowser({
             {folders.map((f, i) => (
               <Row
                 key={f}
+                size={rowSize}
                 icon={folderIcon?.(level + f) ?? 'folder'}
                 label={f.replace(/\/$/, '')}
                 markKey={level + f}
@@ -1021,6 +1050,7 @@ export default function ColumnBrowser({
             {files.map((o, i) => (
               <Row
                 key={o.key}
+                size={rowSize}
                 icon={COL_ICON[kindOf(o)] || 'file'}
                 label={o.displayKey ?? o.key}
                 markKey={o.key}

package/src/organisms/ContentFilters.jsx

@@ -1,4 +1,4 @@
-import { useState, useMemo } from 'react'
+import { useEffect, useState, useMemo } from 'react'
 import Tag from '../atoms/Tag.jsx'
 import Divider from '../atoms/Divider.jsx'
 import Button from '../atoms/Button.jsx'
@@ -115,6 +115,11 @@ const ContentFilters = ({
   mutuallyExclusiveFilters = [],
   customFilterKeys = [],
   searchKeys = ['label', 'name', 'title', 'type'],
+  /* CONTROLLED SEARCH (2026-09-30) — same seam as `filtersOpen`: a consumer that must know the
+   * query (media swaps the tree for a flat list while one is typed) or hand one in (⌘Enter from its
+   * palette) owns it. Absent, the text stays private, exactly as before. */
+  searchValue,
+  onSearchChange,
   headerActions,
   trailingActions,
   trailingPlacement = 'auto',
@@ -182,8 +187,15 @@ const ContentFilters = ({
     setInternalLayout(next)
     onLayoutChange?.(next)
   }
-  const [searchOpen, setSearchOpen] = useState(false)
-  const [searchText, setSearchText] = useState('')
+  const [searchOpen, setSearchOpen] = useState(!!searchValue)
+  const [internalSearch, setInternalSearch] = useState('')
+  const searchText = searchValue !== undefined ? searchValue : internalSearch
+  const setSearchText = (next) => {
+    setInternalSearch(next)
+    onSearchChange?.(next)
+  }
+  /* a query handed in from outside opens the field it lives in */
+  useEffect(() => { if (searchValue) setSearchOpen(true) }, [searchValue])
 
 
   const toggleFilter = (filterType, value) => {

package/src/organisms/MediaLibraryPages.jsx

@@ -1,5 +1,7 @@
-import { Fragment, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react'
+import { Fragment, createContext, useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react'
 import formatSize from '../utilities/formatSize.js'
+import { ROW_HEIGHT, ROW_TYPE } from '../molecules/OptionRow.jsx'
+import { glyphSize } from '../hooks/glyphLadders.js'
 import { Icon } from '@kolkrabbi/kol-icons'
 import Button from '../atoms/Button.jsx'
 import Divider from '../atoms/Divider.jsx'
@@ -299,11 +301,17 @@ function TagEditor({ tags = [], onChange, suggestions = [] }) {
   )
 }
 
+/* THE ROWS VIEW'S STEP ON THE CONTROL RAMP (user 2026-09-30) — the same `rowSize` the columns take,
+ * handed down by context rather than threaded through every subtree level. These rows keep their
+ * own anatomy (twisty, drag hit, table columns) and take only the ramp: box, type, glyph. */
+const RowSize = createContext('md')
+
 /* `depth` indents a row under the folder it was expanded from; `expanded`/`onToggle` draw the
  * disclosure twisty. A folder row without `onToggle` keeps the old behaviour exactly — one chevron
  * that navigates — so nothing that already renders these moves. */
 function FolderRow({ name, icon = 'folder', onClick, onDoubleClick, depth = 0, expanded, onToggle, meta, cols, onContextMenu, drag, dropFiles, selected, current, markKey }) {
   const [over, setOver] = useState(false)
+  const size = useContext(RowSize)
   /* A FOLDER IS A DROP TARGET. `drag` carries the page's move verb and the path this row is; the
    * row highlights only while something is actually over it, so an accidental hover reads as
    * nothing. Without `drag` every handler below is undefined and the row is exactly what it was. */
@@ -333,7 +341,7 @@ function FolderRow({ name, icon = 'folder', onClick, onDoubleClick, depth = 0, e
   return (
     /* THE COLUMN BROWSER'S ROW (user 2026-09-22): `kol-column-browser-row` carries the 4px pill
      * inset, the selected fill and the drop fill; no divider, as the columns have none. */
-    <li onContextMenu={onContextMenu} {...dropProps} data-marquee-key={markKey} data-hit-zone data-drop-over={over || undefined} className={`kol-column-browser-row flex items-center gap-3 py-2 px-3 transition-colors${selected ? ' is-selected' : ''}${current ? ' is-current' : ''}`} style={{ paddingLeft: depth * 20 + 12 }} onClick={onClick} onDoubleClick={onDoubleClick}>
+    <li onContextMenu={onContextMenu} {...dropProps} data-marquee-key={markKey} data-hit-zone data-drop-over={over || undefined} className={`kol-column-browser-row flex items-center gap-3 border border-transparent px-3 ${ROW_HEIGHT[size]} transition-colors${selected ? ' is-selected' : ''}${current ? ' is-current' : ''}`} style={{ paddingLeft: depth * 20 + 12 }} onClick={onClick} onDoubleClick={onDoubleClick}>
       {onToggle ? (
         <button type="button" aria-label={expanded ? `Collapse ${name}` : `Expand ${name}`} aria-expanded={!!expanded}
           onClick={(e) => { e.stopPropagation(); onToggle() }}
@@ -345,11 +353,11 @@ function FolderRow({ name, icon = 'folder', onClick, onDoubleClick, depth = 0, e
       {/* THE FOLDER GLYPH IS THE ONE ICON LEFT, so it fills its box (user 2026-09-23: *"only folder
           should use icon, and it should be bigger"*). Every other kind now renders its own bytes. */}
       <span data-hit {...hitDrag} className="kol-row-hit flex items-center gap-3 min-w-0">
-        <span className="w-8 h-8 shrink-0 flex items-center justify-center text-oq-48"><Icon name={icon} size={26} /></span>
+        <span className="shrink-0 flex items-center justify-center text-oq-48"><Icon name={icon} size={glyphSize(size)} /></span>
         {/* NO TRAILING SLASH (user 2026-09-22). `partition` hands folders back as `audio/` because a
             slash is what marks one in a flat key space; that is storage's spelling, not a label, and
             `ColumnBrowser` has always stripped it. The glyph says "folder". */}
-        <span className="kol-mono-12 min-w-0 truncate text-fg-default">{name.replace(/\/$/, '')}</span>
+        <span className={`${ROW_TYPE[size]} min-w-0 truncate text-fg-default`}>{name.replace(/\/$/, '')}</span>
       </span>
       <span className="flex-1" />
       {/* THE FOLDER'S COUNT SITS IN THE DATE COLUMN and the size column takes a dash — the columns
@@ -419,17 +427,18 @@ function RowSubtree({ level, depth, rowLevel, expanded, onToggle, onOpenFolder,
  * `#img/` drew two rows where the column browser drew four — the two folders, the empty folder the
  * columns knew about, and a file. A list view that cannot show a file is not a list view. */
 function FileRow({ o, onClick, onDoubleClick, depth = 0, formatDate, thumb, cols, onContextMenu, drag, selected, markKey }) {
+  const size = useContext(RowSize)
   const dragProps = drag ? { draggable: true, onDragStart: (e) => { e.stopPropagation(); drag.onDragStart(e, o.key) } } : {}
   return (
-    <li onContextMenu={onContextMenu} data-marquee-key={markKey ?? o.key} data-hit-zone className={`kol-column-browser-row flex items-center gap-3 py-2 px-3 transition-colors${selected ? ' is-selected' : ''}`} style={{ paddingLeft: depth * 20 + 12 }} onClick={onClick} onDoubleClick={onDoubleClick}>
+    <li onContextMenu={onContextMenu} data-marquee-key={markKey ?? o.key} data-hit-zone className={`kol-column-browser-row flex items-center gap-3 border border-transparent px-3 ${ROW_HEIGHT[size]} transition-colors${selected ? ' is-selected' : ''}`} style={{ paddingLeft: depth * 20 + 12 }} onClick={onClick} onDoubleClick={onDoubleClick}>
       <span className="w-4 shrink-0" />
       {/* the hit — icon and name, as in the folder row above */}
       <span data-hit {...dragProps} className="kol-row-hit flex items-center gap-3 min-w-0">
-        <span className="w-8 h-8 shrink-0 flex items-center justify-center text-oq-48 overflow-hidden rounded">
+        <span className="shrink-0 flex items-center justify-center text-oq-48 overflow-hidden rounded" style={{ width: glyphSize(size), height: glyphSize(size) }}>
           {/* a file with no thumbnail draws its glyph at the FOLDER's size — one icon column (user 2026-09-25) */}
-          {thumb ?? <Icon name={kindOf(o) === 'image' ? 'image' : 'file'} size={26} />}
+          {thumb ?? <Icon name={kindOf(o) === 'image' ? 'image' : 'file'} size={glyphSize(size)} />}
         </span>
-        <span className="kol-mono-12 min-w-0 truncate text-fg-default">{o.displayKey ?? o.key.split('/').pop()}</span>
+        <span className={`${ROW_TYPE[size]} min-w-0 truncate text-fg-default`}>{o.displayKey ?? o.key.split('/').pop()}</span>
       </span>
       <span className="flex-1" />
       {cols && <>
@@ -1058,6 +1067,11 @@ export function MediaLibraryBrowse({
    * 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,
+  /* `searchSuggestions` — what the palette lists before you type. Absent: favourites, smart
+   * folders, then the bucket's top-level folders. An array replaces them; a function receives them
+   * and returns the list. Rows are the palette's shape; a row with `run` calls it instead of
+   * jumping to `id` as a file key. */
+  searchSuggestions,
   /* `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,
@@ -1593,6 +1607,9 @@ export function MediaLibraryBrowse({
    * you, which is what the filter bar is for. */
   const [searchOpen, setSearchOpen] = useState(false)
   const [searchQuery, setSearchQuery] = useState('')
+  /* the filter bar's own query — lifted so a typed one swaps the tree for a flat list, and so the
+   * palette's ⌘Enter can hand its query over */
+  const [barQuery, setBarQuery] = useState('')
   /* THE ARROWS IN THE GRID AND THE ROWS (user 2026-09-23: *"arrow navigation doesnt work in grid
    * mode? nor in row mode"*). The columns have always had theirs (`ColumnBrowser`); these are the
    * same keys for the other two views, and every one is listed in the shortcuts sheet.
@@ -1929,8 +1946,12 @@ export function MediaLibraryBrowse({
     .map((o) => ({ ...o, kind: kindOf(o), poster: posterFor(o.key, keySet) }))
   const filtersOn = !!settings.filters
   /* the bar filters FILES, and a tree is drawn from the files under it — so one filtered list
-   * serves both: the wall renders it, the tree is scoped to the keys in it */
-  const filterItems = isWall ? wallFiles : scoped.filter((o) => !isSystemFile(o.key)).map((o) => ({ ...o, kind: kindOf(o), displayKey: prefix ? o.key.slice(prefix.length) : o.key }))
+   * serves both: the wall renders it, the tree is scoped to the keys in it.
+   * THE TREE'S LIST IS THE WHOLE BUCKET, not the folder you stand in (user 2026-09-30: open the
+   * bar at `brand/og/` and `logos`, `original`, `projects` vanished with no filter set). The
+   * columns draw every level up to the root, so a list scoped to `prefix` cut every sibling path
+   * the moment the bar mounted. */
+  const filterItems = isWall ? wallFiles : sortedObjects.filter((o) => !isSystemFile(o.key)).map((o) => ({ ...o, kind: kindOf(o), poster: posterFor(o.key, keySet), displayKey: o.key }))
   const filterKinds = [...new Set(filterItems.map((o) => o.kind))].sort()
   const filterTags = [...new Set(filterItems.flatMap((o) => o.tags ?? []))].sort()
   /* favourites as a one-chip group: ContentFilters matches a value, so a starred file carries one */
@@ -1980,6 +2001,7 @@ export function MediaLibraryBrowse({
                 className={atTitleRoot ? 'is-root' : ''}
                 height={colH}
                 onHeightChange={onColH}
+                rowSize={rowSize}
                 columnWidths={settings.columnWidths}
                 onColumnResize={(i, px) => setSettings({ ...settings, columnWidths: { ...(settings.columnWidths ?? {}), [i]: px } })}
                 objects={treeObjects.filter((o) => !isSystemFile(o.key)).map((o) => ({ ...o, key: `${VROOT}${o.key}` }))}
@@ -2166,13 +2188,23 @@ export function MediaLibraryBrowse({
    * inside it, the same preview pane beside them, the same count line under it — with the size
    * slider at its right end, Finder's. */
   const tileSize = settings.tileSize ?? 180
+  const rowSize = settings.rowSize ?? 'md'
   /* the tile size is the GRID's, not a level's (user 2026-09-24: the slider vanished at the root
    * levels) — one control, drawn wherever the grid is */
+  /* THE TREE VIEWS SCALE TOO (user 2026-09-30: *"we might want to scale everything on slider like we
+   * do in grid view"*) — in steps of the control ramp, not pixels, so a row is always a control height */
+  const RAMP = ['xs', 'sm', 'md', 'lg']
+  const rowSlider = (
+    <input type="range" className="slider-black w-32 cursor-pointer" min={0} max={RAMP.length - 1} step={1} value={Math.max(0, RAMP.indexOf(rowSize))}
+      onChange={(e) => setSettings({ ...settings, rowSize: RAMP[Number(e.target.value)] })} aria-label="Row size" />
+  )
   const sizeSlider = (
     <input type="range" className="slider-black w-32 cursor-pointer" min={100} max={360} step={20} value={tileSize}
       onChange={(e) => setSettings({ ...settings, tileSize: Number(e.target.value) })} aria-label="Tile size" />
   )
-  const wallPane = (files) => (
+  /* `hits` = a query's results: no folders, no root level, each file named by its whole path —
+   * in the tree views as a list, the rows' shape; the wall keeps its tiles */
+  const wallPane = (files, hits = false) => (
     <div ref={viewRef} className="flex flex-col gap-2" style={{ height: colH }}>
     <div className="relative border rounded flex overflow-hidden flex-1 min-h-0" style={{ borderColor: 'var(--kol-oq-08)' }}>
     {/* THE MARQUEE IS THE PANE'S, not the tile grid's (user 2026-09-23: a drag only started where
@@ -2185,7 +2217,7 @@ export function MediaLibraryBrowse({
       onContextMenu={titleLevel ? undefined : (e) => menu.openAt(e, { type: 'level', path: prefix })}
       onClick={(e) => { if (!e.target.closest('[data-marquee-key]')) { setRowSelection(new Set()); setPickedFile(null); setPickedFolder(null); setPickedBucket(null) } }}>
     {gridMarquee.rect && <div className="kol-marquee" style={gridMarquee.rect} />}
-    {titleLevel ? (
+    {titleLevel && !hits ? (
       <div className="grid gap-x-3 gap-y-5" style={{ gridTemplateColumns: `repeat(auto-fill, minmax(${tileSize}px, 1fr))` }}>
         {rootItems.map((it) => (
           <MediaTile key={it.key} preview={<Icon name={it.icon} size="100%" className="text-oq-48" />} name={it.name}
@@ -2193,11 +2225,12 @@ export function MediaLibraryBrowse({
             onClick={(e) => { e.stopPropagation(); setPickedBucket(it.key) }} onDoubleClick={it.open} />
         ))}
       </div>
-    ) : <WallBody files={files} layout="grid" tiles="media" cardMin={tileSize} onSorted={(list) => { gridOrderRef.current = list }}
+    ) : <WallBody files={files} layout={hits && !isWall ? 'list' : 'grid'} tiles="media" cardMin={tileSize} onSorted={(list) => { gridOrderRef.current = list }}
       /* THE GRID DRAWS THE LEVEL'S SUBFOLDERS, ahead of the files (same source: kol-client-olina
        * 2026-09-23 — `projects/` read `0 files` over a blank pane). `flat` is the subtree's files
        * and no folders, as it was. */
-      folders={settings.flat || smartMatches ? [] : folders.map((f) => prefix + f)}
+      folders={settings.flat || smartMatches || hits ? [] : folders.map((f) => prefix + f)}
+      {...(hits && { renderName: (o) => o.key })}
       onOpenFolder={goFolder}
       onPickFolder={(path, e) => { if (selectRow(path, e, [...folders.map((f) => prefix + f), ...files.map((f) => f.key)])) return; rowPickFolder(path) }}
       onFolderContextMenu={(e, path) => menu.openAt(e, { type: 'folder', path, targets: targetsFor(path) })}
@@ -2230,6 +2263,20 @@ export function MediaLibraryBrowse({
     hint: o.key.slice(0, o.key.lastIndexOf('/') + 1) || 'the bucket root',
     group: KIND_LABEL[kindOf(o)] || 'File',
   }))
+  /* THE PALETTE OPENS ON SOMEWHERE TO GO (user 2026-09-30: it opened blank in olina). */
+  const openFolder = (path) => { setAppRoot(false); goFolder(path) }
+  const leafOf = (path) => path.replace(/\/$/, '').split('/').pop()
+  const hintOf = (path) => dirOf(path) || 'the bucket root'
+  const defaultSuggestions = [
+    ...Object.keys(folderRows ?? {}).filter((p) => folderRows[p]?.favourite).sort()
+      .map((p) => ({ id: p, label: leafOf(p), hint: hintOf(p), group: 'Favourites', icon: 'folder', run: () => openFolder(p) })),
+    ...objects.filter((o) => o.favourite && !isSystemFile(o.key))
+      .map((o) => ({ id: o.key, label: leafOf(o.key), hint: hintOf(o.key), group: 'Favourites', icon: 'file' })),
+    ...smartFolders.map((sf) => ({ id: `smart:${sf.id}`, label: sf.name, group: 'Smart folders', icon: 'folder', run: () => setActiveSmart(sf.id) })),
+    ...[...new Set([...treeFolders(''), ...partition(objects.filter((o) => !isSystemFile(o.key)), '').folders])].sort()
+      .map((f) => ({ id: f, label: leafOf(f), group: 'Folders', icon: 'folder', run: () => openFolder(f) })),
+  ]
+  const suggestions = typeof searchSuggestions === 'function' ? searchSuggestions(defaultSuggestions) : (searchSuggestions ?? defaultSuggestions)
   const jumpTo = (key) => {
     const o = objects.find((x) => x.key === key)
     setSearchOpen(false); setSearchQuery('')
@@ -2249,14 +2296,20 @@ export function MediaLibraryBrowse({
     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
+  /* A TYPED QUERY IS A RESULTS LIST (user 2026-09-30, reversing "a flat results list nobody asked
+   * for"): pruning the tree to matching paths hid the files one level down and read as "search only
+   * finds folders". While the bar holds a query, the tree views show every hit flat, each with its
+   * path; clearing it brings the tree back. The wall already was a flat list. */
   const body = (filtered) => (smartMatches
     ? wallPane(filtered ?? smartMatches)
+    : filtered && barQuery.trim() ? wallPane(filtered, true)
     : isWall
       ? wallPane(filtered ?? wallFiles)
       : treeBody(filtered ? new Set(filtered.map((f) => f.key)) : null))
 
   return (
     <div ref={pageRef} {...press} className={`flex flex-col gap-6 ${className}`.trim()}>
+    <RowSize.Provider value={rowSize}>
       <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) } }}
@@ -2440,7 +2493,10 @@ export function MediaLibraryBrowse({
             placeholder="Search this bucket"
             results={searchResults}
             onExpand={() => searchResults[0] && jumpTo(searchResults[0].id)}
-            onSelect={(item) => jumpTo(item.id)}
+            onSelect={(item) => (item.run ? item.run() : jumpTo(item.id))}
+            suggestions={suggestions}
+            enterLabel="Go to file"
+            onOpenResults={(q) => { setSettings({ ...settings, filters: true }); setBarQuery(q) }}
           />
         )}
         {quickLookFolder && (
@@ -2490,6 +2546,8 @@ export function MediaLibraryBrowse({
             title="Files"
             totalCount={filterItems.length}
             searchKeys={['displayKey']}
+            searchValue={barQuery}
+            onSearchChange={setBarQuery}
             filterGroups={[{ label: 'Kind', key: 'kind', values: filterKinds }, ...(filterTags.length ? [{ label: 'Tags', key: 'tags', values: filterTags }] : []), ...(anyStarred ? [{ label: 'Favourites', key: 'starred', values: ['favourite'] }] : [])]}
             mutuallyExclusiveFilters={['kind']}
             /* ONE FUNNEL, NOT TWO (2026-09-22): the crumb row's funnel mounts this bar AND opens
@@ -2513,7 +2571,7 @@ export function MediaLibraryBrowse({
             {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>
-          {isWall && sizeSlider}
+          {isWall ? sizeSlider : rowSlider}
           </div>
         ) : isWall ? (
           /* ONE LINE'S HEIGHT, like the other views' count line — the slider is 24px tall and made
@@ -2665,6 +2723,7 @@ export function MediaLibraryBrowse({
           </>
         )}
       </div>
+    </RowSize.Provider>
     </div>
   )
 }

package/src/organisms/ShellSearchOverlay.jsx

@@ -1,6 +1,26 @@
 import { useEffect, useId, useRef, useState } from 'react'
+import { Icon } from '@kolkrabbi/kol-icons'
 import SearchInput from '../molecules/SearchInput.jsx'
 import Tag from '../atoms/Tag.jsx'
+import Kbd from '../atoms/Kbd.jsx'
+import OptionRow from '../molecules/OptionRow.jsx'
+
+/* ONE COLUMN (2026-09-30): rows, headings and footer sit on the field's own
+ * geometry — the p-2 inset, then the md control's 1px ring + 16px pad — so
+ * every glyph and word lines up under the field's icon and caret. */
+
+/* Rows bucketed by `group` in first-seen order, rank kept inside a group —
+ * one heading per group; arrows rove this order, not the engine's. */
+function groupRows(rows) {
+  const order = []
+  const byGroup = new Map()
+  rows.forEach((r) => {
+    const g = r.group ?? ''
+    if (!byGroup.has(g)) { byGroup.set(g, []); order.push(g) }
+    byGroup.get(g).push(r)
+  })
+  return order.flatMap((g) => byGroup.get(g))
+}
 
 /**
  * HighlightMatch — default row renderer: underlines the first
@@ -56,7 +76,9 @@ export function HighlightMatch({ label, query, ranges }) {
  *
  * @param {boolean}  open          mount/unmount the overlay
  * @param {Function} onClose       () => void — backdrop click, Escape, post-select
- * @param {Array}    results       pre-filtered rows: { id, label, group?, hint? }
+ * @param {Array}    results       pre-filtered rows: { id, label, group?, hint?, icon? }
+ * @param {Array}    [suggestions] rows shown while the query is empty (same shape) —
+ *                                 the palette opens on somewhere to go, not a blank box
  * @param {string}   query         controlled query (drives the highlight slice)
  * @param {Function} onQueryChange (string) => void — input change
  * @param {Function} onSelect      (item) => void — row click / Enter; consumer navigates
@@ -65,11 +87,15 @@ export function HighlightMatch({ label, query, ranges }) {
  *                                 the panel's last line, so Enter is never a surprise
  *                                 (e.g. `All results for “q”`). Rows may carry
  *                                 `highlights` ([start, end] ranges) from the engine.
+ * @param {Function} [onOpenResults] (query) => void — ⌘/Ctrl+Enter: every hit, on the consumer's
+ *                                 own results surface. Plain Enter keeps its meaning.
+ * @param {string}   [resultsLabel] the footer's second line for ⌘Enter (e.g. `All results`)
  */
 export default function ShellSearchOverlay({
   open,
   onClose,
-  results = [],
+  results: rawResults = [],
+  suggestions = [],
   /* EXPANDED — the palette's second state (user ruling 2026-08-01). Enter
    * commits the query and opens `children` as the results body; the palette
    * and the old tag overlay are one surface with two states, not two
@@ -84,6 +110,8 @@ export default function ShellSearchOverlay({
   onSelect,
   placeholder = 'Search…',
   enterLabel,
+  onOpenResults,
+  resultsLabel = 'All results',
 }) {
   const panelRef = useRef(null)
   const listRef = useRef(null)
@@ -92,6 +120,7 @@ export default function ShellSearchOverlay({
   /* Has the user actually chosen a row? See the Enter branch — without this,
    * index 0 counts as a selection and Enter navigates somewhere unasked. */
   const [navigated, setNavigated] = useState(false)
+  const results = groupRows(query ? rawResults : suggestions)
   const active = results.length > 0 ? Math.min(activeIndex, results.length - 1) : -1
 
   /* Focus in on open, restore the opener on close. querySelector instead of
@@ -110,7 +139,7 @@ export default function ShellSearchOverlay({
   /* Keep the active row visible inside the scrolling list. */
   useEffect(() => {
     if (active < 0) return
-    listRef.current?.children[active]?.scrollIntoView({ block: 'nearest' })
+    listRef.current?.querySelectorAll('[role="option"]')[active]?.scrollIntoView({ block: 'nearest' })
   }, [active])
 
   if (!open) return null
@@ -136,12 +165,16 @@ export default function ShellSearchOverlay({
       setActiveIndex((i) => Math.max(i - 1, 0))
     } else if (e.key === 'Enter') {
       e.preventDefault()
+      /* ⌘ENTER OPENS EVERY HIT (user 2026-09-30: *"enter would focus searched item, and maybe
+       * command enter would open the results page"*) — only where the consumer has a place for them. */
+      if ((e.metaKey || e.ctrlKey) && onOpenResults && query) { onOpenResults(query); onClose?.(); return }
       /* Enter COMMITS the query and expands. It only selects when the user has
        * actually arrowed to a row — `activeIndex` starts at 0, so "a row is
        * highlighted" is true from the first keystroke and testing `active >= 0`
        * made Enter navigate to whatever happened to be first. Committing a
        * query must never be a navigation you didn't choose. */
-      if (navigated) select(results[active])
+      /* An empty query has nothing to commit — Enter goes to the top suggestion. */
+      if (active >= 0 && (navigated || !query)) select(results[active])
       else onExpand?.()
     } else if (e.key === 'Tab') {
       /* Focus trap — the input is the palette's only tab stop. */
@@ -182,8 +215,11 @@ export default function ShellSearchOverlay({
             ))}
           </div>
         )}
+        {/* A REAL FIELD, inset in the panel (2026-09-30, shadcn's palette as
+          * the aim) — the flush `bare` strip read as a hole, not a control. */}
+        <div className="kol-tone-grey p-2">
         <SearchInput
-          bare
+          className="w-full"
           value={query}
           onChange={(e) => onQueryChange?.(e.target.value)}
           placeholder={chips.length > 0 ? 'Narrow these results…' : placeholder}
@@ -193,6 +229,7 @@ export default function ShellSearchOverlay({
           aria-controls={listId}
           aria-activedescendant={active >= 0 ? optionId(results[active]) : undefined}
         />
+        </div>
 
         {/* WHY THIS IS NOT `molecules/Dropdown` (asked 2026-08-01). Dropdown is
           * a SELECT: a trigger, a `value`, `onChange(value)`, and rows that are
@@ -204,7 +241,8 @@ export default function ShellSearchOverlay({
           *
           * THE ROW CONTRACT (was documented nowhere):
           *   label     the row's text, match-highlighted against the query
-          *   group     right-aligned origin — 'Atoms', 'Documentation', 'Tags'
+          *   group     section heading the row files under — 'Atoms', 'Documentation', 'Tags'
+          *   icon      optional leading glyph (kol-icons name)
           *   hint      subtext shown when the LABEL was not what matched
           *   href      a destination; dismisses the palette
           *   action    a closure; runs and KEEPS the palette open (tag rows)
@@ -212,46 +250,52 @@ export default function ShellSearchOverlay({
         {expanded ? (
           <div className="border-t border-fg-08 max-h-[70vh] overflow-y-auto">{children}</div>
         ) : results.length > 0 && (
+          /* FIXED BODY HEIGHT — the panel holds still while the list narrows. */
           <ul
             ref={listRef}
             id={listId}
             role="listbox"
-            className="border-t border-fg-08 max-h-80 overflow-y-auto py-1"
+            className="kol-tone-grey h-80 overflow-y-auto px-2 pb-2"
           >
-            {results.map((item, i) => (
-              <li
-                key={item.id}
-                id={optionId(item)}
-                role="option"
-                aria-selected={i === active}
-                /* preventDefault keeps focus in the input through the click */
-                onMouseDown={(e) => e.preventDefault()}
-                onClick={() => select(item)}
-                onMouseEnter={() => { setActiveIndex(i); setNavigated(true) }}
-                className={`flex items-center gap-2 px-4 py-1.5 cursor-pointer kol-mono-14 transition-colors ${
-                  i === active ? 'bg-fg-08 text-fg' : 'text-fg-80'
-                }`}
-              >
-                <span className="flex flex-col min-w-0">
-                  <span className="truncate">
-                    <HighlightMatch label={item.label} query={query} ranges={item.highlights} />
-                  </span>
-                  {item.hint && (
-                    <span className="kol-mono-12 text-fg-48 truncate">{item.hint}</span>
+            {results.map((item, i) => {
+              const heading = (item.group ?? '') !== (results[i - 1]?.group ?? '') || i === 0
+              return (
+                <li key={item.id} role="presentation">
+                  {heading && item.group && (
+                    <p className="kol-helper-12 text-fg-48 px-4 border-x border-transparent pt-3 pb-2">{item.group}</p>
                   )}
-                </span>
-                {item.group && (
-                  <span className="ml-auto shrink-0 kol-helper-10 text-fg-48">{item.group}</span>
-                )}
-              </li>
-            ))}
+                  <OptionRow
+                    id={optionId(item)}
+                    role="option"
+                    aria-selected={i === active}
+                    active={i === active}
+                    icon={item.icon}
+                    label={<HighlightMatch label={item.label} query={query} ranges={item.highlights} />}
+                    hint={item.hint}
+                    /* preventDefault keeps focus in the input through the click */
+                    onMouseDown={(e) => e.preventDefault()}
+                    onClick={() => select(item)}
+                    onMouseEnter={() => { setActiveIndex(i); setNavigated(true) }}
+                  />
+                </li>
+              )
+            })}
           </ul>
         )}
-        {!expanded && enterLabel && query && (
-          <p className="flex items-center gap-2 border-t border-fg-08 px-4 py-2 kol-helper-12 text-fg-64">
-            <kbd className="kol-helper-12 rounded-[var(--kol-radius-sm)] bg-fg-08 px-1.5 py-0.5 text-fg">↵</kbd>
-            {enterLabel}
-          </p>
+        {/* THE FOOTER SAYS WHAT ENTER DOES — always, not only once typing. */}
+        {!expanded && ((!query && results.length > 0) || (query && enterLabel)) && (
+          <div className="border-t border-fg-08 py-2">
+            <p className="flex items-center gap-2 kol-helper-12 text-fg-48 mx-2 px-4 border-x border-transparent">
+              <Kbd icon="corner-down-left" />
+              {query ? enterLabel : 'Go to page'}
+            </p>
+            {query && onOpenResults && (
+              <p className="flex items-center gap-2 kol-helper-12 text-fg-48 mx-2 px-4 border-x border-transparent pt-1">
+                <Kbd icon="command"><Icon name="corner-down-left" size={12} /></Kbd>
+                {resultsLabel}
+              </p>
+            )}
+          </div>
         )}
       </div>
     </div>