@djangocfg/ui-tools 2.1.416 → 2.1.417

package/src/tools/data/Tree/context/TreeContext.tsx

@@ -10,6 +10,7 @@ import {
   DEFAULT_TREE_LABELS,
   type FlatRow,
   type TreeActivateOptions,
+  type TreeContextMenuSlot,
   type TreeItemId,
   type TreeLabels,
   type TreeNode,
@@ -22,7 +23,7 @@ import { useExpansion } from './expansion';
 import { useSelection } from './selection';
 import { useRename } from './rename';
 import { useClipboard } from './clipboard';
-import { useResolvedMenu } from './menu';
+import { useResolvedMenu, renderItemsAsContextMenu, tidyMenuItems } from './menu';
 import { useDnd, type UseDndReturn } from './dnd';
 import { usePersistSync } from './persist';
 import type { TreeContextValue } from './TreeContextValue';
@@ -282,6 +283,24 @@ export function TreeProvider<T>(props: TreeProviderProps<T>) {
     pasteFromClipboard: clipboard.pasteFromClipboard,
   });
 
+  // Translate the declarative resolver into a slot-form
+  // `renderContextMenu` so <TreeRow> doesn't need to know about it.
+  // Explicit slot prop wins (escape-hatch for full custom menus).
+  const finalRenderContextMenu = useMemo<TreeContextMenuSlot<T> | undefined>(
+    () => {
+      if (renderContextMenu) return renderContextMenu;
+      const resolve = resolvedContextMenuActions;
+      if (!resolve) return undefined;
+      return (rowProps, trigger) => {
+        const items = resolve(rowProps);
+        const cleaned = items ? tidyMenuItems(items) : null;
+        if (!cleaned || cleaned.length === 0) return trigger;
+        return renderItemsAsContextMenu(rowProps, cleaned, trigger);
+      };
+    },
+    [renderContextMenu, resolvedContextMenuActions],
+  );
+
   // ---- Final value --------------------------------------------------
 
   const value = useMemo<TreeContextValue<T>>(
@@ -333,7 +352,7 @@ export function TreeProvider<T>(props: TreeProviderProps<T>) {
       renderIcon,
       renderLabel,
       renderActions,
-      renderContextMenu,
+      renderContextMenu: finalRenderContextMenu,
 
       adapter,
       resolvedContextMenuActions,
@@ -371,7 +390,7 @@ export function TreeProvider<T>(props: TreeProviderProps<T>) {
       renderIcon,
       renderLabel,
       renderActions,
-      renderContextMenu,
+      finalRenderContextMenu,
       adapter,
       resolvedContextMenuActions,
       nodeById,

package/src/tools/data/Tree/context/menu/index.ts

@@ -8,3 +8,4 @@ export {
 export type { BuiltinActionContext } from './builtin-actions';
 export { useResolvedMenu } from './use-resolved-menu';
 export type { UseResolvedMenuOptions } from './use-resolved-menu';
+export { renderItemsAsContextMenu, tidyMenuItems } from './render';

package/src/tools/data/Tree/context/menu/render.tsx

@@ -0,0 +1,75 @@
+'use client';
+
+import {
+  ContextMenu,
+  ContextMenuContent,
+  ContextMenuItem,
+  ContextMenuSeparator,
+  ContextMenuShortcut,
+  ContextMenuTrigger,
+} from '@djangocfg/ui-core/components';
+
+import type {
+  TreeContextMenuItem,
+  TreeRowRenderProps,
+} from '../../types';
+
+/**
+ * Render an array of declarative menu items as a themed `<ContextMenu>`
+ * wrapped around the supplied trigger element. Pure presentational layer
+ * — the caller resolves and merges items.
+ */
+export function renderItemsAsContextMenu<T>(
+  rowProps: TreeRowRenderProps<T>,
+  items: TreeContextMenuItem<T>[],
+  trigger: React.ReactNode,
+): React.ReactNode {
+  return (
+    <ContextMenu>
+      <ContextMenuTrigger asChild>{trigger}</ContextMenuTrigger>
+      <ContextMenuContent>
+        {items.map((item, idx) => {
+          if (item === 'separator') {
+            return <ContextMenuSeparator key={`sep-${idx}`} />;
+          }
+          const Icon = item.icon;
+          return (
+            <ContextMenuItem
+              key={item.id}
+              disabled={item.disabled}
+              variant={item.destructive ? 'destructive' : undefined}
+              onSelect={() => item.onSelect(rowProps)}
+            >
+              {Icon ? <Icon /> : null}
+              {item.label}
+              {item.shortcut ? (
+                <ContextMenuShortcut>{item.shortcut}</ContextMenuShortcut>
+              ) : null}
+            </ContextMenuItem>
+          );
+        })}
+      </ContextMenuContent>
+    </ContextMenu>
+  );
+}
+
+/**
+ * Drop trailing / leading / duplicate separators so a merged menu never
+ * shows a separator next to a section header or another separator.
+ */
+export function tidyMenuItems<T>(
+  items: TreeContextMenuItem<T>[],
+): TreeContextMenuItem<T>[] {
+  const out: TreeContextMenuItem<T>[] = [];
+  for (const it of items) {
+    if (it === 'separator') {
+      if (out.length === 0) continue;
+      if (out[out.length - 1] === 'separator') continue;
+      out.push(it);
+    } else {
+      out.push(it);
+    }
+  }
+  while (out.length > 0 && out[out.length - 1] === 'separator') out.pop();
+  return out;
+}

package/src/tools/data/Tree/context/menu/use-resolved-menu.ts

@@ -7,16 +7,30 @@ import type {
   TreeAdapter,
   TreeBuiltinAction,
   TreeContextMenuActionsResolver,
+  TreeContextMenuItem,
   TreeItemId,
   TreeLabels,
   TreeMovePosition,
   TreeNode,
+  TreeRowRenderProps,
 } from '../../types';
+
+export type { TreeContextMenuActionsResolver };
 import {
   buildDefaultMenuItems,
   type BuiltinActionContext,
 } from './builtin-actions';
 
+/**
+ * Internal row-driven resolver — same shape as
+ * `TreeContextMenuActionsResolver` but takes a plain `TreeRowRenderProps`
+ * instead of the context-with-selection. The provider injects
+ * `selectedNodes` itself.
+ */
+export type ResolvedMenuResolver<T> = (
+  row: TreeRowRenderProps<T>,
+) => TreeContextMenuItem<T>[] | null | undefined;
+
 export interface UseResolvedMenuOptions<T> {
   adapter?: TreeAdapter<T>;
   contextMenuActions?: TreeContextMenuActionsResolver<T>;
@@ -50,7 +64,7 @@ export interface UseResolvedMenuOptions<T> {
  */
 export function useResolvedMenu<T>(
   opts: UseResolvedMenuOptions<T>,
-): TreeContextMenuActionsResolver<T> | undefined {
+): ResolvedMenuResolver<T> | undefined {
   const {
     adapter,
     contextMenuActions,
@@ -67,7 +81,7 @@ export function useResolvedMenu<T>(
     pasteFromClipboard,
   } = opts;
 
-  return useMemo<TreeContextMenuActionsResolver<T> | undefined>(() => {
+  return useMemo<ResolvedMenuResolver<T> | undefined>(() => {
     if (!adapter && !contextMenuActions) return undefined;
 
     return (rowProps) => {

package/src/tools/data/Tree/index.tsx

@@ -105,6 +105,7 @@ export type {
 
 export { DEFAULT_TREE_LABELS } from './types';
 export type {
+  TreeActionsHandle,
   TreeRootProps,
   TreeNode,
   TreeItemId,

package/src/tools/data/Tree/types/index.ts

@@ -24,4 +24,4 @@ export type {
   TreeAdapter,
   TreeBuiltinAction,
 } from './adapter';
-export type { TreeRootProps } from './root-props';
+export type { TreeRootProps, TreeActionsHandle } from './root-props';

package/src/tools/data/Tree/types/root-props.ts

@@ -137,6 +137,22 @@ export interface TreeRootProps<T> {
    */
   defaultMenuItems?: TreeBuiltinAction[];
 
+  /**
+   * Imperative handle for outer code. The provided ref receives a
+   * stable handle to `useTreeActions` once Tree mounts. Lets host
+   * components trigger `refresh(id)` / `refreshAll()` from outside
+   * Tree (e.g. after a transport-level mutation completes).
+   */
+  actionsRef?: React.MutableRefObject<TreeActionsHandle | null>;
+
   className?: string;
   style?: CSSProperties;
 }
+
+/** Subset of `useTreeActions()` exposed via `<TreeRoot actionsRef={…}>`. */
+export interface TreeActionsHandle {
+  refresh: (id: string) => Promise<void>;
+  refreshAll: () => Promise<void>;
+  expandAll: () => void;
+  collapseAll: () => void;
+}

package/src/tools/dev/OpenapiViewer/components/DocsLayout/EndpointDoc/Header/MetaActions.tsx

@@ -12,7 +12,6 @@ import {
     Tooltip,
     TooltipContent,
     TooltipTrigger,
-    SafeTooltipProvider,
 } from '@djangocfg/ui-core/components';
 import { cn } from '@djangocfg/ui-core/lib';
 
@@ -119,13 +118,11 @@ export function MetaActions({ anchor, presentSections }: MetaActionsProps) {
     ) : null;
 
     return (
-        <SafeTooltipProvider delayDuration={200}>
-            <div className="flex items-center gap-0.5">
-                <IconButton label={linkLabel} onClick={copyLink} active={linkCopied}>
-                    {linkIcon}
-                </IconButton>
-                {toggleAllNode}
-            </div>
-        </SafeTooltipProvider>
+        <div className="flex items-center gap-0.5">
+            <IconButton label={linkLabel} onClick={copyLink} active={linkCopied}>
+                {linkIcon}
+            </IconButton>
+            {toggleAllNode}
+        </div>
     );
 }

package/src/tools/dev/OpenapiViewer/components/DocsLayout/index.tsx

@@ -3,7 +3,7 @@
 import React, { useCallback, useMemo, useRef, useState } from 'react';
 import { keyBy } from 'lodash-es';
 
-import { Skeleton, TooltipProvider } from '@djangocfg/ui-core/components';
+import { Skeleton } from '@djangocfg/ui-core/components';
 import { useMediaQuery } from '@djangocfg/ui-core/hooks';
 
 import useOpenApiSchema from '../../hooks/useOpenApiSchema';
@@ -234,8 +234,7 @@ export const DocsLayout: React.FC = () => {
     // ─── Desktop ──────────────────────────────────────────────────────────
 
     return (
-        <TooltipProvider delayDuration={350}>
-            <div className="grid grid-cols-[260px_minmax(0,1fr)] items-start">
+        <div className="grid grid-cols-[260px_minmax(0,1fr)] items-start">
                 <EndpointDraftSync schemaId={currentSchema?.id ?? null} />
                 <div
                     className="sticky top-[var(--navbar-height,64px)]"
@@ -283,6 +282,5 @@ export const DocsLayout: React.FC = () => {
                     above the whole layout (sidebar + navbar included). */}
                 <SlideInPlayground open={slideOpen} onClose={handleCloseSlide} />
             </div>
-        </TooltipProvider>
     );
 };

package/src/tools/input/SpeechRecognition/widgets/VoiceComposerSlot.tsx

@@ -6,8 +6,7 @@ import { AlertCircle, Loader2, Mic } from 'lucide-react';
 
 import { useCountdownFromSeconds, useNotificationSounds } from '@djangocfg/ui-core/hooks';
 import { cn } from '@djangocfg/ui-core/lib';
-
-import { useChatContextOptional } from '../../../chat/context';
+import { useActiveComposer } from '@djangocfg/ui-tools/composer-registry';
 import { useSpeechRecognition } from '../hooks/useSpeechRecognition';
 import { useVoiceSupport } from '../hooks/useVoiceSupport';
 import { getSpeechLogger } from '../core/logger';
@@ -105,24 +104,24 @@ export function VoiceComposerSlot({
 }: VoiceComposerSlotProps): React.ReactElement | null {
   const support = useVoiceSupport(engine);
 
-  // Read the composer handle from chat context — works transparently
-  // for the built-in `<Composer>` (registers itself) and for TipTap
-  // hosts that call `useRegisterComposer({ getValue, setValue, focus,
-  // moveCursorToEnd })`. Falls back to a no-op when mounted outside of
-  // a chat.
-  const chatCtx = useChatContextOptional();
-  const composerHandleRef = useRef(chatCtx?.composer ?? null);
-  composerHandleRef.current = chatCtx?.composer ?? null;
+  // Read the active composer handle from the cross-tool registry
+  // (`@djangocfg/ui-tools/composer-registry`). The built-in
+  // `<Composer>` (and TipTap hosts via `useRegisterComposer`) publish
+  // their handle to this registry on mount. Falls back to a no-op
+  // when nothing is registered (no composer in the tree).
+  const activeComposer = useActiveComposer();
+  const composerHandleRef = useRef(activeComposer);
+  composerHandleRef.current = activeComposer;
 
   useEffect(() => {
     log.slot.debug('mount', {
       supported: support.supported,
       reason: support.reason,
-      hasComposerHandle: !!chatCtx?.composer,
+      hasComposerHandle: !!activeComposer,
       hasExplicitValue: value !== undefined,
       hasOnChange: !!onChange,
     });
-  }, [support.supported, support.reason, chatCtx?.composer, value, onChange]);
+  }, [support.supported, support.reason, activeComposer, value, onChange]);
 
   // Resolve value/onChange: prop wins; otherwise pull from the
   // registered composer handle. The slot can therefore be dropped into

package/src/tools/integration/ComposerRegistry/index.ts

@@ -0,0 +1,105 @@
+'use client';
+
+import { useCallback, useSyncExternalStore } from 'react';
+
+/**
+ * Minimal imperative handle every text-editor surface implements so
+ * an external tool (voice dictation, command palette, AI suggestion)
+ * can read/write its text content without traversing React.
+ *
+ * Methods are optional so a host can register a partial handle
+ * (e.g. only `getValue` + `setValue`), and the caller checks before use.
+ */
+export interface ComposerHandle {
+  /** Move keyboard focus into the composer's editable surface. */
+  focus: () => void;
+  /** Move the caret to the very end of the input. */
+  moveCursorToEnd?: () => void;
+  /** Read the current draft text. Voice dictation anchors partial
+   *  transcripts onto the user's already-typed prefix via this. */
+  getValue?: () => string;
+  /** Replace the current draft text. Voice dictation pushes interim
+   *  and final transcripts through this without owning a controlled
+   *  binding. */
+  setValue?: (value: string) => void;
+}
+
+/**
+ * `@djangocfg/ui-tools/composer-registry`
+ *
+ * Cross-tool bridge: the currently-active text composer's handle.
+ *
+ * Producer side (`@djangocfg/ui-tools/chat` and TipTap hosts):
+ *   register their composer's imperative handle via `attachComposer`.
+ *
+ * Consumer side (`@djangocfg/ui-tools/speech-recognition`):
+ *   reads the active handle via `useActiveComposer`/`getActiveComposer`
+ *   and pipes voice transcripts into it.
+ *
+ * Why this lives in its own subpath (not inside `chat`)
+ * ----------------------------------------------------
+ * `chat` and `speech-recognition` are sibling subpath exports. If the
+ * registry lived inside `chat`, then `speech-recognition` would have
+ * to reach into it via a cross-tool relative import — and under Vite
+ * dev's dependency optimizer that file ends up loaded TWICE (once via
+ * the `./chat` URL, once via the `./speech-recognition` relative-up
+ * URL), giving the producer and the consumer two separate `let active`
+ * slots. The active handle registered by chat would be invisible to
+ * speech-recognition (and vice versa).
+ *
+ * Putting the registry in its own dedicated subpath (a single tool
+ * that NEITHER chat nor speech-recognition cross-import — they both
+ * import this one as their dependency) means Vite resolves it from a
+ * single URL across the whole graph. One module instance, one shared
+ * `active` slot.
+ *
+ * Semantics: one active composer per realm. The most recent
+ * `registerComposer(handle)` wins; `registerComposer(null)` clears it.
+ */
+
+type Listener = (handle: ComposerHandle | null) => void;
+
+let active: ComposerHandle | null = null;
+const listeners = new Set<Listener>();
+
+/** Set or replace the active composer handle. Pass `null` to clear. */
+export function registerComposer(handle: ComposerHandle | null): void {
+  active = handle;
+  for (const fn of listeners) fn(active);
+}
+
+/**
+ * Convenience for components: register on mount, unregister on
+ * unmount. Returns a cleanup function suitable for `useEffect`.
+ */
+export function attachComposer(handle: ComposerHandle): () => void {
+  registerComposer(handle);
+  return () => {
+    if (active === handle) registerComposer(null);
+  };
+}
+
+/** Read the current active handle (no subscription). */
+export function getActiveComposer(): ComposerHandle | null {
+  return active;
+}
+
+/** Subscribe to handle changes; returns an unsubscribe fn. */
+export function subscribeComposer(listener: Listener): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+/**
+ * React hook: re-renders the caller whenever the active composer
+ * changes. Built on `useSyncExternalStore` so concurrent rendering,
+ * SSR, and dev-mode strict-effects all behave correctly.
+ */
+export function useActiveComposer(): ComposerHandle | null {
+  const subscribe = useCallback((onChange: () => void) => {
+    return subscribeComposer(onChange);
+  }, []);
+  return useSyncExternalStore(subscribe, getActiveComposer, () => null);
+}

package/src/tools/media/AudioPlayer/Player.tsx

@@ -34,6 +34,7 @@ export const Player = forwardRef<PlayerHandle, PlayerProps>(function Player(prop
     ariaLabel,
     enableKeyboardShortcuts,
     seekStartsPlayback,
+    autoFocus,
   } = props;
 
   // onTimeUpdate is intentionally not wired in the provider — we expose it via
@@ -71,6 +72,7 @@ export const Player = forwardRef<PlayerHandle, PlayerProps>(function Player(prop
         enableKeyboardShortcuts={enableKeyboardShortcuts}
         ariaLabel={ariaLabel}
         seekStartsPlayback={seekStartsPlayback}
+        autoFocus={autoFocus}
         handleRef={ref}
       />
     </PlayerProvider>

package/src/tools/media/AudioPlayer/PlayerShell.tsx

@@ -4,7 +4,6 @@
 // keyboard shortcuts and MediaSession wiring; renders the picked layout.
 
 import { useCallback, useEffect, useImperativeHandle, useState } from 'react';
-import { TooltipProvider } from '@djangocfg/ui-core/components';
 import { useIsPhone } from '@djangocfg/ui-core/hooks';
 import { usePlayerAudio, usePlayerControls, usePlayerMeta } from './context/selectors';
 import { useElementWidth } from './hooks/useResizeObserver';
@@ -26,6 +25,7 @@ type Props = Pick<
   | 'enableKeyboardShortcuts'
   | 'ariaLabel'
   | 'seekStartsPlayback'
+  | 'autoFocus'
 > & {
   handleRef?: React.Ref<PlayerHandle>;
 };
@@ -40,6 +40,7 @@ export function PlayerShell({
   enableKeyboardShortcuts = true,
   ariaLabel,
   seekStartsPlayback = true,
+  autoFocus = false,
   handleRef,
 }: Props) {
   const [container, setContainer] = useState<HTMLDivElement | null>(null);
@@ -87,8 +88,9 @@ export function PlayerShell({
       seek: (s: number) => controls.seek(s),
       getCurrentTime: () => audio.currentTime,
       getDuration: () => (Number.isFinite(audio.duration) ? audio.duration : 0),
+      focus: () => container?.focus(),
     }),
-    [audio, controls],
+    [audio, controls, container],
   );
 
   // Keyboard shortcuts work only when the container can take focus.
@@ -97,26 +99,39 @@ export function PlayerShell({
     container.setAttribute('tabindex', '0');
   }, [container]);
 
+  // `autoFocus` opts the player into pulling keyboard focus on mount
+  // (and whenever the container ref is established). Once focused,
+  // the hotkey scope (Space=play/pause, ←→=seek, ↑↓=volume, M=mute)
+  // is immediately live.
+  //
+  // Deferred via a 0-timeout so the tree row's native focus event
+  // (fired by the click that triggered the mount) lands first; we
+  // then steal focus here. rAF was racy — the row's focus event can
+  // fire AFTER the next animation frame.
+  useEffect(() => {
+    if (!autoFocus || !container) return;
+    const id = setTimeout(() => container.focus(), 0);
+    return () => clearTimeout(id);
+  }, [autoFocus, container]);
+
   return (
-    <TooltipProvider delayDuration={400}>
-      <div
-        ref={setRootRef}
-        role="group"
-        aria-label={ariaLabel ?? 'Audio player'}
-        className={`audioplayer @container/player rounded-lg border border-border/60 bg-card text-foreground shadow-none focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/50 ${className}`}
-      >
-        {resolvedVariant === 'compact' ? (
-          <CompactLayout waveform={waveform} seekStartsPlayback={seekStartsPlayback} />
-        ) : (
-          <DefaultLayout
-            waveform={waveform}
-            reactiveCover={reactiveCover}
-            onPrev={onPrev}
-            onNext={onNext}
-            seekStartsPlayback={seekStartsPlayback}
-          />
-        )}
-      </div>
-    </TooltipProvider>
+    <div
+      ref={setRootRef}
+      role="group"
+      aria-label={ariaLabel ?? 'Audio player'}
+      className={`audioplayer @container/player rounded-lg border border-border/60 bg-card text-foreground shadow-none focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/50 ${className}`}
+    >
+      {resolvedVariant === 'compact' ? (
+        <CompactLayout waveform={waveform} seekStartsPlayback={seekStartsPlayback} />
+      ) : (
+        <DefaultLayout
+          waveform={waveform}
+          reactiveCover={reactiveCover}
+          onPrev={onPrev}
+          onNext={onNext}
+          seekStartsPlayback={seekStartsPlayback}
+        />
+      )}
+    </div>
   );
 }

package/src/tools/media/AudioPlayer/lazy.tsx

@@ -3,31 +3,41 @@
 /**
  * `@djangocfg/ui-tools/audio-player` subpath entrypoint.
  *
- * `LazyPlayer` is exported as a direct (synchronous) alias of `Player`. We
- * intentionally avoid `React.lazy` + `import('./Player')` here: under bundlers
- * that pre-bundle subpath entries (Vite optimizeDeps in Next.js/Vite/SB), the
- * dynamic import creates a second chunk that re-instantiates the React
- * Contexts (AudioRefCtx/ControlsCtx/MetaCtx/StateCtx/LevelsCtx). The slot
- * components and selector hooks re-exported below would then read from a
- * different context instance than `<PlayerProvider>` writes to, which made
- * `usePlayerAudio` throw "must be used inside <PlayerProvider>".
+ * We deliberately keep this surface narrow:
  *
- * Heavy audio-decoding work (peaks, AudioContext) already happens lazily at
- * runtime via effects inside `PlayerProvider`/`PlayerShell` — there is no
- * benefit to splitting the React shell behind a second chunk.
+ *   - `Player` / `LazyPlayer` — the only React component you should
+ *     import. Already wraps `<PlayerProvider>` + `<PlayerShell>`.
+ *   - types
+ *   - `PlayerProvider` + selector hooks — for the rare consumer that
+ *     wants to render a fully custom layout. They must own the
+ *     provider themselves.
+ *   - cross-instance store helpers (active player, preferences).
+ *
+ * Slot components (Cover/Title/Waveform/Controls/Layout) and internal
+ * peak-cache helpers are NOT re-exported from this entrypoint. Earlier
+ * versions did re-export them, which produced a second module-graph
+ * entry into the `context/*` files under Vite's `optimizeDeps`
+ * pre-bundling — the slot files import the same selectors as
+ * `PlayerShell`, but via a different URL key, so `<PlayerProvider>`
+ * (one context instance) and `usePlayerAudio` inside a slot read
+ * (another context instance) ended up on different `createContext()`
+ * objects → "usePlayerAudio must be used inside <PlayerProvider>".
+ *
+ * If you need raw slots, import from a deeper path (e.g.
+ * `@djangocfg/ui-tools/src/tools/media/AudioPlayer/parts/Cover`) and
+ * accept that you must own a single `<PlayerProvider>` boundary.
  */
 
 // ============================================================================
-// Player component (synchronous; previously lazy — see note above)
+// Player component (synchronous; previously lazy)
 // ============================================================================
 
 export { Player, Player as LazyPlayer } from './Player';
 
 // ============================================================================
-// Light surface — types, store, context, slot components, hooks
+// Types
 // ============================================================================
 
-// Types
 export type {
   PlayerProps,
   PlayerState,
@@ -41,7 +51,10 @@ export type {
   PlayerErrorReason,
 } from './types';
 
+// ============================================================================
 // Context provider + selector hooks (no UI)
+// ============================================================================
+
 export {
   PlayerProvider,
   usePlayerAudio,
@@ -53,7 +66,10 @@ export {
   usePlayerState,
 } from './context';
 
+// ============================================================================
 // Cross-instance store (active player, preferences)
+// ============================================================================
+
 export {
   setActivePlayer,
   getActivePlayer,
@@ -66,37 +82,9 @@ export {
   type PlayerPreferences,
 } from './store';
 
-// Store-backed hooks
 export {
   useActivePlayer,
   useLastActivePlayer,
   useIsActivePlayer,
 } from './hooks/useActivePlayer';
 export { usePlayerPreferences } from './hooks/usePlayerPreferences';
-
-// Peak cache helpers
-export { clearPeaksCache, setPeaks } from './audio';
-
-// Slot components — presentational, read from PlayerContext. Safe to
-// re-export synchronously: they don't import the heavy Player tree
-// (audio decoding, layouts, shell) — only context selectors and types.
-export { Cover, CoverPlaceholder, ReactivePulse } from './parts/Cover';
-export { Title, Artist, TimeDisplay } from './parts/Meta';
-export {
-  PlayButton,
-  SkipButton,
-  VolumeControl,
-  LoopButton,
-  ControlsRow,
-  IconButton,
-} from './parts/Controls';
-export {
-  Waveform,
-  PeaksWaveform,
-  LiveWaveform,
-  BarsWaveform,
-  ProgressBar,
-  WaveformSkeleton,
-} from './parts/Waveform';
-export { ErrorState } from './parts/ErrorState';
-export { DefaultLayout, CompactLayout } from './parts/Layout';