@marianmeres/ownsuite 2.1.0 → 2.2.2

package/AGENTS.md

@@ -6,7 +6,7 @@ Machine-readable documentation for AI coding assistants.
 
 ```yaml
 name: "@marianmeres/ownsuite"
-version: "2.0.0"
+version: "2.1.0"
 type: "library"
 language: "typescript"
 runtime: "deno"
@@ -153,16 +153,23 @@ export {
 	createMockAuthAdapter, createMockProfileAdapter,
 	createMockAuthStore, verifyMockAccount,
 } from "./adapters/mod.ts";
-export type { MockAuthStore } from "./adapters/mod.ts";
+export type { MockAccount, MockAuthStore } from "./adapters/mod.ts";
+
+// Upstream types re-exported so they appear in the public doc graph
+// (they already surface as return types of subscribe / on). Not intended
+// as primary consumer API — use them only when typing wrappers.
+export type { PubSub, Subscriber, Unsubscriber } from "@marianmeres/pubsub";
+export type { StoreLike } from "@marianmeres/store";
+export type { Clog } from "@marianmeres/clog";
 ```
 
 ## Account lifecycle (optional)
 
 When `adapters.auth` is supplied, `createOwnsuite` instantiates three extra managers and attaches them as readonly suite properties:
 
-- **`suite.session: SessionManager`** — reactive `{ status, subject, jwt, expiresAt }` persisted via pluggable `SessionStorage` (`"local"` / `"session"` / `"memory"` / custom object). Hydrates on construction; discards expired sessions. Exposes `subscribe` (Svelte-compatible), `get()`, and state-mutation methods (`setAuthenticated`, `setUnverified`, `clear`, `patchSubject`). Writes are driven by `AuthManager`, not consumers directly.
+- **`suite.session: SessionManager`** — reactive `{ status, subject, jwt, expiresAt }` persisted via pluggable `SessionStorage` (`"local"` / `"session"` / `"memory"` / custom object). With a built-in string backend, hydrates by probing in order `local → session → memory` and adopts the first non-expired payload as the active backend for the instance's lifetime (losing backends are wiped). `setAuthenticated({ storage })` pins the session to a specific built-in backend per login ("Remember me"); subsequent `patchSubject` / `setUnverified` writes land on the same backend. `clear()` wipes every built-in backend so stale blobs from a previous toggle don't leak back in. Exposes `subscribe` (Svelte-compatible), `get()`, and state-mutation methods (`setAuthenticated`, `setUnverified`, `clear`, `patchSubject`). Writes are driven by `AuthManager`, not consumers directly.
 
-- **`suite.auth: AuthManager`** — verbs only, no state. `register` / `login` / `logout` / `resendVerification` / `requestPasswordReset` / `changePassword` / `deleteAccount` / `initiateOAuth` (`mode: "popup" | "redirect"`) / `handleOAuthCallback` (redirect mode). Each call pipes the result into the session and fires an `onIdentityChanged` hook that resets + re-initializes every owner-scoped domain with the fresh context.
+- **`suite.auth: AuthManager`** — verbs only, no state. `register(input, options?)` / `login(input, options?)` / `logout` / `resendVerification` / `requestPasswordReset` / `changePassword` / `deleteAccount` / `initiateOAuth(provider, opts)` (`mode: "popup" | "redirect"`) / `handleOAuthCallback(options?)` (redirect mode). The `options.remember` boolean (`true` → localStorage, `false` → sessionStorage, `undefined` → session manager default; same field on `OAuthInitOptions`) pins the resulting session's storage backend. Each call pipes the result into the session and fires an `onIdentityChanged` hook that resets + re-initializes every owner-scoped domain with the fresh context.
 
 - **`suite.profile: ProfileManager`** — singleton (one-row) `/me` CRUD. `fetch` / `update` / `listOAuth` / `unlinkOAuth`. Every successful fetch/update patches the session subject in place so consumers reading `suite.session` see email / roles / verification / connections without a second fetch. Update emits `profile:updated`.
 

package/API.md

@@ -593,10 +593,12 @@ Current JWT, or `null` when anonymous.
 
 Shorthand reads.
 
-#### `session.setAuthenticated({ jwt, subject, expiresAt? })`
+#### `session.setAuthenticated({ jwt, subject, expiresAt?, storage? })`
 
 Enter the `authenticated` state. Normally called by `AuthManager`, not consumers.
 
+- `storage` (`SessionStorageType`, optional) — per-login storage pin. When `"local"` / `"session"` / `"memory"`, switches the active built-in backend for this session (and for subsequent `patchSubject` / `setUnverified` writes). The previously-active built-in backend's blob is wiped as part of the switch so "Remember me" toggles don't leave stale data. Silently ignored when the manager was constructed with a custom `SessionStorage` object, or when the override is itself an object.
+
 #### `session.setUnverified(email)` / `session.clear()` / `session.patchSubject(patch)`
 
 Mutation helpers — typically driven by `AuthManager` / `ProfileManager`.
@@ -613,15 +615,15 @@ Verbs only. Attached as `suite.auth`. No state of its own — results flow into
 
 | Method | Purpose |
 |---|---|
-| `register({ email, password, password_confirm, roles?, extras? })` | Create account. Returns an `AuthTokenResult`. When the server's verification gate is on, the result carries `requiresVerification: true` and the session flips to `"unverified"` — no JWT yet. |
-| `login({ email, password })` | Exchange credentials for a JWT. Session flips to `"authenticated"` on success, `"unverified"` if the server reports the gate. |
+| `register({ email, password, password_confirm, roles?, extras? }, options?)` | Create account. Returns an `AuthTokenResult`. When the server's verification gate is on, the result carries `requiresVerification: true` and the session flips to `"unverified"` — no JWT yet. `options.remember` pins the resulting session to `localStorage` (`true`) or `sessionStorage` (`false`); omit to use the `SessionManager` default. |
+| `login({ email, password }, options?)` | Exchange credentials for a JWT. Session flips to `"authenticated"` on success, `"unverified"` if the server reports the gate. `options.remember` selects per-login storage (see `register`). |
 | `logout()` | Best-effort server revoke + local clear. Idempotent. |
 | `resendVerification({ email, lang? })` | Trigger a fresh verification email. Anti-enumeration: always resolves. |
 | `requestPasswordReset({ email, lang? })` | Trigger a password-reset email. Anti-enumeration. |
 | `changePassword({ current_password?, new_password, confirm_password, token? })` | Authenticated self-change (with `current_password`) or token-based reset. |
 | `deleteAccount({ password?, confirm? })` | Irreversible server delete + local session clear + identity-changed hook. |
-| `initiateOAuth(provider, opts)` | Start an OAuth flow. `mode: "popup"` (default) resolves with the auth result from the popup's `postMessage`; `mode: "redirect"` navigates the top window. |
-| `handleOAuthCallback()` | For `mode: "redirect"` apps, call from your callback route to extract the result from the URL (delegated to `adapter.handleOAuthCallback`). |
+| `initiateOAuth(provider, opts)` | Start an OAuth flow. `mode: "popup"` (default) resolves with the auth result from the popup's `postMessage`; `mode: "redirect"` navigates the top window. `opts.remember` pins the resulting session's storage backend (only meaningful for `action: "login"`). |
+| `handleOAuthCallback(options?)` | For `mode: "redirect"` apps, call from your callback route to extract the result from the URL (delegated to `adapter.handleOAuthCallback`). `options.remember` pins the resulting session's storage — pass the same value the user picked before the redirect. |
 
 Successful identity changes (register-with-autologin, login, OAuth login, logout, deleteAccount) fire the orchestrator's `onIdentityChanged` hook, which resets every owner-scoped domain and re-initializes them with the new context.
 
@@ -735,6 +737,14 @@ interface OAuthInitOptions {
     redirect?: string;
     lang?: string;
     mode?: "popup" | "redirect";  // default "popup"
+    remember?: boolean;           // same semantics as AuthActionOptions.remember
+}
+
+interface AuthActionOptions {
+    /** true → localStorage; false → sessionStorage; undefined → default.
+     *  Ignored when SessionManager was constructed with a custom
+     *  SessionStorage object. */
+    remember?: boolean;
 }
 
 interface OAuthConnection {
@@ -787,9 +797,18 @@ interface StackAccountAdapterOptions {
 
 See [src/oauth/popup.ts](src/oauth/popup.ts) for full definitions. `OAuthPopupMessage` is a union of `OAuthPopupLoginMessage` (`{ type: "oauth_login_success", jwt, email, roles?, ... }`) and `OAuthPopupLinkMessage` (`{ type: "oauth_link_success", provider }`). Errors posted by the server (`{ type: "oauth_error", error }`) cause the promise to reject.
 
-### `MockAuthStore`
+### `MockAccount` / `MockAuthStore`
 
 ```typescript
+interface MockAccount {
+    email: string;
+    password: string;         // plaintext — mock does no hashing
+    roles: string[];
+    isVerified: boolean;
+    hasPassword: boolean;
+    oauthConnections: OAuthConnection[];
+}
+
 interface MockAuthStore {
     accounts: Map<string, MockAccount>;
     requireVerifiedEmail: boolean;
@@ -797,6 +816,8 @@ interface MockAuthStore {
 }
 ```
 
+Fields are public by design so test code can peek at / mutate them directly.
+
 ---
 
 ## Account-lifecycle events

package/README.md

@@ -67,7 +67,10 @@ await suite.auth!.register({
 // suite.session!.get().status === "unverified"
 
 // After the user clicks the email link and the server flips isVerified:
-await suite.auth!.login({ email: "alice@example.com", password: "mysecretpassword" });
+await suite.auth!.login(
+  { email: "alice@example.com", password: "mysecretpassword" },
+  { remember: true }, // true → localStorage; false → sessionStorage (per-login override)
+);
 // suite.session!.get().status === "authenticated"
 // Every registered owner-scoped domain is re-initialized with the new JWT.
 
@@ -86,7 +89,7 @@ await suite.profile!.update({
 await suite.auth!.logout();
 ```
 
-Session state is persisted through a pluggable `SessionStorage` backend (`"local"` / `"session"` / `"memory"` / custom object with `get`/`set`/`del`). Expired stored sessions are discarded on construction so a reload after the JWT lapses starts anonymous.
+Session state is persisted through a pluggable `SessionStorage` backend (`"local"` / `"session"` / `"memory"` / custom object with `get`/`set`/`del`). Expired stored sessions are discarded on construction so a reload after the JWT lapses starts anonymous. With a built-in string backend, hydration probes `local → session → memory` and adopts whichever holds a non-expired payload — the per-login `remember` flag on `auth.login` / `auth.register` / `auth.initiateOAuth` (`true` → `localStorage`, `false` → `sessionStorage`) switches the active backend for that session, and `session.clear()` wipes all built-in backends so toggles can't leak stale data.
 
 Tests can use the in-memory mock adapters (`createMockAuthAdapter`, `createMockProfileAdapter`, `createMockAuthStore`, `verifyMockAccount`) and the injectable popup host for deterministic OAuth dances.
 

package/dist/adapters/mock-auth.d.ts

@@ -10,15 +10,27 @@
  * adapters close over, so tests can peek at or mutate state directly.
  */
 import type { AuthAdapter, OAuthConnection, ProfileAdapter } from "../types/mod.js";
-interface MockAccount {
+/** In-memory account record held by {@link MockAuthStore}. Test code may
+ *  construct these via the `seed` option of {@link createMockAuthStore}. */
+export interface MockAccount {
+    /** Email (and implicit primary key in the mock store). */
     email: string;
+    /** Plaintext password — the mock runs no hashing. */
     password: string;
+    /** Authorization roles returned on the next login / `/me` read. */
     roles: string[];
+    /** Verified flag — flipped by {@link verifyMockAccount}. */
     isVerified: boolean;
+    /** Whether the account has a local password (OAuth-only accounts: `false`). */
     hasPassword: boolean;
+    /** Linked OAuth provider connections. */
     oauthConnections: OAuthConnection[];
 }
+/** In-memory store backing the mock auth + profile adapters. Pass the same
+ *  store to `createMockAuthAdapter` and `createMockProfileAdapter` so they
+ *  share state. Fields are public so test code can peek or mutate them. */
 export interface MockAuthStore {
+    /** Account records, keyed by email. */
     accounts: Map<string, MockAccount>;
     /** If true, register/login return requiresVerification=true until the
      *  email is explicitly verified via `verifyMockAccount()`. */
@@ -26,13 +38,23 @@ export interface MockAuthStore {
     /** Last-issued JWT per email (just a synthetic string). */
     jwtsByEmail: Map<string, string>;
 }
+/** Create a fresh in-memory {@link MockAuthStore}. Pass `seed` to preload
+ *  accounts, `requireVerifiedEmail: true` to make login gate on verification. */
 export declare function createMockAuthStore(init?: {
+    /** When true, register/login return `requiresVerification: true` until
+     *  the account is verified via {@link verifyMockAccount}. Default: `false`. */
     requireVerifiedEmail?: boolean;
+    /** Accounts to preload into the store. */
     seed?: MockAccount[];
 }): MockAuthStore;
+/** Build an {@link AuthAdapter} backed by the given in-memory
+ *  {@link MockAuthStore}. Simulates register / login / password change /
+ *  delete without a server. JWTs are synthetic strings — do not ship. */
 export declare function createMockAuthAdapter(store: MockAuthStore): AuthAdapter;
+/** Build a {@link ProfileAdapter} backed by the given {@link MockAuthStore}.
+ *  Shares state with an auth adapter created from the same store so login-
+ *  then-`/me` round-trips reflect each other. */
 export declare function createMockProfileAdapter(store: MockAuthStore): ProfileAdapter;
 /** Test helper — mark a mock account as verified as if the user had clicked
  *  the link in the verification email. */
 export declare function verifyMockAccount(store: MockAuthStore, email: string): void;
-export {};

package/dist/adapters/mock-auth.js

@@ -9,6 +9,8 @@
  * Deliberately small: everything is held in a shared `Store` object the
  * adapters close over, so tests can peek at or mutate state directly.
  */
+/** Create a fresh in-memory {@link MockAuthStore}. Pass `seed` to preload
+ *  accounts, `requireVerifiedEmail: true` to make login gate on verification. */
 export function createMockAuthStore(init = {}) {
     const store = {
         accounts: new Map(),
@@ -23,6 +25,9 @@ export function createMockAuthStore(init = {}) {
 function mintJwt(email) {
     return `mock.${btoa(email)}.${Date.now().toString(36)}`;
 }
+/** Build an {@link AuthAdapter} backed by the given in-memory
+ *  {@link MockAuthStore}. Simulates register / login / password change /
+ *  delete without a server. JWTs are synthetic strings — do not ship. */
 export function createMockAuthAdapter(store) {
     return {
         register(input, _ctx) {
@@ -148,6 +153,9 @@ export function createMockAuthAdapter(store) {
         },
     };
 }
+/** Build a {@link ProfileAdapter} backed by the given {@link MockAuthStore}.
+ *  Shares state with an auth adapter created from the same store so login-
+ *  then-`/me` round-trips reflect each other. */
 export function createMockProfileAdapter(store) {
     function emailFromCtx(ctx) {
         const jwt = ctx.jwt;

package/dist/adapters/mock.d.ts

@@ -8,6 +8,8 @@
  * path deterministically.
  */
 import type { OwnedCollectionAdapter } from "../types/adapter.js";
+/** Options for {@link createMockOwnedCollectionAdapter}. Only present in
+ *  tests / storybooks — production code never calls this. */
 export interface MockAdapterOptions<TRow> {
     /** Initial seed rows. */
     seed?: TRow[];

package/dist/adapters/stack-account.d.ts

@@ -28,11 +28,18 @@
  * AuthAdapter / ProfileAdapter interfaces.
  */
 import type { AuthAdapter, ProfileAdapter } from "../types/mod.js";
+/** Options shared by the two stack-account adapter factories. */
 export interface StackAccountAdapterOptions {
     /** Base URL of the mounted stack-account app. Default: "/api/account". */
     baseUrl?: string;
     /** Override the `fetch` implementation (useful for tests / SSR). */
     fetch?: typeof fetch;
 }
+/** Build the default {@link AuthAdapter} for `@marianmeres/stack-account`.
+ *  Points at `{baseUrl}/auth/*` (register/login/logout/verify/password/
+ *  delete) and `{baseUrl}/oauth/*` (init + callback). */
 export declare function createStackAccountAuthAdapter(opts?: StackAccountAdapterOptions): AuthAdapter;
+/** Build the default {@link ProfileAdapter} for `@marianmeres/stack-account`.
+ *  Points at `{baseUrl}/me` (GET + PUT) and `{baseUrl}/me/oauth/*` for
+ *  connection listing / unlinking. */
 export declare function createStackAccountProfileAdapter(opts?: StackAccountAdapterOptions): ProfileAdapter;

package/dist/adapters/stack-account.js

@@ -82,6 +82,9 @@ async function requestJson(doFetch, url, init, ctx) {
         return undefined;
     return (await res.json());
 }
+/** Build the default {@link AuthAdapter} for `@marianmeres/stack-account`.
+ *  Points at `{baseUrl}/auth/*` (register/login/logout/verify/password/
+ *  delete) and `{baseUrl}/oauth/*` (init + callback). */
 export function createStackAccountAuthAdapter(opts = {}) {
     const base = opts.baseUrl ?? "/api/account";
     const doFetch = resolveFetch(opts);
@@ -123,6 +126,9 @@ export function createStackAccountAuthAdapter(opts = {}) {
         },
     };
 }
+/** Build the default {@link ProfileAdapter} for `@marianmeres/stack-account`.
+ *  Points at `{baseUrl}/me` (GET + PUT) and `{baseUrl}/me/oauth/*` for
+ *  connection listing / unlinking. */
 export function createStackAccountProfileAdapter(opts = {}) {
     const base = opts.baseUrl ?? "/api/account";
     const doFetch = resolveFetch(opts);

package/dist/domains/auth.d.ts

@@ -12,16 +12,22 @@
  * management.
  */
 import { type PubSub } from "@marianmeres/pubsub";
-import type { AuthAdapter, AuthTokenResult, OAuthInitOptions, OAuthProvider, OwnsuiteContext, ProfileAdapter } from "../types/mod.js";
+import type { AuthActionOptions, AuthAdapter, AuthTokenResult, OAuthInitOptions, OAuthProvider, OwnsuiteContext, ProfileAdapter } from "../types/mod.js";
 import type { SessionManager } from "./session.js";
 import type { ProfileManager } from "./profile.js";
+/** Construction-time options for {@link AuthManager}. Normally assembled
+ *  by `createOwnsuite` — call sites rarely instantiate this directly. */
 export interface AuthManagerOptions {
+    /** Server adapter. The manager is stateless beyond what it pushes into
+     *  {@link SessionManager}. */
     adapter: AuthAdapter;
+    /** Session manager that receives the JWT / subject / status writes. */
     session: SessionManager;
     /** Profile manager — auth hydrates the session subject from `/me`
      *  immediately after login so subscribers see roles/isVerified/etc.
      *  without a second await. */
     profile: ProfileManager;
+    /** Shared pubsub for event emission. Created privately when omitted. */
     pubsub?: PubSub;
     /** Called after a successful identity change (register/login/OAuth
      *  login/logout). The orchestrator wires this to reset + re-init every
@@ -35,37 +41,73 @@ export interface AuthManagerOptions {
      *  tests that don't need a separate profile fetch. */
     profileAdapter?: ProfileAdapter;
 }
+/**
+ * Verbs for the account lifecycle: register / login / logout / OAuth /
+ * password-reset / delete account. Holds no state of its own — every
+ * outcome is piped into the linked {@link SessionManager}, which is the
+ * single source of truth for JWT + subject + status. Usually accessed via
+ * `suite.auth`, not constructed directly.
+ */
 export declare class AuthManager {
     #private;
+    /** Construct a new `AuthManager`. Normally called by `createOwnsuite`,
+     *  not by consumers. */
     constructor(options: AuthManagerOptions);
+    /** Merge `ctx` into the current adapter context. Keys not in `ctx`
+     *  are preserved. */
     setContext(ctx: OwnsuiteContext): void;
+    /** Replace the adapter context wholesale. Callers use this when
+     *  switching subjects or clearing host-app context. */
     replaceContext(ctx: OwnsuiteContext): void;
+    /** Create a new account. Returns the server's {@link AuthTokenResult}.
+     *  When the verification gate is on, the result carries
+     *  `requiresVerification: true` and the session flips to `"unverified"`
+     *  (no JWT). Otherwise the session flips to `"authenticated"` and the
+     *  profile is hydrated from `/me`. `options.remember` pins the session's
+     *  storage backend — see {@link AuthActionOptions.remember}. */
     register(input: {
         email: string;
         password: string;
         password_confirm: string;
         roles?: string[];
         extras?: Record<string, unknown>;
-    }): Promise<AuthTokenResult>;
+    }, options?: AuthActionOptions): Promise<AuthTokenResult>;
+    /** Exchange credentials for a JWT. On success the session flips to
+     *  `"authenticated"` and the profile is hydrated from `/me`. Rejects
+     *  on bad credentials (session untouched) or — when the server's
+     *  verification gate is on for an unverified account — throws through
+     *  the adapter. `options.remember` controls storage persistence. */
     login(input: {
         email: string;
         password: string;
-    }): Promise<AuthTokenResult>;
+    }, options?: AuthActionOptions): Promise<AuthTokenResult>;
+    /** Log out. Best-effort server revoke + unconditional local clear;
+     *  the session is always wiped even if the server call fails. Fires
+     *  `auth:logout` and the `onIdentityChanged` hook. Safe to call when
+     *  already anonymous. */
     logout(): Promise<void>;
+    /** Trigger a fresh verification email. Anti-enumeration: always resolves
+     *  regardless of whether the address corresponds to a real account. */
     resendVerification(input: {
         email: string;
         lang?: string;
     }): Promise<void>;
+    /** Trigger a password-reset email. Anti-enumeration: always resolves. */
     requestPasswordReset(input: {
         email: string;
         lang?: string;
     }): Promise<void>;
+    /** Change the password. Pass `current_password` for an authenticated
+     *  self-change, or `token` for a reset-link flow. `new_password` and
+     *  `confirm_password` are always required. */
     changePassword(input: {
         current_password?: string;
         new_password: string;
         confirm_password: string;
         token?: string;
     }): Promise<void>;
+    /** Irreversibly delete the authenticated account. On success clears the
+     *  local session and fires `auth:logout` + `onIdentityChanged`. */
     deleteAccount(input: {
         password?: string;
         confirm?: boolean;
@@ -78,6 +120,8 @@ export declare class AuthManager {
      */
     initiateOAuth(provider: OAuthProvider, opts: OAuthInitOptions): Promise<AuthTokenResult | void>;
     /** For the redirect-mode callback page: delegate to the adapter if
-     *  available to extract the result from the current URL/page state. */
-    handleOAuthCallback(): Promise<AuthTokenResult | void>;
+     *  available to extract the result from the current URL/page state.
+     *  `options.remember` pins the resulting session to local/session
+     *  storage — pass the same value the user picked before the redirect. */
+    handleOAuthCallback(options?: AuthActionOptions): Promise<AuthTokenResult | void>;
 }

package/dist/domains/auth.js

@@ -13,6 +13,13 @@
  */
 import { createPubSub } from "@marianmeres/pubsub";
 import { openOAuthPopup } from "../oauth/popup.js";
+/**
+ * Verbs for the account lifecycle: register / login / logout / OAuth /
+ * password-reset / delete account. Holds no state of its own — every
+ * outcome is piped into the linked {@link SessionManager}, which is the
+ * single source of truth for JWT + subject + status. Usually accessed via
+ * `suite.auth`, not constructed directly.
+ */
 export class AuthManager {
     #pubsub;
     #adapter;
@@ -20,6 +27,8 @@ export class AuthManager {
     #profile;
     #onIdentityChanged;
     #context;
+    /** Construct a new `AuthManager`. Normally called by `createOwnsuite`,
+     *  not by consumers. */
     constructor(options) {
         this.#adapter = options.adapter;
         this.#session = options.session;
@@ -28,9 +37,13 @@ export class AuthManager {
         this.#onIdentityChanged = options.onIdentityChanged;
         this.#context = options.context ?? {};
     }
+    /** Merge `ctx` into the current adapter context. Keys not in `ctx`
+     *  are preserved. */
     setContext(ctx) {
         this.#context = { ...this.#context, ...ctx };
     }
+    /** Replace the adapter context wholesale. Callers use this when
+     *  switching subjects or clearing host-app context. */
     replaceContext(ctx) {
         this.#context = { ...ctx };
     }
@@ -46,8 +59,13 @@ export class AuthManager {
      *  present, we pull the profile to build a complete subject. When the
      *  server returned requiresVerification, we surface the "unverified"
      *  status without any profile fetch. Triggers identity-change hook on
-     *  actual login. */
-    async #applyAuthResult(result) {
+     *  actual login.
+     *
+     *  `remember` translates to a per-login storage pin on the session:
+     *  `true` → `"local"`, `false` → `"session"`, `undefined` → session
+     *  manager's configured default. Silently no-op in the verification-gate
+     *  branch (no JWT yet → nothing to persist). */
+    async #applyAuthResult(result, remember) {
         if (result.requiresVerification || !result.jwt) {
             this.#session.setUnverified(result.email);
             this.#pubsub.publish("auth:verification:required", {
@@ -66,10 +84,16 @@ export class AuthManager {
             isVerified: result.isVerified ?? false,
             hasPassword: true, // corrected by profile fetch below
         };
+        const storage = remember === true
+            ? "local"
+            : remember === false
+                ? "session"
+                : undefined;
         this.#session.setAuthenticated({
             jwt: result.jwt,
             subject: provisional,
             expiresAt: result.validUntil ?? null,
+            ...(storage ? { storage } : {}),
         });
         // Best-effort hydrate the subject from /me. If this fails we keep the
         // provisional subject; consumers can retry via profile.fetch().
@@ -90,7 +114,13 @@ export class AuthManager {
         return result;
     }
     // ─────────────────────── verbs ──────────────────────────────────────────
-    async register(input) {
+    /** Create a new account. Returns the server's {@link AuthTokenResult}.
+     *  When the verification gate is on, the result carries
+     *  `requiresVerification: true` and the session flips to `"unverified"`
+     *  (no JWT). Otherwise the session flips to `"authenticated"` and the
+     *  profile is hydrated from `/me`. `options.remember` pins the session's
+     *  storage backend — see {@link AuthActionOptions.remember}. */
+    async register(input, options) {
         const result = await this.#adapter.register(input, this.#ctx());
         this.#pubsub.publish("auth:register", {
             type: "auth:register",
@@ -98,17 +128,26 @@ export class AuthManager {
             email: input.email,
             requiresVerification: Boolean(result.requiresVerification),
         });
-        return await this.#applyAuthResult(result);
+        return await this.#applyAuthResult(result, options?.remember);
     }
-    async login(input) {
+    /** Exchange credentials for a JWT. On success the session flips to
+     *  `"authenticated"` and the profile is hydrated from `/me`. Rejects
+     *  on bad credentials (session untouched) or — when the server's
+     *  verification gate is on for an unverified account — throws through
+     *  the adapter. `options.remember` controls storage persistence. */
+    async login(input, options) {
         const result = await this.#adapter.login(input, this.#ctx());
         this.#pubsub.publish("auth:login", {
             type: "auth:login",
             timestamp: Date.now(),
             email: input.email,
         });
-        return await this.#applyAuthResult(result);
+        return await this.#applyAuthResult(result, options?.remember);
     }
+    /** Log out. Best-effort server revoke + unconditional local clear;
+     *  the session is always wiped even if the server call fails. Fires
+     *  `auth:logout` and the `onIdentityChanged` hook. Safe to call when
+     *  already anonymous. */
     async logout() {
         const subjectId = this.#session.get().subject?.id;
         try {
@@ -132,15 +171,23 @@ export class AuthManager {
             }
         }
     }
+    /** Trigger a fresh verification email. Anti-enumeration: always resolves
+     *  regardless of whether the address corresponds to a real account. */
     async resendVerification(input) {
         await this.#adapter.resendVerification(input, this.#ctx());
     }
+    /** Trigger a password-reset email. Anti-enumeration: always resolves. */
     async requestPasswordReset(input) {
         await this.#adapter.requestPasswordReset(input, this.#ctx());
     }
+    /** Change the password. Pass `current_password` for an authenticated
+     *  self-change, or `token` for a reset-link flow. `new_password` and
+     *  `confirm_password` are always required. */
     async changePassword(input) {
         await this.#adapter.changePassword(input, this.#ctx());
     }
+    /** Irreversibly delete the authenticated account. On success clears the
+     *  local session and fires `auth:logout` + `onIdentityChanged`. */
     async deleteAccount(input) {
         await this.#adapter.deleteAccount(input, this.#ctx());
         // Clear session locally and fire logout/identity-change.
@@ -197,15 +244,17 @@ export class AuthManager {
             roles: message.roles ?? [],
             isVerified: true,
         };
-        return await this.#applyAuthResult(result);
+        return await this.#applyAuthResult(result, opts.remember);
     }
     /** For the redirect-mode callback page: delegate to the adapter if
-     *  available to extract the result from the current URL/page state. */
-    async handleOAuthCallback() {
+     *  available to extract the result from the current URL/page state.
+     *  `options.remember` pins the resulting session to local/session
+     *  storage — pass the same value the user picked before the redirect. */
+    async handleOAuthCallback(options) {
         if (!this.#adapter.handleOAuthCallback) {
             throw new Error("AuthManager: handleOAuthCallback is not implemented by the adapter");
         }
         const result = await this.#adapter.handleOAuthCallback(this.#ctx());
-        return await this.#applyAuthResult(result);
+        return await this.#applyAuthResult(result, options?.remember);
     }
 }

package/dist/domains/base.d.ts

@@ -27,12 +27,24 @@ export interface BaseDomainOptions {
  */
 export declare abstract class BaseDomainManager<TData, TAdapter> {
     #private;
+    /** Reactive store holding the full {@link DomainStateWrapper} for this
+     *  domain. Subclasses read + publish through it. */
     protected readonly store: StoreLike<DomainStateWrapper<TData>>;
+    /** Shared pubsub used to emit domain lifecycle / CRUD events. */
     protected readonly pubsub: PubSub;
+    /** Stable name of this domain (used as event `domain` and log prefix). */
     protected readonly domainName: DomainName;
+    /** Scoped logger, prefixed with `ownsuite:<domainName>`. */
     protected readonly clog: Clog;
+    /** Server adapter instance; `null` until `setAdapter()` / constructor
+     *  installs one. */
     protected adapter: TAdapter | null;
+    /** Current context forwarded to every adapter call (jwt, subjectId,
+     *  signal, plus any consumer-supplied extras). */
     protected context: OwnsuiteContext;
+    /** Construct a new domain manager. Not called directly — subclasses like
+     *  {@link OwnedCollectionManager} extend this and are instantiated by
+     *  the suite. */
     constructor(domainName: DomainName, options?: BaseDomainOptions);
     /** Svelte-compatible subscribe method. */
     get subscribe(): StoreLike<DomainStateWrapper<TData>>["subscribe"];
@@ -40,7 +52,11 @@ export declare abstract class BaseDomainManager<TData, TAdapter> {
     get(): DomainStateWrapper<TData>;
     /** True after `destroy()` has been called. */
     get isDestroyed(): boolean;
+    /** Install or replace the server adapter for this domain. Call
+     *  {@link refresh} afterwards to pick up data from the new source. */
     setAdapter(adapter: TAdapter): void;
+    /** Current adapter, or `null` when none installed (typically only in
+     *  tests or between `destroy()` and re-attachment). */
     getAdapter(): TAdapter | null;
     /**
      * Merge `ctx` into the current context. Keys not present in `ctx` are
@@ -49,6 +65,8 @@ export declare abstract class BaseDomainManager<TData, TAdapter> {
     setContext(context: OwnsuiteContext): void;
     /** Replace the context object entirely (no merge with existing). */
     replaceContext(context: OwnsuiteContext): void;
+    /** Snapshot of the current context. Mutating the returned object does
+     *  not affect the manager. */
     getContext(): OwnsuiteContext;
     /** Transition to a new state. */
     protected setState(state: DomainState): void;
@@ -101,6 +119,8 @@ export declare abstract class BaseDomainManager<TData, TAdapter> {
      * callers that prefer a whole-data restore over per-change inversion.
      */
     protected withOptimisticUpdate<T>(operation: string, optimisticUpdate: () => void, serverSync: () => Promise<T>, onSuccess?: (result: T) => void, onError?: (error: DomainError, snapshot: TData | null) => void): Promise<void>;
+    /** Boot the domain — typically fetch its initial list. Subclasses
+     *  implement this; see {@link OwnedCollectionManager.initialize}. */
     abstract initialize(): Promise<void>;
     /**
      * Reset to `initializing` state. Aborts any in-flight reads/mutations

package/dist/domains/base.js

@@ -38,11 +38,20 @@ function safeClone(value) {
  * @typeParam TAdapter - The adapter interface type for server communication.
  */
 export class BaseDomainManager {
+    /** Reactive store holding the full {@link DomainStateWrapper} for this
+     *  domain. Subclasses read + publish through it. */
     store;
+    /** Shared pubsub used to emit domain lifecycle / CRUD events. */
     pubsub;
+    /** Stable name of this domain (used as event `domain` and log prefix). */
     domainName;
+    /** Scoped logger, prefixed with `ownsuite:<domainName>`. */
     clog;
+    /** Server adapter instance; `null` until `setAdapter()` / constructor
+     *  installs one. */
     adapter = null;
+    /** Current context forwarded to every adapter call (jwt, subjectId,
+     *  signal, plus any consumer-supplied extras). */
     context = {};
     /** Mutation chain head. Each create/update/delete appends itself here. */
     #mutationChain = Promise.resolve();
@@ -51,6 +60,9 @@ export class BaseDomainManager {
     /** All active controllers created via `newController()`, for bulk abort. */
     #activeControllers = new Set();
     #destroyed = false;
+    /** Construct a new domain manager. Not called directly — subclasses like
+     *  {@link OwnedCollectionManager} extend this and are instantiated by
+     *  the suite. */
     constructor(domainName, options = {}) {
         this.domainName = domainName;
         this.clog = createClog(`ownsuite:${domainName}`, { color: "auto" });
@@ -76,9 +88,13 @@ export class BaseDomainManager {
     get isDestroyed() {
         return this.#destroyed;
     }
+    /** Install or replace the server adapter for this domain. Call
+     *  {@link refresh} afterwards to pick up data from the new source. */
     setAdapter(adapter) {
         this.adapter = adapter;
     }
+    /** Current adapter, or `null` when none installed (typically only in
+     *  tests or between `destroy()` and re-attachment). */
     getAdapter() {
         return this.adapter;
     }
@@ -93,6 +109,8 @@ export class BaseDomainManager {
     replaceContext(context) {
         this.context = { ...context };
     }
+    /** Snapshot of the current context. Mutating the returned object does
+     *  not affect the manager. */
     getContext() {
         return { ...this.context };
     }