@memberjunction/react-runtime 5.40.2 → 5.41.0

package/dist/utilities/user-state.d.ts

@@ -0,0 +1,7 @@
+export declare const USER_STATE_KEY_PREFIX = "InteractiveComponents_UserState_Root/";
+export declare function resolveUserStateScope(explicitScope: string | undefined | null, namespace: string | undefined | null, name: string | undefined | null): string | null;
+export declare function userStateStorageKey(scope: string | null): string | null;
+export declare function parseStoredUserSettings(raw: string | undefined | null): Record<string, unknown>;
+export declare function mergeUserSettings(hostDefaults: Record<string, unknown> | undefined | null, stored: Record<string, unknown> | undefined | null): Record<string, unknown>;
+export declare function applyUserSettingsUpdate(current: Record<string, unknown> | undefined | null, incoming: Record<string, unknown> | undefined | null): Record<string, unknown>;
+//# sourceMappingURL=user-state.d.ts.map

package/dist/utilities/user-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-state.d.ts","sourceRoot":"","sources":["../../src/utilities/user-state.ts"],"names":[],"mappings":"AAoBA,eAAO,MAAM,qBAAqB,0CAA0C,CAAC;AAiB7E,wBAAgB,qBAAqB,CACnC,aAAa,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,EACxC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,EACpC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAC9B,MAAM,GAAG,IAAI,CAYf;AAMD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAEvE;AAOD,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAa/F;AAOD,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,IAAI,EACxD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,IAAI,GACjD,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzB;AAsBD,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,IAAI,EACnD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,IAAI,GACnD,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAUzB"}

package/dist/utilities/user-state.js

@@ -0,0 +1,48 @@
+export const USER_STATE_KEY_PREFIX = 'InteractiveComponents_UserState_Root/';
+export function resolveUserStateScope(explicitScope, namespace, name) {
+    const explicit = explicitScope?.trim();
+    if (explicit) {
+        return explicit.toLowerCase();
+    }
+    const cleanName = name?.trim();
+    if (!cleanName) {
+        return null;
+    }
+    const cleanNamespace = namespace?.trim();
+    const scope = cleanNamespace ? `${cleanNamespace}/${cleanName}` : cleanName;
+    return scope.toLowerCase();
+}
+export function userStateStorageKey(scope) {
+    return scope ? `${USER_STATE_KEY_PREFIX}${scope}` : null;
+}
+export function parseStoredUserSettings(raw) {
+    if (!raw) {
+        return {};
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return parsed;
+        }
+        return {};
+    }
+    catch {
+        return {};
+    }
+}
+export function mergeUserSettings(hostDefaults, stored) {
+    return { ...(hostDefaults ?? {}), ...(stored ?? {}) };
+}
+export function applyUserSettingsUpdate(current, incoming) {
+    const next = { ...(current ?? {}) };
+    for (const [key, value] of Object.entries(incoming ?? {})) {
+        if (value === null || value === undefined) {
+            delete next[key];
+        }
+        else {
+            next[key] = value;
+        }
+    }
+    return next;
+}
+//# sourceMappingURL=user-state.js.map

package/dist/utilities/user-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-state.js","sourceRoot":"","sources":["../../src/utilities/user-state.ts"],"names":[],"mappings":"AAoBA,MAAM,CAAC,MAAM,qBAAqB,GAAG,uCAAuC,CAAC;AAiB7E,MAAM,UAAU,qBAAqB,CACnC,aAAwC,EACxC,SAAoC,EACpC,IAA+B;IAE/B,MAAM,QAAQ,GAAG,aAAa,EAAE,IAAI,EAAE,CAAC;IACvC,IAAI,QAAQ,EAAE,CAAC;QACb,OAAO,QAAQ,CAAC,WAAW,EAAE,CAAC;IAChC,CAAC;IACD,MAAM,SAAS,GAAG,IAAI,EAAE,IAAI,EAAE,CAAC;IAC/B,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,cAAc,GAAG,SAAS,EAAE,IAAI,EAAE,CAAC;IACzC,MAAM,KAAK,GAAG,cAAc,CAAC,CAAC,CAAC,GAAG,cAAc,IAAI,SAAS,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IAC5E,OAAO,KAAK,CAAC,WAAW,EAAE,CAAC;AAC7B,CAAC;AAMD,MAAM,UAAU,mBAAmB,CAAC,KAAoB;IACtD,OAAO,KAAK,CAAC,CAAC,CAAC,GAAG,qBAAqB,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AAC3D,CAAC;AAOD,MAAM,UAAU,uBAAuB,CAAC,GAA8B;IACpE,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YACnE,OAAO,MAAiC,CAAC;QAC3C,CAAC;QACD,OAAO,EAAE,CAAC;IACZ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAOD,MAAM,UAAU,iBAAiB,CAC/B,YAAwD,EACxD,MAAkD;IAElD,OAAO,EAAE,GAAG,CAAC,YAAY,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,CAAC;AACxD,CAAC;AAsBD,MAAM,UAAU,uBAAuB,CACrC,OAAmD,EACnD,QAAoD;IAEpD,MAAM,IAAI,GAA4B,EAAE,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC,EAAE,CAAC;IAC7D,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC,EAAE,CAAC;QAC1D,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YAC1C,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC;QACnB,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACpB,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC","sourcesContent":["/**\n * @fileoverview Helpers for the per-user interactive-component settings contract\n * (`savedUserSettings` in / `onSaveUserSettings` out).\n *\n * These helpers are intentionally **pure and framework-agnostic** so the Angular\n * host bridge and the Node test harness share one implementation and the scoping /\n * serialization logic can be unit tested in isolation. The host wires these to a\n * durable per-user store (e.g. `UserInfoEngine`); the runtime itself never persists.\n *\n * @module @memberjunction/react-runtime\n */\n\n/**\n * Prefix applied to every interactive-component user-settings storage key. The\n * full key is `InteractiveComponents_UserState_Root/<scope>`, where `<scope>` is\n * resolved by {@link resolveUserStateScope}. It is deliberately long and unique\n * to avoid collisions with other namespaced keys in the shared\n * `MJ: User Settings` keyspace. Keeping the prefix in one place also avoids\n * stringly-typed drift between the seed (read) and persist (write) paths.\n */\nexport const USER_STATE_KEY_PREFIX = 'InteractiveComponents_UserState_Root/';\n\n/**\n * Resolve the stable per-component scope used to namespace a component's\n * persisted user settings.\n *\n * An explicit, host-supplied scope always wins (used when a host needs to\n * differentiate two instances of the same component spec — e.g. scope a form's\n * settings by the entity it edits). Otherwise the scope is derived from the\n * component spec's `namespace` + `name`.\n *\n * The result is lowercased to avoid case-variant duplicate rows in the settings\n * store (per MJ's user-settings key convention).\n *\n * @returns the resolved scope, or `null` when no stable scope can be derived\n *          (e.g. an unnamed component) — signaling the caller to skip persistence.\n */\nexport function resolveUserStateScope(\n  explicitScope: string | undefined | null,\n  namespace: string | undefined | null,\n  name: string | undefined | null\n): string | null {\n  const explicit = explicitScope?.trim();\n  if (explicit) {\n    return explicit.toLowerCase();\n  }\n  const cleanName = name?.trim();\n  if (!cleanName) {\n    return null;\n  }\n  const cleanNamespace = namespace?.trim();\n  const scope = cleanNamespace ? `${cleanNamespace}/${cleanName}` : cleanName;\n  return scope.toLowerCase();\n}\n\n/**\n * Build the full storage key for a resolved scope, or `null` when the scope is\n * `null` (persistence should be skipped).\n */\nexport function userStateStorageKey(scope: string | null): string | null {\n  return scope ? `${USER_STATE_KEY_PREFIX}${scope}` : null;\n}\n\n/**\n * Safely parse a stored settings blob into a plain object. Returns `{}` for\n * null/empty input, invalid JSON, or any non-object JSON (arrays, primitives) —\n * persisted user settings are always a flat key/value object.\n */\nexport function parseStoredUserSettings(raw: string | undefined | null): Record<string, unknown> {\n  if (!raw) {\n    return {};\n  }\n  try {\n    const parsed = JSON.parse(raw);\n    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {\n      return parsed as Record<string, unknown>;\n    }\n    return {};\n  } catch {\n    return {};\n  }\n}\n\n/**\n * Merge host-provided defaults with the stored per-user settings. Stored values\n * win, so a returning user sees their saved preferences while a host can still\n * seed sensible first-run defaults that fill any gaps.\n */\nexport function mergeUserSettings(\n  hostDefaults: Record<string, unknown> | undefined | null,\n  stored: Record<string, unknown> | undefined | null\n): Record<string, unknown> {\n  return { ...(hostDefaults ?? {}), ...(stored ?? {}) };\n}\n\n/**\n * Apply an `onSaveUserSettings` payload to the host's current settings snapshot.\n *\n * **Merge, not replace.** The contract asks components to pass the complete\n * settings object, but the host must be resilient to a component (especially an\n * AI-generated one) passing only the changed keys — and to the stale-prop case\n * where a component spreads the mount-time `savedUserSettings` prop, which the\n * host deliberately never refreshes mid-session (no re-render on save). Under\n * full-replace semantics either slip silently wipes every other saved\n * preference; under merge the worst case is a no-op.\n *\n * **Removing a key requires explicit intent**: set its value to `null` and the\n * key is deleted from the snapshot (reads fall back to defaults via the\n * documented `savedUserSettings?.key ?? fallback` pattern). `undefined` values\n * are treated the same way, since `JSON.stringify` would drop them from the\n * persisted blob anyway and the in-memory snapshot must stay consistent with\n * what is stored.\n *\n * @returns a new object — neither input is mutated.\n */\nexport function applyUserSettingsUpdate(\n  current: Record<string, unknown> | undefined | null,\n  incoming: Record<string, unknown> | undefined | null\n): Record<string, unknown> {\n  const next: Record<string, unknown> = { ...(current ?? {}) };\n  for (const [key, value] of Object.entries(incoming ?? {})) {\n    if (value === null || value === undefined) {\n      delete next[key];\n    } else {\n      next[key] = value;\n    }\n  }\n  return next;\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memberjunction/react-runtime",
-  "version": "5.40.2",
+  "version": "5.41.0",
   "description": "Platform-agnostic React component runtime for MemberJunction. Provides core compilation, registry, and execution capabilities for React components in any JavaScript environment.",
   "type": "module",
   "main": "dist/index.js",
@@ -29,11 +29,11 @@
   },
   "homepage": "https://github.com/MemberJunction/MJ#readme",
   "dependencies": {
-    "@memberjunction/core": "5.40.2",
-    "@memberjunction/global": "5.40.2",
-    "@memberjunction/interactive-component-types": "5.40.2",
-    "@memberjunction/core-entities": "5.40.2",
-    "@memberjunction/graphql-dataprovider": "5.40.2",
+    "@memberjunction/core": "5.41.0",
+    "@memberjunction/global": "5.41.0",
+    "@memberjunction/interactive-component-types": "5.41.0",
+    "@memberjunction/core-entities": "5.41.0",
+    "@memberjunction/graphql-dataprovider": "5.41.0",
     "@babel/standalone": "^7.29.1",
     "rxjs": "^7.8.2"
   },

package/src/__tests__/user-state.test.ts

@@ -0,0 +1,155 @@
+import { describe, it, expect } from 'vitest';
+import {
+  USER_STATE_KEY_PREFIX,
+  resolveUserStateScope,
+  userStateStorageKey,
+  parseStoredUserSettings,
+  mergeUserSettings,
+  applyUserSettingsUpdate
+} from '../utilities/user-state';
+
+describe('user-state helpers', () => {
+  describe('resolveUserStateScope', () => {
+    it('prefers an explicit scope over namespace/name', () => {
+      expect(resolveUserStateScope('Form/Contacts', 'crm', 'ContactForm')).toBe('form/contacts');
+    });
+
+    it('lowercases the explicit scope', () => {
+      expect(resolveUserStateScope('MyDashboard', null, null)).toBe('mydashboard');
+    });
+
+    it('trims surrounding whitespace from the explicit scope', () => {
+      expect(resolveUserStateScope('  Spaced  ', null, null)).toBe('spaced');
+    });
+
+    it('combines namespace and name when no explicit scope is given', () => {
+      expect(resolveUserStateScope(undefined, 'CRM/Analytics', 'AccountDashboard'))
+        .toBe('crm/analytics/accountdashboard');
+    });
+
+    it('uses just the name when there is no namespace', () => {
+      expect(resolveUserStateScope(undefined, undefined, 'SalesReport')).toBe('salesreport');
+      expect(resolveUserStateScope(null, '   ', 'SalesReport')).toBe('salesreport');
+    });
+
+    it('returns null when no stable scope can be derived', () => {
+      expect(resolveUserStateScope(undefined, undefined, undefined)).toBeNull();
+      expect(resolveUserStateScope('', '', '')).toBeNull();
+      expect(resolveUserStateScope('   ', 'crm', '   ')).toBeNull();
+    });
+  });
+
+  describe('userStateStorageKey', () => {
+    it('prefixes a resolved scope with the unique root namespace', () => {
+      expect(userStateStorageKey('form/contacts')).toBe(`${USER_STATE_KEY_PREFIX}form/contacts`);
+      expect(userStateStorageKey('form/contacts')).toBe('InteractiveComponents_UserState_Root/form/contacts');
+    });
+
+    it('returns null for a null scope', () => {
+      expect(userStateStorageKey(null)).toBeNull();
+    });
+  });
+
+  describe('parseStoredUserSettings', () => {
+    it('parses a valid JSON object', () => {
+      expect(parseStoredUserSettings('{"sortBy":"Name","page":2}')).toEqual({ sortBy: 'Name', page: 2 });
+    });
+
+    it('returns an empty object for null/undefined/empty input', () => {
+      expect(parseStoredUserSettings(null)).toEqual({});
+      expect(parseStoredUserSettings(undefined)).toEqual({});
+      expect(parseStoredUserSettings('')).toEqual({});
+    });
+
+    it('returns an empty object for invalid JSON instead of throwing', () => {
+      expect(parseStoredUserSettings('{not valid json')).toEqual({});
+    });
+
+    it('returns an empty object for non-object JSON (arrays, primitives)', () => {
+      expect(parseStoredUserSettings('[1,2,3]')).toEqual({});
+      expect(parseStoredUserSettings('42')).toEqual({});
+      expect(parseStoredUserSettings('"hello"')).toEqual({});
+      expect(parseStoredUserSettings('null')).toEqual({});
+    });
+  });
+
+  describe('mergeUserSettings', () => {
+    it('lets stored values win over host defaults', () => {
+      const merged = mergeUserSettings({ sortBy: 'CloseDate', viewMode: 'grid' }, { sortBy: 'Name' });
+      expect(merged).toEqual({ sortBy: 'Name', viewMode: 'grid' });
+    });
+
+    it('keeps host defaults that the stored settings do not override', () => {
+      expect(mergeUserSettings({ a: 1, b: 2 }, { b: 3 })).toEqual({ a: 1, b: 3 });
+    });
+
+    it('handles null/undefined on either side', () => {
+      expect(mergeUserSettings(null, { x: 1 })).toEqual({ x: 1 });
+      expect(mergeUserSettings({ x: 1 }, null)).toEqual({ x: 1 });
+      expect(mergeUserSettings(null, null)).toEqual({});
+      expect(mergeUserSettings(undefined, undefined)).toEqual({});
+    });
+
+    it('returns a new object (does not mutate inputs)', () => {
+      const defaults = { a: 1 };
+      const stored = { b: 2 };
+      const merged = mergeUserSettings(defaults, stored);
+      expect(merged).not.toBe(defaults);
+      expect(merged).not.toBe(stored);
+      expect(defaults).toEqual({ a: 1 });
+      expect(stored).toEqual({ b: 2 });
+    });
+  });
+
+  describe('applyUserSettingsUpdate', () => {
+    it('overlays incoming keys onto the current snapshot', () => {
+      expect(applyUserSettingsUpdate({ viewMode: 'grid', sortBy: 'CloseDate' }, { sortBy: 'Name' }))
+        .toEqual({ viewMode: 'grid', sortBy: 'Name' });
+    });
+
+    it('preserves untouched keys when a component passes only a delta', () => {
+      // The AI-forgot-the-spread case: a delta must not wipe other preferences.
+      expect(applyUserSettingsUpdate({ viewMode: 'grid', page: 3 }, { sortBy: 'Name' }))
+        .toEqual({ viewMode: 'grid', page: 3, sortBy: 'Name' });
+    });
+
+    it('survives the stale-prop spread (two sequential saves keep both changes)', () => {
+      // Component spreads the mount-time prop both times; the host snapshot
+      // must still accumulate both changes.
+      const mountProp = { viewMode: 'grid' };
+      let snapshot = applyUserSettingsUpdate(mountProp, { ...mountProp, sortBy: 'Name' });
+      snapshot = applyUserSettingsUpdate(snapshot, { ...mountProp, viewMode: 'list' });
+      expect(snapshot).toEqual({ viewMode: 'list', sortBy: 'Name' });
+    });
+
+    it('removes a key when its incoming value is explicitly null', () => {
+      expect(applyUserSettingsUpdate({ sortBy: 'Name', viewMode: 'grid' }, { sortBy: null }))
+        .toEqual({ viewMode: 'grid' });
+    });
+
+    it('removes a key when its incoming value is undefined', () => {
+      expect(applyUserSettingsUpdate({ sortBy: 'Name', viewMode: 'grid' }, { sortBy: undefined }))
+        .toEqual({ viewMode: 'grid' });
+    });
+
+    it('treats a full-object payload as a superset (replace-equivalent)', () => {
+      expect(applyUserSettingsUpdate({ a: 1, b: 2 }, { a: 10, b: 20 })).toEqual({ a: 10, b: 20 });
+    });
+
+    it('handles null/undefined on either side', () => {
+      expect(applyUserSettingsUpdate(null, { x: 1 })).toEqual({ x: 1 });
+      expect(applyUserSettingsUpdate({ x: 1 }, null)).toEqual({ x: 1 });
+      expect(applyUserSettingsUpdate(null, null)).toEqual({});
+    });
+
+    it('returns a new object (does not mutate inputs)', () => {
+      const current = { a: 1 };
+      const incoming = { b: 2 };
+      const next = applyUserSettingsUpdate(current, incoming);
+      expect(next).not.toBe(current);
+      expect(next).not.toBe(incoming);
+      expect(current).toEqual({ a: 1 });
+      expect(incoming).toEqual({ b: 2 });
+    });
+  });
+});

package/src/index.ts

@@ -140,6 +140,15 @@ export {
   unwrapAllComponents
 } from './utilities/component-unwrapper';
 
+export {
+  USER_STATE_KEY_PREFIX,
+  resolveUserStateScope,
+  userStateStorageKey,
+  parseStoredUserSettings,
+  mergeUserSettings,
+  applyUserSettingsUpdate
+} from './utilities/user-state';
+
 // Version information
 export const VERSION = '2.69.1';
 

package/src/utilities/user-state.ts

@@ -0,0 +1,129 @@
+/**
+ * @fileoverview Helpers for the per-user interactive-component settings contract
+ * (`savedUserSettings` in / `onSaveUserSettings` out).
+ *
+ * These helpers are intentionally **pure and framework-agnostic** so the Angular
+ * host bridge and the Node test harness share one implementation and the scoping /
+ * serialization logic can be unit tested in isolation. The host wires these to a
+ * durable per-user store (e.g. `UserInfoEngine`); the runtime itself never persists.
+ *
+ * @module @memberjunction/react-runtime
+ */
+
+/**
+ * Prefix applied to every interactive-component user-settings storage key. The
+ * full key is `InteractiveComponents_UserState_Root/<scope>`, where `<scope>` is
+ * resolved by {@link resolveUserStateScope}. It is deliberately long and unique
+ * to avoid collisions with other namespaced keys in the shared
+ * `MJ: User Settings` keyspace. Keeping the prefix in one place also avoids
+ * stringly-typed drift between the seed (read) and persist (write) paths.
+ */
+export const USER_STATE_KEY_PREFIX = 'InteractiveComponents_UserState_Root/';
+
+/**
+ * Resolve the stable per-component scope used to namespace a component's
+ * persisted user settings.
+ *
+ * An explicit, host-supplied scope always wins (used when a host needs to
+ * differentiate two instances of the same component spec — e.g. scope a form's
+ * settings by the entity it edits). Otherwise the scope is derived from the
+ * component spec's `namespace` + `name`.
+ *
+ * The result is lowercased to avoid case-variant duplicate rows in the settings
+ * store (per MJ's user-settings key convention).
+ *
+ * @returns the resolved scope, or `null` when no stable scope can be derived
+ *          (e.g. an unnamed component) — signaling the caller to skip persistence.
+ */
+export function resolveUserStateScope(
+  explicitScope: string | undefined | null,
+  namespace: string | undefined | null,
+  name: string | undefined | null
+): string | null {
+  const explicit = explicitScope?.trim();
+  if (explicit) {
+    return explicit.toLowerCase();
+  }
+  const cleanName = name?.trim();
+  if (!cleanName) {
+    return null;
+  }
+  const cleanNamespace = namespace?.trim();
+  const scope = cleanNamespace ? `${cleanNamespace}/${cleanName}` : cleanName;
+  return scope.toLowerCase();
+}
+
+/**
+ * Build the full storage key for a resolved scope, or `null` when the scope is
+ * `null` (persistence should be skipped).
+ */
+export function userStateStorageKey(scope: string | null): string | null {
+  return scope ? `${USER_STATE_KEY_PREFIX}${scope}` : null;
+}
+
+/**
+ * Safely parse a stored settings blob into a plain object. Returns `{}` for
+ * null/empty input, invalid JSON, or any non-object JSON (arrays, primitives) —
+ * persisted user settings are always a flat key/value object.
+ */
+export function parseStoredUserSettings(raw: string | undefined | null): Record<string, unknown> {
+  if (!raw) {
+    return {};
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      return parsed as Record<string, unknown>;
+    }
+    return {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Merge host-provided defaults with the stored per-user settings. Stored values
+ * win, so a returning user sees their saved preferences while a host can still
+ * seed sensible first-run defaults that fill any gaps.
+ */
+export function mergeUserSettings(
+  hostDefaults: Record<string, unknown> | undefined | null,
+  stored: Record<string, unknown> | undefined | null
+): Record<string, unknown> {
+  return { ...(hostDefaults ?? {}), ...(stored ?? {}) };
+}
+
+/**
+ * Apply an `onSaveUserSettings` payload to the host's current settings snapshot.
+ *
+ * **Merge, not replace.** The contract asks components to pass the complete
+ * settings object, but the host must be resilient to a component (especially an
+ * AI-generated one) passing only the changed keys — and to the stale-prop case
+ * where a component spreads the mount-time `savedUserSettings` prop, which the
+ * host deliberately never refreshes mid-session (no re-render on save). Under
+ * full-replace semantics either slip silently wipes every other saved
+ * preference; under merge the worst case is a no-op.
+ *
+ * **Removing a key requires explicit intent**: set its value to `null` and the
+ * key is deleted from the snapshot (reads fall back to defaults via the
+ * documented `savedUserSettings?.key ?? fallback` pattern). `undefined` values
+ * are treated the same way, since `JSON.stringify` would drop them from the
+ * persisted blob anyway and the in-memory snapshot must stay consistent with
+ * what is stored.
+ *
+ * @returns a new object — neither input is mutated.
+ */
+export function applyUserSettingsUpdate(
+  current: Record<string, unknown> | undefined | null,
+  incoming: Record<string, unknown> | undefined | null
+): Record<string, unknown> {
+  const next: Record<string, unknown> = { ...(current ?? {}) };
+  for (const [key, value] of Object.entries(incoming ?? {})) {
+    if (value === null || value === undefined) {
+      delete next[key];
+    } else {
+      next[key] = value;
+    }
+  }
+  return next;
+}