@ai-matrx/auth 0.2.4 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog — @ai-matrx/auth
 
+## 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
+`git diff npm/auth/v0.2.4..npm/auth/v0.2.5 -- apps/shared/auth`).
+No source changes intended and no consumer action required.
+
 ## 0.2.4
 ### active organization options (round 2)
 
@@ -48,7 +66,7 @@ No source changes intended and no consumer action required.
   attaches (bounded wait, one retry after the session re-resolves, a foreign-authority token is signed out
   and never retried, every firing reported). Host-neutral: the host injects `report`, `isAnonymousByDesign`,
   `bypassesSessionWait`, `endUnverifiable`. From the website's `utils/supabase/sessionBarrier.ts`.
-- `/guest` (new section) — `createGuestHandover(...)`: a visitor's guest data survives sign-in (claim into the
+- `/guest` (new section) — `createGuestHandover(...)` (the host injects `readGuestClaims`; the section builds no Supabase client): a visitor's guest data survives sign-in (claim into the
   account the session ends in, cookie kept on failure so the next sign-in retries) and sign-up (the same
   account is promoted in place); `guestClientCookieOptions` (the guest client's own cookie name, injected);
   `createGuestSessionEnsurer` (mint a guest once per tab/browser). From the website's `lib/guest/*`.
@@ -67,7 +85,8 @@ Tests: `session-barrier.test.ts`, `guest.test.ts`.
   (injectable `messages`), `resolveOrganizationWithLink` (the one ladder + the link, share admission injected).
 - `organization-gate` — `createOrganizationBootstrapGate`, `isNotAMemberRefusal`, `createNotAMemberRefusalNotice`,
   `resolveChildOrganizationId`, `resolveAdminSeat`, `adminSeatReplacesUserContext`.
-Tests: active-organization (+5), organization-gate (9).
+- `readMembershipRows(db, containerType)` — the paged `mbr_for_user` raw-row read (any container type), returning the failing page's `{error,status}` so a host can wrap it in its own session retry.
+Tests: active-organization (+5), organization-gate (11).
 
 ## 0.2.0
 

package/dist/{active-organization-Cxm6GDIy.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"> & {
@@ -647,4 +653,4 @@ declare function storageHeldOrganization(storage: Pick<Storage, "getItem" | "set
 declare function memoryHeldOrganization(): HeldOrganizationStore;
 declare function createActiveOrganization(options: CreateActiveOrganizationOptions): ActiveOrganization;
 
-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 };
+export { createNotAMemberRefusalNotice as $, type AuthClient as A, NoActiveOrganizationError as B, type CachedActiveOrganization as C, NotAMemberError as D, type NotAMemberRefusalNotice as E, ORGANIZATION_ENTITY_TYPE as F, ORGANIZATION_RESOLUTION_TIMEOUT_MS as G, type HeldOrganizationStore as H, type OrganizationBootstrapGate as I, type OrganizationLapse as J, type OrganizationMembership as K, LINK_ORGANIZATION_QUERY_KEY as L, type OrganizationRefusal as M, NOT_A_MEMBER_RECHECK_GAP_MS as N, type OrganizationsDb as O, type OrganizationRung 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-Cxm6GDIy.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"> & {
@@ -647,4 +653,4 @@ declare function storageHeldOrganization(storage: Pick<Storage, "getItem" | "set
 declare function memoryHeldOrganization(): HeldOrganizationStore;
 declare function createActiveOrganization(options: CreateActiveOrganizationOptions): ActiveOrganization;
 
-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 };
+export { createNotAMemberRefusalNotice as $, type AuthClient as A, NoActiveOrganizationError as B, type CachedActiveOrganization as C, NotAMemberError as D, type NotAMemberRefusalNotice as E, ORGANIZATION_ENTITY_TYPE as F, ORGANIZATION_RESOLUTION_TIMEOUT_MS as G, type HeldOrganizationStore as H, type OrganizationBootstrapGate as I, type OrganizationLapse as J, type OrganizationMembership as K, LINK_ORGANIZATION_QUERY_KEY as L, type OrganizationRefusal as M, NOT_A_MEMBER_RECHECK_GAP_MS as N, type OrganizationsDb as O, type OrganizationRung 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/{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/guest.cjs

@@ -28,7 +28,6 @@ __export(guest_exports, {
   looksLikeVisitorId: () => looksLikeVisitorId
 });
 module.exports = __toCommonJS(guest_exports);
-var import_ssr = require("@supabase/ssr");
 var VISITOR_ID = /^[A-Za-z0-9]{16,200}$/;
 function looksLikeVisitorId(id) {
   return typeof id === "string" && !id.startsWith("temp_") && VISITOR_ID.test(id);
@@ -42,21 +41,11 @@ function createGuestHandover(options) {
   const loud = options.log ?? ((m) => console.error(`[session-handover] LOUD: ${m}`));
   const isGuestCookie = (name) => isGuestCookieName(options.guestCookieName, name);
   const msg = (err) => err instanceof Error ? err.message : String(err);
-  async function readClaims(jar) {
-    if (options.readGuestClaims) return options.readGuestClaims(jar);
-    if (!options.supabase) return null;
-    const guest = (0, import_ssr.createServerClient)(options.supabase.url, options.supabase.publishableKey, {
-      cookieOptions: { name: options.guestCookieName },
-      cookies: { getAll: () => jar.getAll(), setAll: () => void 0 }
-    });
-    const { data } = await guest.auth.getClaims();
-    return data?.claims ?? null;
-  }
   async function readGuestPossession(visitorId) {
     const jar = await options.cookies();
     if (jar.getAll().some((c) => isGuestCookie(c.name))) {
       try {
-        const claims = await readClaims(jar);
+        const claims = await options.readGuestClaims(jar);
         if (claims?.sub && claims.is_anonymous === true) return { guestId: claims.sub, proof: "guest_session" };
       } catch (err) {
         loud(`the guest cookie could not be verified: ${msg(err)}`);

package/dist/guest.d.cts

@@ -1,3 +1,25 @@
+/**
+ * @ai-matrx/auth/guest — a visitor's guest data survives sign-up and sign-in (moved from the
+ * website's `lib/guest/{session-handover,guest-supabase-client,ensure-guest-session}.ts`, 2026-10-12).
+ *
+ * A signed-out visitor who saves holds a GUEST session: a real, not-yet-permanent account that lives in
+ * its OWN cookie (never the main auth cookie, so a guest never looks signed in). Every place a session is
+ * REPLACED (password login, OAuth callback, email confirm, dev-login) runs through `handOverSession`:
+ *
+ *   1. read who the browser's guest is BEFORE the replacement (the verified claims of the guest cookie,
+ *      else the visitor id mapped through the registry — the lost-session case);
+ *   2. replace the session;
+ *   3. when the result is a permanent account other than the guest, CLAIM the guest's workspace into it
+ *      (all or nothing) and drop the guest cookie. A failed claim keeps the cookie, so the next replacement
+ *      (or `settlePendingGuestClaim` on a signed-in load) tries again — it screams, never silently.
+ *
+ * Sign-up with email + password keeps the SAME account (`promoteGuest`): revive, promote in place, revive
+ * again, stamp the registry. Never falls back to a fresh account (that would orphan the guest).
+ *
+ * Host-neutral: the host injects the cookie jar, the guest store (admin reads and the claim/revive doors)
+ * and the cookie names. The browser half is `createGuestClientOptions` (the guest client's own cookie name,
+ * injected) and `createGuestSessionEnsurer` (mint a guest once per tab / per browser).
+ */
 type HandoverVia = "password_login" | "oauth_callback" | "email_otp" | "dev_login" | "sign_up";
 interface GuestPossession {
     guestId: string;
@@ -93,15 +115,15 @@ interface GuestHandoverOptions {
     /** Server cookie jar for this request. */
     cookies(): Promise<GuestCookieJar>;
     store: GuestStore;
-    /** Verified claims of the guest cookie. Default: a server client over `supabase` url + key. */
-    readGuestClaims?(jar: GuestCookieJar): Promise<{
+    /**
+     * Verified claims of the guest cookie (the anonymous JWT in this very request is the proof of possession).
+     * The host builds a server client over the guest cookie name and reads `getClaimsUser`; this section builds no
+     * Supabase client of its own.
+     */
+    readGuestClaims(jar: GuestCookieJar): Promise<{
         sub?: string;
         is_anonymous?: boolean;
     } | null>;
-    supabase?: {
-        url: string;
-        publishableKey: string;
-    };
     /** `Secure` on the carrier cookie. */
     secureCookies?: boolean;
     log?(message: string): void;

package/dist/guest.d.ts

@@ -1,3 +1,25 @@
+/**
+ * @ai-matrx/auth/guest — a visitor's guest data survives sign-up and sign-in (moved from the
+ * website's `lib/guest/{session-handover,guest-supabase-client,ensure-guest-session}.ts`, 2026-10-12).
+ *
+ * A signed-out visitor who saves holds a GUEST session: a real, not-yet-permanent account that lives in
+ * its OWN cookie (never the main auth cookie, so a guest never looks signed in). Every place a session is
+ * REPLACED (password login, OAuth callback, email confirm, dev-login) runs through `handOverSession`:
+ *
+ *   1. read who the browser's guest is BEFORE the replacement (the verified claims of the guest cookie,
+ *      else the visitor id mapped through the registry — the lost-session case);
+ *   2. replace the session;
+ *   3. when the result is a permanent account other than the guest, CLAIM the guest's workspace into it
+ *      (all or nothing) and drop the guest cookie. A failed claim keeps the cookie, so the next replacement
+ *      (or `settlePendingGuestClaim` on a signed-in load) tries again — it screams, never silently.
+ *
+ * Sign-up with email + password keeps the SAME account (`promoteGuest`): revive, promote in place, revive
+ * again, stamp the registry. Never falls back to a fresh account (that would orphan the guest).
+ *
+ * Host-neutral: the host injects the cookie jar, the guest store (admin reads and the claim/revive doors)
+ * and the cookie names. The browser half is `createGuestClientOptions` (the guest client's own cookie name,
+ * injected) and `createGuestSessionEnsurer` (mint a guest once per tab / per browser).
+ */
 type HandoverVia = "password_login" | "oauth_callback" | "email_otp" | "dev_login" | "sign_up";
 interface GuestPossession {
     guestId: string;
@@ -93,15 +115,15 @@ interface GuestHandoverOptions {
     /** Server cookie jar for this request. */
     cookies(): Promise<GuestCookieJar>;
     store: GuestStore;
-    /** Verified claims of the guest cookie. Default: a server client over `supabase` url + key. */
-    readGuestClaims?(jar: GuestCookieJar): Promise<{
+    /**
+     * Verified claims of the guest cookie (the anonymous JWT in this very request is the proof of possession).
+     * The host builds a server client over the guest cookie name and reads `getClaimsUser`; this section builds no
+     * Supabase client of its own.
+     */
+    readGuestClaims(jar: GuestCookieJar): Promise<{
         sub?: string;
         is_anonymous?: boolean;
     } | null>;
-    supabase?: {
-        url: string;
-        publishableKey: string;
-    };
     /** `Secure` on the carrier cookie. */
     secureCookies?: boolean;
     log?(message: string): void;

package/dist/guest.js

@@ -1,5 +1,4 @@
 // src/guest.ts
-import { createServerClient } from "@supabase/ssr";
 var VISITOR_ID = /^[A-Za-z0-9]{16,200}$/;
 function looksLikeVisitorId(id) {
   return typeof id === "string" && !id.startsWith("temp_") && VISITOR_ID.test(id);
@@ -13,21 +12,11 @@ function createGuestHandover(options) {
   const loud = options.log ?? ((m) => console.error(`[session-handover] LOUD: ${m}`));
   const isGuestCookie = (name) => isGuestCookieName(options.guestCookieName, name);
   const msg = (err) => err instanceof Error ? err.message : String(err);
-  async function readClaims(jar) {
-    if (options.readGuestClaims) return options.readGuestClaims(jar);
-    if (!options.supabase) return null;
-    const guest = createServerClient(options.supabase.url, options.supabase.publishableKey, {
-      cookieOptions: { name: options.guestCookieName },
-      cookies: { getAll: () => jar.getAll(), setAll: () => void 0 }
-    });
-    const { data } = await guest.auth.getClaims();
-    return data?.claims ?? null;
-  }
   async function readGuestPossession(visitorId) {
     const jar = await options.cookies();
     if (jar.getAll().some((c) => isGuestCookie(c.name))) {
       try {
-        const claims = await readClaims(jar);
+        const claims = await options.readGuestClaims(jar);
         if (claims?.sub && claims.is_anonymous === true) return { guestId: claims.sub, proof: "guest_session" };
       } catch (err) {
         loud(`the guest cookie could not be verified: ${msg(err)}`);

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-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 { 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-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 { 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

@@ -22,6 +22,7 @@ var organizations_exports = {};
 __export(organizations_exports, {
   LINK_ORGANIZATION_QUERY_KEY: () => LINK_ORGANIZATION_QUERY_KEY,
   MEMBERSHIPS_URL: () => MEMBERSHIPS_URL,
+  MEMBERSHIP_ROWS_PAGE: () => MEMBERSHIP_ROWS_PAGE,
   NOT_A_MEMBER_RECHECK_GAP_MS: () => NOT_A_MEMBER_RECHECK_GAP_MS,
   NoActiveOrganizationError: () => NoActiveOrganizationError,
   NotAMemberError: () => NotAMemberError,
@@ -51,20 +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,
@@ -608,6 +614,10 @@ function createActiveOrganization(options) {
         return current;
       }
       if (options.holdResolved ?? true) await held.write(person.id, resolved.organization.id);
+      if (options.clearStaleHeld) {
+        const stale = await held.read(person.id);
+        if (stale && !memberships.some((m) => m.id === stale)) await held.clear();
+      }
       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);
@@ -858,3 +868,51 @@ function organizationRequiredEnvelope(error, setOn = "request") {
 function organizationRequiredResponse(error) {
   return Response.json(organizationRequiredEnvelope(error), { status: 400 });
 }
+
+// src/organization-membership-rows.ts
+var MEMBERSHIP_ROWS_PAGE = 500;
+async function readMembershipRows(db, containerType, pageSize = MEMBERSHIP_ROWS_PAGE) {
+  const rows = [];
+  for (let from = 0; ; from += pageSize) {
+    const answer = await db.rpc("mbr_for_user", { p_container_type: containerType }).order("id", { ascending: true }).range(from, from + pageSize - 1);
+    if (answer.error) return { data: null, error: answer.error, status: answer.status };
+    const page = Array.isArray(answer.data) ? answer.data : [];
+    rows.push(...page);
+    if (page.length < pageSize) break;
+  }
+  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,4 +1,5 @@
-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 { 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';
 
 /**
@@ -107,4 +108,70 @@ declare function organizationRequiredEnvelope(error: OrganizationRequiredServerE
 /** The standard `Response` (status 400) a route answers the refusal with — no framework needed. */
 declare function organizationRequiredResponse(error: OrganizationRequiredServerError): Response;
 
-export { MEMBERSHIPS_URL, type MembershipReadClient, ORGANIZATION_CONTEXT_REQUIRED_CODE, ORGANIZATION_REQUIRED_CODE, ORGANIZATION_REQUIRED_WIRE_CODE, type OrganizationHoldDetails, type OrganizationHoldSetOn, type OrganizationMembershipSummary, type OrganizationRequiredEnvelope, OrganizationRequiredServerError, type OrganizationRequiredWireMembership, extractOrganizationHoldMemberships, isOrganizationRequiredEnvelope, isOrganizationRequiredError, isOrganizationRequiredServerError, organizationRequired, organizationRequiredEnvelope, organizationRequiredResponse, readCallerMemberships };
+/**
+ * The person's raw membership rows for ONE container type, PAGED — the canonical `mbr_for_user`
+ * door (moved from the website's membershipsService). PostgREST caps one answer at its max-rows
+ * (1000): a person in 1,043 organizations lost the last 43, so the read pages in stable id order
+ * until a short page.
+ *
+ * It does NOT throw: it returns the first failing page's `{ error, status }` so a host can wrap
+ * the whole read in its own session retry (a 401 on a recovering session) and map the error its
+ * own way.
+ */
+
+declare const MEMBERSHIP_ROWS_PAGE = 500;
+interface MembershipRowsAnswer<Row> {
+    readonly data: Row[] | null;
+    readonly error: {
+        message: string;
+        code?: string;
+    } | null;
+    readonly status?: number | undefined;
+}
+declare function readMembershipRows<Row = Record<string, unknown>>(db: OrganizationsDb, containerType: string, pageSize?: number): Promise<MembershipRowsAnswer<Row>>;
+
+/**
+ * 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,4 +1,5 @@
-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 { 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';
 
 /**
@@ -107,4 +108,70 @@ declare function organizationRequiredEnvelope(error: OrganizationRequiredServerE
 /** The standard `Response` (status 400) a route answers the refusal with — no framework needed. */
 declare function organizationRequiredResponse(error: OrganizationRequiredServerError): Response;
 
-export { MEMBERSHIPS_URL, type MembershipReadClient, ORGANIZATION_CONTEXT_REQUIRED_CODE, ORGANIZATION_REQUIRED_CODE, ORGANIZATION_REQUIRED_WIRE_CODE, type OrganizationHoldDetails, type OrganizationHoldSetOn, type OrganizationMembershipSummary, type OrganizationRequiredEnvelope, OrganizationRequiredServerError, type OrganizationRequiredWireMembership, extractOrganizationHoldMemberships, isOrganizationRequiredEnvelope, isOrganizationRequiredError, isOrganizationRequiredServerError, organizationRequired, organizationRequiredEnvelope, organizationRequiredResponse, readCallerMemberships };
+/**
+ * The person's raw membership rows for ONE container type, PAGED — the canonical `mbr_for_user`
+ * door (moved from the website's membershipsService). PostgREST caps one answer at its max-rows
+ * (1000): a person in 1,043 organizations lost the last 43, so the read pages in stable id order
+ * until a short page.
+ *
+ * It does NOT throw: it returns the first failing page's `{ error, status }` so a host can wrap
+ * the whole read in its own session retry (a 401 on a recovering session) and map the error its
+ * own way.
+ */
+
+declare const MEMBERSHIP_ROWS_PAGE = 500;
+interface MembershipRowsAnswer<Row> {
+    readonly data: Row[] | null;
+    readonly error: {
+        message: string;
+        code?: string;
+    } | null;
+    readonly status?: number | undefined;
+}
+declare function readMembershipRows<Row = Record<string, unknown>>(db: OrganizationsDb, containerType: string, pageSize?: number): Promise<MembershipRowsAnswer<Row>>;
+
+/**
+ * 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

@@ -534,6 +534,10 @@ function createActiveOrganization(options) {
         return current;
       }
       if (options.holdResolved ?? true) await held.write(person.id, resolved.organization.id);
+      if (options.clearStaleHeld) {
+        const stale = await held.read(person.id);
+        if (stale && !memberships.some((m) => m.id === stale)) await held.clear();
+      }
       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);
@@ -784,9 +788,58 @@ function organizationRequiredEnvelope(error, setOn = "request") {
 function organizationRequiredResponse(error) {
   return Response.json(organizationRequiredEnvelope(error), { status: 400 });
 }
+
+// src/organization-membership-rows.ts
+var MEMBERSHIP_ROWS_PAGE = 500;
+async function readMembershipRows(db, containerType, pageSize = MEMBERSHIP_ROWS_PAGE) {
+  const rows = [];
+  for (let from = 0; ; from += pageSize) {
+    const answer = await db.rpc("mbr_for_user", { p_container_type: containerType }).order("id", { ascending: true }).range(from, from + pageSize - 1);
+    if (answer.error) return { data: null, error: answer.error, status: answer.status };
+    const page = Array.isArray(answer.data) ? answer.data : [];
+    rows.push(...page);
+    if (page.length < pageSize) break;
+  }
+  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,
+  MEMBERSHIP_ROWS_PAGE,
   NOT_A_MEMBER_RECHECK_GAP_MS,
   NoActiveOrganizationError,
   NotAMemberError,
@@ -816,20 +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.4",
+  "version": "0.3.0",
   "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": "f9020cf33c7ac2b8b854856131eb0b1268eb220d"
+  "gitHead": "032b64c11a538c439562215e8dc33fba11bc0050"
 }