@fias/arche-sdk 2.29.0 → 2.30.0

package/dist/hooks.js

@@ -15,10 +15,13 @@ exports.useAudioGeneration = useAudioGeneration;
 exports.useSurface = useSurface;
 exports.useFiasNavigation = useFiasNavigation;
 exports.usePersistentState = usePersistentState;
+exports.useFiasChrome = useFiasChrome;
 exports.useStepNavigation = useStepNavigation;
 exports.useFiasDataStore = useFiasDataStore;
 exports.useFiasWorkspaces = useFiasWorkspaces;
+exports.useFiasAccess = useFiasAccess;
 exports.useFiasStore = useFiasStore;
+exports.clearSdkReadCaches = clearSdkReadCaches;
 exports.fetchVaultDocumentDownloadUrl = fetchVaultDocumentDownloadUrl;
 exports.useVaultDocuments = useVaultDocuments;
 exports.useArcheAssets = useArcheAssets;
@@ -26,8 +29,10 @@ exports.useArcheAssetBytes = useArcheAssetBytes;
 exports.useLocalStore = useLocalStore;
 exports.useFiasContent = useFiasContent;
 exports.useFiasPreviewState = useFiasPreviewState;
+exports.useEntitySubscription = useEntitySubscription;
 exports.useDataSubscription = useDataSubscription;
 exports.useVaultUserDocuments = useVaultUserDocuments;
+exports.useCreativeLibrary = useCreativeLibrary;
 exports.useFiasConnections = useFiasConnections;
 exports.useFiasX = useFiasX;
 exports.useFiasSchedules = useFiasSchedules;
@@ -744,6 +749,94 @@ function usePersistentState(key, initialValue) {
     }, [key, writer]);
     return [value, setValue];
 }
+/** What a plugin sees before init, and on a host without the chrome lane. */
+const INERT_CHROME = {
+    focusMode: false,
+    focusModeAvailable: false,
+    sidebarAvailable: false,
+    sidebarCollapsed: false,
+    hostExpandedBar: true,
+    hostExpandButton: true,
+};
+/**
+ * The host chrome around your arche — Fias's standard expand/contract (the
+ * internal arches' "focus mode"), the suggested-arches sidebar, and the four
+ * controls the platform's focus-mode bar carries (Fias home, Worktop, Fias
+ * AI, Collapse), so you can place them where your design wants them.
+ *
+ * Three levels, your choice:
+ *  1. Don't call this. The host draws a small expand button over your app;
+ *     expanding shows the host's thin bar with the standard four controls.
+ *  2. Call it and draw your own expand button (`setFocusMode`) and sidebar
+ *     toggle (`setSidebarCollapsed`); keep the host's bar for the way back.
+ *  3. Call it, `setHostExpandedBar(false)`, and draw your own bar from
+ *     `goToFiasHome` / `goToWorktop` / `openAssistant` / `setFocusMode(false)`.
+ *
+ * MOUNTING THIS HOOK TAKES THE CHROME OVER: the host's default expand button
+ * goes away, because a plugin that reads chrome state is expected to draw its
+ * own affordance. Draw one (or set `showExpandButton: false` in the manifest
+ * if you want neither). The host decides what is available — `focusModeAvailable`
+ * is false outside the normal signed-in layout and `sidebarAvailable` is false
+ * where the manifest declined the sidebar — so gate your controls on them.
+ *
+ * `supported` is false before init and on an older host; the state is then
+ * inert and the setters are no-ops, so you can render unconditionally.
+ */
+function useFiasChrome() {
+    const bridge = useBridge();
+    const [chrome, setChrome] = (0, react_1.useState)(bridge.getChrome());
+    const [supported, setSupported] = (0, react_1.useState)(bridge.hasChromeSupport());
+    (0, react_1.useEffect)(() => {
+        // Same "subscribed after init" race as useFiasNavigation: sync on ready
+        // and subscribe for every later change.
+        let cancelled = false;
+        bridge.waitForInit().then(() => {
+            if (cancelled)
+                return;
+            setChrome(bridge.getChrome());
+            setSupported(bridge.hasChromeSupport());
+        });
+        const unsubscribe = bridge.onChromeUpdate((next) => {
+            setChrome(next);
+            setSupported(bridge.hasChromeSupport());
+        });
+        return () => {
+            cancelled = true;
+            unsubscribe();
+        };
+    }, [bridge]);
+    // The takeover, once per bridge: the host drops its default expand button
+    // the moment a plugin reads the chrome. Sent on mount — an older host
+    // ignores an unknown message type.
+    (0, react_1.useEffect)(() => {
+        bridge.setChrome({ hostExpandButton: false });
+    }, [bridge]);
+    const setFocusMode = (0, react_1.useCallback)((on) => bridge.setChrome({ focusMode: on }), [bridge]);
+    const setSidebarCollapsed = (0, react_1.useCallback)((collapsed) => bridge.setChrome({ sidebarCollapsed: collapsed }), [bridge]);
+    const setHostExpandedBar = (0, react_1.useCallback)((shown) => bridge.setChrome({ hostExpandedBar: shown }), [bridge]);
+    const goToFiasHome = (0, react_1.useCallback)(() => bridge.navigateHost('home'), [bridge]);
+    const goToWorktop = (0, react_1.useCallback)(() => bridge.navigateHost('worktop'), [bridge]);
+    const openAssistant = (0, react_1.useCallback)(() => bridge.openAssistant(), [bridge]);
+    return (0, react_1.useMemo)(() => ({
+        ...(chrome ?? INERT_CHROME),
+        supported: supported && chrome !== null,
+        setFocusMode,
+        setSidebarCollapsed,
+        setHostExpandedBar,
+        goToFiasHome,
+        goToWorktop,
+        openAssistant,
+    }), [
+        chrome,
+        supported,
+        setFocusMode,
+        setSidebarCollapsed,
+        setHostExpandedBar,
+        goToFiasHome,
+        goToWorktop,
+        openAssistant,
+    ]);
+}
 /**
  * Manage step navigation for multi-node plugins.
  * Listens for step_navigate messages from the host to support
@@ -866,17 +959,32 @@ function useFiasDataStore() {
     const put = (0, react_1.useCallback)(async (collection, key, data, options) => {
         const res = await (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.PLUGIN_DATASTORE_ENTITY_ID, 'put', {
             collection,
-            key,
+            // No key: the server makes one (collections with audiences, ADR-034).
+            ...(key !== null ? { key } : {}),
             data,
             workspaceId: options?.workspaceId,
+            ...(options?.audience !== undefined ? { audience: options.audience } : {}),
         });
-        return { version: res?.version };
+        return {
+            version: res?.version,
+            ...(res?.key !== undefined ? { key: res.key } : {}),
+            ...(res?.audience !== undefined ? { audience: res.audience } : {}),
+        };
     }, [bridge]);
+    const create = (0, react_1.useCallback)(async (collection, data, options) => {
+        const result = await put(collection, null, data, options);
+        if (result.key === undefined) {
+            // A host that predates server-generated keys cannot have made one.
+            throw new bridge_1.FiasBridgeError('This Fias does not support creating documents in audiences yet', 'AUDIENCES_UNAVAILABLE');
+        }
+        return { ...result, key: result.key };
+    }, [put]);
     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,
+            ...(options?.audience !== undefined ? { audience: options.audience } : {}),
         });
         return res.data;
     }, [bridge]);
@@ -885,6 +993,7 @@ function useFiasDataStore() {
             collection,
             key,
             workspaceId: options?.workspaceId,
+            ...(options?.audience !== undefined ? { audience: options.audience } : {}),
         });
         if (res.data === null || res.data === undefined)
             return null;
@@ -896,6 +1005,7 @@ function useFiasDataStore() {
             ...(res.authoredByCollaborator !== undefined
                 ? { authoredByCollaborator: res.authoredByCollaborator }
                 : {}),
+            ...(res.audience !== undefined ? { audience: res.audience } : {}),
         };
     }, [bridge]);
     const query = (0, react_1.useCallback)(async (collection, options, scope) => {
@@ -910,6 +1020,7 @@ function useFiasDataStore() {
             // rather than at the call. Take the scope arg when it carries one and
             // otherwise leave whatever the spread put there.
             ...(scope?.workspaceId !== undefined ? { workspaceId: scope.workspaceId } : {}),
+            ...(scope?.audience !== undefined ? { audience: scope.audience } : {}),
         });
     }, [bridge]);
     const search = (0, react_1.useCallback)(async (collection, queryText, options, scope) => {
@@ -919,6 +1030,7 @@ function useFiasDataStore() {
             ...options,
             // See `query` above — never blank a caller-supplied workspaceId.
             ...(scope?.workspaceId !== undefined ? { workspaceId: scope.workspaceId } : {}),
+            ...(scope?.audience !== undefined ? { audience: scope.audience } : {}),
         });
         return res.matches;
     }, [bridge]);
@@ -941,6 +1053,7 @@ function useFiasDataStore() {
         listCollections,
         deleteCollection,
         put,
+        create,
         get,
         getDocument,
         query,
@@ -952,6 +1065,7 @@ function useFiasDataStore() {
         listCollections,
         deleteCollection,
         put,
+        create,
         get,
         getDocument,
         query,
@@ -1049,6 +1163,308 @@ function useFiasWorkspaces() {
         removeMember,
     ]);
 }
+/** The refusals that mean "no access here" — the workspaces `get` verb's two answers. */
+const NO_WORKSPACE_ACCESS_CODES = new Set([
+    'NOT_A_MEMBER',
+    'WORKSPACE_NOT_FOUND',
+]);
+/**
+ * The current user's OWN access in a workspace (ADR-034): their tier
+ * (owner/admin/member/viewer), when their membership expires, and — for an
+ * app that declares roles, in an org workspace where they are on — the roles
+ * that count now and the permissions they grant.
+ *
+ * **A UI hint, never security.** Use it to show or hide controls — an "Invite"
+ * button for admins, an editor for those who may edit. It protects nothing:
+ * the platform checks every read and write on arrival, whatever your code
+ * shows. Never build a role check of your own on top of it, and never treat a
+ * role picker in your app as access control.
+ *
+ * `access.mode` says which model answered: `'tier'` (no app roles here),
+ * `'legacy'` (your app declares roles, but this workspace has not turned them
+ * on yet — tier rules apply) or `'roles'`. `can(permission)` is true only in
+ * `'roles'` mode. `access.tier` is `null` when the user has no tier there (not
+ * a member, an expired membership, or a workspace not reachable from where the
+ * app is open). Pass `null`/`undefined` for "no workspace yet" — nothing is
+ * fetched.
+ *
+ * Requires the `data:workspace` permission. Answers only for the signed-in
+ * user; it never returns user ids or anything about other members.
+ *
+ * The answer is a snapshot taken when the workspace is first passed: the hook
+ * does not learn of a change made elsewhere while the app stays open (an
+ * admin changing the user's tier or roles, a membership expiring). Call
+ * `refetch()` when the app has reason to think it changed — after your own
+ * invite or role change, or when the platform refuses an action with
+ * `FORBIDDEN` or `NOT_A_MEMBER` — so a stale answer does not linger in the UI.
+ *
+ * Every `useFiasAccess` for one workspace shares one answer and one request,
+ * so calling it in each row of a long list costs one bridge call, and a
+ * `refetch()`, a host `access_update` or a window focus asks once for all of
+ * them.
+ *
+ * @example
+ * const { access, can } = useFiasAccess(workspaceId);
+ * const canApprove =
+ *   access?.mode === 'roles' ? can('ledger.approve') : access?.tier === 'admin';
+ * return canApprove ? <ApproveButton /> : null; // the server still decides
+ */
+function useFiasAccess(workspaceId) {
+    const bridge = useBridge();
+    // What is shown is read from the workspace's SHARED answer during render
+    // (keyed by workspace, so a previous workspace's answer can never show,
+    // not even on the render where `workspaceId` changes). These copies make
+    // React re-render when it changes, and stand in before this instance has
+    // subscribed.
+    const known = workspaceId ? peekSharedAccess(bridge, workspaceId) : undefined;
+    const [settled, setSettled] = (0, react_1.useState)(known?.settled ?? null);
+    const [fetching, setFetching] = (0, react_1.useState)(known ? known.fetching : !!workspaceId);
+    // One shared ask per workspace (see SharedAccess): mounting joins the
+    // answer, or the ask in flight, that every other instance shares.
+    (0, react_1.useEffect)(() => {
+        if (!workspaceId)
+            return;
+        const shared = sharedAccessFor(bridge, workspaceId);
+        const sync = () => {
+            setSettled(shared.settled);
+            setFetching(shared.fetching);
+        };
+        const unsubscribe = subscribeSharedAccess(shared, sync);
+        askSharedAccess(shared, 'ensure');
+        sync();
+        return unsubscribe;
+    }, [bridge, workspaceId]);
+    const refetch = (0, react_1.useCallback)(() => {
+        if (workspaceId)
+            askSharedAccess(sharedAccessFor(bridge, workspaceId), 'again');
+    }, [bridge, workspaceId]);
+    const openAccessDialog = (0, react_1.useCallback)(async () => {
+        let answer;
+        try {
+            answer = await bridge.request('client_entity_invoke', { entityId: entity_ops_1.APP_ACCESS_DIALOG_ENTITY_ID, input: {} }, ACCESS_SHEET_TIMEOUT_MS);
+        }
+        catch (err) {
+            // A host without the sheet (an older Fias, or an older dev harness) has
+            // no executor for it and answers a generic bridge error naming that —
+            // "no client-side executor registered" / "no client-side executor for …
+            // in the dev harness": the sheet is simply not available. Any other bridge error (a missing permission, a call loop)
+            // is the app's to fix, so it passes through unchanged.
+            if (err instanceof bridge_1.FiasBridgeError &&
+                err.code === 'BRIDGE_ERROR' &&
+                err.message.includes('no client-side executor')) {
+                throw new bridge_1.FiasBridgeError('Managing access is not available here', 'ACCESS_UNAVAILABLE');
+            }
+            throw err;
+        }
+        if (answer && 'error' in answer) {
+            throw new bridge_1.FiasBridgeError(answer.error.message, answer.error.code);
+        }
+        const changed = answer?.changed === true;
+        if (changed)
+            refetch();
+        return { changed };
+    }, [bridge, refetch]);
+    // A refetch of the same workspace keeps its answer while it loads; any
+    // other workspace has no answer until its own arrives.
+    const own = workspaceId && settled?.workspaceId === workspaceId ? settled : null;
+    const current = known ? known.settled : own;
+    const access = current?.access ?? null;
+    const error = current?.error ?? null;
+    const isLoading = !!workspaceId && (current === null || (known ? known.fetching : fetching));
+    const can = (0, react_1.useCallback)((permission) => access?.mode === 'roles' && access.permissions.includes(permission), [access]);
+    // Audiences (ADR-034 phase 2) — UI hints like `can()`.
+    const canReadAudience = (0, react_1.useCallback)((audience) => access?.mode === 'roles' && (access.audiences?.readable.includes(audience) ?? false), [access]);
+    const canDiscloseTo = (0, react_1.useCallback)((audience) => access?.mode === 'roles' && (access.audiences?.disclosable.includes(audience) ?? false), [access]);
+    return (0, react_1.useMemo)(() => ({
+        access,
+        isLoading,
+        error,
+        refetch,
+        can,
+        canReadAudience,
+        canDiscloseTo,
+        openAccessDialog,
+    }), [access, isLoading, error, refetch, can, canReadAudience, canDiscloseTo, openAccessDialog]);
+}
+/**
+ * The last `my_access` answer per workspace, across every `useFiasAccess`
+ * instance in this plugin — what a changed answer is noticed against.
+ */
+const lastAccessAnswers = new Map();
+/** The least time between two focus-triggered `my_access` asks. */
+const FOCUS_REFETCH_MIN_MS = 30000;
+/** How long a person may keep the access sheet open before the call gives up. */
+const ACCESS_SHEET_TIMEOUT_MS = 30 * 60 * 1000;
+const sharedAccessByBridge = new WeakMap();
+function peekSharedAccess(bridge, workspaceId) {
+    return sharedAccessByBridge.get(bridge)?.get(workspaceId);
+}
+function sharedAccessFor(bridge, workspaceId) {
+    let byWorkspace = sharedAccessByBridge.get(bridge);
+    if (!byWorkspace) {
+        byWorkspace = new Map();
+        sharedAccessByBridge.set(bridge, byWorkspace);
+    }
+    let shared = byWorkspace.get(workspaceId);
+    if (!shared) {
+        shared = {
+            bridge,
+            workspaceId,
+            settled: null,
+            fetching: false,
+            answered: false,
+            answeredAt: 0,
+            inFlight: null,
+            scheduled: false,
+            again: false,
+            listeners: new Set(),
+            stopListening: null,
+        };
+        byWorkspace.set(workspaceId, shared);
+    }
+    return shared;
+}
+/** Drop a workspace's entry once nothing shows it and no ask is out. */
+function releaseSharedAccess(shared) {
+    if (shared.listeners.size > 0 || shared.inFlight || shared.scheduled)
+        return;
+    const byWorkspace = sharedAccessByBridge.get(shared.bridge);
+    if (byWorkspace?.get(shared.workspaceId) === shared)
+        byWorkspace.delete(shared.workspaceId);
+}
+function notifySharedAccess(shared) {
+    for (const listener of Array.from(shared.listeners))
+        listener();
+}
+/**
+ * Show a workspace's shared answer. The first instance starts listening for
+ * the host's `access_update` (always asks again) and window focus (asks at
+ * most once per FOCUS_REFETCH_MIN_MS); the last one to leave stops.
+ */
+function subscribeSharedAccess(shared, listener) {
+    shared.listeners.add(listener);
+    if (!shared.stopListening) {
+        // The answer is a snapshot (ADR-034): ask again when the host says the
+        // person's access changed, and when they come back to the window — a
+        // grant or a removal made elsewhere shows up without the app wiring
+        // anything. Focus is frequent (every click back into the frame), so it
+        // is throttled; a host access_update always asks.
+        const unsubscribe = shared.bridge.onAccessUpdate(() => askSharedAccess(shared, 'again'));
+        const onFocus = () => {
+            if (Date.now() - shared.answeredAt >= FOCUS_REFETCH_MIN_MS) {
+                askSharedAccess(shared, 'join');
+            }
+        };
+        const win = typeof window === 'undefined' ? null : window;
+        win?.addEventListener('focus', onFocus);
+        shared.stopListening = () => {
+            unsubscribe();
+            win?.removeEventListener('focus', onFocus);
+        };
+    }
+    return () => {
+        shared.listeners.delete(listener);
+        if (shared.listeners.size === 0 && shared.stopListening) {
+            shared.stopListening();
+            shared.stopListening = null;
+        }
+        releaseSharedAccess(shared);
+    };
+}
+/**
+ * Ask `my_access` for a workspace, at most once for every instance:
+ *   - `ensure` (a mount): only if there is no answer and no ask yet — a first
+ *     ask that failed is tried again;
+ *   - `join` (focus): unless an ask is already out;
+ *   - `again` (access_update, refetch(), a changed access sheet): an ask that
+ *     starts after this demand — the one about to start, or one more after
+ *     the one out, which may answer from before the change.
+ * Demands made in the same tick share the ask that starts at its end.
+ */
+function askSharedAccess(shared, demand) {
+    if (shared.inFlight) {
+        if (demand === 'again')
+            shared.again = true;
+        return;
+    }
+    if (shared.scheduled)
+        return;
+    if (demand === 'ensure' && shared.answered)
+        return;
+    shared.scheduled = true;
+    void Promise.resolve().then(() => {
+        shared.scheduled = false;
+        startSharedAccess(shared);
+    });
+}
+/**
+ * Record an answer. The caches it guards are module-wide, so the comparison
+ * is too: against the last answer for this workspace (a remounted hook still
+ * notices a change). No access at all clears them whatever was seen before.
+ */
+function settleSharedAccess(shared, access) {
+    const answer = JSON.stringify(access);
+    const before = lastAccessAnswers.get(shared.workspaceId);
+    const noAccess = access.mode === 'tier' && access.tier === null;
+    if (noAccess || (before !== undefined && before !== answer))
+        clearSdkReadCaches();
+    lastAccessAnswers.set(shared.workspaceId, answer);
+    shared.answered = true;
+    shared.answeredAt = Date.now();
+    shared.settled = { workspaceId: shared.workspaceId, access, error: null };
+}
+/**
+ * Ask now. A BACKGROUND ask (an answer is already held) does not show as
+ * loading, and a failure of one keeps the answer rather than blanking the
+ * app's controls; only a first answer reports its error. An answer that comes
+ * back when no instance shows the workspace any more is dropped, as a
+ * superseded one always was.
+ */
+function startSharedAccess(shared) {
+    if (shared.listeners.size === 0) {
+        releaseSharedAccess(shared);
+        return;
+    }
+    const { bridge, workspaceId } = shared;
+    const background = shared.answered;
+    if (!background) {
+        shared.fetching = true;
+        notifySharedAccess(shared);
+    }
+    shared.inFlight = (async () => {
+        try {
+            const res = await (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.PLUGIN_WORKSPACES_ENTITY_ID, 'my_access', { workspaceId });
+            if (shared.listeners.size > 0)
+                settleSharedAccess(shared, res.access);
+        }
+        catch (err) {
+            if (shared.listeners.size === 0) {
+                // Nobody shows this workspace now; the answer has no one to reach.
+            }
+            else if (err instanceof bridge_1.FiasBridgeError && NO_WORKSPACE_ACCESS_CODES.has(err.code)) {
+                // No access here at all — the biggest narrowing there is.
+                settleSharedAccess(shared, { mode: 'tier', workspaceId, tier: null, expiresAt: null });
+            }
+            else if (!background) {
+                shared.settled = {
+                    workspaceId,
+                    access: null,
+                    error: err instanceof Error ? err : new Error(String(err)),
+                };
+            }
+        }
+        finally {
+            shared.fetching = false;
+            shared.inFlight = null;
+            if (shared.again) {
+                shared.again = false;
+                askSharedAccess(shared, 'again');
+            }
+            notifySharedAccess(shared);
+            releaseSharedAccess(shared);
+        }
+    })();
+}
 /**
  * Access the in-arche purchase (IAP) store.
  * Provides product listing, purchase initiation, entitlement checking,
@@ -1153,6 +1569,24 @@ const DOWNLOAD_URL_REFRESH_BUFFER_MS = 60000;
  */
 const downloadUrlCache = new Map();
 const downloadUrlInflight = new Map();
+/**
+ * Forget every read the SDK caches that the person's access decided — the
+ * presigned Vault download URLs, which stay valid for their window whatever
+ * happens to the access that minted them. Called by `useFiasAccess` when the
+ * person's access answer changes (ADR-034), so a plugin cannot keep serving a
+ * URL minted under access the person no longer has. (Content-pack and
+ * community-asset URLs are not decided by the person's access.)
+ */
+function clearSdkReadCaches() {
+    downloadUrlGeneration += 1;
+    downloadUrlCache.clear();
+    downloadUrlInflight.clear();
+}
+/**
+ * Bumped by every clear: a fetch that started before a clear must not put the
+ * URL it brings back into the cache afterwards.
+ */
+let downloadUrlGeneration = 0;
 /**
  * Cache-aware fetcher for a presigned download URL. Used internally by
  * `useVaultDocuments().getDownloadUrl()`. Exposed separately so non-React
@@ -1169,6 +1603,7 @@ async function fetchVaultDocumentDownloadUrl(documentId) {
     if (inflight)
         return inflight;
     const bridge = (0, bridge_1.getBridge)();
+    const generation = downloadUrlGeneration;
     // The server bridge returns `expiresAt` as an ISO 8601 string; the
     // SDK surface uses epoch milliseconds. Normalize here so callers
     // don't have to think about the wire shape.
@@ -1180,15 +1615,19 @@ async function fetchVaultDocumentDownloadUrl(documentId) {
             expiresAt: new Date(result.expiresAt).getTime(),
             contentType: result.contentType,
         };
-        downloadUrlCache.set(documentId, {
-            url: normalized.url,
-            expiresAt: normalized.expiresAt,
-            contentType: normalized.contentType,
-        });
+        if (generation === downloadUrlGeneration) {
+            downloadUrlCache.set(documentId, {
+                url: normalized.url,
+                expiresAt: normalized.expiresAt,
+                contentType: normalized.contentType,
+            });
+        }
         return normalized;
     })
         .finally(() => {
-        downloadUrlInflight.delete(documentId);
+        // Only our own entry: a newer request may have replaced it.
+        if (downloadUrlInflight.get(documentId) === promise)
+            downloadUrlInflight.delete(documentId);
     });
     downloadUrlInflight.set(documentId, promise);
     return promise;
@@ -2112,46 +2551,64 @@ function useFiasPreviewState(key, getState, onRestore) {
         return bridge.registerPreviewState(key, () => getStateRef.current(), (state) => onRestoreRef.current(state));
     }, [bridge, key]);
 }
+/** JSON with object keys sorted at every level, so equal content gives equal text. */
+function stableStringify(value) {
+    return JSON.stringify(value, (_key, v) => v && typeof v === 'object' && !Array.isArray(v)
+        ? Object.fromEntries(Object.keys(v)
+            .sort()
+            .map((k) => [k, v[k]]))
+        : v);
+}
 /**
- * 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.
+ * Subscribes to realtime invalidation events through any catalog verb of
+ * `kind: 'subscribe'` (ADR-012 Phase M4) — the primitive behind
+ * `useDataSubscription`. Notify-then-refetch: the platform pushes a minimal
+ * "this changed" event and `onInvalidate` decides what to refetch.
  *
- * Requires the `data:store` permission (same as reading the collection —
- * a live invalidation grants nothing polling couldn't retrieve).
+ * `payload` is the verb's wire payload (`{ op, ...params }`), sent to
+ * `entity_invoke` for `entityId` exactly as given; the hook re-subscribes
+ * when its content changes (key order does not matter). The permission is
+ * the verb's own — a live invalidation grants nothing the matching read
+ * could not 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.
+ *   events during an in-flight refetch coalesces into exactly one more. With
+ *   `minRefetchIntervalMs` it also runs at most once per interval (a trailing
+ *   call still follows the last event), so a busy resource cannot spend your
+ *   per-minute budget on refetches.
+ * - An event says only that the resource changed — not what. Re-read the
+ *   visible head of it and merge by id, so edits and deletions show too; a
+ *   "newer than X" cursor read would never see them.
  * - 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.
+ *   (`status: 'ended'`), `endedReason` says why — `collection_deleted` (the
+ *   observed resource is gone) and `authorization_revoked` are terminal,
+ *   others may warrant resubscribing (unmount/remount or toggle `enabled`).
  *
  * @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);
+ * // Any catalog verb of kind 'subscribe' (see the capability catalog for the
+ * // entity id and payload); refetch the head of the resource on each event.
+ * const { status } = useEntitySubscription(
+ *   ENTITY_ID,
+ *   { op: 'subscribe_feed' },
+ *   refetchHead,
+ *   { enabled: member, minRefetchIntervalMs: 2_000 },
+ * );
  */
-function useDataSubscription(collection, onInvalidate, options) {
+function useEntitySubscription(entityId, payload, 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;
+    const minRefetchIntervalMs = Math.max(0, options?.minRefetchIntervalMs ?? 0);
+    // The payload is wire JSON, so its content is the identity that matters —
+    // a fresh object literal each render, or the same fields in another order,
+    // must not re-subscribe.
+    const payloadKey = stableStringify(payload);
     (0, react_1.useEffect)(() => {
         if (!enabled) {
             setState({ status: 'ended', endedReason: 'unsubscribed' });
@@ -2163,14 +2620,31 @@ function useDataSubscription(collection, onInvalidate, options) {
         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.
+        // With a minimum interval, a run that would land too soon after the last
+        // one is deferred to the interval's end — still exactly one.
         let refetching = false;
         let trailing = false;
+        let lastRunAt = -Infinity;
+        let intervalTimer = null;
         const runInvalidate = async () => {
-            if (refetching) {
+            if (refetching || intervalTimer) {
                 trailing = true;
                 return;
             }
+            const wait = lastRunAt + minRefetchIntervalMs - Date.now();
+            if (wait > 0) {
+                trailing = true;
+                intervalTimer = setTimeout(() => {
+                    intervalTimer = null;
+                    if (trailing && !cancelled) {
+                        trailing = false;
+                        void runInvalidate();
+                    }
+                }, wait);
+                return;
+            }
             refetching = true;
+            lastRunAt = Date.now();
             try {
                 await onInvalidateRef.current();
             }
@@ -2188,8 +2662,8 @@ function useDataSubscription(collection, onInvalidate, options) {
         void (async () => {
             try {
                 const res = await bridge.request('entity_invoke', {
-                    entityId: entity_ops_1.PLUGIN_DATASTORE_ENTITY_ID,
-                    payload: { op: 'subscribe', collection, workspaceId },
+                    entityId,
+                    payload: JSON.parse(payloadKey),
                 });
                 const subscription = res?.output;
                 if (!subscription ||
@@ -2222,14 +2696,55 @@ function useDataSubscription(collection, onInvalidate, options) {
         })();
         return () => {
             cancelled = true;
+            if (intervalTimer)
+                clearTimeout(intervalTimer);
             unsubscribeEvent?.();
             unsubscribeEnded?.();
             if (subscriptionId)
                 bridge.releaseSubscription(subscriptionId);
         };
-    }, [bridge, collection, workspaceId, enabled]);
+    }, [bridge, entityId, payloadKey, enabled, minRefetchIntervalMs]);
     return state;
 }
+/**
+ * Subscribes to realtime change events for a datastore collection
+ * (ADR-012 Phase M4) — `useEntitySubscription` bound to the datastore's
+ * `subscribe` verb. 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 are `useEntitySubscription`'s. Scope-aware:
+ * shared collections notify on any user's writes; user-scoped collections
+ * only on yours; workspace-scoped need `workspaceId` and an active
+ * membership.
+ *
+ * Audiences (ADR-034): in a collection with audiences, changes are announced
+ * per audience — pass `audience` (one the user reads; see
+ * `useFiasAccess().canReadAudience`), and subscribe once per audience you
+ * show. Without one the subscription ends (`AUDIENCE_REQUIRED`).
+ *
+ * @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 audience = options?.audience;
+    return useEntitySubscription(entity_ops_1.PLUGIN_DATASTORE_ENTITY_ID, {
+        op: 'subscribe',
+        collection,
+        workspaceId: options?.workspaceId,
+        ...(audience !== undefined ? { audience } : {}),
+    }, onInvalidate, { enabled: options?.enabled });
+}
 /**
  * Consented access to documents the USER already owns — the only SDK
  * surface that reaches data your plugin did not create. Requires the
@@ -2442,6 +2957,62 @@ async function fetchCommunityAssetUrls(bridge, assetIds) {
     }
     return hits;
 }
+/**
+ * The user's Creative Library (ADR-035): their styles and characters, made in
+ * FiasWorks Studio or any arche they allow, owned by them — or, in a team
+ * workspace that approved this arche, the workspace's. Requires
+ * `vault:creative:read`; `create` / `update` / `remove` / `restore` also need
+ * `vault:creative:write`.
+ *
+ * Generate in a style with `useImageGeneration().generate({ …, creativeStyle:
+ * { styleId } })`: the platform sends the style's pictures and words, so the
+ * arche never has to read them itself.
+ *
+ * @example
+ *   const library = useCreativeLibrary();
+ *   const styles = await library.list({ kind: 'style' });
+ *   await images.generate({ entityId, prompt: 'a red fox', creativeStyle: { styleId: styles[0].itemId } });
+ */
+/** How long a person may keep the Creative Library picker open. */
+const CREATIVE_PICKER_TIMEOUT_MS = 30 * 60 * 1000;
+function useCreativeLibrary() {
+    const bridge = useBridge();
+    return (0, react_1.useMemo)(() => {
+        const item = async (op, args) => (await (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.VAULT_CREATIVE_ENTITY_ID, op, args))
+            .item;
+        return {
+            list: async (options = {}) => (await (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.VAULT_CREATIVE_ENTITY_ID, 'list_items', { ...options })).items,
+            get: (itemId, version) => item('get_item', { itemId, ...(version !== undefined ? { version } : {}) }),
+            create: (fields) => item('create_item', { referenceDocumentIds: [], ...fields }),
+            update: (itemId, fields) => item('update_item', { itemId, ...fields }),
+            remove: (itemId) => item('delete_item', { itemId }),
+            restore: (itemId) => item('restore_item', { itemId }),
+            pick: async (options = {}) => {
+                let answer;
+                try {
+                    answer = await bridge.request('client_entity_invoke', {
+                        entityId: entity_ops_1.CREATIVE_PICKER_ENTITY_ID,
+                        input: options.kind ? { kind: options.kind } : {},
+                    }, CREATIVE_PICKER_TIMEOUT_MS);
+                }
+                catch (err) {
+                    // A host without the picker (an older Fias, the dev harness) has no
+                    // executor for it: the picker is simply not available there.
+                    if (err instanceof bridge_1.FiasBridgeError &&
+                        err.code === 'BRIDGE_ERROR' &&
+                        err.message.includes('no client-side executor')) {
+                        throw new bridge_1.FiasBridgeError('The Creative Library picker is not available here', 'PICKER_UNAVAILABLE');
+                    }
+                    throw err;
+                }
+                if (answer && 'error' in answer) {
+                    throw new bridge_1.FiasBridgeError(answer.error.message, answer.error.code);
+                }
+                return answer;
+            },
+        };
+    }, [bridge]);
+}
 /** Connecting waits on a person (and maybe a provider sign-in in a popup). */
 const CONNECT_TIMEOUT_MS = 10 * 60 * 1000;
 /**
@@ -2784,7 +3355,7 @@ function useDocumentSign() {
 }
 /**
  * Declare Fias AI actions at RUNTIME — the dynamic half of the plugin
- * AI-action plane (`ai:actions` permission; TRUSTED arches only — the host
+ * AI-action plane (`ai:actions` permission for the declaration; TRUSTED arches only — the host
  * silently ignores runtime declarations from non-trusted arches, whose lane
  * is the manifest `fiasAI` block, fixed at publish and reviewed with the
  * submission). Both lanes merge host-side; the manifest wins id collisions.
@@ -2798,8 +3369,10 @@ function useDocumentSign() {
  * Returns `{ openAssistant }` — a fire-and-forget request that the host open
  * the global Fias AI panel, for CONTEXTUAL affordances (an empty-state "Ask
  * Fias AI" button; the host also shows its own "Works with Fias AI" chip).
- * The host debounces it and honours the user's last dismissal — never loop
- * or retry, and there is deliberately no way to pass text along.
+ * Opening needs NO permission — any plugin may do it, actions or not; the
+ * user can still use the assistant's own tools — and `useFiasChrome` offers
+ * the same call. The host debounces it and honours the user's last dismissal
+ * — never loop or retry, and there is deliberately no way to pass text along.
  */
 function useFiasAIActions(config) {
     const bridge = useBridge();