@djangocfg/ui-tools 2.1.416 → 2.1.418

package/src/tools/forms/NotionEditor/styles.css

@@ -0,0 +1,478 @@
+/* ─────────────────────────────────────────────────────────────────────
+ * NotionEditor — Notion-style WYSIWYG. Reuses the typography decisions
+ * from MarkdownEditor's `styles.css` (font, heading scale, list spacing,
+ * code styling) but adds:
+ *   - drag-handle gutter + grabber styling
+ *   - bubble-menu floating toolbar
+ *   - slash-menu popover
+ *   - table cell selection ring
+ *   - code-block lowlight token colours (Prism-compatible)
+ * ───────────────────────────────────────────────────────────────────── */
+
+.notion-editor {
+  position: relative;
+  width: 100%;
+}
+
+.notion-editor .notion-editor-content {
+  outline: none;
+}
+
+.notion-editor .tiptap,
+.notion-editor .ProseMirror {
+  color: var(--color-foreground, var(--foreground));
+  font-family:
+    -apple-system, BlinkMacSystemFont, "SF Pro Text", "Segoe UI", Roboto,
+    "Helvetica Neue", Arial, sans-serif;
+  font-size: 16px;
+  line-height: 1.65;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+  text-rendering: optimizeLegibility;
+  /* Left padding leaves room for the drag-handle gutter so it never
+   * overlaps with text. */
+  padding-left: 32px;
+  padding-right: 8px;
+}
+
+/* Empty placeholder. Tiptap's Placeholder extension stamps
+ * `is-editor-empty` on the doc when nothing has been typed, plus
+ * `is-empty` + `data-placeholder` on the active empty node. We match
+ * BOTH conditions so the ghost prompt shows on a brand-new editor and
+ * on whichever empty block the caret is parked in — but never on
+ * unrelated empty blocks (that would look like literal text content). */
+.notion-editor .tiptap .is-editor-empty:first-child::before,
+.notion-editor .tiptap .ProseMirror-focused > .is-empty::before {
+  content: attr(data-placeholder);
+  float: left;
+  height: 0;
+  pointer-events: none;
+  opacity: 0.35;
+  font-weight: 400;
+}
+
+/* Links */
+.notion-editor .tiptap a {
+  color: var(--color-primary, var(--primary));
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
+
+/* Headings */
+.notion-editor .tiptap h1 {
+  font-size: 2em;
+  font-weight: 700;
+  line-height: 1.2;
+  margin: 1em 0 0.3em;
+  letter-spacing: -0.02em;
+}
+.notion-editor .tiptap h2 {
+  font-size: 1.5em;
+  font-weight: 600;
+  line-height: 1.3;
+  margin: 0.9em 0 0.25em;
+  letter-spacing: -0.01em;
+}
+.notion-editor .tiptap h3 {
+  font-size: 1.25em;
+  font-weight: 600;
+  line-height: 1.35;
+  margin: 0.8em 0 0.2em;
+}
+.notion-editor .tiptap h4 {
+  font-size: 1.1em;
+  font-weight: 600;
+  line-height: 1.4;
+  margin: 0.7em 0 0.2em;
+}
+.notion-editor .tiptap > :is(h1, h2, h3, h4):first-child {
+  margin-top: 0;
+}
+
+.notion-editor .tiptap p {
+  margin: 0.25em 0;
+}
+
+/* Lists */
+.notion-editor .tiptap ul,
+.notion-editor .tiptap ol {
+  padding-left: 1.5em;
+  margin: 0.35em 0;
+}
+.notion-editor .tiptap ul {
+  list-style: disc;
+}
+.notion-editor .tiptap ol {
+  list-style: decimal;
+}
+.notion-editor .tiptap ul ul {
+  list-style: circle;
+}
+.notion-editor .tiptap ul ul ul {
+  list-style: square;
+}
+.notion-editor .tiptap li {
+  margin: 0.15em 0;
+}
+.notion-editor .tiptap li > p {
+  margin: 0;
+}
+
+/* Task list — backed by a React NodeView that mounts our ui-core
+ * <Checkbox>. Selectors target the wrapper class set by `TaskItemView`.
+ *
+ * Alignment math (the part that always goes wrong):
+ *   editor font-size:    16px
+ *   line-height:         1.65 → line box ≈ 26.4px
+ *   cap-height of text:  ≈ 11.5px, sits ≈ 7.5px from line top
+ *   checkbox box:        16px square (ui-core default)
+ *   ⇒ to centre the checkbox on the cap-height row, top = (26.4 − 16) / 2 ≈ 5px
+ *
+ * Using `align-items: flex-start` + a fixed `margin-top` keeps multi-line
+ * task items working: the checkbox stays parked at the top of the first
+ * line and the text wraps freely below. `align-items: center` would
+ * recentre on multi-line items and drift the checkbox into the middle. */
+.notion-editor .tiptap ul[data-type="taskList"] {
+  list-style: none;
+  padding-left: 0;
+  margin-left: 0;
+}
+.notion-editor .tiptap .notion-task-item {
+  display: flex;
+  /* `align-items: baseline` lets the checkbox sit on the *text baseline*
+   * of the first line — independent of checkbox size, font-size, or
+   * line-height. Works correctly across themes / presets that scale the
+   * Checkbox token (macOS vs default). For multi-line items the checkbox
+   * still anchors to the first line (because baseline is per-line) which
+   * is what Notion does. Earlier `align-items: flex-start + margin-top:Xpx`
+   * was brittle: it assumed a fixed checkbox size + line-height. */
+  align-items: baseline;
+  gap: 0.5em;
+  padding: 2px 0;
+}
+.notion-editor .tiptap .notion-task-checkbox {
+  flex-shrink: 0;
+  /* `translateY(2px)` nudges the optical centre of the checkbox box onto
+   * the cap-height line. Without this the checkbox sits visually a bit
+   * high because its bounding box centres on the baseline, not cap-height.
+   * Tiny constant — independent of checkbox / font size. */
+  transform: translateY(2px);
+}
+.notion-editor .tiptap .notion-task-text {
+  flex: 1;
+  min-width: 0;
+}
+.notion-editor .tiptap .notion-task-item[data-checked] .notion-task-text {
+  opacity: 0.55;
+  text-decoration: line-through;
+}
+
+/* Blockquote */
+.notion-editor .tiptap blockquote {
+  border-left: 3px solid var(--color-border, var(--border));
+  padding: 0.2em 0 0.2em 1em;
+  margin: 0.6em 0;
+  color: color-mix(in oklab, var(--color-foreground, var(--foreground)) 80%, transparent);
+}
+.notion-editor .tiptap blockquote > :first-child { margin-top: 0; }
+.notion-editor .tiptap blockquote > :last-child  { margin-bottom: 0; }
+
+/* Divider */
+.notion-editor .tiptap hr {
+  border: none;
+  border-top: 1px solid var(--color-border, var(--border));
+  margin: 1.5em 0;
+}
+
+/* Inline code */
+.notion-editor .tiptap code {
+  background: color-mix(in oklab, var(--color-muted, var(--muted)) 70%, transparent);
+  color: var(--color-foreground, var(--foreground));
+  padding: 0.15em 0.35em;
+  border-radius: 4px;
+  font-size: 0.875em;
+  font-family: "SF Mono", ui-monospace, "JetBrains Mono", "Fira Code", Menlo, Consolas, monospace;
+  border: 1px solid color-mix(in oklab, var(--color-border, var(--border)) 60%, transparent);
+}
+
+/* Code block (lowlight) — always dark, regardless of host theme.
+ * Rationale: syntax highlighting palettes are calibrated for dark
+ * backgrounds; a "light-on-light" code block on a light app theme looks
+ * washed out and reads worse than the same block on dark. Notion / Linear
+ * / GitHub all force-dark code blocks on light themes too. We hardcode
+ * a One Dark-flavour surface and let the token colours below sit on it. */
+.notion-editor .tiptap pre {
+  background: #1e2127;
+  color: #d7dae0;
+  padding: 0.9em 1em;
+  border-radius: 6px;
+  margin: 0.75em 0;
+  font-family: "SF Mono", ui-monospace, "JetBrains Mono", "Fira Code", Menlo, Consolas, monospace;
+  font-size: 0.875em;
+  line-height: 1.55;
+  overflow-x: auto;
+  border: 1px solid rgba(255, 255, 255, 0.06);
+}
+.notion-editor .tiptap pre code {
+  background: transparent;
+  border: none;
+  padding: 0;
+  border-radius: 0;
+  font-size: inherit;
+  color: inherit;
+}
+
+/* Lowlight token colours — One Dark Pro palette. `@tiptap/extension-code-
+ * block-lowlight` emits `.hljs-*` class names; we colour against the fixed
+ * dark surface above so the palette stays readable on every host theme. */
+.notion-editor .hljs-comment,
+.notion-editor .hljs-quote { color: #5c6370; font-style: italic; }
+.notion-editor .hljs-keyword,
+.notion-editor .hljs-selector-tag,
+.notion-editor .hljs-built_in { color: #c678dd; }
+.notion-editor .hljs-string,
+.notion-editor .hljs-attr { color: #98c379; }
+.notion-editor .hljs-number,
+.notion-editor .hljs-literal { color: #d19a66; }
+.notion-editor .hljs-function .hljs-title,
+.notion-editor .hljs-title.function_ { color: #61afef; }
+.notion-editor .hljs-class .hljs-title,
+.notion-editor .hljs-type { color: #e5c07b; }
+.notion-editor .hljs-tag,
+.notion-editor .hljs-name { color: #e06c75; }
+.notion-editor .hljs-attribute { color: #d19a66; }
+.notion-editor .hljs-variable,
+.notion-editor .hljs-template-variable { color: #e06c75; }
+.notion-editor .hljs-symbol,
+.notion-editor .hljs-bullet,
+.notion-editor .hljs-link { color: #56b6c2; }
+.notion-editor .hljs-meta { color: #61afef; }
+.notion-editor .hljs-deletion { background: rgba(224, 108, 117, 0.2); }
+.notion-editor .hljs-addition { background: rgba(152, 195, 121, 0.2); }
+
+/* Tables */
+.notion-editor .tiptap table {
+  border-collapse: collapse;
+  width: 100%;
+  margin: 0.75em 0;
+  font-size: 0.95em;
+  table-layout: fixed;
+}
+.notion-editor .tiptap th,
+.notion-editor .tiptap td {
+  border: 1px solid var(--color-border, var(--border));
+  padding: 0.45em 0.75em;
+  vertical-align: top;
+  text-align: left;
+  min-width: 4ch;
+  position: relative;
+}
+.notion-editor .tiptap th {
+  background: color-mix(in oklab, var(--color-muted, var(--muted)) 60%, transparent);
+  font-weight: 600;
+}
+.notion-editor .tiptap .selectedCell::after {
+  /* ProseMirror table cell selection ring. */
+  background: color-mix(in oklab, var(--color-primary, var(--primary)) 20%, transparent);
+  content: "";
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+  z-index: 2;
+}
+
+/* Images */
+.notion-editor .tiptap img {
+  max-width: 100%;
+  height: auto;
+  border-radius: 6px;
+  margin: 0.5em 0;
+}
+
+/* Marks */
+.notion-editor .tiptap strong { font-weight: 700; }
+.notion-editor .tiptap em { font-style: italic; }
+.notion-editor .tiptap s { text-decoration: line-through; }
+.notion-editor .tiptap mark {
+  background: color-mix(in oklab, var(--color-primary, var(--primary)) 25%, transparent);
+  color: inherit;
+  padding: 0 0.15em;
+  border-radius: 2px;
+}
+
+/* Selection */
+.notion-editor .tiptap ::selection {
+  background: color-mix(in oklab, var(--color-primary, var(--primary)) 25%, transparent);
+}
+
+/* ─────────────────────────────────────────────────────────────────────
+ * Global drag handle (tiptap-extension-global-drag-handle)
+ *
+ * The extension mints a single `.drag-handle` element and reparents it
+ * to the hovered block on `mouseover`. We mask a fixed 2×3 dot grid
+ * (Notion's ⠿ grip) — earlier attempts used `background-repeat: round`
+ * which tiled the dot pattern and produced a 3×5 grid that looked like
+ * a literal halftone block. A `mask-image` with `mask-repeat: no-repeat`
+ * pins exactly six dots regardless of the handle's box size.
+ * ───────────────────────────────────────────────────────────────────── */
+.drag-handle {
+  position: fixed;
+  opacity: 0;
+  transition: opacity 120ms ease-out;
+  height: 1.4rem;
+  width: 1.1rem;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: 4px;
+  cursor: grab;
+  background-color: transparent;
+
+  /* Painted as a `mask-image` of `lucide-react`'s `GripVertical` icon
+   * (six stroked circles at x∈{9,15}, y∈{5,12,19}, r=1, stroke-width=2,
+   * viewBox 24×24). Using lucide ensures the grabber matches every other
+   * icon in the app at the pixel level; we just can't render it as a
+   * <GripVertical/> component because `tiptap-extension-global-drag-handle`
+   * mints the DOM node imperatively. `mask` + `background-color` keeps
+   * the colour theme-driven. */
+  -webkit-mask-image: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'><circle cx='9' cy='12' r='1'/><circle cx='9' cy='5' r='1'/><circle cx='9' cy='19' r='1'/><circle cx='15' cy='12' r='1'/><circle cx='15' cy='5' r='1'/><circle cx='15' cy='19' r='1'/></svg>");
+          mask-image: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'><circle cx='9' cy='12' r='1'/><circle cx='9' cy='5' r='1'/><circle cx='9' cy='19' r='1'/><circle cx='15' cy='12' r='1'/><circle cx='15' cy='5' r='1'/><circle cx='15' cy='19' r='1'/></svg>");
+  -webkit-mask-repeat: no-repeat;
+          mask-repeat: no-repeat;
+  -webkit-mask-position: center;
+          mask-position: center;
+  -webkit-mask-size: 18px 18px;
+          mask-size: 18px 18px;
+  background-color: color-mix(in oklab, var(--color-foreground, var(--foreground)) 45%, transparent);
+}
+.drag-handle:hover {
+  background-color: var(--color-foreground, var(--foreground));
+}
+.drag-handle:active {
+  cursor: grabbing;
+}
+.drag-handle.hide {
+  opacity: 0 !important;
+  pointer-events: none;
+}
+/* Reveal the handle whenever the editor surface is hovered. */
+.notion-editor:hover .drag-handle {
+  opacity: 1;
+}
+
+/* ─────────────────────────────────────────────────────────────────────
+ * Bubble menu — floating selection toolbar
+ * ───────────────────────────────────────────────────────────────────── */
+.notion-bubble-menu {
+  display: flex;
+  gap: 2px;
+  padding: 4px;
+  background: var(--color-popover, var(--popover));
+  color: var(--color-popover-foreground, var(--popover-foreground));
+  border: 1px solid var(--color-border, var(--border));
+  border-radius: 8px;
+  box-shadow: 0 8px 30px rgba(0, 0, 0, 0.35);
+  z-index: 50;
+}
+.notion-bubble-btn {
+  width: 28px;
+  height: 28px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  background: transparent;
+  border: none;
+  border-radius: 4px;
+  cursor: pointer;
+  color: var(--color-foreground, var(--foreground));
+  opacity: 0.7;
+  transition: opacity 120ms, background 120ms;
+}
+.notion-bubble-btn:hover {
+  opacity: 1;
+  background: var(--color-muted, var(--muted));
+}
+.notion-bubble-btn--active {
+  opacity: 1;
+  background: var(--color-muted, var(--muted));
+}
+
+/* ─────────────────────────────────────────────────────────────────────
+ * Slash menu popover
+ * ───────────────────────────────────────────────────────────────────── */
+.notion-slash-list {
+  background: var(--color-popover, var(--popover));
+  color: var(--color-popover-foreground, var(--popover-foreground));
+  border: 1px solid var(--color-border, var(--border));
+  border-radius: 10px;
+  box-shadow: 0 12px 36px rgba(0, 0, 0, 0.5);
+  padding: 4px;
+  width: 280px;
+  max-height: 320px;
+  overflow-y: auto;
+  display: flex;
+  flex-direction: column;
+  gap: 1px;
+}
+.notion-slash-item {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  width: 100%;
+  padding: 6px 8px;
+  border: none;
+  background: transparent;
+  border-radius: 6px;
+  cursor: pointer;
+  text-align: left;
+  color: inherit;
+  font-size: 13px;
+  transition: background 80ms;
+}
+.notion-slash-item--active,
+.notion-slash-item:hover {
+  background: var(--color-muted, var(--muted));
+}
+.notion-slash-empty {
+  padding: 10px 12px;
+  color: color-mix(in oklab, var(--color-foreground, var(--foreground)) 55%, transparent);
+  font-size: 12px;
+  text-align: center;
+}
+.notion-slash-icon {
+  width: 32px;
+  height: 32px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  border: 1px solid var(--color-border, var(--border));
+  border-radius: 6px;
+  background: color-mix(in oklab, var(--color-muted, var(--muted)) 40%, transparent);
+}
+.notion-slash-meta {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+  flex: 1;
+}
+.notion-slash-hint {
+  flex-shrink: 0;
+  padding: 1px 6px;
+  border: 1px solid var(--color-border, var(--border));
+  border-radius: 4px;
+  font-size: 10.5px;
+  font-family: "SF Mono", ui-monospace, "JetBrains Mono", Menlo, Consolas, monospace;
+  color: color-mix(in oklab, var(--color-foreground, var(--foreground)) 55%, transparent);
+  background: color-mix(in oklab, var(--color-muted, var(--muted)) 30%, transparent);
+}
+.notion-slash-title {
+  font-weight: 500;
+  font-size: 13px;
+  line-height: 1.3;
+}
+.notion-slash-desc {
+  font-size: 11.5px;
+  opacity: 0.6;
+  line-height: 1.3;
+}

package/src/tools/forms/NotionEditor/types.ts

@@ -0,0 +1,28 @@
+import type { Editor } from '@tiptap/react';
+
+export interface NotionEditorProps {
+  value: string;
+  onChange: (markdown: string) => void;
+  /** Markdown placeholder shown when document is empty. */
+  placeholder?: string;
+  /** Disable editing — turns the editor into a read-only renderer. */
+  disabled?: boolean;
+  /** Focus the editor on mount. Pair with `key={path}` upstream when the
+   *  host wants a fresh focus per source change. */
+  autoFocus?: boolean;
+  /** Called when the user presses Cmd/Ctrl+S inside the editor. Receives
+   *  the current markdown. The browser default is suppressed. */
+  onSave?: (markdown: string) => void;
+  /** Extra class name on the outer wrapper. */
+  className?: string;
+  /** Minimum height of the editor surface in px. Default 320. */
+  minHeight?: number;
+}
+
+/** Imperative handle exposed via `ref`. Compatible with `ComposerHandle`
+ *  shape used by the chat suite (focus / moveCursorToEnd). */
+export interface NotionEditorHandle {
+  focus: () => void;
+  moveCursorToEnd: () => void;
+  getEditor: () => Editor | null;
+}

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>