@kolkrabbi/kol-component 0.1.2 → 0.3.0

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "KOL design-system components — atoms through organisms, emitting canonical kol-* classes. Pairs with @kolkrabbi/kol-theme for styling.",
   "license": "MIT",
   "type": "module",
   "main": "./src/index.js",
   "module": "./src/index.js",
   "exports": {
-    ".": "./src/index.js"
+    ".": "./src/index.js",
+    "./foundry": "./src/organisms/foundry/index.js"
   },
   "files": [
     "src",
@@ -23,16 +24,23 @@
   "dependencies": {
     "@floating-ui/react": "^0.27.19",
     "embla-carousel-react": "^8.6.0",
-    "@kolkrabbi/kol-loader": "0.2.0"
+    "@kolkrabbi/kol-loader": "0.3.0"
   },
   "peerDependencies": {
     "react": "^18.3.0 || ^19.0.0",
     "react-dom": "^18.3.0 || ^19.0.0",
-    "react-router-dom": "^6.0.0 || ^7.0.0"
+    "react-router-dom": "^6.0.0 || ^7.0.0",
+    "framer-motion": "^12.0.0",
+    "gsap": "^3.13.0",
+    "hls.js": "^1.6.0",
+    "opentype.js": "^1.3.4"
   },
   "peerDependenciesMeta": {
     "react-router-dom": {
       "optional": true
+    },
+    "opentype.js": {
+      "optional": true
     }
   },
   "repository": {

package/src/atoms/AnimatedTitle.jsx

@@ -0,0 +1,108 @@
+import { useEffect, useRef } from 'react'
+import { gsap } from 'gsap'
+import { ScrollTrigger } from 'gsap/ScrollTrigger'
+import usePrefersReducedMotion from '../hooks/usePrefersReducedMotion.js'
+
+gsap.registerPlugin(ScrollTrigger)
+
+/**
+ * AnimatedTitle — scroll-triggered heading that reveals its words one by
+ * one as it scrolls into view: each word starts far off-screen right,
+ * rotated in 3D, and flies into place with a fast stagger (GSAP +
+ * ScrollTrigger; plays entering the viewport, reverses scrolling back
+ * out). `title` is an HTML-bearing string: the literal '<br />' splits
+ * lines, spaces split words, and each word renders via
+ * dangerouslySetInnerHTML so it can carry inline markup (<b>,
+ * <span class>) — pass trusted strings only.
+ *
+ * Typography and color are inherited from the consumer via
+ * `containerClass` — the component owns only the split and the motion.
+ * When the user prefers reduced motion, no GSAP runs at all and the
+ * title renders fully visible and static.
+ *
+ * @param {string}  title          HTML string; '<br />' → lines, ' ' → words. Required. Trusted content only
+ * @param {string}  containerClass classes on the root (typography/color live here)
+ * @param {object}  style          inline style on the root
+ * @param {string}  lineClass      extra classes on each line row, after the flex defaults
+ * @param {number}  stagger        seconds between word starts
+ * @param {string}  start          ScrollTrigger start position
+ * @param {string}  end            ScrollTrigger end position
+ * @param {boolean} immediate      skip ScrollTrigger, play the reveal on mount (non-scrolling stages)
+ */
+export default function AnimatedTitle({
+  title,
+  containerClass,
+  style,
+  lineClass,
+  stagger = 0.02,
+  start = '100 bottom',
+  end = 'center bottom',
+  immediate = false,
+}) {
+  const containerRef = useRef(null)
+  const reducedMotion = usePrefersReducedMotion()
+
+  useEffect(() => {
+    if (reducedMotion) return undefined
+
+    const ctx = gsap.context(() => {
+      const words = containerRef.current.querySelectorAll('.animatedWord')
+
+      gsap.set(words, {
+        opacity: 0,
+        x: '150vw',
+        y: 50,
+        rotateY: -45,
+        rotateX: 15,
+      })
+
+      const titleAnimation = gsap.timeline(
+        immediate
+          ? undefined
+          : {
+              scrollTrigger: {
+                trigger: containerRef.current,
+                start,
+                end,
+                toggleActions: 'play none none reverse',
+              },
+            },
+      )
+
+      titleAnimation.to(
+        words,
+        {
+          opacity: 1,
+          x: 0,
+          y: 0,
+          rotateY: 0,
+          rotateX: 0,
+          ease: 'power2.inOut',
+          stagger,
+        },
+        0,
+      )
+    }, containerRef)
+
+    return () => ctx.revert()
+  }, [title, reducedMotion, immediate, stagger, start, end])
+
+  return (
+    <div ref={containerRef} className={containerClass} style={style}>
+      {title.split('<br />').map((line, index) => (
+        <div
+          key={index}
+          className={`flex items-center justify-center flex-wrap gap-2 md:gap-3 ${lineClass || ''}`}
+        >
+          {line.split(' ').map((word, i) => (
+            <span
+              key={i}
+              className="animatedWord"
+              dangerouslySetInnerHTML={{ __html: word }}
+            />
+          ))}
+        </div>
+      ))}
+    </div>
+  )
+}

package/src/atoms/AssetGrid.jsx

@@ -0,0 +1,29 @@
+/**
+ * AssetGrid — thin responsive N-column grid for tiling asset figures
+ * (swatches, placeholders, spec cards). Fixed 2/3/4-column layout that
+ * collapses to 2 columns under the md breakpoint and to 1 column under
+ * 480px, all via Tailwind responsive utilities — no CSS of its own.
+ *
+ * Purely structural — no styling of the cells, no spacing outside itself
+ * (the source's `mt-8` was a call-site concern and was dropped). Children
+ * just fill the tracks.
+ *
+ * @param {2|3|4}     cols      column count at full width (unknown values fall back to 3)
+ * @param {string}    gap       Tailwind gap utility for both axes
+ * @param {ReactNode} children  grid items
+ * @param {string}    className extra classes appended
+ */
+
+const COLS = {
+  2: 'grid-cols-1 min-[480px]:grid-cols-2',
+  3: 'grid-cols-1 min-[480px]:grid-cols-2 md:grid-cols-3',
+  4: 'grid-cols-1 min-[480px]:grid-cols-2 md:grid-cols-4',
+}
+
+export default function AssetGrid({ cols = 3, gap = 'gap-4', children, className = '' }) {
+  return (
+    <div className={`grid ${COLS[cols] || COLS[3]} ${gap} ${className}`.trim()}>
+      {children}
+    </div>
+  )
+}

package/src/{primitives → atoms}/AssetPlaceholder.jsx

@@ -21,8 +21,10 @@ export default function AssetPlaceholder({
       role="img"
       aria-label={`${label || 'asset'} — ${note}`}
     >
-      <span className="kol-asset-placeholder-note text-[12px] uppercase [letter-spacing:0.12em] text-fg-48">{note}</span>
-      {label && <span className="kol-asset-placeholder-label text-[12px] text-fg-40 [letter-spacing:0.04em]">{label}</span>}
+      {/* note is single-line → helper scale; label can wrap (category · name
+        * in a narrow tile) → line-height-bearing mono scale */}
+      <span className="kol-asset-placeholder-note kol-helper-12 uppercase [letter-spacing:0.12em] text-fg-48">{note}</span>
+      {label && <span className="kol-asset-placeholder-label kol-mono-12 text-fg-40 [letter-spacing:0.04em]">{label}</span>}
     </div>
   )
 }

package/src/atoms/Avatar.jsx

@@ -1,8 +1,8 @@
 const SIZE_MAP = {
-  sm: 'w-8 h-8 text-xs',
-  md: 'w-10 h-10 text-sm',
-  lg: 'w-14 h-14 text-base',
-  xl: 'w-24 h-24 text-3xl',
+  sm: 'w-8 h-8 kol-helper-12',
+  md: 'w-10 h-10 kol-helper-14',
+  lg: 'w-14 h-14 kol-helper-16',
+  xl: 'w-24 h-24 kol-helper-20',
 }
 
 export default function Avatar({ initial, size = 'sm', className = '' }) {

package/src/atoms/Button.jsx

@@ -1,3 +1,4 @@
+import { isValidElement } from 'react'
 import { Icon } from '@kolkrabbi/kol-loader'
 
 /**
@@ -28,6 +29,8 @@ import { Icon } from '@kolkrabbi/kol-loader'
  * @param {string} props.type - Button type attribute (default: 'button')
  * @param {boolean} props.disabled - Disabled state
  * @param {boolean} props.selected - Selected/active state (toggle highlight)
+ * @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 Button = ({
   children,
@@ -50,6 +53,8 @@ const Button = ({
   type = 'button',
   disabled = false,
   selected = false,
+  iconComponent,
+  pressed,
   ...props
 }) => {
   const resolvedIconSize = iconSize ?? (size === 'sm' ? 14 : size === 'lg' ? 18 : 16)
@@ -77,30 +82,36 @@ const Button = ({
 
   // Add kol-btn-animate class if animateIcon is true to disable default hover states
   const animateClass = animateIcon ? 'kol-btn-animate' : ''
-  const quietClass    = quiet ? 'kol-btn-quiet' : ''
+  const quietClass    = quiet && !pressed ? 'kol-btn-quiet' : ''
   const selectedClass = selected ? 'kol-btn-selected' : ''
+  const pressedClass  = pressed ? 'kol-btn-pressed' : ''
 
-  const combinedClass = `kol-btn ${variantClass} ${sizeClass} ${animateClass} ${quietClass} ${selectedClass} ${className}`.trim().replace(/\s+/g, ' ')
+  const combinedClass = `kol-btn ${variantClass} ${sizeClass} ${animateClass} ${quietClass} ${selectedClass} ${pressedClass} ${className}`.trim().replace(/\s+/g, ' ')
 
   // Render icon with optional hover state
   const renderIcon = (iconName, iconHoverName) => {
     if (!iconName && !iconHoverName) return null
 
+    // Icon injection seam — a component type resolves names against a custom
+    // registry (EditorIcon etc.); a pre-rendered node drops in verbatim.
+    if (isValidElement(iconComponent)) return iconComponent
+    const IconCmp = iconComponent || Icon
+
     // If no hover icon, render single icon
     if (!iconHoverName) {
-      return <Icon name={iconName} size={resolvedIconSize} />
+      return <IconCmp name={iconName} size={resolvedIconSize} />
     }
 
     // Render both default and hover icons with positioning
     return (
       <span className="kol-icon-swap-container" style={{ position: 'relative', display: 'inline-flex', width: resolvedIconSize, height: resolvedIconSize, overflow: 'hidden' }}>
-        <Icon
+        <IconCmp
           name={iconName}
           size={resolvedIconSize}
           className="kol-icon-default"
           style={{ position: 'absolute' }}
         />
-        <Icon
+        <IconCmp
           name={iconHoverName}
           size={resolvedIconSize}
           className="kol-icon-hover"
@@ -117,13 +128,16 @@ const Button = ({
       return renderIcon(iconOnly, iconOnlyHover)
     }
 
-    // Button with icon(s) and text
+    // Button with icon(s) and text. Icons render directly as flex items —
+    // wrapper spans (with the old -2px optical margins) sat the glyphs on
+    // the span's text baseline instead of letting align-items center them
+    // against the label.
     if (iconLeft || iconRight || iconLeftHover || iconRightHover) {
       return (
         <span className="flex items-center" style={{ gap: iconGap ?? 8 }}>
-          {(iconLeft || iconLeftHover) && <span style={{ marginLeft: -2 }}>{renderIcon(iconLeft, iconLeftHover)}</span>}
+          {(iconLeft || iconLeftHover) && renderIcon(iconLeft, iconLeftHover)}
           {children}
-          {(iconRight || iconRightHover) && <span style={{ marginRight: -2 }}>{renderIcon(iconRight, iconRightHover)}</span>}
+          {(iconRight || iconRightHover) && renderIcon(iconRight, iconRightHover)}
         </span>
       )
     }
@@ -146,7 +160,7 @@ const Button = ({
         className={combinedClass}
         style={mergedStyle}
         disabled={disabled}
-        aria-pressed={selected ? true : undefined}
+        aria-pressed={pressed !== undefined ? pressed : (selected ? true : undefined)}
         aria-label={iconOnly ? (props['aria-label'] || 'Button') : undefined}
         {...props}
       >

package/src/atoms/CopyButton.jsx

@@ -0,0 +1,50 @@
+import { useState } from 'react'
+
+/**
+ * CopyButton — copy-to-clipboard chip. Clipboard icon + Copy/Copied label
+ * swap with a 1.8s reset; silent when the clipboard is blocked. Chrome
+ * comes from .kol-copy-btn (kol-theme); parents add their own positioning
+ * class (e.g. CodeBlock's .kol-codeblock-copy).
+ *
+ * Props:
+ *   text      — string (or () => string) written to the clipboard
+ *   label     — show the Copy/Copied text next to the icon (default true;
+ *               false = icon-only for tight spots)
+ *   className — extra classes (positioning etc.)
+ */
+export default function CopyButton({ text, label = true, className = '', ...props }) {
+  const [copied, setCopied] = useState(false)
+
+  const onCopy = async () => {
+    try {
+      await navigator.clipboard.writeText(typeof text === 'function' ? text() : String(text ?? ''))
+      setCopied(true)
+      setTimeout(() => setCopied(false), 1800)
+    } catch {
+      /* clipboard blocked — silent */
+    }
+  }
+
+  return (
+    <button
+      type="button"
+      className={`kol-copy-btn ${className}`.trim()}
+      onClick={onCopy}
+      aria-label={copied ? 'Copied' : 'Copy to clipboard'}
+      title={copied ? 'Copied' : 'Copy'}
+      {...props}
+    >
+      {copied ? (
+        <svg viewBox="0 0 20 20" width="14" height="14" aria-hidden="true">
+          <path d="M5 10 L9 14 L15 6" fill="none" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" strokeLinejoin="round" />
+        </svg>
+      ) : (
+        <svg viewBox="0 0 20 20" width="14" height="14" aria-hidden="true">
+          <rect x="6" y="3" width="10" height="12" rx="1" fill="none" stroke="currentColor" strokeWidth="1.4" />
+          <rect x="4" y="6" width="10" height="12" rx="1" fill="none" stroke="currentColor" strokeWidth="1.4" />
+        </svg>
+      )}
+      {label && <span>{copied ? 'Copied' : 'Copy'}</span>}
+    </button>
+  )
+}

package/src/atoms/CurveOverlay.jsx

@@ -0,0 +1,180 @@
+import { useId } from 'react'
+
+/* ------------------------------------------------------------------ *
+ * Curve math — ported from the brand app's curveMath so the primitive
+ * has no app import. Curves return a blend in [0..1] for a position
+ * `t` in [0..1]. `blend` is the amount knob — for 'flat' it IS the
+ * value; for other presets it biases the curve up/down (0.5 = pure
+ * curve); for 'custom' it biases the bezier. Consumers with their own
+ * math bypass all of this via the `easing` prop.
+ * ------------------------------------------------------------------ */
+
+const TAU = Math.PI * 2
+const clamp = (v, lo = 0, hi = 1) => (v < lo ? lo : v > hi ? hi : v)
+
+/* CSS-style cubic-bezier easing: bisect for the parameter s where the
+ * bezier's x(s) ≈ t, then return y(s). 30 iterations = sub-pixel. */
+function cubicBezier(x1, y1, x2, y2, t) {
+  if (t <= 0) return 0
+  if (t >= 1) return 1
+  let lo = 0, hi = 1
+  for (let i = 0; i < 30; i++) {
+    const s = (lo + hi) / 2
+    const oneMs = 1 - s
+    const x = 3 * oneMs * oneMs * s * x1 + 3 * oneMs * s * s * x2 + s * s * s
+    if (x < t) lo = s
+    else       hi = s
+  }
+  const s = (lo + hi) / 2
+  const oneMs = 1 - s
+  return 3 * oneMs * oneMs * s * y1 + 3 * oneMs * s * s * y2 + s * s * s
+}
+
+function curveBlend(t, curve, blend, cp1, cp2) {
+  const bias = (blend - 0.5) * 2
+  switch (curve) {
+    case 'linear':   return clamp(t + bias)
+    case 'reverse':  return clamp((1 - t) + bias)
+    case 'ease':     return clamp((t < 0.5 ? 2 * t * t : 1 - 2 * (1 - t) * (1 - t)) + bias)
+    case 'expo-in':  return clamp(Math.pow(t, 3) + bias)
+    case 'expo-out': return clamp(1 - Math.pow(1 - t, 3) + bias)
+    case 'log':      return clamp(Math.log(1 + t * 9) / Math.log(10) + bias)
+    case 'sine':     return 0.5 + 0.5 * Math.sin((t + blend) * TAU)
+    case 'custom':   return clamp(cubicBezier(cp1.x, cp1.y, cp2.x, cp2.y, t) + bias)
+    case 'flat':
+    default:         return blend
+  }
+}
+
+const SAMPLES = 48
+/* Retokened from the app's `--ui-warning` accent yellow: the overlay
+ * stroke is the theme's editor-accent role, not a warning state. */
+const STROKE = 'var(--kol-accent-primary)'
+
+function sampleCurve(width, height, curve, blend, cp1, cp2, easing) {
+  const pts = []
+  for (let i = 0; i < SAMPLES; i++) {
+    const t = i / (SAMPLES - 1)
+    const v = clamp(easing ? easing(t) : curveBlend(t, curve, blend, cp1, cp2))
+    pts.push({ x: t * width, y: (1 - v) * height })
+  }
+  return pts
+}
+
+/* Draggable control-point dot. The SVG root is pointer-events:none;
+ * only these opt back in, so a parent drag system hit-tests them via
+ * their stable data-role. Outline is `--kol-surface-primary` (was
+ * literal white) so the contrast ring holds in both themes. */
+function Handle({ cx, cy, role }) {
+  return (
+    <circle
+      data-role={role}
+      cx={cx}
+      cy={cy}
+      r="6"
+      fill={STROKE}
+      stroke="var(--kol-surface-primary)"
+      strokeWidth="1.5"
+      style={{ cursor: 'grab', pointerEvents: 'auto' }}
+    />
+  )
+}
+
+/**
+ * CurveOverlay — SVG easing/curve visualizer laid absolutely over a frame:
+ * a dashed accent curve with endpoint dots, and — in `curve="custom"`
+ * mode — a two-handle cubic-bezier editor (Figma/After-Effects style)
+ * with tangent lines back to the anchored endpoints.
+ *
+ * Store-free and render-only: the root is pointer-events-none; only the
+ * two handles accept pointers, carrying data-role="curve-cp1"/"curve-cp2"
+ * so a PARENT drag system picks them up, maps pointer → normalized cp and
+ * passes it back down. Coordinates: x = t·width; y is inverted
+ * (y = (1-v)·height) so value 0 sits at the bottom, 1 at the top —
+ * endpoints are anchored at (0, height) and (width, 0). The svg gets a
+ * useId-derived id so per-instance [data-role] queries can be scoped
+ * (`#id [data-role=…]` — CSS.escape the id, useId contains colons).
+ *
+ * Built-in presets are ported curve math ('flat' | 'linear' | 'reverse' |
+ * 'ease' | 'expo-in' | 'expo-out' | 'log' | 'sine'); pass `easing` to make
+ * the primitive math-agnostic instead.
+ *
+ * @param {number}   width   frame width in px — viewBox width, x-scale
+ * @param {number}   height  frame height in px — viewBox height, y-scale
+ * @param {string}   curve   'custom' → bezier path + handles; else preset name
+ * @param {number}   blend   0..1 curve amount for presets (0.5 = pure curve)
+ * @param {Object}   cp1     {x,y} normalized 0..1 first control point (custom)
+ * @param {Object}   cp2     {x,y} normalized 0..1 second control point (custom)
+ * @param {Function} easing  (t)=>v sampler overriding the built-in presets
+ */
+export default function CurveOverlay({
+  width,
+  height,
+  curve = 'linear',
+  blend = 0.5,
+  cp1,
+  cp2,
+  easing,
+}) {
+  const id = useId()
+  const isCustom = curve === 'custom'
+
+  /* Endpoints stay anchored; only the two control points slide. */
+  const cp1Px = isCustom ? { x: cp1.x * width, y: (1 - cp1.y) * height } : null
+  const cp2Px = isCustom ? { x: cp2.x * width, y: (1 - cp2.y) * height } : null
+
+  const pts = isCustom ? null : sampleCurve(width, height, curve, blend, cp1, cp2, easing)
+  const polylinePoints = pts
+    ? pts.map((p) => `${p.x.toFixed(1)},${p.y.toFixed(1)}`).join(' ')
+    : null
+
+  /* Custom curve: a true cubic path instead of a sampled polyline. */
+  const cubicPath = isCustom
+    ? `M0 ${height.toFixed(1)} C ${cp1Px.x.toFixed(1)} ${cp1Px.y.toFixed(1)}, ${cp2Px.x.toFixed(1)} ${cp2Px.y.toFixed(1)}, ${width.toFixed(1)} 0`
+    : null
+
+  return (
+    <svg
+      id={id}
+      aria-hidden
+      width={width}
+      height={height}
+      viewBox={`0 0 ${width} ${height}`}
+      className="absolute left-0 top-0 overflow-visible pointer-events-none"
+      style={{ zIndex: 3 }}
+    >
+      {isCustom ? (
+        <>
+          <path
+            d={cubicPath}
+            fill="none"
+            stroke={STROKE}
+            strokeWidth="1.5"
+            strokeDasharray="4 3"
+            opacity="0.85"
+          />
+          {/* Tangent lines from endpoints to control points. */}
+          <line x1="0" y1={height} x2={cp1Px.x} y2={cp1Px.y} stroke={STROKE} strokeWidth="1" opacity="0.45" />
+          <line x1={width} y1="0" x2={cp2Px.x} y2={cp2Px.y} stroke={STROKE} strokeWidth="1" opacity="0.45" />
+          <circle cx="0" cy={height} r="3" fill={STROKE} opacity="0.85" />
+          <circle cx={width} cy="0" r="3" fill={STROKE} opacity="0.85" />
+          <Handle cx={cp1Px.x} cy={cp1Px.y} role="curve-cp1" />
+          <Handle cx={cp2Px.x} cy={cp2Px.y} role="curve-cp2" />
+        </>
+      ) : (
+        <>
+          <polyline
+            points={polylinePoints}
+            fill="none"
+            stroke={STROKE}
+            strokeWidth="1.5"
+            strokeDasharray="4 3"
+            opacity="0.85"
+          />
+          <circle cx={pts[0].x} cy={pts[0].y} r="3" fill={STROKE} opacity="0.85" />
+          <circle cx={pts[pts.length - 1].x} cy={pts[pts.length - 1].y} r="3" fill={STROKE} opacity="0.85" />
+        </>
+      )}
+    </svg>
+  )
+}

package/src/atoms/DocsToc.jsx

@@ -0,0 +1,48 @@
+import useScrollSpy from '../hooks/useScrollSpy.js'
+
+/* taxonomy-ok: atoms despite being interactive — it composes only the
+ * useScrollSpy hook, and hooks don't count as nesting; no KOL component
+ * is rendered (nav + anchors only). */
+
+/**
+ * DocsToc — on-page table of contents for long docs pages: a flat list of
+ * anchor links that highlights the heading currently in view. The scroll
+ * spy is useScrollSpy (IntersectionObserver + edge lock); this component
+ * only renders the nav and maps the active id onto the links.
+ *
+ * A matching in-page element must exist for every `toc` id — the spy
+ * observes `document.getElementById(id)`. Clicking a link sets the browser
+ * hash natively; `onNavigate` lets the consumer hook the click (prevent
+ * default, smooth-scroll, close a mobile drawer). Labels render verbatim —
+ * casing is authored at the call site.
+ *
+ * @param {Array<{id: string, label: string}>} toc  headings to render + observe
+ * @param {Function} onNavigate  (event) => void — optional click handler on every link
+ * @param {string}   rootMargin  IntersectionObserver rootMargin passed to the
+ *                               spy. Default keeps the ported source's tighter
+ *                               top band (useScrollSpy's own default is
+ *                               '-30% 0px -60% 0px')
+ */
+export default function DocsToc({ toc, onNavigate, rootMargin = '-80px 0px -80% 0px' }) {
+  const activeId = useScrollSpy(toc.map((item) => item.id), { rootMargin })
+
+  return (
+    <nav>
+      <ul className="space-y-0">
+        {toc.map((item) => (
+          <li key={item.id}>
+            <a
+              href={`#${item.id}`}
+              onClick={onNavigate}
+              className={`kol-mono-12 block rounded py-1 transition-colors focus-visible:ring-focus hover:text-fg-96 ${
+                activeId === item.id ? 'text-fg-96' : 'text-fg-64'
+              }`}
+            >
+              {item.label}
+            </a>
+          </li>
+        ))}
+      </ul>
+    </nav>
+  )
+}

package/src/{molecules → atoms}/DropdownTagFilter.jsx

@@ -16,9 +16,10 @@ const DropdownTagFilter = ({
   selectedValues = new Set(),
   onChange,
   className = '',
+  defaultOpen = false,
   size
 }) => {
-  const [isOpen, setIsOpen] = useState(false)
+  const [isOpen, setIsOpen] = useState(defaultOpen)
   const dropdownRef = useRef(null)
   const [resolvedSize, setResolvedSize] = useState('md')
 

package/src/atoms/EmptyState.jsx

@@ -0,0 +1,22 @@
+/**
+ * EmptyState — a stacked "nothing here yet / nothing selected" text block
+ * for inspectors, empty rails and unshipped panels. Ported from the brand
+ * editor's inspector Placeholder (renamed: AssetPlaceholder already owns
+ * the placeholder name). All lines render as authored — no auto casing
+ * (the source's `uppercase` on the eyebrow was dropped per KOL rules).
+ *
+ * @param {string} eyebrow  kicker line above the title
+ * @param {string} title    headline
+ * @param {string} body     optional supporting line
+ * @param {string} footer   optional note above a top hairline
+ */
+export default function EmptyState({ eyebrow, title, body, footer }) {
+  return (
+    <div>
+      {eyebrow && <p className="kol-helper-10 text-meta mb-1">{eyebrow}</p>}
+      {title && <p className="kol-helper-16 text-emphasis mb-3">{title}</p>}
+      {body && <p className="kol-sans-body-03 text-body mb-4">{body}</p>}
+      {footer && <p className="kol-helper-12 text-meta pt-3 border-t border-fg-08">{footer}</p>}
+    </div>
+  )
+}

package/src/atoms/Figure.jsx

@@ -0,0 +1,27 @@
+/**
+ * Figure — the shared caption'd media shell for long-form prose: optional
+ * label above, an aspect-locked bordered frame around `children`, optional
+ * figcaption below. ImageBlock and VideoBlock (and the portable-text image
+ * renderer) all compose this one shell.
+ *
+ * Aspect is an inline style (not aspect-[x/y]) so any ratio works without
+ * Tailwind needing to see the class. Pass aspect="" for natural height.
+ *
+ * @param {string} label    small mono label above the frame
+ * @param {string} caption  figcaption below the frame
+ * @param {string} aspect   CSS aspect-ratio value, e.g. '5/3' (default)
+ */
+export default function Figure({ label, caption, aspect = '5/3', className = '', children }) {
+  return (
+    <figure className={`kol-prose-figure ${className}`.trim()}>
+      {label && <div className="kol-caption-label">{label}</div>}
+      <div
+        className="border border-fg-08 rounded overflow-hidden"
+        style={aspect ? { aspectRatio: aspect } : undefined}
+      >
+        {children}
+      </div>
+      {caption && <figcaption className="kol-caption-text">{caption}</figcaption>}
+    </figure>
+  )
+}