@fias/arche-sdk 2.33.0 → 2.34.0

package/templates/default/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- fias-sdk-guide-version: 2.33.0 -->
+<!-- fias-sdk-guide-version: 2.34.0 -->
 
 # FIAS Plugin Development Guide
 
@@ -21,19 +21,19 @@ vite.config.ts            # Vite dev server config (port 3100)
 
 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 music tracks 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.                                                                                                                                                                 |
-| Sound effects that must play on cue (hits, jumps, UI clicks)                                                              | The bundle: base64 in `src/`, decoded once at startup with `decodeAudioData` | Ready the moment the plugin opens; nothing to download per session. Keep the set small (a few hundred KB). Not `public/`: a `public/` sound can only play through an `<audio>` element, which lags its cue (badly on iOS). |
-| The same sound effects shared by several arches (optional)                                                                | A workspace asset library: `useArcheAssetBytes().getMany()`                  | One copy for every linked arche; a new version reaches them with a pin refresh, no code republish. Downloaded each session — wait for it before the first cue. MP3 or WAV, ≤ 1 MB and 30 s each.                           |
-| 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.                                                                                                                 |
+| 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 music tracks 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, 3D models | 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.                                                                                                                                                                 |
+| Sound effects that must play on cue (hits, jumps, UI clicks)                                                                         | The bundle: base64 in `src/`, decoded once at startup with `decodeAudioData` | Ready the moment the plugin opens; nothing to download per session. Keep the set small (a few hundred KB). Not `public/`: a `public/` sound can only play through an `<audio>` element, which lags its cue (badly on iOS). |
+| The same sound effects shared by several arches (optional)                                                                           | A workspace asset library: `useArcheAssetBytes().getMany()`                  | One copy for every linked arche; a new version reaches them with a pin refresh, no code republish. Downloaded each session — wait for it before the first cue. MP3 or WAV, ≤ 1 MB and 30 s each.                           |
+| 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:**
 
@@ -1615,7 +1615,7 @@ for (const sound of entries) {
 **Permission:** `entities:client_invoke`
 **Returns:** `FiasContentApi`
 
-Ship large or numerous files — lessons, articles, data, images, audio, fonts — in a `content/` directory beside `src/`. They are not bundled: `fias-dev submit` uploads them separately (only the files that changed), the review reads every one, and the published plugin reads them at runtime through this hook. The host page fetches, verifies and caches them; your plugin never touches the network.
+Ship large or numerous files — lessons, articles, data, images, audio, fonts, 3D models — in a `content/` directory beside `src/`. They are not bundled: `fias-dev submit` uploads them separately (only the files that changed), the review reads every one, and the published plugin reads them at runtime through this hook. The host page fetches, verifies and caches them; your plugin never touches the network.
 
 ```tsx
 import { useFiasContent, FiasContentError } from '@fias/arche-sdk';
@@ -1630,7 +1630,7 @@ const cover = await content.getObjectUrl('img/cover.webp'); // blob: URL for <im
 const { url } = await content.getUrl('audio/theme.ogg'); // signed URL, for long streaming audio
 ```
 
-- Paths are relative to `content/`. Formats: `.md`, `.txt`, `.json` (text, ≤ 5 MB each); `.png`, `.jpg`, `.jpeg`, `.webp`, `.gif`, `.avif` (static, single-frame images, ≤ 20 MB and 50 megapixels); `.ogg` (audio, ≤ 50 MB); `.woff2` (fonts, ≤ 5 MB). A pack holds at most 10,000 files, 2,000 images, 20 MB of text and 500 MB in total. Run `npx fias-dev content check` to validate without submitting.
+- Paths are relative to `content/`. Formats: `.md`, `.txt`, `.json` (text, ≤ 5 MB each); `.png`, `.jpg`, `.jpeg`, `.webp`, `.gif`, `.avif` (static, single-frame images, ≤ 20 MB and 50 megapixels); `.ogg` (audio, ≤ 50 MB); `.woff2` (fonts, ≤ 5 MB); `.glb` (3D models, ≤ 25 MB, read with `getBytes` — see "VR and AR apps (WebXR)" for what a model may hold). A pack holds at most 10,000 files, 2,000 images (counting the textures inside models), 20 MB of text and 500 MB in total. Run `npx fias-dev content check` to validate without submitting.
 - Prefer `getObjectUrl` for images and fonts: repeat views come from the host cache. `getUrl` is for media that must stream or seek; it bypasses the cache, and a URL held past its `expiresAt` must be requested again.
 - Failures throw `FiasContentError` with a `code`: `CONTENT_NOT_FOUND`, `CONTENT_NOT_TEXT`, `CONTENT_TOO_LARGE`, `CONTENT_UNAVAILABLE`, `CONTENT_THROTTLED`, `CONTENT_UNAVAILABLE_IN_PREVIEW`, `PERMISSION_DENIED`, `RATE_LIMIT`. `getMany` returns the error for a failed path instead of throwing.
 - There is no published pack in the Arche Builder preview, so calls there fail with `CONTENT_UNAVAILABLE_IN_PREVIEW`; the dev harness serves your local `content/` directory.
@@ -1860,7 +1860,9 @@ const result = await web.extract({
 
 Your app reads pages only on **websites Fias approved** (regulated institutions such as credit unions and banks, and government sites) — any page on an approved site, so a redesigned or moved page keeps working. To have a site approved, ask Fias. `listSites()` lists them (free).
 
-`extract()` never returns the page's text — not even a short label. You send a **form** — up to 30 fields of kinds `number` and `integer` (optional `min`/`max`), `boolean`, `date` (`YYYY-MM-DD`), `enum` (your own `values`) and `list` (up to 200 rows of those) — and Fias reads the page into it. There is no free-text kind: describe what you need as numbers, dates, yes/no and choices you list (a product type, not a product name). Every value may be `null` (the page did not say); a value that broke its field's rules comes back `null` and is named in `discarded`. A model reading a page is not deterministic, so **where a wrong number matters (money), pass `reads: 2`**: the page is read twice, independently, and only a value both readings agree on is returned — a field they disagree on is `null` (a list keeps only the rows both produced) and is named in `disagreed`, for a person to confirm. A list named in `disagreed` may be missing rows the page prints: never conclude "absent on the page" (not offered) from a field in `disagreed` — treat it as unknown. Agreement says a value was stable across two readings, not that it is right; always show `site.name` and `fetchedAt` beside a figure so a person can check it. With two readings `discarded` names a list whole (`rates`), not a row. Two readings are two reader charges; the platform may raise the floor for every app, so check `disagreed` whatever you asked for. The reader's model, and so a reading's price, is chosen by the platform. URLs must be `https://`; `redirected: true` means the site moved the page within itself (the new address is not returned). The reader fills the form from whatever layout the page has, but it never runs JavaScript: a page that builds its figures with scripts comes back with `scriptHeavy: true` and mostly nulls — read the site's PDF rate sheet instead.
+`extract()` never returns the page's text — not even a short label. You send a **form** — up to 30 fields of kinds `number` and `integer` (optional `min`/`max`), `boolean`, `date` (`YYYY-MM-DD`), `enum` (your own `values`) and `list` (up to 200 rows of those) — and Fias reads the page into it. There is no free-text kind: describe what you need as numbers, dates, yes/no and choices you list (a heading the page prints is fine as a choice if you listed it; a string the page chose never is). Every value may be `null` (the page did not say); a value that broke its field's rules comes back `null` and is named in `discarded`. A model reading a page is not deterministic, so **where a wrong number matters (money), pass `reads: 2`**: the page is read twice, independently, and only a value both readings agree on is returned — a field they disagree on is `null` (a list keeps only the rows both produced) and is named in `disagreed`, for a person to confirm. A list named in `disagreed` may be missing rows the page prints: never conclude "absent on the page" (not offered) from a field in `disagreed` — treat it as unknown. Agreement says a value was stable across two readings, not that it is right; always show `site.name` and `fetchedAt` beside a figure so a person can check it. With two readings `discarded` names a list whole (`rates`), not a row. After the field names, `disagreed` names each row a list lost by its index in the in-order reading (`rates[3]`): the list you get is that reading with those rows removed. **Give a list a `key`** — the item fields that identify a row on the page (`key: ['product', 'months']`) — and a row both readings produced under one key is kept and agreed cell by cell: a cell they disagree on is `null` in the row and named `rates[3].apy` after the row entries, instead of the whole row being dropped because one cell differed (a row with a `null` key cell, or a key value a reading gave twice, is matched whole; the `3` is the row's index in the in-order reading, not in the list you received). `disagreedEntries(disagreed)` splits the entries into `fields`, `rows` and `cells`, each cell with its `position` in the list you received, and `disagreedFieldNames(disagreed)` gives the names alone; match entries by name or the `name[` prefix, never by equality or count. The reader never sees a key: a single reading Fias holds is paired, not bought again, when you add one; what two readings agreed on is read again. Two readings are two reader charges; the platform may raise the floor for every app, so check `disagreed` whatever you asked for. The reader's model, and so a reading's price, is chosen by the platform. URLs must be `https://`; `redirected: true` means the site moved the page within itself (the new address is not returned). The reader fills the form from whatever layout the page has, but it never runs JavaScript: a page that builds its figures with scripts comes back with `scriptHeavy: true` and mostly nulls — read the site's PDF rate sheet instead.
+
+**Write the form from the page, not from what pages usually look like.** Read the page yourself first (you can; the reader cannot show it to you) and write the form from what that page prints, one per product you read off it (each is its own reading pair). List the page's own words — its table headings, its model-year bands, its term column headers — as `enum` choices on each row (up to 50 values of up to 60 characters) plus a fixed escape such as `(none of these)`, so the reader copies and never classifies; keep a small table in the app that turns each heading into the cells your code reads, and key each list by that cell and the printed term. Ask only for cells the page prints: a cell the page never prints is answered `null` by one reading and guessed by the other, whatever its description says. A page changes: rows under your escape choice, a withheld row whose key cell the readings could not agree on, the list named whole in `discarded` (with two readings it never names a row), an empty list where the page says the product is published, or far fewer rows than last time mean the form must be rewritten — tell the user which page, in plain words. On the Rate Research pilot a generic form that asked the reader to classify had 63 of 117 counted rows withheld and agreed twice on three plain misreadings; forms written from each page lost no rows on the next refresh and matched one institution's pages in 57 of 57 values. `reads: 2` stays on either way: it catches the misread digit, which no form can.
 
 One copy of each page serves every app, and a page is fetched from its site **at most once an hour**. `maxAgeSeconds` (default one day, 3600–30 days) is the oldest copy you accept. A fresh fetch (about a tenth of a cent) and each reading (a fast model's tokens — well under a cent for a typical page; two with `reads: 2`) are charged to the user; a cached result costs nothing (`fromCache: true`). `stale: true` means the site could not be asked again just now and you got the last copy. Always show `site.name` and `fetchedAt` beside the figures. Not available in the builder preview or the test channel. **Error codes:** `WEB_SOURCES_DISABLED`, `INVALID_URL`, `SITE_NOT_APPROVED`, `PAGE_EXCLUDED` (a part of the site where the public posts), `ROBOTS_DISALLOWED`, `FETCH_FAILED`, `RESPONSE_TOO_LARGE`, `CONTENT_TYPE_NOT_ALLOWED`, `EXTRACTION_FAILED`, `SOURCE_BUSY`, `RATE_LIMIT` (surface it, never retry in a loop), `INSUFFICIENT_CREDITS`, `PERMISSION_DENIED`.
 
@@ -2171,6 +2173,110 @@ Notes:
 - Only `http(s)` URLs make sense here; `javascript:`/`data:` URLs are blocked
   by the sandbox.
 
+### VR and AR apps (WebXR)
+
+A plugin can be a VR or AR app: a game, a 3D viewer, a space to walk around.
+On a headset such as a Meta Quest, the person opens your arche in the
+headset's browser and presses your "Enter VR" button. No SDK hook or
+permission is needed: the plugin frame is allowed WebXR, and you use the
+browser's own API or a library. With three.js, add `three` to the manifest's
+`dependencies` (the published arche loads it at runtime) and to `package.json`,
+with `@types/three` in `devDependencies`, all at the same exact version.
+
+**Import from `three` itself, never `three/addons/...`.** The published build
+maps a dependency's bare name but not its subpaths, so `three/addons/...`
+(VRButton, OrbitControls, GLTFLoader) works under `npm run dev` and then fails
+the build with "no importmap entry". An Enter VR button is a few lines:
+
+```tsx
+import * as THREE from 'three';
+
+const renderer = new THREE.WebGLRenderer({ antialias: true });
+renderer.xr.enabled = true;
+renderer.xr.setReferenceSpaceType('local-floor'); // y = 0 is the room's floor
+container.appendChild(renderer.domElement);
+
+// Offer VR only where it exists. On a phone or desktop this resolves false and
+// the same scene stays a normal 3D view.
+const vr = (await navigator.xr?.isSessionSupported('immersive-vr').catch(() => false)) ?? false;
+
+// Call from the button's click handler, and request the session before any
+// other await: the click is what lets the browser start it.
+async function enterVr(xr: XRSystem) {
+  const session = await xr.requestSession('immersive-vr', { optionalFeatures: ['local-floor'] });
+  await renderer.xr.setSession(session);
+}
+
+// Not requestAnimationFrame: in VR the headset drives the frames.
+renderer.setAnimationLoop(() => renderer.render(scene, camera));
+```
+
+When you need an addon, copy its file from `node_modules/three/examples/jsm/`
+into `src/vendor/three/`, with the files it imports by relative path, keeping
+the folders. Its other imports are `three`, which the build maps. Beside it, add
+a one-line `.d.ts` so TypeScript uses `@types/three`'s types, for example
+`src/vendor/three/loaders/GLTFLoader.d.ts` holding
+`export * from 'three/examples/jsm/loaders/GLTFLoader.js';`.
+
+**3D models.** Put each model in your content pack as a `.glb`
+(`content/models/chair.glb`) and read its bytes with `useFiasContent()` (see
+that section; it needs the `entities:client_invoke` permission). Your plugin
+cannot fetch, so `GLTFLoader.load(url)` fails, but `parseAsync` takes the
+bytes. Copy GLTFLoader in as above (`loaders/GLTFLoader.js` plus
+`utils/BufferGeometryUtils.js` and `utils/SkeletonUtils.js`) and swap its
+texture loader: three.js decodes embedded textures with `fetch()`, which the
+sandbox blocks, and the model then loads with NO textures and only a console
+warning says why.
+
+```tsx
+import * as THREE from 'three';
+import { useFiasContent } from '@fias/arche-sdk';
+import { GLTFLoader } from './vendor/three/loaders/GLTFLoader.js';
+
+const content = useFiasContent();
+const loader = new GLTFLoader();
+loader.register((parser) => {
+  parser.textureLoader = new THREE.TextureLoader(parser.options.manager); // loads through <img>
+  return { name: 'fias_no_fetch_textures' };
+});
+const gltf = await loader.parseAsync(await content.getBytes('models/chair.glb'), '');
+scene.add(gltf.scene);
+```
+
+What a model may hold, and why:
+
+- One self-contained binary glTF 2.0 file, at most 25 MB: everything packed
+  inside, with no separate `.bin` or image files. A `.gltf` with side files is
+  refused; Blender's glTF exporter makes the right kind with "glTF Binary (.glb)".
+- At most 64 textures, each a still PNG, JPEG, WebP or AVIF. Every texture is
+  screened like an image file and counts toward the pack's 2,000 images; the
+  names and `extras` in the model are reviewed like text.
+- Export without compression. KTX2 / Basis textures are refused, and Draco or
+  meshopt geometry cannot be decoded in a plugin: their three.js decoders need
+  WebAssembly, which the plugin's sandbox does not run.
+
+A texture you apply in code can be its own image file in the pack: pass the URL
+from `content.getObjectUrl('textures/wall.webp')` to
+`new THREE.TextureLoader().loadAsync(url)`.
+
+Notes:
+
+- Entering VR or AR needs a click, and the browser may ask the person for
+  consent. `immersive-ar` (passthrough on Quest) starts the same way: create
+  the renderer with `alpha: true` and hide your sky so the room shows through.
+- Head and controller positions reveal things about the person, like their
+  height. Use them to draw the scene, not as data you save or send.
+- To test on a headset with `fias-dev`, the page must be a secure context.
+  `localhost` is one and a LAN address (`http://192.168.…`) is not, so connect
+  the headset by USB with developer mode on, run the commands below, and open
+  `http://localhost:3200` in the headset's browser. A published arche needs
+  nothing extra.
+
+```bash
+adb reverse tcp:3100 tcp:3100   # your plugin's dev server
+adb reverse tcp:3200 tcp:3200   # the fias-dev harness
+```
+
 ### `useStepNavigation()` — Multi-step workflows
 
 **Permission:** None for in-memory use; `storage:sandbox` when `persistKey` is set (it reads/writes `__state/<persistKey>` via the storage bridge).
@@ -2461,6 +2567,7 @@ When you hit a constraint, say so AND tell the user: file an Entity request on t
 - **`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
+- **You _can_ build VR and AR apps (WebXR)** for headsets like the Meta Quest — see "VR and AR apps (WebXR)" above
 - **No access** to parent DOM, cookies, or localStorage
 - **No external scripts or stylesheets** — everything must be bundled
 - All platform communication goes through the bridge (SDK hooks)

package/templates/default/CLAUDE.md

@@ -1,4 +1,4 @@
-<!-- fias-sdk-guide-version: 2.33.0 -->
+<!-- fias-sdk-guide-version: 2.34.0 -->
 
 # FIAS Plugin Development Guide
 
@@ -21,19 +21,19 @@ vite.config.ts            # Vite dev server config (port 3100)
 
 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 music tracks 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.                                                                                                                                                                 |
-| Sound effects that must play on cue (hits, jumps, UI clicks)                                                              | The bundle: base64 in `src/`, decoded once at startup with `decodeAudioData` | Ready the moment the plugin opens; nothing to download per session. Keep the set small (a few hundred KB). Not `public/`: a `public/` sound can only play through an `<audio>` element, which lags its cue (badly on iOS). |
-| The same sound effects shared by several arches (optional)                                                                | A workspace asset library: `useArcheAssetBytes().getMany()`                  | One copy for every linked arche; a new version reaches them with a pin refresh, no code republish. Downloaded each session — wait for it before the first cue. MP3 or WAV, ≤ 1 MB and 30 s each.                           |
-| 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.                                                                                                                 |
+| 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 music tracks 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, 3D models | 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.                                                                                                                                                                 |
+| Sound effects that must play on cue (hits, jumps, UI clicks)                                                                         | The bundle: base64 in `src/`, decoded once at startup with `decodeAudioData` | Ready the moment the plugin opens; nothing to download per session. Keep the set small (a few hundred KB). Not `public/`: a `public/` sound can only play through an `<audio>` element, which lags its cue (badly on iOS). |
+| The same sound effects shared by several arches (optional)                                                                           | A workspace asset library: `useArcheAssetBytes().getMany()`                  | One copy for every linked arche; a new version reaches them with a pin refresh, no code republish. Downloaded each session — wait for it before the first cue. MP3 or WAV, ≤ 1 MB and 30 s each.                           |
+| 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:**
 
@@ -1615,7 +1615,7 @@ for (const sound of entries) {
 **Permission:** `entities:client_invoke`
 **Returns:** `FiasContentApi`
 
-Ship large or numerous files — lessons, articles, data, images, audio, fonts — in a `content/` directory beside `src/`. They are not bundled: `fias-dev submit` uploads them separately (only the files that changed), the review reads every one, and the published plugin reads them at runtime through this hook. The host page fetches, verifies and caches them; your plugin never touches the network.
+Ship large or numerous files — lessons, articles, data, images, audio, fonts, 3D models — in a `content/` directory beside `src/`. They are not bundled: `fias-dev submit` uploads them separately (only the files that changed), the review reads every one, and the published plugin reads them at runtime through this hook. The host page fetches, verifies and caches them; your plugin never touches the network.
 
 ```tsx
 import { useFiasContent, FiasContentError } from '@fias/arche-sdk';
@@ -1630,7 +1630,7 @@ const cover = await content.getObjectUrl('img/cover.webp'); // blob: URL for <im
 const { url } = await content.getUrl('audio/theme.ogg'); // signed URL, for long streaming audio
 ```
 
-- Paths are relative to `content/`. Formats: `.md`, `.txt`, `.json` (text, ≤ 5 MB each); `.png`, `.jpg`, `.jpeg`, `.webp`, `.gif`, `.avif` (static, single-frame images, ≤ 20 MB and 50 megapixels); `.ogg` (audio, ≤ 50 MB); `.woff2` (fonts, ≤ 5 MB). A pack holds at most 10,000 files, 2,000 images, 20 MB of text and 500 MB in total. Run `npx fias-dev content check` to validate without submitting.
+- Paths are relative to `content/`. Formats: `.md`, `.txt`, `.json` (text, ≤ 5 MB each); `.png`, `.jpg`, `.jpeg`, `.webp`, `.gif`, `.avif` (static, single-frame images, ≤ 20 MB and 50 megapixels); `.ogg` (audio, ≤ 50 MB); `.woff2` (fonts, ≤ 5 MB); `.glb` (3D models, ≤ 25 MB, read with `getBytes` — see "VR and AR apps (WebXR)" for what a model may hold). A pack holds at most 10,000 files, 2,000 images (counting the textures inside models), 20 MB of text and 500 MB in total. Run `npx fias-dev content check` to validate without submitting.
 - Prefer `getObjectUrl` for images and fonts: repeat views come from the host cache. `getUrl` is for media that must stream or seek; it bypasses the cache, and a URL held past its `expiresAt` must be requested again.
 - Failures throw `FiasContentError` with a `code`: `CONTENT_NOT_FOUND`, `CONTENT_NOT_TEXT`, `CONTENT_TOO_LARGE`, `CONTENT_UNAVAILABLE`, `CONTENT_THROTTLED`, `CONTENT_UNAVAILABLE_IN_PREVIEW`, `PERMISSION_DENIED`, `RATE_LIMIT`. `getMany` returns the error for a failed path instead of throwing.
 - There is no published pack in the Arche Builder preview, so calls there fail with `CONTENT_UNAVAILABLE_IN_PREVIEW`; the dev harness serves your local `content/` directory.
@@ -1860,7 +1860,9 @@ const result = await web.extract({
 
 Your app reads pages only on **websites Fias approved** (regulated institutions such as credit unions and banks, and government sites) — any page on an approved site, so a redesigned or moved page keeps working. To have a site approved, ask Fias. `listSites()` lists them (free).
 
-`extract()` never returns the page's text — not even a short label. You send a **form** — up to 30 fields of kinds `number` and `integer` (optional `min`/`max`), `boolean`, `date` (`YYYY-MM-DD`), `enum` (your own `values`) and `list` (up to 200 rows of those) — and Fias reads the page into it. There is no free-text kind: describe what you need as numbers, dates, yes/no and choices you list (a product type, not a product name). Every value may be `null` (the page did not say); a value that broke its field's rules comes back `null` and is named in `discarded`. A model reading a page is not deterministic, so **where a wrong number matters (money), pass `reads: 2`**: the page is read twice, independently, and only a value both readings agree on is returned — a field they disagree on is `null` (a list keeps only the rows both produced) and is named in `disagreed`, for a person to confirm. A list named in `disagreed` may be missing rows the page prints: never conclude "absent on the page" (not offered) from a field in `disagreed` — treat it as unknown. Agreement says a value was stable across two readings, not that it is right; always show `site.name` and `fetchedAt` beside a figure so a person can check it. With two readings `discarded` names a list whole (`rates`), not a row. Two readings are two reader charges; the platform may raise the floor for every app, so check `disagreed` whatever you asked for. The reader's model, and so a reading's price, is chosen by the platform. URLs must be `https://`; `redirected: true` means the site moved the page within itself (the new address is not returned). The reader fills the form from whatever layout the page has, but it never runs JavaScript: a page that builds its figures with scripts comes back with `scriptHeavy: true` and mostly nulls — read the site's PDF rate sheet instead.
+`extract()` never returns the page's text — not even a short label. You send a **form** — up to 30 fields of kinds `number` and `integer` (optional `min`/`max`), `boolean`, `date` (`YYYY-MM-DD`), `enum` (your own `values`) and `list` (up to 200 rows of those) — and Fias reads the page into it. There is no free-text kind: describe what you need as numbers, dates, yes/no and choices you list (a heading the page prints is fine as a choice if you listed it; a string the page chose never is). Every value may be `null` (the page did not say); a value that broke its field's rules comes back `null` and is named in `discarded`. A model reading a page is not deterministic, so **where a wrong number matters (money), pass `reads: 2`**: the page is read twice, independently, and only a value both readings agree on is returned — a field they disagree on is `null` (a list keeps only the rows both produced) and is named in `disagreed`, for a person to confirm. A list named in `disagreed` may be missing rows the page prints: never conclude "absent on the page" (not offered) from a field in `disagreed` — treat it as unknown. Agreement says a value was stable across two readings, not that it is right; always show `site.name` and `fetchedAt` beside a figure so a person can check it. With two readings `discarded` names a list whole (`rates`), not a row. After the field names, `disagreed` names each row a list lost by its index in the in-order reading (`rates[3]`): the list you get is that reading with those rows removed. **Give a list a `key`** — the item fields that identify a row on the page (`key: ['product', 'months']`) — and a row both readings produced under one key is kept and agreed cell by cell: a cell they disagree on is `null` in the row and named `rates[3].apy` after the row entries, instead of the whole row being dropped because one cell differed (a row with a `null` key cell, or a key value a reading gave twice, is matched whole; the `3` is the row's index in the in-order reading, not in the list you received). `disagreedEntries(disagreed)` splits the entries into `fields`, `rows` and `cells`, each cell with its `position` in the list you received, and `disagreedFieldNames(disagreed)` gives the names alone; match entries by name or the `name[` prefix, never by equality or count. The reader never sees a key: a single reading Fias holds is paired, not bought again, when you add one; what two readings agreed on is read again. Two readings are two reader charges; the platform may raise the floor for every app, so check `disagreed` whatever you asked for. The reader's model, and so a reading's price, is chosen by the platform. URLs must be `https://`; `redirected: true` means the site moved the page within itself (the new address is not returned). The reader fills the form from whatever layout the page has, but it never runs JavaScript: a page that builds its figures with scripts comes back with `scriptHeavy: true` and mostly nulls — read the site's PDF rate sheet instead.
+
+**Write the form from the page, not from what pages usually look like.** Read the page yourself first (you can; the reader cannot show it to you) and write the form from what that page prints, one per product you read off it (each is its own reading pair). List the page's own words — its table headings, its model-year bands, its term column headers — as `enum` choices on each row (up to 50 values of up to 60 characters) plus a fixed escape such as `(none of these)`, so the reader copies and never classifies; keep a small table in the app that turns each heading into the cells your code reads, and key each list by that cell and the printed term. Ask only for cells the page prints: a cell the page never prints is answered `null` by one reading and guessed by the other, whatever its description says. A page changes: rows under your escape choice, a withheld row whose key cell the readings could not agree on, the list named whole in `discarded` (with two readings it never names a row), an empty list where the page says the product is published, or far fewer rows than last time mean the form must be rewritten — tell the user which page, in plain words. On the Rate Research pilot a generic form that asked the reader to classify had 63 of 117 counted rows withheld and agreed twice on three plain misreadings; forms written from each page lost no rows on the next refresh and matched one institution's pages in 57 of 57 values. `reads: 2` stays on either way: it catches the misread digit, which no form can.
 
 One copy of each page serves every app, and a page is fetched from its site **at most once an hour**. `maxAgeSeconds` (default one day, 3600–30 days) is the oldest copy you accept. A fresh fetch (about a tenth of a cent) and each reading (a fast model's tokens — well under a cent for a typical page; two with `reads: 2`) are charged to the user; a cached result costs nothing (`fromCache: true`). `stale: true` means the site could not be asked again just now and you got the last copy. Always show `site.name` and `fetchedAt` beside the figures. Not available in the builder preview or the test channel. **Error codes:** `WEB_SOURCES_DISABLED`, `INVALID_URL`, `SITE_NOT_APPROVED`, `PAGE_EXCLUDED` (a part of the site where the public posts), `ROBOTS_DISALLOWED`, `FETCH_FAILED`, `RESPONSE_TOO_LARGE`, `CONTENT_TYPE_NOT_ALLOWED`, `EXTRACTION_FAILED`, `SOURCE_BUSY`, `RATE_LIMIT` (surface it, never retry in a loop), `INSUFFICIENT_CREDITS`, `PERMISSION_DENIED`.
 
@@ -2171,6 +2173,110 @@ Notes:
 - Only `http(s)` URLs make sense here; `javascript:`/`data:` URLs are blocked
   by the sandbox.
 
+### VR and AR apps (WebXR)
+
+A plugin can be a VR or AR app: a game, a 3D viewer, a space to walk around.
+On a headset such as a Meta Quest, the person opens your arche in the
+headset's browser and presses your "Enter VR" button. No SDK hook or
+permission is needed: the plugin frame is allowed WebXR, and you use the
+browser's own API or a library. With three.js, add `three` to the manifest's
+`dependencies` (the published arche loads it at runtime) and to `package.json`,
+with `@types/three` in `devDependencies`, all at the same exact version.
+
+**Import from `three` itself, never `three/addons/...`.** The published build
+maps a dependency's bare name but not its subpaths, so `three/addons/...`
+(VRButton, OrbitControls, GLTFLoader) works under `npm run dev` and then fails
+the build with "no importmap entry". An Enter VR button is a few lines:
+
+```tsx
+import * as THREE from 'three';
+
+const renderer = new THREE.WebGLRenderer({ antialias: true });
+renderer.xr.enabled = true;
+renderer.xr.setReferenceSpaceType('local-floor'); // y = 0 is the room's floor
+container.appendChild(renderer.domElement);
+
+// Offer VR only where it exists. On a phone or desktop this resolves false and
+// the same scene stays a normal 3D view.
+const vr = (await navigator.xr?.isSessionSupported('immersive-vr').catch(() => false)) ?? false;
+
+// Call from the button's click handler, and request the session before any
+// other await: the click is what lets the browser start it.
+async function enterVr(xr: XRSystem) {
+  const session = await xr.requestSession('immersive-vr', { optionalFeatures: ['local-floor'] });
+  await renderer.xr.setSession(session);
+}
+
+// Not requestAnimationFrame: in VR the headset drives the frames.
+renderer.setAnimationLoop(() => renderer.render(scene, camera));
+```
+
+When you need an addon, copy its file from `node_modules/three/examples/jsm/`
+into `src/vendor/three/`, with the files it imports by relative path, keeping
+the folders. Its other imports are `three`, which the build maps. Beside it, add
+a one-line `.d.ts` so TypeScript uses `@types/three`'s types, for example
+`src/vendor/three/loaders/GLTFLoader.d.ts` holding
+`export * from 'three/examples/jsm/loaders/GLTFLoader.js';`.
+
+**3D models.** Put each model in your content pack as a `.glb`
+(`content/models/chair.glb`) and read its bytes with `useFiasContent()` (see
+that section; it needs the `entities:client_invoke` permission). Your plugin
+cannot fetch, so `GLTFLoader.load(url)` fails, but `parseAsync` takes the
+bytes. Copy GLTFLoader in as above (`loaders/GLTFLoader.js` plus
+`utils/BufferGeometryUtils.js` and `utils/SkeletonUtils.js`) and swap its
+texture loader: three.js decodes embedded textures with `fetch()`, which the
+sandbox blocks, and the model then loads with NO textures and only a console
+warning says why.
+
+```tsx
+import * as THREE from 'three';
+import { useFiasContent } from '@fias/arche-sdk';
+import { GLTFLoader } from './vendor/three/loaders/GLTFLoader.js';
+
+const content = useFiasContent();
+const loader = new GLTFLoader();
+loader.register((parser) => {
+  parser.textureLoader = new THREE.TextureLoader(parser.options.manager); // loads through <img>
+  return { name: 'fias_no_fetch_textures' };
+});
+const gltf = await loader.parseAsync(await content.getBytes('models/chair.glb'), '');
+scene.add(gltf.scene);
+```
+
+What a model may hold, and why:
+
+- One self-contained binary glTF 2.0 file, at most 25 MB: everything packed
+  inside, with no separate `.bin` or image files. A `.gltf` with side files is
+  refused; Blender's glTF exporter makes the right kind with "glTF Binary (.glb)".
+- At most 64 textures, each a still PNG, JPEG, WebP or AVIF. Every texture is
+  screened like an image file and counts toward the pack's 2,000 images; the
+  names and `extras` in the model are reviewed like text.
+- Export without compression. KTX2 / Basis textures are refused, and Draco or
+  meshopt geometry cannot be decoded in a plugin: their three.js decoders need
+  WebAssembly, which the plugin's sandbox does not run.
+
+A texture you apply in code can be its own image file in the pack: pass the URL
+from `content.getObjectUrl('textures/wall.webp')` to
+`new THREE.TextureLoader().loadAsync(url)`.
+
+Notes:
+
+- Entering VR or AR needs a click, and the browser may ask the person for
+  consent. `immersive-ar` (passthrough on Quest) starts the same way: create
+  the renderer with `alpha: true` and hide your sky so the room shows through.
+- Head and controller positions reveal things about the person, like their
+  height. Use them to draw the scene, not as data you save or send.
+- To test on a headset with `fias-dev`, the page must be a secure context.
+  `localhost` is one and a LAN address (`http://192.168.…`) is not, so connect
+  the headset by USB with developer mode on, run the commands below, and open
+  `http://localhost:3200` in the headset's browser. A published arche needs
+  nothing extra.
+
+```bash
+adb reverse tcp:3100 tcp:3100   # your plugin's dev server
+adb reverse tcp:3200 tcp:3200   # the fias-dev harness
+```
+
 ### `useStepNavigation()` — Multi-step workflows
 
 **Permission:** None for in-memory use; `storage:sandbox` when `persistKey` is set (it reads/writes `__state/<persistKey>` via the storage bridge).
@@ -2461,6 +2567,7 @@ When you hit a constraint, say so AND tell the user: file an Entity request on t
 - **`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
+- **You _can_ build VR and AR apps (WebXR)** for headsets like the Meta Quest — see "VR and AR apps (WebXR)" above
 - **No access** to parent DOM, cookies, or localStorage
 - **No external scripts or stylesheets** — everything must be bundled
 - All platform communication goes through the bridge (SDK hooks)