@fias/arche-sdk 2.19.1 → 2.20.0

package/dist/hooks.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GRAMMAR_CHECK_ENTITY_ID = exports.NLLB_LANGUAGES = exports.NLLB_TRANSLATION_ENTITY_ID = void 0;
+exports.FiasContentError = exports.PLUGIN_CONTENT_ENTITY_ID = exports.GRAMMAR_CHECK_ENTITY_ID = exports.NLLB_LANGUAGES = exports.NLLB_TRANSLATION_ENTITY_ID = void 0;
 exports.useFiasUser = useFiasUser;
 exports.useFiasTheme = useFiasTheme;
 exports.useFiasVendoredAssets = useFiasVendoredAssets;
@@ -20,6 +20,7 @@ exports.useFiasStore = useFiasStore;
 exports.fetchVaultDocumentDownloadUrl = fetchVaultDocumentDownloadUrl;
 exports.useVaultDocuments = useVaultDocuments;
 exports.useArcheAssets = useArcheAssets;
+exports.useFiasContent = useFiasContent;
 exports.useFiasPreviewState = useFiasPreviewState;
 exports.useDataSubscription = useDataSubscription;
 exports.useVaultUserDocuments = useVaultUserDocuments;
@@ -185,7 +186,13 @@ function useFiasStorage() {
             path,
         });
     }, [bridge]);
-    return { readFile, writeFile, listFiles, deleteFile };
+    // Memoized, like useArcheAssets. An unmemoized object literal here is a
+    // footgun rather than a style question: the natural way to use this hook is
+    // `useEffect(() => { void storage.readFile(...) }, [storage])`, and a fresh
+    // identity every render turns that into an infinite loop — effect, setState,
+    // render, effect. The inner callbacks were already stable; only the
+    // container was not.
+    return (0, react_1.useMemo)(() => ({ readFile, writeFile, listFiles, deleteFile }), [readFile, writeFile, listFiles, deleteFile]);
 }
 /**
  * Invoke platform entities (AI models, etc.) through the bridge.
@@ -573,16 +580,21 @@ function useFiasNavigation() {
         bridge.request('navigate', { path });
     }, [bridge]);
     const openArche = (0, react_1.useCallback)((archeId, opts) => {
-        // `path` is spread in only when supplied: an older host ignores unknown
-        // keys, but sending `path: undefined` would add a key to every call for
-        // no reason and churn the wire shape shipped plugins already emit.
+        // `path` / `payload` are spread in only when supplied: an older host
+        // ignores unknown keys, but sending `path: undefined` would add a key to
+        // every call for no reason and churn the wire shape shipped plugins
+        // already emit.
         bridge.request('open_arche', {
             archeId,
             newTab: opts?.newTab === true,
             ...(opts?.path ? { path: opts.path } : {}),
+            ...(opts?.payload ? { payload: opts.payload } : {}),
         });
     }, [bridge]);
-    return { navigateTo, openArche, currentPath };
+    // Memoized for the same reason as useFiasStorage. `currentPath` is state, so
+    // this identity still changes when the path does — which is correct, and is
+    // exactly what a consumer depending on it wants.
+    return (0, react_1.useMemo)(() => ({ navigateTo, openArche, currentPath }), [navigateTo, openArche, currentPath]);
 }
 /**
  * Like useState, but auto-persists to bridge storage.
@@ -596,12 +608,22 @@ function usePersistentState(key, initialValue) {
     const [value, setValueInternal] = (0, react_1.useState)(initialValue);
     const initializedRef = (0, react_1.useRef)(false);
     const valueRef = (0, react_1.useRef)(initialValue);
+    // Set once the plugin calls the setter. A value set BEFORE the mount read
+    // resolves is newer than anything in storage, so the read must not
+    // overwrite it — it used to, silently reverting e.g. a click that landed
+    // while the read was in flight (the debounced write then persisted the
+    // user's value while the UI showed the stale one).
+    const setByPluginRef = (0, react_1.useRef)(false);
     const writer = (0, react_1.useMemo)(() => createDebouncedWriter(bridge), [bridge]);
     // 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)(() => {
         (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.PLUGIN_STORAGE_ENTITY_ID, 'read', { path: `__state/${key}` })
             .then((result) => {
+            if (setByPluginRef.current) {
+                initializedRef.current = true;
+                return;
+            }
             if (result.exists && result.content !== null) {
                 try {
                     const parsed = JSON.parse(result.content);
@@ -627,6 +649,7 @@ function usePersistentState(key, initialValue) {
     }, [bridge, key, writer]);
     const setValue = (0, react_1.useCallback)((next) => {
         const resolved = typeof next === 'function' ? next(valueRef.current) : next;
+        setByPluginRef.current = true;
         valueRef.current = resolved;
         setValueInternal(resolved);
         writer.schedule(`__state/${key}`, JSON.stringify(resolved));
@@ -1079,9 +1102,7 @@ function useVaultDocuments() {
         });
     }, [bridge]);
     const read = (0, react_1.useCallback)(async (documentId) => {
-        return bridge.request('vault_documents_read', {
-            documentId,
-        });
+        return bridge.request('vault_documents_read', { documentId });
     }, [bridge]);
     const getDownloadUrl = (0, react_1.useCallback)((documentId) => fetchVaultDocumentDownloadUrl(documentId), 
     // The hook closes over the React context's bridge, but the resolver
@@ -1098,16 +1119,47 @@ function useVaultDocuments() {
         };
     }, [bridge]);
     const saveContent = (0, react_1.useCallback)(async (params) => {
-        const res = await (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.VAULT_ARCHE_DOCUMENTS_ENTITY_ID, 'save_own_document_content', {
-            documentId: params.documentId,
-            content: params.content,
-            contentType: params.contentType,
-        });
+        const routed = await routeSaveContent(params.content);
+        let res;
+        if (routed.lane === 'body') {
+            // Small text rides the entity_invoke body.
+            res = await (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.VAULT_ARCHE_DOCUMENTS_ENTITY_ID, 'save_own_document_content', {
+                documentId: params.documentId,
+                content: routed.text,
+                contentType: params.contentType,
+                expectedRevision: params.expectedRevision,
+            });
+        }
+        else {
+            // Bytes — or text too large for the bridge body — go through the
+            // host, which does the presigned PUT the iframe's CSP forbids (same
+            // reason `upload` does; see there). `contentKind: 'text'` keeps the
+            // text lane's must-be-a-text-type rule in force at any size.
+            //
+            // Deliberately NO `name` in this payload: a host that predates
+            // in-place saves requires one for an upload, so it refuses this
+            // message instead of silently creating a NEW document.
+            res = await bridge.request('vault_documents_upload', {
+                saveToDocumentId: params.documentId,
+                bytes: bytesToBase64(routed.bytes),
+                mimeType: params.contentType,
+                contentKind: routed.contentKind,
+                expectedRevision: params.expectedRevision,
+            });
+        }
         // The bytes behind any cached download URL just changed.
         downloadUrlCache.delete(params.documentId);
         return res;
     }, [bridge]);
     const write = (0, react_1.useCallback)(async (params) => {
+        // `write` has no second lane to fall back to, so say so here rather
+        // than let the request die as an opaque 413 at the bridge.
+        if (params.content.length > SAVE_CONTENT_BODY_LANE_MAX_BYTES ||
+            !fitsBridgeBodyAsJsonText(params.content)) {
+            throw new bridge_1.FiasBridgeError('write() takes small text only: at most 200,000 characters, and small enough to ' +
+                'travel in one bridge request once JSON-escaped (quotes, backslashes and newlines ' +
+                'double). Use upload() for larger documents.', 'INVALID_PARAMS');
+        }
         return bridge.request('vault_documents_write', {
             name: params.name,
             content: params.content,
@@ -1152,9 +1204,9 @@ function useVaultDocuments() {
         await bridge.request('vault_documents_detach', { documentId, referenceId });
     }, [bridge]);
     const uploadInit = (0, react_1.useCallback)(async (params) => {
-        // No `userVisible` here by construction: a user-visible save needs the
-        // host's confirmation, which it can only run when it orchestrates the
-        // whole upload. The host REJECTS a `visibility` on this op.
+        // No destination here by construction: a save into the user's
+        // Documents needs the host's Save dialog, which it can only show when it
+        // orchestrates the whole upload. The host REJECTS a `visibility` here.
         return bridge.request('vault_documents_upload_init', {
             name: params.name,
             mimeType: params.mimeType,
@@ -1189,13 +1241,22 @@ function useVaultDocuments() {
             sensitivity: params.sensitivity,
             folderPath: params.folderPath,
             replacesDocumentId: params.replacesDocumentId,
-            // Opt-in user-visible save. The host turns this into a confirmation
-            // the user sees and the iframe cannot script; the server independently
-            // requires `vault:user-documents:write` plus a registered folder for
-            // this arche. Omitted (the common case) keeps the arche-private default.
+            // A save into the user's Documents. The host turns this into its Save
+            // dialog, which the iframe cannot see or script, and performs the
+            // write itself from the user's session. Omitted (the common case)
+            // keeps the arche-private default.
+            destination: params.destination,
             userVisible: params.userVisible,
         });
     }, [bridge]);
+    const saveCopy = (0, react_1.useCallback)(async (documentId, options) => {
+        // Rides the update op, intercepted by the host: it reads the bytes and
+        // shows the Save dialog. Never forwarded — the original is unchanged.
+        return bridge.request('vault_documents_update', {
+            documentId,
+            saveCopy: { ...(options?.suggestedName ? { suggestedName: options.suggestedName } : {}) },
+        });
+    }, [bridge]);
     return (0, react_1.useMemo)(() => ({
         list,
         read,
@@ -1209,6 +1270,7 @@ function useVaultDocuments() {
         attach,
         detach,
         upload,
+        saveCopy,
         uploadInit,
         uploadFinalize,
     }), [
@@ -1224,10 +1286,79 @@ function useVaultDocuments() {
         attach,
         detach,
         upload,
+        saveCopy,
         uploadInit,
         uploadFinalize,
     ]);
 }
+/** Encoded-size ceiling of the text lane (`save_own_document_content`). Must
+ *  match the server's MAX_OWN_DOCUMENT_SAVE_BYTES; content past it is routed
+ *  through the host-uploaded lane rather than refused. */
+const SAVE_CONTENT_BODY_LANE_MAX_BYTES = 200000;
+/**
+ * What the text may occupy ON THE WIRE. The bridge request body is capped at
+ * 256 KB (the server's `PLUGIN_BRIDGE_BODY_LIMIT_BYTES`) and the text travels
+ * inside it as a JSON string, where every `"`, `\` and newline doubles and
+ * every other control character becomes six bytes. So 200 KB of text can be
+ * 400 KB — or 1.2 MB — of request, and the answer is an opaque 413 rather
+ * than a save. Routing therefore looks at the SERIALIZED size too, with ~16 KB
+ * left for the envelope (ids, revision, content type, JSON keys).
+ */
+const BRIDGE_BODY_TEXT_MAX_SERIALIZED_BYTES = 256 * 1024 - 16 * 1024;
+/** True when `text` fits a bridge request body as a JSON string. Encodes at
+ *  most once, and not at all for short strings (a UTF-16 unit is at most six
+ *  bytes of JSON). */
+function fitsBridgeBodyAsJsonText(text, utf8Bytes) {
+    if (text.length * 6 <= BRIDGE_BODY_TEXT_MAX_SERIALIZED_BYTES)
+        return true;
+    // JSON escapes are ASCII, so they cost the same in UTF-16 units as in
+    // bytes: serialized bytes = UTF-8 bytes + the units escaping added.
+    const escapeOverhead = JSON.stringify(text).length - text.length;
+    const bytes = utf8Bytes ?? new TextEncoder().encode(text).length;
+    return bytes + escapeOverhead <= BRIDGE_BODY_TEXT_MAX_SERIALIZED_BYTES;
+}
+/** Mirrors the server's `MAX_OWN_DOCUMENT_PRESIGNED_SAVE_BYTES` — the most an
+ *  in-place save accepts, pinned to what `readBytes` / `getBytes` can serve
+ *  back, so anything saved can be reopened. */
+const SAVE_CONTENT_MAX_BYTES = 15 * 1024 * 1024;
+/**
+ * Pick the lane for `saveContent` from the content itself, encoding text AT
+ * MOST ONCE (a UTF-16 code unit is at most 3 UTF-8 bytes, so short strings
+ * are routed without encoding at all) and refusing anything past the cap
+ * BEFORE the base64 step — which would otherwise build a 20 MB string on the
+ * plugin's main thread for a save the server is certain to refuse.
+ */
+async function routeSaveContent(content) {
+    let routed;
+    if (typeof content === 'string') {
+        // Short enough that neither limit can be reached, whatever it contains:
+        // six bytes of JSON per unit is the worst case, three of UTF-8.
+        if (content.length * 6 <= SAVE_CONTENT_BODY_LANE_MAX_BYTES) {
+            return { lane: 'body', text: content };
+        }
+        const bytes = new TextEncoder().encode(content);
+        routed =
+            bytes.length <= SAVE_CONTENT_BODY_LANE_MAX_BYTES &&
+                fitsBridgeBodyAsJsonText(content, bytes.length)
+                ? { lane: 'body', text: content }
+                : { lane: 'host', bytes, contentKind: 'text' };
+    }
+    else {
+        routed = { lane: 'host', bytes: await toUint8Array(content), contentKind: 'binary' };
+    }
+    if (routed.lane === 'host' && routed.bytes.length > SAVE_CONTENT_MAX_BYTES) {
+        throw new bridge_1.FiasBridgeError(`Content is ${routed.bytes.length} bytes; saveContent accepts at most ` +
+            `${SAVE_CONTENT_MAX_BYTES} bytes (15 MB).`, 'OWN_DOCUMENT_SAVE_TOO_LARGE');
+    }
+    return routed;
+}
+async function toUint8Array(content) {
+    if (content instanceof Uint8Array)
+        return content;
+    if (content instanceof ArrayBuffer)
+        return new Uint8Array(content);
+    return new Uint8Array(await content.arrayBuffer());
+}
 /** Decode base64 transport back to bytes (`get_consented_document_bytes`). */
 function base64ToBytes(base64) {
     const binary = atob(base64);
@@ -1292,6 +1423,134 @@ function useArcheAssets() {
     }, [bridge]);
     return (0, react_1.useMemo)(() => ({ list, index, getUrl }), [list, index, getUrl]);
 }
+/**
+ * Entity ID of the plugin content pack client-side entity (ADR-021) — the
+ * host-side reader behind {@link useFiasContent}. Literal here so the SDK
+ * stays bundle-clean (no `@fias/entities` runtime dep).
+ *
+ * SYNC NOTE: must match `PLUGIN_CONTENT_ENTITY_ID` in
+ * `packages/entities/src/integrations/plugin-content/config.ts`. The
+ * architecture test `sdk-entity-id-constants-match.test.ts` pins this.
+ */
+exports.PLUGIN_CONTENT_ENTITY_ID = 'ent_intg_plugin_content_00000000';
+/** A failed content read: `code` says why, `path` names the file when there is one. */
+class FiasContentError extends Error {
+    constructor(message, code, path) {
+        super(message);
+        this.code = code;
+        this.path = path;
+        this.name = 'FiasContentError';
+    }
+}
+exports.FiasContentError = FiasContentError;
+function toContentError(err) {
+    if (err instanceof FiasContentError)
+        return err;
+    const message = err instanceof Error ? err.message : String(err);
+    const code = err?.code;
+    if (/permission denied/i.test(message))
+        return new FiasContentError(message, 'PERMISSION_DENIED');
+    if (code === 'RATE_LIMITED' || /rate limit/i.test(message)) {
+        return new FiasContentError(message, 'RATE_LIMIT');
+    }
+    return new FiasContentError(message, 'CONTENT_UNAVAILABLE');
+}
+function fileResult(results, path) {
+    const result = results?.[path];
+    if (!result) {
+        throw new FiasContentError(`No result for content/${path}`, 'CONTENT_UNAVAILABLE', path);
+    }
+    if ('error' in result)
+        throw new FiasContentError(result.error.message, result.error.code, path);
+    return result;
+}
+/**
+ * `blob:` URLs built in this iframe, per path. A published pack is immutable,
+ * so one URL per path serves the plugin for its whole life.
+ */
+const contentObjectUrls = new Map();
+/**
+ * Read this plugin's own content pack — the reviewed `content/` directory it
+ * was published with (lessons, data, images, audio, fonts).
+ *
+ * The host page reads the pack from the Fias content CDN, verifies every file
+ * against its hash, and caches it; nothing here touches the network, and a
+ * plugin can only read its own pack. Reads are free for your users; the
+ * contributor pays the pack's storage and bandwidth, and cached repeat reads
+ * cost nothing.
+ *
+ * Paths are relative to `content/`. In the Arche Builder and developer
+ * previews there is no published pack: calls fail with
+ * `CONTENT_UNAVAILABLE_IN_PREVIEW` (the dev harness serves your local
+ * `content/` instead).
+ *
+ * Permission: `entities:client_invoke`.
+ *
+ * @example
+ *   const content = useFiasContent();
+ *   const lessons = await content.list('lessons/');
+ *   const markdown = await content.getText(lessons[0].path);
+ *   const cover = await content.getObjectUrl('img/cover.webp'); // <img src={cover}>
+ */
+function useFiasContent() {
+    const bridge = useBridge();
+    const call = (0, react_1.useCallback)(async (input) => {
+        let response;
+        try {
+            response = await bridge.request('client_entity_invoke', { entityId: exports.PLUGIN_CONTENT_ENTITY_ID, input }, CLIENT_ENTITY_INVOKE_TIMEOUT_MS);
+        }
+        catch (err) {
+            throw toContentError(err);
+        }
+        if (response?.error) {
+            throw new FiasContentError(response.error.message, response.error.code);
+        }
+        return response ?? {};
+    }, [bridge]);
+    const list = (0, react_1.useCallback)(async (prefix) => (await call({ verb: 'list', ...(prefix !== undefined ? { prefix } : {}) })).files ?? [], [call]);
+    const getText = (0, react_1.useCallback)(async (path) => {
+        const { results } = await call({ verb: 'read', paths: [path], as: 'text' });
+        return fileResult(results, path).text;
+    }, [call]);
+    const getJson = (0, react_1.useCallback)(async (path) => JSON.parse(await getText(path)), [getText]);
+    const readBytes = (0, react_1.useCallback)(async (path) => {
+        const { results } = await call({ verb: 'read', paths: [path], as: 'bytes' });
+        return fileResult(results, path);
+    }, [call]);
+    const getBytes = (0, react_1.useCallback)(async (path) => (await readBytes(path)).bytes, [readBytes]);
+    const getMany = (0, react_1.useCallback)(async (paths, as) => {
+        const { results } = await call({ verb: 'read', paths, as });
+        const out = {};
+        for (const path of paths) {
+            try {
+                const result = fileResult(results, path);
+                out[path] =
+                    as === 'text'
+                        ? result.text
+                        : result.bytes;
+            }
+            catch (err) {
+                out[path] = toContentError(err);
+            }
+        }
+        return out;
+    }, [call]);
+    const getObjectUrl = (0, react_1.useCallback)(async (path) => {
+        const cached = contentObjectUrls.get(path);
+        if (cached)
+            return cached;
+        const pending = readBytes(path).then(({ bytes, mimeType }) => URL.createObjectURL(new Blob([bytes], { type: mimeType })));
+        contentObjectUrls.set(path, pending);
+        pending.catch(() => contentObjectUrls.delete(path));
+        return pending;
+    }, [readBytes]);
+    const getUrl = (0, react_1.useCallback)(async (path) => {
+        const { results } = await call({ verb: 'url', paths: [path] });
+        const { url, expiresAt } = fileResult(results, path);
+        return { url, expiresAt };
+    }, [call]);
+    return (0, react_1.useMemo)(() => ({ list, getText, getJson, getBytes, getMany, getObjectUrl, getUrl }), [list, getText, getJson, getBytes, getMany, getObjectUrl, getUrl]);
+}
 /**
  * Preserve transient UI state across a builder-preview rebuild.
  *
@@ -1448,7 +1707,15 @@ function useDataSubscription(collection, onInvalidate, options) {
  * 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
+ * Vault → Arche Access) and audited by the platform.
+ *
+ * The picker offers the files of the workspace the user is acting in (the
+ * host's workspace switcher — Personal, or an org workspace they belong to)
+ * and `list()` returns the grants made in it; a document you hold a grant on
+ * stays readable by id whichever workspace the user is in, because a grant
+ * belongs to the workspace the document lives in. A plugin never names a
+ * workspace; the host does. A member's role caps what they can share and
+ * read. Proprietary-sensitivity
  * documents are never grantable. For documents your plugin CREATES, use
  * `useVaultDocuments` instead.
  */
@@ -1457,6 +1724,39 @@ function useVaultUserDocuments() {
     const pick = (0, react_1.useCallback)(async (options) => {
         return bridge.request('vault_documents_pick', {
             maxDocuments: options?.maxDocuments,
+            access: options?.access,
+            ...(options?.accept ? { accept: [...options.accept] } : {}),
+        });
+    }, [bridge]);
+    const requestEditAccess = (0, react_1.useCallback)(async (documentId) => {
+        // The same host-mediated op as `pick`, naming one document. The HOST
+        // decides whether it may skip the picker (only for a document this arche
+        // already holds a grant on) — nothing here can.
+        return bridge.request('vault_documents_pick', {
+            maxDocuments: 1,
+            access: 'write',
+            documentId,
+        });
+    }, [bridge]);
+    const saveContent = (0, react_1.useCallback)(async (params) => {
+        const routed = await routeSaveContent(params.content);
+        if (routed.lane === 'body') {
+            return (0, entity_ops_1.invokeEntityOp)(bridge, entity_ops_1.VAULT_USER_DOCUMENTS_ENTITY_ID, 'save_consented_document_content', {
+                documentId: params.documentId,
+                content: routed.text,
+                expectedRevision: params.expectedRevision,
+            });
+        }
+        // Bytes, or text past the bridge body: the host does the presigned PUT
+        // (the iframe's CSP forbids it). `saveTarget: 'user'` selects the
+        // consented lane; no `name`, so an older host refuses rather than
+        // creating a new document.
+        return bridge.request('vault_documents_upload', {
+            saveToDocumentId: params.documentId,
+            saveTarget: 'user',
+            bytes: bytesToBase64(routed.bytes),
+            contentKind: routed.contentKind,
+            expectedRevision: params.expectedRevision,
         });
     }, [bridge]);
     const list = (0, react_1.useCallback)(async (options) => {
@@ -1482,7 +1782,7 @@ function useVaultUserDocuments() {
             contentType: res.contentType,
         };
     }, [bridge]);
-    return (0, react_1.useMemo)(() => ({ pick, list, get, getDownloadUrl, getBytes }), [pick, list, get, getDownloadUrl, getBytes]);
+    return (0, react_1.useMemo)(() => ({ pick, requestEditAccess, saveContent, list, get, getDownloadUrl, getBytes }), [pick, requestEditAccess, saveContent, list, get, getDownloadUrl, getBytes]);
 }
 /**
  * Refresh a community-asset URL this many ms before it expires. Larger than the
@@ -1689,7 +1989,7 @@ function useCommunityAssets() {
  * You get a document REFERENCE, not bytes. Read it with
  * `useVaultUserDocuments().getBytes(documentId)`: the host grants you that one
  * document as it relays the handoff, so no `pick()` is needed first. The grant
- * is per-document and revocable in Vault → App Access exactly like a picked
+ * is per-document and revocable in Vault → Arche Access exactly like a picked
  * one, and it needs `vault:user-documents:read` — declare it, or the grant is
  * refused and the file never arrives.
  *