@civitai/sdk 0.9.0 → 0.10.0

package/README.md

@@ -60,6 +60,14 @@ Both give you:
 A block's `app` also has `host`, `viewer`, `context`, `settings`, `theme` and
 `onChange(listener)`. Outside a block they do not exist, and the types say so.
 
+`context` and `theme` are LIVE, not mount-time snapshots: the host pushes
+`THEME_CHANGE` when the viewer toggles dark mode and `ROUTE_CHANGED` when a page
+block's sub-path moves, and both are folded into the same snapshot — so
+`app.context.subPath` tracks `app.host.navigate(path)` (and the viewer's own back
+button) and `onChange` tells you when. Read them on each render rather than
+copying them once; there is deliberately no `onRouteChange`, because one value
+observed two ways is two values that can disagree.
+
 A block opts in by declaring `auth: "oauth"` in its `block.manifest.json`. The
 host then hands it a real OAuth access token that `/api/v1`, the orchestrator
 and the MCP accept, and consent — including `requestGrants` — goes through the
@@ -338,7 +346,7 @@ wider scope — and refuses without one.
 | `resize(height)` | Resizes the frame, clamped to the manifest |
 | `autoResize(element?)` | Keeps the frame as tall as the body (or `element`); returns a stop function |
 | `reportError(message, { fatal })` | `fatal` swaps the block for the host's fallback |
-| `navigate(path, { target })` | Deep-links within this app's own sub-paths |
+| `navigate(path, { scope, target })` | Deep-links within this app's own sub-paths; `scope: 'site'` asks to leave the app for a civitai.com page instead. `scope` defaults to `'app'` |
 | `onVisibilityChange(handler)` | Reports the page hiding and returning |
 | `requestSignIn({ returnUrl })` | Starts sign-in; the block re-initialises signed in |
 | `download({ url, filename })` | Saves to the viewer's device — a sandboxed frame cannot |

package/dist/core/handshake.d.ts

@@ -99,7 +99,17 @@ export interface BlockInitPayload {
     /** The domain ceiling narrowed to this viewer. Always a subset of the above. */
     effectiveBrowsingLevel?: number;
 }
-/** Host messages the transport itself acts on. Domains own everything else. */
+/**
+ * Host messages the transport itself acts on. Domains own everything else.
+ *
+ * `ROUTE_CHANGED` is here rather than in `HostPushes` for the same reason
+ * `THEME_CHANGE` is: it carries a value the snapshot already holds, so the
+ * transport folds it in and `client.context` / `client.onChange` are how a
+ * consumer observes it. A `HostPushes` row plus an `onRouteChange` method would
+ * publish a SECOND way to read one value, which is how `client.context.subPath`
+ * and a callback end up disagreeing. `SUSPEND`/`RESUME` are in `HostPushes`
+ * because they carry no state for the snapshot to hold.
+ */
 export type HostMessage = {
     type: 'BLOCK_INIT';
     payload: BlockInitPayload;
@@ -119,6 +129,11 @@ export type HostMessage = {
     payload: {
         theme: Theme;
     };
+} | {
+    type: 'ROUTE_CHANGED';
+    payload: {
+        subPath: string;
+    };
 };
 /** Discriminator only — the payload is still unvalidated wire data. */
 export declare function isHostMessage<K extends HostMessage['type']>(data: unknown, type: K): data is Extract<HostMessage, {

package/dist/core/transports/iframe-transport.js

@@ -287,6 +287,18 @@ export class IframeTransport {
             this.#applyThemeChange(data.payload.theme);
             return;
         }
+        // The page's sub-path moved under the app root. Folded into the snapshot so
+        // `client.context.subPath` is live and `onChange` reports it — the same
+        // treatment as the theme, and the reason there is no `onRouteChange`.
+        //
+        // Unlike the theme this IS effectively init-gated, because the sub-path
+        // lives only in `context` and the pre-init context has no such key. That
+        // costs nothing: the host sends this only after init, and `BLOCK_INIT`
+        // replaces the snapshot with its own current value.
+        if (isHostMessage(data, 'ROUTE_CHANGED')) {
+            this.#applyRouteChange(data.payload.subPath);
+            return;
+        }
         // Matching the TYPE too, not just the id: `IMAGE_SCAN_RESOLVED` is a push
         // that deliberately reuses its `OPEN_IMAGE_UPLOAD`'s requestId, so an
         // id-only match could resolve the upload with the scan verdict's payload.
@@ -337,6 +349,18 @@ export class IframeTransport {
         this.#snapshot = next;
         this.#emit();
     }
+    // Only ever UPDATES a context that already carries the key; never INTRODUCES
+    // it. A model slot has no route, so synthesising `subPath` would assert a page
+    // context the host never sent. Emits only when the value moved.
+    #applyRouteChange(subPath) {
+        const context = this.#snapshot.context;
+        if (!('subPath' in context))
+            return;
+        if (context.subPath === subPath)
+            return;
+        this.#snapshot = { ...this.#snapshot, context: { ...context, subPath } };
+        this.#emit();
+    }
     #emit() {
         for (const listener of this.#listeners)
             listener();

package/dist/host/index.d.ts

@@ -1,7 +1,7 @@
 import { type BlockTransport } from '../core/transport.js';
 import type { Session } from '../session/index.js';
-import type { DownloadRequest, ImageScanResult, PickedResource, ResourcePickerType, SourceImage } from './protocol.js';
-export type { ConsentRefusal, DownloadRequest, ImageScanResult, PickedResource, ResourcePickerType, SourceImage, UploadedImage, } from './protocol.js';
+import type { DownloadRequest, ImageScanResult, NavigateScope, PickedResource, ResourcePickerType, SourceImage } from './protocol.js';
+export type { ConsentRefusal, DownloadRequest, ImageScanResult, NavigateScope, PickedResource, ResourcePickerType, SourceImage, UploadedImage, } from './protocol.js';
 export interface HostCallOptions {
     signal?: AbortSignal;
 }
@@ -33,8 +33,15 @@ export interface Host {
     reportError(message: string, args?: {
         fatal?: boolean;
     }): void;
-    /** Deep-links within this app's own sub-paths; the host refuses anything else. */
+    /**
+     * Asks the host to navigate. `scope` picks the space `path` is resolved in and
+     * DEFAULTS to `'app'` — this app's own sub-paths, which is all this method
+     * could reach before the field existed. Pass `scope: 'site'` to leave the app
+     * for a civitai.com page; the host grants that per-surface and refuses it
+     * elsewhere. Fire-and-forget either way: a refusal is silent.
+     */
     navigate(path: string, args?: {
+        scope?: NavigateScope;
         target?: 'current' | 'new_tab';
     }): void;
     /** Fires `false` when the page hides and `true` when it returns. */

package/dist/host/index.js

@@ -25,7 +25,12 @@ export function createHost(transport) {
             return () => observer.disconnect();
         },
         reportError: (message, args = {}) => notify('BLOCK_ERROR', { message, fatal: args.fatal ?? false }, { transport }),
-        navigate: (path, args = {}) => notify('NAVIGATE', { path, target: args.target ?? 'current' }, { transport }),
+        // `scope` is OMITTED rather than sent as `undefined` when the caller did not
+        // choose one. Absent and `'app'` mean the same thing to the host, so this is
+        // not a behaviour difference — it keeps the wire payload byte-identical to
+        // what every pre-`scope` build sends, which is the property the back-compat
+        // claim rests on and the one a host-side diff can actually check.
+        navigate: (path, args = {}) => notify('NAVIGATE', { path, ...(args.scope ? { scope: args.scope } : {}), target: args.target ?? 'current' }, { transport }),
         onVisibilityChange(handler) {
             const offSuspend = on(transport, 'SUSPEND', () => handler(false));
             const offResume = on(transport, 'RESUME', () => handler(true));

package/dist/host/protocol.d.ts

@@ -1,5 +1,18 @@
 import type { WrappedToken } from '../core/handshake.js';
 export type ResourcePickerType = 'Checkpoint' | 'LORA';
+/**
+ * Which SPACE a `navigate()` path is resolved in.
+ *
+ *  - `'app'` — under this app's own route, as a sub-path of it. The DEFAULT.
+ *  - `'site'` — at the site root, leaving the app. The host grants this
+ *    per-surface and refuses it where the surface does not hold the capability.
+ *
+ * Omitting it means `'app'`, which is what keeps this field additive: a block
+ * that never sets it behaves as it did before the field existed. A leading slash
+ * carries no meaning — the host normalises it away in both scopes, so
+ * `'/settings'` and `'settings'` are one request within the scope you chose.
+ */
+export type NavigateScope = 'app' | 'site';
 /** The one resource the viewer picked. Discovery only: nothing here is an entitlement. */
 export interface PickedResource {
     versionId: number;
@@ -153,6 +166,7 @@ export type HostNotifications = {
     };
     NAVIGATE: {
         path: string;
+        scope?: NavigateScope;
         target: 'current' | 'new_tab';
     };
     REQUEST_SIGN_IN: {

package/dist/index.d.ts

@@ -14,7 +14,7 @@ export type { StorageCallOptions, StorageClient, StorageKeyEntry, StorageListQue
 export { isTerminal, isTerminalStatus } from './orchestration/index.js';
 export type { OrchestrationClient, Step, StepTemplate, WaitOptions, Workflow, WorkflowPage, WorkflowQuery, WorkflowStatus, WorkflowTemplate, } from './orchestration/index.js';
 export { createHost } from './host/index.js';
-export type { ConsentRefusal, DownloadRequest, Host, HostCallOptions, ImageScanResult, PendingImage, PickedResource, ResourcePickerType, SourceImage, UploadedImage, } from './host/index.js';
+export type { ConsentRefusal, DownloadRequest, Host, HostCallOptions, ImageScanResult, NavigateScope, PendingImage, PickedResource, ResourcePickerType, SourceImage, UploadedImage, } from './host/index.js';
 export { ApiError } from './http/index.js';
 export type { Query, QueryValue, RequestOptions } from './http/index.js';
 export { BridgeError, CivitaiError } from './core/errors.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@civitai/sdk",
-  "version": "0.9.0",
+  "version": "0.10.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",