@object-ui/data-objectstack 4.5.0 → 4.6.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @object-ui/data-objectstack
 
+## 4.6.0
+
+### Patch Changes
+
+- @object-ui/types@4.6.0
+- @object-ui/core@4.6.0
+
 ## 4.5.0
 
 ### Patch Changes

package/README.md

@@ -272,6 +272,46 @@ await dataSource.bulk('users', 'delete', [
 - Provides partial success reporting for resilient error handling
 - Atomic operations where supported by the backend
 
+## User-Scoped State Adapter
+
+In addition to the main `DataSource` adapter, this package ships
+`createObjectStackUserStateAdapter` — a small factory that lets Object UI
+persist per-user UI state (favorites, recent items) into ObjectStack.
+
+```typescript
+import { createObjectStackUserStateAdapter } from '@object-ui/data-objectstack';
+import { useAttachUserStateAdapters } from '@object-ui/app-shell';
+
+const favoritesAdapter = createObjectStackUserStateAdapter({
+  dataSource,        // the ObjectStack DataSource
+  userId: user.id,
+  kind: 'favorites', // or 'recent'
+  // resource: 'user_app_state',  // default
+  // onError: (op, err) => console.warn(`[user-state] ${op} failed`, err),
+});
+
+attach('favorites', favoritesAdapter);
+```
+
+### Backend contract
+
+A single object stores one row per `(user_id, kind)` pair:
+
+```yaml
+object: user_app_state
+fields:
+  - { name: user_id,    type: string,   indexed: true }
+  - { name: kind,       type: string,   indexed: true }
+  - { name: payload,    type: json }
+  - { name: updated_at, type: datetime }
+unique: [user_id, kind]
+```
+
+If the object doesn't exist, every call 404s and the UI silently degrades to
+localStorage-only persistence. See
+[User-Scoped State Persistence](../../content/docs/guide/user-state-persistence.md)
+for the full design.
+
 ## API Reference
 
 ### ObjectStackAdapter

package/dist/index.cjs

@@ -37,6 +37,7 @@ __export(index_exports, {
   createDefaultCanvasConfig: () => createDefaultCanvasConfig,
   createErrorFromResponse: () => createErrorFromResponse,
   createObjectStackAdapter: () => createObjectStackAdapter,
+  createObjectStackUserStateAdapter: () => createObjectStackUserStateAdapter,
   generateContractManifest: () => generateContractManifest,
   getSharedDiscovery: () => getSharedDiscovery,
   is404Error: () => is404Error,
@@ -568,6 +569,96 @@ function generateContractManifest(contract) {
   };
 }
 
+// src/userState.ts
+var DEFAULT_RESOURCE = "user_app_state";
+function createObjectStackUserStateAdapter(options) {
+  const {
+    dataSource,
+    userId,
+    kind,
+    resource = DEFAULT_RESOURCE,
+    onError = () => {
+    }
+  } = options;
+  let cachedRowId = null;
+  const findExisting = async () => {
+    const params = {
+      filter: {
+        user_id: userId,
+        kind
+      },
+      limit: 1
+    };
+    const result = await dataSource.find(resource, params);
+    const rows = result?.data ?? [];
+    return rows.length > 0 ? rows[0] : null;
+  };
+  const decodePayload = (payload) => {
+    if (Array.isArray(payload)) return payload;
+    if (typeof payload === "string") {
+      try {
+        const parsed = JSON.parse(payload);
+        return Array.isArray(parsed) ? parsed : [];
+      } catch {
+        return [];
+      }
+    }
+    return [];
+  };
+  return {
+    async load() {
+      try {
+        const row = await findExisting();
+        if (!row) {
+          cachedRowId = null;
+          return [];
+        }
+        if (row.id !== void 0 && row.id !== null) cachedRowId = row.id;
+        return decodePayload(row.payload);
+      } catch (error) {
+        onError("load", error);
+        return [];
+      }
+    },
+    async save(items) {
+      try {
+        const now = (/* @__PURE__ */ new Date()).toISOString();
+        if (cachedRowId !== null) {
+          try {
+            await dataSource.update(resource, cachedRowId, {
+              payload: items,
+              updated_at: now
+            });
+            return;
+          } catch (updateError) {
+            cachedRowId = null;
+            onError("save", updateError);
+          }
+        }
+        const existing = await findExisting();
+        if (existing && existing.id !== void 0 && existing.id !== null) {
+          cachedRowId = existing.id;
+          await dataSource.update(resource, existing.id, {
+            payload: items,
+            updated_at: now
+          });
+          return;
+        }
+        const created = await dataSource.create(resource, {
+          user_id: userId,
+          kind,
+          payload: items,
+          updated_at: now
+        });
+        const newId = created?.id;
+        if (newId !== void 0 && newId !== null) cachedRowId = newId;
+      } catch (error) {
+        onError("save", error);
+      }
+    }
+  };
+}
+
 // src/integration.ts
 var IntegrationManager = class {
   constructor() {
@@ -2066,6 +2157,7 @@ function createObjectStackAdapter(config) {
   createDefaultCanvasConfig,
   createErrorFromResponse,
   createObjectStackAdapter,
+  createObjectStackUserStateAdapter,
   generateContractManifest,
   getSharedDiscovery,
   is404Error,

package/dist/index.d.cts

@@ -315,6 +315,72 @@ declare function validatePluginContract(contract: PluginContract): ContractValid
  */
 declare function generateContractManifest(contract: PluginContract): Record<string, unknown>;
 
+/**
+ * ObjectStack-backed `UserDataAdapter` factory.
+ *
+ * Persists arbitrary per-user UI state (favorites, recently-accessed items, …)
+ * as a single JSON blob per `(user_id, kind)` row in an object named
+ * `user_app_state`. The single-blob approach keeps round-trips down (one
+ * `find` + one `update`/`create` per change) and matches the
+ * "save the full list" semantics of `FavoritesProvider` / `RecentItemsProvider`.
+ *
+ * ## Required object schema
+ *
+ * Configure an object in ObjectStack with at least the following fields:
+ *
+ * ```yaml
+ * object: user_app_state
+ * fields:
+ *   user_id:    string   # indexed
+ *   kind:       string   # indexed  (e.g. "favorites" | "recent")
+ *   payload:    json     # the serialised list
+ *   updated_at: datetime # (optional) auto-managed
+ * unique: [user_id, kind]
+ * ```
+ *
+ * ## Failure modes
+ *
+ * The adapter is designed to **degrade silently**. Any error — missing schema,
+ * 4xx/5xx, network — is caught:
+ *
+ * - `load()` returns `[]`, so the hosting provider keeps its localStorage state.
+ * - `save()` resolves without throwing, so UI mutations never surface a toast.
+ *
+ * This means an OSS user who hasn't yet provisioned the `user_app_state`
+ * object still gets a perfectly working (localStorage-only) favorites /
+ * recent-items experience. As soon as the object exists, persistence
+ * "lights up" with no code change.
+ *
+ * @module
+ */
+
+interface ObjectStackUserStateAdapterOptions {
+    /** Connected data source (usually the one provided by `<AdapterProvider>`). */
+    dataSource: DataSource<any>;
+    /** Authenticated user id. */
+    userId: string;
+    /** Logical bucket key, e.g. `"favorites"` or `"recent"`. */
+    kind: string;
+    /** Override the storage object name. Defaults to `"user_app_state"`. */
+    resource?: string;
+    /**
+     * Optional console logger for development diagnostics. Defaults to noop so
+     * production builds stay quiet.
+     */
+    onError?: (where: 'load' | 'save', error: unknown) => void;
+}
+interface UserDataAdapter<T> {
+    load(): Promise<T[]>;
+    save(items: T[]): Promise<void>;
+}
+/**
+ * Build a `UserDataAdapter<T>` backed by ObjectStack.
+ *
+ * Each adapter instance is bound to a single `(user, kind)` pair; create one
+ * per slot you want to persist.
+ */
+declare function createObjectStackUserStateAdapter<T = unknown>(options: ObjectStackUserStateAdapterOptions): UserDataAdapter<T>;
+
 /**
  * ObjectUI
  * Copyright (c) 2024-present ObjectStack Inc.
@@ -1057,4 +1123,4 @@ declare function createObjectStackAdapter<T = unknown>(config: {
     reconnectDelay?: number;
 }): DataSource<T>;
 
-export { type AuditEventType, type AuditLogConfig, type AuditLogEntry, AuthenticationError, type BatchProgressEvent, type BatchProgressListener, BulkOperationError, type CSPConfig, type CacheStats, type CloudDeploymentConfig, type CloudHostingConfig, type CloudMarketplaceEntry, CloudOperations, ConnectionError, type ConnectionState, type ConnectionStateEvent, type ConnectionStateListener, type ContractValidationError, type ContractValidationResult, type DataMaskingConfig, type DataMaskingRule, type EmailIntegrationConfig, type IntegrationConfig, IntegrationManager, type IntegrationProvider, type IntegrationTrigger, MetadataNotFoundError, ObjectStackAdapter, ObjectStackError, type PluginAPIContract, type PluginContract, type PluginExport, SecurityManager, type SecurityPolicy, type SlackIntegrationConfig, type StudioCanvasConfig, type StudioColorPalette, type StudioPropertyEditor, type StudioShadowPreset, type StudioThemeBuilderConfig, type StudioTypographyPreset, ValidationError, type WebhookIntegrationConfig, calculateAutoLayout, clearSharedDiscoveryCache, createDefaultCanvasConfig, createErrorFromResponse, createObjectStackAdapter, generateContractManifest, getSharedDiscovery, is404Error, isErrorType, isObjectStackError, snapToGrid, validatePluginContract };
+export { type AuditEventType, type AuditLogConfig, type AuditLogEntry, AuthenticationError, type BatchProgressEvent, type BatchProgressListener, BulkOperationError, type CSPConfig, type CacheStats, type CloudDeploymentConfig, type CloudHostingConfig, type CloudMarketplaceEntry, CloudOperations, ConnectionError, type ConnectionState, type ConnectionStateEvent, type ConnectionStateListener, type ContractValidationError, type ContractValidationResult, type DataMaskingConfig, type DataMaskingRule, type EmailIntegrationConfig, type IntegrationConfig, IntegrationManager, type IntegrationProvider, type IntegrationTrigger, MetadataNotFoundError, ObjectStackAdapter, ObjectStackError, type ObjectStackUserStateAdapterOptions, type PluginAPIContract, type PluginContract, type PluginExport, SecurityManager, type SecurityPolicy, type SlackIntegrationConfig, type StudioCanvasConfig, type StudioColorPalette, type StudioPropertyEditor, type StudioShadowPreset, type StudioThemeBuilderConfig, type StudioTypographyPreset, type UserDataAdapter, ValidationError, type WebhookIntegrationConfig, calculateAutoLayout, clearSharedDiscoveryCache, createDefaultCanvasConfig, createErrorFromResponse, createObjectStackAdapter, createObjectStackUserStateAdapter, generateContractManifest, getSharedDiscovery, is404Error, isErrorType, isObjectStackError, snapToGrid, validatePluginContract };

package/dist/index.d.ts

@@ -315,6 +315,72 @@ declare function validatePluginContract(contract: PluginContract): ContractValid
  */
 declare function generateContractManifest(contract: PluginContract): Record<string, unknown>;
 
+/**
+ * ObjectStack-backed `UserDataAdapter` factory.
+ *
+ * Persists arbitrary per-user UI state (favorites, recently-accessed items, …)
+ * as a single JSON blob per `(user_id, kind)` row in an object named
+ * `user_app_state`. The single-blob approach keeps round-trips down (one
+ * `find` + one `update`/`create` per change) and matches the
+ * "save the full list" semantics of `FavoritesProvider` / `RecentItemsProvider`.
+ *
+ * ## Required object schema
+ *
+ * Configure an object in ObjectStack with at least the following fields:
+ *
+ * ```yaml
+ * object: user_app_state
+ * fields:
+ *   user_id:    string   # indexed
+ *   kind:       string   # indexed  (e.g. "favorites" | "recent")
+ *   payload:    json     # the serialised list
+ *   updated_at: datetime # (optional) auto-managed
+ * unique: [user_id, kind]
+ * ```
+ *
+ * ## Failure modes
+ *
+ * The adapter is designed to **degrade silently**. Any error — missing schema,
+ * 4xx/5xx, network — is caught:
+ *
+ * - `load()` returns `[]`, so the hosting provider keeps its localStorage state.
+ * - `save()` resolves without throwing, so UI mutations never surface a toast.
+ *
+ * This means an OSS user who hasn't yet provisioned the `user_app_state`
+ * object still gets a perfectly working (localStorage-only) favorites /
+ * recent-items experience. As soon as the object exists, persistence
+ * "lights up" with no code change.
+ *
+ * @module
+ */
+
+interface ObjectStackUserStateAdapterOptions {
+    /** Connected data source (usually the one provided by `<AdapterProvider>`). */
+    dataSource: DataSource<any>;
+    /** Authenticated user id. */
+    userId: string;
+    /** Logical bucket key, e.g. `"favorites"` or `"recent"`. */
+    kind: string;
+    /** Override the storage object name. Defaults to `"user_app_state"`. */
+    resource?: string;
+    /**
+     * Optional console logger for development diagnostics. Defaults to noop so
+     * production builds stay quiet.
+     */
+    onError?: (where: 'load' | 'save', error: unknown) => void;
+}
+interface UserDataAdapter<T> {
+    load(): Promise<T[]>;
+    save(items: T[]): Promise<void>;
+}
+/**
+ * Build a `UserDataAdapter<T>` backed by ObjectStack.
+ *
+ * Each adapter instance is bound to a single `(user, kind)` pair; create one
+ * per slot you want to persist.
+ */
+declare function createObjectStackUserStateAdapter<T = unknown>(options: ObjectStackUserStateAdapterOptions): UserDataAdapter<T>;
+
 /**
  * ObjectUI
  * Copyright (c) 2024-present ObjectStack Inc.
@@ -1057,4 +1123,4 @@ declare function createObjectStackAdapter<T = unknown>(config: {
     reconnectDelay?: number;
 }): DataSource<T>;
 
-export { type AuditEventType, type AuditLogConfig, type AuditLogEntry, AuthenticationError, type BatchProgressEvent, type BatchProgressListener, BulkOperationError, type CSPConfig, type CacheStats, type CloudDeploymentConfig, type CloudHostingConfig, type CloudMarketplaceEntry, CloudOperations, ConnectionError, type ConnectionState, type ConnectionStateEvent, type ConnectionStateListener, type ContractValidationError, type ContractValidationResult, type DataMaskingConfig, type DataMaskingRule, type EmailIntegrationConfig, type IntegrationConfig, IntegrationManager, type IntegrationProvider, type IntegrationTrigger, MetadataNotFoundError, ObjectStackAdapter, ObjectStackError, type PluginAPIContract, type PluginContract, type PluginExport, SecurityManager, type SecurityPolicy, type SlackIntegrationConfig, type StudioCanvasConfig, type StudioColorPalette, type StudioPropertyEditor, type StudioShadowPreset, type StudioThemeBuilderConfig, type StudioTypographyPreset, ValidationError, type WebhookIntegrationConfig, calculateAutoLayout, clearSharedDiscoveryCache, createDefaultCanvasConfig, createErrorFromResponse, createObjectStackAdapter, generateContractManifest, getSharedDiscovery, is404Error, isErrorType, isObjectStackError, snapToGrid, validatePluginContract };
+export { type AuditEventType, type AuditLogConfig, type AuditLogEntry, AuthenticationError, type BatchProgressEvent, type BatchProgressListener, BulkOperationError, type CSPConfig, type CacheStats, type CloudDeploymentConfig, type CloudHostingConfig, type CloudMarketplaceEntry, CloudOperations, ConnectionError, type ConnectionState, type ConnectionStateEvent, type ConnectionStateListener, type ContractValidationError, type ContractValidationResult, type DataMaskingConfig, type DataMaskingRule, type EmailIntegrationConfig, type IntegrationConfig, IntegrationManager, type IntegrationProvider, type IntegrationTrigger, MetadataNotFoundError, ObjectStackAdapter, ObjectStackError, type ObjectStackUserStateAdapterOptions, type PluginAPIContract, type PluginContract, type PluginExport, SecurityManager, type SecurityPolicy, type SlackIntegrationConfig, type StudioCanvasConfig, type StudioColorPalette, type StudioPropertyEditor, type StudioShadowPreset, type StudioThemeBuilderConfig, type StudioTypographyPreset, type UserDataAdapter, ValidationError, type WebhookIntegrationConfig, calculateAutoLayout, clearSharedDiscoveryCache, createDefaultCanvasConfig, createErrorFromResponse, createObjectStackAdapter, createObjectStackUserStateAdapter, generateContractManifest, getSharedDiscovery, is404Error, isErrorType, isObjectStackError, snapToGrid, validatePluginContract };

package/dist/index.js

@@ -525,6 +525,96 @@ function generateContractManifest(contract) {
   };
 }
 
+// src/userState.ts
+var DEFAULT_RESOURCE = "user_app_state";
+function createObjectStackUserStateAdapter(options) {
+  const {
+    dataSource,
+    userId,
+    kind,
+    resource = DEFAULT_RESOURCE,
+    onError = () => {
+    }
+  } = options;
+  let cachedRowId = null;
+  const findExisting = async () => {
+    const params = {
+      filter: {
+        user_id: userId,
+        kind
+      },
+      limit: 1
+    };
+    const result = await dataSource.find(resource, params);
+    const rows = result?.data ?? [];
+    return rows.length > 0 ? rows[0] : null;
+  };
+  const decodePayload = (payload) => {
+    if (Array.isArray(payload)) return payload;
+    if (typeof payload === "string") {
+      try {
+        const parsed = JSON.parse(payload);
+        return Array.isArray(parsed) ? parsed : [];
+      } catch {
+        return [];
+      }
+    }
+    return [];
+  };
+  return {
+    async load() {
+      try {
+        const row = await findExisting();
+        if (!row) {
+          cachedRowId = null;
+          return [];
+        }
+        if (row.id !== void 0 && row.id !== null) cachedRowId = row.id;
+        return decodePayload(row.payload);
+      } catch (error) {
+        onError("load", error);
+        return [];
+      }
+    },
+    async save(items) {
+      try {
+        const now = (/* @__PURE__ */ new Date()).toISOString();
+        if (cachedRowId !== null) {
+          try {
+            await dataSource.update(resource, cachedRowId, {
+              payload: items,
+              updated_at: now
+            });
+            return;
+          } catch (updateError) {
+            cachedRowId = null;
+            onError("save", updateError);
+          }
+        }
+        const existing = await findExisting();
+        if (existing && existing.id !== void 0 && existing.id !== null) {
+          cachedRowId = existing.id;
+          await dataSource.update(resource, existing.id, {
+            payload: items,
+            updated_at: now
+          });
+          return;
+        }
+        const created = await dataSource.create(resource, {
+          user_id: userId,
+          kind,
+          payload: items,
+          updated_at: now
+        });
+        const newId = created?.id;
+        if (newId !== void 0 && newId !== null) cachedRowId = newId;
+      } catch (error) {
+        onError("save", error);
+      }
+    }
+  };
+}
+
 // src/integration.ts
 var IntegrationManager = class {
   constructor() {
@@ -2022,6 +2112,7 @@ export {
   createDefaultCanvasConfig,
   createErrorFromResponse,
   createObjectStackAdapter,
+  createObjectStackUserStateAdapter,
   generateContractManifest,
   getSharedDiscovery,
   is404Error,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/data-objectstack",
-  "version": "4.5.0",
+  "version": "4.6.0",
   "description": "ObjectStack Data Adapter for Object UI",
   "license": "MIT",
   "type": "module",
@@ -23,8 +23,8 @@
   ],
   "dependencies": {
     "@objectstack/client": "^4.0.5",
-    "@object-ui/core": "4.5.0",
-    "@object-ui/types": "4.5.0"
+    "@object-ui/core": "4.6.0",
+    "@object-ui/types": "4.6.0"
   },
   "devDependencies": {
     "tsup": "^8.5.1",

package/src/index.ts

@@ -1790,6 +1790,13 @@ export { CloudOperations } from './cloud';
 export type { CloudDeploymentConfig, CloudHostingConfig, CloudMarketplaceEntry } from './cloud';
 
 export { validatePluginContract, generateContractManifest } from './contracts';
+
+// User-scoped persistence adapter (favorites / recent items / …)
+export { createObjectStackUserStateAdapter } from './userState';
+export type {
+  ObjectStackUserStateAdapterOptions,
+  UserDataAdapter,
+} from './userState';
 export type { PluginContract, PluginExport, PluginAPIContract, ContractValidationResult, ContractValidationError } from './contracts';
 
 export { IntegrationManager } from './integration';

package/src/userState.test.ts

@@ -0,0 +1,241 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { createObjectStackUserStateAdapter } from './userState';
+import type { DataSource } from '@object-ui/types';
+
+function mockDataSource(overrides: Partial<DataSource<any>> = {}): DataSource<any> {
+  return {
+    find: vi.fn().mockResolvedValue({ data: [] }),
+    findOne: vi.fn().mockResolvedValue(null),
+    create: vi.fn().mockResolvedValue({}),
+    update: vi.fn().mockResolvedValue({}),
+    delete: vi.fn().mockResolvedValue(true),
+    ...overrides,
+  } as unknown as DataSource<any>;
+}
+
+describe('createObjectStackUserStateAdapter', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe('load', () => {
+    it('returns [] when no row exists for the (user, kind) pair', async () => {
+      const ds = mockDataSource();
+      const adapter = createObjectStackUserStateAdapter({
+        dataSource: ds,
+        userId: 'u1',
+        kind: 'favorites',
+      });
+
+      const items = await adapter.load();
+
+      expect(items).toEqual([]);
+      expect(ds.find).toHaveBeenCalledWith('user_app_state', {
+        filter: { user_id: 'u1', kind: 'favorites' },
+        limit: 1,
+      });
+    });
+
+    it('returns parsed payload when row exists (array payload)', async () => {
+      const payload = [{ id: 'object:contact', label: 'Contact' }];
+      const ds = mockDataSource({
+        find: vi.fn().mockResolvedValue({
+          data: [{ id: 'row-1', user_id: 'u1', kind: 'recent', payload }],
+        }) as any,
+      });
+
+      const adapter = createObjectStackUserStateAdapter({
+        dataSource: ds,
+        userId: 'u1',
+        kind: 'recent',
+      });
+
+      await expect(adapter.load()).resolves.toEqual(payload);
+    });
+
+    it('parses string-encoded JSON payloads', async () => {
+      const items = [{ id: 'a' }, { id: 'b' }];
+      const ds = mockDataSource({
+        find: vi.fn().mockResolvedValue({
+          data: [{ id: 1, payload: JSON.stringify(items) }],
+        }) as any,
+      });
+
+      const adapter = createObjectStackUserStateAdapter({
+        dataSource: ds,
+        userId: 'u',
+        kind: 'k',
+      });
+
+      await expect(adapter.load()).resolves.toEqual(items);
+    });
+
+    it('returns [] when payload is malformed JSON', async () => {
+      const ds = mockDataSource({
+        find: vi.fn().mockResolvedValue({
+          data: [{ id: 1, payload: '{not json' }],
+        }) as any,
+      });
+      const adapter = createObjectStackUserStateAdapter({
+        dataSource: ds,
+        userId: 'u',
+        kind: 'k',
+      });
+
+      await expect(adapter.load()).resolves.toEqual([]);
+    });
+
+    it('swallows errors and returns [] when find() throws', async () => {
+      const onError = vi.fn();
+      const ds = mockDataSource({
+        find: vi.fn().mockRejectedValue(new Error('boom')) as any,
+      });
+
+      const adapter = createObjectStackUserStateAdapter({
+        dataSource: ds,
+        userId: 'u',
+        kind: 'k',
+        onError,
+      });
+
+      await expect(adapter.load()).resolves.toEqual([]);
+      expect(onError).toHaveBeenCalledWith('load', expect.any(Error));
+    });
+
+    it('uses a custom resource name when provided', async () => {
+      const ds = mockDataSource();
+      const adapter = createObjectStackUserStateAdapter({
+        dataSource: ds,
+        userId: 'u',
+        kind: 'k',
+        resource: 'my_prefs',
+      });
+
+      await adapter.load();
+
+      expect(ds.find).toHaveBeenCalledWith('my_prefs', expect.any(Object));
+    });
+  });
+
+  describe('save', () => {
+    it('creates a new row when none exists', async () => {
+      const created = { id: 'new-row' };
+      const ds = mockDataSource({
+        create: vi.fn().mockResolvedValue(created) as any,
+      });
+
+      const adapter = createObjectStackUserStateAdapter({
+        dataSource: ds,
+        userId: 'u1',
+        kind: 'favorites',
+      });
+
+      await adapter.save([{ id: 'a' } as any]);
+
+      expect(ds.create).toHaveBeenCalledWith('user_app_state', {
+        user_id: 'u1',
+        kind: 'favorites',
+        payload: [{ id: 'a' }],
+        updated_at: expect.any(String),
+      });
+    });
+
+    it('updates the existing row when one exists', async () => {
+      const ds = mockDataSource({
+        find: vi.fn().mockResolvedValue({
+          data: [{ id: 'row-99', user_id: 'u', kind: 'k', payload: [] }],
+        }) as any,
+      });
+
+      const adapter = createObjectStackUserStateAdapter({
+        dataSource: ds,
+        userId: 'u',
+        kind: 'k',
+      });
+
+      await adapter.save([{ id: 'x' } as any]);
+
+      expect(ds.update).toHaveBeenCalledWith('user_app_state', 'row-99', {
+        payload: [{ id: 'x' }],
+        updated_at: expect.any(String),
+      });
+      expect(ds.create).not.toHaveBeenCalled();
+    });
+
+    it('uses the cached row id from a previous load on subsequent saves', async () => {
+      const ds = mockDataSource({
+        find: vi.fn().mockResolvedValue({
+          data: [{ id: 'row-42', payload: [] }],
+        }) as any,
+      });
+
+      const adapter = createObjectStackUserStateAdapter({
+        dataSource: ds,
+        userId: 'u',
+        kind: 'k',
+      });
+
+      await adapter.load();
+      (ds.find as any).mockClear();
+
+      await adapter.save([{ id: 'b' } as any]);
+
+      // No second find() — went straight to update via cached id.
+      expect(ds.find).not.toHaveBeenCalled();
+      expect(ds.update).toHaveBeenCalledWith('user_app_state', 'row-42', expect.any(Object));
+    });
+
+    it('falls back to insert when cached row update fails (row deleted server-side)', async () => {
+      const ds = mockDataSource({
+        find: vi.fn()
+          .mockResolvedValueOnce({ data: [{ id: 'stale', payload: [] }] })
+          .mockResolvedValueOnce({ data: [] }) as any,
+        update: vi.fn().mockRejectedValue(new Error('not found')) as any,
+        create: vi.fn().mockResolvedValue({ id: 'new' }) as any,
+      });
+      const onError = vi.fn();
+
+      const adapter = createObjectStackUserStateAdapter({
+        dataSource: ds,
+        userId: 'u',
+        kind: 'k',
+        onError,
+      });
+
+      await adapter.load(); // primes cachedRowId = 'stale'
+      await adapter.save([{ id: 'z' } as any]);
+
+      expect(ds.update).toHaveBeenCalledTimes(1);
+      expect(ds.create).toHaveBeenCalledWith('user_app_state', expect.objectContaining({
+        user_id: 'u',
+        kind: 'k',
+        payload: [{ id: 'z' }],
+      }));
+    });
+
+    it('swallows errors when save() throws', async () => {
+      const onError = vi.fn();
+      const ds = mockDataSource({
+        find: vi.fn().mockRejectedValue(new Error('network down')) as any,
+      });
+
+      const adapter = createObjectStackUserStateAdapter({
+        dataSource: ds,
+        userId: 'u',
+        kind: 'k',
+        onError,
+      });
+
+      await expect(adapter.save([{ id: 'a' } as any])).resolves.toBeUndefined();
+      expect(onError).toHaveBeenCalledWith('save', expect.any(Error));
+    });
+  });
+});

package/src/userState.ts

@@ -0,0 +1,179 @@
+/**
+ * ObjectStack-backed `UserDataAdapter` factory.
+ *
+ * Persists arbitrary per-user UI state (favorites, recently-accessed items, …)
+ * as a single JSON blob per `(user_id, kind)` row in an object named
+ * `user_app_state`. The single-blob approach keeps round-trips down (one
+ * `find` + one `update`/`create` per change) and matches the
+ * "save the full list" semantics of `FavoritesProvider` / `RecentItemsProvider`.
+ *
+ * ## Required object schema
+ *
+ * Configure an object in ObjectStack with at least the following fields:
+ *
+ * ```yaml
+ * object: user_app_state
+ * fields:
+ *   user_id:    string   # indexed
+ *   kind:       string   # indexed  (e.g. "favorites" | "recent")
+ *   payload:    json     # the serialised list
+ *   updated_at: datetime # (optional) auto-managed
+ * unique: [user_id, kind]
+ * ```
+ *
+ * ## Failure modes
+ *
+ * The adapter is designed to **degrade silently**. Any error — missing schema,
+ * 4xx/5xx, network — is caught:
+ *
+ * - `load()` returns `[]`, so the hosting provider keeps its localStorage state.
+ * - `save()` resolves without throwing, so UI mutations never surface a toast.
+ *
+ * This means an OSS user who hasn't yet provisioned the `user_app_state`
+ * object still gets a perfectly working (localStorage-only) favorites /
+ * recent-items experience. As soon as the object exists, persistence
+ * "lights up" with no code change.
+ *
+ * @module
+ */
+
+import type { DataSource, QueryParams } from '@object-ui/types';
+
+export interface ObjectStackUserStateAdapterOptions {
+  /** Connected data source (usually the one provided by `<AdapterProvider>`). */
+  dataSource: DataSource<any>;
+  /** Authenticated user id. */
+  userId: string;
+  /** Logical bucket key, e.g. `"favorites"` or `"recent"`. */
+  kind: string;
+  /** Override the storage object name. Defaults to `"user_app_state"`. */
+  resource?: string;
+  /**
+   * Optional console logger for development diagnostics. Defaults to noop so
+   * production builds stay quiet.
+   */
+  onError?: (where: 'load' | 'save', error: unknown) => void;
+}
+
+export interface UserDataAdapter<T> {
+  load(): Promise<T[]>;
+  save(items: T[]): Promise<void>;
+}
+
+interface UserStateRecord {
+  id?: string | number;
+  user_id: string;
+  kind: string;
+  payload: unknown;
+  updated_at?: string;
+}
+
+const DEFAULT_RESOURCE = 'user_app_state';
+
+/**
+ * Build a `UserDataAdapter<T>` backed by ObjectStack.
+ *
+ * Each adapter instance is bound to a single `(user, kind)` pair; create one
+ * per slot you want to persist.
+ */
+export function createObjectStackUserStateAdapter<T = unknown>(
+  options: ObjectStackUserStateAdapterOptions,
+): UserDataAdapter<T> {
+  const {
+    dataSource,
+    userId,
+    kind,
+    resource = DEFAULT_RESOURCE,
+    onError = () => {},
+  } = options;
+
+  // Cache the row id between load() and save() so we can update in place
+  // without re-querying. Reset on every successful load.
+  let cachedRowId: string | number | null = null;
+
+  const findExisting = async (): Promise<UserStateRecord | null> => {
+    const params: QueryParams = {
+      filter: {
+        user_id: userId,
+        kind,
+      },
+      limit: 1,
+    };
+    const result = await dataSource.find(resource, params);
+    const rows = (result?.data ?? []) as UserStateRecord[];
+    return rows.length > 0 ? rows[0] : null;
+  };
+
+  const decodePayload = (payload: unknown): T[] => {
+    // The server may return the JSON column already parsed, or as a string.
+    if (Array.isArray(payload)) return payload as T[];
+    if (typeof payload === 'string') {
+      try {
+        const parsed = JSON.parse(payload);
+        return Array.isArray(parsed) ? (parsed as T[]) : [];
+      } catch {
+        return [];
+      }
+    }
+    return [];
+  };
+
+  return {
+    async load(): Promise<T[]> {
+      try {
+        const row = await findExisting();
+        if (!row) {
+          cachedRowId = null;
+          return [];
+        }
+        if (row.id !== undefined && row.id !== null) cachedRowId = row.id;
+        return decodePayload(row.payload);
+      } catch (error) {
+        onError('load', error);
+        return [];
+      }
+    },
+
+    async save(items: T[]): Promise<void> {
+      try {
+        const now = new Date().toISOString();
+        // Fast path: we already know the row id from a previous load/save.
+        if (cachedRowId !== null) {
+          try {
+            await dataSource.update(resource, cachedRowId, {
+              payload: items,
+              updated_at: now,
+            });
+            return;
+          } catch (updateError) {
+            // Row may have been deleted server-side — fall through to insert.
+            cachedRowId = null;
+            onError('save', updateError);
+          }
+        }
+
+        const existing = await findExisting();
+        if (existing && existing.id !== undefined && existing.id !== null) {
+          cachedRowId = existing.id;
+          await dataSource.update(resource, existing.id, {
+            payload: items,
+            updated_at: now,
+          });
+          return;
+        }
+
+        const created = await dataSource.create(resource, {
+          user_id: userId,
+          kind,
+          payload: items,
+          updated_at: now,
+        });
+        const newId = (created as UserStateRecord | undefined)?.id;
+        if (newId !== undefined && newId !== null) cachedRowId = newId;
+      } catch (error) {
+        onError('save', error);
+        // Swallow — provider falls back to localStorage as source of truth.
+      }
+    },
+  };
+}