@the_library/public 1.0.0 → 2.0.0

package/README.md

@@ -17,11 +17,13 @@ This document provides exhaustive API reference for all exports from `@the_libra
    - [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)
 
@@ -754,6 +756,42 @@ await unregisterDownloaderSW();
 
 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}`.
 
+### Language Semantics (every value is per-language)
+
+**Every property is per-language by default** (`perLang: true` in the V2 schema, with no overrides) — not just `title`/`description` but also numbers, booleans, and notably the universal `safe`/`deleted` flags. Storage is `Map<propId, Map<Lang, value>>`; every patch carries a `langId` and writes exactly one language slot.
+
+**Read resolution** (`resolveLangValue`): exact language → lang-agnostic slot (`langId 0`, `Lang` code `""`) → single-value fallback (a prop with exactly one variant resolves for *every* language) → `undefined`.
+
+**Write accessors:**
+
+```typescript
+tag.title = 'Philosophy';          // implicit: writes Config.userLang's slot — THE DEFAULT
+tag.setTitle('哲学', 'zho');        // explicit language slot — translations/imports only
+tag.safe = false;                  // ⚠️ also lang-tagged! writes userLang's slot only
+```
+
+`title`, `description`, and `originalLang` (plus generated model props) have explicit-language accessors (`getTitle(lang)` / `setTitle(value, lang)`). `safe`, `deleted`, `ageGradeBand`, and `previewTxId` currently have **only** the implicit userLang accessors.
+
+#### Convention: the default language is the source of truth
+
+**Always use the implicit accessors (`rec.description = value`) unless the task is explicitly about a specific language — then, and only then, use `rec.setDescription(value, lang)`.** The same rule applies to every property on every model.
+
+Why:
+
+1. **Write/read symmetry** — implicit getters resolve `Config.userLang` first and implicit setters write that same slot, so the author's session always sees its own edit. An explicit write to another language's slot is invisible to the session that made it.
+2. **Graceful degradation** — a value that exists only under the default language still renders in every language (single-value fallback) until a real translation is added. Premature explicit-lang variants switch that fallback off: once two variants exist, languages without an exact match resolve nothing.
+3. **Shadowing is permanent** — exact-language slots beat the agnostic slot and are never cleared by writes to other slots. Every unnecessary explicit-lang write creates a variant that must be maintained forever (a stale `fra` description will keep shadowing a corrected default one).
+4. **The pipeline assumes it** — queue LWW consolidation and the per-corpus publish bake both treat the default-language stream as canonical; multilingual variants are the deliberate exception (translations, multilingual imports), not the ambient state.
+
+**Pitfalls to know:**
+
+1. **Flags are per-language.** `book.deleted = true` in an `eng` session does not mark the book deleted for a reader resolving `fra` if an exact `fra` value was hydrated from the `fra` sidecar's `deleteds` column. It only *looks* global while the flag has a single variant (single-value fallback).
+2. **Exact beats agnostic (shadowing).** A `langId 0` write lands in the agnostic slot and is invisible to any language that already holds an exact value. `patch()` never clears other languages' slots.
+3. **Global flips need every slot.** To change a flag for all languages, emit `EditPropertyNumber` ops per language (or `langId: 0` when no exact-lang values exist — e.g. freshly user-created records, whose only flag slots are the constructor's agnostic seeds).
+4. **LWW consolidation is lang-keyed** (`${propertyId}:${langId}` in `Patches.cleanData`), so queued edits in different languages never collapse each other.
+
+**Publish-side counterpart:** the corpus bake resolves patch-log edits per corpus language with the same fallback chain — see book-manager's `specifications/lang-aware-patch-baking.md`, including its documented deviation (base values don't count as variants at bake time, so single-language flag edits bake into every corpus).
+
 ### Core Types & Registry
 
 #### `Registry` (singleton, exported from `registry.ts`)
@@ -1063,6 +1101,137 @@ 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.
+
+```typescript
+import { Stats, PopulateStatsStore, DownloadsByType, VisitsByType, FavoritesByTypes } from '@the_library/public/models';
+```
+
+**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.
+- 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)
+
+`Map<objectType, Map<uid, StatSummary>>`. All reads/writes go through the functions and the `Stats` class below — there is no direct export because the map is rebuilt wholesale on every boot via `PopulateStatsStore()`.
+
+#### `PopulateStatsStore(operations: Array<LocalOp>): void`
+
+Applies a batch of local analytics ops to `StatsStore`, creating a fresh `StatSummary` (`{ visits: [], downloads: [], rating: Rating.None, socialMediaId: [], parts: {} }`) for any `(objectType, objectId)` pair seen for the first time. Used internally by `Stats`'s instance methods (one-op batches) and by boot-time replay (bulk). Safe to call directly when replaying stored ops (e.g. from a worker) without wanting to also re-emit patches.
+
+**Parameters:**
+- `operations: Array<LocalOp>` — ops with `action` one of `ActionTypes.Visit | VisitPart | Download | Rate | RatePart | Share | SharePart`.
+
+**Returns:** `void`
+
+---
+
+#### `DownloadsByType(objectType: number): Array<uid>`
+
+Ids of every record of `objectType` that has at least one recorded download.
+
+#### `VisitsByType(objectType: number): Array<uid>`
+
+Ids of every record of `objectType` that has at least one recorded visit.
+
+#### `FavoritesByTypes(objectType: number): Array<{ id: uid, nbVisits: number, rating: Rating }>`
+
+Ids "worth surfacing" for `objectType` — any record with a visit, a download, or a rating of `Rating.Keep`, `Rating.New`, or `Rating.Shared` — sorted by `nbVisits` descending. Used to power "your library" / favorites views (see `DownloadedBooks.vue`, `VisitedBooks.vue`, `MyBooksIdsTab.vue` in the Vue app).
+
+```typescript
+import { Book, Tag } from '@the_library/public/models/models';
+import { DownloadsByType, VisitsByType, FavoritesByTypes } from '@the_library/public/models';
+
+const downloadedBookIds = DownloadsByType(Book.type).map(id => Book.Load(id));
+const visitedTagIds = VisitsByType(Tag.type);
+const favoriteBooks = FavoritesByTypes(Book.type); // sorted, most-visited first
+```
+
+---
+
+#### `class Stats`
+
+Base class `Orm` extends — normally accessed through a record instance (`book.visit()`), not instantiated directly.
+
+```typescript
+constructor(objectId: uid, objectType: number)
+```
+
+**Instance methods:**
+
+- `visit(): void` — Records a visit (timestamp via `DateUtils.now()`, seconds since the package's fixed inception date — not raw Unix epoch).
+- `download(): void` — Records a download.
+- `share(socialMediaId: number): void` — Records a share to a given social media channel id.
+- `ratePart(partId: number, rating: Rating): void` — Sets the rating for a sub-part (e.g. a book chapter) of the record.
+- `visitPart(partId: number): void` — Records a visit to a sub-part.
+- `get rating(): Rating` / `set rating(rating: Rating)` — Whole-record rating. The getter lazily creates the `StatSummary` (via internal `check()`) if none exists yet, so reading never throws for a never-touched record.
+- `favoriteParts(): Array<{ partId: number, nbVisits: number, rating: Rating }>` — This record's sub-parts with any visits, sorted by `nbVisits` descending.
+
+Every mutating method above follows the same shape: build a typed op → `PopulateStatsStore([op])` (apply locally, synchronous) → `PatchInstance.addPatch(op)` (queue + persist). Reads never touch the patch queue.
+
+```typescript
+import { Book } from '@the_library/public/models/models';
+import { Rating } from '@the_library/public/models';
+
+const book = await Book.LoadAsync(id);
+book.visit();               // whole-record visit
+book.visitPart(3);          // e.g. chapter 3
+book.rating = Rating.Keep;  // whole-record rating
+book.ratePart(3, Rating.Keep);
+book.share(socialMediaId);
+book.favoriteParts();       // [{ partId: 3, nbVisits: 1, rating: Rating.Keep }]
+```
+
+**Real-world pattern** (`router/analytics.ts`): visiting a `Tag` also visits every ancestor tag up the `inTagsIds` chain, and visiting a `Book` also visits every `Tag` it belongs to — so browsing a book implicitly credits the whole topic path it hangs off, not just the leaf record.
+
+**Type: `StatSummary`**
+```typescript
+type StatSummary = {
+  visits: Array<number>;       // timestamps (DateUtils.now() units)
+  downloads: Array<number>;
+  rating: Rating;
+  socialMediaId: Array<number>;
+  parts: {
+    [partId: string]: {
+      rating: Rating;
+      visits: Array<number>;
+      socialMediaId: Array<number>;
+    }
+  };
+}
+```
+
+**Type: `ActionTypes`** (local-only op discriminator — do not confuse with EVM `PatchOperation`)
+```typescript
+enum ActionTypes {
+  Visit = 0,
+  VisitPart = 1,
+  Download = 2,
+  Rate = 3,
+  RatePart = 4,
+  Share = 5,
+  SharePart = 6,
+}
+```
+
+**Type: `Rating`**
+```typescript
+enum Rating {
+  None,
+  New,
+  Keep,
+  Trash,
+  Shared,
+}
+```
+
+**Type: `LocalOp`** (and its variants `BaseLocalOp`, `RateOp`, `PartOp`, `RatePartOp`, `ShareOp`, `SharePartOp`) — the local-analytics half of `QueueItem` (`AnyPatch | LocalOp`). `isEvmPatch(item)` discriminates the two by checking for a defined `operation` field.
+
+---
+
 ### Framework Adapters (`/models/{vue,react,solid,astro}`)
 
 #### Vue Composables
@@ -1380,13 +1549,13 @@ Hydrates a wallet account after connection by pulling `hasAccount`, `username`,
 ```typescript
 import { syncAccount } from '@the_library/public/web3';
 
-const account = await syncAccount('0xabc...', 1116, 'metamask');
+const account = await syncAccount('0xabc...', 146, 'metamask');
 console.log(`${account.username} is level ${account.level}`);
 ```
 
 **Parameters:**
 - `address: string` — Wallet address (hex).
-- `chainId: number` — Chain ID (1116, 1114, etc.).
+- `chainId: number` — Chain ID (146, 14601, etc.).
 - `walletType: WalletType` — `'metamask'` or `'private_key'`.
 
 **Returns:** `Promise<Web3SessionAccount>` — The hydrated account record.
@@ -1427,7 +1596,7 @@ Gets the read-only client for a chain. Blocks until contract addresses/ABIs are
 ```typescript
 import { getReadClient } from '@the_library/public/web3';
 
-const client = getReadClient(1116);
+const client = getReadClient(146);
 await client.ready; // wait for registry load
 
 const balance = await client.projectManagerStorage.balanceOfAddress('0xabc...');
@@ -1436,7 +1605,7 @@ const nbAccounts = await client.bouncerStorage.nbAccounts();
 ```
 
 **Parameters:**
-- `chainId: number` — EVM chain ID (1116, 1114, 84532, etc.).
+- `chainId: number` — EVM chain ID (146, 14601, 84532, etc.).
 - `environment?: 'production' | 'staging'` — Defaults to `'production'`. Use `'staging'` to read staging-deployed contract addresses.
 
 **Returns:** `ReadOnlyDomainAPI` — Typed interface to all contract reads.
@@ -1620,7 +1789,7 @@ If a transaction throws and the run-lock needs to be cleared manually, call `res
 ```typescript
 import { getChain, EVM_CHAINS, DEFAULT_CHAIN_ID } from '@the_library/public/web3';
 
-const chain = getChain(1116);
+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
 
@@ -1630,10 +1799,10 @@ 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' | ...
+  name: string;              // 'Sonic' | 'Sonic Blaze' | 'Base Sepolia'
+  shortName: string;         // 'TREE' | 'WATER' | ... (mainnet/testnet shorthand codenames, not the chain name)
   chainId: number;
-  symbol: string;            // 'CORE' | 'CORETST' | ...
+  symbol: string;            // 'S' | ...
   logo: string;              // URL to chain logo
   explorer: string;          // Block explorer URL
   rpc: string[];             // RPC endpoints
@@ -1650,13 +1819,13 @@ interface EvmChainConfig {
 ```typescript
 import { useChain } from '@the_library/public/web3/vue';
 
-const { chain, client, usdPrice, refreshPrice, isMainnet, chainRouteQuery } = useChain(1116);
+const { chain, client, usdPrice, refreshPrice, isMainnet, chainRouteQuery } = useChain(146);
 // 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
+// chainRouteQuery: { chainId: '146' } — useful for router links
 ```
 
 ---
@@ -1671,7 +1840,7 @@ Dynamic contract address and ABI resolution from the on-chain `AddressRegistry`.
 import { addressLoader, setRegistryBaseUrl } from '@the_library/public/web3';
 
 // Set custom registry host (before anything else runs)
-setRegistryBaseUrl('https://registry.world.bibliotech.com');
+setRegistryBaseUrl('https://registry.worldbibliotech.com');
 
 // Subscribe to per-contract load progress
 const unsubscribe = addressLoader.subscribe((chainId, status) => {
@@ -1697,7 +1866,7 @@ const abi = addressLoader.getAbi(chainId, 'Factory');
 
 #### `setRegistryBaseUrl(url: string): void`
 
-Override the default registry host URL (normally `https://registry.world.bibliotech.com`). Call before any clients are instantiated.
+Override the default registry host URL (normally `https://registry.worldbibliotech.com`). Call before any clients are instantiated.
 
 ---
 
@@ -1712,7 +1881,7 @@ Gets a chain-scoped subscription client.
 ```typescript
 import { getSubscriptionClient } from '@the_library/public/web3';
 
-const subs = getSubscriptionClient(1116);
+const subs = getSubscriptionClient(146);
 
 // First sync: full BFS walk + patch fetch
 const { patches, cursor, truncated } = await subs.sync(rootUserId);
@@ -1943,8 +2112,8 @@ if (!meta.isInstalled() && meta.isInstallable()) {
 ```typescript
 import { storePrivateKey, hasPrivateKey, hasAnyPrivateKey } from '@the_library/public/web3';
 
-storePrivateKey(1116, '0x1234...'); // raw hex, no '0x' prefix required
-if (hasPrivateKey(1116)) {
+storePrivateKey(146, '0x1234...'); // raw hex, no '0x' prefix required
+if (hasPrivateKey(146)) {
   // PrivateKeyConnector can connect to this chain
 }
 
@@ -1968,11 +2137,11 @@ 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);
+const project = await loadProject(146, '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);
+const fresh = await loadProject(146, 'eng', 5, true);
 ```
 
 **Parameters:**
@@ -1994,7 +2163,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(1116, 'eng');
+const projects = await loadProjects(146, 'eng');
 const validProjects = projects.filter(p => p !== null);
 ```
 
@@ -2014,7 +2183,7 @@ Helper to convert raw `Project` data to `ProjectLocale` with language selection
 import { projectLocale } from '@the_library/public/web3';
 
 const raw = await client.projectManagerStorage.loadProject(5);
-const locale = projectLocale(raw, 'eng', 1116);
+const locale = projectLocale(raw, 'eng', 146);
 ```
 
 **Parameters:**
@@ -2031,7 +2200,7 @@ const locale = projectLocale(raw, 'eng', 1116);
 ```typescript
 import { useLoadProjects } from '@the_library/public/web3/vue';
 
-const chainId = ref(1116);
+const chainId = ref(146);
 const language = ref('eng');
 
 const { projects, isLoading, error, reload } = useLoadProjects(chainId, language);
@@ -2051,8 +2220,8 @@ const { projects, isLoading, error, reload } = useLoadProjects(chainId, language
 import { EVM_CHAINS } from '@the_library/public/web3';
 
 // EVM_CHAINS = {
-//   1116: { name: 'CORE', ... },
-//   1114: { name: 'tCORE2', ... },
+//   146: { name: 'Sonic', ... },
+//   14601: { name: 'Sonic Blaze', ... },
 //   84532: { name: 'Base Sepolia', ... },
 // }
 ```
@@ -2061,7 +2230,7 @@ import { EVM_CHAINS } from '@the_library/public/web3';
 
 #### `DEFAULT_CHAIN_ID` (constant)
 
-The default chain for new users (usually production mainnet, e.g., `1116`).
+The default chain for new users (usually production mainnet, e.g., `146`).
 
 ---
 
@@ -2072,7 +2241,7 @@ Gets full metadata for a chain. Throws if `chainId` is not registered.
 ```typescript
 import { getChain } from '@the_library/public/web3';
 
-const chain = getChain(1116);
+const chain = getChain(146);
 console.log(`${chain.name} (${chain.symbol})`);
 ```
 
@@ -2090,7 +2259,7 @@ import { bootstrapWebSDK, BootstrapResultKey } from '@the_library/public/web3/vu
 const result = await bootstrapWebSDK({
   withTest: true,
   environment: 'production',
-  chainFilter: [1116, 1114], // optional: limit to these chains
+  chainFilter: [146, 14601], // optional: limit to these chains
 });
 
 await result.ready; // wait for account discovery
@@ -2154,13 +2323,13 @@ const {
 ```typescript
 import { useChain } from '@the_library/public/web3/vue';
 
-const { chain, client, usdPrice, refreshPrice, isMainnet, chainRouteQuery } = useChain(1116);
+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: '1116' }
+// chainRouteQuery: { chainId: '146' }
 ```
 
 ---
@@ -2171,7 +2340,7 @@ const { chain, client, usdPrice, refreshPrice, isMainnet, chainRouteQuery } = us
 import { useLoadProjects } from '@the_library/public/web3/vue';
 
 const { projects, isLoading, error, reload } = useLoadProjects(
-  ref(1116),
+  ref(146),
   ref('eng')
 );
 ```
@@ -2276,6 +2445,10 @@ interface SocialMediaUrls {
 - `LevelData` — user's reading level and corpus progress
 - `BootData` — result of `bootstrapModelsV2()`
 - `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`, ...)
+- `Rating` — `None` / `New` / `Keep` / `Trash` / `Shared`
+- `LocalOp` (`BaseLocalOp`, `RateOp`, `PartOp`, `RatePartOp`, `ShareOp`, `SharePartOp`) — local analytics op variants
 
 ### Web3 Types
 - `Web3SessionAccount` — wallet state in session store

package/assets/branding/pond-enterprise-logo.svg

@@ -4,7 +4,7 @@
   -    * Non-Profit Public Library — The World Library
   -    *
   -    * Licensed under the D-Open Code Sovereign Licence v1.0
-  -    * https://registry.world.bibliotech.com/licence
+  -    * https://registry.worldbibliotech.com/licence
   -    *
   -    * Technical Guardian ("The Shield"): Pond Enterprise Pty Ltd. (ACN 694 747 987)
   -    * All liability claims directed to Pond Enterprise Pty Ltd.