npm - @voltro/cli - Versions diffs - 0.27.0 → 0.29.0 - Mend

@voltro/cli 0.27.0 → 0.29.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (284) hide show

package/templates/agent-docs/internationalization.md CHANGED Viewed

@@ -51,7 +51,11 @@ Server-side, the active locale is determined by, in priority order:
 The resolved locale is **guaranteed** to be one of the codes in `locales`. Any unsupported value (a cookie pointing at a code you no longer ship, a browser asking for `xx-YY`) falls through to the next signal. RFC 4647 lookup strips subtags one segment at a time — `de-CH-1996` → `de-CH` → `de` — so a `de` catalog serves a `de-CH` browser.
-The client side mirrors #1 (cookie) and #3 (default) for hydration safety. `Accept-Language` is **server-only** because `navigator.languages` can diverge from what the server saw, which would cause a hydration mismatch.
+The client **adopts what the server resolved**, reading it from the `<html lang>` attribute the server render sets, then falling back to the cookie and the default. `Accept-Language` is never read in the browser: `navigator.languages` can diverge from what the server saw.
+> Earlier versions said the client "mirrors cookie and default for hydration safety". That was the opposite of what happened. Dropping the `Accept-Language` signal is not the same as agreeing with the server about it — on a first visit, with no cookie yet, the server negotiated `Accept-Language` while the client fell through to `defaultLocale`. An English browser on a German-default app therefore hydrated `de` over an `en` tree and React discarded the entire server render, which is exactly what SSR was enabled to avoid. It stopped as soon as anything wrote the cookie, so one language switch made it un-reproducible for that developer.
+`<html lang>` carries the same resolved locale — the value the `<I18nProvider>` renders with, on the same request. That matters on its own: it is what a screen reader pronounces in, what Chrome offers to translate *from*, and what hyphenation uses.
 See [Catalogs](/docs/i18n/catalogs) for the type-safe catalog convention and the component hooks, [Plurals & formatting](/docs/i18n/formatting) for CLDR plural selection and the `Intl`-backed date / number / relative-time hooks, and [URL strategies](/docs/i18n/url-strategies) for cookie-only vs URL-prefix routing.
@@ -697,3 +701,159 @@ For dates, numbers and relative time the hooks are the blessed path; reach for `
 - **Don't pin a global `timeZone` / locale for the whole app.** The formatters resolve the active locale from the provider; a pin makes every viewer read the app in one user's settings.
 - **Don't pass a locale-formatted string to a machine consumer.** Formatted output is presentation — send ISO strings and raw numbers to APIs, `dateTime` attributes and sort keys.
 - **Don't format inside a `.map()` by constructing `Intl` objects yourself.** The hooks memoize per locale; a fresh `new Intl.NumberFormat(...)` per row is the slow path.
+---
+<!-- source: en/i18n/datetime.md -->
+## Dates & timezones
+_"@voltro/datetime — UTC-instant storage, timezone-aware arithmetic/formatting on TC39 Temporal, and the request-scoped timezone-context seam."_
+`@voltro/datetime` is the framework's opinion on time: **store UTC instants,
+render in the viewer's timezone, never do zone math by hand.** It is built on the
+[TC39 Temporal](https://tc39.es/proposal-temporal/docs/) standard (via a
+polyfill, so the API is identical on the server and in the browser) and ships
+pure, browser-safe helpers plus a request-scoped timezone seam.
+The `.` entry is browser-safe — no `effect`, no `node:*` — so a route or
+component can import it directly. The Effect seam lives in a separate subpath,
+`@voltro/datetime/context`, so the pure surface carries no `effect` dependency.
+> **Phase 1.** This is the storage + timezone + formatting layer. Schema-DSL
+> temporal column types, `interval()`, and `rrule()` are later phases; use
+> `timestamp()` columns and these helpers today.
+## The storage contract: a `Date` is a UTC instant
+`timestamp()` stores `TIMESTAMPTZ`, and the driver hands your app code a plain JS
+`Date`. A `Date` is a bare epoch-millisecond count with no zone of its own, so
+the ONLY correct reading of it is "the UTC instant it points at". These helpers
+make that reading explicit and lossless in both directions:
+```ts
+import { toInstant, toUTCString, isValidTimeZone } from '@voltro/datetime'
+// A `Date` from a query IS a UTC instant — read it as one, losslessly.
+const when = toInstant(row.createdAt)   // Temporal.Instant
+toUTCString(row.createdAt)              // "2026-08-06T12:00:00Z" — the wire/storage form
+isValidTimeZone('Europe/Berlin')        // true
+isValidTimeZone('Mars/Phobos')          // false
+```
+`toInstant` accepts a `Temporal.Instant`, a JS `Date`, or an ISO-8601 string —
+but a string MUST carry an explicit offset or `Z`. A naive `2026-01-01T12:00`
+denotes no instant and throws, by design: the whole point is that there is no
+silent zone-guessing. Bridge back with `toDate(instant)` for storage or interop.
+## Timezone resolution — the framework convention
+Which zone should a given request render in? Resolve it in priority order, each
+candidate validated as an IANA name, falling back to `UTC`:
+```ts
+import { resolveTimezone } from '@voltro/datetime'
+const tz = resolveTimezone({
+  userTimeZone:    user.timezone,        // 1. the viewing user's profile
+  tenantTimeZone:  tenant.timezone,      // 2. the tenant / org default
+  browserTimeZone: 'Europe/Berlin',      // 3. the browser-reported zone
+})                                        // → a validated IANA name, else 'UTC'
+```
+This mirrors `@voltro/i18n`'s `resolveLocale` in spirit — pure, framework-agnostic,
+no Effect or RPC — so it runs in any request pipeline. An invalid or absent
+candidate falls through to the next signal; the result is GUARANTEED valid.
+### Carrying it through a request — the context seam
+The resolved zone travels through a request via an Effect context tag in
+`@voltro/datetime/context`, so any route, mutation, workflow, or agent can read it:
+```ts
+import { currentTimezone, withTimezone } from '@voltro/datetime/context'
+import { Effect } from 'effect'
+const program = Effect.gen(function* () {
+  const tz = yield* currentTimezone   // the request's zone, or 'UTC' when none set
+  return tz
+})
+// Provide an explicit zone for a sub-computation:
+program.pipe(withTimezone('Europe/Berlin'))
+```
+`currentTimezone` never fails — an absent context is the documented `UTC`
+default, so call sites don't handle a missing-service error. The runtime provides
+the tag per request (via `resolvedTimezoneLayer`); the web layer's `useTimezone()`
+hook is a thin projection over it.
+## Arithmetic — the DST split is in the names
+Every operation that is ambiguous without a zone REQUIRES an IANA `timeZone`
+argument. There is no implicit "system zone", so a call site cannot silently do
+the wrong thing on a differently-configured box. The DST distinction is
+deliberate and encoded in the method names:
+```ts
+import { addDays, addHours, startOfDay, endOfDay } from '@voltro/datetime'
+// WALL-CLOCK: same local time, one calendar day later in Berlin.
+// Across a DST boundary the elapsed real time is 23h or 25h. Needs a zone.
+addDays(when, 1, 'Europe/Berlin')
+// EXACT elapsed time: 24 × 3600 seconds, DST-oblivious. No zone.
+addHours(when, 24)
+// Zone-relative day boundaries.
+startOfDay(when, 'Europe/Berlin')
+endOfDay(when, 'Europe/Berlin')
+```
+`addDays` / `addMonths` are wall-clock ("same local time, N days on"); `addHours`
+is exact elapsed time. Comparisons that measure absolute instants (`isAfter`,
+`isBefore`) take no zone; `isSameDay` does, because "same day" is a wall-clock
+question. For a calendar date with no time and no zone — a birthday, a holiday, a
+due date — use `plainDate(year, month, day)` / `parseDate('2026-08-06')`.
+## Formatting — locale- and timezone-aware
+Formatting is where the viewer's timezone and locale are APPLIED. Both are
+explicit arguments — this layer carries no ambient locale (the web layer resolves
+`useLocale()` and passes it in):
+```ts
+import { formatDate, formatDateTime, formatRelativeTime } from '@voltro/datetime'
+formatDate(row.createdAt, 'Europe/Berlin', { locale: 'de' })        // "6. Aug. 2026"
+formatDateTime(row.createdAt, 'America/New_York', { locale: 'en' })
+formatRelativeTime(row.createdAt, { locale: 'en' })                 // "3 hours ago"
+```
+`FormatOptions` is `{ locale? }` plus any `Intl.DateTimeFormatOptions` override,
+so `formatDate(when, tz, { locale, dateStyle: 'full' })` works. `formatRelativeTime`
+picks the largest unit that fits the signed distance from `now` (default: the
+current instant) and is zone-independent — it measures elapsed real time, not
+wall-clock days.
+> These helpers are the STORAGE/TIMEZONE layer. `@voltro/i18n`'s
+> [`useFormatDate` / `useRelativeTime`](/docs/i18n/formatting) hooks are the
+> React binding that read the active locale from the provider; reach for those in
+> components, and for `@voltro/datetime` in server code, loaders, and tests.
+## Temporal directly
+The exact standard `Temporal` types are re-exported, so you can drop to the full
+API when a helper doesn't cover your case:
+```ts
+import { Temporal } from '@voltro/datetime'
+const noon = Temporal.PlainTime.from('12:00')
+```
+Import `Temporal` from `@voltro/datetime`, never from the polyfill directly — that
+keeps the eventual switch to the native global (once it is universal in browsers)
+a one-line change for the whole codebase.

package/templates/agent-docs/local-first-mobile.md ADDED Viewed

@@ -0,0 +1,414 @@
+# Local-first & Mobile
+> "@voltro/local-first — CRDT text merge (crdtText/mergeCrdtStates), the offline sync-queue + SyncClient wire, presence/awareness, durable persistence, and the localFirst table mixin. Pure and browser-safe; the React hooks live behind a subpath."
+---
+<!-- source: en/local-first/overview.md -->
+## Local-first & CRDTs
+_"@voltro/local-first — CRDT text merge (crdtText/mergeCrdtStates), the offline sync-queue + SyncClient wire, presence/awareness, durable persistence, and the localFirst table mixin. Pure and browser-safe; the React hooks live behind a subpath."_
+`@voltro/local-first` is the framework's foundation for **offline-capable,
+multiplayer, convergent** apps: edit while disconnected, see other peers' cursors,
+and reconcile without losing work when the network returns. The `.` entry is
+**pure and browser-safe** — no `effect`, no `node:*` — so a route or component
+imports it directly. The React wrappers live behind `@voltro/local-first/react`
+(React is an optional peer, so the pure path never pulls it in).
+> **What ships today**: the pure CRDT text merge, the offline sync-queue reducer,
+> the connection-lifecycle state machine, the conflict policy, the
+> [`crdtText()` database column](#the-crdttext-database-column) (with its
+> authoritative server-side merge on the write path), the
+> [`SyncClient`](#the-syncclient-bi-directional-wire) that drives the queue over a
+> transport, [presence/awareness](#presence--awareness) via `usePresence`,
+> [durable IndexedDB persistence](#durable-persistence), and the
+> [`localFirst` table mixin](#the-localfirst-table-mixin). What remains is a thin
+> [runtime binding](#whats-shipped-vs-a-runtime-seam) to provisioned infra
+> (a broker at scale, a running app's transport) — not un-built framework code.
+## CRDT text: `crdtText` + `mergeCrdtStates`
+A CRDT (Conflict-free Replicated Data Type) text field can be edited by many
+peers offline and always converges to the same result. `crdtText()` builds one
+(Yjs-backed behind the `CrdtBackend` abstraction), and `mergeCrdtStates()` is
+the heart of the package — it converges two encoded states into one,
+deterministically and order-independently.
+```ts
+import { crdtText, mergeCrdtStates, decodeCrdtText } from '@voltro/local-first'
+// A field, edited offline. `insert`/`delete` mutate and return the same handle.
+const doc = crdtText('Hello').insert(5, ', world')
+const state = doc.encode() // the wire/storage form: a CrdtState
+// Converge two peers' encoded states — order-independent, no lost edits.
+const remote = crdtText('Hello').insert(5, ' there').encode()
+const merged = mergeCrdtStates(state, remote)
+decodeCrdtText(merged) // the plain-string view; both edits survive
+```
+`mergeCrdtStates` is deterministic (`decodeCrdtText(mergeCrdtStates(a, b))`
+equals the same for `(b, a)`), idempotent (re-merging a contained state is a
+no-op), and treats `emptyCrdtState()` as identity. The backend is a parameter on
+every function (defaulting to Yjs), so a later swap to Loro touches no call site.
+## The `crdtText()` database column
+`@voltro/database` ships a `crdtText()` **column type** for CRDT-managed fields.
+It needs no special DDL — to the declarative differ it is an ordinary nullable
+`bytes` column (BYTEA / BLOB / LONGBLOB / VARBINARY), so it plans and round-trips
+on every dialect like any other:
+```ts
+import { table, id, text, crdtText } from '@voltro/database'
+export const documents = table('documents', {
+  id: id(),
+  title: text(),
+  body: crdtText(), // CRDT-managed field — stored as the encoded state (bytes)
+})
+```
+The row type is `Uint8Array | null` (the encoded CRDT state); decode it to a
+string with `decodeCrdtText()`, and produce writes with a `crdtText()` handle's
+`.encode()`. The merge is **authoritative and server-side**: the runtime folds an
+incoming update into the stored state with `mergeCrdtStates` on the write path
+before writing, then the reactive engine broadcasts the merged result — which is
+what makes concurrent edits converge without a last-write-wins loser.
+## The `localFirst` table mixin
+`localFirst()` **marks a table as local-first** — mirrored to the client, synced
+bi-directionally, and (for its `crdtText()` fields) converged via CRDT merge. It
+adds no column; it is a property the framework reflects on.
+```ts
+import { table, id, text, crdtText, localFirst } from '@voltro/database'
+export const documents = table('documents', {
+  id: id(),
+  title: text(),
+  body: crdtText(),
+}).with(localFirst()) // opt this table into local-first sync + persistence
+```
+Discovery needs no codegen change — a marker mixin rides `.with()` like any
+column type. `isLocalFirst(table)` and `localFirstTables(schema)` are pure
+helpers, and the runtime's schema registry reflects it as `hasLocalFirst(table)`
+(beside `crdtColumns(table)`), which is the signal a client-sync-set builder
+reads. A local-first table may also carry plain columns — those sync
+last-write-wins via the [conflict policy](#conflict-policy-for-non-crdt-fields).
+## The `SyncClient`: bi-directional wire
+`createSyncClient({ transport })` maps the offline sync queue onto a transport:
+a local edit merges optimistically and queues; reconnect drains it to the server
+with retry; incoming merged state folds back via the CRDT — and concurrent edits
+converge. It invents **no** transport of its own — the `SyncTransport` is two
+functions an app binds to its **existing** wire:
+- `push` — deliver a queued CRDT write. Bound to a [`useMutation`](/docs/data/mutations)
+  that writes the `crdtText()` column (the server folds it authoritatively).
+- `onRemoteState` — receive merged state. Bound to the reactive
+  [`useSubscription`](/docs/data/queries) that already streams the row.
+```ts
+import { createSyncClient } from '@voltro/local-first'
+const sync = createSyncClient({
+  transport: {
+    kind: 'sync-transport',
+    push: (write) => runMutation('documents.setBody', write.payload),
+    onRemoteState: (handler) =>
+      subscribeRow('documents', (row) =>
+        handler({ table: 'documents', id: row.id, column: 'body', state: row.body }),
+      ),
+  },
+  adapter: durablePersistence, // optional — survives a reload
+})
+// A local edit: merges locally at once, queues, drains when online.
+sync.enqueue({ table: 'documents', id: 'd1', column: 'body', update: doc.encode() })
+sync.getText({ table: 'documents', id: 'd1', column: 'body' }) // the merged view
+```
+Everything below the two transport functions — the drain loop, retry/attempt
+counting, optimistic local merge, durable persistence — is in the client and
+tested against an in-memory dispatcher that mirrors the server's merge.
+## Presence & awareness
+`usePresence(roomId, self, { channel })` publishes this peer's ephemeral state
+(cursor, name, selection) and returns everyone else's — the multiplayer cursors
+of a collaborative editor. Presence is **ephemeral and high-frequency**, so it
+rides a pub/sub channel, never Postgres CDC or a table.
+```tsx
+import { usePresence } from '@voltro/local-first/react'
+function Editor({ documentId, channel }) {
+  const { presence, others, setPresence } = usePresence(
+    documentId,
+    { cursor: 0, name: 'Ada' },
+    { channel },
+  )
+  // render `others` as remote cursors; update on selection change:
+  const onSelect = (cursor: number) => setPresence({ cursor, name: 'Ada' })
+  return <Cursors others={others} />
+}
+```
+The `PresenceChannel` is the **same dumb string-payload pub/sub shape** as the
+framework broker (`@voltro/plugin-broadcast`), so a runtime binding forwards
+straight onto the app's provisioned broker — in-memory locally,
+Redis/NATS at scale (both already shipped). `createInMemoryPresenceChannel()` is
+the local/test transport. Join/leave, announce-back discovery, cursor
+propagation, and TTL expiry live in the pure `createPresenceRoom` the hook wraps.
+## The offline sync queue
+`useSyncQueue()` is a reactive view over a **pure, tested reducer**: writes made
+offline are queued, and a transport drains them when connectivity returns. Use it
+directly for fine-grained UI, or let the [`SyncClient`](#the-syncclient-bi-directional-wire)
+drive it for you.
+```tsx
+import { useSyncQueue, useConnectionStatus } from '@voltro/local-first/react'
+function SaveIndicator() {
+  const queue = useSyncQueue()
+  const { status } = useConnectionStatus(queue.outstanding)
+  // `outstanding` counts pending + in-flight (0 means synced).
+  return status === 'synced' ? null : <span>Saving… ({status})</span>
+}
+```
+## Connection status
+`useConnectionStatus(outstanding)` observes the connection lifecycle for the
+local-first layer — network up/down plus reconnect confirmation — and folds the
+number of unsynced writes into a display `status` of `offline | syncing |
+synced`, so `synced` means online **and** drained. It feeds the machine the two
+signals a browser can observe (`navigator.onLine` + the `online`/`offline`
+events); confirmed round-trips (`confirm()`/`confirmFailed()`) are left to the
+caller, so the hook never invents a server ping.
+> This is the local-first connection machine, distinct from `@voltro/client`'s
+> RPC-error-derived [`useConnectionStatus`](/docs/ui/client-utilities/use-connection-status) —
+> a different package with a different signal source.
+## Durable persistence
+Local CRDT state and the offline queue should survive a reload. Everything above
+storage speaks the `PersistenceAdapter` contract, so the backing swaps freely:
+- `createInMemoryPersistence()` — ephemeral (lost on reload); the test/default.
+- `createIndexedDbPersistence()` — **durable**, over the browser's own
+  IndexedDB. No WASM, no added dependency; the IDB implementation is injectable,
+  so it is tested against a fake backend that survives a reopen.
+```ts
+import { createIndexedDbPersistence } from '@voltro/local-first'
+const adapter = await createIndexedDbPersistence({ databaseName: 'my-app' })
+const sync = createSyncClient({ transport, adapter }) // state now survives reload
+```
+## Conflict policy for non-CRDT fields
+CRDT fields resolve themselves — the merge **is** the resolver. A plain scalar
+like `title` needs a policy. `conflictPolicy()` declares one per field; the
+default everywhere is last-write-wins, and any field you do not name falls back
+to it, so a policy never has to enumerate every column.
+```ts
+import { conflictPolicy } from '@voltro/local-first'
+const policy = conflictPolicy({
+  title: 'lastWriteWins',
+  // A custom resolver MUST converge: both peers pick the same winner.
+  tags: (local, remote) => (remote.updatedAt >= local.updatedAt ? remote.value : local.value),
+})
+policy.resolveRecord(
+  { title: { value: 'Draft', updatedAt: 1 } },
+  { title: { value: 'Final', updatedAt: 2 } },
+) // → { title: 'Final' }
+```
+The one property that matters is **convergence**: `lastWriteWins` breaks an
+exact `updatedAt` tie on a stable, symmetric key (writer id, then the value's
+string form), so two peers agree regardless of which side each calls "local".
+## What's shipped vs. a runtime seam
+The framework code for local-first is built and tested end to end against
+in-memory transports. What remains is not un-built framework — it is the thin
+binding to **provisioned infrastructure**, sitting behind interfaces the tested
+code already speaks:
+| Runtime seam | What it binds | Why it's a binding, not code |
+| --- | --- | --- |
+| **Sync transport → a running app** | The `SyncClient`'s `push`/`onRemoteState` to one app's `useMutation` + `useSubscription`. | The two functions are app-specific glue; the drain loop, merge, retry, and persistence all ship and are tested. |
+| **Presence channel → a broker at scale** | The `PresenceChannel` to a provisioned Redis/NATS broker. | It's a network hop over an already-shipped broker; the awareness logic ships and is tested over the in-memory channel. |
+| **wa-sqlite / Turso adapter** *(optional)* | A SQL durable adapter for cross-tab queries, behind `PersistenceAdapter`. | IndexedDB is the durable default today; a SQL backing is a sibling factory, nothing above it changes. |
+---
+<!-- source: en/react-native/overview.md -->
+## React Native
+_"@voltro/react-native — the credential-free mobile plumbing: registerDevice + the _voltro_devices table, defineDeepLink + its matcher, useBackgroundSync, and offline-first client defaults + connection status."_
+The existing React-client bindings already run in React Native — the runtime has
+no DOM dependency. `@voltro/react-native` adds the mobile-specific plumbing **on
+top** of that, limited to the parts that need **no per-tenant credentials and no
+native runtime**: device registration, background-sync scheduling, offline-first
+defaults, a connection-status surface, and the deep-link declaration shape.
+The package **root is RN-safe** — no `node:*`, no `@voltro/database`, and React
+is reached only through the hooks (an optional peer). The `_voltro_devices` table
+declaration is server-side and lives at `@voltro/react-native/schema`.
+## Device registration
+A device is registered **after** the OS issues its push token (APNs on iOS, FCM
+on Android, Web Push on web). `registerDevice()` normalises a raw input into a
+row and upserts it through whatever transport the app already has — a generated
+mutation caller or a plain `fetch` — so the package stays free of transport
+coupling.
+```ts
+import { registerDevice } from '@voltro/react-native'
+// `userId`/`tenantId` are stamped SERVER-side from the authenticated request —
+// never trusted from the client. `locale`/`timezone` default from the device.
+await registerDevice(
+  (row) => api.mutate('registerDevice', row),
+  { deviceToken, platform: 'ios' },
+)
+```
+Registration is idempotent: the row is stored in `_voltro_devices` with a unique
+key of `(platform, token)`, so re-registering the same token updates the row in
+place instead of inserting a duplicate. A **rotated** token is a new
+registration; reaping the stale one is the sender adapter's job (a seam), not the
+client's.
+### The `_voltro_devices` table
+The table declaration is a server-side entry — it imports the `@voltro/database`
+column DSL, so it is deliberately off the RN-safe root. Contribute it to your
+schema and it migrates like any framework table (the `_voltro_*` prefix rides the
+declarative differ on `voltro dev` / `voltro db apply`, on every dialect):
+```ts
+// schema/devices.ts — add the framework device table to your app's schema.
+export { devicesTable } from '@voltro/react-native/schema'
+```
+It carries tenant + user scope, `platform`, `token`, `locale`, `timezone`,
+optional `appVersion`/`metadata`, and a `lastSeenAt` rotation clock. It is unique
+on `(platform, token)` and indexed on `userId` — the hot read path for fanning a
+push out to every device of a user.
+## Deep links: `defineDeepLink` + the matcher
+`defineDeepLink({ pattern, handler })` is the descriptor a deep-link file
+declares; its pure matcher turns `/orders/:id` + `/orders/42` into `{ id: '42' }`.
+The params are inferred from the `:name` segments, so `handler` type-checks
+against exactly the params the pattern declares.
+```ts
+import { defineDeepLink } from '@voltro/react-native'
+export default defineDeepLink({
+  pattern: '/orders/:id',
+  handler: ({ id }) => navigateTo(`/orders/${id}`),
+})
+```
+The matcher is pure — no navigation, no side effects — and normalises scheme +
+host away, so a universal link, an App Link, and a custom-scheme URL all match
+the same path-only pattern:
+```ts
+import { matchDeepLink, matchFirstDeepLink } from '@voltro/react-native'
+import orderLink from './orders.deepLink'
+matchDeepLink('/orders/:id', '/orders/42') // → { id: '42' }
+matchDeepLink('/orders/:id', '/orders/42/edit') // → null
+// Until `*.deepLink.ts` file discovery lands, register links by hand —
+// declaration order wins, so list more-specific patterns first.
+const hit = matchFirstDeepLink([orderLink], 'myapp://orders/42')
+hit?.params.id // '42'
+```
+> **Seam — file discovery.** Wiring `*.deepLink.ts` into codegen (so the router
+> auto-collects every declared link) is one additive file, landing after the
+> current release settles. The descriptor shape above is **final**, so register
+> links via `matchFirstDeepLink()` until then.
+## Background sync
+`useBackgroundSync(onSync, options)` owns three triggers — an interval timer, a
+"returned to foreground" subscription, and a manual `sync()` — over a pure
+`shouldSync` policy (single-flight, foreground-gated, interval-gated). The OS
+background-fetch **registration** itself stays the app's; this hook is only the
+interval/foreground state machine.
+```tsx
+import { useBackgroundSync } from '@voltro/react-native'
+function SyncIndicator() {
+  const { status, lastSyncAt, sync } = useBackgroundSync(
+    () => api.refetchAll(),
+    { intervalMs: 60_000, syncOnForeground: true },
+  )
+  return <button onClick={sync}>Sync ({status})</button>
+}
+```
+`onSync` may be async — a rejection is captured into `status: 'error'` +
+`lastError`, a resolution into `status: 'success'` + `lastSyncAt`.
+## Offline-first defaults + connection status
+`offlineFirstDefaults` is the mobile posture as a value you spread into your
+client config: local-first ON, optimistic mutations, sync-on-foreground, a
+5-minute cadence, and a retry backoff schedule. `useMobileConnectionStatus()`
+surfaces a `connected | degraded | offline` status — `offline` from
+`navigator.onLine`, `degraded` from failures the app reports.
+```tsx
+import { offlineFirstDefaults, useMobileConnectionStatus } from '@voltro/react-native'
+// Spread the mobile posture into your client config.
+const config = { ...offlineFirstDefaults, url }
+function ConnectionPill() {
+  const { status, reportFailure, reportSuccess } = useMobileConnectionStatus()
+  return <span data-status={status}>{status}</span>
+}
+```
+## What's shipped vs. a seam
+This package ships the credential-free plumbing above. The parts that need
+external credentials or a native runtime are flagged as **deliberate seams** —
+not built here:
+| Seam | Why it is not in this package |
+|---|---|
+| **APNs / FCM sender adapters** | Need per-tenant Apple Developer / Firebase credentials — genuinely external, managed via provider provisioning. Registration stores the token; sending to it is the seam. |
+| **Native module bindings** (camera, biometrics, secure token storage) | Need a native runtime this TS package cannot provide. |
+| **Swift / Kotlin SDK generators** | An open product decision — not built until demand justifies the maintenance. |
+| **Universal-links / App-Links file automation** (`apple-app-site-association`, `assetlinks.json`) | A deployment-layer concern, not a client primitive. |
+| **`*.deepLink.ts` codegen discovery** | One additive file after the release settles; the descriptor shape is final, so register links via `matchFirstDeepLink()` today. |