@oxyhq/core 20.1.0 → 21.0.0

package/dist/types/session/accountDialogController.d.ts

@@ -9,15 +9,16 @@
  * replaces.
  *
  * The controller owns:
- *   - the unified account list (via {@link projectSwitchableAccounts}), fetched
- *     from `SessionClient` state ∪ `oxyServices.listAccounts()` and hydrated
- *     with `oxyServices.getUsersByIds()`;
+ *   - the device DIRECTORY (ADR 0002) — the server-authoritative read model of
+ *     who is on this device and what each of them may act as, read through
+ *     `SessionClient.refreshDirectory()`. It is not assembled here: the client
+ *     holds one caller's account graph and cannot enumerate another principal's,
+ *     so switchability is the server's answer and the controller only reads it;
  *   - the dialog `view` state machine (`accounts` | `signin` | `qr` | `add` |
  *     `signup`);
- *   - `switchTo` (the uniform switch: `SessionClient.switchAccount` for an
- *     account already on the device, `oxyServices.switchToAccount` to mint on
- *     first entry into a graph account — reusing the existing SDK primitives, no
- *     new switch path);
+ *   - `activateContext` (the ADR 0002 switch, keyed on the `principal acting as
+ *     account` pair) and the two removals an account id cannot name —
+ *     `signOutContext` and `signOutPrincipal`;
  *   - the "Sign in with Oxy" device flow (same-device shared-keychain via
  *     `oxyServices.signInWithSharedIdentity`, else the cross-device QR handoff
  *     via `startCommonsSignIn` → poll → `claimSessionByToken`);
@@ -54,11 +55,12 @@
  * `add` / `startSignup` (the view axis) and `cancelSignIn` (device-flow
  * teardown), never an `open` / `close` / `visible`.
  */
+import type { DeviceDirectory } from '@oxyhq/contracts';
 import type { OxyServices } from '../OxyServices';
 import type { SessionLoginResponse, MinimalUserData } from '../models/session';
 import type { SessionClient } from './SessionClient';
 import type { SocketIOFactory } from './socketLoader';
-import { type SwitchableAccount } from './accountProjection';
+import { type DeviceContext } from './deviceDirectory';
 import { type CommonsDeliveryPlatform, type CommonsDeliveryRoute } from '../utils/commonsDelivery';
 /** The dialog's top-level view. */
 export type AccountDialogView = 'accounts' | 'signin' | 'qr' | 'add' | 'signup';
@@ -192,16 +194,27 @@ export interface SignInFlowState {
 export interface AccountDialogSnapshot {
     /** The current view. */
     view: AccountDialogView;
-    /** The unified, deduped account list (device sign-ins ∪ graph accounts). */
-    accounts: SwitchableAccount[];
-    /** The currently-active account id, or `null` when signed out. */
-    activeAccountId: string | null;
-    /** `true` while the initial account-list fetch is in flight with no data yet. */
+    /**
+     * The server-authoritative device directory — principals and the contexts
+     * each may act as (ADR 0002) — or `null` before the first read.
+     *
+     * The ONE read model a switcher renders. The flat list this replaced was
+     * keyed by account id, so on a device holding two people it could show one
+     * route to a shared organization and never both.
+     */
+    directory: DeviceDirectory | null;
+    /** The active `principal acting as account` pair, actor and subject apart. */
+    activeContext: DeviceContext | null;
+    /** `true` while the first directory read is in flight with nothing to show. */
     loading: boolean;
-    /** A human-readable account-list error, or `null`. */
+    /** A human-readable directory error, or `null`. */
     error: string | null;
-    /** The `accountId` of an in-flight switch, or `null`. */
-    switchingAccountId: string | null;
+    /** The `contextId` of an in-flight activation, or `null`. */
+    activatingContextId: string | null;
+    /** The `contextId` of an in-flight context removal, or `null`. */
+    removingContextId: string | null;
+    /** The `principalId` of an in-flight principal removal, or `null`. */
+    removingPrincipalId: string | null;
     /** The "Sign in with Oxy" device-flow state. */
     signIn: SignInFlowState;
     /** Whether Commons is installed on this device. See {@link CommonsAvailability}. */
@@ -220,8 +233,6 @@ export interface AccountDialogControllerOptions {
      * server would reject.
      */
     clientId?: string | null;
-    /** Locale for display-name resolution. */
-    locale?: string;
     /**
      * Commit a freshly-authorized SIGN-IN session (device flow / shared identity)
      * into the host's session set — device-first registration + durable persist +
@@ -231,24 +242,12 @@ export interface AccountDialogControllerOptions {
      * `SessionClient.registerAndActivate` (registration + activation only — no
      * provider-side durable persist/hydration).
      *
-     * This is the SIGN-IN commit: registers the session into the host's device
-     * set with durable persist + profile hydration. An account SWITCH uses
-     * {@link commitSwitchedSession} instead — see below.
+     * Sign-in is the only thing that commits a session here. An account SWITCH
+     * used to mint one too, on first entry into a graph account; activation mints
+     * the delegated session SERVER-side and hands back a bearer, so there is no
+     * second commit funnel to keep in step with this one.
      */
     commitSession?: (session: SessionLoginResponse) => Promise<void>;
-    /**
-     * Commit a minted graph SWITCH session into the host's session set — same
-     * device-first registration + durable persist + profile hydration as
-     * {@link commitSession}, but IN-PLACE: it must NOT re-run sign-in side effects
-     * that belong only to a fresh authorization (for example, a redundant full
-     * device-set reconcile on switch). Cross-tab/app propagation of the switch
-     * still happens instantly via the server's device-scoped `session_state` /
-     * `session_accounts_changed` socket broadcast — no navigation required.
-     *
-     * When omitted the controller falls back to {@link commitSession} (if wired)
-     * and then to `SessionClient.registerAndActivate`.
-     */
-    commitSwitchedSession?: (session: SessionLoginResponse) => Promise<void>;
     /** Notified after a completed sign-in (bearer planted + session committed). */
     onSignedIn?: (user: MinimalUserData) => void;
     /**
@@ -313,9 +312,7 @@ export declare class AccountDialogController {
     private readonly oxyServices;
     private readonly sessionClient;
     private readonly clientId;
-    private readonly locale?;
     private readonly commitSession?;
-    private readonly commitSwitchedSession?;
     private readonly onSignedIn?;
     private readonly pollIntervalMs;
     private readonly openUrl?;
@@ -326,11 +323,11 @@ export declare class AccountDialogController {
     private readonly platform;
     private readonly listeners;
     private view;
-    private graph;
-    private profilesById;
     private loading;
     private error;
-    private switchingAccountId;
+    private activatingContextId;
+    private removingContextId;
+    private removingPrincipalId;
     private signIn;
     private commonsAvailability;
     /** The secret device-flow token of the active QR flow (never surfaced). */
@@ -406,35 +403,54 @@ export declare class AccountDialogController {
     /** Switch to the "create account" view (passkey / Commons signup entry). */
     startSignup(): void;
     /**
-     * Reload the account graph and per-account profiles, then re-project. Safe to
-     * call repeatedly; concurrent calls are reconciled by a sequence guard so a
-     * slow earlier fetch never overwrites a newer result.
+     * Re-read `GET /session/device/directory`. Safe to call repeatedly;
+     * concurrent calls are reconciled by a sequence guard so a slow earlier read
+     * never overwrites a newer result.
+     *
+     * This is ONE request. It used to be three — the directory, plus
+     * `listAccounts()` and `getUsersByIds()` to rebuild the same tree client-side
+     * — and the reconstruction was not merely redundant: it enumerated the
+     * CALLER's account graph, which on a device holding two people is one
+     * person's answer presented as the device's.
      */
     refresh(): Promise<void>;
     /**
-     * Fetch profiles for any account id (device set ∪ graph) not yet resolved.
-     * Cheap no-op when everything is already hydrated — used from the session
-     * subscription so a newly-added device account gets a name/avatar.
+     * Activate one `principal acting as account` context — the ADR 0002 switch,
+     * and the one that can express what an account id cannot: WHICH person's
+     * route to a shared organization to become.
+     *
+     * There is no on-device/graph fork. The directory has a row for a context the
+     * principal may act as but has never entered, and `POST /session/device/
+     * activate` reuses or mints the delegated session server-side, so one call
+     * covers both cases.
+     *
+     * A context id is not stable across a removal, so a stale one is an ordinary
+     * outcome rather than a bug: the server answers 404 or 403, heals the row, and
+     * the refresh below re-reads a directory that no longer offers it.
      */
-    private ensureProfiles;
-    private loadProfiles;
+    activateContext(contextId: string): Promise<boolean>;
     /**
-     * Switch the active account to `accountId`.
+     * Remove ONE `principal → account` pair, and only that pair.
+     *
+     * Not the account across the device: the same organization reached through a
+     * second person is a different session with a different audit actor, and it
+     * stays. Routing this through `signOut({accountId})` would revoke that second
+     * person's access as a side effect of one person tidying their own list.
      *
-     * Uniform switch model, mirroring the SDK's existing path — NOT a new switch
-     * mechanism:
-     *   - already on this device → `SessionClient.switchAccount` (device-first
-     *     switch of `/session/device/switch`);
-     *   - a graph account not yet on the device (first entry) →
-     *     `oxyServices.switchToAccount` mints + plants a real session and the
-     *     server registers it into the device set, then it is committed
-     *     (`commitSession` when supplied, else `SessionClient.registerAndActivate`).
+     * The removed pair is not gone for good while the membership lives — the
+     * server offers it again on the next read, under a NEW id and at an unchanged
+     * revision — so nothing may hold a context id across this call.
+     */
+    signOutContext(contextId: string): Promise<boolean>;
+    /**
+     * Remove ONE PERSON and every context they reach — and nobody else's,
+     * including when another principal independently operates the same account.
      *
-     * The resulting device-state change flows back through the `SessionClient`
-     * subscription, which re-projects the active row. Concurrent switches are
-     * ignored while one is in flight.
+     * A separate call from {@link signOutContext} because it is a separate
+     * question, not a loop over the first one: the server removes the principal
+     * and elects a replacement active context in one transition.
      */
-    switchTo(accountId: string): Promise<boolean>;
+    signOutPrincipal(principalId: string): Promise<boolean>;
     /**
      * Start "Sign in with Oxy". Native devices with a shared identity mint a
      * session silently (`signInWithSharedIdentity`); everything else (web, or a
@@ -595,10 +611,6 @@ export declare class AccountDialogController {
      * Register a token-planted session into the device set. Prefers the
      * consumer's commit funnel (durable persist + hydration); falls back to
      * `SessionClient.registerAndActivate` (registration + activation only).
-     *
-     * A SWITCH (`opts.fromSwitch`) uses the IN-PLACE `commitSwitchedSession` funnel;
-     * a SIGN-IN uses `commitSession`. When the switch funnel is not wired it falls
-     * back to the sign-in funnel, then to `registerAndActivate`.
      */
     private commitAuthorizedSession;
     private failSignIn;

package/dist/types/session/accountSwitchTargets.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The two questions an account chooser asks of an account-graph node: is this
+ * kind switchable at all, and may THIS caller become it.
+ *
+ * Pure and I/O-free. They live here rather than beside the surfaces that ask
+ * them because there is more than one such surface — the Console's workspace
+ * tree, the Accounts app's managed-account rows — and a second enumeration of
+ * switch targets is a second place for the rule to go missing, which is
+ * precisely how the Console went on offering `channel` rows after the rule
+ * learned to drop them.
+ *
+ * The DEVICE switcher no longer asks anything here: it renders the server's
+ * device directory (ADR 0002, `deviceDirectory.ts`), whose `available` field is
+ * the server's own authorization verdict. These predicates answer a different
+ * question — one about the caller's account GRAPH, which is a list of accounts
+ * to manage, not a list of identities the device can become.
+ */
+import type { AccountRelationship, AccountKind, AccountMember } from '../mixins/OxyServices.accounts';
+/**
+ * Whether the caller can BECOME this account — the one question every account
+ * switcher asks, answered here so no surface has to re-derive it.
+ *
+ * Two independent grounds, either of which suffices:
+ *
+ *  - **It is already the caller's own identity** (`relationship: 'self'`).
+ *    `GET /accounts` resolves its caller through `resolveOperatorId`, so `self`
+ *    is the HUMAN operator's personal account even while they are operating an
+ *    org — never the operated account. Kind is irrelevant on this ground: the
+ *    caller IS that account, so returning to it asks the server for nothing.
+ *  - **The server will mint a session for it** — `isActAsEligibleKind(kind)` is
+ *    the exact predicate `POST /accounts/:id/switch` enforces, so a row offered
+ *    on this ground is never a dead button.
+ *
+ * `isActAsEligibleKind` ALONE is not this question, and reaching for it
+ * directly is the mistake this function exists to prevent: it is false for
+ * `personal` as well as `channel`, so a switcher gated on it alone renders an
+ * empty list rather than a filtered one. Equally, `kind !== 'channel'` is not
+ * this question either — it silently admits every kind invented after it was
+ * written, which is the same trap `isActAsEligibleKind` was introduced to close
+ * on the server.
+ *
+ * Takes a structural subset rather than a whole {@link AccountNode} so a caller
+ * holding an already-projected row can ask it too.
+ */
+export declare function isSwitchTargetAccount(node: {
+    kind?: AccountKind | null;
+    relationship?: AccountRelationship;
+}): boolean;
+/**
+ * Whether the caller may switch INTO this account — the server-side
+ * `account:act_as` gate plus the structural {@link isSwitchTargetAccount} rule.
+ *
+ * `relationship: 'self'` always passes (returning to the caller's own personal
+ * account). Every other ground requires a switch-eligible kind AND
+ * `account:act_as` in the resolved membership permissions. When permissions are
+ * absent but the relationship is `owner`, the owner baseline is assumed — the
+ * API always resolves effective permissions for owned accounts, but test
+ * fixtures and stale rows may omit the membership blob.
+ */
+export declare function canSwitchIntoAccount(node: {
+    kind?: AccountKind | null;
+    relationship?: AccountRelationship;
+    callerMembership?: AccountMember | null;
+}): boolean;

package/dist/types/session/deviceDirectory.d.ts

@@ -0,0 +1,182 @@
+import type { AccountKind, DeviceContextRelationship, DeviceDirectory, DeviceDirectoryProfile } from '@oxyhq/contracts';
+/**
+ * Pure projections over the device directory (`GET /session/device/directory`,
+ * ADR 0002). No I/O — the caller holds the directory `SessionClient` fetched.
+ *
+ * These exist to say the one thing the flat `DeviceSessionState` projection
+ * structurally cannot: WHO an account is being reached through.
+ * `DeviceSessionState.accounts[]` has carried `operatedByUserId` on the wire all
+ * along and nothing in this SDK ever read it, so "signed in as The Oxy
+ * Collective" and "Nate operating The Oxy Collective" render identically today —
+ * two different audit actors, two different revocation paths, one row. The
+ * directory keeps the two facts apart, and so does everything below.
+ */
+/**
+ * The human whose authentication backs a context — the audit actor.
+ *
+ * Always a person (ADR 0001: a principal is never an organization, project,
+ * channel or bot) and the owner of the `authuser` slot. An organization in the
+ * switcher consumes no slot of its own; it is a SUBJECT under some principal.
+ */
+export interface DeviceContextActor {
+    /** Identifies the principal row — the id `POST /session/device/signout { principalId }` takes. */
+    principalId: string;
+    /** The person's own account id. */
+    userId: string;
+    /** Google-style signed-in-human slot, allocated per person. */
+    authuser: number;
+    profile: DeviceDirectoryProfile;
+}
+/** The account a context acts AS — what a profile header renders. */
+export interface DeviceContextSubject {
+    accountId: string;
+    kind: AccountKind;
+    relationship: DeviceContextRelationship;
+    profile: DeviceDirectoryProfile;
+    /**
+     * `false` for a context the principal may act as but has never activated here.
+     *
+     * NOT a synonym for activatable, in either direction — see
+     * {@link canActivateContext}.
+     */
+    onDevice: boolean;
+    /**
+     * Whether this context can be activated right now — the server's whole verdict,
+     * returned as a row rather than omitted so the UI can explain a row going away.
+     *
+     * It is STRICTER than the old `/switch` gate, and stricter than the name
+     * suggests: it is the live `account:act_as` check AND the PRINCIPAL's own
+     * personal session being live. Activation has no proof of who is acting once
+     * the human's own session is gone, so a dead principal makes every one of
+     * their contexts unavailable — the delegated ones whose own sessions are
+     * perfectly alive included.
+     */
+    available: boolean;
+    lastUsedAt: number | null;
+}
+/**
+ * One resolved `principal acting as account` pair — the globally switchable
+ * unit, with its two halves named.
+ */
+export interface DeviceContext {
+    /**
+     * The identifier `POST /session/device/activate` takes. Names the PAIR, never
+     * the account.
+     *
+     * NOT STABLE ACROSS A REMOVAL, and therefore never something to persist or to
+     * hold across a read. Removing a delegated context is not permanent while the
+     * membership lives: the server rematerializes the pair on the next directory
+     * read, as `onDevice: false` under a NEW id — and it does so WITHOUT bumping
+     * `revision`, so "the device has not changed" is not evidence the id has not.
+     * Re-resolve from the directory in hand every time, and read an id that no
+     * longer resolves as gone rather than as an error.
+     */
+    contextId: string;
+    actor: DeviceContextActor;
+    subject: DeviceContextSubject;
+    /**
+     * Whether the actor and the subject are different accounts — "Nate operating
+     * The Oxy Collective" rather than "Nate". Compared by id rather than read off
+     * `relationship`, so it stays true if the vocabulary ever grows a fourth term.
+     */
+    isDelegated: boolean;
+}
+/**
+ * Resolve one context by its id.
+ *
+ * The search is over `(principal, context)` PAIRS, not over accounts: the same
+ * `accountId` legitimately appears under two principals on a shared device, and
+ * matching on the account would hand back whichever person happened to be
+ * enumerated first.
+ */
+export declare function resolveDeviceContext(directory: DeviceDirectory | null, contextId: string): DeviceContext | null;
+/**
+ * One person on the device, with every account they can act as beneath them.
+ *
+ * This is the switcher's shape, and it is grouped rather than flat because the
+ * flat one cannot state the fact the whole model exists for: the same
+ * organization reachable through two people is TWO rows, under two different
+ * humans, and a list keyed by account can only ever show one of them.
+ */
+export interface DevicePrincipalGroup {
+    /** The id `POST /session/device/signout { principalId }` takes. */
+    principalId: string;
+    /** The person's own account id. */
+    userId: string;
+    /** Google-style signed-in-human slot. An organization consumes none. */
+    authuser: number;
+    profile: DeviceDirectoryProfile;
+    /**
+     * Every context this person can reach, in the server's order (their personal
+     * account first, then the accounts they act as, by account id). Not re-sorted
+     * here: the server's order is already total and revision-stable, and a second
+     * ordering rule on the client would be a second thing to keep in agreement.
+     */
+    contexts: DeviceContext[];
+    /** Whether the device's ACTIVE context belongs to this person. */
+    isActive: boolean;
+}
+/**
+ * The directory as the switcher renders it: people, each with what they may
+ * become.
+ *
+ * A principal with no contexts is kept rather than dropped. It is a real state
+ * — a person whose every context was removed while they remain on the device —
+ * and rendering them with nothing under them is how "sign out of this person"
+ * stays reachable. Silently omitting them would strand the row.
+ */
+export declare function projectDevicePrincipals(directory: DeviceDirectory | null): DevicePrincipalGroup[];
+/**
+ * The device's active context, or `null`.
+ *
+ * `null` is a real state, not an error: a device with every context removed, or
+ * one whose active context was healed away, has none. It is also the answer when
+ * `activeContextId` names a row no principal holds — a directory that
+ * disagreed with itself, which resolves to "nothing is active" rather than to a
+ * guess.
+ */
+export declare function resolveActiveContext(directory: DeviceDirectory | null): DeviceContext | null;
+/**
+ * The name a directory row renders: the API's `displayName` when it has one,
+ * otherwise the normalized handle, otherwise the localized unnamed sentinel.
+ *
+ * The identity contract's `displayName ?? handle`, and deliberately not
+ * `getAccountDisplayName`'s multi-field chain — that one is for LOCAL account
+ * surfaces, and the directory profile is an API DTO whose `name.displayName`
+ * the server already composed or deliberately omitted. `getAccountDisplayName`
+ * appears here only for its `null` case, which is the sentinel.
+ */
+export declare function directoryDisplayName(profile: DeviceDirectoryProfile, locale?: string): string;
+/**
+ * A directory row's `@handle`, or `null` when the profile carries no usable
+ * username.
+ *
+ * The directory profile has no email — by design, it is the minimum that
+ * renders a row — so the handle is the secondary line, never a synthesized
+ * `username@oxy.so` address.
+ */
+export declare function directoryHandle(profile: DeviceDirectoryProfile): string | null;
+/**
+ * Whether a switcher may offer this row — the one question it asks, answered
+ * here so no surface has to re-derive it.
+ *
+ * It is deliberately a single field. `available` is the server's complete
+ * verdict (see {@link DeviceContextSubject.available}), and switchability is an
+ * authorization question the client must READ, never recompute; this exists to
+ * name the field that answers it, not to combine several.
+ *
+ * `onDevice` is NOT part of the question and composing the two is the mistake
+ * this function exists to prevent, in both directions. `onDevice: false` is an
+ * ordinary reachable context whose session is minted on first activation, so
+ * requiring it hides every organization the person has not used here yet.
+ * `onDevice: true` does not imply activatable either: when a principal's own
+ * personal session dies, their delegated contexts keep live sessions of their
+ * own and still cannot be activated, so `available || onDevice` would render a
+ * row the server answers with 403 and then heals away.
+ *
+ * Takes a structural subset so a caller holding a raw `DeviceAccountContext`
+ * from the wire can ask it without resolving the pair first.
+ */
+export declare function canActivateContext(context: {
+    available: boolean;
+}): boolean;

package/dist/types/session/deviceSwitcherRows.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The device switcher's RENDER model: the directory's people and contexts with
+ * their names, handles and avatar URLs already resolved.
+ *
+ * Pure. It takes the projection {@link projectDevicePrincipals} produces from
+ * the directory and answers the five questions a row asks —
+ * what is it called, what is its handle, where is its avatar, what accent is it
+ * drawn in, may it be activated — so the views stay presentational and neither
+ * of them re-derives a display rule.
+ *
+ * One thing the flat account rows this replaced carried is deliberately absent,
+ * because the directory does not carry it and inventing it would mean going back
+ * to fetching another person's profiles: **email**. The directory profile is the
+ * minimum that renders a row, so the secondary line is the `@handle` — never a
+ * synthesized `username@oxy.so`.
+ *
+ * The accent is NOT in that category. It was, briefly, and it was wrong: an
+ * accent is part of drawing the row rather than profile data about its owner,
+ * and without it every non-active row falls back to the ambient theme accent, so
+ * a device holding two people draws them identically (issue #961). The server
+ * carries it on the directory profile, so no client has to guess or fetch.
+ *
+ * It lives here rather than in a UI package because there is more than one
+ * switcher — the SDK's account dialog and the `auth.oxy.so` chooser — and the
+ * whole point of ADR 0002 is that they render ONE list, built once.
+ */
+import { type DevicePrincipalGroup } from './deviceDirectory';
+/** One `principal acting as account` row. */
+export interface SwitcherContextRow {
+    /**
+     * The id `activateContext` / `signOutContext` take. Names the PAIR.
+     *
+     * Not stable across a removal, so it is read out of the directory in hand on
+     * every render and never held across one.
+     */
+    contextId: string;
+    accountId: string;
+    displayName: string;
+    /** The `@handle` secondary line, or `null` when the profile has no username. */
+    handle: string | null;
+    avatarUrl: string | undefined;
+    /**
+     * The SUBJECT account's own accent — a named Bloom preset, or `null` when it
+     * has none and the renderer should use the ambient theme accent.
+     *
+     * Forwarded verbatim, never resolved to a colour here: mapping a preset name
+     * to a hex is Bloom's job, and `@oxyhq/core` cannot import a UI package.
+     */
+    color: string | null;
+    /** Whether this pair is the device's active context. */
+    isActive: boolean;
+    /** Whether the actor and the subject are different accounts. */
+    isDelegated: boolean;
+    /**
+     * Whether the row may be pressed — the server's `available`, read and never
+     * recomputed. Composing it with `onDevice` is wrong in both directions (see
+     * `canActivateContext`), so this is one field forwarded, not a derivation.
+     */
+    canActivate: boolean;
+}
+/** One person on this device, with the accounts they can act as beneath them. */
+export interface SwitcherPrincipalRow {
+    /** The id `signOutPrincipal` takes. */
+    principalId: string;
+    displayName: string;
+    handle: string | null;
+    avatarUrl: string | undefined;
+    /** The PERSON's own accent, on the same terms as a context row's. */
+    color: string | null;
+    /** Whether the device's ACTIVE context belongs to this person. */
+    isActive: boolean;
+    contexts: SwitcherContextRow[];
+}
+/** Resolves an avatar file id to a thumbnail URL. Bind to `getFileDownloadUrl`. */
+export type ResolveAvatarUrl = (avatar: string | null | undefined) => string | undefined;
+/** The directory's people and their contexts, ready to render. */
+export declare function buildSwitcherRows(groups: DevicePrincipalGroup[], activeContextId: string | null, resolveAvatarUrl: ResolveAvatarUrl, locale?: string): SwitcherPrincipalRow[];
+/**
+ * Whether the switcher should name the person above each block.
+ *
+ * The question a header answers is "who is operating this account", and that is
+ * only a question worth printing once somebody holds MORE THAN ONE account
+ * here. Two people with one personal account each is the flat list again — every
+ * row already IS a person, and a header would just print each name twice.
+ *
+ * The moment any one of them can act as a second account, every group gets a
+ * header, including the single-context ones: an inconsistent list is harder to
+ * read than a slightly redundant one, and it is exactly then that "The Oxy
+ * Collective, under Nate" and "The Oxy Collective, under Alice" become two
+ * different rows that must be told apart.
+ */
+export declare function showsPrincipalHeaders(rows: SwitcherPrincipalRow[]): boolean;

package/dist/types/session/projectSessionState.d.ts

@@ -1,6 +1,35 @@
 import type { DeviceSessionState } from '@oxyhq/contracts';
 import type { ClientSession } from '../models/session';
 import type { User } from '../models/interfaces';
+/**
+ * Pure projection helpers: `DeviceSessionState` (the device-scoped
+ * multi-account session-sync state produced by `SessionClient`) -> the
+ * shapes `@oxyhq/services` consumers render today
+ * (`ClientSession[]`, an active session id, an active `User`).
+ *
+ * No I/O. The caller fetches profiles via
+ * `oxyServices.getUsersByIds(accountIdsOf(state))` and builds `usersById`
+ * from the result before calling `deviceStateToClientSessions` /
+ * `activeUserOf`.
+ *
+ * Each projection takes an OPTIONAL `pinnedAccountId`. Omit it (or pass `null`)
+ * and the projection resolves the device's `activeAccountId` exactly as before.
+ * Pass it — an IDENTITY-BOUND client, whose user is fixed by the local identity
+ * key — and the projection resolves THAT account instead, so an account switch
+ * made by another app on the same device changes `state` but never the user this
+ * client renders.
+ */
+/**
+ * The account a projection should resolve: the pin when one is supplied and
+ * non-empty, else the device's active account. An empty-string pin is treated as
+ * "not pinned" rather than as an account that can never match.
+ *
+ * Exported so no other projection over the same state answers it a second,
+ * subtly different way. A null state with
+ * a pin still resolves to the pin: the pinned identity is bound by a local key,
+ * not by device membership.
+ */
+export declare function boundAccountIdOf(state: DeviceSessionState | null, pinnedAccountId?: string | null): string | null;
 /**
  * Maps every `SessionAccount` in `state.accounts` to a `ClientSession`.
  *