@equinor/fusion-framework-module-bookmark 3.0.6 → 4.0.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Change Log
 
+## 4.0.0
+
+### Major Changes
+
+- abffa53: Major version bump for Fusion Framework React 19 release.
+
+  All packages are bumped to the next major version as part of the React 19 upgrade. This release drops support for React versions below 18 and includes breaking changes across the framework.
+
+  **Breaking changes:**
+  - Peer dependencies now require React 18 or 19 (`^18.0.0 || ^19.0.0`)
+  - React Router upgraded from v6 to v7
+  - Navigation module refactored with new history API
+  - `renderComponent` and `renderApp` now use `createRoot` API
+
+  **Migration:**
+  - Update your React version to 18.0.0 or higher before upgrading
+  - Replace `NavigationProvider.createRouter()` with `@equinor/fusion-framework-react-router`
+  - See individual package changelogs for package-specific migration steps
+
+### Patch Changes
+
+- Updated dependencies [abffa53]
+- Updated dependencies [abffa53]
+- Updated dependencies [abffa53]
+- Updated dependencies [abffa53]
+  - @equinor/fusion-framework-module@6.0.0
+  - @equinor/fusion-log@2.0.0
+  - @equinor/fusion-observable@9.0.0
+  - @equinor/fusion-query@7.0.0
+
 ## 3.0.6
 
 ### Patch Changes
@@ -57,7 +87,6 @@
 ### Patch Changes
 
 - [#3428](https://github.com/equinor/fusion-framework/pull/3428) [`1700ca8`](https://github.com/equinor/fusion-framework/commit/1700ca8851fa108e55e9729fd24f595272766e63) Thanks [@dependabot](https://github.com/apps/dependabot)! - Update zod from 4.1.9 to 4.1.11
-
   - **v4.1.10**: Fixed shape caching issue (#5263) improving validation performance for complex schemas
   - **v4.1.11**: Maintenance release with general improvements
 
@@ -77,7 +106,6 @@
   Updated source code to migrate from zod v3 to v4. Updated zod dependency from v3.25.76 to v4.1.8 and modified schema definitions in the bookmark module to use explicit key and value types for records, simplified function schema definitions, and replaced zod-inferred types with explicit TypeScript interfaces.
 
   Key changes in source code:
-
   - Fixed record schema definitions to use explicit key and value types (`z.record(z.string(), z.unknown())`)
   - Simplified function schema definitions by removing complex chaining (`.args()` and `.returns()`)
   - Replaced zod-inferred types with explicit TypeScript interfaces for better performance
@@ -87,7 +115,6 @@
   Breaking changes: Record schemas must specify both key and value types explicitly. Function schema definitions now require explicit typing.
 
   Links:
-
   - [Zod v4 Migration Guide](https://github.com/colinhacks/zod/releases/tag/v4.0.0)
   - [Zod v4.1.8 Release Notes](https://github.com/colinhacks/zod/releases/tag/v4.1.8)
 
@@ -98,19 +125,16 @@
 - [#3395](https://github.com/equinor/fusion-framework/pull/3395) [`29f6710`](https://github.com/equinor/fusion-framework/commit/29f6710238baf9b29f42394b30cb8b97f25462c3) Thanks [@odinr](https://github.com/odinr)! - Updated immer from 9.0.16 to 10.1.3 across all packages.
 
   ### Breaking Changes
-
   - Immer 10.x introduces stricter TypeScript types for draft functions
   - `ValidRecipeReturnType` type constraints have changed
   - Promise return types in draft functions are no longer automatically handled
 
   ### Fixes Applied
-
   - Updated BookmarkProvider to handle new immer type constraints
   - Fixed ObservableInput type assignments in mergeScan operations
   - Removed async/await from immer draft functions to comply with new type requirements
 
   ### Links
-
   - [Immer 10.0.0 Release Notes](https://github.com/immerjs/immer/releases/tag/v10.0.0)
   - [Immer Migration Guide](https://github.com/immerjs/immer/blob/main/MIGRATION.md)
 
@@ -119,32 +143,27 @@
   Updated TypeScript type definitions for UUID operations across multiple packages. This major version update provides improved type safety and compatibility with the latest UUID library features.
 
   ### Affected Packages
-
   - @equinor/fusion-framework-module-bookmark: @types/uuid ^9.0.8 → ^11.0.0
   - @equinor/fusion-framework-module-feature-flag: @types/uuid ^10.0.0 → ^11.0.0
   - @equinor/fusion-observable: @types/uuid ^10.0.0 → ^11.0.0
   - @equinor/fusion-query: @types/uuid ^10.0.0 → ^11.0.0
 
   ### Links
-
   - [@types/uuid on npm](https://www.npmjs.com/package/@types/uuid)
   - [DefinitelyTyped @types/uuid](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/uuid)
 
 - [#3347](https://github.com/equinor/fusion-framework/pull/3347) [`11143fa`](https://github.com/equinor/fusion-framework/commit/11143fa3002fb8a6c095052a04c7e596c56bafa8) Thanks [@dependabot](https://github.com/apps/dependabot)! - chore: bump uuid from 11.0.3 to 13.0.0
 
   ### Breaking Changes
-
   - v13.0.0: Make browser exports the default
   - v12.0.0: Update to TypeScript 5.2, remove CommonJS support, drop Node 16 support
 
   ### New Features
-
   - Improved v4() performance
   - Added Node 24 to CI matrix
   - Restored node: prefix support
 
   ### Links
-
   - [GitHub releases](https://github.com/uuidjs/uuid/releases/tag/v13.0.0)
   - [npm changelog](https://www.npmjs.com/package/uuid?activeTab=versions)
 
@@ -159,14 +178,12 @@
 - [#3075](https://github.com/equinor/fusion-framework/pull/3075) [`8fffbfb`](https://github.com/equinor/fusion-framework/commit/8fffbfb12daa9748bf5290e5084cd4d409aed253) Thanks [@odinr](https://github.com/odinr)! - Refactored the `Bookmark` type to be an intersection of `BookmarkWithoutData` and an optional `payload` property, improving type safety and flexibility. Updated `useBookmarkNavigate` to use proper TypeScript typing for bookmark events.
 
   **Module Bookmark Changes:**
-
   - Refactored `Bookmark` type in `packages/modules/bookmark/src/types.ts`
   - Added export for `BookmarkProviderEvents` type in `packages/modules/bookmark/src/index.ts`
   - Updated JSDoc comment from `@note` to `@remarks` in `packages/modules/bookmark/src/BookmarkClient.ts`
   - Reordered tsconfig references (event before services)
 
   **React Changes:**
-
   - Updated `packages/react/modules/bookmark/src/portal/useBookmarkNavigate.ts` to use proper TypeScript typing for bookmark provider events
   - Removed React paths configuration from `packages/react/app/tsconfig.json`
 
@@ -201,7 +218,6 @@
 ### Patch Changes
 
 - [#3088](https://github.com/equinor/fusion-framework/pull/3088) [`7441b13`](https://github.com/equinor/fusion-framework/commit/7441b13aa50dd7362d1629086a27b6b4e571575d) Thanks [@eikeland](https://github.com/eikeland)! - chore: update package typesVersions
-
   - Updated package.json typesVersions.
   - Ensures backward compatibility with older node versions.
   - Ensured consistency with workspace and repository configuration.
@@ -355,7 +371,6 @@
   The new implementation has better state management and error handling, and should be easier to work with than the v1 implementation.
 
   **Highlights:**
-
   - has validation of configuration of the module.
   - uses the `BaseConfigBuilder` pattern for configuration.
   - has validation of requests and responses using zod schemas.
@@ -367,12 +382,10 @@
   - has better logging.
 
   **Migration:**
-
   - update config for enabling the module
   - check all direct access to provider interface if they are still valid
 
   **Breaking changes:**
-
   - The provider interface has changed
   - The client interface has changed
   - The configuration interface has changed
@@ -426,7 +439,6 @@
 - [#2320](https://github.com/equinor/fusion-framework/pull/2320) [`1dd85f3`](https://github.com/equinor/fusion-framework/commit/1dd85f3a408a73df556d1812a5f280945cc100ee) Thanks [@odinr](https://github.com/odinr)! - Removed the `removeComments` option from the `tsconfig.base.json` file.
 
   Removing the `removeComments` option allows TypeScript to preserve comments in the compiled JavaScript output. This can be beneficial for several reasons:
-
   1. Improved debugging: Preserved comments can help developers understand the code better during debugging sessions.
   2. Documentation: JSDoc comments and other important code documentation will be retained in the compiled output.
   3. Source map accuracy: Keeping comments can lead to more accurate source maps, which is crucial for debugging and error tracking.

package/README.md

@@ -1,341 +1,242 @@
 # Bookmark Module
 
-The Bookmark module provides a way to manage bookmarks in the application. It allows users to create, update, and remove bookmarks, as well as manage the current bookmark and the list of bookmarks.
+`@equinor/fusion-framework-module-bookmark` provides bookmark management for Fusion Framework applications. It lets users **create, update, delete, and favourite bookmarks**, track a **current (active) bookmark**, and react to bookmark lifecycle events.
 
-## Features
+Under the hood the module uses an RxJS-based state store with side-effect flows, an API client backed by `@equinor/fusion-framework-module-services`, and an event system powered by `@equinor/fusion-framework-module-event`.
 
-- **Create, update, and delete bookmarks**
-- **Manage current bookmark**
-- **Add and remove bookmarks from favorites**
-- **Event listeners for bookmark-related events**
+## Key Concepts
 
-## Setup
+| Concept | Description |
+| --- | --- |
+| **BookmarkProvider** | Runtime service exposed after the module initialises. All CRUD, favourites, and current-bookmark operations go through this class. |
+| **BookmarkModuleConfigurator** | Builder used during the configure phase to set the source system, filters, resolvers, and custom client. |
+| **Payload Generator** | Callback registered via `addPayloadGenerator` that participates in building the bookmark payload during create and update. The callback receives an Immer draft — mutate in place. |
+| **Source System** | Identifies which system owns the bookmarks (used for filtering and creation). |
+| **Filters** | Optional flags (`application`, `context`) that restrict bookmark queries to the current app and/or context. |
+
+## Installation
 
 ```bash
-pnpm install @equinor/fusion-framework-module-bookmark
+pnpm add @equinor/fusion-framework-module-bookmark
 ```
 
+## Quick Start
+
+The simplest setup — no custom configuration, inherits everything from the parent (e.g. the portal framework):
+
 ```ts
-import { enableBookmarkModule } from ' @equinor/fusion-framework-module-bookmark'
+import { enableBookmark } from '@equinor/fusion-framework-module-bookmark';
+
 const configure = (configurator) => {
-  // simplest setup
-  enableBookmarkModule(configurator);
-}
+  enableBookmark(configurator);
+};
 ```
 
 ## Configuration
+
+Use the callback form of `enableBookmark` to customise behaviour:
+
 ```ts
-/** example of configuration */
-enableBookmarkModule(configurator, async(builder) => {
-    /** Set source system of bookmark, note used for queries and creation */
+import { enableBookmark } from '@equinor/fusion-framework-module-bookmark';
+
+const configure = (configurator) => {
+  enableBookmark(configurator, (builder) => {
+    // Tag bookmarks with their originating system
     builder.setSourceSystem({
-        id: 'source-system-id',
-        name: 'Source System Name',
+      identifier: 'my-app-id',
+      name: 'My Application',
     });
 
-    /** apply filters for current application */
+    // Only return bookmarks for the current application
     builder.setFilter('application', true);
 
-    /** apply filters for current context */
+    // Only return bookmarks for the current context
     builder.setFilter('context', true);
+  });
+};
+```
 
-    /** === Advance Configuration === */
-
-    /** override default implementations */
-    builder.setClient(/** custom client implementation */)
-    builder.setParent(/** custom parent implementation */)
+### Advanced Configuration
 
-    /** override default resolvers */
-    builder.setContextResolver(/** custom context resolver implementation */)
-    builder.setApplicationResolver(/** custom application resolver implementation */)
+```ts
+enableBookmark(configurator, (builder) => {
+  // Provide a custom API client (must implement IBookmarkClient)
+  builder.setClient(myCustomClient);
+
+  // Inherit bookmarks from a different parent provider
+  builder.setParent(parentProvider);
+
+  // Override how the current context is resolved
+  builder.setContextResolver(async (init) => {
+    return async () => ({ id: 'custom-context-id' });
+  });
+
+  // Override how the current application is resolved
+  builder.setApplicationResolver(async (init) => {
+    return async () => ({ appKey: 'my-app' });
+  });
 });
 ```
 
-
 > [!NOTE]
-> When not providing configuration, the configurator will use the parent (ref initiator, example portal framework) configuration, then fallback to default configuration.
-> - `SourceSystem`
-> - `Filter`
-> - `ContextResolver` 
-> - `ApplicationResolver`
-> 
+> When no explicit configuration is provided, the configurator resolves values
+> from the parent framework (portal) and falls back to defaults for:
+> - Source system
+> - Filters
+> - Context resolver
+> - Application resolver
 
 ## BookmarkProvider
 
-The `BookmarkProvider` class is responsible for managing bookmarks in the application. It provides methods for creating, updating, and removing bookmarks, as well as managing the current bookmark and the list of bookmarks.
-
-### Usage
-
-
-#### Creating a Bookmark
+`BookmarkProvider` is the runtime service you interact with after the module is initialised. It exposes both **Observable** and **async/Promise** APIs for every operation.
 
-To create a new bookmark, use the `createBookmark` method:
+### Creating a Bookmark
 
 ```ts
-const newBookmark = {
-    name: 'My Bookmark',
-    payload: { /* Your bookmark data */ },
-};
+bookmarkProvider.createBookmark({
+  name: 'My Bookmark',
+  payload: { filters: { status: 'active' } },
+}).subscribe({
+  next: (bookmark) => console.log('Created:', bookmark.id),
+  error: (err) => console.error('Create failed:', err),
+});
 
-bookmarkProvider.createBookmark(newBookmark).subscribe({
-    next: (bookmark) => {
-        console.log('Bookmark created:', bookmark);
-    },
-    error: (err) => {
-        console.error('Failed to create bookmark:', err);
-    },
+// Or with async/await:
+const bookmark = await bookmarkProvider.createBookmarkAsync({
+  name: 'My Bookmark',
+  payload: { filters: { status: 'active' } },
 });
 ```
 
-
-#### Updating a Bookmark
-
-To update an existing bookmark, use the `updateBookmark` method:
+### Updating a Bookmark
 
 ```ts
-const bookmarkId = 'bookmark-id';
-const bookmarkUpdates = {
-    name: 'Updated Bookmark Name',
-    payload: { /* Updated bookmark data */ },
-};
-
-bookmarkProvider.updateBookmark(bookmarkId, bookmarkUpdates).subscribe({
-    next: (updatedBookmark) => {
-        console.log('Bookmark updated:', updatedBookmark);
-    },
-    error: (err) => {
-        console.error('Failed to update bookmark:', err);
-    },
+bookmarkProvider.updateBookmark('bookmark-id', {
+  name: 'Updated Name',
+  payload: { filters: { status: 'closed' } },
+}).subscribe({
+  next: (updated) => console.log('Updated:', updated.id),
+  error: (err) => console.error('Update failed:', err),
 });
 ```
 
-#### Using payload generator
-
-Callback function which triggers on creation or update of bookmark. It is used to modify the payload of the bookmark.
-
-- payload: The payload of the bookmark, which can be modified of other payload generators.
-- initial: The initial payload of the bookmark, which is the payload of the bookmark before any payload generators have been applied.
+### Deleting a Bookmark
 
 ```ts
-const bookmarkPayloadGenerator = (payload, initial) => {
-    payload.counter = payload.counter ?? 0 + initial.counter;
-};
+bookmarkProvider.deleteBookmark('bookmark-id').subscribe({
+  next: () => console.log('Deleted'),
+  error: (err) => console.error('Delete failed:', err),
+});
 ```
 
-#### Removing a Bookmark
+### Payload Generators
 
-To remove a bookmark, use the `removeBookmark` method:
+Register a callback that runs during create and update to build or transform the bookmark payload. The callback receives an **Immer draft** — mutate it in place:
 
 ```ts
-const bookmarkId = 'bookmark-id';
-
-bookmarkProvider.removeBookmark(bookmarkId).subscribe({
-    next: (result) => {
-        console.log('Bookmark removed:', result);
-    },
-    error: (err) => {
-        console.error('Failed to remove bookmark:', err);
-    },
+const unregister = bookmarkProvider.addPayloadGenerator((payload, initial) => {
+  // `payload` is an Immer draft — mutate directly
+  payload.savedAt = new Date().toISOString();
+  payload.counter = (initial?.counter ?? 0) + 1;
 });
+
+// Call unregister() when the component unmounts to remove the generator
 ```
 
+`canCreateBookmarks` returns `true` only when at least one payload generator is registered.
 
-#### Managing Favorites
+### Current Bookmark
 
-To add a bookmark to favorites, use the `addBookmarkToFavorites` method:
+Set, observe, or clear the active bookmark:
 
 ```ts
-const bookmarkId = 'bookmark-id';
-
-bookmarkProvider.addBookmarkToFavorites(bookmarkId).subscribe({
-    next: (bookmark) => {
-        console.log('Bookmark added to favorites:', bookmark);
-    },
-    error: (err) => {
-        console.error('Failed to add bookmark to favorites:', err);
-    },
-});
-```
+// Set current bookmark by ID (fetches full data automatically)
+bookmarkProvider.setCurrentBookmark('bookmark-id').subscribe();
 
-To remove a bookmark from favorites, use the `removeBookmarkFromFavorites` method:
+// Clear the current bookmark
+bookmarkProvider.setCurrentBookmark(null).subscribe();
 
-```ts
-const bookmarkId = 'bookmark-id';
-bookmarkProvider.removeBookmarkFromFavorites(bookmarkId).subscribe({
-    next: (bookmark) => {
-        console.log('Bookmark removed from favorites:', bookmark);
-    },
-    error: (err) => {
-        console.error('Failed to remove bookmark from favorites:', err);
-    },
+// Observe changes
+bookmarkProvider.currentBookmark$.subscribe((bookmark) => {
+  console.log('Active bookmark:', bookmark);
 });
 ```
 
-
-To check if a bookmark is in favorites, use the `isBookmarkInFavorites` method:
+### Favourites
 
 ```ts
-const bookmarkId = 'bookmark-id';
-
-bookmarkProvider.isBookmarkInFavorites(bookmarkId).subscribe({
-    next: (isFavorite) => {
-        console.log('Is bookmark in favorites:', isFavorite);
-    },
-    error: (err) => {
-        console.error('Failed to check if bookmark is in favorites:', err);
-    },
-});
-```
+// Add to favourites
+bookmarkProvider.addBookmarkToFavorites('bookmark-id').subscribe();
 
+// Remove from favourites
+bookmarkProvider.removeBookmarkAsFavorite('bookmark-id').subscribe();
 
-#### Event Listeners
-
-You can register event listeners for various bookmark-related events:
-
-```ts
-const removeListener = bookmarkProvider.on('onCurrentBookmarkChanged', (event) => {
-    console.log('Current bookmark changed:', event.detail);
+// Check favourite status
+bookmarkProvider.isBookmarkInFavorites('bookmark-id').subscribe((isFav) => {
+  console.log('Is favourite:', isFav);
 });
-
-// To remove the event listener
-removeListener();
 ```
 
-## Client
+### Event Listeners
 
-The `BookmarkClient` class is responsible for fetching bookmarks from the source system. It provides methods for fetching bookmarks by ID, fetching bookmarks by query, and fetching the current bookmark. This is the default implementation of the client and created if not overridden in the configuration.
+Subscribe to lifecycle events emitted by the provider:
 
 ```ts
-/** Example usage with BookmarkClient as stand alone */
-import { BookmarkClient } from '@equinor/fusion-bookmark';
-import { BookmarksApiClient } from '@equinor/fusion-framework-module-services/bookmarks';
-import { HttpClient } from '@equinor/fusion-framework-module-http/client';
-
-const httpClient = new HttpClient('https://my-fusion-backend-url.com');
-const apiClient = new BookmarksApiClient(httpClient, 'json$');
-const client = new BookmarkClient(apiClient);
-
-client.getAllBookmarks().subscribe(bookmarks => {
-    // do something with bookmarks
+const unsubscribe = bookmarkProvider.on('onCurrentBookmarkChanged', (event) => {
+  console.log('Current bookmark changed:', event.detail);
 });
 
-client.getBookmarkById('bookmark-id').subscribe(bookmark => {
-// do something with bookmark
-});
+// Call unsubscribe() to remove the listener
 ```
 
-### Custom Client
+Available events:
 
-By implementing the `IBookmarkClient` interface, you can create a custom client implementation.
+| Event | When it fires |
+| --- | --- |
+| `onCurrentBookmarkChange` | **Before** the current bookmark changes (cancelable) |
+| `onCurrentBookmarkChanged` | **After** the current bookmark has changed |
+| `onBookmarkCreate` | Before a bookmark is created (cancelable) |
+| `onBookmarkCreated` | After a bookmark has been created |
+| `onBookmarkUpdate` | Before a bookmark is updated (cancelable) |
+| `onBookmarkUpdated` | After a bookmark has been updated |
+| `onBookmarkDelete` | Before a bookmark is deleted (cancelable) |
+| `onBookmarkDeleted` | After a bookmark has been deleted |
+| `onBookmarkFavouriteAdd` | Before a bookmark is added to favourites (cancelable) |
+| `onBookmarkFavouriteAdded` | After a bookmark has been added to favourites |
+| `onBookmarkFavouriteRemove` | Before a bookmark is removed from favourites (cancelable) |
+| `onBookmarkFavouriteRemoved` | After a bookmark has been removed from favourites |
+| `onBookmarkPayloadCreatorAdded` | When a new payload generator is registered |
 
-```typescript
-import { IBookmarkClient } from '@equinor/fusion-bookmark';
+## Custom Bookmark Client
 
-export class CustomBookmarkClient implements IBookmarkClient {
-    // Implement the interface methods
-}
+To use a different backend, implement the `IBookmarkClient` interface and pass it to the configurator:
 
-const configure = (configurator) => {
-    enableBookmarkModule(configurator, async(builder) => {
-        builder.setClient(new CustomBookmarkClient());
-    });
+```ts
+import type { IBookmarkClient } from '@equinor/fusion-framework-module-bookmark';
+
+const myClient: IBookmarkClient = {
+  getAllBookmarks: (filter) => { /* ... */ },
+  getBookmarkById: (id) => { /* ... */ },
+  getBookmarkData: (id) => { /* ... */ },
+  setBookmarkData: (id, data) => { /* ... */ },
+  createBookmark: (bookmark) => { /* ... */ },
+  updateBookmark: (id, updates) => { /* ... */ },
+  deleteBookmark: (id) => { /* ... */ },
+  addBookmarkToFavorites: (id) => { /* ... */ },
+  removeBookmarkFromFavorites: (id) => { /* ... */ },
+  isBookmarkFavorite: (id) => { /* ... */ },
 };
-```
-
-## Tips
-
-## Using "shared" creator across multiple components
-
-The bookmark module is designed to allow multiple subscribers to collectively manage the payload of an bookmark. This is done by using a payload generator that is triggered on creation and update of the bookmark. This allows multiple components to share the same payload and update it in a safe way.
-
-To solve this complex problem, internally the bookmark provider uses immer to generate a draft of the payload (a reducer function to update the payload, prevent flux and mutation). This allows the payload to be updated in a safe way, without the need to worry about immutability.
-
-__BAD!__
-```tsx
-/**
- * In this example, the mutation of the payload will fail since the currentBookmark is immutable.
- */ 
-const RootComponent = () => {
-  // note deprecated useBookmark
-  const {
-    addBookmarkCreator,
-    currentBookmark 
-  } = useBookmark();
-
-  const payloadRef = useRef(currentBookmark?.payload ?? {});
 
-  useEffect(() => {
-    // since the reference to is return within the reducer, the value will be frozen
-    // this will break, since `payloadRef.current` is supposed to be updated
-    return addBookmarkCreator(() => payloadRef.current);
-  }, [bookmarkProvider]);
-
-  // updates the payloadRef when the current bookmark changes
-  useEffect(() => {
-    payloadRef.current = currentBookmark?.payload ?? {};
-  }, [currentBookmark]);
-
-
-  return (
-    <>
-      <Component1 payloadRef={payloadRef} />
-      <Component2 payloadRef={payloadRef} />
-    </>
-  );
-}
-
-const Component1 = ({ payloadRef }) => {
-  return <input 
-    value={ payloadRef.current.foo } 
-    onChange={(e) => payloadRef.current.foo = e.target.value } 
-  />
-}
-
-const Component2 = ({ payloadRef }) => { ... }
-```
-
-this version can be improved by updating the payload generator, but see next example to migrate of deprecated `useBookmark` to `useCurrentBookmark`.
-
-```ts
-// fix issue with payload generator
-useEffect(() => {
-    return addBookmarkCreator((payload) => {
-        Object.assign(payload, payloadRef.current);
-    });
-}, [bookmarkProvider]);
+enableBookmark(configurator, (builder) => {
+  builder.setClient(myClient);
+});
 ```
 
+## Error Handling
 
-__BETTER!__
-```tsx
-
-const RootComponent = () => {
-  return (
-    <>
-      <Component1 />
-      <Component2 />
-    </>
-  );
-}
-
-const Component1 = () => {
-  const ref = useRef(null);
+The module exposes two error classes:
 
-  // internally the payload generator will use immer to generate a draft
-  const payloadGenerator = useCallback((payload) => {
-    payload.foo = ref.current.value;
-  }, []);
+- **`BookmarkProviderError`** — thrown by `BookmarkProvider` methods when a high-level operation fails (e.g. timeout, cancelled event, resolution failure).
+- **`BookmarkFlowError`** — thrown inside internal store flows when an API call fails. Carries a reference to the originating request action.
 
-  // use the current bookmark and register the payload generator
-  const { currentBookmark } = useCurrentBookmark({ payloadGenerator });
-
-  // when the current bookmark changes, update the input value
-  useEffect(() => {
-    ref.current.value = currentBookmark.foo;
-  }, [currentBookmark]);
-
-  return <input ref={ref} />
-}
-
-Component2 = () => { ... }
-```
+Errors are also collected in the store and accessible via `bookmarkProvider.errors$`.