@happyvertical/smrt-svelte 0.53.1 → 0.53.3

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

@@ -1,1188 +0,0 @@
-/**
- * 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.availabilityError).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('drops stale fetchAvailability failures after a newer success', async () => {
-        let rejectFirst = null;
-        let resolveSecond = null;
-        const fetchAvailability = vi
-            .fn()
-            .mockImplementationOnce(() => new Promise((_resolve, reject) => {
-            rejectFirst = reject;
-        }))
-            .mockImplementationOnce(() => new Promise((resolve) => {
-            resolveSecond = resolve;
-        }));
-        const { dock } = track(mountDock({
-            tools: [
-                { id: 'chat', label: 'Chat', component: noopTool },
-                { id: 'jobs', label: 'Jobs', component: noopTool },
-            ],
-            fetchAvailability,
-        }));
-        dock.setContext({ type: 'A' });
-        dock.setContext({ type: 'B' });
-        resolveSecond?.([{ id: 'jobs' }]);
-        await Promise.resolve();
-        await Promise.resolve();
-        flushSync();
-        rejectFirst?.(new Error('stale failure'));
-        await Promise.resolve();
-        await Promise.resolve();
-        flushSync();
-        expect(dock.availableTools.map((tool) => tool.id)).toEqual(['jobs']);
-        expect(dock.availabilityError).toBeNull();
-    });
-    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('preserves the registered fallback and exposes synchronous availability errors', async () => {
-        const failure = new Error('sync boom');
-        const fetchAvailability = vi.fn(() => {
-            throw failure;
-        });
-        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 failure is exposed without replacing the safe initial fallback.
-        await new Promise((r) => setTimeout(r, 0));
-        flushSync();
-        expect(dock.availableTools.map((tool) => tool.id)).toEqual(['chat']);
-        expect(dock.availabilityError).toBe(failure);
-        dock.open('chat');
-        flushSync();
-        expect(dock.isOpen).toBe(true);
-        expect(dock.activeTool).toBe('chat');
-    });
-    it('exposes a consumable error for a reasonless rejection', async () => {
-        const fetchAvailability = vi.fn().mockRejectedValueOnce(undefined);
-        const { dock } = track(mountDock({
-            tools: [{ id: 'chat', label: 'Chat', component: noopTool }],
-            fetchAvailability,
-        }));
-        dock.setContext({ type: 'route' });
-        await new Promise((r) => setTimeout(r, 0));
-        flushSync();
-        expect(dock.availableTools.map((tool) => tool.id)).toEqual(['chat']);
-        expect(dock.availabilityError).toBeInstanceOf(Error);
-        expect(dock.availabilityError.message).toContain('without a reason');
-    });
-    it('preserves last-known-good availability and badges after a rejected refresh', async () => {
-        const failure = new Error('availability offline');
-        const fetchAvailability = vi
-            .fn()
-            .mockResolvedValueOnce([
-            { id: 'chat', badge: 2 },
-            { id: 'jobs', badge: 7 },
-        ])
-            .mockRejectedValueOnce(failure);
-        const { dock } = track(mountDock({
-            tools: [
-                { id: 'chat', label: 'Chat', component: noopTool },
-                { id: 'jobs', label: 'Jobs', component: noopTool },
-            ],
-            fetchAvailability,
-        }));
-        dock.setContext({ type: 'route' });
-        await new Promise((r) => setTimeout(r, 0));
-        flushSync();
-        expect(dock.availableTools).toEqual([
-            { id: 'chat', label: 'Chat', badge: 2 },
-            { id: 'jobs', label: 'Jobs', badge: 7 },
-        ]);
-        dock.open('jobs');
-        dock.refreshAvailability();
-        await new Promise((r) => setTimeout(r, 0));
-        flushSync();
-        expect(dock.availabilityError).toBe(failure);
-        expect(dock.availableTools).toEqual([
-            { id: 'chat', label: 'Chat', badge: 2 },
-            { id: 'jobs', label: 'Jobs', badge: 7 },
-        ]);
-        expect(dock.isOpen).toBe(true);
-        expect(dock.activeTool).toBe('jobs');
-        dock.toggle('jobs');
-        flushSync();
-        expect(dock.isOpen).toBe(false);
-        dock.toggle('jobs');
-        flushSync();
-        expect(dock.isOpen).toBe(true);
-        expect(dock.activeTool).toBe('jobs');
-    });
-    it('preserves last-known-good availability after malformed entries', async () => {
-        const fetchAvailability = vi
-            .fn()
-            .mockResolvedValueOnce([{ id: 'jobs', badge: 4 }])
-            .mockResolvedValueOnce([
-            { label: 'Missing id' },
-        ]);
-        const { dock } = track(mountDock({
-            tools: [
-                { id: 'chat', label: 'Chat', component: noopTool },
-                { id: 'jobs', label: 'Jobs', component: noopTool },
-            ],
-            fetchAvailability,
-        }));
-        dock.setContext({ type: 'route' });
-        await new Promise((r) => setTimeout(r, 0));
-        flushSync();
-        expect(dock.availableTools).toEqual([
-            { id: 'jobs', label: 'Jobs', badge: 4 },
-        ]);
-        dock.refreshAvailability();
-        await new Promise((r) => setTimeout(r, 0));
-        flushSync();
-        expect(dock.availableTools).toEqual([
-            { id: 'jobs', label: 'Jobs', badge: 4 },
-        ]);
-        expect(dock.availabilityError).toBeInstanceOf(TypeError);
-    });
-    it('resets contextual availability before a new-context failure', async () => {
-        const failure = new Error('tenant B unavailable');
-        const fetchAvailability = vi
-            .fn()
-            .mockResolvedValueOnce([{ id: 'jobs', label: 'Tenant A jobs', badge: 9 }])
-            .mockRejectedValueOnce(failure);
-        const { dock } = track(mountDock({
-            tools: [
-                { id: 'chat', label: 'Chat', component: noopTool },
-                { id: 'jobs', label: 'Jobs', badge: 1, component: noopTool },
-            ],
-            fetchAvailability,
-        }));
-        dock.setContext({ type: 'tenant-a' });
-        await new Promise((r) => setTimeout(r, 0));
-        flushSync();
-        expect(dock.availableTools).toEqual([
-            { id: 'jobs', label: 'Tenant A jobs', badge: 9 },
-        ]);
-        dock.setContext({ type: 'tenant-b' });
-        await new Promise((r) => setTimeout(r, 0));
-        flushSync();
-        expect(dock.availabilityError).toBe(failure);
-        expect(dock.availableTools).toEqual([
-            { id: 'chat', label: 'Chat', badge: null },
-            { id: 'jobs', label: 'Jobs', badge: 1 },
-        ]);
-    });
-    it('recovers after a later successful availability refresh', async () => {
-        const failure = new Error('temporary failure');
-        const fetchAvailability = vi
-            .fn()
-            .mockRejectedValueOnce(failure)
-            .mockResolvedValueOnce([{ id: 'jobs', badge: 3 }]);
-        const { dock } = track(mountDock({
-            tools: [
-                { id: 'chat', label: 'Chat', component: noopTool },
-                { id: 'jobs', label: 'Jobs', component: noopTool },
-            ],
-            fetchAvailability,
-        }));
-        dock.setContext({ type: 'route' });
-        await new Promise((r) => setTimeout(r, 0));
-        flushSync();
-        expect(dock.availabilityError).toBe(failure);
-        expect(dock.availableTools.map((tool) => tool.id)).toEqual([
-            'chat',
-            'jobs',
-        ]);
-        dock.refreshAvailability();
-        await new Promise((r) => setTimeout(r, 0));
-        flushSync();
-        expect(dock.availabilityError).toBeNull();
-        expect(dock.availableTools).toEqual([
-            { id: 'jobs', label: 'Jobs', badge: 3 },
-        ]);
-    });
-    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);
-        });
-    });
-});