@civitai/sdk 0.6.0 → 0.8.0

package/BREAKING.md

@@ -19,7 +19,7 @@ messages have no destination yet.
 | `SUBMIT_WORKFLOW`, `ESTIMATE_WORKFLOW`, `POLL_WORKFLOW`, `CANCEL_WORKFLOW`, `QUERY_APP_WORKFLOWS`, `CANCEL_APP_WORKFLOW` | `POST /api/v1/blocks/workflows/{submit,estimate,poll,cancel,query}` | **Routes exist.** 🔴 Use these, **not** `app.orchestration` — see *What a direct orchestrator call loses* below |
 | `GET_IMAGES_BY_IDS` | `GET /api/v1/blocks/images?ids=1,2,3` | Batch, up to **100** ids per request. Misses are reported by OMISSION — see below. 🔴 **Not `/api/v1/images`** — that is a `PublicEndpoint`; it ignores your token and answers with anonymous public results rather than erroring |
 | `APP_STORAGE_*` | `POST /api/v1/blocks/app-storage/*` | **Routes exist** — five of them (`get`, `set`, `delete`, `list`, `quota`), civitai#5085. This row said "No v1 route"; that is no longer true. See *App storage* below |
-| `SHARED_*` | `GET\|POST /api/v1/blocks/shared-storage/*` | **Routes exist** — eleven of them; see *Shared storage* below |
+| `SHARED_*` | `app.sharedStorage`, over `GET\|POST /api/v1/blocks/shared-storage/*` | **Routes exist** — eleven of them. `app.sharedStorage` wraps the **five** key/value ones; the higher-level ops are deliberately app-layer. See *Shared storage* below |
 | `GET_BUZZ_BALANCE` | `GET /api/v1/blocks/buzz` | **Route exists.** Returns `{ blue, green, yellow }` — a bare object, three numbers |
 | `GET_BUZZ_ACCOUNTS`, `GET_BUZZ_TRANSACTIONS` | — | No v1 route |
 | `CREATE_POST_FROM_APP` | — | No v1 route, **and deliberately staying on the bridge** — see below |
@@ -57,6 +57,119 @@ first.
 Eleven routes under `/api/v1/blocks/shared-storage/`. Reads take `apps:storage:shared:read`, writes take
 `apps:storage:shared:write` — both scopes already existed; neither is new.
 
+### `app.sharedStorage` wraps FIVE of the eleven, on purpose
+
+`app.sharedStorage` is a **generic cross-user key/value store**: `list`, `get` (the `/item` route, matching its
+tRPC twin `apps.shared.get`), `append`, `update`, `withdraw`. An app no longer needs to hand-roll
+`app.site.get('blocks/shared-storage/…')`, and the shape traps below are handled for it.
+
+🔴 **`vote`, `unvote`, `counts`, `top`, `increment` and `report` are DELIBERATELY ABSENT from the client.**
+The platform serves all eleven routes and will keep doing so — this is a surface decision, not a gap, and not
+an oversight to be "fixed". Shared storage is scoped to generic key/value operations; the higher-level ops
+belong at the app layer, where an app that wants voting, counters or reporting builds them on top of these
+five. If demand shows up, the platform-side surface can be expanded again and the client can follow — but
+**the routes existing is not a reason to add a method here.** Do not add one back without that decision being
+revisited.
+
+What survives the cut, and why: `SharedItem` still carries **`count` and `viewerVoted`** exactly as the two
+read routes project them. Reading a tally is what makes an app-layer vote feature possible; only the
+vote-casting operation is out of scope.
+
+🔴 **It is not the per-viewer client's shape, in four ways.** Each is a real difference in the route table,
+not a stylistic one, and assuming otherwise produces a bug that type-checks:
+
+1. **The two reads are `GET` with a query string**; the three writes are `POST`. A read sent as POST is a `405`.
+2. **`list` is enveloped** — `{ items, metadata: { nextCursor } }`. The cursor sits one level deeper than
+   `app-storage/list`'s top-level `nextCursor`; read the wrong level and pagination is silently dead while
+   every page still parses.
+3. **`append` accepts no key** — the server mints a ULID, so one viewer cannot overwrite another's row.
+4. **Anonymous viewers read but never write** — the inverse of per-viewer storage, where a missing subject
+   refuses everything. See *Who may read, and who may write* below.
+
+### Porting off the bridge: `useSharedStorage` → `app.sharedStorage`
+
+`@civitai/blocks-react`'s `useSharedStorage` hook is what the fleet uses today, and it is **the left column of
+the table at the top of this document, not a rival client of the right one.** It sends `SHARED_LIST`,
+`SHARED_GET`, … over `postMessage` and never touches `/api/v1`; the host receives those messages and calls
+tRPC `apps.shared.*` on the block's behalf. Its own doc says the block *"never sees the datastore credentials
+and never sends its block token (the host injects both)"*.
+
+`app.sharedStorage` is the other side of that migration: the transport becomes a direct `fetch` of
+`/api/v1/blocks/shared-storage/*`, from the block's opaque origin, instead of a message to the host.
+
+**The credential and the CORS declaration are already handled — for both, by code that exists.** `initialize()`
+wires the host session into the client, `createHttp` puts `Authorization: Bearer <token>` on every request and
+retries once on a `401` with a freshly fetched token, and the token still comes **from the host** over the
+bridge (`REQUEST_TOKEN`) — the host continues to mint and rotate it. Scopes are unchanged between the two
+transports (see above). So there is no token plumbing, no CORS work and no manifest change to do.
+
+⚠ **The CORS mechanism differs by trust tier, though neither tier costs you any work.** An unverified block runs
+without `allow-same-origin`, so it fetches from an **opaque origin** and the five routes' `allowOpaqueOrigin`
+opt-in makes the server answer `ACAO: null`. An `internal`- or `verified`-tier block **does** get
+`allow-same-origin`, so it fetches from its **real origin**, where that arm does not apply — it clears CORS via
+the server's origin allowlist instead, which the platform populates itself from the publish-request approval
+rather than anything an author configures.
+
+The work that actually remains is four items, and it is all at the call sites:
+
+1. **Narrow `value` from `unknown`** at every read site — see below.
+2. **Move vote / counter / report logic into your app.** Those methods are not in this client at all; the
+   platform routes still exist. See the deliberate-omission note above.
+3. **Handle refusals as HTTP.** An `ApiError` carrying a `status`, where the bridge surfaced a rejected
+   message — and the anon-write case is a `403` from the scope binding rather than anything the handler said.
+   Read `message ?? error`; see *Error body* below.
+   🔴 **But not every failure is an `ApiError`.** A request the browser blocks — a CORS rejection, a DNS or
+   network failure — never reaches the response layer, so it surfaces as a **fetch `TypeError` with no
+   `status` and no body**. A `catch` that assumes `ApiError` will read `undefined` for the status and report the
+   wrong thing. The bridge had no such failure mode; this transport does. Branch on
+   `error instanceof ApiError` first and treat the rest as transport failure.
+4. **Audit every `limit` you pass** — the normalisation rules changed; see below.
+
+⚠ **This paragraph has had three framings; two claims are retracted.** Recorded so the ground is not re-walked,
+and scoped deliberately — each retraction covers only the words quoted, nothing adjacent:
+**(a)** *"a second client for these same routes"* — **false**: the hook is the bridge/tRPC path and never
+calls `/api/v1`, so the two are different transports, not two clients of one surface.
+**(b)** *"budget for the token/CORS work"* — **false**: both the credential and the CORS declaration are already
+handled, so that advice sent the reader's effort at finished infrastructure while demoting the real work.
+🔴 The *transport* change is NOT retracted — this document still asserts it, above. The list above is what is
+measured; nothing beyond it is claimed.
+
+| | `useSharedStorage` (bridge) | `app.sharedStorage` (HTTP) |
+|---|---|---|
+| Transport | `postMessage` → host → tRPC `apps.shared.*` | direct `fetch` of `/api/v1/blocks/shared-storage/*` |
+| Credential | host-injected | the SDK sends the host-minted token for you |
+| Methods | 10, including `vote`/`unvote`/`count`/`report` | 5, key/value only |
+| A listed row's `value` | `SharedAppendValue` — the typed write shape | `unknown` |
+| `update` resolves | `void` | `{ ok: true }` |
+| `list({ limit })`, out of range / non-integer / non-finite | **normalised**: clamped to 1…100, floored, or defaulted to 50 | **rejected — `400`** on all three |
+
+🔴 **`limit` is the one that bites silently, and it is three changes, not one.** The bridge HOST normalised;
+the REST route VALIDATES and refuses. Measured against the platform's own schema
+(`z.coerce.number().int().min(1).max(100)`), each of these used to succeed and now `400`s:
+
+- **Out of range** — `200` was clamped to 100, `0` was raised to 1. Both now reject.
+- **Non-integer** — `2.5` was floored to 2. Now rejects.
+- **Non-finite or not a number** — `NaN`, `Infinity`, `"abc"` and `""` all fell back to **50**. All now reject.
+  🔴 **This is the one to grep for**: `Number(searchParams.get('n'))` on a missing param is `NaN`, which used
+  to mean "just give me the default" and is now a failed request.
+
+⚠ The `400` body is `{ error: 'Invalid query', details }`, and the SDK reads `error` first — so
+`ApiError.message` is just **"Invalid query"**, naming neither the field nor the reason. The pointer is not
+missing, only moved: **`ApiError.body.details`** carries zod's flattened field errors. Look there, not at
+`.message`, when a read 400s.
+
+Pass a value in range, or omit it and take the server's default. This client deliberately does **not** re-clamp:
+the bounds are the server's, a second copy here is the thing that drifts, and a guard in this package enforces
+that the module carries no numeric literal at all.
+
+🔴 **The `value: unknown` is deliberate, and it is the wire-honest reading.** A row you list was written by some
+OTHER viewer's copy of the app — possibly an older version, possibly a newer one — so its shape is a fact about
+stored data, not a promise a client can keep. Typing it as the *write* shape asserts something nothing checked,
+and it is wrong the moment one viewer ships a schema change. Narrow it at the call site.
+
+Consequence: **a port is not an import swap** — but the cost is call-site work, not infrastructure. Narrow
+`value`, move the vote/counter/report logic into your app, branch on `ApiError.status`, and check every `limit`.
+
 | Method | Path | Scope |
 |---|---|---|
 | `GET` | `/list` | `…shared:read` |

package/README.md

@@ -71,13 +71,14 @@ host's consent dialog.
 **not** an error in itself: the host's OAuth mint is flag-gated, so an opted-in
 block can legitimately receive the block token, and that token serves the
 `/api/v1/blocks/*` routes it was minted for, `GET /api/v1/models/{id}`, and
-`app.storage` — which an OAuth token cannot reach at all. What it does not reach
-is the rest of `/api/v1`, the orchestrator or the MCP. So the refusal sits at the
-surface, not at startup:
+`app.storage` and `app.sharedStorage` — which an OAuth token cannot reach at all.
+What it does not reach is the rest of `/api/v1`, the orchestrator or the MCP. So
+the refusal sits at the surface, not at startup:
 
 | You call | Holding a block token, signed in |
 |---|---|
 | `app.storage.*` | Works. This is the token app storage requires |
+| `app.sharedStorage.*` | Reads work, anonymous included. Writes additionally need a signed-in viewer past the server's minimum-trust gate, so a `403` there is about the VIEWER, not the token |
 | `app.site` on `blocks/…` | Works. These are the routes the token was minted for |
 | `app.site.get('me')` and the rest of `/api/v1` | The API's own 401/403, with `auth: "oauth"` named in the message. `status` and `body` are untouched, so a caller can still branch on them |
 | `app.orchestration.*` | Rejects **before** the request with a `CivitaiError` naming `auth: "oauth"` — the orchestrator accepts no block token on any route, so there is nothing to learn from making the call |
@@ -143,8 +144,11 @@ Routes are addressed by path, so a route `/api/v1` gains needs no release here:
 const images = await app.site.get('images', { query: { limit: 20, username: 'civitai' } });
 ```
 
-A `401` is retried once with a fresh token. Any other failure is an `ApiError`
-carrying `status`, the parsed `body`, and the server's own message.
+A `401` is retried once with a fresh token. Any failure the server answered is an
+`ApiError` carrying `status`, the parsed `body`, and the server's own message —
+while a request the browser never delivered (CORS, DNS, offline) surfaces as a
+fetch `TypeError` with no `status`, so test `error instanceof ApiError` before
+reading one.
 
 ## App storage
 
@@ -190,6 +194,81 @@ try {
 }
 ```
 
+## Shared storage
+
+`app.sharedStorage` is this app's **cross-user** key/value store — one namespace
+every viewer reads and writes, unlike `app.storage`, which is private per viewer.
+Five methods: `list`, `get`, `append`, `update`, `withdraw`.
+
+```ts
+const { items, nextCursor } = await app.sharedStorage.list({ prefix: 'deck:' });
+const { key } = await app.sharedStorage.append({ title: 'My deck', data: { cards } });
+const row = await app.sharedStorage.get(key);        // null when hidden or absent
+await app.sharedStorage.update(key, { title: 'Renamed' });
+const { deleted } = await app.sharedStorage.withdraw(key);
+```
+
+🔴 **Generic key/value on purpose — and deliberately smaller than the route
+table.** The platform serves eleven shared-storage routes; this client wraps the
+five that are key/value operations. `vote`, `unvote`, `counts`, `top`,
+`increment` and `report` are **intentionally absent**: an app that needs voting,
+counters or reporting builds them at its own layer on top of these five, and the
+platform surface expands only if demand shows up. The routes existing is not a
+reason to expect a method here.
+
+Reading a tally still works — `SharedItem` carries `count` and `viewerVoted` as
+the server projects them, which is exactly what makes an app-layer vote feature
+possible. You just cast the vote yourself.
+
+🔴 **Reads and writes have different audiences, and one does not imply the
+other.** This is the opposite of `app.storage`, so do not carry that gate over:
+
+- **An anonymous viewer MAY read** (`list`, `get`) — signed-out browsing is a
+  supported path — and may **never** write. An anon write is a `403` from the
+  scope binding, not the `401` a missing token gives.
+- **A signed-in viewer is not automatically a permitted writer.** Writes clear a
+  server-side minimum-trust gate (account age, paid tier, verified email or a
+  linked OAuth account). Treat a write refusal as a normal outcome with a real
+  message in the UI, not an unexpected error.
+
+So gate the write affordances on `app.viewer`, and render the reads regardless.
+
+Four shape differences from `app.storage`, each of which would otherwise be a bug
+that type-checks:
+
+- **The two reads are `GET`**; the three writes are `POST`. A read sent as `POST`
+  is a `405`.
+- **`list` returns `items` with values included** — so one request renders a page
+  rather than needing a `get` per key — and its `nextCursor` arrives nested under
+  the reply's `metadata`. The client lifts it for you; the rule is the same as
+  `app.storage`'s, absence proves the scan completed.
+- **`append` takes no key.** The server mints a ULID and returns it, so one
+  viewer cannot overwrite another's row. Use `update` for an in-place edit of a
+  row this viewer authored.
+- **`value` is `unknown` on the way out.** The row was written by some other
+  viewer's copy of your app, possibly an older version, so its shape is a fact
+  about the data rather than a promise the client can make. Narrow it yourself.
+
+⚠ **`limit` is validated, not normalised.** Out of range, non-integer, `NaN` and
+`Infinity` are each a `400` and a rejected promise — not a silently adjusted page.
+Pass a value inside the server's range, or omit it and take the server's default.
+🔴 The sharp edge: `Number(searchParams.get('n'))` on a missing param is `NaN`, so
+a pattern that used to fall through to a default is now a failed request.
+
+The `400` body is `{ error: 'Invalid query', details }` and the SDK reads `error`
+first, so `ApiError.message` says only "Invalid query" — the field-level reason is
+in `ApiError.body.details`.
+
+If you are porting from `@civitai/blocks-react`'s `useSharedStorage`, the bridge
+*host* normalised all of this for you and nothing normalises it here;
+[`BREAKING.md`](./BREAKING.md) covers what the port does and does not cost.
+
+`withdraw` answers `{ ok: true, deleted: false }` identically for another
+author's key, an already-withdrawn row and a key that never existed — it is not
+an existence oracle, so do not report that as "someone else owns this". Put every
+string other viewers will read in `title`/`body`, which the server moderates;
+`data` is unmoderated app structure.
+
 ## The orchestrator
 
 Steps are typed by `$type`: `input` is checked against that step's own input,
@@ -374,6 +453,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/app/index.d.ts

@@ -3,6 +3,7 @@ import type { BlockTransport } from '../core/transport.js';
 import { type Host } from '../host/index.js';
 import { type OrchestrationClient } from '../orchestration/index.js';
 import { type GrantOptions, type Scope, type TokenOptions, type TokenSessionOptions } from '../session/index.js';
+import { type SharedStorageClient } from '../shared-storage/index.js';
 import { type SiteClient } from '../site/index.js';
 import { type StorageClient } from '../storage/index.js';
 export interface AppClient {
@@ -26,6 +27,18 @@ export interface AppClient {
      * reading an empty result as "nothing stored".
      */
     readonly storage: StorageClient;
+    /**
+     * This app's CROSS-USER store — one namespace every viewer of this app reads
+     * and writes, which is what makes a shared feed or a "popular" rail possible.
+     *
+     * 🔴 Requires the block token, like {@link AppClient.storage}, but the audience
+     * is NOT the same: an ANONYMOUS viewer MAY read here and may never write. So
+     * `viewer === null` gates the write affordances, not the read — and an anon
+     * write surfaces as 403, refused by the scope binding before the handler runs.
+     * A signed-in viewer is not automatically a permitted writer either: writes
+     * clear a server-side minimum-trust gate.
+     */
+    readonly sharedStorage: SharedStorageClient;
     /**
      * The orchestrator's workflows, as the viewer.
      *

package/dist/app/index.js

@@ -4,6 +4,7 @@ import { createHost, createHostSession } from '../host/index.js';
 import { ApiError, createHttp } from '../http/index.js';
 import { createOrchestrationClient, DEFAULT_ORCHESTRATION_URL, } from '../orchestration/index.js';
 import { createTokenSession, } from '../session/index.js';
+import { createSharedStorageClient, } from '../shared-storage/index.js';
 import { createSiteClient, DEFAULT_SITE_URL } from '../site/index.js';
 import { createStorageClient } from '../storage/index.js';
 /** Long enough for a slow host page; short enough that a block opened on its own says so. */
@@ -77,16 +78,19 @@ const OAUTH_OPT_IN = 'declare `auth: "oauth"` in block.manifest.json';
 const BLOCK_NAMESPACE = /^\/*blocks\//;
 function createAppClient(session, options, holdsBlockTokenNow = () => false) {
     const http = (baseUrl) => createHttp({ session, baseUrl, fetch: options.fetch });
-    // One instance for both site-hosted surfaces: `storage`'s routes live under
-    // the same base URL, so a `siteUrl` override redirects them together.
+    // One instance for all three site-hosted surfaces: the two storage clients'
+    // routes live under the same base URL, so a `siteUrl` override redirects them
+    // together.
     // Wrapped once, so `BLOCK_NAMESPACE` is the single place that decides where the
-    // diagnosis applies. `storage` needs no exemption of its own: every one of its
-    // routes is `blocks/app-storage/*`, which that namespace already excludes, and
-    // `test/storage/seam.test.ts` pins its `BASE` there textually.
+    // diagnosis applies. Neither storage client needs an exemption of its own:
+    // their routes are `blocks/app-storage/*` and `blocks/shared-storage/*`, which
+    // that namespace already excludes, and `test/storage/seam.test.ts` plus
+    // `test/shared-storage/seam.test.ts` pin both `BASE` values there textually.
     const siteHttp = explainApiRefusal(http(options.siteUrl ?? DEFAULT_SITE_URL), holdsBlockTokenNow);
     return {
         site: createSiteClient(siteHttp),
         storage: createStorageClient(siteHttp),
+        sharedStorage: createSharedStorageClient(siteHttp),
         orchestration: createOrchestrationClient(refuseBlockToken(http(options.orchestrationUrl ?? DEFAULT_ORCHESTRATION_URL), holdsBlockTokenNow)),
         requestGrants: (scopes, opts) => session.requestGrants(scopes, opts),
         getToken: (opts) => session.getToken(opts),

package/dist/index.d.ts

@@ -9,6 +9,7 @@ export type { SignIn, SignInOptions } from './sign-in/index.js';
 export { SCOPES } from './session/index.js';
 export type { GrantOptions, Scope, TokenOptions, TokenSource } from './session/index.js';
 export type { SiteClient } from './site/index.js';
+export type { SharedItem, SharedListQuery, SharedListResult, SharedStorageCallOptions, SharedStorageClient, SharedValue, } from './shared-storage/index.js';
 export type { StorageCallOptions, StorageClient, StorageKeyEntry, StorageListQuery, StorageListResult, StorageQuota, } from './storage/index.js';
 export { isTerminal, isTerminalStatus } from './orchestration/index.js';
 export type { OrchestrationClient, Step, StepTemplate, WaitOptions, Workflow, WorkflowPage, WorkflowQuery, WorkflowStatus, WorkflowTemplate, } from './orchestration/index.js';

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/dist/shared-storage/index.d.ts

@@ -0,0 +1,153 @@
+import type { Http } from '../http/index.js';
+export interface SharedStorageCallOptions {
+    signal?: AbortSignal;
+}
+/**
+ * The moderated, user-visible text plus the opaque app-owned blob.
+ *
+ * 🔴 `title` and `body` run the server's BLOCKING content-safety belt on every
+ * write. `data` does NOT — it is unmoderated app structure. Put every string
+ * another viewer will read in `title`/`body`; a text surface smuggled into
+ * `data` reaches other users unmoderated, which is the one thing this split
+ * exists to prevent.
+ */
+export interface SharedValue {
+    title: string;
+    body?: string;
+    data?: unknown;
+}
+/**
+ * One row of the shared store, as `list` and `get` both project it.
+ *
+ * 🔴 `value` is `unknown`, NOT {@link SharedValue}, and that is deliberate: the
+ * row was written by some OTHER viewer's copy of this app — possibly an older
+ * version, possibly a newer one — so its shape is a fact about the data, not a
+ * promise this client can make. Narrow it at the call site. Declaring it
+ * `SharedValue` would assert a shape nothing checked about data we did not write.
+ */
+export interface SharedItem {
+    key: string;
+    /** The row's author. A caller renders "yours" by comparing it to the viewer's id. */
+    authorUserId: number;
+    value: unknown;
+    /**
+     * The row's aggregate up-vote tally, as the server projects it.
+     *
+     * ⚠ Reported, not writable from here: the vote OPERATIONS are deliberately not
+     * part of this client (see the module note). Reading the tally is what lets an
+     * app build voting at its own layer, which is why the field stays.
+     */
+    count: number;
+    /**
+     * The wire carries ISO strings; both stamps are revived here, once, so a
+     * caller can sort and diff without knowing the transport.
+     */
+    createdAt: Date;
+    updatedAt: Date;
+    /**
+     * Whether THIS viewer has voted. 🔴 Always `false` for an anonymous viewer —
+     * who may read this store — so it is not evidence that nobody voted.
+     */
+    viewerVoted: boolean;
+}
+export interface SharedListQuery {
+    /** Narrows to keys starting with this. Escaped server-side against LIKE wildcards. */
+    prefix?: string;
+    /** The server bounds this and applies its own default; this client sends none. */
+    limit?: number;
+    /** An opaque `nextCursor` from a previous page. */
+    cursor?: string;
+}
+export interface SharedListResult {
+    /** Newest-first on the server-generated ULID key. Hidden rows are excluded. */
+    items: SharedItem[];
+    /**
+     * 🔴 PRESENT EXACTLY WHEN THERE MAY BE MORE ROWS, and passed through
+     * untouched. The server sets it iff the page it returned was full, and it
+     * arrives nested under the reply's `metadata` — lifted here, never defaulted,
+     * never normalised, never re-derived from `items.length`. A caller uses its
+     * ABSENCE as proof a scan completed.
+     */
+    nextCursor?: string;
+}
+/**
+ * This app's CROSS-USER key/value store — every viewer of this app reads and
+ * writes one namespace, unlike {@link StorageClient}, which is private per viewer.
+ *
+ * 🔴 DELIBERATELY GENERIC KEY/VALUE, AND DELIBERATELY SMALLER THAN THE ROUTE
+ * TABLE. The platform serves eleven shared-storage routes; this client wraps the
+ * five that are key/value operations. The higher-level ops — `vote`, `unvote`,
+ * `counts`, `top`, `increment`, `report` — are intentionally absent: an app that
+ * needs voting, counters or reporting builds them at its own layer on top of
+ * these five, and the platform surface expands only if demand shows up. **The
+ * routes existing is not a reason to add a method here.** Do not "fix" this
+ * omission.
+ *
+ * 🔴 Requires the block token the host mints, plus the scopes: every read takes
+ * `apps:storage:shared:read` and every write takes `apps:storage:shared:write`.
+ * An app that authenticated with an OAuth access token has no shared storage.
+ *
+ * 🔴 READS AND WRITES HAVE DIFFERENT AUDIENCES, and a caller must not assume one
+ * implies the other:
+ *
+ * - An ANONYMOUS viewer MAY read (`list`, `get`) and may NEVER write. An anon
+ *   write is refused by the scope binding before the handler runs, so it arrives
+ *   as **403**, not the 401 a missing token gives.
+ * - A signed-in viewer is not automatically a permitted writer: writes clear a
+ *   minimum-trust gate (account age, paid tier, verified email or a linked OAuth
+ *   account). Treat a write refusal as a normal outcome and say so in the UI.
+ *
+ * 🔴 EVERY FAILURE REJECTS. No path here resolves to mean "not written" or
+ * "could not read". A caller that must not act on a partial view branches on the
+ * rejection, never on an empty result.
+ */
+export interface SharedStorageClient {
+    /**
+     * One page of rows, newest-first. `GET blocks/shared-storage/list`.
+     *
+     * Values ARE returned, unlike the per-viewer client's `list` — so one request
+     * renders a page rather than needing a `get` per key.
+     */
+    list(query?: SharedListQuery, opts?: SharedStorageCallOptions): Promise<SharedListResult>;
+    /**
+     * One row by key, or `null`. `GET blocks/shared-storage/item`.
+     *
+     * 🔴 `null` covers MISSING **and** HIDDEN, deliberately and identically — a
+     * withdrawn or moderator-hidden row is indistinguishable from one that never
+     * existed, so this is not an oracle for either. It is a 200, not a 404.
+     */
+    get(key: string, opts?: SharedStorageCallOptions): Promise<SharedItem | null>;
+    /**
+     * Files a new row and resolves its key. `POST blocks/shared-storage/append`.
+     *
+     * 🔴 THE KEY IS THE SERVER'S — a ULID it generates, returned here. This method
+     * takes no key and there is no create-at-key call, because a client-chosen key
+     * would let one viewer overwrite another's row.
+     */
+    append(value: SharedValue, opts?: SharedStorageCallOptions): Promise<{
+        key: string;
+    }>;
+    /**
+     * Edits a row the VIEWER AUTHORED, in place. `POST blocks/shared-storage/update`.
+     *
+     * Another author's key is a 403 and a missing or hidden one a 404 — neither is
+     * a silent no-op. Preserved: the key, the author, `createdAt`, and the row's
+     * votes, counters and reports. Replaced: the value.
+     */
+    update(key: string, value: SharedValue, opts?: SharedStorageCallOptions): Promise<{
+        ok: true;
+    }>;
+    /**
+     * Deletes a row the VIEWER AUTHORED. `POST blocks/shared-storage/withdraw`.
+     *
+     * 🔴 `deleted: false` is a SUCCESS, and it is deliberately ambiguous: another
+     * author's key, an already-withdrawn row and a key that never existed all
+     * answer the same way, so this cannot probe for other viewers' rows. Do not
+     * report it to the viewer as "someone else owns this".
+     */
+    withdraw(key: string, opts?: SharedStorageCallOptions): Promise<{
+        ok: true;
+        deleted: boolean;
+    }>;
+}
+export declare function createSharedStorageClient(http: Http): SharedStorageClient;

package/dist/shared-storage/index.js

@@ -0,0 +1,107 @@
+import { CivitaiError } from '../core/errors.js';
+/** Where the five routes this client wraps live under the site base URL. */
+const BASE = 'blocks/shared-storage';
+export function createSharedStorageClient(http) {
+    // 🔴 GET for the reads, POST for the writes — the route table's own split, not
+    // the per-viewer client's uniform POST. A read sent as POST is a 405.
+    const get = (op, query, signal) => http('GET', `${BASE}/${op}`, { query, signal });
+    const post = (op, body, signal) => http('POST', `${BASE}/${op}`, { body, signal });
+    return {
+        async list(query = {}, { signal } = {}) {
+            const res = await get('list', 
+            // Named rather than spread: each of the three is a field a mutation can
+            // drop on its own, and an `undefined` is omitted from the query string,
+            // so the server's own default applies instead of a second copy here.
+            { prefix: query.prefix, limit: query.limit, cursor: query.cursor }, signal);
+            // 🔴 NO `?? []`. A malformed 200 must throw, never answer "no rows": a
+            // caller reads an empty page as "this store is empty" and renders that to
+            // every viewer, and a manufactured empty page is indistinguishable.
+            if (!Array.isArray(res?.items)) {
+                throw new CivitaiError('shared-storage list: reply carried no `items` array');
+            }
+            // 🔴 GUARDED SYMMETRICALLY WITH `items`, and for the same reason. `metadata`
+            // is where `nextCursor` lives, and this method's contract is that the
+            // cursor's ABSENCE proves a scan completed. A `?? {}` here would turn a
+            // malformed envelope into `nextCursor: undefined` — so a caller's
+            // `do…while (cursor)` loop stops after page one and renders 50 of 5,000 rows
+            // as the whole store, silently. The identical malformation of `items` throws;
+            // treating the container the cursor arrives in as optional would have made
+            // the louder half of this reply strict and the quieter half lenient.
+            if (res.metadata == null || typeof res.metadata !== 'object') {
+                throw new CivitaiError('shared-storage list: reply carried no `metadata` object');
+            }
+            const metadata = res.metadata;
+            return {
+                items: res.items.map(toItem),
+                // 🔴 Lifted out of `metadata` and passed through. Not defaulted, not
+                // normalised, not re-derived.
+                nextCursor: metadata.nextCursor,
+            };
+        },
+        async get(key, { signal } = {}) {
+            const res = await get('item', { key }, signal);
+            // 🔴 NO `res?.item ?? null`. `null` is this method's word for "no visible
+            // row", a real answer a caller acts on. A reply that never carried `item`
+            // is not that answer, and must not be dressed up as it.
+            if (res == null || typeof res !== 'object' || !('item' in res)) {
+                throw new CivitaiError('shared-storage get: reply carried no `item`');
+            }
+            return res.item == null ? null : toItem(res.item);
+        },
+        async append(value, { signal } = {}) {
+            const res = await post('append', { value }, signal);
+            // Asserted, not cast: this key is the ONLY handle the caller will ever have
+            // on the row it just created, and a cast would make the declared `string` a
+            // lie we cannot see.
+            if (typeof res?.key !== 'string') {
+                throw new CivitaiError('shared-storage append: reply carried no `key`');
+            }
+            return { key: res.key };
+        },
+        async update(key, value, { signal } = {}) {
+            await post('update', { key, value }, signal);
+            // The route answers `{ ok: true }` and every failure has already rejected,
+            // so there is no second field to check — resolving IS the answer.
+            return { ok: true };
+        },
+        async withdraw(key, { signal } = {}) {
+            const res = await post('withdraw', { key }, signal);
+            if (typeof res?.deleted !== 'boolean') {
+                throw new CivitaiError('shared-storage withdraw: reply carried no `deleted` flag');
+            }
+            return { ok: true, deleted: res.deleted };
+        },
+    };
+}
+function toItem(row) {
+    const r = (row ?? {});
+    if (typeof r.key !== 'string' ||
+        typeof r.authorUserId !== 'number' ||
+        typeof r.count !== 'number' ||
+        typeof r.viewerVoted !== 'boolean' ||
+        !('value' in r)) {
+        throw new CivitaiError('shared-storage: malformed item');
+    }
+    return {
+        key: r.key,
+        authorUserId: r.authorUserId,
+        value: r.value,
+        count: r.count,
+        createdAt: toDate(r.createdAt),
+        updatedAt: toDate(r.updatedAt),
+        viewerVoted: r.viewerVoted,
+    };
+}
+function toDate(raw) {
+    // `new Date(null)` is the epoch, not an Invalid Date, so the NaN check below
+    // cannot be the only gate — a null timestamp would sort and compare silently
+    // wrong forever.
+    if (!(typeof raw === 'string' || raw instanceof Date)) {
+        throw new CivitaiError('shared-storage: malformed item timestamp');
+    }
+    const at = new Date(raw);
+    if (Number.isNaN(at.getTime())) {
+        throw new CivitaiError('shared-storage: malformed item timestamp');
+    }
+    return at;
+}

package/package.json

@@ -1,17 +1,24 @@
 {
   "name": "@civitai/sdk",
-  "version": "0.6.0",
+  "version": "0.8.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"