@voltro/ui-shadcn 0.66.1 → 0.68.0

package/src/compositions/docsLayout.tsx

@@ -16,7 +16,7 @@
 // (callouts, code blocks, steps) are siblings of this file and
 // composable in any combination.
 
-import { useEffect, useState, type ComponentType, type ReactNode } from 'react'
+import { useEffect, useRef, useState, type ComponentType, type ReactNode } from 'react'
 import { cn } from '../cn'
 import type { ShellLinkProps } from './docShell'
 import { ChevronLeftIcon, ChevronRightIcon } from '../primitives/docIcons'
@@ -121,6 +121,12 @@ interface DocsLayoutProps {
   readonly brand: ReactNode
   readonly nav: ReadonlyArray<DocsNavGroup>
   readonly children: ReactNode
+  /** Compose the top bar while retaining the layout's mobile navigation control. */
+  readonly header?: (controls: { readonly menuButton: ReactNode }) => ReactNode
+  /** Full-width introduction above the reading columns. */
+  readonly intro?: ReactNode
+  /** Show the desktop section rail. Mobile navigation remains available. */
+  readonly sidebar?: boolean
   /** Current pathname — used to highlight the active nav entry +
    *  decide which group opens by default. */
   readonly currentPath?: string
@@ -200,7 +206,7 @@ const NavLeaf = ({
 }): ReactNode => {
   const active = isActiveHref(entry.href, currentPath)
   return (
-    <li>
+    <li data-docs-active={active}>
       <Link to={entry.href} prefetch className={cn(NAV_ROW, 'block', navRowColor(active))}>
         <span className="inline-flex items-center gap-2">
           {entry.label}
@@ -454,13 +460,32 @@ const Breadcrumbs = ({
 export const DocsLayout = ({
   brand, nav, children, currentPath, topNav, topRight, search,
   page, LinkComponent = PlainLink, className, labels, footer, sidebarHeader,
+  header, intro, sidebar = true,
 }: DocsLayoutProps): ReactNode => {
   const Link = LinkComponent
   const t = { ...DEFAULT_DOCS_LABELS, ...labels }
-  // Mobile drawer state — only the inline state, no portal/escape
-  // handling here; the search-trigger button can call setMobileOpen
-  // via a parent island when full cmd-k lands.
   const [mobileOpen, setMobileOpen] = useState(false)
+  const drawer = useRef<HTMLDialogElement>(null)
+  useEffect(() => {
+    const element = drawer.current
+    if (!element) return
+    if (mobileOpen && !element.open) element.showModal()
+    if (!mobileOpen && element.open) element.close()
+    if (!mobileOpen) return
+    const previousOverflow = document.body.style.overflow
+    document.body.style.overflow = 'hidden'
+    return () => { document.body.style.overflow = previousOverflow }
+  }, [mobileOpen])
+  useEffect(() => { setMobileOpen(false) }, [currentPath])
+  const menuButton = (
+    <button type="button" onClick={() => setMobileOpen(true)}
+      className="docs-menu-toggle md:hidden inline-flex items-center justify-center w-11 h-11 rounded-md hover:bg-card transition-colors"
+      aria-label={t.toggleMenu} aria-expanded={mobileOpen} aria-haspopup="dialog">
+      <svg width="18" height="18" viewBox="0 0 18 18" fill="none" aria-hidden="true">
+        <path d="M3 5 H15 M3 9 H15 M3 13 H15" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" />
+      </svg>
+    </button>
+  )
 
   return (
     <div className={cn('min-h-screen bg-background text-foreground', className)}>
@@ -468,19 +493,9 @@ export const DocsLayout = ({
        * sticky / max-width / h-16 / glass-on-scroll fade. The
        * children below define the docs-specific row: mobile menu,
        * brand, optional topNav, search, topRight slots. */}
-      <PageHeader>
+      {header ? header({ menuButton }) : <PageHeader>
         <div className="flex items-center gap-4 min-w-0 flex-1">
-          <button
-            type="button"
-            onClick={() => setMobileOpen(!mobileOpen)}
-            className="md:hidden inline-flex items-center justify-center w-8 h-8 rounded-md hover:bg-card transition-colors"
-            aria-label={t.toggleMenu}
-            aria-expanded={mobileOpen}
-          >
-            <svg width="18" height="18" viewBox="0 0 18 18" fill="none" aria-hidden="true">
-              <path d="M3 5 H15 M3 9 H15 M3 13 H15" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" />
-            </svg>
-          </button>
+          {menuButton}
           <div className="flex items-center gap-2 font-semibold">{brand}</div>
           {topNav ? <div className="hidden md:flex items-center gap-1 ml-4">{topNav}</div> : null}
         </div>
@@ -488,36 +503,43 @@ export const DocsLayout = ({
           {search ? <div className="hidden md:block">{search}</div> : null}
           {topRight ? <div className="flex items-center gap-1">{topRight}</div> : null}
         </div>
-      </PageHeader>
+      </PageHeader>}
 
-      <div className="mx-auto max-w-7xl flex">
+      {intro}
+
+      <div className="docs-columns mx-auto max-w-7xl flex">
         {/* Sidebar (desktop) */}
-        <aside className="hidden md:block w-64 shrink-0 border-r border-border">
+        {sidebar ? <aside data-docs-sidebar className="hidden md:block w-64 shrink-0 border-r border-border">
           <div className="sticky top-16 max-h-[calc(100vh-4rem)] overflow-y-auto px-6 py-8">
             {sidebarHeader ? <div className="mb-6">{sidebarHeader}</div> : null}
             {nav.map((group) => (
               <SidebarGroup key={group.section} group={group} {...(currentPath ? { currentPath } : {})} Link={Link} />
             ))}
           </div>
-        </aside>
+        </aside> : null}
 
         {/* Sidebar (mobile drawer) */}
-        {mobileOpen ? (
-          <div className="md:hidden fixed inset-0 z-40 flex">
-            {/* Backdrop */}
-            <div
-              role="button"
-              aria-label={t.closeMenu}
-              className="flex-1 bg-background/70 backdrop-blur-sm"
-              onClick={() => setMobileOpen(false)}
-            />
-            <aside className="w-72 max-w-[80vw] bg-card border-l border-border overflow-y-auto px-6 py-6">
+        <dialog ref={drawer} aria-label={t.menu}
+          onCancel={() => setMobileOpen(false)} onClose={() => setMobileOpen(false)}
+          onKeyDown={event => {
+            if (event.key !== 'Tab') return
+            const controls = [...event.currentTarget.querySelectorAll<HTMLElement>('button:not([disabled]), a[href], select:not([disabled]), [tabindex="0"]')]
+            const first = controls[0]
+            const last = controls.at(-1)
+            if (event.shiftKey && document.activeElement === first) { event.preventDefault(); last?.focus() }
+            if (!event.shiftKey && document.activeElement === last) { event.preventDefault(); first?.focus() }
+          }}
+          onClick={event => { if (event.target === event.currentTarget) setMobileOpen(false) }}
+          className="docs-drawer m-0 ml-auto h-dvh max-h-dvh w-80 max-w-[90vw] border-0 border-l border-border bg-card text-foreground p-0 backdrop:bg-black/50">
+            {mobileOpen ? <div className="min-h-full px-6 py-6" onClick={event => {
+              if (event.target instanceof Element && event.target.closest('a[href]')) setMobileOpen(false)
+            }}>
               <div className="mb-4 flex items-center justify-between">
                 <span className="font-semibold">{t.menu}</span>
                 <button
                   type="button"
                   onClick={() => setMobileOpen(false)}
-                  className="inline-flex items-center justify-center w-7 h-7 rounded-md hover:bg-background transition-colors"
+                  className="inline-flex items-center justify-center w-11 h-11 rounded-md hover:bg-background transition-colors"
                   aria-label={t.close}
                 >
                   <svg width="14" height="14" viewBox="0 0 14 14" fill="none" aria-hidden="true">
@@ -529,9 +551,8 @@ export const DocsLayout = ({
               {nav.map((group) => (
                 <SidebarGroup key={group.section} group={group} {...(currentPath ? { currentPath } : {})} Link={Link} />
               ))}
-            </aside>
-          </div>
-        ) : null}
+            </div> : null}
+        </dialog>
 
         {/* Content + TOC */}
         <div className="flex-1 min-w-0 flex">

package/src/compositions/profileMenu.tsx

@@ -32,7 +32,7 @@ import {
 } from '../primitives/dropdownMenu'
 import { ToggleGroup, ToggleGroupItem } from '../primitives/toggleGroup'
 import {
-  THEME_COOKIE, LOCALE_COOKIE, getCookie, setCookie, deleteCookie, applyTheme,
+  THEME_COOKIE, THEME_CHANGE_EVENT, LOCALE_COOKIE, getCookie, setCookie, applyTheme,
   type ThemePreference,
 } from '../cookies'
 
@@ -43,10 +43,8 @@ const readStoredTheme = (): ThemePreference => {
 }
 
 const persistTheme = (choice: ThemePreference): void => {
-  // 'system' deletes the cookie so the next request falls back to
-  // server default / matchMedia (matches themeBootScript semantics).
-  if (choice === 'system') deleteCookie(THEME_COOKIE)
-  else setCookie(THEME_COOKIE, choice)
+  // Persist System explicitly so every appearance control reads the same choice.
+  setCookie(THEME_COOKIE, choice)
   applyTheme(choice)
 }
 
@@ -66,6 +64,8 @@ export interface ProfileMenuLanguage {
 }
 
 export interface ProfileMenuProps {
+  /** Custom accessible trigger; Radix supplies menu state and focus handling. */
+  readonly trigger?: ReactNode
   readonly identity?: {
     readonly name: string
     readonly sublabel?: string
@@ -146,7 +146,7 @@ const navigateTo = (href: string, external?: boolean): void => {
 
 export const ProfileMenu = ({
   identity, links, languages, currentLanguage, onLanguageChange,
-  logoutUrl, onLogout, signInUrl, labels,
+  logoutUrl, onLogout, signInUrl, labels, trigger,
 }: ProfileMenuProps): ReactNode => {
   const [theme, setTheme] = useState<ThemePreference | undefined>(undefined)
   // Hydrate language from cookie on mount; the prop overrides if set.
@@ -154,8 +154,11 @@ export const ProfileMenu = ({
   const locale = currentLanguage ?? cookieLocale
 
   useEffect(() => {
-    setTheme(readStoredTheme())
+    const refreshTheme = (): void => setTheme(readStoredTheme())
+    refreshTheme()
     setCookieLocale(getCookie(LOCALE_COOKIE) ?? undefined)
+    window.addEventListener(THEME_CHANGE_EVENT, refreshTheme)
+    return () => window.removeEventListener(THEME_CHANGE_EVENT, refreshTheme)
   }, [])
 
   const onThemeChange = useCallback((next: string): void => {
@@ -203,7 +206,7 @@ export const ProfileMenu = ({
   return (
     <DropdownMenu>
       <DropdownMenuTrigger asChild>
-        <Button
+        {trigger ?? <Button
           type="button"
           variant="outline"
           size="icon"
@@ -211,7 +214,7 @@ export const ProfileMenu = ({
           className="rounded-full size-8 text-muted-foreground hover:text-foreground"
         >
           <AvatarGlyph {...(initial ? { initial } : {})} />
-        </Button>
+        </Button>}
       </DropdownMenuTrigger>
 
       <DropdownMenuContent align="end" className="w-64">

package/src/compositions/signalControls.tsx

@@ -0,0 +1,43 @@
+import type { ComponentProps, ReactNode } from 'react'
+import { ProfileMenu, type ProfileMenuProps } from './profileMenu'
+import { SearchIcon } from '../primitives/docIcons'
+import { cn } from '../cn'
+
+export interface SignalPreferencesProps extends Omit<ProfileMenuProps, 'trigger' | 'labels' | 'languages' | 'currentLanguage'> {
+  readonly locale: 'en' | 'de'
+}
+
+/** One appearance/language entry point for public and operating Signal surfaces. */
+export function SignalPreferences({ locale, ...props }: SignalPreferencesProps): ReactNode {
+  const de = locale === 'de'
+  const label = de ? 'Darstellung und Sprache' : 'Appearance and language'
+  return <ProfileMenu {...props} currentLanguage={locale}
+    languages={[{ code: 'en', label: 'EN' }, { code: 'de', label: 'DE' }]}
+    labels={{ openMenu: label, theme: de ? 'Design' : 'Theme', language: de ? 'Sprache' : 'Language',
+      signIn: de ? 'Anmelden' : 'Sign in', signOut: de ? 'Abmelden' : 'Sign out',
+      themes: { system: 'System', light: de ? 'Hell' : 'Light', dark: de ? 'Dunkel' : 'Dark' } }}
+    trigger={<button type="button" className="signal-control signal-preferences" aria-label={label}>
+      <svg viewBox="0 0 24 24" aria-hidden="true"><circle cx="12" cy="12" r="8.5" /><path d="M3.5 12h17M12 3.5c4.5 4.5 4.5 12.5 0 17-4.5-4.5-4.5-12.5 0-17Z" /></svg>
+      <span>{props.identity?.name.trim().charAt(0).toUpperCase() ?? locale.toUpperCase()}</span>
+    </button>} />
+}
+
+export interface SignalSearchProps {
+  readonly label: string
+  readonly onOpen: () => void
+  readonly className?: string
+}
+
+/** Search is a command trigger, sized to the navigation rail with a compact mobile state. */
+export function SignalSearch({ label, onOpen, className }: SignalSearchProps): ReactNode {
+  return <button type="button" className={cn('signal-control signal-search', className)} onClick={onOpen} aria-label={label}>
+    <SearchIcon /><span>{label}</span><kbd aria-hidden="true">⌘ K</kbd>
+  </button>
+}
+
+/** Secondary header action; the filled Signal CTA remains the page's primary action. */
+export function SignalHeaderAction({ children, className, ...props }: ComponentProps<'a'>): ReactNode {
+  return <a {...props} className={cn('signal-control signal-header-action', className)}><span>{children}</span>
+    <svg viewBox="0 0 24 24" aria-hidden="true"><path d="M4 12h15m-6-6 6 6-6 6" /></svg>
+  </a>
+}

package/src/compositions/signalField.tsx

@@ -0,0 +1,75 @@
+import { useEffect, useId, useRef, type ReactNode } from 'react'
+import { cn } from '../cn'
+import { createSignalMotion } from './signalMotion'
+
+export interface SignalFieldProps {
+  /** Enable the ambient wave. Supply a visible pause control when enabling it. */
+  readonly animated?: boolean
+  readonly paused?: boolean
+  readonly className?: string
+}
+
+const ribbons = [
+  "M1080-160C870 90 1570 60 1530 400S1100 670 1320 990",
+  "M1055-160C845 98 1545 72 1505 408S1075 678 1295 998",
+  "M1030-160C820 106 1520 84 1480 416S1050 686 1270 1006",
+  "M1005-160C795 114 1495 96 1455 424S1025 694 1245 1014",
+  "M980-160C770 122 1470 108 1430 432S1000 702 1220 1022",
+  "M955-160C745 130 1445 120 1405 440S975 710 1195 1030",
+  "M930-160C720 138 1420 132 1380 448S950 718 1170 1038",
+  "M905-160C695 146 1395 144 1355 456S925 726 1145 1046",
+  "M880-160C670 154 1370 156 1330 464S900 734 1120 1054",
+  "M855-160C645 162 1345 168 1305 472S875 742 1095 1062",
+  "M830-160C620 170 1320 180 1280 480S850 750 1070 1070",
+  "M805-160C595 178 1295 192 1255 488S825 758 1045 1078"
+]
+const returns = [
+  "M-150 600C170 550-70 930 360 960S490 1100 780 1200",
+  "M-150 621C165 571-75 951 355 981S485 1121 775 1221",
+  "M-150 642C160 592-80 972 350 1002S480 1142 770 1242",
+  "M-150 663C155 613-85 993 345 1023S475 1163 765 1263",
+  "M-150 684C150 634-90 1014 340 1044S470 1184 760 1284"
+]
+const traces = [ribbons[1], ribbons[4], ribbons[7], ribbons[10], returns[2]] as const
+
+/** Decorative Voltro contour field. Import `@voltro/ui-shadcn/signal.css`.
+ * Static at SSR, with reduced-motion and visibility-aware animation on hydration. */
+export function SignalField({ animated = false, paused = false, className }: SignalFieldProps): ReactNode {
+  const ref = useRef<HTMLDivElement>(null)
+  const control = useRef<ReturnType<typeof createSignalMotion> | null>(null)
+  const id = useId()
+  useEffect(() => {
+    const element = ref.current
+    if (!element) return
+    const motion = createSignalMotion(element)
+    control.current = motion
+    return () => { motion.dispose(); control.current = null }
+  }, [])
+  useEffect(() => { control.current?.setEnabled(animated && !paused) }, [animated, paused])
+  return (
+    <div ref={ref} className={cn('signal-atmosphere', className)} aria-hidden="true" data-motion="paused">
+      <div className="field-light" />
+      <svg className="field-contours" viewBox="0 0 1600 1120" fill="none">
+        <defs>
+          <linearGradient id={`${id}-ink`} x1="750" y1="60" x2="1390" y2="1040" gradientUnits="userSpaceOnUse">
+            <stop stopColor="#A874FF" stopOpacity=".05" /><stop offset=".34" stopColor="#A874FF" stopOpacity=".36" />
+            <stop offset=".7" stopColor="#7C3AED" stopOpacity=".12" /><stop offset="1" stopColor="#A874FF" stopOpacity="0" />
+          </linearGradient>
+          <linearGradient id={`${id}-edge`} x1="0" y1="670" x2="740" y2="1120" gradientUnits="userSpaceOnUse">
+            <stop stopColor="#A874FF" stopOpacity="0" /><stop offset=".5" stopColor="#A874FF" stopOpacity=".22" />
+            <stop offset="1" stopColor="#A874FF" stopOpacity="0" />
+          </linearGradient>
+        </defs>
+        <g className="field-ribbons" stroke={`url(#${id}-ink)`} strokeWidth=".8">
+          {ribbons.map((d, i) => <path key={d} d={d} data-wave={`main-${i}`} />)}
+        </g>
+        <g className="field-return" stroke={`url(#${id}-edge)`} strokeWidth=".7">
+          {returns.map((d, i) => <path key={d} d={d} data-wave={`return-${i}`} />)}
+        </g>
+        {traces.map((d, i) => <path key={d} d={d} className={`field-ambient-trace trace-${i}`}
+          data-wave={['main-1', 'main-4', 'main-7', 'main-10', 'return-2'][i]}
+          stroke="#B995FF" strokeWidth="1" pathLength="100" />)}
+      </svg>
+    </div>
+  )
+}

package/src/compositions/signalHeader.tsx

@@ -0,0 +1,96 @@
+import { useEffect, useId, useRef, useState, type ReactNode } from 'react'
+import { cn } from '../cn'
+
+export interface SignalNavigationLink {
+  readonly label: string
+  readonly href: string
+  readonly description?: string
+  readonly current?: boolean
+}
+
+export interface SignalHeaderProps {
+  readonly brand: ReactNode
+  readonly links: readonly SignalNavigationLink[]
+  readonly navigationLabel: string
+  readonly menuLabel: string
+  readonly menuTitle: ReactNode
+  readonly menuLinks: readonly SignalNavigationLink[]
+  readonly utilities?: ReactNode
+  /** Context navigation, such as the Docs section drawer, stays beside the rail. */
+  readonly navigationAction?: ReactNode
+  readonly className?: string
+  /** Keep navigation available while reading; the surface appears after scrolling. */
+  readonly sticky?: boolean
+}
+
+/** Compact brand navigation with a keyboard-accessible disclosure and moving marker. */
+export function SignalHeader({ brand, links, navigationLabel, menuLabel, menuTitle, menuLinks, utilities, navigationAction, className, sticky = false }: SignalHeaderProps): ReactNode {
+  const [open, setOpen] = useState(false)
+  const [scrolled, setScrolled] = useState(false)
+  const ref = useRef<HTMLElement>(null)
+  const trigger = useRef<HTMLButtonElement>(null)
+  const marker = useRef<HTMLSpanElement>(null)
+  const id = useId()
+  useEffect(() => {
+    if (!sticky) return
+    const update = (): void => setScrolled(window.scrollY > 24)
+    update()
+    window.addEventListener('scroll', update, { passive: true })
+    return () => window.removeEventListener('scroll', update)
+  }, [sticky])
+  const move = (target: HTMLElement | null): void => {
+    if (!target || !marker.current) return
+    marker.current.style.transform = `translateX(${target.offsetLeft - 5}px) scaleX(${target.offsetWidth / 100})`
+  }
+  useEffect(() => {
+    const header = ref.current
+    if (!header) return
+    const reset = (): void => move(trigger.current)
+    const resize = new ResizeObserver(reset)
+    resize.observe(header)
+    reset()
+    return () => resize.disconnect()
+  }, [])
+  useEffect(() => {
+    if (!open) return
+    const close = (event: PointerEvent): void => {
+      if (event.target instanceof Node && !ref.current?.contains(event.target)) setOpen(false)
+    }
+    document.addEventListener('pointerdown', close)
+    return () => document.removeEventListener('pointerdown', close)
+  }, [open])
+  return (
+    <header ref={ref} className={cn('signal-masthead', sticky && 'signal-masthead-sticky', className)} data-scrolled={sticky && scrolled}
+      onKeyDown={event => { if (event.key === 'Escape' && open) { setOpen(false); trigger.current?.focus() } }}
+      onBlur={event => { if (!event.currentTarget.contains(event.relatedTarget)) setOpen(false) }}>
+      <div className="signal-header signal-shell">
+        <div className="signal-brand">{brand}</div>
+        <div className="signal-navigation-area">
+          <nav className="signal-navigation" aria-label={navigationLabel} onPointerLeave={() => move(trigger.current)}>
+            <span ref={marker} className="signal-nav-marker" aria-hidden="true" />
+            <button ref={trigger} className="signal-nav-item" type="button" aria-expanded={open} aria-controls={id}
+              onClick={() => setOpen(!open)} onPointerEnter={event => move(event.currentTarget)} onFocus={event => move(event.currentTarget)}>
+              <span className="signal-nav-dot" aria-hidden="true" />{menuLabel}
+              <svg viewBox="0 0 16 16" aria-hidden="true"><path d="m4 6 4 4 4-4" /></svg>
+            </button>
+            {links.map(link => <a key={link.href} href={link.href} className="signal-nav-item" aria-current={link.current ? 'page' : undefined}
+              onPointerEnter={event => move(event.currentTarget)} onFocus={event => move(event.currentTarget)}>
+              {link.label}<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M6 18 18 6M6 6h12v12" /></svg>
+            </a>)}
+            {navigationAction}
+          </nav>
+          {utilities && <div className="signal-header-utilities">{utilities}</div>}
+        </div>
+        <nav id={id} className="signal-menu" aria-label={menuLabel} hidden={!open}>
+          <div className="signal-menu-intro">{menuTitle}</div>
+          <div className="signal-menu-links">
+            {menuLinks.map(link => <a key={link.href} href={link.href} onClick={() => setOpen(false)}>
+              <span>{link.label}{link.description && <small>{link.description}</small>}</span>
+              <svg viewBox="0 0 24 24" aria-hidden="true"><path d="M6 18 18 6M6 6h12v12" /></svg>
+            </a>)}
+          </div>
+        </nav>
+      </div>
+    </header>
+  )
+}

package/src/compositions/signalMotion.ts

@@ -0,0 +1,68 @@
+/** Own all browser resources for one decorative field, including SPA teardown. */
+export function createSignalMotion(element: HTMLElement): {
+  setEnabled: (enabled: boolean) => void
+  dispose: () => void
+} {
+  const media = window.matchMedia('(prefers-reduced-motion: reduce)')
+  const animations: Animation[] = []
+  let enabled = false
+  let visible = false
+  let disposed = false
+  const supportsPath = typeof CSS !== 'undefined' && CSS.supports('d', 'path("M 0 0 L 1 1")')
+
+  if (supportsPath) {
+    for (const path of element.querySelectorAll<SVGPathElement>('path[data-wave]')) {
+      const coordinates = path.getAttribute('d')?.match(/-?\d+(?:\.\d+)?/g)?.map(Number)
+      if (!coordinates || coordinates.length !== 12) continue
+      const n = coordinates
+      const [group, index = '0'] = (path.dataset.wave ?? '').split('-')
+      // Neighboring curves share a wave with a small phase gap so the field
+      // visibly bends without collapsing its parallel contour spacing.
+      const main = group === 'main'
+      const deltas = main
+        ? [0, 0, -60, 34, 86, 54, -44, 70, -70, -54, 0, 0]
+        : [0, 0, 42, -35, -56, 45, 54, -51, -48, 32, 0, 0]
+      const shape = (direction: number): string => {
+        const values = n.map((value, i) => value + (deltas[i] ?? 0) * direction)
+        return `path("M ${values[0]} ${values[1]} C ${values[2]} ${values[3]} ${values[4]} ${values[5]} ${values[6]} ${values[7]} S ${values[8]} ${values[9]} ${values[10]} ${values[11]}")`
+      }
+      const outward = 'cubic-bezier(.333,.524,.667,1)'
+      const inward = 'cubic-bezier(.333,0,.667,.476)'
+      const animation = path.animate([
+        { d: shape(0), easing: outward }, { d: shape(1), easing: inward },
+        { d: shape(0), easing: outward }, { d: shape(-1), easing: inward }, { d: shape(0) },
+      ], { duration: main ? 12000 : 15000, delay: -Number(index) * (main ? 320 : 450), iterations: Infinity })
+      animation.pause()
+      animations.push(animation)
+    }
+  }
+
+  const sync = (): void => {
+    if (disposed) return
+    const running = enabled && visible && !document.hidden && !media.matches
+    element.dataset.motion = running ? 'running' : 'paused'
+    for (const animation of animations) {
+      if (media.matches) animation.cancel()
+      else if (running && animation.playState !== 'running') animation.play()
+      else if (!running && animation.playState === 'running') animation.pause()
+    }
+  }
+  const observer = new IntersectionObserver(([entry]) => {
+    visible = entry?.isIntersecting ?? false
+    sync()
+  }, { threshold: .01 })
+  observer.observe(element)
+  document.addEventListener('visibilitychange', sync)
+  media.addEventListener('change', sync)
+  return {
+    setEnabled(value) { enabled = value; sync() },
+    dispose() {
+      disposed = true
+      observer.disconnect()
+      document.removeEventListener('visibilitychange', sync)
+      media.removeEventListener('change', sync)
+      animations.forEach(animation => animation.cancel())
+      element.dataset.motion = 'paused'
+    },
+  }
+}

package/src/compositions/themeToggle.tsx

@@ -9,7 +9,7 @@
 import { useEffect, useState, type HTMLAttributes, type ReactNode } from 'react'
 import { Button } from '../primitives/button'
 import { cn } from '../cn'
-import { THEME_COOKIE, setCookie } from '../cookies'
+import { THEME_COOKIE, THEME_CHANGE_EVENT, setCookie, applyTheme } from '../cookies'
 
 /**
  * Inline script to drop into <head>. Reads the `voltro:theme` cookie
@@ -56,13 +56,16 @@ export const ThemeToggle = ({
   const [isDark, setIsDark] = useState<boolean | undefined>(undefined)
 
   useEffect(() => {
-    setIsDark(document.documentElement.classList.contains('dark'))
+    const refreshTheme = (): void => setIsDark(document.documentElement.classList.contains('dark'))
+    refreshTheme()
+    window.addEventListener(THEME_CHANGE_EVENT, refreshTheme)
+    return () => window.removeEventListener(THEME_CHANGE_EVENT, refreshTheme)
   }, [])
 
   const toggle = (): void => {
     const next = !document.documentElement.classList.contains('dark')
-    document.documentElement.classList.toggle('dark', next)
     setCookie(THEME_COOKIE, next ? 'dark' : 'light')
+    applyTheme(next ? 'dark' : 'light')
     setIsDark(next)
   }
 

package/src/cookies.ts

@@ -11,6 +11,8 @@
 // omit it in the browser (falls back to `document.cookie`).
 
 export const THEME_COOKIE = 'voltro:theme'
+/** Fired after applyTheme so preference controls in the same document stay in sync. */
+export const THEME_CHANGE_EVENT = 'voltro:theme-change'
 export const LOCALE_COOKIE = 'voltro:locale'
 
 export type ThemePreference = 'system' | 'light' | 'dark'
@@ -108,4 +110,5 @@ export const applyTheme = (theme: ThemePreference): void => {
       typeof window !== 'undefined' &&
       window.matchMedia?.('(prefers-color-scheme: dark)').matches === true)
   document.documentElement.classList.toggle('dark', dark)
+  if (typeof window !== 'undefined') window.dispatchEvent(new Event(THEME_CHANGE_EVENT))
 }

package/src/index.ts

@@ -33,7 +33,7 @@ export { shadcnWidgets } from './widgets'
 
 // ---- User-preference cookies (theme + language) ----
 export {
-  THEME_COOKIE, LOCALE_COOKIE,
+  THEME_COOKIE, THEME_CHANGE_EVENT, LOCALE_COOKIE,
   getCookie, setCookie, deleteCookie,
   parsePreferenceCookies, applyTheme,
 } from './cookies'
@@ -158,3 +158,7 @@ export {
 } from './primitives/docIcons'
 export { SearchModal, SearchTrigger } from './primitives/searchModal'
 export type { SearchModalProps, SearchModalLabels } from './primitives/searchModal'
+
+export { SignalField, type SignalFieldProps } from './compositions/signalField'
+export { SignalPreferences, SignalSearch, SignalHeaderAction, type SignalPreferencesProps, type SignalSearchProps } from './compositions/signalControls'
+export { SignalHeader, type SignalHeaderProps, type SignalNavigationLink } from './compositions/signalHeader'

package/src/primitives/codeBlock.tsx

@@ -77,14 +77,14 @@ export const CodeBlock = ({
   }
 
   return (
-    <figure className={cn('not-prose my-5 rounded-lg overflow-hidden border border-border bg-[oklch(0.18_0.005_280)]', className)}>
+    <figure className={cn('not-prose my-5 rounded-lg overflow-hidden border border-border bg-card text-card-foreground', className)}>
       {(filename || language) ? (
-        <header className="flex items-center justify-between border-b border-border/60 px-4 py-2 bg-card/40">
+        <header className="flex items-center justify-between border-b border-border/60 px-4 py-2 bg-muted">
           {filename ? (
             <span className="text-xs text-muted-foreground font-mono">{filename}</span>
           ) : <span />}
           {language ? (
-            <span className="text-[0.65rem] uppercase tracking-wider text-muted-foreground/80 font-semibold">
+            <span className="text-[0.65rem] uppercase tracking-wider text-muted-foreground font-semibold">
               {language}
             </span>
           ) : null}
@@ -95,7 +95,7 @@ export const CodeBlock = ({
           type="button"
           onClick={doCopy}
           aria-label={copied ? copiedAriaLabel : copyAriaLabel}
-          className="absolute top-3 right-3 inline-flex items-center gap-1 rounded-md border border-border/60 bg-background/70 backdrop-blur px-2 py-1 text-xs text-muted-foreground hover:text-foreground transition-colors"
+          className="absolute top-3 right-3 inline-flex items-center gap-1 rounded-md border border-border/60 bg-background px-2 py-1 text-xs text-muted-foreground hover:text-foreground transition-colors"
         >
           {copied ? (
             <>

package/src/primitives/dialog.tsx

@@ -7,10 +7,10 @@
 // imperative API (`dialogRef.current?.showModal()`) is the native
 // path; we surface it as a uncontrolled wrapper for now.
 
-import type { DialogHTMLAttributes, HTMLAttributes, ReactNode } from 'react'
+import type { ComponentPropsWithRef, HTMLAttributes, ReactNode } from 'react'
 import { cn } from '../cn'
 
-export const Dialog = ({ className, children, ...props }: DialogHTMLAttributes<HTMLDialogElement>): ReactNode => (
+export const Dialog = ({ className, children, ...props }: ComponentPropsWithRef<'dialog'>): ReactNode => (
   <dialog
     data-slot="dialog"
     className={cn(

package/src/primitives/highlightedCode.tsx

@@ -112,6 +112,8 @@ export const HighlightedCode = ({
         const out = hl.codeToHtml(code, {
           lang,
           themes: { light: 'github-light', dark: 'github-dark-dimmed' },
+          // GitHub Light's parameter orange falls below 4.5:1 on white.
+          colorReplacements: { 'github-light': { '#e36209': '#a44100' } },
           defaultColor: false,
         })
         setHtml(out)