@flow-industries/id 0.21.1 → 0.22.0

package/dist/sdk/client/create-flow.js

@@ -13,11 +13,8 @@ import { createStore, initialFlowState } from "./store";
  * see the result instead of racing it. Falls back to running `fn` directly
  * where Web Locks is unavailable.
  */
-function withOriginLock(name, fn) {
-    const locks = 
-    /* SAFETY: the SDK stashes its singleton on globalThis so two bundles of it share one
-     instance; the property is namespaced and written only here. */
-    globalThis.navigator?.locks;
+async function withOriginLock(name, fn) {
+    const locks = globalThis.navigator?.locks;
     if (locks?.request)
         return locks.request(name, fn);
     return fn();
@@ -362,6 +359,7 @@ export function createFlow(options = {}) {
      */
     async function login(loginOpts = {}) {
         const dialogHost = getDialog();
+        dialogHost.captureFocus();
         let accessKeyModule;
         let accessKeyPrep;
         let extraCapabilities;

package/dist/sdk/client/dialog-host.js

@@ -1,4 +1,5 @@
 import { bridgeToWindow, makeIframe } from "./iframe-host";
+import { setOverlayFocus } from "./overlay-focus";
 const HIDDEN_STYLE = {
     position: "fixed",
     inset: "0",
@@ -35,6 +36,12 @@ export function createDialogHost(options) {
     const { host, container = document.body } = options;
     let iframe = null;
     let messenger = null;
+    let opener = null;
+    function captureFocus() {
+        const active = document.activeElement;
+        if (active instanceof HTMLElement && active !== iframe)
+            opener = active;
+    }
     const pending = new Map();
     /**
      * Mounts the iframe and wires up the postMessage bridge. Idempotent — safe
@@ -43,8 +50,9 @@ export function createDialogHost(options) {
     function ensureFrame() {
         if (iframe)
             return;
-        iframe = makeIframe(`${host}`);
+        iframe = makeIframe(`${host}`, "Flow ID");
         iframe.dataset.flowId = "";
+        iframe.inert = true;
         Object.assign(iframe.style, HIDDEN_STYLE);
         container.appendChild(iframe);
         // Bind the bridge to this iframe's own window — a page may host more than
@@ -109,6 +117,8 @@ export function createDialogHost(options) {
         if (!iframe)
             return;
         Object.assign(iframe.style, VISIBLE_STYLE);
+        setOverlayFocus(iframe, true, opener);
+        opener = null;
         // The dialog owns its open/close animation and mounts the overlay (playing
         // the enter animation) on this signal — same mechanism as the profile
         // widget, so every dialog appears and disappears identically.
@@ -124,6 +134,7 @@ export function createDialogHost(options) {
         // requestAnimationFrame, making the close (and the next open) skip straight
         // to the end. While hidden the overlay is transparent and click-through.
         iframe.style.pointerEvents = "none";
+        setOverlayFocus(iframe, false);
         void (
         // SAFETY: the payload map types this topic; the dialog reads exactly these fields.
         messenger?.send("__internal", { type: "dialog-hidden" }));
@@ -190,6 +201,7 @@ export function createDialogHost(options) {
         return dispatchRequest(method, params);
     }
     return {
+        captureFocus,
         open,
         close,
         destroy,

package/dist/sdk/client/flow-widget.js

@@ -11,6 +11,11 @@ const WIDGET_ROUTE = {
     xp: "/dialog/xp-widget",
     "action-timer": "/dialog/action-timer",
 };
+// `satisfies` the full widget union so a new widget cannot ship untitled.
+const WIDGET_TITLE = {
+    xp: "Flow ID XP",
+    "action-timer": "Flow ID action timer",
+};
 /**
  * Mounts one of the inline Flow ID widgets — the XP strip, the action timer —
  * as a transparent iframe the embedder positions and sizes itself.
@@ -42,7 +47,7 @@ export function createFlowWidget(options) {
     const hostOrigin = new URL(host).origin;
     let theme = options.theme ?? "light dark";
     const route = WIDGET_ROUTE[options.widget];
-    const frame = makeIframe(`${host}${route}`);
+    const frame = makeIframe(`${host}${route}`, WIDGET_TITLE[options.widget]);
     frame.style.background = "transparent";
     const container = options.container ?? document.body;
     // Appended before bridging: `contentWindow` is null until the frame is in the

package/dist/sdk/client/focus-session.d.ts

@@ -0,0 +1,18 @@
+import type { ActiveAction, ClockAnchor, FocusSessionEvent, FocusSessionState } from "../types";
+/** A re-read only replaces the anchor when it moves the display by more than
+ * this, so request timing never makes the clock jitter. */
+export declare const REANCHOR_TOLERANCE_SECONDS = 2;
+export declare function anchorFor(active: ActiveAction, readAt: number): ClockAnchor;
+export declare function elapsedSeconds(anchor: ClockAnchor, now: number): number;
+/** Whether a fresh server sample should replace the current anchor: yes when
+ * the pause state flipped or the server disagrees with the extrapolated clock
+ * by more than the tolerance (another surface paused, a replaced session). */
+export declare function shouldReanchor(current: ClockAnchor, next: ActiveAction, now: number): boolean;
+/** `mm:ss`, rolling into `h:mm:ss` past an hour. */
+export declare function formatElapsed(seconds: number): string;
+export declare const INITIAL_FOCUS_STATE: FocusSessionState;
+export declare function focusSessionReducer(state: FocusSessionState, event: FocusSessionEvent): FocusSessionState;
+/** The pill and panel headline: "Meditate", or "Practice · Chinese" when a
+ * subject is attached. `fallback` covers a source the catalog no longer
+ * labels. */
+export declare function actionHeadline(action: Pick<ActiveAction, "label" | "source" | "subject">, fallback: string): string;

package/dist/sdk/client/focus-session.js

@@ -0,0 +1,140 @@
+/** A re-read only replaces the anchor when it moves the display by more than
+ * this, so request timing never makes the clock jitter. */
+export const REANCHOR_TOLERANCE_SECONDS = 2;
+export function anchorFor(active, readAt) {
+    return {
+        accruedSeconds: active.accruedSeconds,
+        paused: active.paused,
+        readAt,
+    };
+}
+export function elapsedSeconds(anchor, now) {
+    if (anchor.paused)
+        return anchor.accruedSeconds;
+    return anchor.accruedSeconds + Math.max(0, now - anchor.readAt) / 1000;
+}
+/** Whether a fresh server sample should replace the current anchor: yes when
+ * the pause state flipped or the server disagrees with the extrapolated clock
+ * by more than the tolerance (another surface paused, a replaced session). */
+export function shouldReanchor(current, next, now) {
+    if (current.paused !== next.paused)
+        return true;
+    return (Math.abs(elapsedSeconds(current, now) - next.accruedSeconds) >
+        REANCHOR_TOLERANCE_SECONDS);
+}
+/** `mm:ss`, rolling into `h:mm:ss` past an hour. */
+export function formatElapsed(seconds) {
+    const whole = Math.max(0, Math.floor(seconds));
+    const hours = Math.floor(whole / 3600);
+    const minutes = Math.floor((whole % 3600) / 60);
+    const secs = whole % 60;
+    const mmss = `${String(minutes).padStart(2, "0")}:${String(secs).padStart(2, "0")}`;
+    return hours > 0 ? `${hours}:${mmss}` : mmss;
+}
+export const INITIAL_FOCUS_STATE = {
+    phase: "unknown",
+    active: null,
+    anchor: null,
+    finished: null,
+    conflict: null,
+    busy: false,
+    failed: false,
+};
+function withActive(state, active, at) {
+    const sameSession = state.active?.sessionId === active.sessionId;
+    const anchor = sameSession && state.anchor && !shouldReanchor(state.anchor, active, at)
+        ? state.anchor
+        : anchorFor(active, at);
+    return {
+        ...state,
+        phase: "active",
+        active,
+        anchor,
+        conflict: null,
+        failed: false,
+    };
+}
+export function focusSessionReducer(state, event) {
+    switch (event.type) {
+        case "read": {
+            if (event.active === null) {
+                return {
+                    ...state,
+                    phase: "idle",
+                    active: null,
+                    anchor: null,
+                    failed: false,
+                };
+            }
+            return withActive(state, event.active, event.at);
+        }
+        case "read-failed":
+            return { ...state, failed: true };
+        case "request":
+            return { ...state, busy: true, failed: false };
+        case "request-failed":
+            return { ...state, busy: false, failed: true };
+        case "started":
+            return {
+                ...withActive(state, event.session, event.at),
+                anchor: anchorFor(event.session, event.at),
+                busy: false,
+                finished: null,
+            };
+        case "conflict":
+            return { ...state, busy: false, conflict: event.active };
+        case "paused": {
+            if (!state.active || !state.anchor)
+                return { ...state, busy: false };
+            const frozen = elapsedSeconds(state.anchor, event.at);
+            return {
+                ...state,
+                busy: false,
+                active: { ...state.active, paused: true, accruedSeconds: frozen },
+                anchor: { accruedSeconds: frozen, paused: true, readAt: event.at },
+            };
+        }
+        case "resumed": {
+            if (!state.active || !state.anchor)
+                return { ...state, busy: false };
+            return {
+                ...state,
+                busy: false,
+                active: { ...state.active, paused: false },
+                anchor: { ...state.anchor, paused: false, readAt: event.at },
+            };
+        }
+        case "finished": {
+            const finished = state.active
+                ? {
+                    source: state.active.source,
+                    label: state.active.label,
+                    subject: state.active.subject,
+                    xpGranted: event.result.xpGranted,
+                    durationSeconds: event.result.durationSeconds,
+                }
+                : null;
+            return {
+                ...state,
+                phase: "idle",
+                active: null,
+                anchor: null,
+                busy: false,
+                finished,
+            };
+        }
+        case "dismiss-finished":
+            return { ...state, finished: null };
+        case "dismiss-conflict":
+            return { ...state, conflict: null };
+        case "reset":
+            return INITIAL_FOCUS_STATE;
+    }
+}
+/** The pill and panel headline: "Meditate", or "Practice · Chinese" when a
+ * subject is attached. `fallback` covers a source the catalog no longer
+ * labels. */
+export function actionHeadline(action, fallback) {
+    const label = action.label ?? fallback;
+    return action.subject ? `${label} · ${action.subject.name}` : label;
+}

package/dist/sdk/client/focus.d.ts

@@ -0,0 +1,11 @@
+import type { FocusApi, UserActionSurface } from "../types";
+export type { ActionCatalogEntry, ActionCatalogResponse, ActionCurve, ActionEventRequest, ActionEventResponse, ActionSubjectRef, ActionTransitionKind, ActiveAction, CatalogFieldRef, ClockAnchor, CreateStudySubjectInput, FinishActionRequest, FinishActionResponse, FinishedSummary, FocusApi, FocusPhase, FocusSessionEvent, FocusSessionState, ListStudySessionsOptions, ListStudySubjectsOptions, StartActionResult, StartFocusRequest, StudyCatalog, StudyCategory, StudyField, StudyRange, StudySearchHit, StudySessionPage, StudySubject, StudySubjectList, StudySubjectRemovalResponse, StudySubjectResponse, StudySummary, UpdateStudySubjectInput, UserActionSurface, XpEstimateContext, } from "../types";
+export { estimateActionXp, flowMultiplier } from "../xp/curve";
+export { ActionsRequestError, isActiveSessionConflict } from "./actions";
+export * from "./focus-session";
+export { StudyRequestError } from "./study";
+export * from "./study-search";
+export declare const MEDITATION_SOURCE = "game.action.meditation";
+export declare const STUDY_SOURCE = "action.study";
+/** Compose action and study requests using the host's credentials and surface. */
+export declare function createFocusApi(host: string, getToken: () => Promise<string | null>, surface: UserActionSurface): FocusApi;

package/dist/sdk/client/focus.js

@@ -0,0 +1,30 @@
+import { createActionsApi } from "./actions";
+import { createStudyApi } from "./study";
+export { estimateActionXp, flowMultiplier } from "../xp/curve";
+export { ActionsRequestError, isActiveSessionConflict } from "./actions";
+export * from "./focus-session";
+export { StudyRequestError } from "./study";
+export * from "./study-search";
+export const MEDITATION_SOURCE = "game.action.meditation";
+export const STUDY_SOURCE = "action.study";
+/** Compose action and study requests using the host's credentials and surface. */
+export function createFocusApi(host, getToken, surface) {
+    const actions = createActionsApi(host, getToken);
+    const study = createStudyApi(host, getToken);
+    return {
+        catalog: actions.catalog,
+        active: actions.me,
+        start(request) {
+            return actions.start({ ...request, surface });
+        },
+        event: actions.event,
+        finish: actions.finish,
+        studyCatalog: study.catalog,
+        subjects: study.subjects,
+        createSubject: study.createSubject,
+        updateSubject: study.updateSubject,
+        deleteSubject: study.deleteSubject,
+        summary: study.summary,
+        sessions: study.sessions,
+    };
+}

package/dist/sdk/client/iframe-host.d.ts

@@ -16,10 +16,12 @@ export declare const OVERLAY_STYLE: Partial<CSSStyleDeclaration>;
 /**
  * Creates a Flow dialog iframe element: WebAuthn-permitted, borderless, and
  * `color-scheme: normal` so the iframe itself stays transparent (the rendered
- * theme is applied to nested card wrappers, not the iframe). The caller owns
- * positioning/visibility and any `data-*` marker.
+ * theme is applied to nested card wrappers, not the iframe). `title` is the
+ * accessible name screen readers announce for the frame (WCAG 4.1.2), so every
+ * Flow surface must say what it is. The caller owns positioning/visibility and
+ * any `data-*` marker.
  */
-export declare function makeIframe(src: string): HTMLIFrameElement;
+export declare function makeIframe(src: string, title: string): HTMLIFrameElement;
 /**
  * Builds a postMessage bridge to a child window (iframe `contentWindow` or
  * popup). Inbound is filtered by `source` so multiple same-origin Flow frames

package/dist/sdk/client/iframe-host.js

@@ -21,12 +21,15 @@ export const OVERLAY_STYLE = {
 /**
  * Creates a Flow dialog iframe element: WebAuthn-permitted, borderless, and
  * `color-scheme: normal` so the iframe itself stays transparent (the rendered
- * theme is applied to nested card wrappers, not the iframe). The caller owns
- * positioning/visibility and any `data-*` marker.
+ * theme is applied to nested card wrappers, not the iframe). `title` is the
+ * accessible name screen readers announce for the frame (WCAG 4.1.2), so every
+ * Flow surface must say what it is. The caller owns positioning/visibility and
+ * any `data-*` marker.
  */
-export function makeIframe(src) {
+export function makeIframe(src, title) {
     const frame = document.createElement("iframe");
     frame.src = src;
+    frame.title = title;
     frame.allow = IFRAME_ALLOW;
     frame.style.border = "none";
     frame.style.colorScheme = "normal";

package/dist/sdk/client/index.d.ts

@@ -1,10 +1,11 @@
 export { defaultIdHost, isLocalHostname } from "../id-host";
-export type { AccessKeyOptions, ActionCatalogEntry, ActionCatalogResponse, ActionCurve, ActionEventRequest, ActionEventResponse, ActionSubjectRef, ActionSurface, ActionsApi, ActionTransitionKind, ActiveActionResponse, ActiveSessionConflict, AdditionalSession, Address, ConnectCapabilities, ConnectResponse, CreateFlowOptions, CreateStudySubjectInput, CurrentAction, DialogHost, FinishActionRequest, FinishActionResponse, Flow, FlowCredential, FlowSessionState, FlowState, FlowUser, FlowWidgetHandle, FlowWidgetName, ListStudySessionsOptions, ListStudySubjectsOptions, LoginOptions, MethodName, MountFlowWidgetOptions, MountProfileOptions, OpenProfileOptions, ProfileButtonHandle, ProfilePosition, RoomMemberEntry, Session, StartActionInput, StartActionResponse, StartActionResult, StudyApi, StudyCatalog, StudyCategory, StudyCategoryTotals, StudyField, StudyRange, StudySessionEntry, StudySessionPage, StudySubject, StudySubjectList, StudySubjectRefusal, StudySubjectRemovalResponse, StudySubjectResponse, StudySubjectTotals, StudySummary, UpdateStudySubjectInput, UserActionSurface, XpEstimateContext, XpMode, } from "../types";
+export type { AccessKeyOptions, ActionCatalogEntry, ActionCatalogResponse, ActionCurve, ActionEventRequest, ActionEventResponse, ActionSubjectRef, ActionSurface, ActionsApi, ActionTransitionKind, ActiveAction, ActiveActionResponse, ActiveSessionConflict, AdditionalSession, Address, CatalogFieldRef, ClockAnchor, ConnectCapabilities, ConnectResponse, CreateFlowOptions, CreateStudySubjectInput, CurrentAction, DialogHost, FinishActionRequest, FinishActionResponse, FinishedSummary, Flow, FlowCredential, FlowSessionState, FlowState, FlowUser, FlowWidgetHandle, FlowWidgetName, FocusApi, FocusPhase, FocusSessionEvent, FocusSessionState, ListStudySessionsOptions, ListStudySubjectsOptions, LoginOptions, MethodName, MountFlowWidgetOptions, MountProfileOptions, OpenProfileOptions, ProfileButtonHandle, ProfilePosition, RoomMemberEntry, Session, StartActionInput, StartActionResponse, StartActionResult, StartFocusRequest, StudyApi, StudyCatalog, StudyCategory, StudyCategoryTotals, StudyField, StudyRange, StudySearchHit, StudySessionEntry, StudySessionPage, StudySubject, StudySubjectList, StudySubjectRefusal, StudySubjectRemovalResponse, StudySubjectResponse, StudySubjectTotals, StudySummary, UpdateStudySubjectInput, UserActionSurface, XpEstimateContext, XpMode, } from "../types";
 export { consistencyCurve, estimateActionXp, FLOW_SCORE_MAX, flowMultiplier, } from "../xp/curve";
 export { ActionsRequestError, createActionsApi, isActiveSessionConflict, } from "./actions";
 export { createFlow, getFlow, requireFlow, resetFlow } from "./create-flow";
 export { createDialogHost } from "./dialog-host";
 export { createFlowWidget } from "./flow-widget";
+export { actionHeadline, anchorFor, catalogFieldIndex, createFocusApi, elapsedSeconds, fieldsCoveredBySubjects, focusSessionReducer, formatElapsed, hitLabel, INITIAL_FOCUS_STATE, MEDITATION_SOURCE, matchScore, normalizeSearchText, REANCHOR_TOLERANCE_SECONDS, recentSubjects, STUDY_SOURCE, searchStudy, shouldReanchor, } from "./focus";
 export { METHODS } from "./methods";
 export { closeProfile, openProfile } from "./open-profile";
 export { createProfileButton } from "./profile-button";

package/dist/sdk/client/index.js

@@ -4,6 +4,7 @@ export { ActionsRequestError, createActionsApi, isActiveSessionConflict, } from
 export { createFlow, getFlow, requireFlow, resetFlow } from "./create-flow";
 export { createDialogHost } from "./dialog-host";
 export { createFlowWidget } from "./flow-widget";
+export { actionHeadline, anchorFor, catalogFieldIndex, createFocusApi, elapsedSeconds, fieldsCoveredBySubjects, focusSessionReducer, formatElapsed, hitLabel, INITIAL_FOCUS_STATE, MEDITATION_SOURCE, matchScore, normalizeSearchText, REANCHOR_TOLERANCE_SECONDS, recentSubjects, STUDY_SOURCE, searchStudy, shouldReanchor, } from "./focus";
 export { METHODS } from "./methods";
 export { closeProfile, openProfile } from "./open-profile";
 export { createProfileButton } from "./profile-button";

package/dist/sdk/client/json-api.d.ts

@@ -18,7 +18,7 @@ export type JsonApiError = (status: number, message: string, reason?: string) =>
  * raw status and payload for the few responses a client treats as values (a
  * start's 409); `request` is the common path that throws on any non-2xx.
  */
-export declare function createJsonApi(host: string, prefix: string, getToken: () => Promise<string | null>, makeError: JsonApiError): {
+export declare function createJsonApi(host: string, prefix: string, getToken: () => Promise<string | null>, makeError: JsonApiError, mapFailure?: (exchange: JsonExchange) => Error): {
     exchange: (path: string, options?: JsonRequestOptions) => Promise<JsonExchange>;
     request: <T>(path: string, options?: JsonRequestOptions) => Promise<T>;
     failure: (exchange: JsonExchange) => Error;

package/dist/sdk/client/json-api.js

@@ -11,10 +11,12 @@ const failureSchema = z.object({
  * raw status and payload for the few responses a client treats as values (a
  * start's 409); `request` is the common path that throws on any non-2xx.
  */
-export function createJsonApi(host, prefix, getToken, makeError) {
+export function createJsonApi(host, prefix, getToken, makeError, mapFailure) {
     /** The error a non-2xx exchange throws: the route's own wording when it
      * sent one, and its machine code as `reason`. */
     function failure(exchange) {
+        if (mapFailure)
+            return mapFailure(exchange);
         const parsed = failureSchema.safeParse(exchange.payload);
         const { error, reason } = parsed.success ? parsed.data : {};
         return makeError(exchange.status, error ?? `Request failed (${exchange.status})`, reason ?? error);

package/dist/sdk/client/open-profile.js

@@ -2,6 +2,7 @@ import { resolveIdHost } from "../id-host";
 import { isValidUsername } from "../usernames";
 import { getFlow, requireFlow } from "./create-flow";
 import { answerTokenRequest, bridgeToWindow, hostIdentity, makeIframe, OVERLAY_STYLE, } from "./iframe-host";
+import { setOverlayFocus } from "./overlay-focus";
 // One overlay per page, kept for the page's lifetime. The alternative — a
 // handle per call site — would put a second fullscreen iframe over the host the
 // moment two parts of an app (a scoreboard and a chat line) both showed a
@@ -23,12 +24,15 @@ function createViewer(options) {
     let visible = false;
     let onClose;
     function applyHitTesting() {
-        if (frame)
-            frame.style.pointerEvents = ready && visible ? "auto" : "none";
+        if (!frame)
+            return;
+        frame.style.pointerEvents = ready && visible ? "auto" : "none";
+        setOverlayFocus(frame, ready && visible);
     }
     function mount(username) {
-        const el = makeIframe(`${host}/dialog/`);
+        const el = makeIframe(`${host}/dialog/`, "Flow ID profile");
         el.dataset.flowProfileView = "";
+        el.inert = true;
         Object.assign(el.style, OVERLAY_STYLE, { pointerEvents: "none" });
         // Appended before bridging: `contentWindow` is null until the frame is in
         // the document, and the bridge is bound to that window.

package/dist/sdk/client/overlay-focus.d.ts

@@ -0,0 +1 @@
+export declare function setOverlayFocus(frame: HTMLIFrameElement, visible: boolean, opener?: HTMLElement | null): void;

package/dist/sdk/client/overlay-focus.js

@@ -0,0 +1,24 @@
+const triggers = new WeakMap();
+export function setOverlayFocus(frame, visible, opener) {
+    if (visible) {
+        if (triggers.has(frame))
+            return;
+        const active = opener ?? document.activeElement;
+        triggers.set(frame, active instanceof HTMLElement && active !== frame ? active : null);
+        frame.inert = false;
+        frame.focus();
+        return;
+    }
+    const restore = document.activeElement === frame;
+    frame.inert = true;
+    const trigger = triggers.get(frame);
+    triggers.delete(frame);
+    if (restore && trigger?.isConnected) {
+        requestAnimationFrame(() => {
+            if (trigger.isConnected &&
+                (document.activeElement === frame ||
+                    document.activeElement === document.body))
+                trigger.focus();
+        });
+    }
+}

package/dist/sdk/client/profile-button.js

@@ -1,6 +1,7 @@
 import { resolveIdHost } from "../id-host";
 import { getFlow, requireFlow } from "./create-flow";
 import { answerTokenRequest, bridgeToWindow, hostIdentity, makeIframe, OVERLAY_STYLE, } from "./iframe-host";
+import { setOverlayFocus } from "./overlay-focus";
 const POSITION_STYLE = {
     "top-right": { top: "0", right: "0" },
     "top-left": { top: "0", left: "0" },
@@ -46,8 +47,8 @@ export function createProfileButton(options) {
         createdContainer = el;
         container = el;
     }
-    function makeFrame() {
-        const frame = makeIframe(`${host}/dialog/`);
+    function makeFrame(title) {
+        const frame = makeIframe(`${host}/dialog/`, title);
         frame.dataset.flowProfile = "";
         frame.style.display = "block";
         return frame;
@@ -71,7 +72,7 @@ export function createProfileButton(options) {
         return bridge;
     }
     // ----- the persistent pill (stays mounted; sizes to its own content) -----
-    const pill = makeFrame();
+    const pill = makeFrame("Flow ID profile button");
     let pillWidth = 0;
     let pillHeight = 0;
     function applyPillSize() {
@@ -105,7 +106,8 @@ export function createProfileButton(options) {
     function ensureDialog() {
         if (dialog)
             return;
-        dialog = makeFrame();
+        dialog = makeFrame("Flow ID profile");
+        dialog.inert = true;
         Object.assign(dialog.style, OVERLAY_STYLE, {
             pointerEvents: "none",
         });
@@ -144,12 +146,14 @@ export function createProfileButton(options) {
         if (!dialog)
             return;
         dialog.style.pointerEvents = "auto";
+        setOverlayFocus(dialog, true);
         void dialogBridge?.send("__internal", { type: "dialog-shown" });
     }
     function hideDialog() {
         if (!dialog)
             return;
         dialog.style.pointerEvents = "none";
+        setOverlayFocus(dialog, false);
         void dialogBridge?.send("__internal", { type: "dialog-hidden" });
     }
     // ----- keep both iframes' identity in sync with the Flow session -----
@@ -186,6 +190,7 @@ export function createProfileButton(options) {
             });
         },
         destroy() {
+            hideDialog();
             unsubscribe();
             pillBridge.destroy();
             dialogBridge?.destroy();

package/dist/sdk/client/rooms.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { createJsonApi } from "./json-api";
 /** Every rooms endpoint answers a failure as `{ error, reason? }`. */
 const failureSchema = z.object({
     error: z.string().optional(),
@@ -22,32 +23,12 @@ export class RoomsRequestError extends Error {
  * bearer and fail fast with a 401-shaped error when no session exists.
  */
 export function createRoomsApi(host, getToken) {
-    async function request(path, options = {}) {
-        const headers = {};
-        const token = await getToken();
-        if (token)
-            headers.Authorization = `Bearer ${token}`;
-        else if (options.authRequired) {
-            throw new RoomsRequestError(401, "Sign in first");
-        }
-        if (options.body !== undefined)
-            headers["Content-Type"] = "application/json";
-        const res = await fetch(`${host}/api/rooms${path}`, {
-            method: options.method ?? "GET",
-            headers,
-            body: options.body !== undefined ? JSON.stringify(options.body) : undefined,
-        });
-        const payload = await res.json().catch(() => ({}));
-        if (!res.ok) {
-            const failure = failureSchema.safeParse(payload);
-            throw new RoomsRequestError(res.status, failure.success && failure.data.error
-                ? failure.data.error
-                : `Rooms request failed (${res.status})`, failure.success ? failure.data.reason : undefined);
-        }
-        /* SAFETY: each caller names the response type of the rooms endpoint it just called; a
-           non-ok status has already thrown above with the server's own wording. */
-        return payload;
-    }
+    const { request } = createJsonApi(host, "/api/rooms", getToken, (status, message, reason) => new RoomsRequestError(status, message, reason), ({ status, payload }) => {
+        const parsed = failureSchema.safeParse(payload);
+        return new RoomsRequestError(status, parsed.success && parsed.data.error
+            ? parsed.data.error
+            : `Rooms request failed (${status})`, parsed.success ? parsed.data.reason : undefined);
+    });
     const slugPath = (slug) => `/${encodeURIComponent(slug)}`;
     const act = (slug, action, body) => request(`${slugPath(slug)}/${action}`, {
         method: "POST",

package/dist/sdk/client/study-search.d.ts

@@ -0,0 +1,20 @@
+import type { CatalogFieldRef, StudyCatalog, StudySearchHit, StudySubject } from "../types";
+export declare function normalizeSearchText(text: string): string;
+/** 4 exact, 3 prefix, 2 a later word's prefix, 1 substring, 0 no match.
+ * Both sides are normalized here so callers can pass raw labels. */
+export declare function matchScore(query: string, candidate: string): number;
+export declare function catalogFieldIndex(catalog: StudyCatalog): Map<string, CatalogFieldRef>;
+/** Live subjects newest-used first; auth stamps `lastUsedAt` at creation, so
+ * a subject never studied sorts by when it was added. */
+export declare function recentSubjects(subjects: readonly StudySubject[], limit?: number): StudySubject[];
+/** Catalog fields the user already keeps under the field's own name are
+ * hidden from results — the subject hit covers them and picking the field
+ * again would only re-create the same subject. A renamed subject ("Math for
+ * my test" under Algebra) leaves the field visible for a second subject. */
+export declare function fieldsCoveredBySubjects(subjects: readonly StudySubject[], index: Map<string, CatalogFieldRef>): Set<string>;
+export declare function searchStudy(query: string, options: {
+    catalog: StudyCatalog;
+    subjects: readonly StudySubject[];
+    limit?: number;
+}): StudySearchHit[];
+export declare function hitLabel(hit: StudySearchHit): string;