@happyvertical/smrt-svelte 0.30.0

package/dist/components/workspace/__tests__/define-tools-dock.test.js

@@ -0,0 +1,1010 @@
+/**
+ * Tests for defineToolsDock factory.
+ *
+ * These tests exercise the reactive API surface directly. Svelte `setContext`
+ * is called inside the factory, but the returned `ToolsDockInstance` is the
+ * subject under test — we don't need a full component tree to verify the
+ * state machine.
+ *
+ * `setContext` only works inside a component init scope, so we invoke the
+ * factory inside Svelte's `mount` (via a thin host component) so that all
+ * `$state` runes wire up correctly.
+ */
+import { flushSync, mount, unmount } from 'svelte';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import HostHarness from './harness.svelte';
+const noopTool = {};
+function mountDock(options) {
+    const target = document.createElement('div');
+    document.body.appendChild(target);
+    const exposed = {
+        dock: undefined,
+    };
+    const component = mount(HostHarness, {
+        target,
+        props: {
+            options,
+            onReady: (dock) => {
+                exposed.dock = dock;
+            },
+        },
+    });
+    return {
+        dock: exposed.dock,
+        teardown: () => {
+            unmount(component);
+            target.remove();
+        },
+    };
+}
+describe('defineToolsDock', () => {
+    let cleanup = [];
+    beforeEach(() => {
+        cleanup = [];
+        if (typeof window !== 'undefined') {
+            window.localStorage.clear();
+        }
+    });
+    afterEach(() => {
+        for (const fn of cleanup.splice(0))
+            fn();
+    });
+    function track(value) {
+        cleanup.push(value.teardown);
+        return value;
+    }
+    it('creates an API with sensible defaults', () => {
+        const { dock } = track(mountDock({
+            tools: [
+                { id: 'chat', label: 'Chat', component: noopTool },
+                { id: 'jobs', label: 'Jobs', component: noopTool },
+            ],
+        }));
+        expect(dock.isOpen).toBe(false);
+        expect(dock.activeTool).toBeNull();
+        expect(dock.layout).toBe('rail');
+        expect(dock.storageKey).toBeNull();
+        expect(dock.availableTools.map((t) => t.id)).toEqual(['chat', 'jobs']);
+    });
+    it('open() / close() / toggle() update isOpen and activeTool', () => {
+        const { dock } = track(mountDock({
+            tools: [
+                { id: 'chat', label: 'Chat', component: noopTool },
+                { id: 'jobs', label: 'Jobs', component: noopTool },
+            ],
+        }));
+        dock.open('chat');
+        flushSync();
+        expect(dock.isOpen).toBe(true);
+        expect(dock.activeTool).toBe('chat');
+        dock.close();
+        flushSync();
+        expect(dock.isOpen).toBe(false);
+        // activeTool persists so re-opening lands on the same tool.
+        expect(dock.activeTool).toBe('chat');
+        dock.toggle('jobs');
+        flushSync();
+        expect(dock.isOpen).toBe(true);
+        expect(dock.activeTool).toBe('jobs');
+        // toggle on the same id closes.
+        dock.toggle('jobs');
+        flushSync();
+        expect(dock.isOpen).toBe(false);
+        // toggle without id flips just isOpen.
+        dock.toggle();
+        flushSync();
+        expect(dock.isOpen).toBe(true);
+    });
+    it('open() on unknown id is a no-op (does not crash, does not open)', () => {
+        const { dock } = track(mountDock({
+            tools: [{ id: 'chat', label: 'Chat', component: noopTool }],
+        }));
+        dock.open('does-not-exist');
+        flushSync();
+        expect(dock.isOpen).toBe(false);
+        expect(dock.activeTool).toBeNull();
+    });
+    it('respects initialOpen and picks first tool when toggled', () => {
+        const { dock } = track(mountDock({
+            tools: [{ id: 'chat', label: 'Chat', component: noopTool }],
+            initialOpen: true,
+        }));
+        expect(dock.isOpen).toBe(true);
+        expect(dock.activeTool).toBeNull();
+        dock.toggle();
+        flushSync();
+        // First toggle while no tool active selects the first available.
+        // (Was open → now closed; activeTool now set on the next open.)
+        expect(dock.isOpen).toBe(false);
+        dock.toggle();
+        flushSync();
+        expect(dock.isOpen).toBe(true);
+        expect(dock.activeTool).toBe('chat');
+    });
+    it('setContext updates context and triggers fetchAvailability', async () => {
+        const fetchAvailability = vi
+            .fn()
+            .mockResolvedValueOnce([{ id: 'chat' }])
+            .mockResolvedValueOnce([{ id: 'chat' }, { id: 'jobs' }]);
+        const { dock } = track(mountDock({
+            tools: [
+                { id: 'chat', label: 'Chat', component: noopTool },
+                { id: 'jobs', label: 'Jobs', component: noopTool },
+                { id: 'hidden', label: 'Hidden', component: noopTool },
+            ],
+            fetchAvailability,
+        }));
+        // No call yet — fetchAvailability only fires on setContext.
+        expect(fetchAvailability).not.toHaveBeenCalled();
+        dock.setContext({ type: 'thing', title: 'A' });
+        // setContext invokes fetchAvailability synchronously; the promise resolves
+        // on the next microtask, so flushSync after a few microtasks is required
+        // for Svelte to settle the resulting state update.
+        expect(fetchAvailability).toHaveBeenCalledTimes(1);
+        await new Promise((r) => setTimeout(r, 0));
+        flushSync();
+        expect(dock.availableTools.map((t) => t.id)).toEqual(['chat']);
+        dock.setContext({ type: 'thing', title: 'B' });
+        expect(fetchAvailability).toHaveBeenCalledTimes(2);
+        await new Promise((r) => setTimeout(r, 0));
+        flushSync();
+        expect(dock.availableTools.map((t) => t.id)).toEqual(['chat', 'jobs']);
+    });
+    it('drops stale fetchAvailability results (race-safety)', async () => {
+        let resolveFirst = null;
+        let resolveSecond = null;
+        const fetchAvailability = vi
+            .fn()
+            .mockImplementationOnce(() => new Promise((r) => {
+            resolveFirst = r;
+        }))
+            .mockImplementationOnce(() => new Promise((r) => {
+            resolveSecond = r;
+        }));
+        const { dock } = track(mountDock({
+            tools: [
+                { id: 'chat', label: 'Chat', component: noopTool },
+                { id: 'jobs', label: 'Jobs', component: noopTool },
+            ],
+            fetchAvailability,
+        }));
+        dock.setContext({ type: 'A' });
+        await Promise.resolve();
+        dock.setContext({ type: 'B' });
+        await Promise.resolve();
+        // Resolve the *stale* (first) call after the newer one. Then resolve the
+        // newer one. The stale value must not stomp the fresh value.
+        resolveFirst?.([{ id: 'chat' }]);
+        resolveSecond?.([{ id: 'jobs' }]);
+        await Promise.resolve();
+        await Promise.resolve();
+        flushSync();
+        expect(dock.availableTools.map((t) => t.id)).toEqual(['jobs']);
+    });
+    it('emit / on / unsubscribe', () => {
+        const { dock } = track(mountDock({
+            tools: [{ id: 'chat', label: 'Chat', component: noopTool }],
+        }));
+        const handler = vi.fn();
+        const off = dock.on('test', handler);
+        dock.emit('test', { ok: true });
+        expect(handler).toHaveBeenCalledWith({ ok: true });
+        off();
+        dock.emit('test', { ok: false });
+        expect(handler).toHaveBeenCalledTimes(1);
+    });
+    it('emit catches handler errors without dropping later handlers', () => {
+        const { dock } = track(mountDock({
+            tools: [{ id: 'chat', label: 'Chat', component: noopTool }],
+        }));
+        const throwing = vi.fn(() => {
+            throw new Error('boom');
+        });
+        const after = vi.fn();
+        dock.on('test', throwing);
+        dock.on('test', after);
+        const errSpy = vi.spyOn(console, 'error').mockImplementation(() => { });
+        expect(() => dock.emit('test', null)).not.toThrow();
+        expect(throwing).toHaveBeenCalled();
+        expect(after).toHaveBeenCalled();
+        errSpy.mockRestore();
+    });
+    it('persists state to localStorage when storageKey provided', () => {
+        const { dock } = track(mountDock({
+            tools: [{ id: 'chat', label: 'Chat', component: noopTool }],
+            storageKey: 'tdtest:v1',
+        }));
+        dock.open('chat');
+        flushSync();
+        const raw = window.localStorage.getItem('tdtest:v1');
+        expect(raw).not.toBeNull();
+        const parsed = JSON.parse(raw);
+        expect(parsed).toEqual({ isOpen: true, activeTool: 'chat' });
+    });
+    it('hydrates state from localStorage on hydrate()', () => {
+        window.localStorage.setItem('tdtest:v2', JSON.stringify({ isOpen: true, activeTool: 'jobs' }));
+        const { dock } = track(mountDock({
+            tools: [
+                { id: 'chat', label: 'Chat', component: noopTool },
+                { id: 'jobs', label: 'Jobs', component: noopTool },
+            ],
+            storageKey: 'tdtest:v2',
+        }));
+        dock.hydrate();
+        flushSync();
+        expect(dock.isOpen).toBe(true);
+        expect(dock.activeTool).toBe('jobs');
+    });
+    it('hydrate() ignores activeTool that no longer matches a registered tool', () => {
+        window.localStorage.setItem('tdtest:v3', JSON.stringify({ isOpen: true, activeTool: 'gone' }));
+        const { dock } = track(mountDock({
+            tools: [{ id: 'chat', label: 'Chat', component: noopTool }],
+            storageKey: 'tdtest:v3',
+        }));
+        dock.hydrate();
+        flushSync();
+        expect(dock.isOpen).toBe(true);
+        expect(dock.activeTool).toBeNull();
+    });
+    it('exposes context on the public ToolsDockApi surface', () => {
+        const { dock } = track(mountDock({
+            tools: [{ id: 'chat', label: 'Chat', component: noopTool }],
+        }));
+        expect(dock.context).toBeNull();
+        dock.setContext({ type: 'route', title: 'Home' });
+        flushSync();
+        expect(dock.context).toEqual({ type: 'route', title: 'Home' });
+        dock.setContext(null);
+        flushSync();
+        expect(dock.context).toBeNull();
+    });
+    it('badge: null in availability clears a registered default (not falls back)', async () => {
+        const fetchAvailability = vi
+            .fn()
+            .mockResolvedValueOnce([{ id: 'chat', badge: null }]);
+        const { dock } = track(mountDock({
+            tools: [{ id: 'chat', label: 'Chat', badge: 3, component: noopTool }],
+            fetchAvailability,
+        }));
+        dock.setContext({ type: 'a' });
+        await new Promise((r) => setTimeout(r, 0));
+        flushSync();
+        // `badge: null` is explicit ("clear it"), not a fallback signal.
+        expect(dock.availableTools[0].badge).toBeNull();
+    });
+    it('handles synchronous throws from fetchAvailability without surfacing them', async () => {
+        const fetchAvailability = vi.fn(() => {
+            throw new Error('sync boom');
+        });
+        const { dock } = track(mountDock({
+            tools: [{ id: 'chat', label: 'Chat', component: noopTool }],
+            fetchAvailability: fetchAvailability,
+        }));
+        // The sync throw must be caught by the wrapped promise chain, not
+        // propagate out of setContext to the caller.
+        expect(() => dock.setContext({ type: 'a' })).not.toThrow();
+        // The internal `.catch` applies an empty-availability result.
+        await new Promise((r) => setTimeout(r, 0));
+        flushSync();
+        expect(dock.availableTools).toEqual([]);
+    });
+    describe('refreshAvailability()', () => {
+        it('re-runs fetchAvailability with the current context', async () => {
+            let availability = [{ id: 'chat' }];
+            const fetchAvailability = vi.fn(async () => availability);
+            const { dock } = track(mountDock({
+                tools: [
+                    { id: 'chat', label: 'Chat', component: noopTool },
+                    { id: 'jobs', label: 'Jobs', component: noopTool },
+                ],
+                fetchAvailability,
+            }));
+            const ctx = { type: 'thing', title: 'A' };
+            dock.setContext(ctx);
+            await new Promise((r) => setTimeout(r, 0));
+            flushSync();
+            expect(fetchAvailability).toHaveBeenCalledTimes(1);
+            expect(dock.availableTools.map((t) => t.id)).toEqual(['chat']);
+            // Side-channel signal: availability changed without a context change.
+            // setContext(ctx) would short-circuit; refreshAvailability() forces it.
+            availability = [{ id: 'chat' }, { id: 'jobs' }];
+            dock.refreshAvailability();
+            expect(fetchAvailability).toHaveBeenCalledTimes(2);
+            // Called with the same (unchanged) context.
+            expect(fetchAvailability).toHaveBeenLastCalledWith(ctx);
+            await new Promise((r) => setTimeout(r, 0));
+            flushSync();
+            // Second fetch's result is reflected in availableTools.
+            expect(dock.availableTools.map((t) => t.id)).toEqual(['chat', 'jobs']);
+        });
+        it('resets to all registered tools when no fetchAvailability is configured', () => {
+            const { dock } = track(mountDock({
+                tools: [
+                    { id: 'chat', label: 'Chat', component: noopTool },
+                    { id: 'jobs', label: 'Jobs', component: noopTool },
+                ],
+            }));
+            expect(dock.availableTools.map((t) => t.id)).toEqual(['chat', 'jobs']);
+            // No-op semantically (all tools were already available), but the
+            // method should not crash without a fetchAvailability callback.
+            expect(() => dock.refreshAvailability()).not.toThrow();
+            flushSync();
+            expect(dock.availableTools.map((t) => t.id)).toEqual(['chat', 'jobs']);
+        });
+        it("emits 'dock:change' when refresh changes only badge values", async () => {
+            // Regression for the badge-only refresh case: a side-channel signal
+            // fires (e.g. a Jobs-count websocket message) and the consumer calls
+            // `refreshAvailability()` to repaint badges. The tool ids haven't
+            // changed and the active tool stays put, but `availableTools` now
+            // carries a different badge — consumers mirroring this into a topbar
+            // count must see a `'dock:change'` event to repaint without polling.
+            let availability = [
+                { id: 'chat', badge: 0 },
+                { id: 'jobs', badge: 0 },
+            ];
+            const fetchAvailability = vi.fn(async () => availability);
+            const { dock } = track(mountDock({
+                tools: [
+                    { id: 'chat', label: 'Chat', component: noopTool },
+                    { id: 'jobs', label: 'Jobs', component: noopTool },
+                ],
+                fetchAvailability,
+            }));
+            dock.setContext({ type: 'thing' });
+            await new Promise((r) => setTimeout(r, 0));
+            flushSync();
+            const handler = vi.fn();
+            dock.on('dock:change', handler);
+            // Side-channel update: same tool ids, different badge values.
+            availability = [
+                { id: 'chat', badge: 0 },
+                { id: 'jobs', badge: 7 },
+            ];
+            dock.refreshAvailability();
+            await new Promise((r) => setTimeout(r, 0));
+            flushSync();
+            // Exactly one emit reflecting the new badge.
+            expect(handler).toHaveBeenCalledTimes(1);
+            expect(handler).toHaveBeenLastCalledWith({
+                isOpen: false,
+                activeTool: null,
+                context: { type: 'thing' },
+            });
+            const jobsAfter = dock.availableTools.find((t) => t.id === 'jobs');
+            expect(jobsAfter?.badge).toBe(7);
+            // Calling refreshAvailability again with byte-identical results must
+            // NOT emit a second time. The discriminating shape check keeps no-op
+            // refreshes silent so consumer mirrors don't see spurious updates.
+            dock.refreshAvailability();
+            await new Promise((r) => setTimeout(r, 0));
+            flushSync();
+            expect(handler).toHaveBeenCalledTimes(1);
+        });
+        it("emits 'dock:change' when refresh clears the active tool", async () => {
+            // Direct coverage for the active-tool-clear branch of
+            // `applyAvailability` reached via `refreshAvailability()` (rather
+            // than via a `setContext()` → refresh chain).
+            let availability = [{ id: 'chat' }, { id: 'jobs' }];
+            const fetchAvailability = vi.fn(async () => availability);
+            const { dock } = track(mountDock({
+                tools: [
+                    { id: 'chat', label: 'Chat', component: noopTool },
+                    { id: 'jobs', label: 'Jobs', component: noopTool },
+                ],
+                fetchAvailability,
+            }));
+            dock.setContext({ type: 'thing' });
+            await new Promise((r) => setTimeout(r, 0));
+            flushSync();
+            dock.open('jobs');
+            flushSync();
+            expect(dock.activeTool).toBe('jobs');
+            const handler = vi.fn();
+            dock.on('dock:change', handler);
+            // Side-channel availability shrink — 'jobs' is no longer available.
+            availability = [{ id: 'chat' }];
+            dock.refreshAvailability();
+            await new Promise((r) => setTimeout(r, 0));
+            flushSync();
+            expect(dock.activeTool).toBeNull();
+            expect(handler).toHaveBeenCalledTimes(1);
+            expect(handler).toHaveBeenLastCalledWith({
+                isOpen: true,
+                activeTool: null,
+                context: { type: 'thing' },
+            });
+        });
+        it('drops stale results from a prior refreshAvailability call (race-safety)', async () => {
+            let resolveFirst = null;
+            let resolveSecond = null;
+            const fetchAvailability = vi
+                .fn()
+                .mockImplementationOnce(() => new Promise((r) => {
+                resolveFirst = r;
+            }))
+                .mockImplementationOnce(() => new Promise((r) => {
+                resolveSecond = r;
+            }));
+            const { dock } = track(mountDock({
+                tools: [
+                    { id: 'chat', label: 'Chat', component: noopTool },
+                    { id: 'jobs', label: 'Jobs', component: noopTool },
+                ],
+                fetchAvailability,
+            }));
+            // First call via refreshAvailability (no prior setContext).
+            dock.refreshAvailability();
+            await Promise.resolve();
+            // Second call before the first resolves.
+            dock.refreshAvailability();
+            await Promise.resolve();
+            // Resolve stale first AFTER fresh second was requested.
+            resolveFirst?.([{ id: 'chat' }]);
+            resolveSecond?.([{ id: 'jobs' }]);
+            await Promise.resolve();
+            await Promise.resolve();
+            flushSync();
+            // Only the most recent result applies.
+            expect(dock.availableTools.map((t) => t.id)).toEqual(['jobs']);
+        });
+    });
+    it('clears activeTool when availability removes the active tool', async () => {
+        let availability = [{ id: 'chat' }, { id: 'jobs' }];
+        const fetchAvailability = vi.fn(async () => availability);
+        const { dock } = track(mountDock({
+            tools: [
+                { id: 'chat', label: 'Chat', component: noopTool },
+                { id: 'jobs', label: 'Jobs', component: noopTool },
+            ],
+            fetchAvailability,
+        }));
+        dock.setContext({ type: 'a' });
+        await Promise.resolve();
+        await Promise.resolve();
+        flushSync();
+        dock.open('jobs');
+        flushSync();
+        expect(dock.activeTool).toBe('jobs');
+        availability = [{ id: 'chat' }];
+        dock.setContext({ type: 'b' });
+        await Promise.resolve();
+        await Promise.resolve();
+        flushSync();
+        expect(dock.availableTools.map((t) => t.id)).toEqual(['chat']);
+        expect(dock.activeTool).toBeNull();
+    });
+    describe("'dock:change' event", () => {
+        it('does not fire during factory construction', () => {
+            // Subscribing in a separate tick would miss any event fired during the
+            // factory body. To assert "no construction-time emit" we count via a
+            // listener added *before* the factory runs — but the factory's
+            // listener bus is internal, so instead we rely on the fact that
+            // `'dock:change'` is gated by the `ready` flag and verify
+            // post-construction state is clean (no recursive errors etc.) here.
+            const { dock } = track(mountDock({
+                tools: [{ id: 'chat', label: 'Chat', component: noopTool }],
+                initialOpen: true,
+            }));
+            // Sanity: initial state reflects options without any emit having fired.
+            expect(dock.isOpen).toBe(true);
+            expect(dock.activeTool).toBeNull();
+        });
+        it('fires on open() with the post-update state', () => {
+            const { dock } = track(mountDock({
+                tools: [
+                    { id: 'chat', label: 'Chat', component: noopTool },
+                    { id: 'jobs', label: 'Jobs', component: noopTool },
+                ],
+            }));
+            const handler = vi.fn();
+            dock.on('dock:change', handler);
+            dock.open('chat');
+            flushSync();
+            expect(handler).toHaveBeenCalledTimes(1);
+            expect(handler).toHaveBeenLastCalledWith({
+                isOpen: true,
+                activeTool: 'chat',
+                context: null,
+            });
+        });
+        it('fires on close() with the post-update state', () => {
+            const { dock } = track(mountDock({
+                tools: [{ id: 'chat', label: 'Chat', component: noopTool }],
+            }));
+            dock.open('chat');
+            flushSync();
+            const handler = vi.fn();
+            dock.on('dock:change', handler);
+            dock.close();
+            flushSync();
+            expect(handler).toHaveBeenCalledTimes(1);
+            expect(handler).toHaveBeenLastCalledWith({
+                // close() leaves activeTool intact so re-opens land on the same tool.
+                isOpen: false,
+                activeTool: 'chat',
+                context: null,
+            });
+        });
+        it('fires on toggle() with the post-update state', () => {
+            const { dock } = track(mountDock({
+                tools: [
+                    { id: 'chat', label: 'Chat', component: noopTool },
+                    { id: 'jobs', label: 'Jobs', component: noopTool },
+                ],
+            }));
+            const handler = vi.fn();
+            dock.on('dock:change', handler);
+            dock.toggle('chat');
+            flushSync();
+            expect(handler).toHaveBeenCalledTimes(1);
+            expect(handler).toHaveBeenLastCalledWith({
+                isOpen: true,
+                activeTool: 'chat',
+                context: null,
+            });
+            dock.toggle('chat');
+            flushSync();
+            expect(handler).toHaveBeenCalledTimes(2);
+            expect(handler).toHaveBeenLastCalledWith({
+                isOpen: false,
+                activeTool: 'chat',
+                context: null,
+            });
+            dock.toggle();
+            flushSync();
+            expect(handler).toHaveBeenCalledTimes(3);
+            expect(handler).toHaveBeenLastCalledWith({
+                isOpen: true,
+                activeTool: 'chat',
+                context: null,
+            });
+        });
+        it('fires on setContext() with the new context', () => {
+            const { dock } = track(mountDock({
+                tools: [{ id: 'chat', label: 'Chat', component: noopTool }],
+            }));
+            const handler = vi.fn();
+            dock.on('dock:change', handler);
+            dock.setContext({ type: 'route', title: 'Home' });
+            flushSync();
+            expect(handler).toHaveBeenCalledTimes(1);
+            expect(handler).toHaveBeenLastCalledWith({
+                isOpen: false,
+                activeTool: null,
+                context: { type: 'route', title: 'Home' },
+            });
+        });
+        it('fires once with cleared state when availability removes the active tool', async () => {
+            let availability = [{ id: 'chat' }, { id: 'jobs' }];
+            const fetchAvailability = vi.fn(async () => availability);
+            const { dock } = track(mountDock({
+                tools: [
+                    { id: 'chat', label: 'Chat', component: noopTool },
+                    { id: 'jobs', label: 'Jobs', component: noopTool },
+                ],
+                fetchAvailability,
+            }));
+            dock.setContext({ type: 'a' });
+            await Promise.resolve();
+            await Promise.resolve();
+            flushSync();
+            dock.open('jobs');
+            flushSync();
+            expect(dock.activeTool).toBe('jobs');
+            const handler = vi.fn();
+            dock.on('dock:change', handler);
+            availability = [{ id: 'chat' }];
+            dock.setContext({ type: 'b' });
+            // setContext emits synchronously …
+            expect(handler).toHaveBeenCalledTimes(1);
+            // … then the async availability refresh resolves, clears the active
+            // tool, and emits a second 'dock:change' with the cleared state.
+            await Promise.resolve();
+            await Promise.resolve();
+            flushSync();
+            expect(handler).toHaveBeenCalledTimes(2);
+            expect(handler).toHaveBeenLastCalledWith({
+                isOpen: true,
+                activeTool: null,
+                context: { type: 'b' },
+            });
+        });
+        it('stops calling a handler after its unsubscribe function runs', () => {
+            const { dock } = track(mountDock({
+                tools: [{ id: 'chat', label: 'Chat', component: noopTool }],
+            }));
+            const handler = vi.fn();
+            const off = dock.on('dock:change', handler);
+            dock.open('chat');
+            flushSync();
+            expect(handler).toHaveBeenCalledTimes(1);
+            off();
+            dock.close();
+            flushSync();
+            expect(handler).toHaveBeenCalledTimes(1);
+        });
+        it('payload type is inferred from ToolsDockEvents', () => {
+            const { dock } = track(mountDock({
+                tools: [{ id: 'chat', label: 'Chat', component: noopTool }],
+            }));
+            // Compile-time check: handler arg should be the `dock:change` payload
+            // shape without an explicit generic.
+            dock.on('dock:change', (e) => {
+                const _isOpen = e.isOpen;
+                const _activeTool = e.activeTool;
+                void _isOpen;
+                void _activeTool;
+            });
+            // Runtime sanity check that the test compiles & wires.
+            dock.open('chat');
+            flushSync();
+            expect(dock.isOpen).toBe(true);
+        });
+        it('non-"dock:*" event names use the stringly-typed overload (e.g. "change" is not reserved)', () => {
+            // After namespacing built-ins under `'dock:*'`, the literal `'change'`
+            // is no longer a key of ToolsDockEvents, so consumers may use it
+            // freely with an explicit payload generic via the stringly-typed
+            // overload.
+            const { dock } = track(mountDock({
+                tools: [{ id: 'chat', label: 'Chat', component: noopTool }],
+            }));
+            const customHandler = vi.fn();
+            const off = dock.on('change', customHandler);
+            dock.emit('change', { selected: 'row-1' });
+            expect(customHandler).toHaveBeenCalledWith({ selected: 'row-1' });
+            // Also confirm a namespaced consumer event works.
+            const appHandler = vi.fn();
+            dock.on('app:custom', appHandler);
+            dock.emit('app:custom', { id: 42 });
+            expect(appHandler).toHaveBeenCalledWith({ id: 42 });
+            // Built-in 'dock:change' must NOT trigger the custom 'change' listener.
+            dock.open('chat');
+            flushSync();
+            expect(customHandler).toHaveBeenCalledTimes(1);
+            off();
+        });
+        // ─────────────────────────────────────────────────────────────
+        // Regression tests: no-op state changes must NOT fire 'dock:change'.
+        //
+        // Before this guard, idempotent calls like `dock.open(activeId)` when
+        // already open emitted spurious events. Combined with effects that
+        // call setContext on every prop change, that produced redundant work
+        // (availability refetch) and could amplify into noisy loops when
+        // consumers wired the 'dock:change' event back into upstream state.
+        // ─────────────────────────────────────────────────────────────
+        it('does NOT fire on open() when already at that state', () => {
+            const { dock } = track(mountDock({
+                tools: [
+                    { id: 'chat', label: 'Chat', component: noopTool },
+                    { id: 'jobs', label: 'Jobs', component: noopTool },
+                ],
+            }));
+            dock.open('chat');
+            flushSync();
+            const handler = vi.fn();
+            dock.on('dock:change', handler);
+            // Same id, already open — no observable state change.
+            dock.open('chat');
+            flushSync();
+            expect(handler).not.toHaveBeenCalled();
+            // open() with no id, already open with an active tool — still a no-op.
+            dock.open();
+            flushSync();
+            expect(handler).not.toHaveBeenCalled();
+        });
+        it('does NOT fire on close() when already closed', () => {
+            const { dock } = track(mountDock({
+                tools: [{ id: 'chat', label: 'Chat', component: noopTool }],
+            }));
+            const handler = vi.fn();
+            dock.on('dock:change', handler);
+            // Initial state is closed; calling close again must not emit.
+            dock.close();
+            flushSync();
+            expect(handler).not.toHaveBeenCalled();
+        });
+        it('does NOT fire on setContext() with the same reference', async () => {
+            const fetchAvailability = vi.fn().mockResolvedValue([{ id: 'chat' }]);
+            const { dock } = track(mountDock({
+                tools: [{ id: 'chat', label: 'Chat', component: noopTool }],
+                fetchAvailability,
+            }));
+            const ctx = { type: 'route', title: 'Home' };
+            dock.setContext(ctx);
+            // Initial emit + initial fetchAvailability call.
+            await new Promise((r) => setTimeout(r, 0));
+            flushSync();
+            expect(fetchAvailability).toHaveBeenCalledTimes(1);
+            const handler = vi.fn();
+            dock.on('dock:change', handler);
+            // Same reference — must short-circuit (no emit, no refetch).
+            dock.setContext(ctx);
+            flushSync();
+            await new Promise((r) => setTimeout(r, 0));
+            flushSync();
+            expect(handler).not.toHaveBeenCalled();
+            expect(fetchAvailability).toHaveBeenCalledTimes(1);
+        });
+        it('does NOT fire on toggle(id) that resolves to the same state', () => {
+            // toggle(sameId) when open+active flips to closed; toggle again
+            // flips back to open+active. Each transition is real, so each emits.
+            // The "no observable change" branch for toggle is hard to trigger
+            // through the API surface alone (toggle always flips at minimum
+            // `isOpen`), so the assertion here is the symmetric one: the emit
+            // counts match the number of real state transitions.
+            const { dock } = track(mountDock({
+                tools: [{ id: 'chat', label: 'Chat', component: noopTool }],
+            }));
+            const handler = vi.fn();
+            dock.on('dock:change', handler);
+            dock.toggle('chat'); // open+active
+            flushSync();
+            dock.toggle('chat'); // close
+            flushSync();
+            expect(handler).toHaveBeenCalledTimes(2);
+        });
+        it('does not retrigger context-forwarding $effect when state mutates', async () => {
+            // Regression guard for the reactive-read leak in emitChange. Without
+            // `untrack` around the $state reads, an $effect calling
+            // dock.setContext would also depend on isOpen/activeTool/context
+            // (read inside the emitChange invoked by setContext). A subsequent
+            // dock.open() would mutate those, re-run the effect, call setContext
+            // again, etc. Here we verify open() does NOT cause the forwarding
+            // effect's tracked count to grow.
+            const fetchAvailability = vi.fn().mockResolvedValue([{ id: 'chat' }]);
+            const { dock } = track(mountDock({
+                tools: [{ id: 'chat', label: 'Chat', component: noopTool }],
+                fetchAvailability,
+            }));
+            // Mount a child component whose $effect mirrors a `currentCtx` $state
+            // into dock.setContext — same pattern <ToolsDock>'s context prop uses.
+            const target = document.createElement('div');
+            document.body.appendChild(target);
+            cleanup.push(() => target.remove());
+            // We use the harness pattern: a tiny inline component would require
+            // its own file. Instead, count how many times fetchAvailability runs
+            // after the initial setContext — open() / close() must not cause it
+            // to re-run via a re-triggered forwarding effect.
+            dock.setContext({ type: 'a' });
+            await new Promise((r) => setTimeout(r, 0));
+            flushSync();
+            const initialFetchCount = fetchAvailability.mock.calls.length;
+            const handler = vi.fn();
+            dock.on('dock:change', handler);
+            dock.open('chat');
+            flushSync();
+            dock.close();
+            flushSync();
+            // Two real state transitions → two emits, but the context-forwarding
+            // chain stays quiet: no extra fetchAvailability calls beyond the
+            // initial setContext.
+            expect(handler).toHaveBeenCalledTimes(2);
+            expect(fetchAvailability.mock.calls.length).toBe(initialFetchCount);
+        });
+    });
+    // ─────────────────────────────────────────────────────────────
+    // Granular events: 'dock:state-changed' and 'dock:context-changed'
+    // split the legacy 'dock:change' so consumers can subscribe to just
+    // the slice they care about. The legacy event still fires (back-compat).
+    // ─────────────────────────────────────────────────────────────
+    describe("'dock:state-changed' event", () => {
+        it('fires on open() / close() / toggle() with state-only payload', () => {
+            const { dock } = track(mountDock({
+                tools: [
+                    { id: 'chat', label: 'Chat', component: noopTool },
+                    { id: 'jobs', label: 'Jobs', component: noopTool },
+                ],
+            }));
+            const handler = vi.fn();
+            dock.on('dock:state-changed', handler);
+            dock.open('chat');
+            flushSync();
+            expect(handler).toHaveBeenCalledTimes(1);
+            expect(handler).toHaveBeenLastCalledWith({
+                isOpen: true,
+                activeTool: 'chat',
+            });
+            dock.close();
+            flushSync();
+            expect(handler).toHaveBeenCalledTimes(2);
+            expect(handler).toHaveBeenLastCalledWith({
+                isOpen: false,
+                activeTool: 'chat',
+            });
+            dock.toggle('jobs');
+            flushSync();
+            expect(handler).toHaveBeenCalledTimes(3);
+            expect(handler).toHaveBeenLastCalledWith({
+                isOpen: true,
+                activeTool: 'jobs',
+            });
+        });
+        it('does NOT fire on setContext() (context-only mutation)', () => {
+            const { dock } = track(mountDock({
+                tools: [{ id: 'chat', label: 'Chat', component: noopTool }],
+            }));
+            const handler = vi.fn();
+            dock.on('dock:state-changed', handler);
+            dock.setContext({ type: 'route', title: 'Home' });
+            flushSync();
+            // setContext alone does not change isOpen/activeTool — must stay silent.
+            expect(handler).not.toHaveBeenCalled();
+        });
+        it('fires when availability clears the active tool', async () => {
+            let availability = [{ id: 'chat' }, { id: 'jobs' }];
+            const fetchAvailability = vi.fn(async () => availability);
+            const { dock } = track(mountDock({
+                tools: [
+                    { id: 'chat', label: 'Chat', component: noopTool },
+                    { id: 'jobs', label: 'Jobs', component: noopTool },
+                ],
+                fetchAvailability,
+            }));
+            dock.setContext({ type: 'a' });
+            await new Promise((r) => setTimeout(r, 0));
+            flushSync();
+            dock.open('jobs');
+            flushSync();
+            const handler = vi.fn();
+            dock.on('dock:state-changed', handler);
+            // Availability shrink → 'jobs' is no longer available, activeTool clears.
+            availability = [{ id: 'chat' }];
+            dock.refreshAvailability();
+            await new Promise((r) => setTimeout(r, 0));
+            flushSync();
+            expect(handler).toHaveBeenCalledTimes(1);
+            expect(handler).toHaveBeenLastCalledWith({
+                isOpen: true,
+                activeTool: null,
+            });
+        });
+        it('does NOT fire on no-op open() / close() / toggle()', () => {
+            const { dock } = track(mountDock({
+                tools: [{ id: 'chat', label: 'Chat', component: noopTool }],
+            }));
+            dock.open('chat');
+            flushSync();
+            const handler = vi.fn();
+            dock.on('dock:state-changed', handler);
+            dock.open('chat'); // already open + active
+            flushSync();
+            dock.close();
+            flushSync();
+            dock.close(); // already closed
+            flushSync();
+            // One observable transition (open → close), so exactly one emit.
+            expect(handler).toHaveBeenCalledTimes(1);
+        });
+        it('does NOT fire on badge-only availability refresh', async () => {
+            // Pure badge churn: no state change, no context change. The legacy
+            // 'dock:change' event still fires (for back-compat consumers
+            // mirroring availableTools), but 'dock:state-changed' stays silent.
+            let availability = [
+                { id: 'chat', badge: 0 },
+            ];
+            const fetchAvailability = vi.fn(async () => availability);
+            const { dock } = track(mountDock({
+                tools: [{ id: 'chat', label: 'Chat', component: noopTool }],
+                fetchAvailability,
+            }));
+            dock.setContext({ type: 'a' });
+            await new Promise((r) => setTimeout(r, 0));
+            flushSync();
+            const stateHandler = vi.fn();
+            dock.on('dock:state-changed', stateHandler);
+            availability = [{ id: 'chat', badge: 7 }];
+            dock.refreshAvailability();
+            await new Promise((r) => setTimeout(r, 0));
+            flushSync();
+            expect(stateHandler).not.toHaveBeenCalled();
+        });
+    });
+    describe("'dock:context-changed' event", () => {
+        it('fires on setContext() with a different reference', () => {
+            const { dock } = track(mountDock({
+                tools: [{ id: 'chat', label: 'Chat', component: noopTool }],
+            }));
+            const handler = vi.fn();
+            dock.on('dock:context-changed', handler);
+            const ctx = { type: 'route', title: 'Home' };
+            dock.setContext(ctx);
+            flushSync();
+            expect(handler).toHaveBeenCalledTimes(1);
+            expect(handler).toHaveBeenLastCalledWith({ context: ctx });
+            dock.setContext(null);
+            flushSync();
+            expect(handler).toHaveBeenCalledTimes(2);
+            expect(handler).toHaveBeenLastCalledWith({ context: null });
+        });
+        it('does NOT fire on open() / close() / toggle() (state-only mutations)', () => {
+            const { dock } = track(mountDock({
+                tools: [{ id: 'chat', label: 'Chat', component: noopTool }],
+            }));
+            const handler = vi.fn();
+            dock.on('dock:context-changed', handler);
+            dock.open('chat');
+            flushSync();
+            dock.close();
+            flushSync();
+            dock.toggle('chat');
+            flushSync();
+            expect(handler).not.toHaveBeenCalled();
+        });
+        it('does NOT fire on setContext() with the same reference', () => {
+            const { dock } = track(mountDock({
+                tools: [{ id: 'chat', label: 'Chat', component: noopTool }],
+            }));
+            const ctx = { type: 'route' };
+            dock.setContext(ctx);
+            flushSync();
+            const handler = vi.fn();
+            dock.on('dock:context-changed', handler);
+            dock.setContext(ctx); // same reference — no-op-guarded
+            flushSync();
+            expect(handler).not.toHaveBeenCalled();
+        });
+        it('does NOT fire on a badge-only availability refresh', async () => {
+            let availability = [
+                { id: 'chat', badge: 0 },
+            ];
+            const fetchAvailability = vi.fn(async () => availability);
+            const { dock } = track(mountDock({
+                tools: [{ id: 'chat', label: 'Chat', component: noopTool }],
+                fetchAvailability,
+            }));
+            dock.setContext({ type: 'a' });
+            await new Promise((r) => setTimeout(r, 0));
+            flushSync();
+            const handler = vi.fn();
+            dock.on('dock:context-changed', handler);
+            availability = [{ id: 'chat', badge: 7 }];
+            dock.refreshAvailability();
+            await new Promise((r) => setTimeout(r, 0));
+            flushSync();
+            // Context didn't change — badge refresh stays silent on this event.
+            expect(handler).not.toHaveBeenCalled();
+        });
+    });
+    describe("'dock:change' event continues to fire (back-compat)", () => {
+        it('fires on state, context, and badge-only availability transitions', async () => {
+            // Use a fetchAvailability that yields the same shape the dock seeded
+            // from the registered tools (no badge), so the post-setContext
+            // availability application is a no-op and we can count emits cleanly.
+            const fetchAvailability = vi
+                .fn()
+                .mockResolvedValue([{ id: 'chat' }]);
+            const { dock } = track(mountDock({
+                tools: [{ id: 'chat', label: 'Chat', component: noopTool }],
+                fetchAvailability,
+            }));
+            const legacyHandler = vi.fn();
+            dock.on('dock:change', legacyHandler);
+            // 1. setContext → 1 synchronous emit. The async availability fetch
+            //    resolves to the same shape the registered tools already had
+            //    (id='chat', no badge), so applyAvailability sees no change and
+            //    does NOT emit a second time.
+            dock.setContext({ type: 'a' });
+            flushSync();
+            await new Promise((r) => setTimeout(r, 0));
+            flushSync();
+            expect(legacyHandler).toHaveBeenCalledTimes(1);
+            // 2. open() → 1 more emit (state change).
+            dock.open('chat');
+            flushSync();
+            expect(legacyHandler).toHaveBeenCalledTimes(2);
+            // 3. badge-only availability refresh → 1 more emit. This is the
+            //    back-compat slice: granular 'dock:state-changed' and
+            //    'dock:context-changed' stay silent, but legacy mirrors of
+            //    availableTools still see the update via 'dock:change'.
+            fetchAvailability.mockResolvedValueOnce([{ id: 'chat', badge: 5 }]);
+            dock.refreshAvailability();
+            await new Promise((r) => setTimeout(r, 0));
+            flushSync();
+            expect(legacyHandler).toHaveBeenCalledTimes(3);
+            // 4. close() → 1 more emit (state change).
+            dock.close();
+            flushSync();
+            expect(legacyHandler).toHaveBeenCalledTimes(4);
+        });
+    });
+});