@happyvertical/smrt-svelte 0.51.4 → 0.51.6

package/AGENTS.md

@@ -16,6 +16,7 @@ subpath you are editing. This file keeps what holds in every module.
 | `src/components/settings/` (`./settings`) | `SettingsCatalog`, `paginateSettingsCatalog`, and the summary-vs-detail scalability contract | [agents/settings.md](agents/settings.md) |
 | `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/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`) | One-call registration of an existing, non-`DataTable` list (already mirroring a headless `DataTableController`) as a mounted `DataSurfaceDescriptor` — a same-behavior port of `registerContentListDataSurface`'s registration/translation logic (`@happyvertical/smrt-content/svelte`), generalized off ContentList's view-mode concept, so any custom list markup can adopt it directly instead of hand-mirroring the registry contract. Not yet unified behind a shared `@happyvertical/smrt-ui/data` implementation (#2917) — this copy is currently ahead; see its own module doc comment for the current, authoritative list of divergences #2917 must adopt rather than assume parity (#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) | — |
 | `src/web/webmcp-ui.ts` | Fixed, low-cardinality WebMCP adapter over the Provider's mounted form-control and data-surface registries (#2521) | — |
 | `src/web/webmcp.svelte.ts` (`useWebMcpTool`) | Component-owned bespoke WebMCP tool. Routes through `@happyvertical/smrt-web`'s `registerWebMcpBespokeTool`, so it shares the fail-closed effect classification and `effects` exposure policy of generated tools — undeclared `annotations` classify destructive and are excluded by default. `namespace` and `maxTools` never apply to a bespoke tool (#2586) | — |

package/README.md

@@ -144,6 +144,44 @@ should be discoverable:
 </Provider>
 ```
 
+A page with its own hand-rolled list markup — not `DataTable` — that already
+mirrors a headless `DataTableController`'s search/filters/sort/page/selection
+can register that same registry in one call with `mountListDataSurface`
+(`@happyvertical/smrt-svelte/web`) instead of hand-writing the registration:
+
+```ts
+import { createDataTableController } from '@happyvertical/smrt-ui/data';
+import { mountListDataSurface } from '@happyvertical/smrt-svelte/web';
+
+const controller = createDataTableController();
+const handle = mountListDataSurface({
+  registry: surfaces,
+  descriptor: myListDescriptor,
+  controller,
+  context: { totalRows, queryFingerprint },
+  refresh: () => reload(),
+});
+
+// Only `controller` is observed automatically. App-owned `context` is a
+// one-time snapshot at mount — publish a fresh one whenever totalRows,
+// queryFingerprint, or freshness changes (an $effect keyed on those values
+// is the usual place):
+handle.update({ totalRows, queryFingerprint });
+
+// on unmount:
+handle.destroy();
+```
+
+It mirrors `controller` into the registry, translates visible table commands
+back into `controller.dispatch()` calls, and routes the fixed
+`refresh`/`retry`/`focus`/`reveal`/`highlight` controls to callbacks; any
+other `controlId` goes through an `onControl` escape hatch (denied by
+default) — except a canonical table-control id (`set-filters`, `reset`,
+`set-page`, … the full `DATA_TABLE_SURFACE_CONTROL_IDS` list from
+`@happyvertical/smrt-ui/data`), which is always intercepted first and never
+reaches `onControl`, even under a custom label. See
+`docs/data-surface-conformance.md` for the full contract.
+
 The default prefix is `smrt_ui_`. Configure `ui.prefix` when multiple Providers
 must coexist in one document; the same prefix cannot be registered twice. The
 six derived names are reserved through the document-global tool-name lock, so
@@ -306,7 +344,7 @@ importable, even if it appears in `dist/`.
 | `@happyvertical/smrt-svelte/workspace/live` | `systemFeed` — the AdminShell system scope (jobs/schedules/dispatch) polled from an app status endpoint; deliberately carries no `smrt-web` dependency |
 | `@happyvertical/smrt-svelte/browser-ai` | Browser AI client (STT/TTS/LLM adapters, capability detection) |
 | `@happyvertical/smrt-svelte/browser-ai/svelte` | Svelte AI components (VoiceInput, CapabilityGate, etc.) |
-| `@happyvertical/smrt-svelte/web` | `smrt-web` live-query bindings (`liveCollection`, `activityFeed`, `useUpdateAvailable`) |
+| `@happyvertical/smrt-svelte/web` | `smrt-web` live-query bindings (`liveCollection`, `activityFeed`, `useUpdateAvailable`) plus `mountListDataSurface` (custom-list data-surface registration) |
 | `@happyvertical/smrt-svelte/i18n/server` | Server-side i18n resolver (Node only) |
 
 Domain-agnostic UI lives in `@happyvertical/smrt-ui`. There is no `ui`,

package/dist/components/workspace/README.md

@@ -35,6 +35,31 @@ identity and action content belongs in `topLeftCorner` / `topRightCorner`,
 wrapped in `ShellCorner side="left"` or `ShellCorner side="right"` so it follows
 the corresponding shell track as that edge expands and collapses.
 
+## AssistantDock recipe (#2904)
+
+`ShellDockTool` also hosts `@happyvertical/smrt-chat/svelte`'s `AssistantDock`
+— a route-aware assistant surface. This package has no runtime dependency on
+`@happyvertical/smrt-chat` (only a devDependency, for tests); the composition
+below is intentionally application code, not a `workspace/` export:
+
+```svelte
+<script lang="ts">
+  import { ShellDockTool } from '@happyvertical/smrt-svelte/workspace';
+  import { AssistantDock } from '@happyvertical/smrt-chat/svelte';
+</script>
+
+<ShellDockTool id="assistant" label="Assistant" icon="bot">
+  {#snippet render()}
+    <AssistantDock {transport} {registry} />
+  {/snippet}
+</ShellDockTool>
+```
+
+`registry` is the same `DataSurfaceRegistry` instance mounted routes register
+their descriptors on. See
+[`docs/assistant-dock.md`](../../../../../docs/assistant-dock.md) for the full
+design.
+
 ## Migration
 
 See [MIGRATION.md](./MIGRATION.md) for the first-generation workspace migration

package/dist/web/__tests__/assistant-dock.integration.svelte.test.js

@@ -0,0 +1,204 @@
+// @vitest-environment jsdom
+/**
+ * AssistantDock conformance-style integration test (#2904).
+ *
+ * Mirrors `data-surface-conformance.integration.svelte.test.ts` in this
+ * directory: a real `DataSurfaceRegistry` and a real
+ * `createAssistantDockController`/`AssistantDock` are composed together;
+ * only the chat transport and the action client are in-process test doubles
+ * (`createInMemoryAssistantTransport`, and a thin `actionClient` adapter over
+ * the registry's own `execute()`), matching that file's stated scope of
+ * faking only the transport boundary.
+ *
+ * Scope note (disclosed deviation from the original test plan): the action
+ * preview/apply path here is driven directly through
+ * `createAssistantDockController` rather than by having a fake model reply
+ * trigger it through the rendered `AssistantDock` DOM — `AssistantDock` has
+ * no built-in "parse this assistant message as an action proposal" step (no
+ * such parsing is specified anywhere in #2904's binding decisions), so the
+ * host application is expected to call `controller.previewAction(...)` from
+ * its own message-rendering logic. This test still exercises the full
+ * dock (registry discovery, rendering, send/poll) through the DOM, and
+ * separately proves the action pathway (preview → confirm → apply → registry
+ * "command" event) end-to-end against the real registry.
+ */
+import { AssistantDock, createAssistantDockController, createInMemoryAssistantTransport, } from '@happyvertical/smrt-chat/svelte';
+import { createDataSurfaceRegistry, } from '@happyvertical/smrt-ui/data-surface';
+import { render, screen, waitFor } from '@testing-library/svelte';
+import { describe, expect, it } from 'vitest';
+const identity = {
+    surfaceId: 'assistant-dock-orders',
+    kind: 'table',
+    subject: { type: 'tenant', id: 'tenant-a' },
+};
+const descriptor = {
+    version: 1,
+    identity,
+    schemaVersion: 1,
+    label: 'Orders',
+    rowKey: 'id',
+    columns: [
+        {
+            id: 'id',
+            label: 'ID',
+            capabilities: ['read', 'project'],
+            role: 'row-key',
+        },
+    ],
+    query: {
+        modes: ['rows'],
+        projectableColumnIds: ['id'],
+        searchableColumnIds: [],
+        filterableColumnIds: [],
+        sortableColumnIds: [],
+    },
+    actions: [
+        {
+            id: 'archive',
+            label: 'Archive',
+            selectionScopes: ['explicit-ids'],
+            requiresConfirmation: true,
+        },
+    ],
+    controls: [{ id: 'data-surface.action.archive', label: 'Archive' }],
+    limits: { maxQueryRows: 100, maxQueryBytes: 100_000, maxSelectionSize: 100 },
+};
+function mountRegistryWithOneSurface() {
+    const registry = createDataSurfaceRegistry();
+    let revision = 1;
+    const state = { archived: false };
+    const unregister = registry.register({
+        descriptor,
+        getSnapshot: () => ({
+            version: 1,
+            descriptor,
+            revision,
+            state: { archived: state.archived },
+        }),
+        execute: async (command) => {
+            // A minimal real mutation: the "archive" action flips `archived` and
+            // bumps the snapshot revision, which is what makes the registry emit a
+            // 'command' event other mounted UI can react to.
+            state.archived = true;
+            revision += 1;
+            return {
+                version: 1,
+                commandId: command.commandId,
+                identity: command.identity,
+                ok: true,
+                revision,
+            };
+        },
+    });
+    return { registry, unregister, state: () => state.archived };
+}
+describe('AssistantDock integration (#2904)', () => {
+    it('fails closed and shows the no-surfaces notice with an empty registry', async () => {
+        const registry = createDataSurfaceRegistry();
+        const transport = createInMemoryAssistantTransport();
+        render(AssistantDock, { props: { transport, registry } });
+        await waitFor(() => {
+            expect(screen.getByText(/No data surfaces are mounted on this route/i)).toBeInTheDocument();
+        });
+    });
+    it('discovers a mounted surface via the registry and renders a sent conversation', async () => {
+        const { registry } = mountRegistryWithOneSurface();
+        const transport = createInMemoryAssistantTransport({
+            respond: (_threadId, userMessage) => ({
+                id: 'assistant-1',
+                threadId: userMessage.threadId,
+                content: 'Archived the order.',
+                role: 'assistant',
+                createdAt: new Date(),
+            }),
+        });
+        render(AssistantDock, { props: { transport, registry } });
+        await waitFor(() => {
+            expect(screen.queryByText(/No data surfaces are mounted on this route/i)).not.toBeInTheDocument();
+        });
+        const thread = await transport.createThread('Order question');
+        // Drive the same controller the component owns internally by exercising
+        // the transport directly (the composer's own send() path is covered at
+        // the unit level in packages/chat); here we assert the descriptor is
+        // visible to a controller built against this exact registry instance.
+        const controller = createAssistantDockController({ transport, registry });
+        await controller.openThread(thread.id);
+        // Cycle-3 second final finding 1: an attached file must round-trip onto
+        // the sent message, not just the message text — this is the surface
+        // that previously rendered nothing for message.attachments.
+        await controller.send('please archive this order', [
+            { id: 'att-1', name: 'order-details.pdf' },
+        ]);
+        await waitFor(() => {
+            expect(controller.messages.some((m) => m.content === 'Archived the order.')).toBe(true);
+        });
+        const sentMessage = controller.messages.find((m) => m.content === 'please archive this order');
+        expect(sentMessage?.attachments).toEqual([
+            { id: 'att-1', name: 'order-details.pdf' },
+        ]);
+        expect(controller.surfaces).toHaveLength(1);
+        expect(controller.surfaces[0].surfaceId).toBe('assistant-dock-orders');
+        controller.dispose();
+    });
+    it('drives preview → confirm → apply through the real registry and fires its "command" event', async () => {
+        const { registry, state } = mountRegistryWithOneSurface();
+        const events = [];
+        registry.subscribe((event) => events.push(event));
+        const actionClient = {
+            async preview(request) {
+                // A preview never mutates: assert the surface is untouched.
+                expect(state()).toBe(false);
+                return {
+                    version: 1,
+                    requestId: request.requestId,
+                    identity: request.identity,
+                    actionId: request.actionId,
+                    phase: 'preview',
+                    ok: true,
+                    confirmationToken: 'token-1',
+                };
+            },
+            async apply(request) {
+                const result = await registry.execute({
+                    version: 1,
+                    commandId: request.requestId,
+                    identity: request.identity,
+                    expectedRevision: 1,
+                    controlId: `data-surface.action.${request.actionId}`,
+                });
+                return {
+                    version: 1,
+                    requestId: request.requestId,
+                    identity: request.identity,
+                    actionId: request.actionId,
+                    phase: 'apply',
+                    ok: result.ok,
+                    reason: result.ok ? undefined : result.reason,
+                };
+            },
+        };
+        const controller = createAssistantDockController({
+            transport: createInMemoryAssistantTransport(),
+            registry,
+            actionClient,
+        });
+        const requestId = 'archive-req-1';
+        await controller.previewAction({
+            version: 1,
+            requestId,
+            identity,
+            actionId: 'archive',
+            phase: 'preview',
+            selection: { scope: 'explicit-ids', rowIds: ['order-1'] },
+        });
+        expect(controller.actions.get(requestId)?.status).toBe('previewed');
+        expect(state()).toBe(false); // preview never mutated the surface
+        // applyAction now takes only requestId — it reuses the idempotencyKey
+        // minted once by previewAction (binding decision #2904, build phase 2).
+        await controller.applyAction(requestId);
+        expect(controller.actions.get(requestId)?.status).toBe('applied');
+        expect(state()).toBe(true);
+        expect(events.some((e) => e.type === 'command')).toBe(true);
+        controller.dispose();
+    });
+});

package/dist/web/__tests__/list-data-surface.fixture.svelte

@@ -0,0 +1,59 @@
+<script lang="ts">
+import type {
+  DataSurfaceDescriptor,
+  DataSurfaceRegistry,
+  DataTableController,
+} from '@happyvertical/smrt-ui/data';
+import {
+  type ListDataSurfaceContext,
+  mountListDataSurface,
+} from '../list-data-surface.svelte.js';
+
+let {
+  registry,
+  descriptor,
+  controller,
+  context,
+  onRefresh,
+  onStar,
+}: {
+  registry: DataSurfaceRegistry;
+  descriptor: DataSurfaceDescriptor;
+  controller: DataTableController;
+  context: ListDataSurfaceContext;
+  onRefresh?: () => boolean | Promise<boolean>;
+  onStar?: (payload: unknown) => boolean;
+} = $props();
+
+let starredCount = $state(0);
+let filterText = $state('');
+
+$effect(() => {
+  const handle = mountListDataSurface({
+    registry,
+    descriptor,
+    controller,
+    context,
+    refresh: onRefresh,
+    onControl: (controlId, payload) => {
+      if (controlId === 'star') {
+        starredCount += 1;
+        return onStar ? onStar(payload) : true;
+      }
+      return false;
+    },
+  });
+  const unsubscribe = controller.subscribe(() => {
+    filterText = String(controller.getState().filters[0]?.value ?? '');
+  });
+  return () => {
+    unsubscribe();
+    handle.destroy();
+  };
+});
+</script>
+
+<ul data-testid="custom-list">
+  <li data-testid="filter-text">{filterText}</li>
+</ul>
+<p data-testid="starred-count">{starredCount}</p>

package/dist/web/__tests__/list-data-surface.fixture.svelte.d.ts

@@ -0,0 +1,14 @@
+import type { DataSurfaceDescriptor, DataSurfaceRegistry, DataTableController } from '@happyvertical/smrt-ui/data';
+import { type ListDataSurfaceContext } from '../list-data-surface.svelte.js';
+type $$ComponentProps = {
+    registry: DataSurfaceRegistry;
+    descriptor: DataSurfaceDescriptor;
+    controller: DataTableController;
+    context: ListDataSurfaceContext;
+    onRefresh?: () => boolean | Promise<boolean>;
+    onStar?: (payload: unknown) => boolean;
+};
+declare const ListDataSurface: import("svelte").Component<$$ComponentProps, {}, "">;
+type ListDataSurface = ReturnType<typeof ListDataSurface>;
+export default ListDataSurface;
+//# sourceMappingURL=list-data-surface.fixture.svelte.d.ts.map

package/dist/web/__tests__/list-data-surface.fixture.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-data-surface.fixture.svelte.d.ts","sourceRoot":"","sources":["../../../src/web/__tests__/list-data-surface.fixture.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,qBAAqB,EACrB,mBAAmB,EACnB,mBAAmB,EACpB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,KAAK,sBAAsB,EAE5B,MAAM,gCAAgC,CAAC;AAEvC,KAAK,gBAAgB,GAAI;IACxB,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,UAAU,EAAE,qBAAqB,CAAC;IAClC,UAAU,EAAE,mBAAmB,CAAC;IAChC,OAAO,EAAE,sBAAsB,CAAC;IAChC,SAAS,CAAC,EAAE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7C,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC;CACxC,CAAC;AAiDF,QAAA,MAAM,eAAe,sDAAwC,CAAC;AAC9D,KAAK,eAAe,GAAG,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC;AAC1D,eAAe,eAAe,CAAC"}

package/dist/web/__tests__/list-data-surface.svelte.test.js

@@ -0,0 +1,106 @@
+/**
+ * Component-lifecycle proof for `mountListDataSurface` (#2906), in the same
+ * conformance style as `data-surface-conformance.integration.svelte.test.ts`:
+ * a real Svelte component mounts a custom (non-DataTable) list, the registry
+ * drives it with commands, and unmounting the component tears the
+ * registration down. The registration/translation logic itself is unit
+ * tested directly against the registry in `list-data-surface.test.ts`.
+ */
+import { createDataSurfaceRegistry, createDataTableController, } from '@happyvertical/smrt-ui/data';
+import { render, screen } from '@testing-library/svelte';
+import { describe, expect, it, vi } from 'vitest';
+import Fixture from './list-data-surface.fixture.svelte';
+const identity = {
+    surfaceId: 'fixture-list',
+    kind: 'list',
+};
+function descriptor() {
+    return {
+        version: 1,
+        identity,
+        schemaVersion: 1,
+        label: 'Fixture list',
+        rowKey: 'id',
+        columns: [
+            { id: 'id', label: 'ID', capabilities: ['read', 'project'] },
+            {
+                id: 'title',
+                label: 'Title',
+                capabilities: ['read', 'search', 'filter', 'sort', 'project'],
+                operators: { filter: ['contains'] },
+            },
+        ],
+        query: {
+            modes: ['rows', 'count'],
+            projectableColumnIds: ['id', 'title'],
+            filterableColumnIds: ['title'],
+            sortableColumnIds: ['title'],
+        },
+        controls: [
+            { id: 'set-filters', label: 'Filter' },
+            { id: 'refresh', label: 'Refresh' },
+            { id: 'star', label: 'Star selected' },
+        ],
+        actions: [],
+        limits: { maxQueryRows: 50, maxQueryBytes: 10_000, maxSelectionSize: 5 },
+    };
+}
+describe('mountListDataSurface (component integration)', () => {
+    it('drives a mounted custom list from the registry and tears down on unmount', async () => {
+        const registry = createDataSurfaceRegistry();
+        const controller = createDataTableController();
+        const onRefresh = vi.fn().mockResolvedValue(true);
+        const { unmount } = render(Fixture, {
+            props: {
+                registry,
+                descriptor: descriptor(),
+                controller,
+                context: { totalRows: 3, queryFingerprint: 'fixture-1' },
+                onRefresh,
+            },
+        });
+        expect(screen.getByTestId('filter-text').textContent).toBe('');
+        const before = registry.inspect(identity);
+        expect(before?.state.totalRows).toBe(3);
+        const filtered = await registry.execute({
+            version: 1,
+            commandId: 'filter-1',
+            identity,
+            expectedRevision: before?.revision ?? 0,
+            controlId: 'set-filters',
+            payload: {
+                filters: [{ columnId: 'title', operator: 'contains', value: 'draft' }],
+            },
+        });
+        expect(filtered.ok).toBe(true);
+        expect(screen.getByTestId('filter-text').textContent).toBe('draft');
+        const refreshed = await registry.execute({
+            version: 1,
+            commandId: 'refresh-1',
+            identity,
+            expectedRevision: registry.inspect(identity)?.revision ?? 0,
+            controlId: 'refresh',
+        });
+        expect(refreshed.ok).toBe(true);
+        expect(onRefresh).toHaveBeenCalledOnce();
+        const starred = await registry.execute({
+            version: 1,
+            commandId: 'star-1',
+            identity,
+            expectedRevision: registry.inspect(identity)?.revision ?? 0,
+            controlId: 'star',
+        });
+        expect(starred.ok).toBe(true);
+        expect(screen.getByTestId('starred-count').textContent).toBe('1');
+        unmount();
+        // Unmounting tore down the mounted surface — the identity is gone.
+        expect(registry.inspect(identity)).toBeUndefined();
+        await expect(registry.execute({
+            version: 1,
+            commandId: 'after-unmount',
+            identity,
+            expectedRevision: 0,
+            controlId: 'refresh',
+        })).resolves.toMatchObject({ ok: false, reason: 'not_found' });
+    });
+});