@ai-matrx/auth 0.2.2 → 0.2.4

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog — @ai-matrx/auth
 
+## 0.2.4
+### active organization options (round 2)
+
+All options default to today's behaviour. `createActiveOrganization`:
+- `accountChoices` — the snapshot carries `favourites` and `startupOrganizationId` (always present: `[]` / null when off); when on,
+  `memberships` is ordered favourites-first and a failed favourites read leaves them out. New `setFavourite(id, on)` (optimistic,
+  rolled back and rethrown on failure) and `setStartup(id | null)`.
+- `cached` `{ userId, read, write? }` — a new `unchecked` status: the memberships could not be read, so the host's cached last answer
+  (or the list already on screen) is shown unverified. `current()` / `ensureOrgId()` answer in `unchecked`.
+- `onLapse({ was, now })` — the organization the person was in is no longer a membership and the ladder chose another.
+- `refreshGapMs` + `refresh({ force? })` — a throttled re-read.
+- `holdResolved` (default true) — false: the ladder's own answer is never written as the held choice; only `switchTo` writes it
+  (the extension's rule).
+- `ActiveOrganizationSnapshot` gains `favourites` and `startupOrganizationId`; new types `CachedActiveOrganization`, `OrganizationLapse`.
+Tests: `active-organization.test.ts` (+9).
+
+## 0.2.3
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/auth/v0.2.2..npm/auth/v0.2.3 -- apps/shared/auth`).
+No source changes intended and no consumer action required.
+
 ## 0.2.2
 ### extension/desktop options (round 2)
 

package/dist/{active-organization-Dy4UtiyR.d.cts → active-organization-Cxm6GDIy.d.cts}

@@ -515,7 +515,11 @@ interface HeldOrganizationStore {
     write(userId: string, organizationId: string): void | Promise<void>;
     clear(): void | Promise<void>;
 }
-type ActiveOrganizationStatus = "idle" | "resolving" | "ready" | "none" | "error";
+/**
+ * `unchecked`: the memberships could not be read, and the answer shown is the host's cached last answer
+ * (`options.cached`), not verified against the database. Only ever produced when `cached` is given.
+ */
+type ActiveOrganizationStatus = "idle" | "resolving" | "ready" | "none" | "error" | "unchecked";
 interface ActiveOrganizationSnapshot {
     readonly status: ActiveOrganizationStatus;
     readonly userId: string | null;
@@ -525,6 +529,25 @@ interface ActiveOrganizationSnapshot {
     /** Which ladder rung answered (or "switched" after a person's click). */
     readonly rung: OrganizationRung | "switched" | "link" | null;
     readonly error: string | null;
+    /**
+     * The account's favourite organization ids. Read only when `options.accountChoices` is on; `[]`
+     * otherwise. When on, `memberships` is ordered favourites, then own, then the rest.
+     */
+    readonly favourites: readonly string[];
+    /** The account's start-up organization setting. Read only when `options.accountChoices` is on; null otherwise. */
+    readonly startupOrganizationId: string | null;
+}
+/** What a host keeps so a launch with no network can still show the last answer (`options.cached`). */
+interface CachedActiveOrganization {
+    readonly memberships: readonly OrganizationMembership[];
+    readonly organizationId: string | null;
+    readonly favourites: readonly string[];
+    readonly startupOrganizationId: string | null;
+}
+/** A held organization that is no longer a membership, and the one the ladder chose instead. */
+interface OrganizationLapse {
+    readonly was: OrganizationMembership;
+    readonly now: OrganizationMembership;
 }
 declare class NoActiveOrganizationError extends Error {
     readonly reason: "signed-out" | "no-memberships" | "unreadable";
@@ -542,6 +565,14 @@ interface ActiveOrganization {
     /** The active organization id now, or null while resolving / with none. Sync (api's getter). */
     current(): string | null;
     /** THE HELD REQUEST: the record's own organization, else the active one once resolved. */
+    /** Re-read, unless `options.refreshGapMs` has not elapsed since the last read (`force` always reads). */
+    refresh(options?: {
+        readonly force?: boolean;
+    }): Promise<ActiveOrganizationSnapshot>;
+    /** Save the account's start-up organization (null: the first). Needs `accountChoices`; throws on refusal. */
+    setStartup(organizationId: string | null): Promise<void>;
+    /** Add or remove a favourite and re-order. Optimistic; rolled back and rethrown if the save fails. */
+    setFavourite(organizationId: string, favourite: boolean): Promise<void>;
     ensureOrgId(recordOrganizationId?: string | null): Promise<string>;
     /** A person's click: switch, remember for this tab, save as last active for the next load. */
     switchTo(organizationId: string): Promise<void>;
@@ -582,13 +613,38 @@ interface CreateActiveOrganizationOptions {
     readonly refusalRecheckGapMs?: number | undefined;
     /** Load as soon as it is created (default true). */
     readonly autoLoad?: boolean | undefined;
+    /**
+     * Read the account's favourites and start-up organization with the memberships, expose both in
+     * the snapshot and order `memberships` favourites-first. A failed favourites read leaves them out
+     * (the list still shows). Default false.
+     */
+    readonly accountChoices?: boolean | undefined;
+    /**
+     * Offline answer. When the memberships cannot be read and nothing is shown yet, the cached answer
+     * is published as `unchecked` if its organization is the held one (or the cached one). `userId`
+     * says whose cache to read when the person cannot be verified; `write` is called after each good read.
+     */
+    readonly cached?: {
+        readonly userId: () => string | null | undefined;
+        readonly read: (userId: string) => CachedActiveOrganization | null | Promise<CachedActiveOrganization | null>;
+        readonly write?: ((userId: string, answer: CachedActiveOrganization) => void | Promise<void>) | undefined;
+    } | undefined;
+    /** Called once when the organization the person was in is no longer a membership and the ladder chose another. */
+    readonly onLapse?: ((lapse: OrganizationLapse) => void) | undefined;
+    /** `refresh()` without `force` does nothing within this many ms of the last read. Default 0 (always reads). */
+    readonly refreshGapMs?: number | undefined;
+    /**
+     * Write the ladder's own answer back as the held organization. Default true. False: only an
+     * explicit `switchTo` writes the held choice (the extension's rule: a computed answer is never a choice).
+     */
+    readonly holdResolved?: boolean | undefined;
 }
 /** A held store over a `Storage` (browser `sessionStorage` = per tab), identity-keyed. */
-declare function storageHeldOrganization(storage: Pick<Storage, "getItem" | "setItem" | "removeItem">, key?: string): HeldOrganizationStore & {
+declare function storageHeldOrganization(storage: Pick<Storage, "getItem" | "setItem" | "removeItem">, key?: string): Omit<HeldOrganizationStore, "read"> & {
     read(userId: string): string | null;
 };
 /** Held in memory: the running app's own choice (desktop, scripts, tests). */
 declare function memoryHeldOrganization(): HeldOrganizationStore;
 declare function createActiveOrganization(options: CreateActiveOrganizationOptions): ActiveOrganization;
 
-export { decideLinkOrganization as $, type AuthClient as A, NotAMemberError as B, type CreateActiveOrganizationOptions as C, type NotAMemberRefusalNotice as D, ORGANIZATION_RESOLUTION_TIMEOUT_MS as E, type OrganizationBootstrapGate as F, type OrganizationMembership as G, type HeldOrganizationStore as H, type OrganizationRefusal as I, type OrganizationRung as J, type OrganizationsDb as K, LINK_ORGANIZATION_QUERY_KEY as L, type ResolveWithLinkInput as M, NOT_A_MEMBER_RECHECK_GAP_MS as N, ORGANIZATION_ENTITY_TYPE as O, type ParentOrganization as P, type ResolvedOrganization as Q, type ReadMembershipsOptions as R, type SessionSourceLike as S, type ResolvedWithLink as T, type UserCredentialsPort as U, adminSeatReplacesUserContext as V, classifyLinkOrganizationValue as W, classifyOrganizationRefusal as X, createActiveOrganization as Y, createNotAMemberRefusalNotice as Z, createOrganizationBootstrapGate as _, SignInError as a, isNotAMemberRefusal as a0, linkOrganizationMalformedMessage as a1, linkOrganizationNotAMemberMessage as a2, linkOrganizationOfferMessage as a3, linkOrganizationSwitchAnnouncement as a4, memoryHeldOrganization as a5, oldestMembership as a6, orderOrganizations as a7, organizationMatches as a8, readAccountOrganizationChoices as a9, readLinkOrganizationParam as aa, readMemberships as ab, readOrganizationFavourites as ac, resolveActiveOrganization as ad, resolveActiveOrganizationLazily as ae, resolveAdminSeat as af, resolveChildOrganizationId as ag, resolveOrganizationWithLink as ah, setOrganizationFavourite as ai, storageHeldOrganization as aj, toAccountOrganizationChoices as ak, writeLastActiveOrganization as al, writeStartupOrganization as am, getSession as b, signInWithOAuth as c, signInWithPassword as d, signOut as e, userCredentials as f, getPerson as g, type AccountOrganizationChoices as h, invalidatePerson as i, type ActiveOrganization as j, type ActiveOrganizationSnapshot as k, type ActiveOrganizationStatus as l, type AdminSeat as m, type AdminSeatInput as n, onSessionChange as o, type ArchiveFilter as p, type LadderInput as q, refreshSession as r, sessionCredentials as s, type LinkOrganizationDecision as t, updatePerson as u, type LinkOrganizationDecisionInput as v, type LinkOrganizationMembership as w, type LinkOrganizationMessages as x, type LinkOrganizationParam as y, NoActiveOrganizationError as z };
+export { createNotAMemberRefusalNotice as $, type AuthClient as A, NoActiveOrganizationError as B, type CachedActiveOrganization as C, NotAMemberError as D, type NotAMemberRefusalNotice as E, ORGANIZATION_RESOLUTION_TIMEOUT_MS as F, type OrganizationBootstrapGate as G, type HeldOrganizationStore as H, type OrganizationLapse as I, type OrganizationMembership as J, type OrganizationRefusal as K, LINK_ORGANIZATION_QUERY_KEY as L, type OrganizationRung as M, NOT_A_MEMBER_RECHECK_GAP_MS as N, ORGANIZATION_ENTITY_TYPE as O, type OrganizationsDb as P, type ParentOrganization as Q, type ReadMembershipsOptions as R, type SessionSourceLike as S, type ResolveWithLinkInput as T, type UserCredentialsPort as U, type ResolvedOrganization as V, type ResolvedWithLink as W, adminSeatReplacesUserContext as X, classifyLinkOrganizationValue as Y, classifyOrganizationRefusal as Z, createActiveOrganization as _, SignInError as a, createOrganizationBootstrapGate as a0, decideLinkOrganization as a1, isNotAMemberRefusal as a2, linkOrganizationMalformedMessage as a3, linkOrganizationNotAMemberMessage as a4, linkOrganizationOfferMessage as a5, linkOrganizationSwitchAnnouncement as a6, memoryHeldOrganization as a7, oldestMembership as a8, orderOrganizations as a9, organizationMatches as aa, readAccountOrganizationChoices as ab, readLinkOrganizationParam as ac, readMemberships as ad, readOrganizationFavourites as ae, resolveActiveOrganization as af, resolveActiveOrganizationLazily as ag, resolveAdminSeat as ah, resolveChildOrganizationId as ai, resolveOrganizationWithLink as aj, setOrganizationFavourite as ak, storageHeldOrganization as al, toAccountOrganizationChoices as am, writeLastActiveOrganization as an, writeStartupOrganization as ao, getSession as b, signInWithOAuth as c, signInWithPassword as d, signOut as e, userCredentials as f, getPerson as g, type AccountOrganizationChoices as h, invalidatePerson as i, type ActiveOrganization as j, type ActiveOrganizationSnapshot as k, type ActiveOrganizationStatus as l, type AdminSeat as m, type AdminSeatInput as n, onSessionChange as o, type ArchiveFilter as p, type CreateActiveOrganizationOptions as q, refreshSession as r, sessionCredentials as s, type LadderInput as t, updatePerson as u, type LinkOrganizationDecision as v, type LinkOrganizationDecisionInput as w, type LinkOrganizationMembership as x, type LinkOrganizationMessages as y, type LinkOrganizationParam as z };

package/dist/{active-organization-Dy4UtiyR.d.ts → active-organization-Cxm6GDIy.d.ts}

@@ -515,7 +515,11 @@ interface HeldOrganizationStore {
     write(userId: string, organizationId: string): void | Promise<void>;
     clear(): void | Promise<void>;
 }
-type ActiveOrganizationStatus = "idle" | "resolving" | "ready" | "none" | "error";
+/**
+ * `unchecked`: the memberships could not be read, and the answer shown is the host's cached last answer
+ * (`options.cached`), not verified against the database. Only ever produced when `cached` is given.
+ */
+type ActiveOrganizationStatus = "idle" | "resolving" | "ready" | "none" | "error" | "unchecked";
 interface ActiveOrganizationSnapshot {
     readonly status: ActiveOrganizationStatus;
     readonly userId: string | null;
@@ -525,6 +529,25 @@ interface ActiveOrganizationSnapshot {
     /** Which ladder rung answered (or "switched" after a person's click). */
     readonly rung: OrganizationRung | "switched" | "link" | null;
     readonly error: string | null;
+    /**
+     * The account's favourite organization ids. Read only when `options.accountChoices` is on; `[]`
+     * otherwise. When on, `memberships` is ordered favourites, then own, then the rest.
+     */
+    readonly favourites: readonly string[];
+    /** The account's start-up organization setting. Read only when `options.accountChoices` is on; null otherwise. */
+    readonly startupOrganizationId: string | null;
+}
+/** What a host keeps so a launch with no network can still show the last answer (`options.cached`). */
+interface CachedActiveOrganization {
+    readonly memberships: readonly OrganizationMembership[];
+    readonly organizationId: string | null;
+    readonly favourites: readonly string[];
+    readonly startupOrganizationId: string | null;
+}
+/** A held organization that is no longer a membership, and the one the ladder chose instead. */
+interface OrganizationLapse {
+    readonly was: OrganizationMembership;
+    readonly now: OrganizationMembership;
 }
 declare class NoActiveOrganizationError extends Error {
     readonly reason: "signed-out" | "no-memberships" | "unreadable";
@@ -542,6 +565,14 @@ interface ActiveOrganization {
     /** The active organization id now, or null while resolving / with none. Sync (api's getter). */
     current(): string | null;
     /** THE HELD REQUEST: the record's own organization, else the active one once resolved. */
+    /** Re-read, unless `options.refreshGapMs` has not elapsed since the last read (`force` always reads). */
+    refresh(options?: {
+        readonly force?: boolean;
+    }): Promise<ActiveOrganizationSnapshot>;
+    /** Save the account's start-up organization (null: the first). Needs `accountChoices`; throws on refusal. */
+    setStartup(organizationId: string | null): Promise<void>;
+    /** Add or remove a favourite and re-order. Optimistic; rolled back and rethrown if the save fails. */
+    setFavourite(organizationId: string, favourite: boolean): Promise<void>;
     ensureOrgId(recordOrganizationId?: string | null): Promise<string>;
     /** A person's click: switch, remember for this tab, save as last active for the next load. */
     switchTo(organizationId: string): Promise<void>;
@@ -582,13 +613,38 @@ interface CreateActiveOrganizationOptions {
     readonly refusalRecheckGapMs?: number | undefined;
     /** Load as soon as it is created (default true). */
     readonly autoLoad?: boolean | undefined;
+    /**
+     * Read the account's favourites and start-up organization with the memberships, expose both in
+     * the snapshot and order `memberships` favourites-first. A failed favourites read leaves them out
+     * (the list still shows). Default false.
+     */
+    readonly accountChoices?: boolean | undefined;
+    /**
+     * Offline answer. When the memberships cannot be read and nothing is shown yet, the cached answer
+     * is published as `unchecked` if its organization is the held one (or the cached one). `userId`
+     * says whose cache to read when the person cannot be verified; `write` is called after each good read.
+     */
+    readonly cached?: {
+        readonly userId: () => string | null | undefined;
+        readonly read: (userId: string) => CachedActiveOrganization | null | Promise<CachedActiveOrganization | null>;
+        readonly write?: ((userId: string, answer: CachedActiveOrganization) => void | Promise<void>) | undefined;
+    } | undefined;
+    /** Called once when the organization the person was in is no longer a membership and the ladder chose another. */
+    readonly onLapse?: ((lapse: OrganizationLapse) => void) | undefined;
+    /** `refresh()` without `force` does nothing within this many ms of the last read. Default 0 (always reads). */
+    readonly refreshGapMs?: number | undefined;
+    /**
+     * Write the ladder's own answer back as the held organization. Default true. False: only an
+     * explicit `switchTo` writes the held choice (the extension's rule: a computed answer is never a choice).
+     */
+    readonly holdResolved?: boolean | undefined;
 }
 /** A held store over a `Storage` (browser `sessionStorage` = per tab), identity-keyed. */
-declare function storageHeldOrganization(storage: Pick<Storage, "getItem" | "setItem" | "removeItem">, key?: string): HeldOrganizationStore & {
+declare function storageHeldOrganization(storage: Pick<Storage, "getItem" | "setItem" | "removeItem">, key?: string): Omit<HeldOrganizationStore, "read"> & {
     read(userId: string): string | null;
 };
 /** Held in memory: the running app's own choice (desktop, scripts, tests). */
 declare function memoryHeldOrganization(): HeldOrganizationStore;
 declare function createActiveOrganization(options: CreateActiveOrganizationOptions): ActiveOrganization;
 
-export { decideLinkOrganization as $, type AuthClient as A, NotAMemberError as B, type CreateActiveOrganizationOptions as C, type NotAMemberRefusalNotice as D, ORGANIZATION_RESOLUTION_TIMEOUT_MS as E, type OrganizationBootstrapGate as F, type OrganizationMembership as G, type HeldOrganizationStore as H, type OrganizationRefusal as I, type OrganizationRung as J, type OrganizationsDb as K, LINK_ORGANIZATION_QUERY_KEY as L, type ResolveWithLinkInput as M, NOT_A_MEMBER_RECHECK_GAP_MS as N, ORGANIZATION_ENTITY_TYPE as O, type ParentOrganization as P, type ResolvedOrganization as Q, type ReadMembershipsOptions as R, type SessionSourceLike as S, type ResolvedWithLink as T, type UserCredentialsPort as U, adminSeatReplacesUserContext as V, classifyLinkOrganizationValue as W, classifyOrganizationRefusal as X, createActiveOrganization as Y, createNotAMemberRefusalNotice as Z, createOrganizationBootstrapGate as _, SignInError as a, isNotAMemberRefusal as a0, linkOrganizationMalformedMessage as a1, linkOrganizationNotAMemberMessage as a2, linkOrganizationOfferMessage as a3, linkOrganizationSwitchAnnouncement as a4, memoryHeldOrganization as a5, oldestMembership as a6, orderOrganizations as a7, organizationMatches as a8, readAccountOrganizationChoices as a9, readLinkOrganizationParam as aa, readMemberships as ab, readOrganizationFavourites as ac, resolveActiveOrganization as ad, resolveActiveOrganizationLazily as ae, resolveAdminSeat as af, resolveChildOrganizationId as ag, resolveOrganizationWithLink as ah, setOrganizationFavourite as ai, storageHeldOrganization as aj, toAccountOrganizationChoices as ak, writeLastActiveOrganization as al, writeStartupOrganization as am, getSession as b, signInWithOAuth as c, signInWithPassword as d, signOut as e, userCredentials as f, getPerson as g, type AccountOrganizationChoices as h, invalidatePerson as i, type ActiveOrganization as j, type ActiveOrganizationSnapshot as k, type ActiveOrganizationStatus as l, type AdminSeat as m, type AdminSeatInput as n, onSessionChange as o, type ArchiveFilter as p, type LadderInput as q, refreshSession as r, sessionCredentials as s, type LinkOrganizationDecision as t, updatePerson as u, type LinkOrganizationDecisionInput as v, type LinkOrganizationMembership as w, type LinkOrganizationMessages as x, type LinkOrganizationParam as y, NoActiveOrganizationError as z };
+export { createNotAMemberRefusalNotice as $, type AuthClient as A, NoActiveOrganizationError as B, type CachedActiveOrganization as C, NotAMemberError as D, type NotAMemberRefusalNotice as E, ORGANIZATION_RESOLUTION_TIMEOUT_MS as F, type OrganizationBootstrapGate as G, type HeldOrganizationStore as H, type OrganizationLapse as I, type OrganizationMembership as J, type OrganizationRefusal as K, LINK_ORGANIZATION_QUERY_KEY as L, type OrganizationRung as M, NOT_A_MEMBER_RECHECK_GAP_MS as N, ORGANIZATION_ENTITY_TYPE as O, type OrganizationsDb as P, type ParentOrganization as Q, type ReadMembershipsOptions as R, type SessionSourceLike as S, type ResolveWithLinkInput as T, type UserCredentialsPort as U, type ResolvedOrganization as V, type ResolvedWithLink as W, adminSeatReplacesUserContext as X, classifyLinkOrganizationValue as Y, classifyOrganizationRefusal as Z, createActiveOrganization as _, SignInError as a, createOrganizationBootstrapGate as a0, decideLinkOrganization as a1, isNotAMemberRefusal as a2, linkOrganizationMalformedMessage as a3, linkOrganizationNotAMemberMessage as a4, linkOrganizationOfferMessage as a5, linkOrganizationSwitchAnnouncement as a6, memoryHeldOrganization as a7, oldestMembership as a8, orderOrganizations as a9, organizationMatches as aa, readAccountOrganizationChoices as ab, readLinkOrganizationParam as ac, readMemberships as ad, readOrganizationFavourites as ae, resolveActiveOrganization as af, resolveActiveOrganizationLazily as ag, resolveAdminSeat as ah, resolveChildOrganizationId as ai, resolveOrganizationWithLink as aj, setOrganizationFavourite as ak, storageHeldOrganization as al, toAccountOrganizationChoices as am, writeLastActiveOrganization as an, writeStartupOrganization as ao, getSession as b, signInWithOAuth as c, signInWithPassword as d, signOut as e, userCredentials as f, getPerson as g, type AccountOrganizationChoices as h, invalidatePerson as i, type ActiveOrganization as j, type ActiveOrganizationSnapshot as k, type ActiveOrganizationStatus as l, type AdminSeat as m, type AdminSeatInput as n, onSessionChange as o, type ArchiveFilter as p, type CreateActiveOrganizationOptions as q, refreshSession as r, sessionCredentials as s, type LadderInput as t, updatePerson as u, type LinkOrganizationDecision as v, type LinkOrganizationDecisionInput as w, type LinkOrganizationMembership as x, type LinkOrganizationMessages as y, type LinkOrganizationParam as z };

package/dist/guest.d.cts

@@ -137,7 +137,7 @@ declare const DEFAULT_GUEST_CARRIER_COOKIE = "matrx_guest_visitor";
 declare function createGuestHandover(options: GuestHandoverOptions): GuestHandover;
 /**
  * Cookie options for the guest's browser client: its OWN cookie name, never the app singleton's. Pass as
- * `createBrowserClient(url, key, { isSingleton: false, cookieOptions: guestClientCookieOptions(name) })`.
+ * the browser client constructor with `isSingleton: false` and `cookieOptions: guestClientCookieOptions(name)`.
  */
 declare function guestClientCookieOptions(cookieName: string, secure?: boolean): {
     name: string;

package/dist/guest.d.ts

@@ -137,7 +137,7 @@ declare const DEFAULT_GUEST_CARRIER_COOKIE = "matrx_guest_visitor";
 declare function createGuestHandover(options: GuestHandoverOptions): GuestHandover;
 /**
  * Cookie options for the guest's browser client: its OWN cookie name, never the app singleton's. Pass as
- * `createBrowserClient(url, key, { isSingleton: false, cookieOptions: guestClientCookieOptions(name) })`.
+ * the browser client constructor with `isSingleton: false` and `cookieOptions: guestClientCookieOptions(name)`.
  */
 declare function guestClientCookieOptions(cookieName: string, secure?: boolean): {
     name: string;

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { H as HeldOrganizationStore, A as AuthClient } from './active-organization-Dy4UtiyR.cjs';
-export { S as SessionSourceLike, a as SignInError, U as UserCredentialsPort, g as getPerson, b as getSession, i as invalidatePerson, o as onSessionChange, r as refreshSession, s as sessionCredentials, c as signInWithOAuth, d as signInWithPassword, e as signOut, u as updatePerson, f as userCredentials } from './active-organization-Dy4UtiyR.cjs';
+import { H as HeldOrganizationStore, A as AuthClient } from './active-organization-Cxm6GDIy.cjs';
+export { S as SessionSourceLike, a as SignInError, U as UserCredentialsPort, g as getPerson, b as getSession, i as invalidatePerson, o as onSessionChange, r as refreshSession, s as sessionCredentials, c as signInWithOAuth, d as signInWithPassword, e as signOut, u as updatePerson, f as userCredentials } from './active-organization-Cxm6GDIy.cjs';
 import { S as SessionStorage, M as MatrxOAuthClient } from './matrx-oauth-_Ji8X5Wm.cjs';
 export { C as ChromeStorageAreaLike, a as StorageUnavailableError, b as browserStorage, e as extensionStorage, k as keyValueStorage, m as memoryStorage } from './matrx-oauth-_Ji8X5Wm.cjs';
 import { SupabaseClient, User } from '@supabase/supabase-js';

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { H as HeldOrganizationStore, A as AuthClient } from './active-organization-Dy4UtiyR.js';
-export { S as SessionSourceLike, a as SignInError, U as UserCredentialsPort, g as getPerson, b as getSession, i as invalidatePerson, o as onSessionChange, r as refreshSession, s as sessionCredentials, c as signInWithOAuth, d as signInWithPassword, e as signOut, u as updatePerson, f as userCredentials } from './active-organization-Dy4UtiyR.js';
+import { H as HeldOrganizationStore, A as AuthClient } from './active-organization-Cxm6GDIy.js';
+export { S as SessionSourceLike, a as SignInError, U as UserCredentialsPort, g as getPerson, b as getSession, i as invalidatePerson, o as onSessionChange, r as refreshSession, s as sessionCredentials, c as signInWithOAuth, d as signInWithPassword, e as signOut, u as updatePerson, f as userCredentials } from './active-organization-Cxm6GDIy.js';
 import { S as SessionStorage, M as MatrxOAuthClient } from './matrx-oauth-_Ji8X5Wm.js';
 export { C as ChromeStorageAreaLike, a as StorageUnavailableError, b as browserStorage, e as extensionStorage, k as keyValueStorage, m as memoryStorage } from './matrx-oauth-_Ji8X5Wm.js';
 import { SupabaseClient, User } from '@supabase/supabase-js';

package/dist/organizations.cjs

@@ -523,7 +523,9 @@ var IDLE = Object.freeze({
   organization: null,
   memberships: Object.freeze([]),
   rung: null,
-  error: null
+  error: null,
+  favourites: Object.freeze([]),
+  startupOrganizationId: null
 });
 function createActiveOrganization(options) {
   const { client } = options;
@@ -534,8 +536,11 @@ function createActiveOrganization(options) {
   let generation = 0;
   let waiters = [];
   let disposed = false;
+  let lastSettled = IDLE;
+  let lastReadAt = Number.NEGATIVE_INFINITY;
   const publish = (next) => {
     current = Object.freeze(next);
+    if (current.status !== "resolving") lastSettled = current;
     if (current.status !== "resolving" && current.status !== "idle") {
       options.bootstrapGate?.markResolved();
       const ready = waiters;
@@ -545,6 +550,7 @@ function createActiveOrganization(options) {
     for (const l of [...listeners]) l();
   };
   const run = async (gen) => {
+    const prior = current.status === "resolving" ? lastSettled : current;
     publish({ ...current, status: "resolving", error: null });
     try {
       const person = await getPerson(client);
@@ -553,8 +559,24 @@ function createActiveOrganization(options) {
         publish({ ...IDLE, status: "none", error: "signed-out" });
         return current;
       }
-      const memberships = await readMemberships(client, person.id);
+      const rawMemberships = await readMemberships(client, person.id);
       if (gen !== generation) return current;
+      let favourites = current.favourites;
+      let startupOrganizationId = current.startupOrganizationId;
+      let account = null;
+      if (options.accountChoices) {
+        const [fav, acct] = await Promise.all([
+          readOrganizationFavourites(client).catch(() => favourites),
+          readAccountOrganizationChoices(client, person.id)
+        ]);
+        favourites = fav;
+        account = acct;
+        startupOrganizationId = acct.startupOrganizationId;
+        if (gen !== generation) return current;
+      }
+      const memberships = options.accountChoices ? orderOrganizations(rawMemberships, favourites) : rawMemberships;
+      const readAccount = () => account ? Promise.resolve(account) : readAccountOrganizationChoices(client, person.id);
+      const before = prior;
       const linkOptions = options.link;
       let resolved;
       let linkDecision = null;
@@ -562,7 +584,7 @@ function createActiveOrganization(options) {
         const r = await resolveOrganizationWithLink({
           memberships,
           held: await held.read(person.id),
-          readAccount: () => readAccountOrganizationChoices(client, person.id),
+          readAccount,
           link: linkOptions.source() ?? null,
           switchWhenALinkAsks: linkOptions.switchWhenALinkAsks?.(),
           signedInAs: linkOptions.signedInAs?.(),
@@ -577,7 +599,7 @@ function createActiveOrganization(options) {
         resolved = await resolveActiveOrganizationLazily({
           memberships,
           held: heldId,
-          readAccount: () => readAccountOrganizationChoices(client, person.id)
+          readAccount
         });
       }
       if (gen !== generation) return current;
@@ -585,7 +607,9 @@ function createActiveOrganization(options) {
         publish({ ...IDLE, status: "none", userId: person.id, error: "no-memberships" });
         return current;
       }
-      await held.write(person.id, resolved.organization.id);
+      if (options.holdResolved ?? true) await held.write(person.id, resolved.organization.id);
+      const wasOrg = before.status === "ready" || before.status === "unchecked" ? before.organization : null;
+      const lapsed = wasOrg && wasOrg.id !== resolved.organization.id && !memberships.some((m) => m.id === wasOrg.id) ? wasOrg : null;
       if (linkDecision && linkDecision.kind !== "no-link") options.link?.onDecision?.(linkDecision);
       publish({
         status: "ready",
@@ -594,12 +618,51 @@ function createActiveOrganization(options) {
         organization: resolved.organization,
         memberships,
         rung: resolved.rung,
-        error: null
+        error: null,
+        favourites,
+        startupOrganizationId
       });
+      if (lapsed) options.onLapse?.({ was: lapsed, now: resolved.organization });
+      lastReadAt = Date.now();
+      if (options.cached?.write) {
+        try {
+          await options.cached.write(person.id, { memberships, organizationId: resolved.organization.id, favourites, startupOrganizationId });
+        } catch {
+        }
+      }
       return current;
     } catch (e) {
       if (gen !== generation) return current;
-      publish({ ...current, status: "error", error: e?.message ?? String(e) });
+      const message = e?.message ?? String(e);
+      if (options.cached && (prior.status === "ready" || prior.status === "unchecked") && prior.organization) {
+        publish({ ...prior, status: "unchecked", error: message });
+        return current;
+      }
+      const cachedUser = options.cached?.userId();
+      if (options.cached && cachedUser) {
+        try {
+          const answer = await options.cached.read(cachedUser);
+          if (gen !== generation) return current;
+          const wanted = await held.read(cachedUser) ?? answer?.organizationId ?? null;
+          const organization = answer?.memberships.find((m) => m.id === wanted) ?? null;
+          if (answer && organization) {
+            publish({
+              status: "unchecked",
+              userId: cachedUser,
+              organizationId: organization.id,
+              organization,
+              memberships: orderOrganizations(answer.memberships, answer.favourites),
+              rung: "held",
+              error: message,
+              favourites: answer.favourites,
+              startupOrganizationId: answer.startupOrganizationId
+            });
+            return current;
+          }
+        } catch {
+        }
+      }
+      publish({ ...current, status: "error", error: message });
       return current;
     }
   };
@@ -643,11 +706,34 @@ function createActiveOrganization(options) {
       };
     },
     load,
-    current: () => current.status === "ready" ? seatFor(current) ?? current.organizationId : null,
+    current: () => current.status === "ready" || current.status === "unchecked" ? seatFor(current) ?? current.organizationId : null,
+    refresh(refreshOptions) {
+      const gap = options.refreshGapMs ?? 0;
+      if (!refreshOptions?.force && gap > 0 && current.status !== "idle" && Date.now() - lastReadAt < gap) return Promise.resolve(current);
+      if (inflight) return inflight;
+      return load();
+    },
+    async setStartup(organizationId) {
+      const snap = await settled();
+      await writeStartupOrganization(client, organizationId);
+      publish({ ...snap, startupOrganizationId: organizationId });
+    },
+    async setFavourite(organizationId, favourite) {
+      const snap = await settled();
+      const before = snap.favourites;
+      const next = favourite ? [...before.filter((f) => f !== organizationId), organizationId] : before.filter((f) => f !== organizationId);
+      publish({ ...snap, favourites: next, memberships: orderOrganizations(snap.memberships, next) });
+      try {
+        await setOrganizationFavourite(client, organizationId, favourite);
+      } catch (e) {
+        publish({ ...current, favourites: before, memberships: orderOrganizations(current.memberships, before) });
+        throw e;
+      }
+    },
     async ensureOrgId(recordOrganizationId) {
       if (recordOrganizationId) return recordOrganizationId;
       const snap = await settled();
-      if (snap.status === "ready" && snap.organizationId) return seatFor(snap) ?? snap.organizationId;
+      if ((snap.status === "ready" || snap.status === "unchecked") && snap.organizationId) return seatFor(snap) ?? snap.organizationId;
       if (snap.status === "error") throw new NoActiveOrganizationError("unreadable", snap.error ?? void 0);
       throw new NoActiveOrganizationError(snap.error === "signed-out" ? "signed-out" : "no-memberships");
     },

package/dist/organizations.d.cts

@@ -1,4 +1,4 @@
-export { h as AccountOrganizationChoices, j as ActiveOrganization, k as ActiveOrganizationSnapshot, l as ActiveOrganizationStatus, m as AdminSeat, n as AdminSeatInput, p as ArchiveFilter, C as CreateActiveOrganizationOptions, H as HeldOrganizationStore, L as LINK_ORGANIZATION_QUERY_KEY, q as LadderInput, t as LinkOrganizationDecision, v as LinkOrganizationDecisionInput, w as LinkOrganizationMembership, x as LinkOrganizationMessages, y as LinkOrganizationParam, N as NOT_A_MEMBER_RECHECK_GAP_MS, z as NoActiveOrganizationError, B as NotAMemberError, D as NotAMemberRefusalNotice, O as ORGANIZATION_ENTITY_TYPE, E as ORGANIZATION_RESOLUTION_TIMEOUT_MS, F as OrganizationBootstrapGate, G as OrganizationMembership, I as OrganizationRefusal, J as OrganizationRung, K as OrganizationsDb, P as ParentOrganization, R as ReadMembershipsOptions, M as ResolveWithLinkInput, Q as ResolvedOrganization, T as ResolvedWithLink, V as adminSeatReplacesUserContext, W as classifyLinkOrganizationValue, X as classifyOrganizationRefusal, Y as createActiveOrganization, Z as createNotAMemberRefusalNotice, _ as createOrganizationBootstrapGate, $ as decideLinkOrganization, a0 as isNotAMemberRefusal, a1 as linkOrganizationMalformedMessage, a2 as linkOrganizationNotAMemberMessage, a3 as linkOrganizationOfferMessage, a4 as linkOrganizationSwitchAnnouncement, a5 as memoryHeldOrganization, a6 as oldestMembership, a7 as orderOrganizations, a8 as organizationMatches, a9 as readAccountOrganizationChoices, aa as readLinkOrganizationParam, ab as readMemberships, ac as readOrganizationFavourites, ad as resolveActiveOrganization, ae as resolveActiveOrganizationLazily, af as resolveAdminSeat, ag as resolveChildOrganizationId, ah as resolveOrganizationWithLink, ai as setOrganizationFavourite, aj as storageHeldOrganization, ak as toAccountOrganizationChoices, al as writeLastActiveOrganization, am as writeStartupOrganization } from './active-organization-Dy4UtiyR.cjs';
+export { h as AccountOrganizationChoices, j as ActiveOrganization, k as ActiveOrganizationSnapshot, l as ActiveOrganizationStatus, m as AdminSeat, n as AdminSeatInput, p as ArchiveFilter, C as CachedActiveOrganization, q as CreateActiveOrganizationOptions, H as HeldOrganizationStore, L as LINK_ORGANIZATION_QUERY_KEY, t as LadderInput, v as LinkOrganizationDecision, w as LinkOrganizationDecisionInput, x as LinkOrganizationMembership, y as LinkOrganizationMessages, z as LinkOrganizationParam, N as NOT_A_MEMBER_RECHECK_GAP_MS, B as NoActiveOrganizationError, D as NotAMemberError, E as NotAMemberRefusalNotice, O as ORGANIZATION_ENTITY_TYPE, F as ORGANIZATION_RESOLUTION_TIMEOUT_MS, G as OrganizationBootstrapGate, I as OrganizationLapse, J as OrganizationMembership, K as OrganizationRefusal, M as OrganizationRung, P as OrganizationsDb, Q as ParentOrganization, R as ReadMembershipsOptions, T as ResolveWithLinkInput, V as ResolvedOrganization, W as ResolvedWithLink, X as adminSeatReplacesUserContext, Y as classifyLinkOrganizationValue, Z as classifyOrganizationRefusal, _ as createActiveOrganization, $ as createNotAMemberRefusalNotice, a0 as createOrganizationBootstrapGate, a1 as decideLinkOrganization, a2 as isNotAMemberRefusal, a3 as linkOrganizationMalformedMessage, a4 as linkOrganizationNotAMemberMessage, a5 as linkOrganizationOfferMessage, a6 as linkOrganizationSwitchAnnouncement, a7 as memoryHeldOrganization, a8 as oldestMembership, a9 as orderOrganizations, aa as organizationMatches, ab as readAccountOrganizationChoices, ac as readLinkOrganizationParam, ad as readMemberships, ae as readOrganizationFavourites, af as resolveActiveOrganization, ag as resolveActiveOrganizationLazily, ah as resolveAdminSeat, ai as resolveChildOrganizationId, aj as resolveOrganizationWithLink, ak as setOrganizationFavourite, al as storageHeldOrganization, am as toAccountOrganizationChoices, an as writeLastActiveOrganization, ao as writeStartupOrganization } from './active-organization-Cxm6GDIy.cjs';
 import '@supabase/supabase-js';
 
 /**

package/dist/organizations.d.ts

@@ -1,4 +1,4 @@
-export { h as AccountOrganizationChoices, j as ActiveOrganization, k as ActiveOrganizationSnapshot, l as ActiveOrganizationStatus, m as AdminSeat, n as AdminSeatInput, p as ArchiveFilter, C as CreateActiveOrganizationOptions, H as HeldOrganizationStore, L as LINK_ORGANIZATION_QUERY_KEY, q as LadderInput, t as LinkOrganizationDecision, v as LinkOrganizationDecisionInput, w as LinkOrganizationMembership, x as LinkOrganizationMessages, y as LinkOrganizationParam, N as NOT_A_MEMBER_RECHECK_GAP_MS, z as NoActiveOrganizationError, B as NotAMemberError, D as NotAMemberRefusalNotice, O as ORGANIZATION_ENTITY_TYPE, E as ORGANIZATION_RESOLUTION_TIMEOUT_MS, F as OrganizationBootstrapGate, G as OrganizationMembership, I as OrganizationRefusal, J as OrganizationRung, K as OrganizationsDb, P as ParentOrganization, R as ReadMembershipsOptions, M as ResolveWithLinkInput, Q as ResolvedOrganization, T as ResolvedWithLink, V as adminSeatReplacesUserContext, W as classifyLinkOrganizationValue, X as classifyOrganizationRefusal, Y as createActiveOrganization, Z as createNotAMemberRefusalNotice, _ as createOrganizationBootstrapGate, $ as decideLinkOrganization, a0 as isNotAMemberRefusal, a1 as linkOrganizationMalformedMessage, a2 as linkOrganizationNotAMemberMessage, a3 as linkOrganizationOfferMessage, a4 as linkOrganizationSwitchAnnouncement, a5 as memoryHeldOrganization, a6 as oldestMembership, a7 as orderOrganizations, a8 as organizationMatches, a9 as readAccountOrganizationChoices, aa as readLinkOrganizationParam, ab as readMemberships, ac as readOrganizationFavourites, ad as resolveActiveOrganization, ae as resolveActiveOrganizationLazily, af as resolveAdminSeat, ag as resolveChildOrganizationId, ah as resolveOrganizationWithLink, ai as setOrganizationFavourite, aj as storageHeldOrganization, ak as toAccountOrganizationChoices, al as writeLastActiveOrganization, am as writeStartupOrganization } from './active-organization-Dy4UtiyR.js';
+export { h as AccountOrganizationChoices, j as ActiveOrganization, k as ActiveOrganizationSnapshot, l as ActiveOrganizationStatus, m as AdminSeat, n as AdminSeatInput, p as ArchiveFilter, C as CachedActiveOrganization, q as CreateActiveOrganizationOptions, H as HeldOrganizationStore, L as LINK_ORGANIZATION_QUERY_KEY, t as LadderInput, v as LinkOrganizationDecision, w as LinkOrganizationDecisionInput, x as LinkOrganizationMembership, y as LinkOrganizationMessages, z as LinkOrganizationParam, N as NOT_A_MEMBER_RECHECK_GAP_MS, B as NoActiveOrganizationError, D as NotAMemberError, E as NotAMemberRefusalNotice, O as ORGANIZATION_ENTITY_TYPE, F as ORGANIZATION_RESOLUTION_TIMEOUT_MS, G as OrganizationBootstrapGate, I as OrganizationLapse, J as OrganizationMembership, K as OrganizationRefusal, M as OrganizationRung, P as OrganizationsDb, Q as ParentOrganization, R as ReadMembershipsOptions, T as ResolveWithLinkInput, V as ResolvedOrganization, W as ResolvedWithLink, X as adminSeatReplacesUserContext, Y as classifyLinkOrganizationValue, Z as classifyOrganizationRefusal, _ as createActiveOrganization, $ as createNotAMemberRefusalNotice, a0 as createOrganizationBootstrapGate, a1 as decideLinkOrganization, a2 as isNotAMemberRefusal, a3 as linkOrganizationMalformedMessage, a4 as linkOrganizationNotAMemberMessage, a5 as linkOrganizationOfferMessage, a6 as linkOrganizationSwitchAnnouncement, a7 as memoryHeldOrganization, a8 as oldestMembership, a9 as orderOrganizations, aa as organizationMatches, ab as readAccountOrganizationChoices, ac as readLinkOrganizationParam, ad as readMemberships, ae as readOrganizationFavourites, af as resolveActiveOrganization, ag as resolveActiveOrganizationLazily, ah as resolveAdminSeat, ai as resolveChildOrganizationId, aj as resolveOrganizationWithLink, ak as setOrganizationFavourite, al as storageHeldOrganization, am as toAccountOrganizationChoices, an as writeLastActiveOrganization, ao as writeStartupOrganization } from './active-organization-Cxm6GDIy.js';
 import '@supabase/supabase-js';
 
 /**

package/dist/organizations.js

@@ -449,7 +449,9 @@ var IDLE = Object.freeze({
   organization: null,
   memberships: Object.freeze([]),
   rung: null,
-  error: null
+  error: null,
+  favourites: Object.freeze([]),
+  startupOrganizationId: null
 });
 function createActiveOrganization(options) {
   const { client } = options;
@@ -460,8 +462,11 @@ function createActiveOrganization(options) {
   let generation = 0;
   let waiters = [];
   let disposed = false;
+  let lastSettled = IDLE;
+  let lastReadAt = Number.NEGATIVE_INFINITY;
   const publish = (next) => {
     current = Object.freeze(next);
+    if (current.status !== "resolving") lastSettled = current;
     if (current.status !== "resolving" && current.status !== "idle") {
       options.bootstrapGate?.markResolved();
       const ready = waiters;
@@ -471,6 +476,7 @@ function createActiveOrganization(options) {
     for (const l of [...listeners]) l();
   };
   const run = async (gen) => {
+    const prior = current.status === "resolving" ? lastSettled : current;
     publish({ ...current, status: "resolving", error: null });
     try {
       const person = await getPerson(client);
@@ -479,8 +485,24 @@ function createActiveOrganization(options) {
         publish({ ...IDLE, status: "none", error: "signed-out" });
         return current;
       }
-      const memberships = await readMemberships(client, person.id);
+      const rawMemberships = await readMemberships(client, person.id);
       if (gen !== generation) return current;
+      let favourites = current.favourites;
+      let startupOrganizationId = current.startupOrganizationId;
+      let account = null;
+      if (options.accountChoices) {
+        const [fav, acct] = await Promise.all([
+          readOrganizationFavourites(client).catch(() => favourites),
+          readAccountOrganizationChoices(client, person.id)
+        ]);
+        favourites = fav;
+        account = acct;
+        startupOrganizationId = acct.startupOrganizationId;
+        if (gen !== generation) return current;
+      }
+      const memberships = options.accountChoices ? orderOrganizations(rawMemberships, favourites) : rawMemberships;
+      const readAccount = () => account ? Promise.resolve(account) : readAccountOrganizationChoices(client, person.id);
+      const before = prior;
       const linkOptions = options.link;
       let resolved;
       let linkDecision = null;
@@ -488,7 +510,7 @@ function createActiveOrganization(options) {
         const r = await resolveOrganizationWithLink({
           memberships,
           held: await held.read(person.id),
-          readAccount: () => readAccountOrganizationChoices(client, person.id),
+          readAccount,
           link: linkOptions.source() ?? null,
           switchWhenALinkAsks: linkOptions.switchWhenALinkAsks?.(),
           signedInAs: linkOptions.signedInAs?.(),
@@ -503,7 +525,7 @@ function createActiveOrganization(options) {
         resolved = await resolveActiveOrganizationLazily({
           memberships,
           held: heldId,
-          readAccount: () => readAccountOrganizationChoices(client, person.id)
+          readAccount
         });
       }
       if (gen !== generation) return current;
@@ -511,7 +533,9 @@ function createActiveOrganization(options) {
         publish({ ...IDLE, status: "none", userId: person.id, error: "no-memberships" });
         return current;
       }
-      await held.write(person.id, resolved.organization.id);
+      if (options.holdResolved ?? true) await held.write(person.id, resolved.organization.id);
+      const wasOrg = before.status === "ready" || before.status === "unchecked" ? before.organization : null;
+      const lapsed = wasOrg && wasOrg.id !== resolved.organization.id && !memberships.some((m) => m.id === wasOrg.id) ? wasOrg : null;
       if (linkDecision && linkDecision.kind !== "no-link") options.link?.onDecision?.(linkDecision);
       publish({
         status: "ready",
@@ -520,12 +544,51 @@ function createActiveOrganization(options) {
         organization: resolved.organization,
         memberships,
         rung: resolved.rung,
-        error: null
+        error: null,
+        favourites,
+        startupOrganizationId
       });
+      if (lapsed) options.onLapse?.({ was: lapsed, now: resolved.organization });
+      lastReadAt = Date.now();
+      if (options.cached?.write) {
+        try {
+          await options.cached.write(person.id, { memberships, organizationId: resolved.organization.id, favourites, startupOrganizationId });
+        } catch {
+        }
+      }
       return current;
     } catch (e) {
       if (gen !== generation) return current;
-      publish({ ...current, status: "error", error: e?.message ?? String(e) });
+      const message = e?.message ?? String(e);
+      if (options.cached && (prior.status === "ready" || prior.status === "unchecked") && prior.organization) {
+        publish({ ...prior, status: "unchecked", error: message });
+        return current;
+      }
+      const cachedUser = options.cached?.userId();
+      if (options.cached && cachedUser) {
+        try {
+          const answer = await options.cached.read(cachedUser);
+          if (gen !== generation) return current;
+          const wanted = await held.read(cachedUser) ?? answer?.organizationId ?? null;
+          const organization = answer?.memberships.find((m) => m.id === wanted) ?? null;
+          if (answer && organization) {
+            publish({
+              status: "unchecked",
+              userId: cachedUser,
+              organizationId: organization.id,
+              organization,
+              memberships: orderOrganizations(answer.memberships, answer.favourites),
+              rung: "held",
+              error: message,
+              favourites: answer.favourites,
+              startupOrganizationId: answer.startupOrganizationId
+            });
+            return current;
+          }
+        } catch {
+        }
+      }
+      publish({ ...current, status: "error", error: message });
       return current;
     }
   };
@@ -569,11 +632,34 @@ function createActiveOrganization(options) {
       };
     },
     load,
-    current: () => current.status === "ready" ? seatFor(current) ?? current.organizationId : null,
+    current: () => current.status === "ready" || current.status === "unchecked" ? seatFor(current) ?? current.organizationId : null,
+    refresh(refreshOptions) {
+      const gap = options.refreshGapMs ?? 0;
+      if (!refreshOptions?.force && gap > 0 && current.status !== "idle" && Date.now() - lastReadAt < gap) return Promise.resolve(current);
+      if (inflight) return inflight;
+      return load();
+    },
+    async setStartup(organizationId) {
+      const snap = await settled();
+      await writeStartupOrganization(client, organizationId);
+      publish({ ...snap, startupOrganizationId: organizationId });
+    },
+    async setFavourite(organizationId, favourite) {
+      const snap = await settled();
+      const before = snap.favourites;
+      const next = favourite ? [...before.filter((f) => f !== organizationId), organizationId] : before.filter((f) => f !== organizationId);
+      publish({ ...snap, favourites: next, memberships: orderOrganizations(snap.memberships, next) });
+      try {
+        await setOrganizationFavourite(client, organizationId, favourite);
+      } catch (e) {
+        publish({ ...current, favourites: before, memberships: orderOrganizations(current.memberships, before) });
+        throw e;
+      }
+    },
     async ensureOrgId(recordOrganizationId) {
       if (recordOrganizationId) return recordOrganizationId;
       const snap = await settled();
-      if (snap.status === "ready" && snap.organizationId) return seatFor(snap) ?? snap.organizationId;
+      if ((snap.status === "ready" || snap.status === "unchecked") && snap.organizationId) return seatFor(snap) ?? snap.organizationId;
       if (snap.status === "error") throw new NoActiveOrganizationError("unreadable", snap.error ?? void 0);
       throw new NoActiveOrganizationError(snap.error === "signed-out" ? "signed-out" : "no-memberships");
     },

package/dist/react.cjs

@@ -182,7 +182,9 @@ var SERVER_ACTIVE = Object.freeze({
   organization: null,
   memberships: Object.freeze([]),
   rung: null,
-  error: null
+  error: null,
+  favourites: Object.freeze([]),
+  startupOrganizationId: null
 });
 function useActiveOrganization(store) {
   return (0, import_react.useSyncExternalStore)(store.subscribe, store.snapshot, () => SERVER_ACTIVE);

package/dist/react.d.cts

@@ -90,7 +90,11 @@ type OrganizationRung = "held" | "last-active" | "startup" | "first";
  * the last person's organization, and a sign-out resets the store.
  */
 
-type ActiveOrganizationStatus = "idle" | "resolving" | "ready" | "none" | "error";
+/**
+ * `unchecked`: the memberships could not be read, and the answer shown is the host's cached last answer
+ * (`options.cached`), not verified against the database. Only ever produced when `cached` is given.
+ */
+type ActiveOrganizationStatus = "idle" | "resolving" | "ready" | "none" | "error" | "unchecked";
 interface ActiveOrganizationSnapshot {
     readonly status: ActiveOrganizationStatus;
     readonly userId: string | null;
@@ -100,6 +104,13 @@ interface ActiveOrganizationSnapshot {
     /** Which ladder rung answered (or "switched" after a person's click). */
     readonly rung: OrganizationRung | "switched" | "link" | null;
     readonly error: string | null;
+    /**
+     * The account's favourite organization ids. Read only when `options.accountChoices` is on; `[]`
+     * otherwise. When on, `memberships` is ordered favourites, then own, then the rest.
+     */
+    readonly favourites: readonly string[];
+    /** The account's start-up organization setting. Read only when `options.accountChoices` is on; null otherwise. */
+    readonly startupOrganizationId: string | null;
 }
 interface ActiveOrganization {
     snapshot(): ActiveOrganizationSnapshot;
@@ -109,6 +120,14 @@ interface ActiveOrganization {
     /** The active organization id now, or null while resolving / with none. Sync (api's getter). */
     current(): string | null;
     /** THE HELD REQUEST: the record's own organization, else the active one once resolved. */
+    /** Re-read, unless `options.refreshGapMs` has not elapsed since the last read (`force` always reads). */
+    refresh(options?: {
+        readonly force?: boolean;
+    }): Promise<ActiveOrganizationSnapshot>;
+    /** Save the account's start-up organization (null: the first). Needs `accountChoices`; throws on refusal. */
+    setStartup(organizationId: string | null): Promise<void>;
+    /** Add or remove a favourite and re-order. Optimistic; rolled back and rethrown if the save fails. */
+    setFavourite(organizationId: string, favourite: boolean): Promise<void>;
     ensureOrgId(recordOrganizationId?: string | null): Promise<string>;
     /** A person's click: switch, remember for this tab, save as last active for the next load. */
     switchTo(organizationId: string): Promise<void>;

package/dist/react.d.ts

@@ -90,7 +90,11 @@ type OrganizationRung = "held" | "last-active" | "startup" | "first";
  * the last person's organization, and a sign-out resets the store.
  */
 
-type ActiveOrganizationStatus = "idle" | "resolving" | "ready" | "none" | "error";
+/**
+ * `unchecked`: the memberships could not be read, and the answer shown is the host's cached last answer
+ * (`options.cached`), not verified against the database. Only ever produced when `cached` is given.
+ */
+type ActiveOrganizationStatus = "idle" | "resolving" | "ready" | "none" | "error" | "unchecked";
 interface ActiveOrganizationSnapshot {
     readonly status: ActiveOrganizationStatus;
     readonly userId: string | null;
@@ -100,6 +104,13 @@ interface ActiveOrganizationSnapshot {
     /** Which ladder rung answered (or "switched" after a person's click). */
     readonly rung: OrganizationRung | "switched" | "link" | null;
     readonly error: string | null;
+    /**
+     * The account's favourite organization ids. Read only when `options.accountChoices` is on; `[]`
+     * otherwise. When on, `memberships` is ordered favourites, then own, then the rest.
+     */
+    readonly favourites: readonly string[];
+    /** The account's start-up organization setting. Read only when `options.accountChoices` is on; null otherwise. */
+    readonly startupOrganizationId: string | null;
 }
 interface ActiveOrganization {
     snapshot(): ActiveOrganizationSnapshot;
@@ -109,6 +120,14 @@ interface ActiveOrganization {
     /** The active organization id now, or null while resolving / with none. Sync (api's getter). */
     current(): string | null;
     /** THE HELD REQUEST: the record's own organization, else the active one once resolved. */
+    /** Re-read, unless `options.refreshGapMs` has not elapsed since the last read (`force` always reads). */
+    refresh(options?: {
+        readonly force?: boolean;
+    }): Promise<ActiveOrganizationSnapshot>;
+    /** Save the account's start-up organization (null: the first). Needs `accountChoices`; throws on refusal. */
+    setStartup(organizationId: string | null): Promise<void>;
+    /** Add or remove a favourite and re-order. Optimistic; rolled back and rethrown if the save fails. */
+    setFavourite(organizationId: string, favourite: boolean): Promise<void>;
     ensureOrgId(recordOrganizationId?: string | null): Promise<string>;
     /** A person's click: switch, remember for this tab, save as last active for the next load. */
     switchTo(organizationId: string): Promise<void>;

package/dist/react.js

@@ -157,7 +157,9 @@ var SERVER_ACTIVE = Object.freeze({
   organization: null,
   memberships: Object.freeze([]),
   rung: null,
-  error: null
+  error: null,
+  favourites: Object.freeze([]),
+  startupOrganizationId: null
 });
 function useActiveOrganization(store) {
   return useSyncExternalStore(store.subscribe, store.snapshot, () => SERVER_ACTIVE);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-matrx/auth",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "AI Matrx sign-in, session and organizations for every app: sign in/out, session storage and refresh per platform (browser, Next.js, extension, desktop, Node), the current person, their organizations and favourites, the one active organization (held requests, never a list filter), and the credentials @ai-matrx/data and @ai-matrx/api read.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -211,5 +211,5 @@
     "test": "vitest run",
     "verify:tarball": "node ./scripts/verify-tarball.mjs"
   },
-  "gitHead": "09da8756d7c80a6f2e611b1dd2d713efee4b0858"
+  "gitHead": "f9020cf33c7ac2b8b854856131eb0b1268eb220d"
 }