@happyvertical/smrt-svelte 0.55.9 → 0.55.11

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"}

package/dist/components/overview/OverviewGrid.svelte

@@ -41,6 +41,8 @@ let {
   editing: editingProp,
   label,
   headingLevel = 2,
+  heading,
+  presentation = 'card',
   models,
   iconComponent,
 }: OverviewGridProps = $props();
@@ -348,7 +350,7 @@ const headingTag = $derived(`h${headingLevel}`);
 {#snippet body(row: Row)}
   {@const Widget = components?.get(row.widget.type) ?? row.def?.component}
   <article class="smrt-overview__widget" aria-labelledby="{uid}-title-{row.widget.id}">
-    <svelte:element this={headingTag} class="smrt-overview__title" id="{uid}-title-{row.widget.id}">{row.title}</svelte:element>
+    <svelte:element this={headingTag} class="smrt-overview__title" id="{uid}-title-{row.widget.id}">{#if heading}{@render heading(row.widget, row.title)}{:else}{row.title}{/if}</svelte:element>
     <div class="smrt-overview__content" aria-busy={row.status === 'loading'}>
       {#if !row.def}
         <p class="smrt-overview__state">{t(M['ui.overview.unavailable'])}</p>
@@ -376,7 +378,7 @@ const headingTag = $derived(`h${headingLevel}`);
   </article>
 {/snippet}
 
-<div class="smrt-overview" bind:this={rootEl} data-editing={editing ? '' : undefined}>
+<div class="smrt-overview" bind:this={rootEl} data-editing={editing ? '' : undefined} data-presentation={presentation}>
   {#if editing}
     <div class="smrt-overview__toolbar" role="toolbar" aria-label={t(M['ui.overview.toolbar'])}>
       <ShellIconButton
@@ -547,6 +549,7 @@ const headingTag = $derived(`h${headingLevel}`);
   .smrt-overview__item[data-drop='before']::before { inset-inline-start: 0; }
   .smrt-overview__item[data-drop='after']::before { inset-inline-end: 0; }
   .smrt-overview__tile { position: relative; block-size: 100%; box-sizing: border-box; padding: var(--smrt-spacing-3); border: 1px solid var(--smrt-color-outline-variant); border-radius: var(--smrt-radius-large, var(--smrt-radius-medium)); background: var(--smrt-color-surface); color: var(--smrt-color-on-surface); }
+  [data-presentation='plain']:not([data-editing]) .smrt-overview__tile { padding: 0; border: 0; border-radius: 0; background: transparent; }
   [data-editing] .smrt-overview__tile { border-style: dashed; }
   .smrt-overview__widget { display: grid; gap: var(--smrt-spacing-2); align-content: start; min-inline-size: 0; }
   .smrt-overview__title { margin: 0; color: var(--smrt-color-on-surface-variant); font-size: var(--smrt-typography-title-small-size, 0.875rem); font-weight: var(--smrt-typography-weight-medium, 500); }

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

@@ -1 +1 @@
-{"version":3,"file":"OverviewGrid.svelte.d.ts","sourceRoot":"","sources":["../../../src/components/overview/OverviewGrid.svelte.ts"],"names":[],"mappings":"AAiCA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AA0bzD,QAAA,MAAM,YAAY,uDAAwC,CAAC;AAC3D,KAAK,YAAY,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;AACpD,eAAe,YAAY,CAAC"}
+{"version":3,"file":"OverviewGrid.svelte.d.ts","sourceRoot":"","sources":["../../../src/components/overview/OverviewGrid.svelte.ts"],"names":[],"mappings":"AAiCA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AA4bzD,QAAA,MAAM,YAAY,uDAAwC,CAAC;AAC3D,KAAK,YAAY,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;AACpD,eAAe,YAAY,CAAC"}

package/dist/components/overview/assistant-surface.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The server half of the overview assistant (#3727 phase 4): one overview, for
+ * one principal, as the adapter `@happyvertical/smrt-chat`'s
+ * `createOverviewTools()` operates on. The chat package depends on no UI
+ * package, so it types this object structurally; this module is the
+ * implementation a host returns from its `open(run, pageId)`.
+ *
+ * Every plan and every restore runs through the phase-1 model and
+ * `checkOverviewOverride`, so the assistant can only store an override the
+ * save endpoint would accept. Persistence stays the host's (phase 3): the
+ * surface calls `persist` with the canonical override and keeps its own copy
+ * of the value it last persisted.
+ *
+ * Svelte-free; on `./overview/server`.
+ */
+import { type OverviewOverrideCheck } from './model.js';
+import { type DescribeOverviewInput, type OverviewDescription, type OverviewPlan } from './operations.js';
+import { type WidgetRegistry } from './registry.js';
+import type { OverviewDefinition, OverviewOverride } from './types.js';
+export interface OverviewAssistantSurfaceOptions {
+    /** The page's declaration (allowed set, models, defaults, cap). */
+    definition: OverviewDefinition;
+    /** Defaults to the shared registry. */
+    registry?: WidgetRegistry;
+    /**
+     * The principal's stored override for this page (untrusted JSON; `null`
+     * for none), as the host loaded it for this request.
+     */
+    override: unknown;
+    /**
+     * The concurrency token of the stored row the host loaded `override` from
+     * (`null` when it loaded no row), echoed back to `persist`. With the
+     * phase-3 store (`createOverviewStore` of `@happyvertical/smrt-preferences`)
+     * this is `state.user.revision` from its `load`.
+     */
+    revision: string | null;
+    /** Whether this principal may customize this page (the role gate). */
+    canCustomize: boolean;
+    /**
+     * Store the canonical override (`null` = back to the defaults) in the
+     * principal's tier, CONDITIONALLY on `expected.revision` still being the
+     * stored one: a save that landed since must answer
+     * `{ ok: false, reason: 'conflict' }`, never be overwritten. The phase-3
+     * store plugs in directly:
+     * `(override, { revision }) => store.save(definition, registry, { scope: 'user', override, revision })`
+     * with `store = createOverviewStore({ db })` from `@happyvertical/smrt-preferences`.
+     */
+    persist: (override: OverviewOverride | null, expected: {
+        revision: string | null;
+    }) => OverviewAssistantPersistResult | Promise<OverviewAssistantPersistResult>;
+    /** Turns titles and labels that are i18n keys into text. */
+    translate?: DescribeOverviewInput['translate'];
+    /** Batch cap (default 20). */
+    maxOperations?: number;
+}
+/**
+ * A conditional write's outcome. `revision` is the stored row's new token
+ * (`null` when the write removed the row); omitted, the surface keeps the
+ * token it had. Structurally `OverviewSaveResult` of
+ * `@happyvertical/smrt-preferences`.
+ */
+export type OverviewAssistantPersistResult = {
+    ok: true;
+    revision?: string | null;
+} | {
+    ok: false;
+    reason: 'conflict' | 'not_allowed' | 'invalid';
+    issues?: readonly unknown[];
+};
+/** One overview for one principal; what `createOverviewTools()` drives. */
+export interface OverviewAssistantSurface {
+    readonly pageId: string;
+    readonly canCustomize: boolean;
+    /** Allowed widget types with their option fields, and the arrangement. */
+    describe(): OverviewDescription;
+    /** The canonical override in effect (`null` = defaults). */
+    current(): OverviewOverride | null;
+    /** Plan a batch against {@link current}. Applies nothing. */
+    plan(operations: unknown): OverviewPlan;
+    /** Validate an override (the Undo value) the way a save is validated. */
+    check(override: unknown): OverviewOverrideCheck;
+    /**
+     * Persist a canonical override if the stored row is still the loaded
+     * revision; on success {@link current} and the revision follow it.
+     */
+    persist(override: OverviewOverride | null): Promise<OverviewAssistantPersistResult>;
+}
+/** Build the assistant adapter for one overview and one principal. */
+export declare function createOverviewAssistantSurface(options: OverviewAssistantSurfaceOptions): OverviewAssistantSurface;
+//# sourceMappingURL=assistant-surface.d.ts.map

package/dist/components/overview/assistant-surface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assistant-surface.d.ts","sourceRoot":"","sources":["../../../src/components/overview/assistant-surface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAGL,KAAK,qBAAqB,EAE3B,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,KAAK,qBAAqB,EAE1B,KAAK,mBAAmB,EACxB,KAAK,YAAY,EAElB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAyB,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AAC3E,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEvE,MAAM,WAAW,+BAA+B;IAC9C,mEAAmE;IACnE,UAAU,EAAE,kBAAkB,CAAC;IAC/B,uCAAuC;IACvC,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B;;;OAGG;IACH,QAAQ,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,sEAAsE;IACtE,YAAY,EAAE,OAAO,CAAC;IACtB;;;;;;;;OAQG;IACH,OAAO,EAAE,CACP,QAAQ,EAAE,gBAAgB,GAAG,IAAI,EACjC,QAAQ,EAAE;QAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,KAClC,8BAA8B,GAAG,OAAO,CAAC,8BAA8B,CAAC,CAAC;IAC9E,4DAA4D;IAC5D,SAAS,CAAC,EAAE,qBAAqB,CAAC,WAAW,CAAC,CAAC;IAC/C,8BAA8B;IAC9B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,MAAM,MAAM,8BAA8B,GACtC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GACtC;IACE,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,UAAU,GAAG,aAAa,GAAG,SAAS,CAAC;IAC/C,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;CAC7B,CAAC;AAEN,2EAA2E;AAC3E,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,0EAA0E;IAC1E,QAAQ,IAAI,mBAAmB,CAAC;IAChC,4DAA4D;IAC5D,OAAO,IAAI,gBAAgB,GAAG,IAAI,CAAC;IACnC,6DAA6D;IAC7D,IAAI,CAAC,UAAU,EAAE,OAAO,GAAG,YAAY,CAAC;IACxC,yEAAyE;IACzE,KAAK,CAAC,QAAQ,EAAE,OAAO,GAAG,qBAAqB,CAAC;IAChD;;;OAGG;IACH,OAAO,CACL,QAAQ,EAAE,gBAAgB,GAAG,IAAI,GAChC,OAAO,CAAC,8BAA8B,CAAC,CAAC;CAC5C;AAED,sEAAsE;AACtE,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,+BAA+B,GACvC,wBAAwB,CA2C1B"}

package/dist/components/overview/assistant-surface.js

@@ -0,0 +1,65 @@
+/**
+ * The server half of the overview assistant (#3727 phase 4): one overview, for
+ * one principal, as the adapter `@happyvertical/smrt-chat`'s
+ * `createOverviewTools()` operates on. The chat package depends on no UI
+ * package, so it types this object structurally; this module is the
+ * implementation a host returns from its `open(run, pageId)`.
+ *
+ * Every plan and every restore runs through the phase-1 model and
+ * `checkOverviewOverride`, so the assistant can only store an override the
+ * save endpoint would accept. Persistence stays the host's (phase 3): the
+ * surface calls `persist` with the canonical override and keeps its own copy
+ * of the value it last persisted.
+ *
+ * Svelte-free; on `./overview/server`.
+ */
+import { checkOverviewOverride, diffOverview, resolveOverview, } from './model.js';
+import { describeOverview, planOverviewOperations, } from './operations.js';
+import { defaultWidgetRegistry } from './registry.js';
+/** Build the assistant adapter for one overview and one principal. */
+export function createOverviewAssistantSurface(options) {
+    const registry = options.registry ?? defaultWidgetRegistry;
+    const { definition } = options;
+    const initial = checkOverviewOverride(definition, options.override, registry);
+    // A stored value the model no longer accepts resolves leniently on load;
+    // its canonical form is whatever survives sanitizing.
+    let current = initial.ok
+        ? initial.override
+        : sanitizedCurrent(definition, registry, options.override);
+    let revision = options.revision;
+    return {
+        pageId: definition.id,
+        canCustomize: options.canCustomize,
+        describe: () => describeOverview({
+            definition,
+            registry,
+            override: current,
+            canCustomize: options.canCustomize,
+            translate: options.translate,
+            maxOperations: options.maxOperations,
+        }),
+        current: () => current,
+        plan: (operations) => planOverviewOperations({
+            definition,
+            registry,
+            override: current,
+            operations,
+            maxOperations: options.maxOperations,
+        }),
+        check: (override) => checkOverviewOverride(definition, override, registry),
+        async persist(override) {
+            const result = await options.persist(override, { revision });
+            if (result.ok) {
+                current = override;
+                if ('revision' in result && result.revision !== undefined) {
+                    revision = result.revision;
+                }
+            }
+            return result;
+        },
+    };
+}
+function sanitizedCurrent(definition, registry, override) {
+    const resolved = resolveOverview(definition, override, registry);
+    return diffOverview(resolved.base, resolved.document);
+}

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

@@ -0,0 +1,115 @@
+/**
+ * The overview assistant in the browser (#3727 phase 4): the structured
+ * operations an in-page assistant (the AssistantDock) applies to a mounted
+ * overview, with a single-step Undo.
+ *
+ * A batch is planned with {@link planOverviewOperations} against the
+ * controller's definition and current override, so it is atomic (one invalid
+ * operation rejects the batch and nothing changes) and can only produce an
+ * override the save endpoint accepts. A valid batch lands through
+ * `controller.restore`, so the grid updates live and the host's `onchange`
+ * persists it like any other edit. The override before the batch is kept for
+ * Undo; Undo restores it exactly, and refuses once the overview changed in
+ * between (it would discard that edit).
+ *
+ * The browser tools (`overview_describe`, `overview_apply`, `overview_undo`)
+ * register on the page's WebMCP registry through `useWebMcpTool`, the same
+ * path every bespoke page tool takes, so the dock offers and runs them like
+ * any other page tool (a `write` waits for the person's Allow unless the host
+ * policy says otherwise). The browser session is the principal: the
+ * controller only holds this viewer's override, and `canCustomize` gates every
+ * apply and undo.
+ */
+import type { Toaster } from '@happyvertical/smrt-ui/feedback';
+import type { WebMcpToolSpec } from '../../web/webmcp.svelte.js';
+import type { OverviewController } from './controller.svelte.js';
+import { type OverviewDescription, type OverviewOperationIssue, type OverviewOperationKind, type OverviewOperationResult } from './operations.js';
+import type { OverviewOverride } from './types.js';
+/** One applied batch, kept for Undo. */
+export interface OverviewAssistantBatch {
+    /** Opaque id; `undo(id)` only undoes this batch. */
+    id: string;
+    results: OverviewOperationResult[];
+    /** How many operations of each kind the batch applied. */
+    counts: Partial<Record<OverviewOperationKind, number>>;
+    /** The override before the batch (what Undo restores). */
+    before: OverviewOverride | null;
+    /** The override the batch produced. */
+    after: OverviewOverride | null;
+}
+export type OverviewAssistantApplyResult = {
+    ok: true;
+    /** `null` when the batch changed nothing (no Undo is offered). */
+    batchId: string | null;
+    results: OverviewOperationResult[];
+} | {
+    ok: false;
+    reason: 'not_allowed' | 'invalid';
+    issues: OverviewOperationIssue[];
+};
+export type OverviewAssistantUndoResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: 'not_allowed' | 'nothing_to_undo' | 'changed_since';
+};
+export interface OverviewAssistantOptions {
+    /**
+     * Tool name prefix (default `overview`): tools are `<prefix>_describe`,
+     * `<prefix>_apply` and `<prefix>_undo`. Give each overview on one page its
+     * own prefix.
+     */
+    toolPrefix?: string;
+    /** Turns widget titles and labels that are i18n keys into text. */
+    translate?: (key: string) => string;
+    /**
+     * Also show each applied batch as a toast with an Undo action (the host
+     * mounts a smrt-ui `ToastViewport` for it). `OverviewAssistantUndo` is the
+     * inline alternative.
+     */
+    toaster?: Toaster;
+    /** Toast and inline message text; receives the batch. */
+    message?: (batch: OverviewAssistantBatch) => string;
+    /** Undo button label (default `Undo`). */
+    undoLabel?: string;
+    /** Called after a batch applies. */
+    onapply?: (batch: OverviewAssistantBatch) => void;
+    /** Batch cap (default 20). */
+    maxOperations?: number;
+}
+export declare class OverviewAssistant {
+    #private;
+    readonly controller: OverviewController;
+    constructor(controller: OverviewController, options?: OverviewAssistantOptions);
+    /** The last applied batch while it can still be undone. */
+    get lastBatch(): OverviewAssistantBatch | null;
+    /** Text for the Undo affordance. */
+    message(batch: OverviewAssistantBatch): string;
+    get undoLabel(): string;
+    /** What the overview allows and shows now. */
+    describe(): OverviewDescription;
+    /** Apply a batch atomically; the grid updates through the controller. */
+    apply(operations: unknown): OverviewAssistantApplyResult;
+    /**
+     * Restore the override from before the last batch. Refused when the
+     * overview changed after that batch (the person edited it), or when `id`
+     * names another batch.
+     */
+    undo(id?: string): OverviewAssistantUndoResult;
+    /** Forget the last batch (hides the Undo affordance). */
+    dismiss(): void;
+    /** The browser tool specs (register with `useOverviewAssistantTools`). */
+    tools(): WebMcpToolSpec[];
+}
+/** Create the browser overview assistant for a controller. */
+export declare function createOverviewAssistant(controller: OverviewController, options?: OverviewAssistantOptions): OverviewAssistant;
+/**
+ * Register the assistant's browser tools on the page's WebMCP registry for
+ * the calling component's lifetime. Call during component initialization.
+ * `apply` and `undo` are `write` tools: the nearest Provider's
+ * `webmcp.effects` must allow `write`, or only `describe` is exposed.
+ */
+export declare function useOverviewAssistantTools(assistant: OverviewAssistant, options?: {
+    effects?: readonly ('read' | 'write' | 'destructive')[];
+}): void;
+//# sourceMappingURL=assistant.svelte.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"assistant.svelte.d.ts","sourceRoot":"","sources":["../../../src/components/overview/assistant.svelte.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iCAAiC,CAAC;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAEjE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,EAIL,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,uBAAuB,EAE7B,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD,wCAAwC;AACxC,MAAM,WAAW,sBAAsB;IACrC,oDAAoD;IACpD,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,uBAAuB,EAAE,CAAC;IACnC,0DAA0D;IAC1D,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC,CAAC;IACvD,0DAA0D;IAC1D,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAChC,uCAAuC;IACvC,KAAK,EAAE,gBAAgB,GAAG,IAAI,CAAC;CAChC;AAED,MAAM,MAAM,4BAA4B,GACpC;IACE,EAAE,EAAE,IAAI,CAAC;IACT,kEAAkE;IAClE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,OAAO,EAAE,uBAAuB,EAAE,CAAC;CACpC,GACD;IACE,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,aAAa,GAAG,SAAS,CAAC;IAClC,MAAM,EAAE,sBAAsB,EAAE,CAAC;CAClC,CAAC;AAEN,MAAM,MAAM,2BAA2B,GACnC;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GACZ;IACE,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,aAAa,GAAG,iBAAiB,GAAG,eAAe,CAAC;CAC7D,CAAC;AAEN,MAAM,WAAW,wBAAwB;IACvC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC;IACpC;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,yDAAyD;IACzD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,sBAAsB,KAAK,MAAM,CAAC;IACpD,0CAA0C;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oCAAoC;IACpC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,sBAAsB,KAAK,IAAI,CAAC;IAClD,8BAA8B;IAC9B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAcD,qBAAa,iBAAiB;;IAC5B,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAC;gBAOtC,UAAU,EAAE,kBAAkB,EAC9B,OAAO,GAAE,wBAA6B;IAaxC,2DAA2D;IAC3D,IAAI,SAAS,IAAI,sBAAsB,GAAG,IAAI,CAE7C;IAED,oCAAoC;IACpC,OAAO,CAAC,KAAK,EAAE,sBAAsB,GAAG,MAAM;IAI9C,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,8CAA8C;IAC9C,QAAQ,IAAI,mBAAmB;IAW/B,yEAAyE;IACzE,KAAK,CAAC,UAAU,EAAE,OAAO,GAAG,4BAA4B;IA4CxD;;;;OAIG;IACH,IAAI,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,2BAA2B;IAmB9C,yDAAyD;IACzD,OAAO,IAAI,IAAI;IAkBf,0EAA0E;IAC1E,KAAK,IAAI,cAAc,EAAE;CAyF1B;AAED,8DAA8D;AAC9D,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,kBAAkB,EAC9B,OAAO,CAAC,EAAE,wBAAwB,GACjC,iBAAiB,CAEnB;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,iBAAiB,EAC5B,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,SAAS,CAAC,MAAM,GAAG,OAAO,GAAG,aAAa,CAAC,EAAE,CAAA;CAAO,GACxE,IAAI,CAMN"}