@ai-matrx/auth 0.2.5 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog — @ai-matrx/auth
 
+## 0.3.1
+- `clearStaleHeld` fix: a held choice already stale when the read began is cleared even when no organization can be answered,
+  and a choice made while the read was in flight is never cleared. Test: `active-organization.test.ts`.
+
+## 0.3.0
+### auth consolidation tail (round 3)
+
+- `/organizations`: `organization-state` — pure decisions the apps' stores made themselves:
+  `shouldPromptForOrganization`, `organizationReadFailureReason`, `organizationWasReplaced`,
+  `reconcileRehydratedOrganization` (+ type `OrganizationStoreFields`).
+- `.`: `looksLikeJwt(token)`, `profileFromClaims(claims)` (+ type `ClaimsProfile`).
+- `createActiveOrganization`: `clearStaleHeld` option (default false) clears a held choice that is no longer a membership.
+- `/react`: `useActiveOrganizationView({ signedIn, resolve, list, choose, deps?, subscribe? })` — load / error vs none /
+  must-choose / choose / reload state machine over host-injected reads.
+- Tests: `organization-state`, `react-view`, `completeSignIn` replay (already-used code and burned code refuse cleanly), claims, clearStaleHeld.
+
 ## 0.2.5
 
 Automatic changed-only republish (docs/metadata drift since the last tag — see

package/dist/{active-organization-DHitxVeN.d.cts → active-organization-B6s9ONIe.d.cts}

@@ -638,6 +638,12 @@ interface CreateActiveOrganizationOptions {
      * explicit `switchTo` writes the held choice (the extension's rule: a computed answer is never a choice).
      */
     readonly holdResolved?: boolean | undefined;
+    /**
+     * After a read, a held choice that is no longer a membership is CLEARED from the held store (a
+     * selection must not outlive the membership). Default false. With `holdResolved` true the
+     * ladder's answer has already replaced it, so this matters for `holdResolved: false`.
+     */
+    readonly clearStaleHeld?: 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): Omit<HeldOrganizationStore, "read"> & {

package/dist/{active-organization-DHitxVeN.d.ts → active-organization-B6s9ONIe.d.ts}

@@ -638,6 +638,12 @@ interface CreateActiveOrganizationOptions {
      * explicit `switchTo` writes the held choice (the extension's rule: a computed answer is never a choice).
      */
     readonly holdResolved?: boolean | undefined;
+    /**
+     * After a read, a held choice that is no longer a membership is CLEARED from the held store (a
+     * selection must not outlive the membership). Default false. With `holdResolved` true the
+     * ladder's answer has already replaced it, so this matters for `holdResolved: false`.
+     */
+    readonly clearStaleHeld?: 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): Omit<HeldOrganizationStore, "read"> & {

package/dist/{claims-DXdbe3cW.d.cts → claims-KrRxsfaG.d.cts}

@@ -74,6 +74,19 @@ declare function isSignedOutError(error: AuthError | {
 }): boolean;
 /** The verified claims as a `{ id, ... }` user, or `null` when there are none. */
 declare function userFromClaims(claims: JwtPayload | undefined): ApiClaimsUser | null;
+/** Three segments whose header and payload decode as JSON. A malformed token is INVALID, not "no verdict". */
+declare function looksLikeJwt(token: string): boolean;
+/** The profile fields a verified token states (names match the `users` profile row). */
+interface ClaimsProfile {
+    id: string;
+    email: string | null;
+    full_name: string | null;
+    avatar_url: string | null;
+    /** Only when the token carries it. */
+    email_verified?: boolean;
+}
+/** Map verified claims to a profile, or `null` when the token carries no subject. */
+declare function profileFromClaims(claims: Record<string, unknown> | null | undefined): ClaimsProfile | null;
 /**
  * GUEST vs ACCOUNT. A signed-in session is a person with an ACCOUNT or a GUEST (anonymous session,
  * `is_anonymous: true`). Account UI (menu, billing, sign-out, org picker) keys on `hasAccount`.
@@ -135,4 +148,4 @@ declare function createClaimsCache(client: ClaimsCapableClient & {
     };
 }, options: ClaimsCacheOptions): () => Promise<ClaimsResult>;
 
-export { type ApiClaimsUser as A, type ClaimsCacheOptions as C, PROJECT_SIGNING_KEYS as P, type ClaimsCapableClient as a, type ClaimsResult as b, PROJECT_SIGNING_KEY_AUTHORITIES as c, accountFlagsFor as d, confirmUnverifiableSession as e, createClaimsCache as f, getClaimsUser as g, isSignedOutError as h, isAuthTransportFailure as i, isUnverifiableTokenError as j, isUnverifiableTokenRefusal as k, pinnedSigningKeysFor as p, userFromClaims as u };
+export { type ApiClaimsUser as A, type ClaimsCacheOptions as C, PROJECT_SIGNING_KEYS as P, type ClaimsCapableClient as a, type ClaimsProfile as b, type ClaimsResult as c, PROJECT_SIGNING_KEY_AUTHORITIES as d, accountFlagsFor as e, confirmUnverifiableSession as f, createClaimsCache as g, getClaimsUser as h, isAuthTransportFailure as i, isSignedOutError as j, isUnverifiableTokenError as k, isUnverifiableTokenRefusal as l, looksLikeJwt as m, profileFromClaims as n, pinnedSigningKeysFor as p, userFromClaims as u };

package/dist/{claims-DXdbe3cW.d.ts → claims-KrRxsfaG.d.ts}

@@ -74,6 +74,19 @@ declare function isSignedOutError(error: AuthError | {
 }): boolean;
 /** The verified claims as a `{ id, ... }` user, or `null` when there are none. */
 declare function userFromClaims(claims: JwtPayload | undefined): ApiClaimsUser | null;
+/** Three segments whose header and payload decode as JSON. A malformed token is INVALID, not "no verdict". */
+declare function looksLikeJwt(token: string): boolean;
+/** The profile fields a verified token states (names match the `users` profile row). */
+interface ClaimsProfile {
+    id: string;
+    email: string | null;
+    full_name: string | null;
+    avatar_url: string | null;
+    /** Only when the token carries it. */
+    email_verified?: boolean;
+}
+/** Map verified claims to a profile, or `null` when the token carries no subject. */
+declare function profileFromClaims(claims: Record<string, unknown> | null | undefined): ClaimsProfile | null;
 /**
  * GUEST vs ACCOUNT. A signed-in session is a person with an ACCOUNT or a GUEST (anonymous session,
  * `is_anonymous: true`). Account UI (menu, billing, sign-out, org picker) keys on `hasAccount`.
@@ -135,4 +148,4 @@ declare function createClaimsCache(client: ClaimsCapableClient & {
     };
 }, options: ClaimsCacheOptions): () => Promise<ClaimsResult>;
 
-export { type ApiClaimsUser as A, type ClaimsCacheOptions as C, PROJECT_SIGNING_KEYS as P, type ClaimsCapableClient as a, type ClaimsResult as b, PROJECT_SIGNING_KEY_AUTHORITIES as c, accountFlagsFor as d, confirmUnverifiableSession as e, createClaimsCache as f, getClaimsUser as g, isSignedOutError as h, isAuthTransportFailure as i, isUnverifiableTokenError as j, isUnverifiableTokenRefusal as k, pinnedSigningKeysFor as p, userFromClaims as u };
+export { type ApiClaimsUser as A, type ClaimsCacheOptions as C, PROJECT_SIGNING_KEYS as P, type ClaimsCapableClient as a, type ClaimsProfile as b, type ClaimsResult as c, PROJECT_SIGNING_KEY_AUTHORITIES as d, accountFlagsFor as e, confirmUnverifiableSession as f, createClaimsCache as g, getClaimsUser as h, isAuthTransportFailure as i, isSignedOutError as j, isUnverifiableTokenError as k, isUnverifiableTokenRefusal as l, looksLikeJwt as m, profileFromClaims as n, pinnedSigningKeysFor as p, userFromClaims as u };

package/dist/index.cjs

@@ -46,10 +46,12 @@ __export(src_exports, {
   isUnverifiableTokenError: () => isUnverifiableTokenError,
   isUnverifiableTokenRefusal: () => isUnverifiableTokenRefusal,
   keyValueStorage: () => keyValueStorage,
+  looksLikeJwt: () => looksLikeJwt,
   memoryStorage: () => memoryStorage,
   oauthAuthClient: () => oauthAuthClient,
   onSessionChange: () => onSessionChange,
   pinnedSigningKeysFor: () => pinnedSigningKeysFor,
+  profileFromClaims: () => profileFromClaims,
   refreshSession: () => refreshSession,
   sessionCredentials: () => sessionCredentials,
   signInWithOAuth: () => signInWithOAuth,
@@ -102,6 +104,36 @@ function userFromClaims(claims) {
     user_metadata: claims.user_metadata ?? {}
   };
 }
+function looksLikeJwt(token) {
+  const parts = token.split(".");
+  if (parts.length !== 3) return false;
+  try {
+    for (const part of parts.slice(0, 2)) {
+      const normalized = part.replace(/-/g, "+").replace(/_/g, "/");
+      const binary = atob(normalized.padEnd(Math.ceil(normalized.length / 4) * 4, "="));
+      const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));
+      JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+function profileFromClaims(claims) {
+  if (!claims) return null;
+  const text = (value) => typeof value === "string" && value.length > 0 ? value : null;
+  const id = text(claims["sub"]);
+  if (!id) return null;
+  const raw = claims["user_metadata"];
+  const meta = raw && typeof raw === "object" && !Array.isArray(raw) ? raw : {};
+  return {
+    id,
+    email: text(claims["email"]),
+    full_name: (typeof meta["full_name"] === "string" ? meta["full_name"] : null) ?? (typeof meta["name"] === "string" ? meta["name"] : null),
+    avatar_url: typeof meta["avatar_url"] === "string" ? meta["avatar_url"] : null,
+    ...typeof meta["email_verified"] === "boolean" && { email_verified: meta["email_verified"] }
+  };
+}
 function accountFlagsFor(claims) {
   if (!claims) return { isGuest: false, hasAccount: false };
   const isGuest = claims.is_anonymous === true;

package/dist/index.d.cts

@@ -1,11 +1,11 @@
-import { H as HeldOrganizationStore, A as AuthClient } from './active-organization-DHitxVeN.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-DHitxVeN.cjs';
+import { H as HeldOrganizationStore, A as AuthClient } from './active-organization-B6s9ONIe.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-B6s9ONIe.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';
 export { AuthChangeEvent, Session, User, UserAttributes } from '@supabase/supabase-js';
 export { CredentialsPort, MatrxCredential, MatrxCredentialKind } from './credentials.cjs';
-export { A as ApiClaimsUser, C as ClaimsCacheOptions, a as ClaimsCapableClient, b as ClaimsResult, P as PROJECT_SIGNING_KEYS, c as PROJECT_SIGNING_KEY_AUTHORITIES, d as accountFlagsFor, e as confirmUnverifiableSession, f as createClaimsCache, g as getClaimsUser, i as isAuthTransportFailure, h as isSignedOutError, j as isUnverifiableTokenError, k as isUnverifiableTokenRefusal, p as pinnedSigningKeysFor, u as userFromClaims } from './claims-DXdbe3cW.cjs';
+export { A as ApiClaimsUser, C as ClaimsCacheOptions, a as ClaimsCapableClient, b as ClaimsProfile, c as ClaimsResult, P as PROJECT_SIGNING_KEYS, d as PROJECT_SIGNING_KEY_AUTHORITIES, e as accountFlagsFor, f as confirmUnverifiableSession, g as createClaimsCache, h as getClaimsUser, i as isAuthTransportFailure, j as isSignedOutError, k as isUnverifiableTokenError, l as isUnverifiableTokenRefusal, m as looksLikeJwt, p as pinnedSigningKeysFor, n as profileFromClaims, u as userFromClaims } from './claims-KrRxsfaG.cjs';
 
 /** How long a request may wait for the first auth report before going anyway. */
 declare const SESSION_ATTACH_BUDGET_MS = 3000;

package/dist/index.d.ts

@@ -1,11 +1,11 @@
-import { H as HeldOrganizationStore, A as AuthClient } from './active-organization-DHitxVeN.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-DHitxVeN.js';
+import { H as HeldOrganizationStore, A as AuthClient } from './active-organization-B6s9ONIe.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-B6s9ONIe.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';
 export { AuthChangeEvent, Session, User, UserAttributes } from '@supabase/supabase-js';
 export { CredentialsPort, MatrxCredential, MatrxCredentialKind } from './credentials.js';
-export { A as ApiClaimsUser, C as ClaimsCacheOptions, a as ClaimsCapableClient, b as ClaimsResult, P as PROJECT_SIGNING_KEYS, c as PROJECT_SIGNING_KEY_AUTHORITIES, d as accountFlagsFor, e as confirmUnverifiableSession, f as createClaimsCache, g as getClaimsUser, i as isAuthTransportFailure, h as isSignedOutError, j as isUnverifiableTokenError, k as isUnverifiableTokenRefusal, p as pinnedSigningKeysFor, u as userFromClaims } from './claims-DXdbe3cW.js';
+export { A as ApiClaimsUser, C as ClaimsCacheOptions, a as ClaimsCapableClient, b as ClaimsProfile, c as ClaimsResult, P as PROJECT_SIGNING_KEYS, d as PROJECT_SIGNING_KEY_AUTHORITIES, e as accountFlagsFor, f as confirmUnverifiableSession, g as createClaimsCache, h as getClaimsUser, i as isAuthTransportFailure, j as isSignedOutError, k as isUnverifiableTokenError, l as isUnverifiableTokenRefusal, m as looksLikeJwt, p as pinnedSigningKeysFor, n as profileFromClaims, u as userFromClaims } from './claims-KrRxsfaG.js';
 
 /** How long a request may wait for the first auth report before going anyway. */
 declare const SESSION_ATTACH_BUDGET_MS = 3000;

package/dist/index.js

@@ -41,6 +41,36 @@ function userFromClaims(claims) {
     user_metadata: claims.user_metadata ?? {}
   };
 }
+function looksLikeJwt(token) {
+  const parts = token.split(".");
+  if (parts.length !== 3) return false;
+  try {
+    for (const part of parts.slice(0, 2)) {
+      const normalized = part.replace(/-/g, "+").replace(/_/g, "/");
+      const binary = atob(normalized.padEnd(Math.ceil(normalized.length / 4) * 4, "="));
+      const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));
+      JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+function profileFromClaims(claims) {
+  if (!claims) return null;
+  const text = (value) => typeof value === "string" && value.length > 0 ? value : null;
+  const id = text(claims["sub"]);
+  if (!id) return null;
+  const raw = claims["user_metadata"];
+  const meta = raw && typeof raw === "object" && !Array.isArray(raw) ? raw : {};
+  return {
+    id,
+    email: text(claims["email"]),
+    full_name: (typeof meta["full_name"] === "string" ? meta["full_name"] : null) ?? (typeof meta["name"] === "string" ? meta["name"] : null),
+    avatar_url: typeof meta["avatar_url"] === "string" ? meta["avatar_url"] : null,
+    ...typeof meta["email_verified"] === "boolean" && { email_verified: meta["email_verified"] }
+  };
+}
 function accountFlagsFor(claims) {
   if (!claims) return { isGuest: false, hasAccount: false };
   const isGuest = claims.is_anonymous === true;
@@ -726,10 +756,12 @@ export {
   isUnverifiableTokenError,
   isUnverifiableTokenRefusal,
   keyValueStorage,
+  looksLikeJwt,
   memoryStorage,
   oauthAuthClient,
   onSessionChange,
   pinnedSigningKeysFor,
+  profileFromClaims,
   refreshSession,
   sessionCredentials,
   signInWithOAuth,

package/dist/next.d.cts

@@ -2,7 +2,7 @@ import { createServerClient, createBrowserClient } from '@supabase/ssr';
 import { b as AuthCookieValue, A as AuthCookie, a as AuthCookieOptions } from './auth-cookie-DWx6Q3xo.cjs';
 export { C as CreateAuthCookieArgs, D as DEFAULT_AUTH_COOKIE_NAME, c as createAuthCookie } from './auth-cookie-DWx6Q3xo.cjs';
 import { SupabaseClient } from '@supabase/supabase-js';
-import { a as ClaimsCapableClient, A as ApiClaimsUser } from './claims-DXdbe3cW.cjs';
+import { a as ClaimsCapableClient, A as ApiClaimsUser } from './claims-KrRxsfaG.cjs';
 
 /**
  * @ai-matrx/data/next — the Next.js Supabase binding.

package/dist/next.d.ts

@@ -2,7 +2,7 @@ import { createServerClient, createBrowserClient } from '@supabase/ssr';
 import { b as AuthCookieValue, A as AuthCookie, a as AuthCookieOptions } from './auth-cookie-DWx6Q3xo.js';
 export { C as CreateAuthCookieArgs, D as DEFAULT_AUTH_COOKIE_NAME, c as createAuthCookie } from './auth-cookie-DWx6Q3xo.js';
 import { SupabaseClient } from '@supabase/supabase-js';
-import { a as ClaimsCapableClient, A as ApiClaimsUser } from './claims-DXdbe3cW.js';
+import { a as ClaimsCapableClient, A as ApiClaimsUser } from './claims-KrRxsfaG.js';
 
 /**
  * @ai-matrx/data/next — the Next.js Supabase binding.

package/dist/organizations.cjs

@@ -52,21 +52,25 @@ __export(organizations_exports, {
   oldestMembership: () => oldestMembership,
   orderOrganizations: () => orderOrganizations,
   organizationMatches: () => organizationMatches,
+  organizationReadFailureReason: () => organizationReadFailureReason,
   organizationRequired: () => organizationRequired,
   organizationRequiredEnvelope: () => organizationRequiredEnvelope,
   organizationRequiredResponse: () => organizationRequiredResponse,
+  organizationWasReplaced: () => organizationWasReplaced,
   readAccountOrganizationChoices: () => readAccountOrganizationChoices,
   readCallerMemberships: () => readCallerMemberships,
   readLinkOrganizationParam: () => readLinkOrganizationParam,
   readMembershipRows: () => readMembershipRows,
   readMemberships: () => readMemberships,
   readOrganizationFavourites: () => readOrganizationFavourites,
+  reconcileRehydratedOrganization: () => reconcileRehydratedOrganization,
   resolveActiveOrganization: () => resolveActiveOrganization,
   resolveActiveOrganizationLazily: () => resolveActiveOrganizationLazily,
   resolveAdminSeat: () => resolveAdminSeat,
   resolveChildOrganizationId: () => resolveChildOrganizationId,
   resolveOrganizationWithLink: () => resolveOrganizationWithLink,
   setOrganizationFavourite: () => setOrganizationFavourite,
+  shouldPromptForOrganization: () => shouldPromptForOrganization,
   storageHeldOrganization: () => storageHeldOrganization,
   toAccountOrganizationChoices: () => toAccountOrganizationChoices,
   writeLastActiveOrganization: () => writeLastActiveOrganization,
@@ -579,6 +583,7 @@ function createActiveOrganization(options) {
       const memberships = options.accountChoices ? orderOrganizations(rawMemberships, favourites) : rawMemberships;
       const readAccount = () => account ? Promise.resolve(account) : readAccountOrganizationChoices(client, person.id);
       const before = prior;
+      const heldAtStart = options.clearStaleHeld ? await held.read(person.id) : null;
       const linkOptions = options.link;
       let resolved;
       let linkDecision = null;
@@ -605,6 +610,9 @@ function createActiveOrganization(options) {
         });
       }
       if (gen !== generation) return current;
+      if (heldAtStart && !memberships.some((m) => m.id === heldAtStart) && await held.read(person.id) === heldAtStart) {
+        await held.clear();
+      }
       if (!resolved) {
         publish({ ...IDLE, status: "none", userId: person.id, error: "no-memberships" });
         return current;
@@ -874,3 +882,37 @@ async function readMembershipRows(db, containerType, pageSize = MEMBERSHIP_ROWS_
   }
   return { data: rows, error: null };
 }
+
+// src/organization-state.ts
+function shouldPromptForOrganization(input) {
+  return input.resolved === true && (input.organizationId ?? null) == null && (input.failure ?? null) == null;
+}
+function organizationReadFailureReason(error) {
+  return error instanceof Error && error.message ? `the organization read failed: ${error.message}` : "the organization read failed";
+}
+function organizationWasReplaced(input) {
+  return Boolean(input.held && input.chosen && input.chosen !== input.held && input.linkKind !== "honoured");
+}
+function reconcileRehydratedOrganization(current, loaded) {
+  const fromLadder = loaded.orgBootstrapResolved === true;
+  if (!fromLadder) {
+    if (current.organization_id == null && loaded.organization_id) {
+      return { organization_id: loaded.organization_id, organization_name: loaded.organization_name ?? null };
+    }
+    return {};
+  }
+  const heldHere = current.orgBootstrapResolved && current.organization_id != null;
+  const patch = { orgBootstrapResolved: true };
+  if (loaded.orgBootstrapFailure !== void 0) {
+    patch.orgBootstrapFailure = loaded.organization_id != null ? null : loaded.orgBootstrapFailure;
+  }
+  if (loaded.organization_id === void 0) return patch;
+  if (heldHere && loaded.organization_id === current.organization_id) {
+    if (loaded.organization_name != null) patch.organization_name = loaded.organization_name;
+    return patch;
+  }
+  if (heldHere) return patch;
+  patch.organization_id = loaded.organization_id;
+  patch.organization_name = loaded.organization_name ?? null;
+  return patch;
+}

package/dist/organizations.d.cts

@@ -1,5 +1,5 @@
-import { O as OrganizationsDb } from './active-organization-DHitxVeN.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, F as ORGANIZATION_ENTITY_TYPE, G as ORGANIZATION_RESOLUTION_TIMEOUT_MS, I as OrganizationBootstrapGate, J as OrganizationLapse, K as OrganizationMembership, M as OrganizationRefusal, P as OrganizationRung, 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-DHitxVeN.cjs';
+import { O as OrganizationsDb } from './active-organization-B6s9ONIe.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, F as ORGANIZATION_ENTITY_TYPE, G as ORGANIZATION_RESOLUTION_TIMEOUT_MS, I as OrganizationBootstrapGate, J as OrganizationLapse, K as OrganizationMembership, M as OrganizationRefusal, P as OrganizationRung, 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-B6s9ONIe.cjs';
 import '@supabase/supabase-js';
 
 /**
@@ -130,4 +130,48 @@ interface MembershipRowsAnswer<Row> {
 }
 declare function readMembershipRows<Row = Record<string, unknown>>(db: OrganizationsDb, containerType: string, pageSize?: number): Promise<MembershipRowsAnswer<Row>>;
 
-export { MEMBERSHIPS_URL, MEMBERSHIP_ROWS_PAGE, type MembershipReadClient, type MembershipRowsAnswer, ORGANIZATION_CONTEXT_REQUIRED_CODE, ORGANIZATION_REQUIRED_CODE, ORGANIZATION_REQUIRED_WIRE_CODE, type OrganizationHoldDetails, type OrganizationHoldSetOn, type OrganizationMembershipSummary, type OrganizationRequiredEnvelope, OrganizationRequiredServerError, type OrganizationRequiredWireMembership, OrganizationsDb, extractOrganizationHoldMemberships, isOrganizationRequiredEnvelope, isOrganizationRequiredError, isOrganizationRequiredServerError, organizationRequired, organizationRequiredEnvelope, organizationRequiredResponse, readCallerMemberships, readMembershipRows };
+/**
+ * The DECISIONS an app's organization store used to make for itself (moved from the website's
+ * `shouldPromptForOrganization`, `appContextSlice` rehydrate reducer and `activeOrgBootstrap`
+ * thunk). Pure: an app's Redux/zustand slice only calls these and assigns what they return.
+ */
+/** The organization fields an app keeps in its store. */
+interface OrganizationStoreFields {
+    readonly organization_id: string | null;
+    readonly organization_name: string | null;
+    readonly orgBootstrapResolved: boolean;
+    readonly orgBootstrapFailure: string | null;
+}
+/**
+ * True when the UI should nudge the person to choose an organization: the bootstrap has resolved,
+ * none is selected, AND the read of their memberships succeeded. A failed read is never the nudge
+ * ("we could not check" speaks instead) — a member of thirteen organizations was once told to pick
+ * one after a single failed fetch.
+ */
+declare function shouldPromptForOrganization(input: {
+    readonly resolved: boolean;
+    readonly organizationId: string | null | undefined;
+    readonly failure: string | null | undefined;
+}): boolean;
+/** The words for a failed membership read — one sentence for every host. */
+declare function organizationReadFailureReason(error: unknown): string;
+/**
+ * A held organization was taken away (removed, archived) and the ladder chose another, and the
+ * choice is not the link's own: switch, and say so.
+ */
+declare function organizationWasReplaced(input: {
+    readonly held: string | null | undefined;
+    readonly chosen: string | null | undefined;
+    readonly linkKind?: string | undefined;
+}): boolean;
+/**
+ * What a REHYDRATE does to the organization fields. Two kinds:
+ *   - the browser CACHE (no `orgBootstrapResolved`) only PAINTS an empty store and never marks the
+ *     question answered, so no request leaves on it;
+ *   - the LOAD LADDER's answer (`orgBootstrapResolved: true`) is the account's and wins over the
+ *     painted cache — unless this store already holds an organization the person chose here.
+ * Returns the fields to assign (empty = change nothing).
+ */
+declare function reconcileRehydratedOrganization(current: Pick<OrganizationStoreFields, "organization_id" | "orgBootstrapResolved">, loaded: Partial<OrganizationStoreFields>): Partial<OrganizationStoreFields>;
+
+export { MEMBERSHIPS_URL, MEMBERSHIP_ROWS_PAGE, type MembershipReadClient, type MembershipRowsAnswer, ORGANIZATION_CONTEXT_REQUIRED_CODE, ORGANIZATION_REQUIRED_CODE, ORGANIZATION_REQUIRED_WIRE_CODE, type OrganizationHoldDetails, type OrganizationHoldSetOn, type OrganizationMembershipSummary, type OrganizationRequiredEnvelope, OrganizationRequiredServerError, type OrganizationRequiredWireMembership, type OrganizationStoreFields, OrganizationsDb, extractOrganizationHoldMemberships, isOrganizationRequiredEnvelope, isOrganizationRequiredError, isOrganizationRequiredServerError, organizationReadFailureReason, organizationRequired, organizationRequiredEnvelope, organizationRequiredResponse, organizationWasReplaced, readCallerMemberships, readMembershipRows, reconcileRehydratedOrganization, shouldPromptForOrganization };

package/dist/organizations.d.ts

@@ -1,5 +1,5 @@
-import { O as OrganizationsDb } from './active-organization-DHitxVeN.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, F as ORGANIZATION_ENTITY_TYPE, G as ORGANIZATION_RESOLUTION_TIMEOUT_MS, I as OrganizationBootstrapGate, J as OrganizationLapse, K as OrganizationMembership, M as OrganizationRefusal, P as OrganizationRung, 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-DHitxVeN.js';
+import { O as OrganizationsDb } from './active-organization-B6s9ONIe.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, F as ORGANIZATION_ENTITY_TYPE, G as ORGANIZATION_RESOLUTION_TIMEOUT_MS, I as OrganizationBootstrapGate, J as OrganizationLapse, K as OrganizationMembership, M as OrganizationRefusal, P as OrganizationRung, 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-B6s9ONIe.js';
 import '@supabase/supabase-js';
 
 /**
@@ -130,4 +130,48 @@ interface MembershipRowsAnswer<Row> {
 }
 declare function readMembershipRows<Row = Record<string, unknown>>(db: OrganizationsDb, containerType: string, pageSize?: number): Promise<MembershipRowsAnswer<Row>>;
 
-export { MEMBERSHIPS_URL, MEMBERSHIP_ROWS_PAGE, type MembershipReadClient, type MembershipRowsAnswer, ORGANIZATION_CONTEXT_REQUIRED_CODE, ORGANIZATION_REQUIRED_CODE, ORGANIZATION_REQUIRED_WIRE_CODE, type OrganizationHoldDetails, type OrganizationHoldSetOn, type OrganizationMembershipSummary, type OrganizationRequiredEnvelope, OrganizationRequiredServerError, type OrganizationRequiredWireMembership, OrganizationsDb, extractOrganizationHoldMemberships, isOrganizationRequiredEnvelope, isOrganizationRequiredError, isOrganizationRequiredServerError, organizationRequired, organizationRequiredEnvelope, organizationRequiredResponse, readCallerMemberships, readMembershipRows };
+/**
+ * The DECISIONS an app's organization store used to make for itself (moved from the website's
+ * `shouldPromptForOrganization`, `appContextSlice` rehydrate reducer and `activeOrgBootstrap`
+ * thunk). Pure: an app's Redux/zustand slice only calls these and assigns what they return.
+ */
+/** The organization fields an app keeps in its store. */
+interface OrganizationStoreFields {
+    readonly organization_id: string | null;
+    readonly organization_name: string | null;
+    readonly orgBootstrapResolved: boolean;
+    readonly orgBootstrapFailure: string | null;
+}
+/**
+ * True when the UI should nudge the person to choose an organization: the bootstrap has resolved,
+ * none is selected, AND the read of their memberships succeeded. A failed read is never the nudge
+ * ("we could not check" speaks instead) — a member of thirteen organizations was once told to pick
+ * one after a single failed fetch.
+ */
+declare function shouldPromptForOrganization(input: {
+    readonly resolved: boolean;
+    readonly organizationId: string | null | undefined;
+    readonly failure: string | null | undefined;
+}): boolean;
+/** The words for a failed membership read — one sentence for every host. */
+declare function organizationReadFailureReason(error: unknown): string;
+/**
+ * A held organization was taken away (removed, archived) and the ladder chose another, and the
+ * choice is not the link's own: switch, and say so.
+ */
+declare function organizationWasReplaced(input: {
+    readonly held: string | null | undefined;
+    readonly chosen: string | null | undefined;
+    readonly linkKind?: string | undefined;
+}): boolean;
+/**
+ * What a REHYDRATE does to the organization fields. Two kinds:
+ *   - the browser CACHE (no `orgBootstrapResolved`) only PAINTS an empty store and never marks the
+ *     question answered, so no request leaves on it;
+ *   - the LOAD LADDER's answer (`orgBootstrapResolved: true`) is the account's and wins over the
+ *     painted cache — unless this store already holds an organization the person chose here.
+ * Returns the fields to assign (empty = change nothing).
+ */
+declare function reconcileRehydratedOrganization(current: Pick<OrganizationStoreFields, "organization_id" | "orgBootstrapResolved">, loaded: Partial<OrganizationStoreFields>): Partial<OrganizationStoreFields>;
+
+export { MEMBERSHIPS_URL, MEMBERSHIP_ROWS_PAGE, type MembershipReadClient, type MembershipRowsAnswer, ORGANIZATION_CONTEXT_REQUIRED_CODE, ORGANIZATION_REQUIRED_CODE, ORGANIZATION_REQUIRED_WIRE_CODE, type OrganizationHoldDetails, type OrganizationHoldSetOn, type OrganizationMembershipSummary, type OrganizationRequiredEnvelope, OrganizationRequiredServerError, type OrganizationRequiredWireMembership, type OrganizationStoreFields, OrganizationsDb, extractOrganizationHoldMemberships, isOrganizationRequiredEnvelope, isOrganizationRequiredError, isOrganizationRequiredServerError, organizationReadFailureReason, organizationRequired, organizationRequiredEnvelope, organizationRequiredResponse, organizationWasReplaced, readCallerMemberships, readMembershipRows, reconcileRehydratedOrganization, shouldPromptForOrganization };

package/dist/organizations.js

@@ -503,6 +503,7 @@ function createActiveOrganization(options) {
       const memberships = options.accountChoices ? orderOrganizations(rawMemberships, favourites) : rawMemberships;
       const readAccount = () => account ? Promise.resolve(account) : readAccountOrganizationChoices(client, person.id);
       const before = prior;
+      const heldAtStart = options.clearStaleHeld ? await held.read(person.id) : null;
       const linkOptions = options.link;
       let resolved;
       let linkDecision = null;
@@ -529,6 +530,9 @@ function createActiveOrganization(options) {
         });
       }
       if (gen !== generation) return current;
+      if (heldAtStart && !memberships.some((m) => m.id === heldAtStart) && await held.read(person.id) === heldAtStart) {
+        await held.clear();
+      }
       if (!resolved) {
         publish({ ...IDLE, status: "none", userId: person.id, error: "no-memberships" });
         return current;
@@ -798,6 +802,40 @@ async function readMembershipRows(db, containerType, pageSize = MEMBERSHIP_ROWS_
   }
   return { data: rows, error: null };
 }
+
+// src/organization-state.ts
+function shouldPromptForOrganization(input) {
+  return input.resolved === true && (input.organizationId ?? null) == null && (input.failure ?? null) == null;
+}
+function organizationReadFailureReason(error) {
+  return error instanceof Error && error.message ? `the organization read failed: ${error.message}` : "the organization read failed";
+}
+function organizationWasReplaced(input) {
+  return Boolean(input.held && input.chosen && input.chosen !== input.held && input.linkKind !== "honoured");
+}
+function reconcileRehydratedOrganization(current, loaded) {
+  const fromLadder = loaded.orgBootstrapResolved === true;
+  if (!fromLadder) {
+    if (current.organization_id == null && loaded.organization_id) {
+      return { organization_id: loaded.organization_id, organization_name: loaded.organization_name ?? null };
+    }
+    return {};
+  }
+  const heldHere = current.orgBootstrapResolved && current.organization_id != null;
+  const patch = { orgBootstrapResolved: true };
+  if (loaded.orgBootstrapFailure !== void 0) {
+    patch.orgBootstrapFailure = loaded.organization_id != null ? null : loaded.orgBootstrapFailure;
+  }
+  if (loaded.organization_id === void 0) return patch;
+  if (heldHere && loaded.organization_id === current.organization_id) {
+    if (loaded.organization_name != null) patch.organization_name = loaded.organization_name;
+    return patch;
+  }
+  if (heldHere) return patch;
+  patch.organization_id = loaded.organization_id;
+  patch.organization_name = loaded.organization_name ?? null;
+  return patch;
+}
 export {
   LINK_ORGANIZATION_QUERY_KEY,
   MEMBERSHIPS_URL,
@@ -831,21 +869,25 @@ export {
   oldestMembership,
   orderOrganizations,
   organizationMatches,
+  organizationReadFailureReason,
   organizationRequired,
   organizationRequiredEnvelope,
   organizationRequiredResponse,
+  organizationWasReplaced,
   readAccountOrganizationChoices,
   readCallerMemberships,
   readLinkOrganizationParam,
   readMembershipRows,
   readMemberships,
   readOrganizationFavourites,
+  reconcileRehydratedOrganization,
   resolveActiveOrganization,
   resolveActiveOrganizationLazily,
   resolveAdminSeat,
   resolveChildOrganizationId,
   resolveOrganizationWithLink,
   setOrganizationFavourite,
+  shouldPromptForOrganization,
   storageHeldOrganization,
   toAccountOrganizationChoices,
   writeLastActiveOrganization,

package/dist/react.cjs

@@ -23,6 +23,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var react_exports = {};
 __export(react_exports, {
   useActiveOrganization: () => useActiveOrganization,
+  useActiveOrganizationView: () => useActiveOrganizationView,
   useSession: () => useSession,
   useSessionIdentity: () => useSessionIdentity
 });
@@ -206,3 +207,47 @@ function useSessionIdentity(options) {
   const source = identity ?? NO_IDENTITY;
   return (0, import_react.useSyncExternalStore)(source.subscribe, source.snapshot, () => SERVER_SESSION_IDENTITY);
 }
+function useActiveOrganizationView(options) {
+  const latest = (0, import_react.useRef)(options);
+  latest.current = options;
+  const [active, setActive] = (0, import_react.useState)(null);
+  const [organizations, setOrganizations] = (0, import_react.useState)([]);
+  const [loading, setLoading] = (0, import_react.useState)(true);
+  const [error, setError] = (0, import_react.useState)(null);
+  const [nonce, setNonce] = (0, import_react.useState)(0);
+  const reload = (0, import_react.useRef)(() => setNonce((n) => n + 1)).current;
+  (0, import_react.useEffect)(() => {
+    let cancelled = false;
+    if (!options.signedIn) {
+      setActive(null);
+      setOrganizations([]);
+      setLoading(false);
+      setError(null);
+      return;
+    }
+    setLoading(true);
+    void (async () => {
+      try {
+        const [resolved, all] = await Promise.all([latest.current.resolve(), latest.current.list()]);
+        if (cancelled) return;
+        setActive(resolved);
+        setOrganizations(all);
+        setError(null);
+      } catch (err) {
+        if (cancelled) return;
+        setError(err instanceof Error ? err.message : String(err));
+      } finally {
+        if (!cancelled) setLoading(false);
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [options.signedIn, nonce, ...options.deps ?? []]);
+  const subscribe = options.subscribe;
+  (0, import_react.useEffect)(() => subscribe ? subscribe(reload) : void 0, [subscribe, reload]);
+  const choose = (0, import_react.useRef)(async (organizationId) => {
+    setActive(await latest.current.choose(organizationId));
+  }).current;
+  return { active, organizations, loading, error, mustChoose: options.signedIn && !loading && !error && !active, choose, reload };
+}

package/dist/react.d.cts

@@ -180,5 +180,36 @@ declare function useActiveOrganization(store: ActiveOrganization): ActiveOrganiz
  * the first session read answers; StrictMode-safe (the store is made and disposed in an effect).
  */
 declare function useSessionIdentity<Id extends string = string>(options: SessionIdentityOptions<Id>): SessionIdentitySnapshot<Id>;
+interface ActiveOrganizationViewOptions<M> {
+    /** Nobody signed in: the view is empty and loads nothing. */
+    readonly signedIn: boolean;
+    /** The organization every request carries now, verified against live membership. Null = must choose. */
+    readonly resolve: () => Promise<M | null>;
+    /** The organizations to list (the host picks the archive filter). */
+    readonly list: () => Promise<readonly M[]>;
+    /** Make `organizationId` the active one; answers the organization now active. */
+    readonly choose: (organizationId: string) => Promise<M | null>;
+    /** Anything that changes what `resolve`/`list` answer (the archive filter, the person). Re-reads when it changes. */
+    readonly deps?: readonly unknown[];
+    /** Another context moved the active organization: call `reload` when it fires. Returns the unsubscribe. */
+    readonly subscribe?: (reload: () => void) => () => void;
+}
+interface ActiveOrganizationView<M> {
+    readonly active: M | null;
+    readonly organizations: readonly M[];
+    readonly loading: boolean;
+    /** Non-null when the organizations could not be READ — never presented as "no organization". */
+    readonly error: string | null;
+    /** True only when signed in, the read succeeded, and no organization is active. */
+    readonly mustChoose: boolean;
+    readonly choose: (organizationId: string) => Promise<void>;
+    readonly reload: () => void;
+}
+/**
+ * The state machine every picker/header needs around the active organization: load, error vs none,
+ * must-choose, choose, reload. The host injects its reads (so a UI and a request kernel that resolve
+ * through the same function can never disagree); this owns the cancellation and the honest states.
+ */
+declare function useActiveOrganizationView<M>(options: ActiveOrganizationViewOptions<M>): ActiveOrganizationView<M>;
 
-export { type SessionState, useActiveOrganization, useSession, useSessionIdentity };
+export { type ActiveOrganizationView, type ActiveOrganizationViewOptions, type SessionState, useActiveOrganization, useActiveOrganizationView, useSession, useSessionIdentity };

package/dist/react.d.ts

@@ -180,5 +180,36 @@ declare function useActiveOrganization(store: ActiveOrganization): ActiveOrganiz
  * the first session read answers; StrictMode-safe (the store is made and disposed in an effect).
  */
 declare function useSessionIdentity<Id extends string = string>(options: SessionIdentityOptions<Id>): SessionIdentitySnapshot<Id>;
+interface ActiveOrganizationViewOptions<M> {
+    /** Nobody signed in: the view is empty and loads nothing. */
+    readonly signedIn: boolean;
+    /** The organization every request carries now, verified against live membership. Null = must choose. */
+    readonly resolve: () => Promise<M | null>;
+    /** The organizations to list (the host picks the archive filter). */
+    readonly list: () => Promise<readonly M[]>;
+    /** Make `organizationId` the active one; answers the organization now active. */
+    readonly choose: (organizationId: string) => Promise<M | null>;
+    /** Anything that changes what `resolve`/`list` answer (the archive filter, the person). Re-reads when it changes. */
+    readonly deps?: readonly unknown[];
+    /** Another context moved the active organization: call `reload` when it fires. Returns the unsubscribe. */
+    readonly subscribe?: (reload: () => void) => () => void;
+}
+interface ActiveOrganizationView<M> {
+    readonly active: M | null;
+    readonly organizations: readonly M[];
+    readonly loading: boolean;
+    /** Non-null when the organizations could not be READ — never presented as "no organization". */
+    readonly error: string | null;
+    /** True only when signed in, the read succeeded, and no organization is active. */
+    readonly mustChoose: boolean;
+    readonly choose: (organizationId: string) => Promise<void>;
+    readonly reload: () => void;
+}
+/**
+ * The state machine every picker/header needs around the active organization: load, error vs none,
+ * must-choose, choose, reload. The host injects its reads (so a UI and a request kernel that resolve
+ * through the same function can never disagree); this owns the cancellation and the honest states.
+ */
+declare function useActiveOrganizationView<M>(options: ActiveOrganizationViewOptions<M>): ActiveOrganizationView<M>;
 
-export { type SessionState, useActiveOrganization, useSession, useSessionIdentity };
+export { type ActiveOrganizationView, type ActiveOrganizationViewOptions, type SessionState, useActiveOrganization, useActiveOrganizationView, useSession, useSessionIdentity };

package/dist/react.js

@@ -181,8 +181,53 @@ function useSessionIdentity(options) {
   const source = identity ?? NO_IDENTITY;
   return useSyncExternalStore(source.subscribe, source.snapshot, () => SERVER_SESSION_IDENTITY);
 }
+function useActiveOrganizationView(options) {
+  const latest = useRef(options);
+  latest.current = options;
+  const [active, setActive] = useState(null);
+  const [organizations, setOrganizations] = useState([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState(null);
+  const [nonce, setNonce] = useState(0);
+  const reload = useRef(() => setNonce((n) => n + 1)).current;
+  useEffect(() => {
+    let cancelled = false;
+    if (!options.signedIn) {
+      setActive(null);
+      setOrganizations([]);
+      setLoading(false);
+      setError(null);
+      return;
+    }
+    setLoading(true);
+    void (async () => {
+      try {
+        const [resolved, all] = await Promise.all([latest.current.resolve(), latest.current.list()]);
+        if (cancelled) return;
+        setActive(resolved);
+        setOrganizations(all);
+        setError(null);
+      } catch (err) {
+        if (cancelled) return;
+        setError(err instanceof Error ? err.message : String(err));
+      } finally {
+        if (!cancelled) setLoading(false);
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [options.signedIn, nonce, ...options.deps ?? []]);
+  const subscribe = options.subscribe;
+  useEffect(() => subscribe ? subscribe(reload) : void 0, [subscribe, reload]);
+  const choose = useRef(async (organizationId) => {
+    setActive(await latest.current.choose(organizationId));
+  }).current;
+  return { active, organizations, loading, error, mustChoose: options.signedIn && !loading && !error && !active, choose, reload };
+}
 export {
   useActiveOrganization,
+  useActiveOrganizationView,
   useSession,
   useSessionIdentity
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-matrx/auth",
-  "version": "0.2.5",
+  "version": "0.3.1",
   "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": "9517977774bcd6e3ed1018bd331ca397a8e7ddfd"
+  "gitHead": "63d7fd1430cbe05b6ed9f0e638ae4c630232497a"
 }