@guuey/chat 0.4.0

package/src/react/guuey-chat.tsx

@@ -0,0 +1,227 @@
+/**
+ * `<GuueyChat>` — the batteries-included surface (guuey#135 wave 3c): the
+ * whole tier stack wired end to end, PLUS the composer (which arrives here
+ * per the founder ruling — earlier tiers are transcript-only).
+ *
+ *     useAgentInvoke → useTranscriptInputs → useTranscript → <Transcript>
+ *                                                          + the composer
+ *
+ * It is a THIN composition of the exported tiers — every wire below is a
+ * public API, so a builder ejects one level down (own composer around
+ * `<Transcript>`, own renderer over `planTranscript`, own everything over
+ * `invokeTurn`) without a cliff. Every prop beyond the connection
+ * essentials is optional.
+ *
+ * ## Composer state matrix
+ *
+ * - `endpointUrl === null` → input disabled, `composerUnavailable`
+ *   placeholder (chat cannot exist).
+ * - idle (`status === "ready"`) → input enabled; **Send** enabled iff the
+ *   input has non-whitespace text.
+ * - in flight (any other status, cold-start waits included — R12's status
+ *   line owns the WHY) → input stays enabled (type the next message while
+ *   the agent works), Send is replaced by **Stop**, which aborts the turn
+ *   (partial text kept, "Stopped." marked — the hook's contract).
+ * - Enter sends; Shift+Enter inserts a newline; an IME-composing Enter
+ *   never sends (the candidate commit is not a submit).
+ *
+ * ## History
+ *
+ * Thread rehydration is the HOOK's mechanics: give `adapters` a `history`
+ * adapter (e.g. `createWebAdapters({ apiBaseUrl, … })`) and a persisted
+ * threadId rehydrates on mount — text transcript + persisted cards, which
+ * mount through the same R6 path as live views. Nothing here to configure.
+ */
+import { useCallback, useMemo, useState, type CSSProperties, type ReactNode } from "react";
+import { createWebAdapters, type AgentInvokeAdapters } from "@guuey/agent-client";
+import { useAgentInvoke } from "@guuey/agent-client/react";
+import type { UiResourceReader } from "@guuey/mcp-apps-host";
+import { calmPolicy, debugPolicy, type TranscriptPolicy } from "../policy.js";
+import { defaultChatStrings, type ChatStrings } from "../strings.js";
+import { DEFAULT_CHAT_THEME, type GuueyChatTheme } from "../theme.js";
+import type { ErrorItem, PromptItem, UserMessageItem } from "../types.js";
+import type { ThemeMode } from "./theme-css.js";
+import { Transcript, type TranscriptWindowing } from "./transcript.js";
+import type { TranscriptComponents, TranscriptItemContext } from "./components.js";
+import { useTranscript, useTranscriptInputs } from "./use-transcript.js";
+
+export interface GuueyChatProps {
+  /** Pod base URL (with or without `/agent/invoke`). `null` disables chat. */
+  endpointUrl: string | null;
+  /** Owning app id — namespaces the persisted threadId. */
+  appId?: string;
+  /**
+   * Host couplings (storage / id / transport / history). Default:
+   * `createWebAdapters()` — localStorage thread persistence + the web SSE
+   * transport (cookie/guest identity, saturation + cold-start retries).
+   */
+  adapters?: AgentInvokeAdapters;
+  /** Policy preset (spec §5). Default `"calm"`. */
+  preset?: "calm" | "debug";
+  /** Knob overrides applied on top of the preset (spec §3's columns). */
+  policy?: Partial<TranscriptPolicy>;
+  /** Per-slot component overrides (spec §3's override column). */
+  components?: Partial<TranscriptComponents>;
+  /** String overrides — merged over the preset's `ChatStrings` (§4.2). */
+  strings?: Partial<ChatStrings>;
+  theme?: GuueyChatTheme;
+  mode?: ThemeMode;
+  /** DOM windowing (§3.2). `false` renders everything. */
+  window?: TranscriptWindowing | false;
+  /** R6 locator resolution (history cards). See `useTranscript`. */
+  reader?: UiResourceReader;
+  /** R6 pass-through (relay hook, sandbox page/flags, host context…). */
+  viewProps?: TranscriptItemContext["viewProps"];
+  /**
+   * R10: what accept/decline actually DO (the grant channel is the host's).
+   * The transcript record moves regardless; without a handler the prompt
+   * card is record-only.
+   */
+  onPromptAction?: (item: PromptItem, action: "accept" | "decline" | "dismiss") => void;
+  /** R11 action slot (sign-in / retry affordances). */
+  onErrorAction?: (item: ErrorItem) => void;
+  className?: string;
+  style?: CSSProperties;
+}
+
+const PROMPT_STATE = {
+  accept: "answered",
+  decline: "declined",
+  dismiss: "dismissed",
+} as const;
+
+export function GuueyChat(props: GuueyChatProps): ReactNode {
+  const {
+    endpointUrl,
+    appId,
+    adapters: adaptersProp,
+    preset = "calm",
+    policy: policyOverrides,
+    components,
+    strings: stringOverrides,
+    theme = DEFAULT_CHAT_THEME,
+    mode = "light",
+    window: windowing,
+    reader,
+    viewProps,
+    onPromptAction,
+    onErrorAction,
+    className,
+    style,
+  } = props;
+
+  const adapters = useMemo(() => adaptersProp ?? createWebAdapters(), [adaptersProp]);
+  const invoke = useAgentInvoke({ endpointUrl, ...(appId !== undefined ? { appId } : {}), adapters, preserveBlocks: true });
+
+  const policy = useMemo(() => {
+    const factory = preset === "debug" ? debugPolicy : calmPolicy;
+    const strings: ChatStrings = {
+      ...defaultChatStrings,
+      ...policyOverrides?.strings,
+      ...stringOverrides,
+    };
+    return factory({ ...policyOverrides, strings });
+  }, [preset, policyOverrides, stringOverrides]);
+
+  const { inputs, resolvePrompt } = useTranscriptInputs(invoke);
+  const { plan, toggle, resolvedMounts, onViewPhase } = useTranscript({
+    inputs,
+    policy,
+    ...(reader !== undefined ? { reader } : {}),
+  });
+
+  // ── Composer ─────────────────────────────────────────────────────────
+  const [input, setInput] = useState("");
+  const busy = invoke.status !== "ready";
+  const available = endpointUrl !== null;
+  const canSend = available && !busy && input.trim() !== "";
+
+  const submit = useCallback((): void => {
+    const text = input.trim();
+    if (text === "" || !available || busy) return;
+    setInput("");
+    void invoke.send(text).catch(() => {
+      // The hook surfaces the failure (`error` / R0 failed-send).
+    });
+  }, [input, available, busy, invoke]);
+
+  const handleRetry = useCallback(
+    (item: UserMessageItem) => {
+      void invoke.send(item.text).catch(() => {
+        // Same contract as submit: the hook owns failure surfacing.
+      });
+    },
+    [invoke],
+  );
+
+  const handlePromptAction = useCallback(
+    (item: PromptItem, action: "accept" | "decline" | "dismiss") => {
+      resolvePrompt(item.promptId, PROMPT_STATE[action]);
+      onPromptAction?.(item, action);
+    },
+    [resolvePrompt, onPromptAction],
+  );
+
+  const strings = policy.strings;
+
+  return (
+    <div
+      className={`guuey-chat-surface${className !== undefined ? ` ${className}` : ""}`}
+      style={style}
+    >
+      <Transcript
+        plan={plan}
+        strings={strings}
+        theme={theme}
+        mode={mode}
+        {...(windowing !== undefined ? { window: windowing } : {})}
+        {...(components !== undefined ? { components } : {})}
+        onToggle={toggle}
+        onRetry={handleRetry}
+        onPromptAction={handlePromptAction}
+        {...(onErrorAction !== undefined ? { onErrorAction } : {})}
+        resolvedMounts={resolvedMounts}
+        onViewPhase={onViewPhase}
+        {...(viewProps !== undefined ? { viewProps } : {})}
+      />
+      <form
+        className="guuey-chat-composer"
+        onSubmit={(e) => {
+          e.preventDefault();
+          submit();
+        }}
+      >
+        <textarea
+          className="guuey-chat-composer-input"
+          rows={1}
+          value={input}
+          onChange={(e) => setInput(e.target.value)}
+          onKeyDown={(e) => {
+            // `isComposing` guards IME input: an Enter that commits a
+            // candidate must not also send the message.
+            if (e.key === "Enter" && !e.shiftKey && !e.nativeEvent.isComposing) {
+              e.preventDefault();
+              submit();
+            }
+          }}
+          disabled={!available}
+          aria-label={strings.composerLabel}
+          placeholder={available ? strings.composerPlaceholder : strings.composerUnavailable}
+        />
+        {busy ? (
+          <button
+            type="button"
+            className="guuey-chat-composer-stop"
+            onClick={() => invoke.abort()}
+          >
+            {strings.stop}
+          </button>
+        ) : (
+          <button type="submit" className="guuey-chat-composer-send" disabled={!canSend}>
+            {strings.send}
+          </button>
+        )}
+      </form>
+    </div>
+  );
+}

package/src/react/markdown.tsx

@@ -0,0 +1,114 @@
+/**
+ * The R1 markdown surface — the ONE place `@guuey/chat` renders
+ * agent-influenced content in the embedder's origin, and therefore the
+ * package's sanitizer boundary (spec §3.1).
+ *
+ * The pipeline is `@silverprotocol/richtext`: markdown → a TYPED AST in
+ * which raw HTML is structurally unrepresentable (no HTML node type
+ * exists; angle brackets can only ever be literal text) → React elements.
+ * That is deliberately STRONGER than the spec's letter (markdown → HTML →
+ * sanitize): there is no HTML string at any point, so there is nothing to
+ * sanitize incorrectly — no `dangerouslySetInnerHTML` anywhere in this
+ * package.
+ *
+ * Safety properties, each pinned by a test:
+ *  - raw HTML (`<img onerror=…>`, `<script>`) renders as literal text;
+ *  - link `href` is populated upstream ONLY for http/https/mailto —
+ *    `javascript:`, `data:`, `vbscript:`, and relative targets parse as
+ *    styled text with NO anchor `href` (richtext's `SAFE_HREF` allowlist);
+ *  - navigable links carry `rel="noopener noreferrer" target="_blank"`;
+ *  - there is NO image syntax in the node vocabulary at all — the spec's
+ *    F5 ruling (markdown images off; R7 media blocks are the sanctioned
+ *    image path) holds structurally, not by configuration.
+ *
+ * Streaming-tolerant by upstream design: unclosed emphasis mid-delta
+ * renders as formatted-so-far.
+ */
+import type { ReactNode } from "react";
+import {
+  parseRichText,
+  type RichTextBlock,
+  type RichTextInline,
+} from "@silverprotocol/richtext";
+
+function Inline({ nodes }: { nodes: RichTextInline[] }): ReactNode {
+  return nodes.map((node, i) => {
+    switch (node.type) {
+      case "text":
+        return <span key={i}>{node.text}</span>;
+      case "break":
+        return <br key={i} />;
+      case "strong":
+        return (
+          <strong key={i}>
+            <Inline nodes={node.children} />
+          </strong>
+        );
+      case "em":
+        return (
+          <em key={i}>
+            <Inline nodes={node.children} />
+          </em>
+        );
+      case "code":
+        return (
+          <code key={i} className="guuey-chat-inline-code">
+            {node.code}
+          </code>
+        );
+      case "link":
+        return node.href ? (
+          <a key={i} href={node.href} target="_blank" rel="noopener noreferrer">
+            <Inline nodes={node.children} />
+          </a>
+        ) : (
+          // Unsafe or unresolvable target: the styled text, no anchor.
+          <span key={i} className="guuey-chat-dead-link">
+            <Inline nodes={node.children} />
+          </span>
+        );
+    }
+  });
+}
+
+function Block({ block }: { block: RichTextBlock }): ReactNode {
+  switch (block.type) {
+    case "paragraph":
+      return (
+        <p>
+          <Inline nodes={block.children} />
+        </p>
+      );
+    case "heading":
+      return (
+        <p className={`guuey-chat-heading${block.level <= 3 ? " guuey-chat-heading-major" : ""}`}>
+          <Inline nodes={block.children} />
+        </p>
+      );
+    case "code-fence":
+      return <pre className="guuey-chat-code-fence">{block.code}</pre>;
+    case "list": {
+      const Tag = block.ordered ? "ol" : "ul";
+      return (
+        <Tag {...(block.ordered && block.start !== undefined ? { start: block.start } : {})}>
+          {block.items.map((item, j) => (
+            <li key={j}>
+              <Inline nodes={item.children} />
+            </li>
+          ))}
+        </Tag>
+      );
+    }
+  }
+}
+
+/** Sanitized markdown → React elements (see the module docblock). */
+export function Markdown({ text }: { text: string }): ReactNode {
+  return (
+    <>
+      {parseRichText(text).map((block, i) => (
+        <Block key={i} block={block} />
+      ))}
+    </>
+  );
+}

package/src/react/theme-css.ts

@@ -0,0 +1,50 @@
+/**
+ * The CSS projection of `GuueyChatTheme` (spec §6): the schema is the
+ * cross-platform contract; this maps one mode's tokens onto the
+ * `--guuey-chat-*` custom properties the shipped stylesheet consumes. RN
+ * (3c) maps the same object to style values instead — no CSS here is
+ * load-bearing for the view-model.
+ */
+import type { GuueyChatTheme } from "../theme.js";
+
+export type ThemeMode = "light" | "dark";
+
+const RADIUS_PX: Record<GuueyChatTheme["shape"]["radius"], string> = {
+  none: "0px",
+  soft: "10px",
+  round: "18px",
+};
+
+const DENSITY_GAP: Record<GuueyChatTheme["shape"]["density"], string> = {
+  compact: "6px",
+  comfortable: "10px",
+};
+
+/**
+ * One mode's tokens as inline custom properties for the transcript root.
+ * Returned as a plain record so callers can spread it into `style` or emit
+ * a stylesheet from it.
+ */
+export function themeCssVars(theme: GuueyChatTheme, mode: ThemeMode): Record<string, string> {
+  const palette = theme.colors[mode];
+  const vars: Record<string, string> = {
+    "--guuey-chat-accent": palette.accent,
+    "--guuey-chat-on-accent": palette.onAccent,
+    "--guuey-chat-ink": palette.ink,
+    "--guuey-chat-ink-muted": palette.inkMuted,
+    "--guuey-chat-surface": palette.surface,
+    "--guuey-chat-canvas": palette.canvas,
+    "--guuey-chat-canvas-muted": palette.canvasMuted,
+    "--guuey-chat-error": palette.error,
+    "--guuey-chat-radius": RADIUS_PX[theme.shape.radius],
+    "--guuey-chat-gap": DENSITY_GAP[theme.shape.density],
+    "--guuey-chat-scale": String(theme.typography.scale ?? 1),
+  };
+  if (theme.typography.fontFamily !== undefined) {
+    vars["--guuey-chat-font"] = theme.typography.fontFamily;
+  }
+  if (theme.typography.monoFontFamily !== undefined) {
+    vars["--guuey-chat-mono-font"] = theme.typography.monoFontFamily;
+  }
+  return vars;
+}

package/src/react/transcript.tsx

@@ -0,0 +1,187 @@
+/**
+ * `<Transcript>` — the plan walker + the §3.2 renderer obligations:
+ *
+ *  - **Scroll contract:** stick-to-bottom while content grows UNLESS the
+ *    user scrolled up, in which case a "jump to latest" affordance appears
+ *    instead; anchoring holds through content resize (a ResizeObserver on
+ *    the item column re-pins — R6 cards growing on `connected` are the
+ *    canonical breaker). `prefers-reduced-motion` downgrades smooth
+ *    scrolling to instant.
+ *  - **Windowing:** long transcripts render the trailing `window.tail`
+ *    items with a "show earlier" expander — the DOM is capped even though
+ *    the plan (already O(groups)) carries everything; the plan's stable
+ *    keys keep expansion state and DOM identity across the window edge.
+ *  - Theme: the resolved `GuueyChatTheme` is projected as `--guuey-chat-*`
+ *    custom properties on the root (import `@guuey/chat/styles.css` once
+ *    for the default look, or restyle the class names entirely).
+ */
+import {
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  type CSSProperties,
+  type ReactNode,
+} from "react";
+import { DEFAULT_CHAT_THEME, type GuueyChatTheme } from "../theme.js";
+import { defaultChatStrings, type ChatStrings } from "../strings.js";
+import type { TranscriptPlan } from "../types.js";
+import {
+  defaultTranscriptComponents,
+  renderItem,
+  type TranscriptComponents,
+  type TranscriptItemContext,
+} from "./components.js";
+import { themeCssVars, type ThemeMode } from "./theme-css.js";
+
+/** How close to the bottom (px) still counts as pinned. */
+const PIN_THRESHOLD_PX = 48;
+
+export interface TranscriptWindowing {
+  /** Trailing items rendered; earlier ones sit behind the expander. */
+  tail: number;
+}
+
+export interface TranscriptProps
+  extends Pick<
+    TranscriptItemContext,
+    "onToggle" | "onRetry" | "onPromptAction" | "onErrorAction" | "resolvedMounts" | "onViewPhase" | "viewProps"
+  > {
+  plan: TranscriptPlan;
+  /** Per-slot component overrides (spec §3's override column). */
+  components?: Partial<TranscriptComponents>;
+  /** The i18n seam — pass the same strings the policy carries. */
+  strings?: ChatStrings;
+  theme?: GuueyChatTheme;
+  mode?: ThemeMode;
+  /** DOM windowing (§3.2). `false` renders everything. Default tail 80. */
+  window?: TranscriptWindowing | false;
+  className?: string;
+  style?: CSSProperties;
+}
+
+export function Transcript(props: TranscriptProps): ReactNode {
+  const {
+    plan,
+    components,
+    strings = defaultChatStrings,
+    theme = DEFAULT_CHAT_THEME,
+    mode = "light",
+    window: windowing = { tail: 80 },
+    className,
+    style,
+    onToggle,
+    onRetry,
+    onPromptAction,
+    onErrorAction,
+    resolvedMounts,
+    onViewPhase,
+    viewProps,
+  } = props;
+
+  const resolvedComponents: TranscriptComponents = useMemo(
+    () => ({ ...defaultTranscriptComponents, ...components }),
+    [components],
+  );
+  const ctx: TranscriptItemContext = useMemo(
+    () => ({ strings, onToggle, onRetry, onPromptAction, onErrorAction, resolvedMounts, onViewPhase, viewProps }),
+    [strings, onToggle, onRetry, onPromptAction, onErrorAction, resolvedMounts, onViewPhase, viewProps],
+  );
+
+  // ── Windowing ────────────────────────────────────────────────────────
+  const [extraShown, setExtraShown] = useState(0);
+  const tail = windowing === false ? Number.POSITIVE_INFINITY : windowing.tail;
+  const visibleFrom = Math.max(0, plan.items.length - tail - extraShown);
+  const hidden = visibleFrom;
+  const visible = plan.items.slice(visibleFrom);
+
+  // ── Scroll contract ──────────────────────────────────────────────────
+  const scroller = useRef<HTMLDivElement>(null);
+  const column = useRef<HTMLDivElement>(null);
+  const pinned = useRef(true);
+  const [showJump, setShowJump] = useState(false);
+
+  const reducedMotion = (): boolean =>
+    typeof matchMedia === "function" && matchMedia("(prefers-reduced-motion: reduce)").matches;
+
+  const scrollToBottom = (smooth: boolean): void => {
+    const el = scroller.current;
+    if (el === null) return;
+    if (typeof el.scrollTo === "function") {
+      el.scrollTo({ top: el.scrollHeight, behavior: smooth && !reducedMotion() ? "smooth" : "auto" });
+    } else {
+      // Environments without Element.scrollTo (jsdom; ancient WebViews).
+      el.scrollTop = el.scrollHeight;
+    }
+  };
+
+  const onScroll = (): void => {
+    const el = scroller.current;
+    if (el === null) return;
+    const nearBottom = el.scrollHeight - el.scrollTop - el.clientHeight < PIN_THRESHOLD_PX;
+    pinned.current = nearBottom;
+    setShowJump(!nearBottom);
+  };
+
+  // New content while pinned keeps the bottom in view (before paint, so
+  // per-frame streaming updates never visibly jump).
+  useLayoutEffect(() => {
+    if (pinned.current) scrollToBottom(false);
+  }, [plan]);
+
+  // Content RESIZE (an R6 card connecting and growing, an image loading)
+  // re-pins too — scrollHeight changes with no plan change.
+  useEffect(() => {
+    const el = column.current;
+    if (el === null || typeof ResizeObserver === "undefined") return;
+    const observer = new ResizeObserver(() => {
+      if (pinned.current) scrollToBottom(false);
+    });
+    observer.observe(el);
+    return () => observer.disconnect();
+  }, []);
+
+  const rootStyle: CSSProperties = { ...themeCssVars(theme, mode), ...style };
+
+  const StatusComponent = resolvedComponents.status;
+
+  return (
+    <div
+      className={`guuey-chat${className !== undefined ? ` ${className}` : ""}`}
+      style={rootStyle}
+      data-guuey-chat-mode={mode}
+    >
+      <div ref={scroller} className="guuey-chat-scroller" onScroll={onScroll}>
+        <div ref={column} className="guuey-chat-column">
+          {hidden > 0 ? (
+            <button
+              type="button"
+              className="guuey-chat-show-earlier"
+              onClick={() => setExtraShown((n) => n + tail)}
+            >
+              {strings.showEarlier(hidden)}
+            </button>
+          ) : null}
+          {visible.map((item) => renderItem(item, resolvedComponents, ctx))}
+          {plan.status !== null ? (
+            <StatusComponent item={plan.status} ctx={ctx} />
+          ) : null}
+        </div>
+      </div>
+      {showJump ? (
+        <button
+          type="button"
+          className="guuey-chat-jump"
+          onClick={() => {
+            pinned.current = true;
+            setShowJump(false);
+            scrollToBottom(true);
+          }}
+        >
+          {strings.jumpToLatest}
+        </button>
+      ) : null}
+    </div>
+  );
+}