@fias/create-fias-plugin 1.4.2 → 1.5.0

package/package.json

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

package/templates/default/AGENTS.md

@@ -179,7 +179,9 @@ import { useFiasDataStore } from '@fias/arche-sdk';
 function MyComponent() {
   const dataStore = useFiasDataStore();
 
-  // Collection management
+  // Collection management. PREFER declaring collections in fias-plugin.json
+  // (see "Declaring your collections" below) — createCollection is capped at
+  // 10/minute, so scaffolding several at startup can silently lose the tail.
   await dataStore.createCollection('scores', { userScope: 'user' }); // or 'shared'
   const collections = await dataStore.listCollections();
   await dataStore.deleteCollection('scores');
@@ -236,6 +238,24 @@ await dataStore.batch([
 ]);
 ```
 
+### Declaring your collections (preferred)
+
+List the collections your plugin needs in `fias-plugin.json` and the platform creates them once at publish, before your plugin ever runs:
+
+```jsonc
+"collections": [
+  { "name": "scores", "scope": "user" },
+  { "name": "ledger", "scope": "workspace", "readMinRole": "member" },
+  { "name": "recipes", "scope": "shared", "writePolicy": "author", "searchable": { "field": "text" } }
+]
+```
+
+`scope` is `user` | `shared` | `workspace`. `readMinRole` / `writeMinRole` are workspace-only; `writePolicy` is shared-only; `searchable` names the text field to embed. Same options as `createCollection`, checked by `fias-dev validate` before you publish.
+
+Why this and not `createCollection` at startup: the runtime op is capped at **10 per minute** while an arche may hold **50** collections, so a plugin creating several on mount can exceed the cap and lose the rest **with no error** — surfacing later as `COLLECTION_NOT_FOUND` on an unrelated call. Declaring has no such window, and a mistake fails your publish instead of a user's session.
+
+Re-publishing is safe: existing collections are left alone, a stricter role floor is applied, a looser one is refused, and a collection you stop declaring is kept (never deleted — it may hold user data). Keep using `createCollection` for collections whose names you only know at runtime.
+
 **Rate limits (per minute):** `put` 120, `get` 300, `query` 60, `delete` 60, `batch` 30, `createCollection` 10
 
 **Error handling:** Data store calls can reject on infrastructure errors or limit violations. Always use `try/catch`. Common error codes: `COLLECTION_NOT_FOUND`, `DOCUMENT_TOO_LARGE`, `STORAGE_LIMIT_REACHED`, `RATE_LIMIT`.
@@ -528,22 +548,6 @@ const { entities, isLoading } = useImageEntities({
 
 Each entry is scrubbed — only fields a UI legitimately needs (no provider model strings, no endpoints, no execution config).
 
-### `useBackgroundRemoval()` — Client-side background removal
-
-**Permission:** `entities:image_remove_background`
-**Returns:** `BackgroundRemovalApi`
-
-Runs the imgly WASM model inside the host page — bytes never leave the user's device. Returns a transparent PNG.
-
-```tsx
-import { useBackgroundRemoval } from '@fias/arche-sdk';
-
-const { removeBackground, isLoading } = useBackgroundRemoval();
-const transparentPng = await removeBackground(jpegBlob);
-```
-
-**Limits:** input ≤ 25 MiB, PNG/JPEG only, rate-limited to 10/min per arche per user. Throws on size violation rather than returning a result.
-
 ### Image-editing capability hooks (auto-generated)
 
 **Permission:** `entities:image_edit`
@@ -750,6 +754,52 @@ const { url } = await userDocs.getDownloadUrl(id); // binary docs (images, PDFs)
 - 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.
 
+### `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
 
 **Permission:** `assets:read`
@@ -772,6 +822,40 @@ const fresh = await getUrl(assetId);
 
 Cache the `assetId`; refresh `signedUrl` via `getUrl()` rather than persisting URLs across sessions.
 
+### `useCommunityAssets()` — User-published images, visible to this arche's users
+
+**Permissions:** `assets:community:read` (browse/view) · `assets:community:publish` (publish/unpublish/listMine)
+**Returns:** `CommunityAssetsApi`
+
+The only way one user's content reaches another user. A user publishes an image **they created here**, and after moderation every authenticated user of **this arche** (and no other) can see it. Free to publish.
+
+```tsx
+import { useCommunityAssets, useImageGeneration } from '@fias/arche-sdk';
+
+const { publish, publishMany, listCommunity, listMine, getUrls, unpublish } = useCommunityAssets();
+const { generate } = useImageGeneration();
+
+// 1. The user makes something, then shares it
+const image = await generate({ prompt: 'a sleepy blue whale' });
+const asset = await publish({ fileId: image.fileId, title: 'Sleepy whale', tags: ['page-art'] });
+// asset.status === 'pending_moderation'  ← NOT visible to others yet
+
+// 2. Browse what the community published
+const { assets, nextCursor } = await listCommunity({ limit: 30, tag: 'page-art' });
+
+// 3. Sign a whole gallery in ONE call (URLs last ~5 min; the hook refreshes them)
+const urls = await getUrls(assets.map((a) => a.assetId));
+// urls[i]: { assetId, url, expiresAt }  → drop straight into <img src={url} />
+```
+
+Three things to design around:
+
+1. **Publishing is not instant.** `publish()` returns `status: 'pending_moderation'`. It shows up in `listCommunity()` only once approved — so show the author their own pending item via `listMine()` instead of optimistically adding it to the community feed.
+2. **Batch your URLs.** Use `getUrls()` for a gallery or a multi-page book. Thirteen separate `getUrl()` calls against a ~5-minute TTL is the shape this exists to avoid. Ids that were taken down or aren't published yet are simply omitted — render around the gap.
+3. **Structure goes in the Data Store.** Which asset belongs on which page/level lives in a `shared`-scope Data Store collection holding `assetId`s. Community Assets stores the bytes and nothing queryable — `tags` plus cursor paging is the whole query surface, deliberately.
+
+Only images the user made or uploaded in **their own** Fias files can be published (pass the `fileId` from a `useImageGeneration()` result). PNG/JPEG/WebP only; every image is re-encoded to a canonical PNG with metadata stripped. Publishers can `unpublish()` their own assets, and any user can `report()` one for review.
+
 ### `useFiasStore()` — In-app purchases (IAP)
 
 **Permission:** `store:purchase`
@@ -941,6 +1025,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.
@@ -1002,7 +1171,7 @@ The SDK also exports the following for advanced use cases. Most plugins don't ne
 
 Other optional sub-fields: `currency: "usd"` (only USD supported today), `platformFeePercent` (override the default platform cut — non-standard).
 
-**Permissions:** `theme:read`, `user:profile:read`, `storage:sandbox`, `data:store`, `data:search`, `entities:invoke`, `entities:client_invoke`, `entities:image_generate`, `entities:image_edit`, `entities:image_remove_background`, `entities:audio_generate`, `entities:web_search`, `store:purchase`, `vault:documents:read`, `vault:documents:write`, `assets:read`, `navigation:open_arche`, `sandbox:vendored-libraries`
+**Permissions:** `theme:read`, `user:profile:read`, `storage:sandbox`, `data:store`, `data:search`, `entities:invoke`, `entities:client_invoke`, `entities:image_generate`, `entities:image_edit`, `entities:audio_generate`, `entities:web_search`, `store:purchase`, `vault:documents:read`, `vault:documents:write`, `assets:read`, `navigation:open_arche`, `sandbox:vendored-libraries`
 
 **Using AI:** Add `"entities:invoke"` to permissions, then use `useEntityInvocation()` with a model entity ID and your own `systemPrompt`. Browse available models with `npx fias-dev entities`.
 
@@ -1053,6 +1222,7 @@ When you hit a constraint, say so AND tell the user: file an Entity request on t
 ### Sandboxing
 
 - Plugins run in an iframe with `sandbox="allow-scripts allow-forms allow-downloads allow-popups allow-popups-to-escape-sandbox"` (note: **no** `allow-same-origin` — the plugin has an opaque origin)
+- **`window.alert()` / `confirm()` / `prompt()` do nothing** (no `allow-modals`): they don't throw — `confirm()` silently returns `false`, so gated actions never run. Build confirmation into your UI (a two-step button or an inline dialog) instead
 - **No `fetch()` or `XMLHttpRequest`** — all network access is blocked
 - **You _can_ open external links in a new tab** (e.g. `window.open('https://…', '_blank')`) — see "Opening external links" above
 - **No access** to parent DOM, cookies, or localStorage

package/templates/default/CLAUDE.md

@@ -179,7 +179,9 @@ import { useFiasDataStore } from '@fias/arche-sdk';
 function MyComponent() {
   const dataStore = useFiasDataStore();
 
-  // Collection management
+  // Collection management. PREFER declaring collections in fias-plugin.json
+  // (see "Declaring your collections" below) — createCollection is capped at
+  // 10/minute, so scaffolding several at startup can silently lose the tail.
   await dataStore.createCollection('scores', { userScope: 'user' }); // or 'shared'
   const collections = await dataStore.listCollections();
   await dataStore.deleteCollection('scores');
@@ -236,6 +238,24 @@ await dataStore.batch([
 ]);
 ```
 
+### Declaring your collections (preferred)
+
+List the collections your plugin needs in `fias-plugin.json` and the platform creates them once at publish, before your plugin ever runs:
+
+```jsonc
+"collections": [
+  { "name": "scores", "scope": "user" },
+  { "name": "ledger", "scope": "workspace", "readMinRole": "member" },
+  { "name": "recipes", "scope": "shared", "writePolicy": "author", "searchable": { "field": "text" } }
+]
+```
+
+`scope` is `user` | `shared` | `workspace`. `readMinRole` / `writeMinRole` are workspace-only; `writePolicy` is shared-only; `searchable` names the text field to embed. Same options as `createCollection`, checked by `fias-dev validate` before you publish.
+
+Why this and not `createCollection` at startup: the runtime op is capped at **10 per minute** while an arche may hold **50** collections, so a plugin creating several on mount can exceed the cap and lose the rest **with no error** — surfacing later as `COLLECTION_NOT_FOUND` on an unrelated call. Declaring has no such window, and a mistake fails your publish instead of a user's session.
+
+Re-publishing is safe: existing collections are left alone, a stricter role floor is applied, a looser one is refused, and a collection you stop declaring is kept (never deleted — it may hold user data). Keep using `createCollection` for collections whose names you only know at runtime.
+
 **Rate limits (per minute):** `put` 120, `get` 300, `query` 60, `delete` 60, `batch` 30, `createCollection` 10
 
 **Error handling:** Data store calls can reject on infrastructure errors or limit violations. Always use `try/catch`. Common error codes: `COLLECTION_NOT_FOUND`, `DOCUMENT_TOO_LARGE`, `STORAGE_LIMIT_REACHED`, `RATE_LIMIT`.
@@ -528,22 +548,6 @@ const { entities, isLoading } = useImageEntities({
 
 Each entry is scrubbed — only fields a UI legitimately needs (no provider model strings, no endpoints, no execution config).
 
-### `useBackgroundRemoval()` — Client-side background removal
-
-**Permission:** `entities:image_remove_background`
-**Returns:** `BackgroundRemovalApi`
-
-Runs the imgly WASM model inside the host page — bytes never leave the user's device. Returns a transparent PNG.
-
-```tsx
-import { useBackgroundRemoval } from '@fias/arche-sdk';
-
-const { removeBackground, isLoading } = useBackgroundRemoval();
-const transparentPng = await removeBackground(jpegBlob);
-```
-
-**Limits:** input ≤ 25 MiB, PNG/JPEG only, rate-limited to 10/min per arche per user. Throws on size violation rather than returning a result.
-
 ### Image-editing capability hooks (auto-generated)
 
 **Permission:** `entities:image_edit`
@@ -750,6 +754,52 @@ const { url } = await userDocs.getDownloadUrl(id); // binary docs (images, PDFs)
 - 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.
 
+### `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
 
 **Permission:** `assets:read`
@@ -772,6 +822,40 @@ const fresh = await getUrl(assetId);
 
 Cache the `assetId`; refresh `signedUrl` via `getUrl()` rather than persisting URLs across sessions.
 
+### `useCommunityAssets()` — User-published images, visible to this arche's users
+
+**Permissions:** `assets:community:read` (browse/view) · `assets:community:publish` (publish/unpublish/listMine)
+**Returns:** `CommunityAssetsApi`
+
+The only way one user's content reaches another user. A user publishes an image **they created here**, and after moderation every authenticated user of **this arche** (and no other) can see it. Free to publish.
+
+```tsx
+import { useCommunityAssets, useImageGeneration } from '@fias/arche-sdk';
+
+const { publish, publishMany, listCommunity, listMine, getUrls, unpublish } = useCommunityAssets();
+const { generate } = useImageGeneration();
+
+// 1. The user makes something, then shares it
+const image = await generate({ prompt: 'a sleepy blue whale' });
+const asset = await publish({ fileId: image.fileId, title: 'Sleepy whale', tags: ['page-art'] });
+// asset.status === 'pending_moderation'  ← NOT visible to others yet
+
+// 2. Browse what the community published
+const { assets, nextCursor } = await listCommunity({ limit: 30, tag: 'page-art' });
+
+// 3. Sign a whole gallery in ONE call (URLs last ~5 min; the hook refreshes them)
+const urls = await getUrls(assets.map((a) => a.assetId));
+// urls[i]: { assetId, url, expiresAt }  → drop straight into <img src={url} />
+```
+
+Three things to design around:
+
+1. **Publishing is not instant.** `publish()` returns `status: 'pending_moderation'`. It shows up in `listCommunity()` only once approved — so show the author their own pending item via `listMine()` instead of optimistically adding it to the community feed.
+2. **Batch your URLs.** Use `getUrls()` for a gallery or a multi-page book. Thirteen separate `getUrl()` calls against a ~5-minute TTL is the shape this exists to avoid. Ids that were taken down or aren't published yet are simply omitted — render around the gap.
+3. **Structure goes in the Data Store.** Which asset belongs on which page/level lives in a `shared`-scope Data Store collection holding `assetId`s. Community Assets stores the bytes and nothing queryable — `tags` plus cursor paging is the whole query surface, deliberately.
+
+Only images the user made or uploaded in **their own** Fias files can be published (pass the `fileId` from a `useImageGeneration()` result). PNG/JPEG/WebP only; every image is re-encoded to a canonical PNG with metadata stripped. Publishers can `unpublish()` their own assets, and any user can `report()` one for review.
+
 ### `useFiasStore()` — In-app purchases (IAP)
 
 **Permission:** `store:purchase`
@@ -941,6 +1025,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.
@@ -1002,7 +1171,7 @@ The SDK also exports the following for advanced use cases. Most plugins don't ne
 
 Other optional sub-fields: `currency: "usd"` (only USD supported today), `platformFeePercent` (override the default platform cut — non-standard).
 
-**Permissions:** `theme:read`, `user:profile:read`, `storage:sandbox`, `data:store`, `data:search`, `entities:invoke`, `entities:client_invoke`, `entities:image_generate`, `entities:image_edit`, `entities:image_remove_background`, `entities:audio_generate`, `entities:web_search`, `store:purchase`, `vault:documents:read`, `vault:documents:write`, `assets:read`, `navigation:open_arche`, `sandbox:vendored-libraries`
+**Permissions:** `theme:read`, `user:profile:read`, `storage:sandbox`, `data:store`, `data:search`, `entities:invoke`, `entities:client_invoke`, `entities:image_generate`, `entities:image_edit`, `entities:audio_generate`, `entities:web_search`, `store:purchase`, `vault:documents:read`, `vault:documents:write`, `assets:read`, `navigation:open_arche`, `sandbox:vendored-libraries`
 
 **Using AI:** Add `"entities:invoke"` to permissions, then use `useEntityInvocation()` with a model entity ID and your own `systemPrompt`. Browse available models with `npx fias-dev entities`.
 
@@ -1053,6 +1222,7 @@ When you hit a constraint, say so AND tell the user: file an Entity request on t
 ### Sandboxing
 
 - Plugins run in an iframe with `sandbox="allow-scripts allow-forms allow-downloads allow-popups allow-popups-to-escape-sandbox"` (note: **no** `allow-same-origin` — the plugin has an opaque origin)
+- **`window.alert()` / `confirm()` / `prompt()` do nothing** (no `allow-modals`): they don't throw — `confirm()` silently returns `false`, so gated actions never run. Build confirmation into your UI (a two-step button or an inline dialog) instead
 - **No `fetch()` or `XMLHttpRequest`** — all network access is blocked
 - **You _can_ open external links in a new tab** (e.g. `window.open('https://…', '_blank')`) — see "Opening external links" above
 - **No access** to parent DOM, cookies, or localStorage