@kolkrabbi/kol-component 0.113.0 → 0.114.0

package/package.json

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