@happyvertical/smrt-svelte 0.55.9 → 0.55.10

package/AGENTS.md

@@ -19,7 +19,7 @@ subpath you are editing. This file keeps what holds in every module.
 | `src/components/app/` (`./app`) | `AppShell` (Provider + ThemeProvider + theme CSS + AdminShell + nav/dock slots), `OwnerSetupForm` (props-driven first-run owner form), `ShellSettingsPage`, `RuntimeDiagnosticsWebMcp`. Browser-only; no `$app/*` or server imports | [agents/workspace.md](agents/workspace.md#app-shell-and-owner-setup-app) |
 | `src/components/workspace/` (`./workspace` + `./web`) | the AdminShell family and its principles, the legacy ToolsDock surface, the `./web` activity-feed and `updateAvailable` adapters, and server-side dock gates | [agents/workspace.md](agents/workspace.md) |
 | `src/components/command-palette/` (`./command-palette`) | `CommandPalette` trigger + dialog, `PaletteProvider` contract, nav and manifest providers (#3713) | [agents/command-palette.md](agents/command-palette.md) |
-| `src/components/overview/` (`./overview` + `./overview/server`) | customizable overview surfaces: `OverviewGrid` flow grid (span 1-4, keyboard reorder/resize) joined to the shell's layout edit mode, host-owned `createOverview` controller, widget registry with versioned option schemas validated on save and load, the server `load(options, ctx)` contract (`loadOverview`), the metric/chart/records/shortcuts/note core widgets, and `registerRecipeWidgets` (recipe `widget` surfaces to registry registrations, injected module resolver) (#3727) | [agents/overview-surfaces.md](agents/overview-surfaces.md) |
+| `src/components/overview/` (`./overview` + `./overview/server`) | customizable overview surfaces: `OverviewGrid` flow grid (span 1-4, keyboard reorder/resize) joined to the shell's layout edit mode, host-owned `createOverview` controller, widget registry with versioned option schemas validated on save and load, the server `load(options, ctx)` contract (`loadOverview`), the metric/chart/records/shortcuts/note core widgets, and `registerRecipeWidgets` (recipe `widget` surfaces to registry registrations, injected module resolver) (#3727); production persistence is `@happyvertical/smrt-preferences` (kind `overview`) | [agents/overview-surfaces.md](agents/overview-surfaces.md) |
 | `src/web/remote-query.svelte.ts` | Svelte 5 binding for query-shaped remote pages: rows, page, totals, loading/refreshing/stale/error, retry, last-updated, and query-scoped live subscriptions (#2445) | — |
 | `src/web/list-data-surface.svelte.ts` (`mountListDataSurface`) | Registers an existing non-`DataTable` list (mirroring a `DataTableController`) as a mounted `DataSurfaceDescriptor`; a same-behavior port of `registerContentListDataSurface`, not yet unified behind smrt-ui (#2917). The module doc comment is the authoritative list of divergences (#2906) | — |
 | `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) | — |

package/agents/overview-surfaces.md

@@ -11,15 +11,16 @@ 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").
+recipes ("Recipe widgets"); phase 3 is production persistence in
+`@happyvertical/smrt-preferences` ("Production persistence"); phase 4 adds
+assistant operations with Undo ("Assistant operations").
 
 ## 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`. |
+| `./overview/server` (`server.ts`) | Svelte-free: types, `validateWidgetOptions`, the model (`resolveOverview`, `checkOverviewOverride`, `applyOverviewOverride`, `diffOverview`, `sanitizeOverview`, ...), `WidgetRegistry` / `registerWidget`, `loadOverview`, the operations (`planOverviewOperations`, `describeOverview`) and `createOverviewAssistantSurface`. 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`, `createOverviewAssistant` / `useOverviewAssistantTools` / `OverviewAssistantUndo`. |
 
 ## Data model (`types.ts`, `model.ts`)
 
@@ -50,7 +51,8 @@ against (absent means 1).
   (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.
+  first; the user override then applies to that (smrt-preferences'
+  `withTenantDefaults`).
 - **Reset** is `controller.reset()` (store `null`) or `resetWidget(id)`.
 
 ## Validation: what keeps a stored overview from running anything
@@ -136,7 +138,11 @@ return { overview };   // LoadedOverview: JSON, serializable
 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`,
+reads: `document`, `base`, `override`, `committedOverride` (with a host-owned
+getter: the newest value handed to `onchange` that the getter has not fed back
+yet, else `override`; emissions are acknowledged in order, so several saves in
+flight never regress it, and a getter value matching none of them and not the
+value before them is a change from elsewhere that drops the queue), `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
@@ -239,17 +245,116 @@ turns the manifest's widget surfaces into `registry.register(...)` calls:
   and a type-level assertion here keeps `RecipeWidgetOptionType` equal to
   `WidgetOptionType`.
 
+## Production persistence (phase 3, `@happyvertical/smrt-preferences`)
+
+Overrides are stored as the `overview` kind of the generic user-interface
+preference table `_smrt_ui_preferences` in
+[smrt-preferences](../../preferences/AGENTS.md) (one row per tenant, kind,
+surface id = `OverviewDefinition.id`, and tier; the kind contract is in its
+[preference-kinds.md](../../preferences/agents/preference-kinds.md)). This
+package stays free of database code: its overview entries import nothing from
+core, tenancy or users. The `overview` kind validates with this package's
+`checkOverviewOverride` on save (only the canonical override is stored) and
+`resolveOverview` on load (bad entries dropped and reported per tier).
+`createOverviewStore({ db })` is the overview-shaped layer over the generic
+store and acts as the ambient principal:
+
+| Call | Does |
+| --- | --- |
+| `load(definition, registry)` | Both tiers resolved page defaults < tenant < user; each tier's `override`, `revision`, `issues`, the merged `document` and `canCustomize: { tenant, user }` |
+| `save(definition, registry, { scope, override, revision })` | Strict validation against the tier's definition (user: tenant-merged); `invalid` / `conflict` / `not_allowed` otherwise |
+| `reset(definition, { scope, revision? })` | Deletes that tier's row |
+| `loadPage(definition, registry, ctx, { scope? })` | `load` plus `loadOverview` of the tier's document, for `+page.server.ts` |
+| `loadWidget(definition, registry, widget, ctx)` | One widget's data for the controller's `loadWidget` remote function (throw on `ok: false`) |
+
+Host wiring for the personal layer: `createOverview({ definition:
+withTenantDefaults(definition, data.overview.tenant.document), override: () =>
+data.overview.user?.override ?? null, onchange: (next) => save({ scope:
+'user', override: next, revision }), canCustomize: () =>
+data.overview.canCustomize.user, loaded: data.overview.loaded, loadWidget })`;
+the organization layer uses the page definition, `tenant.override` and
+`canCustomize.tenant`. Keep the returned `revision` for the next save; on
+`conflict` reload the page data. Permissions are `overviews.customize` (tenant
+default) and `overviews.personalize` (own layout).
+
+Known model limit: a tenant default that later adds a widget whose id equals
+an id a user override already added hides the user's widget (an added widget
+colliding with a base id is skipped). `nextWidgetId` avoids it within one tier
+only.
+
+## Assistant operations (`operations.ts`, `assistant-surface.ts`, `assistant.svelte.ts`)
+
+Phase 4: the assistant adds and configures widgets with structured operations,
+and the person can undo the change.
+
+- **Operations** are data: `add { type, span?, options?, index? }`,
+  `configure { id, options }` (merged onto the current options; `null` clears a
+  key to its default), `move { id, index }`, `resize { id, span }`,
+  `remove { id }`. `OVERVIEW_OPERATION_SCHEMA` is their JSON schema.
+- **`planOverviewOperations({ definition, registry, override, operations })`**
+  plans a batch (at most 20) against the current override. Strict: unknown ops
+  or fields, unregistered or disallowed types (`allowed`, `allowedIn`), invalid
+  options (including a `model` outside `definition.models`), spans outside the
+  type's range, unknown widget ids and the cap are `OverviewOperationIssue`s
+  (`index`, `op`, `widgetId`, `code`, `message`, `options`). The result is then
+  run through `checkOverviewOverride`, so it is always an override a save
+  accepts. **Atomic**: any issue rejects the batch and returns nothing to
+  apply. Later operations see earlier ones; an `add` takes the next free id
+  (`nextWidgetId`, never a removed default's). Total, never throws.
+- **`describeOverview(...)`** is what a model reads first: allowed types with
+  option fields (type, required, default, range, `choices`, the page
+  `models`), span ranges, the current widgets with their index and title.
+  `translate` resolves i18n-key titles and labels.
+- **Server: `createOverviewAssistantSurface({ definition, registry, override,
+  revision, canCustomize, persist })`** is one page for one principal:
+  `describe`, `current`, `plan`, `check` and `persist`. Writes are
+  conditional: `persist(override, { revision })` must write only if the
+  stored row is still the loaded `revision` and answer
+  `{ ok: false, reason: 'conflict' }` otherwise
+  (`OverviewAssistantPersistResult`, structurally `OverviewSaveResult` of
+  `@happyvertical/smrt-preferences`); on success the surface follows the
+  returned `revision`. With phase 3:
+  `persist: (override, { revision }) => store.save(definition, registry, { scope: 'user', override, revision })`
+  where `store = createOverviewStore({ db })` from `@happyvertical/smrt-preferences`,
+  `override` / `revision` come from `store.load(...)`'s `state.user`, and the
+  surface's `definition` is `withTenantDefaults(definition, state.tenant.document)`. It is the adapter
+  `@happyvertical/smrt-chat`'s `createOverviewTools()` drives (typed
+  structurally there; see
+  [chat overview-tools.md](../../chat/agents/overview-tools.md) for the tool
+  contract, error codes and principal/page-scoped Undo). Phase 3 supplies the
+  stored override, the role and `persist`.
+- **Browser: `createOverviewAssistant(controller, { toolPrefix?, toaster?,
+  translate? })`** applies a batch through `controller.restore(plan.override)`,
+  so the grid updates live and the host's `onchange` persists it like any edit.
+  It refuses with `not_allowed` when `canCustomize` is false. `lastBatch`
+  (reactive) keeps `{ id, results, counts, before, after }`; `undo(id?)`
+  restores `before` exactly, once, and refuses with `changed_since` when the
+  override is no longer `after` (the person edited since). Both read
+  `controller.committedOverride`, so in host-owned mode a batch whose save the
+  host has not fed back yet is not mistaken for a change made elsewhere.
+  `useOverviewAssistantTools(assistant)` registers `<prefix>_describe` (read),
+  `<prefix>_apply` and `<prefix>_undo` (write) through `useWebMcpTool`, so the
+  AssistantDock offers them as page tools: the Provider's `webmcp.effects` must
+  allow `write`, the server's `clientToolAllowList` must list `overview_*`, and
+  the dock asks the person to Allow each write unless the host policy says
+  otherwise. Results are JSON strings (`{ ok: false, error, issues }` on a
+  rejected batch).
+- **Undo affordance.** `OverviewAssistantUndo` (`assistant`, optional
+  `message`) shows the last batch with Undo and Dismiss buttons and announces
+  the outcome in its own polite live region; or pass a smrt-ui `toaster` and
+  each batch shows as a toast with an Undo action (the host mounts
+  `ToastViewport`). Strings are `ui.overview.assistant_*`.
+- Tests: `__tests__/operations.test.ts`, `__tests__/assistant.test.ts` (live
+  grid update, Undo, the component with axe) and
+  `__tests__/assistant-tools.integration.test.ts` (chat's tools over this
+  model).
+
 ## 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.
+- **Phase 2, package widgets (#3727, done).** See "Recipe widgets" above.
+- **Phase 3, production persistence (#3727, done).** See "Production
+  persistence" above.
+- **Phase 4, assistant (#3727, done).** See "Assistant operations" above;
+  `createOverviewAssistantSurface` is wired to the stored user tier through
+  `createOverviewStore(...).save` as shown there.
 - **Not built:** the activity widget (Track B, #3710) and agenda.

package/agents/workspace.md

@@ -32,6 +32,12 @@ them from the published artifact versus exporting them is tracked in #2286.
 - App-owned configuration for hidden edges, push/overlay presentation, and
   exclusivity groups
 - User-owned preferences persist as sparse `ShellSettingsDelta` values
+  through a `ShellSettingsAdapter` (`LocalStorageShellSettingsAdapter` by
+  default). Server-side, per tenant and user, they can persist as the
+  `shell-layout` kind of `@happyvertical/smrt-preferences`
+  (`createShellSettingsPreferences`, the server half of an adapter); it
+  validates with `sanitizeShellSettingsDelta`, the untrusted-input reader on
+  the Node-safe `./workspace/server` entry (with `mergeShellSettingsDelta`)
 - Focus tools may register imperatively through `ShellState` or declaratively
   through Svelte helpers
 - Shell activities are client-side records; server jobs, polling, WebSockets,

package/dist/components/activity/ActivityList.svelte

@@ -0,0 +1,35 @@
+<script lang="ts">
+import WorkspaceActivityList from '../workspace/admin-shell/ActivityList.svelte';
+import { tryUseAdminShell } from '../workspace/admin-shell/context.js';
+import { safeActivityHref } from './safe-href.js';
+import type { ActivityListEntry } from './types.js';
+
+interface Props {
+  /** Already-authorized activity rows to display. */
+  entries: ActivityListEntry[];
+  /** Message displayed by the shell list when no activities match. */
+  emptyLabel?: string;
+}
+let { entries, emptyLabel = 'No activity.' }: Props = $props();
+const shell = tryUseAdminShell();
+const prefix = `audit-feed:${crypto.randomUUID()}:`;
+$effect(() => {
+  if (!shell) return;
+  const ids = new Set(entries.map((entry) => `${prefix}${entry.id}`));
+  for (const entry of entries)
+    shell.upsertActivity({
+      id: `${prefix}${entry.id}`,
+      label: entry.title,
+      message: entry.detail,
+      detailHref: safeActivityHref(entry.href),
+      kind: prefix,
+      scope: 'system',
+      status: 'completed',
+      createdAt: entry.occurredAt,
+    });
+  return () => {
+    for (const id of ids) shell.removeActivity(id);
+  };
+});
+</script>
+{#if shell}<WorkspaceActivityList filter={{ kind: prefix }} {emptyLabel} />{:else}<p>{emptyLabel}</p>{/if}

package/dist/components/activity/ActivityList.svelte.d.ts

@@ -0,0 +1,11 @@
+import type { ActivityListEntry } from './types.js';
+interface Props {
+    /** Already-authorized activity rows to display. */
+    entries: ActivityListEntry[];
+    /** Message displayed by the shell list when no activities match. */
+    emptyLabel?: string;
+}
+declare const ActivityList: import("svelte").Component<Props, {}, "">;
+type ActivityList = ReturnType<typeof ActivityList>;
+export default ActivityList;
+//# sourceMappingURL=ActivityList.svelte.d.ts.map

package/dist/components/activity/ActivityList.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ActivityList.svelte.d.ts","sourceRoot":"","sources":["../../../src/components/activity/ActivityList.svelte.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAGpD,UAAU,KAAK;IACb,mDAAmD;IACnD,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC7B,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAiCD,QAAA,MAAM,YAAY,2CAAwC,CAAC;AAC3D,KAAK,YAAY,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;AACpD,eAAe,YAAY,CAAC"}

package/dist/components/activity/index.d.ts

@@ -0,0 +1,3 @@
+export { default as ActivityList } from './ActivityList.svelte';
+export type { ActivityListEntry } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/components/activity/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/activity/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAChE,YAAY,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC"}

package/dist/components/activity/index.js

@@ -0,0 +1 @@
+export { default as ActivityList } from './ActivityList.svelte';

package/dist/components/activity/safe-href.d.ts

@@ -0,0 +1,3 @@
+/** Accept ordinary web links, never executable schemes or protocol-relative URLs. */
+export declare function safeActivityHref(value: string | null | undefined): string | undefined;
+//# sourceMappingURL=safe-href.d.ts.map

package/dist/components/activity/safe-href.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-href.d.ts","sourceRoot":"","sources":["../../../src/components/activity/safe-href.ts"],"names":[],"mappings":"AAAA,qFAAqF;AACrF,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC/B,MAAM,GAAG,SAAS,CASpB"}

package/dist/components/activity/safe-href.js

@@ -0,0 +1,12 @@
+/** Accept ordinary web links, never executable schemes or protocol-relative URLs. */
+export function safeActivityHref(value) {
+    if (!value || value.startsWith('//') || value.includes('\\'))
+        return undefined;
+    try {
+        const url = new URL(value, 'https://smrt.invalid');
+        return ['https:', 'http:'].includes(url.protocol) ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/components/activity/types.d.ts

@@ -0,0 +1,9 @@
+/** Authorized activity projected by an owning domain package. */
+export interface ActivityListEntry {
+    id: string;
+    title: string;
+    detail?: string;
+    occurredAt: string;
+    href?: string | null;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/components/activity/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/components/activity/types.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB"}

package/dist/components/activity/types.js

@@ -0,0 +1 @@
+export {};

package/dist/components/notifications/LocalizedNotifications.fixture.svelte

@@ -0,0 +1,16 @@
+<script lang="ts">
+import { type I18nStore, setI18nContext } from '@happyvertical/smrt-ui/i18n';
+import { untrack } from 'svelte';
+import MailboxDemo from '../../../../messages/src/svelte/components/MailboxDemo.svelte';
+import NotificationBell from './NotificationBell.svelte';
+import type { NotificationProvider } from './types.js';
+
+interface Props {
+  store: I18nStore;
+  provider?: NotificationProvider;
+  mailbox?: boolean;
+}
+let { store, provider, mailbox = false }: Props = $props();
+setI18nContext(untrack(() => store));
+</script>
+{#if mailbox}<MailboxDemo />{:else if provider}<NotificationBell {provider} />{/if}

package/dist/components/notifications/LocalizedNotifications.fixture.svelte.d.ts

@@ -0,0 +1,11 @@
+import { type I18nStore } from '@happyvertical/smrt-ui/i18n';
+import type { NotificationProvider } from './types.js';
+interface Props {
+    store: I18nStore;
+    provider?: NotificationProvider;
+    mailbox?: boolean;
+}
+declare const LocalizedNotifications: import("svelte").Component<Props, {}, "">;
+type LocalizedNotifications = ReturnType<typeof LocalizedNotifications>;
+export default LocalizedNotifications;
+//# sourceMappingURL=LocalizedNotifications.fixture.svelte.d.ts.map

package/dist/components/notifications/LocalizedNotifications.fixture.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LocalizedNotifications.fixture.svelte.d.ts","sourceRoot":"","sources":["../../../src/components/notifications/LocalizedNotifications.fixture.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,SAAS,EAAkB,MAAM,6BAA6B,CAAC;AAI7E,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAGvD,UAAU,KAAK;IACb,KAAK,EAAE,SAAS,CAAC;IACjB,QAAQ,CAAC,EAAE,oBAAoB,CAAC;IAChC,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAeD,QAAA,MAAM,sBAAsB,2CAAwC,CAAC;AACrE,KAAK,sBAAsB,GAAG,UAAU,CAAC,OAAO,sBAAsB,CAAC,CAAC;AACxE,eAAe,sBAAsB,CAAC"}

package/dist/components/notifications/NotificationBell.svelte

@@ -0,0 +1,136 @@
+<script lang="ts">
+import { useI18n } from '@happyvertical/smrt-ui/i18n';
+import { Button } from '@happyvertical/smrt-ui/ui';
+import { M } from '../../i18n/strings.notifications.js';
+import type { NotificationProvider } from './types.js';
+
+interface Props {
+  /** Authorized provider that supplies this user's notification state. */
+  provider: NotificationProvider;
+  /** Accessible trigger and panel heading. */
+  label?: string;
+  /** Maximum number of recent notifications requested from the provider. */
+  limit?: number;
+}
+const { t } = useI18n();
+let { provider, label, limit = 20 }: Props = $props();
+const heading = $derived(label ?? t(M['ui.notification_bell.label']));
+const instanceId = $props.id();
+let panel = $state<HTMLDivElement>();
+let open = $state(false);
+$effect(() => {
+  if (open) panel?.focus();
+});
+let loading = $state(true);
+let error = $state<string | null>(null);
+let unread = $state(0);
+let items = $state<Awaited<ReturnType<NotificationProvider['list']>>>([]);
+let request = 0;
+let generation = 0;
+let active = false;
+
+async function refresh(source = provider, epoch = generation) {
+  if (!active || epoch !== generation) return;
+  const current = ++request;
+  loading = true;
+  error = null;
+  try {
+    const [nextUnread, nextItems] = await Promise.all([
+      source.getUnreadCount(),
+      source.list({ limit }),
+    ]);
+    if (!active || epoch !== generation || current !== request) return;
+    unread =
+      Number.isSafeInteger(nextUnread) && nextUnread > 0 ? nextUnread : 0;
+    items = nextItems;
+  } catch {
+    if (!active || epoch !== generation || current !== request) return;
+    error = M['ui.notification_bell.unavailable'];
+  } finally {
+    if (active && epoch === generation && current === request) loading = false;
+  }
+}
+function safeHref(value: string | null | undefined): string | null {
+  if (!value || value.startsWith('//') || value.includes('\\')) return null;
+  try {
+    const parsed = new URL(value, 'https://smrt.invalid');
+    return parsed.protocol === 'http:' || parsed.protocol === 'https:'
+      ? value
+      : null;
+  } catch {
+    return null;
+  }
+}
+function close() {
+  open = false;
+  document.getElementById(`${instanceId}-trigger`)?.focus();
+}
+function keydown(event: KeyboardEvent) {
+  if (event.key === 'Escape' && open) {
+    event.preventDefault();
+    close();
+  }
+}
+async function mutate(id?: string) {
+  const source = provider;
+  const epoch = generation;
+  try {
+    if (id) await source.markRead(id);
+    else await source.markAllRead();
+    await refresh(source, epoch);
+  } catch {
+    if (active && epoch === generation)
+      error = M['ui.notification_bell.mark_error'];
+  }
+}
+$effect(() => {
+  const source = provider;
+  const epoch = ++generation;
+  active = true;
+  items = [];
+  unread = 0;
+  error = null;
+  void refresh(source, epoch);
+  let stop: (() => void) | undefined;
+  try {
+    stop = source.subscribe?.(() => void refresh(source, epoch));
+  } catch {
+    error = M['ui.notification_bell.live_error'];
+  }
+  return () => {
+    active = false;
+    ++generation;
+    ++request;
+    stop?.();
+  };
+});
+</script>
+
+<div class="smrt-notification-bell">
+  <Button id={`${instanceId}-trigger`} aria-controls={`${instanceId}-panel`} variant="ghost" aria-haspopup="dialog" aria-expanded={open} onclick={() => (open = !open)}>
+    {heading}{#if unread > 0}<span aria-label={t(M['ui.notification_bell.unread'], { count: unread })}> ({unread})</span>{/if}
+  </Button>
+  {#if open}
+    <div bind:this={panel} id={`${instanceId}-panel`} role="dialog" aria-label={heading} tabindex="-1" onkeydown={keydown} class="smrt-notification-bell__panel">
+      <header><strong>{heading}</strong><Button variant="ghost" size="sm" disabled={unread === 0 || loading} onclick={() => mutate()}>{t(M['ui.notification_bell.mark_all'])}</Button></header>
+      {#if error}<p role="alert">{t(error)}</p>{/if}
+      {#if loading}<p role="status">{t(M['ui.notification_bell.loading'])}</p>{:else if items.length === 0}<p>{t(M['ui.notification_bell.empty'])}</p>{:else}<ol>
+        {#each items as item (item.id)}<li data-read={item.readAt ? 'true' : 'false'}>
+          {#if safeHref(item.href)}<a href={safeHref(item.href) ?? undefined}>{item.title}</a>{:else}<strong>{item.title}</strong>{/if}
+          {#if item.body}<p>{item.body}</p>{/if}
+          {#if !item.readAt}<Button variant="ghost" size="sm" onclick={() => mutate(item.id)}>{t(M['ui.notification_bell.mark_one'])}</Button>{/if}
+        </li>{/each}
+      </ol>{/if}
+    </div>
+  {/if}
+</div>
+
+<style>
+  .smrt-notification-bell { position: relative; }
+  .smrt-notification-bell__panel { position: absolute; z-index: 1; inset-block-start: 100%; inset-inline-end: 0; inline-size: min(24rem, 90vw); padding: var(--smrt-spacing-3); background: var(--smrt-color-surface); border: 1px solid var(--smrt-color-outline); border-radius: var(--smrt-radius-medium); }
+  header { display: flex; justify-content: space-between; gap: var(--smrt-spacing-2); }
+  ol { display: grid; gap: var(--smrt-spacing-2); padding: 0; list-style: none; }
+  li { padding-block: var(--smrt-spacing-2); border-block-end: 1px solid var(--smrt-color-outline-variant); }
+  li[data-read='false'] { border-inline-start: 3px solid var(--smrt-color-primary); padding-inline-start: var(--smrt-spacing-2); }
+  p { overflow-wrap: anywhere; }
+</style>

package/dist/components/notifications/NotificationBell.svelte.d.ts

@@ -0,0 +1,13 @@
+import type { NotificationProvider } from './types.js';
+interface Props {
+    /** Authorized provider that supplies this user's notification state. */
+    provider: NotificationProvider;
+    /** Accessible trigger and panel heading. */
+    label?: string;
+    /** Maximum number of recent notifications requested from the provider. */
+    limit?: number;
+}
+declare const NotificationBell: import("svelte").Component<Props, {}, "">;
+type NotificationBell = ReturnType<typeof NotificationBell>;
+export default NotificationBell;
+//# sourceMappingURL=NotificationBell.svelte.d.ts.map

package/dist/components/notifications/NotificationBell.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NotificationBell.svelte.d.ts","sourceRoot":"","sources":["../../../src/components/notifications/NotificationBell.svelte.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAGvD,UAAU,KAAK;IACb,wEAAwE;IACxE,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AA4HD,QAAA,MAAM,gBAAgB,2CAAwC,CAAC;AAC/D,KAAK,gBAAgB,GAAG,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAC5D,eAAe,gBAAgB,CAAC"}

package/dist/components/notifications/index.d.ts

@@ -0,0 +1,3 @@
+export { default as NotificationBell } from './NotificationBell.svelte';
+export type { NotificationItem, NotificationProvider } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/components/notifications/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/notifications/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AACxE,YAAY,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC"}

package/dist/components/notifications/index.js

@@ -0,0 +1 @@
+export { default as NotificationBell } from './NotificationBell.svelte';

package/dist/components/notifications/types.d.ts

@@ -0,0 +1,27 @@
+/** A browser-safe notification supplied by an application-owned provider. */
+export interface NotificationItem {
+    id: string;
+    title: string;
+    body?: string;
+    href?: string | null;
+    severity?: 'info' | 'success' | 'warning' | 'error';
+    occurredAt: string;
+    readAt?: string | null;
+}
+/**
+ * Application boundary for the notification bell.
+ *
+ * Providers authorize their own reads and writes. The component never accepts
+ * a user id or tenant id, so it cannot broaden that authority.
+ */
+export interface NotificationProvider {
+    getUnreadCount(): Promise<number>;
+    list(options?: {
+        limit?: number;
+    }): Promise<NotificationItem[]>;
+    markRead(id: string): Promise<void>;
+    markAllRead(): Promise<void>;
+    /** Optional live transport subscription. Returns an unsubscribe function. */
+    subscribe?(listener: () => void): () => void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/components/notifications/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/components/notifications/types.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;IACpD,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAClC,IAAI,CAAC,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAAC;IAChE,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,6EAA6E;IAC7E,SAAS,CAAC,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;CAC9C"}

package/dist/components/notifications/types.js

@@ -0,0 +1 @@
+export {};

package/dist/components/overview/OverviewAssistantUndo.svelte

@@ -0,0 +1,77 @@
+<script lang="ts">
+/**
+ * The inline Undo affordance for an assistant's overview edit (#3727 phase
+ * 4). While the last batch can be undone it shows a short message with an
+ * Undo button and a dismiss button; the outcome of Undo is announced in the
+ * same polite live region. Place it next to the `OverviewGrid` it belongs to.
+ */
+import { useI18n } from '@happyvertical/smrt-ui/i18n';
+import { Button } from '@happyvertical/smrt-ui/ui';
+import { M } from '../../i18n/strings.overview.js';
+import type {
+  OverviewAssistant,
+  OverviewAssistantBatch,
+} from './assistant.svelte.js';
+
+interface Props {
+  /** The browser assistant from `createOverviewAssistant`. */
+  assistant: OverviewAssistant;
+  /** Message for a batch (default: a generic "updated" line). */
+  message?: (batch: OverviewAssistantBatch) => string;
+  /** Extra class names for the affordance's row, for host placement. */
+  class?: string;
+}
+
+let { assistant, message, class: className = '' }: Props = $props();
+const { t } = useI18n();
+const batch = $derived(assistant.lastBatch);
+let outcome = $state('');
+
+function undo(): void {
+  const current = batch;
+  if (!current) return;
+  const result = assistant.undo(current.id);
+  outcome = result.ok
+    ? t(M['ui.overview.assistant_undone'])
+    : result.reason === 'changed_since'
+      ? t(M['ui.overview.assistant_changed_since'])
+      : t(M['ui.overview.assistant_undo_failed']);
+}
+
+$effect(() => {
+  // A new batch replaces the previous outcome line.
+  if (batch) outcome = '';
+});
+</script>
+
+<div class="smrt-overview-assistant-undo {className}" data-active={batch ? '' : undefined}>
+  <!-- The live region stays mounted so each new message is announced. -->
+  <span class="smrt-overview-assistant-undo__message" role="status" aria-live="polite">
+    {#if batch}
+      {message ? message(batch) : t(M['ui.overview.assistant_applied'])}
+    {:else}
+      {outcome}
+    {/if}
+  </span>
+  {#if batch}
+    <Button size="sm" variant="secondary" onclick={undo}>
+      {t(M['ui.overview.assistant_undo'])}
+    </Button>
+    <Button size="sm" variant="ghost" onclick={() => assistant.dismiss()}>
+      {t(M['ui.overview.assistant_dismiss'])}
+    </Button>
+  {/if}
+</div>
+
+<style>
+  .smrt-overview-assistant-undo {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: var(--smrt-spacing-2, 0.5rem);
+  }
+
+  .smrt-overview-assistant-undo__message {
+    flex: 1 1 12rem;
+  }
+</style>

package/dist/components/overview/OverviewAssistantUndo.svelte.d.ts

@@ -0,0 +1,13 @@
+import type { OverviewAssistant, OverviewAssistantBatch } from './assistant.svelte.js';
+interface Props {
+    /** The browser assistant from `createOverviewAssistant`. */
+    assistant: OverviewAssistant;
+    /** Message for a batch (default: a generic "updated" line). */
+    message?: (batch: OverviewAssistantBatch) => string;
+    /** Extra class names for the affordance's row, for host placement. */
+    class?: string;
+}
+declare const OverviewAssistantUndo: import("svelte").Component<Props, {}, "">;
+type OverviewAssistantUndo = ReturnType<typeof OverviewAssistantUndo>;
+export default OverviewAssistantUndo;
+//# sourceMappingURL=OverviewAssistantUndo.svelte.d.ts.map

package/dist/components/overview/OverviewAssistantUndo.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OverviewAssistantUndo.svelte.d.ts","sourceRoot":"","sources":["../../../src/components/overview/OverviewAssistantUndo.svelte.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EACV,iBAAiB,EACjB,sBAAsB,EACvB,MAAM,uBAAuB,CAAC;AAG/B,UAAU,KAAK;IACb,4DAA4D;IAC5D,SAAS,EAAE,iBAAiB,CAAC;IAC7B,+DAA+D;IAC/D,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,sBAAsB,KAAK,MAAM,CAAC;IACpD,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAsDD,QAAA,MAAM,qBAAqB,2CAAwC,CAAC;AACpE,KAAK,qBAAqB,GAAG,UAAU,CAAC,OAAO,qBAAqB,CAAC,CAAC;AACtE,eAAe,qBAAqB,CAAC"}