@fias/create-fias-plugin 1.9.1 → 1.10.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fias/create-fias-plugin",
-  "version": "1.9.1",
+  "version": "1.10.1",
   "publishConfig": {
     "access": "public"
   },

package/templates/default/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- fias-sdk-guide-version: 2.17.0 -->
+<!-- fias-sdk-guide-version: 2.18.0 -->
 
 # FIAS Plugin Development Guide
 
@@ -728,6 +728,18 @@ const { referenceId } = await vault.attach(documentId, {
 await vault.detach(documentId, referenceId);
 ```
 
+**Saving into the user's OWN files** — `upload(bytes, { ..., userVisible: true })`. By default everything your app writes here is _arche-private_: yours to read and write, invisible in the user's Fias files, unusable by other arches. That is the right home for your app's own state (caches, session snapshots, working files). It is the wrong home for the artifact the user made and asked you to keep — an edited image, an exported document — because they will go looking for it and it will not be there.
+
+```tsx
+const saved = await vault.upload(bytes, {
+  name: 'sunset.png',
+  mimeType: 'image/png',
+  userVisible: true,
+});
+```
+
+Requires the `vault:user-documents:write` permission, and the HOST asks the user to confirm each save by name — you cannot script it, batch it, or pre-approve it. A decline rejects with `SAVE_DECLINED`; that is a normal outcome, not an error to retry. The file lands in `/My-Fias/<your arche's folder>/`, which the platform assigns — you cannot choose it, and `folderPath` is rejected alongside `userVisible`. Your arche must be registered for a user-visible folder platform-side (`ARCHE_NOT_REGISTERED_FOR_USER_VAULT` if not). Passing `replacesDocumentId` saves a new version in place; a version keeps its predecessor's visibility, so you cannot flip a user's visible file to private or vice versa (`VISIBILITY_MISMATCH`). Not available in preview or the dev harness — test it in the published plugin.
+
 **Sensitivity tiers** (`'standard'` | `'confidential'` | `'proprietary'`) gate downstream read access per the Vault's standard matrix. Defaults to `'standard'`.
 
 **`fetchVaultDocumentDownloadUrl(documentId)`** — non-React function that shares the hook's client-side URL cache. Use from PDF exporters, image preloaders, or other non-component code paths.
@@ -770,6 +782,34 @@ const { bytes } = await userDocs.getBytes(id); // raw bytes for PROCESSING binar
 - Revocation behaves differently per method: `getBytes` and `get` re-check the grant on every call, so they start failing immediately. A URL already handed out by `getDownloadUrl` keeps working until it expires (1 hour) — that is the documented contract, not a bug.
 - **Testable in the dev harness (mock mode).** `pick()` grants a small fixture set — a text file, a real PDF, and one deliberately over the 15 MB cap — and `list` / `get` / `getDownloadUrl` / `getBytes` all resolve against it, including the refusals (`BINARY_DOCUMENT` on a text read of a PDF, `CONSENTED_DOCUMENT_TOO_LARGE`, `DOCUMENT_NOT_FOUND`). Run the harness with `FIAS_HARNESS_VAULT_PICK=canceled` to exercise the cancel branch. Not available in the builder preview — `pick()` resolves `{ canceled: true }` there.
 
+### `useArcheHandoff()` — Receive a document the user asked to open in your app
+
+**Permission:** none to receive. Reading the document is a separate act (`vault:user-documents:read`, via `useVaultUserDocuments().getBytes`).
+
+Fires when the user sends a document your way — "open this in <your app>" from the Fias AI assistant, from an email attachment, from any Vault document's "open in" affordance. You are only offered as a destination if the platform has registered your arche for document intake; declaring this hook does not enrol you.
+
+```tsx
+import { useArcheHandoff, useVaultUserDocuments } from '@fias/arche-sdk';
+
+const userDocs = useVaultUserDocuments();
+
+useArcheHandoff((payload) => {
+  if (payload.kind !== 'open_document') return; // switch on kind — the union grows
+  void (async () => {
+    const { bytes } = await userDocs.getBytes(payload.documentId);
+    // Open it as a NEW, UNSAVED document in your editor.
+  })();
+});
+```
+
+**The contract:**
+
+- You get a **reference, not bytes** — and the host grants you that one document as it relays the handoff, so `getBytes(documentId)` works without a `pick()` first. The grant is per-document and revocable in Vault → App Access exactly like a picked one. You must declare `vault:user-documents:read`; without it the grant is refused and the file never reaches you.
+- **Open it as an unsaved copy.** A later save must create a NEW document. The source may be someone's email attachment or a shared file; it is never yours to mutate.
+- **You are the type gate.** If you cannot open this file, say so plainly in your UI. Half-opening it is worse than refusing.
+- Fires **once per handoff**, and one that arrives before your hook mounts is buffered and delivered on registration — so the first handoff of a session is never lost.
+- Nothing hands documents to a preview, so the handler only fires in the published plugin.
+
 ### `useFiasAIActions()` — Let the platform's Fias AI assistant operate your plugin
 
 **Permission:** `ai:actions`
@@ -939,8 +979,28 @@ navigateTo('/settings'); // within THIS arche's route space
 // best-effort — the browser may block the popup, in which case the host
 // navigates in the same tab instead.
 openArche('arc_0123456789abcdef0123456789abcdef', { newTab: true });
+
+// Land on a SPECIFIC page of the target arche instead of its home screen.
+// `path` has no leading slash and is one or two `[A-Za-z0-9_-]` segments.
+// Accepted for `arc_…` targets only — a path aimed at a first-party
+// `arche_…` arche is rejected, as is a malformed one (you get an error, never
+// a silent landing on the home screen).
+openArche('arc_0123456789abcdef0123456789abcdef', { path: 'map' });
+```
+
+**Receiving a deep link.** There is nothing extra to opt into: `currentPath` in
+the init payload is the full platform path the host loaded you at, so an arche
+that wants to be a deep-link target just reads it once at boot.
+
+```tsx
+const { currentPath } = useFiasNavigation();
+// e.g. '/a/arc_0123…/map' → 'map'
+const page = currentPath.split('/').slice(3).join('/') || 'home';
 ```
 
+It is set once, when your app mounts. A deep link from another arche always
+mounts you fresh, so that is exactly when you need it.
+
 ### Opening external links
 
 To send the user to an external website (a YouTube video, docs, your homepage),

package/templates/default/CLAUDE.md

@@ -1,4 +1,4 @@
-<!-- fias-sdk-guide-version: 2.17.0 -->
+<!-- fias-sdk-guide-version: 2.18.0 -->
 
 # FIAS Plugin Development Guide
 
@@ -728,6 +728,18 @@ const { referenceId } = await vault.attach(documentId, {
 await vault.detach(documentId, referenceId);
 ```
 
+**Saving into the user's OWN files** — `upload(bytes, { ..., userVisible: true })`. By default everything your app writes here is _arche-private_: yours to read and write, invisible in the user's Fias files, unusable by other arches. That is the right home for your app's own state (caches, session snapshots, working files). It is the wrong home for the artifact the user made and asked you to keep — an edited image, an exported document — because they will go looking for it and it will not be there.
+
+```tsx
+const saved = await vault.upload(bytes, {
+  name: 'sunset.png',
+  mimeType: 'image/png',
+  userVisible: true,
+});
+```
+
+Requires the `vault:user-documents:write` permission, and the HOST asks the user to confirm each save by name — you cannot script it, batch it, or pre-approve it. A decline rejects with `SAVE_DECLINED`; that is a normal outcome, not an error to retry. The file lands in `/My-Fias/<your arche's folder>/`, which the platform assigns — you cannot choose it, and `folderPath` is rejected alongside `userVisible`. Your arche must be registered for a user-visible folder platform-side (`ARCHE_NOT_REGISTERED_FOR_USER_VAULT` if not). Passing `replacesDocumentId` saves a new version in place; a version keeps its predecessor's visibility, so you cannot flip a user's visible file to private or vice versa (`VISIBILITY_MISMATCH`). Not available in preview or the dev harness — test it in the published plugin.
+
 **Sensitivity tiers** (`'standard'` | `'confidential'` | `'proprietary'`) gate downstream read access per the Vault's standard matrix. Defaults to `'standard'`.
 
 **`fetchVaultDocumentDownloadUrl(documentId)`** — non-React function that shares the hook's client-side URL cache. Use from PDF exporters, image preloaders, or other non-component code paths.
@@ -770,6 +782,34 @@ const { bytes } = await userDocs.getBytes(id); // raw bytes for PROCESSING binar
 - Revocation behaves differently per method: `getBytes` and `get` re-check the grant on every call, so they start failing immediately. A URL already handed out by `getDownloadUrl` keeps working until it expires (1 hour) — that is the documented contract, not a bug.
 - **Testable in the dev harness (mock mode).** `pick()` grants a small fixture set — a text file, a real PDF, and one deliberately over the 15 MB cap — and `list` / `get` / `getDownloadUrl` / `getBytes` all resolve against it, including the refusals (`BINARY_DOCUMENT` on a text read of a PDF, `CONSENTED_DOCUMENT_TOO_LARGE`, `DOCUMENT_NOT_FOUND`). Run the harness with `FIAS_HARNESS_VAULT_PICK=canceled` to exercise the cancel branch. Not available in the builder preview — `pick()` resolves `{ canceled: true }` there.
 
+### `useArcheHandoff()` — Receive a document the user asked to open in your app
+
+**Permission:** none to receive. Reading the document is a separate act (`vault:user-documents:read`, via `useVaultUserDocuments().getBytes`).
+
+Fires when the user sends a document your way — "open this in <your app>" from the Fias AI assistant, from an email attachment, from any Vault document's "open in" affordance. You are only offered as a destination if the platform has registered your arche for document intake; declaring this hook does not enrol you.
+
+```tsx
+import { useArcheHandoff, useVaultUserDocuments } from '@fias/arche-sdk';
+
+const userDocs = useVaultUserDocuments();
+
+useArcheHandoff((payload) => {
+  if (payload.kind !== 'open_document') return; // switch on kind — the union grows
+  void (async () => {
+    const { bytes } = await userDocs.getBytes(payload.documentId);
+    // Open it as a NEW, UNSAVED document in your editor.
+  })();
+});
+```
+
+**The contract:**
+
+- You get a **reference, not bytes** — and the host grants you that one document as it relays the handoff, so `getBytes(documentId)` works without a `pick()` first. The grant is per-document and revocable in Vault → App Access exactly like a picked one. You must declare `vault:user-documents:read`; without it the grant is refused and the file never reaches you.
+- **Open it as an unsaved copy.** A later save must create a NEW document. The source may be someone's email attachment or a shared file; it is never yours to mutate.
+- **You are the type gate.** If you cannot open this file, say so plainly in your UI. Half-opening it is worse than refusing.
+- Fires **once per handoff**, and one that arrives before your hook mounts is buffered and delivered on registration — so the first handoff of a session is never lost.
+- Nothing hands documents to a preview, so the handler only fires in the published plugin.
+
 ### `useFiasAIActions()` — Let the platform's Fias AI assistant operate your plugin
 
 **Permission:** `ai:actions`
@@ -939,8 +979,28 @@ navigateTo('/settings'); // within THIS arche's route space
 // best-effort — the browser may block the popup, in which case the host
 // navigates in the same tab instead.
 openArche('arc_0123456789abcdef0123456789abcdef', { newTab: true });
+
+// Land on a SPECIFIC page of the target arche instead of its home screen.
+// `path` has no leading slash and is one or two `[A-Za-z0-9_-]` segments.
+// Accepted for `arc_…` targets only — a path aimed at a first-party
+// `arche_…` arche is rejected, as is a malformed one (you get an error, never
+// a silent landing on the home screen).
+openArche('arc_0123456789abcdef0123456789abcdef', { path: 'map' });
+```
+
+**Receiving a deep link.** There is nothing extra to opt into: `currentPath` in
+the init payload is the full platform path the host loaded you at, so an arche
+that wants to be a deep-link target just reads it once at boot.
+
+```tsx
+const { currentPath } = useFiasNavigation();
+// e.g. '/a/arc_0123…/map' → 'map'
+const page = currentPath.split('/').slice(3).join('/') || 'home';
 ```
 
+It is set once, when your app mounts. A deep link from another arche always
+mounts you fresh, so that is exactly when you need it.
+
 ### Opening external links
 
 To send the user to an external website (a YouTube video, docs, your homepage),