@fias/arche-sdk 2.3.0 → 2.11.0

package/dist/hooks.test.js

@@ -41,6 +41,18 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 const theme_1 = require("./theme");
+const entity_ops_1 = require("./entity-ops");
+/**
+ * Expected `bridge.request` args for a verb call migrated onto `entity_invoke`
+ * (ADR-012 Phase L, Job 3). Spread into `toHaveBeenCalledWith(...)`.
+ */
+function entityOp(entityId, op, args = {}) {
+    return ['entity_invoke', { entityId, payload: { op, ...args } }];
+}
+/** Wrap a value the way the server's `entity_invoke` envelope does. */
+function output(value) {
+    return { output: value };
+}
 // Build a mock bridge that tracks calls
 function createMockBridge() {
     return {
@@ -57,6 +69,10 @@ function createMockBridge() {
         onThemeUpdate: jest.fn().mockReturnValue(() => { }),
         onNavigationUpdate: jest.fn().mockReturnValue(() => { }),
         onStepNavigationUpdate: jest.fn().mockReturnValue(() => { }),
+        registerPreviewState: jest.fn().mockReturnValue(() => { }),
+        onSubscriptionEvent: jest.fn().mockReturnValue(() => { }),
+        onSubscriptionEnded: jest.fn().mockReturnValue(() => { }),
+        releaseSubscription: jest.fn(),
         attach: jest.fn(),
         destroy: jest.fn(),
     };
@@ -124,6 +140,54 @@ describe('SDK hooks', () => {
             const { useFiasUser } = require('./hooks');
             expect(() => useFiasUser()).toThrow('useBridge must be used within a <FiasProvider>');
         });
+        it('records the error when get_user rejects (no silent swallow)', async () => {
+            const { useFiasUser } = require('./hooks');
+            mockBridge.request.mockRejectedValue(new Error('Permission denied: user:profile:read not granted'));
+            const result = useFiasUser();
+            expect(result).toBeNull();
+            // Let the rejection handler run.
+            await Promise.resolve();
+            await Promise.resolve();
+            // The setter (shared between the user/error useState slots) is called
+            // with the Error — proving the rejection path ran instead of being
+            // swallowed into a permanent null.
+            expect(mockSetState).toHaveBeenCalledWith(expect.any(Error));
+            const errorArg = mockSetState.mock.calls
+                .map((c) => c[0])
+                .find((a) => a instanceof Error);
+            expect(errorArg.message).toContain('user:profile:read');
+        });
+        it('throws the error during render so it hits an error boundary', () => {
+            const react = require('react');
+            // user slot → null; error slot → a populated error.
+            react.useState
+                .mockReturnValueOnce([null, mockSetState])
+                .mockReturnValueOnce([
+                new Error('Permission denied: user:profile:read not granted'),
+                mockSetState,
+            ]);
+            const { useFiasUser } = require('./hooks');
+            expect(() => useFiasUser()).toThrow('user:profile:read');
+        });
+    });
+    describe('useFiasPreviewState', () => {
+        it('registers a keyed provider + restore handler with the bridge', () => {
+            const { useFiasPreviewState } = require('./hooks');
+            const getState = jest.fn(() => ({ rows: 5 }));
+            const onRestore = jest.fn();
+            useFiasPreviewState('report', getState, onRestore);
+            expect(mockBridge.registerPreviewState).toHaveBeenCalledWith('report', expect.any(Function), expect.any(Function));
+            // The wrappers proxy to the live getState/onRestore (via refs).
+            const [, provider, restore] = mockBridge.registerPreviewState.mock.calls[0];
+            expect(provider()).toEqual({ rows: 5 });
+            restore({ rows: 9 });
+            expect(onRestore).toHaveBeenCalledWith({ rows: 9 });
+        });
+        it('throws when used outside FiasProvider', () => {
+            mockContextValue = null;
+            const { useFiasPreviewState } = require('./hooks');
+            expect(() => useFiasPreviewState('k', () => null, () => { })).toThrow('useBridge must be used within a <FiasProvider>');
+        });
     });
     describe('useFiasTheme', () => {
         it('returns initial theme from bridge and subscribes to updates', () => {
@@ -143,32 +207,48 @@ describe('SDK hooks', () => {
             expect(capturedEffectCleanup).toBe(unsubscribe);
         });
     });
+    describe('useFiasNavigation', () => {
+        it('navigateTo and openArche call the bridge with the right ops', () => {
+            const { useFiasNavigation } = require('./hooks');
+            const nav = useFiasNavigation();
+            nav.navigateTo('/settings');
+            expect(mockBridge.request).toHaveBeenCalledWith('navigate', { path: '/settings' });
+            nav.openArche('arc_0123456789abcdef0123456789abcdef', { newTab: true });
+            expect(mockBridge.request).toHaveBeenCalledWith('open_arche', {
+                archeId: 'arc_0123456789abcdef0123456789abcdef',
+                newTab: true,
+            });
+            // newTab defaults to false when opts is omitted.
+            nav.openArche('arche_guilds');
+            expect(mockBridge.request).toHaveBeenCalledWith('open_arche', {
+                archeId: 'arche_guilds',
+                newTab: false,
+            });
+        });
+    });
     describe('useFiasStorage', () => {
         it('returns storage API methods that call bridge.request', async () => {
             const { useFiasStorage } = require('./hooks');
             const storage = useFiasStorage();
-            mockBridge.request.mockResolvedValue('file content');
+            mockBridge.request.mockResolvedValue(output({ content: 'file content', exists: true }));
             await storage.readFile('/test.txt');
-            expect(mockBridge.request).toHaveBeenCalledWith('storage_read', { path: '/test.txt' });
-            mockBridge.request.mockResolvedValue(undefined);
+            expect(mockBridge.request).toHaveBeenCalledWith(...entityOp(entity_ops_1.PLUGIN_STORAGE_ENTITY_ID, 'read', { path: '/test.txt' }));
+            mockBridge.request.mockResolvedValue(output({ success: true }));
             await storage.writeFile('/test.txt', 'data');
-            expect(mockBridge.request).toHaveBeenCalledWith('storage_write', {
-                path: '/test.txt',
-                content: 'data',
-            });
-            mockBridge.request.mockResolvedValue(['a.txt', 'b.txt']);
+            expect(mockBridge.request).toHaveBeenCalledWith(...entityOp(entity_ops_1.PLUGIN_STORAGE_ENTITY_ID, 'write', { path: '/test.txt', content: 'data' }));
+            mockBridge.request.mockResolvedValue(output({ files: ['a.txt', 'b.txt'] }));
             await storage.listFiles('/prefix');
-            expect(mockBridge.request).toHaveBeenCalledWith('storage_list', { prefix: '/prefix' });
-            mockBridge.request.mockResolvedValue(undefined);
+            expect(mockBridge.request).toHaveBeenCalledWith(...entityOp(entity_ops_1.PLUGIN_STORAGE_ENTITY_ID, 'list', { prefix: '/prefix' }));
+            mockBridge.request.mockResolvedValue(output({ success: true }));
             await storage.deleteFile('/test.txt');
-            expect(mockBridge.request).toHaveBeenCalledWith('storage_delete', { path: '/test.txt' });
+            expect(mockBridge.request).toHaveBeenCalledWith(...entityOp(entity_ops_1.PLUGIN_STORAGE_ENTITY_ID, 'delete', { path: '/test.txt' }));
         });
         it('calls listFiles without prefix', async () => {
             const { useFiasStorage } = require('./hooks');
             const storage = useFiasStorage();
-            mockBridge.request.mockResolvedValue([]);
+            mockBridge.request.mockResolvedValue(output({ files: [] }));
             await storage.listFiles();
-            expect(mockBridge.request).toHaveBeenCalledWith('storage_list', { prefix: undefined });
+            expect(mockBridge.request).toHaveBeenCalledWith(...entityOp(entity_ops_1.PLUGIN_STORAGE_ENTITY_ID, 'list', { prefix: undefined }));
         });
     });
     describe('useEntityInvocation', () => {
@@ -211,6 +291,23 @@ describe('SDK hooks', () => {
             await expect(api.invoke({ entityId: 'ent_test', input: 'hello' })).rejects.toThrow('string error');
         });
     });
+    describe('NLLB translation entity', () => {
+        it('exposes the NLLB_LANGUAGES picker list keyed by FLORES code', () => {
+            const { NLLB_LANGUAGES } = require('./hooks');
+            expect(Array.isArray(NLLB_LANGUAGES)).toBe(true);
+            const spanish = NLLB_LANGUAGES.find((l) => l.code === 'spa_Latn');
+            expect(spanish?.label).toBe('Spanish');
+        });
+        it('NLLB_LANGUAGES codes are well-formed FLORES-200 and unique (guards typos/drift)', () => {
+            const { NLLB_LANGUAGES } = require('./hooks');
+            const codes = NLLB_LANGUAGES.map((l) => l.code);
+            for (const l of NLLB_LANGUAGES) {
+                expect(l.label.length).toBeGreaterThan(0);
+                expect(l.code).toMatch(/^[a-z]{3}_[A-Z][a-z]{3}$/);
+            }
+            expect(new Set(codes).size).toBe(codes.length); // no duplicate codes
+        });
+    });
     describe('useFiasNavigation', () => {
         it('returns current path and subscribes to updates', () => {
             mockBridge.getCurrentPath.mockReturnValue('/current');
@@ -261,16 +358,14 @@ describe('SDK hooks', () => {
         it('without persistKey, does not touch storage on mount or setCurrentStep', () => {
             const { useStepNavigation } = require('./hooks');
             const result = useStepNavigation('step-1');
-            expect(mockBridge.request).not.toHaveBeenCalledWith('storage_read', expect.anything());
+            expect(mockBridge.request).not.toHaveBeenCalledWith('entity_invoke', expect.anything());
             result.setCurrentStep('step-2');
-            expect(mockBridge.request).not.toHaveBeenCalledWith('storage_write', expect.anything());
+            expect(mockBridge.request).not.toHaveBeenCalledWith('entity_invoke', expect.anything());
         });
         it('with persistKey, reads persisted value on mount', () => {
             const { useStepNavigation } = require('./hooks');
             useStepNavigation('step-1', { persistKey: 'currentStep' });
-            expect(mockBridge.request).toHaveBeenCalledWith('storage_read', {
-                path: '__state/currentStep',
-            });
+            expect(mockBridge.request).toHaveBeenCalledWith(...entityOp(entity_ops_1.PLUGIN_STORAGE_ENTITY_ID, 'read', { path: '__state/currentStep' }));
         });
         it('with persistKey, writes on setCurrentStep (after debounce flush)', () => {
             jest.useFakeTimers();
@@ -281,12 +376,12 @@ describe('SDK hooks', () => {
                 result.setCurrentStep('step-2');
                 expect(mockSetState).toHaveBeenCalledWith('step-2');
                 // Setter updates in-memory state immediately; the write is debounced.
-                expect(mockBridge.request).not.toHaveBeenCalledWith('storage_write', expect.anything());
+                expect(mockBridge.request).not.toHaveBeenCalledWith('entity_invoke', expect.anything());
                 jest.advanceTimersByTime(260);
-                expect(mockBridge.request).toHaveBeenCalledWith('storage_write', {
+                expect(mockBridge.request).toHaveBeenCalledWith(...entityOp(entity_ops_1.PLUGIN_STORAGE_ENTITY_ID, 'write', {
                     path: '__state/currentStep',
                     content: JSON.stringify('step-2'),
-                });
+                }));
             }
             finally {
                 jest.useRealTimers();
@@ -307,20 +402,17 @@ describe('SDK hooks', () => {
                 hostCallback('step-from-host');
                 expect(mockSetState).toHaveBeenCalledWith('step-from-host');
                 jest.advanceTimersByTime(260);
-                expect(mockBridge.request).toHaveBeenCalledWith('storage_write', {
+                expect(mockBridge.request).toHaveBeenCalledWith(...entityOp(entity_ops_1.PLUGIN_STORAGE_ENTITY_ID, 'write', {
                     path: '__state/currentStep',
                     content: JSON.stringify('step-from-host'),
-                });
+                }));
             }
             finally {
                 jest.useRealTimers();
             }
         });
         it('with persistKey, persisted value wins over initialStep on mount', async () => {
-            mockBridge.request.mockResolvedValue({
-                content: JSON.stringify('step-persisted'),
-                exists: true,
-            });
+            mockBridge.request.mockResolvedValue(output({ content: JSON.stringify('step-persisted'), exists: true }));
             const { useStepNavigation } = require('./hooks');
             useStepNavigation('step-initial', { persistKey: 'currentStep' });
             // Let the storage_read promise resolve
@@ -332,26 +424,39 @@ describe('SDK hooks', () => {
     });
     describe('usePersistentState', () => {
         function countStorageWrites(key) {
-            return mockBridge.request.mock.calls.filter((call) => call[0] === 'storage_write' && call[1].path === `__state/${key}`).length;
+            return mockBridge.request.mock.calls.filter((call) => {
+                if (call[0] !== 'entity_invoke')
+                    return false;
+                const payload = call[1].payload;
+                return payload?.op === 'write' && payload?.path === `__state/${key}`;
+            }).length;
         }
         it('reads initial value from storage on mount', () => {
             const { usePersistentState } = require('./hooks');
             usePersistentState('counter', 0);
-            expect(mockBridge.request).toHaveBeenCalledWith('storage_read', {
-                path: '__state/counter',
-            });
+            expect(mockBridge.request).toHaveBeenCalledWith(...entityOp(entity_ops_1.PLUGIN_STORAGE_ENTITY_ID, 'read', { path: '__state/counter' }));
         });
         it('applies persisted value after storage_read resolves', async () => {
-            mockBridge.request.mockResolvedValue({
-                content: JSON.stringify(42),
-                exists: true,
-            });
+            mockBridge.request.mockResolvedValue(output({ content: JSON.stringify(42), exists: true }));
             const { usePersistentState } = require('./hooks');
             usePersistentState('counter', 0);
             await Promise.resolve();
             await Promise.resolve();
             expect(mockSetState).toHaveBeenCalledWith(42);
         });
+        it('falls back to the initial value when the mount storage_read is denied/fails', async () => {
+            // e.g. the plugin didn't declare `storage:sandbox`. Must not become a
+            // silent unhandled rejection, and must not clobber the initial value.
+            mockBridge.request.mockRejectedValue(new Error('Permission denied: storage:sandbox'));
+            const { usePersistentState } = require('./hooks');
+            const [value] = usePersistentState('counter', 7);
+            // Let the rejection handler run.
+            await Promise.resolve();
+            await Promise.resolve();
+            // No persisted value was applied — the setter was never called with data.
+            expect(mockSetState).not.toHaveBeenCalled();
+            expect(value).toBe(7);
+        });
         it('setter updates in-memory value synchronously, defers write', () => {
             jest.useFakeTimers();
             try {
@@ -365,10 +470,10 @@ describe('SDK hooks', () => {
                 expect(countStorageWrites('counter')).toBe(0);
                 jest.advanceTimersByTime(260);
                 expect(countStorageWrites('counter')).toBe(1);
-                expect(mockBridge.request).toHaveBeenCalledWith('storage_write', {
+                expect(mockBridge.request).toHaveBeenCalledWith(...entityOp(entity_ops_1.PLUGIN_STORAGE_ENTITY_ID, 'write', {
                     path: '__state/counter',
                     content: JSON.stringify(1),
-                });
+                }));
             }
             finally {
                 jest.useRealTimers();
@@ -390,14 +495,15 @@ describe('SDK hooks', () => {
                 expect(writesDuringBurst).toBeLessThanOrEqual(1);
                 // Let the trailing-edge flush fire
                 jest.advanceTimersByTime(260);
-                const writes = mockBridge.request.mock.calls.filter((call) => call[0] === 'storage_write');
+                const writes = mockBridge.request.mock.calls.filter((call) => call[0] === 'entity_invoke' &&
+                    call[1].payload?.op === 'write');
                 // Total writes over the burst: at most 2 (one at maxWait, one trailing).
                 // Never 60. Final write contains the last value.
                 expect(writes.length).toBeGreaterThanOrEqual(1);
                 expect(writes.length).toBeLessThanOrEqual(2);
                 expect(writes[writes.length - 1][1]).toEqual({
-                    path: '__state/counter',
-                    content: JSON.stringify(60),
+                    entityId: entity_ops_1.PLUGIN_STORAGE_ENTITY_ID,
+                    payload: { op: 'write', path: '__state/counter', content: JSON.stringify(60) },
                 });
             }
             finally {
@@ -438,10 +544,10 @@ describe('SDK hooks', () => {
                 expect(capturedEffectCleanup).not.toBeNull();
                 capturedEffectCleanup();
                 expect(countStorageWrites('counter')).toBe(1);
-                expect(mockBridge.request).toHaveBeenCalledWith('storage_write', {
+                expect(mockBridge.request).toHaveBeenCalledWith(...entityOp(entity_ops_1.PLUGIN_STORAGE_ENTITY_ID, 'write', {
                     path: '__state/counter',
                     content: JSON.stringify(7),
-                });
+                }));
             }
             finally {
                 jest.useRealTimers();
@@ -724,139 +830,49 @@ describe('SDK hooks', () => {
             });
             expect(fin.status).toBe('uploaded');
         });
-        it('upload() orchestrates SHA-256 + presigned PUT + finalize, stripping Content-Length', async () => {
+        it('upload() delegates to the host vault_documents_upload op with base64 bytes', async () => {
             const { useVaultDocuments } = freshHooks();
             const api = useVaultDocuments();
-            // Mock crypto.subtle.digest to return a known 32-byte digest.
-            const fakeDigest = new Uint8Array(32);
-            for (let i = 0; i < 32; i++)
-                fakeDigest[i] = i;
-            const originalCrypto = globalThis.crypto;
-            globalThis.crypto = {
-                subtle: { digest: jest.fn().mockResolvedValue(fakeDigest.buffer) },
-            };
-            // Mock fetch.
-            const fetchMock = jest.fn().mockResolvedValue({ ok: true, status: 200 });
-            const originalFetch = globalThis.fetch;
-            globalThis.fetch = fetchMock;
-            try {
-                mockBridge.request.mockResolvedValueOnce({
-                    documentId: 'vdoc_u',
-                    uploadUrl: 'https://s3/up',
-                    requiredHeaders: {
-                        'Content-Type': 'application/octet-stream',
-                        'Content-Length': '4',
-                        'x-amz-checksum-sha256': 'aaa',
-                        'x-amz-tagging': 'pending=true',
-                    },
-                    uploadUrlExpiresAt: '2026-05-21T00:05:00Z',
-                });
-                mockBridge.request.mockResolvedValueOnce({
-                    documentId: 'vdoc_u',
-                    status: 'uploaded',
-                });
-                const bytes = new Uint8Array([1, 2, 3, 4]);
-                const result = await api.upload(bytes, {
-                    name: 'tiny.bin',
-                    mimeType: 'application/octet-stream',
-                });
-                // SDK rendered the digest as lowercase hex.
-                const expectedHex = Array.from(fakeDigest)
-                    .map((b) => b.toString(16).padStart(2, '0'))
-                    .join('');
-                expect(mockBridge.request).toHaveBeenNthCalledWith(1, 'vault_documents_upload_init', expect.objectContaining({
-                    sizeBytes: 4,
-                    checksumSha256: expectedHex,
-                }));
-                // Browser fetch was called with Content-Length stripped from the
-                // headers (browser auto-computes it from body.byteLength).
-                expect(fetchMock).toHaveBeenCalledTimes(1);
-                const fetchOpts = fetchMock.mock.calls[0][1];
-                const headerKeys = Object.keys(fetchOpts.headers).map((k) => k.toLowerCase());
-                expect(headerKeys).not.toContain('content-length');
-                expect(headerKeys).toContain('content-type');
-                expect(headerKeys).toContain('x-amz-checksum-sha256');
-                // Finalize used the same hex digest.
-                expect(mockBridge.request).toHaveBeenNthCalledWith(2, 'vault_documents_upload_finalize', {
-                    documentId: 'vdoc_u',
-                    checksumSha256: expectedHex,
-                });
-                expect(result.status).toBe('uploaded');
-            }
-            finally {
-                globalThis.crypto = originalCrypto;
-                globalThis.fetch = originalFetch;
-            }
+            // Single host-orchestrated op: the host (parent window) runs init → PUT →
+            // finalize. The iframe never fetches (its CSP is connect-src 'none'), so
+            // the SDK no longer touches crypto/fetch here.
+            mockBridge.request.mockResolvedValueOnce({ documentId: 'vdoc_u', status: 'uploaded' });
+            const result = await api.upload(new Uint8Array([1, 2, 3, 4]), {
+                name: 'tiny.bin',
+                mimeType: 'application/octet-stream',
+                tags: ['t'],
+            });
+            expect(mockBridge.request).toHaveBeenCalledTimes(1);
+            expect(mockBridge.request).toHaveBeenCalledWith('vault_documents_upload', expect.objectContaining({
+                name: 'tiny.bin',
+                mimeType: 'application/octet-stream',
+                bytes: btoa(String.fromCharCode(1, 2, 3, 4)),
+                tags: ['t'],
+            }));
+            expect(result.status).toBe('uploaded');
         });
-        it('upload() throws on non-2xx PUT response', async () => {
+        it('upload() rejects when the host upload op fails (e.g. PUT 403)', async () => {
             const { useVaultDocuments } = freshHooks();
             const api = useVaultDocuments();
-            const fakeDigest = new Uint8Array(32);
-            const originalCrypto = globalThis.crypto;
-            globalThis.crypto = {
-                subtle: { digest: jest.fn().mockResolvedValue(fakeDigest.buffer) },
-            };
-            const fetchMock = jest.fn().mockResolvedValue({
-                ok: false,
-                status: 403,
-                statusText: 'Forbidden',
-                text: () => Promise.resolve('signature mismatch'),
-            });
-            const originalFetch = globalThis.fetch;
-            globalThis.fetch = fetchMock;
-            try {
-                mockBridge.request.mockResolvedValueOnce({
-                    documentId: 'vdoc_u',
-                    uploadUrl: 'https://s3/up',
-                    requiredHeaders: { 'Content-Type': 'application/octet-stream' },
-                    uploadUrlExpiresAt: '2026-05-21T00:05:00Z',
-                });
-                await expect(api.upload(new Uint8Array([1, 2, 3]), {
-                    name: 'x.bin',
-                    mimeType: 'application/octet-stream',
-                })).rejects.toThrow(/403/);
-            }
-            finally {
-                globalThis.crypto = originalCrypto;
-                globalThis.fetch = originalFetch;
-            }
+            // The host now performs the PUT; a failure surfaces as a rejected op.
+            mockBridge.request.mockRejectedValueOnce(new Error('Vault upload PUT failed (403): Forbidden'));
+            await expect(api.upload(new Uint8Array([1, 2, 3]), {
+                name: 'x.bin',
+                mimeType: 'application/octet-stream',
+            })).rejects.toThrow(/403/);
         });
         it('upload() accepts a raw ArrayBuffer as well as a Uint8Array', async () => {
             const { useVaultDocuments } = freshHooks();
             const api = useVaultDocuments();
-            const fakeDigest = new Uint8Array(32);
-            const originalCrypto = globalThis.crypto;
-            globalThis.crypto = {
-                subtle: { digest: jest.fn().mockResolvedValue(fakeDigest.buffer) },
-            };
-            const fetchMock = jest.fn().mockResolvedValue({ ok: true, status: 200 });
-            const originalFetch = globalThis.fetch;
-            globalThis.fetch = fetchMock;
-            try {
-                mockBridge.request.mockResolvedValueOnce({
-                    documentId: 'vdoc_u',
-                    uploadUrl: 'https://s3/up',
-                    requiredHeaders: {},
-                    uploadUrlExpiresAt: '2026-05-21T00:05:00Z',
-                });
-                mockBridge.request.mockResolvedValueOnce({
-                    documentId: 'vdoc_u',
-                    status: 'uploaded',
-                });
-                const buffer = new ArrayBuffer(8);
-                const view = new Uint8Array(buffer);
-                view.set([1, 2, 3, 4, 5, 6, 7, 8]);
-                const result = await api.upload(buffer, {
-                    name: 'ab.bin',
-                    mimeType: 'application/octet-stream',
-                });
-                expect(result.status).toBe('uploaded');
-                expect(mockBridge.request).toHaveBeenNthCalledWith(1, 'vault_documents_upload_init', expect.objectContaining({ sizeBytes: 8 }));
-            }
-            finally {
-                globalThis.crypto = originalCrypto;
-                globalThis.fetch = originalFetch;
-            }
+            mockBridge.request.mockResolvedValueOnce({ documentId: 'vdoc_u', status: 'uploaded' });
+            const buffer = new ArrayBuffer(8);
+            new Uint8Array(buffer).set([1, 2, 3, 4, 5, 6, 7, 8]);
+            const result = await api.upload(buffer, {
+                name: 'ab.bin',
+                mimeType: 'application/octet-stream',
+            });
+            expect(result.status).toBe('uploaded');
+            expect(mockBridge.request).toHaveBeenCalledWith('vault_documents_upload', expect.objectContaining({ bytes: btoa(String.fromCharCode(1, 2, 3, 4, 5, 6, 7, 8)) }));
         });
     });
     describe('useSurface', () => {
@@ -928,137 +944,118 @@ describe('SDK hooks', () => {
             await expect(api.generate({ prompt: 'x' })).rejects.toThrow('Lyria timeout');
         });
     });
-    describe('useBackgroundRemoval', () => {
+    describe('useClientEntity', () => {
         it('returns initial state from useState', () => {
-            const { useBackgroundRemoval } = require('./hooks');
-            const api = useBackgroundRemoval();
+            const { useClientEntity } = require('./hooks');
+            const api = useClientEntity();
             expect(api.isLoading).toBe(false);
-            expect(api.result).toBeNull();
             expect(api.error).toBeNull();
-            expect(typeof api.removeBackground).toBe('function');
-        });
-        it('removeBackground posts client_entity_invoke targeting the imgly entity with 120s timeout', async () => {
-            const { useBackgroundRemoval } = require('./hooks');
-            const cutout = new Blob([new Uint8Array([9])], { type: 'image/png' });
-            mockBridge.request.mockResolvedValue({ image: cutout });
-            const api = useBackgroundRemoval();
-            const input = new Blob([new Uint8Array([1])], { type: 'image/png' });
-            const result = await api.removeBackground(input);
-            expect(mockBridge.request).toHaveBeenCalledWith('client_entity_invoke', { entityId: 'ent_intg_imgly_bgrm_000000000000', input: { image: input } }, 120000);
-            expect(result).toBe(cutout);
-        });
-        it('rejects inputs over 25 MiB without calling the bridge', async () => {
-            const { useBackgroundRemoval } = require('./hooks');
-            // 25 MiB + 1 byte. Build a backing buffer (cheap — happy-dom Blob
-            // reads `size` from the constructor input length without
-            // materializing the array contents).
-            const oversized = new Blob([new Uint8Array(25 * 1024 * 1024 + 1)], { type: 'image/png' });
-            const api = useBackgroundRemoval();
-            await expect(api.removeBackground(oversized)).rejects.toThrow('25 MiB');
-            expect(mockBridge.request).not.toHaveBeenCalled();
+            expect(typeof api.invoke).toBe('function');
+        });
+        it('invoke posts client_entity_invoke with the given entityId/input and 120s timeout', async () => {
+            const { useClientEntity } = require('./hooks');
+            const response = { issues: [] };
+            mockBridge.request.mockResolvedValue(response);
+            const api = useClientEntity();
+            const input = { text: 'helo wrld' };
+            const result = await api.invoke('ent_intg_grammar_check_000000000', input);
+            expect(mockBridge.request).toHaveBeenCalledWith('client_entity_invoke', { entityId: 'ent_intg_grammar_check_000000000', input }, 120000);
+            expect(result).toBe(response);
         });
         it('rethrows bridge errors and wraps non-Error rejections', async () => {
-            const { useBackgroundRemoval } = require('./hooks');
+            const { useClientEntity } = require('./hooks');
             mockBridge.request.mockRejectedValue('rate limit hit');
-            const api = useBackgroundRemoval();
-            await expect(api.removeBackground(new Blob([new Uint8Array([1])], { type: 'image/png' }))).rejects.toThrow('rate limit hit');
+            const api = useClientEntity();
+            await expect(api.invoke('ent_intg_grammar_check_000000000', {})).rejects.toThrow('rate limit hit');
         });
     });
     describe('useFiasDataStore', () => {
         it('createCollection forwards name + default userScope', async () => {
             const { useFiasDataStore } = require('./hooks');
             const ds = useFiasDataStore();
-            mockBridge.request.mockResolvedValueOnce({
-                collection: { name: 'scores', userScope: 'user' },
-            });
+            mockBridge.request.mockResolvedValueOnce(output({ collection: { name: 'scores', userScope: 'user' } }));
             const coll = await ds.createCollection('scores');
-            expect(mockBridge.request).toHaveBeenCalledWith('data_create_collection', {
+            expect(mockBridge.request).toHaveBeenCalledWith(...entityOp(entity_ops_1.PLUGIN_DATASTORE_ENTITY_ID, 'create_collection', {
                 name: 'scores',
                 userScope: 'user',
-            });
+            }));
             expect(coll.name).toBe('scores');
         });
         it('createCollection honors an explicit userScope=shared', async () => {
             const { useFiasDataStore } = require('./hooks');
             const ds = useFiasDataStore();
-            mockBridge.request.mockResolvedValueOnce({
-                collection: { name: 'global', userScope: 'shared' },
-            });
+            mockBridge.request.mockResolvedValueOnce(output({ collection: { name: 'global', userScope: 'shared' } }));
             await ds.createCollection('global', { userScope: 'shared' });
-            expect(mockBridge.request).toHaveBeenCalledWith('data_create_collection', {
+            expect(mockBridge.request).toHaveBeenCalledWith(...entityOp(entity_ops_1.PLUGIN_DATASTORE_ENTITY_ID, 'create_collection', {
                 name: 'global',
                 userScope: 'shared',
-            });
+            }));
         });
         it('listCollections returns the array unwrapped from the bridge envelope', async () => {
             const { useFiasDataStore } = require('./hooks');
             const ds = useFiasDataStore();
-            mockBridge.request.mockResolvedValueOnce({
-                collections: [{ name: 'a' }, { name: 'b' }],
-            });
+            mockBridge.request.mockResolvedValueOnce(output({ collections: [{ name: 'a' }, { name: 'b' }] }));
             const list = await ds.listCollections();
             expect(list).toHaveLength(2);
-            expect(mockBridge.request).toHaveBeenCalledWith('data_list_collections', {});
+            expect(mockBridge.request).toHaveBeenCalledWith(...entityOp(entity_ops_1.PLUGIN_DATASTORE_ENTITY_ID, 'list_collections'));
         });
         it('deleteCollection forwards the name', async () => {
             const { useFiasDataStore } = require('./hooks');
             const ds = useFiasDataStore();
-            mockBridge.request.mockResolvedValueOnce(undefined);
+            mockBridge.request.mockResolvedValueOnce(output({ success: true }));
             await ds.deleteCollection('scores');
-            expect(mockBridge.request).toHaveBeenCalledWith('data_delete_collection', {
-                name: 'scores',
-            });
+            expect(mockBridge.request).toHaveBeenCalledWith(...entityOp(entity_ops_1.PLUGIN_DATASTORE_ENTITY_ID, 'delete_collection', { name: 'scores' }));
         });
         it('put forwards collection / key / data', async () => {
             const { useFiasDataStore } = require('./hooks');
             const ds = useFiasDataStore();
-            mockBridge.request.mockResolvedValueOnce(undefined);
+            mockBridge.request.mockResolvedValueOnce(output({ success: true }));
             await ds.put('scores', 'level-1', { score: 100 });
-            expect(mockBridge.request).toHaveBeenCalledWith('data_put', {
+            expect(mockBridge.request).toHaveBeenCalledWith(...entityOp(entity_ops_1.PLUGIN_DATASTORE_ENTITY_ID, 'put', {
                 collection: 'scores',
                 key: 'level-1',
                 data: { score: 100 },
-            });
+            }));
         });
         it('get unwraps { data } from the bridge envelope', async () => {
             const { useFiasDataStore } = require('./hooks');
             const ds = useFiasDataStore();
-            mockBridge.request.mockResolvedValueOnce({ data: { score: 50 } });
+            mockBridge.request.mockResolvedValueOnce(output({ data: { score: 50 } }));
             const result = await ds.get('scores', 'level-1');
             expect(result).toEqual({ score: 50 });
         });
         it('get returns null when the bridge says data is null', async () => {
             const { useFiasDataStore } = require('./hooks');
             const ds = useFiasDataStore();
-            mockBridge.request.mockResolvedValueOnce({ data: null });
+            mockBridge.request.mockResolvedValueOnce(output({ data: null }));
             const result = await ds.get('scores', 'missing');
             expect(result).toBeNull();
         });
         it('query forwards collection + options to data_query', async () => {
             const { useFiasDataStore } = require('./hooks');
             const ds = useFiasDataStore();
-            mockBridge.request.mockResolvedValueOnce({ documents: [], nextCursor: null });
+            mockBridge.request.mockResolvedValueOnce(output({ documents: [], nextCursor: null }));
             await ds.query('scores', {
                 filters: [{ field: 'score', op: 'gte', value: 50 }],
                 orderBy: { field: 'score', direction: 'desc' },
                 limit: 10,
             });
-            expect(mockBridge.request).toHaveBeenCalledWith('data_query', {
+            expect(mockBridge.request).toHaveBeenCalledWith(...entityOp(entity_ops_1.PLUGIN_DATASTORE_ENTITY_ID, 'query', {
                 collection: 'scores',
                 filters: [{ field: 'score', op: 'gte', value: 50 }],
                 orderBy: { field: 'score', direction: 'desc' },
                 limit: 10,
-            });
+            }));
         });
         it('delete forwards collection + key', async () => {
             const { useFiasDataStore } = require('./hooks');
             const ds = useFiasDataStore();
-            mockBridge.request.mockResolvedValueOnce(undefined);
+            mockBridge.request.mockResolvedValueOnce(output({ success: true }));
             await ds.delete('scores', 'level-1');
-            expect(mockBridge.request).toHaveBeenCalledWith('data_delete', {
+            expect(mockBridge.request).toHaveBeenCalledWith(...entityOp(entity_ops_1.PLUGIN_DATASTORE_ENTITY_ID, 'delete', {
                 collection: 'scores',
                 key: 'level-1',
-            });
+            }));
         });
     });
     describe('useFiasStore', () => {
@@ -1069,8 +1066,8 @@ describe('SDK hooks', () => {
             mockBridge.request.mockResolvedValueOnce(products).mockResolvedValueOnce(entitlements);
             const api = useFiasStore();
             // Effect kicks the two bridge calls.
-            expect(mockBridge.request).toHaveBeenNthCalledWith(1, 'store_get_products', {});
-            expect(mockBridge.request).toHaveBeenNthCalledWith(2, 'store_get_entitlements', {});
+            expect(mockBridge.request).toHaveBeenNthCalledWith(1, ...entityOp(entity_ops_1.PLUGIN_STORE_ENTITY_ID, 'get_products'));
+            expect(mockBridge.request).toHaveBeenNthCalledWith(2, ...entityOp(entity_ops_1.PLUGIN_STORE_ENTITY_ID, 'get_entitlements'));
             expect(typeof api.purchase).toBe('function');
         });
         it('hasEntitlement checks productIdentifier + isActive', () => {
@@ -1090,9 +1087,7 @@ describe('SDK hooks', () => {
                 .mockResolvedValueOnce({ success: true, purchaseId: 'p_1' });
             const api = useFiasStore();
             const result = await api.purchase('gems_100');
-            expect(mockBridge.request).toHaveBeenLastCalledWith('store_purchase', {
-                productIdentifier: 'gems_100',
-            });
+            expect(mockBridge.request).toHaveBeenLastCalledWith(...entityOp(entity_ops_1.PLUGIN_STORE_ENTITY_ID, 'purchase', { productIdentifier: 'gems_100' }));
             expect(result.purchaseId).toBe('p_1');
         });
         it('purchase forwards options.quantity to the bridge', async () => {
@@ -1103,10 +1098,10 @@ describe('SDK hooks', () => {
                 .mockResolvedValueOnce({ success: true });
             const api = useFiasStore();
             await api.purchase('gems_100', { quantity: 3 });
-            expect(mockBridge.request).toHaveBeenLastCalledWith('store_purchase', {
+            expect(mockBridge.request).toHaveBeenLastCalledWith(...entityOp(entity_ops_1.PLUGIN_STORE_ENTITY_ID, 'purchase', {
                 productIdentifier: 'gems_100',
                 quantity: 3,
-            });
+            }));
         });
         it('getPurchaseHistory unwraps { purchases }', async () => {
             const { useFiasStore } = require('./hooks');
@@ -1117,7 +1112,7 @@ describe('SDK hooks', () => {
             const api = useFiasStore();
             const history = await api.getPurchaseHistory();
             expect(history).toHaveLength(1);
-            expect(mockBridge.request).toHaveBeenLastCalledWith('store_get_purchase_history', {});
+            expect(mockBridge.request).toHaveBeenLastCalledWith(...entityOp(entity_ops_1.PLUGIN_STORE_ENTITY_ID, 'get_purchase_history'));
         });
         it('restorePurchases returns the restored entitlements array directly', async () => {
             const { useFiasStore } = require('./hooks');
@@ -1128,7 +1123,7 @@ describe('SDK hooks', () => {
             const api = useFiasStore();
             const restored = await api.restorePurchases();
             expect(restored).toHaveLength(1);
-            expect(mockBridge.request).toHaveBeenLastCalledWith('store_restore', {});
+            expect(mockBridge.request).toHaveBeenLastCalledWith(...entityOp(entity_ops_1.PLUGIN_STORE_ENTITY_ID, 'restore'));
         });
         it('swallows a mount-time bridge rejection and clears isLoading', async () => {
             const { useFiasStore } = require('./hooks');
@@ -1166,24 +1161,16 @@ describe('SDK hooks', () => {
     });
     describe('usePersistentState', () => {
         it('reads from storage on mount and applies the parsed value', async () => {
-            mockBridge.request.mockResolvedValue({
-                content: JSON.stringify({ score: 50 }),
-                exists: true,
-            });
+            mockBridge.request.mockResolvedValue(output({ content: JSON.stringify({ score: 50 }), exists: true }));
             const { usePersistentState } = require('./hooks');
             const [value, setValue] = usePersistentState('game-state', { score: 0 });
             expect(value).toEqual({ score: 0 }); // initial (useState returns initial)
-            expect(mockBridge.request).toHaveBeenCalledWith('storage_read', {
-                path: '__state/game-state',
-            });
+            expect(mockBridge.request).toHaveBeenCalledWith(...entityOp(entity_ops_1.PLUGIN_STORAGE_ENTITY_ID, 'read', { path: '__state/game-state' }));
             // setValue is exposed regardless of load completion.
             expect(typeof setValue).toBe('function');
         });
         it('tolerates a corrupted JSON read and keeps initial value', async () => {
-            mockBridge.request.mockResolvedValue({
-                content: 'not-valid-json{',
-                exists: true,
-            });
+            mockBridge.request.mockResolvedValue(output({ content: 'not-valid-json{', exists: true }));
             const { usePersistentState } = require('./hooks');
             const [value] = usePersistentState('x', { count: 1 });
             // initial state from useState (the mocked react.useState returns
@@ -1192,7 +1179,7 @@ describe('SDK hooks', () => {
             await new Promise((r) => setTimeout(r, 0));
         });
         it('setValue with a function variant resolves prev from valueRef', () => {
-            mockBridge.request.mockResolvedValue({ content: null, exists: false });
+            mockBridge.request.mockResolvedValue(output({ content: null, exists: false }));
             const { usePersistentState } = require('./hooks');
             const [, setValue] = usePersistentState('counter', 0);
             // Calling setValue with a function should not throw and should
@@ -1221,9 +1208,7 @@ describe('SDK hooks', () => {
             });
             const { useStepNavigation } = require('./hooks');
             useStepNavigation(undefined, { persistKey: 'wizard' });
-            expect(mockBridge.request).toHaveBeenCalledWith('storage_read', {
-                path: '__state/wizard',
-            });
+            expect(mockBridge.request).toHaveBeenCalledWith(...entityOp(entity_ops_1.PLUGIN_STORAGE_ENTITY_ID, 'read', { path: '__state/wizard' }));
         });
         it('setCurrentStep updates state and schedules a persistent write when persistKey is set', () => {
             const { useStepNavigation } = require('./hooks');
@@ -1286,4 +1271,86 @@ describe('SDK hooks', () => {
         });
     });
 });
+describe('useDataSubscription (ADR-012 Phase M4)', () => {
+    const flush = async () => {
+        // Drain the effect's async subscribe chain (request → listeners → state).
+        await Promise.resolve();
+        await Promise.resolve();
+        await Promise.resolve();
+    };
+    function subscribed(subscriptionId = 'lsub_1') {
+        mockBridge.request.mockResolvedValue({
+            output: { kind: 'subscription', subscriptionId },
+        });
+    }
+    let mockBridge;
+    beforeEach(() => {
+        mockBridge = createMockBridge();
+        mockContextValue = mockBridge;
+        mockSingletonBridge = mockBridge;
+    });
+    it('subscribes via entity_invoke on the datastore entity and refetches once live', async () => {
+        subscribed();
+        const onInvalidate = jest.fn().mockResolvedValue(undefined);
+        const { useDataSubscription } = require('./hooks');
+        useDataSubscription('scores', onInvalidate);
+        await flush();
+        expect(mockBridge.request).toHaveBeenCalledWith('entity_invoke', {
+            entityId: 'ent_intg_plugin_datastore_000000',
+            payload: { op: 'subscribe', collection: 'scores', workspaceId: undefined },
+        });
+        expect(mockBridge.onSubscriptionEvent).toHaveBeenCalledWith('lsub_1', expect.any(Function));
+        expect(mockBridge.onSubscriptionEnded).toHaveBeenCalledWith('lsub_1', expect.any(Function));
+        // Subscribe-then-fetch: the initial refetch fires AFTER the
+        // subscription is live, closing the write-races-the-handshake gap.
+        expect(onInvalidate).toHaveBeenCalledTimes(1);
+        expect(mockSetState).toHaveBeenCalledWith({ status: 'active' });
+    });
+    it('runs onInvalidate single-flight with exactly one trailing call', async () => {
+        subscribed();
+        let resolveFirst = () => undefined;
+        const onInvalidate = jest
+            .fn()
+            .mockImplementationOnce(() => new Promise((resolve) => (resolveFirst = resolve)))
+            .mockResolvedValue(undefined);
+        const { useDataSubscription } = require('./hooks');
+        useDataSubscription('scores', onInvalidate);
+        await flush();
+        expect(onInvalidate).toHaveBeenCalledTimes(1); // initial, still in flight
+        const eventCb = mockBridge.onSubscriptionEvent.mock.calls[0][1];
+        eventCb();
+        eventCb();
+        eventCb();
+        expect(onInvalidate).toHaveBeenCalledTimes(1); // burst coalesced behind the in-flight run
+        resolveFirst();
+        await flush();
+        expect(onInvalidate).toHaveBeenCalledTimes(2); // exactly one trailing call
+    });
+    it('surfaces terminal endings and releases the subscription on cleanup', async () => {
+        subscribed();
+        const { useDataSubscription } = require('./hooks');
+        useDataSubscription('scores', jest.fn().mockResolvedValue(undefined));
+        await flush();
+        const endedCb = mockBridge.onSubscriptionEnded.mock.calls[0][1];
+        endedCb('collection_deleted');
+        expect(mockSetState).toHaveBeenCalledWith({
+            status: 'ended',
+            endedReason: 'collection_deleted',
+        });
+        capturedEffectCleanup?.();
+        expect(mockBridge.releaseSubscription).toHaveBeenCalledWith('lsub_1');
+    });
+    it('a malformed subscribe response ends with transport_error', async () => {
+        mockBridge.request.mockResolvedValue({ output: { data: null } });
+        const onInvalidate = jest.fn();
+        const { useDataSubscription } = require('./hooks');
+        useDataSubscription('scores', onInvalidate);
+        await flush();
+        expect(mockSetState).toHaveBeenCalledWith({
+            status: 'ended',
+            endedReason: 'transport_error',
+        });
+        expect(onInvalidate).not.toHaveBeenCalled();
+    });
+});
 //# sourceMappingURL=hooks.test.js.map