@guuey/chat 0.4.0 → 0.6.0

package/src/native/markdown.tsx

@@ -0,0 +1,205 @@
+/**
+ * The R1 markdown surface, React Native projection.
+ *
+ * Same sanitizer boundary as the web kit (`react/markdown.tsx`), same
+ * pipeline: `@silverprotocol/richtext` parses markdown into a TYPED AST in
+ * which raw HTML is structurally unrepresentable — `<script>` in model
+ * output can only ever be literal text, there is no image node type (the
+ * spec's F5 ruling holds structurally), and link `href` is populated
+ * upstream only for http/https/mailto (`SAFE_HREF`). This module is pure
+ * presentation: AST node → themed RN elements. Navigable links open
+ * through `Linking` — the href is already allowlist-gated upstream, so no
+ * second gate is re-derived here.
+ *
+ * Streaming-tolerant by upstream design: an unclosed `**bol` renders as
+ * bold-so-far and completes in place as deltas arrive.
+ *
+ * Prior art: portal's `MarkdownText` (guuey#95) — this is its published,
+ * token-driven descendant (colors/fonts come from the kit's resolved
+ * `NativeChatTokens`, not an app theme context).
+ */
+import type { ReactNode } from "react";
+import { Linking, Text, View } from "react-native";
+import {
+  parseRichText,
+  type RichTextBlock,
+  type RichTextInline,
+} from "@silverprotocol/richtext";
+import type { NativeChatTokens } from "./theme-native.js";
+
+function InlineRuns({
+  nodes,
+  color,
+  tokens,
+  bold,
+  italic,
+}: {
+  nodes: RichTextInline[];
+  color: string;
+  tokens: NativeChatTokens;
+  bold?: boolean;
+  italic?: boolean;
+}): ReactNode {
+  return nodes.map((node, i) => {
+    const baseStyle = {
+      color,
+      fontSize: tokens.fontSize,
+      fontFamily: tokens.fontFamily,
+      fontWeight: bold ? ("700" as const) : ("400" as const),
+      fontStyle: italic ? ("italic" as const) : ("normal" as const),
+    };
+    switch (node.type) {
+      case "text":
+        return (
+          <Text key={i} style={baseStyle}>
+            {node.text}
+          </Text>
+        );
+      case "break":
+        return <Text key={i}>{"\n"}</Text>;
+      case "strong":
+        return (
+          <InlineRuns key={i} nodes={node.children} color={color} tokens={tokens} bold italic={italic} />
+        );
+      case "em":
+        return (
+          <InlineRuns key={i} nodes={node.children} color={color} tokens={tokens} bold={bold} italic />
+        );
+      case "code":
+        return (
+          <Text
+            key={i}
+            style={{
+              color,
+              fontSize: tokens.fontSize - 1,
+              fontFamily: tokens.monoFontFamily,
+              backgroundColor: tokens.palette.canvasMuted,
+            }}
+          >
+            {node.code}
+          </Text>
+        );
+      case "link": {
+        const href = node.href;
+        if (href === undefined) {
+          // Unsafe or unresolvable target: the styled text, no press target.
+          return (
+            <Text key={i} style={{ ...baseStyle, textDecorationLine: "underline" }}>
+              <InlineRuns nodes={node.children} color={color} tokens={tokens} bold={bold} italic={italic} />
+            </Text>
+          );
+        }
+        return (
+          <Text
+            key={i}
+            accessibilityRole="link"
+            style={{ ...baseStyle, color: tokens.palette.accent, textDecorationLine: "underline" }}
+            onPress={() => {
+              void Linking.openURL(href).catch(() => {
+                // An unopenable-but-safe URL is a platform condition, not an error surface.
+              });
+            }}
+          >
+            <InlineRuns nodes={node.children} color={color} tokens={tokens} bold={bold} italic={italic} />
+          </Text>
+        );
+      }
+    }
+  });
+}
+
+function BlockView({
+  block,
+  color,
+  tokens,
+  trailing,
+}: {
+  block: RichTextBlock;
+  color: string;
+  tokens: NativeChatTokens;
+  trailing?: ReactNode;
+}): ReactNode {
+  switch (block.type) {
+    case "paragraph":
+      return (
+        <Text style={{ fontSize: tokens.fontSize, lineHeight: Math.round(tokens.fontSize * 1.45) }}>
+          <InlineRuns nodes={block.children} color={color} tokens={tokens} />
+          {trailing}
+        </Text>
+      );
+    case "heading":
+      return (
+        <Text
+          style={{
+            color,
+            fontSize: tokens.fontSize + (block.level <= 3 ? 2 : 0),
+            fontFamily: tokens.fontFamily,
+            fontWeight: "700",
+          }}
+        >
+          <InlineRuns nodes={block.children} color={color} tokens={tokens} bold />
+          {trailing}
+        </Text>
+      );
+    case "code-fence":
+      return (
+        <View
+          style={{
+            backgroundColor: tokens.palette.canvasMuted,
+            borderRadius: tokens.radius,
+            padding: tokens.pad,
+          }}
+        >
+          <Text style={{ color, fontSize: tokens.fontSize - 2, fontFamily: tokens.monoFontFamily }}>
+            {block.code}
+          </Text>
+          {trailing}
+        </View>
+      );
+    case "list":
+      return (
+        <View style={{ gap: 2 }}>
+          {block.items.map((item, j) => (
+            <View key={j} style={{ flexDirection: "row" }}>
+              <Text style={{ color, fontSize: tokens.fontSize, fontFamily: tokens.fontFamily }}>
+                {block.ordered ? `${(block.start ?? 1) + j}. ` : "•  "}
+              </Text>
+              <Text style={{ flexShrink: 1, fontSize: tokens.fontSize, lineHeight: Math.round(tokens.fontSize * 1.45) }}>
+                <InlineRuns nodes={item.children} color={color} tokens={tokens} />
+                {j === block.items.length - 1 ? trailing : null}
+              </Text>
+            </View>
+          ))}
+        </View>
+      );
+  }
+}
+
+/** Sanitized markdown → themed RN elements (see the module docblock). */
+export function NativeMarkdown({
+  text,
+  color,
+  tokens,
+  trailing,
+}: {
+  text: string;
+  color: string;
+  tokens: NativeChatTokens;
+  /** Appended inside the LAST block so a streaming caret hugs the text. */
+  trailing?: ReactNode;
+}): ReactNode {
+  const blocks = parseRichText(text);
+  return (
+    <View style={{ gap: 6 }}>
+      {blocks.map((block, i) => (
+        <BlockView
+          key={i}
+          block={block}
+          color={color}
+          tokens={tokens}
+          trailing={i === blocks.length - 1 ? trailing : undefined}
+        />
+      ))}
+    </View>
+  );
+}

package/src/native/theme-native.ts

@@ -0,0 +1,48 @@
+/**
+ * The React Native theme projection (spec §6): `GuueyChatTheme` is the
+ * cross-platform contract; CSS custom properties are the WEB projection
+ * (`react/theme-css.ts`), and this module is the native one — the same
+ * schema resolved into a flat token object RN components read as style
+ * values. No new vocabulary: every field here derives from the schema.
+ */
+import { resolveTheme, type GuueyChatPalette, type GuueyChatTheme } from "../theme.js";
+
+export type NativeThemeMode = "light" | "dark";
+
+/** The resolved style tokens the native components consume. */
+export interface NativeChatTokens {
+  /** The mode-resolved palette (per-token fallback already applied). */
+  palette: GuueyChatPalette;
+  /** shape.radius → px: none 0, soft 10, round 18. */
+  radius: number;
+  /** shape.density → the bubble padding / row gap pair. */
+  pad: number;
+  gap: number;
+  /** typography — undefined means the platform default font. */
+  fontFamily: string | undefined;
+  monoFontFamily: string | undefined;
+  /** Base body size in sp, typography.scale applied (default 15). */
+  fontSize: number;
+}
+
+const RADIUS: Record<GuueyChatTheme["shape"]["radius"], number> = {
+  none: 0,
+  soft: 10,
+  round: 18,
+};
+
+/** Resolve a (possibly partial/stale) theme + mode into native tokens. */
+export function resolveNativeTheme(theme: GuueyChatTheme, mode: NativeThemeMode): NativeChatTokens {
+  const resolved = resolveTheme(theme);
+  const palette = resolved.colors[mode];
+  const comfortable = resolved.shape.density === "comfortable";
+  return {
+    palette,
+    radius: RADIUS[resolved.shape.radius],
+    pad: comfortable ? 12 : 8,
+    gap: comfortable ? 10 : 6,
+    fontFamily: resolved.typography.fontFamily,
+    monoFontFamily: resolved.typography.monoFontFamily,
+    fontSize: Math.round(15 * (resolved.typography.scale ?? 1)),
+  };
+}

package/src/native/transcript.tsx

@@ -0,0 +1,189 @@
+/**
+ * `<NativeTranscript>` — the plan walker + the §3.2 renderer obligations,
+ * restated over React Native's own mechanics:
+ *
+ *  - **Scroll contract, the inverted way.** The list is an INVERTED
+ *    FlatList over the reversed plan (the chat-app contract portal's
+ *    agent-chat screen ratified — guuey#94/#100): content grows at the
+ *    scroll ORIGIN, so "stick to bottom while streaming" and "never shift
+ *    the viewport while the reader is up in history" hold by construction
+ *    — no scrollTo calls during streaming, no re-pin race with content
+ *    resize (an R6 card growing at the origin cannot move the reader's
+ *    viewport). "Release on scroll-up" is likewise structural; the kit
+ *    adds the jump-to-latest affordance when the reader has left the
+ *    newest turn, and its scroll animation respects the platform
+ *    reduce-motion setting.
+ *  - **Windowing** is the list primitive's own virtualization — FlatList
+ *    windows the DOM-equivalent natively; the plan's stable keys are the
+ *    `keyExtractor`, so item identity survives streaming updates.
+ *  - **Accessibility** lives on the item components (`components.tsx`).
+ *
+ * Platform chrome (keyboard insets, dismiss modes, dock scroll policies)
+ * stays HOST-OWNED: `listProps` passes the host's FlatList behavior
+ * through, with the kit composing `onScroll` so both the host's policy and
+ * the jump affordance see every event. The kit owns data/renderItem/keys/
+ * inversion — a host overriding those would be fighting the plan.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState, type ReactNode } from "react";
+import {
+  AccessibilityInfo,
+  FlatList,
+  Pressable,
+  Text,
+  View,
+  type FlatListProps,
+  type NativeScrollEvent,
+  type NativeSyntheticEvent,
+} from "react-native";
+import { DEFAULT_CHAT_THEME, type GuueyChatTheme } from "../theme.js";
+import { defaultChatStrings, type ChatStrings } from "../strings.js";
+import type { DisplayItem, TranscriptPlan } from "../types.js";
+import {
+  nativeTranscriptComponents,
+  renderNativeItem,
+  type NativeTranscriptComponents,
+  type NativeTranscriptItemContext,
+} from "./components.js";
+import { resolveNativeTheme, type NativeThemeMode } from "./theme-native.js";
+
+/** Offset (px) past which the reader counts as "up in history". */
+const JUMP_THRESHOLD_PX = 160;
+
+/** The host-behavior pass-through — everything the kit deliberately does NOT own. */
+export type NativeTranscriptListProps = Pick<
+  FlatListProps<DisplayItem>,
+  | "style"
+  | "contentContainerStyle"
+  | "keyboardDismissMode"
+  | "keyboardShouldPersistTaps"
+  | "automaticallyAdjustKeyboardInsets"
+  | "onScroll"
+  | "scrollEventThrottle"
+  | "ListEmptyComponent"
+  | "scrollIndicatorInsets"
+>;
+
+export interface NativeTranscriptProps
+  extends Pick<
+    NativeTranscriptItemContext,
+    "onToggle" | "onRetry" | "onPromptAction" | "onErrorAction" | "resolvedMounts" | "onViewPhase" | "onViewRef"
+  > {
+  plan: TranscriptPlan;
+  /** Per-slot component overrides (spec §3's override column). */
+  components?: Partial<NativeTranscriptComponents>;
+  /** The i18n seam — pass the same strings the policy carries. */
+  strings?: ChatStrings;
+  theme?: GuueyChatTheme;
+  mode?: NativeThemeMode;
+  /** Host-owned FlatList behavior (keyboard/scroll chrome). */
+  listProps?: NativeTranscriptListProps;
+}
+
+export function NativeTranscript(props: NativeTranscriptProps): ReactNode {
+  const {
+    plan,
+    components,
+    strings = defaultChatStrings,
+    theme = DEFAULT_CHAT_THEME,
+    mode = "light",
+    listProps,
+    onToggle,
+    onRetry,
+    onPromptAction,
+    onErrorAction,
+    resolvedMounts,
+    onViewPhase,
+    onViewRef,
+  } = props;
+
+  const tokens = useMemo(() => resolveNativeTheme(theme, mode), [theme, mode]);
+  const resolvedComponents: NativeTranscriptComponents = useMemo(
+    () => ({ ...nativeTranscriptComponents, ...components }),
+    [components],
+  );
+  const ctx: NativeTranscriptItemContext = useMemo(
+    () => ({ strings, tokens, onToggle, onRetry, onPromptAction, onErrorAction, resolvedMounts, onViewPhase, onViewRef }),
+    [strings, tokens, onToggle, onRetry, onPromptAction, onErrorAction, resolvedMounts, onViewPhase, onViewRef],
+  );
+
+  // Inverted-list data: reversed plan, newest at index 0 (the visual
+  // bottom / scroll origin). Keys are the plan's stable keys.
+  const data = useMemo(() => [...plan.items].reverse(), [plan.items]);
+
+  // Reduce motion: the ONE animation the kit owns is the jump scroll.
+  const [reduceMotion, setReduceMotion] = useState(false);
+  useEffect(() => {
+    let alive = true;
+    void AccessibilityInfo.isReduceMotionEnabled().then((v) => {
+      if (alive) setReduceMotion(v);
+    });
+    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", setReduceMotion);
+    return () => {
+      alive = false;
+      sub.remove();
+    };
+  }, []);
+
+  const listRef = useRef<FlatList<DisplayItem>>(null);
+  const [showJump, setShowJump] = useState(false);
+  const hostOnScroll = listProps?.onScroll;
+  const onScroll = useCallback(
+    (e: NativeSyntheticEvent<NativeScrollEvent>) => {
+      // Inverted coordinates: offset 0 IS the newest turn.
+      setShowJump(e.nativeEvent.contentOffset.y > JUMP_THRESHOLD_PX);
+      hostOnScroll?.(e);
+    },
+    [hostOnScroll],
+  );
+
+  const StatusComponent = resolvedComponents.status;
+
+  return (
+    <View style={{ flex: 1, backgroundColor: tokens.palette.canvas }}>
+      <FlatList
+        ref={listRef}
+        {...listProps}
+        onScroll={onScroll}
+        scrollEventThrottle={listProps?.scrollEventThrottle ?? 16}
+        // Inverted only while non-empty: an inverted ListEmptyComponent
+        // renders upside-down (RN gotcha — portal's receipt).
+        inverted={data.length > 0}
+        data={data}
+        keyExtractor={(item) => item.key}
+        renderItem={({ item }) => (
+          <View style={{ paddingVertical: tokens.gap / 2 }}>
+            {renderNativeItem(item, resolvedComponents, ctx)}
+          </View>
+        )}
+        // Inverted list: the header renders at the VISUAL BOTTOM — where
+        // the live status line belongs.
+        ListHeaderComponent={
+          plan.status !== null ? <StatusComponent item={plan.status} ctx={ctx} /> : null
+        }
+      />
+      {showJump ? (
+        <Pressable
+          accessibilityRole="button"
+          onPress={() => {
+            setShowJump(false);
+            listRef.current?.scrollToOffset({ offset: 0, animated: !reduceMotion });
+          }}
+          style={{
+            position: "absolute",
+            bottom: 12,
+            alignSelf: "center",
+            backgroundColor: tokens.palette.surface,
+            borderRadius: 999,
+            paddingHorizontal: 14,
+            paddingVertical: 8,
+            elevation: 3,
+          }}
+        >
+          <Text style={{ color: tokens.palette.ink, fontSize: tokens.fontSize - 2, fontFamily: tokens.fontFamily }}>
+            {strings.jumpToLatest}
+          </Text>
+        </Pressable>
+      ) : null}
+    </View>
+  );
+}

package/src/native.tsx

@@ -0,0 +1,63 @@
+/**
+ * React Native entry point (`@guuey/chat/native`) — the RN renderer over
+ * the SAME headless view-model as `./react` (wave 3c, guuey#135).
+ *
+ * Zero duplication by construction: the view-model, policies, theme
+ * schema, and strings are the root subpath's exports, and the
+ * renderer-state hooks (`useTranscript`, `useTranscriptInputs`) are the
+ * SAME modules the web kit uses — they are React-generic (no DOM), so both
+ * arms share one implementation. Only the walk differs: RN primitives, the
+ * inverted-list scroll contract, and the schema's native theme projection
+ * (`resolveNativeTheme` — CSS custom properties are the web projection).
+ *
+ * The R6 default is the documented native default-gap: this tier ships
+ * WITHOUT a WebView dependency, so `view` is a required override (a
+ * labeled placeholder renders otherwise — never blank). See
+ * `native/components.tsx`.
+ *
+ * `react` and `react-native` are OPTIONAL peers — the root subpath stays
+ * importable everywhere; this arm loads only inside an RN runtime.
+ */
+export {
+  NativeTranscript,
+  type NativeTranscriptProps,
+  type NativeTranscriptListProps,
+} from "./native/transcript.js";
+export {
+  nativeTranscriptComponents,
+  renderNativeItem,
+  NativeUserMessage,
+  NativeText,
+  NativeReasoning,
+  NativeTool,
+  NativeToolGroup,
+  NativeDataResult,
+  NativeView,
+  NativeViewRef,
+  NativeMedia,
+  NativeCode,
+  NativeCitations,
+  NativePrompt,
+  NativeError,
+  NativeHistoryBoundary,
+  NativeCompaction,
+  NativeUnknown,
+  NativeStatus,
+  type NativeTranscriptComponents,
+  type NativeTranscriptItemContext,
+} from "./native/components.js";
+export { NativeMarkdown } from "./native/markdown.js";
+export {
+  resolveNativeTheme,
+  type NativeChatTokens,
+  type NativeThemeMode,
+} from "./native/theme-native.js";
+// The React-generic renderer-state owner + live assembler — shared with
+// the web kit (one implementation, two walks).
+export {
+  useTranscript,
+  useTranscriptInputs,
+  type UseTranscriptArgs,
+  type UseTranscriptResult,
+  type UseTranscriptInputsResult,
+} from "./react/use-transcript.js";