void startWith(subject.id)}
+ onCreate={(request) => {
+ setCreating(true);
+ setCreateFailed(false);
+ void focus
+ .createSubject(request)
+ .then((subject) => {
+ if (!subject) {
+ setCreateFailed(true);
+ return;
+ }
+ return startWith(subject.id);
+ })
+ .finally(() => setCreating(false));
+ }}
+ />
+ {createFailed ? (
+
+ {t("study.createFailed")}
+
+ ) : null}
+
+
+ );
+}
+
+interface RunningViewProps {
+ active: ActiveAction;
+ onSwitch: () => void;
+}
+
+function RunningView({ active, onSwitch }: RunningViewProps): ReactNode {
+ const focus = usePanelFocus();
+ const elapsed = useFocusElapsed(focus.state);
+ const { surface } = usePanel();
+ const { formatNumber, t } = useFocusText();
+ const entry = catalogEntryFor(focus.catalog, active.source);
+ const xp = entry
+ ? estimateActionXp(entry, {
+ elapsedSeconds: elapsed,
+ priorMinutes: active.priorMinutes,
+ flowScore: active.flowScore,
+ })
+ : null;
+ const headline = actionHeadline(active, t("focus.title"));
+
+ return (
+ <>
+
+
+ {active.paused ? t("focus.paused") : t("focus.running")}
+ {active.surface !== surface
+ ? ` · ${t(`focus.startedIn.${active.surface}`)}`
+ : ""}
+
+
+ {headline}
+
+
+
+ {t("focus.elapsed")}
+
+ {formatElapsed(elapsed)}
+
+
+ {xp !== null ? (
+
+
+ {t("focus.xp", { xp: formatNumber(xp) })}
+
+
+ {t("focus.flowMultiplier", {
+ multiplier: formatNumber(flowMultiplier(active.flowScore)),
+ })}
+
+
+ ) : null}
+
+
+
+
+
{t("focus.finishedTitle")}
+
+
+ {finished.xpGranted > 0
+ ? t("focus.finishedSummary", {
+ action: headline,
+ elapsed,
+ xp: formatNumber(finished.xpGranted),
+ })
+ : t("focus.finishedNoXp", { action: headline, elapsed })}
+
+
+
+
+ );
+}
+
+interface ConflictViewProps {
+ conflict: ActiveAction;
+ requested: StartFocusOptions;
+}
+
+function ConflictView({ conflict, requested }: ConflictViewProps): ReactNode {
+ const focus = usePanelFocus();
+ const { t } = useFocusText();
+ const entry = catalogEntryFor(focus.catalog, requested.source);
+ const subject = requested.subjectId
+ ? (focus.study.subjects?.find((s) => s.id === requested.subjectId) ?? null)
+ : null;
+ const requestedLabel = actionHeadline(
+ { label: entry?.label ?? null, source: requested.source, subject },
+ t("focus.title"),
+ );
+ return (
+ <>
+ {t("focus.conflictTitle")}
+
+
+ {t("focus.conflictBody", {
+ action: actionHeadline(conflict, t("focus.title")),
+ where: t(`focus.startedIn.${conflict.surface}`),
+ requested: requestedLabel,
+ })}
+
+
+
+
+
+
+
+
+ );
+}
diff --git a/src/focus/provider.tsx b/src/focus/provider.tsx
new file mode 100644
index 0000000..a11ab1b
--- /dev/null
+++ b/src/focus/provider.tsx
@@ -0,0 +1,481 @@
+import {
+ type ActionCatalogEntry,
+ type CreateStudySubjectInput,
+ elapsedSeconds,
+ type FocusApi,
+ type FocusSessionState,
+ focusSessionReducer,
+ INITIAL_FOCUS_STATE,
+ isActiveSessionConflict,
+ type StudyCatalog,
+ type StudySubject,
+} from "@flow-industries/id/focus";
+import {
+ createContext,
+ type ReactNode,
+ useCallback,
+ useContext,
+ useEffect,
+ useLayoutEffect,
+ useMemo,
+ useReducer,
+ useRef,
+ useState,
+} from "react";
+
+export interface StartFocusOptions {
+ source: string;
+ subjectId?: string;
+ replace?: boolean;
+}
+
+export type StartFocusOutcome = "started" | "conflict" | "failed";
+
+export interface StudyData {
+ catalog: StudyCatalog | null;
+ subjects: StudySubject[] | null;
+ failed: boolean;
+}
+
+export interface FocusContextValue {
+ /** Signed in with a usable account; everything else is inert otherwise. */
+ enabled: boolean;
+ viewerId: string | null;
+ /** The client the provider talks through, shared with the host management page so it
+ * never builds a second one; null outside a provider. */
+ api: FocusApi | null;
+ state: FocusSessionState;
+ catalog: ActionCatalogEntry[] | null;
+ catalogFailed: boolean;
+ study: StudyData;
+ /** The start a 409 interrupted, kept so "Switch" can repeat it with `replace`. */
+ pendingStart: StartFocusOptions | null;
+ refresh: () => void;
+ loadStudy: () => void;
+ start: (options: StartFocusOptions) => Promise;
+ pause: () => Promise;
+ resume: () => Promise;
+ stop: () => Promise;
+ createSubject: (
+ request: CreateStudySubjectInput,
+ ) => Promise;
+ dismissFinished: () => void;
+ dismissConflict: () => void;
+}
+
+const EMPTY_STUDY: StudyData = { catalog: null, subjects: null, failed: false };
+
+const EMPTY: FocusContextValue = {
+ enabled: false,
+ viewerId: null,
+ api: null,
+ state: INITIAL_FOCUS_STATE,
+ catalog: null,
+ catalogFailed: false,
+ study: EMPTY_STUDY,
+ pendingStart: null,
+ refresh: () => {},
+ loadStudy: () => {},
+ start: async () => "failed",
+ pause: async () => {},
+ resume: async () => {},
+ stop: async () => {},
+ createSubject: async () => null,
+ dismissFinished: () => {},
+ dismissConflict: () => {},
+};
+
+const FocusContext = createContext(EMPTY);
+
+export interface FocusProviderProps {
+ api: FocusApi;
+ viewerId: string | null;
+ children: ReactNode;
+}
+
+export function FocusProvider({
+ api,
+ viewerId,
+ children,
+}: FocusProviderProps): ReactNode {
+ return (
+
+ {children}
+
+ );
+}
+
+function FocusSessionProvider({
+ api,
+ viewerId,
+ children,
+}: FocusProviderProps): ReactNode {
+ const enabled = viewerId !== null;
+ const [state, dispatch] = useReducer(
+ focusSessionReducer,
+ INITIAL_FOCUS_STATE,
+ );
+ const stateRef = useRef(state);
+ stateRef.current = state;
+ const [catalog, setCatalog] = useState(null);
+ const [catalogFailed, setCatalogFailed] = useState(false);
+ const [study, setStudy] = useState(EMPTY_STUDY);
+ const [pendingStart, setPendingStart] = useState(
+ null,
+ );
+ const generationRef = useRef(0);
+ const studyRequestedRef = useRef(false);
+ const mountedRef = useRef(false);
+ const requestRef = useRef(false);
+ const creatingRef = useRef(false);
+ const readRef = useRef(0);
+
+ const read = useCallback(() => {
+ if (!enabled || !mountedRef.current) return;
+ const generation = generationRef.current;
+ const request = ++readRef.current;
+ void api
+ .active()
+ .then((active) => {
+ if (generationRef.current !== generation || request !== readRef.current)
+ return;
+ dispatch({ type: "read", active, at: Date.now() });
+ })
+ .catch(() => {
+ if (generationRef.current !== generation || request !== readRef.current)
+ return;
+ dispatch({ type: "read-failed" });
+ });
+ }, [api, enabled]);
+
+ const loadCatalog = useCallback(() => {
+ if (!enabled || !mountedRef.current) return;
+ const generation = generationRef.current;
+ void api
+ .catalog()
+ .then((result) => {
+ if (generationRef.current !== generation) return;
+ setCatalog(result.actions);
+ setCatalogFailed(false);
+ })
+ .catch(() => {
+ if (generationRef.current !== generation) return;
+ setCatalogFailed(true);
+ });
+ }, [api, enabled]);
+
+ const loadSubjects = useCallback(() => {
+ if (!enabled || !mountedRef.current) return;
+ const generation = generationRef.current;
+ void api
+ .subjects()
+ .then((result) => {
+ if (generationRef.current !== generation) return;
+ setStudy((current) => ({
+ ...current,
+ subjects: result.subjects,
+ }));
+ })
+ .catch(() => {
+ if (generationRef.current !== generation) return;
+ setStudy((current) => ({ ...current, failed: true }));
+ });
+ }, [api, enabled]);
+
+ const markSubjectUsed = useCallback((subjectId: string, at: string) => {
+ setStudy((current) => ({
+ ...current,
+ subjects:
+ current.subjects?.map((subject) =>
+ subject.id === subjectId ? { ...subject, lastUsedAt: at } : subject,
+ ) ?? null,
+ }));
+ }, []);
+
+ const loadStudy = useCallback(() => {
+ if (!enabled || !mountedRef.current) return;
+ studyRequestedRef.current = true;
+ const generation = generationRef.current;
+ void Promise.allSettled([api.studyCatalog(), api.subjects()]).then(
+ ([catalog, subjects]) => {
+ if (generationRef.current !== generation) return;
+ setStudy((current) => ({
+ catalog:
+ catalog.status === "fulfilled" ? catalog.value : current.catalog,
+ subjects:
+ subjects.status === "fulfilled"
+ ? subjects.value.subjects
+ : current.subjects,
+ failed:
+ catalog.status === "rejected" || subjects.status === "rejected",
+ }));
+ },
+ );
+ }, [api, enabled]);
+
+ useLayoutEffect(() => {
+ mountedRef.current = true;
+ requestRef.current = false;
+ creatingRef.current = false;
+ generationRef.current += 1;
+ dispatch({ type: "reset" });
+ setCatalog(null);
+ setCatalogFailed(false);
+ setStudy(EMPTY_STUDY);
+ setPendingStart(null);
+ studyRequestedRef.current = false;
+ if (viewerId !== null) {
+ read();
+ loadCatalog();
+ }
+ return () => {
+ mountedRef.current = false;
+ generationRef.current += 1;
+ };
+ }, [viewerId, read, loadCatalog]);
+
+ useEffect(() => {
+ if (!enabled || !mountedRef.current) return;
+ const generation = generationRef.current;
+ const onVisibility = () => {
+ const active = stateRef.current.active;
+ if (document.visibilityState === "hidden") {
+ if (active) {
+ void api
+ .event({ sessionId: active.sessionId, kind: "focus_lost" })
+ .catch(() => {});
+ }
+ return;
+ }
+ if (!active) {
+ read();
+ return;
+ }
+ void api
+ .event({ sessionId: active.sessionId, kind: "focus_gained" })
+ .catch(() => {})
+ .finally(() => {
+ if (generationRef.current === generation) read();
+ });
+ };
+ document.addEventListener("visibilitychange", onVisibility);
+ return () => document.removeEventListener("visibilitychange", onVisibility);
+ }, [enabled, api, read]);
+
+ const start = useCallback(
+ async (options: StartFocusOptions): Promise => {
+ if (!enabled || !mountedRef.current || requestRef.current)
+ return "failed";
+ const generation = generationRef.current;
+ requestRef.current = true;
+ readRef.current += 1;
+ dispatch({ type: "request" });
+ try {
+ const result = await api.start(options);
+ if (generationRef.current !== generation) return "failed";
+ if (isActiveSessionConflict(result)) {
+ setPendingStart(options);
+ dispatch({ type: "conflict", active: result.active });
+ return "conflict";
+ }
+ setPendingStart(null);
+ dispatch({ type: "started", session: result.session, at: Date.now() });
+ read();
+ if (options.subjectId) {
+ markSubjectUsed(options.subjectId, result.session.startedAt);
+ if (studyRequestedRef.current) loadSubjects();
+ }
+ return "started";
+ } catch {
+ if (generationRef.current === generation) {
+ dispatch({ type: "request-failed" });
+ }
+ return "failed";
+ } finally {
+ if (generationRef.current === generation) requestRef.current = false;
+ }
+ },
+ [api, enabled, read, loadSubjects, markSubjectUsed],
+ );
+
+ const transition = useCallback(
+ async (kind: "pause" | "resume") => {
+ const active = stateRef.current.active;
+ if (!enabled || !mountedRef.current || !active || requestRef.current)
+ return;
+ const generation = generationRef.current;
+ requestRef.current = true;
+ readRef.current += 1;
+ dispatch({ type: "request" });
+ try {
+ await api.event({ sessionId: active.sessionId, kind });
+ if (generationRef.current !== generation) return;
+ dispatch({
+ type: kind === "pause" ? "paused" : "resumed",
+ at: Date.now(),
+ });
+ } catch {
+ if (generationRef.current === generation) {
+ dispatch({ type: "request-failed" });
+ }
+ } finally {
+ if (generationRef.current === generation) requestRef.current = false;
+ }
+ },
+ [api, enabled],
+ );
+
+ const pause = useCallback(() => transition("pause"), [transition]);
+ const resume = useCallback(() => transition("resume"), [transition]);
+
+ const stop = useCallback(async () => {
+ const active = stateRef.current.active;
+ if (!enabled || !mountedRef.current || !active || requestRef.current)
+ return;
+ const generation = generationRef.current;
+ requestRef.current = true;
+ readRef.current += 1;
+ dispatch({ type: "request" });
+ try {
+ const result = await api.finish({ sessionId: active.sessionId });
+ if (generationRef.current !== generation) return;
+ dispatch({ type: "finished", result, at: Date.now() });
+ read();
+ } catch {
+ if (generationRef.current === generation) {
+ dispatch({ type: "request-failed" });
+ }
+ } finally {
+ if (generationRef.current === generation) requestRef.current = false;
+ }
+ }, [api, enabled, read]);
+
+ const createSubject = useCallback(
+ async (request: CreateStudySubjectInput) => {
+ if (!enabled || !mountedRef.current || creatingRef.current) return null;
+ creatingRef.current = true;
+ const generation = generationRef.current;
+ try {
+ const { subject } = await api.createSubject(request);
+ if (generationRef.current !== generation) return null;
+ setStudy((current) => ({
+ ...current,
+ subjects: current.subjects
+ ? [
+ ...current.subjects.filter((row) => row.id !== subject.id),
+ subject,
+ ]
+ : [subject],
+ }));
+ return subject;
+ } catch {
+ return null;
+ } finally {
+ if (generationRef.current === generation) creatingRef.current = false;
+ }
+ },
+ [api, enabled],
+ );
+
+ const dismissFinished = useCallback(
+ () => dispatch({ type: "dismiss-finished" }),
+ [],
+ );
+ const dismissConflict = useCallback(() => {
+ setPendingStart(null);
+ dispatch({ type: "dismiss-conflict" });
+ }, []);
+
+ const value = useMemo(
+ () => ({
+ enabled,
+ viewerId,
+ api: enabled ? api : null,
+ state,
+ catalog,
+ catalogFailed,
+ study,
+ pendingStart,
+ refresh: read,
+ loadStudy,
+ start,
+ pause,
+ resume,
+ stop,
+ createSubject,
+ dismissFinished,
+ dismissConflict,
+ }),
+ [
+ enabled,
+ viewerId,
+ api,
+ state,
+ catalog,
+ catalogFailed,
+ study,
+ pendingStart,
+ read,
+ loadStudy,
+ start,
+ pause,
+ resume,
+ stop,
+ createSubject,
+ dismissFinished,
+ dismissConflict,
+ ],
+ );
+
+ return (
+ {children}
+ );
+}
+
+/** Outside a provider — the embed, or an SSR pass — this answers an inert,
+ * signed-out value instead of throwing: a missing Focus must never take a
+ * chat surface down with it. */
+export function useFocus(): FocusContextValue {
+ return useContext(FocusContext);
+}
+
+/** The running action, or null. */
+export function useActiveAction(): FocusSessionState["active"] {
+ const { state } = useFocus();
+ return state.active;
+}
+
+const CLOCK_TICK_MS = 250;
+
+/** Whole seconds elapsed on the running action, advancing on the local clock
+ * from the last server sample and frozen while paused. Re-renders only when
+ * the displayed second changes. */
+export function useFocusElapsed(providedState?: FocusSessionState): number {
+ const context = useFocus();
+ const state = providedState ?? context.state;
+ const anchor = state.anchor;
+ const [shown, setShown] = useState(() =>
+ anchor ? Math.floor(elapsedSeconds(anchor, Date.now())) : 0,
+ );
+
+ useEffect(() => {
+ if (!anchor) {
+ setShown(0);
+ return;
+ }
+ const tick = () => {
+ const whole = Math.floor(elapsedSeconds(anchor, Date.now()));
+ setShown((current) => (current === whole ? current : whole));
+ };
+ tick();
+ if (anchor.paused) return;
+ const id = window.setInterval(tick, CLOCK_TICK_MS);
+ return () => window.clearInterval(id);
+ }, [anchor]);
+
+ return shown;
+}
diff --git a/src/focus/study-subject-picker.tsx b/src/focus/study-subject-picker.tsx
new file mode 100644
index 0000000..7ff05f8
--- /dev/null
+++ b/src/focus/study-subject-picker.tsx
@@ -0,0 +1,680 @@
+import type {
+ StudyCatalog,
+ StudyCategory,
+ StudyField,
+ StudySubject,
+} from "@flow-industries/id/focus";
+import {
+ recentSubjects,
+ type StudySearchHit,
+ searchStudy,
+} from "@flow-industries/id/focus";
+import { ChevronLeft, ChevronRight, Plus, Search } from "lucide-react";
+import {
+ type FormEvent,
+ type KeyboardEvent,
+ type ReactNode,
+ type RefObject,
+ useEffect,
+ useId,
+ useMemo,
+ useRef,
+ useState,
+} from "react";
+import { Button } from "../components/ui/button";
+import { Input } from "../components/ui/input";
+import { cn } from "../utils/cn";
+import {
+ type FocusText,
+ FocusTextProvider,
+ isolateBidi,
+ useFocusText,
+} from "./text";
+
+const CLAIM_FOCUS_RETRY_MS = 30;
+const CLAIM_FOCUS_ATTEMPTS = 6;
+
+/** Moves focus to `ref` when `enabled` turns on. One `focus()` is not enough
+ * here: the Base UI popup that hosts this picker re-homes focus onto itself
+ * on the frame after a focused child unmounts (the button that opened this
+ * step, the search input the add form replaces), so the claim is retried for
+ * a few frames until it holds. */
+function useClaimFocus(
+ ref: RefObject,
+ enabled: boolean,
+) {
+ useEffect(() => {
+ if (!enabled) return;
+ const input = ref.current;
+ if (!input) return;
+ let attempts = 0;
+ let timer = 0;
+ const claim = () => {
+ if (
+ document.activeElement === input ||
+ attempts >= CLAIM_FOCUS_ATTEMPTS
+ ) {
+ return;
+ }
+ attempts += 1;
+ input.focus();
+ timer = window.setTimeout(claim, CLAIM_FOCUS_RETRY_MS);
+ };
+ claim();
+ return () => window.clearTimeout(timer);
+ }, [ref, enabled]);
+}
+
+export interface StudySubjectPickerProps {
+ text?: FocusText;
+ catalog: StudyCatalog | null;
+ subjects: StudySubject[] | null;
+ /** Data could not be loaded; the picker still offers "Add your own". */
+ failed?: boolean;
+ /** A start or create is in flight — options stay visible but inert. */
+ busy?: boolean;
+ /** Seconds studied today per subject id, rendered as "today: 42 min".
+ * Omitted until the summary API exists; the row simply shows nothing. */
+ todaySeconds?: Record;
+ onPick: (subject: StudySubject) => void;
+ onCreate: (request: { name?: string; field?: string }) => void;
+ /** Rendered as the leading back control when the host has a previous step. */
+ onBack?: () => void;
+ autoFocus?: boolean;
+ className?: string;
+}
+
+type PickerOption =
+ | { kind: "subject"; id: string; subject: StudySubject }
+ | {
+ kind: "field";
+ id: string;
+ field: StudyField;
+ category: StudyCategory;
+ alias: string | null;
+ }
+ | { kind: "category"; id: string; category: StudyCategory }
+ | { kind: "add"; id: string; name: string | null };
+
+type OptionGroup = {
+ key: string;
+ label: string | null;
+ options: PickerOption[];
+};
+
+function subjectOption(subject: StudySubject): PickerOption {
+ return { kind: "subject", id: `subject:${subject.id}`, subject };
+}
+
+function hitOption(hit: StudySearchHit): PickerOption {
+ if (hit.kind === "subject") {
+ return { kind: "subject", id: `subject:${hit.id}`, subject: hit.subject };
+ }
+ return {
+ kind: "field",
+ id: `field:${hit.id}`,
+ field: hit.ref.field,
+ category: hit.ref.category,
+ alias: hit.alias,
+ };
+}
+
+export function StudySubjectPicker(props: StudySubjectPickerProps): ReactNode {
+ return (
+
+
+
+ );
+}
+
+function Picker({
+ catalog,
+ subjects,
+ failed = false,
+ busy = false,
+ todaySeconds,
+ onPick,
+ onCreate,
+ onBack,
+ autoFocus = false,
+ className,
+}: StudySubjectPickerProps): ReactNode {
+ const { formatNumber, t } = useFocusText();
+ const baseId = useId();
+ const inputRef = useRef(null);
+ const [query, setQuery] = useState("");
+ const [categorySlug, setCategorySlug] = useState(null);
+ const [adding, setAdding] = useState(null);
+ const [activeIndex, setActiveIndex] = useState(0);
+ const trimmedQuery = query.trim();
+
+ const category = useMemo(
+ () =>
+ categorySlug && catalog
+ ? (catalog.categories.find((c) => c.slug === categorySlug) ?? null)
+ : null,
+ [catalog, categorySlug],
+ );
+
+ const groups = useMemo(() => {
+ const liveSubjects = subjects ?? [];
+ if (trimmedQuery) {
+ const needle = trimmedQuery.toLowerCase();
+ const results = catalog
+ ? searchStudy(trimmedQuery, { catalog, subjects: liveSubjects }).map(
+ hitOption,
+ )
+ : liveSubjects
+ .filter((s) => s.name.toLowerCase().includes(needle))
+ .map(subjectOption);
+ return [
+ {
+ key: "results",
+ label: t("study.results"),
+ options: results,
+ },
+ {
+ key: "add",
+ label: null,
+ options: [{ kind: "add", id: "add:named", name: trimmedQuery }],
+ },
+ ];
+ }
+ if (category) {
+ return [
+ {
+ key: `category:${category.slug}`,
+ label: category.label,
+ options: category.fields.map((field) => ({
+ kind: "field" as const,
+ id: `field:${field.slug}`,
+ field,
+ category,
+ alias: null,
+ })),
+ },
+ ];
+ }
+ const recent = recentSubjects(liveSubjects);
+ const result: OptionGroup[] = [];
+ if (recent.length > 0) {
+ result.push({
+ key: "recent",
+ label: t("study.recent"),
+ options: recent.map(subjectOption),
+ });
+ }
+ if (catalog) {
+ result.push({
+ key: "browse",
+ label: t("study.browse"),
+ options: catalog.categories.map((c) => ({
+ kind: "category" as const,
+ id: `category:${c.slug}`,
+ category: c,
+ })),
+ });
+ }
+ result.push({
+ key: "add",
+ label: null,
+ options: [{ kind: "add", id: "add:own", name: null }],
+ });
+ return result;
+ }, [catalog, category, subjects, t, trimmedQuery]);
+
+ const options = useMemo(() => groups.flatMap((g) => g.options), [groups]);
+ const clampedIndex = Math.min(activeIndex, Math.max(0, options.length - 1));
+ const activeOption = options[clampedIndex] ?? null;
+ const listId = `${baseId}-listbox`;
+ const optionDomId = (option: PickerOption) =>
+ `${baseId}-${option.id.replace(/[^a-zA-Z0-9_-]/g, "_")}`;
+
+ useClaimFocus(inputRef, autoFocus && adding === null);
+
+ useEffect(() => {
+ if (!activeOption) return;
+ document
+ .getElementById(optionDomId(activeOption))
+ ?.scrollIntoView({ block: "nearest" });
+ });
+
+ const optionLabel = (option: PickerOption): string => {
+ switch (option.kind) {
+ case "subject":
+ return t("study.pickSubject", { subject: option.subject.name });
+ case "field":
+ return `${t("study.pickSubject", { subject: option.field.label })} · ${option.category.label}`;
+ case "category":
+ return t("study.openCategory", { category: option.category.label });
+ case "add":
+ return option.name
+ ? t("study.addNamed", { name: option.name })
+ : t("study.addOwn");
+ }
+ };
+
+ const choose = (option: PickerOption) => {
+ if (busy) return;
+ switch (option.kind) {
+ case "subject":
+ onPick(option.subject);
+ return;
+ case "field":
+ onCreate({ field: option.field.slug });
+ return;
+ case "category":
+ setCategorySlug(option.category.slug);
+ setActiveIndex(0);
+ return;
+ case "add":
+ setAdding(option.name ?? "");
+ return;
+ }
+ };
+
+ const onKeyDown = (event: KeyboardEvent) => {
+ switch (event.key) {
+ case "ArrowDown":
+ event.preventDefault();
+ setActiveIndex(
+ options.length ? (clampedIndex + 1) % options.length : 0,
+ );
+ return;
+ case "ArrowUp":
+ event.preventDefault();
+ setActiveIndex(
+ options.length
+ ? (clampedIndex - 1 + options.length) % options.length
+ : 0,
+ );
+ return;
+ case "Home":
+ if (!query) {
+ event.preventDefault();
+ setActiveIndex(0);
+ }
+ return;
+ case "End":
+ if (!query) {
+ event.preventDefault();
+ setActiveIndex(Math.max(0, options.length - 1));
+ }
+ return;
+ case "Enter":
+ if (activeOption) {
+ event.preventDefault();
+ choose(activeOption);
+ }
+ return;
+ case "Escape":
+ if (query) {
+ event.preventDefault();
+ event.stopPropagation();
+ setQuery("");
+ setActiveIndex(0);
+ } else if (category) {
+ event.preventDefault();
+ event.stopPropagation();
+ setCategorySlug(null);
+ setActiveIndex(0);
+ }
+ return;
+ }
+ };
+
+ if (adding !== null) {
+ return (
+ setAdding(null)}
+ className={className}
+ />
+ );
+ }
+
+ const loading = !failed && (subjects === null || catalog === null);
+ let statusMessage: string | null = null;
+ if (loading) statusMessage = t("study.loading");
+ else if (failed) statusMessage = t("study.failed");
+
+ let back: { label: string; onClick: () => void } | null = null;
+ if (category) {
+ back = {
+ label: t("study.allCategories"),
+ onClick: () => {
+ setCategorySlug(null);
+ setActiveIndex(0);
+ inputRef.current?.focus();
+ },
+ };
+ } else if (onBack) {
+ back = { label: t("focus.pickerTitle"), onClick: onBack };
+ }
+
+ return (
+
+
+ {back ? (
+
+ ) : null}
+
+
{t("study.title")}
+
+ {t("study.description")}
+
+
+
+
+
+ {
+ setQuery(event.target.value);
+ setActiveIndex(0);
+ }}
+ onKeyDown={onKeyDown}
+ className="h-9 ps-8 text-sm md:text-sm"
+ data-study-search=""
+ />
+
+
+ {t(
+ "study.optionCount",
+ { count: formatNumber(options.length) },
+ options.length,
+ )}
+
+ {statusMessage ? (
+
+ {statusMessage}
+
+ ) : null}
+
+ {groups.map((group) => {
+ if (group.options.length === 0) {
+ if (group.key !== "results") return null;
+ return (
+
+ {t("study.noResults", { query: trimmedQuery })}
+
+ );
+ }
+ return (
+
+ {group.label ? (
+
+ {group.label}
+
+ ) : null}
+ {group.options.map((option) => {
+ const active = activeOption?.id === option.id;
+ return (
+
+ );
+ })}
+
+ );
+ })}
+
+
+
+ {children}
+
+ );
+}
diff --git a/src/focus/text.tsx b/src/focus/text.tsx
new file mode 100644
index 0000000..007a9c6
--- /dev/null
+++ b/src/focus/text.tsx
@@ -0,0 +1,121 @@
+import { createContext, type ReactNode, useContext } from "react";
+
+type TextEntry = string | { one: string; other: string };
+
+const CATALOG = {
+ "common.done": "Done",
+ "focus.title": "Focus",
+ "focus.description": "Start an action and earn XP without entering a room.",
+ "focus.pickerTitle": "Start an action",
+ "focus.catalogLoading": "Loading actions…",
+ "focus.catalogFailed": "Actions are unavailable right now.",
+ "focus.sessionLoading": "Checking for a running action…",
+ "focus.start": "Start",
+ "focus.startAction": "Start {action}",
+ "focus.choose": "Choose…",
+ "focus.chooseAction": "Choose what to {action}",
+ "focus.running": "In progress",
+ "focus.paused": "Paused",
+ "focus.pause": "Pause",
+ "focus.resume": "Resume",
+ "focus.stop": "Stop",
+ "focus.switch": "Switch…",
+ "focus.switchNote": "Stopping {action} grants its XP now.",
+ "focus.elapsed": "Elapsed",
+ "focus.xp": "+{xp} XP",
+ "focus.flowMultiplier": "Flow Score ×{multiplier}",
+ "focus.startedIn.game": "Started in the game",
+ "focus.startedIn.talk": "Started in Talk",
+ "focus.startedIn.web": "Started on the web",
+ "focus.pill":
+ "{action}, {elapsed} elapsed, about {xp} XP. Open the running action.",
+ "focus.pillPaused":
+ "{action}, paused at {elapsed}, about {xp} XP. Open the running action.",
+ "focus.finishedTitle": "Nice work",
+ "focus.finishedSummary": "{action} · {elapsed} · +{xp} XP",
+ "focus.finishedNoXp":
+ "{action} · {elapsed} · too short to earn XP this time.",
+ "focus.conflictTitle": "Already in progress",
+ "focus.conflictBody":
+ "{action} is running ({where}). Switch to {requested}? The running action stops and gets its XP.",
+ "focus.conflictSwitch": "Switch",
+ "focus.conflictKeep": "Keep going",
+ "focus.failed": "That didn't go through — try again.",
+ "study.title": "What are you practicing today?",
+ "study.description": "Each subject keeps its own time.",
+ "study.searchLabel": "Search subjects",
+ "study.searchPlaceholder": "Search, e.g. Chinese",
+ "study.recent": "Recent",
+ "study.browse": "Browse",
+ "study.results": "Results",
+ "study.noResults": "Nothing matches “{query}”.",
+ "study.addOwn": "Add your own",
+ "study.addNamed": "Add “{name}”",
+ "study.addName": "Subject name",
+ "study.addNamePlaceholder": "e.g. Math for my test",
+ "study.addCategory": "Category (optional)",
+ "study.addCategoryNone": "No category",
+ "study.addSubmit": "Add and start",
+ "study.allCategories": "All categories",
+ "study.alias": "also “{alias}”",
+ "study.todayMinutes": "today: {minutes} min",
+ "study.loading": "Loading subjects…",
+ "study.failed": "Subjects are unavailable right now.",
+ "study.pickSubject": "Start practicing {subject}",
+ "study.openCategory": "Browse {category}",
+ "study.fieldCount": { one: "{count} field", other: "{count} fields" },
+ "study.optionCount": { one: "{count} option", other: "{count} options" },
+ "study.createFailed": "Couldn't add that subject — try again.",
+} as const satisfies Record;
+
+export type FocusTextKey = keyof typeof CATALOG;
+
+export type TextValues = Record;
+export interface FocusText {
+ t: (key: FocusTextKey, values?: TextValues, count?: number) => string;
+ formatNumber: (value: number) => string;
+}
+export function isolateBidi(value: string | number): string {
+ return `\u2068${value}\u2069`;
+}
+export function createFocusText(
+ locale = "en",
+ messages: Partial> = {},
+): FocusText {
+ const numbers = new Intl.NumberFormat(locale);
+ const plurals = new Intl.PluralRules(locale);
+ return {
+ formatNumber: (value) => numbers.format(value),
+ t(key, values = {}, count) {
+ const entry: TextEntry = messages[key] ?? CATALOG[key];
+ let template: string;
+ // biome-ignore lint: TextEntry is an explicit public string-or-plural contract.
+ if (typeof entry === "string") template = entry;
+ else if (plurals.select(count ?? 0) === "one") template = entry.one;
+ else template = entry.other;
+ return template.replace(/\{([^}]+)\}/g, (_match, name: string) =>
+ String(values[name] ?? ""),
+ );
+ },
+ };
+}
+export const defaultFocusText = createFocusText();
+const FocusTextContext = createContext(defaultFocusText);
+interface FocusTextProviderProps {
+ text?: FocusText;
+ children: ReactNode;
+}
+
+export function FocusTextProvider({
+ text = defaultFocusText,
+ children,
+}: FocusTextProviderProps): ReactNode {
+ return (
+
+ {children}
+
+ );
+}
+export function useFocusText(): FocusText {
+ return useContext(FocusTextContext);
+}
diff --git a/src/styles/tokens.css b/src/styles/tokens.css
index 4d2cab7..779f881 100644
--- a/src/styles/tokens.css
+++ b/src/styles/tokens.css
@@ -124,7 +124,7 @@
--success: #09b270;
--success-background: color-mix(in oklab, var(--success) 12%, var(--background));
- --success-foreground: var(--success);
+ --success-foreground: #067447;
--input-focus: color-mix(in oklab, var(--focus) 12%, var(--input));
--focus: var(--color-pink);
--overlay: oklch(0 0 0 / 0.75);
diff --git a/tests/focus-provider.fixture.tsx b/tests/focus-provider.fixture.tsx
new file mode 100644
index 0000000..4dd8151
--- /dev/null
+++ b/tests/focus-provider.fixture.tsx
@@ -0,0 +1,72 @@
+import { createFocusApi, type FocusApi } from "@flow-industries/id/focus";
+import { StrictMode, useEffect, useMemo, useState } from "react";
+import { createRoot } from "react-dom/client";
+import { FocusProvider, useFocus } from "../src/focus/provider";
+
+function Observer() {
+ const { study, loadStudy } = useFocus();
+ useEffect(() => loadStudy(), [loadStudy]);
+ return (
+ <>
+
+
+
+ );
+}
+
+function Fixture() {
+ const [viewer, setViewer] = useState("Alice");
+ const api = useMemo(
+ () => ({
+ ...createFocusApi("https://unused.invalid", async () => null, "web"),
+ active: async () => null,
+ catalog: async () => ({ actions: [] }),
+ studyCatalog: async () => {
+ if (localStorage.getItem("failure") === "catalog")
+ throw new Error("Catalog unavailable");
+ return {
+ version: 1,
+ categories: [{ slug: "languages", label: "Languages", fields: [] }],
+ };
+ },
+ subjects: async () => {
+ if (localStorage.getItem("failure") === "subjects")
+ throw new Error("Subjects unavailable");
+ if (viewer === "Alice")
+ await new Promise((resolve) => setTimeout(resolve, 250));
+ return {
+ subjects: [
+ {
+ id: viewer,
+ name: viewer,
+ field: null,
+ archivedAt: null,
+ createdAt: "2026-09-08T00:00:00Z",
+ lastUsedAt: "2026-09-08T00:00:00Z",
+ },
+ ],
+ };
+ },
+ }),
+ [viewer],
+ );
+ return (
+ <>
+
+
+
+
+
+ );
+}
+const root = document.getElementById("root");
+if (root)
+ createRoot(root).render(
+
+
+ ,
+ );
diff --git a/tests/focus-provider.spec.ts b/tests/focus-provider.spec.ts
new file mode 100644
index 0000000..ff06b65
--- /dev/null
+++ b/tests/focus-provider.spec.ts
@@ -0,0 +1,53 @@
+import { execFileSync } from "node:child_process";
+import { expect, test } from "@playwright/test";
+
+const script = execFileSync(
+ "bun",
+ ["build", "tests/focus-provider.fixture.tsx", "--target", "browser"],
+ { encoding: "utf8", maxBuffer: 5_000_000 },
+);
+
+test.beforeEach(async ({ page }) => {
+ await page.route("**/provider-fixture", (route) =>
+ route.fulfill({
+ contentType: "text/html",
+ body: '',
+ }),
+ );
+ await page.route("**/provider-fixture.js", (route) =>
+ route.fulfill({ contentType: "text/javascript", body: script }),
+ );
+});
+
+test("child mount loads study and account change discards delayed old subjects", async ({
+ page,
+}) => {
+ await page.goto("/provider-fixture");
+ await expect(page.locator("output")).toContainText('"name":"Alice"');
+ await page.reload();
+ await page.getByRole("button", { name: "Switch" }).click();
+ await expect(page.locator("output")).toContainText('"name":"Bob"');
+ await page.waitForTimeout(350);
+ await expect(page.locator("output")).not.toContainText('"name":"Alice"');
+});
+
+for (const failure of ["catalog", "subjects"]) {
+ test(`preserves successful data when ${failure} fails and recovers`, async ({
+ page,
+ }) => {
+ await page.addInitScript(
+ (value) => localStorage.setItem("failure", value),
+ failure,
+ );
+ await page.goto("/provider-fixture");
+ await expect(page.locator("output")).toContainText('"failed":true');
+ await expect(page.locator("output")).toContainText(
+ failure === "catalog" ? '"name":"Alice"' : '"label":"Languages"',
+ );
+ await page.evaluate(() => localStorage.removeItem("failure"));
+ await page.getByRole("button", { name: "Retry" }).click();
+ await expect(page.locator("output")).toContainText('"failed":false');
+ await expect(page.locator("output")).toContainText('"name":"Alice"');
+ await expect(page.locator("output")).toContainText('"label":"Languages"');
+ });
+}
diff --git a/tests/focus.spec.ts b/tests/focus.spec.ts
new file mode 100644
index 0000000..14116b0
--- /dev/null
+++ b/tests/focus.spec.ts
@@ -0,0 +1,60 @@
+import { expect, test } from "@playwright/test";
+import type { FocusShowcase } from "../app/FocusShowcase";
+
+export type FocusFixture = typeof FocusShowcase;
+
+test.beforeEach(async ({ page }) => {
+ await page.goto("/#focus");
+});
+
+test("keyboard selection, pause, reload recovery and finish", async ({
+ page,
+}) => {
+ await page.getByRole("button", { name: "Choose what to Practice" }).click();
+ const search = page.getByRole("combobox");
+ await expect(search).toBeFocused();
+ await search.fill("Chinese");
+ await search.press("Enter");
+ await expect(page.locator('[data-focus-view="running"]')).toContainText(
+ "Alice's Chinese",
+ );
+ await page.getByRole("button", { name: "Pause", exact: true }).click();
+ const elapsed = await page.locator("[data-focus-elapsed]").textContent();
+ await page.reload();
+ await expect(
+ page.getByRole("button", { name: "Resume", exact: true }),
+ ).toBeVisible();
+ await expect(page.locator("[data-focus-elapsed]")).toHaveText(elapsed ?? "");
+ await page.getByRole("button", { name: "Stop", exact: true }).click();
+ await expect(page.locator('[data-focus-view="finished"]')).toBeVisible();
+});
+
+test("account changes discard delayed private subjects and guest stays inert", async ({
+ page,
+}) => {
+ await page.getByRole("button", { name: "Slow responses" }).click();
+ await page.getByRole("button", { name: "Choose what to Practice" }).click();
+ await page.getByRole("button", { name: "Switch account" }).click();
+ await page.getByRole("button", { name: "Choose what to Practice" }).click();
+ await expect(
+ page.getByRole("option", { name: /Bob's Chinese/ }),
+ ).toBeVisible();
+ await expect(page.locator("[data-study-picker]")).not.toContainText("Alice");
+ await page.getByRole("button", { name: "Sign out", exact: true }).click();
+ await expect(page.locator("[data-study-picker]")).toHaveCount(0);
+ await expect(page.locator("[data-focus-view]")).not.toContainText("Bob");
+});
+
+test("mutation failure retains session and retry succeeds", async ({
+ page,
+}) => {
+ await page.getByRole("button", { name: "Start Meditation" }).click();
+ await page.getByRole("button", { name: "Simulate errors" }).click();
+ await page.getByRole("button", { name: "Stop", exact: true }).click();
+ await expect(
+ page.locator('[data-focus-view="running"] [role="status"]'),
+ ).toBeVisible();
+ await page.getByRole("button", { name: "Simulate errors" }).click();
+ await page.getByRole("button", { name: "Stop", exact: true }).click();
+ await expect(page.locator('[data-focus-view="finished"]')).toBeVisible();
+});
diff --git a/tests/visual.spec.ts-snapshots/components-dark.png b/tests/visual.spec.ts-snapshots/components-dark.png
index e2c03d3..d8a2666 100644
Binary files a/tests/visual.spec.ts-snapshots/components-dark.png and b/tests/visual.spec.ts-snapshots/components-dark.png differ
diff --git a/tests/visual.spec.ts-snapshots/components-light.png b/tests/visual.spec.ts-snapshots/components-light.png
index 221c0a0..330f920 100644
Binary files a/tests/visual.spec.ts-snapshots/components-light.png and b/tests/visual.spec.ts-snapshots/components-light.png differ