{ "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "context-compaction-river", "title": "Context Compaction River", "description": "Context compaction drawn as a meandering river: live turns are points on one curving channel, and a compacted run of turns necks off into a reopenable, re-injectable oxbow lake sitting 12px off the channel.", "dependencies": [], "files": [ { "path": "registry/core/context-compaction-river/component.tsx", "content": "\"use client\";\n\nimport { useEffect, useId, useMemo, useRef, useState, type KeyboardEvent as ReactKeyboardEvent } from \"react\";\n\n// OxbowTurn — the live conversation drawn as one meandering channel in a\n// side rail. Every live turn is a point the channel passes through; the\n// curve itself is decorative (aria-hidden SVG) and carries no information a\n// screen reader needs, because the same facts live as plain text in a real\n// list right below it (\"Live context, N turns\" / \"Compacted: turns 3-9,\n// summarized 2 minutes ago\").\n//\n// When turns get folded into a summary, the component doesn't just drop a\n// row — the compaction keeps its own place in the sequence, and the channel\n// simply stops routing through it: the surviving points ease toward their\n// new (tighter) spacing over ~300ms, which is what \"the river gets shorter\"\n// looks like here, while the folded turns settle 12px off the channel as a\n// closed oxbow-lake shape carrying a token-count chip. That chip is a real,\n// focusable button (never aria-hidden) — opening it reveals the summary and\n// a re-inject action in a role=menu popover. Re-inject animates the lake\n// back onto the channel before the prop change actually removes it, so nothing\n// is left to imagination between \"click\" and \"the turns are back\".\n//\n// The trigger is deliberately open-only (a second click does not close it —\n// only Escape, an outside click, or choosing the menu item does). That is\n// what keeps a synthetic \"press\" pass (which clicks the first control once,\n// unconditionally) and a later scripted \"open this\" check from fighting over\n// the same toggle.\n//\n// Positions are computed from each item's index in the full sequence (turn\n// or compaction alike), so a compaction never needs its own bookkeeping of\n// \"where it used to be\" — it already has a slot. Turn dots and the channel\n// path animate via a direct rAF loop (setAttribute only, no React state on\n// the hot path, sleeps once settled) exactly like this repo's other\n// spring-driven diagrams. Everything else (the oxbow's 12px settle, its\n// entrance/exit) is a plain CSS transform+opacity transition, which reduced\n// motion turns off wholesale in favor of an instant fade-and-move.\n\nexport type OxbowTurnEntry = {\n id: string;\n /** short label, e.g. a turn number — used to build \"turns 3-9\" range text */\n label: string;\n};\n\nexport type OxbowTurnItem =\n | { kind: \"turn\"; id: string; label: string; preview?: string }\n | {\n kind: \"compaction\";\n id: string;\n /** the turns folded into this oxbow, oldest -> newest */\n turns: OxbowTurnEntry[];\n summary: string;\n tokenCount: number;\n /** precomputed, e.g. \"2 minutes ago\" — this component never touches the clock */\n compactedAgo: string;\n };\n\nexport interface OxbowTurnProps {\n /** the full ordered sequence: live turns and compaction (oxbow) entries, interleaved */\n items: OxbowTurnItem[];\n /** fired once a re-inject has finished animating back onto the channel */\n onReinject?: (compactionId: string) => void;\n ariaLabel?: string;\n className?: string;\n}\n\nconst ROW_H = 38;\nconst PAD_Y = 18;\nconst CX = 30; // channel centerline, px from the rail's left edge\nconst AMP1 = 11;\nconst AMP2 = 5;\nconst OFFSET = 12; // brief's \"12px off-channel\"\nconst DOT_R = 3;\nconst EASE_RATE = 0.24; // per-frame lerp toward target, ~300ms settle at 60fps\nconst SETTLE_EPS = 0.04;\nconst RAIL_W = 236;\n\ntype Pt = { x: number; y: number };\n\nfunction channelX(row: number): number {\n return CX + AMP1 * Math.sin(row * 0.85) + AMP2 * Math.sin(row * 1.9 + 1.3);\n}\n\nfunction rowY(row: number): number {\n return PAD_Y + row * ROW_H;\n}\n\n/** Catmull-Rom through `pts`, converted to cubic beziers (tension/6 form). */\nfunction smoothPath(pts: Pt[]): string {\n if (pts.length === 0) return \"\";\n if (pts.length === 1) return `M ${pts[0].x} ${pts[0].y}`;\n let d = `M ${pts[0].x} ${pts[0].y}`;\n for (let i = 0; i < pts.length - 1; i++) {\n const p0 = pts[i - 1] ?? pts[i];\n const p1 = pts[i];\n const p2 = pts[i + 1];\n const p3 = pts[i + 2] ?? p2;\n const c1x = p1.x + (p2.x - p0.x) / 6;\n const c1y = p1.y + (p2.y - p0.y) / 6;\n const c2x = p2.x - (p3.x - p1.x) / 6;\n const c2y = p2.y - (p3.y - p1.y) / 6;\n d += ` C ${c1x} ${c1y}, ${c2x} ${c2y}, ${p2.x} ${p2.y}`;\n }\n return d;\n}\n\nfunction formatTok(n: number): string {\n return Math.round(Math.max(0, n)).toLocaleString(\"en-US\");\n}\n\nfunction turnsLabel(turns: OxbowTurnEntry[]): string {\n if (turns.length === 0) return \"no turns\";\n if (turns.length === 1) return `turn ${turns[0].label}`;\n return `turns ${turns[0].label}–${turns[turns.length - 1].label}`;\n}\n\ntype TurnPoint = { id: string; x: number; y: number; label: string; preview?: string; isLast: boolean };\ntype LakeRow = { id: string; item: Extract; x: number; y: number };\n\nfunction layout(items: OxbowTurnItem[]): { turns: TurnPoint[]; lakes: LakeRow[] } {\n const turns: TurnPoint[] = [];\n const lakes: LakeRow[] = [];\n items.forEach((it, row) => {\n const x = channelX(row);\n const y = rowY(row);\n if (it.kind === \"turn\") {\n turns.push({ id: it.id, x, y, label: it.label, preview: it.preview, isLast: false });\n } else {\n lakes.push({ id: it.id, item: it, x, y });\n }\n });\n if (turns.length > 0) turns[turns.length - 1].isLast = true;\n return { turns, lakes };\n}\n\nexport function OxbowTurn({\n items,\n onReinject,\n ariaLabel = \"Context compaction history\",\n className = \"\",\n}: OxbowTurnProps) {\n const rawId = useId();\n const fid = rawId.replace(/[^a-zA-Z0-9-]/g, \"\");\n\n const [reduced, setReduced] = useState(false);\n const [openId, setOpenId] = useState(null);\n const [enterState, setEnterState] = useState>({});\n const [exitingIds, setExitingIds] = useState>({});\n const [snap, setSnap] = useState(false);\n const [liveMsg, setLiveMsg] = useState(\"\");\n\n const wrapRef = useRef(null);\n const popRef = useRef(null);\n const triggerRefs = useRef>(new Map());\n const pathElRef = useRef(null);\n const dotElsRef = useRef>(new Map());\n const dotWrapElsRef = useRef>(new Map());\n const posRef = useRef>(new Map());\n const prevCompactionIdsRef = useRef>(new Set());\n const cleanupsRef = useRef void>>([]);\n\n useEffect(() => {\n const mq = window.matchMedia(\"(prefers-reduced-motion: reduce)\");\n setReduced(mq.matches);\n const onChange = () => setReduced(mq.matches);\n mq.addEventListener(\"change\", onChange);\n return () => mq.removeEventListener(\"change\", onChange);\n }, []);\n\n useEffect(() => () => {\n for (const cancel of cleanupsRef.current) cancel();\n cleanupsRef.current = [];\n }, []);\n\n const { turns: turnTargets, lakes: lakeRows } = useMemo(() => layout(items), [items]);\n const H = Math.max(PAD_Y * 2, PAD_Y * 2 + Math.max(0, items.length - 1) * ROW_H);\n\n const [initialD] = useState(() => smoothPath(layout(items).turns.map((t) => ({ x: t.x, y: t.y }))));\n\n // channel + turn-dot animation: direct DOM writes, no React state on the hot path\n useEffect(() => {\n const targetMap = new Map(turnTargets.map((t) => [t.id, { x: t.x, y: t.y }]));\n for (const id of Array.from(posRef.current.keys())) {\n if (!targetMap.has(id)) posRef.current.delete(id);\n }\n\n if (reduced) {\n for (const t of turnTargets) {\n posRef.current.set(t.id, { x: t.x, y: t.y });\n const el = dotElsRef.current.get(t.id);\n el?.setAttribute(\"cx\", String(t.x));\n el?.setAttribute(\"cy\", String(t.y));\n const wrapEl = dotWrapElsRef.current.get(t.id);\n if (wrapEl) {\n wrapEl.style.left = `${t.x}px`;\n wrapEl.style.top = `${t.y}px`;\n }\n }\n pathElRef.current?.setAttribute(\"d\", smoothPath(turnTargets.map((t) => ({ x: t.x, y: t.y }))));\n return;\n }\n\n let raf = 0;\n const step = () => {\n let moving = false;\n const pts: Pt[] = [];\n for (const t of turnTargets) {\n const cur = posRef.current.get(t.id) ?? { x: t.x, y: t.y };\n const nx = cur.x + (t.x - cur.x) * EASE_RATE;\n const ny = cur.y + (t.y - cur.y) * EASE_RATE;\n if (Math.abs(t.x - nx) > SETTLE_EPS || Math.abs(t.y - ny) > SETTLE_EPS) moving = true;\n posRef.current.set(t.id, { x: nx, y: ny });\n pts.push({ x: nx, y: ny });\n const el = dotElsRef.current.get(t.id);\n el?.setAttribute(\"cx\", String(nx));\n el?.setAttribute(\"cy\", String(ny));\n const wrapEl = dotWrapElsRef.current.get(t.id);\n if (wrapEl) {\n wrapEl.style.left = `${nx}px`;\n wrapEl.style.top = `${ny}px`;\n }\n }\n pathElRef.current?.setAttribute(\"d\", smoothPath(pts));\n if (moving) raf = requestAnimationFrame(step);\n };\n raf = requestAnimationFrame(step);\n return () => cancelAnimationFrame(raf);\n }, [turnTargets, reduced]);\n\n // compaction enter + aria-live announcements\n useEffect(() => {\n const curIds = new Set(lakeRows.map((l) => l.id));\n const prevIds = prevCompactionIdsRef.current;\n const added = lakeRows.filter((l) => !prevIds.has(l.id));\n const removedCount = Array.from(prevIds).filter((id) => !curIds.has(id)).length;\n\n if (added.length > 0) {\n if (!reduced) {\n setEnterState((s) => {\n const next = { ...s };\n for (const l of added) next[l.id] = \"start\";\n return next;\n });\n const raf1 = requestAnimationFrame(() => {\n const raf2 = requestAnimationFrame(() => {\n setEnterState((s) => {\n const next = { ...s };\n for (const l of added) if (next[l.id] === \"start\") next[l.id] = \"end\";\n return next;\n });\n });\n cleanupsRef.current.push(() => cancelAnimationFrame(raf2));\n });\n cleanupsRef.current.push(() => cancelAnimationFrame(raf1));\n }\n const first = added[0];\n setLiveMsg(\n `Compacted ${turnsLabel(first.item.turns)} into a ${formatTok(first.item.tokenCount)}-token summary.`\n );\n if (!reduced) {\n setSnap(true);\n const t = window.setTimeout(() => setSnap(false), 320);\n cleanupsRef.current.push(() => window.clearTimeout(t));\n }\n } else if (removedCount > 0 && added.length === 0) {\n // a removal this component didn't itself animate (e.g. reset) — still announce\n setLiveMsg(\"Re-injected turns back into live context.\");\n }\n prevCompactionIdsRef.current = curIds;\n }, [lakeRows, reduced]);\n\n // outside click closes the open popover\n useEffect(() => {\n if (!openId) return;\n const onDown = (e: PointerEvent) => {\n const target = e.target as Node;\n if (popRef.current?.contains(target)) return;\n if (triggerRefs.current.get(openId)?.contains(target)) return;\n setOpenId(null);\n };\n document.addEventListener(\"pointerdown\", onDown);\n return () => document.removeEventListener(\"pointerdown\", onDown);\n }, [openId]);\n\n // focus the summary when a popover opens\n useEffect(() => {\n if (!openId) return;\n const raf = requestAnimationFrame(() => {\n popRef.current?.querySelector(\"[data-oxbow-summary]\")?.focus({ preventScroll: true });\n });\n return () => cancelAnimationFrame(raf);\n }, [openId]);\n\n const closeAndReturnFocus = (id: string) => {\n setOpenId(null);\n triggerRefs.current.get(id)?.focus({ preventScroll: true });\n };\n\n const handleReinject = (l: LakeRow) => {\n if (reduced) {\n setOpenId(null);\n onReinject?.(l.id);\n return;\n }\n setOpenId(null);\n setExitingIds((s) => ({ ...s, [l.id]: true }));\n const t = window.setTimeout(() => {\n onReinject?.(l.id);\n setExitingIds((s) => {\n const next = { ...s };\n delete next[l.id];\n return next;\n });\n }, 260);\n cleanupsRef.current.push(() => window.clearTimeout(t));\n };\n\n const onTriggerKeyDown = (l: LakeRow) => (e: ReactKeyboardEvent) => {\n if (e.key === \"ArrowDown\" && openId !== l.id) {\n e.preventDefault();\n setOpenId(l.id);\n }\n };\n\n const onMenuKeyDown = (l: LakeRow) => (e: ReactKeyboardEvent) => {\n if (e.key === \"Escape\") {\n e.preventDefault();\n closeAndReturnFocus(l.id);\n return;\n }\n if (e.key === \"Tab\") {\n setOpenId(null);\n return;\n }\n const items_ = Array.from(e.currentTarget.querySelectorAll('[role=\"menuitem\"]'));\n if (items_.length === 0) return;\n const idx = items_.indexOf(document.activeElement as HTMLElement);\n let next = -1;\n if (e.key === \"ArrowDown\") next = (idx + 1) % items_.length;\n else if (e.key === \"ArrowUp\") next = idx < 0 ? items_.length - 1 : (idx - 1 + items_.length) % items_.length;\n else if (e.key === \"Home\") next = 0;\n else if (e.key === \"End\") next = items_.length - 1;\n if (next >= 0) {\n e.preventDefault();\n items_[next]?.focus({ preventScroll: true });\n }\n };\n\n const turnCount = turnTargets.length;\n\n return (\n
\n \n\n
\n \n \n\n {lakeRows.map((l) => {\n const state = exitingIds[l.id] ? \"exiting\" : enterState[l.id] === \"start\" ? \"entering\" : \"settled\";\n return (\n \n {/* animated as one rigid unit: at rest (translateX 12) this spans exactly\n anchor -> ellipse edge; the stub's own local span is kept constant so\n sliding the group is what \"grows the neck into place\" looks like */}\n \n \n \n \n \n );\n })}\n\n {turnTargets.map((t) => (\n {\n if (el) {\n dotElsRef.current.set(t.id, el);\n if (!posRef.current.has(t.id)) {\n el.setAttribute(\"cx\", String(t.x));\n el.setAttribute(\"cy\", String(t.y));\n posRef.current.set(t.id, { x: t.x, y: t.y });\n }\n } else {\n dotElsRef.current.delete(t.id);\n }\n }}\n r={t.isLast ? DOT_R + 1 : DOT_R}\n className={t.isLast ? \"ns-oxbow-dot-current\" : \"ns-oxbow-dot\"}\n fill={t.isLast ? undefined : \"var(--muted)\"}\n >\n {t.preview ? `${t.label}: ${t.preview}` : t.label}\n \n ))}\n \n\n {/* real interactive targets for the (decorative, aria-hidden) turn dots above:\n positioned by the same rAF loop that drives the SVG circles (dotWrapElsRef),\n so the hit target and its tooltip track the easing motion instead of a\n React-controlled left/top that would snap ahead of the circle it sits on */}\n {turnTargets.map((t) => {\n const turnTipId = `${fid}-turn-tip-${t.id}`;\n const hasPreview = Boolean(t.preview);\n const accName = hasPreview ? `Turn ${t.label}: ${t.preview}` : `Turn ${t.label}`;\n return (\n {\n if (el) {\n dotWrapElsRef.current.set(t.id, el);\n const cur = posRef.current.get(t.id) ?? { x: t.x, y: t.y };\n el.style.left = `${cur.x}px`;\n el.style.top = `${cur.y}px`;\n } else {\n dotWrapElsRef.current.delete(t.id);\n }\n }}\n className=\"absolute -translate-x-1/2 -translate-y-1/2\"\n >\n \n {hasPreview && (\n \n Turn {t.label}: {t.preview}\n \n )}\n
\n );\n })}\n\n {lakeRows.map((l) => {\n const state = exitingIds[l.id] ? \"exiting\" : enterState[l.id] === \"start\" ? \"entering\" : \"settled\";\n const isOpen = openId === l.id;\n const menuId = `${fid}-menu-${l.id}`;\n const tipId = `${fid}-tip-${l.id}`;\n return (\n \n {\n if (el) triggerRefs.current.set(l.id, el);\n else triggerRefs.current.delete(l.id);\n }}\n type=\"button\"\n data-oxbow-trigger\n aria-haspopup=\"menu\"\n aria-expanded={isOpen}\n aria-controls={isOpen ? menuId : undefined}\n aria-describedby={!isOpen ? tipId : undefined}\n aria-label={`Compacted ${turnsLabel(l.item.turns)}, ${formatTok(l.item.tokenCount)} tokens. Open summary and re-inject.`}\n onClick={() => setOpenId(l.id)}\n onKeyDown={onTriggerKeyDown(l)}\n className=\"flex cursor-pointer items-center gap-1.5 whitespace-nowrap rounded-full border border-border px-2.5 py-1 font-mono text-[10px] tracking-wide text-muted transition-colors duration-150 hover:border-foreground/30 hover:text-foreground focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-accent\"\n style={{ background: \"color-mix(in srgb, var(--foreground) 4%, var(--background))\" }}\n >\n {l.item.turns.length}↩\n {formatTok(l.item.tokenCount)} tok\n \n\n {!isOpen && (\n \n {turnsLabel(l.item.turns)} pinched off the channel · re-injectable\n \n )}\n\n {isOpen && (\n \n \n {l.item.summary}\n

\n
\n
\n
Turns
\n
{turnsLabel(l.item.turns)}
\n
\n
\n
Summarized
\n
{l.item.compactedAgo}
\n
\n
\n
Tokens
\n
{formatTok(l.item.tokenCount)}
\n
\n
\n \n handleReinject(l)}\n className=\"w-full cursor-pointer rounded-sm px-2 py-1.5 text-left text-xs text-foreground transition-colors hover:bg-[color-mix(in_srgb,var(--foreground)_6%,transparent)] focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-accent\"\n >\n Re-inject into live context\n \n
\n \n )}\n \n );\n })}\n \n\n
    \n
  • \n Live context, {turnCount} turn{turnCount === 1 ? \"\" : \"s\"}\n
    • \n {lakeRows.map((l) => (\n
  • \n Compacted: {turnsLabel(l.item.turns)}, summarized {l.item.compactedAgo}\n
    • \n ))}\n
\n\n

\n {liveMsg}\n

\n \n );\n}\n", "type": "registry:ui", "target": "components/ui/context-compaction-river.tsx" } ], "meta": { "collection": "core", "tags": [ "context-window", "compaction", "agent", "llm", "svg", "diagram", "history", "mono", "menu", "undo", "accessibility" ], "instruction": "OxbowTurn draws the live conversation as one gently meandering channel in a side rail: a controlled `items` prop is a single ordered sequence of turn entries and compaction entries, and every entry — of either kind — gets one row slot, spaced evenly down the rail. Turn entries are plotted as points on the channel (x from a deterministic two-harmonic sine so the curve reads as organic without any randomness or physics sim); a fresh Catmull-Rom-to-bezier pass through only the turn points draws the channel path. Compaction entries do not contribute a channel point at all, so when a run of turns gets folded into one compaction, the channel simply stops routing through that stretch — the surviving points ease toward their new, tighter spacing over roughly 300ms (a direct rAF loop writing cx/cy/d via setAttribute, no React state on the hot path, sleeping once settled, in the same idiom as this registry's other spring-driven diagrams), which is what 'compaction shortens the river' looks like here. The folded turns settle as a closed oxbow-lake shape — a small filled loop (`color-mix(in srgb, var(--border) 6%, transparent)` fill, `--border` stroke) plus a short connecting stub, both purely decorative and `aria-hidden` — 12px off the channel, animated in on a 300ms cubic-bezier(0.16,1,0.3,1) transform+opacity transition (ease-out-expo) the instant the compaction first appears in `items`. Carried on the lake is a real, always-focusable Geist Mono token-count chip (`{turnsFolded}↩ {tokenCount} tok`, never `aria-hidden`) — clicking it opens a small popover with the plain-language summary, a turns/summarized-at/token-count `
`, and a `role=menu` containing one `role=menuitem`: 're-inject into live context'. Choosing it drifts the lake back onto the channel (reverse transition, ~260ms) before the `onReinject(id)` callback actually fires and the consumer's state update splices the folded turns back into `items` as live turns again — nothing is removed from view until the return trip has finished playing, and a brief stroke-width pulse on the channel marks the splice. The chip trigger is deliberately open-only: a second click while already open is a no-op (only Escape, an outside click, or choosing the menu item closes it), so a scripted 'click the first control' pass and a later 'now click this same control and expect it open' check never fight over the same toggle. Hovering or focusing the chip (without clicking) also reveals a small, token-styled tooltip above it — 'turns {a}–{b} pinched off the channel · re-injectable' — so a user can preview a branch point before committing to opening the full menu; it's wired via `aria-describedby` and hides once the menu is open. The drawing (channel, dots, lake shapes) is entirely `aria-hidden` and carries zero information a screen reader needs beyond redundancy — the actual facts live as plain, always-visible text in a real list right below it: 'Live context, {n} turns' plus one 'Compacted: turns {a}–{b}, summarized {when}' line per oxbow, and every compaction/re-injection additionally announces itself through an `aria-live=polite` region ('Compacted turns 3–9 into a 1,840-token summary.' / re-inject's own announcement). Each turn dot also gets a real, invisible interactive target overlaid on top of it (an unstyled focusable `