@fias/arche-sdk 2.19.1 → 2.19.2

package/dist/entity-ops.d.ts

@@ -30,10 +30,13 @@ export declare const PLUGIN_STORE_ENTITY_ID = "ent_intg_plugin_store_0000000000"
 /** Vault Documents entity — plugins may reach ONLY its consented-read verbs
  * (user-granted documents via the host picker; `vault:user-documents:read`). */
 export declare const VAULT_USER_DOCUMENTS_ENTITY_ID = "ent_intg_vault_documents_0000000";
-/** Vault Arche Documents — documents THIS arche created. Two verbs:
- * `get_own_document_bytes` (`vault:documents:read`) and
- * `save_own_document_content` (additionally `vault:documents:write`) — the
- * permissions `useVaultDocuments` already derives. */
+/** Vault Arche Documents — documents THIS arche created.
+ * `get_own_document_bytes` (`vault:documents:read`), and the in-place save:
+ * `save_own_document_content` for small text, or — driven by the HOST, since
+ * the iframe cannot PUT — `init_own_document_save` /
+ * `finalize_own_document_save` for bytes and large text (all three
+ * additionally `vault:documents:write`). `useVaultDocuments` already derives
+ * both permissions, and `saveContent` picks the lane. */
 export declare const VAULT_ARCHE_DOCUMENTS_ENTITY_ID = "ent_intg_vault_arche_docs_000000";
 /** Community Assets — user-published, moderated images readable by every
  *  authenticated user of the SAME arche. `assets:community:read` for the read

package/dist/entity-ops.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"entity-ops.d.ts","sourceRoot":"","sources":["../src/entity-ops.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE3C,eAAO,MAAM,wBAAwB,qCAAqC,CAAC;AAC3E,eAAO,MAAM,0BAA0B,qCAAqC,CAAC;AAC7E,eAAO,MAAM,2BAA2B,qCAAqC,CAAC;AAC9E,eAAO,MAAM,sBAAsB,qCAAqC,CAAC;AACzE;gFACgF;AAChF,eAAO,MAAM,8BAA8B,qCAAqC,CAAC;AACjF;;;sDAGsD;AACtD,eAAO,MAAM,+BAA+B,qCAAqC,CAAC;AAClF;;;iEAGiE;AACjE,eAAO,MAAM,0BAA0B,qCAAqC,CAAC;AAE7E;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,6BAA6B,KAAK,CAAC;AAChD,eAAO,MAAM,iCAAiC,KAAK,CAAC;AAEpD;;;;;;;;;;;;GAYG;AACH,wBAAsB,cAAc,CAAC,CAAC,EACpC,MAAM,EAAE,UAAU,EAClB,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,EACV,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACjC,OAAO,CAAC,CAAC,CAAC,CAMZ;AAED;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CAAC,CAAC,EACnC,MAAM,EAAE,UAAU,EAClB,EAAE,EAAE,MAAM,EACV,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACjC,OAAO,CAAC,CAAC,CAAC,CAKZ"}
+{"version":3,"file":"entity-ops.d.ts","sourceRoot":"","sources":["../src/entity-ops.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE3C,eAAO,MAAM,wBAAwB,qCAAqC,CAAC;AAC3E,eAAO,MAAM,0BAA0B,qCAAqC,CAAC;AAC7E,eAAO,MAAM,2BAA2B,qCAAqC,CAAC;AAC9E,eAAO,MAAM,sBAAsB,qCAAqC,CAAC;AACzE;gFACgF;AAChF,eAAO,MAAM,8BAA8B,qCAAqC,CAAC;AACjF;;;;;;yDAMyD;AACzD,eAAO,MAAM,+BAA+B,qCAAqC,CAAC;AAClF;;;iEAGiE;AACjE,eAAO,MAAM,0BAA0B,qCAAqC,CAAC;AAE7E;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,6BAA6B,KAAK,CAAC;AAChD,eAAO,MAAM,iCAAiC,KAAK,CAAC;AAEpD;;;;;;;;;;;;GAYG;AACH,wBAAsB,cAAc,CAAC,CAAC,EACpC,MAAM,EAAE,UAAU,EAClB,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,MAAM,EACV,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACjC,OAAO,CAAC,CAAC,CAAC,CAMZ;AAED;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CAAC,CAAC,EACnC,MAAM,EAAE,UAAU,EAClB,EAAE,EAAE,MAAM,EACV,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACjC,OAAO,CAAC,CAAC,CAAC,CAKZ"}

package/dist/entity-ops.js

@@ -10,10 +10,13 @@ exports.PLUGIN_STORE_ENTITY_ID = 'ent_intg_plugin_store_0000000000';
 /** Vault Documents entity — plugins may reach ONLY its consented-read verbs
  * (user-granted documents via the host picker; `vault:user-documents:read`). */
 exports.VAULT_USER_DOCUMENTS_ENTITY_ID = 'ent_intg_vault_documents_0000000';
-/** Vault Arche Documents — documents THIS arche created. Two verbs:
- * `get_own_document_bytes` (`vault:documents:read`) and
- * `save_own_document_content` (additionally `vault:documents:write`) — the
- * permissions `useVaultDocuments` already derives. */
+/** Vault Arche Documents — documents THIS arche created.
+ * `get_own_document_bytes` (`vault:documents:read`), and the in-place save:
+ * `save_own_document_content` for small text, or — driven by the HOST, since
+ * the iframe cannot PUT — `init_own_document_save` /
+ * `finalize_own_document_save` for bytes and large text (all three
+ * additionally `vault:documents:write`). `useVaultDocuments` already derives
+ * both permissions, and `saveContent` picks the lane. */
 exports.VAULT_ARCHE_DOCUMENTS_ENTITY_ID = 'ent_intg_vault_arche_docs_000000';
 /** Community Assets — user-published, moderated images readable by every
  *  authenticated user of the SAME arche. `assets:community:read` for the read

package/dist/entity-ops.js.map

@@ -1 +1 @@
-{"version":3,"file":"entity-ops.js","sourceRoot":"","sources":["../src/entity-ops.ts"],"names":[],"mappings":";;;AAyEA,wCAWC;AAWD,sCASC;AA9EY,QAAA,wBAAwB,GAAG,kCAAkC,CAAC;AAC9D,QAAA,0BAA0B,GAAG,kCAAkC,CAAC;AAChE,QAAA,2BAA2B,GAAG,kCAAkC,CAAC;AACjE,QAAA,sBAAsB,GAAG,kCAAkC,CAAC;AACzE;gFACgF;AACnE,QAAA,8BAA8B,GAAG,kCAAkC,CAAC;AACjF;;;sDAGsD;AACzC,QAAA,+BAA+B,GAAG,kCAAkC,CAAC;AAClF;;;iEAGiE;AACpD,QAAA,0BAA0B,GAAG,kCAAkC,CAAC;AAE7E;;;;;;;;;;;;GAYG;AACU,QAAA,6BAA6B,GAAG,EAAE,CAAC;AACnC,QAAA,iCAAiC,GAAG,EAAE,CAAC;AAEpD;;;;;;;;;;;;GAYG;AACI,KAAK,UAAU,cAAc,CAClC,MAAkB,EAClB,QAAgB,EAChB,EAAU,EACV,OAAgC,EAAE;IAElC,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,OAAO,CAAgB,eAAe,EAAE;QAC/D,QAAQ;QACR,OAAO,EAAE,EAAE,EAAE,EAAE,GAAG,IAAI,EAAE;KACzB,CAAC,CAAC;IACH,OAAO,GAAG,CAAC,MAAM,CAAC;AACpB,CAAC;AAED;;;;;;;;GAQG;AACI,KAAK,UAAU,aAAa,CACjC,MAAkB,EAClB,EAAU,EACV,OAAgC,EAAE;IAElC,OAAO,MAAM,CAAC,OAAO,CAAI,eAAe,EAAE;QACxC,QAAQ,EAAE,8BAAsB;QAChC,OAAO,EAAE,EAAE,EAAE,EAAE,GAAG,IAAI,EAAE;KACzB,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"entity-ops.js","sourceRoot":"","sources":["../src/entity-ops.ts"],"names":[],"mappings":";;;AA4EA,wCAWC;AAWD,sCASC;AAjFY,QAAA,wBAAwB,GAAG,kCAAkC,CAAC;AAC9D,QAAA,0BAA0B,GAAG,kCAAkC,CAAC;AAChE,QAAA,2BAA2B,GAAG,kCAAkC,CAAC;AACjE,QAAA,sBAAsB,GAAG,kCAAkC,CAAC;AACzE;gFACgF;AACnE,QAAA,8BAA8B,GAAG,kCAAkC,CAAC;AACjF;;;;;;yDAMyD;AAC5C,QAAA,+BAA+B,GAAG,kCAAkC,CAAC;AAClF;;;iEAGiE;AACpD,QAAA,0BAA0B,GAAG,kCAAkC,CAAC;AAE7E;;;;;;;;;;;;GAYG;AACU,QAAA,6BAA6B,GAAG,EAAE,CAAC;AACnC,QAAA,iCAAiC,GAAG,EAAE,CAAC;AAEpD;;;;;;;;;;;;GAYG;AACI,KAAK,UAAU,cAAc,CAClC,MAAkB,EAClB,QAAgB,EAChB,EAAU,EACV,OAAgC,EAAE;IAElC,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,OAAO,CAAgB,eAAe,EAAE;QAC/D,QAAQ;QACR,OAAO,EAAE,EAAE,EAAE,EAAE,GAAG,IAAI,EAAE;KACzB,CAAC,CAAC;IACH,OAAO,GAAG,CAAC,MAAM,CAAC;AACpB,CAAC;AAED;;;;;;;;GAQG;AACI,KAAK,UAAU,aAAa,CACjC,MAAkB,EAClB,EAAU,EACV,OAAgC,EAAE;IAElC,OAAO,MAAM,CAAC,OAAO,CAAI,eAAe,EAAE;QACxC,QAAQ,EAAE,8BAAsB;QAChC,OAAO,EAAE,EAAE,EAAE,EAAE,GAAG,IAAI,EAAE;KACzB,CAAC,CAAC;AACL,CAAC"}

package/dist/generated/permissions.d.ts

@@ -9,7 +9,7 @@
  * `tests/architecture/sdk-permissions-match-db-types.test.ts` ensures
  * this file stays in lockstep with the canonical source.
  */
-export type PluginPermission = 'ai:actions' | 'assets:community:publish' | 'assets:community:read' | 'assets:read' | 'data:search' | 'data:store' | 'data:workspace' | 'entities:audio_generate' | 'entities:client_invoke' | 'entities:image_edit' | 'entities:image_generate' | 'entities:invoke' | 'entities:web_search' | 'navigation:open_arche' | 'sandbox:vendored-libraries' | 'storage:sandbox' | 'store:purchase' | 'theme:read' | 'user:profile:read' | 'vault:documents:read' | 'vault:documents:write' | 'vault:user-documents:read' | 'vault:user-documents:write';
+export type PluginPermission = 'ai:actions' | 'assets:community:publish' | 'assets:community:read' | 'assets:read' | 'data:search' | 'data:store' | 'data:workspace' | 'entities:audio_generate' | 'entities:client_invoke' | 'entities:image_edit' | 'entities:image_generate' | 'entities:invoke' | 'entities:web_search' | 'navigation:open_arche' | 'sandbox:vendored-libraries' | 'storage:sandbox' | 'store:purchase' | 'theme:read' | 'user:profile:read' | 'vault:documents:read' | 'vault:documents:write' | 'vault:user-documents:edit' | 'vault:user-documents:read' | 'vault:user-documents:write';
 export declare const VALID_PLUGIN_PERMISSIONS: readonly PluginPermission[];
 export declare function isValidPluginPermission(perm: string): perm is PluginPermission;
 /**

package/dist/generated/permissions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../../src/generated/permissions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,MAAM,gBAAgB,GACxB,YAAY,GACZ,0BAA0B,GAC1B,uBAAuB,GACvB,aAAa,GACb,aAAa,GACb,YAAY,GACZ,gBAAgB,GAChB,yBAAyB,GACzB,wBAAwB,GACxB,qBAAqB,GACrB,yBAAyB,GACzB,iBAAiB,GACjB,qBAAqB,GACrB,uBAAuB,GACvB,4BAA4B,GAC5B,iBAAiB,GACjB,gBAAgB,GAChB,YAAY,GACZ,mBAAmB,GACnB,sBAAsB,GACtB,uBAAuB,GACvB,2BAA2B,GAC3B,4BAA4B,CAAC;AAEjC,eAAO,MAAM,wBAAwB,EAAE,SAAS,gBAAgB,EAwBtD,CAAC;AAEX,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,gBAAgB,CAE9E;AAED;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,EAAE,QAAQ,CAAC,MAAM,CAAC,gBAAgB,EAAE,MAAM,CAAC,CA+BrF,CAAC"}
+{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../../src/generated/permissions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,MAAM,gBAAgB,GACxB,YAAY,GACZ,0BAA0B,GAC1B,uBAAuB,GACvB,aAAa,GACb,aAAa,GACb,YAAY,GACZ,gBAAgB,GAChB,yBAAyB,GACzB,wBAAwB,GACxB,qBAAqB,GACrB,yBAAyB,GACzB,iBAAiB,GACjB,qBAAqB,GACrB,uBAAuB,GACvB,4BAA4B,GAC5B,iBAAiB,GACjB,gBAAgB,GAChB,YAAY,GACZ,mBAAmB,GACnB,sBAAsB,GACtB,uBAAuB,GACvB,2BAA2B,GAC3B,2BAA2B,GAC3B,4BAA4B,CAAC;AAEjC,eAAO,MAAM,wBAAwB,EAAE,SAAS,gBAAgB,EAyBtD,CAAC;AAEX,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,gBAAgB,CAE9E;AAED;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,EAAE,QAAQ,CAAC,MAAM,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAiCrF,CAAC"}

package/dist/generated/permissions.js

@@ -35,6 +35,7 @@ exports.VALID_PLUGIN_PERMISSIONS = [
     'user:profile:read',
     'vault:documents:read',
     'vault:documents:write',
+    'vault:user-documents:edit',
     'vault:user-documents:read',
     'vault:user-documents:write',
 ];
@@ -68,6 +69,7 @@ exports.PLUGIN_PERMISSION_DESCRIPTIONS = {
     'user:profile:read': 'See your display name and avatar.',
     'vault:documents:read': 'Read documents this app itself created in your Vault.',
     'vault:documents:write': 'Create and manage its own documents in your Vault.',
+    'vault:user-documents:edit': 'Save changes to files of yours that you let it edit — you choose each file, earlier versions are kept, and you can remove access any time in Vault → App Access.',
     'vault:user-documents:read': 'Read documents YOU choose to share with it from your Vault — you pick each document, and you can remove access any time in Vault → App Access.',
     'vault:user-documents:write': 'Save its work to your Fias files, where you can find and reuse it. You confirm each save.',
 };

package/dist/generated/permissions.js.map

@@ -1 +1 @@
-{"version":3,"file":"permissions.js","sourceRoot":"","sources":["../../src/generated/permissions.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;;AAqDH,0DAEC;AA5BY,QAAA,wBAAwB,GAAgC;IACnE,YAAY;IACZ,0BAA0B;IAC1B,uBAAuB;IACvB,aAAa;IACb,aAAa;IACb,YAAY;IACZ,gBAAgB;IAChB,yBAAyB;IACzB,wBAAwB;IACxB,qBAAqB;IACrB,yBAAyB;IACzB,iBAAiB;IACjB,qBAAqB;IACrB,uBAAuB;IACvB,4BAA4B;IAC5B,iBAAiB;IACjB,gBAAgB;IAChB,YAAY;IACZ,mBAAmB;IACnB,sBAAsB;IACtB,uBAAuB;IACvB,2BAA2B;IAC3B,4BAA4B;CACpB,CAAC;AAEX,SAAgB,uBAAuB,CAAC,IAAY;IAClD,OAAQ,gCAA8C,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AACxE,CAAC;AAED;;;;GAIG;AACU,QAAA,8BAA8B,GAA+C;IACxF,YAAY,EACV,2HAA2H;IAC7H,0BAA0B,EACxB,0GAA0G;IAC5G,uBAAuB,EACrB,sHAAsH;IACxH,aAAa,EAAE,sDAAsD;IACrE,aAAa,EAAE,qEAAqE;IACpF,YAAY,EAAE,0DAA0D;IACxE,gBAAgB,EAAE,kDAAkD;IACpE,yBAAyB,EAAE,kDAAkD;IAC7E,wBAAwB,EACtB,wEAAwE;IAC1E,qBAAqB,EAAE,+CAA+C;IACtE,yBAAyB,EAAE,mDAAmD;IAC9E,iBAAiB,EAAE,wDAAwD;IAC3E,qBAAqB,EAAE,qDAAqD;IAC5E,uBAAuB,EAAE,8CAA8C;IACvE,4BAA4B,EAC1B,8EAA8E;IAChF,iBAAiB,EAAE,+CAA+C;IAClE,gBAAgB,EAAE,qDAAqD;IACvE,YAAY,EAAE,4BAA4B;IAC1C,mBAAmB,EAAE,mCAAmC;IACxD,sBAAsB,EAAE,uDAAuD;IAC/E,uBAAuB,EAAE,oDAAoD;IAC7E,2BAA2B,EACzB,gJAAgJ;IAClJ,4BAA4B,EAC1B,2FAA2F;CAC9F,CAAC"}
+{"version":3,"file":"permissions.js","sourceRoot":"","sources":["../../src/generated/permissions.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;;AAuDH,0DAEC;AA7BY,QAAA,wBAAwB,GAAgC;IACnE,YAAY;IACZ,0BAA0B;IAC1B,uBAAuB;IACvB,aAAa;IACb,aAAa;IACb,YAAY;IACZ,gBAAgB;IAChB,yBAAyB;IACzB,wBAAwB;IACxB,qBAAqB;IACrB,yBAAyB;IACzB,iBAAiB;IACjB,qBAAqB;IACrB,uBAAuB;IACvB,4BAA4B;IAC5B,iBAAiB;IACjB,gBAAgB;IAChB,YAAY;IACZ,mBAAmB;IACnB,sBAAsB;IACtB,uBAAuB;IACvB,2BAA2B;IAC3B,2BAA2B;IAC3B,4BAA4B;CACpB,CAAC;AAEX,SAAgB,uBAAuB,CAAC,IAAY;IAClD,OAAQ,gCAA8C,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AACxE,CAAC;AAED;;;;GAIG;AACU,QAAA,8BAA8B,GAA+C;IACxF,YAAY,EACV,2HAA2H;IAC7H,0BAA0B,EACxB,0GAA0G;IAC5G,uBAAuB,EACrB,sHAAsH;IACxH,aAAa,EAAE,sDAAsD;IACrE,aAAa,EAAE,qEAAqE;IACpF,YAAY,EAAE,0DAA0D;IACxE,gBAAgB,EAAE,kDAAkD;IACpE,yBAAyB,EAAE,kDAAkD;IAC7E,wBAAwB,EACtB,wEAAwE;IAC1E,qBAAqB,EAAE,+CAA+C;IACtE,yBAAyB,EAAE,mDAAmD;IAC9E,iBAAiB,EAAE,wDAAwD;IAC3E,qBAAqB,EAAE,qDAAqD;IAC5E,uBAAuB,EAAE,8CAA8C;IACvE,4BAA4B,EAC1B,8EAA8E;IAChF,iBAAiB,EAAE,+CAA+C;IAClE,gBAAgB,EAAE,qDAAqD;IACvE,YAAY,EAAE,4BAA4B;IAC1C,mBAAmB,EAAE,mCAAmC;IACxD,sBAAsB,EAAE,uDAAuD;IAC/E,uBAAuB,EAAE,oDAAoD;IAC7E,2BAA2B,EACzB,kKAAkK;IACpK,2BAA2B,EACzB,gJAAgJ;IAClJ,4BAA4B,EAC1B,2FAA2F;CAC9F,CAAC"}

package/dist/hooks.d.ts

@@ -1,4 +1,4 @@
-import type { ArcheHandoffPayload, FiasUser, FiasTheme, FiasStorageApi, DataSubscriptionState, EntityInvocationApi, ClientEntityApi, ImageGenerationApi, ImageEntityFilter, ImageEntitySummary, NllbLanguageOption, AudioGenerationApi, FiasNavigationApi, StepNavigationApi, StepNavigationOptions, FiasDataStoreApi, FiasWorkspacesApi, FiasStoreApi, VaultDocumentsApi, VaultDocumentDownloadUrl, ArcheAssetsApi, CommunityAssetsApi, FiasAIActionsDeclaration } from './types';
+import type { ArcheHandoffPayload, FiasUser, FiasTheme, FiasStorageApi, DataSubscriptionState, EntityInvocationApi, ClientEntityApi, ImageGenerationApi, ImageEntityFilter, ImageEntitySummary, NllbLanguageOption, AudioGenerationApi, FiasNavigationApi, StepNavigationApi, StepNavigationOptions, FiasDataStoreApi, FiasWorkspacesApi, FiasStoreApi, VaultDocumentsApi, VaultDocumentDownloadUrl, VaultUserDocumentSaveContentResult, ArcheAssetsApi, CommunityAssetsApi, FiasAIActionsDeclaration } from './types';
 /**
  * Access the current user's profile information.
  * Requires the `user:profile:read` permission in fias-plugin.json.
@@ -412,14 +412,41 @@ export interface VaultUserDocumentSummary {
     sensitivity: string;
     createdAt: string;
     updatedAt: string;
+    /**
+     * What the user lets you do with this document: `'read'` (open it) or
+     * `'write'` (also save changes to it — see `saveContent`). Open a `'read'`
+     * document read-only, and call `requestEditAccess` when the user starts
+     * editing. Optional: absent on hosts that predate edit access — treat
+     * absent as `'read'`.
+     */
+    access?: 'read' | 'write';
+    /**
+     * Opaque token naming the document's current CONTENT. REQUIRED by
+     * `saveContent` as `expectedRevision` — it is the user's file and they may
+     * be changing it elsewhere. Never parse it.
+     */
+    revision?: string;
 }
 /** Result of the host picker: what the user picked and confirmed, or a
  * cancel. A cancel is a normal outcome — never treat it as an error. */
 export type VaultUserDocumentPickResult = {
     canceled: true;
 } | {
-    documents: Array<Pick<VaultUserDocumentSummary, 'documentId' | 'name' | 'mimeType' | 'sizeBytes'>>;
+    documents: Array<Pick<VaultUserDocumentSummary, 'documentId' | 'name' | 'mimeType' | 'sizeBytes'> & {
+        /** What the user granted for this document. */
+        access?: 'read' | 'write';
+    }>;
 };
+/** Input to `useVaultUserDocuments().saveContent`. */
+export interface VaultUserDocumentSaveContentParams {
+    documentId: string;
+    /** The new content, up to 15 MB: a `string` (UTF-8 text — the document must
+     *  be a text type) or bytes. Transport is chosen for you. The document's
+     *  TYPE cannot change, so there is no `contentType`. */
+    content: string | Uint8Array | ArrayBuffer | Blob;
+    /** REQUIRED. The `revision` you last saw for this document. */
+    expectedRevision: string;
+}
 export interface VaultUserDocumentsApi {
     /**
      * Open the HOST's Vault picker + consent sheet. The user hand-picks
@@ -430,7 +457,55 @@ export interface VaultUserDocumentsApi {
      */
     pick(options?: {
         maxDocuments?: number;
+        /** Ask for EDIT access: the user is shown a consent that says your app
+         *  may CHANGE what they pick. Needs `vault:user-documents:edit` IN
+         *  ADDITION TO `vault:user-documents:read` — `:edit` does not include
+         *  `:read`, and every method of this hook (this one included) is gated
+         *  on `:read`. */
+        access?: 'read' | 'write';
     }): Promise<VaultUserDocumentPickResult>;
+    /**
+     * Ask the user to let you EDIT a document you can already open. The host
+     * shows its own consent for that one file — no picker — and resolves with
+     * the document (now `access: 'write'`), or `{ canceled: true }`. Call it
+     * from a user gesture, when the user actually starts editing — not on open,
+     * and not again right after a decline. Needs `vault:user-documents:edit`
+     * together with `vault:user-documents:read`.
+     * If you hold no grant on the document the host shows the ordinary picker
+     * instead, so you learn nothing about files you were not given.
+     *
+     * CHECK THE RESULT — a resolved promise is not "you may now edit
+     * `documentId`". Because of that picker fallback the one document that
+     * comes back may be a DIFFERENT one the user chose, and the user may have
+     * answered from a sheet that offered view-only. Proceed only when
+     * `documents[0].documentId === documentId` and `documents[0].access ===
+     * 'write'`; treat anything else (including `{ canceled: true }`) as "no".
+     */
+    requestEditAccess(documentId: string): Promise<VaultUserDocumentPickResult>;
+    /**
+     * Save changes, IN PLACE, to a document the user has given you EDIT access
+     * to — same `documentId`, so nothing attached to it detaches. Text or bytes,
+     * up to 15 MB; one method, transport chosen for you.
+     *
+     * Manifest: `vault:user-documents:edit` AND `vault:user-documents:read`.
+     * Declaring `:edit` alone is not enough — it does not include `:read`.
+     *
+     * It is the USER'S file, which makes this stricter than saving your own:
+     * `expectedRevision` is REQUIRED (they may be editing it elsewhere — a stale
+     * one rejects `VERSION_CONFLICT`: re-read, merge or ask, retry); the file's
+     * TYPE cannot change (`MIME_CHANGE_NOT_ALLOWED`); and the platform keeps
+     * earlier versions for them, which count against THEIR storage — a save
+     * that would exceed it rejects `STORAGE_QUOTA_EXCEEDED` and nothing is lost.
+     *
+     * Rejects `EDIT_ACCESS_REQUIRED` when you hold view-only access (call
+     * `requestEditAccess`), and `DOCUMENT_NOT_FOUND` once the user removes your
+     * access in Vault → App Access — which takes effect on your very next save.
+     * Handle both. Debounce (a few seconds idle, plus blur and close) and
+     * surface `RATE_LIMIT` rather than looping: this lane allows fewer saves per
+     * minute than your own documents do. Every save is recorded with your app's
+     * name, and the file shows the user that you changed it.
+     */
+    saveContent(params: VaultUserDocumentSaveContentParams): Promise<VaultUserDocumentSaveContentResult>;
     /** Documents the user has granted this arche (empty until they pick). */
     list(options?: {
         limit?: number;
@@ -481,7 +556,15 @@ export interface VaultUserDocumentsApi {
  * 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 → App 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.
  */

package/dist/hooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"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"}

package/dist/hooks.js

@@ -185,7 +185,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 +579,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 +607,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 +648,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 +1101,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 +1118,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,
@@ -1128,6 +1179,18 @@ function useVaultDocuments() {
         // drop any cached URL for this document.
         downloadUrlCache.delete(documentId);
     }, [bridge]);
+    const promoteToUserFiles = (0, react_1.useCallback)(async (documentId) => {
+        // Rides the existing update op with a host-only flag. The HOST
+        // intercepts it, shows the user its own confirmation, and performs the
+        // promote from the user's session — nothing here (or anywhere in the
+        // iframe) can promote a file without the user agreeing.
+        const res = await bridge.request('vault_documents_update', {
+            documentId,
+            userVisible: true,
+        });
+        downloadUrlCache.delete(documentId);
+        return res;
+    }, [bridge]);
     const deleteDocument = (0, react_1.useCallback)(async (documentId) => {
         await bridge.request('vault_documents_delete', { documentId });
         downloadUrlCache.delete(documentId);
@@ -1204,6 +1267,7 @@ function useVaultDocuments() {
         getDownloadUrl,
         write,
         update,
+        promoteToUserFiles,
         delete: deleteDocument,
         search,
         attach,
@@ -1219,6 +1283,7 @@ function useVaultDocuments() {
         getDownloadUrl,
         write,
         update,
+        promoteToUserFiles,
         deleteDocument,
         search,
         attach,
@@ -1228,6 +1293,74 @@ function useVaultDocuments() {
         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);
@@ -1448,7 +1581,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 → App 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 +1598,38 @@ function useVaultUserDocuments() {
     const pick = (0, react_1.useCallback)(async (options) => {
         return bridge.request('vault_documents_pick', {
             maxDocuments: options?.maxDocuments,
+            access: options?.access,
+        });
+    }, [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 +1655,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