@kolkrabbi/kol-component 0.221.0 → 0.223.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.221.0",
+  "version": "0.223.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

@@ -120,6 +120,7 @@ export { default as Slider } from './molecules/Slider.jsx'
 export { default as SpecList } from './molecules/SpecList.jsx'
 export { default as SpectrumControls, HueStrip, SBSquare, WheelTriangle } from './organisms/SpectrumControls.jsx'
 export { default as SplitToolButton } from './molecules/SplitToolButton.jsx'
+export { default as ToolPalette } from './organisms/ToolPalette.jsx'
 export { default as SwatchControls, SwatchStack, EyedropPick } from './molecules/SwatchControls.jsx'
 export { default as TabsRow } from './molecules/TabsRow.jsx'
 

package/src/molecules/SplitToolButton.jsx

@@ -54,7 +54,14 @@ import { glyphSize } from '../hooks/glyphLadders.js'
  * @param {boolean} props.active - Whether this tool group is the active tool — lit trigger, `aria-pressed`
  * @param {'xs'|'sm'|'md'|'lg'} props.size - Trigger box on the pinned-square ladder — 22 · 26 · 32 · 40 (default: 'md'). The glyph follows the SOLO ladder; it is never set at the call site
  * @param {boolean} props.blurOnClick - Blur the trigger after click so a canvas can reclaim focus and refresh its cursor (default: false)
+ * @param {Function} props.onTrigger - Replaces the trigger's arm: fires with the trigger variant's id on every click. For a fold of one-shot ACTIONS (Boolean: the trigger re-runs the last-picked op) — no pressed state is implied (default: arm via `onChange`)
+ * @param {boolean} props.disabled - Disables the trigger — `.kol-btn:disabled` dims it (default: false)
+ * @param {ElementType} props.iconComponent - Glyph renderer receiving `{ name, size, className, style }` — Button's seam (default: DS `Icon`)
  * @param {string} props.aria-label - Trigger label fallback when no variant resolves
+ *
+ * A variant may carry its own `onSelect()` — that row does its own thing instead of `onChange`
+ * (Text: "Text" arms the tool, "Kinetic type" inserts a layer). Without `lastPicked` the trigger
+ * remembers the last row picked from the menu (kol-fxr ToolPalette, editor-panels-the-held-specs A3).
  * @param {string} props.className - Additional classes on the trigger
  */
 
@@ -77,6 +84,9 @@ const SplitToolButton = ({
   active = false,
   size = 'md',
   blurOnClick = false,
+  onTrigger,
+  disabled = false,
+  iconComponent: IconC = Icon,
   className = '',
   'aria-label': ariaLabel,
 }) => {
@@ -89,20 +99,23 @@ const SplitToolButton = ({
     role: 'menu',
   })
 
+  const [ownLast, setOwnLast] = useState(null)
   const byId = (id) => variants.find((v) => v.id === id)
-  const triggerVariant = (active && byId(value)) || byId(lastPicked) || variants[0]
+  const triggerVariant = (active && byId(value)) || byId(lastPicked ?? ownLast) || variants[0]
   const label = triggerVariant?.label ?? ariaLabel
   const title = triggerVariant?.shortcut ? `${label} (${triggerVariant.shortcut})` : label
 
   /* Arm the last-picked variant on the same click that toggles the menu —
    * floating-ui's useClick (on the reference) handles the open/close half. */
   const handleTriggerClick = (event) => {
-    if (!active && triggerVariant) onChange?.(triggerVariant.id)
+    if (onTrigger) { if (triggerVariant) onTrigger(triggerVariant.id) }
+    else if (!active && triggerVariant) onChange?.(triggerVariant.id)
     if (blurOnClick) event.currentTarget.blur()
   }
 
   const handleSelect = (variant) => {
-    onChange?.(variant.id)
+    if (variant.onSelect) variant.onSelect()
+    else { onChange?.(variant.id); setOwnLast(variant.id) }
     setOpen(false)
   }
 
@@ -113,11 +126,12 @@ const SplitToolButton = ({
         {...popover.getReferenceProps({ onClick: handleTriggerClick })}
         type="button"
         className={`relative kol-btn kol-btn-ghost kol-btn-icon kol-btn-${size} ${active ? 'kol-btn-pressed' : 'kol-btn-quiet'} ${className}`.trim()}
-        aria-pressed={active}
+        disabled={disabled}
+        aria-pressed={onTrigger ? undefined : active}
         aria-label={label}
         title={title}
       >
-        {triggerVariant && <Icon name={triggerVariant.icon} size={glyphSize(size, true)} />}
+        {triggerVariant && <IconC name={triggerVariant.icon} size={glyphSize(size, true)} />}
         <FoldIndicator />
       </button>
       {/* w-max — floats size to content, the menu-family law (2026-08-09). */}
@@ -137,7 +151,7 @@ const SplitToolButton = ({
               className="w-full kol-helper-12 px-3 h-8 inline-flex items-center gap-2 text-body hover:text-emphasis text-left"
             >
               <span className="shrink-0 w-4 inline-flex items-center justify-center">
-                <Icon name={variant.icon} size={14} />
+                <IconC name={variant.icon} size={14} />
               </span>
               <span className="flex-1 truncate">{variant.label}</span>
               <span className="kol-helper-10 text-emphasis shrink-0">

package/src/organisms/ColumnBrowser.jsx

@@ -63,6 +63,7 @@ import { GRAB_COLUMN } from '../utilities/motion.js'
  * @param {Function} formatDate   (isoString) => string — the row/preview date, ISO date-only by default
  * @param {Function} partition    (objects, level) => { folders: string[], files: object[] }
  * @param {Function} renderPreview  (file) => ReactNode — replaces the preview column's media frame (the facts stay — Dimensions and Length are read off whatever <img> / <video> / <audio> the node loads); without it images render the organism's <img>, everything else the DS KindPreview
+ * @param {Function} renderDetails  (file) => ReactNode — rows under the preview column's facts (tags, an Edit action); absent, nothing is added
  * @param {number|string} height    controlled height — px as a number, or ANY CSS length (`'100%'`, `'60vh'`,
  *                                  `'calc(100dvh - 240px)'`) so the browser can fill the space it is given
  *                                  (kol-client-olina 2026-09-22); a CSS length draws no height grabber;
@@ -260,10 +261,16 @@ function Row({
     onDragStart: drop ? (e) => { e.stopPropagation(); drop.onDragStart(e, drop.path) } : undefined,
     onDragOver: (e) => { if (takesFiles(e) || (drop && !isFileDrag(e) && drop.canDrop(drop.path))) { e.preventDefault(); setOver(true) } },
     onDragLeave: () => setOver(false),
+    /* A ROW THAT CANNOT TAKE THE DROP LETS IT BUBBLE (the file-onto-file bug, 2026-09-25): the
+     * enclosing column / list allows the drag, so the drop still fires HERE, and moving into a
+     * FILE's key renamed the dragged file. Unguarded, it skipped `canDrop`; now the container
+     * takes it — dropped on a file, it lands in that file's folder, as Finder does. */
     onDrop: (e) => {
-      e.preventDefault(); e.stopPropagation(); setOver(false)
-      if (takesFiles(e)) dropFiles(e.dataTransfer.files)
-      else if (drop && !isFileDrag(e)) drop.onDrop(drop.path)
+      setOver(false)
+      if (takesFiles(e)) { e.preventDefault(); e.stopPropagation(); dropFiles(e.dataTransfer.files); return }
+      if (!drop || isFileDrag(e) || !drop.canDrop(drop.path)) return
+      e.preventDefault(); e.stopPropagation()
+      drop.onDrop(drop.path)
     },
   } : {}
   return (
@@ -350,7 +357,7 @@ function Row({
   )
 }
 
-function Preview({ o, urlOf, kindOf, kindLabel, formatSize, formatDate, renderPreview, width }) {
+function Preview({ o, urlOf, kindOf, kindLabel, formatSize, formatDate, renderPreview, renderDetails, width }) {
   // Pixel size and length come from the loaded media itself — the bucket stores
   // none. `{ w, h }` off an <img> load, `{ w, h, len }` off a <video>'s and
   // `{ len }` off an <audio>'s loadedmetadata (ColumnBrowserMediaFacts, kol-r2b2
@@ -408,6 +415,14 @@ function Preview({ o, urlOf, kindOf, kindLabel, formatSize, formatDate, renderPr
           </div>
         ))}
       </dl>
+      {/* `renderDetails(o)` — the consumer's rows under the facts (the media D1 pass: tags, Edit) */}
+      {/* its own island: a click or a drag in here is not a click on the browser's background,
+          which deselects (a tag field would unpick the file it edits) */}
+      {renderDetails && (
+        <div onClick={(e) => e.stopPropagation()} onPointerDown={(e) => e.stopPropagation()} onMouseDown={(e) => e.stopPropagation()}>
+          {renderDetails(o)}
+        </div>
+      )}
     </div>
   )
 }
@@ -474,6 +489,9 @@ export default function ColumnBrowser({
   formatDate = defaultFormatDate,
   partition = defaultPartition,
   renderPreview,
+  /* `renderDetails(file)` — extra rows under the preview column's facts (tags, an Edit action);
+   * absent, the column is exactly what it was */
+  renderDetails,
   height,
   defaultHeight = 528,
   onHeightChange,
@@ -648,6 +666,9 @@ export default function ColumnBrowser({
 
   const shiftAnchor = useRef(null)
   const onKeyDown = (e) => {
+    /* typing in a field inside the browser (the preview's tag field) is not navigation */
+    const el = e.target
+    if (el?.isContentEditable || /^(INPUT|TEXTAREA|SELECT)$/.test(el?.tagName ?? '')) return
     /* ⌘↑ / ⌘↓ (user 2026-09-23: *"all modes should 'command up down' to move up and down parent
      * child"*) — Finder's: ⌘↑ is ←, back to the enclosing folder; ⌘↓ opens what the cursor is on,
      * → for a folder and Quick Look for a file. */
@@ -1029,7 +1050,7 @@ export default function ColumnBrowser({
         </>
       ) : shown && (
         <>
-          <Preview key={shown.key} o={shown} urlOf={urlOf} kindOf={kindOf} kindLabel={kindLabel} formatSize={formatSize} formatDate={formatDate} renderPreview={renderPreview} width={widthOf('preview')} />
+          <Preview key={shown.key} o={shown} urlOf={urlOf} kindOf={kindOf} kindLabel={kindLabel} formatSize={formatSize} formatDate={formatDate} renderPreview={renderPreview} renderDetails={renderDetails} width={widthOf('preview')} />
           <ResizeHandle axis="x" onDrag={resizeCol('preview')} onEnd={endDrag} />
         </>
       )}

package/src/organisms/MediaLibraryPages.jsx

@@ -4,6 +4,7 @@ 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 Tag from '../atoms/Tag.jsx'
 import IconFrame from '../atoms/IconFrame.jsx'
 import ActionButton from '../atoms/ActionButton.jsx'
 import SizeOrDownload from '../atoms/SizeOrDownload.jsx'
@@ -66,6 +67,18 @@ import { nearestRatio } from '../utilities/ratios.js'
  * `client.buckets()` (kol-media-client ≥0.2.0); a client with none is one bucket
  * and no dropdown. Settings are kol-r2b2's per-bucket model (`SETTINGS_BASE`),
  * controlled through `settings` / `onSettingsChange` so a consumer persists them.
+ *
+ * WHAT A DATABASE BESIDE THE BUCKET ADDS (the media D1 pass, 2026-09-25 — kol-olina keeps these
+ * in Cloudflare D1). Every verb is optional; a client without one hides that feature and nothing
+ * else changes. Keys are the page's own (bucket keys), `bucket` is the bucket id.
+ *   tags          listed objects carry `tags: string[]`; `setTags(key, tags, bucket)` writes them —
+ *                 preview-pane chips, "Tags…" / "Add tags to N…" in the menu, a Tags filter
+ *                 group, a Tags column under Fields
+ *   text editing  `readText(key, bucket) → { text, draft }` · `writeText(key, text, bucket)` ·
+ *                 `saveDraft(key, text | null, bucket)`; listed objects carry `hasDraft` — Edit in
+ *                 the pane and in Quick Look for markdown · json · yaml · text · code
+ *   settings      `loadSettings(bucket)` · `saveSettings(bucket, settings | null)` (null = reset) —
+ *                 used when the page is UNCONTROLLED; a `settings` prop still wins
  */
 
 /* THE ROW VIEW'S COLUMNS (user 2026-09-22). OFF by default and `rowColumns` turns them on: with
@@ -165,11 +178,32 @@ function useBucketLibrary({ client, bucket, defaults, settings: controlled, onSe
   const buckets = useMemo(() => client?.buckets?.() ?? [], [client])
   const bucketMeta = buckets.find((b) => b.id === bucket) ?? buckets[0] ?? { id: null, label: '', writable: false }
   const bucketId = bucketMeta.id
-  const [own, setOwn] = useState(() => ({ ...SETTINGS_BASE, ...(defaults?.[bucketId] ?? defaults ?? {}) }))
+  const base = () => ({ ...SETTINGS_BASE, ...(defaults?.[bucketId] ?? defaults ?? {}) })
+  const [own, setOwn] = useState(base)
+  /* PERSONALISATION (the media D1 pass, 2026-09-25): an uncontrolled page whose client offers
+   * `loadSettings(bucket)` / `saveSettings(bucket, settings | null)` keeps each person's view
+   * settings THERE — kol-olina's D1 — instead of for this tab only. `null` is reset. A `settings`
+   * prop still wins: a consumer that owns them is left alone, exactly as before. */
+  const remote = !controlled && typeof client?.loadSettings === 'function'
+  useEffect(() => {
+    if (!remote) return undefined
+    let live = true
+    Promise.resolve(client.loadSettings(bucketId ?? undefined))
+      .then((got) => { if (live) setOwn({ ...base(), ...(got ?? {}) }) })
+      .catch(() => {})
+    return () => { live = false }
+  }, [remote, client, bucketId]) // eslint-disable-line react-hooks/exhaustive-deps
   const settings = controlled ?? own
   const setSettings = (next) => {
-    if (next === null) { const back = { ...SETTINGS_BASE, ...(defaults?.[bucketId] ?? defaults ?? {}) }; if (!controlled) setOwn(back); onSettingsChange?.(back); return }
+    if (next === null) {
+      const back = base()
+      if (!controlled) setOwn(back)
+      if (remote) Promise.resolve(client.saveSettings?.(bucketId ?? undefined, null)).then((got) => got && setOwn({ ...back, ...got })).catch(() => {})
+      onSettingsChange?.(back)
+      return
+    }
     if (!controlled) setOwn(next)
+    if (remote) Promise.resolve(client.saveSettings?.(bucketId ?? undefined, next)).catch(() => {})
     onSettingsChange?.(next)
   }
   const [loaded, setLoaded] = useState({ key: null, bucket: null, objects: [], error: null })
@@ -213,6 +247,30 @@ function ImageFrame({ src, vector }) {
 }
 
 
+/* TAGS IN THE PREVIEW PANE (the media D1 pass, 2026-09-25). The file's tags as removable chips and
+ * one field that adds on Enter — comma-separated adds several. Tags are the CLIENT's (`setTags`);
+ * without it, or on a read-only bucket, the chips show and nothing edits them. */
+function TagEditor({ tags = [], onChange }) {
+  const add = (raw) => {
+    const next = raw.split(',').map((t) => t.trim().toLowerCase()).filter(Boolean)
+    if (next.length) onChange([...new Set([...tags, ...next])])
+  }
+  if (!onChange && !tags.length) return null
+  return (
+    <div className="flex flex-col gap-2">
+      <span className="kol-mono-12 text-fg-48">Tags</span>
+      {tags.length > 0 && (
+        <div className="flex flex-wrap gap-1">
+          {tags.map((t) => (
+            <Tag key={t} variant="secondary" size="sm" onRemove={onChange ? () => onChange(tags.filter((x) => x !== t)) : undefined}>{t}</Tag>
+          ))}
+        </div>
+      )}
+      {onChange && <Input size="xs" value="" placeholder="Add a tag" aria-label="Add a tag" onCommit={add} />}
+    </div>
+  )
+}
+
 /* `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. */
@@ -232,10 +290,16 @@ function FolderRow({ name, icon = 'folder', onClick, onDoubleClick, depth = 0, e
   const dropProps = drag || dropFiles ? {
     onDragOver: (e) => { if (takesFiles(e) || (drag && !isFileDrag(e) && drag.canDrop(drag.path))) { e.preventDefault(); setOver(true) } },
     onDragLeave: () => setOver(false),
+    /* A ROW THAT CANNOT TAKE THE DROP LETS IT BUBBLE (the file-onto-file bug, 2026-09-25): the
+     * enclosing column / list allows the drag, so the drop still fires HERE, and moving into a
+     * FILE's key renamed the dragged file. Unguarded, it skipped `canDrop`; now the container
+     * takes it — dropped on a file, it lands in that file's folder, as Finder does. */
     onDrop: (e) => {
-      e.preventDefault(); e.stopPropagation(); setOver(false)
-      if (takesFiles(e)) dropFiles(e.dataTransfer.files)
-      else if (drag && !isFileDrag(e)) drag.onDrop(drag.path)
+      setOver(false)
+      if (takesFiles(e)) { e.preventDefault(); e.stopPropagation(); dropFiles(e.dataTransfer.files); return }
+      if (!drag || isFileDrag(e) || !drag.canDrop(drag.path)) return
+      e.preventDefault(); e.stopPropagation()
+      drag.onDrop(drag.path)
     },
   } : {}
   return (
@@ -264,6 +328,7 @@ function FolderRow({ name, icon = 'folder', onClick, onDoubleClick, depth = 0, e
           line up or the header above them is a lie. The trailing chevron went with them: it
           promised a click that opens, and a click now SELECTS (opening is a double-click). */}
       {cols && <>
+        {cols.tags != null && <span className="shrink-0" style={{ width: cols.tags }} />}
         <span className="kol-mono-12 text-fg-32 shrink-0 truncate" style={{ width: cols.date }}>{meta}</span>
         <span className="kol-mono-12 text-fg-24 shrink-0 truncate" style={{ width: cols.size }}>—</span>
       </>}
@@ -340,6 +405,7 @@ function FileRow({ o, onClick, onDoubleClick, depth = 0, formatDate, thumb, cols
       </span>
       <span className="flex-1" />
       {cols && <>
+        {cols.tags != null && <span className="kol-mono-12 text-fg-48 shrink-0 truncate" style={{ width: cols.tags }}>{(o.tags ?? []).map((t) => `#${t}`).join(' ')}</span>}
         <span className="kol-mono-12 text-fg-32 shrink-0 truncate" style={{ width: cols.date }}>{formatDate?.(o.uploaded)}</span>
         <span className="kol-mono-12 text-fg-32 shrink-0 truncate" style={{ width: cols.size }}>{formatSize(o.size)}</span>
       </>}
@@ -451,12 +517,112 @@ function RowHeader({ sortBy = 'name', sortDir = 'asc', onSort, width, cols, onRe
       <span className="w-4 shrink-0" aria-hidden="true" />
       <span className="w-8 shrink-0" aria-hidden="true" />
       <span className="flex-1 min-w-0">{label('name', 'Name')}</span>
+      {/* Tags does not sort — a file has several — so its header is a plain label */}
+      {cols.tags != null && (
+        <div className="relative shrink-0 border-l" style={{ width: cols.tags, borderColor: 'var(--kol-oq-08)' }}>
+          {handle('tags')}
+          <span className="kol-helper-12 text-fg-48">Tags</span>
+        </div>
+      )}
       {column('date', 'Date')}
       {column('size', 'Size')}
     </div>
   )
 }
 
+/* THE KINDS THAT OPEN AS TEXT — what `FileEditor` takes (the media D1 pass, 2026-09-25) */
+const TEXT_KINDS = new Set(['markdown', 'json', 'yaml', 'text', 'code'])
+
+/* FILE EDITING (the media D1 pass, 2026-09-25) — Quick Look's window with the text in it. Every
+ * pause writes a DRAFT through `client.saveDraft` (kol-olina keeps it in D1, beside the file), so
+ * closing the window or the tab loses nothing; ⌘S or Save writes the FILE (`client.writeText`) and
+ * clears the draft; Revert drops the draft and goes back to the file. The file itself changes only
+ * on Save — a draft is never what anyone else sees. */
+const DRAFT_PAUSE = 800
+function FileEditor({ o, client, bucket, onClose, onSaved, onDraft }) {
+  const [base, setBase] = useState(null) // the saved file's text; null while loading
+  const [text, setText] = useState('')
+  const [status, setStatus] = useState('loading') // loading · saved · draft · editing · saving · error
+  const timer = useRef(null)
+  const latest = useRef('')
+  const baseRef = useRef(null) // `base` for the unmount flush, which would otherwise see the first render's
+  const keep = (b) => { baseRef.current = b; setBase(b) }
+  useEffect(() => {
+    let live = true
+    client.readText(o.key, bucket).then(({ text: file, draft }) => {
+      if (!live) return
+      keep(file ?? '')
+      setText(draft ?? file ?? '')
+      latest.current = draft ?? file ?? ''
+      setStatus(draft != null ? 'draft' : 'saved')
+    }).catch((e) => live && setStatus(`error: ${e.message}`))
+    return () => { live = false }
+  }, [o.key]) // eslint-disable-line react-hooks/exhaustive-deps
+  const flushDraft = () => {
+    if (timer.current == null) return undefined
+    clearTimeout(timer.current); timer.current = null
+    const t = latest.current
+    const clean = t === baseRef.current
+    return Promise.resolve(client.saveDraft?.(o.key, clean ? null : t, bucket))
+      .then(() => { setStatus(clean ? 'saved' : 'draft'); onDraft?.(o.key, !clean) })
+      .catch(() => {})
+  }
+  useEffect(() => () => { flushDraft() }, []) // eslint-disable-line react-hooks/exhaustive-deps
+  const edit = (t) => {
+    setText(t); latest.current = t; setStatus('editing')
+    clearTimeout(timer.current)
+    timer.current = setTimeout(flushDraft, DRAFT_PAUSE)
+  }
+  const save = async () => {
+    clearTimeout(timer.current); timer.current = null
+    setStatus('saving')
+    try {
+      const res = await client.writeText(o.key, latest.current, bucket)
+      keep(latest.current); setStatus('saved')
+      onSaved?.(o.key, res)
+    } catch (e) { setStatus(`error: ${e.message}`) }
+  }
+  const revert = async () => {
+    clearTimeout(timer.current); timer.current = null
+    await client.saveDraft?.(o.key, null, bucket)
+    setText(baseRef.current ?? ''); latest.current = baseRef.current ?? ''; setStatus('saved')
+    onSaved?.(o.key, null)
+  }
+  const dirty = base != null && text !== base
+  /* ⌘S anywhere while the editor is open — not only with the caret in the text */
+  const saveRef = useRef(null)
+  saveRef.current = () => { if (baseRef.current != null && latest.current !== baseRef.current) save() }
+  useEffect(() => {
+    const onKey = (e) => { if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === 's') { e.preventDefault(); saveRef.current() } }
+    window.addEventListener('keydown', onKey)
+    return () => window.removeEventListener('keydown', onKey)
+  }, [])
+  const label = { loading: 'Loading…', saved: 'Saved', draft: 'Draft — not saved to the file', editing: 'Editing…', saving: 'Saving…' }[status] ?? status
+  return (
+    <FullscreenOverlay open onClose={() => { flushDraft(); onClose() }} closeButton={false} scrim>
+      <QuickLookFrame title={o.displayKey ?? o.key.split('/').pop()} meta={label} onClose={() => { flushDraft(); onClose() }}
+        actions={(
+          <span className="flex items-center gap-2">
+            {dirty && <Button variant="nav" size="sm" onClick={revert}>Revert</Button>}
+            <Button variant="secondary" size="sm" onClick={save} disabled={!dirty || status === 'saving'}>Save</Button>
+          </span>
+        )}>
+        <textarea
+          value={text}
+          onChange={(e) => edit(e.target.value)}
+          disabled={base == null}
+          spellCheck={false}
+          aria-label={`Edit ${o.key.split('/').pop()}`}
+          className="kol-mono-12 block bg-transparent text-fg-default p-4 resize-none outline-none"
+          /* inline: Tailwind does not generate arbitrary values from package source (see the SVG box
+             in MediaInspector) — the window's own caps */
+          style={{ width: 'min(900px, var(--kol-ql-max-w))', height: 'min(640px, var(--kol-ql-media-h))' }}
+        />
+      </QuickLookFrame>
+    </FullscreenOverlay>
+  )
+}
+
 /**
  * MediaInspector — the full-screen viewer for one file in a set: image, video
  * (scrubbable, audio on), audio, or a document page, in one `QuickLookFrame`, with
@@ -482,8 +648,9 @@ function RowHeader({ sortBy = 'name', sortDir = 'asc', onSort, width, cols, onRe
  * @param {Function} downloadUrl - `(key) => url` for the download control
  * @param {Set|Object} keySet - The bucket's key set, used to find a video's poster
  * @param {boolean} showNav - ‹ › and n / N in the header (default on); off when not paging a selection
+ * @param {Function} onEdit - `(file) => void` — an Edit action in the header for a text file (markdown · json · yaml · text · code); absent, no Edit
  */
-export function MediaInspector({ files, index, onClose, onPrev, onNext, mediaUrl, downloadUrl, keySet, showNav = true }) {
+export function MediaInspector({ files, index, onClose, onPrev, onNext, mediaUrl, downloadUrl, keySet, showNav = true, onEdit }) {
   const o = files[index]
   const [dims, setDims] = useState(null)
   /* the window's size survives paging — Finder keeps it — so it lives here, not in the frame,
@@ -522,6 +689,11 @@ export function MediaInspector({ files, index, onClose, onPrev, onNext, mediaUrl
      * the header; bare at rest with a wash on hover, `sm` so the glyphs sit with the 12px text. */
     actions: (
       <span className="flex items-center gap-1">
+        {onEdit && TEXT_KINDS.has(kind) && (
+          <Tooltip label="Edit">
+            <Button variant="nav" size="sm" iconOnly="edit" onClick={() => onEdit(o)} aria-label="Edit" />
+          </Tooltip>
+        )}
         <CopyAction label="Copy URL" text={mediaUrl(o.key)} />
         <Tooltip label="Download">
           <Button variant="nav" size="sm" iconOnly="download" href={downloadUrl(o.key)} download={o.key.split('/').pop()} aria-label="Download" />
@@ -976,6 +1148,49 @@ export function MediaLibraryBrowse({
   const press = useLongPress()
   const modal = useModal()
   const canWrite = !!fileActions && writable
+  /* TAGS ARE THE CLIENT'S (the media D1 pass, 2026-09-25) — `client.setTags(key, tags, bucket)`
+   * writes them, the listing carries them back as `o.tags`. The list is patched in place so a chip
+   * lands at once; the next listing confirms it. */
+  const canTag = writable && typeof client?.setTags === 'function'
+  const saveTags = (key, tags) => runAction(async () => {
+    await client.setTags(key, tags, bucketMeta.id ?? undefined)
+    lib.setObjects((list) => list.map((o) => (o.key === key ? { ...o, tags } : o)))
+    setPickedFile((f) => (f?.key === key ? { ...f, tags } : f))
+  })
+  const tagsOf = (key) => objects.find((o) => o.key === key)?.tags ?? []
+  /* EDITING IS THE CLIENT'S TOO — `readText` / `writeText`, with `saveDraft` for the pauses */
+  const canEdit = writable && typeof client?.readText === 'function' && typeof client?.writeText === 'function'
+  const [editing, setEditing] = useState(null)
+  const afterEdit = (key, res) => {
+    lib.setObjects((list) => list.map((o) => (o.key === key ? { ...o, hasDraft: false, ...(res?.size != null && { size: res.size, uploaded: new Date().toISOString() }) } : o)))
+  }
+  const hasTags = canTag || objects.some((o) => o.tags?.length)
+  /* what the preview pane adds under a file's facts, in every view */
+  const detailsFor = (o) => {
+    const tags = tagsOf(o.key)
+    const editable = canEdit && TEXT_KINDS.has(kindOf(o))
+    const hasDraft = objects.find((x) => x.key === o.key)?.hasDraft
+    if (!editable && !canTag && !tags.length) return null
+    return (
+      <div className="flex flex-col gap-4">
+        {editable && (
+          <div className="flex items-center gap-3">
+            <Button variant="secondary" size="sm" iconLeft="edit" onClick={() => setEditing(o)}>Edit</Button>
+            {hasDraft && <span className="kol-mono-12 text-fg-48">Unsaved draft</span>}
+          </div>
+        )}
+        {(canTag || tags.length > 0) && <TagEditor tags={tags} onChange={canTag ? (next) => saveTags(o.key, next) : undefined} />}
+      </div>
+    )
+  }
+  const doTags = async (keys) => {
+    const one = keys.length === 1
+    const current = one ? tagsOf(keys[0]).join(', ') : ''
+    const answer = await modal.prompt(one ? 'Tags, separated by commas:' : `Add tags to ${keys.length} files, separated by commas:`, current, { okLabel: 'Save' })
+    if (answer == null) return
+    const typed = answer.split(',').map((t) => t.trim().toLowerCase()).filter(Boolean)
+    for (const key of keys) await saveTags(key, one ? typed : [...new Set([...tagsOf(key), ...typed])])
+  }
   const [busyAction, setBusyAction] = useState(false)
 
   const runAction = async (fn) => {
@@ -1437,7 +1652,7 @@ export function MediaLibraryBrowse({
   const showRowPreview = folderView === 'rows' && (settings.rowPreview ?? true)
   const showGridPreview = view === 'grid' && (settings.rowPreview ?? true)
   /* OFF by default: a row is a name, and the facts live in the preview (user 2026-09-22) */
-  const rowCols = settings.rowColumns ? rowColWidths(settings) : null
+  const rowCols = settings.rowColumns ? { ...rowColWidths(settings), ...(hasTags && { tags: settings.rowColumnWidths?.tags ?? 140 }) } : null
   const previewWidth = settings.columnWidths?.preview ?? 320
   const previewFile = pickedFile && pickedFile.key.startsWith(prefix) ? pickedFile : null
   const previewFolder = pickedFolder && pickedFolder.startsWith(prefix) ? pickedFolder : null
@@ -1459,6 +1674,7 @@ export function MediaLibraryBrowse({
     ) : previewFile ? (
       <ColumnPreview key={previewFile.key} o={previewFile} urlOf={(o) => mediaUrl(o.key)} kindOf={kindOf} kindLabel={KIND_LABEL}
         formatSize={formatSize} formatDate={formatDate} width={previewWidth}
+        renderDetails={detailsFor}
         renderPreview={(o) => {
           if (isImage(o.contentType)) return <ImageFrame src={mediaUrl(o.key)} vector={o.contentType === 'image/svg+xml'} />
           const poster = posterFor(o.key, keySet)
@@ -1580,6 +1796,7 @@ export function MediaLibraryBrowse({
    * 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 }))
   const filterKinds = [...new Set(filterItems.map((o) => o.kind))].sort()
+  const filterTags = [...new Set(filterItems.flatMap((o) => o.tags ?? []))].sort()
 
   /* ── THE BODY, one of four (2026-09-22) ────────────────────────────────────────────────────
    * `treeBody` draws the columns or the rows over whatever object list it is handed — the whole
@@ -1652,6 +1869,7 @@ export function MediaLibraryBrowse({
                 /* the PROP wins when a consumer passes one; otherwise the `···`
                    owns it through settings (item 15) */
                 stackView={stackView ?? settings.stackView ?? 'list'}
+                renderDetails={(o) => detailsFor({ ...o, key: o.key.slice(VROOT.length) })}
                 renderPreview={(o) => {
                   const real = { ...o, key: o.key.slice(VROOT.length) }
                   if (isImage(real.contentType)) return <ImageFrame src={mediaUrl(real.key)} vector={real.contentType === 'image/svg+xml'} />
@@ -2079,8 +2297,13 @@ export function MediaLibraryBrowse({
         )}
         {quickLook && (
           <MediaInspector files={quickLook.files} index={quickLook.index} onClose={closeQuickLook} mediaUrl={mediaUrl} downloadUrl={downloadUrl} keySet={keySet} showNav={rowSelection.size > 1}
+            onEdit={canEdit ? (f) => { closeQuickLook(); setEditing(f) } : undefined}
             onPrev={() => stepQuickLook(-1)} onNext={() => stepQuickLook(1)} />
         )}
+        {editing && (
+          <FileEditor o={editing} client={client} bucket={bucketMeta.id ?? undefined} onClose={() => setEditing(null)} onSaved={afterEdit}
+            onDraft={(key, has) => lib.setObjects((list) => list.map((x) => (x.key === key ? { ...x, hasDraft: has } : x)))} />
+        )}
         {settingsOpen && (
           <MediaSettings bucketMeta={bucketMeta} settings={settings} profile={profile} onChange={setSettings} onReset={() => setSettings(null)} onClose={() => setSettingsOpen(false)} settingsFooter={settingsFooter} />
         )}
@@ -2097,7 +2320,7 @@ export function MediaLibraryBrowse({
             title="Files"
             totalCount={filterItems.length}
             searchKeys={['displayKey']}
-            filterGroups={[{ label: 'Kind', key: 'kind', values: filterKinds }]}
+            filterGroups={[{ label: 'Kind', key: 'kind', values: filterKinds }, ...(filterTags.length ? [{ label: 'Tags', key: 'tags', values: filterTags }] : [])]}
             mutuallyExclusiveFilters={['kind']}
             /* ONE FUNNEL, NOT TWO (2026-09-22): the crumb row's funnel mounts this bar AND opens
              * its panel, and the bar's own funnel closes the bar — the same switch from either
@@ -2179,6 +2402,7 @@ export function MediaLibraryBrowse({
                       <>
                         <MenuDropdownItem iconLeft={<Icon name="copy" size={14} />} onClick={() => doCopyUrl(many)}>Copy {many.length} URLs</MenuDropdownItem>
                         <MenuDropdownItem iconLeft={<Icon name="download" size={14} />} onClick={() => doDownload(many)}>Download {many.length}</MenuDropdownItem>
+                        {canTag && <MenuDropdownItem iconLeft={<Icon name="hash-01" size={14} />} onClick={() => doTags(many)}>Add tags to {many.length}…</MenuDropdownItem>}
                       </>
                     )}
                     {fileActions.remove && (
@@ -2222,6 +2446,9 @@ export function MediaLibraryBrowse({
                   {target.type === 'file' && (
                     <MenuDropdownItem iconLeft={<Icon name="download" size={14} />} onClick={() => doDownload([target.path])}>Download</MenuDropdownItem>
                   )}
+                  {target.type === 'file' && canTag && (
+                    <MenuDropdownItem iconLeft={<Icon name="hash-01" size={14} />} onClick={() => doTags([target.path])}>Tags…</MenuDropdownItem>
+                  )}
                   {!isLevel && fileActions.remove && (
                     <>
                       <MenuDropdownDivider />

package/src/organisms/ToolPalette.jsx

@@ -0,0 +1,70 @@
+import { Icon } from '@kolkrabbi/kol-icons'
+import Button from '../atoms/Button.jsx'
+import Divider from '../atoms/Divider.jsx'
+import SplitToolButton from '../molecules/SplitToolButton.jsx'
+
+/**
+ * ToolPalette — the editor's tool bar as one row (kol-fxr `shell/panels/ToolPalette.jsx`,
+ * editor-panels-the-held-specs A3, 2026-09-25). Four kinds of cell, all on one pinned-square rung:
+ *
+ * - `tool` — arms a mode; lit while `activeId` is its id
+ * - `action` — a one-shot operation (flip, rotate, duplicate)
+ * - `split` — a fold of variants: `SplitToolButton`. A fold of TOOLS arms (Shape); a fold with
+ *   `action: true` runs its variants instead, the trigger re-running the last-picked one
+ *   (Boolean); a variant with `action: true` inside a tool fold is a one-shot row (Text →
+ *   Kinetic type)
+ * - `divider` — a hairline between groups
+ *
+ * The store is the consumer's (the source read `useTool` + `useComposeState` directly): what
+ * is armed, what each action does and **when an item is disabled** — needs a selection, needs
+ * two booleanable layers — all arrive in `items` and are never inferred here.
+ *
+ * `min-w-0 overflow-x-auto`: at a narrow width the row scrolls in its own box instead of
+ * painting over the rail beside it, as the source learned.
+ *
+ * @param {Object} props
+ * @param {Array<{kind: 'tool'|'action'|'split'|'divider', id?: string, icon?: string, label?: string, shortcut?: string, disabled?: boolean, action?: boolean, variants?: Array<{id: string, label: string, icon: string, shortcut?: string, action?: boolean}>}>} props.items - The row, left to right
+ * @param {string} props.activeId - The armed tool's id — a `tool` item's, or any variant's of a tool fold
+ * @param {Function} props.onSelect - (id) => void — a tool (or a tool variant) was armed
+ * @param {Function} props.onAction - (id) => void — an action (or an action variant) was run
+ * @param {'xs'|'sm'|'md'|'lg'} props.size - The rung — 22 · 26 · 32 · 40 (default: 'md', the source's 32)
+ * @param {ElementType} props.iconComponent - Glyph renderer receiving `{ name, size, className, style }` (default: DS `Icon`)
+ * @param {string} props.className - Additional classes on the row
+ */
+const blur = (e) => e.currentTarget.blur()
+
+const ToolPalette = ({
+  items = [],
+  activeId,
+  onSelect,
+  onAction,
+  size = 'md',
+  iconComponent = Icon,
+  className = '',
+}) => (
+  <div className={`flex items-center gap-1 min-w-0 overflow-x-auto ${className}`.trim()}>
+    {items.map((it, i) => {
+      if (it.kind === 'divider') return <Divider key={`d${i}`} variant="vertical" height={20} className="mx-1.5 shrink-0" />
+      const tip = it.shortcut ? `${it.label} (${it.shortcut})` : it.label
+      if (it.kind === 'split') {
+        const variants = (it.variants ?? []).map((v) => (v.action && !it.action ? { ...v, onSelect: () => onAction?.(v.id) } : v))
+        const run = (id) => (it.action ? onAction : onSelect)?.(id)
+        return (
+          <SplitToolButton key={it.id} variants={variants} value={activeId} size={size} iconComponent={iconComponent}
+            active={!it.action && variants.some((v) => v.id === activeId && !v.action)}
+            onChange={run} onTrigger={it.action ? run : undefined}
+            disabled={it.disabled} blurOnClick aria-label={it.label} />
+        )
+      }
+      const isTool = it.kind === 'tool'
+      return (
+        <Button key={it.id} variant="ghost" size={size} quiet iconOnly={it.icon} iconComponent={iconComponent}
+          pressed={isTool ? activeId === it.id : undefined} disabled={it.disabled}
+          aria-label={it.label} title={tip}
+          onClick={(e) => { (isTool ? onSelect : onAction)?.(it.id); blur(e) }} />
+      )
+    })}
+  </div>
+)
+
+export default ToolPalette