@pinagent/react-native 0.2.4 → 0.2.5

package/dist/native/AgentDock.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Compact dock for minimized agent runs (bottom-left).
+ *
+ * Replaces the old one-fat-pill-per-run stack. It renders the pure
+ * {@link dockModel} aggregation:
+ *
+ * - **Active runs** (connecting/working/awaiting) follow a hybrid rule — a
+ *   single slim chip when one runs, and a collapsed `◐ N agents · M needs you`
+ *   count bar (tap to expand the chip list) once two or more do.
+ * - **Finished runs** (done/failed) always roll into a `▸ N finished` summary
+ *   you tap to review and clear.
+ *
+ * Each `StreamSheet` stays mounted (it renders `null` while minimized) so its
+ * WebSocket keeps streaming; this dock is fed each run's derived `state` from
+ * the parent and is purely presentational. Tapping a chip expands that run's
+ * full sheet; ✕ tears it down.
+ *
+ * All decision logic (partitioning, ordering, headline text) lives in the pure
+ * `run-state` module — this file is intentionally just layout + animation, the
+ * un-testable RN-runtime layer.
+ */
+import type { ReactElement } from 'react';
+import { type DockRun } from './run-state';
+export interface AgentDockProps {
+    /** Minimized runs with their derived state (the expanded one is excluded). */
+    runs: DockRun[];
+    /** Expand a run to its full sheet. */
+    onExpand: (id: string) => void;
+    /** Tear a run down (stops its WS, removes it). */
+    onClose: (id: string) => void;
+}
+export declare function AgentDock({ runs, onExpand, onClose }: AgentDockProps): ReactElement | null;

package/dist/native/MarkdownView.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Render agent Markdown with React Native primitives.
+ *
+ * `parseMarkdown` (markdown.ts) does the parsing; this maps its block/inline
+ * tree onto <View>/<Text>. Inline marks ride as nested <Text> inside the
+ * paragraph's <Text>, which inherits the caller's `baseStyle` (the sheet's text
+ * row), so plain prose keeps its existing look and only the marked-up runs pick
+ * up bold/italic/code/link styling. Like the rest of `src/native`, it leans on
+ * RN core only — no markdown renderer dependency — so it ships as source and
+ * Metro bundles it onto the device unchanged.
+ *
+ * The file is `MarkdownView` (not `Markdown`) so it doesn't collide with
+ * `markdown.ts` on case-insensitive filesystems — tsc treats the two as the
+ * same module otherwise.
+ */
+import type { ReactElement } from 'react';
+import type { StyleProp } from 'react-native';
+import { type TextStyle } from 'react-native';
+export interface MarkdownViewProps {
+    text: string;
+    /** Base text style for paragraphs/inline runs (the sheet's text row). */
+    baseStyle?: StyleProp<TextStyle>;
+}
+export declare function MarkdownView({ text, baseStyle }: MarkdownViewProps): ReactElement;

package/dist/native/Pinagent.d.ts

@@ -24,10 +24,11 @@
  * (MCP) pickup. "+ Add element" multi-picks several targets into one comment
  * (sent as `additionalAnchors`); a single pick leaves them null.
  *
- * The transcript sheet can be minimized to a pill, freeing the screen to pick
- * another element and spawn a second agent. Each run keeps its own live sheet,
- * so multiple agents can stream concurrently — the expanded one shows its full
- * sheet; the rest sit as pills that keep streaming until tapped open.
+ * The transcript sheet can be minimized into the compact bottom-left dock,
+ * freeing the screen to pick another element and spawn a second agent. Each run
+ * keeps its own live sheet, so multiple agents can stream concurrently — the
+ * expanded one shows its full sheet; the rest collapse into the dock (a chip, or
+ * a count bar at 2+) and keep streaming until tapped open.
  */
 import type { ReactElement } from 'react';
 export interface PinagentProps {

package/dist/native/StreamSheet.d.ts

@@ -13,27 +13,32 @@
  * reconnect replays the agent transcript, so we clear `events` on `onReset`
  * but keep local follow-ups.
  *
- * The sheet can be **minimized** to a compact status pill so the developer can
- * keep interacting with the app — e.g. to pick another element and spawn a
- * second agent. Minimizing doesn't tear the run down: the component stays
- * mounted (only its rendering changes), so the WebSocket keeps streaming in the
- * background and the live transcript is intact the moment it's re-expanded.
- * `<Pinagent/>` mounts one of these per concurrent run.
+ * The sheet can be **minimized**: the run drops into the compact bottom-left
+ * `AgentDock` (a chip / count bar) so the developer can keep interacting with
+ * the app — e.g. to pick another element and spawn a second agent. Minimizing
+ * doesn't tear the run down: this component stays mounted and simply renders
+ * `null` (the dock draws the compact UI), so the WebSocket keeps streaming in
+ * the background and the live transcript is intact the moment it's re-expanded.
+ * `<Pinagent/>` mounts one of these per concurrent run and reads each run's
+ * derived {@link RunState} (reported via `onState`) to drive the dock.
  */
 import type { ReactElement } from 'react';
+import { type RunState } from './run-state';
 export interface StreamSheetProps {
     feedbackId: string;
     /** Source label shown in the header (e.g. `file:line` or component name). */
     target: string;
-    /** Render as a compact pill (WS stays live) instead of the full sheet. */
+    /** Minimized → render nothing (the dock shows the compact chip); WS stays live. */
     minimized: boolean;
-    /** Stack position among minimized pills (0 = bottom-most), for layout. */
-    stackIndex: number;
-    /** Collapse the full sheet to its pill. */
+    /** Collapse the full sheet back into the dock. */
     onMinimize: () => void;
-    /** Expand the pill back to the full sheet. */
-    onExpand: () => void;
     /** Dismiss for good — tears down the WS and removes this run's view. */
     onClose: () => void;
+    /**
+     * Report the run's derived state up so the dock can render it. `interrupting`
+     * is the Stop overlay (ticket 015) — the developer tapped Stop and we're
+     * awaiting teardown; the dock relabels the chip to "Stopping…" while active.
+     */
+    onState: (state: RunState, interrupting: boolean) => void;
 }
-export declare function StreamSheet({ feedbackId, target, minimized, stackIndex, onMinimize, onExpand, onClose, }: StreamSheetProps): ReactElement;
+export declare function StreamSheet({ feedbackId, target, minimized, onMinimize, onClose, onState, }: StreamSheetProps): ReactElement | null;

package/dist/native/inspector.d.ts

@@ -156,16 +156,31 @@ interface MeasuredHit {
  * `react-native-pager-view` (and anything that hosts content in a native
  * container) detaches a page's *native* views from the Fabric shadow tree
  * `findNodeAtPoint` walks, so the native hit-test bottoms out at the page
- * wrapper and never reaches the widget. But the React **fiber** tree is intact
- * and the widgets are on-screen, hence measurable — so we hit-test ourselves:
- * DFS the fiber subtree under `root`, measuring each host, and keep the DEEPEST
- * tagged host whose window frame contains the tap.
+ * wrapper — it returns no touched instance at all (`closestPublicInstance` is
+ * null). But the React **fiber** tree is intact and the page's widgets are
+ * on-screen, hence measurable — so we hit-test ourselves: DFS the fiber subtree
+ * under `root` (the app root, an ancestor of every on-screen view), measuring
+ * each host, and keep the DEEPEST tagged host inside the tapped region.
  *
- * Pruned like the browser's `elementFromPoint`: a host whose frame misses the
- * point can't have a (non-overflowing) descendant that hits, so its subtree is
- * skipped. Composite / fragment fibers carry no frame, so we always descend
- * through them to reach their hosts. `measure` is injected so the traversal is
- * unit-testable without an RN runtime.
+ * `region` threads the frame of the nearest measurable host ancestor that
+ * CONTAINS the tap (null until we enter one). Two subtleties this handles:
+ *
+ *  - **Pruning.** A host with a real frame that MISSES the tap can't have a
+ *    (non-overflowing) descendant that hits, so its subtree is skipped — like
+ *    the browser's `elementFromPoint`.
+ *  - **Flattened / detached hosts.** RN flattens layout-only `<View>`s (no
+ *    native view → `measure` returns null) and pager pages are detached, so a
+ *    widget's own tagged hosts often can't be measured. Once we're inside a
+ *    measurable containing region we keep recording tagged hosts even when they
+ *    can't be measured (they borrow the region's frame for the highlight) and
+ *    descend through them — otherwise geometry bottoms out at the outermost
+ *    non-flattened wrapper (e.g. an animated card) and every widget collapses to
+ *    that shared wrapper's source. Measurable siblings still prune wrong
+ *    branches, so we stay within the tapped element.
+ *
+ * Composite / fragment fibers carry no frame, so we always descend through them
+ * to reach their hosts. `measure` is injected so the traversal is unit-testable
+ * without an RN runtime.
  */
 export declare function measureHitTest(root: FiberLike | null, x: number, y: number, measure: (fiber: FiberLike) => Promise<Frame | null>): Promise<MeasuredHit | null>;
 /**

package/dist/native/keyboard-height.d.ts

@@ -0,0 +1,2 @@
+/** Live soft-keyboard height in px (0 when hidden). */
+export declare function useKeyboardHeight(): number;

package/dist/native/keyboard.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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 declare function isDismissKey(key: string): boolean;

package/dist/native/markdown.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 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 declare function parseInline(input: string): InlineSpan[];
+/**
+ * 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 declare function parseMarkdown(source: string): MdBlock[];

package/dist/native/run-state.d.ts

@@ -0,0 +1,120 @@
+/**
+ * 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 } 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>;
+}
+/**
+ * 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 declare function deriveRunState({ events, done, transportError, answered, }: RunStateInput): RunState;
+/** 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;
+}
+/**
+ * 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 declare function interruptOverlayActive(state: RunState, interrupting: boolean): boolean;
+/**
+ * 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 declare function runPresentation(state: RunState, interrupting?: boolean): RunPresentation;
+/** 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;
+}
+/**
+ * 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 declare function dockModel(runs: readonly DockRun[]): DockModel;

package/dist/native/scroll-follow.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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 declare 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 declare function isNearBottom({ offsetY, viewportH, contentH, threshold, }: NearBottomInput): boolean;

package/dist/native/ws-client.d.ts

@@ -45,10 +45,16 @@ export declare class StreamClient {
     sendUserMessage(content: string): void;
     /** Answer an `ask_user` prompt. */
     sendAskResponse(askId: string, answer: string): void;
-    /** Interrupt the in-flight run. */
-    interrupt(): void;
+    /**
+     * 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;
     private connect;
     private onMessage;
+    /** Write a frame if the socket is OPEN. Returns whether it was sent. */
     private send;
     private scheduleReconnect;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pinagent/react-native",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "license": "Apache-2.0",
   "description": "React Native & Expo plugin for Pinagent — tap a view, leave a comment, and a coding agent fixes it with file:line + a screenshot. The native widget ships as source for Metro; the dev-server middleware and Babel source-tagging plugin are built for Node.",
   "keywords": [