@happyvertical/smrt-svelte 0.51.38 → 0.52.0

package/AGENTS.md

@@ -20,6 +20,9 @@ subpath you are editing. This file keeps what holds in every module.
 | `src/web/webmcp-provider.ts` | Provider config for generated data/model WebMCP tools: definitions, effect policy, namespace, budget, legacy/canonical filters, and fetcher seams (#2520) | — |
 | `src/web/webmcp-ui.ts` | Fixed, low-cardinality WebMCP adapter over the Provider's mounted form-control and data-surface registries (#2521) | — |
 | `src/web/webmcp.svelte.ts` (`useWebMcpTool`) | Component-owned bespoke WebMCP tool. Routes through `@happyvertical/smrt-web`'s `registerWebMcpBespokeTool`, so it shares the fail-closed effect classification and `effects` exposure policy of generated tools — undeclared `annotations` classify destructive and are excluded by default. `namespace` and `maxTools` never apply to a bespoke tool (#2586) | — |
+| `src/web/{list,link,step}-surface.svelte.ts` (`useListSurface`, `useLinkSurface`, `useStepSurface`) | Lifecycle hooks mounting a rendered list (projected `state.rows` + a `find` text lookup), a menu/tab row (`open` → `navigate`, hrefs never published), and a wizard (`next`/`back`/`go-to`; a writing step is revealed via `showNext`, never pressed) on the Provider's data-surface registry. The Svelte-free halves live in `@happyvertical/smrt-ui/data` | — |
+| `src/web/webmcp-ui-context.ts` (`useWebMcpUi`, `tryUseWebMcpUi`) | Provider mounted-UI registries; `tryUseWebMcpUi` returns `null` instead of throwing when there is no Provider or its WebMCP UI is off (#2915) | — |
+| `src/components/forms/Form.svelte` + `FormScope.svelte` | Rich Form spreads native attributes/attachments, takes `enhance`, and its `*_stage_changes` tool covers smrt-ui controls via `controlProposalProperties`/`stageControlProposals` (smrt-ui); `FormScope` is the same without a `<form>` element | — |
 
 The composed WebMCP fixture in
 `src/web/__tests__/webmcp-composed.integration.svelte.test.ts` mounts a real

package/README.md

@@ -182,6 +182,25 @@ default) — except a canonical table-control id (`set-filters`, `reset`,
 reaches `onControl`, even under a custom label. See
 `docs/data-surface-conformance.md` for the full contract.
 
+Three lifecycle hooks cover the common page shapes without any registration
+code; each resolves the nearest Provider's registry (or an explicit one),
+re-mounts on an identity change, and unmounts with the component:
+
+- `useListSurface(() => ({ surfaceId, label, description, columns, rows }))`
+  publishes the page's rendered rows, projected to the declared columns and
+  capped (`maxRows`, default 50), as `state.rows`. Columns marked
+  `searchable` enable a `find` control: `{ text }` publishes the rows whose
+  searchable columns contain the text (any case, accents ignored) across all
+  rows, with `state.find = { text, matches }` — so an agent can look an
+  article up by title on the page. It narrows only what the agent reads;
+  table commands stay refused and the page's own controls stay in charge.
+- `useLinkSurface(() => ({ surfaceId, label, description, links, navigate }))`
+  exposes a menu or tab row as an `open` control (see `registerLinkSurface`
+  in smrt-ui).
+- `useStepSurface(() => ({ surfaceId, …, steps, current, next, back,
+  nextWrites, showNext }))` exposes a wizard's `next`/`back`/`go-to`; a step
+  whose forward button writes is revealed for the person, never pressed.
+
 The default prefix is `smrt_ui_`. Configure `ui.prefix` when multiple Providers
 must coexist in one document; the same prefix cannot be registered twice. The
 six derived names are reserved through the document-global tool-name lock, so
@@ -201,6 +220,47 @@ hidden data-surface columns are not serialized. Read responses are marked as
 untrusted content. Bespoke `useWebMcpTool` and `<Form webmcp>` tools retain their
 existing lifecycle and submit behavior.
 
+#### `<Form webmcp>` with SvelteKit `enhance` and smrt-ui fields
+
+The rich `Form` renders its own `<form>`, so it forwards every native form
+attribute (`method`, `action`, `enctype`, `novalidate`, `autocomplete`,
+`aria-*`, `data-*`, …) and attachments (`{@attach …}`) to that element. A
+component cannot take `use:`, so pass SvelteKit's `enhance` as a prop — it is
+applied to the rendered `<form>` and torn down with it. Without `onsubmit`
+the Form never prevents submission, so `enhance` (or a native POST) runs as
+usual and an error summary above the fields keeps working:
+
+```svelte
+<script lang="ts">
+  import { enhance } from '$app/forms';
+  import { Form } from '@happyvertical/smrt-svelte/forms';
+  import { ErrorSummary, FormGroup, Input } from '@happyvertical/smrt-ui/forms';
+</script>
+
+<Form formId="setup-network" webmcp method="POST" action="?/create" novalidate
+  enhance={(form) => enhance(form, submit)}>
+  <ErrorSummary errors={errors} />
+  <FormGroup label="Network name" id="name"><Input name="name" bind:value={name} /></FormGroup>
+</Form>
+```
+
+Its `<formId>_stage_changes` tool describes rich fields (`TextInput`,
+`MoneyInput`, …) and every other control the registry holds for the form:
+smrt-ui primitives (`FormGroup` + `Input`/`Select`/`Textarea`/`Combobox`/…)
+and composites registered with `useControlRegistration`. Proposals for either
+kind are staged for the person to review and apply; nothing is written or
+submitted by the tool.
+
+`FormScope` (`@happyvertical/smrt-svelte/forms`) is the same tool and review
+surface without a `<form>` element — for a fetch-driven wizard, an editor
+saved in parts, or a page that must keep its own `<form>` markup. It joins
+the nearest Provider's control registry (or a local one) and registers no
+tool until at least one proposable control is mounted.
+
+`tryUseWebMcpUi()` returns the Provider's mounted-UI registries, or `null`
+when there is no Provider or its WebMCP UI is off — use it to fall back to a
+local registry instead of catching `useWebMcpUi()`'s throw (#2915).
+
 Custom rich fields may continue to call `registerField(field)` and later
 `unregisterField(name)`. New code should retain and invoke the disposer returned
 by `registerField`: it is bound to that exact registration, so cleanup cannot
@@ -319,6 +379,112 @@ fetch) and mount `AdminShell` in `+layout.svelte`. The `template-sveltekit`
 scaffold adopts AdminShell as its default chrome exactly this way; copy its
 `src/routes/+layout.server.ts` / `+layout.svelte` / `settings/+page.svelte`.
 
+#### Responsive chrome and resizable edges
+
+AdminShell carries the phone/tablet/desktop chrome itself, so hosts do not
+wrap it in a frame. Everything below is opt-in; without these props and config
+keys the shell renders exactly as before.
+
+```svelte
+<script lang="ts">
+  import {
+    AdminShell,
+    createShellState,
+    PhoneBottomBar,
+    PhoneTopBar,
+    ShellNavToggle,
+    ShellTitle,
+    phoneTopBarFor,
+  } from '@happyvertical/smrt-svelte/workspace';
+
+  const shell = createShellState({
+    config: {
+      top: false,
+      bottom: false,
+      left: {
+        label: 'Navigation',
+        // Drawer on phones, icons on tablets, open on desktop.
+        viewportDefaults: { phone: 'collapsed', tablet: 'collapsed', desktop: 'expanded' },
+      },
+      right: {
+        label: 'Assistant',
+        expandedSize: '28rem',
+        resizable: { min: 320, max: 720 }, // drag, arrows, Home/End, double-click resets
+        phone: 'sheet', // or 'hidden' when the host shows it elsewhere on phones
+        keepMounted: true, // closing the sheet keeps the chat (and its draft) alive
+        overlayMedia: '(max-width: 99.9375rem)', // slide over the page below 1600px
+      },
+    },
+    storageKey: 'my-app-shell',
+  });
+</script>
+
+<AdminShell state={shell} path={page.url.pathname} phone={{ scrim: true, swipeToClose: true }}>
+  {#snippet header()}
+    <ShellNavToggle expanded={shell.panels.left === 'expanded'} onclick={() => shell.togglePanel('left')} />
+    <ShellTitle title="Acme" href="/" />
+  {/snippet}
+  {#snippet phoneTopBar()}
+    <PhoneTopBar model={phoneTopBarFor({ path, homeHref: '/', homeTitle: 'Acme', navItems })} homeHref="/" />
+  {/snippet}
+  {#snippet phoneBottomBar()}
+    <PhoneBottomBar {items} />
+  {/snippet}
+  {#snippet overlays({ viewport })}<!-- PhoneSheet, WorkingStrip, … -->{/snippet}
+  …
+</AdminShell>
+```
+
+- **`header`** is a full-width row above every edge (`#smrt-admin-shell-header`,
+  `--smrt-admin-shell-header-size`, default 3.5rem). On phones it is replaced
+  by `phoneTopBar` when one is given.
+- **Viewport classes**: `shell.viewport` is `phone` (≤ 48rem), `tablet`
+  (≤ 64rem) or `desktop`; `ADMIN_SHELL_PHONE_QUERY` / `ADMIN_SHELL_DESKTOP_QUERY`.
+  `viewportDefaults` apply on first render and whenever the class changes; such
+  an edge never persists its open/closed state.
+- **Phone chrome**: `phoneTopBar` overlays the top of the main region and hides
+  on scroll (`phone.hideOnScroll`, pinned by `pinChrome` or an open drawer);
+  `phoneBottomBar` is a bottom row that a form's `[data-form-action-bar]` (see
+  smrt-ui `FormActionBar`) replaces and the on-screen keyboard hides
+  (`:root[data-keyboard-open]`). `phone.scrim` dims the page behind a drawer or
+  sheet, `phone.swipeToClose` closes drawers by swiping. A `path` change on a
+  phone closes open drawers. `overlays` is a layer above the edges (and above
+  the bottom bar's row) for `PhoneSheet`s and status strips.
+- **Page contracts** on phones: `data-shell-breadcrumbs` is hidden,
+  `data-shell-page-title` is visually hidden while the phone top bar shows
+  (the bar carries the title), `data-shell-tabs` sticks under the top bar and
+  slides away with it. smrt-ui's `PageHeader` renders the first two.
+- **Page trail**: `shellPageTrailFor({ path, homeHref, homeTitle, navItems,
+  parents })` is the one source for a page's ancestors: section homes (home
+  and top-level nav pages) have none; other pages get the home, the nav items
+  above them, then page-given `parents`, never the page itself. Pass the
+  `crumbs` to `PageHeader`; `phoneTopBarFor` (same input plus `pageTitle`)
+  sends the phone back arrow to the last crumb.
+- **Resizable edges**: `resizable` on a `push` side edge adds a
+  `role="separator"` (with `aria-valuenow/min/max` in px) on its inner border.
+  Sizes are stored as `ShellSettingsDelta.sizes` through the settings adapter;
+  `persist: false` / `{ state?: false, size?: false }` opts an edge out of
+  storage.
+- **Overlay edges**: `overlayMedia` on a side edge is a media query under
+  which the expanded edge slides over the page (above a scrim, content keeps
+  its width) instead of pushing it, on tablet and desktop; above it the edge
+  docks. `shell.presentationFor(edge)` reports the live presentation. While
+  an overlay is open the page and the other edge are `inert`, the panel takes
+  focus (unless something inside already has it) and returns it on close;
+  Escape or a scrim click closes it, sliding it back out as the scrim fades
+  (no motion under `prefers-reduced-motion`). Resizing applies only while docked.
+- **Kept panels**: `keepMounted: true` keeps a collapsed edge's panel content
+  (`appPanel`, `tenantPanel`, the focus panel, `systemPanel`) mounted with the
+  `hidden` attribute instead of unmounting it, so component state (a chat
+  draft, scroll position) survives closing. The rail renders as usual; the
+  left edge keeps only a `tenantPanel`.
+- **Nav attention**: a `ShellNavItem` with `attention: true` (or a string
+  label) shows a dot in `TenantNav`, over the icon when collapsed, and
+  announces the label ("Needs attention" by default) inside the link.
+- **Public region ids** (`ADMIN_SHELL_REGION_IDS`): `smrt-admin-shell-header`,
+  `smrt-admin-shell-{top,left,right,bottom}-panel`, and
+  `smrt-admin-shell-main`, which is the page scroller.
+
 - **Migration guide** (first-generation `WorkspaceShell`/`RoleShell` →
   `AdminShell`; adoption is additive and non-breaking):
   [`src/components/workspace/MIGRATION.md`](./src/components/workspace/MIGRATION.md)
@@ -357,7 +523,7 @@ resolve against `smrt-ui`:
 | `@happyvertical/smrt-ui` | `PermissionCheck`, `permission` / `hasPermission` / `hasAnyPermission` / `hasAllPermissions` |
 | `@happyvertical/smrt-ui/ui` | UI primitives (Button, Card, Badge, Pagination) |
 | `@happyvertical/smrt-ui/layout` | Layout (Container, Grid, Header, Footer, Masthead, etc.) |
-| `@happyvertical/smrt-ui/calendar` | Calendar and DayView |
+| `@happyvertical/smrt-ui/calendar` | CalendarView (deprecated: Calendar, DayView) |
 | `@happyvertical/smrt-ui/data` | DataTable, CollectionList/ContentList, CollectionToolbar |
 | `@happyvertical/smrt-ui/feedback` | Modal, ConfirmDialog, LoadingOverlay, ProgressBar |
 | `@happyvertical/smrt-ui/chat` | Message bubble, reaction picker, typing indicator |

package/agents/workspace.md

@@ -45,6 +45,30 @@ App settings, tenant names and environment badges wrap within narrow drawers.
 system bars never clip wrapped chips. Custom bars must allow this flex child
 to shrink; use safe alignment if aligning its contents to the end.
 
+### Responsive chrome, viewport defaults, resizable edges
+
+The root grid has five rows: `header` · top edge · body · bottom edge · phone
+bottom bar. The header and phone-bar tracks are `0rem` unless their snippets
+render, so hosts that pass none of the new props get the original layout; keep
+that invariant (`AdminShell.responsive.test.ts` "backward compatibility").
+Phone drawers and the bottom drawer offset themselves by the header and phone
+bar tracks. `shell.viewport` comes from `ADMIN_SHELL_PHONE_QUERY` (48rem, the
+same boundary as the CSS media query — never make one configurable without the
+other) and `ADMIN_SHELL_DESKTOP_QUERY` (64rem); `installShellViewport` runs on
+mount and the `ShellState` constructor detects the initial class so the first
+paint is right.
+
+Edge config: `viewportDefaults` (applied per class change; such an edge never
+stores its state), `phone: 'drawer' | 'sheet' | 'hidden'` (`sheet` is right
+edge only), `resizable` (side edges, `push` only, not on phones) and `persist`.
+`stripUnpersistedSettings` runs on both `hydrate()` and adapter writes;
+runtime `applySettings` is never filtered. Resized widths live in
+`ShellSettingsDelta.sizes` (px; `null` = configured size, pruned on write).
+Drags update with `persist: false` and persist once on pointer up.
+
+The resize separator is a focusable `role="separator"`: its svelte-ignore of
+the non-interactive a11y warnings is deliberate (WAI-ARIA window splitter).
+
 Run `pnpm --filter @happyvertical/smrt-svelte test:e2e` after building the
 package dependencies. The package-local fixture exercises real Chromium bounds
 and touch input across mobile widths and desktop panel-state combinations.

package/dist/browser-ai/adapters/stt/browser-speech.d.ts

@@ -1,5 +1,14 @@
 import type { InitState, OnProgress } from '../../core/types.js';
 import type { BrowserSpeechSTTOptions, STTAdapter, STTCapabilities, STTOptions, STTResult } from './types.js';
+/**
+ * An error from the browser's speech recognition. `speechError` is the Web
+ * Speech error code (`network`, `not-allowed`, `service-not-allowed`,
+ * `no-speech`, `audio-capture`, `aborted`, `language-not-supported`, …).
+ */
+export type BrowserSpeechError = Error & {
+    speechError?: string;
+    speechMessage?: string;
+};
 /**
  * Browser Speech Recognition adapter
  */
@@ -9,6 +18,8 @@ export declare class BrowserSpeechSTTAdapter implements STTAdapter {
     private recognition;
     private options;
     private _isListening;
+    /** Set while our own `abort()` runs, so its `aborted` error is not reported. */
+    private aborting;
     private resultListeners;
     private errorListeners;
     private startListeners;

package/dist/browser-ai/adapters/stt/browser-speech.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser-speech.d.ts","sourceRoot":"","sources":["../../../../src/browser-ai/adapters/stt/browser-speech.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,KAAK,EACV,uBAAuB,EACvB,UAAU,EACV,eAAe,EACf,UAAU,EACV,SAAS,EACV,MAAM,YAAY,CAAC;AAWpB;;GAEG;AACH,qBAAa,uBAAwB,YAAW,UAAU;IACxD,QAAQ,CAAC,IAAI,EAAG,gBAAgB,CAAU;IAE1C,OAAO,CAAC,UAAU,CAA8B;IAChD,OAAO,CAAC,WAAW,CAAkC;IACrD,OAAO,CAAC,OAAO,CAA0B;IACzC,OAAO,CAAC,YAAY,CAAS;IAG7B,OAAO,CAAC,eAAe,CAA0C;IACjE,OAAO,CAAC,cAAc,CAAqC;IAC3D,OAAO,CAAC,cAAc,CAAyB;IAC/C,OAAO,CAAC,YAAY,CAAyB;gBAEjC,OAAO,GAAE,uBAA4B;IAQjD,IAAI,SAAS,IAAI,SAAS,CAEzB;IAEK,iBAAiB,CAAC,WAAW,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAqChE,OAAO,CAAC,wBAAwB;IAwEhC,eAAe,IAAI,eAAe;IA2B5B,KAAK,CAAC,OAAO,GAAE,UAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAqB9C,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAM3B,KAAK,IAAI,IAAI;IAMb,WAAW,IAAI,OAAO;IAItB,QAAQ,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,IAAI,GAAG,MAAM,IAAI;IAK3D,OAAO,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,MAAM,IAAI;IAKrD,OAAO,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAKzC,KAAK,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAKjC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAS/B"}
+{"version":3,"file":"browser-speech.d.ts","sourceRoot":"","sources":["../../../../src/browser-ai/adapters/stt/browser-speech.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,KAAK,EACV,uBAAuB,EACvB,UAAU,EACV,eAAe,EACf,UAAU,EACV,SAAS,EACV,MAAM,YAAY,CAAC;AAWpB;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,KAAK,GAAG;IACvC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF;;GAEG;AACH,qBAAa,uBAAwB,YAAW,UAAU;IACxD,QAAQ,CAAC,IAAI,EAAG,gBAAgB,CAAU;IAE1C,OAAO,CAAC,UAAU,CAA8B;IAChD,OAAO,CAAC,WAAW,CAAkC;IACrD,OAAO,CAAC,OAAO,CAA0B;IACzC,OAAO,CAAC,YAAY,CAAS;IAC7B,gFAAgF;IAChF,OAAO,CAAC,QAAQ,CAAS;IAGzB,OAAO,CAAC,eAAe,CAA0C;IACjE,OAAO,CAAC,cAAc,CAAqC;IAC3D,OAAO,CAAC,cAAc,CAAyB;IAC/C,OAAO,CAAC,YAAY,CAAyB;gBAEjC,OAAO,GAAE,uBAA4B;IAQjD,IAAI,SAAS,IAAI,SAAS,CAEzB;IAEK,iBAAiB,CAAC,WAAW,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAqChE,OAAO,CAAC,wBAAwB;IAqFhC,eAAe,IAAI,eAAe;IA2B5B,KAAK,CAAC,OAAO,GAAE,UAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAqB9C,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAM3B,KAAK,IAAI,IAAI;IAOb,WAAW,IAAI,OAAO;IAItB,QAAQ,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,IAAI,GAAG,MAAM,IAAI;IAK3D,OAAO,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,MAAM,IAAI;IAKrD,OAAO,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAKzC,KAAK,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAKjC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAS/B"}

package/dist/browser-ai/adapters/stt/browser-speech.js

@@ -23,6 +23,8 @@ export class BrowserSpeechSTTAdapter {
     recognition = null;
     options;
     _isListening = false;
+    /** Set while our own `abort()` runs, so its `aborted` error is not reported. */
+    aborting = false;
     // Event listeners
     resultListeners = new Set();
     errorListeners = new Set();
@@ -94,8 +96,13 @@ export class BrowserSpeechSTTAdapter {
             }
         };
         this.recognition.onerror = (event) => {
+            const code = event.error;
+            if (code === 'aborted' && this.aborting) {
+                // We called abort() ourselves: not an error.
+                return;
+            }
             let error;
-            switch (event.error) {
+            switch (code) {
                 case 'not-allowed':
                 case 'service-not-allowed':
                     error = new PermissionDeniedError('microphone', 'browser-speech');
@@ -110,11 +117,18 @@ export class BrowserSpeechSTTAdapter {
                     error = new Error('Network error during speech recognition');
                     break;
                 case 'aborted':
-                    // User aborted, not really an error
-                    return;
+                    // Not our abort(): the browser (or another tab) cut it off.
+                    error = new Error('Speech recognition was aborted');
+                    break;
                 default:
-                    error = new Error(`Speech recognition error: ${event.error}`);
+                    error = new Error(`Speech recognition error: ${code}`);
             }
+            // The Web Speech error code, so callers can tell `service-not-allowed`
+            // (the browser has no speech service, e.g. Brave) from `not-allowed`
+            // (the microphone is blocked), and `network` from everything else.
+            error.speechError = code;
+            if (event.message)
+                error.speechMessage = event.message;
             for (const cb of this.errorListeners) {
                 cb(error);
             }
@@ -127,6 +141,7 @@ export class BrowserSpeechSTTAdapter {
         };
         this.recognition.onend = () => {
             this._isListening = false;
+            this.aborting = false;
             for (const cb of this.endListeners) {
                 cb();
             }
@@ -181,6 +196,7 @@ export class BrowserSpeechSTTAdapter {
     }
     abort() {
         if (this.recognition && this._isListening) {
+            this.aborting = true;
             this.recognition.abort();
         }
     }

package/dist/browser-ai/adapters/stt/browser-speech.test.js

@@ -0,0 +1,113 @@
+/**
+ * BrowserSpeechSTTAdapter errors: every Web Speech error reaches `onError`
+ * with its code (`speechError`), including an `aborted` the adapter did not
+ * cause, and through smrt-ui's `Dictation` Brave's "starts, then `network`"
+ * becomes a plain error instead of a silent stop.
+ */
+import { Dictation } from '@happyvertical/smrt-ui/forms';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { BrowserSpeechSTTAdapter, } from './browser-speech.js';
+import { createSttDictationSource } from './dictation-source.js';
+class FakeRecognition {
+    static last = null;
+    /** What the browser does after start(): Brave errors with `network`. */
+    static afterStart = null;
+    lang = '';
+    continuous = false;
+    interimResults = false;
+    maxAlternatives = 1;
+    onresult = null;
+    onerror = null;
+    onstart = null;
+    onend = null;
+    constructor() {
+        FakeRecognition.last = this;
+    }
+    start = vi.fn(() => {
+        this.onstart?.();
+        FakeRecognition.afterStart?.(this);
+    });
+    stop = vi.fn(() => this.onend?.());
+    abort = vi.fn(() => {
+        this.onerror?.({ error: 'aborted', message: '' });
+        this.onend?.();
+    });
+    fail(code) {
+        this.onerror?.({ error: code, message: '' });
+        this.onend?.();
+    }
+}
+function install() {
+    window.webkitSpeechRecognition =
+        FakeRecognition;
+}
+afterEach(() => {
+    delete window
+        .webkitSpeechRecognition;
+    FakeRecognition.last = null;
+    FakeRecognition.afterStart = null;
+});
+describe('BrowserSpeechSTTAdapter errors', () => {
+    it.each([
+        'network',
+        'not-allowed',
+        'service-not-allowed',
+        'no-speech',
+        'audio-capture',
+        'aborted',
+        'language-not-supported',
+    ])('reports %s with its code', async (code) => {
+        install();
+        const adapter = new BrowserSpeechSTTAdapter();
+        const errors = [];
+        adapter.onError((error) => errors.push(error));
+        await adapter.start({ continuous: true });
+        FakeRecognition.last?.fail(code);
+        expect(errors).toHaveLength(1);
+        expect(errors[0].speechError).toBe(code);
+    });
+    it('does not report the abort it caused itself', async () => {
+        install();
+        const adapter = new BrowserSpeechSTTAdapter();
+        const onError = vi.fn();
+        adapter.onError(onError);
+        await adapter.start();
+        adapter.abort();
+        expect(onError).not.toHaveBeenCalled();
+    });
+});
+describe('Dictation over the browser adapter', () => {
+    it("Brave: it beeps, then 'network' — shown as unavailable, not a silent stop", async () => {
+        install();
+        FakeRecognition.afterStart = (r) => queueMicrotask(() => r.fail('network'));
+        const log = vi.fn();
+        const beep = vi.fn(async () => true);
+        const dictation = new Dictation({
+            source: createSttDictationSource(),
+            onText: () => { },
+            beep,
+            log,
+            requestMicrophone: false,
+        });
+        await dictation.start();
+        await vi.waitFor(() => expect(dictation.state).toBe('error'));
+        expect(beep).toHaveBeenCalled();
+        expect(dictation.errorKind).toBe('unsupported');
+        expect(dictation.errorCode).toBe('network');
+        expect(log).toHaveBeenCalledWith(expect.objectContaining({ kind: 'unsupported', code: 'network' }));
+    });
+    it('an end straight after starting with no error is a failure too', async () => {
+        install();
+        FakeRecognition.afterStart = (r) => queueMicrotask(() => r.onend?.());
+        const dictation = new Dictation({
+            source: createSttDictationSource(),
+            onText: () => { },
+            beep: false,
+            log: () => { },
+            requestMicrophone: false,
+        });
+        await dictation.start();
+        await vi.waitFor(() => expect(dictation.state).toBe('error'));
+        expect(dictation.errorKind).toBe('interrupted');
+    });
+});

package/dist/browser-ai/adapters/stt/dictation-source.d.ts

@@ -0,0 +1,3 @@
+import type { GetSTTOptions, STTAdapter } from './types.js';
+export declare function createSttDictationSource(options?: GetSTTOptions): () => Promise<STTAdapter>;
+//# sourceMappingURL=dictation-source.d.ts.map

package/dist/browser-ai/adapters/stt/dictation-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dictation-source.d.ts","sourceRoot":"","sources":["../../../../src/browser-ai/adapters/stt/dictation-source.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE5D,wBAAgB,wBAAwB,CACtC,OAAO,GAAE,aAA0C,GAClD,MAAM,OAAO,CAAC,UAAU,CAAC,CAc3B"}

package/dist/browser-ai/adapters/stt/dictation-source.js

@@ -0,0 +1,38 @@
+/**
+ * A speech source for smrt-ui's `Dictation` (the microphone button and
+ * "press and hold a field to speak" in `@happyvertical/smrt-ui/forms`).
+ *
+ * `STTAdapter` already has the shape `Dictation` needs (`start`, `stop`,
+ * `onResult`, `onError`, `onStart`, `onEnd`), so this only creates the
+ * adapter lazily, once, the first time someone starts dictating: nothing
+ * loads and no microphone prompt appears until then. Defaults to the
+ * browser's own speech recognition (`browser-speech`), which needs no
+ * download; an unsupported browser rejects with
+ * `CapabilityNotAvailableError`, which `Dictation` reports in plain words.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { createSttDictationSource } from '@happyvertical/smrt-svelte/browser-ai';
+ *   import { Dictation, DictationButton } from '@happyvertical/smrt-ui/forms';
+ *   const dictation = new Dictation({ source: createSttDictationSource(), onText: (t) => … });
+ * </script>
+ * <DictationButton {dictation} />
+ * ```
+ */
+import { getSTT } from './factory.js';
+export function createSttDictationSource(options = { type: 'browser-speech' }) {
+    let adapter = null;
+    return () => {
+        adapter ??= (async () => {
+            const created = await getSTT(options);
+            await created.ensureInitialized();
+            return created;
+        })().catch((error) => {
+            // Let a later tap try again (for example after a permission change).
+            adapter = null;
+            throw error;
+        });
+        return adapter;
+    };
+}

package/dist/browser-ai/adapters/stt/dictation-source.test.js

@@ -0,0 +1,52 @@
+/**
+ * createSttDictationSource: the browser speech adapter, created once and
+ * lazily, and rejected plainly where the browser has no speech recognition.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { createSttDictationSource } from './dictation-source.js';
+class FakeRecognition {
+    lang = '';
+    continuous = false;
+    interimResults = false;
+    maxAlternatives = 1;
+    onresult = null;
+    onerror = null;
+    onstart = null;
+    onend = null;
+    start = vi.fn(() => this.onstart?.());
+    stop = vi.fn(() => this.onend?.());
+    abort = vi.fn();
+}
+describe('createSttDictationSource', () => {
+    afterEach(() => {
+        delete window.SpeechRecognition;
+        delete window
+            .webkitSpeechRecognition;
+    });
+    it('creates one browser speech adapter, on first use', async () => {
+        window.webkitSpeechRecognition =
+            FakeRecognition;
+        const provide = createSttDictationSource();
+        const first = await provide();
+        const second = await provide();
+        expect(first).toBe(second);
+        expect(first.type).toBe('browser-speech');
+        const onStart = vi.fn();
+        first.onStart(onStart);
+        await first.start({
+            language: 'en-CA',
+            continuous: true,
+            interimResults: true,
+        });
+        expect(onStart).toHaveBeenCalled();
+    });
+    it('rejects with CapabilityNotAvailableError without speech recognition, then can retry', async () => {
+        const provide = createSttDictationSource();
+        await expect(provide()).rejects.toMatchObject({
+            name: 'CapabilityNotAvailableError',
+        });
+        window.SpeechRecognition =
+            FakeRecognition;
+        await expect(provide()).resolves.toBeTruthy();
+    });
+});

package/dist/browser-ai/adapters/stt/index.d.ts

@@ -1,7 +1,8 @@
 /**
  * Speech-to-Text adapters
  */
-export { BrowserSpeechSTTAdapter } from './browser-speech.js';
+export { type BrowserSpeechError, BrowserSpeechSTTAdapter, } from './browser-speech.js';
+export { createSttDictationSource } from './dictation-source.js';
 export * from './factory.js';
 export * from './types.js';
 export { WhisperCppSTTAdapter } from './whisper-cpp.js';

package/dist/browser-ai/adapters/stt/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/browser-ai/adapters/stt/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/browser-ai/adapters/stt/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,KAAK,kBAAkB,EACvB,uBAAuB,GACxB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AACjE,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/browser-ai/adapters/stt/index.js

@@ -1,7 +1,8 @@
 /**
  * Speech-to-Text adapters
  */
-export { BrowserSpeechSTTAdapter } from './browser-speech.js';
+export { BrowserSpeechSTTAdapter, } from './browser-speech.js';
+export { createSttDictationSource } from './dictation-source.js';
 export * from './factory.js';
 export * from './types.js';
 export { WhisperCppSTTAdapter } from './whisper-cpp.js';