@guuey/chat 0.4.0

package/src/react/use-transcript.ts

@@ -0,0 +1,274 @@
+/**
+ * The renderer-state owner + the LIVE input assembler (spec §7).
+ *
+ * `planTranscript` is pure — everything stateful about rendering lives
+ * here, in renderer-owned React state:
+ *
+ *  - `useTranscript` owns the user's collapse overrides, the live
+ *    `ViewHostPhase` reports, and locator-mount resolution, merges them
+ *    into the inputs, and returns the (memoized) plan;
+ *  - `useTranscriptInputs` assembles `TranscriptInputs` from
+ *    `useAgentInvoke`'s return — the live twin of the root export's
+ *    `transcriptInputsFromHistory`.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import type { UseAgentInvokeReturn } from "@guuey/agent-client";
+import {
+  resolveViewMount,
+  type ResolvedViewMount,
+  type UiResourceReader,
+  type ViewHostPhase,
+} from "@guuey/mcp-apps-host";
+import { planTranscript } from "../plan.js";
+import type { TranscriptPolicy } from "../policy.js";
+import type {
+  ItemKey,
+  PromptItemInput,
+  TranscriptInputs,
+  TranscriptMessage,
+  TranscriptOverrides,
+  TranscriptPlan,
+} from "../types.js";
+
+// ─── useTranscript ─────────────────────────────────────────────────────────
+
+export interface UseTranscriptArgs {
+  inputs: TranscriptInputs;
+  policy: TranscriptPolicy;
+  /**
+   * Resolves R6 `locator` mounts (history cards persisted as `ui://`
+   * identities) with a fresh authenticated `resources/read`. Without one,
+   * locators render the R13 "view expired" state after a failed local
+   * resolution — labeled, never blank.
+   */
+  reader?: UiResourceReader;
+}
+
+export interface UseTranscriptResult {
+  plan: TranscriptPlan;
+  /** Flip one item's collapse state (wired to every toggle's onClick). */
+  toggle: (key: ItemKey) => void;
+  /** The live collapse-override map (renderer-owned, plan input). */
+  overrides: TranscriptOverrides;
+  /** Wire to `<GuueyView onPhaseChange>` (the default kit already does). */
+  onViewPhase: (key: ItemKey, phase: ViewHostPhase) => void;
+  /** Locator resolutions: mount material, or `"expired"` for a miss. */
+  resolvedMounts: ReadonlyMap<ItemKey, ResolvedViewMount | "expired">;
+}
+
+export function useTranscript({ inputs, policy, reader }: UseTranscriptArgs): UseTranscriptResult {
+  const [overrides, setOverrides] = useState<TranscriptOverrides>({});
+  const [phases, setPhases] = useState<Readonly<Record<string, ViewHostPhase>>>({});
+  const [resolvedMounts, setResolvedMounts] = useState<
+    ReadonlyMap<ItemKey, ResolvedViewMount | "expired">
+  >(new Map());
+
+  const merged = useMemo<TranscriptInputs>(
+    () => ({ ...inputs, viewPhases: { ...inputs.viewPhases, ...phases } }),
+    [inputs, phases],
+  );
+  const plan = useMemo(() => planTranscript(merged, policy, overrides), [merged, policy, overrides]);
+
+  // Toggle flips the item's CURRENT resolved state (policy default or a
+  // previous override) — read from the plan so the first toggle of a
+  // default-expanded item collapses it.
+  const planRef = useRef(plan);
+  planRef.current = plan;
+  const toggle = useCallback((key: ItemKey) => {
+    const findExpanded = (): boolean => {
+      for (const item of planRef.current.items) {
+        if (item.key === key) return item.expanded;
+        if (item.kind === "tool-group") {
+          for (const tool of item.tools) {
+            if (tool.key === key) return tool.expanded;
+            if (tool.result?.key === key) return tool.result.expanded;
+          }
+        }
+        if (item.kind === "tool" && item.result?.key === key) return item.result.expanded;
+      }
+      return false;
+    };
+    const current = findExpanded();
+    setOverrides((prev) => ({ ...prev, [key]: { expanded: !current } }));
+  }, []);
+
+  const onViewPhase = useCallback((key: ItemKey, phase: ViewHostPhase) => {
+    setPhases((prev) => (prev[key] === phase ? prev : { ...prev, [key]: phase }));
+  }, []);
+
+  // Locator resolution — one read per locator key, misses become "expired".
+  const readerRef = useRef(reader);
+  readerRef.current = reader;
+  const inFlight = useRef(new Set<ItemKey>());
+  useEffect(() => {
+    for (const item of plan.items) {
+      if (item.kind !== "view") continue;
+      if (item.mount === null || item.mount.channel !== "locator") continue;
+      if (resolvedMounts.has(item.key) || inFlight.current.has(item.key)) continue;
+      const read = readerRef.current;
+      const locator = item.mount;
+      inFlight.current.add(item.key);
+      const settle = (value: ResolvedViewMount | "expired"): void => {
+        inFlight.current.delete(item.key);
+        setResolvedMounts((prev) => {
+          const next = new Map(prev);
+          next.set(item.key, value);
+          return next;
+        });
+      };
+      if (read === undefined) {
+        settle("expired");
+        continue;
+      }
+      void resolveViewMount(locator, read).then(
+        (resolved) => settle(resolved ?? "expired"),
+        () => settle("expired"),
+      );
+    }
+  }, [plan, resolvedMounts]);
+
+  return { plan, toggle, overrides, onViewPhase, resolvedMounts };
+}
+
+// ─── useTranscriptInputs (the live assembler) ──────────────────────────────
+
+export interface UseTranscriptInputsResult {
+  inputs: TranscriptInputs;
+  /**
+   * Record the user's action on an R10 prompt (the host performs the
+   * actual grant/decline through its own channel; this moves the
+   * transcript record). A pending prompt whose hook-side request vanishes
+   * without a recorded action reads as `dismissed`.
+   */
+  resolvePrompt: (id: string, state: "answered" | "declined" | "dismissed") => void;
+}
+
+/** How often the escalation clock ticks while a status needs one. */
+const ELAPSED_TICK_MS = 500;
+
+export function useTranscriptInputs(invoke: UseAgentInvokeReturn): UseTranscriptInputsResult {
+  // §4: the elapsed clock is a view-model INPUT — this is the renderer-side
+  // timer that feeds it. Reset on every status change; ticking only while a
+  // status line is showing (R12 escalation + debug detail).
+  const [elapsedMs, setElapsedMs] = useState(0);
+  useEffect(() => {
+    setElapsedMs(0);
+    if (invoke.status === "ready" || invoke.status === "responding") return;
+    const startedAt = Date.now();
+    const timer = setInterval(() => setElapsedMs(Date.now() - startedAt), ELAPSED_TICK_MS);
+    return () => clearInterval(timer);
+  }, [invoke.status]);
+
+  // R10 ledger: the hook exposes only the LATEST pending ask; the
+  // transcript keeps the record of every ask and its resolution.
+  const [prompts, setPrompts] = useState<PromptItemInput[]>([]);
+  const promptSeq = useRef(0);
+  useEffect(() => {
+    const request = invoke.profileConsentRequest;
+    if (request === null) {
+      setPrompts((prev) =>
+        prev.some((p) => p.kind === "consent" && p.state === "pending")
+          ? prev.map((p) =>
+              p.kind === "consent" && p.state === "pending" ? { ...p, state: "dismissed" } : p,
+            )
+          : prev,
+      );
+      return;
+    }
+    setPrompts((prev) => {
+      if (prev.some((p) => p.kind === "consent" && p.state === "pending")) return prev;
+      return [
+        ...prev,
+        {
+          id: `consent.${promptSeq.current++}`,
+          kind: "consent",
+          appId: request.appId,
+          requested: request.requested,
+          state: "pending",
+        },
+      ];
+    });
+  }, [invoke.profileConsentRequest]);
+  useEffect(() => {
+    const request = invoke.profileLinkRequest;
+    if (request === null) {
+      setPrompts((prev) =>
+        prev.some((p) => p.kind === "link" && p.state === "pending")
+          ? prev.map((p) =>
+              p.kind === "link" && p.state === "pending" ? { ...p, state: "dismissed" } : p,
+            )
+          : prev,
+      );
+      return;
+    }
+    setPrompts((prev) => {
+      if (prev.some((p) => p.kind === "link" && p.state === "pending")) return prev;
+      return [
+        ...prev,
+        {
+          id: `link.${promptSeq.current++}`,
+          kind: "link",
+          appId: request.appId,
+          requested: request.requested,
+          state: "pending",
+        },
+      ];
+    });
+  }, [invoke.profileLinkRequest]);
+
+  const resolvePrompt = useCallback(
+    (id: string, state: "answered" | "declined" | "dismissed") => {
+      setPrompts((prev) => prev.map((p) => (p.id === id ? { ...p, state } : p)));
+      // Clearing the hook's pending request AFTER the ledger moved keeps the
+      // dismissal effect above from double-transitioning it.
+      const pending = prompts.find((p) => p.id === id);
+      if (pending?.kind === "consent") invoke.clearProfileConsentRequest();
+      if (pending?.kind === "link") invoke.clearProfileLinkRequest();
+    },
+    [invoke, prompts],
+  );
+
+  const inputs = useMemo<TranscriptInputs>(() => {
+    // Source-ownership split (plan.ts's rules): the trailing assistant
+    // entry is the IN-FLIGHT fold (or the abort-kept partial) — it moves to
+    // `assistantText` so the plan can mark it streaming/stopped; settled
+    // turns stay in `messages`.
+    const inFlight = invoke.status !== "ready";
+    let messages: TranscriptMessage[] = invoke.messages;
+    let assistantText = "";
+    const last = messages[messages.length - 1];
+    if (last !== undefined && last.role === "assistant" && (inFlight || invoke.aborted)) {
+      assistantText = last.text;
+      messages = messages.slice(0, -1);
+    }
+    return {
+      result: invoke.reduceResult,
+      assistantText,
+      status: invoke.status,
+      statusElapsedMs: elapsedMs,
+      activeTool: invoke.activeTool,
+      error: invoke.error !== null ? { message: invoke.error, code: invoke.errorCode } : null,
+      prompts,
+      messages,
+      ...(invoke.historyCards.length > 0 ? { historyCards: invoke.historyCards } : {}),
+      sendStates: invoke.sendStates,
+      aborted: invoke.aborted,
+      adopted: invoke.adopted,
+    };
+  }, [
+    invoke.messages,
+    invoke.status,
+    invoke.activeTool,
+    invoke.error,
+    invoke.errorCode,
+    invoke.reduceResult,
+    invoke.historyCards,
+    invoke.sendStates,
+    invoke.aborted,
+    invoke.adopted,
+    elapsedMs,
+    prompts,
+  ]);
+
+  return { inputs, resolvePrompt };
+}

package/src/react.tsx

@@ -0,0 +1,51 @@
+/**
+ * React entry point (`@guuey/chat/react`) — the component kit over the
+ * root subpath's headless view-model (wave 3b, guuey#135).
+ *
+ * The root subpath stays React-free forever; everything React-coupled —
+ * the per-category components, `<Transcript>`, the renderer-state owner
+ * (`useTranscript`), and the live input assembler (`useTranscriptInputs`)
+ * — lives behind this arm, with `react` as an optional peer (the
+ * mcp-apps-host precedent).
+ *
+ * Composition ladder (spec §1 "configurable"): use `<Transcript>` with the
+ * default kit as-is → override per-category components → tune policy knobs
+ * → drop to `planTranscript` + `attachViewHost` and render it all yourself.
+ */
+export {
+  Transcript,
+  type TranscriptProps,
+  type TranscriptWindowing,
+} from "./react/transcript.js";
+export {
+  defaultTranscriptComponents,
+  renderItem,
+  DefaultUserMessage,
+  DefaultText,
+  DefaultReasoning,
+  DefaultTool,
+  DefaultToolGroup,
+  DefaultDataResult,
+  DefaultView,
+  DefaultMedia,
+  DefaultCode,
+  DefaultCitations,
+  DefaultPrompt,
+  DefaultError,
+  DefaultHistoryBoundary,
+  DefaultCompaction,
+  DefaultUnknown,
+  DefaultStatus,
+  type TranscriptComponents,
+  type TranscriptItemContext,
+} from "./react/components.js";
+export {
+  useTranscript,
+  useTranscriptInputs,
+  type UseTranscriptArgs,
+  type UseTranscriptResult,
+  type UseTranscriptInputsResult,
+} from "./react/use-transcript.js";
+export { GuueyChat, type GuueyChatProps } from "./react/guuey-chat.js";
+export { Markdown } from "./react/markdown.js";
+export { themeCssVars, type ThemeMode } from "./react/theme-css.js";

package/src/strings.ts

@@ -0,0 +1,144 @@
+/**
+ * The ONE place every user-facing string lives — the i18n seam (spec §4.2).
+ *
+ * Builders override any string (or all of them, for a locale) through
+ * `TranscriptPolicy.strings` without forking components; nothing else in the
+ * package carries literal copy. Parameterized strings are functions so word
+ * order stays translatable ("Ran 4 tools" vs "4 Werkzeuge ausgeführt").
+ *
+ * The en defaults below are the founder-review copy from the wave-3a design
+ * (§4.2 + per-row labels; guuey#135 — F7 keeps them wordsmith-able until 3b
+ * freezes the voice).
+ */
+export interface ChatStrings {
+  /** R12 escalation ladder (spec §4.2). */
+  connecting: string;
+  starting: string;
+  longStart: string;
+  thinking: string;
+  usingTool: (toolTitle: string) => string;
+  /** R1 aborted-partial marker + §4.2 aborted line. */
+  stopped: string;
+
+  /** R11 family copy — each is a PREFIX slot for the builder's own wording. */
+  errorAuth: string;
+  errorQuota: string;
+  errorTransient: string;
+  errorInvalid: string;
+
+  /** R3/R4. */
+  toolGroup: (count: number) => string;
+  toolGroupFailures: (count: number) => string;
+  toolDidntFinish: string;
+  /** R4 calm attribution chrome on a display-bearing call ("via {tool}"). */
+  viaTool: (toolTitle: string) => string;
+
+  /** R2. */
+  reasoningLabel: string;
+
+  /** R9. */
+  citations: (count: number) => string;
+
+  /** R15 — the trust invariant's label. */
+  unknownLabel: string;
+
+  /** R14. */
+  compaction: string;
+
+  /** R0. */
+  userCouldntSend: string;
+  userRetry: string;
+
+  /** R6 states. */
+  viewNegotiating: string;
+  viewBootFailure: string;
+  viewInlineFallback: string;
+  viewExpired: string;
+  viewSandboxUnavailable: string;
+
+  /** #192 debug-preset marker (calm never shows it — spec §3, F10). */
+  recoveredFromHistory: string;
+
+  /** R5 empty result. */
+  noOutput: string;
+  /** R5/R15 byte-count note. */
+  bytes: (byteCount: number) => string;
+
+  /** R13 states. */
+  historyLoading: string;
+  threadGone: string;
+
+  /** Renderer chrome (spec §3.2 — the 3b kit's own affordances). */
+  jumpToLatest: string;
+  showEarlier: (count: number) => string;
+  copy: string;
+  copied: string;
+
+  /** The 3c composer (`<GuueyChat>`). */
+  composerPlaceholder: string;
+  composerUnavailable: string;
+  composerLabel: string;
+  send: string;
+  stop: string;
+}
+
+/** Humanize a wire tool name: `render_weather-card` → `render weather card`. */
+export function humanizeToolName(wireName: string): string {
+  return wireName.replace(/[_-]+/g, " ").trim();
+}
+
+export const defaultChatStrings: ChatStrings = {
+  connecting: "Connecting…",
+  starting: "Starting your agent…",
+  longStart: "Starting your agent… first load can take a minute",
+  thinking: "Thinking…",
+  usingTool: (toolTitle) => `Using ${toolTitle}…`,
+  stopped: "Stopped.",
+
+  errorAuth: "Sign in to continue.",
+  errorQuota: "This agent is over its usage limit.",
+  errorTransient: "Something went wrong on our side — try again.",
+  errorInvalid: "The app sent a request the agent couldn't read.",
+
+  toolGroup: (count) => `Ran ${count} tools`,
+  toolGroupFailures: (count) => (count === 1 ? "1 failed" : `${count} failed`),
+  toolDidntFinish: "didn't finish",
+  viaTool: (toolTitle) => `via ${toolTitle}`,
+
+  reasoningLabel: "Thought for a moment",
+
+  citations: (count) => (count === 1 ? "1 source" : `${count} sources`),
+
+  unknownLabel: "Unrecognized content",
+
+  compaction: "Earlier conversation summarized",
+
+  userCouldntSend: "Couldn't send",
+  userRetry: "Retry",
+
+  viewNegotiating: "Loading view…",
+  viewBootFailure: "This view couldn't start",
+  viewInlineFallback: "Showing plain content",
+  viewExpired: "This view expired",
+  viewSandboxUnavailable: "Interactive view unavailable",
+
+  recoveredFromHistory: "recovered from history",
+
+  noOutput: "no output",
+  bytes: (byteCount) =>
+    byteCount >= 1024 ? `${Math.round(byteCount / 1024)} KB` : `${byteCount} B`,
+
+  historyLoading: "Loading conversation…",
+  threadGone: "This conversation is no longer available.",
+
+  jumpToLatest: "Jump to latest",
+  showEarlier: (count) => `Show ${count} earlier`,
+  copy: "Copy",
+  copied: "Copied",
+
+  composerPlaceholder: "Message the agent…",
+  composerUnavailable: "Chat is unavailable.",
+  composerLabel: "Message",
+  send: "Send",
+  stop: "Stop",
+};

package/src/theme.ts

@@ -0,0 +1,195 @@
+/**
+ * Theme = platform data (wave-3a design §6, founder-ratified).
+ *
+ * ONE serializable token schema, four consumers: this package's default
+ * theme, the per-app theme configured on platform.guuey.com (console editor
+ * + app-record field + runtime delivery — a platform-lane slice sharing this
+ * schema), the widget (defaults to the app's configured theme), and portal
+ * (defaults to the GUUEY theme, per-app override).
+ *
+ * EVOLUTION RULE (spec §6): this schema becomes PERSISTED platform data —
+ * changes are additive-only, parsing is LENIENT (unknown keys pass through,
+ * never rejected), and every new token ships with a default-theme fallback.
+ * A stored theme from any earlier schema version must always parse:
+ * `resolveTheme` merges per-token over the default, so a half-configured (or
+ * old-schema) app theme can never produce an unreadable surface.
+ *
+ * The React kit (3b) projects these as `--guuey-chat-*` CSS custom
+ * properties; RN (3c) maps the same object to style values — the schema is
+ * the cross-platform contract, CSS is one projection.
+ */
+import { z } from "zod";
+
+/**
+ * One mode's palette — grounded in the widget's shipped `--guuey-*`
+ * custom-property precedent (`apps/widget/src/app/globals.css`).
+ */
+export const GuueyChatPalette = z
+  .object({
+    accent: z.string(),
+    onAccent: z.string(),
+    ink: z.string(),
+    inkMuted: z.string(),
+    surface: z.string(),
+    canvas: z.string(),
+    canvasMuted: z.string(),
+    error: z.string(),
+  })
+  .loose();
+export type GuueyChatPalette = z.infer<typeof GuueyChatPalette>;
+
+export const GuueyChatTheme = z
+  .object({
+    name: z.string(),
+    /** BOTH palettes always present — mode is the consumer's runtime choice. */
+    colors: z.object({ light: GuueyChatPalette, dark: GuueyChatPalette }).loose(),
+    typography: z
+      .object({
+        fontFamily: z.string().optional(),
+        monoFontFamily: z.string().optional(),
+        scale: z.number().optional(),
+      })
+      .loose(),
+    shape: z
+      .object({
+        radius: z.enum(["none", "soft", "round"]),
+        density: z.enum(["compact", "comfortable"]),
+      })
+      .loose(),
+  })
+  .loose();
+export type GuueyChatTheme = z.infer<typeof GuueyChatTheme>;
+
+/**
+ * The brand-neutral-but-polished package default — the theme a builder gets
+ * before configuring anything, and the per-token fallback floor every other
+ * theme resolves against.
+ */
+export const DEFAULT_CHAT_THEME: GuueyChatTheme = {
+  name: "default",
+  colors: {
+    light: {
+      accent: "#2f6bff",
+      onAccent: "#ffffff",
+      ink: "#111318",
+      inkMuted: "#5b6270",
+      surface: "#ffffff",
+      canvas: "#f7f7f5",
+      canvasMuted: "#eceded",
+      error: "#d64545",
+    },
+    dark: {
+      accent: "#5c8dff",
+      onAccent: "#0b0d12",
+      ink: "#e8e9ee",
+      inkMuted: "#9aa0ac",
+      surface: "#1b1e26",
+      canvas: "#0f1116",
+      canvasMuted: "#1b1e26",
+      error: "#ff6b6b",
+    },
+  },
+  typography: {},
+  shape: { radius: "soft", density: "comfortable" },
+};
+
+/**
+ * The guuey visual identity — portal's default, and the look an app
+ * "unleashes" its own theme against. Values are the widget's shipped
+ * slime/ink/fog tokens verbatim; the saturated accents deliberately do not
+ * change between modes (they read the same on any canvas — the widget's own
+ * documented posture).
+ */
+export const GUUEY_CHAT_THEME: GuueyChatTheme = {
+  name: "guuey",
+  colors: {
+    light: {
+      accent: "#b8ff3a",
+      onAccent: "#0e1014",
+      ink: "#0e1014",
+      inkMuted: "#1a1d24",
+      surface: "#ffffff",
+      canvas: "#f6f5ee",
+      canvasMuted: "#ecebe0",
+      error: "#ff5b5b",
+    },
+    dark: {
+      accent: "#b8ff3a",
+      onAccent: "#0e1014",
+      ink: "#e7e8ec",
+      inkMuted: "#9aa0ac",
+      surface: "#1a1d24",
+      canvas: "#0e1014",
+      canvasMuted: "#1a1d24",
+      error: "#ff5b5b",
+    },
+  },
+  typography: {},
+  shape: { radius: "soft", density: "comfortable" },
+};
+
+/** The candidate shape `resolveTheme` accepts: anything partial, unknown, or stale. */
+const PartialPalette = GuueyChatPalette.partial();
+const PartialTheme = z
+  .object({
+    name: z.string().optional(),
+    colors: z
+      .object({ light: PartialPalette.optional(), dark: PartialPalette.optional() })
+      .loose()
+      .optional(),
+    typography: GuueyChatTheme.shape.typography.optional(),
+    shape: GuueyChatTheme.shape.shape.partial().loose().optional(),
+  })
+  .loose();
+
+/** The known token set — the per-token fallback iterates THIS, so unknown
+ * (future-schema) keys are preserved by the parse but never projected. */
+const PALETTE_TOKENS = [
+  "accent",
+  "onAccent",
+  "ink",
+  "inkMuted",
+  "surface",
+  "canvas",
+  "canvasMuted",
+  "error",
+] as const;
+
+function mergePalette(
+  base: GuueyChatPalette,
+  over: z.infer<typeof PartialPalette> | undefined,
+): GuueyChatPalette {
+  if (!over) return { ...base };
+  const merged: GuueyChatPalette = { ...base };
+  for (const token of PALETTE_TOKENS) {
+    const value = over[token];
+    if (typeof value === "string") merged[token] = value;
+  }
+  return merged;
+}
+
+/**
+ * Resolve a stored (possibly partial, possibly old-schema, possibly not even
+ * object-shaped) theme against a base — per-token fallback, lenient parse.
+ * NEVER throws: unparseable input resolves to the base theme untouched.
+ */
+export function resolveTheme(
+  candidate: unknown,
+  base: GuueyChatTheme = DEFAULT_CHAT_THEME,
+): GuueyChatTheme {
+  const parsed = PartialTheme.safeParse(candidate);
+  if (!parsed.success) return { ...base, colors: { light: { ...base.colors.light }, dark: { ...base.colors.dark } } };
+  const p = parsed.data;
+  return {
+    name: p.name ?? base.name,
+    colors: {
+      light: mergePalette(base.colors.light, p.colors?.light),
+      dark: mergePalette(base.colors.dark, p.colors?.dark),
+    },
+    typography: { ...base.typography, ...(p.typography ?? {}) },
+    shape: {
+      radius: p.shape?.radius ?? base.shape.radius,
+      density: p.shape?.density ?? base.shape.density,
+    },
+  };
+}