@kolkrabbi/kol-component 0.112.0 → 0.114.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.112.0",
+  "version": "0.114.0",
   "description": "KOL design-system components — atoms through organisms, emitting canonical kol-* classes. Pairs with @kolkrabbi/kol-theme for styling.",
   "license": "MIT",
   "type": "module",
@@ -12,6 +12,8 @@
     "./molecules/*": "./src/molecules/*.jsx",
     "./organisms/*": "./src/organisms/*.jsx",
     "./utilities/*": "./src/utilities/*.jsx",
+    "./utilities/id3": "./src/utilities/id3.js",
+    "./utilities/frontmatter": "./src/utilities/frontmatter.js",
     "./hooks/*": "./src/hooks/*.js"
   },
   "dependencies": {
@@ -30,7 +32,7 @@
     "react-router-dom": "^6.0.0 || ^7.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-icons": "^0.22.0"
+    "@kolkrabbi/kol-icons": "^0.23.0"
   },
   "files": [
     "src",

package/src/hooks/usePlayback.js

@@ -0,0 +1,38 @@
+import { useRef, useState } from 'react'
+
+/**
+ * usePlayback — ONE media element's playback state for a PlaybackBar
+ * (PlaybackBarAndAudioSheet, kol-r2b2 2026-08-27, promoted verbatim). The sheet
+ * spreads `handlers` on its <audio> / <video> and hands `bar` to the bar; the
+ * bar never touches the element (the React-compiler lint forbids mutating a
+ * ref passed as a prop, and a presentational bar should not know one exists).
+ *
+ * @param {Function} onLoaded  (element) => void once metadata lands
+ * @returns {{ ref, handlers, bar }} — `bar` = { playing, time, duration, rate, onToggle, onSeek, onVolume, onRate }
+ */
+export default function usePlayback(onLoaded) {
+  const ref = useRef(null)
+  const [playing, setPlaying] = useState(false)
+  const [time, setTime] = useState(0)
+  const [duration, setDuration] = useState(0)
+  const [rate, setRate] = useState(1)
+  const handlers = {
+    onPlay: () => setPlaying(true),
+    onPause: () => setPlaying(false),
+    onEnded: () => setPlaying(false),
+    onTimeUpdate: (e) => setTime(e.target.currentTime),
+    onLoadedMetadata: (e) => { setDuration(e.target.duration); onLoaded?.(e.target) },
+  }
+  const bar = {
+    playing,
+    time,
+    duration,
+    rate,
+    onToggle: () => (playing ? ref.current.pause() : ref.current.play()),
+    onSeek: (t) => { const v = Math.max(0, Math.min(duration || 0, t)); ref.current.currentTime = v; setTime(v) },
+    onVolume: (v) => { ref.current.volume = v },
+    /* the bar's `>>` — 1 → 1.5 → 2 → 1 */
+    onRate: (r) => { ref.current.playbackRate = r; setRate(r) },
+  }
+  return { ref, handlers, bar }
+}

package/src/hooks/useTilt.js

@@ -13,19 +13,36 @@ import { useMotionValue, useSpring, useTransform } from 'framer-motion'
  *
  * Defaults are the design: tilt ±4°, spring 350/35, perspective 700,
  * rest position center (0.5/0.5).
+ *
+ * `grounded` (ShelfCardTiltWrapsCard, kol-website 2026-08-27 — lifted out of
+ * TiltCardInner so the shelf and the card share ONE feel, no new component):
+ * the "planted at the bottom" tilt — targets snapped to 3 zones, rescaled to
+ * ±2.5°, chased by a lazy spring (250/25/0.6), rotateX clamped to min(0, …) so
+ * it only ever tilts back, pivoting about `center bottom`.
  */
 export default function useTilt({
   magnitude = 4,
   perspective = 700,
   stiffness = 350,
   damping = 35,
+  grounded = false,
 } = {}) {
   const ref = useRef(null)
   const mouseX = useMotionValue(0.5)
   const mouseY = useMotionValue(0.5)
 
-  const rotateX = useSpring(useTransform(mouseY, [0, 1], [magnitude, -magnitude]), { stiffness, damping })
-  const rotateY = useSpring(useTransform(mouseX, [0, 1], [-magnitude, magnitude]), { stiffness, damping })
+  const springX = useSpring(useTransform(mouseY, [0, 1], [magnitude, -magnitude]), { stiffness, damping })
+  const springY = useSpring(useTransform(mouseX, [0, 1], [-magnitude, magnitude]), { stiffness, damping })
+
+  /* the grounded springs always exist (hooks are unconditional) and are only
+   * SELECTED when asked for — a free tilt pays two idle springs, nothing more */
+  const zones = 3
+  const snap = (v) => Math.round(v * zones) / zones
+  const lazy = { stiffness: 250, damping: 25, mass: 0.6 }
+  const lazyX = useSpring(useTransform(springX, (v) => Math.min(0, snap(-v / magnitude) * 2.5)), lazy)
+  const lazyY = useSpring(useTransform(springY, (v) => snap(v / magnitude) * 2.5), lazy)
+  const rotateX = grounded ? lazyX : springX
+  const rotateY = grounded ? lazyY : springY
 
   const onMouseMove = (e) => {
     const rect = ref.current?.getBoundingClientRect()
@@ -41,7 +58,13 @@ export default function useTilt({
 
   return {
     ref,
-    style: { rotateX, rotateY, transformStyle: 'preserve-3d', transformPerspective: perspective },
+    style: {
+      rotateX,
+      rotateY,
+      transformStyle: 'preserve-3d',
+      transformPerspective: perspective,
+      ...(grounded ? { transformOrigin: 'center bottom' } : null),
+    },
     onMouseMove,
     onMouseLeave,
     motionValues: { mouseX, mouseY, rotateX, rotateY },

package/src/index.js

@@ -144,6 +144,11 @@ 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'
+export { default as PlaybackBar } from './molecules/PlaybackBar.jsx'
+export { default as AudioSheet } from './molecules/AudioSheet.jsx'
+export { default as DocPage } from './molecules/DocPage.jsx'
+export { default as DocFrontmatter } from './molecules/DocFrontmatter.jsx'
+export { parseFrontmatter } from './utilities/frontmatter.js'
 export { readCover } from './utilities/id3.js'
 export { kindOf, extOf, isSystemFile, KINDS, KIND_LABEL } from './utilities/mediaKinds.js'
 export { default as markdownToHtml, inlineToHtml } from './utilities/markdownToHtml.js'
@@ -171,6 +176,7 @@ export { default as usePrefersReducedMotion } from './hooks/usePrefersReducedMot
 export { default as useReveal } from './hooks/useReveal.js'
 export { default as useScrollSpy } from './hooks/useScrollSpy.js'
 export { default as useTilt } from './hooks/useTilt.js'
+export { default as usePlayback } from './hooks/usePlayback.js'
 export { default as useCoarsePointer } from './hooks/useCoarsePointer.js'
 export { default as useAxisAnimation } from './hooks/useAxisAnimation.js'
 export { useEyedropper, pickFromCanvasElement } from './hooks/useEyedropper.js'

package/src/molecules/AudioSheet.jsx

@@ -0,0 +1,62 @@
+import { useEffect, useState } from 'react'
+import { Icon } from '@kolkrabbi/kol-icons'
+import usePlayback from '../hooks/usePlayback.js'
+import PlaybackBar, { clock } from './PlaybackBar.jsx'
+import { readCover } from '../utilities/id3.js'
+
+/* taxonomy-ok: molecule — nests PlaybackBar (relative) + kol-icons' Icon. */
+
+function useCover(src) {
+  const [cover, setCover] = useState(null)
+  useEffect(() => {
+    let live = true
+    readCover(src).then((url) => { if (live) setCover(url) }).catch(() => {})
+    return () => { live = false }
+  }, [src])
+  return cover
+}
+
+/**
+ * AudioSheet — audio in the overlay, ruled against the QuickTime audio reference
+ * (PlaybackBarAndAudioSheet, kol-r2b2 2026-08-27), two variants:
+ *
+ *   cover  the same as VideoSheet — the artwork is the frame (`w-[min(78vh,100vw_-_10rem)]`,
+ *          square), the bar floating over its bottom edge (inset 16, radius 12)
+ *   sheet  the QuickTime window — a dark plate (`bg-fg-absolute-88`, `min(100vw − 10rem, 1000px)`),
+ *          the cover square left, `Time: mm:ss` beside it, the bar flush along the bottom
+ *
+ * Artwork = the file's embedded ID3 `APIC` cover (`readCover`); no cover → a light
+ * square carrying the `music-note` glyph, the reference's. `autoPlay`; `onDuration`
+ * for the overlay's facts. The `10rem` in the widths is the overlay's arrow gutter.
+ *
+ * @param {string}   src         the audio URL
+ * @param {Function} onDuration  (seconds) => void once metadata lands
+ * @param {'cover'|'sheet'} variant
+ */
+export default function AudioSheet({ src, onDuration, variant = 'cover' }) {
+  const { ref, handlers, bar } = usePlayback((el) => onDuration?.(el.duration))
+  const cover = useCover(src)
+  const audio = <audio ref={ref} src={src} autoPlay preload="metadata" {...handlers} />
+  const art = cover
+    ? <img src={cover} alt="" className="w-full h-full object-cover" />
+    : <div className="w-full h-full flex items-center justify-center bg-absolute-white text-fg-absolute-32"><Icon name="music-note" size={64} /></div>
+
+  if (variant === 'sheet') return (
+    <div className="relative w-[min(100vw_-_10rem,1000px)] rounded overflow-hidden bg-fg-absolute-88">
+      {audio}
+      <div className="flex items-center gap-16 p-10 pb-24">
+        <div className="w-[min(50vh,380px)] aspect-square shrink-0 overflow-hidden">{art}</div>
+        <span className="kol-mono-16 text-absolute-white"><span className="opacity-48">Time: </span><b className="opacity-80">{clock(bar.duration)}</b></span>
+      </div>
+      <PlaybackBar {...bar} place="left-0 right-0 bottom-0" />
+    </div>
+  )
+
+  return (
+    <div className="relative max-w-full">
+      {audio}
+      <div className="w-[min(78vh,100vw_-_10rem)] aspect-square rounded overflow-hidden">{art}</div>
+      <PlaybackBar {...bar} place="left-4 right-4 bottom-4 rounded-xl" />
+    </div>
+  )
+}

package/src/molecules/DocFrontmatter.jsx

@@ -0,0 +1,88 @@
+import { Icon } from '@kolkrabbi/kol-icons'
+import Tag from '../atoms/Tag.jsx'
+
+/* taxonomy-ok: molecule — nests Tag (atom) + kol-icons' Icon. */
+
+/* the workshop's DocsFrontmatter, ported minus the cap/expand and tag mode
+ * (DocPageAndKindShowcase, kol-r2b2 2026-08-27): every field carries an icon and
+ * an AUTHORED label (the no-auto-casing law — the fallback humanises the key
+ * where the string is made), reading order is the kol-docs contract, `related`
+ * and `aliases` are the deliberate omissions */
+const FIELD_ICONS = {
+  file: 'file', title: 'type', type: 'library', status: 'check', updated: 'refresh', created: 'plus',
+  verified: 'shield-check', description: 'message', audience: 'user', aliases: 'repeat', sources: 'code',
+  superseded_by: 'arrow-right', drift: 'alert-triangle', version: 'hash-01', tags: 'hash-02', id: 'hash-01',
+  reuses: 'repeat', slug: 'external-link', source: 'code', imported_from: 'arrow-right', type_styles: 'type',
+  classes: 'library', tokens: 'hash-01', composes: 'component-01', in_sets: 'grid', used_in: 'layers',
+  date: 'journal', category: 'folder', modified: 'edit',
+}
+const FIELD_LABELS = {
+  file: 'File', title: 'Title', type: 'Type', status: 'Status', updated: 'Updated', created: 'Created',
+  verified: 'Verified', description: 'Description', audience: 'Audience', aliases: 'Aliases', sources: 'Sources',
+  superseded_by: 'Superseded by', drift: 'Drift', version: 'Version', tags: 'Tags', source: 'Source',
+  imported_from: 'Imported from', type_styles: 'Type styles', classes: 'Classes', tokens: 'Tokens',
+  composes: 'Composes', in_sets: 'In sets', used_in: 'Used in', date: 'Date', category: 'Category', modified: 'Modified',
+}
+const FIELD_ORDER = [
+  'title', 'type', 'status', 'created', 'updated', 'tags', 'description', 'aliases', 'sources',
+  'verified', 'audience', 'superseded_by', 'drift', 'category', 'date', 'modified', 'version',
+]
+const HIDDEN = new Set(['related', 'aliases'])
+const CASED_VALUE_FIELDS = new Set(['type', 'status'])
+const DATE_FIELDS = new Set(['updated', 'created', 'verified', 'date', 'modified'])
+
+const humanise = (key) => {
+  const words = String(key).replace(/[-_]+/g, ' ').trim()
+  return words.charAt(0).toUpperCase() + words.slice(1)
+}
+const formatDate = (s) => {
+  const d = new Date(s)
+  if (isNaN(d)) return s
+  return d.toLocaleDateString('en-GB', { day: '2-digit', month: '2-digit', year: 'numeric' }).replace(/\//g, '.')
+}
+const orderFields = (metadata) => {
+  const present = Object.keys(metadata).filter(
+    (k) => !HIDDEN.has(k) && metadata[k] != null && metadata[k] !== '' && !(Array.isArray(metadata[k]) && metadata[k].length === 0),
+  )
+  const known = FIELD_ORDER.filter((k) => present.includes(k))
+  const rest = present.filter((k) => !FIELD_ORDER.includes(k)).sort()
+  return [...known, ...rest]
+}
+
+/**
+ * DocFrontmatter — the frontmatter block above a markdown document's prose: the
+ * `FRONTMATTER` eyebrow, icon + label keys, mono values, tags as `Tag` chips,
+ * arrays stacked, a hairline below. A member of `DocPage`.
+ *
+ * @param {Object} metadata  the parsed frontmatter (`parseFrontmatter`)
+ */
+export default function DocFrontmatter({ metadata }) {
+  const fields = metadata ? orderFields(metadata) : []
+  if (fields.length === 0) return null
+  return (
+    <div className="kol-doc-frontmatter border-b border-fg-08 pb-5 mb-6">
+      <div className="kol-doc-eyebrow mb-2">Frontmatter</div>
+      {fields.map((key) => {
+        const value = metadata[key]
+        const icon = FIELD_ICONS[key]
+        return (
+          <div key={key} className="flex items-baseline gap-4 py-1">
+            <span className="flex items-center gap-2 min-w-[120px] kol-helper-12 text-meta">
+              {icon && <Icon name={icon} size={14} />}
+              {FIELD_LABELS[key] ?? humanise(key)}
+            </span>
+            <span className="flex-1 min-w-0 [overflow-wrap:anywhere] kol-mono-12 text-strong">
+              {key === 'tags' && Array.isArray(value) ? (
+                <span className="flex flex-wrap gap-1.5">{value.map((tag) => <Tag key={tag}>{tag}</Tag>)}</span>
+              ) : DATE_FIELDS.has(key) ? formatDate(String(value))
+                : CASED_VALUE_FIELDS.has(key) ? humanise(String(value))
+                : Array.isArray(value) ? (
+                  <span className="flex flex-col gap-1">{value.map((item, i) => <span key={i} className="break-all">{String(item)}</span>)}</span>
+                ) : String(value)}
+            </span>
+          </div>
+        )
+      })}
+    </div>
+  )
+}

package/src/molecules/DocPage.jsx

@@ -0,0 +1,30 @@
+import DocFrontmatter from './DocFrontmatter.jsx'
+
+/* taxonomy-ok: molecule — nests DocFrontmatter (relative). */
+
+/**
+ * DocPage — ONE plate for every document (DocPageAndKindShowcase, kol-r2b2
+ * 2026-08-27, user ruling): markdown · text · code · JSON · YAML render on the
+ * same page. Where it sits decides its presentation, in kol-theme (≥0.75.0):
+ *
+ *   in `.kol-overlay`                 an A-series page — 85vh tall, 85vh / √2 wide,
+ *                                     `max-width: calc(100vw − 10rem)` (the arrow gutter),
+ *                                     `fg-04`, radius sm, padding 24, scrolls inside
+ *   in `.kol-column-browser-preview`  the same document zoomed 0.5 on the frame, padding 24
+ *
+ * The code block INSIDE the page is transparent, borderless and full width, so
+ * YAML scales like JSON; prose is bounded by the page, not by its own measure.
+ * `KindPreview` reaches for this for every document kind, so consumers pass
+ * nothing; `frontmatter` (markdown only) renders `DocFrontmatter` above the body.
+ *
+ * @param {Object}    frontmatter  parsed frontmatter, or null
+ * @param {ReactNode} children     the prose or the code block
+ */
+export default function DocPage({ frontmatter, className = '', children }) {
+  return (
+    <div className={`kol-doc-page ${className}`.trim()}>
+      {frontmatter && <DocFrontmatter metadata={frontmatter} />}
+      {children}
+    </div>
+  )
+}

package/src/molecules/KindPreview.jsx

@@ -5,6 +5,8 @@ import CodeBlock from './CodeBlock.jsx'
 import AssetPlaceholder from '../utilities/AssetPlaceholder.jsx'
 import { kindOf as defaultKindOf, extOf as defaultExtOf, KIND_LABEL } from '../utilities/mediaKinds.js'
 import markdownToHtml from '../utilities/markdownToHtml.js'
+import { parseFrontmatter } from '../utilities/frontmatter.js'
+import DocPage from './DocPage.jsx'
 
 /* taxonomy-ok: molecule — nests the DS media atoms + CodeBlock (relative). */
 
@@ -18,7 +20,10 @@ import markdownToHtml from '../utilities/markdownToHtml.js'
  * border — `VideoBlock`'s Figure border is why kol-r2b2 bypassed it; the overlay
  * player is `AudioPreview`), markdown → rendered prose in `.kol-prose`
  * (markdownToHtml, KindPreviewMarkdown 2026-08-27), json / yaml / text / code →
- * `CodeBlock` (language by kind or extension), the rest
+ * `CodeBlock` (language by kind or extension) — every document on ONE plate,
+ * `DocPage` (DocPageAndKindShowcase 2026-08-27: the overlay's A-series page, the
+ * column's zoomed frame; markdown's frontmatter rendered above the prose from
+ * the same fetch), the rest
  * → `AssetPlaceholder`. Images are the caller's (ColumnBrowser keeps its own
  * `<img>` so it can read the dimensions). Text fetches cap at `textLimit`.
  *
@@ -80,19 +85,20 @@ export default function KindPreview({ o, urlOf = (x) => x.url, poster, kindOf =
     if (loading) return <span className="kol-mono-12 text-meta">Loading…</span>
     if (error) return <span className="kol-mono-12 text-ui-error">Couldn’t load: {error}</span>
     if (kind === 'markdown') {
+      const meta = parseFrontmatter(text)
       return (
-        <div className="max-w-[70ch] max-h-[78vh] overflow-y-auto">
+        <DocPage frontmatter={Object.keys(meta).length ? meta : null}>
           <div className="kol-prose" dangerouslySetInnerHTML={{ __html: markdownToHtml(text) }} />
           {truncated && <p className="kol-mono-12 text-meta">truncated at {textLimit / 1024} KB</p>}
-        </div>
+        </DocPage>
       )
     }
     const language = kind === 'json' ? 'json' : kind === 'yaml' ? 'yaml' : LANG[ext] || 'text'
     return (
-      <div className="max-w-[80ch] max-h-[78vh] overflow-y-auto">
+      <DocPage>
         <CodeBlock code={text} language={language} filename={name} />
         {truncated && <p className="kol-mono-12 text-meta">truncated at {textLimit / 1024} KB</p>}
-      </div>
+      </DocPage>
     )
   }
   if (kind === 'segments') {

package/src/molecules/PlaybackBar.jsx

@@ -0,0 +1,80 @@
+/* eslint-disable react-hooks/refs -- floating-ui's `refs.setReference` is a callback ref, as in the DS Tooltip */
+import { useState } from 'react'
+import IconFrame from '../atoms/IconFrame.jsx'
+import { usePopover, PopoverPanel } from '../utilities/Popover.jsx'
+
+/* taxonomy-ok: molecule — nests IconFrame (atom) + PopoverPanel (relative). */
+
+/* mm:ss — the reference bar shows two-digit minutes (00:12 · 00:25) */
+export const clock = (s) => `${String(Math.floor((s || 0) / 60)).padStart(2, '0')}:${String(Math.floor((s || 0) % 60)).padStart(2, '0')}`
+
+const RATES = [1, 1.5, 2]
+
+/**
+ * PlaybackBar — the QuickTime bar, ruled against the reference (PlaybackBarAndAudioSheet,
+ * kol-r2b2 2026-08-27; supersedes 0.107.0's strip): a frosted strip over media —
+ * `bg-fg-absolute-48 backdrop-blur-xl`, **radius 12** (`rounded-xl`, the user's
+ * ruling on this surface — the 4px container law stands elsewhere), `h-16 px-8
+ * gap-7` — white glyphs whatever the theme (`.kol-playback-bar`, kol-theme ≥0.75.0:
+ * opacity .8, 1 on hover / focus-visible), the transport cluster (`skip-back-15` ·
+ * play / pause · `skip-forward-15`, ghost IconFrames, gap-5), elapsed as `mm:ss`
+ * (`kol-mono-16 tabular-nums`), a native range scrubber (2px track at white 40 %,
+ * a 4 × 28 white pill knob — `.kol-playback-scrub`), the TOTAL length (not the
+ * remaining), volume behind `speaker` (the vertical `slider-black` range in a
+ * PopoverPanel), and `>>` (`chevrons-right`) cycling the speed 1 → 1.5 → 2.
+ *
+ * PRESENTATIONAL — the sheet owns the media element (`usePlayback`); this bar
+ * never touches it. `place` positions it: floating over media (`left-4 right-4
+ * bottom-4 rounded-xl`) or flush along a plate's bottom edge (`left-0 right-0
+ * bottom-0`).
+ *
+ * @param {boolean}  playing
+ * @param {number}   time      seconds elapsed
+ * @param {number}   duration  seconds total
+ * @param {number}   rate      playback speed (1)
+ * @param {Function} onToggle
+ * @param {Function} onSeek    (seconds) => void
+ * @param {Function} onVolume  (0..1) => void
+ * @param {Function} onRate    (rate) => void — omit to hide the speed control
+ * @param {string}   place     the strip's position classes (see above)
+ */
+export default function PlaybackBar({ playing, time, duration, rate = 1, onToggle, onSeek, onVolume, onRate, place = 'left-4 right-4 bottom-4 rounded-xl' }) {
+  const [volume, setVolume] = useState(100)
+  const [open, setOpen] = useState(false)
+  const pop = usePopover({ open, onOpenChange: setOpen, placement: 'top' })
+  const nextRate = RATES[(RATES.indexOf(rate) + 1) % RATES.length]
+  return (
+    <div className={`kol-playback-bar absolute h-16 px-8 flex items-center gap-7 bg-fg-absolute-48 backdrop-blur-xl text-absolute-white ${place}`}>
+      <div className="flex items-center gap-5">
+        <IconFrame name="skip-back-15" variant="ghost" size="sm" onClick={() => onSeek(time - 15)} aria-label="Back 15 seconds" />
+        <IconFrame name={playing ? 'pause' : 'play'} variant="ghost" size="sm" onClick={onToggle} aria-label={playing ? 'Pause' : 'Play'} />
+        <IconFrame name="skip-forward-15" variant="ghost" size="sm" onClick={() => onSeek(time + 15)} aria-label="Forward 15 seconds" />
+      </div>
+      <span className="kol-mono-16 tabular-nums opacity-80">{clock(time)}</span>
+      <input type="range" className="kol-playback-scrub flex-1 min-w-0" min={0} max={duration || 0} step={0.1} value={time} onChange={(e) => onSeek(Number(e.target.value))} aria-label="Scrub" />
+      <span className="kol-mono-16 tabular-nums opacity-80">{clock(duration)}</span>
+      <span ref={pop.refs.setReference} {...pop.getReferenceProps()} className="inline-flex">
+        <IconFrame name="speaker" variant={open ? 'secondary' : 'ghost'} size="sm" onClick={() => {}} aria-label="Volume" />
+      </span>
+      <PopoverPanel popover={pop} className="p-2">
+        <div className="w-6 h-24 flex items-center justify-center">
+          <input
+            type="range"
+            min={0}
+            max={100}
+            value={volume}
+            onChange={(e) => { const v = Number(e.target.value); onVolume?.(v / 100); setVolume(v) }}
+            className="slider-black cursor-pointer w-24 -rotate-90"
+            aria-label="Volume"
+          />
+        </div>
+      </PopoverPanel>
+      {onRate && (
+        <span className="flex items-center gap-1">
+          <IconFrame name="chevrons-right" variant="ghost" size="sm" onClick={() => onRate(nextRate)} aria-label={`Playback speed ${rate}× — next ${nextRate}×`} />
+          {rate !== 1 && <span className="kol-mono-12 tabular-nums opacity-80">{rate}×</span>}
+        </span>
+      )}
+    </div>
+  )
+}

package/src/molecules/TiltBento.jsx

@@ -90,12 +90,16 @@ function Media({ src, poster, className }) {
  * @param {ReactNode} description    hover-revealed paragraph
  * @param {string}    href           CTA target; `http*`/`mailto` → new-tab anchor, else same-tab (onNavigate seam)
  * @param {Function}  onNavigate     (event) => void — same-tab CTA click seam (SPA intercept)
- * @param {ReactNode} buttonLabel    CTA label (no default — author it)
+ * @param {ReactNode} buttonLabel    CTA label — NO DEFAULT, BY DESIGN: an `href` with no label is a
+ *                                   call-site bug, not a gap (the retired kol-website fork defaulted
+ *                                   'View Project'; TiltBentoVoiceAndDefaults 2026-08-27)
  * @param {ReactNode} bodyContent    extra content injected into the stack
  * @param {number}    overlayOpacity scrim darkness % over the media, 0 disables (default 60)
  * @param {boolean}   alignRight     right-align the card (ms-auto) vs fill (size-full)
  * @param {boolean}   enableTilt     master tilt switch (default true)
- * @param {string}    titleClassName title classes
+ * @param {string}    titleClassName title classes — the family default is `kol-sans-heading-01
+ *                                   text-absolute-white` (confirmed 2026-08-27; the fork's was
+ *                                   heading-02 uppercase — a consumer wanting that passes it)
  * @param {string}    contentClassName inner content-box classes
  * @param {string}    imageClassName media fit/position classes
  * @param {string}    contentStackClassName stack layout classes
@@ -166,7 +170,10 @@ export default function TiltBento({
           )}
           <div className={contentStackClassName}>
             {title && <h3 className={titleClassName}>{title}</h3>}
-            {subtitle && <p className={`kol-mono-text text-absolute-white ${revealClass}`}>{subtitle}</p>}
+            {/* kol-mono-14 — one rung above the mono-12 description, as the retired
+              * fork drew it (TiltBentoVoiceAndDefaults, kol-website 2026-08-27: this
+              * rode `kol-mono-text`, a class retired from the theme — zero rules emitted) */}
+            {subtitle && <p className={`kol-mono-14 text-absolute-white ${revealClass}`}>{subtitle}</p>}
             {description && <p className={`kol-mono-12 text-absolute-white pb-6 ${revealClass}`}>{description}</p>}
             {bodyContent}
             {href && (

package/src/molecules/VideoSheet.jsx

@@ -1,87 +1,24 @@
-/* eslint-disable react-hooks/refs -- floating-ui's `refs.setReference` is a callback ref, as in the DS Tooltip */
-import { useRef, useState } from 'react';
-import IconFrame from '../atoms/IconFrame.jsx';
-import Slider from './Slider.jsx';
-import { usePopover, PopoverPanel } from '../utilities/Popover.jsx';
-import { formatLength } from './AudioPreview.jsx';
+import usePlayback from '../hooks/usePlayback.js'
+import PlaybackBar from './PlaybackBar.jsx'
 
-/* taxonomy-ok: molecule — nests IconFrame (atom) + Slider / PopoverPanel (relative). */
+/* taxonomy-ok: molecule — nests PlaybackBar (relative). */
 
 /**
- * VideoSheet — the overlay for video: the QuickTime bar (ruled in kol-r2b2
- * 2026-08-27, PlayDiscAndVideoBar; promoted verbatim). No native controls; a
- * frosted strip over the video's bottom edge, inset 16px, radius 4px (never
- * more), `bg-fg-absolute-64` (absolute black — it sits on video, not on the
- * theme) + `backdrop-blur-md`, `h-14 px-4 gap-3`: skip-back 15 · play/pause ·
- * skip-forward 15 · elapsed · the DS Slider as the scrubber with the REMAINING
- * time as its readout · volume behind `slider-01` (the vertical `slider-black`
- * range in a PopoverPanel, as AudioPreview). Click on the video toggles play;
- * `autoPlay`. Aria-labels only, no `title` tooltips.
+ * VideoSheet — the overlay for video: the frame with the QuickTime bar floating
+ * over its bottom edge (`PlaybackBar`, inset 16, radius 12 — PlaybackBarAndAudioSheet,
+ * kol-r2b2 2026-08-27). No native controls; click on the video toggles play;
+ * `autoPlay`, `playsInline`, `preload="metadata"`. Aria-labels only.
  *
  * @param {string}   src     the video URL
  * @param {string}   poster  the poster URL
  * @param {Function} onMeta  ({ w, h, len }) => void once metadata lands — the overlay's facts
  */
 export default function VideoSheet({ src, poster, onMeta }) {
-  const ref = useRef(null);
-  const [playing, setPlaying] = useState(false);
-  const [time, setTime] = useState(0);
-  const [duration, setDuration] = useState(0);
-  const [volume, setVolume] = useState(100);
-  const [open, setOpen] = useState(false);
-  const pop = usePopover({ open, onOpenChange: setOpen, placement: 'top' });
-  const toggle = () => (playing ? ref.current.pause() : ref.current.play());
-  const seek = (t) => { const v = Math.max(0, Math.min(duration || 0, t)); ref.current.currentTime = v; setTime(v); };
+  const { ref, handlers, bar } = usePlayback((el) => onMeta?.({ w: el.videoWidth, h: el.videoHeight, len: el.duration }))
   return (
     <div className="relative max-w-full">
-      <video
-        ref={ref}
-        src={src}
-        poster={poster}
-        autoPlay
-        playsInline
-        preload="metadata"
-        className="max-w-full max-h-[78vh] rounded"
-        onClick={toggle}
-        onPlay={() => setPlaying(true)}
-        onPause={() => setPlaying(false)}
-        onEnded={() => setPlaying(false)}
-        onTimeUpdate={(e) => setTime(e.target.currentTime)}
-        onLoadedMetadata={(e) => { setDuration(e.target.duration); onMeta?.({ w: e.target.videoWidth, h: e.target.videoHeight, len: e.target.duration }); }}
-      />
-      <div className="absolute left-4 right-4 bottom-4 h-14 px-4 rounded flex items-center gap-3 bg-fg-absolute-64 backdrop-blur-md">
-        <IconFrame name="skip-back-15" variant="ghost" size="sm" onClick={() => seek(time - 15)} aria-label="Back 15 seconds" />
-        <IconFrame name={playing ? 'pause' : 'play'} variant="ghost" size="sm" onClick={toggle} aria-label={playing ? 'Pause' : 'Play'} />
-        <IconFrame name="skip-forward-15" variant="ghost" size="sm" onClick={() => seek(time + 15)} aria-label="Forward 15 seconds" />
-        <span className="kol-mono-14 text-fg-64 tabular-nums">{formatLength(time)}</span>
-        {/* DS Slider: the track is the scrubber, its readout is the remaining time. */}
-        <Slider
-          className="flex-1 min-w-0"
-          min={0}
-          max={duration || 0}
-          step={0.1}
-          value={time}
-          onChange={seek}
-          formatValue={(v) => formatLength(Math.max(0, (duration || 0) - v))}
-          displayWidth={5}
-        />
-        <span ref={pop.refs.setReference} {...pop.getReferenceProps()} className="inline-flex">
-          <IconFrame name="slider-01" variant={open ? 'secondary' : 'ghost'} size="sm" onClick={() => {}} aria-label="Volume" />
-        </span>
-        <PopoverPanel popover={pop} className="p-2">
-          <div className="w-6 h-24 flex items-center justify-center">
-            <input
-              type="range"
-              min={0}
-              max={100}
-              value={volume}
-              onChange={(e) => { const v = Number(e.target.value); ref.current.volume = v / 100; setVolume(v); }}
-              className="slider-black cursor-pointer w-24 -rotate-90"
-              aria-label="Volume"
-            />
-          </div>
-        </PopoverPanel>
-      </div>
+      <video ref={ref} src={src} poster={poster} autoPlay playsInline preload="metadata" className="max-w-full max-h-[78vh] rounded" onClick={bar.onToggle} {...handlers} />
+      <PlaybackBar {...bar} place="left-4 right-4 bottom-4 rounded-xl" />
     </div>
-  );
+  )
 }

package/src/organisms/ColumnBrowser.jsx

@@ -1,4 +1,4 @@
-import { useEffect, useRef, useState } from 'react'
+import { Fragment, useEffect, useRef, useState } from 'react'
 import { Icon } from '@kolkrabbi/kol-icons'
 import KindPreview from '../molecules/KindPreview.jsx'
 import { formatLength } from '../molecules/AudioPreview.jsx'
@@ -27,7 +27,14 @@ import { kindOf as dsKindOf, KIND_LABEL as DS_KIND_LABEL } from '../utilities/me
  * Rows wear the DS Table's cell metrics (12px 16px, mono 12, an oq-08 hairline
  * between rows, none after the last). Selected and cursor rows draw the HOVER
  * fill (`bg-fg-04`) — user ruling: "make hover state the selected state".
- * Height is fixed at 528px = 12 rows × 44px (user ruling); columns scroll.
+ * Height defaults to 528px = 12 rows × 44px (user ruling); columns scroll. Both
+ * the height and every column's width are DRAGGABLE, Finder-style
+ * (ColumnBrowserResize, kol-r2b2 2026-08-27 — user: "column height drag yes and
+ * individual column width drag" · "that should be a set in ds"): a strip along
+ * the browser's bottom edge (`row-resize`) and one on each column's right edge
+ * (`col-resize`, the border already there is the visual — the strip is the hit
+ * area, invisible at rest, `fg-08` on hover / while dragging). Pointer events
+ * with `setPointerCapture`, no library; native CSS `resize:` was rejected.
  *
  * The app-owned bits are SEAMS with working defaults: `urlOf(o)` (the preview
  * image — no URL, no image), `kindOf(o)` (image / video / audio / file from
@@ -45,6 +52,11 @@ import { kindOf as dsKindOf, KIND_LABEL as DS_KIND_LABEL } from '../utilities/me
  * @param {Function} formatSize   (bytes) => string
  * @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 {number}   height         controlled height in px (omit for uncontrolled)
+ * @param {number}   defaultHeight  uncontrolled start height (528); min 240
+ * @param {Function} onHeightChange (px) => void — on every drag step; the consumer persists it
+ * @param {number}   columnWidth    every column's start width (260); the preview column starts at 320; min 160
+ * @param {Function} onColumnResize (index, px) => void — the column's index, or `'preview'`
  * @param {string}   className    extra classes on the browser
  */
 
@@ -96,7 +108,7 @@ function Row({ icon, label, active, cursor = false, trailing, onClick, muted = f
   )
 }
 
-function Preview({ o, urlOf, kindOf, kindLabel, formatSize, renderPreview }) {
+function Preview({ o, urlOf, kindOf, kindLabel, formatSize, renderPreview, 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
@@ -115,7 +127,7 @@ function Preview({ o, urlOf, kindOf, kindLabel, formatSize, renderPreview }) {
     ['Date', o.uploaded ? new Date(o.uploaded).toISOString().slice(0, 10) : '—'],
   ]
   return (
-    <div className="kol-column-browser-preview w-[320px] shrink-0 overflow-y-auto p-4 flex flex-col gap-4">
+    <div className="kol-column-browser-preview shrink-0 overflow-y-auto p-4 flex flex-col gap-4" style={{ width }}>
       {/* the media frame: an image is the organism's own <img> (it reads the
         * dimensions); anything else is `renderPreview(o)` or the DS KindPreview
         * (video · audio · code · text — SettingsPanelChromeAndColumnPreview,
@@ -158,6 +170,28 @@ function Preview({ o, urlOf, kindOf, kindLabel, formatSize, renderPreview }) {
   )
 }
 
+/* one edge handle: captures the pointer, reports the delta along its axis;
+ * `is-dragging` keeps the wash on while the pointer is captured */
+function ResizeHandle({ axis, onDrag, onEnd }) {
+  const [dragging, setDragging] = useState(false)
+  const start = useRef(null)
+  return (
+    <div
+      className={`kol-column-browser-resize-${axis} ${dragging ? 'is-dragging' : ''}`.trim()}
+      role="separator"
+      aria-orientation={axis === 'x' ? 'vertical' : 'horizontal'}
+      onPointerDown={(e) => { e.preventDefault(); e.currentTarget.setPointerCapture(e.pointerId); start.current = axis === 'x' ? e.clientX : e.clientY; setDragging(true) }}
+      onPointerMove={(e) => { if (start.current == null) return; onDrag((axis === 'x' ? e.clientX : e.clientY) - start.current) }}
+      onPointerUp={(e) => { e.currentTarget.releasePointerCapture(e.pointerId); start.current = null; setDragging(false); onEnd?.() }}
+      onPointerCancel={() => { start.current = null; setDragging(false); onEnd?.() }}
+    />
+  )
+}
+
+const MIN_H = 240
+const MIN_W = 160
+const PREVIEW_W = 320
+
 export default function ColumnBrowser({
   objects = [],
   prefix = '',
@@ -171,8 +205,33 @@ export default function ColumnBrowser({
   formatSize = defaultFormatSize,
   partition = defaultPartition,
   renderPreview,
+  height,
+  defaultHeight = 528,
+  onHeightChange,
+  columnWidth = 260,
+  onColumnResize,
   className = '',
 }) {
+  /* height: controlled-or-uncontrolled like Slider; widths: organism-internal,
+   * by column index (the preview keyed apart), seeded from `columnWidth` */
+  const [ownH, setOwnH] = useState(defaultHeight)
+  const h = height ?? ownH
+  const [widths, setWidths] = useState({})
+  const widthOf = (i) => widths[i] ?? (i === 'preview' ? PREVIEW_W : columnWidth)
+  const dragBase = useRef(null)
+  const resizeCol = (i) => (dx) => {
+    if (dragBase.current == null) dragBase.current = widthOf(i)
+    const w = Math.max(MIN_W, Math.round(dragBase.current + dx))
+    setWidths((prev) => (prev[i] === w ? prev : { ...prev, [i]: w }))
+    onColumnResize?.(i, w)
+  }
+  const resizeH = (dy) => {
+    if (dragBase.current == null) dragBase.current = h
+    const next = Math.max(MIN_H, Math.round(dragBase.current + dy))
+    if (height == null) setOwnH(next)
+    onHeightChange?.(next)
+  }
+  const endDrag = () => { dragBase.current = null }
   const [picked, setPicked] = useState(null)
   /* `onPick` (ColumnBrowserOnPick, kol-r2b2 2026-08-27): the picked file, for
    * a Finder-style breadcrumb — fired whenever it changes; a folder pick or an
@@ -304,19 +363,22 @@ export default function ColumnBrowser({
       ref={rootRef}
       tabIndex={0}
       onKeyDown={onKeyDown}
-      // Fixed height — 12 rows of 44px (user ruling 2026-08-27), so the browser never jumps as columns change; each column scrolls.
-      className={`kol-column-browser flex overflow-x-auto h-[528px] border rounded outline-none ${className}`.trim()}
-      style={{ borderColor: 'var(--kol-oq-08)' }}
+      // 12 rows of 44px by default (user ruling 2026-08-27), so the browser never jumps as columns change; each column scrolls.
+      // The scroll box is the INNER flex row: the bottom handle is absolute on this root, so it spans the visible width, not the scrolled one.
+      className={`kol-column-browser relative border rounded outline-none ${className}`.trim()}
+      style={{ borderColor: 'var(--kol-oq-08)', height: h }}
     >
+      <div className="flex h-full overflow-x-auto">
       {levels.map((level, k) => {
         const { folders, files } = partition(objects.filter((o) => o.key.startsWith(level)), level)
         const next = levels[k + 1]
         const activeFolder = next ? next.slice(level.length) : null
+        const last = k === levels.length - 1 && !shown
         return (
+          <Fragment key={level || '/'}>
           <ul
-            key={level || '/'}
-            className="kol-column-browser-column w-[260px] shrink-0 overflow-y-auto border-r last:border-r-0"
-            style={{ borderColor: 'var(--kol-oq-08)' }}
+            className={`kol-column-browser-column shrink-0 overflow-y-auto ${last ? '' : 'border-r'}`.trim()}
+            style={{ borderColor: 'var(--kol-oq-08)', width: widthOf(k) }}
           >
             {folders.map((f, i) => (
               <Row
@@ -344,9 +406,18 @@ export default function ColumnBrowser({
               <li className="kol-mono-12 text-fg-32 px-4 py-3">empty</li>
             )}
           </ul>
+          <ResizeHandle axis="x" onDrag={resizeCol(k)} onEnd={endDrag} />
+          </Fragment>
         )
       })}
-      {shown && <Preview key={shown.key} o={shown} urlOf={urlOf} kindOf={kindOf} kindLabel={kindLabel} formatSize={formatSize} renderPreview={renderPreview} />}
+      {shown && (
+        <>
+          <Preview key={shown.key} o={shown} urlOf={urlOf} kindOf={kindOf} kindLabel={kindLabel} formatSize={formatSize} renderPreview={renderPreview} width={widthOf('preview')} />
+          <ResizeHandle axis="x" onDrag={resizeCol('preview')} onEnd={endDrag} />
+        </>
+      )}
+      </div>
+      <ResizeHandle axis="y" onDrag={resizeH} onEnd={endDrag} />
     </div>
   )
 }

package/src/organisms/MediaViewer.jsx

@@ -29,8 +29,12 @@ import FullscreenOverlay from '../utilities/FullscreenOverlay.jsx'
 
 /* Inverse-tier chip tokens: the overlay scrim is surface-inverse, and .kol-overlay
  * carries no surface-context class, so the standard fg ramp doesn't flip there. */
+/* FIXED at the viewport edges, never inside the sheet (DocPageAndKindShowcase,
+ * kol-r2b2 2026-08-27 — absolute to the stage they sat inside the plate and
+ * centred on stage + caption, "too low"); the body stops 10rem short of the
+ * edges so nothing runs under them. */
 const CHIP =
-  'kol-embla-btn absolute top-1/2 z-10 hidden -translate-y-1/2 items-center justify-center border border-fg-inverse-16 text-inverse hover:border-fg-inverse-32 md:flex'
+  'kol-embla-btn fixed top-1/2 z-10 hidden -translate-y-1/2 items-center justify-center border border-fg-inverse-16 text-inverse hover:border-fg-inverse-32 md:flex'
 
 /* Mounted only while the overlay is open, so embla initializes fresh each open
  * with `startIndex` frozen at mount — no reInit games on later index changes. */
@@ -67,7 +71,7 @@ function ViewerStage({ media, index, onIndexChange }) {
       <div className="overflow-hidden" ref={emblaRef}>
         <div className="flex items-center">
           {media.map((item, i) => (
-            <figure key={i} className="flex min-w-0 flex-[0_0_100%] flex-col items-center justify-center gap-3">
+            <figure key={i} className="flex min-w-0 flex-[0_0_100%] flex-col items-center justify-center gap-3 [&>*]:max-w-[calc(100vw-10rem)]">
               {item.kind === 'video' ? (
                 <video
                   src={item.url}
@@ -92,7 +96,7 @@ function ViewerStage({ media, index, onIndexChange }) {
         <>
           <button
             type="button"
-            className={`${CHIP} left-4`}
+            className={`${CHIP} left-6`}
             aria-label="Previous"
             onClick={(e) => { e.stopPropagation(); emblaApi?.scrollPrev() }}
           >
@@ -100,7 +104,7 @@ function ViewerStage({ media, index, onIndexChange }) {
           </button>
           <button
             type="button"
-            className={`${CHIP} right-4`}
+            className={`${CHIP} right-6`}
             aria-label="Next"
             onClick={(e) => { e.stopPropagation(); emblaApi?.scrollNext() }}
           >

package/src/utilities/TiltCard.jsx

@@ -1,4 +1,4 @@
-import { motion, useSpring, useTransform } from 'framer-motion'
+import { motion } from 'framer-motion'
 import useTilt from '../hooks/useTilt.js'
 import usePrefersReducedMotion from '../hooks/usePrefersReducedMotion.js'
 import useCoarsePointer from '../hooks/useCoarsePointer.js'
@@ -65,36 +65,16 @@ export default function TiltCard({
 }
 
 function TiltCardInner({ src, alt, className, variant, magnitude, perspective, children }) {
-  const tilt = useTilt({ magnitude, perspective })
-  const grounded = variant === 'grounded'
-
-  /* Zone-based tilt: normalize the spring output back to -1..1, snap it to
-   * 3 zones, rescale to ±2.5°, and let a slower lazy spring catch up so the
-   * card lags and settles into quantized angles. rotateX is clamped to
-   * min(0, …) — grounded cards only ever tilt back. */
-  const zones = 3
-  const snap = (v) => Math.round(v * zones) / zones
-  const lazySpring = { stiffness: 250, damping: 25, mass: 0.6 }
-
-  const targetX = useTransform(tilt.motionValues.rotateX, (v) =>
-    grounded ? Math.min(0, snap(-v / magnitude) * 2.5) : v,
-  )
-  const targetY = useTransform(tilt.motionValues.rotateY, (v) =>
-    grounded ? snap(v / magnitude) * 2.5 : v,
-  )
-
-  const lazyRotateX = useSpring(targetX, lazySpring)
-  const lazyRotateY = useSpring(targetY, lazySpring)
-
-  const style = grounded
-    ? { ...tilt.style, rotateX: lazyRotateX, rotateY: lazyRotateY, transformOrigin: 'center bottom' }
-    : tilt.style
+  /* the grounded feel — zones, ±2.5°, the lazy spring, the bottom pivot — lives
+   * in useTilt now (ShelfCardTiltWrapsCard, 2026-08-27), so the shelf's card
+   * wrapper and this frame are one motion, not two copies of eight lines */
+  const tilt = useTilt({ magnitude, perspective, grounded: variant === 'grounded' })
 
   return (
     <motion.div
       ref={tilt.ref}
       className={`relative ${className}`}
-      style={style}
+      style={tilt.style}
       onMouseMove={tilt.onMouseMove}
       onMouseLeave={tilt.onMouseLeave}
     >

package/src/utilities/frontmatter.js

@@ -0,0 +1,29 @@
+/**
+ * parseFrontmatter — the workshop engine's handrolled YAML-subset parser,
+ * verbatim (`packages/workshop/src/engine/frontmatter.js`; DocPageAndKindShowcase,
+ * kol-r2b2 2026-08-27): `key: value`, block lists (`  - item`), inline `[a, b]`
+ * tags. Keys are lowercased. No gray-matter / js-yaml.
+ */
+export function parseFrontmatter(raw) {
+  const metadata = {}
+  const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/)
+  if (!match) return metadata
+  const lines = match[1].split(/\r?\n/)
+  for (let i = 0; i < lines.length; i++) {
+    const kv = lines[i].match(/^([A-Za-z][A-Za-z0-9 -]*):\s*(.*)$/)
+    if (!kv) continue
+    const key = kv[1].toLowerCase()
+    const value = kv[2].trim()
+    if (!value) {
+      const items = []
+      while (i + 1 < lines.length && lines[i + 1].match(/^\s+-\s+/)) { i++; items.push(lines[i].replace(/^\s+-\s+/, '').trim()) }
+      metadata[key] = items.length ? items : ''
+    } else {
+      metadata[key] = value
+    }
+  }
+  if (typeof metadata.tags === 'string' && metadata.tags.startsWith('[')) {
+    metadata.tags = metadata.tags.slice(1, -1).split(',').map((t) => t.trim()).filter(Boolean)
+  }
+  return metadata
+}