@kolkrabbi/kol-component 0.232.0 → 0.234.0

package/src/molecules/SplitToolButton.jsx

@@ -4,7 +4,7 @@ import { PopoverPanel, usePopover, Tooltip } from '../utilities/Popover.jsx'
 import { glyphSize } from '../hooks/glyphLadders.js'
 
 /**
- * SplitToolButton — single-trigger split tool button + variant menu (the
+ * SplitToolButton — A tool button with a variant menu. single-trigger split tool button + variant menu (the
  * tool-palette idiom: Select · Text · [Shape ◢] · Pattern). A pinned-square
  * quiet/pressed trigger shows the current variant while the group is `active`
  * (else the `lastPicked` variant) plus a corner fold indicator; ONE click both
@@ -65,7 +65,7 @@ import { glyphSize } from '../hooks/glyphLadders.js'
  * @param {string} props.className - Additional classes on the trigger
  */
 
-/* Corner fold marker — `fold-indicator`, promoted into kol-icon-set-v1
+/* Corner fold marker — `fold-indicator`, promoted into kol-icon-set-interface
  * 2026-09-03 from kol-fxr's own drawing (editor-set-is-behind-its-source); the
  * comment that stood here said it did not exist yet and should be promoted, so
  * this is that. Lives inside the button so it dims with kol-btn-quiet and

package/src/molecules/Stepper.jsx

@@ -1,5 +1,5 @@
 /**
- * Stepper — number input + chevron buttons, built on the .kol-control shell.
+ * Stepper — A number input with step buttons. number input + chevron buttons, built on the .kol-control shell.
  *
  *   size="xs" / "sm" (default) / "md" / "lg" — matched padding + type class.
  *   Chevron scale follows the size: 6 / 8 / 10 / 12 px each, stacked. xs is the

package/src/molecules/SwatchControls.jsx

@@ -92,7 +92,7 @@ export function SwatchStack({
 }
 
 /**
- * EyedropPick — eyedropper icon button + a sample chip of the sampled color.
+ * EyedropPick — Sample a color from the screen. eyedropper icon button + a sample chip of the sampled color.
  * The button is hidden when the browser EyeDropper API is unavailable (no
  * affordance for an action that can't run); when supported but unusable pass
  * `disabled` to dim it. `onPick` is the app seam where EyeDropper + canvas
@@ -173,7 +173,7 @@ function NoneMarker({ onClear }) {
 }
 
 /**
- * SwatchControls — the composed colour-panel top row: SwatchStack (fill /
+ * SwatchControls — Fill and stroke swatches with an eyedropper. The composed colour-panel top row: SwatchStack (fill /
  * stroke paint chips + swap + none) alongside EyedropPick (eyedropper +
  * sample chip). Fully controlled and store-free; the app owns the swap, clear,
  * and pick handlers.

package/src/molecules/TabsRow.jsx

@@ -5,7 +5,7 @@ import { Icon } from '@kolkrabbi/kol-icons'
 /* taxonomy-ok: nests kol-icons's Icon */
 
 /**
- * TabsRow — labeled underline tab strip: text tabs where the active tab gets
+ * TabsRow — Text tabs with an underline. labeled underline tab strip: text tabs where the active tab gets
  * a 2px bottom underline and emphasis color; inactive tabs are muted and
  * brighten on hover. Optional leading close button and trailing minimise
  * chevron render only when their handlers are passed — no outer chrome, the

package/src/molecules/TiltBento.jsx

@@ -64,7 +64,7 @@ function Media({ src, poster, className }) {
 }
 
 /**
- * TiltBento — media hover-card for grid/bento walls, the Tilt family's composed
+ * TiltBento — A tilting media card for bento walls. media hover-card for grid/bento walls, the Tilt family's composed
  * tile (was `BentoCard` until 2026-08-27, user ruling: the three tilting things
  * in the estate are ONE prefix family — `TiltCard` the bare frame, `TiltBento`
  * this tile, `useTilt` the one hook; `BentoCard` is the alias on the retirement

package/src/molecules/VideoBlock.jsx

@@ -15,7 +15,7 @@ export function getEmbedUrl(url) {
 }
 
 /**
- * VideoBlock — a captioned prose video: the DS Figure shell (optional label,
+ * VideoBlock — A captioned video for prose. a captioned prose video: the DS Figure shell (optional label,
  * aspect-locked bordered frame, optional figcaption) wrapping either an
  * <iframe> embed (YouTube/Vimeo, auto-parsed from `url`) or a native <video>
  * file player. Embed wins when `url` parses; otherwise the `file` player runs.

package/src/molecules/VideoSheet.jsx

@@ -5,7 +5,7 @@ import QuickLookFrame from './QuickLookFrame.jsx'
 /* taxonomy-ok: molecule — nests PlaybackBar + QuickLookFrame (relative). */
 
 /**
- * VideoSheet — video in the Quick Look window: the frame at the video's own aspect ratio, the
+ * VideoSheet — A video in the preview window. video in the Quick Look window: the frame at the video's own aspect ratio, the
  * QuickTime bar docked in the window's footer (2026-09-23 — it floated over the picture, which
  * made video the one kind whose controls sat on the media). No native controls; click on the
  * video toggles play; no autoplay (user 2026-09-23 — Quick Look opens paused), `playsInline`, `preload="metadata"`.

package/src/organisms/Canvas.jsx

@@ -419,7 +419,7 @@ function isTypingTarget(el) {
 }
 
 /**
- * PanZoomViewport — infinite-canvas viewport (pan + zoom), and the one that
+ * PanZoomViewport — An infinite canvas to pan and zoom. infinite-canvas viewport (pan + zoom), and the one that
  * publishes `CanvasZoomContext`.
  *
  * Pan: hold Space + drag (cursor grab/grabbing), or two-finger trackpad
@@ -787,7 +787,7 @@ export function useFrameGeom(containerRef, virtualWidth = CANVAS_VIRTUAL_W) {
 }
 
 /**
- * CanvasRuler — top + left rulers in virtual-canvas px, mapped through the
+ * CanvasRuler — Rulers along the canvas edges. top + left rulers in virtual-canvas px, mapped through the
  * measured frame geometry (see useFrameGeom).
  *
  * Dragging off a ruler starts a new guide: the ruler only ANNOUNCES the
@@ -900,7 +900,7 @@ function GuideLine({ axis, screenPos, interactive, onGrab }) {
 }
 
 /**
- * CanvasGuides — ruler guides rendered at the viewport level so each line
+ * CanvasGuides — Guide lines across the whole canvas. ruler guides rendered at the viewport level so each line
  * spans the entire visible canvas area instead of clipping to the letterbox
  * frame. Positions are stored in virtual canvas px and threaded down as props
  * — the viewport is chrome and owns no guide state; the screen mapping is the

package/src/organisms/ColumnBrowser.jsx

@@ -12,7 +12,7 @@ import useMarquee from '../hooks/useMarquee.js'
 import { GRAB_COLUMN } from '../utilities/motion.js'
 
 /**
- * ColumnBrowser — Finder-style Miller columns over a flat key space (kol-r2b2's
+ * ColumnBrowser — Finder-style columns over a bucket. Finder-style Miller columns over a flat key space (kol-r2b2's
  * `src/ColumnBrowser.jsx`, built and ruled there first — user 2026-08-27: "make
  * it locally first, then ship it" — and shipped verbatim; ticket ColumnBrowser).
  * The listing surface's FOLDER view: it replaces the folder rows above the
@@ -249,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, size = 'md',
+  icon, label, active, trail = false, 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)
@@ -275,15 +275,18 @@ function Row({
     },
   } : {}
   /* 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. */
+   * setting scales height and glyph; the name keeps ONE type in every view (`kol-item-name`, the
+   * grid's), as Finder does. The deepest selection takes the pressed (white) fill, the folders on the
+   * way to it the trail; hover and the bare cursor paint nothing (the 2026-09-02 ruling). The `zones`
+   * row below is the phone's and keeps its own. */
   if (!zones) return (
     <OptionRow
       as="li"
       size={size}
-      fill={false}
-      selected={active}
+      type="kol-item-name"
+      hover={false}
+      selected={active && !trail}
+      trail={active && trail}
       muted={muted && !cursor}
       icon={icon}
       label={label}
@@ -1039,8 +1042,11 @@ export default function ColumnBrowser({
                 label={f.replace(/\/$/, '')}
                 markKey={level + f}
                 active={f === activeFolder || isPicked(level + f)}
+                /* a folder on the path is the TRAIL unless it is the deepest pick — the column after
+                 * it is its own contents with nothing chosen, and no file is showing */
+                trail={f === activeFolder && !isPicked(level + f) && (!!shown || k < levels.length - 2)}
                 cursor={cursorActive && cursor.col === k && cursor.idx === i}
-                trailing={<Icon name="chevron-right" size={12} className="text-oq-32" />}
+                trailing={<Icon name="chevron-right" size={12} className={f === activeFolder && !shown && k === levels.length - 2 ? '' : 'text-oq-32'} />}
                 onContextMenu={onRowContextMenu && ((e) => onRowContextMenu(e, { type: 'folder', path: level + f }))}
                 drop={dragFor?.(level + f)}
                 dropFiles={onDropFiles ? (list) => onDropFiles(list, level + f) : undefined}

package/src/organisms/ContentCollection.jsx

@@ -1,7 +1,7 @@
 import usePrefersReducedMotion from '../hooks/usePrefersReducedMotion.js'
 
 /**
- * ContentCollection — the container half of the content-card system: the
+ * ContentCollection — A grid or list of content items. the container half of the content-card system: the
  * grid/list switch plus the motion that belongs to it. Animation lives in
  * the wrapper — the only place it can (06-content-card-system.md §6);
  * cards never animate themselves.

package/src/organisms/CurveEditor.jsx

@@ -109,7 +109,7 @@ function TermRow({ term, onSet, onRemove, canRemove }) {
 }
 
 /**
- * CurveEditor — curve authoring: a kind picker, per-kind ranges and
+ * CurveEditor — Author a curve by kind and expression. curve authoring: a kind picker, per-kind ranges and
  * EXPRESSION fields, and the epicycle term list.
  *
  * Lifted from kol-fxr's editor (`compose/inspectors/CurveEditor.jsx`,

package/src/organisms/DocumentEditor.jsx

@@ -11,7 +11,7 @@ import { splitFrontmatter, joinFrontmatter } from '@kolkrabbi/kol-markdown'
 import { readDraft, writeDraft, clearDraft } from '../utilities/localDrafts.js'
 
 /**
- * DocumentEditor — write a text file: open one, or make a new one (media D1 plan v2, 2026-09-26).
+ * DocumentEditor — Open or write a text file. write a text file: open one, or make a new one (media D1 plan v2, 2026-09-26).
  *
  * The concept is kol-olina's brand notes page (NoteEdit): a title, a markdown body, Write / Preview,
  * attachments from the bucket, a page for writing something NEW rather than a button hidden in a

package/src/organisms/FeaturedCarousel.jsx

@@ -85,7 +85,7 @@ function SlideMedia({ media, active = true, onEnded, onTimeUpdate }) {
  * the one hero (SectionHeroRound2); this stays as its engine and renders
  * unchanged. Removed from the barrel at the next major.
  *
- * FeaturedCarousel — a full-width carousel of featured media: each wide slide
+ * FeaturedCarousel — A full-width carousel of featured media. a full-width carousel of featured media: each wide slide
  * is a fixed-height frame with an image or HLS-video background and a centered
  * OverlayGlassPanel (title / description / CTA), plus prev/next and optional
  * autoplay with a progress bar.

package/src/organisms/FramedMediaBand.jsx

@@ -1,7 +1,7 @@
 import Image from '../atoms/Image'
 
 /**
- * FramedMediaBand — full-width media breather band: a centered, aspect-locked
+ * FramedMediaBand — A full-width band with one framed image. full-width media breather band: a centered, aspect-locked
  * frame (bordered surface-secondary panel, rounded) holding one object-cover
  * image. Extracted from the foundry TypefacePage, where it sat inlined 5x
  * verbatim between content sections. The double radius (`rounded` panel,

package/src/organisms/GalleryCarousel.jsx

@@ -9,7 +9,7 @@ import MediaViewer from './MediaViewer.jsx'
 const DRAG_THRESHOLD_SQ = 25
 
 /**
- * GalleryCarousel — the project-detail media gallery: a horizontal, drag-scroll
+ * GalleryCarousel — A shelf of media that opens fullscreen. the project-detail media gallery: a horizontal, drag-scroll
  * shelf of image/video tiles where clicking a tile opens THE shared fullscreen
  * MediaViewer starting at that tile.
  *

package/src/organisms/KeyframeEditor.jsx

@@ -22,7 +22,7 @@ export const DEFAULT_KEYFRAMES = [
 ]
 
 /**
- * KeyframeEditor — a keyframe list over a pose track, kept sorted by `t`.
+ * KeyframeEditor — A sorted list of keyframes. a keyframe list over a pose track, kept sorted by `t`.
  *
  *   { t: 0..1, rot: [x, y, z] RADIANS, pos: [x, y, z], scale, ease }
  *

package/src/organisms/LayerStack.jsx

@@ -207,7 +207,7 @@ function CanvasRow({ IconC, active, collapsed, onToggleCollapse, onSelect }) {
 }
 
 /**
- * LayerStack — the layers panel: a z-stacked tree of rows with HTML5 drag to
+ * LayerStack — The layers panel. the layers panel: a z-stacked tree of rows with HTML5 drag to
  * reorder AND reparent in one gesture, hover-revealed eye + lock toggles,
  * inline rename, collapsible containers, and a Canvas root row above it all.
  *
@@ -440,7 +440,7 @@ export default function LayerStack({
 }
 
 /**
- * AddLayerButton — the `+` that opens a menu of layer types. Lives in the
+ * AddLayerButton — Add a layer from a menu. the `+` that opens a menu of layer types. Lives in the
  * panel's tab row, not the stack footer (the source's placement). One entry
  * may expand inline to a kind picker so adding "a shape" doesn't silently
  * default to the first kind.

package/src/organisms/MediaLibrary.jsx

@@ -19,7 +19,7 @@ import { SettingsChipRow, chipCls } from './SettingsPanel.jsx'
 import { filterMedia } from '../utilities/mediaSearch.js'
 
 /**
- * MediaLibrary — a browser over an object bucket, in two views over one
+ * MediaLibrary — Browse and pick files from a bucket. a browser over an object bucket, in two views over one
  * headless core. Consolidates four consumer forks (kol-ds-fxr, kol-labs-single,
  * kol-client-kolkrabbi, kol-website/brand — 9 files, ~1542 lines) that had
  * already diverged: only fxr carried the canvas-taint fix, only labs carried
@@ -263,7 +263,7 @@ function sortFiles(files, { by, dir }) {
 }
 
 /**
- * MediaLibraryProvider — the headless core: one list call, then a
+ * MediaLibraryProvider — The data core behind the media views. 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.

package/src/organisms/MediaLibraryExplorer.jsx

@@ -4,7 +4,7 @@ import { useModal } from '../molecules/Modal.jsx'
 import useMediaQuery from '../hooks/useMediaQuery.js'
 
 /**
- * MediaLibraryExplorer — the media surface, and since 2026-09-22 a thin name for it.
+ * MediaLibraryExplorer — The media browser. the media surface, and since 2026-09-22 a thin name for it.
  *
  * IT USED TO BE THE MERGE ITSELF: it held a BROWSE · FILES switch and mounted one of two pages,
  * each of which listed the bucket, drew its own header and printed its own count. The user's read

package/src/organisms/MediaLibraryPages.jsx

@@ -1,6 +1,6 @@
 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 { ROW_HEIGHT, ROW_FILL } from '../molecules/OptionRow.jsx'
 import { glyphSize } from '../hooks/glyphLadders.js'
 import { Icon } from '@kolkrabbi/kol-icons'
 import Button from '../atoms/Button.jsx'
@@ -303,7 +303,9 @@ 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. */
+ * own anatomy (twisty, drag hit, table columns) and take the ramp's box and glyph, OptionRow's
+ * fills (picked = the pressed white, the folder you are in = the trail) and the one item type,
+ * `kol-item-name`, that the columns and the grid use. */
 const RowSize = createContext('md')
 
 /* `depth` indents a row under the folder it was expanded from; `expanded`/`onToggle` draw the
@@ -341,7 +343,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 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}>
+    <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 ${ROW_FILL.selected}` : ''}${current ? ' is-current' : ''}${current && !selected ? ` ${ROW_FILL.trail}` : ''}`} 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() }}
@@ -353,11 +355,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="shrink-0 flex items-center justify-center text-oq-48"><Icon name={icon} size={glyphSize(size)} /></span>
+        <span className={`shrink-0 flex items-center justify-center${selected ? '' : ' 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={`${ROW_TYPE[size]} min-w-0 truncate text-fg-default`}>{name.replace(/\/$/, '')}</span>
+        <span className={`kol-item-name min-w-0 truncate${selected ? '' : ' 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
@@ -365,8 +367,8 @@ function FolderRow({ name, icon = 'folder', onClick, onDoubleClick, depth = 0, e
           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>
+        <span className={`kol-item-name ${selected ? "opacity-60" : "text-fg-32"} shrink-0 truncate`} style={{ width: cols.date }}>{meta}</span>
+        <span className={`kol-item-name ${selected ? "opacity-60" : "text-fg-24"} shrink-0 truncate`} style={{ width: cols.size }}>—</span>
       </>}
       <RowMenuButton onOpen={onContextMenu} className="-my-1 -mr-1" />
     </li>
@@ -430,21 +432,21 @@ function FileRow({ o, onClick, onDoubleClick, depth = 0, formatDate, thumb, cols
   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 border border-transparent px-3 ${ROW_HEIGHT[size]} 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 ${ROW_FILL.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="shrink-0 flex items-center justify-center text-oq-48 overflow-hidden rounded" style={{ width: glyphSize(size), height: glyphSize(size) }}>
+        <span className={`shrink-0 flex items-center justify-center overflow-hidden rounded${selected ? '' : ' text-oq-48'}`} 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={glyphSize(size)} />}
         </span>
-        <span className={`${ROW_TYPE[size]} min-w-0 truncate text-fg-default`}>{o.displayKey ?? o.key.split('/').pop()}</span>
+        <span className={`kol-item-name min-w-0 truncate${selected ? '' : ' text-fg-default'}`}>{o.displayKey ?? o.key.split('/').pop()}</span>
       </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>
+        {cols.tags != null && <span className={`kol-item-name ${selected ? "opacity-60" : "text-fg-48"} shrink-0 truncate`} style={{ width: cols.tags }}>{(o.tags ?? []).map((t) => `#${t}`).join(' ')}</span>}
+        <span className={`kol-item-name ${selected ? "opacity-60" : "text-fg-32"} shrink-0 truncate`} style={{ width: cols.date }}>{formatDate?.(o.uploaded)}</span>
+        <span className={`kol-item-name ${selected ? "opacity-60" : "text-fg-32"} shrink-0 truncate`} style={{ width: cols.size }}>{formatSize(o.size)}</span>
       </>}
       <RowMenuButton onOpen={onContextMenu} className="-my-1 -mr-1" />
     </li>
@@ -594,7 +596,7 @@ function FileEditorHost({ o, client, bucket, onClose, onSaved, assets }) {
 }
 
 /**
- * MediaInspector — the full-screen viewer for one file in a set: image, video
+ * MediaInspector — View one file at full size. the full-screen viewer for one file in a set: image, video
  * (scrubbable, audio on), audio, or a document page, in one `QuickLookFrame`, with
  * prev / next fixed at the viewport edges.
  *

package/src/organisms/MediaTileGallery.jsx

@@ -2,7 +2,7 @@ import { useState } from 'react'
 import MediaViewer from './MediaViewer.jsx'
 
 /**
- * MediaTileGallery — a stack or grid of framed media tiles that open THE
+ * MediaTileGallery — Media tiles that open a fullscreen viewer. a stack or grid of framed media tiles that open THE
  * shared fullscreen MediaViewer at the clicked tile, paged across all items
  * (the monorepo's FullscreenGallery recreated on the shared viewer instead of
  * its nav-less single image; the AssetFigure/AssetGrid deps are dropped —

package/src/organisms/RecordManager.jsx

@@ -35,7 +35,7 @@ const ToolbarIcon = ({ name, label, onClick, active = false, triggerClassName })
 )
 
 /**
- * RecordManager — full-screen CMS record surface (lobby: RecordManager,
+ * RecordManager — A full-screen CMS record editor. full-screen CMS record surface (lobby: RecordManager,
  * reference: Framer CMS). A reorderable record table plus a slide-over detail
  * panel of FieldRows.
  *

package/src/organisms/SectionCards.jsx

@@ -6,7 +6,7 @@ import useSectionTheme from '../hooks/useSectionTheme.js'
 import { minHeightClass } from './sectionHeights.js'
 
 /**
- * SectionCards — the "N-up feature cards" band: a `SectionText` header over a
+ * SectionCards — A header over a row of feature cards. the "N-up feature cards" band: a `SectionText` header over a
  * responsive row of `SectionCardItem` cards, capped by an optional centred
  * action row. `FeaturesCardSection` is this component under its old name and
  * prop names (`headerLabel` → `headline`, `headerDescription` → `body`,

package/src/organisms/SectionCta.jsx

@@ -5,7 +5,7 @@ import SectionText from '../molecules/SectionText.jsx'
 import { minHeightClass } from './sectionHeights.js'
 
 /**
- * SectionCta — the editorial two-column contact/CTA band: a large display
+ * SectionCta — A closing call-to-action band. the editorial two-column contact/CTA band: a large display
  * wordmark on the left (e.g. "/ CONNECT") and a right column of stacked
  * label-over-value rows, each a `SectionText` (label in the helper voice,
  * value as a heading-01; a row with `href` renders its value as a link).

package/src/organisms/SectionFaq.jsx

@@ -6,7 +6,7 @@ import SectionText from '../molecules/SectionText.jsx'
 import { minHeightClass } from './sectionHeights.js'
 
 /**
- * SectionFaq — a `SectionText` header over an `Accordion` of question /
+ * SectionFaq — Questions and answers in an accordion. a `SectionText` header over an `Accordion` of question /
  * answer items. The one NEW surface in the section family (SectionSet,
  * 2026-08-26) — the behaviour already shipped in the Accordion molecule; this
  * is the section around it.

package/src/organisms/SectionHero.jsx

@@ -85,7 +85,7 @@ function MediaLayer({ media }) {
 }
 
 /**
- * SectionHero — the full-bleed media hero: cover-fit background media (image
+ * SectionHero — Full-bleed media hero with a glass panel. the full-bleed media hero: cover-fit background media (image
  * or video) filling a fixed-height section, an optional surface scrim, and
  * the text in a glass panel over it. `FullBleedHero` is this component under
  * its old name (alias kept).

package/src/organisms/SectionNewsletter.jsx

@@ -8,7 +8,7 @@ import useSectionTheme from '../hooks/useSectionTheme.js'
 import { minHeightClass } from './sectionHeights.js'
 
 /**
- * SectionNewsletter — the newsletter card of the section family
+ * SectionNewsletter — A newsletter signup card. the newsletter card of the section family
  * (SectionNewsletter, kol-website 2026-08-27 — user: the newsletter as a card
  * in the family, same ladder, same cap, content centred on y, not its own
  * thing). `SectionText` (label · headline · body, centred) with the email

package/src/organisms/SectionSplit.jsx

@@ -6,7 +6,7 @@ import useSectionTheme from '../hooks/useSectionTheme.js'
 import { minHeightClass } from './sectionHeights.js'
 
 /**
- * SectionSplit — the media-and-text split section, on `SectionText` (the
+ * SectionSplit — Text beside media. the media-and-text split section, on `SectionText` (the
  * text column) beside the media frame. Two columns at/above 901px, one
  * stacked column below. `FeatureSplit` is this component under its old name
  * and old prop names (kept as an alias — see FeatureSplit.jsx).

package/src/organisms/SettingsPanel.jsx

@@ -9,7 +9,7 @@ import FullscreenOverlay from '../utilities/FullscreenOverlay.jsx'
 import { Tooltip } from '../utilities/Popover.jsx'
 
 /**
- * SettingsPanel — a settings surface for the thing you are looking at: you
+ * SettingsPanel — Settings beside the thing they change. 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).
@@ -107,7 +107,7 @@ export default function SettingsPanel({
 }
 
 /**
- * SettingsRow — a `LabeledControl inline` (SettingsPanelApproved, 2026-08-27):
+ * SettingsRow — One labelled setting. a `LabeledControl inline` (SettingsPanelApproved, 2026-08-27):
  * uppercase label (`kol-helper-10` tracked, meta ink) in a 160px column, the
  * control fills the rest. A switch sits at the far right (`align="end"`, the
  * default); a dropdown fills the row (`align="fill"`). No hint sentences on the
@@ -127,7 +127,7 @@ export function SettingsRow({ label, hint, align = 'end', labelWidth = 160, chil
   )
 }
 
-/** SettingsSwitch — the row's on/off control: the DS ToggleSwitch, bare, sm.
+/** SettingsSwitch — An on/off setting. the row's on/off control: the DS ToggleSwitch, bare, sm.
  *  `disabledHint` rides a DS `Tooltip` so a switch that cannot act says why;
  *  inside a row's `hint` it wins while hovered, as the native `title` did. */
 export function SettingsSwitch({ on = false, onChange, disabled = false, disabledHint, label, title }) {
@@ -144,7 +144,7 @@ export function SettingsSwitch({ on = false, onChange, disabled = false, disable
   return tip ? <Tooltip label={tip}>{toggle}</Tooltip> : toggle
 }
 
-/** LabeledControlSection — a section of LabeledControls: the EYEBROW
+/** LabeledControlSection — A titled section of labelled controls. a section of LabeledControls: the EYEBROW
  *  (`kol-eyebrow text-fg-80`) standing apart from the rows (gap-3), the rows in
  *  their own stack — `rowGap` 1 for switch rows (24 tall already), 2 for
  *  dropdown rows. `divided` = a hairline above (between sections).
@@ -161,7 +161,7 @@ export function LabeledControlSection({ label, divided = false, rowGap = 2, chil
   )
 }
 
-/** SettingsChoice — the row's one-of-N control: the DS Dropdown, sm · primary
+/** SettingsChoice — A one-of-many setting. the row's one-of-N control: the DS Dropdown, sm · primary
  *  (SettingsPanelEyebrowAndDropdowns — user: "put the toggles inside a dropdown,
  *  because it's super messy like it is"). Options are values or `{ value, label }`;
  *  width is the call site's (`className="w-40"`).
@@ -189,7 +189,7 @@ 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'}`
 
 /**
- * SettingsMulti — a many-of-N control as ONE Dropdown (SettingsPanelApproved,
+ * SettingsMulti — A many-of-many setting in one dropdown. a many-of-N control as ONE Dropdown (SettingsPanelApproved,
  * 2026-08-27 — the kinds row): the trigger reads `N of M <noun>`, every entry
  * toggles and `✓` marks the ones that are on. No grouping.
  * @param {Array}  options   [{ value, label }]
@@ -210,7 +210,7 @@ export function SettingsMulti({ options = [], selected = [], onToggle, noun = 'k
 }
 
 /**
- * SettingsChipRow — a wrap of toggle chips with optional counts (an
+ * SettingsChipRow — A row of toggle chips. a wrap of toggle chips with optional counts (an
  * allow-list: every chip sets a default, never a gate). `allChip` puts an
  * "all" chip first — the same control chip, filled when every option is on
  * (SettingsPanelEyebrowAndDropdowns — user: "Show all in ghost mode? makes no
@@ -247,7 +247,7 @@ export function SettingsChipRow({ options = [], selected = [], onToggle, allChip
   )
 }
 
-/** SettingsFooter — a Divider, then one `IconFrame refresh` (primary · sm) at the
+/** SettingsFooter — Reset settings to their defaults. a Divider, then one `IconFrame refresh` (primary · sm) at the
  *  right = reset to defaults (SettingsPanelApproved, 2026-08-27). No status word,
  *  no text button. `customised` is accepted for compatibility and unused.
  *

package/src/organisms/ShellSearchOverlay.jsx

@@ -59,7 +59,7 @@ export function HighlightMatch({ label, query, ranges }) {
 }
 
 /**
- * ShellSearchOverlay — the ⌘K command palette: fullscreen dim + centered
+ * ShellSearchOverlay — The ⌘K search palette. the ⌘K command palette: fullscreen dim + centered
  * panel, a bare SearchInput on top, result rows beneath (HighlightMatch
  * label, dim hint line, right-aligned group label). Distinct from Modal
  * (prompt/confirm only) — this is the search/command primitive.

package/src/organisms/ShortcutsOverlay.jsx

@@ -2,7 +2,7 @@ import { useEffect } from 'react'
 import SettingsSections from './SettingsSections.jsx'
 
 /**
- * ShortcutsOverlay — the keyboard-shortcut sheet: blurred scrim, centred
+ * ShortcutsOverlay — The keyboard shortcut sheet. the keyboard-shortcut sheet: blurred scrim, centred
  * panel, a 2-col grid (label · keys), Esc / backdrop-click close.
  * Ported from the shared cut (mirror's, "copied from kol-monitor").
  *

package/src/organisms/SpectrumControls.jsx

@@ -41,7 +41,7 @@ const HUE_GRADIENT =
   'linear-gradient(to right, hsl(0,100%,50%), hsl(60,100%,50%), hsl(120,100%,50%), hsl(180,100%,50%), hsl(240,100%,50%), hsl(300,100%,50%), hsl(360,100%,50%))'
 
 /**
- * HueStrip — 1D hue slider: a rainbow bar with a draggable knob. Pointer
+ * HueStrip — A hue slider. 1D hue slider: a rainbow bar with a draggable knob. Pointer
  * drag anywhere on the strip; focus + Left/Right (or Down/Up) arrow keys
  * nudge hue by 1° (role="slider").
  *
@@ -116,7 +116,7 @@ export function HueStrip({ hue, onChange }) {
 }
 
 /**
- * SBSquare — 2D saturation/value picker: white→hue horizontal gradient with
+ * SBSquare — Pick saturation and value on a square. 2D saturation/value picker: white→hue horizontal gradient with
  * a black overlay fading upward, crosshair handle. Fills its container
  * (consumer owns the size — and the rounding: apply `rounded-[var(--kol-radius-xs)]
  * overflow-hidden` on the wrapper). Focus + arrow keys nudge: Left/Right =
@@ -233,7 +233,7 @@ function vertexAt(angleRad) {
 }
 
 /**
- * WheelTriangle — HSV color wheel: conic hue ring with an inscribed,
+ * WheelTriangle — A hue wheel with a value triangle. HSV color wheel: conic hue ring with an inscribed,
  * rotating HSV triangle for saturation/value. Ring press snaps hue to the
  * cursor angle and drags; triangle press grabs the SV handle with a
  * cursor↔handle offset so fine tuning never teleports it. Focus + arrow
@@ -478,7 +478,7 @@ function SvgHandle({ cx, cy, r = 2.4 }) {
 }
 
 /**
- * SpectrumControls — the composed classic square picker: HueStrip stacked
+ * SpectrumControls — A hue strip over a saturation square. The composed classic square picker: HueStrip stacked
  * over a fill-height SBSquare, per the source color panel's Hue mode layout
  * (SBSquare wrapped in `rounded-[var(--kol-radius-xs)] overflow-hidden`, see its comment).
  * Fills its container — the consumer owns the outer size. For the ring

package/src/organisms/SpectrumGrid.jsx

@@ -4,7 +4,7 @@ import { resolveCssVar, resolveCssColor, isLight } from '../hooks/cssVar.js'
 import { Tooltip } from '../utilities/Popover.jsx'
 
 /**
- * SpectrumGrid — matrix view of the whole ramp system: rows = ramps, columns =
+ * SpectrumGrid — Every ramp by every stop. matrix view of the whole ramp system: rows = ramps, columns =
  * stops (50 → 900). Each cell is a ColorSwatch tile with the stop number and
  * hex printed over it (text color contrast-corrected via isLight), so the whole
  * palette is scannable in one grid.

package/src/organisms/ToolPalette.jsx

@@ -5,7 +5,7 @@ import SplitToolButton from '../molecules/SplitToolButton.jsx'
 import { Tooltip } from '../utilities/Popover.jsx'
 
 /**
- * ToolPalette — the editor's tool bar as one row (kol-fxr `shell/panels/ToolPalette.jsx`,
+ * ToolPalette — The editor's tool bar. 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