@djangocfg/ui-tools 2.1.407 → 2.1.409

package/src/tools/SpeechRecognition/__tests__/language.test.ts

@@ -11,9 +11,15 @@ describe('toBCP47', () => {
     expect(toBCP47('no')).toBe('nb-NO');
   });
 
-  it('falls back to <code>-<UPPER(code)> for unmapped ISO codes', () => {
-    expect(toBCP47('uk')).toBe('uk-UK');
-    expect(toBCP47('cs')).toBe('cs-CS');
+  it('resolves catalogue ISO codes to their canonical dialect', () => {
+    // Not in the built-in table, but present in the Web Speech
+    // catalogue — must resolve to a real region, never `uk-UK`/`cs-CS`.
+    expect(toBCP47('uk')).toBe('uk-UA');
+    expect(toBCP47('cs')).toBe('cs-CZ');
+  });
+
+  it('falls back to <code>-<UPPER(code)> for fully unknown ISO codes', () => {
+    expect(toBCP47('xx')).toBe('xx-XX');
   });
 
   it('passes BCP-47 input through unchanged', () => {

package/src/tools/SpeechRecognition/components/RecordingPulse.tsx

@@ -0,0 +1,59 @@
+'use client';
+
+import type * as React from 'react';
+
+import { cn } from '@djangocfg/ui-core/lib';
+
+export interface RecordingPulseProps {
+  /** When false the overlay is fully hidden (no DOM cost, no animation). */
+  active: boolean;
+  /**
+   * Live RMS mic level 0..1 (from `useMicLevel` / `useSpeechRecognition`).
+   * Drives the pulse amplitude so the ring "breathes" with the voice.
+   * Omit for a steady ambient pulse.
+   */
+  level?: number;
+  /** Tailwind colour token for the ring. @default 'bg-destructive' */
+  tone?: string;
+  className?: string;
+}
+
+/**
+ * Pulsing circle overlay that signals an active recording — Gemini-style
+ * `circle-overlay`. Sits absolutely over a round mic button (`inset-0`),
+ * so the parent must be `relative`.
+ *
+ * Two layers: a steady `animate-ping` halo for the "still recording"
+ * baseline, plus a level-driven ring that scales with mic amplitude so
+ * loud speech visibly bumps the pulse. Pointer-events are off — the
+ * button underneath stays fully clickable.
+ */
+export function RecordingPulse({
+  active,
+  level = 0,
+  tone = 'bg-destructive',
+  className,
+}: RecordingPulseProps): React.ReactElement | null {
+  if (!active) return null;
+
+  // Map RMS 0..1 → a calm 1.0–1.45 scale. Speech rarely exceeds ~0.5
+  // RMS, so we amplify the low end for a lively-but-not-jittery ring.
+  const amp = Math.min(1, Math.max(0, level));
+  const scale = 1 + Math.min(0.45, amp * 0.9);
+  const glowOpacity = 0.25 + Math.min(0.35, amp * 0.7);
+
+  return (
+    <span aria-hidden className={cn('pointer-events-none absolute inset-0', className)}>
+      {/* Steady halo — guarantees visible feedback even in silence. */}
+      <span className={cn('absolute inset-0 rounded-full opacity-30 animate-ping', tone)} />
+      {/* Amplitude ring — scales smoothly with the live mic level. */}
+      <span
+        className={cn(
+          'absolute inset-0 rounded-full transition-transform duration-100 ease-out',
+          tone,
+        )}
+        style={{ transform: `scale(${scale})`, opacity: glowOpacity }}
+      />
+    </span>
+  );
+}

package/src/tools/SpeechRecognition/components/index.ts

@@ -14,3 +14,5 @@ export { ErrorBanner } from './ErrorBanner';
 export type { ErrorBannerProps } from './ErrorBanner';
 export { PushToTalkHint } from './PushToTalkHint';
 export type { PushToTalkHintProps } from './PushToTalkHint';
+export { RecordingPulse } from './RecordingPulse';
+export type { RecordingPulseProps } from './RecordingPulse';

package/src/tools/SpeechRecognition/core/engine/external.ts

@@ -37,8 +37,8 @@ export interface ExternalEngineHandle {
    */
   emitPartial(text: string): void;
   /**
-   * Push the final transcript. Closes the current segment; the engine
-   * emits `final` then transitions to `closed`.
+   * Push the final transcript. Closes the current segment. With the
+   * default `closeOnFinal`, also closes the whole session.
    */
   emitFinal(text: string, confidence?: number): void;
   /** Surface a backend error. Engine transitions to `closed`. */
@@ -85,6 +85,17 @@ export interface ExternalEngineOptions {
    * native side to confirm the capture session opened.
    */
   autoMarkListening?: boolean;
+  /**
+   * If `true` (default), the engine closes the whole session right
+   * after the first `emitFinal` — the common single-shot case (one
+   * recording → one transcript, e.g. cmdop Wails push-to-talk).
+   *
+   * Set `false` for rolling backends that emit many partial/final
+   * pairs within a single capture session (Deepgram-style streaming).
+   * The session then stays `listening` after each `emitFinal` and only
+   * closes on an explicit `stop()` / `abort()` or `emitError`.
+   */
+  closeOnFinal?: boolean;
 }
 
 /**
@@ -124,6 +135,7 @@ export function createExternalEngine(
   opts: ExternalEngineOptions,
 ): RecognitionEngine {
   const bus = createEngineBus();
+  const closeOnFinal = opts.closeOnFinal ?? true;
   let currentSegmentId: string | null = null;
   let unsubscribe: Unsub | null = null;
   let running = false;
@@ -145,11 +157,16 @@ export function createExternalEngine(
       if (!running) return;
       const id = currentSegmentId ?? newSegmentId();
       bus.emit('final', text, id, confidence);
-      // External engines almost always go idle right after their
-      // final — close the session so consumers' `onStop` fires
-      // without requiring a separate `stop()` call.
-      bus.emit('state', 'closed');
-      teardown();
+      // Single-shot engines (default) go idle right after their final —
+      // close the session so consumers' `onStop` fires without a
+      // separate `stop()` call. Rolling engines keep the session open
+      // and just reset the segment so the next partial starts fresh.
+      if (closeOnFinal) {
+        bus.emit('state', 'closed');
+        teardown();
+      } else {
+        currentSegmentId = null;
+      }
     },
     emitError(err: RecognitionError): void {
       bus.emit('error', err);

package/src/tools/SpeechRecognition/core/language.ts

@@ -5,11 +5,14 @@
  * STT services expect.
  *
  * We keep a small built-in table for the locales we ship translations
- * for; everything else falls through to `<code>-<UPPER(code)>`, which
- * works for the majority of regions. The mapping is also re-exported
- * so consumers can extend it.
+ * for; codes outside it are looked up in the full Web Speech catalogue
+ * (so `uk` → `uk-UA`, not the invalid `uk-UK`), and only fall through
+ * to `<code>-<UPPER(code)>` as a last resort. The mapping is also
+ * re-exported so consumers can extend it.
  */
 
+import { WEB_SPEECH_LANGUAGES } from './languages-catalog';
+
 const ISO_TO_BCP47: Record<string, string> = {
   en: 'en-US',
   ru: 'ru-RU',
@@ -32,11 +35,23 @@ const ISO_TO_BCP47: Record<string, string> = {
 
 export const DEFAULT_ISO_TO_BCP47 = ISO_TO_BCP47;
 
+/** ISO-639 primary subtag → default catalogue dialect (e.g. `uk` → `uk-UA`). */
+const CATALOG_ISO_TO_TAG: Record<string, string> = (() => {
+  const map: Record<string, string> = {};
+  for (const lang of WEB_SPEECH_LANGUAGES) {
+    const first = lang.dialects[0];
+    if (first) map[lang.iso.toLowerCase()] = first.code;
+  }
+  return map;
+})();
+
 /**
  * Normalise any of:
  *   - BCP-47 ("en-US", "ru-RU") — passed through.
- *   - ISO 639-1 ("en", "ru")    — mapped via the table above, or
- *                                 falls back to `<code>-<UPPER(code)>`.
+ *   - ISO 639-1 ("en", "ru")    — mapped via the built-in table, then
+ *                                 the full Web Speech catalogue, then
+ *                                 `<code>-<UPPER(code)>` as a last
+ *                                 resort.
  *   - `null`/`undefined`/empty  — returns `undefined`.
  */
 export function toBCP47(
@@ -48,7 +63,9 @@ export function toBCP47(
   if (!trimmed) return undefined;
   if (trimmed.includes('-')) return trimmed; // already BCP-47
   const lower = trimmed.toLowerCase();
-  return table[lower] ?? `${lower}-${lower.toUpperCase()}`;
+  return (
+    table[lower] ?? CATALOG_ISO_TO_TAG[lower] ?? `${lower}-${lower.toUpperCase()}`
+  );
 }
 
 /**

package/src/tools/SpeechRecognition/hooks/usePushToTalk.ts

@@ -13,17 +13,27 @@ export interface UsePushToTalkOptions {
 
 const MOD_KEYS = new Set(['shift', 'ctrl', 'alt', 'meta', 'mod']);
 
+/** `mod` resolves to ⌘ on Apple platforms, Ctrl elsewhere. */
+function isApplePlatform(): boolean {
+  if (typeof navigator === 'undefined') return false;
+  const p =
+    (navigator as { userAgentData?: { platform?: string } }).userAgentData
+      ?.platform ?? navigator.platform;
+  return /mac|iphone|ipad|ipod/i.test(p ?? '');
+}
+
 function parseChord(chord: string): { mods: Set<string>; main: string | null } {
   const parts = chord
     .toLowerCase()
     .split('+')
     .map((s) => s.trim());
+  const modAlias = isApplePlatform() ? 'meta' : 'ctrl';
   const mods = new Set<string>();
   let main: string | null = null;
   for (const part of parts) {
     if (MOD_KEYS.has(part)) {
-      mods.add(part === 'mod' ? 'meta' : part);
-    } else {
+      mods.add(part === 'mod' ? modAlias : part);
+    } else if (part) {
       main = part;
     }
   }
@@ -34,12 +44,33 @@ function matches(e: KeyboardEvent, mods: Set<string>, main: string | null): bool
   if (mods.has('shift') !== e.shiftKey) return false;
   if (mods.has('ctrl') !== e.ctrlKey) return false;
   if (mods.has('alt') !== e.altKey) return false;
-  // 'mod' → meta on mac / ctrl elsewhere; we already normalised to 'meta'.
-  if (mods.has('meta') !== (e.metaKey || (!e.metaKey && false))) return false;
+  if (mods.has('meta') !== e.metaKey) return false;
   if (main && e.key.toLowerCase() !== main) return false;
   return true;
 }
 
+/**
+ * Key-up matcher — modifier state is unreliable on `keyup` (releasing
+ * the modifier itself drops the flag before the main key's keyup), so
+ * we only check the main key here. Pure-modifier chords match when the
+ * released key is one of the chord's modifiers.
+ */
+function matchesRelease(
+  e: KeyboardEvent,
+  mods: Set<string>,
+  main: string | null,
+): boolean {
+  const key = e.key.toLowerCase();
+  if (main) return key === main;
+  // Pure-modifier chord: stop when any chord modifier is released.
+  return (
+    (mods.has('shift') && key === 'shift') ||
+    (mods.has('ctrl') && key === 'control') ||
+    (mods.has('alt') && key === 'alt') ||
+    (mods.has('meta') && key === 'meta')
+  );
+}
+
 /**
  * Hold-to-talk wiring. Press → `start()`, release → `stop()`. Ignores
  * repeats and skips keydown inside `<input>` / `<textarea>` unless a
@@ -70,7 +101,7 @@ export function usePushToTalk(
       void recognition.start();
     };
     const onUp = (e: KeyboardEvent): void => {
-      if (!matches(e, mods, main) && main && e.key.toLowerCase() !== main) return;
+      if (!matchesRelease(e, mods, main)) return;
       if (recognition.status !== 'listening' && recognition.status !== 'starting') return;
       void recognition.stop();
     };

package/src/tools/SpeechRecognition/hooks/useSpeechRecognition.ts

@@ -98,12 +98,22 @@ export function useSpeechRecognition(
     ];
     return () => {
       offs.forEach((off) => off());
+      // Release the mic / socket if the consumer unmounts (or swaps
+      // the engine) mid-session. Without this the MediaRecorder and
+      // getUserMedia stream keep running headless after unmount.
+      engine.abort();
     };
   }, [engine]);
 
-  // AutoStop driven by silence + maxMs caps.
+  // AutoStop driven by silence + maxMs caps. `level` updates ~60fps,
+  // so it must NOT live in the effect deps — otherwise the silence
+  // interval is torn down and recreated every animation frame, which
+  // both wastes CPU and resets the silence timer before it can fire.
+  // The interval reads the freshest level through a ref instead.
   const silenceTimer = useRef<number | null>(null);
   const maxTimer = useRef<number | null>(null);
+  const levelRef = useRef(level);
+  levelRef.current = level;
   useEffect(() => {
     if (state.status !== 'listening') return undefined;
     const { silenceMs, maxMs, silenceThreshold = 0.02 } = config.autoStop ?? {};
@@ -113,9 +123,10 @@ export function useSpeechRecognition(
         void engine.stop();
       }, maxMs);
     }
+    let checkInterval: number | null = null;
     if (silenceMs) {
-      const checkInterval = window.setInterval(() => {
-        if (level < silenceThreshold) {
+      checkInterval = window.setInterval(() => {
+        if (levelRef.current < silenceThreshold) {
           if (silenceTimer.current == null) {
             silenceTimer.current = window.setTimeout(() => {
               log.engine.debug('autoStop silence detected');
@@ -127,19 +138,15 @@ export function useSpeechRecognition(
           silenceTimer.current = null;
         }
       }, 200);
-      return () => {
-        clearInterval(checkInterval);
-        if (silenceTimer.current != null) clearTimeout(silenceTimer.current);
-        silenceTimer.current = null;
-        if (maxTimer.current != null) clearTimeout(maxTimer.current);
-        maxTimer.current = null;
-      };
     }
     return () => {
+      if (checkInterval != null) clearInterval(checkInterval);
+      if (silenceTimer.current != null) clearTimeout(silenceTimer.current);
+      silenceTimer.current = null;
       if (maxTimer.current != null) clearTimeout(maxTimer.current);
       maxTimer.current = null;
     };
-  }, [state.status, config.autoStop, level, engine]);
+  }, [state.status, config.autoStop, engine]);
 
   const start = useCallback(async () => {
     if (state.status === 'listening' || state.status === 'starting') return;

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

@@ -2,7 +2,7 @@
 
 import type * as React from 'react';
 import { useCallback, useEffect, useRef } from 'react';
-import { Loader2, Mic } from 'lucide-react';
+import { AlertCircle, Loader2, Mic } from 'lucide-react';
 
 import { useCountdownFromSeconds, useNotificationSounds } from '@djangocfg/ui-core/hooks';
 import { cn } from '@djangocfg/ui-core/lib';
@@ -13,8 +13,12 @@ import { useVoiceSupport } from '../hooks/useVoiceSupport';
 import { getSpeechLogger } from '../core/logger';
 import { normaliseFinal } from '../core/transcript';
 import { DEFAULT_VOICE_SOUNDS, type VoiceSoundEvent } from '../core/audio/defaults';
+import { RecordingPulse } from '../components/RecordingPulse';
 import type { RecognitionEngine } from '../types';
 
+/** High-level visual state the composer mic button reflects. */
+export type VoiceSlotState = 'idle' | 'listening' | 'processing' | 'error';
+
 const log = getSpeechLogger();
 
 export interface VoiceComposerSlotProps {
@@ -51,18 +55,26 @@ export interface VoiceComposerSlotProps {
    * — users can silence everything via their own UI.
    */
   sounds?: boolean | { start?: string; stop?: string };
+  /** Notified whenever the high-level visual state changes. */
+  onStateChange?: (state: VoiceSlotState) => void;
 }
 
+/**
+ * Per-size geometry. Mirrors the chat composer action-bar buttons
+ * (`composer-kit/ComposerButton` `BUTTON_SIZE`) so the slot drops into
+ * `composerSlots.inlineEnd` round and correctly sized with no host CSS.
+ */
 const SIZE_CLS: Record<NonNullable<VoiceComposerSlotProps['size']>, string> = {
-  sm: 'h-8 w-8 [&_svg]:h-4 [&_svg]:w-4',
-  md: 'h-9 w-9 [&_svg]:h-4 [&_svg]:w-4',
-  lg: 'h-12 w-12 [&_svg]:h-5 [&_svg]:w-5',
+  sm: 'h-7 w-7 [&_svg]:size-4',
+  md: 'h-9 w-9 [&_svg]:size-[1.125rem]',
+  lg: 'h-11 w-11 [&_svg]:size-5',
 };
 
 const STORAGE_KEY = 'djangocfg-stt:voice-sounds';
 
 /**
- * Drop-in slot for the `<Composer toolbarEnd>` (or `toolbarStart`) prop.
+ * Drop-in microphone slot for `<Composer>` — pass it as a raw node via
+ * `composerSlots.inlineEnd` (inline layout) or `composerSlots.blockStart`.
  *
  * Renders a microphone button — but only when the browser + device
  * combination can actually do speech recognition. Firefox, in-app
@@ -89,6 +101,7 @@ export function VoiceComposerSlot({
   className,
   onFinish,
   sounds = true,
+  onStateChange,
 }: VoiceComposerSlotProps): React.ReactElement | null {
   const support = useVoiceSupport(engine);
 
@@ -113,7 +126,7 @@ export function VoiceComposerSlot({
 
   // Resolve value/onChange: prop wins; otherwise pull from the
   // registered composer handle. The slot can therefore be dropped into
-  // `composerToolbarEnd` of `ChatRoot` with zero props.
+  // `composerBlockStart` of `ChatRoot` with zero props.
   const resolvedGetValue = useCallback((): string => {
     if (value !== undefined) return value;
     return composerHandleRef.current?.getValue?.() ?? '';
@@ -289,51 +302,106 @@ export function VoiceComposerSlot({
     void rec.start();
   }, [rec, resolvedGetValue]);
 
+  // Derive the high-level visual state from the engine status. The
+  // engine owns the truth — `processing` is the post-speech tail while
+  // the final result settles (`stopping`), `error` is a recoverable
+  // failure that resets to `idle` on the next press.
+  const stopping = rec.status === 'stopping';
+  const slotState: VoiceSlotState = listening
+    ? 'listening'
+    : stopping
+      ? 'processing'
+      : rec.status === 'error'
+        ? 'error'
+        : 'idle';
+
+  // Notify the host on every transition (after render, ref-guarded so
+  // identical states never fire twice).
+  const lastStateRef = useRef<VoiceSlotState | null>(null);
+  const onStateChangeRef = useRef(onStateChange);
+  onStateChangeRef.current = onStateChange;
+  useEffect(() => {
+    if (lastStateRef.current === slotState) return;
+    lastStateRef.current = slotState;
+    onStateChangeRef.current?.(slotState);
+  }, [slotState]);
+
   if (!support.supported) return null;
   if (hideOnMobile && support.isMobile) return null;
 
-  const stopping = rec.status === 'stopping';
+  // Tooltip: countdown + hotkey hint while listening, error copy on
+  // failure, plain prompt otherwise.
+  const tooltip =
+    slotState === 'listening'
+      ? `Listening — ${countdown.label || `${maxSeconds}s left`} · Enter to finish · Esc to cancel`
+      : slotState === 'processing'
+        ? 'Transcribing…'
+        : slotState === 'error'
+          ? rec.error?.message || 'Dictation failed — tap to retry'
+          : 'Dictate message';
 
-  // Tooltip: countdown + hotkey hint while listening, plain copy
-  // otherwise. Avoids the absolutely-positioned label that clipped
-  // against the composer bottom edge in the previous design.
-  const tooltip = listening
-    ? `Listening — ${countdown.label || `${maxSeconds}s left`} · Enter to finish · Esc to cancel`
-    : 'Dictate message';
+  const ariaLabel =
+    slotState === 'listening'
+      ? 'Stop dictation'
+      : slotState === 'error'
+        ? 'Dictation failed — retry'
+        : 'Dictate message';
 
   return (
     <span className="inline-flex items-center gap-1.5 !h-auto">
-      {listening && countdown.label ? (
+      {slotState === 'listening' && countdown.label ? (
         <span
           aria-hidden
-          className="rounded-full bg-destructive/10 px-1.5 py-0.5 font-mono text-[10px] leading-none text-destructive tabular-nums"
+          className="rounded-full bg-destructive/10 px-1.5 py-0.5 font-mono text-[10px] leading-none text-destructive tabular-nums animate-in fade-in duration-200"
         >
           {countdown.label}
         </span>
       ) : null}
+      {slotState === 'error' ? (
+        <span
+          aria-hidden
+          className="rounded-full bg-destructive/10 px-1.5 py-0.5 text-[10px] leading-none text-destructive animate-in fade-in duration-200"
+        >
+          Failed
+        </span>
+      ) : null}
       <button
         type="button"
         onClick={toggle}
-        aria-pressed={listening}
-        aria-label={listening ? 'Stop dictation' : 'Dictate message'}
+        aria-pressed={slotState === 'listening'}
+        aria-label={ariaLabel}
         title={tooltip}
+        data-state={slotState}
         className={cn(
-          'relative inline-flex items-center justify-center rounded-full transition-colors',
+          'relative inline-flex items-center justify-center rounded-full transition-all duration-200',
           'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2',
           SIZE_CLS[size],
-          listening
-            ? 'bg-destructive text-destructive-foreground hover:bg-destructive/90'
-            : 'text-muted-foreground hover:bg-muted hover:text-foreground',
+          slotState === 'listening' &&
+            'bg-destructive text-destructive-foreground hover:bg-destructive/90',
+          slotState === 'processing' &&
+            'bg-primary/10 text-primary hover:bg-primary/15',
+          slotState === 'error' &&
+            'bg-destructive/10 text-destructive hover:bg-destructive/15',
+          slotState === 'idle' &&
+            'text-muted-foreground hover:bg-muted hover:text-foreground',
           className,
         )}
       >
-        {listening && (
-          <span
-            aria-hidden
-            className="absolute inset-0 rounded-full bg-destructive/30 animate-ping"
+        {/* Recording feedback — pulsing circle overlay driven by the
+            live mic level. Hidden in every non-listening state. */}
+        <RecordingPulse active={slotState === 'listening'} level={rec.level} />
+        {slotState === 'processing' ? (
+          <Loader2 className="animate-spin" />
+        ) : slotState === 'error' ? (
+          <AlertCircle />
+        ) : (
+          <Mic
+            className={cn(
+              'transition-transform duration-200',
+              slotState === 'listening' && 'scale-110',
+            )}
           />
         )}
-        {stopping ? <Loader2 className="animate-spin" /> : <Mic />}
       </button>
     </span>
   );

package/src/tools/SpeechRecognition/widgets/index.ts

@@ -3,4 +3,4 @@ export type { DictationFieldProps } from './DictationField';
 export { VoiceMessageRecorder } from './VoiceMessageRecorder';
 export type { VoiceMessageRecorderProps } from './VoiceMessageRecorder';
 export { VoiceComposerSlot } from './VoiceComposerSlot';
-export type { VoiceComposerSlotProps } from './VoiceComposerSlot';
+export type { VoiceComposerSlotProps, VoiceSlotState } from './VoiceComposerSlot';

package/src/tools/Tree/README.md

@@ -275,11 +275,7 @@ The active mode is also exposed on each row as
 ## VSCode-style file icons
 
 Tree is generic over `T` — it has no opinion on whether nodes are files. For a
-ready-made VSCode-style icon set, install the optional companion subpath:
-
-```bash
-pnpm add material-file-icons
-```
+ready-made VSCode-style icon set, use the `file-icon` companion subpath:
 
 ```tsx
 import { TreeRoot } from '@djangocfg/ui-tools/tree';
@@ -292,9 +288,9 @@ import { createFileIconSlot } from '@djangocfg/ui-tools/file-icon';
 />
 ```
 
-`material-file-icons` is declared in `optionalDependencies`. If it's not
-installed, `<FileIcon>` falls back to a Lucide `File` icon — no warnings, no
-runtime errors.
+The icon SVGs are vendored statically from `material-file-icons` (MIT) — no
+runtime dependency, no install step, and resolution is synchronous in any
+bundler.
 
 Folders use a small built-in mapping (`src` → `FolderCode`,
 `node_modules` → `Package`, `.git` → `FolderGit2`, `dist`/`build`/`.next`

package/src/tools/Tree/TreeRoot.tsx

@@ -1,10 +1,10 @@
 'use client';
 
-import { useCallback, useRef } from 'react';
+import { useCallback, useEffect, useRef } from 'react';
 import { cn } from '@djangocfg/ui-core/lib';
 
 import { TreeProvider, useTreeContext } from './context/TreeContext';
-import { TreeContent } from './components/TreeContent';
+import { TreeContent, treeRowDomId } from './components/TreeContent';
 import { TreeSearchInput } from './components/TreeSearchInput';
 import { appearanceToStyle } from './data/appearance';
 import { useTreeKeyboard } from './hooks/useTreeKeyboard';
@@ -125,15 +125,22 @@ function TreeRootShell<T>({
     [keyboardRef],
   );
 
-  // Type-ahead jump.
+  // Keep the focused row scrolled into view whenever focus moves (keyboard
+  // nav, type-ahead, programmatic). Centralised so every focus source gets
+  // consistent scrolling — previously only type-ahead scrolled.
+  const focusedId = ctx.focused;
+  useEffect(() => {
+    if (!focusedId) return;
+    const el = containerRef.current?.querySelector<HTMLElement>(
+      `[data-tree-row][data-id="${CSS.escape(focusedId)}"]`,
+    );
+    el?.scrollIntoView({ block: 'nearest' });
+  }, [focusedId]);
+
+  // Type-ahead jump — focus update; scrolling handled by the effect above.
   const onTypeAheadMatch = useCallback(
     (id: string) => {
       ctx.setFocus(id);
-      // Scroll the row into view if it has rendered.
-      const el = containerRef.current?.querySelector<HTMLElement>(
-        `[data-tree-row][data-id="${CSS.escape(id)}"]`,
-      );
-      el?.scrollIntoView({ block: 'nearest' });
     },
     [ctx],
   );
@@ -150,8 +157,13 @@ function TreeRootShell<T>({
     <div
       ref={setContainerRef}
       tabIndex={0}
+      role="tree"
+      aria-label={ctx.labels.ariaLabel}
+      aria-multiselectable={ctx.selectionMode === 'multiple' || undefined}
+      aria-activedescendant={focusedId ? treeRowDomId(focusedId) : undefined}
       className={cn(
-        'group/tree flex h-full w-full flex-col gap-2 outline-none',
+        'group/tree flex h-full w-full flex-col gap-2 rounded-sm outline-none',
+        'focus-visible:ring-1 focus-visible:ring-ring/50',
         className,
       )}
       style={{ ...appearanceToStyle(ctx.appearance), ...style }}
@@ -159,7 +171,7 @@ function TreeRootShell<T>({
     >
       {enableSearch ? <TreeSearchInput className="mx-2 mt-2" /> : null}
       <div className="min-h-0 flex-1 overflow-auto px-1">
-        <TreeContent<T>>{renderRow}</TreeContent>
+        <TreeContent<T> role="group">{renderRow}</TreeContent>
       </div>
     </div>
   );