@flow-industries/id 0.21.2 → 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();

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/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/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;

package/dist/sdk/client/study-search.js

@@ -0,0 +1,116 @@
+export function normalizeSearchText(text) {
+    return text
+        .normalize("NFD")
+        .replace(/\p{M}+/gu, "")
+        .toLowerCase()
+        .replace(/\s+/g, " ")
+        .trim();
+}
+/** 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 function matchScore(query, candidate) {
+    const normalizedQuery = normalizeSearchText(query);
+    const normalizedCandidate = normalizeSearchText(candidate);
+    if (!normalizedQuery || !normalizedCandidate)
+        return 0;
+    if (normalizedCandidate === normalizedQuery)
+        return 4;
+    if (normalizedCandidate.startsWith(normalizedQuery))
+        return 3;
+    if (normalizedCandidate.includes(` ${normalizedQuery}`))
+        return 2;
+    if (normalizedCandidate.includes(normalizedQuery))
+        return 1;
+    return 0;
+}
+export function catalogFieldIndex(catalog) {
+    const index = new Map();
+    for (const category of catalog.categories) {
+        for (const field of category.fields) {
+            index.set(field.slug, { category, field });
+        }
+    }
+    return index;
+}
+/** Live subjects newest-used first; auth stamps `lastUsedAt` at creation, so
+ * a subject never studied sorts by when it was added. */
+export function recentSubjects(subjects, limit = 5) {
+    return [...subjects]
+        .sort((a, b) => b.lastUsedAt.localeCompare(a.lastUsedAt))
+        .slice(0, limit);
+}
+/** 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 function fieldsCoveredBySubjects(subjects, index) {
+    const covered = new Set();
+    for (const subject of subjects) {
+        if (!subject.field)
+            continue;
+        const ref = index.get(subject.field);
+        if (!ref)
+            continue;
+        if (normalizeSearchText(subject.name) === normalizeSearchText(ref.field.label)) {
+            covered.add(subject.field);
+        }
+    }
+    return covered;
+}
+function bestAliasMatch(query, field) {
+    let best = null;
+    for (const alias of field.aliases ?? []) {
+        const score = matchScore(query, alias);
+        if (score > (best?.score ?? 0))
+            best = { alias, score };
+    }
+    return best;
+}
+export function searchStudy(query, options) {
+    const { catalog, subjects, limit = 12 } = options;
+    if (!normalizeSearchText(query))
+        return [];
+    const index = catalogFieldIndex(catalog);
+    const covered = fieldsCoveredBySubjects(subjects, index);
+    const hits = [];
+    for (const subject of subjects) {
+        const ref = subject.field ? (index.get(subject.field) ?? null) : null;
+        let score = matchScore(query, subject.name);
+        if (ref) {
+            score = Math.max(score, matchScore(query, ref.field.label));
+            const alias = bestAliasMatch(query, ref.field);
+            if (alias)
+                score = Math.max(score, alias.score);
+        }
+        if (score > 0) {
+            hits.push({ kind: "subject", id: subject.id, subject, ref, score });
+        }
+    }
+    for (const ref of index.values()) {
+        if (covered.has(ref.field.slug))
+            continue;
+        const labelScore = matchScore(query, ref.field.label);
+        const alias = bestAliasMatch(query, ref.field);
+        const score = Math.max(labelScore, alias?.score ?? 0);
+        if (score === 0)
+            continue;
+        hits.push({
+            kind: "field",
+            id: ref.field.slug,
+            ref,
+            alias: alias && alias.score > labelScore ? alias.alias : null,
+            score,
+        });
+    }
+    hits.sort((a, b) => {
+        if (b.score !== a.score)
+            return b.score - a.score;
+        if (a.kind !== b.kind)
+            return a.kind === "subject" ? -1 : 1;
+        return hitLabel(a).localeCompare(hitLabel(b));
+    });
+    return hits.slice(0, limit);
+}
+export function hitLabel(hit) {
+    return hit.kind === "subject" ? hit.subject.name : hit.ref.field.label;
+}

package/dist/sdk/react/use-cooldown.d.ts

@@ -0,0 +1 @@
+export declare function useCooldown(initial: number): [number, (next: number) => void];

package/dist/sdk/react/use-cooldown.js

@@ -0,0 +1,12 @@
+import { useEffect, useState } from "react";
+export function useCooldown(initial) {
+    const [cooldown, setCooldown] = useState(initial);
+    const cooldownActive = cooldown > 0;
+    useEffect(() => {
+        if (!cooldownActive)
+            return;
+        const timer = setInterval(() => setCooldown((c) => (c <= 1 ? 0 : c - 1)), 1000);
+        return () => clearInterval(timer);
+    }, [cooldownActive]);
+    return [cooldown, setCooldown];
+}

package/dist/sdk/types/auth.d.ts

@@ -160,3 +160,15 @@ export type VerifiedFlowJWT = JWTPayload & {
      */
     guest?: boolean;
 };
+export type PasskeyEnrollment = {
+    userId: string;
+    username: string;
+    credential: FlowCredential;
+};
+export type AccountRegistration = {
+    username: string;
+    email: string;
+    subscribedToNews: boolean;
+    walletAddress: string | null;
+    credential: FlowCredential | null;
+};

package/dist/sdk/types/dialog.d.ts

@@ -1,3 +1,4 @@
+import type { RpcRequest } from "./protocol";
 /**
  * Async view state for a dialog panel — the three states every fetched
  * section renders (spinner / retry row / content), so "empty" stays
@@ -89,3 +90,27 @@ export type DialogState = {
     customFeatures?: DialogCustomFeatures;
     customLabels?: DialogCustomLabels;
 };
+export type SignUpProps = {
+    request: RpcRequest;
+    rpId: string;
+    accessKeyHash?: string | undefined;
+    guestToken?: string | undefined;
+    onHome: () => void;
+    onSignIn: () => void;
+};
+export type SignInWithEmailProps = {
+    request: RpcRequest;
+    onBack: () => void;
+    onHome: () => void;
+};
+/** Cookie-authoritative identity for account data operations. */
+export type AccountDataIdentity = {
+    id: string;
+    username: string;
+    isGuest: boolean;
+};
+/** Validated export file and any collections capped by the server. */
+export type AccountDataDownload = {
+    blob: Blob;
+    truncated: string[];
+};

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

@@ -0,0 +1,109 @@
+import type { ActionCatalogResponse, ActionEventRequest, ActionEventResponse, ActionSubjectRef, ActiveActionResponse, CreateStudySubjectInput, FinishActionRequest, FinishActionResponse, ListStudySessionsOptions, ListStudySubjectsOptions, StartActionInput, StartActionResult, StudyCatalog, StudyCategory, StudyField, StudyRange, StudySessionPage, StudySubject, StudySubjectList, StudySubjectRemovalResponse, StudySubjectResponse, StudySummary, UpdateStudySubjectInput } from "./index";
+/** The running session as the header pill and the panel see it: the shape of
+ * `GET /api/actions/me`, of a start's `session` and of a 409's `active`. */
+export type ActiveAction = ActiveActionResponse;
+/** A start as the UI requests it. The surface is not the caller's to choose:
+ * `createFocusApi` stamps every start with the injected host surface. `sessionId` may be
+ * omitted; the SDK mints the idempotency key. */
+export type StartFocusRequest = Omit<StartActionInput, "surface">;
+export interface FocusApi {
+    catalog(): Promise<ActionCatalogResponse>;
+    /** The caller's running session, or null when idle. */
+    active(): Promise<ActiveAction | null>;
+    /** Resolves to the 409 conflict as a value; every other refusal throws. */
+    start(request: StartFocusRequest): Promise<StartActionResult>;
+    event(request: ActionEventRequest): Promise<ActionEventResponse>;
+    finish(request: FinishActionRequest): Promise<FinishActionResponse>;
+    studyCatalog(): Promise<StudyCatalog>;
+    subjects(options?: ListStudySubjectsOptions): Promise<StudySubjectList>;
+    createSubject(request: CreateStudySubjectInput): Promise<StudySubjectResponse>;
+    /** Rename (`{ name }`), re-anchor (`{ field }`), archive or restore
+     * (`{ archived }`) a subject. Archiving is what the picker means by
+     * "remove"; the host subject-management surface also offers deletion. */
+    updateSubject(id: string, patch: UpdateStudySubjectInput): Promise<StudySubjectResponse>;
+    /** Removes a subject outright when nothing references it; auth archives it
+     * instead when sessions do, which the `outcome` reports. */
+    deleteSubject(id: string): Promise<StudySubjectRemovalResponse>;
+    /** Finished study time per subject and per category; the running session
+     * is not in it and is folded in live from the provider. */
+    summary(range: StudyRange): Promise<StudySummary>;
+    /** One subject's finished sessions, newest first, keyset-paged on
+     * `nextBefore`. */
+    sessions(options: ListStudySessionsOptions): Promise<StudySessionPage>;
+}
+export interface CatalogFieldRef {
+    category: StudyCategory;
+    field: StudyField;
+}
+export type StudySearchHit = {
+    kind: "subject";
+    id: string;
+    subject: StudySubject;
+    ref: CatalogFieldRef | null;
+    score: number;
+} | {
+    kind: "field";
+    id: string;
+    ref: CatalogFieldRef;
+    /** The alias that matched when the label itself did not. */
+    alias: string | null;
+    score: number;
+};
+export interface ClockAnchor {
+    accruedSeconds: number;
+    paused: boolean;
+    readAt: number;
+}
+export type FocusPhase = "unknown" | "idle" | "active";
+/** What Stop leaves behind, shown exactly once before it is dismissed. */
+export interface FinishedSummary {
+    source: string;
+    label: string | null;
+    subject: ActionSubjectRef | null;
+    xpGranted: number;
+    durationSeconds: number;
+}
+export interface FocusSessionState {
+    phase: FocusPhase;
+    active: ActiveAction | null;
+    anchor: ClockAnchor | null;
+    finished: FinishedSummary | null;
+    /** The other session a plain start ran into, awaiting "switch?". */
+    conflict: ActiveAction | null;
+    busy: boolean;
+    failed: boolean;
+}
+export type FocusSessionEvent = {
+    type: "read";
+    active: ActiveAction | null;
+    at: number;
+} | {
+    type: "read-failed";
+} | {
+    type: "request";
+} | {
+    type: "request-failed";
+} | {
+    type: "started";
+    session: ActiveAction;
+    at: number;
+} | {
+    type: "conflict";
+    active: ActiveAction;
+} | {
+    type: "paused";
+    at: number;
+} | {
+    type: "resumed";
+    at: number;
+} | {
+    type: "finished";
+    result: FinishActionResponse;
+    at: number;
+} | {
+    type: "dismiss-finished";
+} | {
+    type: "dismiss-conflict";
+} | {
+    type: "reset";
+};

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

@@ -1,19 +1,23 @@
 export type { AccountDeleteRequest, AccountDeleteResponse, AccountErasureCounts, AccountErasureEntry, AccountErasureFeed, AccountErasureResult, AccountExport, AccountExportAccount, AccountExportActionEvent, AccountExportActionSession, AccountExportAttendance, AccountExportAuthoredEvent, AccountExportCharacterStateTime, AccountExportFollow, AccountExportGameEvent, AccountExportOtherService, AccountExportOwnedRoom, AccountExportPasskey, AccountExportRoomEvents, AccountExportRoomMembership, AccountExportRoomPlayerState, AccountExportRoomPresence, AccountExportRoomRestriction, AccountExportRoomSettings, AccountExportRooms, AccountExportRsvp, AccountExportSettingsSurface, AccountExportStudySubject, AccountExportXpGrant, AccountExportXpSummary, } from "./account-data";
 export type { ActionCurve, ActionEventRequest, ActionEventResponse, ActionsApi, ActiveActionState, FinishActionRequest, ListStudySessionsOptions, ListStudySubjectsOptions, StartActionInput, StartActionResult, StudyApi, StudySubjectResponse, UseActiveActionOptions, XpEstimateContext, } from "./actions";
-export type { AccountSession, AccountSessionsResponse, AdditionalSession, AuthConfig, AuthResponse, AuthResponseWithWebAuthn, BioNormalization, BioRejection, BioWriteRefusal, BioWriteResult, FlowCredential, FlowUser, PasskeyPluginOptions, RevokeAllSessionsResponse, RevokeSessionResponse, SecurityActivityEntry, SecurityActivityResponse, SessionUser, VerifiedFlowJWT, VerifyOptions, WebAuthnSignature, } from "./auth";
+export type { AccountRegistration, AccountSession, AccountSessionsResponse, AdditionalSession, AuthConfig, AuthResponse, AuthResponseWithWebAuthn, BioNormalization, BioRejection, BioWriteRefusal, BioWriteResult, FlowCredential, FlowUser, PasskeyEnrollment, PasskeyPluginOptions, RevokeAllSessionsResponse, RevokeSessionResponse, SecurityActivityEntry, SecurityActivityResponse, SessionUser, VerifiedFlowJWT, VerifyOptions, WebAuthnSignature, } from "./auth";
 export type { BodyRegion, CosmeticItem, CosmeticMaterial, CosmeticPaint, CosmeticSlot, EquipConflict, EquippedCosmetic, EquippedCosmetics, EquipRegion, PaintSlot, SettingsConflict, } from "./cosmetics";
 export { BODY_REGIONS, COSMETIC_MATERIALS } from "./cosmetics";
-export type { BoundaryError, DialogCustomFeatures, DialogCustomLabels, DialogError, DialogReferrer, DialogState, Loadable, ProfileData, ProfileIdentity, } from "./dialog";
+export type { AccountDataDownload, AccountDataIdentity, BoundaryError, DialogCustomFeatures, DialogCustomLabels, DialogError, DialogReferrer, DialogState, Loadable, ProfileData, ProfileIdentity, SignInWithEmailProps, SignUpProps, } from "./dialog";
 export type { AuthErrorCode, AuthEventName, AuthEventRecord, AuthMode, AuthOutcome, BeaconBody, FunnelStep, } from "./events";
+export type { ActiveAction, CatalogFieldRef, ClockAnchor, FinishedSummary, FocusApi, FocusPhase, FocusSessionEvent, FocusSessionState, StartFocusRequest, StudySearchHit, } from "./focus";
 export type { GameEventReport, GameLifecycleEventName, GameLifecycleFeedEvent, GameLifecycleFeedPage, GamePlayerSession, } from "./game";
 export { GAME_LIFECYCLE_EVENT_NAMES } from "./game";
+export type { AccountProfileData } from "./landing";
 export type { Bridge, BridgeParameters, FlowAccount, FlowRemote, FlowRemoteConfig, FromWindowOptions, MessageResponse, Messenger, OneOf, Payload, QueuedRequest, ReadyOptions, RemoteFlowState, RemoteState, Schema, Storage, Topic, WithReady, } from "./messenger";
+export type { OtpVerificationFailure, OtpVerificationResult, VerificationAdapter, } from "./otp";
 export type { Call, ConnectCapabilities, ConnectRequest, ConnectResponse, GuestRequest, GuestResponse, MethodName, MethodParams, MethodResult, RestoreResponse, RpcRequest, SendCallsParams, SendCallsRequest, SendCallsResponse, SendTransactionParams, SendTransactionRequest, SendTransactionResponse, SignMessageRequest, SignMessageResponse, SignOutRequest, SignOutResponse, SignTypedDataRequest, SignTypedDataResponse, TransactionArgs, TypedData, TypedDataDomain, TypedDataField, } from "./protocol";
 export { getConnectCapabilities, isPersonalSignParams, isSendCallsParams, isSendTransactionParams, } from "./protocol";
 export type { CreateRoomEventInput, RoomEventArchive, RoomEventAttendance, RoomEventFrequency, RoomEventInstance, RoomEventInterest, RoomEventInterestState, RoomEventList, RoomEventOccurrence, RoomEventRecurrence, RoomEventRoomRef, RoomEventRun, RoomEventSeries, RoomEventStatus, SetInterestInput, UpdateRoomEventInput, } from "./room-events";
 export type { CreateRoomInput, GlobalRole, ModerationSubject, MyRooms, PlayerPositionReport, RoleChangeVerdict, RoomCapabilities, RoomCapability, RoomChannel, RoomDetail, RoomList, RoomMemberEntry, RoomMembers, RoomOccupancy, RoomOwner, RoomPlayerPosition, RoomPresenceEntry, RoomPresenceSnapshot, RoomRestrictionKind, RoomRole, RoomSummary, RoomSurfaceSettings, RoomsApi, RoomVisibility, StaffEntry, UpdateRoomInput, VerifyRoomContext, Viewer, VoiceDecisionReason, VoiceDecisionSubject, VoiceRoomDecision, } from "./rooms";
 export type { AccessKeyOptions, AccessKeyPreparation, Address, ColorScheme, CreateDialogHostOptions, CreateFlowOptions, DialogHost, DialogOpenOptions, FinalizeAccessKeyParams, Flow, FlowConnectorParameters, FlowCookieNames, FlowIdProviderProps, FlowSessionState, FlowState, FlowWidgetHandle, FlowWidgetName, FlowWidgetProps, Listener, LoginOptions, MountFlowWidgetOptions, MountProfileOptions, OpenProfileOptions, PrepareArgsWithAuth, PrepareTransactionRequestPhase, ProfileButtonHandle, ProfileButtonProps, ProfilePosition, ResolveAccountParams, ResolvedAccessKeyOptions, RootCredential, RunLoginParams, RunLoginResult, SendCallsArgs, SendTransactionArgs, Session, SigningContext, SignMessageArgs, SignTypedDataArgs, Store, StoredAccessKey, UseOpenProfileOptions, WagmiConnectCapabilities, WagmiConnectParams, } from "./sdk";
 export type { GracefulShutdownCleanup, GracefulShutdownOptions, GracefulShutdownServer, GracefulShutdownSignal, ResolvedFlowSession, ResolveSessionOptions, SessionRouteOptions, SessionRouteResponse, SessionRouteSession, } from "./server";
+export type { CosmeticOffer, PaintDescriptor, SettingDescriptor, Settings, SettingsMigration, StoredSettings, SurfaceRegistry, } from "./settings";
 export type { CreateStudySubjectInput, ListStudySessionsInput, StudyCatalog, StudyCategory, StudyCategoryTotals, StudyField, StudyRange, StudySessionEntry, StudySessionPage, StudySessionsResult, StudySubject, StudySubjectCreation, StudySubjectList, StudySubjectRefusal, StudySubjectRemoval, StudySubjectRemovalResponse, StudySubjectTotals, StudySubjectUpdate, StudySummary, UpdateStudySubjectInput, } from "./study";
 export type { CoinAsset, IdentifiedTx, TxApprove, TxConvert, TxSend, TxSwap, } from "./tx";
-export type { ActionCatalogEntry, ActionCatalogResponse, ActionDayContext, ActionEventKind, ActionSessionState, ActionSubjectRef, ActionSurface, ActionTransitionKind, ActiveActionResponse, ActiveSessionConflict, CurrentAction, FinishActionResponse, LevelProgress, PublicProfile, PublicProfileRefusal, PublicProfileResult, PublicProfileSignal, PublicUserProfile, StartActionResponse, StartUserSessionResult, UserActionSurface, XpGrantResult, XpMode, XpRecentGrant, XpSummary, } from "./xp";
+export type { ActionCatalogEntry, ActionCatalogResponse, ActionDayContext, ActionDurations, ActionEventKind, ActionSessionState, ActionSubjectRef, ActionSurface, ActionTimelineEvent, ActionTransitionKind, ActiveActionResponse, ActiveSessionConflict, CurrentAction, FinishActionResponse, LevelProgress, PublicProfile, PublicProfileRefusal, PublicProfileResult, PublicProfileSignal, PublicUserProfile, StartActionResponse, StartUserSessionResult, UserActionSurface, XpGrantResult, XpMode, XpRecentGrant, XpSummary, } from "./xp";

package/dist/sdk/types/landing.d.ts

@@ -0,0 +1,9 @@
+import type { FlowUser } from "./auth";
+export type AccountProfileData = FlowUser & {
+    email?: string | null;
+    emailVerified?: boolean;
+    subscribedToNews?: boolean;
+    createdAt?: string;
+    image?: string | null;
+    walletAddress?: string | null;
+};

package/dist/sdk/types/otp.d.ts

@@ -0,0 +1,20 @@
+import type { AuthErrorCode } from "./events";
+export type OtpVerificationFailure = {
+    ok: false;
+    errorCode: AuthErrorCode;
+    apiCode: "INVALID_OTP" | "OTP_EXPIRED" | "TOO_MANY_ATTEMPTS";
+    status: 400 | 403;
+    message: string;
+    attemptsRemaining?: number;
+};
+export type OtpVerificationResult = {
+    ok: true;
+} | OtpVerificationFailure;
+export interface VerificationAdapter {
+    findVerificationValue(identifier: string): Promise<{
+        id: string;
+        value: string;
+        expiresAt: Date;
+    } | null | undefined>;
+    deleteVerificationValue(id: string): Promise<void>;
+}

package/dist/sdk/types/settings.d.ts

@@ -0,0 +1,162 @@
+import type { RawValue } from "../json";
+import type { CosmeticItem, CosmeticMaterial, CosmeticSlot, EquipRegion, SettingsConflict } from "./cosmetics";
+export interface PaintDescriptor {
+    key: string;
+    group: string;
+    label: string;
+    description?: string;
+    type: "paint";
+    default: string;
+    options: {
+        value: string;
+        label: string;
+    }[];
+    /**
+     * The item this colour lands on, and the material on it that is recoloured.
+     * Both travel on the descriptor rather than being read back out of the key: a
+     * form grouping its pickers by item, and a renderer deciding which surface a
+     * colour applies to, each want one of them, and neither should be taking a
+     * key apart to get it.
+     */
+    cosmetic: string;
+    material: CosmeticMaterial;
+}
+export interface CosmeticOffer extends CosmeticItem {
+    /**
+     * Every equip region this item cannot share a body with — its own, plus
+     * everything they overlap. Another item is blocked by this one exactly when
+     * its `regions` intersect this list, so a client tests a set instead of
+     * re-implementing the rule.
+     */
+    conflicts: readonly EquipRegion[];
+    /**
+     * The colour pickers this item brings once it is worn: the SAME descriptors
+     * {@link SurfaceRegistry.derived} emits for it, from the same builder, so a
+     * client rendering its draft and a client reading the derived list for a
+     * saved loadout draw the same rows.
+     *
+     * An offer, not a setting. A colour is a setting the player HAS only while
+     * its item is equipped — that is what {@link sanitize} prunes on — and
+     * nothing here widens the stored blob or the write path.
+     */
+    paint: readonly PaintDescriptor[];
+}
+export type SettingDescriptor = {
+    key: string;
+    group: string;
+    label: string;
+    description?: string;
+    type: "number";
+    default: number;
+    min: number;
+    max: number;
+    step: number;
+} | {
+    key: string;
+    group: string;
+    label: string;
+    description?: string;
+    type: "boolean";
+    default: boolean;
+} | {
+    key: string;
+    group: string;
+    label: string;
+    description?: string;
+    type: "enum";
+    default: string;
+    options: {
+        value: string;
+        label: string;
+    }[];
+} | {
+    key: string;
+    group: string;
+    label: string;
+    description?: string;
+    /** Free text with a shape, for values no fixed option list can cover —
+     * a Discord snowflake, a channel id. `pattern` is a source string (not a
+     * RegExp) so the descriptor stays JSON-serializable for the schema
+     * endpoint the settings form reads. */
+    type: "text";
+    default: string;
+    maxLength: number;
+    pattern?: string;
+} | {
+    key: string;
+    group: string;
+    label: string;
+    description?: string;
+    /** One cosmetic slot: the stored value is a catalog cosmetic id, or ""
+     * for nothing equipped. `items` is the catalog projection the customizer
+     * reads off the schema endpoint so it can render a draft loadout with no
+     * catalog data of its own — which picks would collide, and which colour
+     * pickers a pick brings with it. UX only; the conflict rule is enforced
+     * on save, and a draft is never a claim about what may be saved.
+     *
+     * The default is an item id, not "": a player who has never dressed is
+     * wearing the starting outfit, and saying so here is what lets "" mean
+     * the one thing it should — a player who chose to wear nothing there. */
+    type: "cosmetic";
+    default: string;
+    slot: CosmeticSlot;
+    /**
+     * Whether an avatar may go with this slot empty. False is the slot a
+     * client offers a "None" chip for; true is one where `""` is refused on
+     * save. Projected here rather than restated in the customizer for the
+     * reason {@link CosmeticOffer.conflicts} is: the rule belongs to the
+     * slot, and a second hand-maintained copy of it goes quiet (AUTH-222).
+     */
+    required: boolean;
+    items: readonly CosmeticOffer[];
+} | PaintDescriptor;
+export type StoredSettings = Record<string, RawValue>;
+export type Settings = Record<string, number | boolean | string>;
+export interface SettingsMigration {
+    to: number;
+    up: (stored: StoredSettings) => StoredSettings;
+}
+export interface SurfaceRegistry {
+    /**
+     * Bumped only when a setting in this surface is renamed or retyped. A stored
+     * blob stamps the version it was last normalized to; {@link normalize} walks
+     * an old blob up to this version on read, preserving the user's chosen value
+     * instead of dropping it. Adding or removing a setting does NOT bump it.
+     */
+    version: number;
+    settings: readonly SettingDescriptor[];
+    /**
+     * The steps {@link normalize} walks an out-of-date blob up through, in
+     * ascending {@link SettingsMigration.to} order. A surface that has never
+     * renamed anything has none, and its blobs need no walk.
+     */
+    migrations?: readonly SettingsMigration[];
+    /**
+     * Enum defaults are drawn from the option list seeded by the user id instead
+     * of the descriptor default, so every unsaved user gets their own stable
+     * random pick — identical on every read and on every surface that reads it.
+     */
+    randomDefaults?: boolean;
+    /**
+     * Cross-field rule for the whole surface, evaluated on the MERGED blob by
+     * the one settings write path. Per-descriptor {@link sanitize} cannot
+     * express it: an equip-region collision is a relation between two keys, not
+     * a property of either. Living on the surface rather than in a route is what
+     * makes it impossible for a second write path to skip.
+     */
+    validate?: (settings: Settings) => SettingsConflict | null;
+    /**
+     * The settings this surface has only because of what is stored in it — the
+     * appearance surface's colour pickers for the cosmetics a player is
+     * currently wearing.
+     *
+     * Derived rather than fixed is the whole mechanism: a setting that exists
+     * only while its cosmetic is equipped is dropped by {@link sanitize} the
+     * moment the cosmetic is not, so unequipping an item takes its colour with
+     * it and re-equipping cannot resurrect a colour the player never chose.
+     *
+     * Reads the surface's FIXED settings only, never its own output, so the
+     * descriptor list is resolved in one pass and cannot recurse.
+     */
+    derived?: (settings: Settings) => readonly SettingDescriptor[];
+}

package/dist/sdk/types/xp.d.ts

@@ -212,3 +212,11 @@ export interface CurrentAction {
     since: string;
     subject?: string;
 }
+export interface ActionTimelineEvent {
+    kind: ActionEventKind;
+    at: Date;
+}
+export interface ActionDurations {
+    accruedSeconds: number;
+    focusedSeconds: number;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flow-industries/id",
-  "version": "0.21.2",
+  "version": "0.22.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -50,6 +50,10 @@
     "./start/server": {
       "types": "./dist/sdk/start/server.d.ts",
       "import": "./dist/sdk/start/server.js"
+    },
+    "./focus": {
+      "types": "./dist/sdk/client/focus.d.ts",
+      "import": "./dist/sdk/client/focus.js"
     }
   },
   "files": [
@@ -126,7 +130,7 @@
   ],
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1073.0",
-    "@flow-industries/ui": "^0.21.0",
+    "@flow-industries/ui": "^0.21.1",
     "@hono/otel": "^1.1.2",
     "@openobserve/browser-logs": "^0.3.1",
     "@openobserve/browser-rum": "^0.3.1",