@equinor/fusion-framework-react-app 14.0.3 → 14.1.0

package/dist/types/ag-grid/community.d.ts

@@ -0,0 +1,11 @@
+/**
+ * AG Grid community-tier sub-path entry-point.
+ *
+ * @remarks
+ * Re-exports every public symbol from
+ * `@equinor/fusion-framework-react-ag-grid/community` so the application
+ * resolves a single shared copy of `ag-grid-community`.
+ *
+ * @packageDocumentation
+ */
+export * from '@equinor/fusion-framework-react-ag-grid/community';

package/dist/types/ag-grid/enterprise.d.ts

@@ -0,0 +1,11 @@
+/**
+ * AG Grid enterprise-tier sub-path entry-point.
+ *
+ * @remarks
+ * Re-exports every public symbol from
+ * `@equinor/fusion-framework-react-ag-grid/enterprise` so the application
+ * resolves a single shared copy of `ag-grid-enterprise`.
+ *
+ * @packageDocumentation
+ */
+export * from '@equinor/fusion-framework-react-ag-grid/enterprise';

package/dist/types/ag-grid/react.d.ts

@@ -0,0 +1,11 @@
+/**
+ * AG Grid React component sub-path entry-point.
+ *
+ * @remarks
+ * Re-exports the AG Grid React bindings from
+ * `@equinor/fusion-framework-react-ag-grid/react`, including the
+ * `AgGridReact` component, `enableAgGrid`, and their associated types.
+ *
+ * @packageDocumentation
+ */
+export * from '@equinor/fusion-framework-react-ag-grid/react';

package/dist/types/ag-grid/testing.d.ts

@@ -0,0 +1,18 @@
+/**
+ * AG Grid test helpers sub-path entry-point.
+ *
+ * @remarks
+ * Re-exports the AG Grid test helpers from
+ * `@equinor/fusion-framework-module-ag-grid/testing`. Import from test setup
+ * files only — these helpers patch global state and are not meant for
+ * application runtime code.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Silences AG Grid Enterprise's unlicensed "License Key Not Found" banner on
+ * `console.error` so it doesn't bury real failures in test output.
+ *
+ * @returns A function that restores the original `console.error`.
+ */
+export { suppressAgGridLicenseBanner } from '@equinor/fusion-framework-module-ag-grid/testing';

package/dist/types/ag-grid/theme.d.ts

@@ -0,0 +1,13 @@
+/**
+ * AG Grid theme sub-path entry-point.
+ *
+ * @remarks
+ * Re-exports the Fusion AG Grid theme utilities from
+ * `@equinor/fusion-framework-module-ag-grid/themes`, together with the
+ * application-scoped {@link useTheme} hook.
+ *
+ * @packageDocumentation
+ */
+export { fusionTheme, createThemeFromTheme, createTheme, } from '@equinor/fusion-framework-module-ag-grid/themes';
+export type { Theme } from '@equinor/fusion-framework-module-ag-grid/themes';
+export { useTheme } from './useTheme';

package/dist/types/create-component.d.ts

@@ -27,7 +27,7 @@ export type ComponentRenderer<TFusion extends Fusion = Fusion, TEnv = AppEnv> =
  * @example
  * ```tsx
  * const configCallback: AppConfigurator = (configurator) => {
- *  configurator.http.configureClient(
+ *  configurator.configureHttpClient(
  *     'bar', {
  *       baseUri: 'https://somewhere-test.com',
  *       defaultScopes: ['foo/.default']

package/dist/types/version.d.ts

@@ -1 +1 @@
-export declare const version = "14.0.3";
+export declare const version = "14.1.0";

package/docs/bookmark.md

@@ -78,6 +78,13 @@ const MyApp = () => {
 };
 ```
 
+> [!WARNING]
+> If your app has **not** called `enableBookmark`, `useCurrentBookmark` falls back to the
+> portal's framework-scoped bookmark provider and logs a `@deprecation` console warning
+> (`"application has not enabled bookmarks, this will not work in the future"`). This
+> fallback is deprecated and will be removed — always call `enableBookmark` in apps that
+> use bookmarks.
+
 ## useBookmark (Deprecated)
 
 > [!CAUTION]

package/docs/context.md

@@ -29,12 +29,14 @@ Returns the currently selected context from the application-scoped context modul
 ```ts
 function useCurrentContext(): {
   currentContext: ContextItem | null | undefined;
-  setCurrentContext: (context?: ContextItem | string | null) => void;
+  setCurrentContext: (context?: ContextItem | string | null) => void | Promise<ContextItem | null>;
 };
 ```
 
 **Returns:** An object with the current context (`ContextItem | null | undefined`) and a setter to change it.
 
+`setCurrentContext` clears the context when called with no argument (or `null`), resolves an item by `id` when given a `string`, or sets the given `ContextItem` directly. Clearing returns `void`; setting by `id` or by item returns a `Promise` that resolves once the switch completes — `await` it when you need to know the new context has taken effect (e.g. before navigating).
+
 ### Example
 
 ```tsx

package/docs/framework.md

@@ -31,11 +31,11 @@ Use this when your app hasn't configured its own context module but still needs
 ```ts
 function useFrameworkCurrentContext(): {
   currentContext: ContextItem | undefined;
-  setCurrentContext: (entry?: ContextItem | string | null) => void;
+  setCurrentContext: (entry?: ContextItem | string | null) => void | Promise<ContextItem | null>;
 };
 ```
 
-**Returns:** An object with `currentContext` (the portal's active context, or `undefined` if none is selected) and `setCurrentContext` to change it.
+**Returns:** An object with `currentContext` (the portal's active context, or `undefined` if none is selected) and `setCurrentContext` to change it. Clearing (no argument or `null`) returns `void`; setting by `id` or by item returns a `Promise` that resolves once the switch completes.
 
 **Example:**
 

package/docs/msal.md

@@ -116,7 +116,7 @@ const TokenInfo = () => {
   return (
     <div>
       <p>Access Token: {token.accessToken.substring(0, 20)}...</p>
-      <p>Expires: {new Date(token.expiresOn).toLocaleString()}</p>
+      <p>Expires: {token.expiresOn?.toLocaleString() ?? 'unknown'}</p>
       <p>Token Type: {token.tokenType}</p>
       <p>Scope: {token.scopes.join(', ')}</p>
     </div>
@@ -134,8 +134,8 @@ const TokenInfo = () => {
 
 **Note:** The `AuthenticationResult` type includes:
 - `accessToken: string`
-- `account: AccountInfo`
-- `expiresOn: Date`
+- `account: AccountInfo | null`
+- `expiresOn: Date | null`
 - `tokenType: string`
 - `scopes: string[]`
 - And more...

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@equinor/fusion-framework-react-app",
-  "version": "14.0.3",
+  "version": "14.1.0",
   "description": "",
+  "type": "module",
   "main": "./dist/esm/index.js",
   "types": "./dist/types/index.d.ts",
   "exports": {
@@ -68,6 +69,26 @@
     "./routing": {
       "types": "./dist/types/routing/index.d.ts",
       "import": "./dist/esm/routing/index.js"
+    },
+    "./ag-grid": {
+      "types": "./dist/types/ag-grid/react.d.ts",
+      "import": "./dist/esm/ag-grid/react.js"
+    },
+    "./ag-grid/community": {
+      "types": "./dist/types/ag-grid/community.d.ts",
+      "import": "./dist/esm/ag-grid/community.js"
+    },
+    "./ag-grid/enterprise": {
+      "types": "./dist/types/ag-grid/enterprise.d.ts",
+      "import": "./dist/esm/ag-grid/enterprise.js"
+    },
+    "./ag-grid/theme": {
+      "types": "./dist/types/ag-grid/theme.d.ts",
+      "import": "./dist/esm/ag-grid/theme.js"
+    },
+    "./ag-grid/testing": {
+      "types": "./dist/types/ag-grid/testing.d.ts",
+      "import": "./dist/esm/ag-grid/testing.js"
     }
   },
   "typesVersions": {
@@ -116,6 +137,21 @@
       ],
       "routing": [
         "dist/types/routing/index.d.ts"
+      ],
+      "ag-grid": [
+        "dist/types/ag-grid/react.d.ts"
+      ],
+      "ag-grid/community": [
+        "dist/types/ag-grid/community.d.ts"
+      ],
+      "ag-grid/enterprise": [
+        "dist/types/ag-grid/enterprise.d.ts"
+      ],
+      "ag-grid/theme": [
+        "dist/types/ag-grid/theme.d.ts"
+      ],
+      "ag-grid/testing": [
+        "dist/types/ag-grid/testing.d.ts"
       ]
     }
   },
@@ -131,46 +167,62 @@
     "directory": "packages/react"
   },
   "dependencies": {
-    "@equinor/fusion-framework-app": "13.0.3",
-    "@equinor/fusion-framework-module": "6.1.2",
-    "@equinor/fusion-framework-module-http": "8.0.5",
-    "@equinor/fusion-framework-module-app": "8.0.5",
-    "@equinor/fusion-framework-module-navigation": "7.0.8",
-    "@equinor/fusion-framework-react": "8.0.1",
-    "@equinor/fusion-framework-react-module": "4.0.2",
-    "@equinor/fusion-framework-react-module-http": "11.0.1"
+    "@equinor/fusion-framework-app": "13.1.0",
+    "@equinor/fusion-framework": "8.1.0",
+    "@equinor/fusion-framework-module": "6.1.3",
+    "@equinor/fusion-framework-module-app": "8.1.0",
+    "@equinor/fusion-framework-react-module": "4.0.3",
+    "@equinor/fusion-framework-react": "9.0.0",
+    "@equinor/fusion-framework-module-navigation": "7.0.9",
+    "@equinor/fusion-framework-module-http": "8.1.0",
+    "@equinor/fusion-framework-react-module-http": "12.0.0"
   },
   "devDependencies": {
-    "@testing-library/react": "^16.0.0",
+    "@remix-run/router": "^1.23.3",
     "@types/react": "^19.2.7",
     "@types/react-dom": "^19.2.3",
-    "happy-dom": "^20.8.4",
+    "@vitest/browser-playwright": "^4.1.0",
+    "playwright": "^1.62.1",
     "react": "^19.2.1",
     "react-dom": "^19.2.1",
     "rxjs": "^7.8.1",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.0",
-    "@equinor/fusion-framework-module-event": "6.0.1",
-    "@equinor/fusion-framework-module-analytics": "3.0.8",
-    "@equinor/fusion-framework-module-ag-grid": "37.0.2",
-    "@equinor/fusion-framework-module-msal": "10.0.2",
-    "@equinor/fusion-framework-module-feature-flag": "2.0.3",
-    "@equinor/fusion-framework-react-module-bookmark": "6.0.1",
-    "@equinor/fusion-framework-module-state": "^2.0.1",
-    "@equinor/fusion-framework-react-module-context": "7.0.2",
-    "@equinor/fusion-framework-react-router": "2.4.0",
-    "@equinor/fusion-observable": "9.2.0"
+    "vitest": "^4.1.10",
+    "vitest-browser-react": "^2.2.0",
+    "@equinor/fusion-framework-react-ag-grid": "37.1.0",
+    "@equinor/fusion-framework-module-ag-grid": "37.1.0",
+    "@equinor/fusion-framework-module-context": "9.0.0",
+    "@equinor/fusion-framework-module-event": "6.1.0",
+    "@equinor/fusion-framework-module-analytics": "3.1.0",
+    "@equinor/fusion-framework-module-bookmark": "4.1.0",
+    "@equinor/fusion-framework-module-feature-flag": "2.1.0",
+    "@equinor/fusion-framework-module-msal": "11.0.0",
+    "@equinor/fusion-framework-module-state": "^2.0.2",
+    "@equinor/fusion-framework-module-telemetry": "7.1.0",
+    "@equinor/fusion-framework-react-module-bookmark": "7.0.0",
+    "@equinor/fusion-framework-react-module-context": "7.0.3",
+    "@equinor/fusion-framework-react-router": "2.4.1",
+    "@equinor/fusion-framework-vitest-plugin-react-app": "1.0.0",
+    "@equinor/fusion-observable": "9.2.1"
   },
   "peerDependencies": {
     "@types/react": "^18.0.0 || ^19.0.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
     "rxjs": "^7.0.0",
-    "@equinor/fusion-framework-module-msal": "^10.0.2",
-    "@equinor/fusion-framework-react-router": "^2.4.0",
-    "@equinor/fusion-framework-module-state": "^2.0.1"
+    "@equinor/fusion-framework-react-ag-grid": "^37.1.0",
+    "@equinor/fusion-framework-module-state": "^2.0.2",
+    "@equinor/fusion-framework-module-ag-grid": "^37.1.0",
+    "@equinor/fusion-framework-react-router": "^2.4.1",
+    "@equinor/fusion-framework-module-msal": "^11.0.0"
   },
   "peerDependenciesMeta": {
+    "@equinor/fusion-framework-module-ag-grid": {
+      "optional": true
+    },
+    "@equinor/fusion-framework-react-ag-grid": {
+      "optional": true
+    },
     "@equinor/fusion-framework-react-module-ag-grid": {
       "optional": true
     },

package/src/__tests__/Apploader.test.tsx

@@ -0,0 +1,51 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { mockFramework } from '@equinor/fusion-framework/mock';
+import { enableAppManifestMock } from '@equinor/fusion-framework-app/mock';
+import type { AppManifest, AppModule } from '@equinor/fusion-framework-module-app';
+
+import { Apploader } from '../apploader/Apploader';
+import { renderAppComponent } from '@equinor/fusion-framework-vitest-plugin-react-app/test';
+
+// resolved from this test file rather than hardcoded, so it survives a package move
+const fixturesUri = new URL('./fixtures', import.meta.url).pathname;
+
+describe('Apploader', () => {
+  it('mounts the child app’s rendered content once its script loads', async () => {
+    const manifest: AppManifest = {
+      appKey: 'child-app',
+      displayName: 'Child App',
+      description: 'A child application',
+      type: 'standalone',
+      build: { version: '1.0.0', entryPoint: 'apploader-child-script.ts', assetPath: '' },
+    };
+
+    const fusion = await mockFramework<[AppModule]>((configurator) =>
+      enableAppManifestMock(configurator, { manifest }, fixturesUri),
+    );
+
+    const { container } = await renderAppComponent(<Apploader appKey="child-app" />, { fusion });
+
+    // the loading state renders synchronously, before the script's dynamic import resolves
+    expect(container.textContent).toContain('Loading child-app');
+    await vi.waitFor(() => expect(container.textContent).toContain('mounted: child-app'));
+  });
+
+  it('surfaces the load error instead of throwing when the app’s script fails to import', async () => {
+    const manifest: AppManifest = {
+      appKey: 'broken-app',
+      displayName: 'Broken App',
+      description: 'An application whose build entry point does not exist',
+      type: 'standalone',
+      build: { version: '1.0.0', entryPoint: 'does-not-exist.ts', assetPath: '' },
+    };
+
+    const fusion = await mockFramework<[AppModule]>((configurator) =>
+      enableAppManifestMock(configurator, { manifest }, fixturesUri),
+    );
+
+    const { container } = await renderAppComponent(<Apploader appKey="broken-app" />, { fusion });
+
+    await vi.waitFor(() => expect(container.textContent).toContain('Error loading broken-app'));
+  });
+});

package/src/__tests__/fixtures/apploader-child-script.ts

@@ -0,0 +1,9 @@
+import type { AppScriptModule } from '@equinor/fusion-framework-module-app';
+
+// a minimal stand-in for a real app bundle's entry point, dynamically imported by `App.initialize()`
+export const renderApp: AppScriptModule['renderApp'] = (el, { env }) => {
+  el.textContent = `mounted: ${env.manifest?.appKey}`;
+  return () => {
+    el.textContent = '';
+  };
+};

package/src/__tests__/testApp.test.tsx

@@ -0,0 +1,76 @@
+import { describe, expect } from 'vitest';
+
+import { enableContextMock } from '@equinor/fusion-framework-module-context/mock';
+import type { ContextItem } from '@equinor/fusion-framework-module-context';
+import { useCurrentContext } from '@equinor/fusion-framework-react-app/context';
+import { useFramework } from '@equinor/fusion-framework-react';
+import { createHistory, enableNavigation } from '@equinor/fusion-framework-module-navigation';
+import type { NavigationModule } from '@equinor/fusion-framework-module-navigation';
+
+import { testApp } from '@equinor/fusion-framework-vitest-plugin-react-app/test';
+
+const projectA: ContextItem = {
+  id: 'ctx-a',
+  title: 'Project A',
+  type: { id: 'ProjectMaster' },
+  value: {},
+};
+
+const Greeting = () => <p>hello</p>;
+
+const CurrentContext = () => {
+  const { currentContext } = useCurrentContext();
+  return <p>{currentContext?.title ?? 'none'}</p>;
+};
+
+describe('testApp', () => {
+  testApp(
+    'resolves a fusion/app scope and renders through the public /vitest entry point',
+    async ({ render, fusion, app }) => {
+      const screen = await render(<Greeting />);
+      await expect.element(screen.getByText('hello')).toBeVisible();
+      expect(fusion).toBeDefined();
+      expect(app).toBeDefined();
+    },
+  );
+
+  describe('with a seeded context module', () => {
+    const test = testApp.extend(
+      'configureApp',
+      { injected: true },
+      () => (configurator) =>
+        enableContextMock(configurator, (mock) => mock.setCurrentContext(projectA)),
+    );
+
+    test('starts on the seeded context', async ({ render }) => {
+      const screen = await render(<CurrentContext />);
+      await expect.element(screen.getByText(projectA.title as string)).toBeVisible();
+    });
+  });
+
+  describe('with a configured parent framework', () => {
+    const NavigationLocation = () => {
+      const { navigation } = useFramework<[NavigationModule]>().modules;
+      return <p>{navigation.history.location.pathname}</p>;
+    };
+
+    // pushed on the history instance itself, before it's handed to the framework configurator,
+    // so a passing assertion also proves `configureFusion` ran ahead of framework initialization
+    const history = createHistory('memory');
+    history.push('/configured-by-configure-fusion');
+
+    const test = testApp.extend(
+      'configureFusion',
+      { injected: true },
+      () => (configurator) =>
+        enableNavigation(configurator, { configure: (config) => config.setHistory(history) }),
+    );
+
+    test('resolves the fusion instance with the configured navigation history', async ({
+      render,
+    }) => {
+      const screen = await render(<NavigationLocation />);
+      await expect.element(screen.getByText('/configured-by-configure-fusion')).toBeVisible();
+    });
+  });
+});

package/src/__tests__/useAccessToken.test.tsx

@@ -0,0 +1,51 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { mockFramework } from '@equinor/fusion-framework/mock';
+
+import { useAccessToken } from '../msal/useAccessToken';
+import { renderAppHook } from '@equinor/fusion-framework-vitest-plugin-react-app/test';
+
+describe('useAccessToken', () => {
+  it('resolves an access token from the app scope’s real, mock-backed auth module', async () => {
+    // `renderAppHook` runs the real msal module against an in-process mock client,
+    // so `auth` behaves exactly as it would with a signed-in user in production.
+    const { result, unmount } = await renderAppHook(() =>
+      useAccessToken({ scopes: ['User.Read'] }),
+    );
+
+    // `renderAppHook` awaits the render, and the mock resolves near-instantly,
+    // so the pending state may have already settled by the time we can observe it
+    await vi.waitFor(() => expect(result.current.pending).toBe(false));
+
+    expect(result.current.error).toBeNull();
+    // a structurally valid JWT has three dot-separated segments
+    expect(result.current.token?.split('.')).toHaveLength(3);
+
+    // unmount before the next test's environment tears down, so no acquisition
+    // effect can flush a state update against an already-destroyed `window`
+    await unmount();
+  });
+
+  it('surfaces an acquisition error instead of throwing', async () => {
+    const fusion = await mockFramework();
+    // persistent, not `-Once`: the app module hoists via a version-compat proxy that
+    // may call through before the hook's own effect does, consuming a one-shot mock
+    vi.spyOn(fusion.modules.auth, 'acquireToken').mockRejectedValue(
+      new Error('acquisition failed'),
+    );
+
+    const { result, unmount } = await renderAppHook(
+      () => useAccessToken({ scopes: ['User.Read'] }),
+      {
+        fusion,
+      },
+    );
+
+    await vi.waitFor(() => expect(result.current.pending).toBe(false));
+
+    expect(result.current.token).toBeUndefined();
+    expect(result.current.error).toBeInstanceOf(Error);
+
+    await unmount();
+  });
+});

package/src/__tests__/useAppSetting.test.tsx

@@ -0,0 +1,133 @@
+import { act } from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { mockFramework } from '@equinor/fusion-framework/mock';
+import { enableAppManifestMock } from '@equinor/fusion-framework-app/mock';
+import type { AppModule } from '@equinor/fusion-framework-module-app';
+import { createRouterMiddleware } from '@equinor/fusion-framework-module-http/mock';
+
+import { useAppSetting } from '../settings/useAppSetting';
+import { renderAppHook } from '@equinor/fusion-framework-vitest-plugin-react-app/test';
+
+const env = {
+  manifest: {
+    appKey: 'test-app',
+    displayName: 'Test App',
+    description: 'A test application',
+    type: 'standalone' as const,
+  },
+};
+
+/**
+ * Boots a parent framework whose `apps` client serves per-user settings from an
+ * in-memory store, so `useAppSetting` exercises the real fetch/update round-trip
+ * instead of a stubbed provider.
+ *
+ * @param initial - The settings the store starts seeded with.
+ * @param putResponse - Overrides the response a PUT request resolves to, to simulate a failed update.
+ */
+const mockSettingsFusion = async (
+  initial: Record<string, unknown> = {},
+  putResponse?: () => Response,
+) => {
+  const store: Record<string, unknown> = { ...initial };
+  const fusion = await mockFramework<[AppModule]>((configurator) => {
+    configurator.http.addMiddleware(
+      createRouterMiddleware('https://apps.fusion.test', (router) => {
+        router.get('/persons/me/apps/:appKey/settings', () => Response.json(store));
+        router.put('/persons/me/apps/:appKey/settings', async ({ request }) => {
+          // a caller-supplied response simulates a failed persistence request
+          if (putResponse) return putResponse();
+          // the PUT body replaces the seeded keys it targets, leaving the rest of the store untouched
+          Object.assign(store, await request.json());
+          return Response.json(store);
+        });
+      }),
+    );
+    enableAppManifestMock(configurator, env);
+  });
+  fusion.modules.app.setCurrentApp(env.manifest.appKey);
+  return fusion;
+};
+
+describe('useAppSetting', () => {
+  it('resolves the persisted value for a single setting key', async () => {
+    const fusion = await mockSettingsFusion({ theme: 'dark' });
+
+    const { result } = await renderAppHook(
+      () => useAppSetting<{ theme: string }, 'theme'>('theme'),
+      { env, fusion },
+    );
+
+    await vi.waitFor(() => expect(result.current[0]).toBe('dark'));
+  });
+
+  it('falls back to the default value until the persisted settings resolve', async () => {
+    const fusion = await mockSettingsFusion({ theme: 'dark' });
+
+    const { result } = await renderAppHook(
+      () => useAppSetting<{ theme: string }, 'theme'>('theme', 'light'),
+      { env, fusion },
+    );
+
+    expect(result.current[0]).toBe('light');
+    await vi.waitFor(() => expect(result.current[0]).toBe('dark'));
+  });
+
+  it('persists an updated value and notifies onUpdated', async () => {
+    const fusion = await mockSettingsFusion({ theme: 'dark' });
+    const onUpdated = vi.fn();
+
+    const { result } = await renderAppHook(
+      () => useAppSetting<{ theme: string }, 'theme'>('theme', undefined, { onUpdated }),
+      { env, fusion },
+    );
+
+    await vi.waitFor(() => expect(result.current[0]).toBe('dark'));
+
+    act(() => {
+      result.current[1]('light');
+    });
+
+    await vi.waitFor(() => expect(result.current[0]).toBe('light'));
+    await vi.waitFor(() => expect(onUpdated).toHaveBeenCalled());
+  });
+
+  it('resolves the next value from the previous one when given an updater function', async () => {
+    const fusion = await mockSettingsFusion({ count: 1 });
+
+    const { result } = await renderAppHook(
+      () => useAppSetting<{ count: number }, 'count'>('count'),
+      { env, fusion },
+    );
+
+    await vi.waitFor(() => expect(result.current[0]).toBe(1));
+
+    act(() => {
+      result.current[1]((current) => (current ?? 0) + 1);
+    });
+
+    await vi.waitFor(() => expect(result.current[0]).toBe(2));
+  });
+
+  it('surfaces a persistence failure through onError instead of throwing', async () => {
+    const fusion = await mockSettingsFusion(
+      { theme: 'dark' },
+      () => new Response(null, { status: 500 }),
+    );
+    const onError = vi.fn();
+
+    const { result } = await renderAppHook(
+      () => useAppSetting<{ theme: string }, 'theme'>('theme', undefined, { onError }),
+      { env, fusion },
+    );
+
+    await vi.waitFor(() => expect(result.current[0]).toBe('dark'));
+
+    act(() => {
+      result.current[1]('light');
+    });
+
+    await vi.waitFor(() => expect(onError).toHaveBeenCalledWith(expect.any(Error)));
+  });
+});