@fias/arche-sdk 2.29.0 → 2.30.0

package/dist/hooks.test.js

@@ -71,7 +71,13 @@ function createMockBridge() {
         getHolder: jest.fn().mockReturnValue(null),
         onHolderReady: jest.fn().mockReturnValue(() => { }),
         onThemeUpdate: jest.fn().mockReturnValue(() => { }),
+        onAccessUpdate: jest.fn().mockReturnValue(() => { }),
         onNavigationUpdate: jest.fn().mockReturnValue(() => { }),
+        getChrome: jest.fn().mockReturnValue(null),
+        hasChromeSupport: jest.fn().mockReturnValue(false),
+        onChromeUpdate: jest.fn().mockReturnValue(() => { }),
+        setChrome: jest.fn(),
+        navigateHost: jest.fn(),
         onStepNavigationUpdate: jest.fn().mockReturnValue(() => { }),
         registerPreviewState: jest.fn().mockReturnValue(() => { }),
         onSubscriptionEvent: jest.fn().mockReturnValue(() => { }),
@@ -244,6 +250,66 @@ describe('SDK hooks', () => {
             });
         });
     });
+    describe('useFiasChrome', () => {
+        const HOST_STATE = {
+            focusMode: true,
+            focusModeAvailable: true,
+            sidebarAvailable: true,
+            sidebarCollapsed: false,
+            hostExpandedBar: true,
+            hostExpandButton: false,
+        };
+        it('is inert and unsupported before init / on an older host, and still renders', () => {
+            const { useFiasChrome } = require('./hooks');
+            const chrome = useFiasChrome();
+            expect(chrome.supported).toBe(false);
+            expect(chrome.focusMode).toBe(false);
+            expect(chrome.focusModeAvailable).toBe(false);
+            expect(chrome.sidebarAvailable).toBe(false);
+            expect(chrome.hostExpandedBar).toBe(true);
+            expect(mockBridge.onChromeUpdate).toHaveBeenCalled();
+        });
+        it('spreads the host state and reports supported once delivered', () => {
+            mockBridge.getChrome.mockReturnValue(HOST_STATE);
+            mockBridge.hasChromeSupport.mockReturnValue(true);
+            const { useFiasChrome } = require('./hooks');
+            const chrome = useFiasChrome();
+            expect(chrome.supported).toBe(true);
+            expect(chrome.focusMode).toBe(true);
+            expect(chrome.hostExpandButton).toBe(false);
+        });
+        it('TAKES THE CHROME OVER on mount — the host drops its default expand button', () => {
+            const { useFiasChrome } = require('./hooks');
+            useFiasChrome();
+            expect(mockBridge.setChrome).toHaveBeenCalledWith({ hostExpandButton: false });
+        });
+        it('setters send one-field chrome_set patches; navigation uses the closed enum', () => {
+            const { useFiasChrome } = require('./hooks');
+            const chrome = useFiasChrome();
+            chrome.setFocusMode(true);
+            expect(mockBridge.setChrome).toHaveBeenCalledWith({ focusMode: true });
+            chrome.setSidebarCollapsed(true);
+            expect(mockBridge.setChrome).toHaveBeenCalledWith({ sidebarCollapsed: true });
+            chrome.setHostExpandedBar(false);
+            expect(mockBridge.setChrome).toHaveBeenCalledWith({ hostExpandedBar: false });
+            chrome.goToFiasHome();
+            expect(mockBridge.navigateHost).toHaveBeenCalledWith('home');
+            chrome.goToWorktop();
+            expect(mockBridge.navigateHost).toHaveBeenCalledWith('worktop');
+            chrome.openAssistant();
+            expect(mockBridge.openAssistant).toHaveBeenCalled();
+        });
+        it('cleanup unsubscribes from chrome updates', () => {
+            const unsubscribe = jest.fn();
+            mockBridge.onChromeUpdate.mockReturnValue(unsubscribe);
+            const { useFiasChrome } = require('./hooks');
+            useFiasChrome();
+            // The LAST captured cleanup is the takeover effect's (none) or the
+            // subscription's — walk the captured one if present.
+            capturedEffectCleanup?.();
+            expect(unsubscribe).toHaveBeenCalled();
+        });
+    });
     describe('hook return identity', () => {
         // These two returns MUST be memoized. The natural way to consume them is
         // `useEffect(() => { void storage.readFile(...) }, [storage])`, and a
@@ -788,6 +854,205 @@ describe('SDK hooks', () => {
             expect(mockBridge.request).toHaveBeenCalledWith(...entityOp(entity_ops_1.PLUGIN_WORKSPACES_ENTITY_ID, 'create', { forActingHolder: true }));
         });
     });
+    // ADR-034 phase 0b. The real-render cases (stale answers across workspace
+    // switches, the render before effects run, refetch) live in
+    // use-fias-access.render.test.tsx, which CI runs through the package's
+    // `test:render` script; these mock React and run under the root config.
+    describe('useFiasAccess', () => {
+        const settle = () => new Promise((r) => setTimeout(r, 0));
+        const setCalls = () => mockSetState.mock.calls.map((c) => c[0]);
+        it('asks the workspaces entity for my_access with the workspace id', async () => {
+            const { useFiasAccess } = require('./hooks');
+            const access = { mode: 'tier', workspaceId: 'ws_1', tier: 'member', expiresAt: null };
+            mockBridge.request.mockResolvedValue(output({ access }));
+            useFiasAccess('ws_1');
+            await settle();
+            expect(mockBridge.request).toHaveBeenCalledWith(...entityOp(entity_ops_1.PLUGIN_WORKSPACES_ENTITY_ID, 'my_access', { workspaceId: 'ws_1' }));
+            expect(setCalls()).toContainEqual({ workspaceId: 'ws_1', access, error: null });
+        });
+        it.each(['NOT_A_MEMBER', 'WORKSPACE_NOT_FOUND'])('%s becomes tier: null', async (code) => {
+            const { useFiasAccess } = require('./hooks');
+            const { FiasBridgeError } = jest.requireActual('./bridge');
+            mockBridge.request.mockRejectedValue(new FiasBridgeError('refused', code));
+            useFiasAccess('ws_1');
+            await settle();
+            expect(setCalls()).toContainEqual({
+                workspaceId: 'ws_1',
+                access: { mode: 'tier', workspaceId: 'ws_1', tier: null, expiresAt: null },
+                error: null,
+            });
+        });
+        it('surfaces any other failure as an error', async () => {
+            const { useFiasAccess } = require('./hooks');
+            const { FiasBridgeError } = jest.requireActual('./bridge');
+            mockBridge.request.mockRejectedValue(new FiasBridgeError('slow down', 'RATE_LIMIT'));
+            useFiasAccess('ws_1');
+            await settle();
+            expect(setCalls()).toContainEqual({
+                workspaceId: 'ws_1',
+                access: null,
+                error: expect.objectContaining({ code: 'RATE_LIMIT' }),
+            });
+        });
+        it('asks nothing without a workspace', async () => {
+            const { useFiasAccess } = require('./hooks');
+            const state = useFiasAccess(null);
+            await settle();
+            expect(mockBridge.request).not.toHaveBeenCalled();
+            expect(state).toMatchObject({ access: null, isLoading: false, error: null });
+        });
+        it('asks again when the host says the person’s access changed (ADR-034)', async () => {
+            const { useFiasAccess } = require('./hooks');
+            const access = { mode: 'tier', workspaceId: 'ws_1', tier: 'member', expiresAt: null };
+            mockBridge.request.mockResolvedValue(output({ access }));
+            useFiasAccess('ws_1');
+            await settle();
+            expect(mockBridge.request).toHaveBeenCalledTimes(1);
+            const listener = mockBridge.onAccessUpdate.mock.calls[0][0];
+            listener();
+            await settle();
+            expect(mockBridge.request).toHaveBeenCalledTimes(2);
+        });
+        it('a failed background refetch keeps the answer it had', async () => {
+            const { useFiasAccess } = require('./hooks');
+            const { FiasBridgeError } = jest.requireActual('./bridge');
+            const access = { mode: 'tier', workspaceId: 'ws_1', tier: 'member', expiresAt: null };
+            mockBridge.request.mockResolvedValueOnce(output({ access }));
+            useFiasAccess('ws_1');
+            await settle();
+            mockSetState.mockClear();
+            mockBridge.request.mockRejectedValueOnce(new FiasBridgeError('slow down', 'RATE_LIMIT'));
+            const subscriptions = mockBridge.onAccessUpdate.mock.calls;
+            subscriptions[subscriptions.length - 1][0]();
+            await settle();
+            // No blanking answer was written, and nothing flipped to loading.
+            expect(setCalls()).not.toContainEqual(expect.objectContaining({ access: null }));
+            expect(setCalls()).not.toContain(true);
+        });
+        it('window focus asks again at most once per 30 s', async () => {
+            const listeners = {};
+            const win = {
+                addEventListener: jest.fn((type, fn) => (listeners[type] = fn)),
+                removeEventListener: jest.fn(),
+            };
+            globalThis.window = win;
+            try {
+                const { useFiasAccess } = require('./hooks');
+                const access = { mode: 'tier', workspaceId: 'ws_1', tier: 'member', expiresAt: null };
+                mockBridge.request.mockResolvedValue(output({ access }));
+                useFiasAccess('ws_1');
+                await settle();
+                expect(mockBridge.request).toHaveBeenCalledTimes(1);
+                listeners.focus();
+                await settle();
+                expect(mockBridge.request).toHaveBeenCalledTimes(1);
+                const now = Date.now();
+                jest.spyOn(Date, 'now').mockReturnValue(now + 31000);
+                listeners.focus();
+                await settle();
+                expect(mockBridge.request).toHaveBeenCalledTimes(2);
+            }
+            finally {
+                delete globalThis.window;
+                jest.restoreAllMocks();
+            }
+        });
+        it('opens the host’s access sheet with no input, and asks again only if it changed', async () => {
+            const { useFiasAccess } = require('./hooks');
+            const access = { mode: 'tier', workspaceId: 'ws_1', tier: 'member', expiresAt: null };
+            mockBridge.request.mockResolvedValue(output({ access }));
+            const state = useFiasAccess('ws_1');
+            await settle();
+            mockBridge.request.mockClear();
+            mockBridge.request.mockResolvedValueOnce({ changed: false });
+            await expect(state.openAccessDialog()).resolves.toEqual({ changed: false });
+            expect(mockBridge.request).toHaveBeenCalledWith('client_entity_invoke', { entityId: 'ent_intg_app_access_dialog_00000', input: {} }, expect.any(Number));
+            expect(mockBridge.request).toHaveBeenCalledTimes(1);
+            mockBridge.request.mockResolvedValueOnce({ changed: true });
+            mockBridge.request.mockResolvedValue(output({ access }));
+            await expect(state.openAccessDialog()).resolves.toEqual({ changed: true });
+            await settle();
+            expect(mockBridge.request).toHaveBeenCalledTimes(3);
+        });
+        it('a host without the sheet (an older Fias) is ACCESS_UNAVAILABLE, not a bare bridge error', async () => {
+            const { useFiasAccess } = require('./hooks');
+            const { FiasBridgeError } = jest.requireActual('./bridge');
+            mockBridge.request.mockResolvedValue(output({ access: null }));
+            const state = useFiasAccess('ws_1');
+            await settle();
+            mockBridge.request.mockRejectedValueOnce(new FiasBridgeError('no client-side executor registered', 'BRIDGE_ERROR'));
+            await expect(state.openAccessDialog()).rejects.toMatchObject({ code: 'ACCESS_UNAVAILABLE' });
+        });
+        it('an older dev harness without the sheet is ACCESS_UNAVAILABLE too', async () => {
+            const { useFiasAccess } = require('./hooks');
+            const { FiasBridgeError } = jest.requireActual('./bridge');
+            mockBridge.request.mockResolvedValue(output({ access: null }));
+            const state = useFiasAccess('ws_1');
+            await settle();
+            mockBridge.request.mockRejectedValueOnce(new FiasBridgeError('client_entity_invoke: no client-side executor for ent_intg_app_access_dialog_00000 in the dev harness', 'BRIDGE_ERROR'));
+            await expect(state.openAccessDialog()).rejects.toMatchObject({ code: 'ACCESS_UNAVAILABLE' });
+        });
+        it('any other bridge error (e.g. a missing permission) passes through unchanged', async () => {
+            const { useFiasAccess } = require('./hooks');
+            const { FiasBridgeError } = jest.requireActual('./bridge');
+            mockBridge.request.mockResolvedValue(output({ access: null }));
+            const state = useFiasAccess('ws_1');
+            await settle();
+            mockBridge.request.mockRejectedValueOnce(new FiasBridgeError('Permission denied: data:workspace not granted', 'BRIDGE_ERROR'));
+            await expect(state.openAccessDialog()).rejects.toMatchObject({
+                code: 'BRIDGE_ERROR',
+                message: 'Permission denied: data:workspace not granted',
+            });
+        });
+        it('the sheet’s refusal is a typed error', async () => {
+            const { useFiasAccess } = require('./hooks');
+            mockBridge.request.mockResolvedValue(output({ access: null }));
+            const state = useFiasAccess('ws_1');
+            await settle();
+            mockBridge.request.mockResolvedValueOnce({
+                error: { code: 'NOT_IN_WORKSPACE', message: 'Personal' },
+            });
+            await expect(state.openAccessDialog()).rejects.toMatchObject({ code: 'NOT_IN_WORKSPACE' });
+        });
+    });
+    describe('useCreativeLibrary().pick (ADR-035 D8)', () => {
+        const PICKED = {
+            item: { itemId: 'vci_' + 'a'.repeat(32), kind: 'style', name: 'Ink', version: 2 },
+        };
+        it('asks the host’s picker for a kind, waiting on the person', async () => {
+            const { useCreativeLibrary } = require('./hooks');
+            mockBridge.request.mockResolvedValue(PICKED);
+            await expect(useCreativeLibrary().pick({ kind: 'style' })).resolves.toEqual(PICKED);
+            const [op, payload, timeout] = mockBridge.request.mock.calls[0];
+            expect(op).toBe('client_entity_invoke');
+            expect(payload).toEqual({ entityId: entity_ops_1.CREATIVE_PICKER_ENTITY_ID, input: { kind: 'style' } });
+            expect(timeout).toBeGreaterThanOrEqual(5 * 60 * 1000);
+        });
+        it('sends nothing when no kind is asked, and passes a closed sheet through', async () => {
+            const { useCreativeLibrary } = require('./hooks');
+            mockBridge.request.mockResolvedValue({ canceled: true });
+            await expect(useCreativeLibrary().pick()).resolves.toEqual({ canceled: true });
+            expect(mockBridge.request.mock.calls[0][1]).toEqual({
+                entityId: entity_ops_1.CREATIVE_PICKER_ENTITY_ID,
+                input: {},
+            });
+        });
+        it('turns a refusal result into a typed error', async () => {
+            const { useCreativeLibrary } = require('./hooks');
+            mockBridge.request.mockResolvedValue({
+                error: { code: 'SHEET_BUSY', message: 'Another request is waiting' },
+            });
+            await expect(useCreativeLibrary().pick()).rejects.toMatchObject({ code: 'SHEET_BUSY' });
+        });
+        it('a host with no picker answers PICKER_UNAVAILABLE', async () => {
+            const { useCreativeLibrary } = require('./hooks');
+            const { FiasBridgeError } = jest.requireActual('./bridge');
+            mockBridge.request.mockRejectedValue(new FiasBridgeError('no client-side executor registered for x', 'BRIDGE_ERROR'));
+            await expect(useCreativeLibrary().pick()).rejects.toMatchObject({
+                code: 'PICKER_UNAVAILABLE',
+            });
+        });
+    });
     describe('useFiasConnections', () => {
         it('lists through the connections entity', async () => {
             const { useFiasConnections } = require('./hooks');
@@ -1212,6 +1477,7 @@ describe('SDK hooks', () => {
                 __esModule: true,
                 getBridge: () => mockSingletonBridge,
                 FiasBridge: jest.fn(),
+                FiasBridgeError: jest.requireActual('./bridge').FiasBridgeError,
                 resetBridge: jest.fn(),
             }));
             jest.doMock('react', () => require('react'));
@@ -1337,6 +1603,136 @@ describe('SDK hooks', () => {
             expect(second.url).toBe('https://example.com/new');
             expect(mockBridge.request).toHaveBeenCalledTimes(2);
         });
+        it('a changed access answer forgets cached download URLs (ADR-034)', async () => {
+            const { useVaultDocuments, useFiasAccess } = freshHooks();
+            const api = useVaultDocuments();
+            mockBridge.request.mockResolvedValueOnce({
+                url: 'https://example.com/minted-under-old-access',
+                expiresAt: Date.now() + 10 * 60000,
+            });
+            await api.getDownloadUrl('file_c');
+            const answer = (permissions) => ({
+                output: {
+                    access: {
+                        mode: 'roles',
+                        workspaceId: 'ws_1',
+                        tier: 'member',
+                        expiresAt: null,
+                        roles: [],
+                        permissions,
+                    },
+                },
+            });
+            const settle = () => new Promise((r) => setTimeout(r, 0));
+            mockBridge.request.mockResolvedValueOnce(answer(['ledger.read']));
+            useFiasAccess('ws_1');
+            await settle();
+            // The same answer again keeps the cache…
+            mockBridge.request.mockResolvedValueOnce(answer(['ledger.read']));
+            const subscriptions = mockBridge.onAccessUpdate.mock.calls;
+            const listener = subscriptions[subscriptions.length - 1][0];
+            listener();
+            await settle();
+            mockBridge.request.mockClear();
+            await api.getDownloadUrl('file_c');
+            expect(mockBridge.request).not.toHaveBeenCalled();
+            // …a different one does not.
+            mockBridge.request.mockResolvedValueOnce(answer([]));
+            listener();
+            await settle();
+            mockBridge.request.mockClear();
+            mockBridge.request.mockResolvedValueOnce({
+                url: 'https://example.com/fresh',
+                expiresAt: Date.now() + 10 * 60000,
+            });
+            await expect(api.getDownloadUrl('file_c')).resolves.toMatchObject({
+                url: 'https://example.com/fresh',
+            });
+        });
+        it('losing the workspace (NOT_A_MEMBER) forgets cached download URLs too (ADR-034)', async () => {
+            const { useVaultDocuments, useFiasAccess } = freshHooks();
+            const { FiasBridgeError } = jest.requireActual('./bridge');
+            const api = useVaultDocuments();
+            mockBridge.request.mockResolvedValueOnce({
+                url: 'https://example.com/old',
+                expiresAt: Date.now() + 10 * 60000,
+            });
+            await api.getDownloadUrl('file_d');
+            const settle = () => new Promise((r) => setTimeout(r, 0));
+            mockBridge.request.mockResolvedValueOnce({
+                output: { access: { mode: 'tier', workspaceId: 'ws_1', tier: 'member', expiresAt: null } },
+            });
+            useFiasAccess('ws_1');
+            await settle();
+            mockBridge.request.mockRejectedValueOnce(new FiasBridgeError('gone', 'NOT_A_MEMBER'));
+            const subscriptions = mockBridge.onAccessUpdate.mock.calls;
+            subscriptions[subscriptions.length - 1][0]();
+            await settle();
+            mockBridge.request.mockClear();
+            mockBridge.request.mockResolvedValueOnce({
+                url: 'https://example.com/new',
+                expiresAt: Date.now() + 10 * 60000,
+            });
+            await expect(api.getDownloadUrl('file_d')).resolves.toMatchObject({
+                url: 'https://example.com/new',
+            });
+        });
+        it('a remounted access hook still forgets the caches — on no access, and on a changed answer', async () => {
+            const { useVaultDocuments, useFiasAccess } = freshHooks();
+            const { FiasBridgeError } = jest.requireActual('./bridge');
+            const api = useVaultDocuments();
+            const settle = () => new Promise((r) => setTimeout(r, 0));
+            const cacheUrl = async (documentId, url) => {
+                mockBridge.request.mockResolvedValueOnce({ url, expiresAt: Date.now() + 600000 });
+                await api.getDownloadUrl(documentId);
+            };
+            const fresh = async (documentId, url) => {
+                mockBridge.request.mockClear();
+                mockBridge.request.mockResolvedValueOnce({ url, expiresAt: Date.now() + 600000 });
+                await expect(api.getDownloadUrl(documentId)).resolves.toMatchObject({ url });
+            };
+            // A brand-new hook whose FIRST answer is "no access" (the old one unmounted).
+            await cacheUrl('file_f', 'https://example.com/old');
+            mockBridge.request.mockRejectedValueOnce(new FiasBridgeError('gone', 'NOT_A_MEMBER'));
+            useFiasAccess('ws_9');
+            await settle();
+            await fresh('file_f', 'https://example.com/new');
+            // One hook sees an answer; a later, new hook sees a different one.
+            const answer = (tier) => ({
+                output: { access: { mode: 'tier', workspaceId: 'ws_8', tier, expiresAt: null } },
+            });
+            mockBridge.request.mockResolvedValueOnce(answer('admin'));
+            useFiasAccess('ws_8');
+            await settle();
+            await cacheUrl('file_g', 'https://example.com/old-g');
+            // The first hook unmounts (instances of one workspace share an answer
+            // while any is mounted), then a new one mounts.
+            capturedEffectCleanup?.();
+            mockBridge.request.mockResolvedValueOnce(answer('viewer'));
+            useFiasAccess('ws_8');
+            await settle();
+            await fresh('file_g', 'https://example.com/new-g');
+        });
+        it('a fetch already in flight when the caches are forgotten does not refill them', async () => {
+            const hooks = freshHooks();
+            const api = hooks.useVaultDocuments();
+            let answer;
+            mockBridge.request.mockImplementationOnce(() => new Promise((r) => (answer = r)));
+            const pending = api.getDownloadUrl('file_e');
+            hooks.clearSdkReadCaches();
+            answer({
+                url: 'https://example.com/minted-before',
+                expiresAt: new Date(Date.now() + 600000).toISOString(),
+            });
+            await pending;
+            mockBridge.request.mockResolvedValueOnce({
+                url: 'https://example.com/after',
+                expiresAt: new Date(Date.now() + 600000).toISOString(),
+            });
+            await expect(api.getDownloadUrl('file_e')).resolves.toMatchObject({
+                url: 'https://example.com/after',
+            });
+        });
         it('getDownloadUrl dedups concurrent in-flight calls', async () => {
             const { useVaultDocuments } = freshHooks();
             const api = useVaultDocuments();
@@ -1698,6 +2094,47 @@ describe('SDK hooks', () => {
                 data: { score: 100 },
             }));
         });
+        it('put with a null key creates: no key is sent, the audience is, and the server’s key comes back (ADR-034 phase 2)', async () => {
+            const { useFiasDataStore } = require('./hooks');
+            const ds = useFiasDataStore();
+            mockBridge.request.mockResolvedValueOnce(output({ key: 'rec_0123456789abcdef0123456789abcdef', version: 1, audience: 'board' }));
+            const result = await ds.put('papers', null, { t: 1 }, { workspaceId: 'ws_1', audience: 'board' });
+            expect(mockBridge.request).toHaveBeenCalledWith(...entityOp(entity_ops_1.PLUGIN_DATASTORE_ENTITY_ID, 'put', {
+                collection: 'papers',
+                data: { t: 1 },
+                workspaceId: 'ws_1',
+                audience: 'board',
+            }));
+            expect(result).toEqual({
+                key: 'rec_0123456789abcdef0123456789abcdef',
+                version: 1,
+                audience: 'board',
+            });
+        });
+        it('create is a keyless put; a host that predates server keys is refused, never guessed at', async () => {
+            const { useFiasDataStore } = require('./hooks');
+            const ds = useFiasDataStore();
+            mockBridge.request.mockResolvedValueOnce(output({ key: 'rec_1', version: 1, audience: 'staff' }));
+            await expect(ds.create('papers', { t: 1 }, { workspaceId: 'ws_1', audience: 'staff' })).resolves.toMatchObject({ key: 'rec_1', audience: 'staff' });
+            mockBridge.request.mockResolvedValueOnce(output({ version: 1 }));
+            await expect(ds.create('papers', { t: 1 }, { workspaceId: 'ws_1', audience: 'staff' })).rejects.toMatchObject({ code: 'AUDIENCES_UNAVAILABLE' });
+        });
+        it('get, query and search forward an audience only when one is named', async () => {
+            const { useFiasDataStore } = require('./hooks');
+            const ds = useFiasDataStore();
+            mockBridge.request.mockResolvedValue(output({ data: null, documents: [], matches: [] }));
+            await ds.get('papers', 'k', { workspaceId: 'ws_1', audience: 'staff' });
+            await ds.query('papers', {}, { workspaceId: 'ws_1', audience: 'staff' });
+            await ds.search('papers', 'q', {}, { workspaceId: 'ws_1', audience: 'staff' });
+            await ds.get('papers', 'k', { workspaceId: 'ws_1' });
+            const payloads = mockBridge.request.mock.calls.map((c) => c[1].payload);
+            expect(payloads.slice(0, 3).map((p) => p.audience)).toEqual([
+                'staff',
+                'staff',
+                'staff',
+            ]);
+            expect(payloads[3]).not.toHaveProperty('audience');
+        });
         it('get unwraps { data } from the bridge envelope', async () => {
             const { useFiasDataStore } = require('./hooks');
             const ds = useFiasDataStore();
@@ -2474,6 +2911,19 @@ describe('useDataSubscription (ADR-012 Phase M4)', () => {
         expect(onInvalidate).toHaveBeenCalledTimes(1);
         expect(mockSetState).toHaveBeenCalledWith({ status: 'active' });
     });
+    it('names the audience to watch, where a collection has audiences (ADR-034 phase 2)', async () => {
+        subscribed();
+        const { useDataSubscription } = require('./hooks');
+        useDataSubscription('papers', jest.fn().mockResolvedValue(undefined), {
+            workspaceId: 'ws_1',
+            audience: 'board',
+        });
+        await flush();
+        expect(mockBridge.request).toHaveBeenCalledWith('entity_invoke', {
+            entityId: 'ent_intg_plugin_datastore_000000',
+            payload: { op: 'subscribe', collection: 'papers', workspaceId: 'ws_1', audience: 'board' },
+        });
+    });
     it('runs onInvalidate single-flight with exactly one trailing call', async () => {
         subscribed();
         let resolveFirst = () => undefined;
@@ -2521,6 +2971,95 @@ describe('useDataSubscription (ADR-012 Phase M4)', () => {
         expect(onInvalidate).not.toHaveBeenCalled();
     });
 });
+describe('useEntitySubscription (ADR-012 Phase M4 — any subscribe-kind verb)', () => {
+    const flush = async () => {
+        await Promise.resolve();
+        await Promise.resolve();
+        await Promise.resolve();
+    };
+    let mockBridge;
+    beforeEach(() => {
+        mockBridge = createMockBridge();
+        mockContextValue = mockBridge;
+        mockSingletonBridge = mockBridge;
+    });
+    it('forwards the entity id and the verb payload verbatim, then refetches once live', async () => {
+        mockBridge.request.mockResolvedValue({
+            output: { kind: 'subscription', subscriptionId: 'lsub_chat' },
+        });
+        const onInvalidate = jest.fn().mockResolvedValue(undefined);
+        const { useEntitySubscription } = require('./hooks');
+        useEntitySubscription('ent_intg_litcraft_player_0000000', { op: 'subscribe_guild_chat' }, onInvalidate);
+        await flush();
+        expect(mockBridge.request).toHaveBeenCalledWith('entity_invoke', {
+            entityId: 'ent_intg_litcraft_player_0000000',
+            payload: { op: 'subscribe_guild_chat' },
+        });
+        expect(mockBridge.onSubscriptionEvent).toHaveBeenCalledWith('lsub_chat', expect.any(Function));
+        expect(onInvalidate).toHaveBeenCalledTimes(1);
+        expect(mockSetState).toHaveBeenCalledWith({ status: 'active' });
+    });
+    it('enabled: false subscribes to nothing and reports unsubscribed', async () => {
+        const onInvalidate = jest.fn();
+        const { useEntitySubscription } = require('./hooks');
+        useEntitySubscription('ent_x', { op: 'subscribe_x' }, onInvalidate, { enabled: false });
+        await flush();
+        expect(mockBridge.request).not.toHaveBeenCalled();
+        expect(onInvalidate).not.toHaveBeenCalled();
+        expect(mockSetState).toHaveBeenCalledWith({ status: 'ended', endedReason: 'unsubscribed' });
+    });
+    it('sends the payload exactly as given (key order is identity-neutral, not rewritten)', async () => {
+        mockBridge.request.mockResolvedValue({
+            output: { kind: 'subscription', subscriptionId: 'lsub_1' },
+        });
+        const { useEntitySubscription } = require('./hooks');
+        useEntitySubscription('ent_x', { workspaceId: 'ws_1', op: 'subscribe_x' }, jest.fn());
+        await flush();
+        expect(mockBridge.request).toHaveBeenCalledWith('entity_invoke', {
+            entityId: 'ent_x',
+            payload: { op: 'subscribe_x', workspaceId: 'ws_1' },
+        });
+    });
+    it('minRefetchIntervalMs caps refetches to one per interval with one trailing run', async () => {
+        jest.useFakeTimers();
+        try {
+            mockBridge.request.mockResolvedValue({
+                output: { kind: 'subscription', subscriptionId: 'lsub_1' },
+            });
+            const onInvalidate = jest.fn().mockResolvedValue(undefined);
+            const { useEntitySubscription } = require('./hooks');
+            useEntitySubscription('ent_x', { op: 'subscribe_x' }, onInvalidate, {
+                minRefetchIntervalMs: 2000,
+            });
+            await flush();
+            expect(onInvalidate).toHaveBeenCalledTimes(1); // the subscribe-then-fetch run
+            const eventCb = mockBridge.onSubscriptionEvent.mock.calls[0][1];
+            eventCb();
+            eventCb();
+            eventCb();
+            await flush();
+            expect(onInvalidate).toHaveBeenCalledTimes(1); // inside the interval: deferred, not dropped
+            await jest.advanceTimersByTimeAsync(2000);
+            expect(onInvalidate).toHaveBeenCalledTimes(2); // exactly one trailing run at the interval's end
+            capturedEffectCleanup?.();
+        }
+        finally {
+            jest.useRealTimers();
+        }
+    });
+    it('a rejected handshake ends with transport_error and never refetches', async () => {
+        mockBridge.request.mockRejectedValue(new Error('NOT_A_MEMBER'));
+        const onInvalidate = jest.fn();
+        const { useEntitySubscription } = require('./hooks');
+        useEntitySubscription('ent_x', { op: 'subscribe_x' }, onInvalidate);
+        await flush();
+        expect(mockSetState).toHaveBeenCalledWith({
+            status: 'ended',
+            endedReason: 'transport_error',
+        });
+        expect(onInvalidate).not.toHaveBeenCalled();
+    });
+});
 describe('useFiasAIActions', () => {
     let mockBridge;
     beforeEach(() => {