@civitai/sdk 0.8.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
@@ -131,6 +139,29 @@ and a flag that the viewer signed in before (`returning`). Signing in again is
 a quick round trip, since Civitai remembers the consent. `requestGrants` goes
 back to Civitai for anything not yet granted.
 
+### Without leaving the page
+
+A page that must not be navigated away from, such as one with a chat or an
+editor embedded in it, signs in in a popup instead:
+
+```ts
+import { createSignIn, initialize } from '@civitai/sdk';
+
+const auth = await createSignIn({ clientId, scopes: ['ai:write:budgeted'] });
+button.onclick = async () => {
+  await auth.signInWithPopup(); // from the click itself: browsers only open a popup there
+  const app = await initialize(auth);
+};
+```
+
+Civitai returns the popup to `redirectUri`, the same page by default. That page
+calls `createSignIn()` as on any visit; in the popup it hands the result back to
+the page that opened it and closes. The result travels over a same-origin
+`BroadcastChannel`, not `window.opener`, because signing in through Google cuts
+the opener. A blocked popup rejects with `SignInError` `code: 'popup-blocked'`;
+pass a `signal` to give up, which rejects with `code: 'canceled'`.
+`requestGrants` still leaves the page.
+
 Only scopes with an OAuth equivalent can be asked for: `user:read:self`,
 `models:read:self`, `ai:write:budgeted`, `buzz:read:self`, `posts:write:self`
 and `social:tip:self`. The storage and collection scopes belong to blocks.
@@ -315,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/dist/sign-in/index.d.ts

@@ -3,7 +3,11 @@ import type { GrantOptions, Scope, TokenSessionOptions } from '../session/index.
 export declare const DEFAULT_AUTH_URL = "https://auth.civitai.com";
 export declare class SignInError extends CivitaiError {
     readonly status?: number;
-    constructor(message: string, status?: number, options?: ErrorOptions);
+    /** `canceled`: the viewer gave up on a popup sign-in. `popup-blocked`: the browser refused to open it. */
+    readonly code?: 'canceled' | 'popup-blocked';
+    constructor(message: string, status?: number, options?: ErrorOptions & {
+        code?: 'canceled' | 'popup-blocked';
+    });
 }
 type SignInStorage = Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;
 export interface SignInOptions {
@@ -34,6 +38,15 @@ export interface SignIn extends TokenSessionOptions {
     signIn(opts?: {
         scopes?: readonly Scope[];
     }): Promise<never>;
+    /**
+     * Signs in in a popup, so the page stays where it is. Call it straight from a click or key press:
+     * browsers only open a popup there. Civitai returns the popup to `redirectUri`, whose page must call
+     * `createSignIn()` with the same client, which hands the result back here and closes the popup.
+     */
+    signInWithPopup(opts?: {
+        scopes?: readonly Scope[];
+        signal?: AbortSignal;
+    }): Promise<void>;
     signOut(): Promise<void>;
 }
 export declare function scopeBitmask(scopes: readonly Scope[]): number;

package/dist/sign-in/index.js

@@ -13,10 +13,13 @@ const OAUTH_BITS = {
 const EXPIRY_MARGIN_MS = 60_000;
 export class SignInError extends CivitaiError {
     status;
+    /** `canceled`: the viewer gave up on a popup sign-in. `popup-blocked`: the browser refused to open it. */
+    code;
     constructor(message, status, options) {
         super(message, options);
         this.name = 'SignInError';
         this.status = status;
+        this.code = options?.code;
     }
 }
 export function scopeBitmask(scopes) {
@@ -62,6 +65,14 @@ function writeJson(storage, key, value) {
         // Private windows can refuse storage; the viewer then signs in again next visit.
     }
 }
+const canceled = () => new SignInError('sign-in was canceled', undefined, { code: 'canceled' });
+function popupFeatures(win) {
+    const width = 520;
+    const height = 720;
+    const left = Math.max(0, Math.round(win.screenX + (win.outerWidth - width) / 2));
+    const top = Math.max(0, Math.round(win.screenY + (win.outerHeight - height) / 2));
+    return `popup,width=${width},height=${height},left=${left},top=${top}`;
+}
 /**
  * Sign-in with Civitai for an app outside civitai.com. Completes the return
  * from Civitai when the page has just come back from it.
@@ -72,6 +83,9 @@ export async function createSignIn(options) {
     const doFetch = options.fetch ?? fetch.bind(globalThis);
     const authUrl = options.authUrl ?? DEFAULT_AUTH_URL;
     const key = `civitai.sign-in.${options.clientId}`;
+    // A same-origin channel, not `popup.opener`: Civitai may pass the popup through Google, whose
+    // opener policy cuts that link for good.
+    const channelName = key;
     const pendingKey = `${key}.pending`;
     const returningKey = `${key}.returning`;
     const requested = scopeBitmask(options.scopes);
@@ -123,15 +137,14 @@ export async function createSignIn(options) {
         });
         return refreshing;
     };
-    const signIn = async ({ scopes } = {}) => {
-        const verifier = randomString();
-        const pending = {
-            state: randomString(),
-            verifier,
-            redirectUri: options.redirectUri ?? `${win.location.origin}${win.location.pathname}`,
-            scope: requested | (scopes ? scopeBitmask(scopes) : 0) | (tokens?.scope ?? 0),
-        };
-        writeJson(storage, pendingKey, pending);
+    const newPending = (scopes, popup) => ({
+        state: randomString(),
+        verifier: randomString(),
+        redirectUri: options.redirectUri ?? `${win.location.origin}${win.location.pathname}`,
+        scope: requested | (scopes ? scopeBitmask(scopes) : 0) | (tokens?.scope ?? 0),
+        ...(popup ? { popup: true } : {}),
+    });
+    const authorizeUrl = async (pending) => {
         const url = new URL('/api/auth/oauth/authorize', authUrl);
         url.search = new URLSearchParams({
             client_id: options.clientId,
@@ -139,33 +152,79 @@ export async function createSignIn(options) {
             response_type: 'code',
             state: pending.state,
             scope: String(pending.scope),
-            code_challenge: await challengeFor(verifier),
+            code_challenge: await challengeFor(pending.verifier),
             code_challenge_method: 'S256',
         }).toString();
-        win.location.assign(url.toString());
+        return url.toString();
+    };
+    const complete = async (pending, params) => {
+        const code = params.get('code');
+        if (!code)
+            throw new SignInError(params.get('error_description') ?? params.get('error') ?? 'sign-in was declined');
+        save(await tokenRequest({ grant_type: 'authorization_code', code, redirect_uri: pending.redirectUri, code_verifier: pending.verifier }, pending.scope));
+    };
+    const signIn = async ({ scopes } = {}) => {
+        const pending = newPending(scopes, false);
+        writeJson(storage, pendingKey, pending);
+        win.location.assign(await authorizeUrl(pending));
         return new Promise(() => { });
     };
+    const signInWithPopup = async ({ scopes, signal } = {}) => {
+        // Written before the popup opens: a popup starts with a copy of this page's sessionStorage.
+        const pending = newPending(scopes, true);
+        writeJson(storage, pendingKey, pending);
+        const popup = win.open('about:blank', key, popupFeatures(win));
+        if (!popup) {
+            writeJson(storage, pendingKey, null);
+            throw new SignInError('the browser blocked the sign-in popup', undefined, { code: 'popup-blocked' });
+        }
+        const channel = new BroadcastChannel(channelName);
+        try {
+            const returned = new Promise((resolve, reject) => {
+                channel.onmessage = (event) => {
+                    const params = new URLSearchParams(typeof event.data?.search === 'string' ? event.data.search : '');
+                    if (params.get('state') === pending.state)
+                        resolve(params);
+                };
+                if (signal?.aborted)
+                    reject(canceled());
+                signal?.addEventListener('abort', () => reject(canceled()), { once: true });
+            });
+            popup.location.replace(await authorizeUrl(pending));
+            await complete(pending, await returned);
+            error = null;
+        }
+        finally {
+            channel.close();
+            if (readJson(storage, pendingKey)?.state === pending.state)
+                writeJson(storage, pendingKey, null);
+            if (!popup.closed)
+                popup.close();
+        }
+    };
     const params = new URLSearchParams(win.location.search);
     const pending = readJson(storage, pendingKey);
     if (pending && params.get('state') === pending.state) {
-        writeJson(storage, pendingKey, null);
-        const code = params.get('code');
         const clean = new URL(win.location.href);
         for (const key of ['code', 'state', 'error', 'error_description'])
             clean.searchParams.delete(key);
-        win.history.replaceState(win.history.state, '', clean.toString());
-        try {
-            if (!code)
-                throw new SignInError(params.get('error_description') ?? params.get('error') ?? 'sign-in was declined');
-            save(await tokenRequest({
-                grant_type: 'authorization_code',
-                code,
-                redirect_uri: pending.redirectUri,
-                code_verifier: pending.verifier,
-            }, pending.scope));
+        if (pending.popup) {
+            // This is the popup: the page that opened it holds the verifier and does the exchange.
+            const channel = new BroadcastChannel(channelName);
+            channel.postMessage({ search: win.location.search });
+            channel.close();
+            win.history.replaceState(win.history.state, '', clean.toString());
+            win.close();
         }
-        catch (err) {
-            error = err instanceof SignInError ? err : new SignInError('sign-in failed', undefined, { cause: err });
+        else {
+            writeJson(storage, pendingKey, null);
+            win.history.replaceState(win.history.state, '', clean.toString());
+            try {
+                await complete(pending, params);
+            }
+            catch (err) {
+                error = err instanceof SignInError ? err : new SignInError('sign-in failed', undefined, { cause: err });
+            }
         }
     }
     return {
@@ -194,6 +253,7 @@ export async function createSignIn(options) {
             return signIn({ scopes });
         },
         signIn,
+        signInWithPopup,
         signOut: async () => {
             const held = tokens;
             save(null);

package/package.json

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