@djangocfg/ui-tools 2.1.416 → 2.1.418

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-tools",
-  "version": "2.1.416",
+  "version": "2.1.418",
   "description": "Heavy React tools with lazy loading - for Electron, Vite, CRA, Next.js apps",
   "keywords": [
     "ui-tools",
@@ -66,10 +66,15 @@
       "import": "./dist/file-icon/index.mjs",
       "require": "./dist/file-icon/index.cjs"
     },
+    "./composer-registry": {
+      "types": "./dist/composer-registry/index.d.ts",
+      "import": "./dist/composer-registry/index.mjs",
+      "require": "./dist/composer-registry/index.cjs"
+    },
     "./audio-player": {
-      "types": "./src/tools/media/AudioPlayer/lazy.tsx",
-      "import": "./src/tools/media/AudioPlayer/lazy.tsx",
-      "require": "./src/tools/media/AudioPlayer/lazy.tsx"
+      "types": "./dist/audio-player/index.d.ts",
+      "import": "./dist/audio-player/index.mjs",
+      "require": "./dist/audio-player/index.cjs"
     },
     "./chat": {
       "types": "./src/tools/chat/lazy.tsx",
@@ -111,6 +116,11 @@
       "import": "./src/tools/forms/MarkdownEditor/lazy.tsx",
       "require": "./src/tools/forms/MarkdownEditor/lazy.tsx"
     },
+    "./notion-editor": {
+      "types": "./src/tools/forms/NotionEditor/lazy.tsx",
+      "import": "./src/tools/forms/NotionEditor/lazy.tsx",
+      "require": "./src/tools/forms/NotionEditor/lazy.tsx"
+    },
     "./markdown-message": {
       "types": "./src/tools/dev/MarkdownMessage/index.ts",
       "import": "./src/tools/dev/MarkdownMessage/index.ts",
@@ -254,8 +264,8 @@
     "test:watch": "vitest"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.416",
-    "@djangocfg/ui-core": "^2.1.416",
+    "@djangocfg/i18n": "^2.1.418",
+    "@djangocfg/ui-core": "^2.1.418",
     "consola": "^3.4.2",
     "lodash-es": "^4.18.1",
     "lucide-react": "^0.545.0",
@@ -274,14 +284,25 @@
     "@rjsf/utils": "^6.1.2",
     "@rjsf/validator-ajv8": "^6.1.2",
     "@rpldy/uploady": "^1.8.5",
-    "@tiptap/core": "^3.20.1",
-    "@tiptap/extension-mention": "^3.20.1",
-    "@tiptap/extension-placeholder": "^3.20.1",
-    "@tiptap/markdown": "^3.20.1",
-    "@tiptap/pm": "^3.20.1",
-    "@tiptap/react": "^3.20.1",
-    "@tiptap/starter-kit": "^3.20.1",
-    "@tiptap/suggestion": "^3.20.1",
+    "@tiptap/core": "^3.23.0",
+    "@tiptap/extension-bubble-menu": "^3.23.0",
+    "@tiptap/extension-code-block-lowlight": "^3.23.0",
+    "@tiptap/extension-highlight": "^3.23.0",
+    "@tiptap/extension-mention": "^3.23.0",
+    "@tiptap/extension-placeholder": "^3.23.0",
+    "@tiptap/extension-table": "^3.23.0",
+    "@tiptap/extension-table-cell": "^3.23.0",
+    "@tiptap/extension-table-header": "^3.23.0",
+    "@tiptap/extension-table-row": "^3.23.0",
+    "@tiptap/extension-task-item": "^3.23.0",
+    "@tiptap/extension-task-list": "^3.23.0",
+    "@tiptap/markdown": "^3.23.0",
+    "@tiptap/pm": "^3.23.0",
+    "@tiptap/react": "^3.23.0",
+    "@tiptap/starter-kit": "^3.23.0",
+    "@tiptap/suggestion": "^3.23.0",
+    "lowlight": "^3.3.0",
+    "tiptap-extension-global-drag-handle": "^0.1.18",
     "@wavesurfer/react": "^1.0.12",
     "@radix-ui/react-slot": "^1.2.4",
     "@radix-ui/react-direction": "^1.1.1",
@@ -319,9 +340,9 @@
     "@maplibre/maplibre-gl-geocoder": "^1.7.0"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.416",
-    "@djangocfg/typescript-config": "^2.1.416",
-    "@djangocfg/ui-core": "^2.1.416",
+    "@djangocfg/i18n": "^2.1.418",
+    "@djangocfg/typescript-config": "^2.1.418",
+    "@djangocfg/ui-core": "^2.1.418",
     "@types/lodash-es": "^4.17.12",
     "@types/mapbox__mapbox-gl-draw": "^1.4.8",
     "@types/node": "^25.2.3",

package/src/tools/chat/composer/Composer.tsx

@@ -4,6 +4,7 @@ import { forwardRef, useEffect, useMemo, useRef, useState } from 'react';
 
 import { Textarea } from '@djangocfg/ui-core/components';
 import { cn } from '@djangocfg/ui-core/lib';
+import { attachComposer } from '@djangocfg/ui-tools/composer-registry';
 
 import { useChatContextOptional } from '../context';
 import type { UseChatComposerReturn } from '../hooks/useChatComposer';
@@ -174,10 +175,10 @@ export const Composer = forwardRef<HTMLDivElement, ComposerProps>(function Compo
   // host overrides it explicitly — see §3.1 of the redesign doc.
   const layout: ComposerLayout = layoutProp ?? (size === 'sm' ? 'inline' : 'stacked');
 
-  // Register the composer's handle with the chat context so other parts
-  // of the tree (useAutoFocusOnStreamEnd, VoiceComposerSlot) can drive it
-  // imperatively. No-op when used outside a ChatProvider.
-  const register = ctx?.registerComposer;
+  // Publish the composer's imperative handle to the cross-tool
+  // composer registry (`@djangocfg/ui-tools/composer-registry`).
+  // Consumers (useAutoFocusOnStreamEnd, VoiceComposerSlot) read it
+  // from there — works the same inside or outside a ChatProvider.
   const composerFocus = composer.focus;
   const composerSetValue = composer.setValue;
   const textareaRef = composer.textareaRef;
@@ -189,8 +190,8 @@ export const Composer = forwardRef<HTMLDivElement, ComposerProps>(function Compo
   // ours so we don't overwrite it (child effects run before parent).
   const hasCustomTextarea = !!slots?.Textarea;
   useEffect(() => {
-    if (!register || hasCustomTextarea) return;
-    register({
+    if (hasCustomTextarea) return;
+    return attachComposer({
       focus: composerFocus,
       moveCursorToEnd: () => {
         const el = textareaRef.current;
@@ -201,8 +202,7 @@ export const Composer = forwardRef<HTMLDivElement, ComposerProps>(function Compo
       getValue: () => getValueRef.current(),
       setValue: composerSetValue,
     });
-    return () => register(null);
-  }, [register, hasCustomTextarea, composerFocus, composerSetValue, textareaRef]);
+  }, [hasCustomTextarea, composerFocus, composerSetValue, textareaRef]);
 
   const inlineStart = composerSlots?.inlineStart;
   const inlineEnd = composerSlots?.inlineEnd;

package/src/tools/chat/context/ChatProvider.tsx

@@ -8,9 +8,10 @@ import {
   useEffect,
   useMemo,
   useRef,
-  useState,
 } from 'react';
 
+import { getActiveComposer } from '@djangocfg/ui-tools/composer-registry';
+
 import type { ChatConfig, ChatLabels, ChatTransport } from '../types';
 import { DEFAULT_LABELS } from '../types';
 import type { BlockRegistry } from '../messages/blocks';
@@ -34,18 +35,12 @@ import type { ChatAudioConfig, UseChatAudioReturn } from '../core/audio/types';
  *  Consumed by `VoiceComposerSlot` for the focus / move-caret behaviour
  *  during live dictation.
  */
-export interface ComposerHandle {
-  focus: () => void;
-  /** Move the caret to the very end of the input. */
-  moveCursorToEnd?: () => void;
-  /** Read the current draft text. Needed by voice dictation to anchor
-   *  partial transcripts onto the user's already-typed prefix. */
-  getValue?: () => string;
-  /** Replace the current draft text. Voice dictation uses this to push
-   *  interim + final transcripts into the composer without owning a
-   *  controlled binding. */
-  setValue?: (value: string) => void;
-}
+// `ComposerHandle` lives in `@djangocfg/ui-tools/composer-registry` —
+// the cross-tool registry shared by chat (producer) and
+// speech-recognition (consumer). Re-export here so existing call sites
+// `import { ComposerHandle } from '@djangocfg/ui-tools/chat'` keep
+// working unchanged.
+export type { ComposerHandle } from '@djangocfg/ui-tools/composer-registry';
 
 export interface ChatContextValue extends UseChatReturn {
   layout: UseChatLayoutReturn;
@@ -56,13 +51,6 @@ export interface ChatContextValue extends UseChatReturn {
    * Components like ``AudioToggle`` use this to auto-hide when there
    * is nothing to mute. */
   hasAudio: boolean;
-  /** Composer registry. The built-in `<Composer>` calls
-   *  `registerComposer({ focus })` on mount; custom composers (e.g.
-   *  cmdop's MarkdownEditor wrapper) do the same via the
-   *  `useRegisterComposer` helper. Read it via `composer?.focus()` —
-   *  null until any composer has mounted. Plan64 follow-up. */
-  composer: ComposerHandle | null;
-  registerComposer: (handle: ComposerHandle | null) => void;
   /** Registry of `kind` → renderer for `message.blocks`. `null` when the
    *  host wired none — `<MessageBubble>` then uses `BUILTIN_BLOCK_REGISTRY`. */
   blockRegistry: BlockRegistry | null;
@@ -70,48 +58,6 @@ export interface ChatContextValue extends UseChatReturn {
 
 const Ctx = createContext<ChatContextValue | null>(null);
 
-// ─── Dual-bundle guard ────────────────────────────────────────────────────
-//
-// `@djangocfg/ui-tools` ships its root export through `dist/` (compiled) but
-// most subpaths resolve to raw `src/`. If a consumer mixes them — e.g.
-// `ChatRoot` from the root barrel and `VoiceComposerSlot` from
-// `@djangocfg/ui-tools/speech-recognition` — `createContext(...)` runs twice
-// and produces two distinct context instances. The Composer registers its
-// handle on one; `useChatContextOptional()` in the voice slot reads from the
-// other, sees `null`, and silently drops every transcript.
-//
-// We tag the global with our module identity. When more than one tag is
-// observed the consumer is told exactly what to do.
-type GuardSlot = { stamps: Set<symbol>; warned: boolean };
-const GLOBAL_KEY = '__djangocfg_chat_ctx_stamps__';
-const stamp = Symbol('djangocfg.chat.ctx');
-function markCtxLoad(): void {
-  if (typeof globalThis === 'undefined') return;
-  const g = globalThis as unknown as Record<string, GuardSlot | undefined>;
-  let slot = g[GLOBAL_KEY];
-  if (!slot) {
-    slot = { stamps: new Set(), warned: false };
-    g[GLOBAL_KEY] = slot;
-  }
-  slot.stamps.add(stamp);
-  if (slot.stamps.size > 1 && !slot.warned && process.env.NODE_ENV !== 'production') {
-    slot.warned = true;
-    // eslint-disable-next-line no-console
-    console.warn(
-      '[@djangocfg/ui-tools/chat] Two ChatProvider context instances detected — ' +
-        'this means `@djangocfg/ui-tools` was loaded twice (one bundle via the root ' +
-        '`.` export → `dist/`, another via a `./chat` / `./speech-recognition` subpath → `src/`). ' +
-        'Symptom: `useChatContextOptional()` returns `null` for descendants of `<ChatProvider>`, ' +
-        'so VoiceComposerSlot drops transcripts, useChatReset silently no-ops, etc. ' +
-        '\n\nFix: import every Chat surface from the SAME subpath. Recommended:\n' +
-        "  import { ChatRoot, ChatLauncher, useChatContextOptional, … } from '@djangocfg/ui-tools/chat';\n" +
-        "  import { VoiceComposerSlot } from '@djangocfg/ui-tools/speech-recognition';\n" +
-        '\n(See packages/ui-tools/src/tools/Chat/README.md → "Anti-patterns".)',
-    );
-  }
-}
-markCtxLoad();
-
 export interface ChatProviderProps {
   transport: ChatTransport;
   config?: ChatConfig;
@@ -240,26 +186,17 @@ export function ChatProvider({
     );
   }, [audio]);
 
-  // Composer registry — kept in state (not a ref) so consumers
-  // observing `ctx.composer` re-render when a composer mounts /
-  // unmounts. The setter is the API surface; pass it to the composer
-  // on mount and call with `null` on unmount.
-  const [composer, setComposer] = useState<ComposerHandle | null>(null);
-  const registerComposer = useCallback((handle: ComposerHandle | null) => {
-    setComposer(handle);
-  }, []);
-
   // Re-focus the composer on the streaming → idle edge. Lives here (not
   // in `ChatRoot`) so it works for *every* usage pattern — `ChatRoot`,
   // a hand-rolled `ChatProvider` + `Composer` layout, or headless — as
-  // long as a composer registered its handle.
-  const composerRef = useRef<ComposerHandle | null>(composer);
-  composerRef.current = composer;
+  // long as a composer registered its handle. The active handle lives
+  // in `@djangocfg/ui-tools/composer-registry` — a single cross-tool
+  // registry shared with `<VoiceComposerSlot>`.
   useStreamEndFocus({
     isStreaming: chat.isStreaming,
     enabled: autoFocusOnStreamEnd,
     delayMs: 0,
-    resolveTarget: () => composerRef.current,
+    resolveTarget: () => getActiveComposer(),
   });
 
   const value = useMemo<ChatContextValue>(
@@ -270,11 +207,9 @@ export function ChatProvider({
       labels,
       audio: audioApi,
       hasAudio,
-      composer,
-      registerComposer,
       blockRegistry: blockRegistry ?? null,
     }),
-    [chat, layout, config, labels, audioApi, hasAudio, composer, registerComposer, blockRegistry],
+    [chat, layout, config, labels, audioApi, hasAudio, blockRegistry],
   );
 
   return (

package/src/tools/chat/hooks/useAutoFocusOnStreamEnd.ts

@@ -1,8 +1,13 @@
 'use client';
 
-import { type RefObject, useEffect, useRef } from 'react';
+import { type RefObject, useEffect } from 'react';
 
-import { useChatContextOptional, type ComposerHandle } from '../context';
+import {
+  attachComposer,
+  getActiveComposer,
+  type ComposerHandle,
+} from '@djangocfg/ui-tools/composer-registry';
+import { useChatContextOptional } from '../context';
 import { useStreamEndFocus, type Focusable } from './useStreamEndFocus';
 
 export type { Focusable } from './useStreamEndFocus';
@@ -63,18 +68,14 @@ export function useAutoFocusOnStreamEnd(
   // Prefer the prop (caller knows best), fall back to context.
   const isStreaming = isStreamingProp ?? ctx?.isStreaming ?? false;
 
-  // Keep latest ctx-composer in a ref so target resolution always sees
-  // the freshest registered handle.
-  const composerHandleRef = useRef<ComposerHandle | null>(null);
-  composerHandleRef.current = ctx?.composer ?? null;
-
   useStreamEndFocus({
     isStreaming,
     enabled,
     delayMs,
-    // Resolve in priority order: explicit ref > registered composer.
+    // Resolve in priority order: explicit ref > active composer
+    // (from the cross-tool registry).
     resolveTarget: () =>
-      (targetRef?.current as Focusable | null) ?? composerHandleRef.current,
+      (targetRef?.current as Focusable | null) ?? getActiveComposer(),
   });
 }
 
@@ -94,8 +95,6 @@ export function useAutoFocusOnStreamEnd(
  * No-op when called outside a `<ChatProvider>`.
  */
 export function useRegisterComposer(handle: ComposerHandle): void {
-  const ctx = useChatContextOptional();
-  const register = ctx?.registerComposer;
   const focus = handle.focus;
   const moveCursorToEnd = handle.moveCursorToEnd;
   // Forward `getValue/setValue` too — voice dictation reads/writes the
@@ -104,8 +103,6 @@ export function useRegisterComposer(handle: ComposerHandle): void {
   const getValue = handle.getValue;
   const setValue = handle.setValue;
   useEffect(() => {
-    if (!register) return;
-    register({ focus, moveCursorToEnd, getValue, setValue });
-    return () => register(null);
-  }, [register, focus, moveCursorToEnd, getValue, setValue]);
+    return attachComposer({ focus, moveCursorToEnd, getValue, setValue });
+  }, [focus, moveCursorToEnd, getValue, setValue]);
 }

package/src/tools/chat/hooks/useFocusOnEmptyClick.ts

@@ -3,7 +3,9 @@
 import { useCallback, useRef } from 'react';
 import type { MouseEvent as ReactMouseEvent, RefObject } from 'react';
 
-import { useChatContextOptional, type ComposerHandle } from '../context';
+import { getActiveComposer } from '@djangocfg/ui-tools/composer-registry';
+
+import { useChatContextOptional } from '../context';
 import type { Focusable } from './useAutoFocusOnStreamEnd';
 
 export interface UseFocusOnEmptyClickOptions {
@@ -51,9 +53,6 @@ export function useFocusOnEmptyClick(
   const { targetRef, enabled = true, skipWhileStreaming = true } = options;
   const ctx = useChatContextOptional();
 
-  const composerHandleRef = useRef<ComposerHandle | null>(null);
-  composerHandleRef.current = ctx?.composer ?? null;
-
   const isStreamingRef = useRef(false);
   isStreamingRef.current = ctx?.isStreaming ?? false;
 
@@ -83,7 +82,7 @@ export function useFocusOnEmptyClick(
         explicit.focus?.();
         return;
       }
-      composerHandleRef.current?.focus?.();
+      getActiveComposer()?.focus?.();
     },
     [enabled, skipWhileStreaming, targetRef],
   );

package/src/tools/chat/launcher/header/ChatHeader.tsx

@@ -7,7 +7,6 @@ import {
   Button,
   Tooltip,
   TooltipContent,
-  TooltipProvider,
   TooltipTrigger,
 } from '@djangocfg/ui-core/components';
 import { cn } from '@djangocfg/ui-core/lib';
@@ -66,24 +65,20 @@ export function ChatHeader({
         {actions}
         {closeSlot ??
           (showClose && onClose && (
-            <TooltipProvider delayDuration={300}>
-              <Tooltip>
-                <TooltipTrigger asChild>
-                  <Button
-                    variant="ghost"
-                    size="sm"
-                    onClick={onClose}
-                    aria-label={closeLabel}
-                    className="-mr-1 h-7 w-7 p-0"
-                  >
-                    <X className="h-4 w-4" />
-                  </Button>
-                </TooltipTrigger>
-                {/* Tooltip portals to <body> in ui-core's anchored-overlay
-                    tier, already above the dock — no override needed. */}
-                <TooltipContent side="bottom">{closeLabel}</TooltipContent>
-              </Tooltip>
-            </TooltipProvider>
+            <Tooltip>
+              <TooltipTrigger asChild>
+                <Button
+                  variant="ghost"
+                  size="sm"
+                  onClick={onClose}
+                  aria-label={closeLabel}
+                  className="-mr-1 h-7 w-7 p-0"
+                >
+                  <X className="h-4 w-4" />
+                </Button>
+              </TooltipTrigger>
+              <TooltipContent side="bottom">{closeLabel}</TooltipContent>
+            </Tooltip>
           ))}
       </div>
     </header>

package/src/tools/chat/launcher/header/ChatHeaderActionButton.tsx

@@ -6,7 +6,6 @@ import type { ButtonHTMLAttributes, ReactNode } from 'react';
 import {
   Tooltip,
   TooltipContent,
-  TooltipProvider,
   TooltipTrigger,
 } from '@djangocfg/ui-core/components';
 import { cn } from '@djangocfg/ui-core/lib';
@@ -102,19 +101,16 @@ export const ChatHeaderActionButton = forwardRef<HTMLButtonElement, ChatHeaderAc
     // Opted out — keep the native `title` only.
     if (tooltip === false) return button;
 
-    // Floating tooltip on hover *and* keyboard focus. Self-contained
-    // `<TooltipProvider>` so the button works standalone without the
-    // host wiring an ambient provider; Radix dedupes nested providers.
+    // Floating tooltip on hover *and* keyboard focus.
+    // Host app mounts <UiProviders> (which includes TooltipProvider).
     const tooltipLabel = tooltip ?? ariaLabel;
     return (
-      <TooltipProvider delayDuration={300}>
-        <Tooltip>
-          <TooltipTrigger asChild>{button}</TooltipTrigger>
-          {/* Tooltip portals to <body> in ui-core's anchored-overlay tier,
-              already above the dock — no z-index override needed. */}
-          <TooltipContent side="bottom">{tooltipLabel}</TooltipContent>
-        </Tooltip>
-      </TooltipProvider>
+      <Tooltip>
+        <TooltipTrigger asChild>{button}</TooltipTrigger>
+        {/* Tooltip portals to <body> in ui-core's anchored-overlay tier,
+            already above the dock — no z-index override needed. */}
+        <TooltipContent side="bottom">{tooltipLabel}</TooltipContent>
+      </Tooltip>
     );
   },
 );

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

@@ -1,17 +1,9 @@
 'use client';
 
-import { useCallback, useEffect, useMemo, useRef } from 'react';
+import { useCallback, useEffect, useRef } from 'react';
 import { cn } from '@djangocfg/ui-core/lib';
-import {
-  ContextMenu,
-  ContextMenuContent,
-  ContextMenuItem,
-  ContextMenuSeparator,
-  ContextMenuShortcut,
-  ContextMenuTrigger,
-} from '@djangocfg/ui-core/components';
 
-import { TreeContext, TreeProvider, useTreeContext } from './context/TreeContext';
+import { TreeProvider, useTreeContext } from './context/TreeContext';
 import { TreeDndProvider } from './TreeDndProvider';
 import { TreeContent, treeRowDomId } from './components/TreeContent';
 import { TreeEmptyArea } from './components/TreeEmptyArea';
@@ -22,70 +14,7 @@ import {
   useTreeTypeAhead,
   useTreeFinderHotkeys,
 } from './hooks';
-import type {
-  TreeContextMenuItem,
-  TreeContextMenuSlot,
-  TreeRootProps,
-  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.
- */
-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.
- */
-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;
-}
+import type { TreeActionsHandle, TreeRootProps } from './types';
 
 /**
  * High-level entry point. Wraps Provider + (optional) search bar + content.
@@ -126,6 +55,7 @@ function TreeRoot<T>(props: TreeRootProps<T>) {
     persistSelection = false,
     adapter,
     defaultMenuItems,
+    actionsRef,
     className,
     style,
   } = props;
@@ -171,6 +101,7 @@ function TreeRoot<T>(props: TreeRootProps<T>) {
         enableTypeAhead={enableTypeAhead}
         enableFinderHotkeys={enableFinderHotkeys}
         renderRow={renderRow}
+        actionsRef={actionsRef}
       />
     </TreeProvider>
   );
@@ -183,6 +114,7 @@ interface TreeRootShellProps<T> {
   enableTypeAhead: boolean;
   enableFinderHotkeys: boolean;
   renderRow?: TreeRootProps<T>['renderRow'];
+  actionsRef?: React.MutableRefObject<TreeActionsHandle | null>;
 }
 
 function TreeRootShell<T>({
@@ -192,10 +124,33 @@ function TreeRootShell<T>({
   enableTypeAhead,
   enableFinderHotkeys,
   renderRow,
+  actionsRef,
 }: TreeRootShellProps<T>) {
   const containerRef = useRef<HTMLDivElement>(null);
   const ctx = useTreeContext<T>();
 
+  // Publish the action handle to the outer ref so host code can call
+  // refresh / refreshAll after a mutation that originated outside Tree.
+  // Effect runs after mount; the ref stays populated until unmount.
+  useEffect(() => {
+    if (!actionsRef) return;
+    actionsRef.current = {
+      refresh: ctx.refresh,
+      refreshAll: ctx.refreshAll,
+      expandAll: ctx.expandAll,
+      collapseAll: ctx.collapseAll,
+    };
+    return () => {
+      if (actionsRef.current) actionsRef.current = null;
+    };
+  }, [
+    actionsRef,
+    ctx.refresh,
+    ctx.refreshAll,
+    ctx.expandAll,
+    ctx.collapseAll,
+  ]);
+
   // Keyboard navigation (↑↓ ←→ Home/End Enter Esc Cmd+A, Shift-extend) —
   // scoped via callback ref.
   const isMulti = ctx.selectionMode === 'multiple';
@@ -288,27 +243,9 @@ function TreeRootShell<T>({
     enabled: enableTypeAhead,
   });
 
-  // Build the final renderContextMenu slot from the merged declarative
-  // resolver. `renderContextMenu` (escape-hatch slot) wins if both are
-  // provided. We replace `ctx.renderContextMenu` on the child context
-  // here so TreeRow keeps reading a single source of truth.
-  const finalRenderContextMenu = useMemo<TreeContextMenuSlot<T> | undefined>(() => {
-    if (ctx.renderContextMenu) return ctx.renderContextMenu;
-    const resolve = ctx.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);
-    };
-  }, [ctx.renderContextMenu, ctx.resolvedContextMenuActions]);
-
-  const childCtx = useMemo(
-    () => ({ ...ctx, renderContextMenu: finalRenderContextMenu }),
-    [ctx, finalRenderContextMenu],
-  );
-
+  // Tree body. `ctx.renderContextMenu` is already the final slot —
+  // TreeProvider does the declarative→slot merge centrally, so Shell
+  // doesn't re-derive it (and no nested provider override is needed).
   const treeBody = (
     <div
       ref={setContainerRef}
@@ -336,23 +273,10 @@ function TreeRootShell<T>({
     </div>
   );
 
-  // If we computed a different renderContextMenu slot than the one in
-  // the parent provider, override it via a thin nested provider so
-  // <TreeRow> reads the merged slot. Otherwise skip the wrapper to keep
-  // the render cheap.
-  const body =
-    finalRenderContextMenu === ctx.renderContextMenu ? (
-      treeBody
-    ) : (
-      <TreeContext.Provider value={childCtx as never}>
-        {treeBody}
-      </TreeContext.Provider>
-    );
-
   // Wrap in @dnd-kit context only when DnD is active — `TreeDndProvider`
   // short-circuits to a fragment otherwise, so we don't pay the
   // sensor-registration cost.
-  return <TreeDndProvider>{body}</TreeDndProvider>;
+  return <TreeDndProvider>{treeBody}</TreeDndProvider>;
 }
 
 export default TreeRoot;