@hamak/ui-store 0.6.0 → 0.7.2

package/dist/impl/fs/commands/fs-commands.js

@@ -1,8 +1,8 @@
-import { fileSystemNodeInitialState } from '../../../api';
+import { fileSystemNodeInitialState } from '../../../api/index.js';
 import { pathSteps } from '@hamak/shared-utils';
-import { DataUpdater } from '../utils/data-updater';
+import { DataUpdater } from '../utils/data-updater.js';
 import { produce, current, isDraft, original } from 'immer';
-import { deepEqual } from '../utils/deep-equal';
+import { deepEqual } from '../utils/deep-equal.js';
 // Re-export path utilities from shared-utils for internal use
 export { pathSteps, parentPathSteps } from '@hamak/shared-utils';
 /**
@@ -258,6 +258,20 @@ export class FileSystemCommandHandler {
         return isDraft(o) ? original(o) : o;
     }
 }
+/**
+ * Build an empty-object prototype stack mirroring `itinerary` depth-for-depth,
+ * with `{}` at every level. Passed to `DataUpdater` so that missing object
+ * intermediates along the path are materialized instead of silently no-op'ing.
+ *
+ * Object-only: it cannot synthesize array intermediates — callers needing those
+ * must supply an explicit `prototypes` stack (see `ensurePath` JSDoc).
+ */
+function buildEmptyObjectProtos(itinerary) {
+    if (itinerary === undefined) {
+        return undefined;
+    }
+    return { value: {}, parent: buildEmptyObjectProtos(itinerary.parent) };
+}
 /**
  * File content command handler - handles structure commands on file content
  */
@@ -308,25 +322,37 @@ export class FileContentCommandHandler {
         this.updater.executeDelete(content, itinerary);
     }
     executeSet(file, command) {
-        const { itinerary, value } = command;
+        const { itinerary, value, prototypes } = command;
         if (itinerary === undefined) {
             file.content = value;
         }
         const { content } = file;
-        this.updater.executeSet(content, itinerary, value);
+        // executeSet navigates the itinerary's parent, so the prototype stack must
+        // mirror `itinerary.parent`.
+        const effectivePrototypes = prototypes
+            ?? (command.ensurePath ? buildEmptyObjectProtos(itinerary?.parent) : undefined);
+        this.updater.executeSet(content, itinerary, value, effectivePrototypes);
     }
     executeAdd(file, command) {
-        const { itinerary, value } = command;
+        const { itinerary, value, prototypes } = command;
         const { content } = file;
-        this.updater.executeAdd(content, itinerary, value);
+        // executeAdd navigates the full itinerary (the target container), so the
+        // prototype stack mirrors `itinerary`.
+        const effectivePrototypes = prototypes
+            ?? (command.ensurePath ? buildEmptyObjectProtos(itinerary) : undefined);
+        this.updater.executeAdd(content, itinerary, value, effectivePrototypes);
     }
     executeInsert(file, command) {
-        const { itinerary, value } = command;
+        const { itinerary, value, prototypes } = command;
         if (itinerary === undefined) {
             return;
         }
         const { content } = file;
-        this.updater.executeInsert(content, itinerary, value);
+        // executeInsert navigates the itinerary's parent, so the prototype stack
+        // mirrors `itinerary.parent`.
+        const effectivePrototypes = prototypes
+            ?? (command.ensurePath ? buildEmptyObjectProtos(itinerary.parent) : undefined);
+        this.updater.executeInsert(content, itinerary, value, effectivePrototypes);
     }
     /**
      * Executes a batch of commands, rebasing each on previous mutations.

package/dist/impl/fs/commands/structure-commands.d.ts

@@ -17,7 +17,32 @@ export interface UnitaryStructureNodeCommandBase extends StructureNodeCommandBas
  */
 export interface StructureNodeUpsertCommandBase extends UnitaryStructureNodeCommandBase {
     name: "add-at" | "set-at" | 'insert-at';
+    /**
+     * Explicit prototype stack used to materialize missing intermediates along
+     * the itinerary's parent. Each {@link StackElement} level mirrors one
+     * itinerary step (deepest first) and its `value` is the node inserted when
+     * that step is absent. Use this when the missing intermediates include
+     * arrays, or when they need non-empty seed values.
+     *
+     * Takes precedence over {@link ensurePath} when both are supplied.
+     */
     prototypes?: StackElement<any>;
+    /**
+     * Convenience flag for the common "create missing object intermediates"
+     * case: when true (and `prototypes` is absent), the handler synthesizes an
+     * empty-object (`{}`) prototype stack of matching depth, so deep writes into
+     * nested-object documents materialize their parent path instead of silently
+     * no-op'ing when the parent is absent.
+     *
+     * Object-only: each synthesized intermediate is `{}`. For **absent-array**
+     * intermediates this is insufficient — supply `prototypes` explicitly with
+     * an array (`[]`) at the relevant level.
+     *
+     * When false/absent, today's silent-no-op semantics are preserved (no
+     * intermediates are created and a deep write into an absent parent does
+     * nothing).
+     */
+    ensurePath?: boolean;
 }
 /**
  * Add a value at the specified itinerary

package/dist/impl/fs/commands/structure-commands.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"structure-commands.d.ts","sourceRoot":"","sources":["../../../../src/impl/fs/commands/structure-commands.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAE9D;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,WAAW,GAAG,WAAW,GAAG,cAAc,CAAA;CACvE;AAED;;GAEG;AACH,MAAM,WAAW,+BAAgC,SAAQ,wBAAwB;IAC/E,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,WAAW,GAAG,WAAW,CAAA;IACrD,SAAS,EAAE,SAAS,CAAA;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,8BAA+B,SAAQ,+BAA+B;IACrF,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,WAAW,CAAA;IACvC,UAAU,CAAC,EAAG,YAAY,CAAC,GAAG,CAAC,CAAA;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,uBAAwB,SAAQ,8BAA8B;IAC7E,IAAI,EAAE,QAAQ,CAAA;IACd,KAAK,EAAE,GAAG,CAAA;CACX;AAED;;GAEG;AACH,MAAM,WAAW,0BAA2B,SAAQ,8BAA8B;IAChF,IAAI,EAAE,WAAW,CAAA;IACjB,KAAK,EAAE,GAAG,CAAA;CACX;AAED;;GAEG;AACH,MAAM,WAAW,uBAAwB,SAAQ,8BAA8B;IAC7E,IAAI,EAAE,QAAQ,CAAA;IACd,KAAK,EAAE,GAAG,CAAA;CACX;AAED;;GAEG;AACH,MAAM,WAAW,0BAA2B,SAAQ,+BAA+B;IACjF,IAAI,EAAE,WAAW,CAAA;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,+BAAgC,SAAQ,wBAAwB;IAC/E,IAAI,EAAE,cAAc,CAAA;IACpB,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,QAAQ,EAAE,2BAA2B,EAAE,CAAA;CACxC;AAED;;GAEG;AACH,MAAM,MAAM,2BAA2B,GACnC,uBAAuB,GACvB,0BAA0B,GAC1B,uBAAuB,GACvB,0BAA0B,CAAA;AAE9B;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,2BAA2B,GAAG,+BAA+B,CAAA;AAEhG;;GAEG;AACH,qBAAa,0BAA0B;IACrC,OAAO,CAAC,SAAS,EAAG,SAAS,EAAE,KAAK,EAAG,GAAG,EAAE,UAAU,CAAC,EAAE,YAAY,CAAC,GAAG,CAAC,GAAI,uBAAuB;IAIrG,UAAU,CAAC,SAAS,EAAG,SAAS,EAAE,KAAK,EAAG,GAAG,EAAE,UAAU,CAAC,EAAE,YAAY,CAAC,GAAG,CAAC,GAAI,0BAA0B;IAI3G,OAAO,CAAC,SAAS,EAAG,SAAS,EAAE,KAAK,EAAG,GAAG,EAAE,UAAU,CAAC,EAAE,YAAY,CAAC,GAAG,CAAC,GAAI,uBAAuB;IAIrG,UAAU,CAAC,SAAS,EAAG,SAAS,GAAI,0BAA0B;IAI9D,WAAW,CAAC,QAAQ,EAAG,2BAA2B,EAAE,EAAE,UAAU,UAAQ,GAAI,+BAA+B;CAG5G;AAED,eAAO,MAAM,OAAO,4BAAmC,CAAA"}
+{"version":3,"file":"structure-commands.d.ts","sourceRoot":"","sources":["../../../../src/impl/fs/commands/structure-commands.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAE9D;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,WAAW,GAAG,WAAW,GAAG,cAAc,CAAA;CACvE;AAED;;GAEG;AACH,MAAM,WAAW,+BAAgC,SAAQ,wBAAwB;IAC/E,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,WAAW,GAAG,WAAW,CAAA;IACrD,SAAS,EAAE,SAAS,CAAA;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,8BAA+B,SAAQ,+BAA+B;IACrF,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,WAAW,CAAA;IACvC;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAG,YAAY,CAAC,GAAG,CAAC,CAAA;IAC/B;;;;;;;;;;;;;;OAcG;IACH,UAAU,CAAC,EAAG,OAAO,CAAA;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,uBAAwB,SAAQ,8BAA8B;IAC7E,IAAI,EAAE,QAAQ,CAAA;IACd,KAAK,EAAE,GAAG,CAAA;CACX;AAED;;GAEG;AACH,MAAM,WAAW,0BAA2B,SAAQ,8BAA8B;IAChF,IAAI,EAAE,WAAW,CAAA;IACjB,KAAK,EAAE,GAAG,CAAA;CACX;AAED;;GAEG;AACH,MAAM,WAAW,uBAAwB,SAAQ,8BAA8B;IAC7E,IAAI,EAAE,QAAQ,CAAA;IACd,KAAK,EAAE,GAAG,CAAA;CACX;AAED;;GAEG;AACH,MAAM,WAAW,0BAA2B,SAAQ,+BAA+B;IACjF,IAAI,EAAE,WAAW,CAAA;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,+BAAgC,SAAQ,wBAAwB;IAC/E,IAAI,EAAE,cAAc,CAAA;IACpB,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,QAAQ,EAAE,2BAA2B,EAAE,CAAA;CACxC;AAED;;GAEG;AACH,MAAM,MAAM,2BAA2B,GACnC,uBAAuB,GACvB,0BAA0B,GAC1B,uBAAuB,GACvB,0BAA0B,CAAA;AAE9B;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,2BAA2B,GAAG,+BAA+B,CAAA;AAEhG;;GAEG;AACH,qBAAa,0BAA0B;IACrC,OAAO,CAAC,SAAS,EAAG,SAAS,EAAE,KAAK,EAAG,GAAG,EAAE,UAAU,CAAC,EAAE,YAAY,CAAC,GAAG,CAAC,GAAI,uBAAuB;IAIrG,UAAU,CAAC,SAAS,EAAG,SAAS,EAAE,KAAK,EAAG,GAAG,EAAE,UAAU,CAAC,EAAE,YAAY,CAAC,GAAG,CAAC,GAAI,0BAA0B;IAI3G,OAAO,CAAC,SAAS,EAAG,SAAS,EAAE,KAAK,EAAG,GAAG,EAAE,UAAU,CAAC,EAAE,YAAY,CAAC,GAAG,CAAC,GAAI,uBAAuB;IAIrG,UAAU,CAAC,SAAS,EAAG,SAAS,GAAI,0BAA0B;IAI9D,WAAW,CAAC,QAAQ,EAAG,2BAA2B,EAAE,EAAE,UAAU,UAAQ,GAAI,+BAA+B;CAG5G;AAED,eAAO,MAAM,OAAO,4BAAmC,CAAA"}

package/dist/impl/fs/core/fs-adapter.d.ts

@@ -1,7 +1,7 @@
 import { Action } from '@reduxjs/toolkit';
-import { FileSystemCommandHandler } from '../commands/fs-commands';
-import { FileSystemNode, FileSystemState, FileContentSchema, FileSystemNodeActionParams, FileSystemNodeAction, Selector } from '../../../api';
-import { StructureNodeCommand } from '../commands/structure-commands';
+import { FileSystemCommandHandler } from '../commands/fs-commands.js';
+import { FileSystemNode, FileSystemState, FileContentSchema, FileSystemNodeActionParams, FileSystemNodeAction, Selector } from '../../../api/index.js';
+import { StructureNodeCommand } from '../commands/structure-commands.js';
 /**
  * Factory function to create a FileSystemAdapter
  */

package/dist/impl/fs/core/fs-adapter.js

@@ -1,6 +1,6 @@
 import { createSelector } from '@reduxjs/toolkit';
-import { FileSystemCommandHandler, pathSteps } from '../commands/fs-commands';
-import { fileSystemNodeInitialState } from '../../../api';
+import { FileSystemCommandHandler, pathSteps } from '../commands/fs-commands.js';
+import { fileSystemNodeInitialState } from '../../../api/index.js';
 /**
  * Factory function to create a FileSystemAdapter
  */

package/dist/impl/fs/core/fs-facade.d.ts

@@ -1,5 +1,5 @@
-import { FileNode, FileSystemNode, FileSystemState, Selector } from '../../../api';
-import { FileSystemAdapter, FileSystemNodeActions } from './fs-adapter';
+import { FileNode, FileSystemNode, FileSystemState, Selector } from '../../../api/index.js';
+import { FileSystemAdapter, FileSystemNodeActions } from './fs-adapter.js';
 import { Path, Pathway, PathwayResolver, RelativePathwayResolver } from '@hamak/shared-utils';
 /**
  * Selector that returns a FileSystemNode generally the root of the Filesystem Overlay

package/dist/impl/fs/index.d.ts

@@ -1,8 +1,8 @@
-export * from './core/fs-adapter';
-export * from './core/fs-facade';
-export * from './commands/fs-commands';
-export * from './commands/structure-commands';
+export * from './core/fs-adapter.js';
+export * from './core/fs-facade.js';
+export * from './commands/fs-commands.js';
+export * from './commands/structure-commands.js';
 export { pathSteps, parentPathSteps } from '@hamak/shared-utils';
-export * from './utils/data-updater';
-export * from './utils/deep-equal';
+export * from './utils/data-updater.js';
+export * from './utils/deep-equal.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/impl/fs/index.js

@@ -1,11 +1,11 @@
 // Core filesystem functionality
-export * from './core/fs-adapter';
-export * from './core/fs-facade';
+export * from './core/fs-adapter.js';
+export * from './core/fs-facade.js';
 // Commands
-export * from './commands/fs-commands';
-export * from './commands/structure-commands';
+export * from './commands/fs-commands.js';
+export * from './commands/structure-commands.js';
 // Re-export path utilities from shared-utils for backward compatibility
 export { pathSteps, parentPathSteps } from '@hamak/shared-utils';
 // Utilities
-export * from './utils/data-updater';
-export * from './utils/deep-equal';
+export * from './utils/data-updater.js';
+export * from './utils/deep-equal.js';

package/dist/impl/fs/utils/data-updater.d.ts

@@ -1,5 +1,5 @@
 import { Itinerary, StackElement } from '@hamak/shared-utils';
-import { UnitaryStructureNodeCommand, BatchUpdateStructureNodeCommand } from '../commands/structure-commands';
+import { UnitaryStructureNodeCommand, BatchUpdateStructureNodeCommand } from '../commands/structure-commands.js';
 /**
  * DataUpdater class handles operations on data structures using itineraries
  */

package/dist/impl/index.d.ts

@@ -2,11 +2,12 @@
  * UI Store Implementation
  * Concrete implementations of Redux store management
  */
-export * from '../api';
-export * from '../spi';
-export * from './core';
-export * from './middleware';
-export * from './plugin';
-export * from './fs';
-export * from './autosave';
+export * from '../api/index.js';
+export * from '../spi/index.js';
+export * from './core/index.js';
+export * from './middleware/index.js';
+export * from './plugin/index.js';
+export * from './fs/index.js';
+export * from './autosave/index.js';
+export * from './persistence/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/impl/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/impl/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AAEvB,cAAc,QAAQ,CAAC;AACvB,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,MAAM,CAAC;AACrB,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/impl/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,cAAc,QAAQ,CAAC;AACvB,cAAc,QAAQ,CAAC;AAEvB,cAAc,QAAQ,CAAC;AACvB,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,MAAM,CAAC;AACrB,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC"}

package/dist/impl/index.js

@@ -3,10 +3,11 @@
  * Concrete implementations of Redux store management
  */
 // Re-export API and SPI for convenience
-export * from '../api';
-export * from '../spi';
-export * from './core';
-export * from './middleware';
-export * from './plugin';
-export * from './fs';
-export * from './autosave';
+export * from '../api/index.js';
+export * from '../spi/index.js';
+export * from './core/index.js';
+export * from './middleware/index.js';
+export * from './plugin/index.js';
+export * from './fs/index.js';
+export * from './autosave/index.js';
+export * from './persistence/index.js';

package/dist/impl/middleware/index.d.ts

@@ -1,6 +1,6 @@
 /**
  * Middleware Export
  */
-export * from './event-bridge-middleware';
-export * from './logger-middleware';
+export * from './event-bridge-middleware.js';
+export * from './logger-middleware.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/impl/middleware/index.js

@@ -1,5 +1,5 @@
 /**
  * Middleware Export
  */
-export * from './event-bridge-middleware';
-export * from './logger-middleware';
+export * from './event-bridge-middleware.js';
+export * from './logger-middleware.js';

package/dist/impl/persistence/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * State persistence implementations and wiring.
+ * See amah/app-framework#30.
+ */
+export * from './web-storage-persistence-provider.js';
+export * from './persistence-filter.js';
+export * from './persistence-resolver.js';
+export * from './persistence-wiring.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/impl/persistence/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/impl/persistence/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,oCAAoC,CAAC;AACnD,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC"}

package/dist/impl/persistence/index.js

@@ -0,0 +1,8 @@
+/**
+ * State persistence implementations and wiring.
+ * See amah/app-framework#30.
+ */
+export * from './web-storage-persistence-provider.js';
+export * from './persistence-filter.js';
+export * from './persistence-resolver.js';
+export * from './persistence-wiring.js';

package/dist/impl/persistence/persistence-filter.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Slice-level whitelist/blacklist filtering for persisted state.
+ *
+ * Persistence operates at the top-level reducer key ("slice") granularity:
+ * a whitelist keeps only the named slices; a blacklist drops named slices.
+ * The whitelist is applied first, then the blacklist. See amah/app-framework#30.
+ */
+import type { StorePersistenceConfig } from '../../api/index.js';
+export type SliceSelection = Pick<StorePersistenceConfig, 'whitelist' | 'blacklist'>;
+export declare function pickPersistableState(state: Record<string, unknown> | null | undefined, selection: SliceSelection): Record<string, unknown>;
+//# sourceMappingURL=persistence-filter.d.ts.map

package/dist/impl/persistence/persistence-filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence-filter.d.ts","sourceRoot":"","sources":["../../../src/impl/persistence/persistence-filter.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAExD,MAAM,MAAM,cAAc,GAAG,IAAI,CAC/B,sBAAsB,EACtB,WAAW,GAAG,WAAW,CAC1B,CAAC;AAEF,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,EACjD,SAAS,EAAE,cAAc,GACxB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAgBzB"}

package/dist/impl/persistence/persistence-filter.js

@@ -0,0 +1,24 @@
+/**
+ * Slice-level whitelist/blacklist filtering for persisted state.
+ *
+ * Persistence operates at the top-level reducer key ("slice") granularity:
+ * a whitelist keeps only the named slices; a blacklist drops named slices.
+ * The whitelist is applied first, then the blacklist. See amah/app-framework#30.
+ */
+export function pickPersistableState(state, selection) {
+    if (!state || typeof state !== 'object')
+        return {};
+    const { whitelist, blacklist } = selection;
+    const result = {};
+    for (const key of Object.keys(state)) {
+        // A set whitelist constrains to its members (an empty whitelist persists
+        // nothing); an unset whitelist imposes no constraint. The blacklist is
+        // then applied on top.
+        if (whitelist && !whitelist.includes(key))
+            continue;
+        if (blacklist && blacklist.includes(key))
+            continue;
+        result[key] = state[key];
+    }
+    return result;
+}

package/dist/impl/persistence/persistence-resolver.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Resolves a concrete `IPersistenceProvider` from a `StorePersistenceConfig`.
+ * Used to build the default provider when a consumer enables persistence but
+ * does not mount a custom one. See amah/app-framework#30.
+ */
+import type { StorePersistenceConfig } from '../../api/index.js';
+import type { IPersistenceProvider } from '../../spi/index.js';
+export declare function resolvePersistenceProvider(persistence: StorePersistenceConfig): IPersistenceProvider;
+//# sourceMappingURL=persistence-resolver.d.ts.map

package/dist/impl/persistence/persistence-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence-resolver.d.ts","sourceRoot":"","sources":["../../../src/impl/persistence/persistence-resolver.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AACxD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAMtD,wBAAgB,0BAA0B,CACxC,WAAW,EAAE,sBAAsB,GAClC,oBAAoB,CAiBtB"}

package/dist/impl/persistence/persistence-resolver.js

@@ -0,0 +1,22 @@
+/**
+ * Resolves a concrete `IPersistenceProvider` from a `StorePersistenceConfig`.
+ * Used to build the default provider when a consumer enables persistence but
+ * does not mount a custom one. See amah/app-framework#30.
+ */
+import { createLocalStoragePersistenceProvider, createSessionStoragePersistenceProvider, } from './web-storage-persistence-provider.js';
+export function resolvePersistenceProvider(persistence) {
+    const storage = persistence.storage ?? 'localStorage';
+    switch (storage) {
+        case 'sessionStorage':
+            return createSessionStoragePersistenceProvider();
+        case 'indexedDB':
+            // Not yet implemented — fall back to localStorage so enabling it is not a
+            // silent no-op. Tracked as a follow-up in #30.
+            console.warn("[persistence] storage 'indexedDB' is not implemented yet; " +
+                'falling back to localStorage.');
+            return createLocalStoragePersistenceProvider();
+        case 'localStorage':
+        default:
+            return createLocalStoragePersistenceProvider();
+    }
+}

package/dist/impl/persistence/persistence-wiring.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Load/save wiring that connects a Redux store to an `IPersistenceProvider`.
+ *
+ * - `loadPersistedState` rehydrates the whitelisted slice on boot (async,
+ *   called before store creation so the result can seed `preloadedState`).
+ * - `attachPersistenceSave` subscribes to the store and writes the whitelisted
+ *   slice back, debounced, on every change. See amah/app-framework#30.
+ */
+import type { Store } from 'redux';
+import type { StorePersistenceConfig } from '../../api/index.js';
+import type { IPersistenceProvider } from '../../spi/index.js';
+/** Default storage key when `persistence.key` is not set. */
+export declare const DEFAULT_PERSISTENCE_KEY = "state";
+/** Default debounce window for save-on-change. */
+export declare const DEFAULT_PERSISTENCE_DEBOUNCE_MS = 250;
+export declare function persistenceKey(persistence: StorePersistenceConfig): string;
+/**
+ * Load the persisted slice and re-apply the whitelist/blacklist defensively
+ * (in case the config tightened since the data was written). Returns
+ * `undefined` when nothing is persisted, so callers can spread it into
+ * `preloadedState` without overwriting reducer defaults.
+ */
+export declare function loadPersistedState(provider: IPersistenceProvider, persistence: StorePersistenceConfig): Promise<Record<string, unknown> | undefined>;
+/**
+ * Subscribe to the store and persist the whitelisted slice on change,
+ * debounced. Returns an unsubscribe function that also cancels a pending save.
+ */
+export declare function attachPersistenceSave(store: Pick<Store, 'getState' | 'subscribe'>, provider: IPersistenceProvider, persistence: StorePersistenceConfig): () => void;
+//# sourceMappingURL=persistence-wiring.d.ts.map

package/dist/impl/persistence/persistence-wiring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence-wiring.d.ts","sourceRoot":"","sources":["../../../src/impl/persistence/persistence-wiring.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC;AACnC,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AACxD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAGtD,6DAA6D;AAC7D,eAAO,MAAM,uBAAuB,UAAU,CAAC;AAE/C,kDAAkD;AAClD,eAAO,MAAM,+BAA+B,MAAM,CAAC;AAEnD,wBAAgB,cAAc,CAAC,WAAW,EAAE,sBAAsB,GAAG,MAAM,CAE1E;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,oBAAoB,EAC9B,WAAW,EAAE,sBAAsB,GAClC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC,CAQ9C;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,WAAW,CAAC,EAC5C,QAAQ,EAAE,oBAAoB,EAC9B,WAAW,EAAE,sBAAsB,GAClC,MAAM,IAAI,CAyCZ"}

package/dist/impl/persistence/persistence-wiring.js

@@ -0,0 +1,69 @@
+/**
+ * Load/save wiring that connects a Redux store to an `IPersistenceProvider`.
+ *
+ * - `loadPersistedState` rehydrates the whitelisted slice on boot (async,
+ *   called before store creation so the result can seed `preloadedState`).
+ * - `attachPersistenceSave` subscribes to the store and writes the whitelisted
+ *   slice back, debounced, on every change. See amah/app-framework#30.
+ */
+import { pickPersistableState } from './persistence-filter.js';
+/** Default storage key when `persistence.key` is not set. */
+export const DEFAULT_PERSISTENCE_KEY = 'state';
+/** Default debounce window for save-on-change. */
+export const DEFAULT_PERSISTENCE_DEBOUNCE_MS = 250;
+export function persistenceKey(persistence) {
+    return persistence.key ?? DEFAULT_PERSISTENCE_KEY;
+}
+/**
+ * Load the persisted slice and re-apply the whitelist/blacklist defensively
+ * (in case the config tightened since the data was written). Returns
+ * `undefined` when nothing is persisted, so callers can spread it into
+ * `preloadedState` without overwriting reducer defaults.
+ */
+export async function loadPersistedState(provider, persistence) {
+    const loaded = await provider.load(persistenceKey(persistence));
+    if (loaded == null || typeof loaded !== 'object')
+        return undefined;
+    const filtered = pickPersistableState(loaded, persistence);
+    return Object.keys(filtered).length > 0 ? filtered : undefined;
+}
+/**
+ * Subscribe to the store and persist the whitelisted slice on change,
+ * debounced. Returns an unsubscribe function that also cancels a pending save.
+ */
+export function attachPersistenceSave(store, provider, persistence) {
+    const key = persistenceKey(persistence);
+    const debounceMs = persistence.debounceMs ?? DEFAULT_PERSISTENCE_DEBOUNCE_MS;
+    let timer = null;
+    // Seed the baseline with the current slice so a change that leaves the
+    // persisted slice untouched (e.g. a non-whitelisted slice updated) never
+    // triggers a redundant write — including right after rehydration.
+    let lastSerialized = JSON.stringify(pickPersistableState(store.getState(), persistence));
+    const flush = () => {
+        timer = null;
+        const slice = pickPersistableState(store.getState(), persistence);
+        const serialized = JSON.stringify(slice);
+        // Skip redundant writes when the persisted slice did not actually change.
+        if (serialized === lastSerialized)
+            return;
+        lastSerialized = serialized;
+        void provider.save(key, slice);
+    };
+    const unsubscribe = store.subscribe(() => {
+        if (timer !== null)
+            clearTimeout(timer);
+        if (debounceMs <= 0) {
+            flush();
+        }
+        else {
+            timer = setTimeout(flush, debounceMs);
+        }
+    });
+    return () => {
+        if (timer !== null) {
+            clearTimeout(timer);
+            timer = null;
+        }
+        unsubscribe();
+    };
+}

package/dist/impl/persistence/web-storage-persistence-provider.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Web Storage Persistence Provider
+ *
+ * Concrete `IPersistenceProvider` backed by a Web Storage area
+ * (`localStorage` / `sessionStorage`). When the backing storage is
+ * unavailable — SSR, private-mode quota errors, disabled storage — it
+ * degrades gracefully to an in-memory map so callers never throw. This mirrors
+ * the `createLocalStorageActiveProjectStorage` fallback pattern used
+ * downstream. See amah/app-framework#30.
+ */
+import type { IPersistenceProvider } from '../../spi/index.js';
+/** Minimal structural subset of the Web Storage API we depend on. */
+export interface WebStorageLike {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    key(index: number): string | null;
+    readonly length: number;
+}
+/** Default namespace every persisted key is prefixed with. */
+export declare const DEFAULT_PERSISTENCE_NAMESPACE = "@hamak/ui-store";
+export declare class WebStoragePersistenceProvider implements IPersistenceProvider {
+    private readonly storage;
+    private readonly namespace;
+    private readonly memory;
+    private readonly available;
+    /**
+     * @param storage   Backing web storage, or `null` to run in-memory only.
+     * @param namespace Key prefix; `clear()` only removes keys under this prefix
+     *                  so it never wipes unrelated app state.
+     */
+    constructor(storage: WebStorageLike | null, namespace?: string);
+    isAvailable(): boolean;
+    save(key: string, state: unknown): Promise<void>;
+    load(key: string): Promise<any | null>;
+    remove(key: string): Promise<void>;
+    clear(): Promise<void>;
+    private fullKey;
+    /** Verify the storage area is usable with a write/remove round-trip. */
+    private static probe;
+}
+/** Provider backed by `window.localStorage` (in-memory fallback when absent). */
+export declare function createLocalStoragePersistenceProvider(namespace?: string): WebStoragePersistenceProvider;
+/** Provider backed by `window.sessionStorage` (in-memory fallback when absent). */
+export declare function createSessionStoragePersistenceProvider(namespace?: string): WebStoragePersistenceProvider;
+//# sourceMappingURL=web-storage-persistence-provider.d.ts.map

package/dist/impl/persistence/web-storage-persistence-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-storage-persistence-provider.d.ts","sourceRoot":"","sources":["../../../src/impl/persistence/web-storage-persistence-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAEtD,qEAAqE;AACrE,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACpC,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,8DAA8D;AAC9D,eAAO,MAAM,6BAA6B,oBAAoB,CAAC;AAI/D,qBAAa,6BAA8B,YAAW,oBAAoB;IAUtE,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAV5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA6B;IACpD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAU;IAEpC;;;;OAIG;gBAEgB,OAAO,EAAE,cAAc,GAAG,IAAI,EAC9B,SAAS,GAAE,MAAsC;IAKpE,WAAW,IAAI,OAAO;IAIhB,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAchD,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC;IAsBtC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAYlC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAmB5B,OAAO,CAAC,OAAO;IAIf,wEAAwE;IACxE,OAAO,CAAC,MAAM,CAAC,KAAK;CAUrB;AAcD,iFAAiF;AACjF,wBAAgB,qCAAqC,CACnD,SAAS,CAAC,EAAE,MAAM,GACjB,6BAA6B,CAK/B;AAED,mFAAmF;AACnF,wBAAgB,uCAAuC,CACrD,SAAS,CAAC,EAAE,MAAM,GACjB,6BAA6B,CAK/B"}