@hadoku/prefs-client 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 WolffM
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,3 +1,98 @@
-# Temporary Holding Version
+# @wolffm/prefs-client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Client SDK for the hadoku unified preferences store. Wraps `hadoku.me/prefs/api/v1/*` with localStorage caching, debounced writes, Zod-validated reads, and a React `usePrefs()` hook.
+
+See [`docs/planning/unified-prefs-2026-05-20.md`](https://github.com/WolffM/hadoku_site/blob/main/docs/planning/unified-prefs-2026-05-20.md) for the architectural background.
+
+## Install
+
+```sh
+pnpm add @wolffm/prefs-client zod
+# React consumers also:
+pnpm add react
+```
+
+## Usage
+
+```ts
+import { z } from 'zod';
+import { createPrefsClient } from '@wolffm/prefs-client';
+import { usePrefs } from '@wolffm/prefs-client/react';
+
+const TaskPrefsSchema = z.object({
+  theme: z.string().optional(),
+  themeMode: z.enum(['simple', 'advanced']).optional(),
+  alwaysVerticalLayout: z.boolean().optional(),
+});
+
+export const taskPrefs = createPrefsClient({
+  appId: 'task',
+  schema: TaskPrefsSchema,
+  defaults: { theme: 'light', themeMode: 'simple' },
+  migrations: [
+    (blob) => {
+      if ('simpleMode' in blob) {
+        blob.themeMode = blob.simpleMode ? 'simple' : 'advanced';
+        delete blob.simpleMode;
+      }
+      return blob;
+    },
+  ],
+  bootstrapToSessionStorage: { theme: 'hadoku-theme' },
+});
+
+function Settings() {
+  const { prefs, save, loading } = usePrefs(taskPrefs);
+  if (loading || !prefs) return null;
+  return (
+    <ThemeToggle
+      value={prefs.theme}
+      onChange={(t) => save({ theme: t }, { scope: 'device' })}
+    />
+  );
+}
+```
+
+## Key behaviours
+
+- **Cache**: localStorage at `prefs-cache:{userId}:{appId}`. Stale-while-revalidate.
+- **Writes**: 1s-debounced PUT. Multiple `save()` calls within the window coalesce into one network call.
+- **Conflicts**: API-Always-Wins. On a 409 the SDK adopts the server blob and re-renders; the local patch is discarded.
+- **Cross-tab**: BroadcastChannel keyed by `prefs:{userId}:{appId}` propagates saves between tabs without a server roundtrip.
+- **Anon → authed**: call `client.promoteAnonPrefsToUser()` after sign-in. If the server already has user-scope prefs (signed in on another device first), the server wins.
+- **Dirty-field protection**: a background refresh (or an incoming cross-tab broadcast) never overwrites a field with a save still pending/in-flight — it merges the server/remote blob with your unconfirmed local value instead. Otherwise a refresh landing between an optimistic write and its debounced PUT would visibly revert the change.
+- **FOUC bootstrap**: `bootstrapToSessionStorage` mirrors specific fields to sessionStorage so the inline `<head>` script can apply theme before React mounts. Mirroring only happens on an explicit local `save()` by default — never on read/hydrate/refresh/broadcast-receive — so an app embedded under a host that owns the same sessionStorage key can't clobber it just by booting. Pass `mirrorBootstrapOnRead: true` to restore the old every-read mirroring for a key nothing else writes to.
+
+## Capacitor (native APK)
+
+Storage is **auto-detected**: in a native Capacitor webview the SDK reads
+the `Capacitor.Plugins.Preferences` global and uses it for the cache; in a
+browser it uses localStorage. No configuration, no import, and **no
+`@capacitor/preferences` dependency added to web bundles** — the detection
+is a runtime global read, so web-only consumers are unaffected.
+
+Requirements for the native side:
+
+- The host APK must have `@capacitor/preferences` installed (so Capacitor
+  registers the plugin global). The SDK does not bundle or import it.
+- The APK mints its own `hadoku_device_id` in native storage, separate from
+  the mobile browser's — so the native app and mobile Safari are two
+  distinct devices by design.
+
+You can still override with an explicit adapter (or force one in tests) via
+`createPrefsClient({ storage })`. `detectStorage()` and `capacitorStorage()`
+are exported if you want to resolve the adapter yourself.
+
+## Header-mode (service-to-service, no cookie)
+
+Pass `userKey` when there's no `hadoku_session` cookie to ride (e.g. a CLI
+or a native app that authenticates with a raw key instead of the cookie):
+
+```ts
+const client = createPrefsClient({
+  appId: 'task-mobile',
+  schema: TaskPrefsSchema,
+  userKey: process.env.HADOKU_API_KEY,
+  // storage auto-detects Capacitor; pass an explicit adapter only to override
+});
+```

package/dist/games.d.ts

@@ -0,0 +1,195 @@
+/**
+ * Game stats — the wire contract, and the rules both ends must agree on.
+ *
+ * Pure: no fetch, no DOM. prefs-api imports this file directly so the ingest
+ * validates against the very types the client is built from, and the two can
+ * never be hand-synced out of step the way watchparty-stats-api's 28 columns
+ * were. The client half lives in ./games.ts.
+ *
+ * Design: hadoku_site docs/planning/game-stats-2026-10-09.md
+ */
+/** A categorical fact. An array is a SET — a breakdown counts each element. */
+type StatAttr = string | number | boolean | string[];
+type StatAttrs = Record<string, StatAttr>;
+/** A numeric fact. Summed across matches, and maxed, by every aggregate read. */
+type StatCounters = Record<string, number>;
+type SeatKind = 'user' | 'guest' | 'bot';
+type SeatOutcome = 'win' | 'loss' | 'draw';
+declare const GAME_ID_PATTERN: RegExp;
+declare const STAT_KEY_PATTERN: RegExp;
+declare const DEFAULT_MODE = "default";
+declare const STARTING_RATING = 1500;
+/** A game server's own id for a match — a UUID fits, so does a ULID. */
+declare const MATCH_ID_PATTERN: RegExp;
+/** Ingest bounds. Generous for a game, tight for a payload someone abuses. */
+declare const STAT_LIMITS: {
+    readonly seats: 16;
+    readonly keysPerObject: 48;
+    readonly stringLength: 200;
+    readonly arrayLength: 64;
+};
+interface MatchSeatReport {
+    seat: number;
+    kind: SeatKind;
+    /** The player's own key, as the edge stamped it on their requests. Required
+     *  for `kind: 'user'`, absent otherwise. Resolved and discarded by the API. */
+    userKey?: string;
+    /** What the room called this player. A snapshot for history, never a key. */
+    displayName?: string;
+    /** 1 = winner. Equal placements tie; all-equal is a draw. */
+    placement: number;
+    attrs?: StatAttrs;
+    counters?: StatCounters;
+}
+interface MatchReport {
+    /** Minted by the game server. Re-posting the same id is a no-op. */
+    matchId: string;
+    /** Rating pool; omit for a game with one competitive shape. */
+    mode?: string;
+    roomId?: string;
+    startedAt?: number;
+    endedAt: number;
+    /** false records the match — history, profile, breakdowns — without moving anyone's rating or counting it on the leaderboard. Default true. */
+    rated?: boolean;
+    attrs?: StatAttrs;
+    counters?: StatCounters;
+    seats: MatchSeatReport[];
+}
+interface RecordMatchResult {
+    matchId: string;
+    /** true when this matchId was already recorded and nothing changed. */
+    duplicate: boolean;
+    /** New rating per seat number, for seats whose rating moved. */
+    ratings: Record<number, number>;
+}
+interface SeatView {
+    seat: number;
+    kind: SeatKind;
+    /** The registry name for a user seat (current, so it follows a rename);
+     *  the reported display name otherwise. */
+    name: string | null;
+    /** true on the caller's own seat. */
+    isMe: boolean;
+    placement: number;
+    outcome: SeatOutcome;
+    ratingBefore: number | null;
+    ratingAfter: number | null;
+    attrs: StatAttrs;
+    counters: StatCounters;
+}
+interface MatchView {
+    matchId: string;
+    gameId: string;
+    mode: string;
+    startedAt: number | null;
+    endedAt: number;
+    rated: boolean;
+    attrs: StatAttrs;
+    counters: StatCounters;
+    seats: SeatView[];
+}
+interface MatchPage {
+    matches: MatchView[];
+    /** Pass back as `before` for the next page; null on the last one. */
+    nextBefore: number | null;
+}
+interface OutcomeTotals {
+    games: number;
+    wins: number;
+    losses: number;
+    draws: number;
+}
+interface CounterTotals {
+    sum: number;
+    max: number;
+}
+interface ProfileView {
+    name: string;
+    isMe: boolean;
+    totals: OutcomeTotals;
+    ratings: {
+        mode: string;
+        rating: number;
+        games: number;
+    }[];
+    counters: Record<string, CounterTotals>;
+    lastPlayedAt: number | null;
+}
+/** `rating`, an outcome total, `winrate`, or `counter:<key>` (summed). */
+type LeaderboardBy = 'rating' | 'games' | 'wins' | 'winrate' | `counter:${string}`;
+interface LeaderboardRow {
+    rank: number;
+    name: string;
+    isMe: boolean;
+    value: number;
+    totals: OutcomeTotals;
+}
+interface BreakdownRow extends OutcomeTotals {
+    value: string;
+    /** The seat attrs a read asked to carry (`with`), off the group's most recent seat. Absent when it asked for none. */
+    attrs?: StatAttrs;
+}
+/** Win/loss/draw from placements, the one place that rule is written. */
+declare function outcomesFor(placements: readonly number[]): SeatOutcome[];
+declare function winRate(t: OutcomeTotals): number;
+
+interface GameStatsClientOptions {
+    gameId: string;
+    /** The prefs mount (`https://hadoku.me/prefs` by default), without `/api/v1`. */
+    baseUrl?: string;
+    fetch?: typeof fetch;
+}
+declare class GameStatsError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+/**
+ * What a read is narrowed to beyond its player and mode. Both default to off,
+ * so a read that names neither sees every match.
+ */
+interface StatsFilter {
+    /** Only the matches that ranked: a game reports one unrated when a bot, a guest or a test account sat in it. */
+    rated?: boolean;
+    /** Only the matches whose scalar match attr is one of the values: `{ format: ['standard', 'modern'] }`. */
+    match?: Readonly<Record<string, readonly string[]>>;
+}
+/** `player` is a registry name; omit it for the caller. */
+interface PlayerScope extends StatsFilter {
+    player?: string;
+    mode?: string;
+}
+declare function createGameStatsClient(opts: GameStatsClientOptions): {
+    profile: (s?: PlayerScope) => Promise<ProfileView>;
+    matches: (s?: PlayerScope & {
+        limit?: number;
+        before?: number;
+    }) => Promise<MatchPage>;
+    match: (matchId: string) => Promise<MatchView>;
+    leaderboard: (s?: {
+        by?: LeaderboardBy;
+        mode?: string;
+        limit?: number;
+    }) => Promise<{
+        by: LeaderboardBy;
+        rows: LeaderboardRow[];
+    }>;
+    /**
+     * Outcome totals grouped by one attr. `player: '*'` spans everyone.
+     * `with` names seat attrs each row carries, off its most recent seat.
+     */
+    breakdown: (attr: string, { with: withAttrs, ...s }?: PlayerScope & {
+        with?: readonly string[];
+    }) => Promise<{
+        attr: string;
+        rows: BreakdownRow[];
+    }>;
+};
+type GameStatsClient = ReturnType<typeof createGameStatsClient>;
+interface RecordMatchOptions extends GameStatsClientOptions {
+    /** The game server's own service-tier key. */
+    serviceKey: string;
+}
+/** Server-side: report one finished match. Safe to retry with the same matchId. */
+declare function recordMatch(opts: RecordMatchOptions, report: MatchReport): Promise<RecordMatchResult>;
+
+export { type BreakdownRow, type CounterTotals, DEFAULT_MODE, GAME_ID_PATTERN, type GameStatsClient, type GameStatsClientOptions, GameStatsError, type LeaderboardBy, type LeaderboardRow, MATCH_ID_PATTERN, type MatchPage, type MatchReport, type MatchSeatReport, type MatchView, type OutcomeTotals, type PlayerScope, type ProfileView, type RecordMatchOptions, type RecordMatchResult, STARTING_RATING, STAT_KEY_PATTERN, STAT_LIMITS, type SeatKind, type SeatOutcome, type SeatView, type StatAttr, type StatAttrs, type StatCounters, type StatsFilter, createGameStatsClient, outcomesFor, recordMatch, winRate };

package/dist/games.js

@@ -0,0 +1,99 @@
+// src/constants.ts
+var PREFS_API_BASE = "https://hadoku.me/prefs";
+
+// src/games-contract.ts
+var GAME_ID_PATTERN = /^[a-z][a-z0-9-]{0,31}$/;
+var STAT_KEY_PATTERN = /^[a-zA-Z][a-zA-Z0-9_]{0,47}$/;
+var DEFAULT_MODE = "default";
+var STARTING_RATING = 1500;
+var MATCH_ID_PATTERN = /^[A-Za-z0-9_-]{8,64}$/;
+var STAT_LIMITS = {
+  seats: 16,
+  keysPerObject: 48,
+  stringLength: 200,
+  arrayLength: 64
+};
+function outcomesFor(placements) {
+  const best = Math.min(...placements);
+  const allTied = placements.every((p) => p === best);
+  return placements.map((p) => allTied ? "draw" : p === best ? "win" : "loss");
+}
+function winRate(t) {
+  return t.games === 0 ? 0 : t.wins / t.games;
+}
+
+// src/games.ts
+var GameStatsError = class extends Error {
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+    this.name = "GameStatsError";
+  }
+  status;
+};
+function gameBase(opts) {
+  if (!GAME_ID_PATTERN.test(opts.gameId)) throw new Error(`invalid gameId: ${opts.gameId}`);
+  return `${opts.baseUrl ?? PREFS_API_BASE}/api/v1/_games/${opts.gameId}`;
+}
+async function readJson(res) {
+  if (!res.ok) {
+    const body = await res.json().catch(() => null);
+    throw new GameStatsError(res.status, body?.message ?? `HTTP ${res.status}`);
+  }
+  return await res.json();
+}
+function query({
+  match,
+  ...params
+}) {
+  const q = new URLSearchParams();
+  for (const [k, v] of Object.entries(params)) {
+    if (v === void 0 || v === false) continue;
+    q.set(k, v === true ? "1" : String(v));
+  }
+  for (const [k, values] of Object.entries(match ?? {})) {
+    for (const v of values) q.append(`match.${k}`, v);
+  }
+  const s = q.toString();
+  return s ? `?${s}` : "";
+}
+function createGameStatsClient(opts) {
+  const base = gameBase(opts);
+  const f = opts.fetch ?? fetch;
+  const get = (path) => f(`${base}${path}`, { credentials: "include" }).then(readJson);
+  return {
+    profile: (s = {}) => get(`/profile${query({ ...s })}`),
+    matches: (s = {}) => get(`/matches${query({ ...s })}`),
+    match: (matchId) => get(`/matches/${encodeURIComponent(matchId)}`),
+    leaderboard: (s = {}) => get(`/leaderboard${query({ ...s })}`),
+    /**
+     * Outcome totals grouped by one attr. `player: '*'` spans everyone.
+     * `with` names seat attrs each row carries, off its most recent seat.
+     */
+    breakdown: (attr, { with: withAttrs, ...s } = {}) => get(
+      `/breakdown${query({ attr, ...s, with: withAttrs?.length ? withAttrs.join(",") : void 0 })}`
+    )
+  };
+}
+async function recordMatch(opts, report) {
+  const f = opts.fetch ?? fetch;
+  const res = await f(`${gameBase(opts)}/matches`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", "X-User-Key": opts.serviceKey },
+    body: JSON.stringify(report)
+  });
+  return readJson(res);
+}
+export {
+  DEFAULT_MODE,
+  GAME_ID_PATTERN,
+  GameStatsError,
+  MATCH_ID_PATTERN,
+  STARTING_RATING,
+  STAT_KEY_PATTERN,
+  STAT_LIMITS,
+  createGameStatsClient,
+  outcomesFor,
+  recordMatch,
+  winRate
+};

package/dist/index.d.ts

@@ -0,0 +1,117 @@
+import { z } from 'zod';
+import { P as PrefsClientOptions, a as PrefsClient, A as AsyncStorage } from './types-DCldC4WA.js';
+export { b as PrefsMigration, c as PrefsRow, S as SaveOptions, d as Scope, e as ServerReadResult, f as capacitorStorage, g as detectStorage, l as localStorageAdapter, m as memoryStorage, s as sessionStorageWrite } from './types-DCldC4WA.js';
+
+/**
+ * createPrefsClient — vanilla (no React) client for the prefs-api.
+ *
+ * Architecture, top-down:
+ *
+ *   read()
+ *     ├─ if cache present → return cached blob synchronously-ish + kick off
+ *     │   a background refresh (return-stale-while-revalidate)
+ *     └─ if cache empty   → fetch from server, populate cache, return
+ *
+ *   save(patch)
+ *     ├─ merge patch into in-memory current blob
+ *     ├─ update cache + notify listeners synchronously (optimistic UI)
+ *     ├─ debounce 1s, then PUT
+ *     └─ on 409: adopt server blob from response, overwrite cache, notify
+ *                (API-Always-Wins per docs/planning/unified-prefs-2026-05-20.md)
+ *
+ *   subscribe(listener)
+ *     ├─ stash listener in a Set
+ *     ├─ also wire BroadcastChannel('prefs:{userId}:{appId}') so cross-tab
+ *     │   saves propagate without a server roundtrip
+ *     └─ unsubscribe returns a fn that clears both
+ *
+ * The client is per-app: one createPrefsClient call per app schema. Sharing
+ * the same id across apps would clobber caches.
+ */
+
+declare function createPrefsClient<S extends z.ZodType>(opts: PrefsClientOptions<S>): PrefsClient<z.infer<S>>;
+
+/**
+ * Get-or-mint the per-browser device id.
+ *
+ * Canonical localStorage key: `hadoku_device_id`. Shared across all
+ * apps on this browser — every microfrontend gets the same id so prefs
+ * scoped to "this device" reflect the user's actual physical device,
+ * not the URL they happened to be on when they first set the value.
+ *
+ * Capacitor APK is a separate "device" by design: the @capacitor/preferences
+ * store is isolated from the browser's localStorage, so the APK mints its
+ * own id on first launch and never sees the web id. The user can theme
+ * the two differently, which is the desired UX.
+ *
+ * The id is opaque and never sent to the server EXCEPT as the X-Device-Id
+ * header on prefs-api requests. It's not a secret — losing it just means
+ * the device looks "new" to the prefs store (no security consequence).
+ */
+
+declare const DEVICE_ID_KEY = "hadoku_device_id";
+/**
+ * Read the device id; mint and persist one if absent. The async signature
+ * lets us swap in @capacitor/preferences storage transparently.
+ */
+declare function getDeviceId(storage?: AsyncStorage): Promise<string>;
+
+/**
+ * How a cache scope was derived — i.e. how much this identity can be trusted
+ * to be distinct from the last person who used this browser.
+ *
+ *   'user'    stable registry userId. Distinct per user, stable across logins.
+ *   'session' signed in, but the server gave no stable id (a registry row
+ *             predating lazy userId minting). Distinct per user; NOT stable
+ *             across logins, so it costs a cache miss after re-login and
+ *             re-reads from the server, which is authoritative anyway.
+ *   'anon'    no session at all. The shared row — correct here, since
+ *             anonymous visitors are indistinguishable by definition.
+ *   'none'    signed in and unidentifiable (no userId AND no sessionId).
+ *             Nothing may be persisted: there is no value that is safe to
+ *             reuse, and the shared row is exactly the wrong answer.
+ */
+type IdentityScope = 'user' | 'session' | 'anon' | 'none';
+interface WhoamiResult {
+    userId: string;
+    userType: 'admin' | 'wife' | 'service' | 'friend' | 'public';
+    name?: string | null;
+    /**
+     * How `userId` was derived. Callers that PERSIST anything keyed by
+     * `userId` must check this: 'none' means do not persist at all, and
+     * 'anon' means the key is shared with every other browser user.
+     */
+    scope: IdentityScope;
+}
+interface WhoamiOpts {
+    /** Override the base URL for testing. Default: edge-router origin. */
+    whoamiUrl?: string;
+    /** Header-mode auth — sent as X-User-Key. Browser path can leave undefined. */
+    userKey?: string;
+}
+/** Sentinel userId for callers without a recognised session/key. */
+declare const ANON_USER_ID = "anon";
+declare function whoami(opts?: WhoamiOpts): Promise<WhoamiResult>;
+
+/**
+ * Build-time constants. Kept in their own module so the React entry can
+ * import them without dragging in the rest of the SDK surface.
+ *
+ * PREFS_API_BASE points at the hadoku edge-router /prefs prefix. Apps
+ * that want to test against a non-prod environment pass `apiBase` to
+ * createPrefsClient — this default is for the published-package consumer
+ * who just wants it to work against prod.
+ *
+ * Lint-rule note: workers in this repo are required to use the edge-routes
+ * constants from @wolffm/worker-utils. This package is the consumer-facing
+ * SDK published to GitHub Packages and CANNOT depend on worker-utils (which
+ * is itself a workspace dep). The hardcoded URL is the contract with the
+ * consuming app, so the rule is disabled here.
+ */
+declare const PREFS_API_BASE = "https://hadoku.me/prefs";
+/** localStorage cache key prefix. Full key: `prefs-cache:{userId}:{appId}`. */
+declare const CACHE_KEY_PREFIX = "prefs-cache";
+/** Debounce window for PUTs. Matches watchparty's pattern (1s coalesce). */
+declare const SAVE_DEBOUNCE_MS = 1000;
+
+export { ANON_USER_ID, AsyncStorage, CACHE_KEY_PREFIX, DEVICE_ID_KEY, type IdentityScope, PREFS_API_BASE, PrefsClient, PrefsClientOptions, SAVE_DEBOUNCE_MS, type WhoamiResult, createPrefsClient, getDeviceId, whoami };

package/dist/index.js

@@ -0,0 +1,527 @@
+// src/constants.ts
+var PREFS_API_BASE = "https://hadoku.me/prefs";
+var CACHE_KEY_PREFIX = "prefs-cache";
+var SAVE_DEBOUNCE_MS = 1e3;
+
+// src/storage.ts
+var localStorageAdapter = {
+  get(key) {
+    if (typeof window === "undefined") return Promise.resolve(null);
+    try {
+      return Promise.resolve(window.localStorage.getItem(key));
+    } catch {
+      return Promise.resolve(null);
+    }
+  },
+  set(key, value) {
+    if (typeof window === "undefined") return Promise.resolve();
+    try {
+      window.localStorage.setItem(key, value);
+    } catch {
+    }
+    return Promise.resolve();
+  },
+  remove(key) {
+    if (typeof window === "undefined") return Promise.resolve();
+    try {
+      window.localStorage.removeItem(key);
+    } catch {
+    }
+    return Promise.resolve();
+  }
+};
+var memoryStorage = () => {
+  const store = /* @__PURE__ */ new Map();
+  return {
+    get(key) {
+      return Promise.resolve(store.get(key) ?? null);
+    },
+    set(key, value) {
+      store.set(key, value);
+      return Promise.resolve();
+    },
+    remove(key) {
+      store.delete(key);
+      return Promise.resolve();
+    }
+  };
+};
+var sessionStorageWrite = (key, value) => {
+  if (typeof window === "undefined") return;
+  try {
+    window.sessionStorage.setItem(key, value);
+  } catch {
+  }
+};
+function readCapacitorGlobal() {
+  return globalThis.Capacitor;
+}
+function capacitorStorage() {
+  const cap = readCapacitorGlobal();
+  if (!cap?.isNativePlatform?.()) return null;
+  const prefs = cap.Plugins?.Preferences;
+  if (!prefs) return null;
+  return {
+    async get(key) {
+      const { value } = await prefs.get({ key });
+      return value ?? null;
+    },
+    async set(key, value) {
+      await prefs.set({ key, value });
+    },
+    async remove(key) {
+      await prefs.remove({ key });
+    }
+  };
+}
+function detectStorage() {
+  return capacitorStorage() ?? localStorageAdapter;
+}
+
+// src/get-device-id.ts
+var DEVICE_ID_KEY = "hadoku_device_id";
+async function getDeviceId(storage = localStorageAdapter) {
+  const existing = await storage.get(DEVICE_ID_KEY);
+  if (existing && isUuid(existing)) {
+    return existing;
+  }
+  const fresh = mintUuid();
+  await storage.set(DEVICE_ID_KEY, fresh);
+  return fresh;
+}
+function mintUuid() {
+  const c = globalThis.crypto;
+  if (c?.randomUUID) {
+    return c.randomUUID();
+  }
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (ch) => {
+    const r = Math.random() * 16 | 0;
+    const v = ch === "x" ? r : r & 3 | 8;
+    return v.toString(16);
+  });
+}
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function isUuid(s) {
+  return UUID_RE.test(s);
+}
+
+// src/whoami.ts
+var ANON_USER_ID = "anon";
+var WHOAMI_GLOBAL = "__hadokuWhoami";
+var SESSION_SCOPE_PREFIX = "sess:";
+var UNSCOPED_ID = "unscoped";
+function adaptWhoami(body) {
+  if (!body || body.valid === false) {
+    return { userId: ANON_USER_ID, userType: "public", scope: "anon" };
+  }
+  const userType = body.userType === "admin" || body.userType === "wife" || body.userType === "service" || body.userType === "friend" || body.userType === "public" ? body.userType : "public";
+  const name = typeof body.name === "string" ? body.name : null;
+  if (typeof body.userId === "string" && body.userId) {
+    return { userId: body.userId, userType, name, scope: "user" };
+  }
+  if (typeof body.sessionId === "string" && body.sessionId) {
+    return {
+      userId: `${SESSION_SCOPE_PREFIX}${body.sessionId}`,
+      userType,
+      name,
+      scope: "session"
+    };
+  }
+  return { userId: UNSCOPED_ID, userType, name, scope: "none" };
+}
+async function fetchWhoamiRaw(url, userKey) {
+  const headers = {};
+  if (userKey) {
+    headers["X-User-Key"] = userKey;
+  }
+  try {
+    const resp = await fetch(url, {
+      method: "GET",
+      headers,
+      credentials: "include",
+      cache: "no-store"
+    });
+    if (!resp.ok) return null;
+    return await resp.json();
+  } catch {
+    return null;
+  }
+}
+function defaultWhoamiUrl() {
+  const loc = globalThis.location;
+  if (loc && (loc.protocol === "http:" || loc.protocol === "https:")) return "/session/whoami";
+  return `${PREFS_API_BASE.replace(/\/prefs$/, "")}/session/whoami`;
+}
+async function whoami(opts = {}) {
+  const url = opts.whoamiUrl ?? defaultWhoamiUrl();
+  if (opts.userKey) {
+    return adaptWhoami(await fetchWhoamiRaw(url, opts.userKey));
+  }
+  const g = globalThis;
+  let shared = g[WHOAMI_GLOBAL];
+  if (!shared) {
+    shared = fetchWhoamiRaw(url);
+    g[WHOAMI_GLOBAL] = shared;
+  }
+  try {
+    return adaptWhoami(await shared);
+  } catch {
+    return { userId: ANON_USER_ID, userType: "public", scope: "anon" };
+  }
+}
+
+// src/client.ts
+function createPrefsClient(opts) {
+  const apiBase = opts.apiBase ?? PREFS_API_BASE;
+  const mirrorOnRead = opts.mirrorBootstrapOnRead ?? false;
+  const storage = opts.storage ?? detectStorage();
+  const listeners = /* @__PURE__ */ new Set();
+  const migrations = opts.migrations ?? [];
+  const defaults = opts.defaults ?? {};
+  const bootstrapMap = opts.bootstrapToSessionStorage ?? {};
+  let userId = null;
+  let identityScope = "anon";
+  let wroteWhileAnon = false;
+  let deviceId = opts.deviceId ?? null;
+  let currentBlob = null;
+  let userVersion = 0;
+  let deviceVersion = 0;
+  let pendingPatch = {};
+  let pendingScope = "user";
+  const dirtyFields = /* @__PURE__ */ new Set();
+  let saveTimer = null;
+  let savePromise = null;
+  let initPromise = null;
+  let bcast = null;
+  let destroyed = false;
+  const broadcastId = `${Math.random().toString(36).slice(2)}-${Date.now()}`;
+  function ensureInit() {
+    if (initPromise) return initPromise;
+    initPromise = (async () => {
+      const who = await whoami({
+        userKey: opts.userKey,
+        // An EXPLICIT apiBase (a non-prod environment) names where identity lives
+        // too. With none, leave it to whoami()'s default — same-origin in a
+        // browser — rather than pinning the hadoku.me constant (#419).
+        ...opts.apiBase ? { whoamiUrl: `${opts.apiBase.replace(/\/prefs$/, "")}/session/whoami` } : {}
+      });
+      userId = who.userId;
+      identityScope = who.scope;
+      if (!deviceId) {
+        deviceId = await getDeviceId(storage);
+      }
+      const cached = await readCache();
+      if (cached) {
+        userVersion = cached.userVersion;
+        deviceVersion = cached.deviceVersion;
+        currentBlob = applyDefaultsAndParse(cached.blob);
+        if (mirrorOnRead) mirrorBootstrap(currentBlob);
+        notify(currentBlob);
+      }
+      if (canPersist() && typeof BroadcastChannel !== "undefined") {
+        bcast = new BroadcastChannel(`prefs:${userId}:${opts.appId}`);
+        bcast.addEventListener("message", onBroadcast);
+      }
+    })();
+    return initPromise;
+  }
+  function buildHeaders() {
+    const h = { "Content-Type": "application/json" };
+    if (opts.userKey) h["X-User-Key"] = opts.userKey;
+    if (deviceId) h["X-Device-Id"] = deviceId;
+    return h;
+  }
+  async function fetchFromServer() {
+    const resp = await fetch(`${apiBase}/api/v1/${opts.appId}`, {
+      method: "GET",
+      headers: buildHeaders(),
+      credentials: "include"
+    });
+    if (!resp.ok) {
+      throw new Error(`prefs-api GET failed: ${resp.status}`);
+    }
+    return await resp.json();
+  }
+  async function putToServer(scope, patch, expectedVersion) {
+    const resp = await fetch(`${apiBase}/api/v1/${opts.appId}`, {
+      method: "PUT",
+      headers: buildHeaders(),
+      credentials: "include",
+      body: JSON.stringify({
+        scope,
+        patch,
+        expectedVersion
+      })
+    });
+    if (resp.status === 409) {
+      const body2 = await resp.json();
+      if (body2.current) {
+        return { ok: false, conflict: body2.current };
+      }
+      throw new Error("prefs-api 409 without current-state body");
+    }
+    if (!resp.ok) {
+      throw new Error(`prefs-api PUT failed: ${resp.status}`);
+    }
+    const body = await resp.json();
+    return { ok: true, row: body, scope: body.scope };
+  }
+  function cacheKey() {
+    return `${CACHE_KEY_PREFIX}:${userId ?? ANON_USER_ID}:${opts.appId}`;
+  }
+  function canPersist() {
+    return identityScope !== "none";
+  }
+  function canSync() {
+    return identityScope === "user" || identityScope === "session";
+  }
+  async function readCache() {
+    if (!canPersist()) return null;
+    const raw = await storage.get(cacheKey());
+    if (!raw) return null;
+    try {
+      const parsed = JSON.parse(raw);
+      if (parsed && typeof parsed === "object" && parsed.blob && typeof parsed.blob === "object") {
+        return parsed;
+      }
+    } catch {
+    }
+    return null;
+  }
+  async function writeCache(env) {
+    if (!canPersist()) return;
+    await storage.set(cacheKey(), JSON.stringify(env));
+  }
+  function applyDefaultsAndParse(rawBlob) {
+    let withDefaults = { ...defaults, ...rawBlob };
+    for (const m of migrations) {
+      withDefaults = m(withDefaults);
+    }
+    const result = opts.schema.safeParse(withDefaults);
+    if (result.success) {
+      return result.data;
+    }
+    const fallback = opts.schema.safeParse({ ...defaults });
+    return fallback.success ? fallback.data : withDefaults;
+  }
+  function mirrorBootstrap(blob) {
+    for (const [field, sessionKey] of Object.entries(bootstrapMap)) {
+      if (typeof sessionKey !== "string" || !sessionKey) continue;
+      const value = blob[field];
+      if (typeof value === "string") {
+        sessionStorageWrite(sessionKey, value);
+      }
+    }
+  }
+  function notify(blob) {
+    for (const l of listeners) {
+      try {
+        l(blob);
+      } catch {
+      }
+    }
+  }
+  function broadcast(blob) {
+    if (!bcast) return;
+    try {
+      bcast.postMessage({ source: broadcastId, blob });
+    } catch {
+    }
+  }
+  function onBroadcast(ev) {
+    const data = ev.data;
+    if (!data || data.source === broadcastId || !data.blob) return;
+    const reconciled = reconcileDirty(data.blob);
+    currentBlob = applyDefaultsAndParse(reconciled);
+    if (mirrorOnRead) mirrorBootstrap(currentBlob);
+    notify(currentBlob);
+  }
+  function reconcileDirty(remote) {
+    if (dirtyFields.size === 0 || !currentBlob) return remote;
+    const local = currentBlob;
+    const reconciled = { ...remote };
+    for (const field of dirtyFields) {
+      if (field in local) reconciled[field] = local[field];
+    }
+    return reconciled;
+  }
+  async function refreshFromServer() {
+    if (!canSync()) {
+      if (currentBlob === null) {
+        currentBlob = applyDefaultsAndParse({});
+        if (mirrorOnRead) mirrorBootstrap(currentBlob);
+        notify(currentBlob);
+      }
+      return;
+    }
+    const server = await fetchFromServer();
+    userVersion = server.user?.version ?? 0;
+    deviceVersion = server.device?.version ?? 0;
+    const merged = reconcileDirty(server.merged ?? {});
+    currentBlob = applyDefaultsAndParse(merged);
+    await writeCache({
+      blob: merged,
+      userVersion,
+      deviceVersion,
+      cachedAt: Date.now()
+    });
+    if (mirrorOnRead) mirrorBootstrap(currentBlob);
+    notify(currentBlob);
+    broadcast(currentBlob);
+  }
+  function scheduleFlush() {
+    if (saveTimer) clearTimeout(saveTimer);
+    saveTimer = setTimeout(() => {
+      void flushPending();
+    }, SAVE_DEBOUNCE_MS);
+  }
+  async function flushPending() {
+    if (Object.keys(pendingPatch).length === 0) return;
+    if (savePromise) {
+      await savePromise;
+    }
+    const patchSnapshot = pendingPatch;
+    const scopeSnapshot = pendingScope;
+    pendingPatch = {};
+    if (saveTimer) {
+      clearTimeout(saveTimer);
+      saveTimer = null;
+    }
+    if (!canSync()) {
+      for (const key of Object.keys(patchSnapshot)) {
+        if (!(key in pendingPatch)) dirtyFields.delete(key);
+      }
+      return;
+    }
+    const expectedVersion = scopeSnapshot === "user" ? userVersion : deviceVersion;
+    savePromise = (async () => {
+      try {
+        const result = await putToServer(scopeSnapshot, patchSnapshot, expectedVersion);
+        if (result.ok) {
+          if (result.scope === "user") {
+            userVersion = result.row.version;
+          } else {
+            deviceVersion = result.row.version;
+          }
+          await refreshFromServer();
+        } else {
+          if (scopeSnapshot === "user") {
+            userVersion = result.conflict.version;
+          } else {
+            deviceVersion = result.conflict.version;
+          }
+          await refreshFromServer();
+        }
+        for (const key of Object.keys(patchSnapshot)) {
+          if (!(key in pendingPatch)) dirtyFields.delete(key);
+        }
+      } catch {
+        pendingPatch = { ...patchSnapshot, ...pendingPatch };
+        pendingScope = scopeSnapshot;
+      } finally {
+        savePromise = null;
+      }
+    })();
+    await savePromise;
+  }
+  const client = {
+    appId: opts.appId,
+    async read() {
+      await ensureInit();
+      if (currentBlob === null) {
+        try {
+          await refreshFromServer();
+        } catch {
+          currentBlob = applyDefaultsAndParse({});
+        }
+      } else {
+        void refreshFromServer().catch(() => {
+        });
+      }
+      return currentBlob ?? applyDefaultsAndParse({});
+    },
+    async save(patch, saveOpts) {
+      await ensureInit();
+      const scope = saveOpts?.scope ?? "user";
+      if (identityScope === "anon") wroteWhileAnon = true;
+      const base = currentBlob ?? {};
+      const nextBlob = applyDefaultsAndParse({ ...base, ...patch });
+      currentBlob = nextBlob;
+      await writeCache({
+        blob: { ...base, ...patch },
+        userVersion,
+        deviceVersion,
+        cachedAt: Date.now()
+      });
+      mirrorBootstrap(nextBlob);
+      notify(nextBlob);
+      broadcast(nextBlob);
+      if (Object.keys(pendingPatch).length > 0 && pendingScope !== scope) {
+        await flushPending();
+      }
+      pendingPatch = { ...pendingPatch, ...patch };
+      pendingScope = scope;
+      for (const key of Object.keys(patch)) dirtyFields.add(key);
+      if (saveOpts?.expectedVersion !== void 0) {
+        await flushPending();
+      } else {
+        scheduleFlush();
+      }
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    async promoteAnonPrefsToUser() {
+      if (!wroteWhileAnon) return;
+      const anonKey = `${CACHE_KEY_PREFIX}:${ANON_USER_ID}:${opts.appId}`;
+      const raw = await storage.get(anonKey);
+      if (!raw) return;
+      let anon;
+      try {
+        anon = JSON.parse(raw);
+      } catch {
+        return;
+      }
+      if (!anon.blob || Object.keys(anon.blob).length === 0) return;
+      await ensureInit();
+      const server = await fetchFromServer();
+      if (server.user) {
+        await refreshFromServer();
+        await storage.remove(anonKey);
+        return;
+      }
+      await putToServer("user", anon.blob, 0);
+      await refreshFromServer();
+      await storage.remove(anonKey);
+    },
+    async flush() {
+      await flushPending();
+    },
+    destroy() {
+      if (destroyed) return;
+      destroyed = true;
+      if (saveTimer) clearTimeout(saveTimer);
+      if (bcast) bcast.close();
+      listeners.clear();
+    }
+  };
+  return client;
+}
+export {
+  ANON_USER_ID,
+  CACHE_KEY_PREFIX,
+  DEVICE_ID_KEY,
+  PREFS_API_BASE,
+  SAVE_DEBOUNCE_MS,
+  capacitorStorage,
+  createPrefsClient,
+  detectStorage,
+  getDeviceId,
+  localStorageAdapter,
+  memoryStorage,
+  sessionStorageWrite,
+  whoami
+};

package/dist/react.d.ts

@@ -0,0 +1,20 @@
+import { a as PrefsClient } from './types-DCldC4WA.js';
+import 'zod';
+
+interface UsePrefsResult<T extends Record<string, unknown>> {
+    prefs: T | null;
+    save: PrefsClient<T>['save'];
+    loading: boolean;
+    error: Error | null;
+}
+/**
+ * Reactive prefs hook. Returns `prefs: null` on the first render (before
+ * the cache hydrates / server responds), then the merged blob after init.
+ *
+ * Uses useSyncExternalStore so concurrent-mode tearing isn't a concern:
+ * the snapshot we return is the same one we'll get next render until
+ * the subscription fires.
+ */
+declare function usePrefs<T extends Record<string, unknown>>(client: PrefsClient<T>): UsePrefsResult<T>;
+
+export { PrefsClient, type UsePrefsResult, usePrefs };

package/dist/react.js

@@ -0,0 +1,54 @@
+// src/react.ts
+import { useEffect, useState, useSyncExternalStore } from "react";
+function usePrefs(client) {
+  const store = useStoreFromClient(client);
+  const prefs = useSyncExternalStore(store.subscribe, store.getSnapshot, store.getServerSnapshot);
+  const [loading, setLoading] = useState(prefs === null);
+  const [error, setError] = useState(null);
+  useEffect(() => {
+    let cancelled = false;
+    setLoading(true);
+    setError(null);
+    client.read().then(() => {
+      if (!cancelled) setLoading(false);
+    }).catch((err) => {
+      if (cancelled) return;
+      setError(err instanceof Error ? err : new Error(String(err)));
+      setLoading(false);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [client]);
+  const save = (patch, saveOpts) => client.save(patch, saveOpts);
+  return { prefs, save, loading, error };
+}
+var storeCache = /* @__PURE__ */ new WeakMap();
+function useStoreFromClient(client) {
+  const cached = storeCache.get(client);
+  if (cached) return cached;
+  let snapshot = null;
+  const onChangeListeners = /* @__PURE__ */ new Set();
+  const unsubscribe = client.subscribe((next) => {
+    snapshot = next;
+    for (const l of onChangeListeners) l();
+  });
+  const store = {
+    subscribe: (onChange) => {
+      onChangeListeners.add(onChange);
+      return () => {
+        onChangeListeners.delete(onChange);
+        if (onChangeListeners.size === 0) {
+          void unsubscribe;
+        }
+      };
+    },
+    getSnapshot: () => snapshot,
+    getServerSnapshot: () => null
+  };
+  storeCache.set(client, store);
+  return store;
+}
+export {
+  usePrefs
+};

package/dist/types-DCldC4WA.d.ts

@@ -0,0 +1,190 @@
+import { z } from 'zod';
+
+/**
+ * Storage abstraction over localStorage + Capacitor Preferences.
+ *
+ * The web path is synchronous-under-the-hood (localStorage), but we expose
+ * an async interface uniformly so the React hook + client code never branches
+ * on platform. Capacitor's @capacitor/preferences is async-only; the cost of
+ * making the web path also async is one extra microtask per call, which is
+ * irrelevant against the 1s debounce timeline anyway.
+ *
+ * The Capacitor adapter is a runtime detection — we DON'T import
+ * @capacitor/preferences at module load time so the package stays installable
+ * by web-only apps without adding the peer dep. Apps that build a Capacitor
+ * APK pass the adapter explicitly via createPrefsClient({ storage: ... }).
+ *
+ * Adapters return Promise<...> via Promise.resolve(...) rather than `async`
+ * methods — the inner operations are sync, so dropping the keyword keeps the
+ * intent honest and silences eslint's require-await rule.
+ */
+interface AsyncStorage {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    remove(key: string): Promise<void>;
+}
+/** localStorage-backed AsyncStorage. SSR-safe (no-ops when window is absent). */
+declare const localStorageAdapter: AsyncStorage;
+/**
+ * No-op-ish storage backed by a Map. For SSR, tests with no jsdom, or the
+ * very first ever paint before window.localStorage exists. All operations
+ * succeed silently; reads return whatever was set. Lets the SDK boot in
+ * Node-side rendering without exploding.
+ */
+declare const memoryStorage: () => AsyncStorage;
+/**
+ * Same shape as AsyncStorage but synchronous — the inline FOUC-prevention
+ * script in <head> can't await, so sessionStorage write-through has to be
+ * sync. Kept separate from AsyncStorage so the type system catches anyone
+ * trying to use this for the main cache path.
+ */
+declare const sessionStorageWrite: (key: string, value: string) => void;
+/**
+ * Build an AsyncStorage backed by the Capacitor Preferences plugin, or null
+ * if we're not in a native Capacitor context (or the plugin isn't installed
+ * in the host app). Pure runtime read — no import, no peer dep.
+ */
+declare function capacitorStorage(): AsyncStorage | null;
+/**
+ * Resolve the default storage backend. Native Capacitor → Preferences plugin;
+ * everything else → localStorage. createPrefsClient calls this when the
+ * consumer doesn't pass an explicit `storage` adapter, so a task-mobile APK
+ * gets isolated native storage with zero config while web apps keep
+ * localStorage. The branch is a sync global read; no async, no import.
+ */
+declare function detectStorage(): AsyncStorage;
+
+/**
+ * Public type surface — the parts a consuming app reaches for. Internal
+ * helpers (network shapes, cache envelopes) live next to their owners.
+ */
+
+/** Pref scope. Same shape as the API column; never mix this with code paths. */
+type Scope = 'user' | 'device';
+/**
+ * A migration is applied to the raw merged blob BEFORE Zod parse. Migrations
+ * are ordered (apply in array order) and must be idempotent — they may run
+ * on a blob that's already been migrated previously, depending on whether
+ * the cache or the server was stale at read time. Keep them as
+ * `(blob: any) => any` shape; the SDK doesn't try to type-check them
+ * against the schema because the whole point is to transform a shape that
+ * doesn't match the schema yet.
+ */
+type PrefsMigration = (blob: Record<string, unknown>) => Record<string, unknown>;
+interface PrefsClientOptions<S extends z.ZodType> {
+    /** App identifier — matches the `app_id` column. `[a-z0-9-]+`. */
+    appId: string;
+    /** Zod schema describing the prefs blob for this app. */
+    schema: S;
+    /**
+     * Baseline values applied when a field is absent from the merged blob.
+     * Server values always win over defaults. Use this to pin "what does
+     * the UI fall back to before the first sync".
+     */
+    defaults?: Partial<z.infer<S>>;
+    /**
+     * Migrations applied in order to the raw merged blob (post-merge, pre-parse).
+     * Useful for renaming a field or coercing an old value into the new shape.
+     * Apps own their own migration history; the SDK never reorders or
+     * de-duplicates them.
+     */
+    migrations?: PrefsMigration[];
+    /**
+     * Mirror specific fields to sessionStorage. Keys are SDK schema field
+     * names; values are the sessionStorage key the inline `<head>`
+     * FOUC-prevention script reads. Lets theme apply before React mounts
+     * without giving up the per-user / per-device split.
+     *
+     * By default this only mirrors on an explicit local save() — never on
+     * read/hydrate/refresh/broadcast-receive — so an app embedded under a
+     * host that owns the same sessionStorage key can't clobber it just by
+     * booting. Pass `mirrorBootstrapOnRead: true` to restore the old
+     * every-read mirroring, for a key nothing else writes to.
+     */
+    bootstrapToSessionStorage?: Partial<Record<keyof z.infer<S>, string>>;
+    /** See `bootstrapToSessionStorage`. Default: false. */
+    mirrorBootstrapOnRead?: boolean;
+    /** Override edge-router base. Default 'https://hadoku.me/prefs'. */
+    apiBase?: string;
+    /**
+     * Header-mode auth (Capacitor / s2s). Browser apps with the cookie
+     * leave this undefined.
+     */
+    userKey?: string;
+    /** Storage backend. Defaults to localStorage; pass a Capacitor adapter for APK builds. */
+    storage?: AsyncStorage;
+    /**
+     * Override the device id. If omitted, getDeviceId() reads/mints from
+     * localStorage `hadoku_device_id`. The CapacitorOK SDK consumer may
+     * want to pre-supply this from native code.
+     */
+    deviceId?: string;
+}
+interface PrefsRow<T> {
+    blob: T;
+    version: number;
+    updatedAt: number;
+    deviceId?: string | null;
+}
+/** Server response from GET /api/v1/:appId. */
+interface ServerReadResult<T> {
+    user: PrefsRow<T> | null;
+    device: PrefsRow<T> | null;
+    merged: T;
+}
+interface SaveOptions {
+    /** Default: 'user'. Use 'device' for per-device-only fields like theme. */
+    scope?: Scope;
+    /**
+     * Override the auto-managed expectedVersion. The SDK always sends the
+     * last-known server version; you only need this for forced overwrites
+     * (e.g. promoting anon prefs to user on first sign-in).
+     */
+    expectedVersion?: number;
+}
+/**
+ * `T` is the app's prefs blob (a `z.infer` of its schema). It is intentionally
+ * UNCONSTRAINED rather than `T extends Record<string, unknown>`: under zod v4,
+ * `z.infer<S>` for the generic schema `S` in {@link createPrefsClient} widens to
+ * `unknown`, which a `Record` bound would reject at the generic definition —
+ * forcing every consumer's prefs type to collapse to `any`. Leaving `T` open
+ * lets each concrete call site keep its real inferred object type; the runtime
+ * blob is always an object (schema-guaranteed), and the implementation casts to
+ * `Record<string, unknown>` where it needs object semantics.
+ */
+interface PrefsClient<T> {
+    readonly appId: string;
+    /**
+     * Resolve the schema-validated, defaults-applied, migrated prefs.
+     * Returns the cached value on first call (if present) and triggers a
+     * background refresh; subsequent calls return the freshest known value.
+     */
+    read(): Promise<T>;
+    /**
+     * Apply a partial patch. Coalesced via a 1s debounce so a slider that
+     * fires 30 onChange events in two seconds only PUTs twice.
+     */
+    save(patch: Partial<T>, opts?: SaveOptions): Promise<void>;
+    /** Subscribe to changes (incl. cross-tab via BroadcastChannel). */
+    subscribe(listener: (prefs: T) => void): () => void;
+    /**
+     * One-shot migration on sign-in: take the current anon-cached prefs
+     * and PUT them under the user scope IF the server has no user-scope row
+     * yet. If the server already has a row (signed in elsewhere first),
+     * the server wins and our anon picks are discarded.
+     *
+     * NO-OPS unless THIS client instance actually wrote a preference while
+     * anonymous. The anon cache row is shared by every user of the browser, so
+     * without that evidence its contents belong to whoever used the browser
+     * last — and this method writes to the SERVER, so promoting them would
+     * persist one user's preferences under another's identity. Safe to call
+     * unconditionally on sign-in; it decides for itself.
+     */
+    promoteAnonPrefsToUser(): Promise<void>;
+    /** Flush any pending debounced PUTs immediately. For beforeunload. */
+    flush(): Promise<void>;
+    /** Tear down (cancels timers, closes BroadcastChannel). */
+    destroy(): void;
+}
+
+export { type AsyncStorage as A, type PrefsClientOptions as P, type SaveOptions as S, type PrefsClient as a, type PrefsMigration as b, type PrefsRow as c, type Scope as d, type ServerReadResult as e, capacitorStorage as f, detectStorage as g, localStorageAdapter as l, memoryStorage as m, sessionStorageWrite as s };

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@hadoku/prefs-client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.0",
+  "description": "Client SDK for the hadoku unified preferences store. Wraps /prefs/api/v1/* with localStorage caching, debounced writes, Zod-validated reads, and a usePrefs() React hook, plus match history, ratings and leaderboards for every game (./games).",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "default": "./dist/react.js"
+    },
+    "./games": {
+      "types": "./dist/games.d.ts",
+      "default": "./dist/games.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/WolffM/hadoku_site.git",
+    "directory": "packages/prefs-client"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "zod": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "hadoku",
+    "preferences",
+    "prefs",
+    "sdk",
+    "game-stats"
+  ],
+  "license": "ISC"
+}