@joewinke/jatui 0.34.2 → 0.36.1

package/dist/utils/audioRecorderCore.d.ts

@@ -57,11 +57,32 @@ export interface AudioRecorderFrame {
     /** Time-domain bytes (from getByteTimeDomainData) — raw PCM-ish shape. */
     time: Uint8Array;
 }
+/** One MediaRecorder timeslice of audio, handed to `onChunk` as it arrives
+ * (jatui-ft2ot). The take keeps accumulating for `onStop` regardless — hosts
+ * that buffer chunks (restartable dictation, live transcription) consume
+ * both streams independently. */
+export interface AudioRecorderChunk {
+    /** The chunk blob — one MediaRecorder `dataavailable` payload. */
+    blob: Blob;
+    /** MIME type of the recording (same value `onStop` reports). */
+    mimeType: string;
+    /** Cumulative bytes captured so far in this take (all chunks, not just this one). */
+    sizeBytes: number;
+    /** Pause-adjusted elapsed ms at the moment this chunk arrived. */
+    elapsedMs: number;
+    /** 0-based index of this chunk within the take. Resets on a new take. */
+    index: number;
+}
 export interface AudioRecorderOptions {
     /** `'toggle'` (default) or `'push'` (hold-to-talk — see module header). */
     mode?: AudioRecorderMode;
     /** Auto-stop ceiling in ms. 0 (default) records until stopped manually. */
     maxDurationMs?: number;
+    /** Timeslice in ms passed to `MediaRecorder.start()` — chunks are emitted
+     * at least this often and delivered to `onChunk` (jatui-ft2ot). Default
+     * 1000 (the historical behavior). 0 records as a single blob until stop
+     * (no intermediate chunking). */
+    timesliceMs?: number;
     /** Fired once the mic stream is live and recording has started. */
     onStart?: () => void;
     onPause?: () => void;
@@ -77,6 +98,12 @@ export interface AudioRecorderOptions {
     /** Fired every animation frame while recording — analyser data for hosts
      * that draw their own waveform/level UI. Not fired while paused. */
     onFrame?: (frame: AudioRecorderFrame) => void;
+    /** Fired per MediaRecorder chunk as it arrives (every `timesliceMs`, plus
+     * a final shorter chunk at stop). The take still accumulates for `onStop` —
+     * hosts get the full take AND a live chunk stream (restartable dictation,
+     * streaming transcription). A throwing handler reports `handler-failed`
+     * but does NOT stop the recording. */
+    onChunk?: (chunk: AudioRecorderChunk) => void;
 }
 /** Injectable platform bindings — defaults resolve from globalThis lazily at factory time, so Node (no MediaRecorder) degrades to `supported: false` instead of throwing at import. */
 export interface AudioRecorderDeps {
@@ -104,11 +131,18 @@ export interface AudioRecorderSnapshot {
     elapsedMs: number;
     /** Last error, or null. */
     error: AudioRecorderError | null;
+    /** Live mic MediaStream while the recorder holds it (starting/recording),
+     * else null (jatui-ft2ot). For hosts that attach the raw stream — WebRTC,
+     * a custom MediaRecorder with requestData()-driven streaming. */
+    stream: MediaStream | null;
 }
 export interface AudioRecorderCore {
     /** False when the platform has no getUserMedia/MediaRecorder (SSR, Node). */
     readonly supported: boolean;
     readonly mode: AudioRecorderMode;
+    /** Live mic MediaStream while the recorder holds it, else null — same
+     * value as `snapshot().stream`, for hosts that read it imperatively. */
+    readonly stream: MediaStream | null;
     /** Current reactive-independent snapshot (the rune wrapper copies this into $state). */
     snapshot(): AudioRecorderSnapshot;
     /** Subscribe to snapshot changes. Returns an unsubscribe fn. */

package/dist/utils/audioRecorderCore.js

@@ -61,7 +61,7 @@ export function computeElapsedMs(startedAt, pausedTotalMs, pauseStartedAt, now)
     return Math.max(0, now - startedAt - pausedMs);
 }
 export function createAudioRecorderCore(options = {}, deps = {}) {
-    const { mode = 'toggle', maxDurationMs = 0, onStart, onPause, onResume, onStop, onCancel, onError, onFrame } = options;
+    const { mode = 'toggle', maxDurationMs = 0, timesliceMs = 1000, onStart, onPause, onResume, onStop, onCancel, onError, onFrame, onChunk } = options;
     // Lazy globalThis defaults — resolved per factory call, never at import time.
     const g = (v) => v;
     const getUserMedia = deps.getUserMedia ??
@@ -87,6 +87,8 @@ export function createAudioRecorderCore(options = {}, deps = {}) {
     let level = 0;
     let sizeBytes = 0;
     let error = null;
+    /** 0-based index of the next chunk in the current take. */
+    let chunkIndex = 0;
     // Recorder internals
     let recorder = null;
     let stream = null;
@@ -105,7 +107,15 @@ export function createAudioRecorderCore(options = {}, deps = {}) {
     let pendingCancel = false;
     const listeners = new Set();
     function snapshot() {
-        return { phase, paused, level, sizeBytes, elapsedMs: computeElapsedMs(startedAt, pausedTotalMs, pauseStartedAt, now()), error };
+        return {
+            phase,
+            paused,
+            level,
+            sizeBytes,
+            elapsedMs: computeElapsedMs(startedAt, pausedTotalMs, pauseStartedAt, now()),
+            error,
+            stream
+        };
     }
     function notify() {
         const s = snapshot();
@@ -273,11 +283,32 @@ export function createAudioRecorderCore(options = {}, deps = {}) {
         }
         chunks = [];
         sizeBytes = 0;
+        chunkIndex = 0;
         recorder.ondataavailable = (e) => {
             if (e.data && e.data.size > 0) {
-                chunks.push(e.data);
-                sizeBytes += e.data.size;
+                const blob = e.data;
+                chunks.push(blob);
+                sizeBytes += blob.size;
+                const chunk = {
+                    blob,
+                    mimeType,
+                    sizeBytes,
+                    elapsedMs: elapsed(),
+                    index: chunkIndex++
+                };
                 notify();
+                if (onChunk) {
+                    try {
+                        onChunk(chunk);
+                    }
+                    catch (err) {
+                        // A throwing chunk handler must not lose the take — report and keep capturing.
+                        fail({
+                            kind: 'handler-failed',
+                            message: `Chunk kept, but the onChunk handler failed: ${err instanceof Error ? err.message : String(err)}`
+                        });
+                    }
+                }
             }
         };
         recorder.onstop = () => {
@@ -300,7 +331,7 @@ export function createAudioRecorderCore(options = {}, deps = {}) {
                 analyser = null;
             }
         }
-        recorder.start(1000);
+        recorder.start(timesliceMs > 0 ? timesliceMs : undefined);
         startedAt = now();
         pausedTotalMs = 0;
         pauseStartedAt = 0;
@@ -381,7 +412,10 @@ export function createAudioRecorderCore(options = {}, deps = {}) {
         if (wasCancelled)
             return;
         if (chunks.length === 0) {
-            // Zero chunks (e.g. stopped before any data arrived) — fail loud, not a silent no-op.
+            // Zero chunks (e.g. stopped before any data arrived) — fail loud, not a
+            // silent no-op. Release the mic + audio graph like every other exit, so
+            // a failed take can't leave a hot microphone behind.
+            teardown();
             phase = 'idle';
             notify();
             fail({ kind: 'too-short', message: 'Recording was too short — nothing was captured. Try again.' });
@@ -434,6 +468,9 @@ export function createAudioRecorderCore(options = {}, deps = {}) {
             return supported;
         },
         mode,
+        get stream() {
+            return stream;
+        },
         snapshot,
         subscribe,
         start,

package/dist/utils/keyboardShortcutHub.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Keyboard shortcut hub — the "one overlay" coordination layer for
+ * KeyboardShortcutsOverlay's host/contributor mode.
+ *
+ * Page-level overlay instances usually self-render (the pre-existing
+ * non-host fallback path). But an app shell can mount ONE "global" host
+ * overlay; every other overlay on the page then becomes a contributor:
+ * instead of self-rendering it contributes its sections (under a
+ * `sectionTitle`) to the host's panel and forwards its `open` requests to
+ * the host, so exactly one `?`-overlay exists no matter how many surfaces
+ * mount the component.
+ *
+ * Pure TypeScript (no Svelte), subscriber-based like ShortcutRegistry —
+ * reactivity lives in the overlay components, which re-read on notify.
+ *
+ * Usage (app shell):
+ *
+ *   <KeyboardShortcutsOverlay mode="host" />           // owns the `?` toggle
+ *
+ * Usage (page / portal / contract page):
+ *
+ *   <KeyboardShortcutsOverlay
+ *     {sections}
+ *     sectionTitle="Inbox"
+ *     showHint={false}
+ *   />
+ *   // self-renders when no host exists; contributes when one does
+ */
+export interface ShortcutContribution {
+    /** Stable id for the contributing surface (page route, portal name…). */
+    id: string;
+    /** Label under which the contributed sections appear in the host panel. */
+    sectionTitle: string;
+    /** Contributed sections (same shape as KeyboardShortcutsOverlay's `sections`). */
+    sections: ShortcutSectionLike[];
+    /** Registry snapshot (context-keyed sections) — optional alternative to `sections`. */
+    registrySections?: ShortcutSectionLike[];
+}
+export interface ShortcutSectionLike {
+    title: string;
+    shortcuts: {
+        key: string;
+        description: string;
+        color?: string;
+    }[];
+}
+export interface KeyboardShortcutHost {
+    /** Toggle the host overlay open/closed. */
+    toggle: () => void;
+    /** Open the host overlay (idempotent while already open). */
+    open: () => void;
+}
+declare class KeyboardShortcutHub {
+    private host;
+    private contributions;
+    private listeners;
+    /** True when a host overlay is mounted (contributing instances defer to it). */
+    get hasHost(): boolean;
+    /** Mount the host. Returns the unmount function. */
+    registerHost(host: KeyboardShortcutHost): () => void;
+    /** Contribute sections from a page-level overlay instance. Returns unregister. */
+    contribute(contribution: ShortcutContribution): () => void;
+    /** Contributed sections in registration order, labelled by sectionTitle. */
+    getContributions(): ShortcutContribution[];
+    /** Ask the host overlay to open. No-op when there is no host. */
+    requestOpen(): boolean;
+    /** Subscribe to hub changes (host mount/unmount, contributions). */
+    subscribe(listener: () => void): () => void;
+    private notify;
+}
+export declare const keyboardShortcutHub: KeyboardShortcutHub;
+export declare const KEYBOARD_SHORTCUT_HUB_ID = "keyboard-shortcut-hub";
+export {};

package/dist/utils/keyboardShortcutHub.js

@@ -0,0 +1,89 @@
+/**
+ * Keyboard shortcut hub — the "one overlay" coordination layer for
+ * KeyboardShortcutsOverlay's host/contributor mode.
+ *
+ * Page-level overlay instances usually self-render (the pre-existing
+ * non-host fallback path). But an app shell can mount ONE "global" host
+ * overlay; every other overlay on the page then becomes a contributor:
+ * instead of self-rendering it contributes its sections (under a
+ * `sectionTitle`) to the host's panel and forwards its `open` requests to
+ * the host, so exactly one `?`-overlay exists no matter how many surfaces
+ * mount the component.
+ *
+ * Pure TypeScript (no Svelte), subscriber-based like ShortcutRegistry —
+ * reactivity lives in the overlay components, which re-read on notify.
+ *
+ * Usage (app shell):
+ *
+ *   <KeyboardShortcutsOverlay mode="host" />           // owns the `?` toggle
+ *
+ * Usage (page / portal / contract page):
+ *
+ *   <KeyboardShortcutsOverlay
+ *     {sections}
+ *     sectionTitle="Inbox"
+ *     showHint={false}
+ *   />
+ *   // self-renders when no host exists; contributes when one does
+ */
+const HUB_ID = 'keyboard-shortcut-hub';
+class KeyboardShortcutHub {
+    host = null;
+    contributions = new Map();
+    listeners = new Set();
+    /** True when a host overlay is mounted (contributing instances defer to it). */
+    get hasHost() {
+        return this.host !== null;
+    }
+    /** Mount the host. Returns the unmount function. */
+    registerHost(host) {
+        if (this.host && this.host !== host) {
+            // Two hosts — the later one wins (last-mounted). Warn loudly: a
+            // page accidentally mounting a second global overlay is a bug.
+            console.warn('[keyboardShortcutHub] replacing an existing host overlay — did you mount the global overlay twice?');
+        }
+        this.host = host;
+        this.notify();
+        return () => {
+            if (this.host === host) {
+                this.host = null;
+                this.notify();
+            }
+        };
+    }
+    /** Contribute sections from a page-level overlay instance. Returns unregister. */
+    contribute(contribution) {
+        this.contributions.set(contribution.id, contribution);
+        this.notify();
+        return () => {
+            if (this.contributions.get(contribution.id) === contribution) {
+                this.contributions.delete(contribution.id);
+                this.notify();
+            }
+        };
+    }
+    /** Contributed sections in registration order, labelled by sectionTitle. */
+    getContributions() {
+        return [...this.contributions.values()];
+    }
+    /** Ask the host overlay to open. No-op when there is no host. */
+    requestOpen() {
+        if (!this.host)
+            return false;
+        this.host.open();
+        return true;
+    }
+    /** Subscribe to hub changes (host mount/unmount, contributions). */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    notify() {
+        for (const l of this.listeners)
+            l();
+    }
+}
+export const keyboardShortcutHub = new KeyboardShortcutHub();
+export const KEYBOARD_SHORTCUT_HUB_ID = HUB_ID;

package/dist/utils/mentionParser.d.ts

@@ -4,8 +4,16 @@
  * Handles parsing and rendering of @-mentions in messages.
  * Format: [@Display Name](type:id) -> clickable links
  *
- * The URL generator is configurable — consuming apps provide their own
- * routing via the `urlGenerator` parameter or by setting a default.
+ * URL routing has three layers (most specific first):
+ *   1. the `urlGenerator` parameter on a given parse/render call
+ *   2. a per-type registration — registerMentionType(type, generator) —
+ *      so each mention type carries its own routing (e.g. @agent mentions
+ *      route to /admin/settings/agent while @user routes elsewhere)
+ *   3. the single app-wide default — setMentionUrlGenerator
+ *
+ * The per-type registry is what lets a consuming app retire a local
+ * mentionParser copy (mos-i8nnd.18): one default generator cannot express
+ * per-type routing.
  */
 export interface MentionMatch {
     type: string;
@@ -17,6 +25,22 @@ export interface MentionMatch {
     fullMatch: string;
 }
 export type MentionUrlGenerator = (type: string, id: string) => string;
+/** The mention type used to reference agents (extractAgentMentions). */
+export declare const AGENT_MENTION_TYPE = "agent";
+/** Per-type registration record held by the registry. */
+export interface MentionTypeConfig {
+    urlGenerator: MentionUrlGenerator;
+}
+/**
+ * Register a URL generator for a specific mention type.
+ *
+ * Call once at app startup per routed type (e.g. registerMentionType('agent',
+ * () => '/admin/settings/agent')). Re-registering a type replaces its
+ * generator; the returned function unregisters exactly that registration.
+ * The type must be an identifier token — the mention regex only accepts
+ * `[A-Za-z0-9_-]+`, so anything else could never match a mention.
+ */
+export declare function registerMentionType(type: string, urlGenerator: MentionUrlGenerator): () => void;
 /**
  * Set the default URL generator for mentions.
  * Call this once at app startup to configure mention link routing.
@@ -73,6 +97,24 @@ export declare function replaceMentionInContent(content: string, startIndex: num
     newContent: string;
     newCursorPosition: number;
 };
+/**
+ * Extract only agent mentions (type='agent').
+ */
+export declare function extractAgentMentions(content: string): MentionMatch[];
+/**
+ * Cheap boolean check — does the content contain at least one mention?
+ */
+export declare function hasMentions(content: string): boolean;
+/**
+ * Unique ids of @user mentions, in order of first appearance.
+ * Agent mentions are separate — use extractAgentMentions.
+ */
+export declare function getMentionedUserIds(content: string): string[];
+/**
+ * Mentions deduped by type+id (first occurrence wins, appearance order
+ * preserved), optionally filtered to a single type.
+ */
+export declare function getUniqueMentionsByType(content: string, type?: string): MentionMatch[];
 /**
  * Simple HTML escape function
  */

package/dist/utils/mentionParser.js

@@ -4,9 +4,43 @@
  * Handles parsing and rendering of @-mentions in messages.
  * Format: [@Display Name](type:id) -> clickable links
  *
- * The URL generator is configurable — consuming apps provide their own
- * routing via the `urlGenerator` parameter or by setting a default.
+ * URL routing has three layers (most specific first):
+ *   1. the `urlGenerator` parameter on a given parse/render call
+ *   2. a per-type registration — registerMentionType(type, generator) —
+ *      so each mention type carries its own routing (e.g. @agent mentions
+ *      route to /admin/settings/agent while @user routes elsewhere)
+ *   3. the single app-wide default — setMentionUrlGenerator
+ *
+ * The per-type registry is what lets a consuming app retire a local
+ * mentionParser copy (mos-i8nnd.18): one default generator cannot express
+ * per-type routing.
+ */
+/** The mention type used to reference agents (extractAgentMentions). */
+export const AGENT_MENTION_TYPE = 'agent';
+// Per-type registry — populated by registerMentionType; wins over the
+// app-wide default for that type, loses to an explicit generator argument.
+const mentionTypes = new Map();
+/**
+ * Register a URL generator for a specific mention type.
+ *
+ * Call once at app startup per routed type (e.g. registerMentionType('agent',
+ * () => '/admin/settings/agent')). Re-registering a type replaces its
+ * generator; the returned function unregisters exactly that registration.
+ * The type must be an identifier token — the mention regex only accepts
+ * `[A-Za-z0-9_-]+`, so anything else could never match a mention.
  */
+export function registerMentionType(type, urlGenerator) {
+    if (!/^[A-Za-z0-9_-]+$/.test(type)) {
+        throw new TypeError(`mention type ${JSON.stringify(type)} must match /^[A-Za-z0-9_-]+$/ — ` +
+            'the mention regex only matches identifier tokens');
+    }
+    mentionTypes.set(type, { urlGenerator });
+    return () => {
+        // Only remove OUR registration — a later re-registration must survive.
+        if (mentionTypes.get(type)?.urlGenerator === urlGenerator)
+            mentionTypes.delete(type);
+    };
+}
 // Regex to match mention pattern: [@Display Name](type:id)
 //
 // `type` is an identifier token, never free text (mos-3xvn1): it lands in
@@ -28,7 +62,6 @@ export function setMentionUrlGenerator(generator) {
  */
 export function parseMentions(content, urlGenerator) {
     const mentions = [];
-    const gen = urlGenerator ?? defaultUrlGenerator;
     let match;
     MENTION_REGEX.lastIndex = 0;
     while ((match = MENTION_REGEX.exec(content)) !== null) {
@@ -37,7 +70,9 @@ export function parseMentions(content, urlGenerator) {
             type,
             id,
             displayName,
-            url: gen(type, id),
+            // Resolution: explicit call-site generator > per-type registered
+            // generator > the app-wide default.
+            url: (urlGenerator ?? mentionTypes.get(type)?.urlGenerator ?? defaultUrlGenerator)(type, id),
             startIndex: match.index,
             endIndex: match.index + fullMatch.length,
             fullMatch
@@ -147,6 +182,51 @@ export function replaceMentionInContent(content, startIndex, endIndex, mentionSt
     const newCursorPosition = startIndex + mentionString.length;
     return { newContent, newCursorPosition };
 }
+/**
+ * Extract only agent mentions (type='agent').
+ */
+export function extractAgentMentions(content) {
+    return parseMentions(content).filter((mention) => mention.type === AGENT_MENTION_TYPE);
+}
+/**
+ * Cheap boolean check — does the content contain at least one mention?
+ */
+export function hasMentions(content) {
+    MENTION_REGEX.lastIndex = 0;
+    return MENTION_REGEX.test(content);
+}
+/**
+ * Unique ids of @user mentions, in order of first appearance.
+ * Agent mentions are separate — use extractAgentMentions.
+ */
+export function getMentionedUserIds(content) {
+    const ids = [];
+    for (const mention of parseMentions(content)) {
+        if (mention.type !== 'user')
+            continue;
+        if (!ids.includes(mention.id))
+            ids.push(mention.id);
+    }
+    return ids;
+}
+/**
+ * Mentions deduped by type+id (first occurrence wins, appearance order
+ * preserved), optionally filtered to a single type.
+ */
+export function getUniqueMentionsByType(content, type) {
+    const seen = new Set();
+    const out = [];
+    for (const mention of parseMentions(content)) {
+        if (type && mention.type !== type)
+            continue;
+        const key = `${mention.type}:${mention.id}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(mention);
+    }
+    return out;
+}
 /**
  * Simple HTML escape function
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joewinke/jatui",
-  "version": "0.34.2",
+  "version": "0.36.1",
   "private": false,
   "description": "Shared Svelte 5 component library for JAT projects",
   "type": "module",
@@ -188,6 +188,7 @@
     "lenis": "^1.3.25",
     "livekit-client": "^2.20.1",
     "motion": "^12.42.2",
+    "@playwright/test": "^1.62.1",
     "playwright": "^1.62.1",
     "svelte": "^5.0.0",
     "tailwindcss": "^4.0.0",