@fias/arche-sdk 2.3.0 → 2.11.0

package/dist/hooks.js

@@ -1,26 +1,33 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.GRAMMAR_CHECK_ENTITY_ID = exports.NLLB_LANGUAGES = exports.NLLB_TRANSLATION_ENTITY_ID = void 0;
 exports.useFiasUser = useFiasUser;
 exports.useFiasTheme = useFiasTheme;
+exports.useFiasVendoredAssets = useFiasVendoredAssets;
 exports.useFiasStorage = useFiasStorage;
 exports.useEntityInvocation = useEntityInvocation;
 exports.useImageGeneration = useImageGeneration;
 exports.useImageEntities = useImageEntities;
-exports.useBackgroundRemoval = useBackgroundRemoval;
+exports.useClientEntity = useClientEntity;
 exports.useAudioGeneration = useAudioGeneration;
 exports.useSurface = useSurface;
 exports.useFiasNavigation = useFiasNavigation;
 exports.usePersistentState = usePersistentState;
 exports.useStepNavigation = useStepNavigation;
 exports.useFiasDataStore = useFiasDataStore;
+exports.useFiasWorkspaces = useFiasWorkspaces;
 exports.useFiasStore = useFiasStore;
 exports.fetchVaultDocumentDownloadUrl = fetchVaultDocumentDownloadUrl;
 exports.useVaultDocuments = useVaultDocuments;
 exports.useArcheAssets = useArcheAssets;
+exports.useFiasPreviewState = useFiasPreviewState;
+exports.useDataSubscription = useDataSubscription;
+exports.useVaultUserDocuments = useVaultUserDocuments;
 const react_1 = require("react");
 const react_dom_1 = require("react-dom");
 const context_1 = require("./context");
 const bridge_1 = require("./bridge");
+const entity_ops_1 = require("./entity-ops");
 /**
  * Internal helper to get bridge from context, throws if not wrapped in FiasProvider.
  */
@@ -58,7 +65,7 @@ function createDebouncedWriter(bridge) {
         if (timerId !== null)
             clearTimeout(timerId);
         pending = null;
-        bridge.request('storage_write', { path, content }).catch(() => { });
+        (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.PLUGIN_STORAGE_ENTITY_ID, 'write', { path, content }).catch(() => { });
     }
     function schedule(path, content) {
         const now = Date.now();
@@ -84,21 +91,34 @@ function createDebouncedWriter(bridge) {
  * Access the current user's profile information.
  * Requires the `user:profile:read` permission in fias-plugin.json.
  *
+ * If the `get_user` bridge request fails — most commonly because the plugin
+ * called this hook without declaring `user:profile:read` — the error is
+ * thrown during render so it surfaces to the nearest error boundary
+ * (`FiasProvider` installs one). Previously a failed/denied request left the
+ * hook permanently returning `null`, indistinguishable from "still loading",
+ * so a UI that gated on `if (!user)` hung on an infinite spinner forever.
+ *
  * @returns The current user's profile or null while loading.
  */
 function useFiasUser() {
     const bridge = useBridge();
     const [user, setUser] = (0, react_1.useState)(null);
+    const [error, setError] = (0, react_1.useState)(null);
     (0, react_1.useEffect)(() => {
         let mounted = true;
         bridge.request('get_user', {}).then((data) => {
             if (mounted)
                 setUser(data);
+        }, (err) => {
+            if (mounted)
+                setError(err instanceof Error ? err : new Error(String(err)));
         });
         return () => {
             mounted = false;
         };
     }, [bridge]);
+    if (error)
+        throw error;
     return user;
 }
 /**
@@ -116,6 +136,25 @@ function useFiasTheme() {
     }, [bridge]);
     return theme;
 }
+/**
+ * Self-hosted asset URLs for a platform-vendored library, for plugins that
+ * declare the `sandbox:vendored-libraries` permission. Returns a file-key → URL
+ * map (for `pdfjs-dist`: `{ mainModule, worker, cMapUrl, standardFontDataUrl }`),
+ * or `null` when the host's CDN is unconfigured or the library isn't vendored
+ * (the plugin should then degrade gracefully).
+ *
+ * Delivered in the init payload (no gated request); values are static for the
+ * session. The import specifier is already pinned to its main module via the
+ * host importmap, so a plugin typically only needs `worker` (pass to the
+ * pdf-core loader's `workerModuleUrl`) and the CMap/font directories.
+ *
+ * @param importSpecifier The vendored library's bare module name (e.g. `'pdfjs-dist'`).
+ * @returns The library's asset URLs, or null if unavailable.
+ */
+function useFiasVendoredAssets(importSpecifier) {
+    const bridge = useBridge();
+    return bridge.getVendoredAssets(importSpecifier);
+}
 /**
  * Access the plugin's sandboxed storage.
  * Requires the `storage:sandbox` permission in fias-plugin.json.
@@ -125,18 +164,23 @@ function useFiasTheme() {
 function useFiasStorage() {
     const bridge = useBridge();
     const readFile = (0, react_1.useCallback)(async (path) => {
-        const res = await bridge.request('storage_read', { path });
+        const res = await (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.PLUGIN_STORAGE_ENTITY_ID, 'read', { path });
         return res?.content ?? null;
     }, [bridge]);
     const writeFile = (0, react_1.useCallback)(async (path, content) => {
-        await bridge.request('storage_write', { path, content });
+        await (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.PLUGIN_STORAGE_ENTITY_ID, 'write', {
+            path,
+            content,
+        });
     }, [bridge]);
     const listFiles = (0, react_1.useCallback)(async (prefix) => {
-        const res = await bridge.request('storage_list', { prefix });
+        const res = await (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.PLUGIN_STORAGE_ENTITY_ID, 'list', { prefix });
         return res?.files ?? [];
     }, [bridge]);
     const deleteFile = (0, react_1.useCallback)(async (path) => {
-        await bridge.request('storage_delete', { path });
+        await (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.PLUGIN_STORAGE_ENTITY_ID, 'delete', {
+            path,
+        });
     }, [bridge]);
     return { readFile, writeFile, listFiles, deleteFile };
 }
@@ -276,48 +320,63 @@ function useImageEntities(filter) {
     }, [fetchOnce]);
     return { entities, isLoading, error, refetch: fetchOnce };
 }
-/** Mirrors the host-side cap in the imgly executor. Pre-checked here so a
- *  100 MB blob isn't structured-cloned across postMessage just to be
- *  rejected. */
-const BG_REMOVAL_MAX_BYTES = 25 * 1024 * 1024;
 /**
- * Entity ID of the imgly background-removal client-side entity. Literal
- * here so the SDK stays bundle-clean (no `@fias/entities` runtime dep).
+ * `useBackgroundRemoval()` was REMOVED. It targeted the on-device imgly
+ * background-removal entity, which was retired platform-wide for
+ * licensing reasons (AGPL-3.0), along with its
+ * `entities:image_remove_background` permission.
  *
- * SYNC NOTE: must match `IMGLY_BACKGROUND_REMOVAL_ENTITY_ID` in
- * `packages/entities/src/integrations/imgly-background-removal/config.ts`.
- * The architecture test `sdk-entity-id-constants-match.test.ts` pins
- * this — drift fails CI.
+ * There is no client-side replacement. Server-side background removal is
+ * available to plugins through the paid `image.smart-remove-background`
+ * invocation surface (Stability / Recraft) under the
+ * `entities:image_edit` permission.
  */
-const IMGLY_BACKGROUND_REMOVAL_ENTITY_ID = 'ent_intg_imgly_bgrm_000000000000';
 /**
- * Remove the background from an image via the bridge's generic
- * `client_entity_invoke` op, targeting the imgly background-removal
- * entity. The host page runs the WASM model locally — bytes never leave
- * the user's device. Returns a transparent PNG.
+ * Default timeout for a client-side entity invocation. Client-side entities
+ * (WASM models, dictionary engines) can take many seconds to warm up and
+ * run, so we use the same 2-minute ceiling as the image/audio surfaces.
+ */
+const CLIENT_ENTITY_INVOKE_TIMEOUT_MS = 120000;
+/**
+ * Invoke a client-side ("on-device") entity through the bridge's generic
+ * `client_entity_invoke` op. Client-side entities execute entirely in the
+ * browser (e.g. the nspell + retext grammar checker, the NLLB-200
+ * translator) — input never leaves the device and there is no per-call
+ * credit cost.
+ *
+ * This is the client-side counterpart to {@link useEntityInvocation}, which
+ * invokes server-side, credit-billed AI entities. Target an entity by its ID
+ * and supply the input shape that entity documents; the typed result flows
+ * back through the returned promise:
  *
- * Requires the `entities:image_remove_background` permission in
- * `fias-plugin.json`. Inputs must be a PNG/JPEG `Blob` no larger than
- * 25 MiB. The bridge rate-limits to 10 calls/minute per arche per user
- * (sourced from the entity's `pluginInvocable.rateLimitPerMinute`).
+ * ```tsx
+ * const { invoke, isLoading, error } = useClientEntity();
+ * const { issues } = await invoke<GrammarCheckInput, GrammarCheckResult>(
+ *   GRAMMAR_CHECK_ENTITY_ID,
+ *   { text },
+ * );
+ * ```
+ *
+ * Requires the `entities:client_invoke` permission in `fias-plugin.json`.
+ * Per-entity rate limits (each entity's `pluginInvocable.rateLimitPerMinute`)
+ * are enforced by the host.
+ *
+ * Input limits are enforced **host-side by each entity's executor**, not by
+ * this hook — being generic, it cannot know a given entity's caps (e.g. the
+ * grammar entity's 100,000-character limit). Oversized/invalid input is
+ * rejected after it crosses the bridge, surfacing as a rejected promise /
+ * `error`. If you want to fail fast before the round-trip, pre-validate in
+ * your own code against the limits the entity documents.
  */
-function useBackgroundRemoval() {
+function useClientEntity() {
     const bridge = useBridge();
     const [isLoading, setIsLoading] = (0, react_1.useState)(false);
-    const [result, setResult] = (0, react_1.useState)(null);
     const [error, setError] = (0, react_1.useState)(null);
-    const removeBackground = (0, react_1.useCallback)(async (image) => {
-        if (image.size > BG_REMOVAL_MAX_BYTES) {
-            const e = new Error('background-removal: image exceeds 25 MiB limit');
-            setError(e);
-            throw e;
-        }
+    const invoke = (0, react_1.useCallback)(async (entityId, input) => {
         setIsLoading(true);
         setError(null);
         try {
-            const res = await bridge.request('client_entity_invoke', { entityId: IMGLY_BACKGROUND_REMOVAL_ENTITY_ID, input: { image } }, 120000);
-            setResult(res.image);
-            return res.image;
+            return await bridge.request('client_entity_invoke', { entityId, input }, CLIENT_ENTITY_INVOKE_TIMEOUT_MS);
         }
         catch (err) {
             const e = err instanceof Error ? err : new Error(String(err));
@@ -328,8 +387,76 @@ function useBackgroundRemoval() {
             setIsLoading(false);
         }
     }, [bridge]);
-    return { removeBackground, isLoading, result, error };
+    return { invoke, isLoading, error };
 }
+/**
+ * Entity ID of the NLLB-200 on-device translation entity. Exported so plugins
+ * can target it via the generic {@link useClientEntity} hook, with
+ * `TranslateParams` / `TranslationResult` as the I/O types.
+ *
+ * SYNC NOTE: must match `NLLB_TRANSLATION_ENTITY_ID` in
+ * `packages/entities/src/integrations/nllb-translation/config.ts`. The
+ * architecture test `sdk-entity-id-constants-match.test.ts` pins this —
+ * drift fails CI.
+ */
+exports.NLLB_TRANSLATION_ENTITY_ID = 'ent_intg_nllb_xlate_000000000000';
+/**
+ * Curated list of target languages for the NLLB translator, as
+ * label/FLORES-200-code pairs. Not exhaustive (NLLB supports 200 languages) —
+ * a convenient default set for building a picker. Sorted by label.
+ */
+exports.NLLB_LANGUAGES = [
+    { label: 'Arabic', code: 'arb_Arab' },
+    { label: 'Bengali', code: 'ben_Beng' },
+    { label: 'Bulgarian', code: 'bul_Cyrl' },
+    { label: 'Catalan', code: 'cat_Latn' },
+    { label: 'Chinese (Simplified)', code: 'zho_Hans' },
+    { label: 'Chinese (Traditional)', code: 'zho_Hant' },
+    { label: 'Croatian', code: 'hrv_Latn' },
+    { label: 'Czech', code: 'ces_Latn' },
+    { label: 'Danish', code: 'dan_Latn' },
+    { label: 'Dutch', code: 'nld_Latn' },
+    { label: 'English', code: 'eng_Latn' },
+    { label: 'Finnish', code: 'fin_Latn' },
+    { label: 'French', code: 'fra_Latn' },
+    { label: 'German', code: 'deu_Latn' },
+    { label: 'Greek', code: 'ell_Grek' },
+    { label: 'Hebrew', code: 'heb_Hebr' },
+    { label: 'Hindi', code: 'hin_Deva' },
+    { label: 'Hungarian', code: 'hun_Latn' },
+    { label: 'Indonesian', code: 'ind_Latn' },
+    { label: 'Italian', code: 'ita_Latn' },
+    { label: 'Japanese', code: 'jpn_Jpan' },
+    { label: 'Korean', code: 'kor_Hang' },
+    { label: 'Norwegian', code: 'nob_Latn' },
+    { label: 'Persian', code: 'pes_Arab' },
+    { label: 'Polish', code: 'pol_Latn' },
+    { label: 'Portuguese', code: 'por_Latn' },
+    { label: 'Romanian', code: 'ron_Latn' },
+    { label: 'Russian', code: 'rus_Cyrl' },
+    { label: 'Serbian', code: 'srp_Cyrl' },
+    { label: 'Slovak', code: 'slk_Latn' },
+    { label: 'Spanish', code: 'spa_Latn' },
+    { label: 'Swedish', code: 'swe_Latn' },
+    { label: 'Tamil', code: 'tam_Taml' },
+    { label: 'Telugu', code: 'tel_Telu' },
+    { label: 'Thai', code: 'tha_Thai' },
+    { label: 'Turkish', code: 'tur_Latn' },
+    { label: 'Ukrainian', code: 'ukr_Cyrl' },
+    { label: 'Urdu', code: 'urd_Arab' },
+    { label: 'Vietnamese', code: 'vie_Latn' },
+];
+/**
+ * Entity ID of the grammar_check client-side entity. Exported so plugins can
+ * target it via the generic {@link useClientEntity} hook. Literal here so the
+ * SDK stays bundle-clean (no `@fias/entities` runtime dep).
+ *
+ * SYNC NOTE: must match `GRAMMAR_CHECK_ENTITY_ID` in
+ * `packages/entities/src/integrations/grammar-check/config.ts`. The
+ * architecture test `sdk-entity-id-constants-match.test.ts` pins this —
+ * drift fails CI.
+ */
+exports.GRAMMAR_CHECK_ENTITY_ID = 'ent_intg_grammar_check_000000000';
 /**
  * Generate audio (music today; future speech/SFX sub-types via the same
  * hook) via the bridge's `audio_generate` op. Returns an array of clips
@@ -414,9 +541,10 @@ function useSurface(surfaceKey, timeoutMs = 180000) {
     return { invoke, isLoading, result, error };
 }
 /**
- * Navigate within the plugin's route space.
+ * Navigate within the plugin's route space (`navigateTo`), or open another
+ * arche's page (`openArche`, requires the `navigation:open_arche` permission).
  *
- * @returns Navigation API (navigateTo, currentPath).
+ * @returns Navigation API (navigateTo, openArche, currentPath).
  */
 function useFiasNavigation() {
     const bridge = useBridge();
@@ -441,7 +569,10 @@ function useFiasNavigation() {
     const navigateTo = (0, react_1.useCallback)((path) => {
         bridge.request('navigate', { path });
     }, [bridge]);
-    return { navigateTo, currentPath };
+    const openArche = (0, react_1.useCallback)((archeId, opts) => {
+        bridge.request('open_arche', { archeId, newTab: opts?.newTab === true });
+    }, [bridge]);
+    return { navigateTo, openArche, currentPath };
 }
 /**
  * Like useState, but auto-persists to bridge storage.
@@ -459,8 +590,7 @@ function usePersistentState(key, initialValue) {
     // Load from storage on mount; flush any pending write on unmount/key change
     // so rapid updates in a game loop never lose their last value.
     (0, react_1.useEffect)(() => {
-        bridge
-            .request('storage_read', { path: `__state/${key}` })
+        (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.PLUGIN_STORAGE_ENTITY_ID, 'read', { path: `__state/${key}` })
             .then((result) => {
             if (result.exists && result.content !== null) {
                 try {
@@ -473,6 +603,13 @@ function usePersistentState(key, initialValue) {
                 }
             }
             initializedRef.current = true;
+        })
+            .catch(() => {
+            // A failed/denied storage_read (e.g. the plugin didn't declare
+            // `storage:sandbox`) must not become a silent unhandled rejection.
+            // Persistence is best-effort — fall back to the initial value and
+            // let subsequent writes fail on their own rather than hanging here.
+            initializedRef.current = true;
         });
         return () => {
             writer.flush();
@@ -514,10 +651,7 @@ function useStepNavigation(initialStep, options) {
             return;
         }
         let cancelled = false;
-        bridge
-            .request('storage_read', {
-            path: `__state/${persistKey}`,
-        })
+        (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.PLUGIN_STORAGE_ENTITY_ID, 'read', { path: `__state/${persistKey}` })
             .then((result) => {
             // Don't clobber a user-initiated setCurrentStep that landed before this resolved.
             if (cancelled || initializedRef.current)
@@ -590,34 +724,81 @@ function useStepNavigation(initialStep, options) {
 function useFiasDataStore() {
     const bridge = useBridge();
     const createCollection = (0, react_1.useCallback)(async (name, options) => {
-        const res = await bridge.request('data_create_collection', { name, userScope: options?.userScope ?? 'user' });
+        const res = await (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.PLUGIN_DATASTORE_ENTITY_ID, 'create_collection', {
+            name,
+            userScope: options?.userScope ?? 'user',
+            searchable: options?.searchable,
+            writeMinRole: options?.writeMinRole,
+            readMinRole: options?.readMinRole,
+            writePolicy: options?.writePolicy,
+        });
         return res.collection;
     }, [bridge]);
     const listCollections = (0, react_1.useCallback)(async () => {
-        const res = await bridge.request('data_list_collections', {});
+        const res = await (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.PLUGIN_DATASTORE_ENTITY_ID, 'list_collections');
         return res.collections;
     }, [bridge]);
     const deleteCollection = (0, react_1.useCallback)(async (name) => {
-        await bridge.request('data_delete_collection', { name });
+        await (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.PLUGIN_DATASTORE_ENTITY_ID, 'delete_collection', { name });
     }, [bridge]);
-    const put = (0, react_1.useCallback)(async (collection, key, data) => {
-        await bridge.request('data_put', { collection, key, data });
+    const put = (0, react_1.useCallback)(async (collection, key, data, options) => {
+        await (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.PLUGIN_DATASTORE_ENTITY_ID, 'put', {
+            collection,
+            key,
+            data,
+            workspaceId: options?.workspaceId,
+        });
     }, [bridge]);
-    const get = (0, react_1.useCallback)(async (collection, key) => {
-        const res = await bridge.request('data_get', {
+    const get = (0, react_1.useCallback)(async (collection, key, options) => {
+        const res = await (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.PLUGIN_DATASTORE_ENTITY_ID, 'get', {
             collection,
             key,
+            workspaceId: options?.workspaceId,
         });
         return res.data;
     }, [bridge]);
-    const query = (0, react_1.useCallback)(async (collection, options) => {
-        return bridge.request('data_query', {
+    const getDocument = (0, react_1.useCallback)(async (collection, key, options) => {
+        const res = await (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.PLUGIN_DATASTORE_ENTITY_ID, 'get', {
+            collection,
+            key,
+            workspaceId: options?.workspaceId,
+        });
+        if (res.data === null || res.data === undefined)
+            return null;
+        return {
+            key: res.key ?? key,
+            data: res.data,
+            updatedAt: res.updatedAt ?? '',
+            ...(res.authoredByCollaborator !== undefined
+                ? { authoredByCollaborator: res.authoredByCollaborator }
+                : {}),
+        };
+    }, [bridge]);
+    const query = (0, react_1.useCallback)(async (collection, options, scope) => {
+        return (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.PLUGIN_DATASTORE_ENTITY_ID, 'query', {
             collection,
             ...options,
+            workspaceId: scope?.workspaceId,
         });
     }, [bridge]);
-    const deleteDoc = (0, react_1.useCallback)(async (collection, key) => {
-        await bridge.request('data_delete', { collection, key });
+    const search = (0, react_1.useCallback)(async (collection, queryText, options, scope) => {
+        const res = await (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.PLUGIN_DATASTORE_ENTITY_ID, 'search', {
+            collection,
+            query: queryText,
+            ...options,
+            workspaceId: scope?.workspaceId,
+        });
+        return res.matches;
+    }, [bridge]);
+    const deleteDoc = (0, react_1.useCallback)(async (collection, key, options) => {
+        await (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.PLUGIN_DATASTORE_ENTITY_ID, 'delete', {
+            collection,
+            key,
+            workspaceId: options?.workspaceId,
+        });
+    }, [bridge]);
+    const batch = (0, react_1.useCallback)(async (operations) => {
+        await (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.PLUGIN_DATASTORE_ENTITY_ID, 'batch', { operations });
     }, [bridge]);
     return (0, react_1.useMemo)(() => ({
         createCollection,
@@ -625,9 +806,84 @@ function useFiasDataStore() {
         deleteCollection,
         put,
         get,
+        getDocument,
         query,
+        search,
         delete: deleteDoc,
-    }), [createCollection, listCollections, deleteCollection, put, get, query, deleteDoc]);
+        batch,
+    }), [
+        createCollection,
+        listCollections,
+        deleteCollection,
+        put,
+        get,
+        getDocument,
+        query,
+        search,
+        deleteDoc,
+        batch,
+    ]);
+}
+/**
+ * Access workspace tenancy — team/org workspaces with role-gated membership
+ * (owner/admin/member/viewer) over `workspace`-scoped Data Store collections
+ * (ADR-010). The creating user becomes the founding owner; a workspace always
+ * keeps at least one owner.
+ *
+ * Requires the `data:workspace` permission in fias-plugin.json. To read/write a
+ * workspace's documents, use `useFiasDataStore()` with `{ workspaceId }` on a
+ * collection created with `userScope: 'workspace'`.
+ *
+ * @example
+ * const workspaces = useFiasWorkspaces();
+ * const ws = await workspaces.create('Acme Corp');
+ * await workspaces.addMember(ws.workspaceId, otherUserId, 'member');
+ * // then, with useFiasDataStore():
+ * await dataStore.put('ledger', 'tx-1', { amount: 100 }, { workspaceId: ws.workspaceId });
+ *
+ * @returns Workspace API with lifecycle + membership methods.
+ */
+function useFiasWorkspaces() {
+    const bridge = useBridge();
+    const create = (0, react_1.useCallback)(async (displayName) => {
+        const res = await (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.PLUGIN_WORKSPACES_ENTITY_ID, 'create', { displayName });
+        return res.workspace;
+    }, [bridge]);
+    const list = (0, react_1.useCallback)(async () => {
+        const res = await (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.PLUGIN_WORKSPACES_ENTITY_ID, 'list');
+        return res.workspaces;
+    }, [bridge]);
+    const get = (0, react_1.useCallback)(async (workspaceId) => {
+        const res = await (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.PLUGIN_WORKSPACES_ENTITY_ID, 'get', { workspaceId });
+        return res.workspace;
+    }, [bridge]);
+    const archive = (0, react_1.useCallback)(async (workspaceId) => {
+        await (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.PLUGIN_WORKSPACES_ENTITY_ID, 'archive', { workspaceId });
+    }, [bridge]);
+    const listMembers = (0, react_1.useCallback)(async (workspaceId) => {
+        const res = await (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.PLUGIN_WORKSPACES_ENTITY_ID, 'list_members', { workspaceId });
+        return res.members;
+    }, [bridge]);
+    const addMember = (0, react_1.useCallback)(async (workspaceId, username, role, expiresAt) => {
+        const res = await (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.PLUGIN_WORKSPACES_ENTITY_ID, 'add_member', {
+            workspaceId,
+            username,
+            role,
+            expiresAt,
+        });
+        return res.member;
+    }, [bridge]);
+    const updateMember = (0, react_1.useCallback)(async (workspaceId, username, role) => {
+        const res = await (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.PLUGIN_WORKSPACES_ENTITY_ID, 'update_member', { workspaceId, username, role });
+        return res.member;
+    }, [bridge]);
+    const removeMember = (0, react_1.useCallback)(async (workspaceId, username) => {
+        await (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.PLUGIN_WORKSPACES_ENTITY_ID, 'remove_member', {
+            workspaceId,
+            username,
+        });
+    }, [bridge]);
+    return (0, react_1.useMemo)(() => ({ create, list, get, archive, listMembers, addMember, updateMember, removeMember }), [create, list, get, archive, listMembers, addMember, updateMember, removeMember]);
 }
 /**
  * Access the in-arche purchase (IAP) store.
@@ -647,8 +903,8 @@ function useFiasStore() {
     (0, react_1.useEffect)(() => {
         let mounted = true;
         Promise.all([
-            bridge.request('store_get_products', {}),
-            bridge.request('store_get_entitlements', {}),
+            (0, entity_ops_1.invokeStoreOp)(bridge, 'get_products'),
+            (0, entity_ops_1.invokeStoreOp)(bridge, 'get_entitlements'),
         ])
             .then(([prods, ents]) => {
             if (mounted) {
@@ -666,7 +922,7 @@ function useFiasStore() {
         };
     }, [bridge]);
     const purchase = (0, react_1.useCallback)(async (productIdentifier, options) => {
-        const result = await bridge.request('store_purchase', {
+        const result = await (0, entity_ops_1.invokeStoreOp)(bridge, 'purchase', {
             productIdentifier,
             ...options,
         });
@@ -688,11 +944,11 @@ function useFiasStore() {
         return entitlements.some((e) => e.productIdentifier === productIdentifier && e.isActive);
     }, [entitlements]);
     const getPurchaseHistory = (0, react_1.useCallback)(async () => {
-        const res = await bridge.request('store_get_purchase_history', {});
+        const res = await (0, entity_ops_1.invokeStoreOp)(bridge, 'get_purchase_history');
         return res.purchases;
     }, [bridge]);
     const restorePurchases = (0, react_1.useCallback)(async () => {
-        const restored = await bridge.request('store_restore', {});
+        const restored = await (0, entity_ops_1.invokeStoreOp)(bridge, 'restore');
         setEntitlements(restored);
         return restored;
     }, [bridge]);
@@ -871,37 +1127,24 @@ function useVaultDocuments() {
         });
     }, [bridge]);
     const upload = (0, react_1.useCallback)(async (bytes, params) => {
-        // Copy into a freshly-allocated, non-shared ArrayBuffer so the
-        // SubtleCrypto + fetch overloads resolve cleanly. (Uint8Array's
-        // generic ArrayBufferLike parameter pessimistically widens to
-        // ArrayBuffer|SharedArrayBuffer, which neither API accepts.)
+        // The presigned PUT must run in the HOST, not here: the plugin iframe's
+        // CSP is `connect-src 'none'`, which silently blocks an in-iframe
+        // `fetch` PUT in published plugins. The host (parent window, no
+        // connect-src restriction) orchestrates init → PUT → finalize via the
+        // `vault_documents_upload` bridge op; the presigned URL is backend-issued
+        // host-side, so the iframe can't redirect the PUT (no SSRF). The
+        // lower-level `uploadInit`/`uploadFinalize` remain for advanced callers.
         const src = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
-        const u8 = new Uint8Array(src.byteLength);
-        u8.set(src);
-        const sizeBytes = u8.byteLength;
-        const digest = await crypto.subtle.digest('SHA-256', u8);
-        const checksumHex = bytesToHex(new Uint8Array(digest));
-        const init = await uploadInit({ ...params, sizeBytes, checksumSha256: checksumHex });
-        // PUT the bytes directly to S3 using the headers the server
-        // signed. Browsers forbid setting `Content-Length` explicitly
-        // (the Fetch spec lists it as forbidden — the browser computes
-        // it from `body.byteLength` automatically). Filter it out so the
-        // fetch doesn't either error in strict mode or silently send a
-        // different length than what we tried to pass. The signed value
-        // still matches because S3 sees the auto-set length, which the
-        // server matched against `sizeBytes` at init time.
-        const browserHeaders = Object.fromEntries(Object.entries(init.requiredHeaders).filter(([k]) => k.toLowerCase() !== 'content-length'));
-        const putResp = await fetch(init.uploadUrl, {
-            method: 'PUT',
-            body: u8,
-            headers: browserHeaders,
+        return bridge.request('vault_documents_upload', {
+            name: params.name,
+            mimeType: params.mimeType,
+            bytes: bytesToBase64(src),
+            tags: params.tags,
+            sensitivity: params.sensitivity,
+            folderPath: params.folderPath,
+            replacesDocumentId: params.replacesDocumentId,
         });
-        if (!putResp.ok) {
-            const text = await putResp.text().catch(() => '');
-            throw new Error(`Vault upload PUT failed (${putResp.status}): ${text || putResp.statusText}`);
-        }
-        return uploadFinalize({ documentId: init.documentId, checksumSha256: checksumHex });
-    }, [uploadInit, uploadFinalize]);
+    }, [bridge]);
     return (0, react_1.useMemo)(() => ({
         list,
         read,
@@ -930,19 +1173,15 @@ function useVaultDocuments() {
         uploadFinalize,
     ]);
 }
-/**
- * Render a byte array as lowercase hex. Used by `upload` to convert
- * the `crypto.subtle.digest('SHA-256', ...)` output into the
- * wire-format (hex) that the bridge expects. S3 still wants base64
- * for `x-amz-checksum-sha256` — that conversion happens server-side
- * in `generatePresignedUploadUrl`, not here.
- */
-function bytesToHex(bytes) {
-    let out = '';
-    for (let i = 0; i < bytes.length; i++) {
-        out += bytes[i].toString(16).padStart(2, '0');
+/** Base64-encode bytes for transport to the host's `vault_documents_upload`
+ *  op (the host does the presigned PUT — see PluginBridge.handleVaultUpload). */
+function bytesToBase64(bytes) {
+    let binary = '';
+    const chunk = 0x8000;
+    for (let i = 0; i < bytes.length; i += chunk) {
+        binary += String.fromCharCode(...bytes.subarray(i, i + chunk));
     }
-    return out;
+    return btoa(binary);
 }
 /**
  * Access the contributor-curated asset library for this arche.
@@ -980,4 +1219,188 @@ function useArcheAssets() {
     }, [bridge]);
     return (0, react_1.useMemo)(() => ({ list, index, getUrl }), [list, index, getUrl]);
 }
+/**
+ * Preserve transient UI state across a builder-preview rebuild.
+ *
+ * In the arche builder, editing code (or a background cross-device sync)
+ * rebuilds the preview, which reloads the iframe and wipes the plugin's
+ * in-memory state — losing, for example, a report the user just generated.
+ * This hook lets you opt that state into host-side preservation: just before
+ * the reload the host snapshots `getState()`, and after the reload it hands the
+ * value back to `onRestore`.
+ *
+ * Inert outside the builder preview (the host never requests a capture), so
+ * it's safe to leave in production plugin code.
+ *
+ * @param key       Stable namespace for this slice of state (so multiple calls
+ *                  don't collide). Use a literal like `'report'`.
+ * @param getState  Returns the current serializable state. Must be JSON-safe.
+ * @param onRestore Receives the snapshot after a reload. Reads the latest
+ *                  closure via a ref, so you don't need a stable identity.
+ *
+ * @example
+ * const [report, setReport] = useState<Report | null>(null);
+ * useFiasPreviewState('report', () => report, (saved) => setReport(saved as Report));
+ */
+function useFiasPreviewState(key, getState, onRestore) {
+    const bridge = useBridge();
+    const getStateRef = (0, react_1.useRef)(getState);
+    getStateRef.current = getState;
+    const onRestoreRef = (0, react_1.useRef)(onRestore);
+    onRestoreRef.current = onRestore;
+    (0, react_1.useEffect)(() => {
+        return bridge.registerPreviewState(key, () => getStateRef.current(), (state) => onRestoreRef.current(state));
+    }, [bridge, key]);
+}
+/**
+ * Subscribes to realtime change events for a datastore collection
+ * (ADR-012 Phase M4). Notify-then-refetch: the platform pushes a minimal
+ * "this collection changed" invalidation and `onInvalidate` decides what to
+ * refetch — typically re-running the `useFiasDataStore().query(...)` your
+ * component renders from.
+ *
+ * Requires the `data:store` permission (same as reading the collection —
+ * a live invalidation grants nothing polling couldn't retrieve).
+ *
+ * Semantics and guarantees:
+ * - Best-effort, at-most-once delivery: events can be lost or duplicated;
+ *   the initial refetch fires AFTER the subscription is live, so a write
+ *   racing the subscribe is never missed.
+ * - `onInvalidate` runs single-flight with one trailing call: a burst of
+ *   events during an in-flight refetch coalesces into exactly one more.
+ * - The host renews authorization periodically; when it definitively ends
+ *   (`status: 'ended'`), `endedReason` says why — `collection_deleted` and
+ *   `authorization_revoked` are terminal, others may warrant resubscribing
+ *   (unmount/remount or toggle `enabled`).
+ * - Scope-aware: shared collections notify on any user's writes; user-scoped
+ *   collections only on yours; workspace-scoped need `workspaceId` and an
+ *   active membership.
+ *
+ * @example
+ * const dataStore = useFiasDataStore();
+ * const [scores, setScores] = useState<DataStoreDocument[]>([]);
+ * const refresh = useCallback(async () => {
+ *   const res = await dataStore.query('scores', { limit: 50 });
+ *   setScores(res.documents);
+ * }, [dataStore]);
+ * const { status } = useDataSubscription('scores', refresh);
+ */
+function useDataSubscription(collection, onInvalidate, options) {
+    const bridge = useBridge();
+    const [state, setState] = (0, react_1.useState)({ status: 'subscribing' });
+    const onInvalidateRef = (0, react_1.useRef)(onInvalidate);
+    onInvalidateRef.current = onInvalidate;
+    const enabled = options?.enabled ?? true;
+    const workspaceId = options?.workspaceId;
+    (0, react_1.useEffect)(() => {
+        if (!enabled) {
+            setState({ status: 'ended', endedReason: 'unsubscribed' });
+            return;
+        }
+        let cancelled = false;
+        let subscriptionId = null;
+        let unsubscribeEvent = null;
+        let unsubscribeEnded = null;
+        // Single-flight + exactly one trailing call: events arriving during an
+        // in-flight refetch coalesce into one follow-up, never a parallel run.
+        let refetching = false;
+        let trailing = false;
+        const runInvalidate = async () => {
+            if (refetching) {
+                trailing = true;
+                return;
+            }
+            refetching = true;
+            try {
+                await onInvalidateRef.current();
+            }
+            catch {
+                // The caller's refetch failed — their concern; the subscription
+                // stays live and the next event tries again.
+            }
+            refetching = false;
+            if (trailing && !cancelled) {
+                trailing = false;
+                void runInvalidate();
+            }
+        };
+        setState({ status: 'subscribing' });
+        void (async () => {
+            try {
+                const res = await bridge.request('entity_invoke', {
+                    entityId: entity_ops_1.PLUGIN_DATASTORE_ENTITY_ID,
+                    payload: { op: 'subscribe', collection, workspaceId },
+                });
+                const subscription = res?.output;
+                if (!subscription ||
+                    subscription.kind !== 'subscription' ||
+                    typeof subscription.subscriptionId !== 'string') {
+                    if (!cancelled)
+                        setState({ status: 'ended', endedReason: 'transport_error' });
+                    return;
+                }
+                if (cancelled) {
+                    bridge.releaseSubscription(subscription.subscriptionId);
+                    return;
+                }
+                subscriptionId = subscription.subscriptionId;
+                unsubscribeEvent = bridge.onSubscriptionEvent(subscriptionId, () => void runInvalidate());
+                unsubscribeEnded = bridge.onSubscriptionEnded(subscriptionId, (reason) => {
+                    if (!cancelled)
+                        setState({ status: 'ended', endedReason: reason });
+                });
+                setState({ status: 'active' });
+                // Subscribe-then-fetch ordering: refetch AFTER the subscription is
+                // live so a write racing the handshake is reflected either in this
+                // fetch or in the event it triggers — never silently missed.
+                void runInvalidate();
+            }
+            catch {
+                if (!cancelled)
+                    setState({ status: 'ended', endedReason: 'transport_error' });
+            }
+        })();
+        return () => {
+            cancelled = true;
+            unsubscribeEvent?.();
+            unsubscribeEnded?.();
+            if (subscriptionId)
+                bridge.releaseSubscription(subscriptionId);
+        };
+    }, [bridge, collection, workspaceId, enabled]);
+    return state;
+}
+/**
+ * Consented access to documents the USER already owns — the only SDK
+ * surface that reaches data your plugin did not create. Requires the
+ * `vault:user-documents:read` permission. Every access is user-consented
+ * (per-document grants created in the host picker, revocable any time in
+ * Vault → App Access) and audited by the platform. Proprietary-sensitivity
+ * documents are never grantable. For documents your plugin CREATES, use
+ * `useVaultDocuments` instead.
+ */
+function useVaultUserDocuments() {
+    const bridge = useBridge();
+    const pick = (0, react_1.useCallback)(async (options) => {
+        return bridge.request('vault_documents_pick', {
+            maxDocuments: options?.maxDocuments,
+        });
+    }, [bridge]);
+    const list = (0, react_1.useCallback)(async (options) => {
+        const res = await (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.VAULT_USER_DOCUMENTS_ENTITY_ID, 'list_consented_documents', { limit: options?.limit, offset: options?.offset });
+        return res.documents;
+    }, [bridge]);
+    const get = (0, react_1.useCallback)(async (documentId, options) => {
+        return (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.VAULT_USER_DOCUMENTS_ENTITY_ID, 'get_consented_document', { documentId, includeContent: options?.includeContent });
+    }, [bridge]);
+    const getDownloadUrl = (0, react_1.useCallback)(async (documentId) => {
+        const res = await (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.VAULT_USER_DOCUMENTS_ENTITY_ID, 'get_consented_document_url', { documentId });
+        return {
+            url: res.url,
+            expiresAt: new Date(res.expiresAt).getTime(),
+            contentType: res.contentType,
+        };
+    }, [bridge]);
+    return (0, react_1.useMemo)(() => ({ pick, list, get, getDownloadUrl }), [pick, list, get, getDownloadUrl]);
+}
 //# sourceMappingURL=hooks.js.map