@pinagent/react-native 0.2.4 → 0.2.5

package/src/native/keyboard.ts

@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Keyboard-shortcut helpers for the React Native widget.
+ *
+ * The browser widget wires its hotkeys to `document`-level `keydown`
+ * listeners (see packages/widget/src/keyboard.ts). React Native has no such
+ * global key stream in JS: the core `Keyboard` module only reports the soft
+ * keyboard showing/hiding, never key presses, and there's no document to
+ * listen on. A faithful port of the *global* web hotkeys (toggle picker,
+ * hop-to-next-agent, minimize-all) would need a native module — iOS
+ * `UIKeyCommand` / an Android key bridge — which we deliberately avoid: the RN
+ * widget ships as plain JS source for Metro with zero native setup.
+ *
+ * What IS reachable, and all we need in practice, are the key events a focused
+ * `TextInput` surfaces — so the shortcuts live where a hardware keyboard is
+ * actually in play (the composer and the stream sheet, both modal):
+ *   - Return/Enter, via `onSubmitEditing` on the single-line inputs — submits
+ *     the agent answer and the follow-up, mirroring the web composer's
+ *     Enter-to-send. Wired directly on the input (no key inspection needed).
+ *   - Escape, via `onKeyPress` — backs out of a sheet, mirroring the web
+ *     widget's Escape. Decided here so the (RN-runtime-only, untestable)
+ *     components stay thin and the rule is unit-tested.
+ *
+ * `onKeyPress`'s `nativeEvent` only carries `key` on native platforms (no
+ * modifier flags), so these predicates take the bare key name — there's no
+ * Shift/Cmd to branch on, which is also why plain Enter stays a newline in the
+ * multiline composer rather than hijacking submit. Hardware Back (Android) is
+ * handled separately by each Modal's `onRequestClose`.
+ */
+
+/**
+ * Should this key event back out of the current sheet? Escape on a hardware
+ * keyboard — the RN analog of the web widget's Escape. Only the Escape key
+ * qualifies; every printable key (i.e. normal typing) is ignored, so an
+ * `onKeyPress` handler built on this never interferes with text entry.
+ */
+export function isDismissKey(key: string): boolean {
+  return key === 'Escape';
+}

package/src/native/markdown.ts

@@ -0,0 +1,194 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Tiny, dependency-free Markdown parser for the RN widget.
+ *
+ * The agent streams its replies as Markdown — Claude writes **bold**, `code`,
+ * fenced blocks, bullet/numbered lists, headings and links. The StreamSheet
+ * used to drop that straight into a <Text>, so the markers showed up as
+ * literal characters. This module folds the raw text into a small block/inline
+ * tree that `Markdown.tsx` renders with React Native primitives — no
+ * markdown-it, no extra runtime dependency, in keeping with the rest of the
+ * native source (see transcript.ts for the same "mirror, don't import" stance).
+ *
+ * It is intentionally a *subset* of CommonMark covering what shows up in chat:
+ * ATX headings, fenced code, blockquotes, unordered/ordered lists, thematic
+ * breaks, paragraphs, and inline code / bold / italic / links. Anything it
+ * doesn't recognise falls through as plain text, so the worst case degrades to
+ * the old behaviour rather than dropping content. Pure and deterministic, so
+ * it's unit-tested like the transcript reducer.
+ */
+
+/** An inline run carrying at most the marks we render. */
+export interface InlineSpan {
+  text: string;
+  bold?: boolean;
+  italic?: boolean;
+  code?: boolean;
+  /** Present on link spans; the destination URL. */
+  href?: string;
+}
+
+export type MdBlock =
+  | { type: 'heading'; level: number; spans: InlineSpan[] }
+  | { type: 'paragraph'; spans: InlineSpan[] }
+  | { type: 'code'; text: string; lang?: string }
+  | { type: 'list'; ordered: boolean; items: InlineSpan[][] }
+  | { type: 'quote'; spans: InlineSpan[] }
+  | { type: 'hr' };
+
+/**
+ * Inline scanner: walk the string and, at each step, take the earliest of the
+ * recognised markers — ties broken by priority (code > link > bold > italic),
+ * so `**x**` reads as one bold run rather than two italics, and a backtick span
+ * is never re-parsed for emphasis. Text between markers is emitted verbatim;
+ * an unbalanced marker (a lone `*`) never matches and stays literal, so we
+ * never swallow content.
+ */
+export function parseInline(input: string): InlineSpan[] {
+  const matchers: Array<{ re: RegExp; make: (m: RegExpExecArray) => InlineSpan }> = [
+    { re: /`([^`]+)`/, make: (m) => ({ text: m[1] ?? '', code: true }) },
+    { re: /\[([^\]]+)\]\(([^)\s]+)\)/, make: (m) => ({ text: m[1] ?? '', href: m[2] ?? '' }) },
+    { re: /\*\*([^*]+)\*\*/, make: (m) => ({ text: m[1] ?? '', bold: true }) },
+    { re: /__([^_]+)__/, make: (m) => ({ text: m[1] ?? '', bold: true }) },
+    { re: /\*([^*]+)\*/, make: (m) => ({ text: m[1] ?? '', italic: true }) },
+    { re: /_([^_]+)_/, make: (m) => ({ text: m[1] ?? '', italic: true }) },
+  ];
+
+  const spans: InlineSpan[] = [];
+  let rest = input;
+  while (rest.length > 0) {
+    let best: { index: number; length: number; span: InlineSpan } | null = null;
+    for (const { re, make } of matchers) {
+      const m = re.exec(rest);
+      // Strictly-less keeps the higher-priority matcher on an index tie.
+      if (m && (best === null || m.index < best.index)) {
+        best = { index: m.index, length: (m[0] ?? '').length, span: make(m) };
+      }
+    }
+    if (best === null) {
+      pushText(spans, rest);
+      break;
+    }
+    pushText(spans, rest.slice(0, best.index));
+    spans.push(best.span);
+    rest = rest.slice(best.index + best.length);
+  }
+  return spans;
+}
+
+function pushText(spans: InlineSpan[], text: string): void {
+  if (text) spans.push({ text });
+}
+
+/**
+ * Fold raw Markdown into render-ready blocks. Line-oriented and greedy:
+ * consecutive list items fold into one list, consecutive `>` lines into one
+ * quote, and consecutive plain lines into one paragraph (soft-wrapped lines are
+ * joined with a space). Blank lines separate paragraphs. Pure and
+ * deterministic.
+ */
+export function parseMarkdown(source: string): MdBlock[] {
+  const blocks: MdBlock[] = [];
+  const lines = source.replace(/\r\n?/g, '\n').split('\n');
+
+  let paragraph: string[] = [];
+  function flushParagraph(): void {
+    const text = paragraph.join(' ').trim();
+    paragraph = [];
+    if (text) blocks.push({ type: 'paragraph', spans: parseInline(text) });
+  }
+
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i] ?? '';
+
+    // Fenced code block: ``` or ```lang … until a closing ``` (or EOF).
+    const fence = /^\s*```(.*)$/.exec(line);
+    if (fence) {
+      flushParagraph();
+      const lang = (fence[1] ?? '').trim();
+      const body: string[] = [];
+      i++;
+      while (i < lines.length) {
+        const l = lines[i] ?? '';
+        if (/^\s*```\s*$/.test(l)) break;
+        body.push(l);
+        i++;
+      }
+      i++; // consume the closing fence (no-op at EOF)
+      blocks.push({ type: 'code', text: body.join('\n'), ...(lang ? { lang } : {}) });
+      continue;
+    }
+
+    // Blank line: end the current paragraph.
+    if (/^\s*$/.test(line)) {
+      flushParagraph();
+      i++;
+      continue;
+    }
+
+    // Thematic break: a line of 3+ identical -, * or _.
+    if (/^\s*([-*_])\1{2,}\s*$/.test(line)) {
+      flushParagraph();
+      blocks.push({ type: 'hr' });
+      i++;
+      continue;
+    }
+
+    // ATX heading (#–######), trailing #'s stripped.
+    const heading = /^\s*(#{1,6})\s+(.*?)\s*#*\s*$/.exec(line);
+    if (heading) {
+      flushParagraph();
+      blocks.push({
+        type: 'heading',
+        level: (heading[1] ?? '').length,
+        spans: parseInline(heading[2] ?? ''),
+      });
+      i++;
+      continue;
+    }
+
+    // Blockquote: fold consecutive `>` lines together.
+    if (/^\s*>/.test(line)) {
+      flushParagraph();
+      const quoted: string[] = [];
+      while (i < lines.length) {
+        const l = lines[i] ?? '';
+        if (!/^\s*>/.test(l)) break;
+        quoted.push(l.replace(/^\s*>\s?/, ''));
+        i++;
+      }
+      blocks.push({ type: 'quote', spans: parseInline(quoted.join(' ').trim()) });
+      continue;
+    }
+
+    // List: fold consecutive items of the same kind (ordered vs unordered).
+    const first = matchListItem(line);
+    if (first) {
+      flushParagraph();
+      const items: InlineSpan[][] = [];
+      while (i < lines.length) {
+        const it = matchListItem(lines[i] ?? '');
+        if (!it || it.ordered !== first.ordered) break;
+        items.push(parseInline(it.text));
+        i++;
+      }
+      blocks.push({ type: 'list', ordered: first.ordered, items });
+      continue;
+    }
+
+    // Otherwise accumulate into the running paragraph.
+    paragraph.push(line.trim());
+    i++;
+  }
+  flushParagraph();
+  return blocks;
+}
+
+function matchListItem(line: string): { ordered: boolean; text: string } | null {
+  const ul = /^\s*[-*+]\s+(.*)$/.exec(line);
+  if (ul) return { ordered: false, text: ul[1] ?? '' };
+  const ol = /^\s*\d+[.)]\s+(.*)$/.exec(line);
+  if (ol) return { ordered: true, text: ol[1] ?? '' };
+  return null;
+}

package/src/native/run-state.ts

@@ -0,0 +1,204 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Pure run-state model for the RN widget's live agent runs.
+ *
+ * The minimized agent UI used to derive its status ad-hoc inside `StreamSheet`
+ * from a tangle of booleans (`running`/`done`/`transportError`/`askOpen`),
+ * encoded purely by dot color. This module replaces that with one explicit,
+ * unit-testable state machine: a {@link RunState} per run, a presentation map
+ * (glyph + tone + label, not color-alone), and the aggregation
+ * ({@link dockModel}) the compact bottom-left dock renders.
+ *
+ * It's deliberately dependency-free (only the sibling `transcript` reducer) so
+ * it's testable without React Native — the device UI (`AgentDock`, the expanded
+ * `StreamSheet`) stays a thin renderer over these pure functions, the same way
+ * `transcript.ts` / `restore.ts` keep their logic out of the un-testable
+ * RN-runtime layer.
+ */
+
+import { type AgentEvent, pendingAsk } from './transcript';
+
+/**
+ * The lifecycle state of one streamed agent run.
+ *
+ * - `connecting` — socket up, transcript not replayed yet (no events). The
+ *   brief window after spawn/restore and again right after a reconnect.
+ * - `working`    — events are flowing and the run hasn't ended.
+ * - `awaiting`   — blocked on an `ask_user` the developer hasn't answered. The
+ *   one state that needs the developer's attention; it pulses.
+ * - `done`       — ended cleanly (success result, or the bus simply closed).
+ * - `failed`     — ended on an error (server error frame, transport error, or a
+ *   non-success result subtype).
+ */
+export type RunState = 'connecting' | 'working' | 'awaiting' | 'done' | 'failed';
+
+export interface RunStateInput {
+  /** The folded agent event stream (same array `StreamSheet` accumulates). */
+  events: AgentEvent[];
+  /** Set once the run reached a terminal `result`/`done`. */
+  done: boolean;
+  /** Non-null when a server `error` frame (or "no dev server") arrived. */
+  transportError: string | null;
+  /** `askId` → answer, so an answered question no longer reads as `awaiting`. */
+  answered: Record<string, string>;
+}
+
+/** Did the run's last terminal event signal failure rather than success? */
+function endedInFailure(events: AgentEvent[]): boolean {
+  for (let i = events.length - 1; i >= 0; i--) {
+    const e = events[i];
+    if (!e) continue;
+    if (e.type === 'error') return true;
+    if (e.type === 'result') return e.subtype !== 'success';
+  }
+  return false;
+}
+
+/**
+ * Collapse the raw run booleans into a single {@link RunState}. Pure and
+ * order-sensitive: a transport error wins over everything (you can't answer or
+ * keep working over a dead socket), then an unanswered question, then terminal
+ * done/failure, else working-vs-connecting by whether any event has arrived.
+ */
+export function deriveRunState({
+  events,
+  done,
+  transportError,
+  answered,
+}: RunStateInput): RunState {
+  if (transportError) return 'failed';
+  const ask = pendingAsk(events);
+  if (ask && !answered[ask.askId]) return 'awaiting';
+  if (done) return endedInFailure(events) ? 'failed' : 'done';
+  return events.length > 0 ? 'working' : 'connecting';
+}
+
+/** Semantic color bucket; mapped to concrete colors in the component layer. */
+export type RunTone = 'neutral' | 'active' | 'attention' | 'success' | 'danger';
+
+export interface RunPresentation {
+  /** Short status word for labels / accessibility. */
+  label: string;
+  /** Monochrome glyph so state never rides on color alone. */
+  glyph: string;
+  /** Semantic tone the renderer maps to a palette entry. */
+  tone: RunTone;
+  /** Whether the chip should pulse to pull the developer back. */
+  pulse: boolean;
+  /** Non-terminal (connecting/working/awaiting) — i.e. still an active run. */
+  active: boolean;
+}
+
+const PRESENTATION: Record<RunState, RunPresentation> = {
+  connecting: { label: 'Connecting', glyph: '◌', tone: 'neutral', pulse: false, active: true },
+  working: { label: 'Working', glyph: '◐', tone: 'active', pulse: false, active: true },
+  awaiting: { label: 'Needs you', glyph: '!', tone: 'attention', pulse: true, active: true },
+  done: { label: 'Done', glyph: '✓', tone: 'success', pulse: false, active: false },
+  failed: { label: 'Failed', glyph: '✕', tone: 'danger', pulse: false, active: false },
+};
+
+/**
+ * Does an "interrupting" overlay actually apply right now?
+ *
+ * Stop is purely a client-side affordance over the existing `interrupt` frame
+ * (ticket 015): tapping it sets a local flag, and we keep showing "Stopping…"
+ * until the server lands a terminal event. The overlay therefore applies only
+ * while the run is still {@link RunPresentation.active active} — once it reaches
+ * a terminal `done`/`failed` state the interrupt resolved, so the overlay drops
+ * even if the caller's flag hasn't been cleared yet. Modeling it as an overlay
+ * (rather than a sixth {@link RunState}) keeps the state machine — and the dock
+ * aggregation — unchanged and unit-testable.
+ */
+export function interruptOverlayActive(state: RunState, interrupting: boolean): boolean {
+  return interrupting && PRESENTATION[state].active;
+}
+
+/**
+ * Presentation for a run, optionally overlaid with an interrupting affordance.
+ *
+ * With `interrupting` true on a still-active run we relabel to "Stopping…" and
+ * stop any pulse (the developer asked it to halt — pulsing for attention is the
+ * wrong signal), keeping the underlying state's glyph/tone/active so the dock
+ * partitioning is undisturbed. Terminal states ignore the flag (see
+ * {@link interruptOverlayActive}).
+ */
+export function runPresentation(state: RunState, interrupting = false): RunPresentation {
+  const base = PRESENTATION[state];
+  if (!interruptOverlayActive(state, interrupting)) return base;
+  return { ...base, label: 'Stopping…', pulse: false };
+}
+
+/** A run as the dock sees it: identity, header label, and derived state. */
+export interface DockRun {
+  id: string;
+  /** Header label — `file:line` if anchored, else the component name. */
+  target: string;
+  state: RunState;
+  /**
+   * The developer tapped Stop and we're awaiting the run's terminal event
+   * (ticket 015). An overlay over `state`, not a state — the chip relabels to
+   * "Stopping…" while it's still active. Ignored once terminal.
+   */
+  interrupting?: boolean;
+}
+
+export interface DockModel {
+  /** connecting/working/awaiting, sorted attention-first (stable within tone). */
+  active: DockRun[];
+  /** done/failed, in input order. */
+  finished: DockRun[];
+  /** Collapse the active runs into a single count bar (true at ≥2 active). */
+  collapseActive: boolean;
+  /** How many active runs are blocked on input. */
+  awaitingCount: number;
+  /** State driving the collapsed bar's glyph/tone (most attention-worthy). */
+  summaryState: RunState;
+  /** Bar text, e.g. `3 agents · 1 needs you`. */
+  activeHeadline: string;
+  /** True when any finished run failed (lets the summary flag failures). */
+  finishedHasFailure: boolean;
+}
+
+/** Attention priority for ordering/summarizing active runs (higher = first). */
+const ACTIVE_PRIORITY: Record<RunState, number> = {
+  awaiting: 3,
+  working: 2,
+  connecting: 1,
+  done: 0,
+  failed: 0,
+};
+
+/**
+ * Aggregate runs into what the dock draws. Active runs surface attention-first
+ * (a blocked run jumps above a busy one); ≥2 of them collapse into one count
+ * bar. Finished runs always roll into a `▸ N finished` summary. Pure so the
+ * hybrid + done-summary behavior is covered without rendering anything.
+ */
+export function dockModel(runs: readonly DockRun[]): DockModel {
+  // Stable attention-first sort for active runs: decorate with the input index
+  // so equal-tone runs keep their arrival order.
+  const active = runs
+    .filter((r) => runPresentation(r.state).active)
+    .map((run, i) => ({ run, i }))
+    .sort((a, b) => ACTIVE_PRIORITY[b.run.state] - ACTIVE_PRIORITY[a.run.state] || a.i - b.i)
+    .map(({ run }) => run);
+  const finished = runs.filter((r) => !runPresentation(r.state).active);
+
+  const awaitingCount = active.filter((r) => r.state === 'awaiting').length;
+  const summaryState = active[0]?.state ?? 'working';
+  const noun = active.length === 1 ? 'agent' : 'agents';
+  const activeHeadline =
+    awaitingCount > 0
+      ? `${active.length} ${noun} · ${awaitingCount} needs you`
+      : `${active.length} ${noun}`;
+
+  return {
+    active,
+    finished,
+    collapseActive: active.length >= 2,
+    awaitingCount,
+    summaryState,
+    activeHeadline,
+    finishedHasFailure: finished.some((r) => r.state === 'failed'),
+  };
+}

package/src/native/scroll-follow.ts

@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Pure scroll-follow predicate for the RN widget's live transcript.
+ *
+ * The expanded `StreamSheet` transcript used to call `scrollToEnd` on every
+ * content change, so scrolling up to re-read earlier output during an active run
+ * got yanked back to the bottom by the next event. The fix is the standard
+ * chat-log "stick to bottom only while already near the bottom" behavior — and
+ * the near-bottom test is the one piece of math worth pulling out of the
+ * un-testable RN-runtime layer (mirrors how `run-state.ts` / `transcript.ts`
+ * keep their logic pure, see packages/react-native/src/native).
+ */
+
+/** Default slack (in px) for treating "almost at the bottom" as "at bottom". */
+export const NEAR_BOTTOM_THRESHOLD = 24;
+
+export interface NearBottomInput {
+  /** `contentOffset.y` — how far the content is scrolled up from the top. */
+  offsetY: number;
+  /** `layoutMeasurement.height` — the visible viewport height. */
+  viewportH: number;
+  /** `contentSize.height` — the full scrollable content height. */
+  contentH: number;
+  /** Slack in px; the gap to the bottom that still counts as "at bottom". */
+  threshold?: number;
+}
+
+/**
+ * True when the scroll position is within `threshold` px of the bottom (so
+ * auto-follow should keep pinning new content into view). Pure and tolerant of
+ * the bouncy/over-scroll values RN can report: a negative remaining distance
+ * (rubber-band past the end) still reads as at-bottom, and content shorter than
+ * the viewport is always at-bottom. A non-finite or non-positive threshold
+ * falls back to {@link NEAR_BOTTOM_THRESHOLD}.
+ */
+export function isNearBottom({
+  offsetY,
+  viewportH,
+  contentH,
+  threshold = NEAR_BOTTOM_THRESHOLD,
+}: NearBottomInput): boolean {
+  const slack = Number.isFinite(threshold) && threshold > 0 ? threshold : NEAR_BOTTOM_THRESHOLD;
+  // Content that doesn't fill the viewport can't be scrolled — always pinned.
+  if (contentH <= viewportH) return true;
+  const distanceFromBottom = contentH - (offsetY + viewportH);
+  return distanceFromBottom <= slack;
+}

package/src/native/ws-client.ts

@@ -84,9 +84,14 @@ export class StreamClient {
     this.send({ type: 'ask_response', askId, answer });
   }
 
-  /** Interrupt the in-flight run. */
-  interrupt(): void {
-    this.send({ type: 'interrupt', feedbackId: this.feedbackId });
+  /**
+   * Interrupt the in-flight run. Returns whether the frame was actually written
+   * to an OPEN socket — `false` means it was dropped (socket closed/reconnecting)
+   * so the UI can say "couldn't stop" instead of silently no-opping. The server
+   * tears the run down on its own terminal event; this is just the request.
+   */
+  interrupt(): boolean {
+    return this.send({ type: 'interrupt', feedbackId: this.feedbackId });
   }
 
   private connect(): void {
@@ -151,13 +156,16 @@ export class StreamClient {
     }
   }
 
-  private send(msg: Record<string, unknown>): void {
+  /** Write a frame if the socket is OPEN. Returns whether it was sent. */
+  private send(msg: Record<string, unknown>): boolean {
     const s = this.socket;
-    if (!s || s.readyState !== 1 /* OPEN */) return;
+    if (!s || s.readyState !== 1 /* OPEN */) return false;
     try {
       s.send(JSON.stringify(msg));
+      return true;
     } catch {
       // socket closing mid-write
+      return false;
     }
   }