@the_library/public 2.0.0 → 2.1.0

package/README.md

@@ -1,760 +1,559 @@
-# @the_library/public — Complete API Documentation
+# @the_library/public
 
-This document provides exhaustive API reference for all exports from `@the_library/public` and its subpaths. It is organized by subpath/module and includes every function, type, interface, and composable with full parameter and return type documentation.
+The JavaScript SDK of the World Library: download and read books stored on Arweave, work with the library's records (books, people, tags…), and read and write the library's smart contracts. One ESM package with a separate entry point per area, for browsers (Web Workers, IndexedDB, Cache Storage) and, for the Web3 and registry parts, Node.
 
----
-
-## Table of Contents
-
-1. [Downloader API](#1-downloader-api--the_libraryPublicdownloader)
-   - [Initialization](#initialization)
-   - [File Operations](#file-operations)
-   - [Metadata & Storage](#metadata--storage)
-   - [Cache Management](#cache-management)
-   - [Cache Store API](#cache-store-api)
-   - [Keys & Naming](#keys--naming)
-   - [Framework Adapters](#framework-adapters-downloaderframeworknames)
-   - [Service Worker API](#service-worker-api--the_libraryPublicdownloadersw)
-
-2. [Models API](#2-models-api--the_libraryPublicmodels)
-   - [Language Semantics](#language-semantics-every-value-is-per-language)
-   - [Core Types & Registry](#core-types--registry)
-   - [Record Cache & Reactivity](#record-cache--reactivity)
-   - [Generated Models](#generated-models)
-   - [Schema Registry](#schema-registry)
-   - [Trash Index](#trash-index)
-   - [Stats & Local Analytics](#stats--local-analytics)
-   - [Framework Adapters](#framework-adapters-modelsframeworknames)
-   - [Patch & Session Management](#patch--session-management)
-
-3. [Web3 API](#3-web3-api--the_libraryPublicweb3)
-   - [Session API](#31-session-api)
-   - [Client API](#32-client-api)
-   - [Registry API](#33-registry-api)
-   - [Subscription API](#34-subscription-api)
-   - [Contracts API](#35-contracts-api)
-   - [Events API](#36-events-api)
-   - [Wallets API](#37-wallets-api)
-   - [Projects API](#38-projects-api)
-   - [Chain & Network Configuration](#39-chain--network-configuration)
-   - [Vue Composables](#310-vue-composables--the_libraryPublicweb3vue)
-
-4. [Branding API](#4-branding-api--the_libraryPublicbranding)
+This README explains [why the SDK is designed the way it is](#why-it-is-designed-this-way), gives short [how-to guides](#how-to-guides), and is the API reference, organised by entry point. The reference covers the public surface and the functions an app normally calls; the type declarations shipped in `dist/` are the complete, authoritative list.
 
----
-
-## 1. Downloader API (`@the_library/public/downloader`)
+**Licence:** D-Open Code Sovereign Licence 1.1 (unified edition), `LicenseRef-DOCSL-1.1`. See [`LICENSE`](./LICENSE) and the [full text](https://registry.worldbibliotech.com/licence). In short:
 
-The Downloader manages parallelized, cross-worker PDF and image fetching, decryption, decompression, and rendering using Web Workers and IndexedDB/Cache API storage backends.
-
-### Initialization
+- non-commercial use of unmodified copies (bundling, minifying and caching are fine);
+- public, anonymous, read-only access: writing to the library's contracts through this SDK is reserved to the services the licensor authorises;
+- by using the package you accept the licence, including its liquidated-damages clause for modifying the code or redirecting its contract addresses (section 16.4).
 
-#### `InitDownloaderV2(options?: InitOptions): Promise<void>`
+Third-party components keep their own licences: [`THIRD_PARTY_NOTICES`](./THIRD_PARTY_NOTICES). For commercial use or a modified build: admin@pondenterprise.com.
 
-Single-call initialization of the download orchestrator. Must be called once at app boot before calling any file-fetch functions. Idempotent — subsequent calls are no-ops.
+## Install
 
-```typescript
-import { InitDownloaderV2 } from '@the_library/public/downloader';
-
-await InitDownloaderV2({
-  gateways: ['https://arweave.net', 'https://arweave.dev'],
-  requestPersistence: true,
-  concurrency: { pdf: 3, preview: 6 },
-  mupdfUrl: '/js/mupdf.js',
-});
+```sh
+npm install @the_library/public @the_library/network-config
 ```
 
-**Parameters:**
-- `options.gateways?: string[]` — Array of Arweave gateway URLs to try in sequence. Defaults to `['https://arweave.net']`.
-- `options.requestPersistence?: boolean` — If `true`, asks the browser for persistent storage via `navigator.storage.persist()`, which may prevent auto-eviction of cached files. Defaults to `false`.
-- `options.concurrency?: { pdf: number; preview: number }` — Limits simultaneous downloads: `pdf` caps concurrent PDF fetches, `preview` caps concurrent page-image renders. Defaults to `{ pdf: 3, preview: 6 }`.
-- `options.mupdfUrl?: string` — URL to `mupdf.js` (WASM runtime). Must be adjacent to `mupdf-wasm.js` and `mupdf-wasm.wasm` in the app's `public/` directory. Defaults to `'/js/mupdf.js'`.
-
-**Returns:** `Promise<void>` — resolves once worker threads are initialized.
-
-**Throws:** 
-- If `InitDownloaderV2` is called simultaneously from multiple call sites, the first promise is returned (idempotency guard).
-- Worker thread setup errors (e.g., broken WASM URL) surface on the returned promise.
-
----
-
-#### `preloadWorkersV2(): void`
+- `@the_library/network-config` is already a dependency; install it yourself as well because you import from it directly (chain IDs, `getChain`, `EVM_CHAINS`, …), which strict installers such as pnpm require.
+- `vue`, `react` and `solid-js` are optional peer dependencies: install the one whose adapters you import.
+- ESM only (`import`), with TypeScript declarations.
 
-Eagerly constructs worker threads so the worker JS bundles download in the background. Call as early as possible (e.g., during app shell initialization before the app mounts components).
+## Entry points
 
-```typescript
-import { preloadWorkersV2 } from '@the_library/public/downloader';
+| Import | What it gives you |
+|---|---|
+| `@the_library/public/downloader` | Download, cache and render book PDFs, covers and pages ([§1](#1-downloader-api-the_librarypublicdownloader)) |
+| `@the_library/public/downloader/vue` · `/react` · `/solid` | Reactive download state ([§1](#framework-adapters-downloadervuereactsolid)) |
+| `@the_library/public/downloader/sw` | Optional offline service worker ([§1](#service-worker-api-the_librarypublicdownloadersw)) |
+| `@the_library/public/models` | The record engine: cache, reactivity, patches, search, trash, stats ([§2](#2-models-api-the_librarypublicmodels)) |
+| `@the_library/public/models/models` | Generated model classes: `Book`, `Person`, `Tag`, `ClassificationSystem`, `Post` ([§2](#generated-models)) |
+| `@the_library/public/models/vue` · `/react` · `/solid` · `/astro` | Session bootstrap and framework views ([§2](#framework-adapters-modelsvuereactsolidastro)) |
+| `@the_library/public/web3` | EVM read/write clients, session, wallets, subscriptions, projects ([§3](#3-web3-api-the_librarypublicweb3)) |
+| `@the_library/public/web3/network` | `toViemChain` ([§3.9](#39-chain--network-configuration)) |
+| `@the_library/public/web3/registry` | Registry manifest loader ([§3.3](#33-registry-api)) |
+| `@the_library/public/web3/vue` | Vue composables: `bootstrapWebSDK`, `useWeb3Session`, `useChain`, … ([§3.10](#310-vue-composables-the_librarypublicweb3vue)) |
+| `@the_library/public/web3/auth` | Signed admin-batch and deletion-consent messages ([§3.11](#311-auth-api-the_librarypublicweb3auth)) |
+| `@the_library/public/branding` | Shared branding and contact data ([§4](#4-branding-api-the_librarypublicbranding)) |
+| `@the_library/public/branding/assets/*` | Brand images (logos, favicon) |
 
-// Call immediately when app boots, before any heavy imports:
-preloadWorkersV2();
-```
+`@the_library/public/models.js` and `@the_library/public/models/models.js` are aliases of `/models` and `/models/models`.
 
-**Parameters:** None
+The package also ships `dist/global/public.global.js`, a single browser script that exposes the main entry points (and `@the_library/network-config`) on `window.TheLibraryPublic`, keyed by import path, with their export names in `dist/global/public.manifest.json`. It expects Vue on `window.Vue`.
 
-**Returns:** `void` (synchronous; starts background downloads, doesn't wait for them)
+Chain IDs in the examples come from `@the_library/network-config` (`DEFAULT_CHAIN_ID` for production, `DEFAULT_STAGING_CHAIN_ID` for the testnet). Don't hard-code them: the networks behind those roles change.
 
 ---
 
-### File Operations
-
-#### `GetPdf(txId: string, options?: { priority?: 'low' | 'high' }): Promise<Response>`
-
-Fetches, decrypts, and decompresses a PDF by Arweave TX ID. Returns a `Response` object wrapping the decrypted bytes.
+## Why it is designed this way
 
-```typescript
-import { GetPdf, GetObjectUrl } from '@the_library/public/downloader';
+This SDK is the engineering foundation of:
 
-const response = await GetPdf(txId);
-const blob = await response.blob();
-const objectUrl = await GetObjectUrl(response); // for <iframe> or <embed>
-```
+- [**datapond.earth**](https://datapond.earth) — the framework: *UniMarc & Web3*, a web3 data framework for the public domain;
+- [**worldbibliotech.com**](https://worldbibliotech.com) — the World Library, the live library built on it;
+- [**wordlibrary.net**](https://wordlibrary.net) — the anti-cheat idea behind the library's rankings, in plain language;
+- the upcoming *MARC work (STARMARC).
 
-**Parameters:**
-- `txId: string` — Arweave TX ID identifying the encrypted PDF.
-- `options.priority?: 'low' | 'high'` — Queue priority. Defaults to `'low'`. Use `'high'` for user-initiated "open book" actions to bump ahead of background prefetches.
+The aim is to bring sovereign data to public libraries. It does so by taking the design of a public library — one shared collection, a personal copy for every reader, public records, open to everyone — as the blueprint for a public web3 framework. Each principle below says what the idea means and which part of the code carries it.
 
-**Returns:** `Promise<Response>` — HTTP `Response` object (status 200) wrapping the decrypted PDF bytes. Use `.blob()`, `.arrayBuffer()`, or `.text()` to read the body.
-
-**Throws:**
-- If all gateways are unreachable or return 404/500, rejects with a `NetworkError` or `NotFoundError`.
-- If decryption fails, rejects with a `DecryptionError`.
-
-**Caching:** The result is cached by `txId` in the browser's Cache API (under `CACHES.pdf`). Subsequent calls return the cached response synchronously.
-
----
+### A library catalogue, built from library standards
 
-#### `GetImage(txId: string, pageOverride?: number): Promise<Response>`
+Records are described with the identifiers and classifications that library catalogues already use. These are defined once in [`@the_library/canonical-schemas`](https://www.npmjs.com/package/@the_library/canonical-schemas) and implemented in [`@the_library/standard-adapters`](https://www.npmjs.com/package/@the_library/standard-adapters):
 
-Renders a page preview image (JPEG/PNG) via the mupdf worker. By default, renders the first page of a PDF. Returns a `Response` wrapping the image bytes.
+- **identifiers:** ISBN, ISSN, ISNI, ORCID;
+- **classifications:** Dewey, Library of Congress, UDC, Chinese, BBK, Thai and Colon.
 
-```typescript
-import { GetImage } from '@the_library/public/downloader';
+This is what "UNIMARC compatible by design" means here. A book, its editions, its authors and its subjects line up with the fields of a UNIMARC (and MARC 21) bibliographic record: see the [correspondence table](https://www.npmjs.com/package/@the_library/canonical-schemas#unimarc-and-marc-21). These packages don't include a UNIMARC record converter.
 
-// Get the cover image (first page)
-const coverResponse = await GetImage(txId);
-const imageBlob = await coverResponse.blob();
-const imgSrc = URL.createObjectURL(imageBlob);
+### Sovereign data: the records live on Gnosis and Arweave
 
-// Get a specific page
-const page5Image = await GetImage(txId, 5);
-```
+- **The shared catalogue** is published on Arweave as compact binary sidecars, found through the registry manifest ([§3.3](#33-registry-api)).
+- **Every change a reader makes** — an edit, a deletion, a rating — is a patch. It is saved by `Factory.save()` under the reader's own account on Gnosis.
+- **Book files** come from Arweave and are kept in the browser (Cache Storage and IndexedDB), with an optional offline service worker ([§1](#service-worker-api-the_librarypublicdownloadersw)).
+- **The parts that are not on-chain:**
+  - `registry.worldbibliotech.com` serves the registry manifest, with the on-chain `AddressRegistry` as fallback;
+  - AWS Lambdas create accounts from an email address, top up gas, and send the recovery and deletion-consent emails;
+  - Arweave gateways serve the files;
+  - price oracles are used on chains that have one.
 
-**Parameters:**
-- `txId: string` — Arweave TX ID of the PDF.
-- `pageOverride?: number` — 1-indexed page number. Defaults to `1` (first page).
+### One shared collection, your own copy
 
-**Returns:** `Promise<Response>` — HTTP `Response` object (status 200) wrapping JPEG/PNG bytes.
+Everyone starts from the same canonical collection. A reader's edits change their own copy, not anyone else's. Their patches are kept under their account (the records' `creatorUsername`), and other readers only receive them by subscribing to that reader ([§3.4](#34-subscription-api)).
 
-**Throws:**
-- Same as `GetPdf` (gateway errors, decryption failures).
-- If `pageOverride` is out of range (e.g., page 1000 of a 10-page PDF), rejects with `RangeError`.
+### Anti-cheat: curation, not likes
 
-**Caching:** Rendered images are cached in `CACHES.preview` under the key `{txId}_page{n}`. Cached preview images persist across sessions.
+The ranking idea ([wordlibrary.net](https://wordlibrary.net)) is to count what readers remove, not what they like. A fake like hides in a crowd. Faking curation takes many coordinated deletions, and those leave a public trail.
 
----
+What this SDK provides is that trail. Deletions and moves are ordinary patches on the reader's account (the `deleted`/`safe` flags, see [Trash Index](#trash-index)). They are saved publicly on Gnosis, and anyone can read them through the read client and subscription sync. The ranking itself is computed outside this package.
 
-#### `EnsurePdf(txId: string): Promise<void>`
+### Identity: an account, not a person
 
-Pre-downloads and caches a PDF without needing the `Response` object back. Useful for background prefetching or "warm up" operations.
+- **On-chain, an account is** an address, a username, a user ID, a country and a language.
+- **The email address is never stored on-chain in clear**, only as a hash. That hash is used for account recovery and for email-confirmed deletion ([§3.11](#311-auth-api-the_librarypublicweb3auth)).
+- **Accounts are pseudonymous, not anonymous.** A reader's saved actions, including visits, downloads, ratings and shares, are public under their account. The aggregate statistics (`StatsPivotStorage`) carry no user ID ([Stats](#stats--local-analytics)).
+- **The wallet key** is kept in the browser's `localStorage`, unencrypted ([Private Key Storage](#private-key-storage)).
 
-```typescript
-import { EnsurePdf } from '@the_library/public/downloader';
+### Free to use
 
-// Background prefetch (fire and forget)
-EnsurePdf(txId).catch(e => console.warn('Prefetch failed:', e));
+There are no paywalls, login walls or ads; that is a condition of the licence. Reading, searching and downloading need no account.
 
-// Wait for it
-await EnsurePdf(txId);
-```
+Saving to the chain needs a member account. A library can create accounts in bulk, or a reader can take the $2 `account` membership. Either way, when the account is created or restored, the project tops its wallet up with gas to the chain's `memberFundingTarget`, so members don't buy gas themselves. Donations are voluntary.
 
-**Parameters:**
-- `txId: string` — Arweave TX ID of the PDF.
+### Built to last
 
-**Returns:** `Promise<void>` — resolves once the PDF is cached.
-
-**Throws:** Same as `GetPdf`.
+- **Property IDs are permanent:** they come from an append-only dictionary ([canonical-schemas](https://www.npmjs.com/package/@the_library/canonical-schemas#changing-a-definition)).
+- **A storage contract is never redeployed empty:** a new version is migrated with every record.
+- **Book files on Arweave are permanent.**
+- **No network is hard-coded:** apps take their chains from `@the_library/network-config` by role (production, staging).
 
 ---
 
-#### `EnsurePageImage(txId: string, page: number): Promise<void>`
-
-Pre-renders and caches a specific page image without returning the bytes. Used to warm up page-image cache before the user scrolls to that page.
-
-```typescript
-import { EnsurePageImage } from '@the_library/public/downloader';
-
-// Render pages 2-5 in the background while user reads page 1
-for (let i = 2; i <= 5; i++) {
-  EnsurePageImage(txId, i).catch(e => console.warn(`Page ${i} prefetch failed`));
-}
-```
-
-**Parameters:**
-- `txId: string` — Arweave TX ID.
-- `page: number` — 1-indexed page number.
-
-**Returns:** `Promise<void>` — resolves once the image is cached.
+## How-to guides
 
-**Throws:** Same as `GetImage`.
+Each recipe is type-checked against the published package.
 
----
+### Open a book
 
-#### `DownloadPdfToDisk(txId: string, filename?: string): Promise<void>`
-
-Triggers a browser "Save As" dialog and writes the decrypted PDF to the user's local Downloads folder.
+Show a book's cover, then open its PDF. Serve `file-worker-v2.js` and `mu-worker-v2.js` (from `dist/downloader/`) at your site's root.
 
 ```typescript
-import { DownloadPdfToDisk } from '@the_library/public/downloader';
-
-await DownloadPdfToDisk(txId, 'My Book Title.pdf');
-```
-
-**Parameters:**
-- `txId: string` — Arweave TX ID.
-- `filename?: string` — Suggested filename for the browser's save dialog. If omitted, the browser uses a default name.
-
-**Returns:** `Promise<void>` — resolves once the download is initiated (does not wait for the user to confirm the save dialog).
-
-**Throws:**
-- Same as `GetPdf` (fetch/decrypt errors).
-- If the browser blocks the download (e.g., security policy), the promise rejects with a `SecurityError`.
-
----
-
-#### `GetObjectUrl(response: Response): Promise<string>`
+import { preloadWorkersV2, GetImage, GetPdf, GetObjectUrl, revokeObjectUrl } from '@the_library/public/downloader';
+import { Book } from '@the_library/public/models/models';
 
-Converts a `GetPdf` or `GetImage` response to a blob URL suitable for `<iframe src="">`, `<embed src="">`, or `<img src="">`.
+preloadWorkersV2();                                    // start the workers early
 
-```typescript
-import { GetPdf, GetObjectUrl } from '@the_library/public/downloader';
+const book = await Book.LoadAsync(bookId);             // bookId: bigint
+img.src = await GetObjectUrl(await GetImage(book.previewTxId));
 
-const pdfResponse = await GetPdf(txId);
-const blobUrl = await GetObjectUrl(pdfResponse);
-// Now use: <iframe :src="blobUrl" />
+const edition = book.getDefaultInstance('eng');        // the edition in a language
+if (edition) frame.src = await GetObjectUrl(await GetPdf(edition.downloadTxId));
+// when the reader closes it: revokeObjectUrl(frame.src)
 ```
 
-**Parameters:**
-- `response: Response` — A `Response` object returned by `GetPdf` or `GetImage`.
-
-**Returns:** `Promise<string>` — A `blob:` URL (e.g., `blob:https://example.com/...`).
-
----
+### Load the catalogue
 
-#### `revokeObjectUrl(blobUrl: string): void`
-
-Explicitly revokes a blob URL created by `GetObjectUrl` to release memory.
+Read the published registry, then boot the models from the collection it points to. Serve `patch-worker.js` (from `dist/models/`) at your site's root.
 
 ```typescript
-const blobUrl = await GetObjectUrl(response);
-// ... later ...
-revokeObjectUrl(blobUrl);
-```
-
-**Parameters:**
-- `blobUrl: string` — The blob URL to revoke.
-
-**Returns:** `void`
+import { addressLoader } from '@the_library/public/web3';
+import { bootstrapModelsV2 } from '@the_library/public/models/vue';   // or /react, /solid, /astro
+import { Book, Tag, Person, NewBookWithId, NewTagWithId, NewPersonWithId } from '@the_library/public/models/models';
 
-**Note:** Blob URLs are automatically revoked when the page navigates away or the tab closes. Manual revocation is only necessary to free memory during a long-running session (e.g., a single-page app that opens/closes many books).
+await addressLoader.loadManifest('production');
+const corpus = addressLoader.getCollectionCorpus('production');
+if (!corpus) throw new Error('no collection in the registry manifest');
 
----
+await bootstrapModelsV2({
+  userLang: 'eng',
+  models: [
+    { type: Book.type, create: NewBookWithId },
+    { type: Tag.type, create: NewTagWithId },
+    { type: Person.type, create: NewPersonWithId },
+  ],
+  registry: { dataBlock: corpus, gateway: 'https://arweave.net' },
+});
 
-#### `storageEstimate(): Promise<{ usage: number; quota: number }>`
+const title = (await Book.LoadAsync(bookId)).getTitle('eng');
+```
 
-Queries the browser's storage quota and current usage.
+### Read the chain
 
 ```typescript
-import { storageEstimate } from '@the_library/public/downloader';
+import { DEFAULT_CHAIN_ID } from '@the_library/network-config';
+import { getReadClient } from '@the_library/public/web3';
 
-const { usage, quota } = await storageEstimate();
-const percentUsed = (usage / quota) * 100;
-console.log(`${percentUsed.toFixed(1)}% of storage in use`);
+const client = getReadClient(DEFAULT_CHAIN_ID);
+await client.ready;                                   // contract addresses and ABIs loaded
+const members = await client.bouncerStorage.nbAccounts();
 ```
 
-**Parameters:** None
-
-**Returns:** `Promise<{ usage: number; quota: number }>` — `usage` is bytes currently used by Cache API + IndexedDB, `quota` is the browser's total storage quota in bytes.
-
----
-
-### Metadata & Storage
-
-#### `getBookData(txId: string): Promise<BookData | undefined>`
-
-Reads cached book metadata (title, page count, etc.) from IndexedDB.
+### Start a Vue app with accounts
 
 ```typescript
-import { getBookData } from '@the_library/public/downloader';
+import { createApp } from 'vue';
+import { bootstrapWebSDK, BootstrapResultKey } from '@the_library/public/web3/vue';
 
-const bookData = await getBookData(txId);
-if (bookData) {
-  console.log(`${bookData.title} has ${bookData.pages} pages`);
-}
+const result = await bootstrapWebSDK({ environment: 'production' });
+const app = createApp(App);
+app.provide(BootstrapResultKey, result);
+app.mount('#app');
+
+// in a component
+import { useWeb3Session } from '@the_library/public/web3/vue';
+const { activeAccount, registeredAccounts } = useWeb3Session();
 ```
 
-**Parameters:**
-- `txId: string` — Arweave TX ID.
+### Save a reader's changes
 
-**Returns:** `Promise<BookData | undefined>` — Book metadata if cached, `undefined` if no metadata has been hydrated yet.
+Edits made through the models are queued on the device; this sends them to the chain under the active account.
 
-**Type: `BookData`**
 ```typescript
-interface BookData {
-  txId: string;
-  title: string;
-  pages: number;
-  // ... other fields set by the mupdf worker
+import { sessionStore, hasUnsavedPatches, saveMyLevel } from '@the_library/public/web3';
+
+const me = sessionStore.getState().active;
+if (me && await hasUnsavedPatches(me.account, me.chainId)) {
+  await saveMyLevel(me.wallet, me.chainId, me.account);
 }
 ```
 
----
-
-#### `getAllBookData(): Promise<BookData[]>`
+### Work offline
 
-Retrieves all cached book metadata records from IndexedDB.
+Register the optional service worker (`dl2-sw.js`, served at `/dl2-sw.js`). Cached books then load from plain URLs, with or without a network.
 
 ```typescript
-import { getAllBookData } from '@the_library/public/downloader';
+import { registerDownloaderSW } from '@the_library/public/downloader/sw';
 
-const allBooks = await getAllBookData();
-console.log(`${allBooks.length} books cached`);
+const status = await registerDownloaderSW({ allowedOrigins: ['example.org'] });
+if (status.registered) img.src = `/ar/${txId}`;        // served from Cache Storage when cached
 ```
 
-**Parameters:** None
-
-**Returns:** `Promise<BookData[]>` — Array of all cached `BookData` records. Empty array if no books have been hydrated yet.
-
 ---
 
-#### `getDownloadRecord(txId: string): Promise<DownloadRecord | undefined>`
+## Table of Contents
 
-Reads the download progress record for a TX ID.
+- [Why it is designed this way](#why-it-is-designed-this-way)
+- [How-to guides](#how-to-guides)
 
-```typescript
-import { getDownloadRecord } from '@the_library/public/downloader';
+1. [Downloader API](#1-downloader-api-the_librarypublicdownloader)
+   - [Initialization](#initialization)
+   - [File Operations](#file-operations)
+   - [Metadata & Storage](#metadata--storage)
+   - [Download State](#download-state)
+   - [Keys & Naming](#keys--naming)
+   - [Framework Adapters (/downloader/{vue,react,solid})](#framework-adapters-downloadervuereactsolid)
+   - [Service Worker API](#service-worker-api-the_librarypublicdownloadersw)
 
-const record = await getDownloadRecord(txId);
-if (record) {
-  console.log(`${record.loaded}/${record.total} bytes downloaded`);
-}
-```
+2. [Models API](#2-models-api-the_librarypublicmodels)
+   - [Language Semantics (every value is per-language)](#language-semantics-every-value-is-per-language)
+   - [Core Types & Registry](#core-types--registry)
+   - [Record Cache & Reactivity](#record-cache--reactivity)
+   - [Generated Models](#generated-models)
+   - [Schema Registry](#schema-registry)
+   - [Trash Index](#trash-index)
+   - [Stats & Local Analytics](#stats--local-analytics)
+   - [Framework Adapters (/models/{vue,react,solid,astro})](#framework-adapters-modelsvuereactsolidastro)
+   - [Patch & Session Management](#patch--session-management)
 
-**Parameters:**
-- `txId: string` — Arweave TX ID.
+3. [Web3 API](#3-web3-api-the_librarypublicweb3)
+   - [Session API](#31-session-api)
+   - [Client API](#32-client-api)
+   - [Registry API](#33-registry-api)
+   - [Subscription API](#34-subscription-api)
+   - [Contracts API](#35-contracts-api)
+   - [Events API](#36-events-api)
+   - [Wallets API](#37-wallets-api)
+   - [Projects API](#38-projects-api)
+   - [Chain & Network Configuration](#39-chain--network-configuration)
+   - [Vue Composables](#310-vue-composables-the_librarypublicweb3vue)
+   - [Auth API](#311-auth-api-the_librarypublicweb3auth)
 
-**Returns:** `Promise<DownloadRecord | undefined>`
+4. [Branding API](#4-branding-api-the_librarypublicbranding)
 
-**Type: `DownloadRecord`**
-```typescript
-interface DownloadRecord {
-  txId: string;
-  loaded: number;   // bytes downloaded so far
-  total: number;    // total file size in bytes
-  timestamp: number; // last update time (ms since epoch)
-}
-```
+[Appendix: Type Quick Reference](#appendix-type-quick-reference)
+   - [Download Types](#download-types)
+   - [Models Types](#models-types)
+   - [Web3 Types](#web3-types)
+   - [Branding Types](#branding-types)
 
 ---
 
-#### `getAllDownloadRecords(): Promise<DownloadRecord[]>`
-
-Retrieves all download progress records.
-
-```typescript
-import { getAllDownloadRecords } from '@the_library/public/downloader';
-
-const records = await getAllDownloadRecords();
-console.log(`${records.length} active/recent downloads`);
-```
+## 1. Downloader API (`@the_library/public/downloader`)
 
-**Parameters:** None
+The downloader fetches book PDFs from Arweave, renders cover and page images in Web Workers (mupdf), and keeps everything in the browser's Cache Storage, with metadata and download records in IndexedDB. Every file is identified by its Arweave transaction ID (`txId`). When storage use passes 80% of the browser's quota, the least recently used PDFs are deleted until it is back under 65%; the open book and [pinned](#setpinnedpdfstxids-string-void) books are never deleted.
 
-**Returns:** `Promise<DownloadRecord[]>` — Array of all cached progress records.
+The workers are separate files shipped in `dist/downloader/`: `file-worker-v2.js` and `mu-worker-v2.js`, loaded from your site's root (`/file-worker-v2.js`, `/mu-worker-v2.js`), and the optional service worker `dl2-sw.js` (`/dl2-sw.js`). Page rendering also needs `mupdf.js`, with `mupdf-wasm.js` and `mupdf-wasm.wasm` next to it, at `mupdfUrl`.
 
----
-
-### Cache Management
+### Initialization
 
-#### `downloadState`
+#### `InitDownloaderV2(opts?: InitOptions): Promise<void>`
 
-The canonical, synchronous, framework-agnostic store for all file state. Every framework adapter (`vue`, `react`, `solid`) is a thin reactive wrapper around this store.
+Starts the download orchestrator. Every file function below calls it for you, so calling it yourself is only needed to pass options or to start early. Repeated calls return the first call's promise; a failed start can be retried.
 
 ```typescript
-import { downloadState } from '@the_library/public/downloader';
+import { InitDownloaderV2 } from '@the_library/public/downloader';
 
-// Subscribe to changes
-const unsubscribe = downloadState.subscribe((changedTxId) => {
-  console.log(`File state changed for ${changedTxId}`);
+await InitDownloaderV2({
+  gateways: ['https://arweave.net', 'https://permagate.io'],
+  concurrency: { pdf: 3, preview: 6 },
+  mupdfUrl: '/js/mupdf.js',
 });
-
-// Read current state
-const fileState = downloadState.get(txId);
-if (fileState?.phase === 'done') {
-  console.log('Download complete');
-}
-
-// Read render state (page images, book metadata)
-const renderState = downloadState.getRender(txId);
-console.log(`${renderState.pages.size} page images cached`);
-
-// Global summary
-const summary = downloadState.summary();
-console.log(`${summary.downloading} active downloads`);
 ```
 
-**Methods:**
-
-- `downloadState.get(txId: string): FileState | undefined` — Returns current state of one file.
-  
-- `downloadState.getRender(txId: string): RenderState | undefined` — Returns render/page state for one file.
-  
-- `downloadState.summary(): DownloadSummary` — Returns global aggregate (total files, total bytes, etc.).
-  
-- `downloadState.subscribe(callback: (txId: string) => void): () => void` — Registers a listener. Returns unsubscribe function.
-
-**Type: `FileState`**
-```typescript
-interface FileState {
-  phase: 'unknown' | 'queued' | 'downloading' | 'done' | 'error';
-  loaded: number;
-  total: number;
-  error?: string;
-  progress?: number; // 0-1
-}
-```
-
-**Type: `RenderState`**
-```typescript
-interface RenderState {
-  bookData?: BookData;
-  pages: Map<number, FilePhase>; // page number -> 'done' | 'error' | ...
-}
-```
+**`InitOptions`** (all optional):
+- `gateways: string[]` — Arweave gateways, tried in order. Default `['https://arweave.net', 'https://permagate.io', 'https://ar-io.dev']`.
+- `requestPersistence: boolean` — ask the browser for persistent storage (`navigator.storage.persist()`), so cached books aren't evicted under storage pressure. Default `true`.
+- `concurrency: { pdf: number; preview: number }` — how many PDFs and how many cover images download at once. Default `{ pdf: 3, preview: 6 }`.
+- `muWorkerTimeout: number` — milliseconds before a render request to the mupdf worker is abandoned. Default `60000`.
+- `mupdfUrl: string` — URL of `mupdf.js`. Default `'/js/mupdf.js'`.
 
 ---
 
-#### `deletePdf(txId: string): Promise<boolean>`
+#### `preloadWorkersV2(): void`
 
-Removes a cached PDF from Cache API storage.
+Creates the two worker threads immediately, so their scripts download while the app is still starting. Call it as early as possible.
 
 ```typescript
-import { deletePdf } from '@the_library/public/downloader';
+import { preloadWorkersV2 } from '@the_library/public/downloader';
 
-const deleted = await deletePdf(txId);
-console.log(deleted ? 'Deleted' : 'Not found in cache');
+preloadWorkersV2();
 ```
 
-**Parameters:**
-- `txId: string` — Arweave TX ID.
-
-**Returns:** `Promise<boolean>` — `true` if deletion succeeded, `false` if the PDF was not cached.
-
 ---
 
-#### `deletePreview(txId: string): Promise<boolean>`
+### File Operations
 
-Removes all cached page preview images for a TX ID.
+#### `GetPdf(txId: string): Promise<Response>`
+
+Returns the book's PDF as a `Response`, from the cache when it's there, otherwise after downloading it. The book becomes the "open book", which pruning never removes.
 
 ```typescript
-import { deletePreview } from '@the_library/public/downloader';
+import { GetPdf, GetObjectUrl } from '@the_library/public/downloader';
 
-await deletePreview(txId);
+const response = await GetPdf(txId);
+const url = await GetObjectUrl(response); // for <iframe> or <embed>
 ```
 
-**Parameters:**
-- `txId: string` — Arweave TX ID.
-
-**Returns:** `Promise<boolean>` — `true` if deletion succeeded.
+**Throws** if the download fails on every gateway, or `DownloadQuotaExceededError` if the browser refused to store it.
 
 ---
 
-#### `deleteDownloadRecord(txId: string): Promise<void>`
+#### `GetImage(txId: string): Promise<Response>`
 
-Removes the download progress record from IndexedDB.
+Returns the book's cover (preview) image. Calls for different books are limited by `concurrency.preview`, and repeated calls for the same book share one download, so it's safe to call for every book in a list.
 
 ```typescript
-import { deleteDownloadRecord } from '@the_library/public/downloader';
+import { GetImage } from '@the_library/public/downloader';
 
-await deleteDownloadRecord(txId);
+const cover = await GetImage(txId);
+img.src = URL.createObjectURL(await cover.blob());
 ```
 
-**Parameters:**
-- `txId: string` — Arweave TX ID.
-
-**Returns:** `Promise<void>`
-
 ---
 
-### Cache Store API
-
-Raw cache and IndexedDB access (rarely called directly; use the higher-level APIs above when possible).
-
-#### `openPdfCache(): Promise<Cache>`
+#### `EnsurePageImage(txId: string, page: number): Promise<Response>`
 
-Gets the Cache API store for PDFs.
+Renders one page of the PDF to an image (downloading the PDF first if needed), caches it, and returns it.
 
 ```typescript
-const cache = await openPdfCache();
-const keys = await cache.keys();
-```
-
-#### `openPreviewCache(): Promise<Cache>`
-
-Gets the Cache API store for preview images.
-
-#### `openPagesCache(): Promise<Cache>`
-
-Gets the Cache API store for individual page images.
-
-#### `matchPdf(txId: string): Promise<Response | undefined>`
-
-Low-level cache lookup for a single PDF.
-
-#### `matchPreview(txId: string): Promise<Response | undefined>`
-
-Low-level cache lookup for a cover/first-page image.
-
-#### `matchPage(txId: string, pageNumber: number): Promise<Response | undefined>`
-
-Low-level cache lookup for a specific page image.
+import { EnsurePageImage } from '@the_library/public/downloader';
 
-#### `putPdf(txId: string, response: Response): Promise<void>`
+const page2 = await EnsurePageImage(txId, 2);
+```
 
-Low-level cache write for a PDF.
+---
 
-#### `putPreview(txId: string, response: Response): Promise<void>`
+#### `EnsurePdf(txId: string): Promise<void>`
 
-Low-level cache write for a cover image.
+Downloads and caches the PDF without returning it, e.g. to prefetch the next book.
 
-#### `putPage(txId: string, pageNumber: number, response: Response): Promise<void>`
+---
 
-Low-level cache write for a page image.
+#### `EnsurePageCount(txId: string): Promise<number>`
 
-#### `pdfKeys(): Promise<string[]>`
+Returns the PDF's page count, downloading and parsing the PDF if needed.
 
-Lists all cached PDF keys.
+---
 
-#### `previewKeys(): Promise<string[]>`
+#### `DownloadPdfToDisk(txId: string, filename: string): Promise<void>`
 
-Lists all cached preview-image keys.
+Saves the PDF to the user's device through the browser's normal download. `.pdf` is appended to `filename` if it's missing.
 
-#### `pageKeys(): Promise<string[]>`
+```typescript
+import { DownloadPdfToDisk } from '@the_library/public/downloader';
 
-Lists all cached page-image keys.
+await DownloadPdfToDisk(txId, 'My Book Title');
+```
 
 ---
 
-### Keys & Naming
-
-#### `pdfKey(txId: string): string`
+#### `GetObjectUrl(resp: Response): Promise<string>` and `revokeObjectUrl(url: string): void`
 
-Generates the cache key for a PDF.
+Turn a response from the functions above into a `blob:` URL, and release it when you no longer need it.
 
 ```typescript
-const key = pdfKey(txId); // e.g., "arweave_pdf_{txId}"
+const url = await GetObjectUrl(await GetPdf(txId));
+// … later
+revokeObjectUrl(url);
 ```
 
-#### `previewKey(txId: string): string`
+---
 
-Generates the cache key for a cover image.
+#### `SetPinnedPdfs(txIds: string[]): void`
 
-#### `pageKey(txId: string, pageNumber: number): string`
+Protects these books from pruning, e.g. a shelf the user marked for offline reading. Replaces the previous list; the open book stays protected regardless.
 
-Generates the cache key for a specific page.
+---
 
-```typescript
-const key = pageKey(txId, 5); // e.g., "arweave_page_5_{txId}"
-```
+#### `storageEstimate(): Promise<StorageEstimate>`
 
-#### `CACHES` (constant)
+The browser's own storage figures (`navigator.storage.estimate()`): `usage` and `quota` in bytes.
 
 ```typescript
-import { CACHES } from '@the_library/public/downloader';
-
-// CACHES = {
-//   pdf: 'dl2-pdf-cache-v1',
-//   preview: 'dl2-preview-cache-v1',
-//   pages: 'dl2-pages-cache-v1'
-// }
-```
-
-#### `CACHE_VERSION` (constant)
+import { storageEstimate } from '@the_library/public/downloader';
 
-```typescript
-import { CACHE_VERSION } from '@the_library/public/downloader';
-// CACHE_VERSION = 1
+const { usage = 0, quota = 1 } = await storageEstimate();
+console.log(`${((usage / quota) * 100).toFixed(1)}% of storage in use`);
 ```
 
-#### `DL2_SW_VERSION` (constant)
-
-Service worker build version. Used internally to detect when the SW script has been updated.
-
 ---
 
-### Framework Adapters (`/downloader/{vue,react,solid}`)
+#### `DownloadQuotaExceededError`
 
-#### Vue Composables
+Thrown (rejected) when the browser refused to store a download because storage is full. It has a `txId` property. Use it to stop retrying and ask the user to free space, instead of treating it like a network error.
 
 ```typescript
-import {
-  useFileStatus,
-  useRenderStatus,
-  useGlobalProgress,
-  usePruning
-} from '@the_library/public/downloader/vue';
-
-// Reactive ref for one file's download state
-const status = useFileStatus(txId); // ComputedRef<FileState | undefined>
-
-// Reactive ref for render/page state
-const render = useRenderStatus(txId); // ComputedRef<RenderState | undefined>
+import { GetPdf, DownloadQuotaExceededError } from '@the_library/public/downloader';
 
-// Global download progress
-const progress = useGlobalProgress(); // ComputedRef<DownloadSummary>
-
-// LRU pruning activity
-const pruning = usePruning(); // ComputedRef<PruningState>
+try {
+  await GetPdf(txId);
+} catch (e) {
+  if (e instanceof DownloadQuotaExceededError) showStorageFullMessage(e.txId);
+  else throw e;
+}
 ```
 
-#### React Hooks
+---
 
-```typescript
-import {
-  useFileStatus,
-  useRenderStatus,
-  useGlobalProgress,
-  usePruning
-} from '@the_library/public/downloader/react';
+### Metadata & Storage
 
-// Synchronized external store hooks
-const status = useFileStatus(txId);       // FileState | undefined
-const render = useRenderStatus(txId);     // RenderState | undefined
-const progress = useGlobalProgress();     // DownloadSummary
-const pruning = usePruning();             // PruningState
-```
+#### `getBookData(txId: string): Promise<BookData | undefined>`
 
-#### Solid.js Primitives
+The page dimensions recorded once the PDF has been parsed, or `undefined` before that.
 
 ```typescript
-import {
-  useFileStatus,
-  useRenderStatus,
-  useGlobalProgress,
-  usePruning
-} from '@the_library/public/downloader/solid';
-
-// Solid createMemo/createSignal-based reactivity
-const [status] = useFileStatus(txId);
-const [render] = useRenderStatus(txId);
-const [progress] = useGlobalProgress();
-const [pruning] = usePruning();
+interface BookData {
+  txId: string;
+  dimensions: Array<{ width: number; height: number }>; // one entry per page
+  parsed: boolean;
+}
 ```
 
 ---
 
-### Service Worker API (`@the_library/public/downloader/sw`)
-
-Installs a service worker that intercepts PDF/image requests, serving cached responses offline and persisting downloads across tab reloads.
+### Download State
 
-#### `registerDownloaderSW(): Promise<ServiceWorkerState>`
+#### `downloadState`
 
-Registers (or reuses) the downloader service worker.
+The synchronous store behind every framework adapter: the state of each file, the pages rendered for each book, and pruning activity.
 
 ```typescript
-import { registerDownloaderSW } from '@the_library/public/downloader/sw';
-
-const state = await registerDownloaderSW();
-if (state.active) {
-  console.log('Service worker active and controlling pages');
-}
-```
+import { downloadState } from '@the_library/public/downloader';
 
-**Parameters:** None
+const unsubscribe = downloadState.subscribe((changedKey) => { /* re-read what you show */ });
 
-**Returns:** `Promise<ServiceWorkerState>`
+downloadState.get(txId);        // FileState
+downloadState.getRender(txId);  // RenderState: { bookData?, pages: Map<page, FilePhase> }
+downloadState.summary();        // { active, queued, loaded, total } across all files
+downloadState.pruning;          // PruningState: { active, freedBytes, removedCount }
+```
 
-**Type: `ServiceWorkerState`**
 ```typescript
-interface ServiceWorkerState {
-  registered: boolean;     // SW is registered
-  active: boolean;         // SW is controlling this page
-  waiting: boolean;        // Update pending
-  installing: boolean;     // New registration in progress
-  controller: ServiceWorkerContainer | null;
+type FilePhase = 'unknown' | 'queued' | 'downloading' | 'done' | 'error';
+
+interface FileState {
+  phase: FilePhase;
+  loaded?: number;  // bytes so far
+  total?: number;   // bytes, when known
+  error?: string;
 }
 ```
 
+Progress is also announced as window events, `ARWEAVE_DOWNLOAD_PROGRESS` (`detail: DownloadProgressDetail` — `{ txId, loaded, total? }`) and `ARWEAVE_DOWNLOAD_DONE` (`detail: DownloadDoneDetail` — `{ txId, mime: 'pdf' | 'preview' }`).
+
 ---
 
-#### `swStatus(): Promise<ServiceWorkerState>`
+### Keys & Naming
 
-Checks current service worker status without re-registering.
+The cache names and keys, for code that reads Cache Storage directly (the service worker does):
 
 ```typescript
-import { swStatus } from '@the_library/public/downloader/sw';
+import { CACHES, CACHE_VERSION, pdfKey, previewKey, pageKey } from '@the_library/public/downloader';
 
-const state = await swStatus();
+CACHES;              // { pdf: 'dl2-pdf-v1', preview: 'dl2-preview-v1', pages: 'dl2-pages-v1' }
+CACHE_VERSION;       // 1
+pdfKey(txId);        // '/ar/<txId>'  (in CACHES.pdf)
+previewKey(txId);    // '/ar/<txId>'  (in CACHES.preview)
+pageKey(txId, 5);    // '/pages/<txId>/5'
 ```
 
-**Parameters:** None
-
-**Returns:** `Promise<ServiceWorkerState>`
+`DL2_SW_VERSION` is the build's version stamp for the service worker.
 
 ---
 
-#### `clearDownloaderCaches(): Promise<void>`
+### Framework Adapters (`/downloader/{vue,react,solid}`)
 
-Drops all Cache API entries (PDFs, page images, previews), but keeps IndexedDB metadata records intact.
+The same four hooks in each framework, wrapping `downloadState`:
 
 ```typescript
-import { clearDownloaderCaches } from '@the_library/public/downloader/sw';
+import { useFileStatus, useRenderStatus, useGlobalProgress, usePruning } from '@the_library/public/downloader/vue';
 
-await clearDownloaderCaches();
-console.log('Cache storage cleared, IndexedDB preserved');
+const status   = useFileStatus(txId);    // ComputedRef<FileState>
+const render   = useRenderStatus(txId);  // ComputedRef<RenderState>
+const progress = useGlobalProgress();    // ComputedRef<{ active, queued, loaded, total }>
+const pruning  = usePruning();           // ComputedRef<PruningState>
 ```
 
-**Parameters:** None
-
-**Returns:** `Promise<void>`
+- `@the_library/public/downloader/react` returns the values themselves (`FileState`, `RenderState`, …), re-rendering on change.
+- `@the_library/public/downloader/solid` returns accessors: `const status = useFileStatus(txId); status().phase`.
 
 ---
 
-#### `nukeDownloaderStorage(): Promise<void>`
+### Service Worker API (`@the_library/public/downloader/sw`)
+
+An optional service worker (`/dl2-sw.js`, registered with scope `/`) answers same-origin `GET` requests for `/ar/<txId>` (a PDF or cover) and `/pages/<txId>/<n>` (a rendered page) from Cache Storage, fetching `/ar/` files from Arweave when they aren't cached yet. Plain `<img src="/ar/…">` and `<iframe src="/ar/…">` tags then work offline. Add `?dl2-bypass=1` to a URL to skip the service worker for that request.
+
+#### `registerDownloaderSW(opts?: SwGateOptions): Promise<SwStatus>`
 
-Full reset: deletes everything — Cache API entries, IndexedDB records, service worker registration. Use when the user logs out or to recover storage quota.
+Registers the service worker, unless something stops it; `reason` in the result says what:
+
+- the page's host isn't in `allowedOrigins` (default `['datapond.earth', 'localhost']`, subdomains included) → `'origin-not-allowed'`;
+- in development (`import.meta.env.DEV`), only when `enableInDev: true` **and** `localStorage['dl2:sw'] === 'on'` → otherwise `'dev-mode'`;
+- kill switches: `?dl2-sw=off` in the URL or `localStorage['dl2:sw'] = 'off'` unregisters it (`'kill-switch-off'`); `?dl2-sw=purge` also erases all downloader storage (`'kill-switch-purge'`).
 
 ```typescript
-import { nukeDownloaderStorage } from '@the_library/public/downloader/sw';
+import { registerDownloaderSW } from '@the_library/public/downloader/sw';
 
-await nukeDownloaderStorage();
-console.log('All download data erased');
+const status = await registerDownloaderSW({ allowedOrigins: ['example.org'] });
+if (!status.registered) console.info('Downloader SW not active:', status.reason);
 ```
 
-**Parameters:** None
+```typescript
+interface SwGateOptions { allowedOrigins?: string[]; enableInDev?: boolean }
 
-**Returns:** `Promise<void>`
+interface SwStatus {
+  supported: boolean;    // the browser has service workers
+  registered: boolean;
+  controlling: boolean;  // a service worker controls this page
+  scope?: string;
+  version?: string;
+  reason?: string;       // why it isn't registered
+}
+```
 
----
+#### `swStatus(): Promise<SwStatus>`
 
-#### `unregisterDownloaderSW(): Promise<void>`
+The current status, without registering anything.
 
-Unregisters the service worker.
+#### `unregisterDownloaderSW(opts?: { clearCaches?: boolean; reload?: boolean }): Promise<boolean>`
 
-```typescript
-import { unregisterDownloaderSW } from '@the_library/public/downloader/sw';
+Unregisters the service worker; resolves `true` if one was removed. `clearCaches` also deletes the downloader's caches; `reload` reloads the page if a worker was removed.
 
-await unregisterDownloaderSW();
-```
+#### `clearDownloaderCaches(): Promise<void>`
 
-**Parameters:** None
+Deletes every downloader cache (all Cache Storage entries named `dl2-…`). IndexedDB records are kept.
+
+#### `nukeDownloaderStorage(): Promise<void>`
 
-**Returns:** `Promise<void>`
+Full reset: unregisters the service worker, deletes the caches, and deletes the downloader's IndexedDB database.
 
 ---
 
 ## 2. Models API (`@the_library/public/models`)
 
-The Models API provides the in-memory ORM, record cache, patch/replay engine, and schema registry for Sanctuary's data model. The root subpath exports only the framework-agnostic core; session bootstrap and reactive views are framework-specific and live under `/models/{vue,react,solid,astro}`.
+The Models API provides the in-memory ORM, record cache, patch/replay engine, and schema registry for the library's data model. The root subpath exports only the framework-agnostic core; session bootstrap and reactive views are framework-specific and live under `/models/{vue,react,solid,astro}`.
 
 ### Language Semantics (every value is per-language)
 
@@ -794,38 +593,39 @@ Why:
 
 ### Core Types & Registry
 
-#### `Registry` (singleton, exported from `registry.ts`)
+#### `Registry` (singleton)
 
-Holds enriched `ModelDefinition` for every registered object type — property IDs, field schemas, and relations.
+Holds the `ModelDefinition` of every model type: its props, instance fields and relations, as compiled from `@the_library/canonical-schemas`.
 
 ```typescript
 import { Registry, type ModelDefinition } from '@the_library/public/models';
+import { Book } from '@the_library/public/models/models';
 
-// Get schema by numeric type ID
 const bookSchema: ModelDefinition = Registry.get(Book.type);
-// bookSchema.name, bookSchema.typePrefix, bookSchema.props, bookSchema.instanceFields, ...
-
-// Get schema by class name
-const byName = Registry.getByName('Book');
+const byName = Registry.getByName('Book'); // ModelDefinition | undefined
 ```
 
 **Methods:**
 
-- `Registry.get(typeId: number): ModelDefinition` — Returns the enriched schema for a type. Throws if `typeId` is not registered.
-
-- `Registry.getByName(name: string): ModelDefinition` — Returns the schema for a named type (e.g., 'Book'). Throws if no type with that name is registered.
-
-- `Registry.all(): ModelDefinition[]` — Returns all registered type schemas.
+- `Registry.get(id: number): ModelDefinition` — the schema for a type ID. An unknown ID logs a warning and returns an empty `Generic` placeholder.
+- `Registry.getByName(name: string): ModelDefinition | undefined` — the schema for a model name such as `'Book'`.
+- `Registry.register(schema: ModelDefinition): void` and `Registry.clear(): void` — used by the generated models and by tests.
 
 **Type: `ModelDefinition`**
 ```typescript
 interface ModelDefinition {
-  name: string;                        // e.g., 'Book'
-  type: number;                        // numeric type ID
-  typePrefix: string;                  // e.g., 'B' for Book
-  props: PropertyDefinition[];          // field schemas
-  instanceFields: InstanceFieldInfo[]; // relation/reference fields
-  relations: RelationDefinition[];
+  name: string;                         // e.g. 'Book'
+  typePrefix: string;
+  objectId: number;                     // the numeric type ID (Book.type)
+  multipleInstances: boolean;
+  uidStrategy?: string | string[];
+  instanceUidStrategy?: string | string[];
+  isPrivate?: boolean;                  // default true: creation patches are hidden from public reads
+  standardPks?: Record<string, string>;
+  props: SchemaProp[];
+  instanceFields: SchemaInstanceField[];
+  relations: SchemaRelation[];
+  indexes?: SchemaIndex[];
 }
 ```
 
@@ -833,204 +633,128 @@ interface ModelDefinition {
 
 ### Record Cache & Reactivity
 
-#### `configureDb(options?: { cacheLimit?: number }): void`
+Loaded records live in an in-memory LRU cache, one per model type. Record IDs are `bigint` (`uid`). Every function below takes an optional `creatorUsername`. Canonical records are shared by everyone; user-created records (IDs with the top bit set) are kept per creator, and without `creatorUsername` the default set with `setDefaultCreatorUsername()` is used (an error if none is set; `hasRecord` returns `false` instead).
+
+#### `configureDb(opts: { cacheLimit?: number }): void`
 
-Sets the in-memory LRU cache size. Call before loading any records.
+Sets how many records of each type the cache keeps (default `10000`). Call it before loading records.
 
 ```typescript
 import { configureDb } from '@the_library/public/models';
 
-// Lower cache limit for mobile devices
-configureDb({ cacheLimit: 500 });
+configureDb({ cacheLimit: 2000 }); // e.g. on mobile
 ```
 
-**Parameters:**
-- `options.cacheLimit?: number` — Maximum number of records to hold in memory. Default is `2000`. Older records are evicted when the limit is exceeded.
-
-**Returns:** `void`
-
 ---
 
-#### `getRecord(typeId: number, id: string): any`
+#### `getRecord(objectType: number, id: bigint, creatorUsername?: string): any`
 
-Synchronously retrieves a record from the cache.
+Returns a cached record synchronously. **Throws** if it isn't in the cache (never loaded, or evicted); check with `hasRecord`, or load it with the model's `LoadAsync`.
 
 ```typescript
-import { getRecord } from '@the_library/public/models';
-import { Book } from '@the_library/public/models';
+import { getRecord, hasRecord } from '@the_library/public/models';
+import { Book } from '@the_library/public/models/models';
 
-if (hasRecord(Book.type, bookId)) {
-  const book = getRecord(Book.type, bookId);
-  console.log(book.title);
-}
+const book = hasRecord(Book.type, bookId) ? getRecord(Book.type, bookId) : await Book.LoadAsync(bookId);
 ```
 
-**Parameters:**
-- `typeId: number` — The model type ID (e.g., `Book.type`).
-- `id: string` — The record UID.
-
-**Returns:** The record object (e.g., a `Book` instance) if cached.
-
-**Throws:** If the record is not in cache (LRU eviction or never loaded). Use `hasRecord()` to check first, or call the model's `LoadAsync()` method to load from disk.
-
 ---
 
-#### `addRecord(typeId: number, id: string, record: any): void`
-
-Adds or updates a record in the cache.
-
-```typescript
-import { addRecord } from '@the_library/public/models';
-
-addRecord(Book.type, bookId, bookInstance);
-```
-
-**Parameters:**
-- `typeId: number` — Model type ID.
-- `id: string` — Record UID.
-- `record: any` — The record object.
+#### `addRecord(objectType: number, obj: { id: bigint }, creatorUsername?: string): void`
 
-**Returns:** `void`
+Puts a record object into the cache (replacing one with the same `id`).
 
 ---
 
-#### `removeRecord(typeId: number, id: string): void`
-
-Removes a record from the cache.
-
-```typescript
-import { removeRecord } from '@the_library/public/models';
-
-removeRecord(Book.type, bookId);
-```
-
-**Parameters:**
-- `typeId: number` — Model type ID.
-- `id: string` — Record UID.
+#### `removeRecord(objectType: number, id: bigint, creatorUsername?: string): void`
 
-**Returns:** `void`
+Drops a record from the cache.
 
 ---
 
-#### `hasRecord(typeId: number, id: string): boolean`
-
-Checks if a record is currently cached.
-
-```typescript
-import { hasRecord } from '@the_library/public/models';
-
-if (hasRecord(Book.type, bookId)) {
-  // safe to call getRecord()
-}
-```
-
-**Parameters:**
-- `typeId: number` — Model type ID.
-- `id: string` — Record UID.
+#### `hasRecord(objectType: number, id: bigint, creatorUsername?: string): boolean`
 
-**Returns:** `boolean`
+Whether the record is in the cache right now.
 
 ---
 
-#### `pinRecord(typeId: number, id: string): void`
+#### `pinRecord(objectType: number, id: bigint, creatorUsername?: string, reason?: string): void`
 
-Pins a record so it won't be evicted from the LRU cache. Use for the currently-open record, search results, etc.
+Keeps a record in the cache until it is unpinned, e.g. the book that's open. A record stays pinned while any `reason` (default `'lifecycle'`) still pins it, so independent callers use different reasons; pinning twice with the same reason needs only one unpin.
 
 ```typescript
-import { pinRecord } from '@the_library/public/models';
+import { pinRecord, unpinRecord } from '@the_library/public/models';
 
-// User opened a book — don't evict it while they're reading
-pinRecord(Book.type, openBookId);
+pinRecord(Book.type, openBookId, undefined, 'reader');
+// when the reader closes:
+unpinRecord(Book.type, openBookId, undefined, 'reader');
 ```
 
-**Parameters:**
-- `typeId: number` — Model type ID.
-- `id: string` — Record UID.
-
-**Returns:** `void`
-
 ---
 
-#### `unpinRecord(typeId: number, id: string): void`
+#### `unpinRecord(objectType: number, id: bigint, creatorUsername?: string, reason?: string): void`
 
-Unpins a record so it can be evicted again.
-
-```typescript
-import { unpinRecord } from '@the_library/public/models';
-
-// User closed the book
-unpinRecord(Book.type, openBookId);
-```
-
-**Parameters:**
-- `typeId: number` — Model type ID.
-- `id: string` — Record UID.
-
-**Returns:** `void`
+Removes a pin added with the same `reason`; the record can then be evicted again.
 
 ---
 
-#### `addReactivitySystem(system: ReactivitySystem): void`
+#### `addReactivitySystem(sys: ReactivitySystem): () => void`
 
-Installs a framework-agnostic reactivity hook that fires when records change. Framework adapters call this once at boot.
+Registers a reactivity system and returns a function that unregisters it. Several can be registered at once (one per framework); the framework adapters' `install…Reactivity()` functions call this for you.
 
 ```typescript
 import { addReactivitySystem } from '@the_library/public/models';
 
-addReactivitySystem({
-  track: (typeId, id) => { /* called when record added/changed */ },
-  trigger: (typeId, id) => { /* called when record needs re-render */ },
+const remove = addReactivitySystem({
+  track: (obj) => { /* a record was read: subscribe to it */ },
+  trigger: (obj) => { /* a record changed: re-render its readers */ },
 });
 ```
 
 ---
 
-#### `setReactivitySystem(system: ReactivitySystem): void`
+#### `setReactivitySystem(sys: ReactivitySystem | null): void`
 
-Replaces the current reactivity system. Typically called by framework adapters during initialization.
+Replaces all registered systems with `sys`, or removes them all with `null`. Meant for single-framework apps and tests; use `addReactivitySystem` when frameworks coexist.
 
 ---
 
 ### Generated Models
 
-Generated model classes (e.g., `Book`, `Person`, `Tag`) are built from your schema via `pnpm generate` and exported from both the root (`@the_library/public/models`) and the dedicated `/models/models` subpath.
+The model classes (`Book`, `Person`, `Tag`, `ClassificationSystem`, `Post`) are generated from `@the_library/canonical-schemas` and exported from `@the_library/public/models/models` (and from `@the_library/public/models`). Every value is read and written per language (see [Language Semantics](#language-semantics-every-value-is-per-language)).
 
 ```typescript
-import { Book, Person, NewBookWithId, ModelTypes } from '@the_library/public/models';
-// equivalently: from '@the_library/public/models/models'
+import { Book, NewBookWithId, ModelTypes } from '@the_library/public/models/models';
 
-// Create a new record in memory (not yet persisted)
-const book = NewBookWithId('book:abc123', 'username');
-book.title = 'A Study in Scarlet';
-book.author = 'Sir Arthur Conan Doyle';
+// Load a record (from the cache, or IndexedDB / the network when it isn't cached)
+const book = await Book.LoadAsync(bookId);          // bookId: bigint
+book.getTitle('eng');
 
-// Load an existing record from disk
-const loaded = await Book.LoadAsync('book:abc123');
+// Synchronous access when it's known to be cached
+if (Book.Has(bookId)) Book.Load(bookId);
 
-// Check type at runtime
-if (loaded instanceof Book) {
-  console.log('It is a book');
-}
+// Create a record in memory and edit it
+const draft = NewBookWithId(newId);
+draft.setTitle('A Study in Scarlet', 'eng');
+draft.validateIsbn();                                // one validate<Standard>() per standard the model uses
 
-// Generic record hydration (type unknown at compile time)
-const typeId = 10; // some numeric type
-const RecordClass = ModelTypes[typeId];
-const generic = new RecordClass();
+// Model class by numeric type ID
+const BookClass = ModelTypes[Book.type];
 ```
 
-**Key Functions:**
-
-- `NewBookWithId(id: string, creatorUsername: string): Book` — Factory to create a new Book record in memory.
+**Key members:**
 
-- `Book.LoadAsync(id: string): Promise<Book>` — Loads a Book by UID from IndexedDB.
-
-- `ModelTypes: { [typeId: number]: typeof ModelClass }` — Maps numeric type IDs to model classes.
+- `Book.type: number` — the model's type ID.
+- `Book.LoadAsync(id: bigint, creatorUsername?: string): Promise<Book>`, `Book.Load(id, creatorUsername?): Book` (throws when not cached) and `Book.Has(id, creatorUsername?): boolean`.
+- `NewBookWithId(id: bigint, creatorUsername?: string): Book` — a new record in memory; `NewPersonWithId`, `NewTagWithId`, `NewClassificationSystemWithId` and `NewPostWithId` work the same way.
+- `get<Prop>(lang)` / `set<Prop>(value, lang)` for every prop, e.g. `getCopyrightStatus('eng')`; the plain property (`book.title`, `book.copyrightStatus`) reads and writes the default language.
+- `ModelTypes: Record<number, ModelClass>` — model classes by type ID.
 
 ---
 
 ### Schema Registry
 
-The `Registry` singleton (above) holds `ModelDefinition` for each type. Accessed via `Registry.get(typeId)` or `Registry.getByName(name)`.
+The `Registry` singleton ([above](#registry-singleton)) holds the `ModelDefinition` of each type: `Registry.get(typeId)` or `Registry.getByName(name)`.
 
 ---
 
@@ -1069,7 +793,7 @@ const unsubscribe = trashStore.subscribe(Tag.type, () => {
 
 **Methods:**
 
-- `trashStore.list(objectType: number, usernames?: string[]): number[]` — Merges trashed ids across `usernames`. Empty array (default) merges **every** bucketed username for that type.
+- `trashStore.list(objectType: number, usernames?: string[]): uid[]` — Merges trashed ids across `usernames`. Empty array (default) merges **every** bucketed username for that type.
 
 - `trashStore.count(objectType: number, usernames?: string[]): number` — Same merge semantics as `list()`; returns the count.
 
@@ -1082,7 +806,7 @@ const unsubscribe = trashStore.subscribe(Tag.type, () => {
 **Type: `TrashStore`**
 ```typescript
 interface TrashStore {
-  list(objectType: number, usernames?: string[]): number[];
+  list(objectType: number, usernames?: string[]): uid[];
   count(objectType: number, usernames?: string[]): number;
   usernames(objectType: number): string[];
   subscribe(objectType: number, listener: () => void): () => void;
@@ -1103,7 +827,12 @@ Full (re)scan — walks every currently-hydrated record and reconciles trash mem
 
 ### Stats & Local Analytics
 
-Per-record engagement tracking (visits, downloads, ratings, shares) for any object type. Stats are **local-only** — they use the same patch/queue/IndexedDB pipeline as everything else in `models_v2`, but are never serialized to the EVM and never leave the device. There is no server-side aggregation; each device's `StatsStore` is a private, ephemeral index rebuilt from that device's own patch history on every boot.
+Per-record engagement tracking (visits, downloads, ratings, shares) for any object type. Each action is applied to the in-memory `StatsStore` at once and queued like any other edit; on the next save it goes to the chain (all except `VisitPart`, which stays on the device):
+
+- **Under the reader's account** — the action words are stored with the rest of the save in `BackupStorage`, so they are public under that account's identity (an account, not a real name) and come back to the reader's other devices when the save is restored.
+- **Aggregated, without user IDs** — `Factory.save()` also feeds them to `StatsPivotStorage`, a global weekly pivot of visit, download, rating and share counts per record, with no user ID.
+
+`StatsStore` itself is a per-device index, rebuilt on every boot from the patches in IndexedDB (local and restored).
 
 ```typescript
 import { Stats, PopulateStatsStore, DownloadsByType, VisitsByType, FavoritesByTypes } from '@the_library/public/models';
@@ -1111,7 +840,7 @@ import { Stats, PopulateStatsStore, DownloadsByType, VisitsByType, FavoritesByTy
 
 **Why this exists / how it fits the patch pipeline:**
 - `Orm` (the base class every generated model — `Book`, `Tag`, `Person`, ... — extends) **also extends `Stats`**. So `book.visit()`, `book.download()`, `book.rating = Rating.Keep`, `book.ratePart(3, Rating.Keep)`, `book.share(socialMediaId)`, and `book.favoriteParts()` are available directly on every record with no separate lookup step.
-- Each call builds a `LocalOp` (discriminated by `action: ActionTypes`, not `operation: PatchOperation` like EVM patches — see `isEvmPatch()` in `interfaces.ts`), applies it to the in-memory `StatsStore` immediately, and pushes it through `PatchInstance.addPatch()` so it is queued and persisted to IndexedDB exactly like a property edit — just never included when patches are serialized for chain submission.
+- Each call builds a `LocalOp` (discriminated by `action: ActionTypes`, not `operation: PatchOperation` like EVM patches — see `isEvmPatch()` in `interfaces.ts`), applies it to the in-memory `StatsStore` immediately, and pushes it through `PatchInstance.addPatch()` so it is queued and persisted to IndexedDB exactly like a property edit. When patches are serialized for the chain, `localOpToActionPatch()` turns it into an `ActionOperation` word (`VisitPart` has no opcode left and stays local); `actionPatchToLocalOp()` reverses this for restored saves.
 - On boot, `InitPatchWorker()` (`worker-patch-main.ts`) loads every locally-stored patch for the current user, filters to the non-EVM ones (`!isEvmPatch(p)`), and replays them through `PopulateStatsStore()` to reconstruct `StatsStore` from scratch — the module-level `Map` holds nothing across a page reload until this runs.
 
 #### `StatsStore` (internal, not exported)
@@ -1204,7 +933,7 @@ type StatSummary = {
 }
 ```
 
-**Type: `ActionTypes`** (local-only op discriminator — do not confuse with EVM `PatchOperation`)
+**Type: `ActionTypes`** (local op discriminator — do not confuse with EVM `PatchOperation`; on the chain these become `ActionOperation` words)
 ```typescript
 enum ActionTypes {
   Visit = 0,
@@ -1234,253 +963,119 @@ enum Rating {
 
 ### Framework Adapters (`/models/{vue,react,solid,astro}`)
 
-#### Vue Composables
+Each adapter exports the session functions below plus that framework's reactive views. The session functions are the same in all four:
 
-```typescript
-import {
-  bootstrapModelsV2,
-  useLevel,
-  useDraft,
-  useTrash,
-  resetModelsV2Session
-} from '@the_library/public/models/vue';
-```
+| Export | Vue | React | Solid | Astro |
+|---|---|---|---|---|
+| `bootstrapModelsV2`, `resetModelsV2Session`, `clearLocalPatches`, `loadSearch` | ✓ | ✓ | ✓ | ✓ |
+| `install…Reactivity` | `installVueReactivity` | `installReactReactivity` | `installSolidReactivity` | `installVanillaReactivity` |
+| `useLevel`, `useTrash` | ✓ | ✓ | ✓ | — |
+| `useDraft` | ✓ | — | ✓ | — |
+| other | `useBookSearch`, `useStatsTick` | `useModelUpdate` | `getAllPatches`, `hasPartition`, `loadPartition` | `subscribeRecord` |
 
-**`bootstrapModelsV2(options: BootstrapOptions): Promise<void>`**
+#### `bootstrapModelsV2(opts: SessionBootstrapOptions): Promise<void>`
 
-Initializes the models subsystem once at app boot. Idempotent across Astro `<ClientRouter />` navigations.
+Starts the models session once at app boot: loads the corpus into the patch worker and hydrates the records. Calling it again (for example on every Astro `<ClientRouter />` navigation) doesn't boot twice.
 
 ```typescript
+import { bootstrapModelsV2 } from '@the_library/public/models/vue';
+import { Book, NewBookWithId } from '@the_library/public/models/models';
+
 await bootstrapModelsV2({
-  userLang: 'en',
-  models: [{ type: Book.type, create: NewBookWithId }],
-  localMode: '/corpus_v2',  // OR registry: { dataBlock, gateway }
-  onBoot: (data) => console.log(`booted ${data.sidecars.length} sidecars`),
+  userLang: 'eng',
+  models: [{ type: Book.type, create: (id) => NewBookWithId(id) }],
+  localMode: '/corpus_v2',            // or: registry: { dataBlock, gateway }
+  onBoot: (data) => { /* booted */ },
 });
 ```
 
-**Parameters:**
-- `userLang: string` — User's preferred language (ISO 639-1 or custom code).
-- `models: ModelFactory[]` — Array of `{ type: number; create: (id, username) => ModelInstance }`.
-- `localMode?: string` — Folder path to serve corpus from (dev mode, mutually exclusive with `registry`).
-- `registry?: { dataBlock: string; gateway: string }` — Arweave data block & gateway (production mode).
-- `onBoot?: (data: BootData) => void` — Callback fired when bootstrap completes.
+**`SessionBootstrapOptions`:**
+- `userLang: Lang` — the user's language.
+- `models: ModelFactory[]` — `{ type: number; create: (id: bigint) => Orm }` for each model to hydrate.
+- `selectedLangs?: Lang[]` — further languages to load.
+- `localMode?: string` / `localManifest?: LocalCorpusIndex` — serve the corpus from a local folder holding `bin/` and `corpus-index.json` (development, book-manager). When set, `registry` is ignored.
+- `registry?: { dataBlock: RegistryDataBlock; gateway?: string }` — load it from Arweave, as published in the registry manifest (production).
+- `workerPath?: string | URL` — URL of the patch worker (default `/patch-worker.js`).
+- `loadAiSidecars?: boolean` — also load the AI results sidecars.
+- `search?: boolean` — load the Book search index in the background after boot (default `true`; never blocks or fails boot).
+- `onBoot?(data)`, `onBootError?(err)`, `init?()`, `onNavigate?()` — lifecycle callbacks.
 
-**Returns:** `Promise<void>` — resolves once all sidecars are hydrated.
+#### `resetModelsV2Session(): void`
 
----
+Clears the session and the cached level state, for logout and tests/HMR.
 
-**`useLevel(username?: string): Ref<LevelData>`**
+#### `clearLocalPatches()`
 
-Reactive per-username level state and corpus metadata.
+Deletes every locally queued, unsaved edit from IndexedDB (for all users) — "discard my local edits". Reload the page right after it.
 
-```typescript
-import { useLevel } from '@the_library/public/models/vue';
+#### `loadSearch(lang?: Lang): Promise<void>`
 
-const { level, progress } = useLevel('alice').value;
-console.log(`Alice's level: ${level}`);
-```
+Starts (or retries) loading the search index for a language. Boot starts it on its own when `search` is enabled.
 
-**Parameters:**
-- `username?: string` — Username. Defaults to the currently-logged-in user.
+---
 
-**Returns:** `Ref<LevelData>`
+#### `useLevel(username: string)`
+
+The user's level: `{ level, progress, points }` (`level` starts at 1, `progress` is 0–100 toward the next level). Vue returns a `ComputedRef<LevelState>`, React the `LevelState`, Solid an `Accessor<LevelState>`.
 
-**Type: `LevelData`**
 ```typescript
-interface LevelData {
-  username: string;
-  level: number;
-  progress: number; // 0-1
-  lastUpdated: number; // timestamp
-}
+import { useLevel } from '@the_library/public/models/vue';
+
+const level = useLevel(username);
+level.value.level;
 ```
 
 ---
 
-**`useDraft(getter: () => ModelInstance): { draft, isDirty, commit, rollback }`**
+#### `useDraft(model)`
 
-Tracks edits to a model instance before committing them back to the original.
+Edits a record on a copy, then applies or discards the changes. Vue takes a `Ref` or a getter; Solid a getter.
 
 ```typescript
 import { useDraft } from '@the_library/public/models/vue';
 
 const { draft, isDirty, commit, rollback } = useDraft(() => book);
-
-// Edit the draft
 draft.value.title = 'New Title';
-
-// Check if unsaved changes exist
-if (isDirty.value) {
-  await commit(); // apply to original book
-  // or rollback() to discard
-}
+if (isDirty.value) commit(); // or rollback()
 ```
 
-**Parameters:**
-- `getter: () => ModelInstance` — A function returning the record to edit (usually a computed ref).
-
-**Returns:** 
-```typescript
-{
-  draft: Ref<ModelInstance>;  // editable proxy of the original
-  isDirty: Ref<boolean>;      // true if any properties differ
-  commit: () => Promise<void>; // apply changes to original
-  rollback: () => void;        // discard changes
-}
-```
+Returns `{ draft, isDirty, commit: () => void, rollback: () => void }` (`ComputedRef`s in Vue, accessors in Solid).
 
 ---
 
-**`useTrash(objectType: number, usernames?: string[]): { count: Ref<number>; getIds: () => number[] }`**
+#### `useTrash(objectType: number, usernames?: string[])`
 
-Reactive view over the global [Trash Index](#trash-index) for one object type, merged across `usernames`. Population and live updates are entirely automatic — nothing to register, nothing to feed it.
+A live view of the [Trash Index](#trash-index) for one model type, merged across `usernames` (default `[]`: every known username). It fills and updates itself.
 
 ```typescript
 import { useTrash } from '@the_library/public/models/vue';
 import { Tag } from '@the_library/public/models/models';
 
-const { count, getIds } = useTrash(Tag.type); // merges every username (canonical catalog trash)
-```
-
-**Parameters:**
-- `objectType: number` — Model type ID (e.g. `Tag.type`).
-- `usernames?: string[]` — Usernames to merge. Defaults to `[]` (every known username — see the `'canonical'` vs `'mine'` note in [Trash Index](#trash-index)).
-
-**Returns:**
-```typescript
-{
-  count: Ref<number>;
-  getIds: () => number[];
-}
-```
-
----
-
-**`resetModelsV2Session(): void`**
-
-Clears the session and cached level state. Used for logout and testing/HMR.
-
-```typescript
-import { resetModelsV2Session } from '@the_library/public/models/vue';
-
-resetModelsV2Session();
-```
-
----
-
-#### React Hooks
-
-Same API as Vue, but exported from `@the_library/public/models/react`:
-
-```typescript
-import {
-  bootstrapModelsV2,
-  useLevel,
-  useModelUpdate,
-  useTrash,
-  resetModelsV2Session
-} from '@the_library/public/models/react';
-```
-
-**`useLevel(username?: string): LevelData`**
-
-Hook returning the current level data. Re-renders when level changes.
-
-**`useModelUpdate(record: ModelInstance): boolean`**
-
-Subscribes to updates for a single record, triggering re-render on change. Returns `true` if subscription is active.
-
-**`useTrash(objectType: number, usernames?: string[]): { count: number; getIds: () => number[] }`**
-
-Re-renders the calling component whenever the global [Trash Index](#trash-index) changes for `objectType`, merged across `usernames` (defaults to `[]` — every known username). Population and live updates are entirely automatic.
-
-```typescript
-import { useTrash } from '@the_library/public/models/react';
-import { Tag } from '@the_library/public/models/models';
-
-const { count, getIds } = useTrash(Tag.type);
-```
-
-**Note:** React does **not** export `useDraft` (no fine-grained reactivity primitive like Vue's `Ref`). Use manual imperative edits or a state manager instead.
-
----
-
-#### Solid.js Primitives
-
-```typescript
-import {
-  bootstrapModelsV2,
-  useLevel,
-  subscribeRecord,
-  useTrash,
-  resetModelsV2Session
-} from '@the_library/public/models/solid';
+const { count, getIds } = useTrash(Tag.type); // count: ComputedRef<number>, getIds(): bigint[]
 ```
 
-**`useLevel(username?: string): () => LevelData`**
-
-Signal factory returning the current level data.
-
-**`subscribeRecord(record: ModelInstance, callback: (record) => void): () => void`**
-
-Manual subscription to record updates. Returns unsubscribe function.
-
-**`useTrash(objectType: number, usernames?: string[]): { count: () => number; getIds: () => number[] }`**
-
-Signal accessor over the global [Trash Index](#trash-index) for one object type, merged across `usernames` (defaults to `[]` — every known username). Population and live updates are entirely automatic.
-
-```typescript
-import { useTrash } from '@the_library/public/models/solid';
-import { Tag } from '@the_library/public/models/models';
-
-const { count, getIds } = useTrash(Tag.type);
-return <span>{count()}</span>;
-```
+In React `count` is a number (the component re-renders on change), in Solid an accessor.
 
 ---
 
-#### Astro / Static Generation
-
-```typescript
-import {
-  bootstrapModelsV2,
-  resetModelsV2Session,
-  subscribeRecord
-} from '@the_library/public/models/astro';
-```
-
-**`bootstrapModelsV2(options): Promise<void>`**
-
-Same as Vue/React.
-
-**`subscribeRecord(record, callback): () => void`**
-
-Manual subscription (islands use this for client-side updates).
+#### Framework-specific views
 
-**Note:** Astro does **not** export `useLevel`, `useDraft`, or `useTrash` — use vanilla JS on the client (`trashStore` directly from `@the_library/public/models` works fine, it's framework-agnostic).
+- **`useBookSearch(options?)`** (Vue) — everything a search box needs over the Book search index: bind `text`, set `filters` and `sort`, read the results, which update as the user types and as the index changes. Results are record IDs: resolve them with `Book.Has(id)` / `Book.Load(id)`. Options: `lang`, `pageSize`, `facets`, `debounceMs`.
+- **`useStatsTick()`** (Vue) — a `ShallowRef<number>` that changes whenever the local stats change; read it inside a `computed` that uses `VisitsByType` / `DownloadsByType` / `FavoritesByTypes`.
+- **`useModelUpdate(record)`** (React) — re-renders the component when `record` changes. React can't track reads during render, so components subscribe to each record they show.
+- **`getAllPatches()`, `hasPartition(basePath)`, `loadPartition(…)`** (Solid) — list queued patches; check for and merge an extra local corpus partition (e.g. book-manager's `deleted/` archive) into the running session.
+- **`subscribeRecord(record, cb: () => void): () => void`** (Astro) — calls `cb` when `record` changes; returns the unsubscribe function. Astro has no `useLevel`, `useDraft` or `useTrash`: use `trashStore` from `@the_library/public/models` directly on the client.
 
 ---
 
 ### Patch & Session Management
 
-Low-level APIs (not normally called directly; used by `bootstrapModelsV2`):
+Low-level functions behind `bootstrapModelsV2` and saving; apps rarely call them:
 
-#### `serializePatches(patches: Patch[]): Uint8Array`
-
-Encodes patches to binary for transmission or storage.
-
-#### `deserializePatches(data: Uint8Array): Patch[]`
-
-Decodes binary patches.
-
-#### `applyRestoredPatches(patches: Patch[], models: ModelFactory[]): void`
-
-Applies a set of deserialized patches to the in-memory records.
-
-#### `getPatchInstanceByAccount(username: string): Patches`
-
-Retrieves the patch store for a specific account.
+- **`serializePatches(fromIndex: number, toIndex: number): Promise<EvmPayload>`** — packs the queued patches in that sequence window (`fromIndex` exclusive, `toIndex` inclusive) into the payload sent to the chain.
+- **`deserializePatches(username: string, payload: EvmPayload, source?: PatchSource): Promise<void>`** — unpacks a user's payload read from the chain and applies it.
+- **`applyRestoredPatches(ops: AnyPatch[], creatorUsername?: string): Promise<{ applied: number; skipped: number }>`** — replays operations onto the records in memory. Records not loaded yet are skipped; their operations stay in IndexedDB and apply when the record is next loaded. Safe to repeat.
+- **`getPatchInstanceByAccount(account: string): Patches`** — the patch queue of one account.
 
 ---
 
@@ -1514,7 +1109,13 @@ const unsubscribe = sessionStore.subscribe(() => {
 
 - `sessionStore.getState(): SessionState` — Returns current state: `{ active: Web3SessionAccount | null; known: Web3SessionAccount[] }`.
 
-- `sessionStore.subscribe(callback: () => void): () => void` — Registers a listener, returns unsubscribe function.
+- `sessionStore.subscribe(listener: () => void): () => void` — Registers a listener, returns unsubscribe function.
+
+- Writes: `setActive(account | null)`, `addKnown(account)`, `updateAccount(address, chainId, patch)`, `removeAccount(address, chainId)`, `clearAll()`, `updateProjectVotes(address, chainId, projectId, amount)`.
+
+- Save counters: `lastSyncCounters(address, chainId)` → `{ lastPatchIndex, lastRestorationIndex }`, `setLastSavedPatchIndex(…)`, `setLastRestorationIndex(…)`.
+
+- Persistence: `persist()` / `load()` write and read the known accounts in `localStorage`.
 
 **Type: `Web3SessionAccount`**
 ```typescript
@@ -1522,9 +1123,14 @@ interface Web3SessionAccount {
   account: string;              // hex address
   chainId: number;
   wallet: WalletType;           // 'metamask' | 'private_key'
-  username?: string;
-  userId?: number;
+  username: string;
+  userId: number;
   hasAccount: boolean;          // registered on-chain
+  lastPatchIndex: number;       // last local patch sequence saved to the chain
+  lastRestorationIndex: number; // last on-chain save restored on this device
+  country?: string;
+  language?: string;
+  lastUpdated?: number;         // when it was last read from the chain
   level?: number;
   projectBalance?: {
     contributions: number;
@@ -1532,31 +1138,29 @@ interface Web3SessionAccount {
     remaining: number;
   };
   donationsPerProject?: number[];
-  metadata?: {
-    country?: string;
-    language?: string;
-    lastSyncTime?: number;
-  };
 }
 ```
 
 ---
 
-#### `syncAccount(address: string, chainId: number, walletType: WalletType): Promise<Web3SessionAccount>`
+#### `syncAccount(address: string, chainId: number, wallet: WalletType, environment?: 'production' | 'staging', forceRefresh?: boolean): Promise<Web3SessionAccount>`
 
 Hydrates a wallet account after connection by pulling `hasAccount`, `username`, `level`, and other on-chain data. Also kicks off background subscription sync for the account's `userId`.
 
 ```typescript
+import { DEFAULT_CHAIN_ID } from '@the_library/network-config';
 import { syncAccount } from '@the_library/public/web3';
 
-const account = await syncAccount('0xabc...', 146, 'metamask');
+const account = await syncAccount('0xabc...', DEFAULT_CHAIN_ID, 'metamask');
 console.log(`${account.username} is level ${account.level}`);
 ```
 
 **Parameters:**
 - `address: string` — Wallet address (hex).
-- `chainId: number` — Chain ID (146, 14601, etc.).
-- `walletType: WalletType` — `'metamask'` or `'private_key'`.
+- `chainId: number` — Chain ID, e.g. `DEFAULT_CHAIN_ID` (production) or `DEFAULT_STAGING_CHAIN_ID` (testnet), both from `@the_library/network-config`.
+- `wallet: WalletType` — `'metamask'` or `'private_key'`.
+- `environment?: 'production' | 'staging'` — which deployment to read. Defaults to the session's environment (`getSessionEnvironment()`).
+- `forceRefresh?: boolean` — re-read the chain even if the account was already hydrated. Default `false`: an account already in `sessionStore` is returned as is.
 
 **Returns:** `Promise<Web3SessionAccount>` — The hydrated account record.
 
@@ -1569,19 +1173,7 @@ console.log(`${account.username} is level ${account.level}`);
 
 #### `useWeb3Session()` (Vue composable)
 
-Reactive wrapper over `sessionStore`.
-
-```typescript
-import { useWeb3Session } from '@the_library/public/web3/vue';
-
-const {
-  accounts,           // Ref<Web3SessionAccount[]> — all known accounts
-  registeredAccounts, // Ref<Web3SessionAccount[]> — only hasAccount=true
-  activeAccount,      // Ref<Web3SessionAccount | null>
-  isConnecting,       // Ref<boolean>
-  setActive,          // (account: Web3SessionAccount) => void
-} = useWeb3Session();
-```
+Reactive wrapper over `sessionStore`; see [3.10 Vue Composables](#useweb3session-useweb3sessionreturn).
 
 ---
 
@@ -1594,9 +1186,10 @@ Typed read and write adapters over deployed contracts.
 Gets the read-only client for a chain. Blocks until contract addresses/ABIs are loaded from the registry.
 
 ```typescript
+import { DEFAULT_CHAIN_ID } from '@the_library/network-config';
 import { getReadClient } from '@the_library/public/web3';
 
-const client = getReadClient(146);
+const client = getReadClient(DEFAULT_CHAIN_ID);
 await client.ready; // wait for registry load
 
 const balance = await client.projectManagerStorage.balanceOfAddress('0xabc...');
@@ -1605,7 +1198,7 @@ const nbAccounts = await client.bouncerStorage.nbAccounts();
 ```
 
 **Parameters:**
-- `chainId: number` — EVM chain ID (146, 14601, 84532, etc.).
+- `chainId: number` — EVM chain ID, e.g. `DEFAULT_CHAIN_ID` or `DEFAULT_STAGING_CHAIN_ID` from `@the_library/network-config`.
 - `environment?: 'production' | 'staging'` — Defaults to `'production'`. Use `'staging'` to read staging-deployed contract addresses.
 
 **Returns:** `ReadOnlyDomainAPI` — Typed interface to all contract reads.
@@ -1616,16 +1209,20 @@ interface ReadOnlyDomainAPI {
   readonly chainId: number;
   readonly ready: Promise<void>;
   readonly bouncerStorage: BouncerStorageReadAPI;
-  readonly archivistStorage: ArchivistStorageReadAPI;
   readonly scientistStorage: ScientistStorageReadAPI;
+  readonly archivistStorage: ArchivistStorageReadAPI;
   readonly projectManagerStorage: ProjectManagerStorageReadAPI;
   readonly factory: FactoryReadAPI;
+  readonly accountManager: AccountManagerReadAPI;
   readonly addressRegistry: AddressRegistryReadAPI;
   readonly subscriptionManager: SubscriptionManagerReadAPI;
   readonly libraryRegistryStorage: LibraryRegistryStorageReadAPI;
   readonly publicLibraryStorage: PublicLibraryStorageReadAPI;
+  readonly dSafeHRStorage: DSafeHRStorageReadAPI;
+  readonly relationshipIndexerStorage: RelationshipIndexerReadAPI;
   getUsdPrice(): Promise<number>;
   getRegistryStatus(): Promise<any>;
+  getNativeBalance(address: string): Promise<bigint>;
 }
 ```
 
@@ -1786,53 +1383,64 @@ If a transaction throws and the run-lock needs to be cleared manually, call `res
 
 #### Chain Metadata
 
-```typescript
-import { getChain, EVM_CHAINS, DEFAULT_CHAIN_ID } from '@the_library/public/web3';
+Chain metadata comes from `@the_library/network-config` (install it next to this package). `@the_library/public/web3` only adds `toViemChain`.
 
-const chain = getChain(146);
-// chain.name, chain.symbol, chain.shortName, chain.logo, chain.explorer, 
-// chain.rpc, chain.main (true for mainnet), chain.deployed, chain.stagingDeployed
+```typescript
+import { getChain, EVM_CHAINS, DEFAULT_CHAIN_ID, DEFAULT_STAGING_CHAIN_ID } from '@the_library/network-config';
+import { toViemChain } from '@the_library/public/web3'; // also at '@the_library/public/web3/network'
 
-const deployedChains = Object.values(EVM_CHAINS).filter(c => c.deployed);
+const chain = getChain(DEFAULT_CHAIN_ID);              // production chain (testnet: DEFAULT_STAGING_CHAIN_ID)
+const viemChain = toViemChain(chain);                  // viem `Chain` for createPublicClient & co.
+const deployedChains = Object.values(EVM_CHAINS).filter((c) => c.deployed);
 ```
 
 **Type: `EvmChainConfig`**
 ```typescript
 interface EvmChainConfig {
-  name: string;              // 'Sonic' | 'Sonic Blaze' | 'Base Sepolia'
-  shortName: string;         // 'TREE' | 'WATER' | ... (mainnet/testnet shorthand codenames, not the chain name)
   chainId: number;
-  symbol: string;            // 'S' | ...
-  logo: string;              // URL to chain logo
-  explorer: string;          // Block explorer URL
-  rpc: string[];             // RPC endpoints
-  main: boolean;             // Mainnet vs testnet
-  deployed: boolean;         // Contracts deployed on this chain
-  stagingDeployed?: boolean;
+  name: string;                 // e.g. 'Gnosis Mainnet'
+  symbol: string;               // native coin, e.g. 'XDAI'
+  shortName: string;            // 'TREE' (mainnet) | 'WATER' (testnet): codenames, not the chain name
+  decimals: number;
+  explorer: string;             // block explorer URL
+  rpc: string;                  // RPC endpoint
+  website: string;
+  main: boolean;                // mainnet or testnet
+  brand: string;                // brand name, e.g. 'GNOSIS'
+  price: ChainPrice;            // { stable: true } (coin = $1) or { pythOracle, usdPriceId }
+  memberFundingTarget: string;  // native amount a member wallet is topped up to
+  staffFundingTarget: string;   // native amount a new library-staff wallet receives
+  addresses?: { addressRegistry?: string; stagingAddressRegistry?: string; [contract: string]: string | undefined };
+  deployed?: boolean;           // production contracts deployed on this chain
+  stagingDeployed?: boolean;    // staging contracts deployed on this chain
 }
 ```
 
+`addresses` is a bootstrap copy, used only to reach the chain when the registry manifest can't be loaded; read deployed addresses through the [Registry API](#33-registry-api).
+
 ---
 
 #### Vue Composable: `useChain(chainId)`
 
 ```typescript
+import { DEFAULT_CHAIN_ID } from '@the_library/network-config';
 import { useChain } from '@the_library/public/web3/vue';
 
-const { chain, client, usdPrice, refreshPrice, isMainnet, chainRouteQuery } = useChain(146);
+const { chain, client, usdPrice, isPriceLoading, refreshPrice, isMainnet, isDeployed, chainRouteQuery } = useChain(DEFAULT_CHAIN_ID);
 // chain: EvmChainConfig
-// client: ReadOnlyDomainAPI (ready to use)
-// usdPrice: Ref<number> — live USD price polling
-// refreshPrice: () => Promise<void>
-// isMainnet: boolean
-// chainRouteQuery: { chainId: '146' } — useful for router links
+// client: ReadOnlyDomainAPI
+// usdPrice: Ref<number | null> — USD price of the native coin
+// isPriceLoading: Ref<boolean>
+// refreshPrice(): Promise<void>
+// isMainnet, isDeployed: ComputedRef<boolean>
+// chainRouteQuery(extra?) — { chainId, ...extra } for router links
 ```
 
 ---
 
 ### 3.3 Registry API
 
-Dynamic contract address and ABI resolution from the on-chain `AddressRegistry`.
+Contract addresses, ABIs and collection pointers, read from the published registry manifest (`https://registry.worldbibliotech.com/<env>/manifest.json`), falling back to the on-chain `AddressRegistry` when the manifest can't be loaded.
 
 #### `addressLoader` (singleton)
 
@@ -1854,13 +1462,13 @@ const abi = addressLoader.getAbi(chainId, 'Factory');
 
 **Methods:**
 
-- `addressLoader.subscribe(callback: (chainId, LoadingStatus) => void): () => void` — Listen for load progress.
+- `addressLoader.subscribe(listener: (chainId: string | number, status: LoadingStatus) => void): () => void` — Listen for load progress.
 
-- `addressLoader.getAddress(chainId: number, contractName: string): string | undefined` — Resolved contract address, or `undefined` if not yet loaded.
+- `addressLoader.getAddress(chainId: string | number, name: string, environment?: 'production' | 'staging'): string | undefined` — Resolved contract address, or `undefined` if not yet loaded.
 
-- `addressLoader.getAbi(chainId: number, contractName: string): any[] | undefined` — Resolved ABI array, or `undefined` if not yet loaded.
+- `addressLoader.getAbi(chainId: string | number, name: string, environment?: 'production' | 'staging'): any` — Resolved ABI, or `undefined` if not yet loaded.
 
-- `addressLoader.loadManifest(environment: 'production' | 'staging'): Promise<Manifest>` — Manually load the registry manifest (auto-called by clients).
+- `addressLoader.loadManifest(environment?: 'production' | 'staging'): Promise<Manifest>` — Manually load the registry manifest (auto-called by clients).
 
 ---
 
@@ -1874,14 +1482,15 @@ Override the default registry host URL (normally `https://registry.worldbibliote
 
 Walks the on-chain subscription graph (who-follows-whom) and incrementally fetches patches.
 
-#### `getSubscriptionClient(chainId: number): SubscriptionClient`
+#### `getSubscriptionClient(chainId: number, environment?: 'production' | 'staging'): SubscriptionClient`
 
 Gets a chain-scoped subscription client.
 
 ```typescript
+import { DEFAULT_CHAIN_ID } from '@the_library/network-config';
 import { getSubscriptionClient } from '@the_library/public/web3';
 
-const subs = getSubscriptionClient(146);
+const subs = getSubscriptionClient(DEFAULT_CHAIN_ID);
 
 // First sync: full BFS walk + patch fetch
 const { patches, cursor, truncated } = await subs.sync(rootUserId);
@@ -1896,13 +1505,13 @@ const score = await subs.getScore(userId);
 
 **Methods:**
 
-- `subs.sync(rootUserId: number): Promise<SyncResult>` — Walk subscription graph starting from a user, fetch all patches.
+- `subs.sync(rootUserId: number, opts?: SyncOptions): Promise<SyncResult>` — Walk subscription graph starting from a user, fetch all patches.
 
-- `subs.syncSince(cursor: SyncCursor): Promise<SyncResult>` — Incremental sync using a persisted cursor.
+- `subs.syncSince(cursor: SyncCursor, opts?: SyncOptions): Promise<SyncResult>` — Incremental sync using a persisted cursor.
 
 - `subs.getSubscriptions(userId: number): Promise<number[]>` — List of users this user subscribes to.
 
-- `subs.getScore(userId: number): Promise<number>` — Social score for a user.
+- `subs.getScore(userId: number): Promise<bigint>` — Social score for a user.
 
 **Type: `SyncResult`**
 ```typescript
@@ -1918,91 +1527,87 @@ interface SyncResult {
 #### `cursorStore` (IndexedDB persistence)
 
 ```typescript
-import { cursorStore } from '@the_library/public/web3';
+import { DEFAULT_CHAIN_ID } from '@the_library/network-config';
+import { cursorStore, cursorKey } from '@the_library/public/web3';
 
-const cursor = await cursorStore.get(userId);
-const result = cursor 
+// one cursor per environment, chain and user
+const key = cursorKey('production', DEFAULT_CHAIN_ID, userId);
+const cursor = await cursorStore.get(key);
+const result = cursor
   ? await subs.syncSince(cursor)
   : await subs.sync(userId);
-await cursorStore.set(userId, result.cursor);
+await cursorStore.set(key, result.cursor);
 ```
 
 **Methods:**
 
-- `cursorStore.get(userId: number): Promise<SyncCursor | null>` — Retrieve persisted cursor, or `null` if never synced.
+- `cursorStore.get(key: string): Promise<SyncCursor | undefined>` — Retrieve the persisted cursor, or `undefined` if never synced.
 
-- `cursorStore.set(userId: number, cursor: SyncCursor): Promise<void>` — Save cursor for next sync.
+- `cursorStore.set(key: string, cursor: SyncCursor): Promise<void>` — Save the cursor for the next sync.
 
----
+- `cursorKey(environment, chainId, userId): string` — the key. The same `userId` exists on each environment and chain, each with its own subscription history, so a bare user ID would mix their cursors.
 
-#### Vue Composable: `useSubscriptionSync(userId)`
+---
 
-```typescript
-import { useSubscriptionSync } from '@the_library/public/web3/vue';
+#### Vue Composable: `useSubscriptionSync(userId, chainId, environment)`
 
-const { cursor, patches, isLoading, refresh } = useSubscriptionSync(userId);
-// cursor: Ref<SyncCursor>
-// patches: Ref<Patch[]>
-// isLoading: Ref<boolean>
-// refresh: () => Promise<void>
-```
+See [3.10 Vue Composables](#usesubscriptionsyncuserid-number-chainid-number-environment-production--staging).
 
 ---
 
 ### 3.5 Contracts API
 
-Static ABI exports for contracts that don't use dynamic resolution.
+ABIs bundled with the package, for the contracts the SDK must reach before (or without) the registry: `addressRegistryAbi`, `dSafeHRStorageAbi`, `relationshipIndexerStorageAbi` and `pythAbi`. They are generated from the deployed contracts; every other ABI comes from the registry (`addressLoader.getAbi`, `getContractAbi`).
 
 ```typescript
-import { addressRegistryAbi, pythAbi } from '@the_library/public/web3';
-
-// Use with viem directly:
+import { addressRegistryAbi } from '@the_library/public/web3';
 import { createPublicClient, http } from 'viem';
 
-const client = createPublicClient({ 
-  chain: /*...*/, 
-  transport: http() 
-});
+const client = createPublicClient({ chain: /* toViemChain(getChain(…)) */, transport: http() });
 
-const data = await client.readContract({
-  address: '0x...',
+const [factory] = await client.readContract({
+  address: '0x…',                     // the AddressRegistry, from the registry manifest
   abi: addressRegistryAbi,
   functionName: 'getLatestContract',
   args: ['Factory'],
 });
 ```
 
+`getContractDisplayName(name)` and `CONTRACT_DISPLAY_NAMES` give each contract's public name (e.g. `StatsPivotStorage` → "The Records Room").
+
 ---
 
 ### 3.6 Events API
 
-Typed pub/sub bus for wallet and transaction state notifications.
+Typed pub/sub bus for wallet, session and transaction notifications.
 
 #### `WalletEvents` (typed pub/sub)
 
+Every `on…` function returns its unsubscribe function; each has a matching `emit…`.
+
 ```typescript
-import { WalletEvents, type WalletState, type WalletError } from '@the_library/public/web3';
+import { WalletEvents, WalletState } from '@the_library/public/web3';
 
 const unsubWalletState = WalletEvents.onWalletStateEvent((e) => {
-  // e: { wallet, chainId, event: WalletState, functionName?, timestamp }
-  if (e.event === 'TRANSACTION_STARTED') showSpinner();
-  if (e.event === 'TRANSACTION_DONE') hideSpinner();
-  if (e.event === 'ACCOUNT_SYNCED') updateUI();
+  // e: { wallet, chainId?, timestamp, event: WalletState, functionName?, functionArgs? }
+  if (e.event === WalletState.TRANSACTION_STARTED) showSpinner();
+  if (e.event === WalletState.TRANSACTION_DONE) hideSpinner();
+  if (e.event === WalletState.READY) updateUI();
 });
 
 const unsubError = WalletEvents.onWalletError((e) => {
-  // e: { wallet, chainId, reason: WalletError, timestamp }
+  // e: { wallet, chainId?, timestamp, reason: WalletError | WalletUxError, args? }
   toast.error(e.reason);
 });
 
 const unsubSaveRestored = WalletEvents.onSaveRestored((e) => {
-  // e: { compressedActions, indexes, stringIndexes, timestamp }
-  // Patches from on-chain state that outran local edits
+  // e: { wallet, chainId?, timestamp, username, account, newRestorationIndex, appliedCount }
+  // saves from another device were restored into this one
 });
 
 const unsubPatchesSynced = WalletEvents.onSubscriptionPatchesSynced((e) => {
-  // e: { rootUserId, patches: Patch[], timestamp }
-  // Subscription graph patches fetched in background
+  // e: { rootUserId, chainId, appliedCount, timestamp }
+  // subscription sync merged patches from the readers this user follows
 });
 
 // Unsubscribe
@@ -2012,24 +1617,21 @@ unsubSaveRestored();
 unsubPatchesSynced();
 ```
 
+The other events: `onSessionUpdated` and `onWalletSessionDeleted` (`{ account, chainId, wallet }`), `onChainChanged`, and `onDisconnected` (`{ …, reason? }`).
+
 **Enums:**
 
-**`WalletState`** — transaction lifecycle events:
-- `'WALLET_CONNECTED'`
-- `'WALLET_DISCONNECTED'`
-- `'TRANSACTION_STARTED'`
-- `'TRANSACTION_DONE'`
-- `'TRANSACTION_FAILED'`
-- `'ACCOUNT_SYNCED'`
-- `'SUBSCRIPTION_SYNC_STARTED'`
-- `'SUBSCRIPTION_SYNC_DONE'`
+**`WalletState`** — connector and transaction lifecycle:
+- setup: `INITIALIZING`, `READY`, `INTERNAL_ERROR`, `TIMEOUT`, `WALLET_INSTALLED`
+- availability: `NOT_CONNECTED`, `NOT_INSTALLED`, `NOT_ALLOWED`, `NOT_SUPPORTED`, `NOT_READY`
+- `CONNECT_STARTED` / `CONNECT_DONE` / `CONNECT_FAILED`
+- `UPDATING_STATE_STARTED` / `UPDATING_STATE_DONE` / `UPDATING_STATE_FAILED`
+- `TRANSACTION_STARTED` / `TRANSACTION_DONE` / `TRANSACTION_FAILED`
+- `CHAIN_CHANGED_STARTED` / `CHAIN_CHANGED_DONE` / `CHAIN_CHANGED_FAILED`
+
+**`WalletError`** — `NO_ACCOUNTS`, `USER_REJECTED`, `INSUFFICIENT_FUNDS`, `LOGIN_INTO_WALLET`, `REQUEST_ALREADY_PENDING`, `UNKNOWN_ERROR`, `CONFIG_MISSING`, `NOT_SUPPORTED`, `NOT_CONNECTED`, `NOT_INSTALLED`, `NOT_ALLOWED`, `NETWORK_NOT_SUPPORTED`.
 
-**`WalletError`** — error reasons:
-- `'NETWORK_ERROR'`
-- `'TRANSACTION_REJECTED'`
-- `'INSUFFICIENT_BALANCE'`
-- `'UNKNOWN_ERROR'`
-- etc. (see source for full list)
+**`WalletUxError`** — something the user has to do in their wallet: `NO_ACCOUNT_SWITCH`, `NO_NETWORK_SWITCH`, `NETWORK_NOT_SUPPORTED`, `NO_INTERNET`, `NO_DISCONNECT`, `NO_ACCOUNT_DISCONNECT`.
 
 ---
 
@@ -2042,7 +1644,9 @@ const bus = getEventBus();
 const unsubscribe = bus.on('topic', (data) => { /* handle */ });
 bus.emit('topic', data);
 bus.once('topic', (data) => { /* one-time listener */ });
-bus.clear('topic'); // remove all listeners
+bus.off('topic', listener);
+bus.listenerCount('topic');
+bus.clear('topic'); // remove all listeners (all topics when called without one)
 ```
 
 ---
@@ -2110,10 +1714,11 @@ if (!meta.isInstalled() && meta.isInstallable()) {
 #### Private Key Storage
 
 ```typescript
+import { DEFAULT_CHAIN_ID } from '@the_library/network-config';
 import { storePrivateKey, hasPrivateKey, hasAnyPrivateKey } from '@the_library/public/web3';
 
-storePrivateKey(146, '0x1234...'); // raw hex, no '0x' prefix required
-if (hasPrivateKey(146)) {
+storePrivateKey(DEFAULT_CHAIN_ID, '0x1234...'); // raw hex, no '0x' prefix required
+if (hasPrivateKey(DEFAULT_CHAIN_ID)) {
   // PrivateKeyConnector can connect to this chain
 }
 
@@ -2122,7 +1727,7 @@ if (hasAnyPrivateKey()) {
 }
 ```
 
-**Warning:** Private keys are stored in plaintext localStorage. **Only use for dev/test wallets, never for real user funds.**
+**Warning:** Private keys are stored in plaintext localStorage. `storeEncryptedPrivateKey`, `getDecryptedPrivateKey` and `hasEncryptedPrivateKey` are compatibility aliases of the three functions above: they do **not** encrypt anything. A key stored this way is readable by any script running on the page, so keep only small balances (such as the gas top-up of a member wallet) on these wallets.
 
 ---
 
@@ -2135,13 +1740,14 @@ Project discovery and voting.
 Loads a single project by ID with language fallback. Cached automatically.
 
 ```typescript
+import { DEFAULT_CHAIN_ID } from '@the_library/network-config';
 import { loadProject } from '@the_library/public/web3';
 
-const project = await loadProject(146, 'eng', 5);
+const project = await loadProject(DEFAULT_CHAIN_ID, 'eng', 5);
 console.log(`${project.version.name} — ${project.balance} tokens`);
 
 // Force re-fetch from chain, bypassing cache
-const fresh = await loadProject(146, 'eng', 5, true);
+const fresh = await loadProject(DEFAULT_CHAIN_ID, 'eng', 5, true);
 ```
 
 **Parameters:**
@@ -2152,7 +1758,7 @@ const fresh = await loadProject(146, 'eng', 5, true);
 
 **Returns:** `Promise<ProjectLocale>`
 
-**Throws:** If cache miss and chain unreachable.
+**Throws:** If the chain can't be read and there is no cached copy (an expired copy is returned instead, unless `refresh` is set).
 
 ---
 
@@ -2163,7 +1769,7 @@ Loads all projects for a chain/language. Returns cached projects if chain is unr
 ```typescript
 import { loadProjects } from '@the_library/public/web3';
 
-const projects = await loadProjects(146, 'eng');
+const projects = await loadProjects(DEFAULT_CHAIN_ID, 'eng');
 const validProjects = projects.filter(p => p !== null);
 ```
 
@@ -2175,21 +1781,21 @@ const validProjects = projects.filter(p => p !== null);
 
 ---
 
-#### `projectLocale(project: Project, language: string, chainId: number): ProjectLocale`
+#### `projectLocale(project: Project, userLanguage: string, _chainId: number): ProjectLocale`
 
-Helper to convert raw `Project` data to `ProjectLocale` with language selection and decimal normalization.
+Helper to convert raw `Project` data to `ProjectLocale`, picking the version in `userLanguage` (with fallback). Votes are whole numbers (1 vote = $1), so nothing is converted.
 
 ```typescript
 import { projectLocale } from '@the_library/public/web3';
 
 const raw = await client.projectManagerStorage.loadProject(5);
-const locale = projectLocale(raw, 'eng', 146);
+const locale = projectLocale(raw, 'eng', DEFAULT_CHAIN_ID);
 ```
 
 **Parameters:**
 - `project: Project` — Raw contract data.
-- `language: string` — Preferred language.
-- `chainId: number` — For decimal normalization.
+- `userLanguage: string` — Preferred language.
+- `_chainId: number` — Unused; kept for existing callers.
 
 **Returns:** `ProjectLocale`
 
@@ -2197,53 +1803,24 @@ const locale = projectLocale(raw, 'eng', 146);
 
 #### Vue Composable: `useLoadProjects(chainId, language)`
 
-```typescript
-import { useLoadProjects } from '@the_library/public/web3/vue';
-
-const chainId = ref(146);
-const language = ref('eng');
-
-const { projects, isLoading, error, reload } = useLoadProjects(chainId, language);
-// projects: Ref<Array<ProjectLocale | null>>
-// isLoading: Ref<boolean>
-// error: Ref<Error | null>
-// reload: () => Promise<void>
-```
+See [3.10 Vue Composables](#useloadprojectschainid-mayberefnumber-language-mayberefstring-useloadprojectsreturn).
 
 ---
 
 ### 3.9 Chain & Network Configuration
 
-#### `EVM_CHAINS` (constant)
+Networks are defined in `@the_library/network-config`, not in this package; import from it directly. Never hard-code a chain ID: take it from there.
 
 ```typescript
-import { EVM_CHAINS } from '@the_library/public/web3';
+import { EVM_CHAINS, getChain, DEFAULT_CHAIN_ID, DEFAULT_STAGING_CHAIN_ID, CANONICAL } from '@the_library/network-config';
 
-// EVM_CHAINS = {
-//   146: { name: 'Sonic', ... },
-//   14601: { name: 'Sonic Blaze', ... },
-//   84532: { name: 'Base Sepolia', ... },
-// }
+EVM_CHAINS;                         // Record<chainId, EvmChainConfig>: every defined network
+DEFAULT_CHAIN_ID;                   // the production chain (CANONICAL.production)
+DEFAULT_STAGING_CHAIN_ID;           // the staging chain, a testnet (CANONICAL.staging)
+getChain(DEFAULT_CHAIN_ID).name;    // throws for an unknown chain ID
 ```
 
----
-
-#### `DEFAULT_CHAIN_ID` (constant)
-
-The default chain for new users (usually production mainnet, e.g., `146`).
-
----
-
-#### `getChain(chainId: number): EvmChainConfig`
-
-Gets full metadata for a chain. Throws if `chainId` is not registered.
-
-```typescript
-import { getChain } from '@the_library/public/web3';
-
-const chain = getChain(146);
-console.log(`${chain.name} (${chain.symbol})`);
-```
+The `EvmChainConfig` shape is listed under [Chain Metadata](#chain-metadata). To turn one into a viem `Chain`, use `toViemChain(config)` from `@the_library/public/web3` (or `@the_library/public/web3/network`).
 
 ---
 
@@ -2251,16 +1828,12 @@ console.log(`${chain.name} (${chain.symbol})`);
 
 #### `bootstrapWebSDK(options?: BootstrapOptions): Promise<BootstrapResult>`
 
-Single app-wide initialization: registers connectors, loads persisted session, hydrates accounts.
+Single app-wide initialization: registers the wallet connectors, loads the persisted session and hydrates the accounts.
 
 ```typescript
 import { bootstrapWebSDK, BootstrapResultKey } from '@the_library/public/web3/vue';
 
-const result = await bootstrapWebSDK({
-  withTest: true,
-  environment: 'production',
-  chainFilter: [146, 14601], // optional: limit to these chains
-});
+const result = await bootstrapWebSDK({ environment: 'production' });
 
 await result.ready; // wait for account discovery
 
@@ -2269,20 +1842,21 @@ app.provide(BootstrapResultKey, result);
 ```
 
 **Parameters:**
-- `options.withTest?: boolean` — Include test chains (Base Sepolia).
-- `options.environment?: 'production' | 'staging'` — Contract environment.
-- `options.chainFilter?: number[]` — Optional: only bootstrap these chains.
+- `options.environment?: 'production' | 'staging'` — which deployment to use.
+- `options.withTest?: boolean` — include testnets. Default `true`; `false` keeps only mainnets.
+- `options.chainFilter?: number[]` — bootstrap exactly these chains instead (takes precedence over `withTest`).
 
 **Returns:** `Promise<BootstrapResult>`
 
 **Type: `BootstrapResult`**
 ```typescript
 interface BootstrapResult {
-  ready: Promise<void>;
+  primaryAccount: Web3SessionAccount | null;
   chains: EvmChainConfig[];
+  connectorsByChain: Record<number, ChainConnectors>;  // { chain, installed, installable }
   installedConnectors: WalletConnector[];
   installableConnectors: WalletConnector[];
-  primaryAccount: Web3SessionAccount | null;
+  ready: Promise<void>;
 }
 ```
 
@@ -2290,7 +1864,7 @@ interface BootstrapResult {
 
 #### `useBootstrap(): BootstrapResult`
 
-Retrieves the app-wide bootstrap result (must have been provided via `app.provide(BootstrapResultKey, result)`).
+Returns the `BootstrapResult` provided at the app root with `app.provide(BootstrapResultKey, result)`.
 
 ```typescript
 import { useBootstrap } from '@the_library/public/web3/vue';
@@ -2300,7 +1874,7 @@ const { chains, installedConnectors, primaryAccount } = useBootstrap();
 
 ---
 
-#### `useWeb3Session()`
+#### `useWeb3Session(): UseWeb3SessionReturn`
 
 Reactive wrapper over `sessionStore`.
 
@@ -2308,62 +1882,122 @@ Reactive wrapper over `sessionStore`.
 import { useWeb3Session } from '@the_library/public/web3/vue';
 
 const {
-  accounts,           // Ref<Web3SessionAccount[]>
-  registeredAccounts, // Ref<Web3SessionAccount[]> filtered by hasAccount=true
-  activeAccount,      // Ref<Web3SessionAccount | null>
-  isConnecting,       // Ref<boolean>
-  setActive,          // (account: Web3SessionAccount) => void
+  accounts,                    // ComputedRef<Web3SessionAccount[]>
+  registeredAccounts,          // ComputedRef<Web3SessionAccount[]>, only hasAccount = true
+  activeAccount,               // ComputedRef<Web3SessionAccount | null>
+  isConnecting,                // Ref<boolean>
+  setActive,                   // (account) => void
+  discoverAccounts,            // (connector, { forceRefresh? }) => Promise<Web3SessionAccount[]>
+  syncAccount,                 // (address, chainId, wallet, forceRefresh?) => Promise<Web3SessionAccount>
+  accountsForChain,            // (chainId) => ComputedRef<Web3SessionAccount[]>
+  registeredAccountsForChain,  // (chainId) => ComputedRef<Web3SessionAccount[]>
 } = useWeb3Session();
 ```
 
+It also exposes the save counters: `lastSyncCounters(address, chainId)`, `setLastSavedPatchIndex(…)` and `setLastDownloadedSaveIndex(…)`.
+
+---
+
+#### `useChain(chainId: MaybeRef<number>): UseChainReturn`
+
+See [Chain Metadata → `useChain`](#vue-composable-usechainchainid).
+
 ---
 
-#### `useChain(chainId: number | Ref<number>)`
+#### `useLoadProjects(chainId: MaybeRef<number>, language: MaybeRef<string>): UseLoadProjectsReturn`
 
 ```typescript
-import { useChain } from '@the_library/public/web3/vue';
+import { DEFAULT_CHAIN_ID } from '@the_library/network-config';
+import { useLoadProjects } from '@the_library/public/web3/vue';
 
-const { chain, client, usdPrice, refreshPrice, isMainnet, chainRouteQuery } = useChain(146);
-// chain: Ref<EvmChainConfig>
-// client: Ref<ReadOnlyDomainAPI>
-// usdPrice: Ref<number>
-// refreshPrice: () => Promise<void>
-// isMainnet: boolean
-// chainRouteQuery: { chainId: '146' }
+const { projects, isLoading, error, reload } = useLoadProjects(DEFAULT_CHAIN_ID, ref('eng'));
+// projects: Ref<Array<ProjectLocale | null>>, isLoading: Ref<boolean>, error: Ref<Error | null>, reload(): Promise<void>
 ```
 
 ---
 
-#### `useLoadProjects(chainId: number | Ref<number>, language: string | Ref<string>)`
+#### `useSubscriptionSync(userId: number, chainId: number, environment: 'production' | 'staging')`
+
+The state of a user's subscription sync: the stored cursor and how many patches the last sync applied (for a toast or badge). The sync itself runs on its own (after saves, at boot and on account discovery) and merges new patches into the models; this composable only reports it. `chainId` and `environment` are required because the same `userId` has a separate cursor on each chain and environment.
 
 ```typescript
-import { useLoadProjects } from '@the_library/public/web3/vue';
+import { DEFAULT_CHAIN_ID } from '@the_library/network-config';
+import { useSubscriptionSync } from '@the_library/public/web3/vue';
 
-const { projects, isLoading, error, reload } = useLoadProjects(
-  ref(146),
-  ref('eng')
-);
+const { cursor, appliedCount, isLoading, refresh } = useSubscriptionSync(userId, DEFAULT_CHAIN_ID, 'production');
+// cursor: Ref<SyncCursor | null>, appliedCount: Ref<number>, isLoading: Ref<boolean>, refresh(): Promise<void>
 ```
 
 ---
 
-#### `useSubscriptionSync(userId: number | Ref<number>)`
+#### `mutationBus`, `registerHandler`, `bootstrapMutationHandlers`
+
+Tracks the chain writes in flight, for optimistic UI and the transaction toasts.
+
+- `mutationBus.dispatch(mutation, commit, label): Promise<boolean>` — applies the optimistic update registered for `mutation.type`, runs `commit` (which calls `onAccepted()` once the wallet has signed), and resolves `true` on success. On failure (including `commit` returning `false`) it rolls the update back, records an entry in `mutationBus.errors` (`reason: 'rejected'` when the user declined) and resolves `false`.
+- `mutationBus.pending`, `.errors`, `.successes` — reactive lists for the UI; `reportError(label, reason?, detail?)` / `reportSuccess(label, detail?)` add entries for writes made outside `dispatch`, and `clearError(id)` / `clearSuccess(id)` remove them.
+- `ChainMutation` is one of `retire`, `vote`, `save`, `subscribe`, `unsubscribe`, each with `wallet`, `chainId` and `account`.
+- `registerHandler(type, { applyOptimistic, rollback })` — the optimistic update for one mutation type. `bootstrapMutationHandlers()` registers the built-in ones (`vote`, `retire`).
+
+---
+
+### 3.11 Auth API (`@the_library/public/web3/auth`)
+
+Signed messages shared by the browser and the Lambdas, so signer and verifier always build the same message. No wallet or network code: plain functions over viem's hashing and signature recovery.
+
+#### Batch authorization (bulk account creation)
+
+An admin signs (EIP-191 `personal_sign`) a message committing to the environment, batch ID, exact email list, `forceSendEmail` flag and signing time; the Lambda rebuilds the message, recovers the signer and checks it against its admin list.
 
 ```typescript
-import { useSubscriptionSync } from '@the_library/public/web3/vue';
+import { createBatchSigningMessage, verifyBatchAuthorization, parseAuthorizedAdmins } from '@the_library/public/web3/auth';
+
+const payload = { environment: 'staging', batchId, emails, forceSendEmail: false, issuedAt: new Date().toISOString() };
+const signature = await walletClient.signMessage({ account, message: createBatchSigningMessage(payload) });
+
+// on the server
+const result = await verifyBatchAuthorization({ payload, signature, authorizedAdmins: parseAuthorizedAdmins(process.env.AUTHORIZED_ADMINS) });
+if (result.ok) { /* result.signer, result.emails (normalized) */ } else { /* result.reason */ }
+```
 
-const { cursor, patches, isLoading, refresh } = useSubscriptionSync(userId);
+- `verifyBatchAuthorization({ payload, signature, authorizedAdmins, claimedSigner?, now? })` → `{ ok: true, signer, emails } | { ok: false, reason }`, where `reason` is one of `invalid_batch_id`, `invalid_emails`, `invalid_issued_at`, `expired`, `issued_in_future`, `malformed_signature`, `signer_mismatch`, `unauthorized_signer`.
+- Signatures older than `BATCH_AUTHORIZATION_MAX_AGE_MS` (10 minutes) are rejected; `issuedAt` may be up to `BATCH_AUTHORIZATION_MAX_CLOCK_SKEW_MS` (2 minutes) in the future.
+- `normalizeBatchEmails(emails)` (lowercased, trimmed, de-duplicated, sorted) and `hashBatchEmails(emails)` (keccak256 of that list) are the building blocks.
+
+#### Deletion consent (email-confirmed account deletion)
+
+The Lambda signs, as `AccountManager`'s oracle, a consent to retire one account, and delivers it only by email; the link proves control of the inbox, and `AccountManager.unregisterWithConsent` refuses to retire an account without it. The signed hash is `keccak256(abi.encodePacked("EmailConsent", account, chainId, accountManager, expiry))`.
+
+```typescript
+import { signDeletionConsent, encodeDeletionConsentToken, buildConfirmDeleteLink, DELETION_CONSENT_TTL_SECONDS } from '@the_library/public/web3/auth';
+
+// Lambda
+const consent = { account, chainId, accountManager, expiry: Math.floor(Date.now() / 1000) + DELETION_CONSENT_TTL_SECONDS };
+const signed = await signDeletionConsent(consent, oracleAccount.signMessage);
+const link = buildConfirmDeleteLink(encodeDeletionConsentToken(signed), frontendUrl);
+```
+
+```typescript
+import { decodeDeletionConsentToken, verifyDeletionConsent } from '@the_library/public/web3/auth';
+
+// Browser, before sending the transaction (the contract repeats every check)
+const consent = decodeDeletionConsentToken(token);   // shape only, or null
+const check = consent && await verifyDeletionConsent(consent, { chainId, accountManager, oracleSigner });
 ```
 
+- `verifyDeletionConsent` fails with `malformed`, `expired`, `wrong_chain`, `wrong_account_manager` or `signer_mismatch`. Take `oracleSigner` and `accountManager` from the chain or registry, never from the link.
+- `DELETION_CONSENT_TTL_SECONDS` is 24 hours; `DELETION_CONSENT_PURPOSE` is `'EmailConsent'`; `deletionConsentMessageHash(consent)` returns the hash above.
+
 ---
 
 ## 4. Branding API (`@the_library/public/branding`)
 
-Static, framework-agnostic branding and contact data shared across apps.
+Static, framework-agnostic branding and contact data shared across the project's apps.
 
 ```typescript
 import {
-  globalBranding,
+  globalBranding,           // { founder, builder, socialMedia, contactFormUrl }
+  founder, builder, socialMedia,
   worldBiblioTechBranding,
   dsafeLegalBranding,
   worldBibliotekBranding,
@@ -2371,33 +2005,25 @@ import {
 
 import type { AppBranding, FounderInfo, BuilderInfo, SocialMediaUrls } from '@the_library/public/branding';
 
-// Access global founder/contact data
-console.log(globalBranding.founder.email); // 'data@datapond.earth'
-console.log(globalBranding.founder.name);
-console.log(globalBranding.builder.name);
-console.log(globalBranding.socialMedia.x); // 'https://x.com/realDataPond'
+globalBranding.founder.email;            // 'data@datapond.earth'
+globalBranding.builder.name;             // 'Pond Enterprise'
+globalBranding.socialMedia.x;            // 'https://x.com/realDataPond'
 
-// Access app-specific branding
-console.log(worldBiblioTechBranding.appName); // 'World Biblio Tech'
-console.log(worldBiblioTechBranding.url);
-console.log(worldBiblioTechBranding.images.logo); // asset path
+worldBiblioTechBranding.appName;         // 'World Biblio Tech'
+worldBiblioTechBranding.images.logo;     // '@the_library/public/branding/assets/icon_transparent.png'
 ```
 
+Image paths point into the package's `branding/assets/` folder, so a bundler resolves them as `@the_library/public/branding/assets/<file>`.
+
 **Type: `AppBranding`**
 ```typescript
 interface AppBranding {
   appName: string;
-  url: string;
-  description?: string;
-  images: {
-    logo: string;      // relative path (e.g., '@the_library/public/branding/assets/...')
-    favicon?: string;
-    banner?: string;
-  };
-  support?: {
-    email?: string;
-    url?: string;
-  };
+  appUrl: string;
+  comingSoonUrl?: string;
+  supportEmail?: string;
+  contactFormUrl?: string;
+  images: { logo?: string; favicon?: string };
 }
 ```
 
@@ -2406,7 +2032,9 @@ interface AppBranding {
 interface FounderInfo {
   name: string;
   email: string;
-  title?: string;
+  whatsapp: string;
+  linkedIn: string;
+  photoPath: string;
 }
 ```
 
@@ -2414,17 +2042,23 @@ interface FounderInfo {
 ```typescript
 interface BuilderInfo {
   name: string;
-  title?: string;
+  url: string;
+  email: string;
+  whatsapp: string;
+  linkedIn: string;
+  logoPath: string;
 }
 ```
 
 **Type: `SocialMediaUrls`**
 ```typescript
 interface SocialMediaUrls {
-  x?: string;        // Twitter/X
-  github?: string;
-  linkedin?: string;
-  // ... other platforms
+  facebook: string;
+  instagram: string;
+  bluesky: string;
+  linkedin: string;
+  x: string;
+  kickstarter: string;
 }
 ```
 
@@ -2435,15 +2069,15 @@ interface SocialMediaUrls {
 ### Download Types
 - `FileState` — download/error state for one file
 - `RenderState` — page images and book metadata
-- `BookData` — cached book title, page count, etc.
-- `DownloadRecord` — progress (loaded/total bytes)
+- `BookData` — page dimensions of a parsed PDF
+- `DownloadProgressDetail`, `DownloadDoneDetail` — payloads of the download window events
 - `PruningState` — LRU cache eviction activity
 - `InitOptions` — downloader setup parameters
+- `SwStatus`, `SwGateOptions` (`/downloader/sw`) — service worker status and registration options
 
 ### Models Types
 - `ModelDefinition` — schema for a model type
-- `LevelData` — user's reading level and corpus progress
-- `BootData` — result of `bootstrapModelsV2()`
+- `LevelState` — a user's level: `{ level, progress, points }`
 - `TrashStore` — global trash index API (`list`/`count`/`usernames`/`subscribe`)
 - `StatSummary` — per-record visits/downloads/rating/shares/parts
 - `ActionTypes` — local analytics op discriminator (`Visit`, `Download`, `Rate`, ...)
@@ -2454,7 +2088,7 @@ interface SocialMediaUrls {
 - `Web3SessionAccount` — wallet state in session store
 - `SessionState` — `{ active, known }`
 - `ReadOnlyDomainAPI` — read client interface
-- `EvmChainConfig` — chain metadata
+- `EvmChainConfig` — chain metadata (from `@the_library/network-config`)
 - `ProjectLocale` — project with selected language
 - `Project` — raw contract data
 - `ProjectVersion` — project version metadata