@djangocfg/ui-tools 2.1.430 → 2.1.432

package/src/tools/forms/NotionEditor/README.md

@@ -3,9 +3,10 @@
 Notion-style WYSIWYG markdown editor built on **TipTap v3**.
 
 Lazy-loaded sibling of [`MarkdownEditor`](../MarkdownEditor/) — same
-markdown round-trip, but with a heavier extension stack and the
-floating menus (slash / bubble / drag handle) that users expect from a
-"document" editor.
+markdown round-trip, but with a heavier extension stack, the floating
+menus (slash / bubble / drag handle) users expect from a "document"
+editor, **and serializable block nodes** (a link-preview *bookmark*
+card and an interactive *map* block) that round-trip through markdown.
 
 ```tsx
 import { NotionEditor } from '@djangocfg/ui-tools/notion-editor';
@@ -16,84 +17,96 @@ import { NotionEditor } from '@djangocfg/ui-tools/notion-editor';
   onSave={(md) => writeFile(md)}
   autoFocus
   placeholder="Type '/' for commands…"
+  resolveLinkPreview={unfurl}   // optional — powers bookmark cards
 />
 ```
 
+> **Bundle.** The full stack (lowlight common pack + tables + drag
+> handle, plus the lazy MapLibre chunk when a map block mounts) lands
+> around ~350 KB minified. `@djangocfg/ui-tools/notion-editor` is the
+> **lazy** entry (`lazy.tsx`) — pages that never render the editor pay
+> nothing. All of it is `'use client'`.
+
 ## When to use this vs `MarkdownEditor`
 
-| Use case                                | Pick                |
-| --------------------------------------- | ------------------- |
-| Chat composer, single-paragraph input   | `MarkdownEditor`    |
-| Note / doc surface, multi-paragraph     | `NotionEditor`      |
-| `.md` file viewer with full editing     | `NotionEditor`      |
-| Slim mention dropdown, no tables/tasks  | `MarkdownEditor`    |
-| Slash menu, drag handle, tables, hljs   | `NotionEditor`      |
-
-The two coexist intentionally — `NotionEditor` is ~350 KB minified
-(lowlight common pack + tables + drag handle); `MarkdownEditor` is
-~200 KB. Don't mount NotionEditor inside a chat composer just to get
-features the user will never use.
-
-## Features
-
-- **Slash menu (`/`)** — 11 commands: Text, H1-H3, Bullet/Numbered/Todo
-  lists, Quote, Code block, Divider, Table. Each item shows its
-  markdown shorthand (`#`, `- [ ]`, etc.) as a kbd hint. Filtering by
-  title + aliases. `Esc` / click-outside close.
-- **Bubble menu** — floating selection toolbar with Bold, Italic,
-  Underline, Strike, Code, Highlight, Link. Each button has a Tooltip
-  with the keyboard shortcut. Auto-hides inside code blocks and on
-  empty selections.
-- **Cmd+K link prompt** — opens a Radix Dialog with URL input and
-  Save/Remove/Cancel. Snapshots and restores selection across the
-  dialog mount. Rejects unsafe schemes (`javascript:`, `data:`).
-- **Drag handle** — Notion-style ⠿ grip appears on the left of every
-  block on hover (powered by `tiptap-extension-global-drag-handle`).
-  The icon is rendered as a `mask-image` of `lucide`'s `GripVertical`
-  so it matches the rest of the app at the pixel level.
-- **Smart Cmd+A** — first press selects the current text block, second
-  press selects the whole document (Notion convention).
-- **Heading-aware placeholder** — empty H1/H2/H3 show "Heading 1/2/3";
-  empty paragraphs show the supplied placeholder.
-- **Forced-dark code blocks** — code blocks render on a fixed One Dark
-  Pro surface regardless of host theme. Avoids the washed-out
-  "light syntax on light page" look every editor hits.
-- **Task list with ui-core `<Checkbox>`** — `taskItem` uses a React
-  `NodeView` so the checkbox is the same component used everywhere
-  else in the app (theme-aware, focus ring, etc.). Aligned to the
-  text cap-height via `align-items: baseline`.
-- **Cmd+S save hook** — `onSave?: (md: string) => void` bound to
-  Cmd/Ctrl+S via `useHotkey`, scoped to the editor DOM so it doesn't
-  collide with global palettes higher up.
-- **autoFocus** — declarative prop. Pair with `key={path}` upstream
-  when the parent wants a fresh focus per file change.
-- **Markdown shortcuts** — StarterKit's input rules cover `#`, `>`,
-  `-`, `1.`, `` ``` ``, `---` → matching block on type.
-
-## Extension stack
-
-Built once per editor instance (see `extensions.ts`). Order matters
-for markdown serialisation — `Markdown` is registered before
-`Highlight`/`TaskList` so the latter use the markdown extension's
-node spec when serialising.
-
-- `StarterKit` — paragraph, headings 1-4, bold/italic/code/strike,
-  blockquote, ordered+unordered list, link, underline, horizontal
-  rule, history. CodeBlock is **disabled** here — replaced by
-  `CodeBlockLowlight` for syntax highlighting.
-- `Placeholder` — heading-aware ghost text.
-- `Markdown` — bidirectional serialisation via `@tiptap/markdown`.
-  Handles tables, task lists (`- [ ]`), highlight (`==text==`).
-- `Highlight` — `==text==` mark.
-- `TaskList` + `TaskItem.extend({ addNodeView: TaskItemView })`.
-- `Table` + `TableRow` + `TableHeader` + `TableCell`.
-- `CodeBlockLowlight` — uses `lowlight`'s `common` language pack
-  (~25 languages). Add more by importing them and registering on the
-  shared `lowlight` instance.
-- `GlobalDragHandle` — block grabber. **One handle per page** — see
-  the "Known limitations" section below.
-- `SlashExtension` — wraps `@tiptap/suggestion` for the `/` menu.
-- `CustomKeymap` — smart Cmd+A.
+| Use case                                | Pick             |
+| --------------------------------------- | ---------------- |
+| Chat composer, single-paragraph input   | `MarkdownEditor` |
+| Note / doc surface, multi-paragraph     | `NotionEditor`   |
+| `.md` file viewer with full editing     | `NotionEditor`   |
+| Slim mention dropdown, no tables/tasks  | `MarkdownEditor` |
+| Slash menu, drag handle, tables, hljs   | `NotionEditor`   |
+| Bookmark cards / embedded map blocks    | `NotionEditor`   |
+
+The two coexist intentionally — `NotionEditor` is heavier; don't mount
+it inside a chat composer just to get features the user will never use.
+
+## Props
+
+`NotionEditorProps` (see `types.ts`):
+
+| Prop                 | Type                       | Default              | Notes |
+| -------------------- | -------------------------- | -------------------- | ----- |
+| `value`              | `string`                   | —                    | Markdown source (required). |
+| `onChange`           | `(md: string) => void`     | —                    | Fired on every keystroke with freshly-serialised markdown (required). |
+| `placeholder`        | `string`                   | `"Type '/' for commands…"` | Ghost text on an empty paragraph. |
+| `disabled`           | `boolean`                  | `false`              | Read-only renderer (also makes map blocks static). |
+| `autoFocus`          | `boolean`                  | `false`              | Focus on mount. Pair with `key={path}` upstream for fresh focus per file. |
+| `onSave`             | `(md: string) => void`     | —                    | Bound to Cmd/Ctrl+S, scoped to the editor DOM. |
+| `className`          | `string`                   | `''`                 | Extra class on the outer wrapper. |
+| `minHeight`          | `number`                   | `320`                | Min height of the editor surface (px). |
+| `resolveLinkPreview` | `ResolveLinkPreview`       | `undefined`          | **Host URL-unfurl resolver** threaded into the bookmark node. `undefined` → cards render a hostname/favicon fallback. See [nodes.md](./@docs/nodes.md#bookmark-block). |
+
+`resolveLinkPreview` is captured on first build (memoised on
+`[placeholder, resolveLinkPreview]`) — pass a **stable reference** (a
+host method), not a new closure per render.
+
+### Imperative API
+
+```tsx
+const ref = useRef<NotionEditorHandle>(null);
+
+ref.current?.focus();             // focus the editor surface
+ref.current?.moveCursorToEnd();   // focus + caret at end
+ref.current?.getEditor();         // raw TipTap Editor (escape hatch)
+```
+
+`NotionEditorHandle` is structurally compatible with `ComposerHandle`
+from `@djangocfg/ui-tools/composer-registry` — the chat suite can
+register a NotionEditor as a composer if you ever want to swap them in.
+
+## Features at a glance
+
+- **Slash menu (`/`)** — 12 commands: Text, H1-H3, Bullet/Numbered/Todo
+  lists, Quote, Code block, Divider, Table, and **Map**. Filtering by
+  title + aliases; each item shows its markdown shorthand as a hint.
+  See [slash.md](./@docs/slash.md).
+- **Block nodes** — a **bookmark** (link-preview) card from pasting a
+  bare URL on an empty line, and an interactive **map** block from
+  `/map`. Both round-trip through markdown. See [nodes.md](./@docs/nodes.md).
+- **Interactive map editing** — drag a pin, click-to-add, remove,
+  switch basemap; every edit writes back into the document via
+  `useNodeAttrs`. See [interactivity.md](./@docs/interactivity.md).
+- **Safe block rendering** — each block parses its attrs through a Zod
+  schema; a malformed payload renders `<BlockError>` instead of
+  crashing the editor. See [interactivity.md](./@docs/interactivity.md#safe-rendering).
+- **Bubble menu** — floating selection toolbar (Bold, Italic, Underline,
+  Strike, Code, Highlight, Link) with shortcut tooltips. Auto-hides in
+  code blocks and on empty selections.
+- **Cmd+K link prompt**, **drag handle**, **smart Cmd+A**,
+  **heading-aware placeholder**, **forced-dark code blocks**,
+  **task list** (ui-core `<Checkbox>`), **Cmd+S save hook**,
+  **markdown input rules**. See [editor.md](./@docs/editor.md).
+
+## Docs
+
+| Doc | Covers |
+|---|---|
+| [nodes.md](./@docs/nodes.md) | The **bookmark** + **map** block nodes — triggers, payload shapes, the `resolveLinkPreview` injection, and markdown serialisation / round-trip. |
+| [interactivity.md](./@docs/interactivity.md) | The `useNodeAttrs` write-back seam (how map edits persist) and the Zod-validator / `<BlockError>` safety net. |
+| [slash.md](./@docs/slash.md) | The `/` slash menu — the command list, filtering, and how to add a command (incl. `/map`). |
+| [editor.md](./@docs/editor.md) | Base editor config — the TipTap extension stack, keymap, task items, drag handle, link dialog, markdown round-trip table, and known limitations. |
+| [stories.md](./@docs/stories.md) | The Storybook stories list. |
 
 ## Files
 
@@ -101,8 +114,10 @@ node spec when serialising.
 | ----------------------------- | ----------------------------------------------------------- |
 | `lazy.tsx`                    | Subpath entry — `React.lazy` + `forwardRef` for the handle  |
 | `NotionEditor.tsx`            | Main component + `BubbleSelectionToolbar`                   |
-| `extensions.ts`               | Assembled TipTap stack (factory `notionExtensions()`)       |
+| `extensions.ts`              | Assembled TipTap stack (factory `notionExtensions()`)       |
 | `types.ts`                    | `NotionEditorProps`, `NotionEditorHandle`                   |
+| `BookmarkNode.ts` · `BookmarkView.tsx` | Bookmark (link-preview) block node + NodeView      |
+| `MapNode.ts` · `MapView.tsx` · `MapEditLayer.tsx` | Map block node, NodeView, editable layer |
 | `SlashExtension.ts`           | TipTap extension wrapping `@tiptap/suggestion`              |
 | `createSlashSuggestion.ts`    | Suggestion config — floating-ui popup mount/update/teardown |
 | `SlashList.tsx`               | Popover content (listbox + keyboard nav)                    |
@@ -112,126 +127,32 @@ node spec when serialising.
 | `LinkDialog.tsx`              | Cmd+K link prompt (ui-core Dialog)                          |
 | `styles.css`                  | Typography + slash/bubble menu + drag handle + lowlight     |
 
-## Imperative API
-
-```tsx
-const ref = useRef<NotionEditorHandle>(null);
-
-ref.current?.focus();             // focus the editor surface
-ref.current?.moveCursorToEnd();   // focus + caret at end
-ref.current?.getEditor();         // raw TipTap Editor (escape hatch)
-```
-
-`NotionEditorHandle` is structurally compatible with `ComposerHandle`
-from `@djangocfg/ui-tools/composer-registry` — the chat suite can
-register a NotionEditor as a composer if you ever want to swap them in
-the chat input (unusual, but allowed).
+Shared seams used by the block nodes live under `src/common/` (outside
+this folder): `common/link-preview` (the `LinkPreviewCard` +
+`ResolveLinkPreview` contract), `common/blocks` (payload types, Zod
+schemas, `<BlockError>`), and `common/tiptap` (the `useNodeAttrs`
+write-back hook).
 
 ## Saving — dirty / pristine handling
 
-The editor is **uncontrolled-ish**: it calls `onChange` on every
-keystroke with the freshly-serialised markdown. The host owns state
-and detects "dirty" however it likes.
-
-Two gotchas the host needs to know about:
+The editor calls `onChange` on every keystroke with the freshly
+serialised markdown; the host owns state and detects "dirty" however it
+likes. Two gotchas:
 
-1. **TipTap re-serialises markdown on mount** (trailing newline,
-   CRLF → LF normalisation). The first `onChange` after
-   `setContent(value)` is byte-different from `value` even though
-   nobody typed. If you compare `draft !== savedContent` literally,
-   the dirty indicator lights up on every file open. **Fix in the
-   host**: normalise both sides before comparing.
+1. **TipTap re-serialises markdown on mount** (trailing newline, CRLF →
+   LF). The first `onChange` after `setContent(value)` is byte-different
+   from `value` even though nobody typed. Normalise both sides before a
+   dirty comparison:
 
    ```ts
    const norm = (s: string) => s.replace(/\r\n/g, '\n').trimEnd();
    const isDirty = norm(draft) !== norm(saved);
    ```
 
-2. **Cmd+S only fires when focus is inside the editor**. If the user
-   clicked outside (header, sidebar) and presses Cmd+S, this hook
-   doesn't fire. Add a window-level `useHotkey('mod+s', save)` in the
-   host as a fallback — both paths call the same save fn.
+2. **Cmd+S only fires when focus is inside the editor.** Add a
+   window-level `useHotkey('mod+s', save)` in the host as a fallback —
+   both paths call the same save fn.
 
 See `cmdop/.../document-preview/viewers/text-viewer.tsx` for the
-canonical wiring.
-
-## Markdown round-trip
-
-| Input            | Round-trips? | Notes                              |
-| ---------------- | ------------ | ---------------------------------- |
-| Headings         | ✓            | H1-H4 only (StarterKit config)     |
-| Bold/italic/etc. | ✓            |                                    |
-| Inline code      | ✓            |                                    |
-| Code blocks      | ✓            | Language fence preserved by hljs   |
-| Bullet/ordered   | ✓            | Nested too                         |
-| Task lists       | ✓            | GFM `- [x]` / `- [ ]`              |
-| Blockquote       | ✓            |                                    |
-| Horizontal rule  | ✓            | `---`                              |
-| Tables           | ✓            | GFM tables — alignment via `:--:`  |
-| Links            | ✓            | autolinks too                      |
-| Highlight        | ✓            | `==text==` extension syntax        |
-| Images           | mostly       | Round-trip URLs, no upload yet     |
-| HTML passthrough | ✗            | Stripped on parse                  |
-| Footnotes        | ✗            | Not in StarterKit                  |
-
-## Known limitations
-
-- **One editor per page (drag handle).**
-  `tiptap-extension-global-drag-handle` mints a single DOM grabber
-  attached to `document.body`. Mounting two `NotionEditor` instances
-  on the same page (e.g. a side-by-side diff) makes them fight over
-  the handle. If you need multiple editors, render only one with
-  drag-handle support.
-
-- **Slash popup is portal'd to `document.body`.**
-  If the parent unmounts the editor mid-suggestion, the popup gets
-  cleaned up by ProseMirror's `onExit` — but a hostile race (route
-  change while menu is open) can leave an orphan div. Rare; visible
-  only via the inspector.
-
-- **No image upload pipeline (yet).**
-  `Image` extension is not registered. Pasting an image from the
-  clipboard inserts the data-URL into the document (browser default)
-  but there's no upload integration. Add `@tiptap/extension-image` +
-  a custom paste handler when you have a target storage. See Novel's
-  `plugins/upload-images.tsx` for the canonical pattern.
-
-- **Bubble menu uses `@tiptap/react/menus`'s `BubbleMenu`** (Tippy
-  under the hood). Slash menu uses `floating-ui` directly. Two
-  positioning libraries for one editor — kept this way because
-  `BubbleMenu` is opinionated about anchor invalidation and Tippy
-  handles it correctly; reimplementing on floating-ui would save
-  ~5 KB but cost a week of edge cases.
-
-## Storybook
-
-Stories live at `apps/storybook/stories/ui-tools/markdown/NotionEditor.stories.tsx`:
-
-- Default (empty editor with placeholder)
-- With sample content (every supported block + serialised output panel)
-- Auto-focus on mount
-- Read-only
-- Compact (240px min-height)
-
-Each story renders a right-side panel showing the current serialised
-markdown so you can watch the round-trip live as you type.
-
-## Wiring inside a host
-
-The canonical host is `cmdop`'s document-preview text viewer:
-
-```tsx
-// .md → NotionEditor only (it's already WYSIWYG, no Preview/Source split)
-<div className="mx-auto w-full max-w-[820px] px-6 py-6">
-  <NotionEditor
-    value={draft}
-    onChange={handleChange}
-    onSave={save}
-    autoFocus
-    minHeight={420}
-  />
-</div>
-```
-
-Use `key={path}` on the wrapper if you remount per file — that's what
-makes `autoFocus` fire on each file open.
+canonical wiring. Use `key={path}` on the wrapper if you remount per
+file — that's what makes `autoFocus` fire on each file open.

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

@@ -17,6 +17,9 @@ import { SlashExtension } from './SlashExtension';
 import { createSlashSuggestion } from './createSlashSuggestion';
 import { TaskItemView } from './TaskItemView';
 import { CustomKeymap } from './CustomKeymap';
+import { BookmarkNode } from './BookmarkNode';
+import { MapNode } from './MapNode';
+import type { ResolveLinkPreview } from '../../../common/link-preview';
 
 // Lowlight bundle: "common" languages cover ts/js/json/py/go/rust/etc.
 // The full language pack pulls in ~300KB more — opt-in case by case.
@@ -24,6 +27,13 @@ const lowlight = createLowlight(common);
 
 export interface BuildExtensionsOptions {
   placeholder: string;
+  /**
+   * Host resolver for the `bookmark` (link-preview) node. Given a URL it
+   * returns unfurl metadata. Threaded into `BookmarkNode.options` and read by
+   * its NodeView. Default `undefined` → the card renders its own
+   * hostname/favicon fallback (same seam as chat's `config.linkPreview`).
+   */
+  resolveLinkPreview?: ResolveLinkPreview;
 }
 
 /**
@@ -97,6 +107,11 @@ export function notionExtensions(opts: BuildExtensionsOptions): AnyExtension[] {
       // ships — typo and all. Spelling it correctly is silently ignored.
       scrollTreshold: 100,
     }),
+    // Bookmark (link-preview) block — paste a bare URL on an empty line and
+    // it becomes a card. The host resolver is threaded through options.
+    BookmarkNode.configure({ resolveLinkPreview: opts.resolveLinkPreview }),
+    // Map block — inserted via the `/map` slash command (see slashItems).
+    MapNode,
     SlashExtension.configure({
       suggestion: createSlashSuggestion(),
     }),

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

@@ -6,6 +6,7 @@ import {
   Heading3,
   List,
   ListOrdered,
+  Map as MapIcon,
   Minus,
   Quote,
   Table as TableIcon,
@@ -13,6 +14,7 @@ import {
   type LucideIcon,
 } from 'lucide-react';
 import type { Editor, Range } from '@tiptap/react';
+import { DEFAULT_MAP_PAYLOAD } from './MapNode';
 
 export interface SlashItem {
   title: string;
@@ -146,6 +148,23 @@ export const slashItems: SlashItem[] = [
         .run();
     },
   },
+  {
+    title: 'Map',
+    description: 'Interactive map block.',
+    icon: MapIcon,
+    aliases: ['map', 'location', 'geo', 'pin'],
+    command: ({ editor, range }) => {
+      // Drop the typed `/map`, then insert a map block seeded with a sensible
+      // default payload so the user sees a live map immediately. Attrs are
+      // plain JSON and round-trip through markdown (see MapNode).
+      editor
+        .chain()
+        .focus()
+        .deleteRange(range)
+        .setMapBlock({ ...DEFAULT_MAP_PAYLOAD })
+        .run();
+    },
+  },
 ];
 
 /** Case-insensitive filter over title + aliases. */

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

@@ -58,6 +58,15 @@
   text-underline-offset: 2px;
 }
 
+/* …but block-card NodeViews (bookmark/map) own their styling — the card is
+   itself an <a>, and its inner title/description must NOT inherit the editor
+   link underline (it read as if the whole card text were a link). */
+.notion-editor .tiptap .notion-bookmark a,
+.notion-editor .tiptap a.notion-bookmark {
+  color: inherit;
+  text-decoration: none;
+}
+
 /* Headings */
 .notion-editor .tiptap h1 {
   font-size: 2em;
@@ -167,6 +176,22 @@
   text-decoration: line-through;
 }
 
+/* ── Bookmark (link-preview) + Map block nodes ────────────────────────────
+ * Block-level NodeViews rendering shared cards (LinkPreviewCard / the map).
+ * The card / map owns its own frame (radius, border, shadow); here we only
+ * own the block's vertical rhythm so it breathes like a paragraph and the
+ * ProseMirror-selectednode ring reads cleanly on the atom. */
+.notion-editor .tiptap .notion-bookmark,
+.notion-editor .tiptap .notion-map {
+  margin: 0.75em 0;
+}
+.notion-editor .tiptap .notion-bookmark.ProseMirror-selectednode,
+.notion-editor .tiptap .notion-map.ProseMirror-selectednode {
+  outline: 2px solid var(--ring);
+  outline-offset: 2px;
+  border-radius: var(--radius, 0.5rem);
+}
+
 /* Blockquote */
 .notion-editor .tiptap blockquote {
   border-left: 3px solid var(--color-border, var(--border));

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

@@ -1,4 +1,5 @@
 import type { Editor } from '@tiptap/react';
+import type { ResolveLinkPreview } from '../../../common/link-preview';
 
 export interface NotionEditorProps {
   value: string;
@@ -17,6 +18,14 @@ export interface NotionEditorProps {
   className?: string;
   /** Minimum height of the editor surface in px. Default 320. */
   minHeight?: number;
+  /**
+   * Host resolver for the `bookmark` (link-preview) block. When a user pastes
+   * a bare URL on an empty line it becomes a bookmark card; this resolver
+   * unfurls the URL into title/description/image (a Wails/Go method, a
+   * Next.js API route). Default `undefined` → the card renders its own
+   * hostname/favicon fallback. Same seam as chat's `config.linkPreview`.
+   */
+  resolveLinkPreview?: ResolveLinkPreview;
 }
 
 /** Imperative handle exposed via `ref`. Compatible with `ComposerHandle`

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

@@ -182,6 +182,11 @@ export function createExternalEngine(
   return {
     id: opts.id ?? 'external',
     isSupported: opts.supported ?? true,
+    // Capture happens outside the browser (native / sidecar), so this
+    // engine must never be gated on `navigator.mediaDevices.getUserMedia`
+    // — that API is absent in many host shells (Wails WKWebView) and in
+    // headless / non-secure contexts, yet the engine works fine there.
+    usesMicrophone: false,
     on(event, cb): Unsub {
       return bus.on(event, cb);
     },

package/src/tools/input/SpeechRecognition/types.ts

@@ -82,6 +82,16 @@ export type Unsub = () => void;
 export interface RecognitionEngine {
   readonly id: string;
   readonly isSupported: boolean;
+  /**
+   * Whether this engine captures audio through the browser microphone
+   * (`navigator.mediaDevices.getUserMedia`). `true` (default when
+   * omitted) for the browser-native engines — Web Speech, HTTP and
+   * WebSocket all open a `getUserMedia` stream. `false` for engines
+   * that own capture outside the browser (`createExternalEngine` —
+   * Wails / Tauri / native whisper sidecar), so consumers must NOT gate
+   * them on `getUserMedia` being present.
+   */
+  readonly usesMicrophone?: boolean;
   start(opts: EngineStartOptions): Promise<void>;
   stop(): Promise<void>;
   abort(): void;