@kolkrabbi/kol-component 0.235.0 → 0.237.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.235.0",
+  "version": "0.237.0",
   "description": "The core component library",
   "license": "MIT",
   "type": "module",
@@ -25,8 +25,8 @@
     "embla-carousel-react": "^8.6.0",
     "pdfjs-dist": "^6.3.289",
     "react-syntax-highlighter": "^16.1.1",
-    "@kolkrabbi/kol-markdown": "^0.1.2",
-    "@kolkrabbi/kol-search": "^0.2.0"
+    "@kolkrabbi/kol-search": "^0.3.0",
+    "@kolkrabbi/kol-markdown": "^0.1.2"
   },
   "peerDependencies": {
     "@kolkrabbi/kol-icons": ">=0.22.0",
@@ -37,7 +37,7 @@
     "react-dom": "^18.3.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-icons": "^0.32.0"
+    "@kolkrabbi/kol-icons": "^0.33.0"
   },
   "files": [
     "src",

package/src/atoms/Button.jsx

@@ -1,5 +1,5 @@
 import { isValidElement } from 'react'
-import { toneClass } from '../utilities/tone.js'
+import { toneClass, VARIANT_TONE } from '../utilities/tone.js'
 import { Icon } from '@kolkrabbi/kol-icons'
 import { glyphSize } from '../hooks/glyphLadders.js'
 
@@ -12,7 +12,7 @@ import { glyphSize } from '../hooks/glyphLadders.js'
  *
  * @param {Object} props
  * @param {ReactNode} props.children - Button content
- * @param {'primary'|'secondary'|'accent'|'outline'|'ghost'|'nav'|'danger'|'grey'|'control'} props.variant - Visual variant. UNSET (the default) inherits the tone of the nearest `kol-tone-*` wrapper, else renders primary; the five ground variants are aliases of `tone`. `danger` is the destructive treatment (--ui-error fill); `nav` is the chrome rung — transparent, oq-64 ink, one step brighter than `ghost`; `control` is an alias for `ghost` (legacy call-sites).
+ * @param {'accent'|'danger'|'nav'} props.variant - The intent; the GROUND is `tone`. `primary · secondary · outline · ghost · grey · control` are deprecated aliases of tones (2026-10-01, on the retirement ledger): pass `tone` — `secondary` is `tone="inverted"`, `control` is `tone="ghost"`, the rest keep their name. Visual variant. UNSET (the default) inherits the tone of the nearest `kol-tone-*` wrapper, else renders primary; the five ground variants are aliases of `tone`. `danger` is the destructive treatment (--ui-error fill); `nav` is the chrome rung — transparent, oq-64 ink, one step brighter than `ghost`; `control` is an alias for `ghost` (legacy call-sites).
  * @param {'xs'|'sm'|'md'|'lg'} props.size - Button size (default: 'md'); xs is the panel rung (ControlsXsRung, 2026-09-01) — kol-mono-8 in a 22px shell (20 icon-only), opt-in by prop
  * @param {string} props.iconLeft - Icon name to display on the left
  * @param {string} props.iconRight - Icon name to display on the right
@@ -36,6 +36,8 @@ import { glyphSize } from '../hooks/glyphLadders.js'
  * @param {ElementType|ReactNode} props.iconComponent - Icon renderer seam — a component that receives `{ name, size, className, style }` in place of the DS Icon (custom icon registries plug in here), or a pre-rendered node dropped in verbatim where the glyph would go. Defaults to DS Icon.
  * @param {boolean} props.pressed - Toggle state — sets `aria-pressed` (true/false) and `kol-btn-pressed`; a `quiet` button drops its dimming while pressed. Leave undefined for non-toggle buttons.
  */
+const warned = new Set()
+
 const Button = ({
   children,
   variant,
@@ -85,6 +87,12 @@ const Button = ({
    * `kol-btn-secondary` (the text color as fill) until 2026-09-29, so a misspelt variant
    * shipped inverted. It now stamps nothing, like an unset variant: the wrapper's tone,
    * else primary — and says so in dev. */
+  /* the six tone-duplicates still render exactly as they did — an alias gains nothing and loses
+   * nothing — and say once in dev what replaces them */
+  if (import.meta.env.DEV && VARIANT_TONE[variant] && !warned.has(variant)) {
+    warned.add(variant)
+    console.warn(`Button: variant="${variant}" is deprecated — use tone="${VARIANT_TONE[variant]}"`)
+  }
   const KNOWN = ['primary', 'secondary', 'accent', 'outline', 'ghost', 'nav', 'danger', 'grey']
   const known = !resolvedVariant || KNOWN.includes(resolvedVariant)
   if (!known && import.meta.env.DEV) console.warn(`Button: unknown variant "${resolvedVariant}" — rendering the inherited tone (primary)`)

package/src/atoms/Kbd.jsx

@@ -1,7 +1,7 @@
 /**
  * Kbd — A key cap for a shortcut. 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
+ * the search modal 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.
@@ -10,7 +10,9 @@
  *                          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
+ *                          is a GLYPH, never a typed character in the mono face.
+ *                          It follows the cap: 10 in `sm`, 12 in `md` (2026-10-02 —
+ *                          it was 12 in both, so in the small ⌘K cap the ⌘ outgrew the K)
  */
 import { Icon } from '@kolkrabbi/kol-icons'
 
@@ -18,6 +20,7 @@ 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',
 }
+const GLYPH = { sm: 10, md: 12 }
 
 export default function Kbd({ size = 'md', icon, className = '', children, ...rest }) {
   return (
@@ -26,7 +29,7 @@ export default function Kbd({ size = 'md', icon, className = '', children, ...re
       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} />}
+      {icon && <Icon name={icon} size={GLYPH[size] ?? GLYPH.md} />}
       {children}
     </kbd>
   )

package/src/index.js

@@ -23,7 +23,7 @@ export { default as Avatar } from './atoms/Avatar.jsx'
 export { default as Badge } from './atoms/Badge.jsx'
 export { default as Button } from './atoms/Button.jsx'
 export { default as CloseButton } from './atoms/CloseButton.jsx'
-export { default as ActionButton } from './atoms/ActionButton.jsx'
+export { default as ActionButton } from './molecules/ActionButton.jsx'
 export { default as FileIcon } from './atoms/FileIcon.jsx'
 export { default as SizeOrDownload } from './atoms/SizeOrDownload.jsx'
 export { default as SortHeader } from './atoms/SortHeader.jsx'
@@ -38,21 +38,22 @@ export { default as IconFrame } from './atoms/IconFrame.jsx'
 export { default as ExitPreview } from './utilities/ExitPreview.jsx'
 export { default as Figure } from './atoms/Figure.jsx'
 export { default as FullscreenOverlay } from './utilities/FullscreenOverlay.jsx'
-export { default as HlsVideo } from './atoms/HlsVideo.jsx'
-/* AudioPlayer — HlsVideo's opposite number: same tier and shape, inverted
- * intent (built to be operated, not decorative). See its header before editing
- * either one. */
-export { default as AudioPlayer } from './atoms/AudioPlayer.jsx'
+/* BackgroundVideo — renamed from HlsVideo and moved to utilities 2026-10-01 (user ruling: no UI,
+ * and the name said how it streams, not what it is for). `HlsVideo` is the alias, on the ledger. */
+export { default as BackgroundVideo, default as HlsVideo } from './utilities/BackgroundVideo.jsx'
 export { default as Input } from './atoms/Input.jsx'
 export { default as Label } from './atoms/Label.jsx'
 export { default as LabeledControl } from './molecules/LabeledControl.jsx'
 export { default as OverlayGlassPanel } from './utilities/OverlayGlassPanel.jsx'
 export { default as Pill } from './atoms/Pill.jsx'
 export { usePopover, PopoverPanel, Tooltip } from './utilities/Popover.jsx'
+/* armLongPress — the touch hold the panel value controls report (moved from kol-hardware 2026-10-01) */
+export { armLongPress } from './utilities/armLongPress.js'
 export { default as ContextMenu, useContextMenu } from './molecules/ContextMenu.jsx'
 export { default as ProsePreview } from './utilities/ProsePreview.jsx'
 export { default as QuantityInput } from './molecules/QuantityInput.jsx'
-export { default as RotaryDial } from './atoms/RotaryDial.jsx'
+/* Knob — the survivor's name (2026-10-02): `variant` dial · panel. `RotaryDial` is the alias, on the ledger. */
+export { default as Knob, default as RotaryDial } from './molecules/Knob.jsx'
 export { default as SearchInput } from './molecules/SearchInput.jsx'
 export { default as InspectorSection, default as Section } from './molecules/InspectorSection.jsx'
 export { default as SectionText } from './molecules/SectionText.jsx'
@@ -96,8 +97,10 @@ export { default as SectionCardItem, default as CardFeatureItem } from './molecu
 export { default as CodeBlock } from './molecules/CodeBlock.jsx'
 export { default as ColorInputRow } from './molecules/ColorInputRow.jsx'
 export { default as ColorRamp } from './molecules/ColorRamp.jsx'
-export { default as ColorSwatch } from './atoms/ColorSwatch.jsx'
+export { default as ColorSwatch } from './molecules/ColorSwatch.jsx'
 export { default as Dropdown } from './molecules/Dropdown.jsx'
+/* MultiSelect — several pick-one settings in one dropdown, a column each (2026-10-01, first cut) */
+export { default as MultiSelect } from './molecules/MultiSelect.jsx'
 export { default as FieldRow, StatusChip } from './molecules/FieldRow.jsx'
 export { default as FramedMediaBand } from './organisms/FramedMediaBand.jsx'
 export { default as Image } from './atoms/Image.jsx'
@@ -128,6 +131,8 @@ export { default as ToolPalette } from './organisms/ToolPalette.jsx'
 export { default as DocumentEditor } from './organisms/DocumentEditor.jsx'
 export { default as SwatchControls, SwatchStack, EyedropPick } from './molecules/SwatchControls.jsx'
 export { default as TabsRow } from './molecules/TabsRow.jsx'
+/* TabChips — tabs as chips, for inside a toolbar (2026-10-01; was the showcase's local DocTabs) */
+export { default as TabChips } from './molecules/TabChips.jsx'
 
 // organisms
 /* monorepo sets (P6–P10) — organism members. Foundry members live in the
@@ -183,10 +188,11 @@ export { default as SectionNewsletter } from './organisms/SectionNewsletter.jsx'
 export { default as NewsletterBand } from './organisms/NewsletterBand.jsx'
 export { default as ColumnBrowser } from './organisms/ColumnBrowser.jsx'
 export { default as KindPreview } from './molecules/KindPreview.jsx'
-export { default as AudioPreview, AudioTile, VideoTile, formatLength } from './molecules/AudioPreview.jsx'
-export { default as VideoSheet } from './molecules/VideoSheet.jsx'
+/* MediaPlayer — the one player (2026-10-02): `variant` video · audio, `frame` for the Quick Look
+ * window. VideoSheet · AudioSheet · AudioPreview · AudioPlayer are its aliases, on the ledger. */
+export { default as MediaPlayer, VideoSheet, AudioSheet, AudioPreview, AudioPlayer } from './molecules/MediaPlayer.jsx'
+export { AudioTile, VideoTile, formatLength } from './molecules/PlayTile.jsx'
 export { default as PlaybackBar } from './molecules/PlaybackBar.jsx'
-export { default as AudioSheet } from './molecules/AudioSheet.jsx'
 export { default as QuickLookFrame } from './molecules/QuickLookFrame.jsx'
 export { default as MediaTile } from './molecules/MediaTile.jsx'
 export { default as RowMenuButton } from './molecules/RowMenuButton.jsx'

package/src/molecules/ColorInputRow.jsx

@@ -1,6 +1,6 @@
 import { useState } from 'react'
 import { Icon } from '@kolkrabbi/kol-icons'
-import ColorSwatch from '../atoms/ColorSwatch'
+import ColorSwatch from './ColorSwatch.jsx'
 import Input from '../atoms/Input'
 import { usePopover, PopoverPanel, Tooltip } from '../utilities/Popover'
 

package/src/molecules/ColorRamp.jsx

@@ -1,5 +1,5 @@
 import { useEffect, useState } from 'react'
-import ColorSwatch from '../atoms/ColorSwatch.jsx'
+import ColorSwatch from './ColorSwatch.jsx'
 import { resolveCssVar, isLight } from '../hooks/cssVar.js'
 
 /**

package/src/molecules/CopyButton.jsx

@@ -1,4 +1,4 @@
-import ActionButton from '../atoms/ActionButton.jsx'
+import ActionButton from './ActionButton.jsx'
 
 /**
  * CopyButton — Copy text to the clipboard. THE copy-to-clipboard control (2026-08-09 user ruling): the

package/src/molecules/Dropdown.jsx

@@ -163,7 +163,9 @@ const Dropdown = ({
   /* `{ divider: true }` in `options` draws a hairline between groups (FoundationsTones, 2026-09-26 —
    * user: none on top, the filled tones in order, outline and ghost apart). It is never a choice:
    * the lookup, the fallback and the trigger's width all read the choices only. */
-  const choices = options.filter((opt) => !opt?.divider)
+  /* `{ heading: 'Variant' }` names the list (2026-10-01 — user: "first item 'variant' then divider
+   * then the list"): a row that says what the dropdown sets, never a choice. */
+  const choices = options.filter((opt) => !opt?.divider && !opt?.heading)
   const currentOption = choices.find((opt) => opt.value === value) || choices[0]
 
   /* A clamped list (Popover caps the panel to the viewport) can open with the
@@ -172,7 +174,7 @@ const Dropdown = ({
   const listRef = useRef(null)
   useEffect(() => {
     if (!isOpen) return
-    const idx = options.findIndex((opt) => !opt?.divider && opt.value === currentOption?.value)
+    const idx = options.findIndex((opt) => !opt?.divider && !opt?.heading && opt.value === currentOption?.value)
     listRef.current?.children[idx]?.scrollIntoView({ block: 'nearest' })
   }, [isOpen]) // eslint-disable-line react-hooks/exhaustive-deps
 
@@ -253,6 +255,7 @@ const Dropdown = ({
         <div ref={listRef} className="kol-dd-list" role="listbox">
           {options.map((option, i) => {
             if (option?.divider) return <MenuDropdownDivider key={`divider-${i}`} />
+            if (option?.heading) return <div key={`heading-${i}`} className={`${resolvedSize === 'xs' ? 'kol-mono-8 px-2 h-5' : 'kol-helper-12 px-3 h-8'} flex shrink-0 items-center text-meta`}>{option.heading}</div>
             const isActive = option.value === currentOption?.value
             return (
               <MenuDropdownItem

package/src/molecules/KindPreview.jsx

@@ -1,6 +1,6 @@
 import { useEffect, useState } from 'react'
-import { AudioTile, VideoTile } from './AudioPreview.jsx'
-import HlsVideo from '../atoms/HlsVideo.jsx'
+import { AudioTile, VideoTile } from './PlayTile.jsx'
+import BackgroundVideo from '../utilities/BackgroundVideo.jsx'
 import CodeBlock from './CodeBlock.jsx'
 import AssetPlaceholder from '../utilities/AssetPlaceholder.jsx'
 import FileIcon from '../atoms/FileIcon.jsx'
@@ -16,11 +16,11 @@ import DocPage from './DocPage.jsx'
  * KindPreview — A preview for any kind of file. a preview for any kind of file: kol-r2b2's `KindPreview.jsx`,
  * promoted 2026-08-27 (SettingsPanelChromeAndColumnPreview). Before it, anything
  * that was not an image or a video showed a grey box with the word "text".
- * HLS → `HlsVideo` (inert — the DS's background-video atom, preview only),
+ * HLS → `BackgroundVideo` (inert — the DS's background-video atom, preview only),
  * video → `VideoTile` and audio → `AudioTile` (ColumnBrowserMediaFacts
  * 2026-08-27 — the square column tile with one play/pause control; no Figure, no
  * border — `VideoBlock`'s Figure border is why kol-r2b2 bypassed it; the overlay
- * player is `AudioPreview`), markdown → rendered prose in `.kol-prose`
+ * player is `MediaPlayer`), markdown → rendered prose in `.kol-prose`
  * (markdownToHtml, KindPreviewMarkdown 2026-08-27), json / yaml / text / code →
  * `CodeBlock` (language by kind or extension) — every document on ONE plate,
  * `DocPage` (DocPageAndKindShowcase 2026-08-27: the overlay's A-series page, the
@@ -171,10 +171,10 @@ export default function KindPreview({
 
   if (kind === 'playlist') {
     /* the caption is pane chrome — in a tile it is a line of prose over the picture */
-    if (fit !== 'pane') return <HlsVideo src={url} poster={poster} className="w-full h-full object-cover" />
+    if (fit !== 'pane') return <BackgroundVideo src={url} poster={poster} className="w-full h-full object-cover" />
     return (
       <div className="flex flex-col items-center gap-2">
-        <HlsVideo src={url} poster={poster} className="max-w-full max-h-[70vh] rounded" />
+        <BackgroundVideo src={url} poster={poster} className="max-w-full max-h-[70vh] rounded" />
         <span className="kol-mono-12 text-meta">HLS stream · playback is preview-only, no controls</span>
       </div>
     )

package/src/{atoms/RotaryDial.jsx → molecules/Knob.jsx}

@@ -1,4 +1,5 @@
 import { useEffect, useRef, useState } from 'react'
+import KnobPanel from './KnobPanel.jsx'
 
 /** Clamp to min–max, snapped to the nearest step from min. */
 const snapTo = (v, min, max, step) => {
@@ -7,12 +8,17 @@ const snapTo = (v, min, max, step) => {
 }
 
 /**
- * RotaryDial — drag-to-set rotary knob numeric input. The KNOB VARIANT of
+ * Knob — drag-to-set rotary knob numeric input. The ROTARY TWIN of
  * Slider (molecules/Slider.jsx): both implement the shared value-control
  * contract — `value` / `min` / `max` / `step` / `onChange(next: number)` /
  * `label` / `size` / `disabled` / `formatValue`. Controlled; onChange always
  * fires with the plain number.
  *
+ * ONE KNOB, TWO VARIANTS (user ruling 2026-10-02: *"knob being the more simple form, rotary dial
+ * being more of a variant"*). It was `RotaryDial` with kol-hardware's `Knob` wrapped over it; the
+ * name is `Knob` now, `dial` is the ring-and-disc drawing that name used to mean, and `RotaryDial`
+ * is the alias on the retirement ledger.
+ *
  * Vertical pointer drag rotates the whole dial over a 270° sweep (−135° to
  * +135°) mapped onto min–max; a full sweep is ~200px of drag, movement
  * measured absolute from drag start. A local visual buffer keeps rotation
@@ -30,9 +36,12 @@ const snapTo = (v, min, max, step) => {
  * @param {number}   size        dial px size (default 80); derives ring + disc radii
  * @param {boolean}  disabled    blocks drag + keyboard and dims the control (default false)
  * @param {Function} formatValue optional readout formatter (value: number) => string; default `${value}%`
+ * @param {'dial'|'panel'} variant  `dial` (default) = the ring and disc · `panel` = the rack knob (kol-hardware's, merged 2026-10-01): a cap in the hardware colors;
+ *                            there `size` is `sm · md · lg · xl` (24 · 32 · 40 · 64) and it also takes `labelPlacement`
+ *                            (`column · row · row-left · row-right`), `bipolar`, `labelMinWidth` and `onHold`
  * @param {number}   defaultValue alt-click the dial resets to this (falls back to `min`) — Slider carries the same gesture
  */
-export default function RotaryDial({
+export default function Knob({
   label,
   value = 0,
   onChange,
@@ -43,6 +52,11 @@ export default function RotaryDial({
   disabled = false,
   formatValue,
   defaultValue,
+  variant = 'dial',
+  labelPlacement,
+  bipolar,
+  labelMinWidth,
+  onHold,
 }) {
   const [isDragging, setIsDragging] = useState(false)
   const [localValue, setLocalValue] = useState(value) // visual buffer — updates every move
@@ -119,6 +133,10 @@ export default function RotaryDial({
     handlePointerDown(e)
   }
 
+  if (variant === 'panel') {
+    return <KnobPanel value={value} onChange={onChange} min={bipolar && min === 0 ? undefined : min} max={max} label={label} variant={labelPlacement} bipolar={bipolar} labelMinWidth={labelMinWidth} size={typeof size === 'string' ? size : undefined} defaultValue={defaultValue} onHold={onHold} />
+  }
+
   const outerRadius = size / 2
   const innerRadius = (size * 0.7) / 2
   const strokeWidth = 2

package/src/molecules/KnobPanel.jsx

@@ -0,0 +1,116 @@
+import { useCallback } from 'react'
+import { armLongPress } from '../utilities/armLongPress.js'
+
+const NO_HOLD = { move() {}, cancel() {} }
+
+const SIZES = { sm: 24, md: 32, lg: 40, xl: 64 }
+
+/**
+ * KnobPanel — Knob's `variant="panel"`: the rack knob. A cap and a pointer line in the
+ * hardware cap colors, sized 24 · 32 · 40 · 64 by name, with the four label placements and the
+ * bipolar legend. It was kol-hardware's own `Knob` (kol-monitor's rack, lifted 2026-09-01) and is
+ * carried here class for class — merged in 2026-10-01 (user ruling). Not exported:
+ * reach it through `<Knob variant="panel">`.
+ */
+export default function KnobPanel({ value, onChange, min, max, label, variant = 'column', bipolar = false, labelMinWidth, size: sizeProp = 'sm', defaultValue, onHold }) {
+  const size = SIZES[sizeProp] || SIZES.sm
+  const effMin = min ?? (bipolar ? -100 : 0)
+  const effMax = max ?? 100
+  const effDefault = defaultValue ?? (bipolar ? 0 : 50)
+  const angle = ((value - effMin) / (effMax - effMin)) * 270 - 135
+  const r = size / 2
+  const ir = r * 0.56
+
+  const handlePointerDown = useCallback((e) => {
+    e.preventDefault()
+    // Alt/Option + click resets to default instead of starting a drag
+    if (e.altKey) {
+      onChange(effDefault)
+      return
+    }
+    const startY = e.clientY
+    const startVal = value
+    const range = effMax - effMin
+
+    const id = e.pointerId
+    const handleMove = (e) => {
+      if (e.pointerId !== id) return  // a second finger is a pan, not this knob
+      hold.move(e)
+      const delta = (startY - e.clientY) * (range / 200)
+      const next = Math.round(Math.max(effMin, Math.min(effMax, startVal + delta)))
+      onChange(next)
+    }
+    const handleUp = () => {
+      hold.cancel()
+      window.removeEventListener('pointermove', handleMove)
+      window.removeEventListener('pointerup', handleUp)
+    }
+    // Touch: hold still 500ms → the holder's sheet instead of the drag
+    const hold = onHold ? armLongPress(e, () => { handleUp(); onHold({ label, value, min: effMin, max: effMax, defaultValue: effDefault }) }) : NO_HOLD
+    window.addEventListener('pointermove', handleMove)
+    window.addEventListener('pointerup', handleUp)
+  }, [value, effMin, effMax, effDefault, onChange, onHold, label])
+
+  const knobSvg = (
+    <svg width={size} height={size} viewBox={`0 0 ${size} ${size}`}>
+      <circle cx={r} cy={r} r={r * 0.75} style={{ fill: 'var(--kol-ctl-hw-cap)', stroke: 'var(--kol-fg-24)' }} strokeWidth="1" />
+      <line
+        x1={r} y1={r}
+        x2={r + ir * Math.cos((angle - 90) * Math.PI / 180)}
+        y2={r + ir * Math.sin((angle - 90) * Math.PI / 180)}
+        style={{ stroke: 'var(--kol-ctl-hw-on-cap)' }} strokeWidth="1.5" strokeLinecap="round"
+      />
+    </svg>
+  )
+
+  if (variant === 'row-left' || variant === 'row') {
+    return (
+      <div
+        onPointerDown={handlePointerDown}
+        style={{ cursor: 'ns-resize', touchAction: 'none', display: 'flex', alignItems: 'center', gap: 4 }}
+      >
+        {label && (
+          <span className="kol-helper-8 text-fg-32" style={{ textTransform: 'uppercase', lineHeight: 1 }}>
+            {label}
+          </span>
+        )}
+        {knobSvg}
+      </div>
+    )
+  }
+
+  if (variant === 'row-right') {
+    return (
+      <div
+        onPointerDown={handlePointerDown}
+        style={{ cursor: 'ns-resize', touchAction: 'none', display: 'flex', alignItems: 'center', gap: 4 }}
+      >
+        {knobSvg}
+        {label && (
+          <span className="kol-helper-8 text-fg-32" style={{ textTransform: 'uppercase', lineHeight: 1, minWidth: labelMinWidth }}>
+            {label}
+          </span>
+        )}
+      </div>
+    )
+  }
+
+  return (
+    <div
+      onPointerDown={handlePointerDown}
+      style={{ cursor: 'ns-resize', touchAction: 'none', display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 2 }}
+    >
+      {bipolar && (
+        <span className="kol-helper-8 text-fg-32" style={{ lineHeight: 1 }}>
+          -/+
+        </span>
+      )}
+      {knobSvg}
+      {label && (
+        <span className="kol-helper-8 text-fg-32" style={{ textTransform: 'uppercase', lineHeight: 1 }}>
+          {label}
+        </span>
+      )}
+    </div>
+  )
+}

package/src/molecules/LabeledControl.jsx

@@ -23,6 +23,9 @@
  *            kol-monitor 2026-09-01 — in a narrow multi-column grid a fixed
  *            160 label left the control 4px, and a nowrap combo painted into
  *            the neighbour column; the 48px column gap had been hiding it).
+ *   variant — `'panel'` is the hardware panel label (was kol-hardware `PanelLabel`, merged
+ *            2026-10-01): `kol-helper-8`, uppercase, hugging the control; it takes
+ *            `labelPosition` (`top · bottom · left · right`, default bottom), `labelClass` and `gap`.
  *   children — the control body.
  *   className — additional classes on the wrapper.
  */
@@ -33,7 +36,26 @@ export default function LabeledControl({
   labelWidth = 48,
   children,
   className = '',
+  variant,
+  labelPosition = 'bottom',
+  labelClass = 'kol-helper-8',
+  gap = 0,
 }) {
+  if (variant === 'panel') {
+    const isRow = labelPosition === 'left' || labelPosition === 'right'
+    const labelEl = label && (
+      <span className={`${labelClass} text-fg-32`} style={{ textTransform: 'uppercase', lineHeight: 1 }}>
+        {label}
+      </span>
+    )
+    return (
+      <div style={{ display: 'inline-flex', flexDirection: isRow ? 'row' : 'column', alignItems: 'center', gap }}>
+        {(labelPosition === 'top' || labelPosition === 'left') && labelEl}
+        {children}
+        {(labelPosition === 'bottom' || labelPosition === 'right') && labelEl}
+      </div>
+    )
+  }
   const showLabel  = !!label
   const labelInner = (
     <>

package/src/molecules/MediaPlayer.jsx

@@ -0,0 +1,107 @@
+import usePlayback from '../hooks/usePlayback.js'
+import PlaybackBar, { clock } from './PlaybackBar.jsx'
+import QuickLookFrame from './QuickLookFrame.jsx'
+import FileIcon from '../atoms/FileIcon.jsx'
+import { useCover } from './PlayTile.jsx'
+
+/* taxonomy-ok: molecule — nests PlaybackBar + QuickLookFrame (relative) + FileIcon (atom). */
+
+/**
+ * MediaPlayer — Play a video or an audio file. the media, `PlaybackBar` and the `usePlayback` hook
+ * as ONE player (user ruling 2026-10-02: *"I was referring to the two players in the quicklook in
+ * media"*). It was four components — `VideoSheet` and `AudioSheet` (the Quick Look pair),
+ * `AudioPreview` (its own transport) and `AudioPlayer` (the browser's strip) — and each is an
+ * alias of this one now, on the retirement ledger.
+ *
+ * `variant` is what plays. `frame` is where: given, the player draws inside `QuickLookFrame` (the
+ * Quick Look window — the bar docked in its footer); absent, it plays inline (*"why would media
+ * player not just prop the window, its not called WINDOWmediaplayer"*).
+ *
+ *   video           the picture at its own ratio; click toggles play. Inline, the bar floats over
+ *                   its bottom edge (inset 16, radius 12)
+ *   audio           inline, the bar alone. In the window, Finder's layout: the artwork square (the
+ *                   file's embedded ID3 cover; none → `FileIcon`) beside `Time: mm:ss`
+ *
+ * No native controls, no autoplay (Quick Look opens paused), `playsInline`.
+ *
+ * @param {'video'|'audio'} variant  what plays (default `video`)
+ * @param {string}   src       the media URL
+ * @param {string}   poster    video — the poster URL
+ * @param {string}   ext       audio — the extension, for the no-cover icon
+ * @param {Function} onMeta    ({ w, h, len }) => void once metadata lands (audio reports `len` only)
+ * @param {Object}   frame     the window's header — `QuickLookFrame`'s title · meta · actions · onClose · nav · size
+ * @param {'none'|'metadata'|'auto'} preload  the native preload hint (default `metadata`)
+ * @param {string}   className inline only — the player's box (its width is the caller's)
+ */
+export default function MediaPlayer({ variant = 'video', src, poster, ext, onMeta, frame, preload = 'metadata', className = '' }) {
+  const audio = variant === 'audio'
+  const { ref, handlers, bar } = usePlayback((el) => onMeta?.(audio ? { len: el.duration } : { w: el.videoWidth, h: el.videoHeight, len: el.duration }))
+  const cover = useCover(audio && frame ? src : null)
+  const media = audio
+    ? <audio ref={ref} src={src} preload={preload} {...handlers} />
+    : <video ref={ref} src={src} poster={poster} playsInline preload={preload} className={frame ? 'kol-quicklook-media' : 'block w-full'} onClick={bar.onToggle} {...handlers} />
+
+  if (frame) {
+    return (
+      <QuickLookFrame {...frame} footer={<PlaybackBar {...bar} docked />}>
+        {media}
+        {audio && (
+          <div className="kol-quicklook-audio">
+            <div className="kol-quicklook-art">
+              {cover
+                ? <img src={cover} alt="" className="w-full h-full object-cover" />
+                : <FileIcon ext={ext} glyph="music-note" className="w-[52%]" />}
+            </div>
+            <span className="kol-mono-16 text-meta">Time: <b className="text-strong">{clock(bar.duration)}</b></span>
+          </div>
+        )}
+      </QuickLookFrame>
+    )
+  }
+
+  return (
+    <div className={`relative ${className}`.trim()}>
+      {media}
+      <PlaybackBar {...bar} docked={audio} />
+    </div>
+  )
+}
+
+/**
+ * @deprecated 2026-10-02 — use `<MediaPlayer variant="video" frame={…}>`. Drops when nobody imports it (04-retirements.md).
+ * VideoSheet — the video in the Quick Look window. Same props.
+ */
+export function VideoSheet({ frame, ...props }) {
+  return <MediaPlayer variant="video" frame={frame ?? {}} {...props} />
+}
+
+/**
+ * @deprecated 2026-10-02 — use `<MediaPlayer variant="audio" frame={…}>`; `onDuration(seconds)` is `onMeta({ len })`. Drops when nobody imports it (04-retirements.md).
+ * AudioSheet — audio in the Quick Look window.
+ */
+export function AudioSheet({ frame, onDuration, ...props }) {
+  return <MediaPlayer variant="audio" frame={frame ?? {}} onMeta={onDuration && ((m) => onDuration(m.len))} {...props} />
+}
+
+/**
+ * @deprecated 2026-10-02 — use `<MediaPlayer variant="audio">`; `onDuration(seconds)` is `onMeta({ len })`. Drops when nobody imports it (04-retirements.md).
+ * AudioPreview — the inline audio player. Its own transport is the `PlaybackBar` now.
+ */
+export function AudioPreview({ onDuration, ...props }) {
+  return <MediaPlayer variant="audio" onMeta={onDuration && ((m) => onDuration(m.len))} {...props} />
+}
+
+/**
+ * @deprecated 2026-10-02 — use `<MediaPlayer variant="audio">`. Drops when nobody imports it (04-retirements.md).
+ * AudioPlayer — the native audio strip with a label. The strip is the
+ * `PlaybackBar` now; the label is the caller's to draw.
+ */
+export function AudioPlayer({ src, label, preload, className = '' }) {
+  if (!src) return null
+  return (
+    <figure className={`kol-audio-player flex flex-col gap-3 ${className}`.trim()}>
+      {label && <figcaption className="kol-mono-12 text-fg-48">{label}</figcaption>}
+      <MediaPlayer variant="audio" src={src} preload={preload} />
+    </figure>
+  )
+}

package/src/molecules/Modal.jsx

@@ -120,7 +120,7 @@ function ModalView({ state, closeWith }) {
         )}
         <div className="flex gap-2 justify-end">
           {state.kind !== 'alert' && <Button size="sm" onClick={cancel}>{state.cancelLabel ?? 'Cancel'}</Button>}
-          <Button variant="primary"   size="sm" onClick={submit}>{state.okLabel ?? 'OK'}</Button>
+          <Button tone="primary"   size="sm" onClick={submit}>{state.okLabel ?? 'OK'}</Button>
         </div>
       </div>
     </div>