@flytedan/flytebot-design-system 0.14.0 → 0.16.0

package/dist/index.d.ts

@@ -2088,20 +2088,30 @@ declare const MarkdownEditor: React.ForwardRefExoticComponent<MarkdownEditorProp
 interface AccountMenuLink {
     id: string;
     label: string;
-    icon: string;
+    icon?: string;
     href?: string;
     /** Hidden unless the signed-in user holds this permission. */
     perm?: string;
     badge?: string;
     onSelect?: () => void;
 }
+/** A named, permission-filtered section of links rendered below the top-level (ungrouped)
+ *  `links` — e.g. "Administration", "Architecture", "Raw Data". A group is hidden entirely
+ *  once every one of its links is filtered out by `perm`. */
+interface AccountMenuGroup {
+    label: string;
+    links: AccountMenuLink[];
+}
 interface AccountMenuProps {
     links?: AccountMenuLink[];
-    /** Administration section. Each entry is filtered by its own `perm`. */
-    adminLinks?: AccountMenuLink[];
+    /** Named sections below `links`, e.g. Administration. Each entry is filtered by its own
+     *  `perm`; a group with no visible links renders nothing. */
+    groups?: AccountMenuGroup[];
     /** Preferred over href navigation — lets an SPA route without a page load. */
     onNavigate?: (href: string | undefined, item: AccountMenuLink) => void;
-    onSignOut?: () => void;
+    /** May return a Promise — the sign-out item shows a spinner and disables itself until it
+     *  settles, then closes the menu. Falls back to the injected session's own `signOut`. */
+    onSignOut?: () => void | Promise<void>;
     showRoles?: boolean;
     /** Demo affordance: impersonate another member to see their UI. Default true. */
     allowUserSwitch?: boolean;
@@ -2109,9 +2119,210 @@ interface AccountMenuProps {
 }
 /**
  * The avatar button + popover every flytedesk app puts in its top right.
- * Reads the signed-in user from SessionKit; shows Administration only to those who can use it.
+ * Reads the signed-in user from the nearest SessionProvider; shows each `groups` section
+ * only to those who can use at least one of its links.
  */
-declare function AccountMenu({ links, adminLinks, onNavigate, onSignOut, showRoles, allowUserSwitch, className, ...rest }: AccountMenuProps): React.JSX.Element;
+declare function AccountMenu({ links, groups, onNavigate, onSignOut, showRoles, allowUserSwitch, className, ...rest }: AccountMenuProps): React.JSX.Element;
+
+/** Whatever a session-aware component asks of the signed-in user, independent of any specific
+ *  identity provider. `kits/session.ts`'s own demo `User` extends this with fixture-only
+ *  bookkeeping (status, lastActive, …) that a real integration is never expected to supply. */
+interface SessionUser {
+    id: string;
+    name: string;
+    email: string;
+    title?: string;
+    team?: string;
+    phone?: string;
+    bio?: string;
+    timezone?: string;
+    /** Identity is managed by an SSO provider — ProfilePage disables the email field with a
+     *  different help string when true. */
+    sso?: boolean;
+    joined?: string;
+    notify?: Record<string, boolean>;
+    /** Display-only role names — used by the demo "View as another member" list. Not read
+     *  anywhere permissions are actually decided; `SessionContextValue.roles`/`can`/`hasRole`
+     *  are the source of truth for the SIGNED-IN user. */
+    roles?: string[];
+}
+interface SessionRole {
+    id: string;
+    name: string;
+}
+/** One flytedesk app the signed-in user can reach — the "All flytedesk apps" switcher's row
+ *  shape. The design system never fetches this list; it is supplied via `AppSwitcher`'s own
+ *  `apps` prop or via `SessionContextValue.apps`. */
+interface AppEntry {
+    key: string;
+    name: string;
+    url: string;
+    icon?: string;
+    /** True for the app the switcher itself is currently rendered inside. */
+    current?: boolean;
+}
+/** Demo-only affordance: impersonate another member to see their UI. Present ONLY on the demo
+ *  provider — a real, injected session must never populate this — so AccountMenu can key its
+ *  "View as another member" row on this field simply existing, rather than on a separate
+ *  boolean prop a real integration could forget to turn off. */
+interface DemoSessionControls {
+    allUsers: SessionUser[];
+    setActiveUser: (userId: string) => void;
+}
+interface SessionContextValue {
+    user: SessionUser;
+    /** The signed-in user's roles, for display (AccountMenu's/ProfilePage's role badges). */
+    roles: SessionRole[];
+    /** Every permission key the signed-in user holds. */
+    permissions: string[];
+    /** All of `permission` must be held. */
+    can: (permission: string | string[]) => boolean;
+    /** At least one of `permissions` must be held. */
+    canAny: (permissions: string[]) => boolean;
+    hasRole: (roleId: string) => boolean;
+    /** The app's real sign-out handler. AccountMenu's `onSignOut` prop, when supplied, still
+     *  wins over this — this is the fallback every app gets for free. May return a Promise —
+     *  AccountMenu shows a pending state on its sign-out item until it settles. */
+    signOut: () => void | Promise<void>;
+    /** Persists a profile edit. Omit on a session that does not support self-service profile
+     *  edits; ProfilePage then relies solely on its own `onSave` prop. */
+    saveProfile?: (patch: Partial<SessionUser>) => void | Promise<void>;
+    /** The flytedesk apps this user can reach, for `AppSwitcher`. Omit if the app instead
+     *  passes `AppSwitcher`'s own `apps` prop directly. */
+    apps?: AppEntry[];
+    demo?: DemoSessionControls;
+}
+interface SessionProviderProps {
+    value: SessionContextValue;
+    children?: React.ReactNode;
+}
+/** Mount once near the app root with the real, signed-in session. Every session-aware
+ *  component in this package reads from this provider and nothing else. */
+declare function SessionProvider({ value, children }: SessionProviderProps): React.FunctionComponentElement<React.ProviderProps<SessionContextValue | null>>;
+/** Reads the nearest `SessionProvider`. Throws when none is mounted — a session-aware
+ *  component with nothing to read from is a wiring bug to surface immediately, not a state to
+ *  silently render through. */
+declare function useSessionContext(): SessionContextValue;
+
+interface AppSwitcherProps {
+    /**
+     * The flytedesk apps this user can reach. Defaults to the injected session's own `apps`
+     * (`SessionContextValue.apps`) when omitted — this package never fetches the list itself;
+     * an app either passes it here or wires it into its `SessionProvider` value.
+     */
+    apps?: AppEntry[];
+    /** Preferred over `url` navigation — lets an SPA route without a page load. */
+    onNavigate?: (app: AppEntry) => void;
+    className?: string;
+}
+/**
+ * The "All flytedesk apps" switcher every flytedesk app puts in its topbar, beside
+ * `AccountMenu`: a grid-icon trigger anchoring a list of the apps the signed-in user can
+ * reach, the current app marked and not selectable. Reuses `Popover`/`Menu` — the same
+ * keyboard-complete, ARIA-correct list every other menu-shaped control in this package is
+ * built on — rather than a bespoke list, so Home/End/type-ahead/arrow-key behavior is
+ * identical everywhere.
+ *
+ * Renders nothing when there are no apps to switch to (an empty switcher is not a control,
+ * it's a dead button), so a Topbar can render it unconditionally.
+ */
+declare function AppSwitcher({ apps: appsProp, onNavigate, className }: AppSwitcherProps): React.JSX.Element | null;
+
+type ThemeMode = "light" | "dark" | "system";
+type TextScale = "sm" | "md" | "lg" | "xl";
+interface AppearancePrefs {
+    theme: ThemeMode;
+    textScale: TextScale;
+    highContrast: boolean;
+    /** Can only ever ADD reduced motion on top of the `prefers-reduced-motion` OS floor
+     *  tokens.css already respects — turning this off never re-enables motion the OS
+     *  itself asked to reduce. */
+    reduceMotion: boolean;
+}
+declare const DEFAULT_STORAGE_KEY = "fd-appearance";
+declare const DEFAULT_PREFS: AppearancePrefs;
+/** An app-supplied external store for `AppearancePrefs` — the same read/subscribe shape
+ *  `React.useSyncExternalStore` expects, plus a `write`. Implement this over whatever a
+ *  consuming app already has (a server-synced prefs cache, a Redux/Zustand store, …) to
+ *  drive `AppearanceMenu` from that state instead of the default localStorage store. */
+interface AppearanceStore {
+    /** Synchronous current value. Called on every render that might have changed it —
+     *  must be cheap and must not allocate a new object unless the value actually changed
+     *  (React compares by reference to decide whether to re-render). */
+    getSnapshot: () => AppearancePrefs;
+    /** Persist a full prefs object. `AppearanceMenu` always calls this with the complete,
+     *  merged record — never a partial patch — so a store never needs to merge itself. */
+    write: (prefs: AppearancePrefs) => void;
+    /** Register a callback fired whenever the snapshot changes for a reason other than this
+     *  store's own `write` call returning (e.g. another tab, or an app's async server
+     *  hydration completing after mount). Returns its own unsubscribe. */
+    subscribe: (onChange: () => void) => () => void;
+}
+interface AppearanceStoreOptions {
+    /** localStorage (or `storage`) key these prefs are read from / written to. Default
+     *  "fd-appearance". Namespace this per consuming app. */
+    storageKey?: string;
+    /** Swappable for tests or a non-browser environment. Default `window.localStorage`
+     *  (read lazily — safe to import this module where `window` doesn't exist yet). */
+    storage?: Pick<Storage, "getItem" | "setItem">;
+    /** Overrides the built-in defaults (`system` / `md` / off / off) per field. */
+    defaults?: Partial<AppearancePrefs>;
+}
+/** "system" resolved against the OS's current setting. Pure aside from reading
+ *  `matchMedia` — never throws in an environment without it (SSR, some test runners). */
+declare function resolveTheme(mode: ThemeMode): "light" | "dark";
+/** Reads stored prefs, falling back field-by-field to defaults — a missing key, a
+ *  malformed JSON blob, or a value of the wrong shape/type each fall back individually
+ *  rather than discarding the whole record (a bad stored value degrades, it never
+ *  crashes the caller). Used internally by `createLocalStorageAppearanceStore`; exported
+ *  as a low-level primitive for a caller building its own store on top of a similar
+ *  key/value backend. */
+declare function loadPrefs(opts?: AppearanceStoreOptions): AppearancePrefs;
+declare function savePrefs(prefs: AppearancePrefs, opts?: AppearanceStoreOptions): void;
+/** The default `AppearanceStore`: backed by `storage` (default `window.localStorage`)
+ *  under `storageKey` (default `"fd-appearance"`). Same-tab writes notify this store's
+ *  own subscribers synchronously; the browser's `storage` event keeps every OTHER tab
+ *  in sync too (a tab never gets its own `storage` event for its own write, which is
+ *  exactly why same-tab notification is handled separately here). The window listener is
+ *  attached only while at least one subscriber is registered, and removed once the last
+ *  one unsubscribes — a store an app creates per-mount never leaks a listener. */
+declare function createLocalStorageAppearanceStore(opts?: AppearanceStoreOptions): AppearanceStore;
+/** Sets every attribute this kit's tokens.css rules read: `[data-theme]` (resolved,
+ *  never "system" itself — nothing downstream re-resolves it), `[data-text-scale]`,
+ *  `[data-contrast="high"]` (present only when on — absent, not "normal", is the "off"
+ *  state so a plain `[data-contrast]` selector alone is meaningless) and
+ *  `[data-motion="reduce"]` (same absent-is-off shape). No inline styles: every visual
+ *  effect is a CSS rule in this package's own styles, driven by these attributes alone. */
+declare function applyPrefs(prefs: AppearancePrefs, root?: HTMLElement): void;
+/** [prefs, update] over an app-supplied `AppearanceStore`. Reads through
+ *  `React.useSyncExternalStore`, so a snapshot that changes for ANY reason — this hook's
+ *  own `update`, another tab, or an app's async server hydration landing after mount —
+ *  re-renders with the new value and re-applies it to the DOM. Any number of independent
+ *  instances may run at once as long as each is given its own store (or its own
+ *  `storageKey`, for the default store) — nothing here is a module-level singleton. */
+declare function useAppearancePrefs(store: AppearanceStore): [AppearancePrefs, (patch: Partial<AppearancePrefs>) => void];
+
+interface AppearanceMenuProps extends AppearanceStoreOptions {
+    /** An app-supplied external store (read/write/subscribe) — e.g. an adapter over a
+     *  server-synced prefs cache, so a value that arrives after mount still reaches this
+     *  menu and the DOM. Omit to get the default localStorage-backed store, configured by
+     *  `storageKey`/`storage`/`defaults`. */
+    store?: AppearanceStore;
+    className?: string;
+}
+/**
+ * The appearance popover every flytedesk app puts in its topbar: theme, text size, high
+ * contrast, and a reduced-motion override on top of the OS's own `prefers-reduced-
+ * motion`. Fits `Topbar`'s `actions`/`overflowActions` slot (see Topbar.tsx) the same
+ * way `AccountMenu` does — an `IconButton` trigger anchoring a `Popover`.
+ *
+ * Persistence is caller-configurable (`storageKey`/`storage`, see kits/appearance.ts) —
+ * pass a `storageKey` to namespace it per app; nothing here is a shared/global key.
+ * Every visual effect is a CSS rule in this package's own styles (tokens.css) driven by
+ * the `[data-theme]`/`[data-text-scale]`/`[data-contrast]`/`[data-motion]` attributes
+ * this component sets on `document.documentElement` — no inline styles, no app-side CSS.
+ */
+declare function AppearanceMenu({ className, store: storeProp, storageKey, storage, defaults }: AppearanceMenuProps): React.JSX.Element;
 
 interface EndpointSpec {
     id: string;
@@ -2158,202 +2369,42 @@ declare function Json({ obj }: {
 /** Drop-in browser for a simulated API contract. Takes the spec as data. */
 declare function ApiSpecBrowser({ spec, onRequest, modules, groups, title, kicker, lede, sourceNote, conventions, openQuestions, className, ...rest }: ApiSpecBrowserProps): React.JSX.Element;
 
-interface PermissionItem {
-    key: string;
-    label: string;
-    detail: string;
-}
-interface PermissionGroup {
-    group: string;
-    items: PermissionItem[];
-}
-interface Role {
-    id: string;
-    name: string;
-    system: boolean;
-    description: string;
-    permissions: string[];
-}
-interface Flag {
+type ProfileFieldType = "text" | "textarea" | "select" | "readonly";
+interface ProfileFieldDef {
+    /** Draft/patch key. Also the key `onSave`'s draft carries this value under. */
     key: string;
-    project: string;
     label: string;
-    description: string;
-    /** Kill switch. False means off for everyone, whatever the targeting says. */
-    enabled: boolean;
-    /** 0-100. Bucketed on a stable hash of the user id so answers never flicker. */
-    rollout: number;
-    /** Role ids the flag is forced on for. */
-    roles: string[];
-    /** Per-user overrides, highest precedence: { userId: true | false } */
-    users: Record<string, boolean>;
-    owner?: string;
-    updated?: string;
-    /** Which screen this flag gates, if any. */
-    screen?: string;
-    /** Target ship date for an unshipped feature. */
-    eta?: string | null;
-    /** Date this shipped — set instead of `eta` once it's done. */
-    shippedAt?: string;
-    /** Build phase index into PHASES. */
-    phase?: number;
-    /** Human estimate, e.g. "4 days". */
-    effort?: string;
-    /** What has to be built for this to be real. */
-    backend?: string;
-    /** Other flag keys this depends on. */
-    dependsOn?: string[];
-}
-interface User {
-    id: string;
-    name: string;
-    email: string;
-    title?: string;
-    team?: string;
-    roles: string[];
-    status: "active" | "invited" | "suspended";
-    lastActive?: string;
-    joined?: string;
-    sso?: boolean;
-    timezone?: string;
-    phone?: string;
-    bio?: string;
-    notify?: Record<string, boolean>;
-}
-interface Session {
-    user: User;
-    roles: Role[];
-    permissions: string[];
-    /** Resolved flag key → on/off for THIS user. */
-    flags: Record<string, boolean>;
-    allRoles: Role[];
-    allFlags: Flag[];
-    allUsers: User[];
-}
-interface FlagExplanation {
-    on: boolean;
-    reason: string;
-    detail: string;
-}
-/** roadmap()'s per-flag result row. Not declared in session.d.ts (roadmap() itself is one of
- *  the six SessionKit members missing from that file) — inferred from what roadmap() actually
- *  builds and returns for each flag. */
-interface RoadmapItem {
+    /** Default "text". "readonly" renders like "text" but is never editable, regardless
+     *  of any `onChange`. */
+    type?: ProfileFieldType;
+    /** Groups fields sharing the same value into one Card, titled by this group's name.
+     *  Default group: "Identity". Fields are rendered in the order their group first
+     *  appears, then in the order given within that group. */
+    group?: string;
+    /** Shown under the group's title — the first field in a group with one supplies it. */
+    groupDescription?: React.ReactNode;
+    placeholder?: string;
+    /** Static help text, or computed from the signed-in user (e.g. a different string for
+     *  an SSO- vs. password-managed account). */
+    help?: string | ((user: SessionUser) => string);
+    /** Required for `type: "select"`. */
+    options?: string[];
+    /** For `type: "textarea"`. Default 3. */
+    rows?: number;
+    /** Forces read-only regardless of `type`. */
+    readOnly?: boolean;
+    /** Computes this field's initial value from the signed-in user. Default: the user
+     *  property of the same name, coerced to a string (`String(user[key] ?? "")`) — set
+     *  this when the field's key doesn't match a `SessionUser` property, or needs
+     *  formatting. */
+    value?: (user: SessionUser) => string;
+}
+interface ProfileNotificationDef {
+    /** Draft key, read from/written into `notify: Record<string, boolean>`. */
     key: string;
     label: string;
-    project: string;
-    description: string;
-    backend?: string;
-    effort?: string;
-    owner?: string;
-    dependsOn: string[];
-    screen: string | null;
-    enabled: boolean;
-    /** Which build phase this sits in, and why that phase comes where it does. */
-    phase?: number;
-    phaseName: string;
-    phaseWhy: string | null;
-    phaseStart: string | null;
-    /** Derived, not stored: whether every endpoint the feature needs is wired. */
-    implemented: boolean;
-    date: string | null;
-    /** True when the only date on record is when the UI was designed, not when it ships. */
-    dateIsDesign: boolean;
-    status: "shipped" | "next" | "planned";
-}
-/** roadmap()'s return shape. */
-interface RoadmapResult {
-    items: RoadmapItem[];
-    /** Index of the first unshipped item — everything above it is history. */
-    nextIndex: number;
-    shipped: number;
-    remaining: number;
-}
-/** Stable 0–99 bucket from a string, so rollout answers never flicker between reloads. */
-declare function bucket(seed: string): number;
-/** Build the session document a real GET /me would return. */
-declare function buildSession(userId: string, overrides?: {
-    users?: User[];
-    roles?: Role[];
-    flags?: Flag[];
-}): Session;
-/** The precedence rule, in one place so the admin UI and the app can never disagree. */
-declare function evaluateFlag(flag: Flag, user: User): boolean;
-/** Why a flag resolved the way it did — shown in the admin UI, invaluable in support. */
-declare function explainFlag(flag: Flag, user: User): FlagExplanation;
-declare global {
-    interface Window {
-        /** Admin-app-injected overrides for the demo dataset, read by loadSession(). */
-        __FD_ADMIN_OVERRIDES?: {
-            users?: User[];
-            roles?: Role[];
-            flags?: Flag[];
-        };
-    }
+    description?: string;
 }
-/** Replace this with `fetch(API + "/me")` to go live. */
-declare function loadSession(userId?: string): Session;
-declare function getSession(): Session;
-declare function setActiveUser(userId: string): Session;
-/** Local profile edits persist so the demo keeps them across reloads. */
-declare function saveProfile(patch: Partial<User>): User;
-/** Recompute after the admin app mutates users/roles/flags. */
-declare function refresh(): Session;
-declare function subscribe(fn: (s: Session) => void): () => void;
-declare function can(permission: string | string[]): boolean;
-declare function canAny(permissions: string[]): boolean;
-declare function hasRole(roleId: string): boolean;
-declare function flagOn(key: string): boolean;
-/** The flag registry entry, whatever the session shape.
- *  Not declared in session.d.ts — see the module doc comment on SessionKit below. */
-declare function findFlag(key: string): Flag | null;
-declare function flagState(key: string): "on" | "off";
-declare function isEnabled(key: string): boolean;
-declare function flagVisible(key: string): boolean;
-declare function flagLive(key: string): boolean;
-declare function roadmap(overrides?: {
-    flags?: Flag[];
-    isComplete?: (key: string) => boolean;
-}): RoadmapResult;
-/** React binding. Re-renders on user switch, profile save, or admin mutation. */
-declare function useSession(): Session;
-/**
- * Session, RBAC and feature flags for every flytedesk app.
- *
- * Not a security boundary: permissions gate the UI so people aren't shown affordances they
- * cannot use. The server must re-check all of it.
- *
- * To go live, replace loadSession() with a fetch of GET /me → { user, roles, permissions, flags }.
- */
-declare const SessionKit: {
-    PERMISSION_CATALOG: PermissionGroup[];
-    ALL_PERMISSIONS: string[];
-    ROLES: Role[];
-    FLAGS: Flag[];
-    USERS: User[];
-    loadSession: typeof loadSession;
-    getSession: typeof getSession;
-    setActiveUser: typeof setActiveUser;
-    saveProfile: typeof saveProfile;
-    refresh: typeof refresh;
-    subscribe: typeof subscribe;
-    can: typeof can;
-    canAny: typeof canAny;
-    hasRole: typeof hasRole;
-    flagOn: typeof flagOn;
-    useSession: typeof useSession;
-    findFlag: typeof findFlag;
-    flagState: typeof flagState;
-    isEnabled: typeof isEnabled;
-    flagVisible: typeof flagVisible;
-    flagLive: typeof flagLive;
-    roadmap: typeof roadmap;
-    evaluateFlag: typeof evaluateFlag;
-    explainFlag: typeof explainFlag;
-    bucket: typeof bucket;
-    buildSession: typeof buildSession;
-};
-
 interface DeviceSession {
     id: string;
     device: string;
@@ -2362,20 +2413,40 @@ interface DeviceSession {
     current?: boolean;
 }
 interface ProfilePageProps {
-    /** Defaults to the signed-in user from SessionKit. */
-    user?: User;
-    /** Persist through your own endpoint. Defaults to SessionKit.saveProfile. */
-    onSave?: (draft: Partial<User>) => void | Promise<void>;
+    /** Defaults to the signed-in user from the injected session. */
+    user?: SessionUser;
+    /** The editable fields this app's profile has. Omit (or pass none) and no field cards
+     *  render at all — only the avatar header and the Access card remain. */
+    fields?: ProfileFieldDef[];
+    /** The notification toggles this app has. Omit and the Notifications card doesn't
+     *  render. */
+    notifications?: ProfileNotificationDef[];
+    /** Rendered after the field cards and before Notifications — for app-specific content
+     *  that isn't a plain field, e.g. a link out to another app's own profile page for
+     *  fields that live there instead. */
+    extra?: React.ReactNode;
+    /** Renders the "Change photo" button when supplied; omitted entirely otherwise. */
+    onChangePhoto?: () => void;
+    /** Persist edited fields/notifications through your own endpoint. Defaults to the
+     *  injected session's `saveProfile` (the demo provider wires this to
+     *  SessionKit.saveProfile); if neither is available, Save is disabled. Receives every
+     *  field's current value under its `key`, plus `notify` when `notifications` is set. */
+    onSave?: (draft: Record<string, string> & {
+        notify?: Record<string, boolean>;
+    }) => void | Promise<void>;
     onNavigate?: (href: string) => void;
+    /** Renders the "Signed-in devices" card when supplied (an empty array still renders
+     *  the card, showing none); omitted entirely otherwise — no fabricated device list. */
     sessions?: DeviceSession[];
-    showSessions?: boolean;
+    onSignOutEverywhere?: () => void | Promise<void>;
     className?: string;
 }
 /**
- * The shared profile page: identity, working preferences, notifications, devices.
- * Roles are shown but never editable — self-promotion is the reason RBAC exists.
+ * The shared profile page: identity, working preferences, notifications, devices — all
+ * driven entirely by the `fields`/`notifications`/`sessions` this app supplies. Roles are
+ * shown but never editable — self-promotion is the reason RBAC exists.
  */
-declare function ProfilePage({ user: userProp, onSave, onNavigate, sessions, showSessions, className, ...rest }: ProfilePageProps): React.JSX.Element;
+declare function ProfilePage({ user: userProp, fields, notifications, extra, onChangePhoto, onSave, onNavigate, sessions, onSignOutEverywhere, className, }: ProfilePageProps): React.JSX.Element;
 
 interface RoadmapTimelineProps {
     /** Called with a flag key when the reader clicks one — route it to your flag admin. */
@@ -2419,7 +2490,9 @@ interface GateProps {
     compact?: boolean;
     children?: React.ReactNode;
 }
-/** Permission gate. Denied by default shows PermissionDenied. */
+/** Permission gate. Denied by default shows PermissionDenied. Reads the injected session
+ *  (see kits/sessionContext.tsx) — re-renders whenever that context's value changes, so no
+ *  separate subscription is needed here. */
 declare function Gate({ perm, anyOf, role, silent, fallback, compact, children }: GateProps): React.ReactNode;
 interface FeatureGateProps {
     flag: string;
@@ -3497,6 +3570,207 @@ interface FileBrowserProps {
  */
 declare function FileBrowser({ folders, files, currentFolderId, onNavigate, onCreateFolder, onRenameFolder, onMoveFolder, onMoveFile, onOpenFile, onRemoveFile, onDeleteFolder, onUpload, loading, permissions, className, }: FileBrowserProps): React.JSX.Element;
 
+interface PermissionItem {
+    key: string;
+    label: string;
+    detail: string;
+}
+interface PermissionGroup {
+    group: string;
+    items: PermissionItem[];
+}
+interface Role {
+    id: string;
+    name: string;
+    system: boolean;
+    description: string;
+    permissions: string[];
+}
+interface Flag {
+    key: string;
+    project: string;
+    label: string;
+    description: string;
+    /** Kill switch. False means off for everyone, whatever the targeting says. */
+    enabled: boolean;
+    /** 0-100. Bucketed on a stable hash of the user id so answers never flicker. */
+    rollout: number;
+    /** Role ids the flag is forced on for. */
+    roles: string[];
+    /** Per-user overrides, highest precedence: { userId: true | false } */
+    users: Record<string, boolean>;
+    owner?: string;
+    updated?: string;
+    /** Which screen this flag gates, if any. */
+    screen?: string;
+    /** Target ship date for an unshipped feature. */
+    eta?: string | null;
+    /** Date this shipped — set instead of `eta` once it's done. */
+    shippedAt?: string;
+    /** Build phase index into PHASES. */
+    phase?: number;
+    /** Human estimate, e.g. "4 days". */
+    effort?: string;
+    /** What has to be built for this to be real. */
+    backend?: string;
+    /** Other flag keys this depends on. */
+    dependsOn?: string[];
+}
+/** The demo fixture's user record. Extends the provider-agnostic `SessionUser` (see
+ *  `kits/sessionContext.tsx`) with bookkeeping fields only this in-memory fixture needs — a
+ *  real, injected session is never expected to supply `status`/`lastActive`. */
+interface User extends SessionUser {
+    roles: string[];
+    status: "active" | "invited" | "suspended";
+    lastActive?: string;
+}
+interface Session {
+    user: User;
+    roles: Role[];
+    permissions: string[];
+    /** Resolved flag key → on/off for THIS user. */
+    flags: Record<string, boolean>;
+    allRoles: Role[];
+    allFlags: Flag[];
+    allUsers: User[];
+}
+interface FlagExplanation {
+    on: boolean;
+    reason: string;
+    detail: string;
+}
+/** roadmap()'s per-flag result row. Not declared in session.d.ts (roadmap() itself is one of
+ *  the six SessionKit members missing from that file) — inferred from what roadmap() actually
+ *  builds and returns for each flag. */
+interface RoadmapItem {
+    key: string;
+    label: string;
+    project: string;
+    description: string;
+    backend?: string;
+    effort?: string;
+    owner?: string;
+    dependsOn: string[];
+    screen: string | null;
+    enabled: boolean;
+    /** Which build phase this sits in, and why that phase comes where it does. */
+    phase?: number;
+    phaseName: string;
+    phaseWhy: string | null;
+    phaseStart: string | null;
+    /** Derived, not stored: whether every endpoint the feature needs is wired. */
+    implemented: boolean;
+    date: string | null;
+    /** True when the only date on record is when the UI was designed, not when it ships. */
+    dateIsDesign: boolean;
+    status: "shipped" | "next" | "planned";
+}
+/** roadmap()'s return shape. */
+interface RoadmapResult {
+    items: RoadmapItem[];
+    /** Index of the first unshipped item — everything above it is history. */
+    nextIndex: number;
+    shipped: number;
+    remaining: number;
+}
+/** Stable 0–99 bucket from a string, so rollout answers never flicker between reloads. */
+declare function bucket(seed: string): number;
+/** Build the session document a real GET /me would return. */
+declare function buildSession(userId: string, overrides?: {
+    users?: User[];
+    roles?: Role[];
+    flags?: Flag[];
+}): Session;
+/** The precedence rule, in one place so the admin UI and the app can never disagree. */
+declare function evaluateFlag(flag: Flag, user: User): boolean;
+/** Why a flag resolved the way it did — shown in the admin UI, invaluable in support. */
+declare function explainFlag(flag: Flag, user: User): FlagExplanation;
+declare global {
+    interface Window {
+        /** Admin-app-injected overrides for the demo dataset, read by loadSession(). */
+        __FD_ADMIN_OVERRIDES?: {
+            users?: User[];
+            roles?: Role[];
+            flags?: Flag[];
+        };
+    }
+}
+/** Replace this with `fetch(API + "/me")` to go live. */
+declare function loadSession(userId?: string): Session;
+declare function getSession(): Session;
+declare function setActiveUser(userId: string): Session;
+/** Local profile edits persist so the demo keeps them across reloads. */
+declare function saveProfile(patch: Partial<User>): User;
+/** Recompute after the admin app mutates users/roles/flags. */
+declare function refresh(): Session;
+declare function subscribe(fn: (s: Session) => void): () => void;
+declare function can(permission: string | string[]): boolean;
+declare function canAny(permissions: string[]): boolean;
+declare function hasRole(roleId: string): boolean;
+declare function flagOn(key: string): boolean;
+/** The flag registry entry, whatever the session shape.
+ *  Not declared in session.d.ts — see the module doc comment on SessionKit below. */
+declare function findFlag(key: string): Flag | null;
+declare function flagState(key: string): "on" | "off";
+declare function isEnabled(key: string): boolean;
+declare function flagVisible(key: string): boolean;
+declare function flagLive(key: string): boolean;
+declare function roadmap(overrides?: {
+    flags?: Flag[];
+    isComplete?: (key: string) => boolean;
+}): RoadmapResult;
+/** React binding. Re-renders on user switch, profile save, or admin mutation. */
+declare function useSession(): Session;
+/**
+ * Session, RBAC and feature flags for every flytedesk app.
+ *
+ * Not a security boundary: permissions gate the UI so people aren't shown affordances they
+ * cannot use. The server must re-check all of it.
+ *
+ * To go live, replace loadSession() with a fetch of GET /me → { user, roles, permissions, flags }.
+ */
+declare const SessionKit: {
+    PERMISSION_CATALOG: PermissionGroup[];
+    ALL_PERMISSIONS: string[];
+    ROLES: Role[];
+    FLAGS: Flag[];
+    USERS: User[];
+    loadSession: typeof loadSession;
+    getSession: typeof getSession;
+    setActiveUser: typeof setActiveUser;
+    saveProfile: typeof saveProfile;
+    refresh: typeof refresh;
+    subscribe: typeof subscribe;
+    can: typeof can;
+    canAny: typeof canAny;
+    hasRole: typeof hasRole;
+    flagOn: typeof flagOn;
+    useSession: typeof useSession;
+    findFlag: typeof findFlag;
+    flagState: typeof flagState;
+    isEnabled: typeof isEnabled;
+    flagVisible: typeof flagVisible;
+    flagLive: typeof flagLive;
+    roadmap: typeof roadmap;
+    evaluateFlag: typeof evaluateFlag;
+    explainFlag: typeof explainFlag;
+    bucket: typeof bucket;
+    buildSession: typeof buildSession;
+};
+/**
+ * Mounts the built-in fixture `SessionKit` behind the same `SessionProvider` contract every
+ * session-aware component reads (see `kits/sessionContext.tsx`). This is the ONLY place the
+ * demo fixture is wired to that contract — AccountMenu/Gate/ProfilePage/AppSwitcher never
+ * import `SessionKit` directly, so a real app supplying its own `<SessionProvider value={...}>`
+ * gets identical behavior with no demo-only code path left running underneath it.
+ *
+ * `demo` is populated on the resulting context value, which is what lets AccountMenu show
+ * "View as another member" here and nowhere else: a real session simply never sets it.
+ */
+declare function DemoSessionProvider({ children }: {
+    children?: React.ReactNode;
+}): React.FunctionComponentElement<SessionProviderProps>;
+
 interface TableQuery {
     /** 1-indexed. */
     page: number;
@@ -3769,4 +4043,4 @@ interface VersionStore<TState, TDiff = unknown> {
 }
 declare function createVersionStore<TState, TDiff = unknown>(initialState: TState, options?: CreateVersionStoreOptions<TState, TDiff>): VersionStore<TState, TDiff>;
 
-export { AccountMenu, type AccountMenuLink, type AccountMenuProps, AgentChatPanel, type AgentChatPanelProps, ApiSpecBrowser, type ApiSpecBrowserProps, type Attachment, Avatar, type AvatarProps, AvatarStack, type AvatarStackProps, Badge, type BadgeProps, BudgetReallocator, type BudgetReallocatorProps, Button, type ButtonProps, CHANNELS, CHANNEL_WEIGHTS, CHAT_UNAVAILABLE, Calendar, type CalendarProps, Card, type CardProps, CardRow, type CardRowProps, ChannelContribution, type ChannelContributionChannel, type ChannelContributionProps, ChannelMeta, type ChannelMetaRecord, ChannelTag, type ChannelTagProps, ChannelWeightOf, type ChatAdapter, ChatComposer, type ChatComposerProps, type ChatEngine, type ChatEngineOptions, ChatKit, type ChatMessage, type ChatRenderContext, ChatSessionBar, type ChatSessionBarProps, ChatTranscript, type ChatTranscriptProps, ChatTurn, type ChatTurnProps, Checkbox, type CheckboxProps, type Citation, Citations, type CitationsProps, Clamp, type ClampProps, ClockFace, type ClockFaceProps, CodeBlock, type CodeBlockProps, Collapsible, type CollapsibleProps, ComingSoon, type ComingSoonProps, type ContextUsage, type CreateVersionStoreOptions, CsiBadge, type CsiBadgeProps, CsiHero, type CsiHeroProps, CsiMeter, type CsiMeterProps, DataTable, type DataTableColumn, type DataTableProps, DatePicker, type DatePickerProps, type DeviceSession, DiffBlock, type DiffBlockProps, Drawer, type DrawerProps, Dropzone, DropzoneKit, type DropzoneProps, ENTITY_ROW_METRIC_WIDTH, type EditorTrigger, EmptyState, type EmptyStateProps, type EndpointSpec, EntityRow, type EntityRowAction, type EntityRowContent, type EntityRowMetric, EntityRowMetrics, type EntityRowMetricsProps, type EntityRowProps, FILE_VIEWER_CSV_ROW_LIMIT, FILE_VIEWER_TEXT_LIMIT, FeatureGate, type FeatureGateProps, type FeatureStatus, FileBrowser, type FileBrowserFile, type FileBrowserFolder, type FileBrowserPermissions, type FileBrowserProps, FileChip, type FileChipProps, FileGrid, type FileGridProps, FileKit, FilePickButton, type FilePickButtonProps, type FileRejection, FileStrip, type FileStripProps, FileTile, type FileTileProps, type FileUploadHandler, FileViewer, type FileViewerProps, FilterBar, type FilterBarProps, type FilterField, type FilterFieldOption, type FilterFieldSelect, type FilterFieldText, Flag$1 as Flag, type FlagExplanation, type FlagProps, FlytedeskBrand, type FlytedeskBrandProps, FlytedeskMark, type FlytedeskMarkProps, FormatEta, Gate, type GateProps, IMPORTANCE_LEVELS, IconButton, type IconButtonProps, type ImportanceLevel, type ImportanceLevelId, ImportanceTag, type ImportanceTagProps, type ImportanceTokens, Input, type InputProps, type JobStatus, Json, KeyHint, type KeyHintProps, type ListEnvelope, LoadingRegion, type LoadingRegionProps, Markdown, MarkdownEditor, type MarkdownEditorHandle, type MarkdownEditorProps, MarkdownInline, type MarkdownProps, type MentionSource, Menu, MenuButton, type MenuButtonProps, type MenuItem, type MenuProps, MessageBody, type MessageBodyProps, type MessageGroup, Meter, type MeterProps, type MeterSegment, type MeterSegmentInput, MixGap, type MixGapProps, type MixGapRow, MockJobKit, type MockJobStatus, Modal, type ModalProps, ModeSwitch, type ModeSwitchProps, type Model, ModelControls, type ModelControlsProps, NumberInput, type NumberInputProps, POPOVER_BODY_MIN, type Packet, PacketCard, type PacketCardProps, type PacketSchema, type Pager, Pagination, type PaginationProps, PermissionDenied, type PermissionDeniedProps, type PermissionGroup, PermissionHint, type PermissionItem, type Placement, type PollOptions, Popover, type PopoverProps, type PreferenceCriterion, PreferenceMeter, type PreferenceMeterProps, ProfilePage, type ProfilePageProps, ProgressBar, type ProgressBarProps, QueryKit, type QueuedTurn, QuotaRow, type QuotaRowProps, Radio, type RadioProps, RangeSlider, type RangeSliderProps, RelativeTime, type RelativeTimeProps, type RoadmapItem, type RoadmapResult, RoadmapTimeline, type RoadmapTimelineProps, type Role, RunActions, type RunActionsProps, type RunConfig, RuntimeKit, type RuntimeSummary, SaturationDistribution, type SaturationDistributionCampus, type SaturationDistributionProps, ScoreMeter, type ScoreMeterProps, SearchField, type SearchFieldProps, SegmentedControl, type SegmentedControlProps, SegmentedMeter, type SegmentedMeterProps, Select, type SelectOption, type SelectProps, type SendMessageResult, type ServerTable, type Session, type Flag as SessionFlag, SessionKit, type SessionStats, SidebarNav, type SidebarNavItem, type SidebarNavProps, Skeleton, type SkeletonProps, SkeletonText, type SkeletonTextProps, type SlashCommand, Slider, type SliderProps, SortMenu, type SortMenuField, type SortMenuProps, type SpecModule, Spinner, type SpinnerProps, StatTile, type StatTileProps, type Step, StepList, type StepListProps, type StreamHandlers, type Suggestion, SurroundSound, type SurroundSoundProps, Switch, type SwitchProps, type TableQuery, Tabs, type TabsProps, Tag, type TagProps, TestModeBar, type TestModeBarProps, Textarea, type TextareaProps, ThinkingBlock, type ThinkingBlockProps, type ThreadSummary, TimePicker, type TimePickerProps, Toast, type ToastProps, Tooltip, type TooltipProps, Topbar, type TopbarProps, TranscriptKit, TransferList, type TransferListProps, type TransferListSide, type TransferListSideProps, type UsageLimit, UseFeatureStatus, UseRuntimeMode, type UseServerTableOptions, type User, VIRTUAL_LIST_BUFFER_ROWS, VIRTUAL_LIST_ROW_GAP, type VersionRecord, type VersionStore, VirtualList, type VirtualListProps, type VirtualLoadedBand, type VirtualWindow, type VoiceHandler, acceptMatches, anyOfFilter, channelWeightOf, computeNeedMore, computeVirtualWindow, createVersionStore, eqFilter, extensionOf, extractClipboardFiles, filterFiles, formatAbsolute, formatBytes, formatClock, formatDuration, formatEta, formatRelative, groupMessages, hasModifier, iconForMime, importanceLevel, importanceTokens, isImage, isSystemMessage, jobBucket, languageLabel, markdownToText, meterFormats, modifierLabel, parseDelimited, pastedTextName, pluralizeUnit, preferenceScore, preferenceSegments, rangeFilter, revokeAttachment, toAttachment, tokenize, useChatEngine, useFeatureStatus, usePopoverPosition, useRuntimeMode, useServerTable, useStagedFiles, visibleMessages };
+export { AccountMenu, type AccountMenuLink, type AccountMenuProps, AgentChatPanel, type AgentChatPanelProps, ApiSpecBrowser, type ApiSpecBrowserProps, type AppEntry, AppSwitcher, type AppSwitcherProps, AppearanceMenu, type AppearanceMenuProps, type AppearancePrefs, type AppearanceStore, type AppearanceStoreOptions, type Attachment, Avatar, type AvatarProps, AvatarStack, type AvatarStackProps, Badge, type BadgeProps, BudgetReallocator, type BudgetReallocatorProps, Button, type ButtonProps, CHANNELS, CHANNEL_WEIGHTS, CHAT_UNAVAILABLE, Calendar, type CalendarProps, Card, type CardProps, CardRow, type CardRowProps, ChannelContribution, type ChannelContributionChannel, type ChannelContributionProps, ChannelMeta, type ChannelMetaRecord, ChannelTag, type ChannelTagProps, ChannelWeightOf, type ChatAdapter, ChatComposer, type ChatComposerProps, type ChatEngine, type ChatEngineOptions, ChatKit, type ChatMessage, type ChatRenderContext, ChatSessionBar, type ChatSessionBarProps, ChatTranscript, type ChatTranscriptProps, ChatTurn, type ChatTurnProps, Checkbox, type CheckboxProps, type Citation, Citations, type CitationsProps, Clamp, type ClampProps, ClockFace, type ClockFaceProps, CodeBlock, type CodeBlockProps, Collapsible, type CollapsibleProps, ComingSoon, type ComingSoonProps, type ContextUsage, type CreateVersionStoreOptions, CsiBadge, type CsiBadgeProps, CsiHero, type CsiHeroProps, CsiMeter, type CsiMeterProps, DEFAULT_PREFS, DEFAULT_STORAGE_KEY, DataTable, type DataTableColumn, type DataTableProps, DatePicker, type DatePickerProps, type DemoSessionControls, DemoSessionProvider, type DeviceSession, DiffBlock, type DiffBlockProps, Drawer, type DrawerProps, Dropzone, DropzoneKit, type DropzoneProps, ENTITY_ROW_METRIC_WIDTH, type EditorTrigger, EmptyState, type EmptyStateProps, type EndpointSpec, EntityRow, type EntityRowAction, type EntityRowContent, type EntityRowMetric, EntityRowMetrics, type EntityRowMetricsProps, type EntityRowProps, FILE_VIEWER_CSV_ROW_LIMIT, FILE_VIEWER_TEXT_LIMIT, FeatureGate, type FeatureGateProps, type FeatureStatus, FileBrowser, type FileBrowserFile, type FileBrowserFolder, type FileBrowserPermissions, type FileBrowserProps, FileChip, type FileChipProps, FileGrid, type FileGridProps, FileKit, FilePickButton, type FilePickButtonProps, type FileRejection, FileStrip, type FileStripProps, FileTile, type FileTileProps, type FileUploadHandler, FileViewer, type FileViewerProps, FilterBar, type FilterBarProps, type FilterField, type FilterFieldOption, type FilterFieldSelect, type FilterFieldText, Flag$1 as Flag, type FlagExplanation, type FlagProps, FlytedeskBrand, type FlytedeskBrandProps, FlytedeskMark, type FlytedeskMarkProps, FormatEta, Gate, type GateProps, IMPORTANCE_LEVELS, IconButton, type IconButtonProps, type ImportanceLevel, type ImportanceLevelId, ImportanceTag, type ImportanceTagProps, type ImportanceTokens, Input, type InputProps, type JobStatus, Json, KeyHint, type KeyHintProps, type ListEnvelope, LoadingRegion, type LoadingRegionProps, Markdown, MarkdownEditor, type MarkdownEditorHandle, type MarkdownEditorProps, MarkdownInline, type MarkdownProps, type MentionSource, Menu, MenuButton, type MenuButtonProps, type MenuItem, type MenuProps, MessageBody, type MessageBodyProps, type MessageGroup, Meter, type MeterProps, type MeterSegment, type MeterSegmentInput, MixGap, type MixGapProps, type MixGapRow, MockJobKit, type MockJobStatus, Modal, type ModalProps, ModeSwitch, type ModeSwitchProps, type Model, ModelControls, type ModelControlsProps, NumberInput, type NumberInputProps, POPOVER_BODY_MIN, type Packet, PacketCard, type PacketCardProps, type PacketSchema, type Pager, Pagination, type PaginationProps, PermissionDenied, type PermissionDeniedProps, type PermissionGroup, PermissionHint, type PermissionItem, type Placement, type PollOptions, Popover, type PopoverProps, type PreferenceCriterion, PreferenceMeter, type PreferenceMeterProps, type ProfileFieldDef, type ProfileFieldType, type ProfileNotificationDef, ProfilePage, type ProfilePageProps, ProgressBar, type ProgressBarProps, QueryKit, type QueuedTurn, QuotaRow, type QuotaRowProps, Radio, type RadioProps, RangeSlider, type RangeSliderProps, RelativeTime, type RelativeTimeProps, type RoadmapItem, type RoadmapResult, RoadmapTimeline, type RoadmapTimelineProps, type Role, RunActions, type RunActionsProps, type RunConfig, RuntimeKit, type RuntimeSummary, SaturationDistribution, type SaturationDistributionCampus, type SaturationDistributionProps, ScoreMeter, type ScoreMeterProps, SearchField, type SearchFieldProps, SegmentedControl, type SegmentedControlProps, SegmentedMeter, type SegmentedMeterProps, Select, type SelectOption, type SelectProps, type SendMessageResult, type ServerTable, type Session, type SessionContextValue, type Flag as SessionFlag, SessionKit, SessionProvider, type SessionProviderProps, type SessionRole, type SessionStats, type SessionUser, SidebarNav, type SidebarNavItem, type SidebarNavProps, Skeleton, type SkeletonProps, SkeletonText, type SkeletonTextProps, type SlashCommand, Slider, type SliderProps, SortMenu, type SortMenuField, type SortMenuProps, type SpecModule, Spinner, type SpinnerProps, StatTile, type StatTileProps, type Step, StepList, type StepListProps, type StreamHandlers, type Suggestion, SurroundSound, type SurroundSoundProps, Switch, type SwitchProps, type TableQuery, Tabs, type TabsProps, Tag, type TagProps, TestModeBar, type TestModeBarProps, type TextScale, Textarea, type TextareaProps, type ThemeMode, ThinkingBlock, type ThinkingBlockProps, type ThreadSummary, TimePicker, type TimePickerProps, Toast, type ToastProps, Tooltip, type TooltipProps, Topbar, type TopbarProps, TranscriptKit, TransferList, type TransferListProps, type TransferListSide, type TransferListSideProps, type UsageLimit, UseFeatureStatus, UseRuntimeMode, type UseServerTableOptions, type User, VIRTUAL_LIST_BUFFER_ROWS, VIRTUAL_LIST_ROW_GAP, type VersionRecord, type VersionStore, VirtualList, type VirtualListProps, type VirtualLoadedBand, type VirtualWindow, type VoiceHandler, acceptMatches, anyOfFilter, applyPrefs, channelWeightOf, computeNeedMore, computeVirtualWindow, createLocalStorageAppearanceStore, createVersionStore, eqFilter, extensionOf, extractClipboardFiles, filterFiles, formatAbsolute, formatBytes, formatClock, formatDuration, formatEta, formatRelative, groupMessages, hasModifier, iconForMime, importanceLevel, importanceTokens, isImage, isSystemMessage, jobBucket, languageLabel, loadPrefs, markdownToText, meterFormats, modifierLabel, parseDelimited, pastedTextName, pluralizeUnit, preferenceScore, preferenceSegments, rangeFilter, resolveTheme, revokeAttachment, savePrefs, toAttachment, tokenize, useAppearancePrefs, useChatEngine, useFeatureStatus, usePopoverPosition, useRuntimeMode, useServerTable, useSessionContext, useStagedFiles, visibleMessages };