@the_library/public 1.0.0

package/README.md

@@ -0,0 +1,2298 @@
+# @the_library/public — Complete API Documentation
+
+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.
+
+---
+
+## 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)
+   - [Core Types & Registry](#core-types--registry)
+   - [Record Cache & Reactivity](#record-cache--reactivity)
+   - [Generated Models](#generated-models)
+   - [Schema Registry](#schema-registry)
+   - [Trash Index](#trash-index)
+   - [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)
+
+---
+
+## 1. Downloader API (`@the_library/public/downloader`)
+
+The Downloader manages parallelized, cross-worker PDF and image fetching, decryption, decompression, and rendering using Web Workers and IndexedDB/Cache API storage backends.
+
+### Initialization
+
+#### `InitDownloaderV2(options?: InitOptions): Promise<void>`
+
+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.
+
+```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',
+});
+```
+
+**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`
+
+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).
+
+```typescript
+import { preloadWorkersV2 } from '@the_library/public/downloader';
+
+// Call immediately when app boots, before any heavy imports:
+preloadWorkersV2();
+```
+
+**Parameters:** None
+
+**Returns:** `void` (synchronous; starts background downloads, doesn't wait for them)
+
+---
+
+### 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.
+
+```typescript
+import { GetPdf, GetObjectUrl } from '@the_library/public/downloader';
+
+const response = await GetPdf(txId);
+const blob = await response.blob();
+const objectUrl = await GetObjectUrl(response); // for <iframe> or <embed>
+```
+
+**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.
+
+**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.
+
+---
+
+#### `GetImage(txId: string, pageOverride?: number): Promise<Response>`
+
+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.
+
+```typescript
+import { GetImage } from '@the_library/public/downloader';
+
+// Get the cover image (first page)
+const coverResponse = await GetImage(txId);
+const imageBlob = await coverResponse.blob();
+const imgSrc = URL.createObjectURL(imageBlob);
+
+// Get a specific page
+const page5Image = await GetImage(txId, 5);
+```
+
+**Parameters:**
+- `txId: string` — Arweave TX ID of the PDF.
+- `pageOverride?: number` — 1-indexed page number. Defaults to `1` (first page).
+
+**Returns:** `Promise<Response>` — HTTP `Response` object (status 200) wrapping JPEG/PNG bytes.
+
+**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`.
+
+**Caching:** Rendered images are cached in `CACHES.preview` under the key `{txId}_page{n}`. Cached preview images persist across sessions.
+
+---
+
+#### `EnsurePdf(txId: string): Promise<void>`
+
+Pre-downloads and caches a PDF without needing the `Response` object back. Useful for background prefetching or "warm up" operations.
+
+```typescript
+import { EnsurePdf } from '@the_library/public/downloader';
+
+// Background prefetch (fire and forget)
+EnsurePdf(txId).catch(e => console.warn('Prefetch failed:', e));
+
+// Wait for it
+await EnsurePdf(txId);
+```
+
+**Parameters:**
+- `txId: string` — Arweave TX ID of the PDF.
+
+**Returns:** `Promise<void>` — resolves once the PDF is cached.
+
+**Throws:** Same as `GetPdf`.
+
+---
+
+#### `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.
+
+**Throws:** Same as `GetImage`.
+
+---
+
+#### `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.
+
+```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>`
+
+Converts a `GetPdf` or `GetImage` response to a blob URL suitable for `<iframe src="">`, `<embed src="">`, or `<img src="">`.
+
+```typescript
+import { GetPdf, GetObjectUrl } from '@the_library/public/downloader';
+
+const pdfResponse = await GetPdf(txId);
+const blobUrl = await GetObjectUrl(pdfResponse);
+// Now use: <iframe :src="blobUrl" />
+```
+
+**Parameters:**
+- `response: Response` — A `Response` object returned by `GetPdf` or `GetImage`.
+
+**Returns:** `Promise<string>` — A `blob:` URL (e.g., `blob:https://example.com/...`).
+
+---
+
+#### `revokeObjectUrl(blobUrl: string): void`
+
+Explicitly revokes a blob URL created by `GetObjectUrl` to release memory.
+
+```typescript
+const blobUrl = await GetObjectUrl(response);
+// ... later ...
+revokeObjectUrl(blobUrl);
+```
+
+**Parameters:**
+- `blobUrl: string` — The blob URL to revoke.
+
+**Returns:** `void`
+
+**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).
+
+---
+
+#### `storageEstimate(): Promise<{ usage: number; quota: number }>`
+
+Queries the browser's storage quota and current usage.
+
+```typescript
+import { storageEstimate } from '@the_library/public/downloader';
+
+const { usage, quota } = await storageEstimate();
+const percentUsed = (usage / quota) * 100;
+console.log(`${percentUsed.toFixed(1)}% of storage in use`);
+```
+
+**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.
+
+```typescript
+import { getBookData } from '@the_library/public/downloader';
+
+const bookData = await getBookData(txId);
+if (bookData) {
+  console.log(`${bookData.title} has ${bookData.pages} pages`);
+}
+```
+
+**Parameters:**
+- `txId: string` — Arweave TX ID.
+
+**Returns:** `Promise<BookData | undefined>` — Book metadata if cached, `undefined` if no metadata has been hydrated yet.
+
+**Type: `BookData`**
+```typescript
+interface BookData {
+  txId: string;
+  title: string;
+  pages: number;
+  // ... other fields set by the mupdf worker
+}
+```
+
+---
+
+#### `getAllBookData(): Promise<BookData[]>`
+
+Retrieves all cached book metadata records from IndexedDB.
+
+```typescript
+import { getAllBookData } from '@the_library/public/downloader';
+
+const allBooks = await getAllBookData();
+console.log(`${allBooks.length} books 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>`
+
+Reads the download progress record for a TX ID.
+
+```typescript
+import { getDownloadRecord } from '@the_library/public/downloader';
+
+const record = await getDownloadRecord(txId);
+if (record) {
+  console.log(`${record.loaded}/${record.total} bytes downloaded`);
+}
+```
+
+**Parameters:**
+- `txId: string` — Arweave TX ID.
+
+**Returns:** `Promise<DownloadRecord | undefined>`
+
+**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)
+}
+```
+
+---
+
+#### `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`);
+```
+
+**Parameters:** None
+
+**Returns:** `Promise<DownloadRecord[]>` — Array of all cached progress records.
+
+---
+
+### Cache Management
+
+#### `downloadState`
+
+The canonical, synchronous, framework-agnostic store for all file state. Every framework adapter (`vue`, `react`, `solid`) is a thin reactive wrapper around this store.
+
+```typescript
+import { downloadState } from '@the_library/public/downloader';
+
+// Subscribe to changes
+const unsubscribe = downloadState.subscribe((changedTxId) => {
+  console.log(`File state changed for ${changedTxId}`);
+});
+
+// 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' | ...
+}
+```
+
+---
+
+#### `deletePdf(txId: string): Promise<boolean>`
+
+Removes a cached PDF from Cache API storage.
+
+```typescript
+import { deletePdf } from '@the_library/public/downloader';
+
+const deleted = await deletePdf(txId);
+console.log(deleted ? 'Deleted' : 'Not found in cache');
+```
+
+**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>`
+
+Removes all cached page preview images for a TX ID.
+
+```typescript
+import { deletePreview } from '@the_library/public/downloader';
+
+await deletePreview(txId);
+```
+
+**Parameters:**
+- `txId: string` — Arweave TX ID.
+
+**Returns:** `Promise<boolean>` — `true` if deletion succeeded.
+
+---
+
+#### `deleteDownloadRecord(txId: string): Promise<void>`
+
+Removes the download progress record from IndexedDB.
+
+```typescript
+import { deleteDownloadRecord } from '@the_library/public/downloader';
+
+await deleteDownloadRecord(txId);
+```
+
+**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>`
+
+Gets the Cache API store for PDFs.
+
+```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.
+
+#### `putPdf(txId: string, response: Response): Promise<void>`
+
+Low-level cache write for a PDF.
+
+#### `putPreview(txId: string, response: Response): Promise<void>`
+
+Low-level cache write for a cover image.
+
+#### `putPage(txId: string, pageNumber: number, response: Response): Promise<void>`
+
+Low-level cache write for a page image.
+
+#### `pdfKeys(): Promise<string[]>`
+
+Lists all cached PDF keys.
+
+#### `previewKeys(): Promise<string[]>`
+
+Lists all cached preview-image keys.
+
+#### `pageKeys(): Promise<string[]>`
+
+Lists all cached page-image keys.
+
+---
+
+### Keys & Naming
+
+#### `pdfKey(txId: string): string`
+
+Generates the cache key for a PDF.
+
+```typescript
+const key = pdfKey(txId); // e.g., "arweave_pdf_{txId}"
+```
+
+#### `previewKey(txId: string): string`
+
+Generates the cache key for a cover image.
+
+#### `pageKey(txId: string, pageNumber: number): string`
+
+Generates the cache key for a specific page.
+
+```typescript
+const key = pageKey(txId, 5); // e.g., "arweave_page_5_{txId}"
+```
+
+#### `CACHES` (constant)
+
+```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)
+
+```typescript
+import { CACHE_VERSION } from '@the_library/public/downloader';
+// CACHE_VERSION = 1
+```
+
+#### `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}`)
+
+#### Vue Composables
+
+```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>
+
+// Global download progress
+const progress = useGlobalProgress(); // ComputedRef<DownloadSummary>
+
+// LRU pruning activity
+const pruning = usePruning(); // ComputedRef<PruningState>
+```
+
+#### React Hooks
+
+```typescript
+import {
+  useFileStatus,
+  useRenderStatus,
+  useGlobalProgress,
+  usePruning
+} from '@the_library/public/downloader/react';
+
+// Synchronized external store hooks
+const status = useFileStatus(txId);       // FileState | undefined
+const render = useRenderStatus(txId);     // RenderState | undefined
+const progress = useGlobalProgress();     // DownloadSummary
+const pruning = usePruning();             // PruningState
+```
+
+#### Solid.js Primitives
+
+```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();
+```
+
+---
+
+### 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.
+
+#### `registerDownloaderSW(): Promise<ServiceWorkerState>`
+
+Registers (or reuses) the downloader service worker.
+
+```typescript
+import { registerDownloaderSW } from '@the_library/public/downloader/sw';
+
+const state = await registerDownloaderSW();
+if (state.active) {
+  console.log('Service worker active and controlling pages');
+}
+```
+
+**Parameters:** None
+
+**Returns:** `Promise<ServiceWorkerState>`
+
+**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;
+}
+```
+
+---
+
+#### `swStatus(): Promise<ServiceWorkerState>`
+
+Checks current service worker status without re-registering.
+
+```typescript
+import { swStatus } from '@the_library/public/downloader/sw';
+
+const state = await swStatus();
+```
+
+**Parameters:** None
+
+**Returns:** `Promise<ServiceWorkerState>`
+
+---
+
+#### `clearDownloaderCaches(): Promise<void>`
+
+Drops all Cache API entries (PDFs, page images, previews), but keeps IndexedDB metadata records intact.
+
+```typescript
+import { clearDownloaderCaches } from '@the_library/public/downloader/sw';
+
+await clearDownloaderCaches();
+console.log('Cache storage cleared, IndexedDB preserved');
+```
+
+**Parameters:** None
+
+**Returns:** `Promise<void>`
+
+---
+
+#### `nukeDownloaderStorage(): Promise<void>`
+
+Full reset: deletes everything — Cache API entries, IndexedDB records, service worker registration. Use when the user logs out or to recover storage quota.
+
+```typescript
+import { nukeDownloaderStorage } from '@the_library/public/downloader/sw';
+
+await nukeDownloaderStorage();
+console.log('All download data erased');
+```
+
+**Parameters:** None
+
+**Returns:** `Promise<void>`
+
+---
+
+#### `unregisterDownloaderSW(): Promise<void>`
+
+Unregisters the service worker.
+
+```typescript
+import { unregisterDownloaderSW } from '@the_library/public/downloader/sw';
+
+await unregisterDownloaderSW();
+```
+
+**Parameters:** None
+
+**Returns:** `Promise<void>`
+
+---
+
+## 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}`.
+
+### Core Types & Registry
+
+#### `Registry` (singleton, exported from `registry.ts`)
+
+Holds enriched `ModelDefinition` for every registered object type — property IDs, field schemas, and relations.
+
+```typescript
+import { Registry, type ModelDefinition } from '@the_library/public/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');
+```
+
+**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.
+
+**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[];
+}
+```
+
+---
+
+### Record Cache & Reactivity
+
+#### `configureDb(options?: { cacheLimit?: number }): void`
+
+Sets the in-memory LRU cache size. Call before loading any records.
+
+```typescript
+import { configureDb } from '@the_library/public/models';
+
+// Lower cache limit for mobile devices
+configureDb({ cacheLimit: 500 });
+```
+
+**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`
+
+Synchronously retrieves a record from the cache.
+
+```typescript
+import { getRecord } from '@the_library/public/models';
+import { Book } from '@the_library/public/models';
+
+if (hasRecord(Book.type, bookId)) {
+  const book = getRecord(Book.type, bookId);
+  console.log(book.title);
+}
+```
+
+**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.
+
+**Returns:** `void`
+
+---
+
+#### `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.
+
+**Returns:** `void`
+
+---
+
+#### `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.
+
+**Returns:** `boolean`
+
+---
+
+#### `pinRecord(typeId: number, id: string): void`
+
+Pins a record so it won't be evicted from the LRU cache. Use for the currently-open record, search results, etc.
+
+```typescript
+import { pinRecord } from '@the_library/public/models';
+
+// User opened a book — don't evict it while they're reading
+pinRecord(Book.type, openBookId);
+```
+
+**Parameters:**
+- `typeId: number` — Model type ID.
+- `id: string` — Record UID.
+
+**Returns:** `void`
+
+---
+
+#### `unpinRecord(typeId: number, id: 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`
+
+---
+
+#### `addReactivitySystem(system: ReactivitySystem): void`
+
+Installs a framework-agnostic reactivity hook that fires when records change. Framework adapters call this once at boot.
+
+```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 */ },
+});
+```
+
+---
+
+#### `setReactivitySystem(system: ReactivitySystem): void`
+
+Replaces the current reactivity system. Typically called by framework adapters during initialization.
+
+---
+
+### 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.
+
+```typescript
+import { Book, Person, NewBookWithId, ModelTypes } from '@the_library/public/models';
+// equivalently: 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 an existing record from disk
+const loaded = await Book.LoadAsync('book:abc123');
+
+// Check type at runtime
+if (loaded instanceof Book) {
+  console.log('It is a book');
+}
+
+// Generic record hydration (type unknown at compile time)
+const typeId = 10; // some numeric type
+const RecordClass = ModelTypes[typeId];
+const generic = new RecordClass();
+```
+
+**Key Functions:**
+
+- `NewBookWithId(id: string, creatorUsername: string): Book` — Factory to create a new Book record in memory.
+
+- `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.
+
+---
+
+### Schema Registry
+
+The `Registry` singleton (above) holds `ModelDefinition` for each type. Accessed via `Registry.get(typeId)` or `Registry.getByName(name)`.
+
+---
+
+### Trash Index
+
+A global, boot-owned index of which record ids (any object type) are currently `deleted` or flagged `!safe` — bucketed by the `creatorUsername` namespace the record belongs to. Fully automatic: there is nothing to register or feed it.
+
+```typescript
+import { trashStore, scanTrash, type TrashStore } from '@the_library/public/models';
+```
+
+**How it populates:**
+- **At boot** — `scanTrash()` runs a full pass over every currently-hydrated record right after `hydrateAll()` (both the initial `bootModelsV2()` call and every `loadLanguage()` call), deriving membership directly from each record's live `deleted`/`safe` state. No per-type registration needed — `deleted`/`safe` are universal base properties present on every model.
+- **Live** — registered internally as a `ReactivitySystem` (see `addReactivitySystem`, above). `Orm.patch()` fires this unconditionally for every mutation source — a local edit, `restoreAccountSave()`'s cross-device replay, and subscription-graph sync alike — so the index stays current automatically as patches land from anywhere, for any username. (An item lands in the trash by having its `deleted`/`safe` property patched — the same op every property edit uses — so this module never creates patches, it only mirrors them.)
+- **Instant paint** — a localStorage snapshot seeds the in-memory state synchronously at import time, so `useTrash()` reads a cached value immediately instead of empty until `bootModelsV2()` resolves; `scanTrash()` then reconciles it against the live corpus once boot completes.
+
+#### `trashStore` (singleton)
+
+```typescript
+import { Tag } from '@the_library/public/models/models';
+import { trashStore } from '@the_library/public/models';
+
+// All ids currently trashed for Tag, merged across every bucketed username
+const allTrashedTagIds = trashStore.list(Tag.type);
+
+// Merge only specific usernames' buckets
+const mineOnly = trashStore.list(Tag.type, ['mine']);
+
+const count = trashStore.count(Tag.type);
+const buckets = trashStore.usernames(Tag.type); // e.g. ['canonical']
+
+const unsubscribe = trashStore.subscribe(Tag.type, () => {
+  console.log('Tag trash changed:', trashStore.count(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.count(objectType: number, usernames?: string[]): number` — Same merge semantics as `list()`; returns the count.
+
+- `trashStore.usernames(objectType: number): string[]` — Usernames currently bucketed for a type (e.g. to populate a filter picker).
+
+- `trashStore.subscribe(objectType: number, listener: () => void): () => void` — Registers a listener, fired whenever that type's trash membership changes for *any* username. Returns an unsubscribe function.
+
+**Important — `'canonical'` vs `'mine'`:** `Orm.creatorUsername` resolves to the fixed string `'canonical'` for any record id without the top bit set (`isUserCreated()` false) — which is essentially the entire shared catalog (`Book`, `Tag`, ...), regardless of who edited it or which sync path delivered the patch. Only records with a genuinely user-created id (top bit set) carry a specific creator's username. Filtering `list()`/`count()` to `['mine']` for catalog types will silently return nothing — call with no argument (or `[]`) unless you specifically know the type is user-created content.
+
+**Type: `TrashStore`**
+```typescript
+interface TrashStore {
+  list(objectType: number, usernames?: string[]): number[];
+  count(objectType: number, usernames?: string[]): number;
+  usernames(objectType: number): string[];
+  subscribe(objectType: number, listener: () => void): () => void;
+}
+```
+
+---
+
+#### `scanTrash(): void`
+
+Full (re)scan — walks every currently-hydrated record and reconciles trash membership against its live `deleted`/`safe` state. Called automatically by `session.ts`'s `hydrateAll()` (boot + every `loadLanguage()` call); not normally called directly.
+
+**Parameters:** None
+
+**Returns:** `void`
+
+---
+
+### Framework Adapters (`/models/{vue,react,solid,astro}`)
+
+#### Vue Composables
+
+```typescript
+import {
+  bootstrapModelsV2,
+  useLevel,
+  useDraft,
+  useTrash,
+  resetModelsV2Session
+} from '@the_library/public/models/vue';
+```
+
+**`bootstrapModelsV2(options: BootstrapOptions): Promise<void>`**
+
+Initializes the models subsystem once at app boot. Idempotent across Astro `<ClientRouter />` navigations.
+
+```typescript
+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`),
+});
+```
+
+**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.
+
+**Returns:** `Promise<void>` — resolves once all sidecars are hydrated.
+
+---
+
+**`useLevel(username?: string): Ref<LevelData>`**
+
+Reactive per-username level state and corpus metadata.
+
+```typescript
+import { useLevel } from '@the_library/public/models/vue';
+
+const { level, progress } = useLevel('alice').value;
+console.log(`Alice's level: ${level}`);
+```
+
+**Parameters:**
+- `username?: string` — Username. Defaults to the currently-logged-in user.
+
+**Returns:** `Ref<LevelData>`
+
+**Type: `LevelData`**
+```typescript
+interface LevelData {
+  username: string;
+  level: number;
+  progress: number; // 0-1
+  lastUpdated: number; // timestamp
+}
+```
+
+---
+
+**`useDraft(getter: () => ModelInstance): { draft, isDirty, commit, rollback }`**
+
+Tracks edits to a model instance before committing them back to the original.
+
+```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
+}
+```
+
+**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
+}
+```
+
+---
+
+**`useTrash(objectType: number, usernames?: string[]): { count: Ref<number>; getIds: () => number[] }`**
+
+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.
+
+```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';
+```
+
+**`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>;
+```
+
+---
+
+#### 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).
+
+**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).
+
+---
+
+### Patch & Session Management
+
+Low-level APIs (not normally called directly; used by `bootstrapModelsV2`):
+
+#### `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.
+
+---
+
+## 3. Web3 API (`@the_library/public/web3`)
+
+The Web3 API consolidates blockchain login, wallet connections, transaction mutations, session state, on-chain subscriptions, and contract/address resolution.
+
+### 3.1 Session API
+
+Manages wallet accounts, session persistence, and the centralized write-transaction pipeline.
+
+#### `sessionStore` (singleton)
+
+The canonical, framework-agnostic store for known and active wallet accounts.
+
+```typescript
+import { sessionStore } from '@the_library/public/web3';
+
+const { active, known } = sessionStore.getState();
+console.log(`Active account: ${active?.account}`);
+console.log(`${known.length} known accounts`);
+
+// React to changes
+const unsubscribe = sessionStore.subscribe(() => {
+  const newState = sessionStore.getState();
+  console.log('Session changed', newState);
+});
+```
+
+**Methods:**
+
+- `sessionStore.getState(): SessionState` — Returns current state: `{ active: Web3SessionAccount | null; known: Web3SessionAccount[] }`.
+
+- `sessionStore.subscribe(callback: () => void): () => void` — Registers a listener, returns unsubscribe function.
+
+**Type: `Web3SessionAccount`**
+```typescript
+interface Web3SessionAccount {
+  account: string;              // hex address
+  chainId: number;
+  wallet: WalletType;           // 'metamask' | 'private_key'
+  username?: string;
+  userId?: number;
+  hasAccount: boolean;          // registered on-chain
+  level?: number;
+  projectBalance?: {
+    contributions: number;
+    allocated: number;
+    remaining: number;
+  };
+  donationsPerProject?: number[];
+  metadata?: {
+    country?: string;
+    language?: string;
+    lastSyncTime?: number;
+  };
+}
+```
+
+---
+
+#### `syncAccount(address: string, chainId: number, walletType: WalletType): 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 { syncAccount } from '@the_library/public/web3';
+
+const account = await syncAccount('0xabc...', 1116, 'metamask');
+console.log(`${account.username} is level ${account.level}`);
+```
+
+**Parameters:**
+- `address: string` — Wallet address (hex).
+- `chainId: number` — Chain ID (1116, 1114, etc.).
+- `walletType: WalletType` — `'metamask'` or `'private_key'`.
+
+**Returns:** `Promise<Web3SessionAccount>` — The hydrated account record.
+
+**Side effects:**
+- Adds/updates the account in `sessionStore`.
+- Persists the account to localStorage.
+- Kicks off a background `subscriptionSync` for the account's `userId`.
+
+---
+
+#### `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();
+```
+
+---
+
+### 3.2 Client API
+
+Typed read and write adapters over deployed contracts.
+
+#### `getReadClient(chainId: number, environment?: 'production' | 'staging'): ReadOnlyDomainAPI`
+
+Gets the read-only client for a chain. Blocks until contract addresses/ABIs are loaded from the registry.
+
+```typescript
+import { getReadClient } from '@the_library/public/web3';
+
+const client = getReadClient(1116);
+await client.ready; // wait for registry load
+
+const balance = await client.projectManagerStorage.balanceOfAddress('0xabc...');
+const level = await client.archivistStorage.userLevel(userId);
+const nbAccounts = await client.bouncerStorage.nbAccounts();
+```
+
+**Parameters:**
+- `chainId: number` — EVM chain ID (1116, 1114, 84532, etc.).
+- `environment?: 'production' | 'staging'` — Defaults to `'production'`. Use `'staging'` to read staging-deployed contract addresses.
+
+**Returns:** `ReadOnlyDomainAPI` — Typed interface to all contract reads.
+
+**Type: `ReadOnlyDomainAPI`**
+```typescript
+interface ReadOnlyDomainAPI {
+  readonly chainId: number;
+  readonly ready: Promise<void>;
+  readonly bouncerStorage: BouncerStorageReadAPI;
+  readonly archivistStorage: ArchivistStorageReadAPI;
+  readonly scientistStorage: ScientistStorageReadAPI;
+  readonly projectManagerStorage: ProjectManagerStorageReadAPI;
+  readonly factory: FactoryReadAPI;
+  readonly addressRegistry: AddressRegistryReadAPI;
+  readonly subscriptionManager: SubscriptionManagerReadAPI;
+  readonly libraryRegistryStorage: LibraryRegistryStorageReadAPI;
+  readonly publicLibraryStorage: PublicLibraryStorageReadAPI;
+  getUsdPrice(): Promise<number>;
+  getRegistryStatus(): Promise<any>;
+}
+```
+
+---
+
+#### Contract APIs
+
+**`BouncerStorageReadAPI`**
+
+Account identity and registration queries:
+
+- `hasAccount(address: string): Promise<boolean>` — Is the address registered?
+- `userInfos(address: string): Promise<[username, country, language, userId]>` — Fetch user metadata by address.
+- `userData(userId: number): Promise<[id, addr, username, language, country]>` — Fetch user metadata by ID.
+- `getUsernameByAddress(address: string): Promise<string>` — Get username for an address.
+- `userIdOf(address: string): Promise<number>` — Get user ID for an address.
+- `userIdToUsername(userId: number): Promise<string>` — Get username for a user ID.
+- `usernameToUserId(username: string): Promise<number>` — Get user ID for a username.
+- `userAddr(userId: number): Promise<string>` — Get address for a user ID.
+- `nbAccounts(): Promise<number>` — Total registered accounts on this chain.
+- `getAllLocationCounts(): Promise<any[]>` — Aggregate account counts by location.
+- `getActiveLocationCount(): Promise<number>` — Number of locations with at least one account.
+- `identityStats(): Promise<[nbVerbs, nbAdjectives]>` — Stats on generated usernames.
+
+---
+
+**`ArchivistStorageReadAPI`**
+
+User level and backup history:
+
+- `userLevel(userId: number): Promise<number>` — Reading level for a user.
+- `nbWrites(userId: number): Promise<number>` — Total patches authored.
+- `loadActions(userId: number): Promise<[bigint[], bigint[], string[]]>` — All patches for a user (raw format).
+- `loadActionsSince(userId: number, index: number): Promise<[bigint[], bigint[], string[]]>` — Patches since a given index.
+
+---
+
+**`ScientistStorageReadAPI`**
+
+Anonymized reading statistics:
+
+- `getLastMonthId(): Promise<number>` — Latest month in the stats index.
+- `getDeploymentDate(): Promise<[year, month]>` — When the contract was deployed.
+- `getStatsRaw(action: number, objectType: number, monthId: number): Promise<[bigint[], number[]]>` — Raw stats for a category/type/month.
+
+---
+
+**`ProjectManagerStorageReadAPI`**
+
+Project discovery and donation voting:
+
+- `nbProjects(): Promise<number>` — Total projects on-chain.
+- `getProjectSupportedLanguages(projectId: number): Promise<string[]>` — Languages available for a project.
+- `loadProject(projectId: number): Promise<Project>` — Fetch full project metadata.
+- `balanceOfAddress(address: string): Promise<{ total, donations, unspent }>` — Wallet's donation balance breakdown.
+- `addressDonationsPerProject(address: string): Promise<number[]>` — Vote allocation by project (array indexed by projectId-1).
+- `projectVotingBalances(projectId: number): Promise<number>` — Total votes allocated to a project.
+
+---
+
+**`FactoryReadAPI`**
+
+Global corpus metadata:
+
+- `load(): Promise<[bigint[], bigint[], string[]]>` — All patches in the corpus (raw format).
+- `loadUsername(username: string): Promise<[bigint[], bigint[], string[]]>` — Patches for one user.
+- `loadUsernameSince(username: string, index: number): Promise<[bigint[], bigint[], string[]]>` — Incremental patch fetch.
+- `nbWritesByUsername(username: string): Promise<number>` — Patch count for a user.
+
+---
+
+**`AddressRegistryReadAPI`**
+
+Dynamic contract address/ABI resolution:
+
+- `getLatestContract(name: string): Promise<[address, abiUrl]>` — Latest address for a named contract.
+- `getContractHistory(name: string): Promise<AddressRegistryContractRecord[]>` — All addresses ever deployed for a contract.
+- `getAllContractNames(): Promise<string[]>` — List of all contracts.
+- `getLatestData(key: string): Promise<string>` — Fetch arbitrary key-value data from the registry.
+
+---
+
+**`SubscriptionManagerReadAPI`**
+
+Who-follows-whom graph:
+
+- `getSubscriptions(userId: number): Promise<number[]>` — List of user IDs that this user subscribes to.
+- `getSubscriptionCount(userId: number): Promise<bigint>` — Total subscriptions for a user.
+- `isSubscribed(subscriber: number, target: number): Promise<boolean>` — Is `subscriber` following `target`?
+- `scoreOf(userId: number): Promise<bigint>` — Social score (based on follower count, etc.).
+
+---
+
+**`LibraryRegistryStorageReadAPI`**
+
+Library Collection and Registry metadata:
+
+- `getUnverifiedCollectionIds(): Promise<string[]>` — List of pending collection IDs.
+- `getVerifiedCollectionIds(): Promise<string[]>` — List of verified collection IDs.
+- `getCollection(id: string): Promise<Collection>` — Get full collection metadata by ID.
+
+---
+
+**`LibraryRegistryStorageWriteAPI`**
+
+Library Collection and Registry mutations (Requires Admin Authorization):
+
+- `addUnverifiedCollection(input: CollectionInput, options?: TransactionOptions): Promise<any>` — Submits a new collection for review.
+- `verifyCollection(id: string, options?: TransactionOptions): Promise<any>` — Approves a pending collection.
+- `rejectCollection(id: string, options?: TransactionOptions): Promise<any>` — Rejects and removes a pending collection.
+- `updateCollectionStats(id: string, initialBookCount: number, dSafeBookCount: number, options?: TransactionOptions): Promise<any>` — Updates statistics for a collection.
+- `setImportStatus(id: string, status: number, options?: TransactionOptions): Promise<any>` — Updates the import status enum.
+- `setPublished(id: string, isPublished: boolean, options?: TransactionOptions): Promise<any>` — Toggles publication status of a collection.
+- `setCollectionPublicLibrary(id: string, publicLibraryId: number, options?: TransactionOptions): Promise<any>` — Links a collection to a public library.
+- `setPublicLibraryStorage(storageAddr: string, options?: TransactionOptions): Promise<any>` — Sets the address of the PublicLibraryStorage contract.
+
+---
+
+**`PublicLibraryStorageReadAPI`**
+
+Public Library cataloging metadata:
+
+- `libraryExists(id: number): Promise<boolean>` — Checks if a library ID exists.
+- `getPublicLibrary(id: number): Promise<PublicLibrary>` — Get full public library metadata by ID.
+- `nbLibraries(): Promise<number>` — Returns the total number of registered public libraries.
+
+---
+
+**`PublicLibraryStorageWriteAPI`**
+
+Public Library management (Requires Admin Authorization):
+
+- `addPublicLibrary(input: PublicLibraryInput, options?: TransactionOptions): Promise<any>` — Creates a new public library record.
+- `updatePublicLibrary(id: number, input: PublicLibraryInput, options?: TransactionOptions): Promise<any>` — Updates an existing public library record.
+
+---
+
+#### Write Operations
+
+```typescript
+import { writeOperations, resetTransactionState } from '@the_library/public/web3';
+
+await writeOperations.register(walletType, chainId, address, registrationFee);
+await writeOperations.vote(walletType, chainId, address, projectId, language, voteAmount);
+await writeOperations.save(walletType, chainId, address, compressedActions, textIndexes, textData, level);
+await writeOperations.subscribe(walletType, chainId, address, subscriberUserId, targetUserId);
+await writeOperations.unsubscribe(walletType, chainId, address, subscriberUserId, targetUserId);
+```
+
+All write operations:
+- Acquire a 1-minute run-lock (only one transaction per address/chain at a time).
+- Emit `WalletEvents` state notifications.
+- Automatically refresh the account via `syncAccount()` on success.
+
+If a transaction throws and the run-lock needs to be cleared manually, call `resetTransactionState()`.
+
+---
+
+#### Chain Metadata
+
+```typescript
+import { getChain, EVM_CHAINS, DEFAULT_CHAIN_ID } from '@the_library/public/web3';
+
+const chain = getChain(1116);
+// chain.name, chain.symbol, chain.shortName, chain.logo, chain.explorer, 
+// chain.rpc, chain.main (true for mainnet), chain.deployed, chain.stagingDeployed
+
+const deployedChains = Object.values(EVM_CHAINS).filter(c => c.deployed);
+```
+
+**Type: `EvmChainConfig`**
+```typescript
+interface EvmChainConfig {
+  name: string;              // 'CORE' | 'tCORE2' | 'Base Sepolia'
+  shortName: string;         // 'core' | 'tcore2' | ...
+  chainId: number;
+  symbol: string;            // 'CORE' | 'CORETST' | ...
+  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;
+}
+```
+
+---
+
+#### Vue Composable: `useChain(chainId)`
+
+```typescript
+import { useChain } from '@the_library/public/web3/vue';
+
+const { chain, client, usdPrice, refreshPrice, isMainnet, chainRouteQuery } = useChain(1116);
+// chain: EvmChainConfig
+// client: ReadOnlyDomainAPI (ready to use)
+// usdPrice: Ref<number> — live USD price polling
+// refreshPrice: () => Promise<void>
+// isMainnet: boolean
+// chainRouteQuery: { chainId: '1116' } — useful for router links
+```
+
+---
+
+### 3.3 Registry API
+
+Dynamic contract address and ABI resolution from the on-chain `AddressRegistry`.
+
+#### `addressLoader` (singleton)
+
+```typescript
+import { addressLoader, setRegistryBaseUrl } from '@the_library/public/web3';
+
+// Set custom registry host (before anything else runs)
+setRegistryBaseUrl('https://registry.world.bibliotech.com');
+
+// Subscribe to per-contract load progress
+const unsubscribe = addressLoader.subscribe((chainId, status) => {
+  console.log(`chain ${chainId}: ${status.loaded}/${status.total} contracts loaded`);
+});
+
+// Get resolved address/ABI for a contract
+const addr = addressLoader.getAddress(chainId, 'Factory');
+const abi = addressLoader.getAbi(chainId, 'Factory');
+```
+
+**Methods:**
+
+- `addressLoader.subscribe(callback: (chainId, 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.getAbi(chainId: number, contractName: string): any[] | undefined` — Resolved ABI array, or `undefined` if not yet loaded.
+
+- `addressLoader.loadManifest(environment: 'production' | 'staging'): Promise<Manifest>` — Manually load the registry manifest (auto-called by clients).
+
+---
+
+#### `setRegistryBaseUrl(url: string): void`
+
+Override the default registry host URL (normally `https://registry.world.bibliotech.com`). Call before any clients are instantiated.
+
+---
+
+### 3.4 Subscription API
+
+Walks the on-chain subscription graph (who-follows-whom) and incrementally fetches patches.
+
+#### `getSubscriptionClient(chainId: number): SubscriptionClient`
+
+Gets a chain-scoped subscription client.
+
+```typescript
+import { getSubscriptionClient } from '@the_library/public/web3';
+
+const subs = getSubscriptionClient(1116);
+
+// First sync: full BFS walk + patch fetch
+const { patches, cursor, truncated } = await subs.sync(rootUserId);
+
+// Later: incremental — only fetch new patches since cursor
+const next = await subs.syncSince(cursor);
+
+// Query the graph
+const followees = await subs.getSubscriptions(userId);
+const score = await subs.getScore(userId);
+```
+
+**Methods:**
+
+- `subs.sync(rootUserId: number): 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.getSubscriptions(userId: number): Promise<number[]>` — List of users this user subscribes to.
+
+- `subs.getScore(userId: number): Promise<number>` — Social score for a user.
+
+**Type: `SyncResult`**
+```typescript
+interface SyncResult {
+  patches: Patch[];
+  cursor: SyncCursor;     // Persist this to resume next sync
+  truncated: boolean;     // true if result was truncated (more data available)
+}
+```
+
+---
+
+#### `cursorStore` (IndexedDB persistence)
+
+```typescript
+import { cursorStore } from '@the_library/public/web3';
+
+const cursor = await cursorStore.get(userId);
+const result = cursor 
+  ? await subs.syncSince(cursor)
+  : await subs.sync(userId);
+await cursorStore.set(userId, result.cursor);
+```
+
+**Methods:**
+
+- `cursorStore.get(userId: number): Promise<SyncCursor | null>` — Retrieve persisted cursor, or `null` if never synced.
+
+- `cursorStore.set(userId: number, cursor: SyncCursor): Promise<void>` — Save cursor for next sync.
+
+---
+
+#### Vue Composable: `useSubscriptionSync(userId)`
+
+```typescript
+import { useSubscriptionSync } from '@the_library/public/web3/vue';
+
+const { cursor, patches, isLoading, refresh } = useSubscriptionSync(userId);
+// cursor: Ref<SyncCursor>
+// patches: Ref<Patch[]>
+// isLoading: Ref<boolean>
+// refresh: () => Promise<void>
+```
+
+---
+
+### 3.5 Contracts API
+
+Static ABI exports for contracts that don't use dynamic resolution.
+
+```typescript
+import { addressRegistryAbi, pythAbi } from '@the_library/public/web3';
+
+// Use with viem directly:
+import { createPublicClient, http } from 'viem';
+
+const client = createPublicClient({ 
+  chain: /*...*/, 
+  transport: http() 
+});
+
+const data = await client.readContract({
+  address: '0x...',
+  abi: addressRegistryAbi,
+  functionName: 'getLatestContract',
+  args: ['Factory'],
+});
+```
+
+---
+
+### 3.6 Events API
+
+Typed pub/sub bus for wallet and transaction state notifications.
+
+#### `WalletEvents` (typed pub/sub)
+
+```typescript
+import { WalletEvents, type WalletState, type WalletError } 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();
+});
+
+const unsubError = WalletEvents.onWalletError((e) => {
+  // e: { wallet, chainId, reason: WalletError, timestamp }
+  toast.error(e.reason);
+});
+
+const unsubSaveRestored = WalletEvents.onSaveRestored((e) => {
+  // e: { compressedActions, indexes, stringIndexes, timestamp }
+  // Patches from on-chain state that outran local edits
+});
+
+const unsubPatchesSynced = WalletEvents.onSubscriptionPatchesSynced((e) => {
+  // e: { rootUserId, patches: Patch[], timestamp }
+  // Subscription graph patches fetched in background
+});
+
+// Unsubscribe
+unsubWalletState();
+unsubError();
+unsubSaveRestored();
+unsubPatchesSynced();
+```
+
+**Enums:**
+
+**`WalletState`** — transaction lifecycle events:
+- `'WALLET_CONNECTED'`
+- `'WALLET_DISCONNECTED'`
+- `'TRANSACTION_STARTED'`
+- `'TRANSACTION_DONE'`
+- `'TRANSACTION_FAILED'`
+- `'ACCOUNT_SYNCED'`
+- `'SUBSCRIPTION_SYNC_STARTED'`
+- `'SUBSCRIPTION_SYNC_DONE'`
+
+**`WalletError`** — error reasons:
+- `'NETWORK_ERROR'`
+- `'TRANSACTION_REJECTED'`
+- `'INSUFFICIENT_BALANCE'`
+- `'UNKNOWN_ERROR'`
+- etc. (see source for full list)
+
+---
+
+#### Low-level `EventBus` (rarely used)
+
+```typescript
+import { getEventBus } from '@the_library/public/web3';
+
+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
+```
+
+---
+
+### 3.7 Wallets API
+
+Wallet connectors (MetaMask, PrivateKey) and metadata.
+
+#### `getConnector(type: WalletType): WalletConnector | undefined`
+
+Retrieves a registered wallet connector by type.
+
+```typescript
+import { getConnector } from '@the_library/public/web3';
+
+const metamask = getConnector('metamask');
+if (metamask?.isAvailable()) {
+  const { address, chainId } = await metamask.connect();
+}
+```
+
+**Parameters:**
+- `type: WalletType` — `'metamask'` | `'private_key'`
+
+**Returns:** The connector, or `undefined` if not registered (e.g., `bootstrapWebSDK()` hasn't run yet).
+
+---
+
+#### `getRegisteredConnectors(): WalletConnector[]`
+
+Lists all registered connectors.
+
+```typescript
+import { getRegisteredConnectors } from '@the_library/public/web3';
+
+const connectors = getRegisteredConnectors();
+// array of MetaMaskConnector, PrivateKeyConnector, etc.
+```
+
+---
+
+#### `walletMeta` (metadata for each wallet)
+
+```typescript
+import { walletMeta } from '@the_library/public/web3';
+
+const meta = walletMeta.metamask;
+// {
+//   displayName: 'MetaMask',
+//   logoUrl: 'https://...',
+//   description: '...',
+//   website: 'https://metamask.io',
+//   isInstalled(): boolean,
+//   isInstallable(): boolean,
+//   getInstallUrl(): string,
+// }
+
+if (!meta.isInstalled() && meta.isInstallable()) {
+  window.open(meta.getInstallUrl(), '_blank');
+}
+```
+
+---
+
+#### Private Key Storage
+
+```typescript
+import { storePrivateKey, hasPrivateKey, hasAnyPrivateKey } from '@the_library/public/web3';
+
+storePrivateKey(1116, '0x1234...'); // raw hex, no '0x' prefix required
+if (hasPrivateKey(1116)) {
+  // PrivateKeyConnector can connect to this chain
+}
+
+if (hasAnyPrivateKey()) {
+  // At least one chain has a stored key
+}
+```
+
+**Warning:** Private keys are stored in plaintext localStorage. **Only use for dev/test wallets, never for real user funds.**
+
+---
+
+### 3.8 Projects API
+
+Project discovery and voting.
+
+#### `loadProject(chainId: number, language: string, projectId: number, refresh?: boolean): Promise<ProjectLocale>`
+
+Loads a single project by ID with language fallback. Cached automatically.
+
+```typescript
+import { loadProject } from '@the_library/public/web3';
+
+const project = await loadProject(1116, 'eng', 5);
+console.log(`${project.version.name} — ${project.balance} tokens`);
+
+// Force re-fetch from chain, bypassing cache
+const fresh = await loadProject(1116, 'eng', 5, true);
+```
+
+**Parameters:**
+- `chainId: number` — Chain ID.
+- `language: string` — Preferred language code (e.g., 'eng', 'deu', 'spa').
+- `projectId: number` — On-chain project ID (1-indexed).
+- `refresh?: boolean` — If `true`, bypass cache and refetch from chain.
+
+**Returns:** `Promise<ProjectLocale>`
+
+**Throws:** If cache miss and chain unreachable.
+
+---
+
+#### `loadProjects(chainId: number, language: string): Promise<Array<ProjectLocale | null>>`
+
+Loads all projects for a chain/language. Returns cached projects if chain is unreachable (with console warning).
+
+```typescript
+import { loadProjects } from '@the_library/public/web3';
+
+const projects = await loadProjects(1116, 'eng');
+const validProjects = projects.filter(p => p !== null);
+```
+
+**Parameters:**
+- `chainId: number` — Chain ID.
+- `language: string` — Preferred language code.
+
+**Returns:** `Promise<Array<ProjectLocale | null>>` — Array where `null` entries represent projects that failed to load.
+
+---
+
+#### `projectLocale(project: Project, language: string, chainId: number): ProjectLocale`
+
+Helper to convert raw `Project` data to `ProjectLocale` with language selection and decimal normalization.
+
+```typescript
+import { projectLocale } from '@the_library/public/web3';
+
+const raw = await client.projectManagerStorage.loadProject(5);
+const locale = projectLocale(raw, 'eng', 1116);
+```
+
+**Parameters:**
+- `project: Project` — Raw contract data.
+- `language: string` — Preferred language.
+- `chainId: number` — For decimal normalization.
+
+**Returns:** `ProjectLocale`
+
+---
+
+#### Vue Composable: `useLoadProjects(chainId, language)`
+
+```typescript
+import { useLoadProjects } from '@the_library/public/web3/vue';
+
+const chainId = ref(1116);
+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>
+```
+
+---
+
+### 3.9 Chain & Network Configuration
+
+#### `EVM_CHAINS` (constant)
+
+```typescript
+import { EVM_CHAINS } from '@the_library/public/web3';
+
+// EVM_CHAINS = {
+//   1116: { name: 'CORE', ... },
+//   1114: { name: 'tCORE2', ... },
+//   84532: { name: 'Base Sepolia', ... },
+// }
+```
+
+---
+
+#### `DEFAULT_CHAIN_ID` (constant)
+
+The default chain for new users (usually production mainnet, e.g., `1116`).
+
+---
+
+#### `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(1116);
+console.log(`${chain.name} (${chain.symbol})`);
+```
+
+---
+
+### 3.10 Vue Composables (`@the_library/public/web3/vue`)
+
+#### `bootstrapWebSDK(options?: BootstrapOptions): Promise<BootstrapResult>`
+
+Single app-wide initialization: registers connectors, loads persisted session, hydrates accounts.
+
+```typescript
+import { bootstrapWebSDK, BootstrapResultKey } from '@the_library/public/web3/vue';
+
+const result = await bootstrapWebSDK({
+  withTest: true,
+  environment: 'production',
+  chainFilter: [1116, 1114], // optional: limit to these chains
+});
+
+await result.ready; // wait for account discovery
+
+// Provide at app root
+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.
+
+**Returns:** `Promise<BootstrapResult>`
+
+**Type: `BootstrapResult`**
+```typescript
+interface BootstrapResult {
+  ready: Promise<void>;
+  chains: EvmChainConfig[];
+  installedConnectors: WalletConnector[];
+  installableConnectors: WalletConnector[];
+  primaryAccount: Web3SessionAccount | null;
+}
+```
+
+---
+
+#### `useBootstrap(): BootstrapResult`
+
+Retrieves the app-wide bootstrap result (must have been provided via `app.provide(BootstrapResultKey, result)`).
+
+```typescript
+import { useBootstrap } from '@the_library/public/web3/vue';
+
+const { chains, installedConnectors, primaryAccount } = useBootstrap();
+```
+
+---
+
+#### `useWeb3Session()`
+
+Reactive wrapper over `sessionStore`.
+
+```typescript
+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
+} = useWeb3Session();
+```
+
+---
+
+#### `useChain(chainId: number | Ref<number>)`
+
+```typescript
+import { useChain } from '@the_library/public/web3/vue';
+
+const { chain, client, usdPrice, refreshPrice, isMainnet, chainRouteQuery } = useChain(1116);
+// chain: Ref<EvmChainConfig>
+// client: Ref<ReadOnlyDomainAPI>
+// usdPrice: Ref<number>
+// refreshPrice: () => Promise<void>
+// isMainnet: boolean
+// chainRouteQuery: { chainId: '1116' }
+```
+
+---
+
+#### `useLoadProjects(chainId: number | Ref<number>, language: string | Ref<string>)`
+
+```typescript
+import { useLoadProjects } from '@the_library/public/web3/vue';
+
+const { projects, isLoading, error, reload } = useLoadProjects(
+  ref(1116),
+  ref('eng')
+);
+```
+
+---
+
+#### `useSubscriptionSync(userId: number | Ref<number>)`
+
+```typescript
+import { useSubscriptionSync } from '@the_library/public/web3/vue';
+
+const { cursor, patches, isLoading, refresh } = useSubscriptionSync(userId);
+```
+
+---
+
+## 4. Branding API (`@the_library/public/branding`)
+
+Static, framework-agnostic branding and contact data shared across apps.
+
+```typescript
+import {
+  globalBranding,
+  worldBiblioTechBranding,
+  dsafeLegalBranding,
+  worldBibliotekBranding,
+} from '@the_library/public/branding';
+
+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'
+
+// Access app-specific branding
+console.log(worldBiblioTechBranding.appName); // 'World Biblio Tech'
+console.log(worldBiblioTechBranding.url);
+console.log(worldBiblioTechBranding.images.logo); // asset path
+```
+
+**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;
+  };
+}
+```
+
+**Type: `FounderInfo`**
+```typescript
+interface FounderInfo {
+  name: string;
+  email: string;
+  title?: string;
+}
+```
+
+**Type: `BuilderInfo`**
+```typescript
+interface BuilderInfo {
+  name: string;
+  title?: string;
+}
+```
+
+**Type: `SocialMediaUrls`**
+```typescript
+interface SocialMediaUrls {
+  x?: string;        // Twitter/X
+  github?: string;
+  linkedin?: string;
+  // ... other platforms
+}
+```
+
+---
+
+## Appendix: Type Quick Reference
+
+### 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)
+- `PruningState` — LRU cache eviction activity
+- `InitOptions` — downloader setup parameters
+
+### Models Types
+- `ModelDefinition` — schema for a model type
+- `LevelData` — user's reading level and corpus progress
+- `BootData` — result of `bootstrapModelsV2()`
+- `TrashStore` — global trash index API (`list`/`count`/`usernames`/`subscribe`)
+
+### Web3 Types
+- `Web3SessionAccount` — wallet state in session store
+- `SessionState` — `{ active, known }`
+- `ReadOnlyDomainAPI` — read client interface
+- `EvmChainConfig` — chain metadata
+- `ProjectLocale` — project with selected language
+- `Project` — raw contract data
+- `ProjectVersion` — project version metadata
+- `SyncResult` — subscription sync result
+- `SyncCursor` — resume point for incremental sync
+- `WalletState` — transaction event enums
+- `WalletError` — error reason enums
+- `BootstrapResult` — app initialization result
+
+### Branding Types
+- `AppBranding` — app-specific branding data
+- `FounderInfo` — founder contact info
+- `BuilderInfo` — builder/team info
+- `SocialMediaUrls` — social media links