@harborclient/sdk 0.7.0 → 1.0.0

package/dist/runtime/store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/runtime/store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,GAAG;IAClD,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,MAAM,IAAI,CAAC;IAChD,WAAW,EAAE,MAAM,CAAC,CAAC;IACrB,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC;CAC7B,CAkBA;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,UAAU,EAAE,MAAM,GAAG,UAAU,CAO1F"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/runtime/store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAG9C;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAE5C;;;;;OAKG;IACH,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9C;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B;;;;OAIG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;IAE5C;;OAEG;IACH,WAAW,IAAI,CAAC,CAAC;IAEjB;;OAEG;IACH,QAAQ,IAAI,CAAC,CAAC;IAEd;;OAEG;IACH,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnC;;;;OAIG;IACH,GAAG,CAAC,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB,CAAC,CAAC;IAC1C,4CAA4C;IAC5C,OAAO,EAAE,WAAW,CAAC;IAErB,+CAA+C;IAC/C,GAAG,EAAE,MAAM,CAAC;IAEZ;;;;;OAKG;IACH,KAAK,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,CAAC,CAAC;IAE3B;;;OAGG;IACH,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,OAAO,CAAC;IAEjC;;;OAGG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,yFAAyF;IACzF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,GAAG;IAClD,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,MAAM,IAAI,CAAC;IAChD,WAAW,EAAE,MAAM,CAAC,CAAC;IACrB,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC;CAC7B,CAkBA;AAYD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,OAAO,EAAE,yBAAyB,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CA+C5F;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,UAAU,EAAE,MAAM,GAAG,UAAU,CAO1F;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,YAAY,CAAC,OAAO,CAAC,GAAG,YAAY,CAAC,OAAO,CAAC,EAAE,EACvD,OAAO,CAAC,EAAE,wBAAwB,GACjC,UAAU,CA0BZ"}

package/dist/runtime/store.js

@@ -1,3 +1,4 @@
+import { useSyncExternalStore } from './react.js';
 /**
  * Creates a module-level external store compatible with React `useSyncExternalStore`.
  *
@@ -22,6 +23,67 @@ export function createExternalStore(initial) {
         }
     };
 }
+/**
+ * Compares two JSON-serializable values using `JSON.stringify`.
+ *
+ * @param a - First value.
+ * @param b - Second value.
+ */
+function defaultEquals(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+/**
+ * Creates a storage-backed external store for sharing state across plugin webviews.
+ *
+ * Separate plugin webviews do not share memory; use {@link syncOnWindowFocus} to
+ * reload when another surface writes storage.
+ *
+ * @param options - Storage key, parse/equals helpers, and the plugin storage API.
+ */
+export function createStorageStore(options) {
+    const { storage, key, parse, equals = defaultEquals, keepCurrentWhenMissing = false } = options;
+    const external = createExternalStore(parse(undefined));
+    /**
+     * Reloads from storage and updates subscribers when the parsed snapshot changed.
+     */
+    async function reloadFromStorage() {
+        const raw = await storage.get(key);
+        if (raw === undefined && keepCurrentWhenMissing) {
+            return;
+        }
+        const next = parse(raw);
+        const current = external.getSnapshot();
+        if (!equals(current, next)) {
+            external.setState(next);
+        }
+    }
+    /**
+     * Updates the snapshot, notifies subscribers, and persists when the value changed.
+     *
+     * @param next - New snapshot value.
+     */
+    async function set(next) {
+        const current = external.getSnapshot();
+        if (equals(current, next)) {
+            return;
+        }
+        external.setState(next);
+        await storage.set(key, next);
+    }
+    /**
+     * React hook returning the current storage-backed snapshot.
+     */
+    function useValue() {
+        return useSyncExternalStore(external.subscribe, external.getSnapshot, external.getSnapshot);
+    }
+    return {
+        subscribe: external.subscribe,
+        getSnapshot: external.getSnapshot,
+        useValue,
+        reloadFromStorage,
+        set
+    };
+}
 /**
  * Starts an interval and returns a disposable that clears it on deactivation.
  *
@@ -36,3 +98,35 @@ export function setIntervalDisposable(callback, intervalMs) {
         }
     };
 }
+/**
+ * Reloads one or more storage-backed stores when the window regains focus or
+ * becomes visible, with optional polling for live cross-webview updates.
+ *
+ * Push the returned disposable onto `hc.subscriptions`, or dispose it from a
+ * React effect cleanup.
+ *
+ * @param stores - One store or an array of stores to reload together.
+ * @param options - Optional polling interval in milliseconds.
+ */
+export function syncOnWindowFocus(stores, options) {
+    const list = Array.isArray(stores) ? stores : [stores];
+    /**
+     * Reloads every registered store from plugin storage.
+     */
+    const reload = () => {
+        for (const store of list) {
+            void store.reloadFromStorage();
+        }
+    };
+    window.addEventListener('focus', reload);
+    document.addEventListener('visibilitychange', reload);
+    reload();
+    const intervalDisposable = options?.intervalMs !== undefined ? setIntervalDisposable(reload, options.intervalMs) : null;
+    return {
+        dispose: () => {
+            window.removeEventListener('focus', reload);
+            document.removeEventListener('visibilitychange', reload);
+            intervalDisposable?.dispose();
+        }
+    };
+}

package/dist/runtime/store.ts

@@ -1,4 +1,99 @@
 import type { Disposable } from '../types.js';
+import { useSyncExternalStore } from './react.js';
+
+/**
+ * Minimal storage surface used by {@link createStorageStore}.
+ */
+export interface StorageLike {
+  /**
+   * Returns the stored value for a key.
+   *
+   * @param key - Storage key within the plugin namespace.
+   */
+  get<T>(key: string): Promise<T | undefined>;
+
+  /**
+   * Persists a JSON-serializable value.
+   *
+   * @param key - Storage key within the plugin namespace.
+   * @param value - Value to persist.
+   */
+  set<T>(key: string, value: T): Promise<void>;
+}
+
+/**
+ * Reactive store backed by plugin storage and compatible with React
+ * `useSyncExternalStore`.
+ */
+export interface StorageStore<T> {
+  /**
+   * Subscribes to snapshot changes for `useSyncExternalStore`.
+   *
+   * @param listener - Callback invoked when the snapshot changes.
+   */
+  subscribe(listener: () => void): () => void;
+
+  /**
+   * Returns the current in-memory snapshot.
+   */
+  getSnapshot(): T;
+
+  /**
+   * React hook returning the current snapshot.
+   */
+  useValue(): T;
+
+  /**
+   * Reloads from storage and notifies subscribers when the parsed value changed.
+   */
+  reloadFromStorage(): Promise<void>;
+
+  /**
+   * Updates the in-memory snapshot, notifies subscribers, and persists to storage.
+   *
+   * @param next - New snapshot value.
+   */
+  set(next: T): Promise<void>;
+}
+
+/**
+ * Options for {@link createStorageStore}.
+ */
+export interface CreateStorageStoreOptions<T> {
+  /** Plugin storage API from `hc.storage`. */
+  storage: StorageLike;
+
+  /** Storage key within the plugin namespace. */
+  key: string;
+
+  /**
+   * Validates and hydrates a raw storage value into a typed snapshot.
+   * Called with `undefined` when the key has never been set.
+   *
+   * @param raw - Raw value from storage, or `undefined` when absent.
+   */
+  parse: (raw: unknown) => T;
+
+  /**
+   * Compares two snapshots to skip no-op reloads and writes.
+   * Defaults to `JSON.stringify` equality.
+   */
+  equals?: (a: T, b: T) => boolean;
+
+  /**
+   * When true, {@link StorageStore.reloadFromStorage} leaves the snapshot
+   * unchanged if the storage key is absent. Default false (apply `parse(undefined)`).
+   */
+  keepCurrentWhenMissing?: boolean;
+}
+
+/**
+ * Options for {@link syncOnWindowFocus}.
+ */
+export interface SyncOnWindowFocusOptions {
+  /** Optional polling interval in milliseconds in addition to focus/visibility reloads. */
+  intervalMs?: number;
+}
 
 /**
  * Creates a module-level external store compatible with React `useSyncExternalStore`.
@@ -29,6 +124,73 @@ export function createExternalStore<T>(initial: T): {
   };
 }
 
+/**
+ * Compares two JSON-serializable values using `JSON.stringify`.
+ *
+ * @param a - First value.
+ * @param b - Second value.
+ */
+function defaultEquals<T>(a: T, b: T): boolean {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+/**
+ * Creates a storage-backed external store for sharing state across plugin webviews.
+ *
+ * Separate plugin webviews do not share memory; use {@link syncOnWindowFocus} to
+ * reload when another surface writes storage.
+ *
+ * @param options - Storage key, parse/equals helpers, and the plugin storage API.
+ */
+export function createStorageStore<T>(options: CreateStorageStoreOptions<T>): StorageStore<T> {
+  const { storage, key, parse, equals = defaultEquals, keepCurrentWhenMissing = false } = options;
+  const external = createExternalStore(parse(undefined));
+
+  /**
+   * Reloads from storage and updates subscribers when the parsed snapshot changed.
+   */
+  async function reloadFromStorage(): Promise<void> {
+    const raw = await storage.get(key);
+    if (raw === undefined && keepCurrentWhenMissing) {
+      return;
+    }
+    const next = parse(raw);
+    const current = external.getSnapshot();
+    if (!equals(current, next)) {
+      external.setState(next);
+    }
+  }
+
+  /**
+   * Updates the snapshot, notifies subscribers, and persists when the value changed.
+   *
+   * @param next - New snapshot value.
+   */
+  async function set(next: T): Promise<void> {
+    const current = external.getSnapshot();
+    if (equals(current, next)) {
+      return;
+    }
+    external.setState(next);
+    await storage.set(key, next);
+  }
+
+  /**
+   * React hook returning the current storage-backed snapshot.
+   */
+  function useValue(): T {
+    return useSyncExternalStore(external.subscribe, external.getSnapshot, external.getSnapshot);
+  }
+
+  return {
+    subscribe: external.subscribe,
+    getSnapshot: external.getSnapshot,
+    useValue,
+    reloadFromStorage,
+    set
+  };
+}
+
 /**
  * Starts an interval and returns a disposable that clears it on deactivation.
  *
@@ -43,3 +205,44 @@ export function setIntervalDisposable(callback: () => void, intervalMs: number):
     }
   };
 }
+
+/**
+ * Reloads one or more storage-backed stores when the window regains focus or
+ * becomes visible, with optional polling for live cross-webview updates.
+ *
+ * Push the returned disposable onto `hc.subscriptions`, or dispose it from a
+ * React effect cleanup.
+ *
+ * @param stores - One store or an array of stores to reload together.
+ * @param options - Optional polling interval in milliseconds.
+ */
+export function syncOnWindowFocus(
+  stores: StorageStore<unknown> | StorageStore<unknown>[],
+  options?: SyncOnWindowFocusOptions
+): Disposable {
+  const list = Array.isArray(stores) ? stores : [stores];
+
+  /**
+   * Reloads every registered store from plugin storage.
+   */
+  const reload = (): void => {
+    for (const store of list) {
+      void store.reloadFromStorage();
+    }
+  };
+
+  window.addEventListener('focus', reload);
+  document.addEventListener('visibilitychange', reload);
+  reload();
+
+  const intervalDisposable =
+    options?.intervalMs !== undefined ? setIntervalDisposable(reload, options.intervalMs) : null;
+
+  return {
+    dispose: () => {
+      window.removeEventListener('focus', reload);
+      document.removeEventListener('visibilitychange', reload);
+      intervalDisposable?.dispose();
+    }
+  };
+}

package/dist/runtime/viewHost.js

@@ -7,7 +7,7 @@ import {
   parseViewHostRole,
   resolveContributionKindFromUrl
 } from './createBridgedPluginContext.js';
-import { setHostReact } from './reactHost.js';
+import { setHostReact, setHostReactDom } from './reactHost.js';
 
 /**
  * Bootstraps an isolated plugin webview shell.
@@ -47,6 +47,7 @@ export async function bootstrapViewHost(options = {}) {
     ]);
 
   setHostReact(React);
+  setHostReactDom(ReactDOM);
 
   const manifest = await fetch(`harbor-plugin://${pluginId}/manifest.json`).then((response) =>
     response.json()

package/dist/runtime-utils.d.ts

@@ -33,4 +33,63 @@ export declare function truncateBody(body: string, maxBytes: number, suffix?: st
     body: string;
     truncated: boolean;
 };
+/**
+ * Minimum log level emitted by {@link createLogger}.
+ *
+ * Messages below the active level are suppressed. `silent` suppresses all output.
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+/**
+ * Plugin-scoped logger with consistent `[pluginId]` prefixing and level control.
+ *
+ * Safe in the SES plugin main runtime where only `console`, `Date`, and `Math`
+ * globals are available.
+ */
+export interface Logger {
+    /**
+     * Logs a debug message when the active level is `debug`.
+     *
+     * @param args - Values forwarded to the console after the prefix.
+     */
+    debug(...args: unknown[]): void;
+    /**
+     * Logs an informational message when the active level is `debug` or `info`.
+     *
+     * @param args - Values forwarded to the console after the prefix.
+     */
+    info(...args: unknown[]): void;
+    /**
+     * Logs a warning when the active level is below `error`.
+     *
+     * @param args - Values forwarded to the console after the prefix.
+     */
+    warn(...args: unknown[]): void;
+    /**
+     * Logs an error when the active level is not `silent`.
+     *
+     * @param args - Values forwarded to the console after the prefix.
+     */
+    error(...args: unknown[]): void;
+    /**
+     * Changes the minimum log level for subsequent calls.
+     *
+     * @param level - New minimum level.
+     */
+    setLevel(level: LogLevel): void;
+}
+/**
+ * Creates a plugin-scoped logger that prefixes every message with `[pluginId]`.
+ *
+ * Routes through `console` only so the logger works in both the renderer and
+ * the SES-hardened main runtime. When `console.warn` or `console.error` are
+ * unavailable, falls back to `console.log`.
+ *
+ * @param pluginId - Manifest id used as the log prefix.
+ * @param options - Optional initial configuration.
+ * @param options.level - Minimum level to emit. Defaults to `info`.
+ * @returns Logger with level-filtered `debug`, `info`, `warn`, and `error` methods.
+ */
+export declare function createLogger(pluginId: string, options?: {
+    level?: LogLevel;
+}): Logger;
 //# sourceMappingURL=runtime-utils.d.ts.map

package/dist/runtime-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-utils.d.ts","sourceRoot":"","sources":["../src/runtime-utils.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,MAAM,SAAO,GAAG,MAAM,CAK9C;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAmBhD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CA+BvE;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,MAAM,SAAsD,GAC3D;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAQtC"}
+{"version":3,"file":"runtime-utils.d.ts","sourceRoot":"","sources":["../src/runtime-utils.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,MAAM,SAAO,GAAG,MAAM,CAK9C;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAmBhD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CA+BvE;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,MAAM,SAAsD,GAC3D;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAQtC;AAED;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEtE;;;;;GAKG;AACH,MAAM,WAAW,MAAM;IACrB;;;;OAIG;IACH,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAEhC;;;;OAIG;IACH,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAE/B;;;;OAIG;IACH,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAE/B;;;;OAIG;IACH,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAEhC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI,CAAC;CACjC;AAUD;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,QAAQ,CAAA;CAAE,GAAG,MAAM,CAuDrF"}

package/dist/runtime-utils.js

@@ -99,3 +99,69 @@ export function truncateBody(body, maxBytes, suffix = `\n\n[truncated — body e
         truncated: true
     };
 }
+const LOG_LEVEL_RANK = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+    silent: 4
+};
+/**
+ * Creates a plugin-scoped logger that prefixes every message with `[pluginId]`.
+ *
+ * Routes through `console` only so the logger works in both the renderer and
+ * the SES-hardened main runtime. When `console.warn` or `console.error` are
+ * unavailable, falls back to `console.log`.
+ *
+ * @param pluginId - Manifest id used as the log prefix.
+ * @param options - Optional initial configuration.
+ * @param options.level - Minimum level to emit. Defaults to `info`.
+ * @returns Logger with level-filtered `debug`, `info`, `warn`, and `error` methods.
+ */
+export function createLogger(pluginId, options) {
+    const prefix = `[${pluginId}]`;
+    let level = options?.level ?? 'info';
+    /**
+     * Emits a message when its severity meets the active level threshold.
+     *
+     * @param messageLevel - Severity of the message being logged.
+     * @param write - Console method to invoke when the message is not suppressed.
+     * @param args - Values forwarded after the prefix.
+     */
+    function log(messageLevel, write, ...args) {
+        if (LOG_LEVEL_RANK[messageLevel] < LOG_LEVEL_RANK[level]) {
+            return;
+        }
+        write(prefix, ...args);
+    }
+    const consoleLog = (...values) => {
+        console.log(...values);
+    };
+    return {
+        debug(...args) {
+            log('debug', consoleLog, ...args);
+        },
+        info(...args) {
+            log('info', consoleLog, ...args);
+        },
+        warn(...args) {
+            const write = typeof console.warn === 'function'
+                ? (...values) => {
+                    console.warn(...values);
+                }
+                : consoleLog;
+            log('warn', write, ...args);
+        },
+        error(...args) {
+            const write = typeof console.error === 'function'
+                ? (...values) => {
+                    console.error(...values);
+                }
+                : consoleLog;
+            log('error', write, ...args);
+        },
+        setLevel(nextLevel) {
+            level = nextLevel;
+        }
+    };
+}

package/dist/runtime-utils.test.js

@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, it, jest } from '@jest/globals';
-import { byteLength, randomId, truncateBody, truncateToBytes } from './runtime-utils.js';
+import { byteLength, createLogger, randomId, truncateBody, truncateToBytes } from './runtime-utils.js';
 const originalTextEncoder = globalThis.TextEncoder;
 const originalCrypto = globalThis.crypto;
 afterEach(() => {
@@ -102,3 +102,76 @@ describe('truncateBody', () => {
         });
     });
 });
+describe('createLogger', () => {
+    it('prefixes messages with [pluginId]', () => {
+        const logSpy = jest.spyOn(console, 'log').mockImplementation(() => { });
+        const logger = createLogger('my-plugin');
+        logger.info('hello');
+        expect(logSpy).toHaveBeenCalledWith('[my-plugin]', 'hello');
+        logSpy.mockRestore();
+    });
+    it('filters messages below the active level', () => {
+        const logSpy = jest.spyOn(console, 'log').mockImplementation(() => { });
+        const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => { });
+        const logger = createLogger('my-plugin', { level: 'warn' });
+        logger.debug('hidden');
+        logger.info('hidden');
+        logger.warn('visible');
+        expect(logSpy).not.toHaveBeenCalled();
+        expect(warnSpy).toHaveBeenCalledTimes(1);
+        expect(warnSpy).toHaveBeenCalledWith('[my-plugin]', 'visible');
+        logSpy.mockRestore();
+        warnSpy.mockRestore();
+    });
+    it('updates the active level via setLevel', () => {
+        const logSpy = jest.spyOn(console, 'log').mockImplementation(() => { });
+        const logger = createLogger('my-plugin');
+        logger.info('before');
+        logger.setLevel('silent');
+        logger.info('after');
+        expect(logSpy).toHaveBeenCalledTimes(1);
+        expect(logSpy).toHaveBeenCalledWith('[my-plugin]', 'before');
+        logSpy.mockRestore();
+    });
+    it('suppresses all output at silent level', () => {
+        const logSpy = jest.spyOn(console, 'log').mockImplementation(() => { });
+        const errorSpy = jest.spyOn(console, 'error').mockImplementation(() => { });
+        const logger = createLogger('my-plugin', { level: 'silent' });
+        logger.debug('a');
+        logger.info('b');
+        logger.warn('c');
+        logger.error('d');
+        expect(logSpy).not.toHaveBeenCalled();
+        expect(errorSpy).not.toHaveBeenCalled();
+        logSpy.mockRestore();
+        errorSpy.mockRestore();
+    });
+    it('routes warn and error through console.warn and console.error when available', () => {
+        const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => { });
+        const errorSpy = jest.spyOn(console, 'error').mockImplementation(() => { });
+        const logger = createLogger('my-plugin', { level: 'debug' });
+        logger.warn('warned');
+        logger.error('failed');
+        expect(warnSpy).toHaveBeenCalledWith('[my-plugin]', 'warned');
+        expect(errorSpy).toHaveBeenCalledWith('[my-plugin]', 'failed');
+        warnSpy.mockRestore();
+        errorSpy.mockRestore();
+    });
+    it('falls back to console.log when console.warn and console.error are unavailable', () => {
+        const logSpy = jest.spyOn(console, 'log').mockImplementation(() => { });
+        const originalWarn = console.warn;
+        const originalError = console.error;
+        // @ts-expect-error — exercise SES main-runtime fallback
+        console.warn = undefined;
+        // @ts-expect-error — exercise SES main-runtime fallback
+        console.error = undefined;
+        const logger = createLogger('my-plugin', { level: 'debug' });
+        logger.warn('warned');
+        logger.error('failed');
+        expect(logSpy).toHaveBeenCalledWith('[my-plugin]', 'warned');
+        expect(logSpy).toHaveBeenCalledWith('[my-plugin]', 'failed');
+        console.warn = originalWarn;
+        console.error = originalError;
+        logSpy.mockRestore();
+    });
+});

package/dist/storage/index.d.ts

@@ -1,2 +1,3 @@
 export { createCappedList, mergeById, type CreateCappedListOptions, type MergeByIdOptions } from './cappedList.js';
+export { arrayOf, asRecord, bool, isRecord, num, numArray, oneOf, recordOf, str, strArray } from './validate.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/storage/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,SAAS,EACT,KAAK,uBAAuB,EAC5B,KAAK,gBAAgB,EACtB,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/storage/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,SAAS,EACT,KAAK,uBAAuB,EAC5B,KAAK,gBAAgB,EACtB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,OAAO,EACP,QAAQ,EACR,IAAI,EACJ,QAAQ,EACR,GAAG,EACH,QAAQ,EACR,KAAK,EACL,QAAQ,EACR,GAAG,EACH,QAAQ,EACT,MAAM,eAAe,CAAC"}

package/dist/storage/index.js

@@ -1 +1,2 @@
 export { createCappedList, mergeById } from './cappedList.js';
+export { arrayOf, asRecord, bool, isRecord, num, numArray, oneOf, recordOf, str, strArray } from './validate.js';

package/dist/storage/validate.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Returns true when a value is a plain object record (not null, not an array).
+ *
+ * @param value - Candidate value from plugin storage.
+ */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/**
+ * Narrows an unknown storage value to a string-keyed record, or null when invalid.
+ *
+ * @param value - Raw value from plugin storage.
+ */
+export declare function asRecord(value: unknown): Record<string, unknown> | null;
+/**
+ * Returns a string when the value is a string; otherwise the fallback.
+ *
+ * @param value - Candidate field value.
+ * @param fallback - Value used when the candidate is not a string.
+ */
+export declare function str<F>(value: unknown, fallback: F): string | F;
+/**
+ * Returns a finite number when the value is a number; otherwise the fallback.
+ *
+ * @param value - Candidate field value.
+ * @param fallback - Value used when the candidate is not a finite number.
+ */
+export declare function num<F>(value: unknown, fallback: F): number | F;
+/**
+ * Returns a boolean when the value is a boolean; otherwise the fallback.
+ *
+ * @param value - Candidate field value.
+ * @param fallback - Value used when the candidate is not a boolean.
+ */
+export declare function bool<F>(value: unknown, fallback: F): boolean | F;
+/**
+ * Returns the candidate when it is one of the allowed string literals; otherwise the fallback.
+ *
+ * @param value - Candidate field value.
+ * @param allowed - Permitted string literals.
+ * @param fallback - Value used when the candidate is not in {@link allowed}.
+ */
+export declare function oneOf<T extends string, F>(value: unknown, allowed: readonly T[], fallback: F): T | F;
+/**
+ * Filters an array to finite numbers; returns an empty array when the input is not an array.
+ *
+ * @param value - Candidate array from plugin storage.
+ */
+export declare function numArray(value: unknown): number[];
+/**
+ * Filters an array to non-empty strings; returns an empty array when the input is not an array.
+ *
+ * @param value - Candidate array from plugin storage.
+ */
+export declare function strArray(value: unknown): string[];
+/**
+ * Filters an array through a type guard; returns an empty array when the input is not an array.
+ *
+ * @param value - Candidate array from plugin storage.
+ * @param guard - Predicate that narrows each element.
+ */
+export declare function arrayOf<T>(value: unknown, guard: (entry: unknown) => entry is T): T[];
+/**
+ * Builds a string-keyed record from entries that pass a type guard.
+ *
+ * Non-record inputs (including arrays) return an empty object so callers can treat
+ * malformed storage as "no data" without throwing.
+ *
+ * @param value - Raw value from plugin storage.
+ * @param guard - Predicate that narrows each property value.
+ */
+export declare function recordOf<T>(value: unknown, guard: (entry: unknown) => entry is T): Record<string, T>;
+//# sourceMappingURL=validate.d.ts.map

package/dist/storage/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/storage/validate.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzE;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAEvE;AAED;;;;;GAKG;AACH,wBAAgB,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,GAAG,MAAM,GAAG,CAAC,CAE9D;AAED;;;;;GAKG;AACH,wBAAgB,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,GAAG,MAAM,GAAG,CAAC,CAE9D;AAED;;;;;GAKG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,GAAG,OAAO,GAAG,CAAC,CAEhE;AAED;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,EACvC,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,SAAS,CAAC,EAAE,EACrB,QAAQ,EAAE,CAAC,GACV,CAAC,GAAG,CAAC,CAIP;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CAOjD;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CAKjD;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAKrF;AAED;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EACxB,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,KAAK,IAAI,CAAC,GACpC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAYnB"}