strata-storage 2.9.0 → 3.0.0

package/AI-INTEGRATION-GUIDE.md

@@ -82,7 +82,21 @@ export const storage = defineStorage({
 });
 ```
 
-## Shared storage areas — how this library identifies its own keys (2.9.0)
+## Key prefix and the 3.0.0 migration
+
+`localStorage` and `sessionStorage` keys are written under **`strata:`** as of 3.0.0
+(`DEFAULT_WEB_KEY_PREFIX`, exported). Existing data migrates itself: a miss at `strata:<key>` falls back to the bare `<key>`, and if the value is one of ours it is moved under the prefix. Per key, on read — never a bulk sweep, never a value that is not our envelope, never overwriting an existing prefixed value.
+
+🔴 **Set `keyPrefix: false` when anything outside this library reads a physical key directly** — a pre-paint theme script, a logger reading its own level. Migration keeps the data reachable through this library; it cannot fix a hard-coded reader.
+
+```typescript
+export const storage = defineStorage({ keyPrefix: false });          // pre-3.0 keys
+export const storage = defineStorage({ migrateLegacyKeys: false });  // don't adopt 2.x entries
+```
+
+`cookies` (already `strata_`), `indexedDB`, `cache`, `memory` and `url` are unchanged. `namespace` is a separate mechanism: the physical key is `<keyPrefix><namespace>:<key>`.
+
+## Shared storage areas — how this library identifies its own keys
 
 `localStorage`, `sessionStorage` and cookies are shared with every other script on the origin, and the default key prefix is empty — so a name test cannot tell our keys from theirs. **A key counts as ours only when its stored value is a `StorageValue` envelope.**
 

package/CHANGELOG.md

@@ -5,6 +5,66 @@ All notable changes to Strata Storage will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.0.0] - 2026-09-01
+
+**Breaking: the web adapters now prefix their keys with `strata:`.** One line restores the old behaviour,
+and existing data migrates itself on read — but read the migration notes before upgrading, because a
+consumer that reads a physical key from outside this library must opt out.
+
+### Breaking
+
+- **`localStorage` and `sessionStorage` keys are now written under `strata:`.** `DEFAULT_WEB_KEY_PREFIX`
+  is exported. Before this release the default prefix was the empty string, so this library's keys sat
+  unprefixed among every other script's on the origin. 2.9.0 made that *safe* — a key is ours only if its
+  value is a `StorageValue` envelope — and this makes it *tidy*, so our keys are identifiable by name too.
+  - `cookies` are unchanged: they already defaulted to `strata_`, and moving them would break existing
+    cookies for no gain.
+  - `indexedDB` and `cache` own a named store, `memory` owns its own Map, and the URL adapter already
+    prefixes its params. None of them can collide with another script's keys, so none of them change.
+  - `namespace` is a separate mechanism and is unaffected. The physical key is
+    `<keyPrefix><namespace>:<key>`.
+
+### Added
+
+- **`keyPrefix`** — set `false` (or `''`) for the pre-3.0 behaviour, or a string for your own prefix. A
+  per-adapter `adapters.localStorage.prefix` still wins over it.
+- **`migrateLegacyKeys`** (default `true`) — adopt pre-3.0 unprefixed entries on read.
+
+### Migration
+
+**Most consumers need to do nothing.** On a miss at `strata:<key>`, the adapter looks for the bare `<key>`
+and, if the value is one of ours, moves it under the prefix and returns it. Your data stays reachable.
+
+Three properties of that migration, each verified in a browser:
+
+- **It is per key, on read — never a bulk sweep.** A sweep would adopt every unprefixed envelope on the
+  origin, including keys belonging to an instance that opted out or to a sibling app still on 2.x.
+- **It never adopts a value that is not ours** — the 2.9.0 envelope check is what makes it safe at all.
+  A planted `_cltk` is left exactly where it is.
+- **It never overwrites.** A value already at the prefixed key wins and the legacy entry is left alone.
+
+🔴 **Take `keyPrefix: false` if anything outside this library reads a physical key directly** — a
+pre-paint theme script that runs before any module loads, or a logger reading its own level. Those
+readers know the exact key name, and a prefix changes it underneath them. Migration keeps the *data*
+reachable through this library; it cannot fix a hard-coded reader.
+
+```typescript
+// Frozen physical key names, or an external reader — keep 2.x behaviour:
+export const storage = defineStorage({ keyPrefix: false });
+```
+
+🔴 **Two applications sharing one origin, one still on 2.x:** set `migrateLegacyKeys: false` on the
+upgraded one, so it does not move keys the other still reads. Better, give each app a `namespace` —
+they were already colliding before this release.
+
+### Fixed
+
+- **A live timer no longer keeps a Node process alive.** `setInterval` holds the event loop open, so a
+  short-lived script — a build step, a CLI, an SSR warmup — that created an instance never exited unless
+  it also called `close()`. Measured: a script doing one `set`/`get` hung until killed at 120s, and now
+  exits immediately. All three timers (adapter TTL, cross-adapter cleanup, auto-backup) are `unref`'d;
+  it is a no-op in browsers.
+
 ## [2.9.0] - 2026-09-01
 
 Closes the entire consumer-reported issue queue — six entries from five projects (LabFlow, ClearHire,

package/README.md

@@ -32,7 +32,7 @@ integrity checksums and mirrored backups are opt-in per call or per instance.
 
 | | |
 |---|---|
-| **Version** | `2.9.0` |
+| **Version** | `3.0.0` |
 | **License** | MIT |
 | **Node** | `>=24.13.0` |
 | **Platforms** | Web · iOS · Android (via Capacitor) |
@@ -306,6 +306,8 @@ Passed to `defineStorage(config)` or `new Strata(config)`:
 | Option | Type | Default | What it does |
 |---|---|---|---|
 | `defaultStorages` | `StorageType[]` | `['localStorage', 'indexedDB', 'sessionStorage', 'memory']` | Preference order for picking the default adapter, and the fallback order when one is unusable. 🔴 **Not a registration list** — operations with no explicit `storage` (`keys`, `clear`, `size`, `subscribe`) span every *registered* adapter. To leave one out entirely use `adapters: { <name>: false }`. |
+| `keyPrefix` | `string \| false` | `'strata:'` | Key prefix for `localStorage`/`sessionStorage`. `false` restores pre-3.0 unprefixed keys — take it when anything outside this library reads a physical key directly. |
+| `migrateLegacyKeys` | `boolean` | `true` | Adopt pre-3.0 unprefixed entries on read: never a bulk sweep, never a non-envelope, never overwriting an existing prefixed value. |
 | `adapters` | `object` | `{}` | Per-adapter settings, or `false` to leave that adapter unregistered entirely. `localStorage`/`sessionStorage` take `{ prefix }`; `indexedDB` takes `{ dbName, version }`; `cookies` takes `{ secure, sameSite }`; `cache` takes `{ cacheName }`. Settings apply immediately, so they hold for `setSync`/`getSync` issued before `initialize()` resolves. |
 | `encryption` | `{ enabled, password }` | disabled | AES-GCM encryption on every write. Async path only. |
 | `compression` | `{ enabled, threshold }` | disabled | Compress values above `threshold` bytes. Async path only. |
@@ -466,16 +468,17 @@ More: [Troubleshooting](https://stratastorage-docs.aoneahsan.com/reference/troub
 - **Node support is minimal.** Only the `memory` adapter is available outside a browser, so values do not
   persist across processes.
 - **Web adapters share their storage area, and identify their own data by shape.** `localStorage`,
-  `sessionStorage` and cookies are shared with every other script on the origin, and the default key
-  prefix is empty — so a name test alone cannot tell our keys from theirs. Since `2.9.0` an adapter
-  treats a key as its own only when the stored value is a `StorageValue` envelope, so `keys()`, the TTL
-  sweep and `clear()` never touch another application's data, and a value we cannot read is skipped at
-  `debug` rather than reported as an error. **The consequence to know about:** a key written to the same
-  area by something other than this library is invisible to `keys()` by design. Call `setLogLevel('debug')`
-  to see what is being skipped and why. Setting a prefix or a namespace is still worth doing for a clean
-  keyspace — `defineStorage({ namespace: 'myapp' })`, or
-  `defineStorage({ adapters: { localStorage: { prefix: 'myapp:' } } })` — but it is no longer what keeps
-  the library off other people's keys.
+  `sessionStorage` and cookies are shared with every other script on the origin. An adapter treats a key
+  as its own only when the stored value is a `StorageValue` envelope, so `keys()`, the TTL sweep and
+  `clear()` never touch another application's data, and a value we cannot read is skipped at `debug`
+  rather than reported as an error. **The consequence to know about:** a key written to the same area by
+  something other than this library is invisible to `keys()` by design. Call `setLogLevel('debug')` to see
+  what is being skipped and why.
+- **Keys are prefixed `strata:` since 3.0.0, and that is a breaking change.** Existing data migrates
+  itself on read, so most consumers do nothing. 🔴 **But if anything outside this library reads a physical
+  key directly — a pre-paint theme script, a logger reading its own level — set
+  `defineStorage({ keyPrefix: false })`.** Migration keeps the data reachable through this library; it
+  cannot fix a hard-coded reader. See [Changelog](https://github.com/aoneahsan/strata-storage/blob/main/CHANGELOG.md).
 - **Firebase adapter names are not in the `StorageType` union.** `'firestore'` and `'realtime'` are runtime
   names, so strict TypeScript may need a cast on the options object.
 

package/dist/adapters/web/LocalStorageAdapter.d.ts

@@ -7,11 +7,32 @@ import type { StorageType, StorageCapabilities, StorageValue, ClearOptions, Size
 /**
  * Browser localStorage adapter
  */
+/**
+ * The key prefix web adapters use unless told otherwise, as of 3.0.0.
+ *
+ * 🔴 Before 3.0.0 this was the empty string, which meant this library's keys sat
+ * unprefixed among every other script's in a shared storage area. 2.9.0 made that
+ * safe (a key is ours only if its value is a `StorageValue` envelope); this makes
+ * it tidy as well, so our keys are identifiable by name too.
+ *
+ * Opt out with `defineStorage({ keyPrefix: false })` — see `StrataConfig`.
+ */
+export declare const DEFAULT_WEB_KEY_PREFIX = "strata:";
 export declare class LocalStorageAdapter extends BaseAdapter {
     readonly name: StorageType;
     readonly capabilities: StorageCapabilities;
     protected prefix: string;
     protected listeners: Map<SubscriptionCallback, (event: StorageEvent) => void>;
+    /**
+     * Whether to adopt pre-3.0 unprefixed entries on read.
+     *
+     * 🔴 Defaults to FALSE, and only `Strata` turns it on — for the adapters whose
+     * prefix it resolved. A directly constructed adapter must never adopt bare
+     * keys: `plugin/web.ts` builds a `strata_prefs_` instance beside the main one,
+     * and if that adopted every unprefixed entry it found, it would take them from
+     * the instance they belong to.
+     */
+    protected migrateLegacyKeys: boolean;
     constructor(prefix?: string);
     /**
      * Check if localStorage is available
@@ -23,7 +44,34 @@ export declare class LocalStorageAdapter extends BaseAdapter {
      */
     configure(config?: {
         prefix?: string;
+        migrateLegacyKeys?: boolean;
     }): void;
+    /**
+     * Adopt a pre-3.0 unprefixed entry for `key`, moving it under the current
+     * prefix. Returns the adopted value, or null when there is nothing to adopt.
+     *
+     * This is the whole of the 3.0.0 migration, and it is deliberately **per key,
+     * on read** rather than a bulk sweep. A sweep would adopt every unprefixed
+     * envelope on the origin — including keys belonging to another instance that
+     * opted out of the prefix, or to a sibling application still on 2.x. Adopting
+     * only what the caller actually asks for keeps the blast radius to keys this
+     * instance already uses.
+     *
+     * Three conditions, all required:
+     *  1. migration is enabled and a prefix is actually in effect (nothing to move
+     *     data *into* otherwise);
+     *  2. the legacy value is **ours** — `parseOwnValue`, the 2.9.0 shape check. It
+     *     is what makes this safe at all: with no prefix to go on, shape is the only
+     *     way to tell our data from a third party's;
+     *  3. the prefixed slot is **empty**. A value already there is authoritative, so
+     *     the legacy entry is left alone rather than overwriting newer data.
+     *
+     * It MOVES rather than copies. A copy leaves a stale duplicate that diverges the
+     * moment anything writes — a silent wrong answer, worse than a clean break. A
+     * consumer that needs the bare key to keep existing (a pre-paint script, a
+     * logger reading its own level) takes `keyPrefix: false` instead.
+     */
+    protected adoptLegacyKey<T = unknown>(key: string): StorageValue<T> | null;
     /**
      * Initialize the adapter
      */
@@ -98,6 +146,20 @@ export declare class LocalStorageAdapter extends BaseAdapter {
         fullKey: string;
         value: StorageValue;
     }>;
+    /**
+     * Remove an entry `ownKeys()` returned, by its PHYSICAL key.
+     *
+     * 🔴 Not `removeSync(key)`. That rebuilds the physical key as `prefix + key`,
+     * which is wrong for a pre-3.0 legacy entry — those live at the bare key, so
+     * `ownKeys()` reports `fullKey === key` for them. Rebuilding would delete
+     * `strata:<key>` instead and leave the legacy entry behind, so `clear()` and
+     * the expiry sweep would silently skip exactly the entries not yet migrated.
+     */
+    protected removeOwnedEntry(entry: {
+        key: string;
+        fullKey: string;
+        value: StorageValue;
+    }): void;
     /**
      * Reclaim expired entries, returning how many were removed.
      *

package/dist/adapters/web/LocalStorageAdapter.js

@@ -9,6 +9,17 @@ import { logger } from "../../utils/logger.js";
 /**
  * Browser localStorage adapter
  */
+/**
+ * The key prefix web adapters use unless told otherwise, as of 3.0.0.
+ *
+ * 🔴 Before 3.0.0 this was the empty string, which meant this library's keys sat
+ * unprefixed among every other script's in a shared storage area. 2.9.0 made that
+ * safe (a key is ours only if its value is a `StorageValue` envelope); this makes
+ * it tidy as well, so our keys are identifiable by name too.
+ *
+ * Opt out with `defineStorage({ keyPrefix: false })` — see `StrataConfig`.
+ */
+export const DEFAULT_WEB_KEY_PREFIX = 'strata:';
 export class LocalStorageAdapter extends BaseAdapter {
     name = 'localStorage';
     capabilities = {
@@ -24,7 +35,17 @@ export class LocalStorageAdapter extends BaseAdapter {
     };
     prefix;
     listeners = new Map();
-    constructor(prefix = '') {
+    /**
+     * Whether to adopt pre-3.0 unprefixed entries on read.
+     *
+     * 🔴 Defaults to FALSE, and only `Strata` turns it on — for the adapters whose
+     * prefix it resolved. A directly constructed adapter must never adopt bare
+     * keys: `plugin/web.ts` builds a `strata_prefs_` instance beside the main one,
+     * and if that adopted every unprefixed entry it found, it would take them from
+     * the instance they belong to.
+     */
+    migrateLegacyKeys = false;
+    constructor(prefix = DEFAULT_WEB_KEY_PREFIX) {
         super();
         this.prefix = prefix;
     }
@@ -54,6 +75,70 @@ export class LocalStorageAdapter extends BaseAdapter {
         if (config?.prefix !== undefined) {
             this.prefix = config.prefix;
         }
+        if (config?.migrateLegacyKeys !== undefined) {
+            this.migrateLegacyKeys = config.migrateLegacyKeys;
+        }
+    }
+    /**
+     * Adopt a pre-3.0 unprefixed entry for `key`, moving it under the current
+     * prefix. Returns the adopted value, or null when there is nothing to adopt.
+     *
+     * This is the whole of the 3.0.0 migration, and it is deliberately **per key,
+     * on read** rather than a bulk sweep. A sweep would adopt every unprefixed
+     * envelope on the origin — including keys belonging to another instance that
+     * opted out of the prefix, or to a sibling application still on 2.x. Adopting
+     * only what the caller actually asks for keeps the blast radius to keys this
+     * instance already uses.
+     *
+     * Three conditions, all required:
+     *  1. migration is enabled and a prefix is actually in effect (nothing to move
+     *     data *into* otherwise);
+     *  2. the legacy value is **ours** — `parseOwnValue`, the 2.9.0 shape check. It
+     *     is what makes this safe at all: with no prefix to go on, shape is the only
+     *     way to tell our data from a third party's;
+     *  3. the prefixed slot is **empty**. A value already there is authoritative, so
+     *     the legacy entry is left alone rather than overwriting newer data.
+     *
+     * It MOVES rather than copies. A copy leaves a stale duplicate that diverges the
+     * moment anything writes — a silent wrong answer, worse than a clean break. A
+     * consumer that needs the bare key to keep existing (a pre-paint script, a
+     * logger reading its own level) takes `keyPrefix: false` instead.
+     */
+    adoptLegacyKey(key) {
+        if (!this.migrateLegacyKeys || !this.prefix)
+            return null;
+        // A key already carrying our prefix is not a legacy key.
+        if (key.startsWith(this.prefix))
+            return null;
+        let storage;
+        try {
+            storage = this.getStorage();
+        }
+        catch {
+            return null;
+        }
+        const raw = storage.getItem(key);
+        if (raw === null)
+            return null;
+        const value = this.parseOwnValue(raw, key);
+        if (!value)
+            return null;
+        if (storage.getItem(this.prefix + key) !== null) {
+            logger.debug(`${this.name}: legacy key "${key}" not adopted — "${this.prefix}${key}" already exists and wins.`);
+            return null;
+        }
+        try {
+            storage.setItem(this.prefix + key, raw);
+            storage.removeItem(key);
+        }
+        catch (error) {
+            // Out of quota, or the area turned read-only mid-flight. The legacy entry
+            // is still intact and still readable, so report and return it.
+            logger.warn(`${this.name}: could not migrate legacy key "${key}":`, error);
+            return value;
+        }
+        logger.debug(`${this.name}: migrated legacy key "${key}" to "${this.prefix}${key}".`);
+        return value;
     }
     /**
      * Initialize the adapter
@@ -115,7 +200,8 @@ export class LocalStorageAdapter extends BaseAdapter {
         }
         // A value that is not our envelope belongs to somebody else sharing this
         // area. parseOwnValue() logs it at debug and returns null — never an error.
-        const value = this.parseOwnValue(item, key);
+        // A miss falls through to a pre-3.0 unprefixed entry, if there is one.
+        const value = this.parseOwnValue(item, key) ?? this.adoptLegacyKey(key);
         if (!value)
             return null;
         if (this.isExpired(value)) {
@@ -200,7 +286,8 @@ export class LocalStorageAdapter extends BaseAdapter {
         // Iterates owned entries INCLUDING expired ones: `expiredOnly` filters on
         // exactly the entries `keysSync()` leaves out, so driving this loop from
         // `keysSync()` made that option a guaranteed no-op.
-        for (const { key, value } of this.ownKeys(true)) {
+        for (const entry of this.ownKeys(true)) {
+            const { key, value } = entry;
             let shouldDelete = true;
             const pattern = options.pattern || options.prefix;
             if (pattern) {
@@ -215,7 +302,7 @@ export class LocalStorageAdapter extends BaseAdapter {
                 shouldDelete = false;
             }
             if (shouldDelete) {
-                this.removeSync(key);
+                this.removeOwnedEntry(entry);
             }
         }
     }
@@ -243,6 +330,7 @@ export class LocalStorageAdapter extends BaseAdapter {
     ownKeys(includeExpired = false) {
         const storage = this.getStorage();
         const owned = [];
+        const seen = new Set();
         for (let i = 0; i < storage.length; i++) {
             const fullKey = storage.key(i);
             if (!fullKey?.startsWith(this.prefix))
@@ -253,10 +341,48 @@ export class LocalStorageAdapter extends BaseAdapter {
                 continue;
             if (!includeExpired && this.isExpired(value))
                 continue;
+            seen.add(key);
             owned.push({ key, fullKey, value });
         }
+        // Pre-3.0 unprefixed entries are still ours and must appear here, or `keys()`,
+        // `clear()` and `size()` would silently omit everything not yet read back
+        // (adoption is per-read, so a freshly upgraded app has migrated nothing yet).
+        //
+        // 🔴 Listing is NOT adopting. Enumerating must not move data — a `keys()` call
+        // is a question, not a write — so these are reported at their real physical
+        // key and migrate only when actually read. A prefixed entry for the same
+        // logical key always wins, so upgraded keys are never listed twice.
+        if (this.migrateLegacyKeys && this.prefix) {
+            for (let i = 0; i < storage.length; i++) {
+                const fullKey = storage.key(i);
+                if (!fullKey || fullKey.startsWith(this.prefix) || seen.has(fullKey))
+                    continue;
+                const value = this.parseOwnValue(storage.getItem(fullKey), fullKey);
+                if (!value)
+                    continue;
+                if (!includeExpired && this.isExpired(value))
+                    continue;
+                seen.add(fullKey);
+                owned.push({ key: fullKey, fullKey, value });
+            }
+        }
         return owned;
     }
+    /**
+     * Remove an entry `ownKeys()` returned, by its PHYSICAL key.
+     *
+     * 🔴 Not `removeSync(key)`. That rebuilds the physical key as `prefix + key`,
+     * which is wrong for a pre-3.0 legacy entry — those live at the bare key, so
+     * `ownKeys()` reports `fullKey === key` for them. Rebuilding would delete
+     * `strata:<key>` instead and leave the legacy entry behind, so `clear()` and
+     * the expiry sweep would silently skip exactly the entries not yet migrated.
+     */
+    removeOwnedEntry(entry) {
+        this.getStorage().removeItem(entry.fullKey);
+        if (this.hasChangeListeners()) {
+            this.emitChange(entry.key, entry.value.value, undefined, 'local');
+        }
+    }
     /**
      * Reclaim expired entries, returning how many were removed.
      *
@@ -269,9 +395,9 @@ export class LocalStorageAdapter extends BaseAdapter {
      */
     async cleanupExpired() {
         let removed = 0;
-        for (const { key, value } of this.ownKeys(true)) {
-            if (this.isExpired(value)) {
-                this.removeSync(key);
+        for (const entry of this.ownKeys(true)) {
+            if (this.isExpired(entry.value)) {
+                this.removeOwnedEntry(entry);
                 removed++;
             }
         }

package/dist/core/BaseAdapter.js

@@ -45,6 +45,13 @@ export class BaseAdapter {
                 logger.error(`TTL cleanup error in ${this.name}:`, error);
             }
         }, this.ttlCheckInterval);
+        // 🔴 Do not hold a Node process open. An outstanding interval keeps the event
+        // loop alive, so a short-lived script — a build step, a CLI, an SSR warmup —
+        // that creates an instance and finishes its work never exits unless it also
+        // calls close(). `unref` does not exist in browsers (setInterval returns a
+        // number there), so the optional call is simply a no-op; in Node the timer
+        // keeps working for as long as the process does.
+        this.ttlCleanupInterval.unref?.();
     }
     /**
      * Stop TTL cleanup

package/dist/core/Strata.d.ts

@@ -320,7 +320,27 @@ export declare class Strata {
      * ```
      */
     registerAdapter(adapter: StorageAdapter): void;
-    /** The configured options for one adapter, or undefined when it has none. */
+    /**
+     * Web adapters that share their storage area with every other script on the
+     * origin, and therefore take the instance-wide `keyPrefix`.
+     *
+     * Cookies are excluded deliberately: they already default to `strata_`, so
+     * moving them would break existing cookies for no gain. IndexedDB and the Cache
+     * API own a named store, memory owns its own Map, and the URL adapter already
+     * prefixes its params — none of them can collide with another script's keys.
+     */
+    private static readonly PREFIXED_WEB_ADAPTERS;
+    /**
+     * The configured options for one adapter, or undefined when it has none.
+     *
+     * For the shared-area web adapters this also resolves the 3.0.0 key prefix and
+     * decides whether that adapter may adopt pre-3.0 unprefixed entries. Precedence,
+     * and it lives only here:
+     *
+     *   1. `adapters.<name>.prefix` — the most specific thing the caller wrote
+     *   2. `keyPrefix` — the instance-wide switch (`false` restores 2.x behaviour)
+     *   3. the adapter's own constructor default (`DEFAULT_WEB_KEY_PREFIX`)
+     */
     private adapterConfigFor;
     /** Push the configured options into an adapter synchronously. */
     private applyAdapterConfig;

package/dist/core/Strata.js

@@ -116,6 +116,9 @@ export class Strata {
             this._ttlCleanupTimer = setInterval(() => {
                 void this.cleanupAllAdapters();
             }, interval);
+            // See BaseAdapter.startTTLCleanup — a live interval must not keep a Node
+            // process alive. No-op in browsers.
+            this._ttlCleanupTimer.unref?.();
         }
         // Start periodic auto-backup if configured
         if (this.config.autoBackup?.interval) {
@@ -1304,10 +1307,49 @@ export class Strata {
         // to it did not reach the sync path.
         this.applyAdapterConfig(adapter);
     }
-    /** The configured options for one adapter, or undefined when it has none. */
+    /**
+     * Web adapters that share their storage area with every other script on the
+     * origin, and therefore take the instance-wide `keyPrefix`.
+     *
+     * Cookies are excluded deliberately: they already default to `strata_`, so
+     * moving them would break existing cookies for no gain. IndexedDB and the Cache
+     * API own a named store, memory owns its own Map, and the URL adapter already
+     * prefixes its params — none of them can collide with another script's keys.
+     */
+    static PREFIXED_WEB_ADAPTERS = new Set([
+        'localStorage',
+        'sessionStorage',
+    ]);
+    /**
+     * The configured options for one adapter, or undefined when it has none.
+     *
+     * For the shared-area web adapters this also resolves the 3.0.0 key prefix and
+     * decides whether that adapter may adopt pre-3.0 unprefixed entries. Precedence,
+     * and it lives only here:
+     *
+     *   1. `adapters.<name>.prefix` — the most specific thing the caller wrote
+     *   2. `keyPrefix` — the instance-wide switch (`false` restores 2.x behaviour)
+     *   3. the adapter's own constructor default (`DEFAULT_WEB_KEY_PREFIX`)
+     */
     adapterConfigFor(name) {
         const raw = this.config.adapters?.[name];
-        return typeof raw === 'object' && raw !== null ? raw : undefined;
+        const explicit = typeof raw === 'object' && raw !== null ? { ...raw } : undefined;
+        if (!Strata.PREFIXED_WEB_ADAPTERS.has(name))
+            return explicit;
+        const resolved = explicit ?? {};
+        // Only fill in the prefix when the caller did not name one for this adapter.
+        if (resolved.prefix === undefined && this.config.keyPrefix !== undefined) {
+            resolved.prefix = this.config.keyPrefix === false ? '' : this.config.keyPrefix;
+        }
+        // 🔴 Migration is enabled HERE and nowhere else — only for an adapter whose
+        // prefix this instance resolved. A directly constructed adapter must never
+        // adopt bare keys: `plugin/web.ts` builds a `strata_prefs_` instance beside
+        // the main one, and if that adopted every unprefixed entry it found it would
+        // take them from the instance they belong to.
+        if (resolved.migrateLegacyKeys === undefined) {
+            resolved.migrateLegacyKeys = this.config.migrateLegacyKeys !== false;
+        }
+        return resolved;
     }
     /** Push the configured options into an adapter synchronously. */
     applyAdapterConfig(adapter) {
@@ -1678,6 +1720,7 @@ export class Strata {
                 }
             })();
         }, cfg.interval);
+        this._autoBackupTimer.unref?.();
     }
     async selectAdapter(storage) {
         await this.ensureReady();

package/dist/index.d.ts

@@ -8,6 +8,7 @@ export { CookieAdapter } from "./adapters/web/CookieAdapter.js";
 export { CacheAdapter } from "./adapters/web/CacheAdapter.js";
 export { MemoryAdapter } from "./adapters/web/MemoryAdapter.js";
 export { URLAdapter, type URLAdapterConfig } from "./adapters/web/URLAdapter.js";
+export { DEFAULT_WEB_KEY_PREFIX } from "./adapters/web/LocalStorageAdapter.js";
 export { EncryptionManager } from "./features/encryption.js";
 export { CompressionManager } from "./features/compression.js";
 export { TTLManager } from "./features/ttl.js";

package/dist/index.js

@@ -10,6 +10,7 @@ export { CookieAdapter } from "./adapters/web/CookieAdapter.js";
 export { CacheAdapter } from "./adapters/web/CacheAdapter.js";
 export { MemoryAdapter } from "./adapters/web/MemoryAdapter.js";
 export { URLAdapter } from "./adapters/web/URLAdapter.js";
+export { DEFAULT_WEB_KEY_PREFIX } from "./adapters/web/LocalStorageAdapter.js";
 // Core features
 export { EncryptionManager } from "./features/encryption.js";
 export { CompressionManager } from "./features/compression.js";

package/dist/types/index.d.ts

@@ -308,6 +308,38 @@ export interface StrataConfig {
      * Default storage types in order of preference
      */
     defaultStorages?: StorageType[];
+    /**
+     * Key prefix for the web adapters that share a storage area with every other
+     * script on the origin (`localStorage`, `sessionStorage`).
+     *
+     * Defaults to `'strata:'` as of 3.0.0. Set `false` (or `''`) for the pre-3.0
+     * behaviour of writing to the bare key.
+     *
+     * 🔴 **Take the opt-out when anything outside this library reads a physical key
+     * directly** — a pre-paint theme script that runs before any module loads, or a
+     * logger reading its own level. Those readers know the exact key name, and a
+     * prefix changes it underneath them. `migrateLegacyKeys` keeps the *data*
+     * reachable through this library, but it cannot fix a hard-coded reader.
+     *
+     * Composes with `namespace`, which is a separate mechanism and unaffected:
+     * the physical key is `<keyPrefix><namespace>:<key>`. A per-adapter
+     * `adapters.localStorage.prefix` overrides this for that adapter.
+     */
+    keyPrefix?: string | false;
+    /**
+     * Whether the shared-area web adapters may adopt pre-3.0 unprefixed entries.
+     * Default `true`.
+     *
+     * Migration is per key and happens on read: a miss at the prefixed key falls
+     * back to the bare key, and if the value is one of ours it is moved under the
+     * prefix. It never overwrites an existing prefixed value, and it never adopts a
+     * value that is not a `StorageValue` envelope — which is what stops it taking
+     * another application's keys.
+     *
+     * Set `false` when two applications share an origin and one of them is still on
+     * 2.x, so that upgrading one does not move keys the other still reads.
+     */
+    migrateLegacyKeys?: boolean;
     /**
      * Adapter configuration
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "strata-storage",
-  "version": "2.9.0",
+  "version": "3.0.0",
   "description": "One storage API across web, iOS and Android — zero runtime dependencies.",
   "type": "module",
   "packageManager": "yarn@4.17.0",