@fias/arche-sdk 2.20.0 → 2.21.0

package/templates/default/CLAUDE.md

@@ -1,4 +1,4 @@
-<!-- fias-sdk-guide-version: 2.20.0 -->
+<!-- fias-sdk-guide-version: 2.21.0 -->
 
 # FIAS Plugin Development Guide
 
@@ -12,9 +12,34 @@ package.json              # Dependencies and scripts
 src/
   index.tsx               # Entry point — must render into #root with <FiasProvider> wrapper
   App.tsx                 # Main component
+public/                   # Optional — static images, fonts, sounds referenced as '/name.png'
+content/                  # Optional — a content pack read with useFiasContent() (lessons, data, media)
 vite.config.ts            # Vite dev server config (port 3100)
 ```
 
+## Where does each kind of data go?
+
+Decide by who writes the data and when, before you write the code: moving data to a different home after you publish means a migration.
+
+| What it is                                                                                                                | Where it goes                                             | What you get                                                                                                                                                        |
+| ------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Your code and small constants (config, a short word list)                                                                 | The bundle (`src/`)                                       | One file, max 5 MB uncompressed. Every user downloads all of it each time the plugin opens.                                                                         |
+| A few static images, fonts or sounds your UI names directly                                                               | `public/`, referenced as literal `'/name.png'` strings    | Served from a CDN. Binary only (png, jpg, webp, gif, woff, woff2, ogg), top-level files only, 4 MB each, 600 files and 120 MB in total.                             |
+| Content you write and ship with each version: lessons, articles, levels, reference data, large image or audio sets, fonts | A content pack: `content/` + `useFiasContent()`           | Not bundled, so users download only what they open. Reviewed on every publish and read-only at runtime. You pay its storage and bandwidth; reads are free to users. |
+| Images you want to change without republishing code (logos, maps, photos with alt text)                                   | The asset library: `useArcheAssets()` + `fias-dev assets` | Managed from the CLI and refreshed without a code publish.                                                                                                          |
+| Records your app writes while it runs: progress, things users create, shared catalogues, leaderboards                     | `useFiasDataStore()` collections                          | Queryable, `user` or `shared` scope, write policies, optional semantic search.                                                                                      |
+| Files only your app uses, for one user: drafts, caches, working data                                                      | `useFiasStorage()`                                        | Free-form paths, private to the plugin and the user. Not shown in their Vault.                                                                                      |
+| A small piece of UI state that should survive a reload (a setting, the last tab)                                          | `usePersistentState()`                                    | Debounced writes to `useFiasStorage()`.                                                                                                                             |
+| Images one user shares with the app's other users                                                                         | `useCommunityAssets()`                                    | Moderated before anyone else sees them.                                                                                                                             |
+| Documents the user should keep: files your app makes for them, or files they already have                                 | `useVaultDocuments()` / `useVaultUserDocuments()`         | In the user's My Data, where they outlive your plugin. Reading files they already had needs their consent.                                                          |
+
+**Common mistakes:**
+
+- **Inlining content in `src/`** — a JSON file of lessons, a level pack, base64 images. It counts against the 5 MB cap, and every user downloads all of it to use a little. Put it in `content/`.
+- **Seeding content you wrote into the DataStore from the plugin.** Every user's session tries to write it, the first writer of a `shared` document owns it, and nothing reviews it. Ship it in `content/`. If it must also be searchable, keep a searchable copy in a `shared` collection, but display the pack's version.
+- **Using the DataStore or `useFiasStorage()` for data that is the same for every user.** That is content.
+- **Building `public/` paths at runtime**, e.g. `` `/music-${name}.ogg` ``. Only literal paths are rewritten to the CDN when you publish, so a path built in code 404s in production. Use a lookup table of literal strings, or move the files to `content/` and read them by name.
+
 ## SDK API Reference
 
 All hooks require the app to be wrapped in `<FiasProvider>`:
@@ -479,6 +504,25 @@ generate({
 
 Mode values: `'text-to-image'` (baseline), `'image-to-image'` (requires `referenceImage`), `'vector'` (SVG output). Style values: `'illustration'` (stylized / digital-art) or `'photoreal'`.
 
+**Several reference images, and output resolution.** A model whose `maxReferenceImages` (from `useImageEntities`) is more than one takes them together in `referenceImages` — Nano Banana 2 (`ent_modeldef_nano_banana_2`) takes up to 14. There is no role per image: the model reads them in order, so the prompt says which is which. `resolution` picks one of the model's `supportedResolutions`; higher costs more (`creditsPerImageByResolution`):
+
+```tsx
+generate({
+  entityId: 'ent_modeldef_nano_banana_2',
+  prompt:
+    'The knight from the first image, standing on a cliff at dawn, painted in the style of the second and third images',
+  referenceImages: [
+    { fileId: knight.fileId },
+    { fileId: styleA.fileId },
+    { fileId: styleB.fileId },
+  ],
+  size: '21:9',
+  resolution: '2K', // '512px' | '1K' (default) | '2K' | '4K'
+});
+```
+
+Use `referenceImage` for one picture and `referenceImages` for several — not both. More than the model takes returns `TOO_MANY_REFERENCE_IMAGES`; a resolution it does not list returns `INVALID_RESOLUTION`. Prefer `fileId` / `archeAssetId` over `dataUrl` when sending several: each `dataUrl` counts against the bridge message size. The result's `costCents` is what the call actually cost, markup included.
+
 Use `npx fias-dev entities --detail <entityId>` to check supported sizes, qualities, and styles for each model.
 
 #### Full example
@@ -545,14 +589,15 @@ const { entities, isLoading } = useImageEntities({
   supportsReferenceImage: true,
 });
 // entities[i]: { entityId, displayName, provider, modes, supportedSizes,
-//                supportsReferenceImage, isPlatformRecommended,
-//                creditsPerImage, estimatedDurationMs, company, strengths,
-//                providerParams, ... }
+//                supportsReferenceImage, maxReferenceImages,
+//                supportedResolutions, defaultResolution, isPlatformRecommended,
+//                creditsPerImage, creditsPerImageByResolution,
+//                estimatedDurationMs, company, strengths, providerParams, ... }
 ```
 
 Each entry is scrubbed — only fields a UI legitimately needs (no provider model strings, no endpoints, no execution config).
 
-`creditsPerImage` is what one image costs the user in credits, markup already included — it matches what the ledger deducts, so it is the figure to show. `estimatedDurationMs` sizes a progress indicator; `company` and `strengths` are model-info copy. All optional: absent means the model has nothing to declare, not that the data is missing.
+`creditsPerImage` is what one image costs the user in credits, markup already included — it matches what the ledger deducts, so it is the figure to show. For a model priced by resolution it is the price at `defaultResolution`, and `creditsPerImageByResolution` has each resolution's; Nano Banana 2 also bills reference images and thinking as tokens on top (a fraction of a credit to a few credits). `estimatedDurationMs` sizes a progress indicator; `company` and `strengths` are model-info copy. All optional: absent means the model has nothing to declare, not that the data is missing.
 
 **Tunable engine parameters.** `providerParams` describes what a model exposes for tuning — enough to render a settings panel without hardcoding a thing:
 
@@ -564,6 +609,8 @@ const seed = entity.providerParams?.find((p) => p.key === 'seed');
 await generate({ entityId, prompt, providerParams: { seed: 42 } });
 ```
 
+Nano Banana 2 exposes `seed`, `temperature` (0–2) and `thinking_level` (`'minimal'` default, or `'high'` — the model plans the picture first: better at layouts and directions like "seen from above", slower, and its thinking tokens are billed).
+
 **The `category` trap.** A param carrying `category: 'quality'` or `'style'` does NOT belong in `providerParams` — send it on the matching top-level field. Providers read those two from the top level only, and an unrecognized `providerParams` key is dropped without an error, so the image generates at the model's default **and you are billed for it anyway**:
 
 ```tsx
@@ -877,7 +924,10 @@ const saved = await userDocs.saveContent({
 
 ### Sending a document for signature — Document Sign handoff
 
-**Permission:** `navigation:open_arche`.
+**Permission:** `navigation:open_arche` to hand the document over. Reading the
+envelope's status afterwards is a separate act (`docsign:envelopes:read`) —
+your app only ever sees envelopes it started this way, and never their
+document bytes.
 
 Hand one of the user's Vault PDFs to Document Sign with recipients pre-filled.
 They place the signature fields and press Send there — a handoff never sends
@@ -921,7 +971,9 @@ created, which is why the outcome is there.
 **Treat the result as a pointer, never as a record.** It tells you which
 envelope to look at; it is not evidence of what happened to it. Match it to an
 outstanding request by `requestId`, consume it once, and never re-point an
-existing association because a `correlationId` matched.
+existing association because a `correlationId` matched. Anything you would act
+on — who signed, what is outstanding — comes from reading the envelope under
+`docsign:envelopes:read`, not from the payload.
 
 **A handoff ENDS YOUR APP'S PROCESS. Anything you will need afterwards has to
 be written down before you call `openArche`.** The host navigates away and
@@ -950,6 +1002,65 @@ local dev. Judging on arrival therefore rejects every genuine reply, not an
 occasional one. Hold the result until you know what was outstanding, then
 evaluate it.
 
+### `useDocumentSign()` — Follow an envelope you handed over
+
+**Permission:** `docsign:envelopes:read`
+
+The other half of the handoff above. Once the user has pressed Send in
+Document Sign, this is how your app learns what happened — status, who the
+recipients are, where each of them has got to, and the audit timeline.
+
+```tsx
+import { useDocumentSign } from '@fias/arche-sdk';
+
+const sign = useDocumentSign();
+
+const envelope = await sign.getEnvelope(approval.envelopeId);
+if (envelope.status === 'completed') markApproved(approval.id);
+
+// The audit timeline, oldest first.
+const { events } = await sign.listEvents(approval.envelopeId);
+```
+
+**The contract:**
+
+- **Only envelopes YOUR app started**, via a `sign_document` handoff. Not one
+  the user created in Document Sign directly, not another app's. Two
+  independent gates, both the user's: they grant access by pressing Send on an
+  envelope you handed over (named to them on the send screen, revocable in
+  Vault → App Access), and the platform separately requires the envelope to
+  record your app as its origin. Either one missing means no read.
+- **This is where truth comes from.** The `sign_document_result` handoff is a
+  pointer; it rides navigation state, which is forgeable. Write "signed" into
+  an approval record only on the strength of a read.
+- **No list verb.** Keep the `envelopeId` on your own record and read by id —
+  the same reason the result has to be matched to an outstanding `requestId`
+  and consumed once.
+- **Drafts are not readable.** Send is the moment the user grants access, so a
+  `saved_draft` result gives you an id to keep, and `getEnvelope` on it rejects
+  until the envelope is actually sent. Do not poll a draft.
+- **One error for every refusal.** `ENVELOPE_NOT_FOUND_OR_NOT_GRANTED` covers
+  an unknown id, an envelope you did not start, one on a workspace this user
+  cannot act for, a draft, and one whose access the user has removed. Deliberately
+  indistinguishable — a specific "it exists but you cannot see it" would let
+  anyone probe for envelope ids. Treat it as "we can no longer follow this",
+  not as a bug, and stop asking.
+- **You never see the document.** No bytes, no download URL — and no recipient
+  email addresses either. Name, role, status and timestamps only. If your app
+  supplied the recipients, it already has their addresses.
+- **The timeline is a projection, not the stored rows.** `type`, `actorKind`,
+  `recipientId`, `createdAt`. Signers' IP addresses and user agents, the event
+  payloads, and the hash-chain columns stay on the platform — they belong to
+  the signing certificate, not to your app.
+- **There are no webhooks.** Nothing calls you when a recipient signs. Read
+  when your UI needs to know — on mount, on a refresh the user asked for — not
+  on a timer.
+- Terminal envelopes (`voided`, `expired`, `declined`) stay readable. A
+  terminal outcome is part of the trail you came for; your UI should render it
+  rather than leaving the record stuck on "in progress".
+- Not available in the builder preview: a preview tenant has no arche row, so
+  it can never be an envelope's origin.
+
 ### `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`).
@@ -1514,6 +1625,7 @@ When you hit a constraint, say so AND tell the user: file an Entity request on t
 ### Size and File Limits
 
 - **Bundle size:** Max 5 MB, measured **uncompressed** — the raw bytes of the final single HTML file with your JS and CSS inlined. Files in `public/` don't count toward it (they have their own caps: 4 MB per file, 120 MB and 600 files total)
+- **Content packs:** files in `content/` don't count toward the bundle either. If content (lessons, data, media) is what is pushing you toward the cap, move it there — see "Where does each kind of data go?" above. A pack holds up to 10,000 files and 500 MB (20 MB of text, 2,000 images)
 - **Dependencies:** Max 20, exact semver versions only (e.g., `"4.4.7"`, not `"^4.4.7"`)
 - Platform packages (`react`, `react-dom`, `@fias/arche-sdk`) are provided — do not include in `dependencies`
 
@@ -1523,6 +1635,7 @@ When you hit a constraint, say so AND tell the user: file an Entity request on t
 - `storage_write`: 120/minute
 - `storage_read`: 300/minute
 - `storage_list`, `storage_delete`: 60/minute
+- Content reads (`useFiasContent()`): 120/minute — read related files together with `getMany` (up to 100 per call)
 
 A separate **runaway-loop detector** fires if any method is called >50 times in 5 s and blocks that method for 10 s. Errors include the target, e.g. `Runaway loop detected: "storage_write" (path: __state/gameState) …` — the path tells you where to debounce at the source.
 
@@ -1612,6 +1725,8 @@ npm run submit
 # Builds, validates, packages, uploads, submits for AI review
 ```
 
+If the plugin has a `content/` folder, submit uploads it too — only the files that changed — and the review reads the whole pack on every publish. `npx fias-dev content check` validates it without submitting.
+
 The first time you list a plugin in the marketplace there is a one-time
 listing fee; subsequent submissions of the same plugin only pay a small
 per-review fee. The harness fetches the exact amount from the server and