@mieweb/ui 0.10.0-dev.9 → 0.11.0-dev.0

package/dist/hooks/index.d.cts

@@ -1,45 +1,28 @@
-export { R as ResolvedTheme, T as Theme, u as useTheme } from '../useTheme-B9SWu6ui.cjs';
 import * as React from 'react';
 import { RefObject } from 'react';
-export { A as AnchoredPlacement, U as UseAnchoredPositionOptions, a as UseAnchoredPositionReturn, u as useAnchoredPosition } from '../useAnchoredPosition-CKwLSQW8.cjs';
-export { D as DEFAULT_FILLER_WORDS, a as DEFAULT_MIN_SILENCE_MS, b as DEFAULT_NL_SILENCE_MS, F as FillerAnalysis, S as SilenceThresholdCount, T as TranscriptClipboard, c as TranscriptEditStats, U as UseTranscriptEditsOptions, d as UseTranscriptEditsResult, e as buildPlaybackSegments, g as getSpeedAtIndex, i as initEditableWords, f as insertSilences, u as useTranscriptEdits } from '../useTranscriptEdits-CGzlemHT.cjs';
-import '../transcript-Cg7uSW-C.cjs';
 
-interface UseScrollSpyOptions {
-    /** CSS selector for the elements to observe (e.g. 'h2, h3, h4') */
-    selectors?: string;
-    /** Explicit list of element IDs to observe (alternative to selectors) */
-    ids?: string[];
-    /** IntersectionObserver root margin (default: '0px 0px -60% 0px') */
-    rootMargin?: string;
-    /** IntersectionObserver threshold (default: 0) */
-    threshold?: number | number[];
-    /** Scroll container element ref. Defaults to document viewport. */
-    root?: RefObject<HTMLElement | null>;
-    /** Whether the hook is active (default: true) */
-    enabled?: boolean;
-}
-interface UseScrollSpyReturn {
-    /** The ID of the currently active (in-view) element */
-    activeId: string | null;
-}
+type Theme = 'light' | 'dark' | 'system';
+type ResolvedTheme = 'light' | 'dark';
 /**
- * Tracks which section is currently in the viewport using IntersectionObserver.
- * Pairs naturally with `TableOfContents` to highlight the active heading.
+ * Hook for managing theme state with localStorage persistence and system preference support.
  *
  * @example
  * ```tsx
- * function DocsPage() {
- *   const { activeId } = useScrollSpy({ selectors: 'h2, h3' });
+ * function ThemeToggle() {
+ *   const { theme, setTheme, resolvedTheme } = useTheme();
  *   return (
- *     <aside>
- *       <TableOfContents activeId={activeId} />
- *     </aside>
+ *     <button onClick={() => setTheme(resolvedTheme === 'dark' ? 'light' : 'dark')}>
+ *       {resolvedTheme === 'dark' ? '☀️' : '🌙'}
+ *     </button>
  *   );
  * }
  * ```
  */
-declare function useScrollSpy({ selectors, ids, rootMargin, threshold, root, enabled, }?: UseScrollSpyOptions): UseScrollSpyReturn;
+declare function useTheme(): {
+    theme: Theme;
+    setTheme: (newTheme: Theme) => void;
+    resolvedTheme: ResolvedTheme;
+};
 
 /** Read the current dark-mode state from the document root. */
 declare function isDarkMode(): boolean;
@@ -64,6 +47,18 @@ declare const RTL_LOCALES: readonly ["ar", "he", "fa", "ur"];
  * right-to-left script.
  */
 declare function isRtlLocale(locale: string): boolean;
+/**
+ * Non-hook check for event handlers: true when the element currently renders
+ * right-to-left. Use inside `onKeyDown` to invert ArrowLeft/ArrowRight so
+ * horizontal arrows follow the *visual* direction:
+ *
+ * ```ts
+ * const rtl = isRtl(event.currentTarget);
+ * ```
+ *
+ * Prefer `useDirection()` when the direction drives rendering.
+ */
+declare function isRtl(element?: Element | null): boolean;
 /**
  * Hook returning the effective text direction (`ltr` | `rtl`) inherited from
  * the nearest `dir` attribute — zero setup for consumers who set
@@ -125,6 +120,79 @@ declare function usePrefersReducedMotion(): boolean;
  */
 declare function useClickOutside<T extends HTMLElement>(ref: RefObject<T | null> | ReadonlyArray<RefObject<HTMLElement | null>>, callback: () => void, enabled?: boolean): void;
 
+type AnchoredPlacement = 'bottom-start' | 'bottom-end' | 'bottom' | 'top-start' | 'top-end' | 'top' | 'right-start' | 'right-end' | 'right' | 'left-start' | 'left-end' | 'left';
+type AnchoredSide = 'top' | 'bottom' | 'left' | 'right';
+interface UseAnchoredPositionOptions {
+    /** Whether the floating element is currently shown */
+    open: boolean;
+    /** Preferred placement relative to the anchor (flips when out of space) */
+    placement?: AnchoredPlacement;
+    /** Gap between the anchor and the floating element, in px */
+    offset?: number;
+    /** Force the floating element to the anchor's width */
+    matchWidth?: boolean;
+    /** Use the anchor's width as the floating element's minimum width */
+    matchMinWidth?: boolean;
+    /** Minimum distance from the viewport edges, in px */
+    viewportPadding?: number;
+    /** Flip to the opposite vertical side when the preferred side is cramped */
+    allowFlip?: boolean;
+    /** Optional element whose visible rectangle also constrains the popup */
+    boundaryRef?: React.RefObject<HTMLElement | null>;
+    /**
+     * Additional cap on the floating element's height, in px. The height is
+     * always clamped to the available viewport space; this only lowers that
+     * limit further (omitting it does not remove the viewport constraint).
+     */
+    maxHeight?: number;
+}
+interface UseAnchoredPositionReturn<TAnchor extends HTMLElement, TFloating extends HTMLElement> {
+    /** Attach to the element the popup is anchored to (trigger/input) */
+    anchorRef: React.RefObject<TAnchor | null>;
+    /** Attach to the floating element (menu/listbox/panel) */
+    floatingRef: React.RefObject<TFloating | null>;
+    /** Fixed-position style for the floating element — spread onto it */
+    style: React.CSSProperties;
+    /**
+     * Side of the anchor in use after flipping.
+     *
+     * Widened from `'top' | 'bottom'` to {@link AnchoredSide} in 0.8.0 alongside
+     * the new horizontal (`left*` / `right*`) placements — consumers that
+     * annotate this as `'top' | 'bottom'` need to widen their annotation.
+     */
+    actualSide: AnchoredSide;
+    /** Recompute the position (e.g. after async content loads) */
+    update: () => void;
+}
+/**
+ * Positions a floating element (dropdown menu, autocomplete listbox,
+ * date-picker calendar, …) relative to an anchor using `position: fixed`,
+ * so it is never clipped by `overflow: hidden` ancestors.
+ *
+ * Render the floating element through `createPortal(..., document.body)`
+ * and spread the returned `style` onto it. The hook:
+ * - flips vertically when there is not enough space on the preferred side
+ * - clamps horizontally to the viewport or optional boundary element
+ * - constrains `maxHeight` to the available space (add `overflow-auto`)
+ * - tracks scroll, resize, and anchor/content size changes while open
+ *
+ * @example
+ * ```tsx
+ * const { anchorRef, floatingRef, style } = useAnchoredPosition<
+ *   HTMLButtonElement,
+ *   HTMLDivElement
+ * >({ open, placement: 'bottom-start' });
+ *
+ * <button ref={anchorRef} onClick={() => setOpen(!open)}>Open</button>
+ * {open &&
+ *   createPortal(
+ *     <div ref={floatingRef} style={style} className="overflow-auto …">…</div>,
+ *     document.body
+ *   )}
+ * ```
+ */
+declare function useAnchoredPosition<TAnchor extends HTMLElement = HTMLElement, TFloating extends HTMLElement = HTMLElement>({ open, placement, offset, matchWidth, matchMinWidth, viewportPadding, allowFlip, boundaryRef, maxHeight, }: UseAnchoredPositionOptions): UseAnchoredPositionReturn<TAnchor, TFloating>;
+
 /**
  * Hook that triggers a callback when the Escape key is pressed.
  * Useful for closing modals, dropdowns, and other overlays.
@@ -164,6 +232,113 @@ declare function useEscapeKey(callback: () => void, enabled?: boolean): void;
  */
 declare function useFocusTrap<T extends HTMLElement>(enabled?: boolean): RefObject<T | null>;
 
+/** CSS custom properties written to `<html>` while the hook is mounted. */
+declare const KEYBOARD_INSET_VAR = "--mieweb-keyboard-inset";
+declare const VISUAL_VIEWPORT_HEIGHT_VAR = "--mieweb-visual-viewport-height";
+declare const VISUAL_VIEWPORT_OFFSET_TOP_VAR = "--mieweb-visual-viewport-offset-top";
+/** Boolean attribute set on `<html>` while an on-screen keyboard is open. */
+declare const KEYBOARD_OPEN_ATTRIBUTE = "data-keyboard-open";
+/** Attribute on `<html>` naming the active {@link KeyboardInsetSource}. */
+declare const KEYBOARD_SOURCE_ATTRIBUTE = "data-keyboard-source";
+/**
+ * Where keyboard metrics come from.
+ *
+ * - `'visual-viewport'` — the Visual Viewport API. Works in any browser, but
+ *   iOS only reports the keyboard once its slide-in animation has finished.
+ * - `'native'` — `keyboardWillShow` / `keyboardWillHide` window events with a
+ *   `keyboardHeight` property, as fired by `cordova-plugin-ionic-keyboard` and
+ *   Capacitor's Keyboard plugin. They arrive *before* the keyboard animates,
+ *   so layout can move in step with it.
+ */
+type KeyboardInsetSource = 'visual-viewport' | 'native';
+interface KeyboardInsetState {
+    /** Pixels of the layout viewport covered by the on-screen keyboard. */
+    keyboardInset: number;
+    /** Whether an on-screen keyboard currently covers part of the page. */
+    isKeyboardOpen: boolean;
+}
+interface UseKeyboardInsetOptions {
+    /** Track the keyboard; `false` stops tracking and clears the CSS variables. @default true */
+    enabled?: boolean;
+    /** Where keyboard metrics come from. @default 'visual-viewport' */
+    source?: KeyboardInsetSource;
+}
+/**
+ * Tracks the on-screen keyboard and publishes it on `<html>`.
+ *
+ * ### `source: 'native'` (Cordova / Capacitor apps)
+ *
+ * Listens for the native keyboard plugin's `keyboardWillShow` /
+ * `keyboardWillHide` window events. Configure the plugin so the WebView is
+ * neither resized nor panned (for `cordova-plugin-ionic-keyboard`:
+ * `KeyboardResize=false`), keep the app shell at full height, and move only
+ * the composer dock by `--mieweb-keyboard-inset` with a short transition
+ * (~250ms) so it rides up with the keyboard. Only `--mieweb-keyboard-inset`,
+ * `data-keyboard-open` and `data-keyboard-source` are published; the
+ * visual-viewport variables stay unset.
+ *
+ * ### `source: 'visual-viewport'` (browsers, default)
+ *
+ * Uses the Visual Viewport API.
+ *
+ * iOS Safari and WKWebView (Cordova) ignore
+ * `interactive-widget=resizes-content`, and `dvh` does not shrink for the
+ * keyboard: the page keeps its full height and iOS pans the visual viewport
+ * to reveal the focused input, pushing headers off-screen. This hook
+ * measures what is actually visible and publishes it on `<html>` so an app
+ * shell can follow the visible area instead:
+ *
+ * - `--mieweb-keyboard-inset` — keyboard height in px (0 when closed)
+ * - `--mieweb-visual-viewport-height` — visible height in px
+ * - `--mieweb-visual-viewport-offset-top` — how far iOS panned the page
+ * - `data-keyboard-open` — present while the keyboard is open
+ *
+ * On browsers that already resize the layout for the keyboard (Chrome on
+ * Android with `interactive-widget=resizes-content`) the inset stays 0 and
+ * the variables simply mirror the layout viewport.
+ *
+ * iOS reports the visual viewport only after the keyboard has finished
+ * animating, so a shell sized this way snaps into place once the keyboard
+ * lands. Prefer `source: 'native'` wherever a native keyboard plugin exists.
+ *
+ * Mount it once, near the app root.
+ *
+ * @example
+ * ```tsx
+ * function AppShell({ children }) {
+ *   useKeyboardInset();
+ *   return (
+ *     <div
+ *       style={{
+ *         height: 'var(--mieweb-visual-viewport-height, 100dvh)',
+ *         transform: 'translateY(var(--mieweb-visual-viewport-offset-top, 0px))',
+ *       }}
+ *     >
+ *       {children}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example Native app (keyboard plugin with WebView resizing disabled)
+ * ```tsx
+ * function ComposerDock({ children }) {
+ *   useKeyboardInset({ source: 'native' });
+ *   return (
+ *     <div
+ *       style={{
+ *         paddingBottom: 'calc(var(--mieweb-keyboard-inset, 0px) + 0.5rem)',
+ *         transition: 'padding-bottom 250ms ease',
+ *       }}
+ *     >
+ *       {children}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useKeyboardInset(options?: UseKeyboardInsetOptions): KeyboardInsetState;
+
 /**
  * Options for keyboard shortcut hook
  */
@@ -259,15 +434,67 @@ declare function useIsLargeDesktop(): boolean;
 /** Returns true when viewport is smaller than 1024px (mobile/tablet) */
 declare function useIsMobileOrTablet(): boolean;
 
+interface UseScrollSpyOptions {
+    /** CSS selector for the elements to observe (e.g. 'h2, h3, h4') */
+    selectors?: string;
+    /** Explicit list of element IDs to observe (alternative to selectors) */
+    ids?: string[];
+    /** IntersectionObserver root margin (default: '0px 0px -60% 0px') */
+    rootMargin?: string;
+    /** IntersectionObserver threshold (default: 0) */
+    threshold?: number | number[];
+    /** Scroll container element ref. Defaults to document viewport. */
+    root?: RefObject<HTMLElement | null>;
+    /** Whether the hook is active (default: true) */
+    enabled?: boolean;
+}
+interface UseScrollSpyReturn {
+    /** The ID of the currently active (in-view) element */
+    activeId: string | null;
+}
+/**
+ * Tracks which section is currently in the viewport using IntersectionObserver.
+ * Pairs naturally with `TableOfContents` to highlight the active heading.
+ *
+ * @example
+ * ```tsx
+ * function DocsPage() {
+ *   const { activeId } = useScrollSpy({ selectors: 'h2, h3' });
+ *   return (
+ *     <aside>
+ *       <TableOfContents activeId={activeId} />
+ *     </aside>
+ *   );
+ * }
+ * ```
+ */
+declare function useScrollSpy({ selectors, ids, rootMargin, threshold, root, enabled, }?: UseScrollSpyOptions): UseScrollSpyReturn;
+
 /** Insert `draggedId` before/after `targetId` in `ids`. */
 declare function reorderIds(ids: string[], draggedId: string, targetId: string, after: boolean): string[];
+/** Move `id` by `delta` positions (clamped). Returns `ids` unchanged when it can't move. */
+declare function moveIdBy(ids: string[], id: string, delta: number): string[];
+interface DragReorderLabels {
+    moveUp: string;
+    moveDown: string;
+    /** Announced after a keyboard/button move */
+    moved: (position: number, total: number, id: string) => string;
+}
+declare const DEFAULT_DRAG_REORDER_LABELS: DragReorderLabels;
 interface UseDragReorderOptions {
     /** Current flat order of item ids (props order) */
     ids: string[];
-    /** Called with the full new id order after a drop. Omit to disable dragging. */
+    /** Called with the full new id order after a drop or move. Omit to disable reordering. */
     onReorder?: (ids: string[]) => void;
     /** Restrict drops, e.g. to the same status group */
     canDropOn?: (draggedId: string, targetId: string) => boolean;
+    /** Add Alt+ArrowUp / Alt+ArrowDown handling (and `tabIndex={0}`) to `rowProps`. Off by default so rows with their own `onKeyDown` keep working. */
+    keyboard?: boolean;
+    /** Receives move announcements instead of the returned `announcement` string. */
+    announce?: (message: string) => void;
+    /** Element rendered as the drag image (`dataTransfer.setDragImage`). */
+    getDragPreview?: (id: string) => Element | null;
+    labels?: Partial<DragReorderLabels>;
 }
 interface DragOverState {
     id: string;
@@ -283,6 +510,17 @@ interface UseDragReorderReturn {
     over: DragOverState | null;
     /** Spread onto each row element (must be keyed by a stable id) */
     rowProps: (id: string) => React.HTMLAttributes<HTMLElement>;
+    /** Move an item by `delta` positions; no-op at the ends or across `canDropOn` boundaries. */
+    moveBy: (id: string, delta: number) => void;
+    /** Props for a visible move button */
+    moveButtonProps: (id: string, direction: 'up' | 'down', label?: string) => {
+        type: 'button';
+        onClick: (e: React.MouseEvent) => void;
+        disabled: boolean;
+        'aria-label': string;
+    };
+    /** Latest move message; render in an `aria-live="polite"` region (empty when `announce` is given). */
+    announcement: string;
 }
 /**
  * HTML5 drag-and-drop list reordering. Rows spread `rowProps(id)`; on drop the
@@ -290,19 +528,77 @@ interface UseDragReorderReturn {
  * consumer persists it (e.g. on the encounter/patient object) and feeds the
  * list back in props order.
  *
- * Drag-and-drop is a pointer-only affordance: pair it with a keyboard
- * alternative (e.g. move buttons / Alt+Arrow keys) for accessibility.
+ * Drag-and-drop is pointer-only, so pair it with `moveButtonProps` buttons
+ * and/or `keyboard: true` (Alt+↑/↓ on focused rows), and render
+ * `announcement` in a polite live region.
  *
  * @example
  * ```tsx
- * const drag = useDragReorder({ ids: items.map((i) => i.id), onReorder });
+ * const drag = useDragReorder({ ids: items.map((i) => i.id), onReorder, keyboard: true });
  * // <li {...drag.rowProps(item.id)} className={cn(dragIndicatorClasses(drag, item.id))}>
+ * //   <button {...drag.moveButtonProps(item.id, 'up')}><ChevronUp /></button>
+ * // <div aria-live="polite" className="sr-only">{drag.announcement}</div>
  * ```
  */
-declare function useDragReorder({ ids, onReorder, canDropOn, }: UseDragReorderOptions): UseDragReorderReturn;
+declare function useDragReorder({ ids, onReorder, canDropOn, keyboard, announce, getDragPreview, labels: labelsProp, }: UseDragReorderOptions): UseDragReorderReturn;
 /** Tailwind classes for the drag state of a row: drop indicator + dragging dim. */
 declare function dragIndicatorClasses(drag: Pick<UseDragReorderReturn, 'draggingId' | 'over'>, id: string): string;
 
+interface OrderPersistenceAdapter {
+    /** Previously saved order, or null when there is none */
+    load: () => string[] | null | Promise<string[] | null>;
+    save: (order: string[]) => void | Promise<void>;
+}
+interface UseOrderPersistenceOptions extends OrderPersistenceAdapter {
+    /** Delay before `save` runs; rapid changes collapse into one save. */
+    debounceMs?: number;
+    /** Called when `load` or `save` throws or rejects */
+    onError?: (error: unknown) => void;
+}
+interface UseOrderPersistenceReturn {
+    /** Saved order merged with the current `ids` */
+    order: string[];
+    /** Update the order immediately and schedule a debounced save */
+    setOrder: (order: string[]) => void;
+}
+/** Keep saved ids that still exist, then append new ids in their given order. */
+declare function mergeOrder(saved: string[] | null, ids: string[]): string[];
+/**
+ * Persist a user's item order (sections, widgets, list rows) through any
+ * storage. Updates are optimistic, saves are debounced and a pending save is
+ * flushed on unmount and on `pagehide` (navigation, refresh, tab close). On
+ * `pagehide` only work `save` starts synchronously is guaranteed — use
+ * localStorage or `navigator.sendBeacon` there; an async `fetch` may be cut
+ * off. `load` runs once after mount, so server and first client render use
+ * `ids` order.
+ *
+ * @example
+ * ```tsx
+ * const adapter = React.useMemo(() => localStorageOrderAdapter('clinic-sections'), []);
+ * const { order, setOrder } = useOrderPersistence(sectionIds, adapter);
+ * const drag = useDragReorder({ ids: order, onReorder: setOrder });
+ * ```
+ */
+declare function useOrderPersistence(ids: string[], { load, save, debounceMs, onError }: UseOrderPersistenceOptions): UseOrderPersistenceReturn;
+/** `useOrderPersistence` adapter backed by `localStorage` (no-op on the server or when storage is blocked). */
+declare function localStorageOrderAdapter(key: string): OrderPersistenceAdapter;
+
+/**
+ * Keeps a tab (or any one-of-N view) selection in a URL query parameter so it
+ * survives reloads and can be shared. Writes with `history.replaceState` (no
+ * router, no history entry), drops the parameter when the value equals
+ * `defaultValue`, follows back/forward via `popstate`, and ignores values not
+ * in `allowed`. SSR-safe: renders `defaultValue` on the server and during
+ * hydration.
+ *
+ * @example
+ * ```tsx
+ * const [tab, setTab] = useUrlTab('tab', 'summary', ['summary', 'history'] as const);
+ * <Tabs value={tab} onValueChange={(v) => setTab(v as typeof tab)}>…</Tabs>
+ * ```
+ */
+declare function useUrlTab<T extends string>(param: string, defaultValue: T, allowed: readonly T[]): [T, (value: T) => void];
+
 /**
  * State for an `aria-live` region that re-announces even when the same
  * message is emitted twice in a row. Setting identical React state bails out
@@ -544,4 +840,264 @@ interface UseMediaTransportReturn {
  */
 declare function useMediaTransport(options?: UseMediaTransportOptions): UseMediaTransportReturn;
 
-export { type Direction, type DragOverState, type HoverPreviewState, type KeyboardShortcutOptions, type MediaTransportState, RTL_LOCALES, type UseDragReorderOptions, type UseDragReorderReturn, type UseMediaTransportOptions, type UseMediaTransportReturn, type UseScrollSpyOptions, type UseScrollSpyReturn, type UseStickToBottomOptions, type UseStickToBottomReturn, type UseYouTubeHoverPreviewOptions, type UseYouTubeHoverPreviewReturn, dragIndicatorClasses, isDarkMode, isRtlLocale, reorderIds, useClickOutside, useCommandK, useDirection, useDragReorder, useEscapeKey, useFocusTrap, useIsDarkMode, useIsDesktop, useIsLargeDesktop, useIsMobile, useIsMobileOrTablet, useIsSmallTablet, useIsTablet, useKeyboardShortcut, useLiveAnnouncement, useMediaQuery, useMediaTransport, usePrefersReducedMotion, useScrollSpy, useStickToBottom, useStreamEndedBelowFold, useYouTubeHoverPreview };
+/**
+ * Transcript schema for @mieweb/ui media components.
+ *
+ * Provider-agnostic and persistence-agnostic. Canonical time unit is
+ * **milliseconds** (consumers with seconds-based data, e.g. osheet, adapt
+ * at the boundary).
+ *
+ * Shared by TranscriptView, MediaEditor, and useTranscriptEdits.
+ */
+/** Type of transcript word - 'word' for spoken content, 'silence' for detected gaps, 'silence-newline' for longer pauses */
+type WordType = 'word' | 'silence' | 'silence-newline';
+interface TranscriptWord {
+    text: string;
+    startMs: number;
+    endMs: number;
+    /** References Speaker.id when diarization is available */
+    speakerId?: string;
+    confidence?: number;
+    /** Type of word: 'word' for spoken content, 'silence' for detected gaps. Defaults to 'word' */
+    wordType?: WordType;
+}
+/** A diarized segment of contiguous speech (osheet-style granularity) */
+interface TranscriptSegment {
+    text: string;
+    startMs: number;
+    endMs: number;
+    /** References Speaker.id when diarization is available */
+    speakerId?: string;
+    words: TranscriptWord[];
+}
+interface Speaker {
+    id: string;
+    /** Display name (e.g. 'Clinician', 'Patient'). Hosts may remap via speakerLabels props. */
+    name?: string;
+}
+interface Transcript {
+    durationMs: number;
+    speakers?: Speaker[];
+    words: TranscriptWord[];
+    segments?: TranscriptSegment[];
+}
+/**
+ * An editable word that references the original transcript word.
+ * Used in the edited timeline to track deletions and reordering.
+ */
+interface EditableWord {
+    /** Index into the SILENCE-INSERTED baseline timeline (transcript.words
+     *  with detected silence pseudo-words interleaved) — NOT into
+     *  transcript.words. -1 for split/inserted entries with no baseline slot.
+     *  Consumers persisting edits should key by this timeline. */
+    originalIndex: number;
+    /** The word data (from original transcript) */
+    word: TranscriptWord;
+    /** Whether this word is marked as deleted */
+    deleted: boolean;
+    /** Whether this word was inserted (pasted from clipboard) */
+    inserted?: boolean;
+}
+/**
+ * Represents a contiguous segment of playback from the original media.
+ * Used when playing back an edited timeline with potentially reordered/deleted words.
+ */
+interface PlaybackSegment {
+    startMs: number;
+    endMs: number;
+    /** Indices into the editedWords array that this segment covers */
+    editedIndices: number[];
+}
+/** Available playback speed multipliers */
+type PlaybackSpeed = 0.5 | 0.75 | 1 | 1.25 | 1.5 | 1.75 | 2;
+/**
+ * A speed marker applied to a word in the transcript.
+ * The speed applies from this word until the next speed marker or end of transcript.
+ */
+interface SpeedMarker {
+    /** Index in the editedWords array where the speed marker is placed */
+    wordIndex: number;
+    /** The playback speed multiplier */
+    speed: PlaybackSpeed;
+}
+
+/**
+ * useTranscriptEdits — headless transcript-editing state hook.
+ *
+ * Extracted from pulseclip's TranscriptViewer for @mieweb/ui. Holds the
+ * edited word timeline (deletions, insertions, text edits, silence
+ * splitting), a single-level undo stack, an internal clipboard, speed
+ * markers, and derived playback/statistics data.
+ *
+ * Controlled + persistence-agnostic: no DOM, no fetches. Selection lives in
+ * the UI layer — mutations take explicit indices. State flows out via
+ * `onChange` and back in via `initialEditedWords` / `initialUndoStack`.
+ */
+
+/** Default filler words offered for removal */
+declare const DEFAULT_FILLER_WORDS: string[];
+/** Default minimum silence duration in milliseconds to detect and insert */
+declare const DEFAULT_MIN_SILENCE_MS = 400;
+/** Default threshold for "newline" silences - longer pauses that indicate paragraph breaks */
+declare const DEFAULT_NL_SILENCE_MS = 1500;
+/** Clipboard data for cut/copy/paste operations */
+interface TranscriptClipboard {
+    words: EditableWord[];
+    operation: 'cut' | 'copy';
+}
+/** Count and total duration of silences above a given threshold (seconds) */
+interface SilenceThresholdCount {
+    threshold: number;
+    count: number;
+    durationMs: number;
+}
+/**
+ * Builds playback segments from the edited word list.
+ * Consecutive words in original order are merged into single segments.
+ * Inserted (pasted) words each get their own segment since they may be duplicates.
+ */
+declare function buildPlaybackSegments(editedWords: EditableWord[]): PlaybackSegment[];
+/**
+ * Get the effective playback speed at a given word index.
+ * Finds the most recent speed marker at or before the word index,
+ * or returns the default speed if no marker applies.
+ */
+declare function getSpeedAtIndex(wordIndex: number, speedMarkers: SpeedMarker[], defaultSpeed: PlaybackSpeed): PlaybackSpeed;
+/**
+ * Detect silences between words and return a new array with silence pseudo-words inserted.
+ * Silences are detected as gaps between the endMs of one word and startMs of the next.
+ * Silences >= nlSilenceMs are marked as 'silence-newline' for visual line breaks.
+ */
+declare function insertSilences(words: TranscriptWord[], minSilenceMs?: number, nlSilenceMs?: number): TranscriptWord[];
+/** Initialize editable words from transcript, inserting detected silences */
+declare function initEditableWords(transcript: Transcript, minSilenceMs?: number, nlSilenceMs?: number): EditableWord[];
+interface UseTranscriptEditsOptions {
+    /** The source transcript (canonical, immutable) */
+    transcript: Transcript;
+    /** Initial edited words (from saved edits) */
+    initialEditedWords?: EditableWord[];
+    /** Initial undo stack (from saved edits) */
+    initialUndoStack?: EditableWord[][];
+    /** Fired after every mutation (for persistence) */
+    onChange?: (editedWords: EditableWord[], undoStack: EditableWord[][]) => void;
+    /** Minimum silence duration (ms) to detect and insert. Default 400 */
+    minSilenceMs?: number;
+    /** Threshold (ms) for "newline" silences (paragraph breaks). Default 1500 */
+    nlSilenceMs?: number;
+    /** Initial speed markers (from saved edits) */
+    initialSpeedMarkers?: SpeedMarker[];
+    /** Initial default playback speed (from saved edits). Default 1 */
+    initialDefaultSpeed?: PlaybackSpeed;
+}
+interface TranscriptEditStats {
+    /** Non-deleted spoken words (silences excluded) */
+    activeWordCount: number;
+    /** Non-deleted silence entries */
+    activeSilenceCount: number;
+    /** Deleted spoken words */
+    deletedWordCount: number;
+    /** Deleted silence entries */
+    deletedSilenceCount: number;
+    /** Total duration of non-deleted entries, adjusted for speed markers */
+    editedDurationMs: number;
+}
+interface FillerAnalysis {
+    /** Occurrence count per normalized word (fillers and every active word) */
+    matchCounts: Map<string, number>;
+    /** Total duration (ms) per normalized word */
+    durations: Map<string, number>;
+    /** Count + total duration of active silences above each analysis threshold */
+    silenceCounts: SilenceThresholdCount[];
+    /** The built-in filler word list */
+    defaultFillerWords: string[];
+}
+interface UseTranscriptEditsResult {
+    /** The edited timeline (words + silence pseudo-words) */
+    editedWords: EditableWord[];
+    /** Undo snapshots, oldest first */
+    undoStack: EditableWord[][];
+    /** Internal clipboard from the last cut/copy, or null */
+    clipboard: TranscriptClipboard | null;
+    /** Whether any edit has been made (deletions, insertions, text edits, speed markers) */
+    hasEdits: boolean;
+    /** Push the current editedWords onto the undo stack (call before external batch mutations) */
+    pushUndo: () => void;
+    /** Restore the most recent undo snapshot */
+    undo: () => void;
+    /** Step forward again after an undo. Cleared by any new edit. */
+    redo: () => void;
+    /** Whether there is anything to redo */
+    canRedo: boolean;
+    /** Toggle the deleted flag on a single word */
+    toggleWordDeleted: (index: number) => void;
+    /**
+     * Toggle the deleted state of a contiguous range. The first index acts as
+     * the anchor: all words are set to the opposite of the anchor's state
+     * (delete all if anchor active, restore all if anchor deleted).
+     */
+    deleteRange: (indices: number[]) => void;
+    /** Cut words at the given indices into the clipboard (marks them deleted) */
+    cut: (indices: number[]) => void;
+    /** Copy non-deleted words at the given indices into the clipboard */
+    copy: (indices: number[]) => void;
+    /**
+     * Paste the clipboard at a word index. `before` (default true) inserts
+     * before the word at `atIndex`; false inserts after it. Returns the index
+     * where the first pasted word landed, or null if the clipboard was empty.
+     */
+    paste: (atIndex: number, before?: boolean) => number | null;
+    /** Replace a word's text (no-op if unchanged) */
+    setWordText: (index: number, text: string) => void;
+    /** Split a silence at the given index into segments with the given durations (seconds) */
+    splitSilence: (index: number, durationsSec: number[]) => void;
+    /** Toggle the word at the index deleted (editor "delete" action) */
+    deleteWord: (index: number) => void;
+    /** Replace the entire edit state from an external source (e.g. an editable script view); undo-safe */
+    replaceEditedWords: (next: EditableWord[]) => void;
+    /** Mark matching filler words (and silences above the given seconds threshold) deleted */
+    removeFillers: (fillerWords: string[], removeSilenceAboveSec: number | null) => void;
+    /** Rebuild silence detection with new thresholds, preserving word deletions.
+     *  Not undoable — clears the undo stack (prior snapshots reference the old silence layout). */
+    setSilenceThresholds: (minMs: number, nlMs: number) => void;
+    /** Current silence detection thresholds (ms) */
+    silenceThresholds: {
+        minSilenceMs: number;
+        nlSilenceMs: number;
+    };
+    /** Speed markers, sorted by word index */
+    speedMarkers: SpeedMarker[];
+    /** Default playback speed when no marker applies */
+    defaultSpeed: PlaybackSpeed;
+    /** Set the default playback speed (undoable) */
+    setDefaultSpeed: (speed: PlaybackSpeed) => void;
+    /** Add/update/remove a speed marker (re-selecting the same speed removes it; undoable) */
+    toggleSpeedMarker: (index: number, speed: PlaybackSpeed) => void;
+    /** Remove the speed marker at a word index, if any (undoable) */
+    removeSpeedMarker: (index: number) => void;
+    /**
+     * Apply one speed across an index range (typically the selection): marks the
+     * start, restores the prior effective speed after the end. One undo step.
+     */
+    setSpeedForRange: (startIndex: number, endIndex: number, speed: PlaybackSpeed) => void;
+    /** Effective playback speed at a word index */
+    getSpeedAtIndex: (index: number) => PlaybackSpeed;
+    /** The speed marker at a word index, if any */
+    getSpeedMarkerAtIndex: (index: number) => SpeedMarker | undefined;
+    /** Contiguous playback segments built from the edited timeline */
+    playbackSegments: PlaybackSegment[];
+    /** Word/silence counts and speed-adjusted edited duration */
+    stats: TranscriptEditStats;
+    /** Filler word and silence analysis for removal UIs */
+    fillerAnalysis: FillerAnalysis;
+}
+/**
+ * Headless transcript-editing hook. See module docs for scope.
+ *
+ * Undo semantics: each mutation snapshots the full `editedWords` array onto
+ * a single-level stack before applying; `undo` pops one snapshot. Speed
+ * markers and silence-threshold changes are NOT part of the undo stack
+ * (matching the source component).
+ */
+declare function useTranscriptEdits(options: UseTranscriptEditsOptions): UseTranscriptEditsResult;
+
+export { type AnchoredPlacement, DEFAULT_DRAG_REORDER_LABELS, DEFAULT_FILLER_WORDS, DEFAULT_MIN_SILENCE_MS, DEFAULT_NL_SILENCE_MS, type Direction, type DragOverState, type DragReorderLabels, type FillerAnalysis, type HoverPreviewState, KEYBOARD_INSET_VAR, KEYBOARD_OPEN_ATTRIBUTE, KEYBOARD_SOURCE_ATTRIBUTE, type KeyboardInsetSource, type KeyboardInsetState, type KeyboardShortcutOptions, type MediaTransportState, type OrderPersistenceAdapter, RTL_LOCALES, type ResolvedTheme, type SilenceThresholdCount, type Theme, type TranscriptClipboard, type TranscriptEditStats, type UseAnchoredPositionOptions, type UseAnchoredPositionReturn, type UseDragReorderOptions, type UseDragReorderReturn, type UseKeyboardInsetOptions, type UseMediaTransportOptions, type UseMediaTransportReturn, type UseOrderPersistenceOptions, type UseOrderPersistenceReturn, type UseScrollSpyOptions, type UseScrollSpyReturn, type UseStickToBottomOptions, type UseStickToBottomReturn, type UseTranscriptEditsOptions, type UseTranscriptEditsResult, type UseYouTubeHoverPreviewOptions, type UseYouTubeHoverPreviewReturn, VISUAL_VIEWPORT_HEIGHT_VAR, VISUAL_VIEWPORT_OFFSET_TOP_VAR, buildPlaybackSegments, dragIndicatorClasses, getSpeedAtIndex, initEditableWords, insertSilences, isDarkMode, isRtl, isRtlLocale, localStorageOrderAdapter, mergeOrder, moveIdBy, reorderIds, useAnchoredPosition, useClickOutside, useCommandK, useDirection, useDragReorder, useEscapeKey, useFocusTrap, useIsDarkMode, useIsDesktop, useIsLargeDesktop, useIsMobile, useIsMobileOrTablet, useIsSmallTablet, useIsTablet, useKeyboardInset, useKeyboardShortcut, useLiveAnnouncement, useMediaQuery, useMediaTransport, useOrderPersistence, usePrefersReducedMotion, useScrollSpy, useStickToBottom, useStreamEndedBelowFold, useTheme, useTranscriptEdits, useUrlTab, useYouTubeHoverPreview };