@fias/arche-sdk 2.12.0 → 2.14.0

package/templates/default/AGENTS.md

@@ -744,6 +744,7 @@ if ('canceled' in picked) {
 const granted = await userDocs.list(); // all granted docs
 const { document, content } = await userDocs.get(id, { includeContent: true }); // text docs
 const { url } = await userDocs.getDownloadUrl(id); // binary docs (images, PDFs)
+const { bytes } = await userDocs.getBytes(id); // raw bytes for PROCESSING binary docs
 ```
 
 **The consent model (what to tell your users):**
@@ -752,7 +753,55 @@ const { url } = await userDocs.getDownloadUrl(id); // binary docs (images, PDFs)
 - After revocation, `get`/`getDownloadUrl` reject with `DOCUMENT_NOT_FOUND` — handle that path gracefully (drop the document from your UI; do not retry in a loop).
 - `proprietary`-sensitivity documents are never grantable (they don't even appear in the picker).
 - Every read is audited by the platform; a new document _version_ is a new documentId, so a re-pick is needed after the user replaces a document.
-- Not available in the builder preview or the dev harness — `pick()` resolves `{ canceled: true }` there. Test the flow in the published plugin with your own documents.
+- `getDownloadUrl` is for DISPLAY (`<img src>`); your iframe cannot fetch the URL (CSP). To process binary content (parse a PDF, transform an image), use `getBytes(id)` — size-capped at 15 MB (`CONSENTED_DOCUMENT_TOO_LARGE` names the cap; ask the user to open the file manually instead). `getBytes` has a tighter per-minute budget than the rest of the family because it can move megabytes: read sequentially, and surface a rate-limit error rather than retrying in a loop.
+- 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.
+
+### `useFiasAIActions()` — Let the platform's Fias AI assistant operate your plugin
+
+**Permission:** `ai:actions`
+
+The platform assistant (the Fias AI button in the host header) can perform actions inside your plugin — but only ones you declare. Declared actions become the assistant's tools while your plugin is open; a user can say "rotate the selected pages" and the assistant calls your handler.
+
+There are two declaration lanes, one shape:
+
+- **Manifest (static, every plugin):** a `fiasAI: { description, actions: [...] }` block in `fias-plugin.json`. Fixed at publish and reviewed with your submission.
+- **Runtime (this hook, trusted arches only):** declare/extend actions from code. The host silently ignores runtime declarations from non-trusted arches — manifest actions still work there, and this hook still handles their dispatches.
+
+```tsx
+import { useFiasAIActions } from '@fias/arche-sdk';
+
+useFiasAIActions({
+  description: 'Once a document is open, the assistant can rotate its pages.',
+  actions: [
+    {
+      id: 'rotate_pages', // lowercase snake_case — becomes the tool name
+      description: 'Rotate the selected pages 90° clockwise.',
+      parameterSchema: { type: 'object', properties: {} },
+      availableWhen: { documentOpen: true }, // hidden until the state says so
+    },
+  ],
+  state: { documentOpen: doc !== null }, // small, flag-shaped — NOT your data
+  onAction: async (actionId, params) => {
+    if (actionId === 'rotate_pages') {
+      if (!doc) throw new Error('No document is open.'); // ALWAYS re-check
+      await rotateSelected();
+      return;
+    }
+    throw new Error(`Unknown action ${actionId}`);
+  },
+});
+```
+
+Rules that matter:
+
+- **Throw to report failure.** The assistant awaits `onAction` before telling the model the action applied — a batch ("do this to each file") stops on the failing step only if you throw.
+- **Re-check preconditions in `onAction`.** `availableWhen` filtering is presentation; a stale turn can still dispatch a hidden verb.
+- **Keep `state` tiny** (`{documentOpen: true}`, `hasPages: true`) — it is embedded in the assistant's prompt every turn and oversized snapshots are dropped.
+- **UI state only.** Actions manipulate what the user could do in your interface; anything touching server state stays in your own code paths.
+- `requiresConfirmation: true` makes the assistant ask the user before dispatching. It escalates only — nothing can skip a confirmation the platform requires.
+- Manifest actions win id collisions with runtime ones; the merged list is capped at 50.
+- The assistant is not present in the builder preview or the dev harness — declarations are accepted but nothing dispatches until the published plugin runs with the Fias AI window.
 
 ### `useArcheAssets()` — Contributor-published asset library
 
@@ -979,6 +1028,91 @@ await fias.dataStore.listCollections();
 await fias.dataStore.deleteCollection('scores');
 ```
 
+### Panels (dialogs, reward popups, empty states)
+
+A **panel** is a bounded block of declarative content — a title, an ordered list of leaf
+elements, some buttons. The platform ships a shared renderer, `@fias/panel-kit`, from its own
+CDN, so you get the same dialog/reward-popup look as first-party arches without writing modal,
+scrim or focus-trap code.
+
+**Opt in** with a permission and a dependency (the platform serves the module; do NOT install it
+from npm — it isn't there):
+
+```json
+// fias-plugin.json
+{
+  "permissions": ["sandbox:vendored-libraries"],
+  "dependencies": { "@fias/panel-kit": "0.3.0" }
+}
+```
+
+The build **pins the version from the platform registry and rejects a manifest that declares a
+different one**, with the exact string to write. When a new panel-kit ships, bump this on your
+next submission — already-published builds keep resolving the version they were built against.
+
+**Render one.** Inline is just a component; modal goes through the host:
+
+```tsx
+import { Panel, PanelHost, usePanel } from '@fias/panel-kit';
+
+// Inline — in the page's normal flow.
+<Panel definition={definition} context={{ values: { score }, items }} onAction={handleAction} />;
+
+// Modal — mount <PanelHost> once near your app root, then:
+const { showPanel } = usePanel();
+const outcome = await showPanel(definition, { context: { values, items } });
+if (outcome.type === 'emit' && outcome.token === 'restart') restart();
+```
+
+`onAction` / the resolved outcome hands you the parsed intent — the renderer never navigates. A
+button's `action` is a closed namespace: `close`, `emit:<token>` (your own verb, handed back to
+you), `open_arche:arc_<32 hex>`, `open_url:https://…`.
+
+**Elements** are leaf kinds only — no nesting, no layout algebra, no conditionals beyond one
+truthiness check:
+
+| Kind              | What it draws                                                                     |
+| ----------------- | --------------------------------------------------------------------------------- |
+| `text`            | Plain text; `{placeholder}` tokens fill from `context.values`. Never HTML.        |
+| `conditionalText` | The same, only when `context.values[showIf]` is truthy. `showIf` is a value NAME. |
+| `image`           | A platform storage key the host resolves.                                         |
+| `assetImage`      | An arche asset-library id (`as_…`).                                               |
+| `items`           | `context.items` — the list you pass at render time.                               |
+| `slottedItems`    | `context.itemsBySlot[slot]` — several independent lists in one panel.             |
+| `button`          | Label + action.                                                                   |
+| `spacer`          | Vertical whitespace.                                                              |
+
+Both text kinds take `joinNext: true` to share a line with the element after them
+(`Base Reward: [icon] Fabricanse ×1`).
+
+**Theming.** A `theme` sets colours, font, radii, spacing and the quantity format. Pass it to the
+presenter — not to a wrapping element — because the modal portals out of your subtree:
+
+```tsx
+<PanelHost theme={{ bg: '#F6EAD2', accent: '#D8B24A', amountFormat: '×{n}' }} />
+```
+
+Values are grammars, not free CSS: hex or `rgb()/rgba()` colours, `px`/`rem`/`em` lengths, a font
+stack with no parentheses. Anything else is dropped (a `url()` in a custom property would make
+every panel you draw fetch a third-party asset).
+
+**Panels as DATA.** If your panels live in storage rather than in code — a `dataStore` document,
+an admin-edited blob — validate on the WRITE, using the same rules the platform enforces:
+
+```ts
+import { validatePanelCatalog } from '@fias/arche-sdk';
+
+const result = validatePanelCatalog(draft); // { panels: [...], theme?: {...} }
+if (!result.ok) return showErrors(result.issues); // one message per problem, path-prefixed
+await fias.dataStore.put('panels', 'catalog', draft);
+```
+
+That is the whole pattern for server-driven panel content: **your existing storage plus a shared
+validator** — no new permission, no platform call. Changing a panel's wording then means editing
+a document, not shipping a release. `validatePanelDefinition` and `validatePanelTheme` validate
+the parts individually; the types (`PanelDefinition`, `PanelElement`, `PanelTheme`, `PanelCatalog`)
+come from `@fias/arche-sdk` too, so the shape you store is the shape the renderer takes.
+
 ### Advanced exports (rarely needed)
 
 The SDK also exports the following for advanced use cases. Most plugins don't need them.

package/templates/default/CLAUDE.md

@@ -744,6 +744,7 @@ if ('canceled' in picked) {
 const granted = await userDocs.list(); // all granted docs
 const { document, content } = await userDocs.get(id, { includeContent: true }); // text docs
 const { url } = await userDocs.getDownloadUrl(id); // binary docs (images, PDFs)
+const { bytes } = await userDocs.getBytes(id); // raw bytes for PROCESSING binary docs
 ```
 
 **The consent model (what to tell your users):**
@@ -752,7 +753,55 @@ const { url } = await userDocs.getDownloadUrl(id); // binary docs (images, PDFs)
 - After revocation, `get`/`getDownloadUrl` reject with `DOCUMENT_NOT_FOUND` — handle that path gracefully (drop the document from your UI; do not retry in a loop).
 - `proprietary`-sensitivity documents are never grantable (they don't even appear in the picker).
 - Every read is audited by the platform; a new document _version_ is a new documentId, so a re-pick is needed after the user replaces a document.
-- Not available in the builder preview or the dev harness — `pick()` resolves `{ canceled: true }` there. Test the flow in the published plugin with your own documents.
+- `getDownloadUrl` is for DISPLAY (`<img src>`); your iframe cannot fetch the URL (CSP). To process binary content (parse a PDF, transform an image), use `getBytes(id)` — size-capped at 15 MB (`CONSENTED_DOCUMENT_TOO_LARGE` names the cap; ask the user to open the file manually instead). `getBytes` has a tighter per-minute budget than the rest of the family because it can move megabytes: read sequentially, and surface a rate-limit error rather than retrying in a loop.
+- 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.
+
+### `useFiasAIActions()` — Let the platform's Fias AI assistant operate your plugin
+
+**Permission:** `ai:actions`
+
+The platform assistant (the Fias AI button in the host header) can perform actions inside your plugin — but only ones you declare. Declared actions become the assistant's tools while your plugin is open; a user can say "rotate the selected pages" and the assistant calls your handler.
+
+There are two declaration lanes, one shape:
+
+- **Manifest (static, every plugin):** a `fiasAI: { description, actions: [...] }` block in `fias-plugin.json`. Fixed at publish and reviewed with your submission.
+- **Runtime (this hook, trusted arches only):** declare/extend actions from code. The host silently ignores runtime declarations from non-trusted arches — manifest actions still work there, and this hook still handles their dispatches.
+
+```tsx
+import { useFiasAIActions } from '@fias/arche-sdk';
+
+useFiasAIActions({
+  description: 'Once a document is open, the assistant can rotate its pages.',
+  actions: [
+    {
+      id: 'rotate_pages', // lowercase snake_case — becomes the tool name
+      description: 'Rotate the selected pages 90° clockwise.',
+      parameterSchema: { type: 'object', properties: {} },
+      availableWhen: { documentOpen: true }, // hidden until the state says so
+    },
+  ],
+  state: { documentOpen: doc !== null }, // small, flag-shaped — NOT your data
+  onAction: async (actionId, params) => {
+    if (actionId === 'rotate_pages') {
+      if (!doc) throw new Error('No document is open.'); // ALWAYS re-check
+      await rotateSelected();
+      return;
+    }
+    throw new Error(`Unknown action ${actionId}`);
+  },
+});
+```
+
+Rules that matter:
+
+- **Throw to report failure.** The assistant awaits `onAction` before telling the model the action applied — a batch ("do this to each file") stops on the failing step only if you throw.
+- **Re-check preconditions in `onAction`.** `availableWhen` filtering is presentation; a stale turn can still dispatch a hidden verb.
+- **Keep `state` tiny** (`{documentOpen: true}`, `hasPages: true`) — it is embedded in the assistant's prompt every turn and oversized snapshots are dropped.
+- **UI state only.** Actions manipulate what the user could do in your interface; anything touching server state stays in your own code paths.
+- `requiresConfirmation: true` makes the assistant ask the user before dispatching. It escalates only — nothing can skip a confirmation the platform requires.
+- Manifest actions win id collisions with runtime ones; the merged list is capped at 50.
+- The assistant is not present in the builder preview or the dev harness — declarations are accepted but nothing dispatches until the published plugin runs with the Fias AI window.
 
 ### `useArcheAssets()` — Contributor-published asset library
 
@@ -979,6 +1028,91 @@ await fias.dataStore.listCollections();
 await fias.dataStore.deleteCollection('scores');
 ```
 
+### Panels (dialogs, reward popups, empty states)
+
+A **panel** is a bounded block of declarative content — a title, an ordered list of leaf
+elements, some buttons. The platform ships a shared renderer, `@fias/panel-kit`, from its own
+CDN, so you get the same dialog/reward-popup look as first-party arches without writing modal,
+scrim or focus-trap code.
+
+**Opt in** with a permission and a dependency (the platform serves the module; do NOT install it
+from npm — it isn't there):
+
+```json
+// fias-plugin.json
+{
+  "permissions": ["sandbox:vendored-libraries"],
+  "dependencies": { "@fias/panel-kit": "0.3.0" }
+}
+```
+
+The build **pins the version from the platform registry and rejects a manifest that declares a
+different one**, with the exact string to write. When a new panel-kit ships, bump this on your
+next submission — already-published builds keep resolving the version they were built against.
+
+**Render one.** Inline is just a component; modal goes through the host:
+
+```tsx
+import { Panel, PanelHost, usePanel } from '@fias/panel-kit';
+
+// Inline — in the page's normal flow.
+<Panel definition={definition} context={{ values: { score }, items }} onAction={handleAction} />;
+
+// Modal — mount <PanelHost> once near your app root, then:
+const { showPanel } = usePanel();
+const outcome = await showPanel(definition, { context: { values, items } });
+if (outcome.type === 'emit' && outcome.token === 'restart') restart();
+```
+
+`onAction` / the resolved outcome hands you the parsed intent — the renderer never navigates. A
+button's `action` is a closed namespace: `close`, `emit:<token>` (your own verb, handed back to
+you), `open_arche:arc_<32 hex>`, `open_url:https://…`.
+
+**Elements** are leaf kinds only — no nesting, no layout algebra, no conditionals beyond one
+truthiness check:
+
+| Kind              | What it draws                                                                     |
+| ----------------- | --------------------------------------------------------------------------------- |
+| `text`            | Plain text; `{placeholder}` tokens fill from `context.values`. Never HTML.        |
+| `conditionalText` | The same, only when `context.values[showIf]` is truthy. `showIf` is a value NAME. |
+| `image`           | A platform storage key the host resolves.                                         |
+| `assetImage`      | An arche asset-library id (`as_…`).                                               |
+| `items`           | `context.items` — the list you pass at render time.                               |
+| `slottedItems`    | `context.itemsBySlot[slot]` — several independent lists in one panel.             |
+| `button`          | Label + action.                                                                   |
+| `spacer`          | Vertical whitespace.                                                              |
+
+Both text kinds take `joinNext: true` to share a line with the element after them
+(`Base Reward: [icon] Fabricanse ×1`).
+
+**Theming.** A `theme` sets colours, font, radii, spacing and the quantity format. Pass it to the
+presenter — not to a wrapping element — because the modal portals out of your subtree:
+
+```tsx
+<PanelHost theme={{ bg: '#F6EAD2', accent: '#D8B24A', amountFormat: '×{n}' }} />
+```
+
+Values are grammars, not free CSS: hex or `rgb()/rgba()` colours, `px`/`rem`/`em` lengths, a font
+stack with no parentheses. Anything else is dropped (a `url()` in a custom property would make
+every panel you draw fetch a third-party asset).
+
+**Panels as DATA.** If your panels live in storage rather than in code — a `dataStore` document,
+an admin-edited blob — validate on the WRITE, using the same rules the platform enforces:
+
+```ts
+import { validatePanelCatalog } from '@fias/arche-sdk';
+
+const result = validatePanelCatalog(draft); // { panels: [...], theme?: {...} }
+if (!result.ok) return showErrors(result.issues); // one message per problem, path-prefixed
+await fias.dataStore.put('panels', 'catalog', draft);
+```
+
+That is the whole pattern for server-driven panel content: **your existing storage plus a shared
+validator** — no new permission, no platform call. Changing a panel's wording then means editing
+a document, not shipping a release. `validatePanelDefinition` and `validatePanelTheme` validate
+the parts individually; the types (`PanelDefinition`, `PanelElement`, `PanelTheme`, `PanelCatalog`)
+come from `@fias/arche-sdk` too, so the shape you store is the shape the renderer takes.
+
 ### Advanced exports (rarely needed)
 
 The SDK also exports the following for advanced use cases. Most plugins don't need them.