@tai42/studio-sdk 0.2.0

package/src/hooks/useSse.ts

@@ -0,0 +1,314 @@
+/**
+ * `useSse` — the live interactions stream, implemented over the api-client's
+ * `streamInteractions` (fetch + ReadableStream, never EventSource).
+ *
+ * SSE event contract: events `interaction.add` /
+ * `interaction.answered` / `interaction.removed` / `interaction.backlog_done`.
+ * The `add` frame (backlog on connect + live tail) carries the full question;
+ * `answered` / `removed` frames carry only ids. On (re)connect the server
+ * replays the current pending set as the backlog; this hook treats that backlog
+ * as authoritative — an entry not re-seen by `interaction.backlog_done` is
+ * dropped, so an interaction removed while the client was disconnected does not
+ * linger. `add` frames are at-least-once, so entries are de-duplicated by
+ * `interaction_id`, and a redelivered `add` preserves the client `answered` flag.
+ *
+ * The `Interaction` type is imported type-only (no runtime dep on api-client);
+ * frames are validated defensively and a malformed frame is surfaced as an error,
+ * never rendered as a silent blank. `answered` is not a wire field — it is a
+ * client flag this hook flips on an `interaction.answered` event.
+ */
+import { useEffect, useRef, useState } from 'react';
+import type { Interaction } from '@tai42/api-client';
+
+import { useApi } from './useApi';
+import { useOnUnauthorized } from './useUnauthorized';
+
+/** A live interaction plus the client-maintained `answered` flag. */
+export type StreamInteraction = Interaction & { readonly answered: boolean };
+
+export interface InteractionsStreamState {
+  readonly interactions: StreamInteraction[];
+  readonly connected: boolean;
+  readonly backlogLoaded: boolean;
+  readonly error: Error | null;
+}
+
+// Reconnect backoff: capped exponential with full jitter. The delay for attempt
+// n is a random value in [0, min(CAP, BASE * 2**n)); the attempt counter resets
+// only when a connection is proven healthy (`interaction.backlog_done`), not when
+// it merely opens — so a flapping server that accepts the request then drops the
+// body still backs off instead of tight-looping. A healthy tail-reconnect is
+// near-instant while a sustained outage backs off, and the jitter spreads many
+// clients apart rather than retrying in lockstep.
+const RECONNECT_BASE_MS = 1500;
+const RECONNECT_CAP_MS = 30000;
+
+// The wire `answer_format` values. Duplicated from the api-client enum by design:
+// the SDK is the leaf and must not import api-client at runtime. The `satisfies`
+// pin against `Interaction['answer_format']` fails to compile if a listed value
+// leaves the union, so this runtime guard cannot silently drift from the type.
+const ANSWER_FORMATS = new Set<string>([
+  'text',
+  'confirm',
+  'select',
+  'form',
+  'external',
+] as const satisfies readonly Interaction['answer_format'][]);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** Parse a frame's JSON to a plain object, or null when it is not one. */
+function parseJson(data: string): Record<string, unknown> | null {
+  if (!data) return null;
+  try {
+    const obj: unknown = JSON.parse(data);
+    return isRecord(obj) ? obj : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Validate an `interaction.add` frame into an `Interaction`, or null when it is
+ * malformed. This mirrors the api-client `interaction` zod schema exactly — it
+ * accepts what that schema accepts, no more, no less. The strict-required fields
+ * — `interaction_id`, `group_id`, `created_at`, `timeout_at` — must be a string
+ * and `answer_format` a known enum value; any missing or non-string one returns
+ * null so the caller surfaces it as an error rather than rendering a blank card.
+ * Two fields are laxer, matching the schema: `question` is
+ * `z.string().default('')`, whose default substitutes ONLY an absent/undefined
+ * value, so a missing question normalizes to `''` while a present `null` (or any
+ * present non-string) is rejected; `format_payload` is nullish, so an absent/null
+ * value (text/confirm carry none) normalizes to `{}` while a present non-object is
+ * rejected — never silently coerced to a blank card.
+ */
+function parseAddFrame(data: string): Interaction | null {
+  const obj = parseJson(data);
+  if (obj === null) return null;
+  const {
+    interaction_id,
+    group_id,
+    question,
+    answer_format,
+    format_payload,
+    created_at,
+    timeout_at,
+    sensitive,
+    server_verified,
+    channel,
+    media,
+  } = obj;
+  if (typeof interaction_id !== 'string') return null;
+  if (typeof group_id !== 'string') return null;
+  // `question` is z.string().default('') in the schema: the default substitutes
+  // ONLY an absent/undefined value, so a missing question is valid while a
+  // present null (or any other present non-string) is malformed.
+  if (question !== undefined && typeof question !== 'string') return null;
+  if (typeof created_at !== 'string') return null;
+  if (typeof timeout_at !== 'string') return null;
+  if (typeof answer_format !== 'string' || !ANSWER_FORMATS.has(answer_format)) return null;
+  // `format_payload` is nullish in the schema: absent/null normalizes to {}, but
+  // a present non-object is malformed and must not be coerced to a blank card.
+  if (format_payload != null && !isRecord(format_payload)) return null;
+  // `sensitive` is z.boolean().default(false): an absent value normalizes to
+  // false, while a present non-boolean is malformed.
+  if (sensitive !== undefined && typeof sensitive !== 'boolean') return null;
+  // `server_verified` is z.boolean().optional(): an absent value stays undefined,
+  // while a present non-boolean is malformed.
+  if (server_verified !== undefined && typeof server_verified !== 'boolean') return null;
+  // `channel` is z.string().optional(): the delivery-channel name rides the frame
+  // only for a channel-delivered question; absent stays undefined, a present
+  // non-string is malformed.
+  if (channel !== undefined && typeof channel !== 'string') return null;
+  // `media` is z.array(z.unknown()).optional(): the display-only media rides the
+  // frame only when the question carries some; absent stays undefined, a present
+  // non-array is malformed. The ITEMS stay unknown here (loose by design) — each is
+  // validated per item by the renderer, so one bad item never fails this frame.
+  if (media !== undefined && !Array.isArray(media)) return null;
+  return {
+    interaction_id,
+    group_id,
+    question: typeof question === 'string' ? question : '',
+    answer_format: answer_format as Interaction['answer_format'],
+    format_payload: isRecord(format_payload) ? format_payload : {},
+    created_at,
+    timeout_at,
+    sensitive: sensitive ?? false,
+    ...(typeof server_verified === 'boolean' ? { server_verified } : {}),
+    ...(typeof channel === 'string' ? { channel } : {}),
+    ...(Array.isArray(media) ? { media } : {}),
+  };
+}
+
+/** The interaction id from an `answered` / `removed` frame, or null. */
+function parseId(data: string): string | null {
+  const id = parseJson(data)?.interaction_id;
+  return typeof id === 'string' ? id : null;
+}
+
+export function useInteractionsStream(): InteractionsStreamState {
+  const api = useApi();
+  const onUnauthorized = useOnUnauthorized();
+  const [state, setState] = useState<InteractionsStreamState>({
+    interactions: [],
+    connected: false,
+    backlogLoaded: false,
+    error: null,
+  });
+  // Source of truth: a dedupe map keyed by interaction_id, rebuilt into the
+  // ordered array on every change.
+  const mapRef = useRef<Map<string, StreamInteraction>>(new Map());
+
+  useEffect(() => {
+    const controller = new AbortController();
+    const aborted = () => controller.signal.aborted;
+
+    // A successful data frame rebuilds the list and clears any transient
+    // frame-parse error — one bad frame on a healthy stream must not stick.
+    const publish = () => {
+      setState((prev) => ({
+        ...prev,
+        interactions: Array.from(mapRef.current.values()),
+        error: null,
+      }));
+    };
+
+    const surfaceMalformed = (event: string) => {
+      setState((prev) => ({ ...prev, error: new Error(`malformed interaction frame: ${event}`) }));
+    };
+
+    // Per-connection reconcile state: the replayed backlog is authoritative, so
+    // ids not re-seen by `interaction.backlog_done` are dropped as
+    // removed-while-disconnected.
+    let reconciling = false;
+    let seenInBacklog = new Set<string>();
+    // Consecutive failed reconnect attempts. Reset only when a connection proves
+    // healthy (`interaction.backlog_done`), NOT merely when it opens — a server
+    // that accepts the request then drops the body would otherwise reset every
+    // time and never back off.
+    let reconnectAttempt = 0;
+    const beginConnection = () => {
+      reconciling = true;
+      seenInBacklog = new Set();
+    };
+
+    const applyFrame = (event: string, data: string) => {
+      if (event === 'interaction.backlog_done') {
+        if (reconciling) {
+          for (const id of mapRef.current.keys()) {
+            if (!seenInBacklog.has(id)) mapRef.current.delete(id);
+          }
+          reconciling = false;
+        }
+        // A completed backlog is proof the connection is healthy — clear the
+        // reconnect backoff so the next drop reconnects promptly.
+        reconnectAttempt = 0;
+        setState((prev) => ({
+          ...prev,
+          interactions: Array.from(mapRef.current.values()),
+          backlogLoaded: true,
+        }));
+        return;
+      }
+      if (event === 'interaction.removed') {
+        const id = parseId(data);
+        if (id === null) {
+          surfaceMalformed(event);
+          return;
+        }
+        mapRef.current.delete(id);
+        publish();
+        return;
+      }
+      if (event === 'interaction.answered') {
+        const id = parseId(data);
+        if (id === null) {
+          surfaceMalformed(event);
+          return;
+        }
+        // The answered frame carries only ids — flip the existing item's flag,
+        // keeping its question/format. An answered event for an item we never saw
+        // has nothing to show.
+        const existing = mapRef.current.get(id);
+        if (existing) mapRef.current.set(id, { ...existing, answered: true });
+        publish();
+        return;
+      }
+      // interaction.add — the full question.
+      const interaction = parseAddFrame(data);
+      if (interaction === null) {
+        surfaceMalformed(event);
+        return;
+      }
+      if (reconciling) seenInBacklog.add(interaction.interaction_id);
+      // Dedupe by id; a redelivered add preserves the client answered flag so a
+      // prior `answered` is not undone by an at-least-once replay.
+      const existing = mapRef.current.get(interaction.interaction_id);
+      mapRef.current.set(interaction.interaction_id, {
+        ...interaction,
+        answered: existing?.answered ?? false,
+      });
+      publish();
+    };
+
+    // The abort signal is the single cancellation source of truth: the cleanup
+    // aborts it, and every loop guard reads it fresh.
+    const run = async () => {
+      while (!aborted()) {
+        try {
+          const frames = await api.streamInteractions(controller.signal);
+          if (aborted()) return;
+          beginConnection();
+          setState((prev) => ({ ...prev, connected: true, error: null }));
+          for await (const frame of frames) {
+            if (aborted()) return;
+            applyFrame(frame.event, frame.data);
+          }
+        } catch (err) {
+          if (aborted()) return;
+          const error = err instanceof Error ? err : new Error(String(err));
+          setState((prev) => ({ ...prev, connected: false, error }));
+          if (error.name === 'ApiUnauthorizedError') {
+            // A 401 means the stored credential is dead — reconnecting would just
+            // replay the same bad key every delay forever. Treat it as terminal
+            // and hand off to the app's 401→login handler, the same path every
+            // other data call takes; do not loop.
+            onUnauthorized();
+            return;
+          }
+        }
+        // Stream ended or errored → wait, then reconnect (server replays backlog).
+        // Guard before the setState, like every other setState in run(): a
+        // microtask scheduled after the `for await` must not write state after
+        // the effect cleanup has aborted (and unmounted) the hook.
+        if (aborted()) return;
+        setState((prev) => ({ ...prev, connected: false }));
+        const ceiling = Math.min(RECONNECT_CAP_MS, RECONNECT_BASE_MS * 2 ** reconnectAttempt);
+        const delay = Math.random() * ceiling;
+        reconnectAttempt += 1;
+        await new Promise<void>((resolve) => {
+          const onAbort = () => {
+            clearTimeout(timer);
+            resolve();
+          };
+          const timer = setTimeout(() => {
+            // Normal wake: drop the abort listener so it does not accumulate
+            // across reconnects ({ once: true } only self-removes on firing).
+            controller.signal.removeEventListener('abort', onAbort);
+            resolve();
+          }, delay);
+          controller.signal.addEventListener('abort', onAbort, { once: true });
+        });
+      }
+    };
+
+    void run();
+    return () => {
+      controller.abort();
+    };
+  }, [api, onUnauthorized]);
+
+  return state;
+}

package/src/hooks/useTheme.ts

@@ -0,0 +1,133 @@
+/**
+ * `useTheme` — light/dark theme, token-driven. The active theme stamps
+ * `data-theme` on the document root, which the DS token layers key off.
+ *
+ * A three-state PREFERENCE sits behind the resolved theme: `'light'` and
+ * `'dark'` pin it, `'system'` follows `prefers-color-scheme` and tracks OS
+ * changes live. The resolved `theme` a consumer reads is always the concrete
+ * `'light' | 'dark'` the tokens need — never `'system'`.
+ *
+ * The preference persists to `localStorage`, but ONLY when the operator sets it
+ * explicitly (`setPreference` / `setTheme` / `toggle`). Boot READS the stored
+ * value; it never WRITES one, so a session that only ever renders the app leaves
+ * storage untouched. A `'system'` preference clears any pinned choice and hands
+ * the theme back to the OS.
+ */
+import {
+  createContext,
+  createElement,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+} from 'react';
+import type { ReactNode } from 'react';
+
+export type Theme = 'light' | 'dark';
+export type ThemePreference = 'light' | 'dark' | 'system';
+
+export interface ThemeState {
+  /** The resolved theme the tokens key off — always concrete, never `'system'`. */
+  readonly theme: Theme;
+  /** The operator's choice: a pinned theme, or `'system'` to follow the OS. */
+  readonly preference: ThemePreference;
+  /** Set the preference and persist it. The only path that writes storage. */
+  readonly setPreference: (preference: ThemePreference) => void;
+  /** Pin an explicit theme (persists) — a preference shortcut kept for callers. */
+  readonly setTheme: (theme: Theme) => void;
+  /** Flip between the two pinned themes off the current resolved theme (persists). */
+  readonly toggle: () => void;
+}
+
+const ThemeContext = createContext<ThemeState | null>(null);
+
+/** Where the explicit preference is stored between sessions. */
+const STORAGE_KEY = 'tai-studio.theme-preference';
+
+function systemTheme(): Theme {
+  try {
+    return globalThis.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+  } catch {
+    return 'light';
+  }
+}
+
+/** The persisted preference, or `'system'` when none is stored or storage is
+ * unavailable. A READ only — boot never writes, so an untouched session leaves
+ * storage alone (the login flows depend on this). */
+function readStoredPreference(): ThemePreference {
+  try {
+    const raw = globalThis.localStorage.getItem(STORAGE_KEY);
+    if (raw === 'light' || raw === 'dark' || raw === 'system') return raw;
+  } catch {
+    // No storage (private mode / non-browser) — the OS preference is the default.
+  }
+  return 'system';
+}
+
+export function ThemeProvider({ children }: { children: ReactNode }) {
+  const [preference, setPreferenceState] = useState<ThemePreference>(readStoredPreference);
+  // The live OS resolution, kept current by the listener below; it only feeds the
+  // resolved theme while the preference is `'system'`.
+  const [systemResolved, setSystemResolved] = useState<Theme>(systemTheme);
+  const theme: Theme = preference === 'system' ? systemResolved : preference;
+
+  useEffect(() => {
+    globalThis.document.documentElement.setAttribute('data-theme', theme);
+  }, [theme]);
+
+  // Track the OS preference live, but ONLY while following it. The same defensive
+  // guard as `systemTheme()` — jsdom has no `matchMedia`, so subscribing is
+  // best-effort and its absence simply leaves the last resolved value in place.
+  useEffect(() => {
+    if (preference !== 'system') return;
+    let query: MediaQueryList;
+    try {
+      query = globalThis.matchMedia('(prefers-color-scheme: dark)');
+    } catch {
+      return;
+    }
+    setSystemResolved(query.matches ? 'dark' : 'light');
+    const onChange = (event: MediaQueryListEvent): void => {
+      setSystemResolved(event.matches ? 'dark' : 'light');
+    };
+    query.addEventListener('change', onChange);
+    return () => {
+      query.removeEventListener('change', onChange);
+    };
+  }, [preference]);
+
+  const setPreference = useCallback((next: ThemePreference) => {
+    setPreferenceState(next);
+    try {
+      globalThis.localStorage.setItem(STORAGE_KEY, next);
+    } catch {
+      // Storage unavailable — the choice still applies for this session in memory.
+    }
+  }, []);
+
+  const setTheme = useCallback(
+    (next: Theme) => {
+      setPreference(next);
+    },
+    [setPreference],
+  );
+
+  const toggle = useCallback(() => {
+    setPreference(theme === 'dark' ? 'light' : 'dark');
+  }, [setPreference, theme]);
+
+  const value = useMemo<ThemeState>(
+    () => ({ theme, preference, setPreference, setTheme, toggle }),
+    [theme, preference, setPreference, setTheme, toggle],
+  );
+
+  return createElement(ThemeContext.Provider, { value }, children);
+}
+
+export function useTheme(): ThemeState {
+  const state = useContext(ThemeContext);
+  if (state === null) throw new Error('useTheme must be used within a <ThemeProvider>');
+  return state;
+}

package/src/hooks/useUnauthorized.ts

@@ -0,0 +1,20 @@
+/**
+ * `useOnUnauthorized` — the app's "the credential is dead, route to login" handler,
+ * provided through an SDK-owned context so shared hooks can reach it without a
+ * runtime dependency on the shell or the router.
+ *
+ * The default is a no-op, so a consumer rendered without a provider (a test, or a
+ * plugin in isolation) still works — it just does not route. The shell wires the
+ * real handler (the same one the api-client's 401 path drives) so a 401 raised
+ * OUTSIDE TanStack Query — notably the raw interactions SSE fetch — lands on the
+ * one login-routing path instead of being retried against a known-bad key.
+ */
+import { createContext, useContext } from 'react';
+
+const UnauthorizedContext = createContext<() => void>(() => undefined);
+
+export const UnauthorizedProvider = UnauthorizedContext.Provider;
+
+export function useOnUnauthorized(): () => void {
+  return useContext(UnauthorizedContext);
+}

package/src/host.ts

@@ -0,0 +1,15 @@
+/**
+ * @tai42/studio-sdk/host — the HOST-ONLY registry API. `loadPlugin` (the one entry
+ * through which a plugin's `register` contributes) and `getContributions` (what the
+ * shell reads) live here, apart from the plugin surface, so the served plugin asset
+ * carries no way to forge, wipe, or enumerate the registry. Only the host bundle
+ * imports this. See SECURITY.md for the trust boundary.
+ */
+export { loadPlugin, getContributions } from './plugin/registry';
+export {
+  setPluginHostState,
+  getPluginHostState,
+  subscribePluginHost,
+  usePluginContributions,
+} from './plugin/host-state';
+export type { PluginLoaderState, PluginContributionsSnapshot } from './plugin/host-state';