@happyvertical/smrt-svelte 0.55.7 → 0.55.9

package/agents/overview-surfaces.md

@@ -0,0 +1,255 @@
+# smrt-svelte/overview
+
+Module semantics for `src/components/overview/` (`./overview` and
+`./overview/server`, #3727). Package orientation and cross-module invariants are
+in [../AGENTS.md](../AGENTS.md); the shell edit mode it joins is in
+[workspace.md](workspace.md#editing-the-layout-in-place).
+
+An overview is a **customizable surface**: a flow grid of registered widgets,
+each with an options object. A page declares which widget types it allows and
+its default arrangement; admins (or users, per role) add, reorder, resize,
+configure and remove widgets inside that confined set, and reset returns to the
+default. Phase 1 (this module) is the surface, the registry, the data model, the
+server load contract and five core widgets; phase 2 adds package widgets from
+recipes ("Recipe widgets"). Persistence and assistant operations are later
+phases (see "Extension points").
+
+## Two entries
+
+| Entry | Contents |
+|---|---|
+| `./overview/server` (`server.ts`) | Svelte-free: types, `validateWidgetOptions`, the model (`resolveOverview`, `checkOverviewOverride`, `applyOverviewOverride`, `diffOverview`, `sanitizeOverview`, ...), `WidgetRegistry` / `registerWidget`, `loadOverview`. Safe in a `+page.server.ts` or a save endpoint. |
+| `./overview` (`index.ts`) | Everything above plus `OverviewGrid`, `createOverview` (controller), `WidgetOptionsForm`, the core widgets and `registerCoreWidgets`, `shortcutsFromNav`, `formatWidgetValue`, `parseMarkdown` / `safeHref`. |
+
+## Data model (`types.ts`, `model.ts`)
+
+A saved overview is data, never code:
+`{ widgets: [{ id, type, span, options, version? }] }`. `span` is 1 to 4 (a widget
+type may narrow its own range); `options` is a flat object of JSON primitives;
+`version` is the widget's option-schema version the options were written
+against (absent means 1).
+
+- **`OverviewDefinition`** (what a page declares): `id` (dotted ids allowed,
+  `events.home`), `defaults`, `allowed` (widget types; omit for every registered
+  type), `models` (confines `model` options, including a substituted default: a
+  default outside the list fails validation, so its loader never runs),
+  `maxWidgets` (default 24).
+  `defineOverview` validates ids.
+- **`OverviewOverride`** is the sparse, versioned (`version: 1`) delta a host
+  stores: `order`, `removed`, `added`, `changed[id] = { span?, options?, version? }`.
+  `applyOverviewOverride(base, override)` is total: ids the base no longer has
+  are ignored, an added widget colliding with a base id is skipped, and widgets
+  the order does not list keep their slots (a default shipped later still
+  appears). `diffOverview(base, next)` is its inverse (round-trip tested), so
+  every client edit is "mutate the document, store the diff"; an edit that
+  returns to the defaults stores `null`.
+- **Ids are stable.** `nextWidgetId` yields `w<n>` and reserves the ids of
+  removed defaults, so a new widget never takes a removed default's id (the
+  override would delete it). It is total for any stored ids: numeric suffixes
+  beyond `Number.MAX_SAFE_INTEGER` are ignored when picking the next number
+  (they would stop incrementing), and an exhausted high end restarts at `w1`.
+- **Tiers.** `resolveOverview` merges one override. A host with tenant defaults
+  and user overrides merges the tenant tier into the definition's `defaults`
+  first (phase 3); the user override then applies to that.
+- **Reset** is `controller.reset()` (store `null`) or `resetWidget(id)`.
+
+## Validation: what keeps a stored overview from running anything
+
+Options are validated against the widget's versioned schema on **save**
+(`checkOverviewOverride`, strict: any issue rejects, and the returned override is
+re-derived from the sanitized result, so persist that) and on **load**
+(`sanitizeOverview`, lenient: the bad widget is dropped and reported as an
+`OverviewIssue`, the rest render). Nothing here calls a widget's `load` for a
+widget that failed validation.
+
+- `schema.ts` field types: `text`, `markdown`, `identifier`, `model`, `integer`,
+  `number`, `boolean`, `enum`. There is **no free-form query, filter expression,
+  URL or SQL field**. "Which data" is a `model` (a bare `Class`, `pkg:Class` or
+  `@scope/pkg:Class`, optionally confined to the page's `models`), an
+  `identifier` (a field or named-filter id, `[A-Za-z_][A-Za-z0-9_.-]{0,63}`) or a
+  closed `enum`. The loader maps those to queries it owns and authorizes.
+- Strict: unknown keys, wrong types, out-of-range numbers, values outside a closed
+  set and missing required fields fail the whole options object. Missing optional
+  fields take their default; `null` counts as missing.
+- `sanitizeOverview` also drops: unknown types, types outside the page's
+  `allowed` set or a widget's `allowedIn`, duplicate ids, widgets over the cap,
+  newer-than-known versions, and older versions without a working `migrate`.
+  Spans are clamped to the widget's range. It is idempotent.
+- `migrate(options, fromVersion)` upgrades stored options to the current version
+  (return `null` to drop). It runs on untrusted input inside a try/catch, and its
+  result is validated like any other options.
+- A widget id removed by the user and a type removed by a release both degrade to
+  "dropped and reported", never an error page.
+
+## Registry (`registry.ts`)
+
+`registerWidget({ type, title, options, component | loadComponent, load, allowedIn,
+version, migrate, defaultSpan, minSpan, maxSpan })` on the shared
+`defaultWidgetRegistry`, or `createWidgetRegistry()` for an isolated one (tests,
+several surfaces). Registration is code, at module scope; registering a type
+twice throws unless `{ replace: true }`. `title`, `description` and option
+`label` / `help` / `choices[].label` are text **or i18n keys** (the UI runs them
+through `t`, which returns an unregistered string unchanged); the core widgets
+use `ui.overview.*` keys from `i18n/strings.overview.ts` (registered in
+`i18n/server.ts`).
+
+`component` renders synchronously. `loadComponent` is the lazy form (dynamic import
+by export ref): resolve it **before** render with `resolveWidgetComponents(types)`
+in a universal load and pass the map to `OverviewGrid components`, so server and
+client render the same tree. A type that cannot resolve renders as unavailable.
+
+## Server load contract (`load.ts`)
+
+```ts
+// +page.server.ts
+const resolved = resolveOverview(definition, await storedOverride(event), registry);
+const overview = await loadOverview(resolved.document, definition, registry, {
+  locale, tenantId, db /* the request's permission-checked capabilities */,
+});
+return { overview };   // LoadedOverview: JSON, serializable
+```
+
+- A widget's `load(options, ctx)` receives **validated options only** and a
+  `WidgetLoadContext` the host built from the request principal: `overviewId`, an
+  abort `signal`, `locale`, and any host capabilities (index keys). It must
+  authorize through `ctx` (the user's permissions and tenant filters), never
+  through option values. Reports-backed chart loaders call the runtime-report
+  compiler with this context; this package does not depend on it.
+- Loads run in parallel with a per-widget timeout (default 8 s; the signal
+  aborts). A thrown error, a timeout or non-serializable / oversized data
+  (default 256 KB of JSON) becomes a per-widget error tile
+  (`error.code`: `load_failed | timeout | invalid_data`); the real error goes only
+  to `onError` for server logs, never to the client. One bad widget never fails
+  the page.
+- `LoadedOverview` is what the page returns and `createOverview({ loaded })` seeds
+  the controller from, so the grid renders every widget at first paint with no
+  client-only fetching and **no hydration mismatch** (the grid has no
+  effect-dependent content; the only `$effect` requests data for widgets the
+  seeded entries do not cover, which never happens on first render).
+  `scripts/overview-ssr.test.mjs` renders the grid through Vite SSR.
+- Formatting is deterministic per locale (`Intl` with the i18n store's locale), and
+  no widget formats dates or reads the clock; loaders send preformatted meta.
+
+## Controller (`controller.svelte.ts`)
+
+`createOverview({ definition, registry?, override?, onchange?, canCustomize?,
+loaded?, loadWidget? })`, the `ShellLayout` pattern: **persistence is host-owned**.
+With an `override` getter the host is the source of truth and feeds each edit back
+(`onchange(override | null)`); without it the value is kept in memory. Reactive
+reads: `document`, `base`, `override`, `issues`, `customized`, `canCustomize`,
+`addable`, `full`, `entry(widget)`. Operations, each returning
+`{ ok: true, id } | { ok: false, reason, issues? }` and refused with
+`not_allowed` when `canCustomize()` is false (the role gate; the server must check
+the same on save): `add(type, options?)`, `remove`, `move(id, toIndex)` (index
+after removal), `resize(id, span)`, `setOptions`, `resetWidget`, `reset`,
+`restore(override)` (the Undo hook), `reload(id)`.
+
+`loadWidget(widget, signal)` is how a client edit gets data for an added or
+reconfigured widget: the host runs the widget's `load` where its data lives (a
+remote function in production, the in-browser source in smrt-planner). The
+controller drops results for stale option keys and aborts superseded loads.
+Call `destroy()` when the owner unmounts.
+
+## Grid and edit mode (`OverviewGrid.svelte`)
+
+Props in `grid-types.ts`. `editing` defaults to the shell's layout editor
+(`tryUseShellLayout()?.editing`), so the same pencil edits the grid under an
+`AppShell` with `layoutEditing`; pass `editing` to drive it without a shell. It is
+off whenever `controller.canCustomize` is false.
+
+- **Flow grid.** CSS grid of 4 columns, 2 below 40rem and 1 below 22rem of the
+  grid's own width (container queries); `data-span` / `--span` carry the span. Gaps
+  are tile padding, not grid gap, so a drag never crosses a dead zone.
+- **Reorder** uses the headless `createSortable` engine in its `flow` mode (a
+  single wrapping list): the handle is the existing grip (Space picks up, any
+  arrow steps along reading order, mirrored in RTL, Enter drops, Escape cancels;
+  pointer and native drag use the horizontal midpoint for tiles sharing a row).
+- **Resize** is an end-edge `role="slider"` (arrows, Home, End; pointer drag snaps
+  to a column boundary via the pure `spanFromPointer`, committed on release).
+- **Chrome** is icon-only `ShellIconButton`s (configure, remove) plus the toolbar
+  (add, reset). Widgets render as on the site inside an `inert` wrapper. Add and
+  configure open `Modal`s; `WidgetOptionsForm` is generated from the option field
+  descriptors with smrt-ui `Form` / `FormGroup` / `Input` / `Select` / `Textarea` /
+  `Checkbox` (the descriptors mirror the generated screens' field shape) and shows
+  each schema issue beside its field. A widget with a required option and no
+  default opens the form before it is added.
+- A polite live region announces moves, resizes, adds, removals and resets.
+  `OverviewGrid.test.ts` runs axe in view and edit mode.
+
+## Core widgets (`widgets/`)
+
+`registerCoreWidgets(registry, loaders)` registers `note` always and each
+data-backed widget only when its loader is given (structural injection: this
+package depends on no data package). Widgets render only when the grid has
+`ready` data (it draws loading and error tiles) and treat `data` as untrusted
+shape. Data shapes are in `widgets/data.ts`.
+
+| Type | Options | Data |
+|---|---|---|
+| `metric` | `title`, `model`*, `measure`, `field`, `filter` | `{ value, format?, currency?, label?, change?, href? }` (money = integer minor units) |
+| `chart` | `title`, `model`*, `groupBy`, `measure`, `field`, `period`, `style` (bar/line), `filter` | `{ points: [{ label, value }], format?, currency?, href? }`, one measure of a runtime report |
+| `records` | `title`, `model`*, `sort`, `direction`, `limit`, `filter` | `{ rows: [{ id, title, subtitle?, meta?, href? }], total?, href? }`; the loader chooses the title field and the visible records |
+| `shortcuts` | `title`, `section` | `{ items: [{ id, label, href, icon?, description? }] }`; `shortcutsFromNav(sections, sectionId)` maps `resolveShellNavModel` / `useShellLayout().sections` (visible entries, user renames) |
+| `note` | `title`, `body` (Markdown) | none |
+
+`note` renders `parseMarkdown` output as elements (headings, paragraphs, lists,
+quotes, fenced code, bold/italic/code/links). There is no `{@html}`; raw HTML is
+literal text and `safeHref` limits links to http(s), mailto, same-site paths and
+fragments. Record and shortcut hrefs pass `safeHref` too. Charts carry their
+numbers as text (inline for bars, a visually hidden table for the line).
+
+## Recipe widgets (`recipe-widgets.ts`)
+
+A package contributes a widget with a `widget` surface on a recipe
+([core recipes.md](../../core/agents/recipes.md#widget-surfaces-3727) has the
+declaration and its scan-time rules). `registerRecipeWidgets(registry, recipes,
+resolveExport, { replace?, enabled? })` (async, Svelte-free, on both entries)
+turns the manifest's widget surfaces into `registry.register(...)` calls:
+
+| Surface field | Registration |
+|---|---|
+| `type`, `label`, `description`, `icon`, `version` | `type`, `title`, `description`, `icon`, `version` |
+| `options` | `options` (plain JSON; `registry.register` re-validates the schema) |
+| `export` | `loadComponent` (lazy; the export may be a component or a `{ default }` module) |
+| `data.load` | `load` (resolved on first use; a missing or non-function loader is that widget's error tile) |
+| `migrate` | `migrate`, **resolved eagerly** because the registry's `migrate` is synchronous |
+| `allowedIn`, `defaultSpan`, `minSpan`, `maxSpan` | same names |
+| `data.models` | not registered: documentation of what the loader reads; confine with the page's `models` |
+
+- **The module resolver is injected.** `resolveExport(specifier, exportName)` is
+  the host's: a static map of dynamic imports in a bundled app, a stub in tests.
+  Nothing is imported when the manifest is read, and the registration itself
+  imports nothing except `migrate` exports. Relative or absolute specifiers
+  are refused.
+- **Never throws for a bad surface.** The result is `{ registered, skipped,
+  dispose }`; a skip carries `reason` `duplicate_type` (a core widget or another
+  recipe owns the type; `replace` overrides), `invalid` (the registry refused the
+  definition) or `unresolved` (a `migrate` export is missing). One broken package
+  cannot take down the overview.
+- **`enabled(recipeId)`** keeps widgets of recipes that are off out of the add
+  list. Call the helper again (after `dispose()`) when the set changes.
+- Widget types share one registry namespace with the core widgets
+  (`metric`, `chart`, `records`, `shortcuts`, `note`). Pages still confine what
+  can appear with `defineOverview({ allowed })`, and a widget with `allowedIn`
+  only validates inside those overview ids.
+- `src/components/overview/__tests__/recipe-widgets.test.ts` covers lazy
+  resolution, the loader and migrate paths, allowed placements and the skip
+  reasons. The scanner's copy of the option vocabulary and patterns is checked
+  against `types.ts` / `schema.ts` by `packages/scanner/src/__tests__/recipe-widgets.test.ts`,
+  and a type-level assertion here keeps `RecipeWidgetOptionType` equal to
+  `WidgetOptionType`.
+
+## Extension points left for later phases
+
+- **Phase 2, package widgets (#3727, done).** See "Recipe widgets" below.
+- **Phase 3, production persistence.** Implement the `override` getter /
+  `onchange` pair against the `_smrt_` table (tenant tier merged into
+  `definition.defaults`, user tier as the override), validate saves with
+  `checkOverviewOverride` and persist its canonical `override`, run
+  `loadOverview` in the page load, and supply `loadWidget` as a remote function
+  that calls the same `load`. Role gating = `canCustomize` plus the same check in
+  the save endpoint. No migration or table lives in this package.
+- **Phase 4, assistant.** The controller methods are the structured operations;
+  `restore(override)` plus the `override` getter give Undo (snapshot before,
+  restore after). `OverviewOpResult.issues` is the validation feedback to return.
+- **Not built:** the activity widget (Track B, #3710) and agenda.

package/agents/screens.md

@@ -0,0 +1,57 @@
+# smrt-svelte/screens
+
+Module semantics for `src/components/screens/` (`./screens`). Package orientation, the cross-module
+invariants, and the traps that apply before editing anything live in
+[../AGENTS.md](../AGENTS.md) — read that first.
+
+## Manifest-derived record screens (`./screens`, #3718)
+
+`RecipeScreens` is the default screen set for a package that ships models but no
+consumer UI (tags, facts, secrets, profiles, reports, prompts). It composes
+`ListScreen`, `DetailScreen` and `EditForm`, each of which can also be used on
+its own. Every screen takes a generated web `definition`
+(`ScreenCollectionDefinition`, structurally a `SmrtWebCollectionDefinition`) and
+an optional resolved `policy` (`ScreenPolicy`, structurally smrt-fields'
+`ResolvedObjectFieldPolicy`). The module imports neither package: smrt-svelte
+stays below the domain layer, and the app passes both in as props.
+
+- **Field selection is `fields.ts`, pure and node-testable.** `deriveScreenFields`
+  is the single rule for list / view / edit. A field renders only when it is in
+  BOTH the definition and the policy, so sensitive, transient and
+  read-permission-gated fields (which the policy resolver omits) can never appear
+  on a generated screen. Hidden fields are dropped; system fields (`id`,
+  `tenantId`, `createdBy`, `updatedBy`, `createdAt`, `updatedAt`) are never
+  editable, and the two timestamps appear on a view as read-only advanced meta.
+  Do not add a second selection rule in a component.
+- **Without a policy the code seed applies**: `ui.basic` / `ui.group` / `ui.order`
+  hints and the cold-start rule (no `basic` markers => everything basic; any
+  marker => unmarked fields advanced). Order is `order`, then declaration order.
+- **Tiers**: list shows basic scalar columns only (no long text, JSON or raw
+  reference columns; capped at `DEFAULT_MAX_LIST_COLUMNS`, an explicit `columns`
+  list is never capped); view and edit show advanced fields behind a disclosure
+  (the edit one opens itself when an advanced field has a problem). Policy
+  `label`, `help` and `required` win over the manifest; on create, a resolved
+  policy default (an explicit `null` included) beats the manifest default.
+  `locked` governs who may change the POLICY, never the record value, so it is
+  not applied here.
+- **Values are `values.ts`**: money (`ui.widget: 'currency'` on an INTEGER field
+  only) is integer minor units end to end. Editing shows major units but converts
+  with exact string math (`majorStringToMinorUnits`), never `* 100`; integers are
+  rejected unless JavaScript-safe; datetimes go out as ISO strings (an unchanged datetime keeps the
+  loaded record's full precision via `parseDraft`'s `record` context; the control
+  only shows minutes); JSON as parsed values. Empty optional text becomes `null` when the field is nullable and `''`
+  otherwise (unset text persists as `''`); every other empty optional field is
+  `null`. Errors are codes, mapped to messages by the component via `useI18n`.
+- **Transport-neutral.** `RecipeScreens` drives a `RecipeScreensSource`
+  (`list` / `get` / `create` / `update` / `delete`); an operation the source lacks
+  (or `can` turns off) is simply not offered, so a read-only source is a
+  read-only screen set. `view` and `recordId` are bindable and `onnavigate`
+  fires on every user navigation, so an app can mirror them into its router.
+  `EditForm.onsubmit` throws to report a failed save or returns `{ fieldErrors }`.
+  Remount `EditForm` with `{#key}` when switching records (`RecipeScreens` does).
+- **Not the policy-editing surface.** The policy gear, field-usage telemetry and
+  the per-field renderer registry live in `ObjectForm`
+  (`@happyvertical/smrt-fields/svelte`); `EditForm` is the dependency-light
+  default and does not replace it. Not wired into recipe surfaces yet (#3708).
+- Component props live in `types.ts`, not in the `.svelte` files, so the barrel
+  never re-exports types from a component.

package/dist/browser-ai/adapters/tts/browser-synthesis.d.ts

@@ -16,6 +16,11 @@ export declare class BrowserSynthesisTTSAdapter implements TTSAdapter {
     private options;
     private voices;
     private currentUtterance;
+    private operationGeneration;
+    private initializationGeneration;
+    private initialization;
+    private cancelVoiceLoad;
+    private settleCurrentSpeech;
     private startListeners;
     private endListeners;
     private errorListeners;

package/dist/browser-ai/adapters/tts/browser-synthesis.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser-synthesis.d.ts","sourceRoot":"","sources":["../../../../src/browser-ai/adapters/tts/browser-synthesis.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,KAAK,EACV,0BAA0B,EAC1B,UAAU,EACV,eAAe,EACf,UAAU,EACV,QAAQ,EACT,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,qBAAa,0BAA2B,YAAW,UAAU;IAC3D,QAAQ,CAAC,IAAI,EAAG,mBAAmB,CAAU;IAE7C,OAAO,CAAC,UAAU,CAA8B;IAChD,OAAO,CAAC,SAAS,CAAgC;IACjD,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,MAAM,CAA8B;IAE5C,OAAO,CAAC,gBAAgB,CAAyC;IAGjE,OAAO,CAAC,cAAc,CAAyB;IAC/C,OAAO,CAAC,YAAY,CAAyB;IAC7C,OAAO,CAAC,cAAc,CAAqC;IAC3D,OAAO,CAAC,iBAAiB,CAErB;gBAEQ,OAAO,GAAE,0BAA+B;IAUpD,IAAI,SAAS,IAAI,SAAS,CAEzB;IAEK,iBAAiB,CAAC,WAAW,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;YAqClD,UAAU;IA+BxB,eAAe,IAAI,eAAe;IAUlC,SAAS,IAAI,QAAQ,EAAE;IAUvB,OAAO,CAAC,SAAS;IAkCX,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,UAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAiElE,IAAI,IAAI,IAAI;IAOZ,KAAK,IAAI,IAAI;IAMb,MAAM,IAAI,IAAI;IAMd,UAAU,IAAI,OAAO;IAIrB,QAAQ,IAAI,OAAO;IAInB,OAAO,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAKzC,KAAK,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAKvC,OAAO,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,MAAM,IAAI;IAKrD,UAAU,CACR,QAAQ,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,IAAI,GACxD,MAAM,IAAI;IAKP,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAU/B"}
+{"version":3,"file":"browser-synthesis.d.ts","sourceRoot":"","sources":["../../../../src/browser-ai/adapters/tts/browser-synthesis.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,KAAK,EACV,0BAA0B,EAC1B,UAAU,EACV,eAAe,EACf,UAAU,EACV,QAAQ,EACT,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,qBAAa,0BAA2B,YAAW,UAAU;IAC3D,QAAQ,CAAC,IAAI,EAAG,mBAAmB,CAAU;IAE7C,OAAO,CAAC,UAAU,CAA8B;IAChD,OAAO,CAAC,SAAS,CAAgC;IACjD,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,MAAM,CAA8B;IAC5C,OAAO,CAAC,gBAAgB,CAAyC;IACjE,OAAO,CAAC,mBAAmB,CAAK;IAChC,OAAO,CAAC,wBAAwB,CAAK;IACrC,OAAO,CAAC,cAAc,CAA8B;IACpD,OAAO,CAAC,eAAe,CAA6B;IACpD,OAAO,CAAC,mBAAmB,CAA6B;IAGxD,OAAO,CAAC,cAAc,CAAyB;IAC/C,OAAO,CAAC,YAAY,CAAyB;IAC7C,OAAO,CAAC,cAAc,CAAqC;IAC3D,OAAO,CAAC,iBAAiB,CAErB;gBAEQ,OAAO,GAAE,0BAA+B;IAUpD,IAAI,SAAS,IAAI,SAAS,CAEzB;IAEK,iBAAiB,CAAC,WAAW,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;YAmClD,UAAU;IAwBxB,eAAe,IAAI,eAAe;IAUlC,SAAS,IAAI,QAAQ,EAAE;IAUvB,OAAO,CAAC,SAAS;IAkCX,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,UAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAgFlE,IAAI,IAAI,IAAI;IAOZ,KAAK,IAAI,IAAI;IAMb,MAAM,IAAI,IAAI;IAMd,UAAU,IAAI,OAAO;IAIrB,QAAQ,IAAI,OAAO;IAInB,OAAO,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAKzC,KAAK,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAKvC,OAAO,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,MAAM,IAAI;IAKrD,UAAU,CACR,QAAQ,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,IAAI,GACxD,MAAM,IAAI;IAKP,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAa/B"}

package/dist/browser-ai/adapters/tts/browser-synthesis.js

@@ -14,8 +14,12 @@ export class BrowserSynthesisTTSAdapter {
     synthesis = null;
     options;
     voices = [];
-    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: Used in speak/stop/pause
     currentUtterance = null;
+    operationGeneration = 0;
+    initializationGeneration = 0;
+    initialization = null;
+    cancelVoiceLoad = null;
+    settleCurrentSpeech = null;
     // Event listeners
     startListeners = new Set();
     endListeners = new Set();
@@ -36,58 +40,60 @@ export class BrowserSynthesisTTSAdapter {
     async ensureInitialized(_onProgress) {
         if (this._initState === 'ready')
             return;
-        if (this._initState === 'initializing') {
-            // Wait for existing initialization
-            return new Promise((resolve, reject) => {
-                const check = () => {
-                    if (this._initState === 'ready')
-                        resolve();
-                    else if (this._initState === 'error')
-                        reject(new Error('Initialization failed'));
-                    else
-                        setTimeout(check, 50);
-                };
-                check();
-            });
-        }
+        if (this.initialization)
+            return this.initialization;
+        const generation = this.initializationGeneration;
         this._initState = 'initializing';
-        try {
-            if (typeof window === 'undefined' || !window.speechSynthesis) {
-                throw new CapabilityNotAvailableError('Web Speech Synthesis API', 'browser-synthesis');
+        const initialization = (async () => {
+            try {
+                if (typeof window === 'undefined' || !window.speechSynthesis) {
+                    throw new CapabilityNotAvailableError('Web Speech Synthesis API', 'browser-synthesis');
+                }
+                this.synthesis = window.speechSynthesis;
+                await this.loadVoices(this.synthesis);
+                if (generation === this.initializationGeneration) {
+                    this._initState = 'ready';
+                }
+            }
+            catch (error) {
+                if (generation === this.initializationGeneration) {
+                    this._initState = 'error';
+                }
+                throw error;
             }
-            this.synthesis = window.speechSynthesis;
-            // Load voices - they may load asynchronously
-            await this.loadVoices();
-            this._initState = 'ready';
+        })();
+        this.initialization = initialization;
+        try {
+            await initialization;
         }
-        catch (error) {
-            this._initState = 'error';
-            throw error;
+        finally {
+            if (this.initialization === initialization)
+                this.initialization = null;
         }
     }
-    async loadVoices() {
-        if (!this.synthesis)
+    async loadVoices(synthesis) {
+        this.voices = synthesis.getVoices();
+        if (this.voices.length > 0)
             return;
-        // Get voices - may be empty initially in some browsers
-        this.voices = this.synthesis.getVoices();
-        if (this.voices.length === 0) {
-            // Wait for voices to load
-            await new Promise((resolve) => {
-                const handleVoicesChanged = () => {
-                    this.voices = this.synthesis?.getVoices() ?? [];
-                    if (this.voices.length > 0) {
-                        this.synthesis?.removeEventListener('voiceschanged', handleVoicesChanged);
-                        resolve();
-                    }
-                };
-                this.synthesis?.addEventListener('voiceschanged', handleVoicesChanged);
-                // Timeout after 2 seconds - some browsers may not fire the event
-                setTimeout(() => {
-                    this.voices = this.synthesis?.getVoices() ?? [];
-                    resolve();
-                }, 2000);
-            });
-        }
+        await new Promise((resolve) => {
+            const finish = () => {
+                clearTimeout(timeout);
+                synthesis.removeEventListener('voiceschanged', handleVoicesChanged);
+                this.cancelVoiceLoad = null;
+                resolve();
+            };
+            const handleVoicesChanged = () => {
+                this.voices = synthesis.getVoices();
+                if (this.voices.length > 0)
+                    finish();
+            };
+            const timeout = setTimeout(() => {
+                this.voices = synthesis.getVoices();
+                finish();
+            }, 2000);
+            this.cancelVoiceLoad = finish;
+            synthesis.addEventListener('voiceschanged', handleVoicesChanged);
+        });
     }
     getCapabilities() {
         return {
@@ -133,12 +139,15 @@ export class BrowserSynthesisTTSAdapter {
         return this.voices.find((v) => v.default) || this.voices[0];
     }
     async speak(text, options = {}) {
+        // Invalidate previous requests before the asynchronous voices wait.
+        this.stop();
+        const generation = this.operationGeneration;
         await this.ensureInitialized();
+        if (generation !== this.operationGeneration)
+            return;
         if (!this.synthesis) {
             throw new Error('Synthesis not initialized');
         }
-        // Cancel any current speech
-        this.stop();
         return new Promise((resolve, reject) => {
             const utterance = new SpeechSynthesisUtterance(text);
             // Set voice
@@ -154,21 +163,34 @@ export class BrowserSynthesisTTSAdapter {
             utterance.rate = options.rate ?? this.options.defaultRate ?? 1;
             utterance.pitch = options.pitch ?? this.options.defaultPitch ?? 1;
             utterance.volume = options.volume ?? this.options.defaultVolume ?? 1;
+            const isCurrent = () => generation === this.operationGeneration &&
+                this.currentUtterance === utterance;
+            const settle = () => {
+                this.currentUtterance = null;
+                this.settleCurrentSpeech = null;
+                resolve();
+            };
             // Set up event handlers
             utterance.onstart = () => {
+                if (!isCurrent())
+                    return;
                 for (const cb of this.startListeners) {
                     cb();
                 }
             };
             utterance.onend = () => {
-                this.currentUtterance = null;
+                if (!isCurrent())
+                    return;
+                settle();
                 for (const cb of this.endListeners) {
                     cb();
                 }
-                resolve();
             };
             utterance.onerror = (event) => {
+                if (!isCurrent())
+                    return;
                 this.currentUtterance = null;
+                this.settleCurrentSpeech = null;
                 const error = new Error(`Speech synthesis error: ${event.error}`);
                 for (const cb of this.errorListeners) {
                     cb(error);
@@ -176,19 +198,22 @@ export class BrowserSynthesisTTSAdapter {
                 reject(error);
             };
             utterance.onboundary = (event) => {
+                if (!isCurrent())
+                    return;
                 for (const cb of this.boundaryListeners) {
                     cb(event.charIndex, event.charLength || 1);
                 }
             };
             this.currentUtterance = utterance;
+            this.settleCurrentSpeech = settle;
             this.synthesis?.speak(utterance);
         });
     }
     stop() {
-        if (this.synthesis) {
-            this.synthesis.cancel();
-            this.currentUtterance = null;
-        }
+        ++this.operationGeneration;
+        // Settle before native cancel: it may emit synchronous callbacks or none.
+        this.settleCurrentSpeech?.();
+        this.synthesis?.cancel();
     }
     pause() {
         if (this.synthesis) {
@@ -224,6 +249,9 @@ export class BrowserSynthesisTTSAdapter {
     }
     async dispose() {
         this.stop();
+        ++this.initializationGeneration;
+        this.cancelVoiceLoad?.();
+        this.initialization = null;
         this.synthesis = null;
         this.voices = [];
         this.startListeners.clear();

package/dist/components/command-palette/CommandPalette.svelte

@@ -0,0 +1,75 @@
+<script lang="ts">
+/**
+ * CommandPalette - the trigger and the dialog together: the one component a
+ * host drops into a shell slot.
+ *
+ * ```svelte
+ * <AppShell slotItems={[{ id: 'item:command-palette', label: 'Search',
+ *   slot: 'header.center', render: search }]} ... />
+ * ```
+ *
+ * The palette is the `palette` prop, else the nearest `setCommandPalette()`
+ * context, else one created here from `providers` and `navigate` (then only
+ * this component can reach it). Mount it once: it owns the global shortcut.
+ */
+import { onDestroy, untrack } from 'svelte';
+import CommandPaletteDialog from './CommandPaletteDialog.svelte';
+import CommandPaletteTrigger from './CommandPaletteTrigger.svelte';
+import { tryUseCommandPalette } from './context.js';
+import {
+  CommandPaletteController,
+  type CommandPaletteOptions,
+} from './controller.svelte.js';
+import { DEFAULT_PALETTE_HOTKEYS } from './hotkeys.js';
+import type { PaletteProvider } from './types.js';
+
+interface Props {
+  /** The palette to use; default: context, else a new one. */
+  palette?: CommandPaletteController;
+  /** Providers for the palette created here (ignored when one is supplied). */
+  providers?: readonly PaletteProvider[];
+  /** Navigation seam for the palette created here. */
+  navigate?: CommandPaletteOptions['navigate'];
+  /** Shortcuts that toggle the palette; `false` for none. */
+  hotkeys?: readonly string[] | false;
+  /** Trigger text and dialog name (default "Search"). */
+  label?: string;
+  /** Show only the glyph in the trigger. */
+  compact?: boolean;
+  /** Render the dialog and shortcut without a trigger. */
+  hideTrigger?: boolean;
+}
+
+let {
+  palette: paletteProp,
+  providers = [],
+  navigate,
+  hotkeys = DEFAULT_PALETTE_HOTKEYS,
+  label,
+  compact = false,
+  hideTrigger = false,
+}: Props = $props();
+
+// The palette made here (when none is supplied) is built once from the initial
+// `providers` and `navigate`; register later providers through the controller.
+const fromContext = tryUseCommandPalette();
+const owned: CommandPaletteController | null = untrack(() =>
+  paletteProp || fromContext
+    ? null
+    : new CommandPaletteController({ providers, navigate }),
+);
+onDestroy(() => owned?.destroy());
+const palette = $derived(
+  paletteProp ?? fromContext ?? (owned as CommandPaletteController),
+);
+</script>
+
+{#if !hideTrigger}
+  <CommandPaletteTrigger
+    {palette}
+    {label}
+    {compact}
+    hotkeys={hotkeys === false ? [] : hotkeys}
+  />
+{/if}
+<CommandPaletteDialog {palette} {hotkeys} {label} />

package/dist/components/command-palette/CommandPalette.svelte.d.ts

@@ -0,0 +1,22 @@
+import { CommandPaletteController, type CommandPaletteOptions } from './controller.svelte.js';
+import type { PaletteProvider } from './types.js';
+interface Props {
+    /** The palette to use; default: context, else a new one. */
+    palette?: CommandPaletteController;
+    /** Providers for the palette created here (ignored when one is supplied). */
+    providers?: readonly PaletteProvider[];
+    /** Navigation seam for the palette created here. */
+    navigate?: CommandPaletteOptions['navigate'];
+    /** Shortcuts that toggle the palette; `false` for none. */
+    hotkeys?: readonly string[] | false;
+    /** Trigger text and dialog name (default "Search"). */
+    label?: string;
+    /** Show only the glyph in the trigger. */
+    compact?: boolean;
+    /** Render the dialog and shortcut without a trigger. */
+    hideTrigger?: boolean;
+}
+declare const CommandPalette: import("svelte").Component<Props, {}, "">;
+type CommandPalette = ReturnType<typeof CommandPalette>;
+export default CommandPalette;
+//# sourceMappingURL=CommandPalette.svelte.d.ts.map

package/dist/components/command-palette/CommandPalette.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommandPalette.svelte.d.ts","sourceRoot":"","sources":["../../../src/components/command-palette/CommandPalette.svelte.ts"],"names":[],"mappings":"AAoBA,OAAO,EACL,wBAAwB,EACxB,KAAK,qBAAqB,EAC3B,MAAM,wBAAwB,CAAC;AAEhC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAGlD,UAAU,KAAK;IACb,4DAA4D;IAC5D,OAAO,CAAC,EAAE,wBAAwB,CAAC;IACnC,6EAA6E;IAC7E,SAAS,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;IACvC,oDAAoD;IACpD,QAAQ,CAAC,EAAE,qBAAqB,CAAC,UAAU,CAAC,CAAC;IAC7C,2DAA2D;IAC3D,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,KAAK,CAAC;IACpC,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,wDAAwD;IACxD,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AA2CD,QAAA,MAAM,cAAc,2CAAwC,CAAC;AAC7D,KAAK,cAAc,GAAG,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC;AACxD,eAAe,cAAc,CAAC"}