@hadoku/prefs-client 1.1.3 → 1.1.5

package/README.md

@@ -97,6 +97,28 @@ const client = createPrefsClient({
 });
 ```
 
+## Platform rows (`@wolffm/prefs-client/platform`)
+
+Rows that belong to no single app. Import the definition rather than retyping the appId,
+scope and schema, so the second app to need a setting finds the first one's row instead of
+inventing its own.
+
+| Row                   | Fields                   | Scope  | Owner                                                      |
+| --------------------- | ------------------------ | ------ | ---------------------------------------------------------- |
+| `games` (`GAMES_ROW`) | `muted`, `volume` (0..1) | device | every hadoku game: master sound, above a game's own levels |
+| `portfolio`           | `theme`                  | device | `@wolffm/themes`; do not write it from an app              |
+
+```ts
+import { createPrefsClient } from '@wolffm/prefs-client';
+import { GAMES_ROW, GAMES_DEFAULTS } from '@wolffm/prefs-client/platform';
+
+const games = createPrefsClient({ ...GAMES_ROW, defaults: GAMES_DEFAULTS });
+await games.save({ muted: true }, { scope: GAMES_ROW.scope });
+```
+
+The profile picture is not a row here: it is `./avatar` below, whose fallback is the
+watchparty character.
+
 ## Avatars (`@wolffm/prefs-client/avatar`)
 
 One resolved avatar per hadoku user, chosen by the user at `hadoku.me/account`.

package/dist/avatar.d.ts

@@ -22,8 +22,8 @@ type LinkProvider = (typeof LINK_PROVIDERS)[number];
  *   square, at least 184px. Render it as an `<img>`; never fetch it server-side
  *   on a user's behalf.
  *
- * A source that stops being available (an unlink, an admin removal, a Discord
- * avatar that changed) resolves to `sprite` with no action from the app.
+ * A source that stops being available (an unlink, an admin removal, an account
+ * whose custom avatar was removed) resolves to `sprite` with no action from the app.
  */
 type ResolvedAvatar = {
     source: 'sprite';
@@ -36,12 +36,10 @@ type ResolvedAvatar = {
 };
 /** A linked account as its owner sees it. Never carries a token. */
 interface LinkedAccountView {
-    /** null when the account has no custom avatar, or the cached one went stale. */
+    /** null when the account has no custom avatar. */
     avatarUrl: string | null;
     linkedAt: number;
     refreshedAt: number;
-    /** Set when Discord stopped serving the cached avatar: link again to pick up the new one. */
-    stale: boolean;
 }
 interface UploadView {
     url: string;

package/dist/platform.d.ts

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+
+/**
+ * Platform rows — prefs rows that belong to no single app, so every app that
+ * reads or writes one imports its definition from here rather than retyping
+ * the appId, the scope and the schema.
+ *
+ * A row here is only a NAME and a SHAPE: prefs-api accepts any `[a-z0-9-]+`
+ * appId and stores the blob as given, so nothing server-side changes when one
+ * is added. What this file stops is the second app inventing its own row for
+ * the same setting (bomberman's `bomberman.volume` in localStorage beside
+ * cardtable's `games` row, 2026-10-30).
+ *
+ * Not here, and why:
+ *   - Theme (`portfolio`, device scope) is owned by `@wolffm/themes`, which
+ *     renders the picker for every app.
+ *   - The profile picture is `./avatar`: one resolved avatar per user, whose
+ *     fallback is the watchparty character read from the `watchparty` row.
+ *
+ * Usage:
+ *   createPrefsClient({ ...GAMES_ROW, defaults: GAMES_DEFAULTS })
+ *   prefs.save({ volume: 0.4 }, { scope: GAMES_ROW.scope })
+ */
+
+/**
+ * Master sound for every hadoku game. Device scope: the right volume belongs
+ * to the speakers, not the account. A game's own levels (music, effects) stay
+ * in its own row; these two sit above them.
+ */
+declare const GAMES_ROW: {
+    readonly appId: "games";
+    readonly scope: "device";
+    readonly schema: z.ZodObject<{
+        muted: z.ZodOptional<z.ZodBoolean>;
+        volume: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+};
+type GamesPrefs = z.infer<typeof GAMES_ROW.schema>;
+declare const GAMES_DEFAULTS: Required<GamesPrefs>;
+
+export { GAMES_DEFAULTS, GAMES_ROW, type GamesPrefs };

package/dist/platform.js

@@ -0,0 +1,17 @@
+// src/platform.ts
+import { z } from "zod";
+var GAMES_ROW = {
+  appId: "games",
+  scope: "device",
+  schema: z.object({
+    /** Silences the game entirely; `volume` is kept for when it is unmuted. */
+    muted: z.boolean().optional(),
+    /** Master volume, 0 (silent) to 1 (full). */
+    volume: z.number().min(0).max(1).optional()
+  })
+};
+var GAMES_DEFAULTS = { muted: false, volume: 1 };
+export {
+  GAMES_DEFAULTS,
+  GAMES_ROW
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hadoku/prefs-client",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "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), and the one resolved avatar per user (./avatar).",
   "type": "module",
   "main": "./dist/index.js",
@@ -18,6 +18,10 @@
       "types": "./dist/games.d.ts",
       "default": "./dist/games.js"
     },
+    "./platform": {
+      "types": "./dist/platform.d.ts",
+      "default": "./dist/platform.js"
+    },
     "./avatar": {
       "types": "./dist/avatar.d.ts",
       "default": "./dist/avatar.js"