@civitai/sdk 0.6.0 → 0.7.0

package/README.md

@@ -374,6 +374,91 @@ not exported, because four of the five fleet apps that store per-viewer state
 need knobs it does not have (injected latency, prefix-targeted refusals, quota
 overrides, a cursor it ignores, a read that never settles). Copy it if it helps.
 
+## Web storage in a block
+
+A block is framed at an **opaque origin**: civitai's `intersectSandbox` adds
+`allow-same-origin` only for the `internal` and `verified` trust tiers, and in
+v1 every approved block is `unverified`. There, `localStorage` and
+`sessionStorage` do not merely come back empty — *reading the property throws*:
+
+```
+SecurityError: Failed to read the 'localStorage' property from 'Window':
+The document is sandboxed and lacks the 'allow-same-origin' flag.
+```
+
+Guarding your own call sites is not enough, because a dependency that touches
+storage while its module body evaluates takes the app down before any of your
+code runs — and libraries routinely mislabel the failure as something else.
+
+So the package ships a repair behind its own subpath. Importing
+`@civitai/sdk/safe-storage` installs a spec-shaped in-memory `Storage` over any
+web-storage global that is present but unusable. It is inert where storage works
+and where there is none at all (Node/SSR/workers), and it never replaces a
+healthy store.
+
+🔴 **This is not automatic. Add the import yourself, as the first import in your
+entry module** — `import '@civitai/sdk'` on its own installs nothing:
+
+```
+import '@civitai/sdk/safe-storage'; // side-effect import; keep it FIRST
+import 'some-library-that-reads-localStorage';
+```
+
+The import *is* the install, so for most blocks that line is the whole of it.
+There is nothing to configure. The subpath does export two functions, for the
+cases the import alone cannot cover:
+
+- `installSafeStorage(scope?)` — run the repair at a *specific moment* rather
+  than at module-evaluation time. The one that matters: immediately before an
+  `await import('some-lib')` that reads storage while evaluating. A hoisted
+  static import cannot be placed "after" anything, so a dynamic import is the
+  case the side-effect line does not solve. Returns which globals it replaced.
+- `createMemoryStorage()` — the spec-shaped in-memory `Storage` itself, if you
+  want one without touching any global.
+
+Two things about that line:
+
+- **First is the whole point.** ES imports are hoisted and evaluated in order,
+  so a storage-touching dependency imported *above* this one still evaluates
+  first and nothing can reach it in time. Put it above every other import,
+  including your framework's.
+- **It is a side-effect-only import, so bundlers must be told to keep it.** The
+  package declares a `sideEffects` allowlist naming
+  `./dist/safe-storage/index.js` for exactly that reason; `sideEffects: false`
+  would license every bundler to drop it. The package root
+  (`./dist/index.js`) is deliberately *not* in that allowlist — it is pure
+  re-exports and stays fully tree-shakeable.
+
+### Two things "inert where storage works" hides
+
+Both only ever happen at a **real** origin — neither can occur in the block
+sandbox this subpath exists for.
+
+- **It writes a probe key.** Classifying a store means a real round trip, so at
+  import each of `localStorage` and `sessionStorage` gets one
+  `setItem('__civitai_app_sdk_storage_probe__', '1')` followed immediately by
+  `removeItem`. Net contents are unchanged and neither store object is replaced
+  — but per the Web Storage spec each write queues a `storage` event in the
+  other documents sharing the store, so a cross-tab listener that does not
+  filter by key will see spurious events.
+- **A FULL store counts as broken.** The write probe cannot tell "quota
+  exhausted" from "storage disabled" — a `QuotaExceededError` classifies the
+  store as unusable, and the repair swaps in the in-memory fallback, seeded
+  first from every entry it could still read. Nothing readable is lost, but the
+  store stops persisting: writes after that point are session-scoped and gone
+  on reload. In a block that is the honest semantic regardless. In an app at a
+  real origin with a full `localStorage`, it is a downgrade from persistent to
+  session-scoped that you opted into by importing this subpath.
+
+A block built on `@civitai/app-sdk/blocks` already gets this: that entry imports
+its own copy (`@civitai/app-sdk/safe-storage`). A block that has finished porting
+to `@civitai/sdk` imports neither, which is why this line exists.
+
+The fallback is session-scoped — nothing survives a reload, which is the honest
+semantic at an opaque origin, since there is no origin to persist against. Treat
+web storage in a block as a cache, never a source of truth. The durable
+per-viewer store is [app storage](#app-storage).
+
 ## Checks
 
 - `npm run api` regenerates [`api/public-api.md`](./api/public-api.md) from the

package/dist/index.js

@@ -2,6 +2,17 @@
  * `const app = await initialize()`, then `app.site`, `app.orchestration` and,
  * inside a civitai.com page, `app.host`. Outside one, `createSignIn()` gets the token.
  */
+// 🔴 NOTHING IS IMPORTED FOR SIDE EFFECTS HERE, on purpose. This entry is pure
+// re-exports, so `./dist/index.js` stays droppable and `import '@civitai/sdk'`
+// stays inert in Node/SSR.
+//
+// The opaque-origin web-storage repair lives behind its own subpath,
+// `@civitai/sdk/safe-storage` (`./safe-storage/index.ts`), and a block opts in
+// with one line at the top of its entry module. Installing it from here would
+// make every consumer of this package — server runtimes included — pay a side
+// effect it never asked for, and would still not fix the ordering problem: a
+// storage-touching dependency imported ABOVE `@civitai/sdk` evaluates first
+// either way. See the README's "Web storage in a block".
 export { initialize } from './app/index.js';
 export { createSignIn, SignInError } from './sign-in/index.js';
 export { SCOPES } from './session/index.js';

package/dist/safe-storage/index.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Survive an opaque-origin sandbox. Published as the side-effect subpath
+ * `@civitai/sdk/safe-storage`; a block opts in with `import
+ * '@civitai/sdk/safe-storage';` as the first line of its entry module. The
+ * package root does NOT import it — see `src/index.ts`.
+ *
+ * 🔴 **This is a deliberate independent COPY of `@civitai/app-sdk`'s
+ * `src/safe-storage/index.ts`, not a shared module.** The two packages are
+ * separate codebases (`@civitai/sdk` succeeds `@civitai/app-sdk`) and must not
+ * depend on each other — a successor that imports its predecessor would drag
+ * the whole 0.x surface back in. The duplication is the price of that
+ * independence. The two bodies are held byte-identical modulo comments by
+ * `tests/guards/safe-storage-copy-parity.test.mjs`, so a fix to one goes red
+ * until it is applied to the other — do not rely on remembering.
+ *
+ * Why this has to exist here at all: a block that has finished porting to
+ * `@civitai/sdk` no longer imports `@civitai/app-sdk/blocks`, which is what
+ * used to install the shim. `civitai-app-requests` is exactly that shape today
+ * — its only remaining `@civitai/app-sdk/blocks` import is in a test file — so
+ * without this module its shipped bundle has no repair at all.
+ *
+ * Civitai Apps run in an iframe sandboxed as `allow-scripts allow-forms`,
+ * deliberately WITHOUT `allow-same-origin` (see civitai's
+ * `src/components/AppBlocks/sandbox.ts`: `intersectSandbox` adds
+ * `allow-same-origin` only for the `internal`/`verified` trust tiers, and in v1
+ * every approved block is `unverified`). The document therefore has an
+ * **opaque origin**, and there is no origin to key web storage against, so the
+ * platform does not merely return an empty store — merely *reading* the
+ * property throws:
+ *
+ *   SecurityError: Failed to read the 'localStorage' property from 'Window':
+ *   The document is sandboxed and lacks the 'allow-same-origin' flag.
+ *
+ * Guarding your own call sites is not enough: any third-party dependency that
+ * touches storage unguarded takes the whole app down, and libraries routinely
+ * *mislabel* the failure. A real production example — Photo Sphere Viewer's
+ * `SYSTEM.load()` runs an unguarded ``TOUCH_KEY in localStorage`` touch probe,
+ * its `Viewer` constructor catches the resulting SecurityError, reports the
+ * generic "Your browser does not seem to support WebGL", and returns without
+ * rethrowing. The app's own fallback never ran and users with perfectly good
+ * GPUs saw a WebGL error. (The sandbox does not block WebGL — only storage.)
+ *
+ * So this module installs a spec-shaped in-memory `Storage` over any
+ * `localStorage`/`sessionStorage` that is present but unusable. Importing it
+ * runs the install (see the bottom of the file).
+ *
+ * The fallback is session-scoped — nothing survives a reload — which is the
+ * honest semantic at an opaque origin: there is no origin to persist against.
+ * Treat storage in a block as a cache, never a source of truth; the durable
+ * per-user store is the platform's app-storage API.
+ */
+/** Which globals a call to {@link installSafeStorage} actually replaced. */
+export interface SafeStorageInstallResult {
+    /** `true` when `localStorage` was replaced by the in-memory fallback. */
+    localStorage: boolean;
+    /** `true` when `sessionStorage` was replaced by the in-memory fallback. */
+    sessionStorage: boolean;
+}
+declare const STORAGE_NAMES: readonly ['localStorage', 'sessionStorage'];
+/** The web-storage globals this module can repair. */
+export type SafeStorageName = (typeof STORAGE_NAMES)[number];
+/**
+ * A `Storage` work-alike backed by a `Map`.
+ *
+ * Implemented as a **Proxy, not a class**, because real `Storage` is an exotic
+ * object: `s.foo = 1`, `'foo' in s`, `s.foo` and `delete s.foo` are aliases for
+ * `setItem`/`getItem`/`removeItem`. Libraries use exactly that form (PSV's
+ * touch probe is literally ``KEY in localStorage`` then
+ * `localStorage[KEY] === 'true'`), so a plain class would still break them.
+ */
+export declare function createMemoryStorage(): Storage;
+/**
+ * Replace any present-but-unusable `localStorage`/`sessionStorage` on `scope`
+ * with an in-memory `Storage`, so third-party code that touches it unguarded
+ * cannot throw.
+ *
+ * - **No-op where storage works — but not a no-TOUCH.** A healthy `Storage` is
+ *   never replaced and its contents are unchanged, but it *is* written to:
+ *   classifying it means a real round trip, so each of `localStorage` and
+ *   `sessionStorage` gets `setItem('__civitai_app_sdk_storage_probe__', '1')`
+ *   immediately followed by `removeItem`. MEASURED against the built artifact
+ *   with instrumented healthy stores: exactly those four operations, the store
+ *   objects not replaced, contents identical before and after. Per the Web
+ *   Storage spec every one of those writes queues a `storage` event in the
+ *   *other* documents that share the store, so at a REAL origin a cross-tab
+ *   listener that does not filter by key sees spurious events (the two
+ *   `localStorage` writes are the ones another tab receives). At the opaque
+ *   origin this module exists for there is no other same-origin document, so
+ *   there is nothing to receive them.
+ * - **No-op where storage is absent** (Node/SSR/workers). Nothing is invented.
+ * - **Never loses readable data.** When the old store reads but refuses writes
+ *   (full / disabled), its entries are copied into the fallback first, so the
+ *   shim cannot shadow a live session.
+ * - **Idempotent.** Once the fallback is installed the round-trip probe
+ *   succeeds, so a second call is a no-op and values already written survive.
+ * - **Never throws.** Every step is guarded; a shim that could fail at import
+ *   would be a worse outage than the bug it fixes.
+ *
+ * This module installs on import, so most apps never need to call it. Call it
+ * explicitly when you want the guarantee at a specific moment — e.g. right
+ * before `await import('some-lib')` that reads storage while evaluating.
+ *
+ * @param scope Object carrying the storage globals. Defaults to `globalThis`.
+ */
+export declare function installSafeStorage(scope?: object): SafeStorageInstallResult;
+export {};

package/dist/safe-storage/index.js

@@ -0,0 +1,374 @@
+/**
+ * Survive an opaque-origin sandbox. Published as the side-effect subpath
+ * `@civitai/sdk/safe-storage`; a block opts in with `import
+ * '@civitai/sdk/safe-storage';` as the first line of its entry module. The
+ * package root does NOT import it — see `src/index.ts`.
+ *
+ * 🔴 **This is a deliberate independent COPY of `@civitai/app-sdk`'s
+ * `src/safe-storage/index.ts`, not a shared module.** The two packages are
+ * separate codebases (`@civitai/sdk` succeeds `@civitai/app-sdk`) and must not
+ * depend on each other — a successor that imports its predecessor would drag
+ * the whole 0.x surface back in. The duplication is the price of that
+ * independence. The two bodies are held byte-identical modulo comments by
+ * `tests/guards/safe-storage-copy-parity.test.mjs`, so a fix to one goes red
+ * until it is applied to the other — do not rely on remembering.
+ *
+ * Why this has to exist here at all: a block that has finished porting to
+ * `@civitai/sdk` no longer imports `@civitai/app-sdk/blocks`, which is what
+ * used to install the shim. `civitai-app-requests` is exactly that shape today
+ * — its only remaining `@civitai/app-sdk/blocks` import is in a test file — so
+ * without this module its shipped bundle has no repair at all.
+ *
+ * Civitai Apps run in an iframe sandboxed as `allow-scripts allow-forms`,
+ * deliberately WITHOUT `allow-same-origin` (see civitai's
+ * `src/components/AppBlocks/sandbox.ts`: `intersectSandbox` adds
+ * `allow-same-origin` only for the `internal`/`verified` trust tiers, and in v1
+ * every approved block is `unverified`). The document therefore has an
+ * **opaque origin**, and there is no origin to key web storage against, so the
+ * platform does not merely return an empty store — merely *reading* the
+ * property throws:
+ *
+ *   SecurityError: Failed to read the 'localStorage' property from 'Window':
+ *   The document is sandboxed and lacks the 'allow-same-origin' flag.
+ *
+ * Guarding your own call sites is not enough: any third-party dependency that
+ * touches storage unguarded takes the whole app down, and libraries routinely
+ * *mislabel* the failure. A real production example — Photo Sphere Viewer's
+ * `SYSTEM.load()` runs an unguarded ``TOUCH_KEY in localStorage`` touch probe,
+ * its `Viewer` constructor catches the resulting SecurityError, reports the
+ * generic "Your browser does not seem to support WebGL", and returns without
+ * rethrowing. The app's own fallback never ran and users with perfectly good
+ * GPUs saw a WebGL error. (The sandbox does not block WebGL — only storage.)
+ *
+ * So this module installs a spec-shaped in-memory `Storage` over any
+ * `localStorage`/`sessionStorage` that is present but unusable. Importing it
+ * runs the install (see the bottom of the file).
+ *
+ * The fallback is session-scoped — nothing survives a reload — which is the
+ * honest semantic at an opaque origin: there is no origin to persist against.
+ * Treat storage in a block as a cache, never a source of truth; the durable
+ * per-user store is the platform's app-storage API.
+ */
+const STORAGE_NAMES = ['localStorage', 'sessionStorage'];
+const PROBE_KEY = '__civitai_app_sdk_storage_probe__';
+/**
+ * A `Storage` work-alike backed by a `Map`.
+ *
+ * Implemented as a **Proxy, not a class**, because real `Storage` is an exotic
+ * object: `s.foo = 1`, `'foo' in s`, `s.foo` and `delete s.foo` are aliases for
+ * `setItem`/`getItem`/`removeItem`. Libraries use exactly that form (PSV's
+ * touch probe is literally ``KEY in localStorage`` then
+ * `localStorage[KEY] === 'true'`), so a plain class would still break them.
+ */
+export function createMemoryStorage() {
+    const map = new Map();
+    const api = {
+        getItem(key) {
+            const k = String(key);
+            return map.has(k) ? map.get(k) : null;
+        },
+        setItem(key, value) {
+            map.set(String(key), String(value));
+        },
+        removeItem(key) {
+            map.delete(String(key));
+        },
+        clear() {
+            map.clear();
+        },
+        key(index) {
+            return Array.from(map.keys())[index] ?? null;
+        },
+        get length() {
+            return map.size;
+        },
+    };
+    // `Reflect.has` walks the prototype chain, so `'toString' in storage` stays
+    // true exactly as it is for a real Storage instance. Only keys that are NOT
+    // part of the Storage API fall through to the backing map.
+    const isApiKey = (prop) => typeof prop === 'symbol' || Reflect.has(api, prop);
+    return new Proxy(api, {
+        get(target, prop, receiver) {
+            if (isApiKey(prop))
+                return Reflect.get(target, prop, receiver);
+            return map.get(prop);
+        },
+        set(target, prop, value, receiver) {
+            if (isApiKey(prop))
+                return Reflect.set(target, prop, value, receiver);
+            map.set(prop, String(value));
+            return true;
+        },
+        has(_target, prop) {
+            return isApiKey(prop) || map.has(prop);
+        },
+        deleteProperty(_target, prop) {
+            // `delete storage.getItem` must NOT destroy the method, and
+            // `delete storage.length` must NOT leave `length` undefined — a
+            // `for (i < storage.length)` loop would then silently iterate zero
+            // times. Real `Storage` is unbothered: its API lives on
+            // `Storage.prototype`, so deleting it from the instance finds no own
+            // property, reports success and changes nothing. Mirror that exactly.
+            if (isApiKey(prop))
+                return true;
+            map.delete(prop);
+            return true;
+        },
+        // Enumeration sees only stored keys — matching real Storage, where
+        // `Object.keys(localStorage)` lists the entries, not the methods.
+        ownKeys() {
+            return Array.from(map.keys());
+        },
+        // A non-extensible target would make the `ownKeys` trap above violate a
+        // proxy invariant (it must then report every own key of the target), so a
+        // single `Object.freeze(localStorage)` — from a SES/`harden()` lockdown
+        // sweep, say — would make `Object.keys` / spread / `JSON.stringify` /
+        // `for...in` throw on this object FOREVER. Refusing keeps enumeration
+        // alive and matches the platform: `Storage` is a legacy platform object
+        // with a named-property handler, whose `[[PreventExtensions]]` also
+        // returns false.
+        preventExtensions: () => false,
+        getOwnPropertyDescriptor(target, prop) {
+            if (!isApiKey(prop) && map.has(prop)) {
+                return {
+                    value: map.get(prop),
+                    writable: true,
+                    enumerable: true,
+                    configurable: true,
+                };
+            }
+            return Reflect.getOwnPropertyDescriptor(target, prop);
+        },
+    });
+}
+/**
+ * Is `scope[name]` Node's *disabled* web-storage stub?
+ *
+ * Node >= 22 defines `globalThis.localStorage` / `sessionStorage` as lazy
+ * accessors. Without `--localstorage-file` they return `undefined` **and emit
+ * `ExperimentalWarning: localStorage is not available because
+ * --localstorage-file was not provided.` on every read** — so importing this
+ * module would print that on every server boot and in CI. `in` does not trip
+ * the warning, but it does report `true` there, so existence alone is not
+ * enough to skip the read.
+ *
+ * Both signals must agree, and anything ambiguous falls through to a real
+ * probe:
+ *
+ * 1. we are running on Node;
+ * 2. the property is an **own, non-enumerable accessor with a setter** —
+ *    Node's replaceable global. The web platform can never match this:
+ *    `Window.localStorage` is a WebIDL *readonly* attribute, so it is
+ *    `enumerable: true` with `set: undefined`, in a sandbox exactly as much as
+ *    anywhere else. That is a spec guarantee, not a guess, and it is why the
+ *    check does not also test for `window` — happy-dom-style test
+ *    environments expose a `window` while `globalThis.localStorage` is still
+ *    Node's stub underneath.
+ *
+ * Skipping costs nothing either way. Without `--localstorage-file` the read
+ * would have returned `undefined` → `absent`, which is what we return; *with*
+ * it the storage works → `usable`, which is also a no-op.
+ */
+function isNodeWebStorageStub(scope, name) {
+    const runtime = globalThis;
+    if (typeof runtime.process?.versions?.node !== 'string')
+        return false;
+    const descriptor = Object.getOwnPropertyDescriptor(scope, name);
+    return (descriptor !== undefined &&
+        typeof descriptor.get === 'function' &&
+        typeof descriptor.set === 'function' &&
+        descriptor.enumerable === false);
+}
+/**
+ * Classify `scope[name]`.
+ *
+ * Reading the property can succeed while writing still throws (storage
+ * disabled, private-browsing quirks, quota exhausted), so probe a real
+ * round-trip rather than trusting the getter.
+ *
+ * `absent` is deliberately distinct from `broken`: a runtime with no web
+ * storage at all (Node/SSR, a worker) must be left alone. Inventing a
+ * `localStorage` there would flip isomorphic libraries onto their browser code
+ * path and cause a *different* class of bug than the one we are fixing.
+ *
+ * **Never throws.** `installSafeStorage()` runs at module scope, so an escaping
+ * error would reject `import '@civitai/sdk'` outright and take down every app
+ * and block that imports it — a worse failure than the one being fixed.
+ */
+function probe(scope, name) {
+    // `in` is the only safe existence check, and it has to come first.
+    //
+    // It runs [[HasProperty]], which does NOT invoke the getter — on an ordinary
+    // object (`globalThis` included) it runs no user code at all, so it cannot
+    // throw and cannot trip Node's stub (above).
+    //
+    // The conventional `typeof localStorage === 'undefined'` guard is NOT a
+    // substitute: inside a real opaque-origin sandbox `typeof localStorage`
+    // ALSO throws, because `typeof` on a member/global reference still resolves
+    // the property and runs the throwing getter — only `typeof` of an
+    // *undeclared identifier* is safe, and this identifier is declared.
+    // `'localStorage' in window` is the probe that survives there, and it
+    // correctly answers `true`: in the sandbox the global exists, it is merely
+    // unreadable. So the sandbox is classified `broken` below, never `absent`.
+    if (!(name in scope))
+        return { health: 'absent' };
+    if (isNodeWebStorageStub(scope, name))
+        return { health: 'absent' };
+    let storage;
+    try {
+        storage = scope[name];
+    }
+    catch {
+        // The opaque-origin case: the getter itself throws.
+        return { health: 'broken' };
+    }
+    if (storage === undefined || storage === null)
+        return { health: 'absent' };
+    // Everything below TOUCHES the object we were handed, and every one of those
+    // touches can throw — a revoked `Proxy` answers even a plain property read
+    // with a TypeError, and any exotic object can have a throwing getter. So the
+    // shape check lives inside the `try` alongside the round-trip probe rather
+    // than in front of it.
+    //
+    // A property read that throws is classified `broken`, not `usable`: every
+    // consumer's `localStorage.getItem(...)` would throw exactly the same way, so
+    // the global is unusable by definition — the same conclusion the throwing
+    // *getter* above already reaches. Leaving it in place would keep a provably
+    // lethal global on the page; replacing it cannot produce a false positive,
+    // because a healthy `Storage` never throws on method access.
+    try {
+        if (typeof storage.getItem !== 'function' || typeof storage.setItem !== 'function') {
+            return { health: 'broken', storage };
+        }
+        storage.setItem(PROBE_KEY, '1');
+        storage.removeItem(PROBE_KEY);
+        return { health: 'usable', storage };
+    }
+    catch {
+        return { health: 'broken', storage };
+    }
+}
+/**
+ * Copy whatever `existing` still holds into `into`, best-effort.
+ *
+ * The write probe fails for two very different reasons. At an opaque origin
+ * there is nothing to read and nothing to preserve. But a *full* (or
+ * write-disabled) storage on an ordinary origin — historically the
+ * Safari-private-mode shape, and the likeliest real-world trigger — reads
+ * perfectly well: swapping a bare in-memory `Storage` over it would shadow
+ * live data, turning "can't save" into "the session is gone". So the fallback
+ * inherits the current entries first.
+ *
+ * Values written *after* the swap are session-scoped and lost on reload, the
+ * same as every other install path — the fallback never claims to persist.
+ *
+ * Reading the old store is itself unguarded territory (revoked proxies,
+ * throwing getters, an object that is not `Storage`-shaped at all), so the
+ * whole copy is best-effort: an empty fallback still beats a global that
+ * throws.
+ */
+function seedFrom(existing, into) {
+    try {
+        const size = existing.length;
+        if (typeof size !== 'number' || typeof existing.key !== 'function')
+            return;
+        if (typeof existing.getItem !== 'function')
+            return;
+        for (let index = 0; index < size; index += 1) {
+            const key = existing.key(index);
+            if (key === null || key === undefined || key === PROBE_KEY)
+                continue;
+            const value = existing.getItem(key);
+            if (value !== null && value !== undefined)
+                into.setItem(key, value);
+        }
+    }
+    catch {
+        // Unreadable after all. Nothing to inherit; carry on with an empty store.
+    }
+}
+/**
+ * Replace any present-but-unusable `localStorage`/`sessionStorage` on `scope`
+ * with an in-memory `Storage`, so third-party code that touches it unguarded
+ * cannot throw.
+ *
+ * - **No-op where storage works — but not a no-TOUCH.** A healthy `Storage` is
+ *   never replaced and its contents are unchanged, but it *is* written to:
+ *   classifying it means a real round trip, so each of `localStorage` and
+ *   `sessionStorage` gets `setItem('__civitai_app_sdk_storage_probe__', '1')`
+ *   immediately followed by `removeItem`. MEASURED against the built artifact
+ *   with instrumented healthy stores: exactly those four operations, the store
+ *   objects not replaced, contents identical before and after. Per the Web
+ *   Storage spec every one of those writes queues a `storage` event in the
+ *   *other* documents that share the store, so at a REAL origin a cross-tab
+ *   listener that does not filter by key sees spurious events (the two
+ *   `localStorage` writes are the ones another tab receives). At the opaque
+ *   origin this module exists for there is no other same-origin document, so
+ *   there is nothing to receive them.
+ * - **No-op where storage is absent** (Node/SSR/workers). Nothing is invented.
+ * - **Never loses readable data.** When the old store reads but refuses writes
+ *   (full / disabled), its entries are copied into the fallback first, so the
+ *   shim cannot shadow a live session.
+ * - **Idempotent.** Once the fallback is installed the round-trip probe
+ *   succeeds, so a second call is a no-op and values already written survive.
+ * - **Never throws.** Every step is guarded; a shim that could fail at import
+ *   would be a worse outage than the bug it fixes.
+ *
+ * This module installs on import, so most apps never need to call it. Call it
+ * explicitly when you want the guarantee at a specific moment — e.g. right
+ * before `await import('some-lib')` that reads storage while evaluating.
+ *
+ * @param scope Object carrying the storage globals. Defaults to `globalThis`.
+ */
+export function installSafeStorage(scope = globalThis) {
+    const result = { localStorage: false, sessionStorage: false };
+    for (const name of STORAGE_NAMES) {
+        const { health, storage } = probe(scope, name);
+        if (health !== 'broken')
+            continue;
+        // Inherit anything the old store still holds, so a storage that reads
+        // fine but refuses writes (full / disabled) does not lose its data behind
+        // the shim. Skipped at an opaque origin, where the read itself threw and
+        // there is nothing to inherit.
+        const fallback = createMemoryStorage();
+        if (storage)
+            seedFrom(storage, fallback);
+        try {
+            Object.defineProperty(scope, name, {
+                value: fallback,
+                // `configurable: true` on purpose — a consumer (or a second call) can
+                // still swap in its own store via `Object.defineProperty`.
+                configurable: true,
+                // `writable: false` matches the browser: `window.localStorage = x` is
+                // a no-op in sloppy mode and a TypeError in strict mode on the real
+                // thing, sandboxed or not. A writable shim would quietly accept that
+                // assignment and hand blocks a *different* behaviour from production.
+                writable: false,
+                enumerable: false,
+            });
+            result[name] = true;
+        }
+        catch {
+            // Non-configurable in this engine — nothing more we can do. Swallowing
+            // keeps a best-effort shim from becoming its own boot failure.
+        }
+    }
+    return result;
+}
+// Install on import.
+//
+// Import order is the whole game: ES module imports are hoisted, so a
+// *statement* can never run before a sibling `import` of a dependency that
+// reads storage while evaluating. Only an import side effect can, which is why
+// this module installs on import rather than exposing a call to make — a block
+// writes `import '@civitai/sdk/safe-storage';` as the FIRST import in its
+// entry module and is then ahead of every dependency it imports afterwards.
+//
+// 🔴 That ordering is the app's job and nothing here can enforce it: a
+// storage-touching dependency imported ABOVE this specifier still evaluates
+// first. Keep it first.
+//
+// The blast radius is bounded by the rules above: it only ever replaces a
+// global that is already *provably* unusable, so in every healthy runtime this
+// is a couple of `setItem`/`removeItem` calls and nothing else.
+installSafeStorage();

package/package.json

@@ -1,17 +1,24 @@
 {
   "name": "@civitai/sdk",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "The Civitai SDK: an app holds a token and calls the Civitai API and the orchestrator; a block asks its host only to show host UI.",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "sideEffects": false,
+  "comment-sideEffects": "An ALLOWLIST, not `false`. `./dist/safe-storage/index.js` installs the opaque-origin storage repair when imported, and a bare `false` licenses every bundler to drop it. `./dist/index.js` is deliberately NOT listed: the package root is pure re-exports and must stay droppable. Pinned by test/safe-storage.test.ts.",
+  "sideEffects": [
+    "./dist/safe-storage/index.js"
+  ],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./safe-storage": {
+      "types": "./dist/safe-storage/index.d.ts",
+      "import": "./dist/safe-storage/index.js"
+    },
     "./testing": {
       "types": "./dist/testing.d.ts",
       "import": "./dist/testing.js"