@pinagent/react-native 0.2.1 → 0.2.3

package/dist/native/Pinagent.d.ts

@@ -0,0 +1,50 @@
+/**
+ * <Pinagent/> — the React Native widget. Mount it once at your app root:
+ *
+ *   export default function App() {
+ *     return (
+ *       <>
+ *         <YourApp />
+ *         <Pinagent />
+ *       </>
+ *     );
+ *   }
+ *
+ * Modeled on pinagent's Next.js `<Pinagent/>` (a single root-mounted
+ * component) rather than the Vite `<script>` injection, which has no RN
+ * analog. Renders `null` in production so it has zero cost in release
+ * builds.
+ *
+ * Flow: tap the pin FAB to arm picking → tap a view → we resolve its source
+ * via the RN Inspector, hide our own overlay, and capture a screenshot →
+ * type a comment → submit POSTs to the Metro middleware, which stores it
+ * and (optionally) spawns an agent. When an agent is spawned, a live
+ * transcript sheet streams the run back over WebSocket (see StreamSheet /
+ * ws-client); otherwise a toast confirms the comment was filed for pull-mode
+ * (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.
+ */
+import type { ReactElement } from 'react';
+export interface PinagentProps {
+    /**
+     * Absolute project root, used to make `_debugSource` file paths
+     * project-relative (matching the web babel plugin's output). Defaults
+     * to the value Metro injects, falling back to '' (paths stay absolute,
+     * still usable).
+     */
+    projectRoot?: string;
+    /** Route/screen name to record with the comment. Defaults to OS name. */
+    screenName?: string;
+}
+/**
+ * Hard dev-only gate. `__DEV__` is `false` in release bundles, so the
+ * whole widget — and its require()s into RN internals — drops out. Kept
+ * as a thin wrapper so the hooks live in `PinagentDev`, called
+ * unconditionally (rules-of-hooks).
+ */
+export declare function Pinagent(props: PinagentProps): ReactElement | null;

package/dist/native/StreamSheet.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Live agent transcript sheet for React Native.
+ *
+ * After a comment is submitted and an agent is spawned, the widget opens this
+ * bottom sheet and streams the run over WebSocket (see `ws-client.ts`). It's
+ * the RN analog of the web widget's agent tray: a scrolling transcript, an
+ * answer form when the agent calls `ask_user`, a follow-up box, and Stop /
+ * Dismiss controls.
+ *
+ * State is intentionally simple and reducer-driven: agent events accumulate in
+ * one array folded by `renderTranscript`; user follow-ups are tracked locally
+ * (the bus only streams agent events, not the developer's messages). A
+ * 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.
+ */
+import type { ReactElement } from 'react';
+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: boolean;
+    /** Stack position among minimized pills (0 = bottom-most), for layout. */
+    stackIndex: number;
+    /** Collapse the full sheet to its pill. */
+    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;
+}
+export declare function StreamSheet({ feedbackId, target, minimized, stackIndex, onMinimize, onExpand, onClose, }: StreamSheetProps): ReactElement;

package/dist/native/brand.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Pinagent brand palette for the React Native widget.
+ *
+ * Mirrors BRAND_INK / BRAND_CREAM / BRAND_GOLD in `packages/ui/src/tokens.ts`. That
+ * package is web-only (React-DOM + Tailwind) so the native widget can't import
+ * it — keep these in sync if the brand palette changes there.
+ */
+/** Dark charcoal — the FAB surface / ink-mode surfaces and primary text. */
+export declare const BRAND_INK = "#201B21";
+/** Warm cream — the pin mark on dark surfaces, light backgrounds, brand identity. */
+export declare const BRAND_CREAM = "#FCF9E8";
+/** Gold accent — focus rings; the active picking state. */
+export declare const BRAND_GOLD = "#FFD700";

package/dist/native/index.d.ts

@@ -0,0 +1,7 @@
+export type { PinagentProps } from './Pinagent';
+export { Pinagent } from './Pinagent';
+export type { AgentEvent, ServerMessage, TranscriptRow } from './transcript';
+export { pendingAsk, renderTranscript } from './transcript';
+export { devServerBaseUrl, submitFeedback } from './transport';
+export type { FeedbackInput, PickResult } from './types';
+export { devServerWsUrl, StreamClient } from './ws-client';

package/dist/native/inspector.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Tap point → source location, the React Native way.
+ *
+ * This is the RN analog of the web widget's DOM walk for `data-pa-loc`.
+ * RN's own dev Inspector (Dev Menu → "Show Inspector") resolves a touch
+ * to a component + source file using exactly this internal API; we lean
+ * on the same machinery rather than reinventing it.
+ *
+ * Source data comes from the `data-pa-loc="file:line:col"` prop the
+ * `@pinagent/react-native/babel` plugin splices onto every authored JSX
+ * element at build time — the exact RN analog of the web babel plugin's
+ * DOM attribute. The plugin's prop rides along on the host fiber's
+ * `memoizedProps`, which `getInspectorDataForViewAtPoint` hands back to us
+ * as `data.props`, so the tapped view resolves to its source directly.
+ *
+ * Why a build-time prop instead of RN's old `_debugSource`: React 19
+ * deleted `_debugSource`, and RN 0.81+ dropped the `source` field from the
+ * inspector payload — neither carries a source location anymore. We still
+ * read both as a fallback for older RN/React, then degrade to `loc: null`.
+ *
+ * Both the module path AND the payload shape returned by
+ * `getInspectorDataForViewAtPoint` have shifted across RN versions, so
+ * every read here is defensive: we extract what we can and degrade to
+ * `loc: null` rather than throw inside a tap handler.
+ */
+import type { PickResult } from './types';
+interface RawFiberLike {
+    fileName?: string;
+    lineNumber?: number;
+    columnNumber?: number;
+}
+type RawProps = Record<string, unknown> | null | undefined;
+/** RN measure callback: `(x, y, width, height, pageX, pageY)`. */
+type RawMeasureCb = (x: number, y: number, width: number, height: number, pageX: number, pageY: number) => void;
+interface RawHierarchyItem {
+    name?: string;
+    getInspectorData?: (toFiber: unknown) => {
+        /** Removed in RN 0.81+, kept for back-compat. */
+        source?: RawFiberLike | null;
+        /** The host fiber's `memoizedProps` — carries our `data-pa-loc`. */
+        props?: RawProps;
+        /** Measures this owner's host fiber (window/screen coords). */
+        measure?: (cb: RawMeasureCb) => void;
+    };
+}
+interface RawInspectorData {
+    frame?: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    } | null;
+    hierarchy?: RawHierarchyItem[];
+    /** Newer RN returns the closest fiber directly. */
+    closestInstance?: {
+        _debugSource?: RawFiberLike;
+    } | null;
+    /** Some versions surface the resolved source straight on the payload. */
+    source?: RawFiberLike | null;
+    /**
+     * NOT the tapped leaf's props. RN fills this from the nearest authored
+     * *composite owner's* FIRST host descendant (`getHostProps` →
+     * `findCurrentHostFiber`) — i.e. that component's outermost view — so a tap
+     * on a nested child surfaces its container here, not the element under the
+     * finger. Used only as a fallback; `closestPublicInstance` pins the leaf.
+     */
+    props?: RawProps;
+    /**
+     * The public instance of the host view actually under the finger — the
+     * deepest hit-tested node. Fabric only; Paper passes a numeric view tag we
+     * can't bridge, so we degrade to `props`. Its fiber's `memoizedProps` carry
+     * the leaf's own `data-pa-loc`. See {@link tappedLeafLoc}.
+     */
+    closestPublicInstance?: unknown;
+}
+interface FiberLike {
+    tag?: number;
+    return?: FiberLike | null;
+    stateNode?: {
+        canonical?: {
+            publicInstance?: unknown;
+        };
+    } | null;
+    /** Host fibers carry the committed props — where `data-pa-loc` rides. */
+    memoizedProps?: RawProps;
+}
+type Loc = NonNullable<PickResult['loc']>;
+/**
+ * Walk a host fiber's render-tree parent (`return`) chain, returning the first
+ * `data-pa-loc` found on a fiber's `memoizedProps` — the tapped element itself,
+ * or, when that exact host is untagged (a 3rd-party / RN-internal view), the
+ * nearest authored element enclosing it. Capped against a malformed `return`
+ * cycle. Pure over a fiber-like chain; exported for unit testing without an RN
+ * runtime.
+ */
+export declare function nearestPaLocUp(fiber: FiberLike | null): Loc | null;
+/**
+ * Keep only authored React components in the breadcrumb. Two kinds of noise
+ * are hidden because clicking them is meaningless — they map to no source the
+ * developer can act on:
+ *
+ *  - **Native host components** — RN's view classes, named `RCT…`
+ *    (`RCTText`, `RCTView`, `RCTScrollView`, …).
+ *  - **HOC / wrapper display names** — parenthesized by convention
+ *    (`withDevTools(App)`, `ForwardRef(X)`, `Memo(X)`, `Connect(X)`).
+ *
+ * Identifiers can't contain `(`, so a parenthesized name is always a wrapper.
+ */
+export declare function isAuthoredComponentName(name: unknown): name is string;
+type Frame = NonNullable<PickResult['frame']>;
+interface RawCrumb {
+    name: string;
+    loc: Loc | null;
+    measure?: (cb: RawMeasureCb) => void;
+}
+/**
+ * Build the per-segment breadcrumb: each authored component in the hierarchy
+ * paired with its own `data-pa-loc` (so a press can re-anchor onto that
+ * ancestor) and a `measure` fn (so the highlight can follow the selection).
+ * Same order as {@link nameChainOf} — root first, tapped last.
+ *
+ * Each crumb's `loc` falls back to the nearest resolvable source in the
+ * hierarchy when its own host props carry none, so pressing ANY breadcrumb
+ * re-anchors the comment onto a real `file:line` — not just the tapped
+ * (innermost) one. Without the fallback, only the tapped element (which
+ * `pickLoc` resolves with its own hierarchy walk) got a path; ancestor crumbs
+ * whose first host child is untagged collapsed to `loc: null`, so re-focusing
+ * onto them showed a bare component name instead of a source snippet.
+ *
+ * Exported for unit testing — a pure function over the (duck-typed) inspector
+ * payload, so it needs no RN runtime (unlike `resolvePick`).
+ */
+export declare function crumbsOf(data: RawInspectorData): RawCrumb[];
+/**
+ * Measure a hierarchy item's host fiber to a window-coordinate {@link Frame}.
+ * Resolves null if there's no measure fn or it never calls back (guarded so a
+ * stuck measure can't hang the pick).
+ */
+export declare function measureFrame(measure?: (cb: RawMeasureCb) => void): Promise<Frame | null>;
+/**
+ * Resolve a tap (in window coordinates) to a {@link PickResult}.
+ *
+ * @param rootView  A host view instance from which to reach the app root —
+ *   pass a ref's `.current` (the widget passes its own overlay `<View>`).
+ *   We climb to the app-root host instance before hit-testing, since the
+ *   inspector searches within the passed view's subtree. NOT a
+ *   `findNodeHandle` number — the Fabric inspector rejects a bare tag.
+ */
+export declare function resolvePick(rootView: unknown, x: number, y: number, projectRoot: string): Promise<PickResult>;
+export {};

package/dist/native/multi-pick.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Multi-select payload builder (ticket 008).
+ *
+ * On web, Cmd/Ctrl-click accumulates several elements into one comment and the
+ * extras are submitted as `additionalAnchors` (landing in the
+ * `widget_anchors.additional_anchors` JSON column). RN is touch-only, so the
+ * composer offers an explicit "+ Add element" affordance: re-enter pick mode,
+ * tap another element, and it appends a removable chip. This module turns the
+ * primary anchor + the collected extras into the `additionalAnchors` array,
+ * matching the web `AdditionalAnchorSchema` shape so the server accepts it
+ * unchanged.
+ *
+ * Pure (no RN runtime imports) → unit-testable here. The RN UI state + capture
+ * lives in Pinagent.tsx; this just shapes the wire payload.
+ *
+ * Web semantics preserved:
+ * - A single pick (no extras) → `additionalAnchors` OMITTED (the server stores
+ *   `additional_anchors` as null), not an empty array.
+ * - The primary anchor is NOT duplicated into the extras.
+ * - Each extra keeps the loc/selector it was tapped with (no breadcrumb
+ *   re-anchoring for extras — that applies to the primary only, web parity).
+ */
+import type { AdditionalAnchor } from './types';
+/** A primary or extra pick as captured by the RN composer. */
+export interface ChipPick {
+    /** Stable key for the chip + removal (e.g. a per-pick counter). */
+    key: string;
+    /** Resolved source location, or null for an unresolvable native view. */
+    loc: {
+        file: string;
+        line: number;
+        col: number;
+    } | null;
+    /** Component name-chain ("App > Home > Button") — RN's selector stand-in. */
+    selector: string;
+    /** Tap point in window coordinates (the `clickX`/`clickY` the schema wants). */
+    clickX: number;
+    clickY: number;
+    /** Innermost component name, for the chip label. */
+    label: string;
+}
+/**
+ * Build the `additionalAnchors` field from the extra picks (everything after
+ * the primary). Returns `undefined` when there are no extras so the caller can
+ * spread it and leave the field off entirely for single-pick submits.
+ *
+ * @param extras the non-primary picks, in pick order (preserved on the wire).
+ */
+export declare function buildAdditionalAnchors(extras: readonly ChipPick[]): AdditionalAnchor[] | undefined;
+/**
+ * Remove a chip by key from a pick list, preserving order. Used for both the
+ * primary+extras chip row removal and the extras-only list; the caller decides
+ * which list to pass (the primary is never removable in the UI).
+ */
+export declare function removeChip(picks: readonly ChipPick[], key: string): ChipPick[];

package/dist/native/pin-icon.d.ts

@@ -0,0 +1,21 @@
+/**
+ * PinIcon — pinagent's teardrop pin mark, for the React Native FAB.
+ *
+ * The mark is the canonical PIN_PATH / BRAND_VIEWBOX from `packages/ui/src/tokens.ts`
+ * (web-only, hence mirrored here). We draw it with `react-native-svg` when it's
+ * available — an OPTIONAL peer, lazily required exactly like
+ * `react-native-view-shot` in screenshot.ts, so a release build never pulls the
+ * native module in: the require only runs once <Pinagent/> actually renders,
+ * which it never does when `!__DEV__`.
+ *
+ * When the peer isn't installed we fall back to a View-drawn teardrop in the
+ * same colour, so the FAB always shows a brand pin — never a generic glyph.
+ */
+import type { ReactElement } from 'react';
+export interface PinIconProps {
+    /** Square edge length, in px. */
+    size?: number;
+    /** Fill colour of the pin (pass a brand token). */
+    color: string;
+}
+export declare function PinIcon({ size, color }: PinIconProps): ReactElement;

package/dist/native/restore.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Restore-filter: turn the server's feedback list into the minimized pills the
+ * RN widget seeds on mount, so an app reload mid-run brings the running streams
+ * back instead of losing them.
+ *
+ * The dev server (`.pinagent/db.sqlite`) is the source of truth — RN keeps no
+ * device-local mirror (see ticket 001). On `<Pinagent/>` mount we
+ * `GET /__pinagent/feedback`, run the list through {@link restorePills}, and
+ * seed `streams` with the result; each restored id then subscribes over the
+ * existing WS client, which replays the transcript (and fires `done` for
+ * already-finished runs).
+ *
+ * This module is pure (no RN runtime imports) so it's unit-testable here. The
+ * filter mirrors the web widget's `listPendingForCurrentPage`
+ * (`packages/widget/src/db/reads.ts`): pending-only, scoped to the current
+ * surface URL, newest first.
+ */
+/** Default cap so a stale backlog doesn't flood the screen with pills. */
+export declare const RESTORE_LIMIT = 5;
+/** A minimized run pill: the same shape `<Pinagent/>` keeps in `streams`. */
+export interface RestoredPill {
+    id: string;
+    /** Header label — `file:line` if anchored, else the selector/component. */
+    target: string;
+}
+/**
+ * The subset of a feedback list item (`storage.list()` projection,
+ * `FeedbackRecord`) this filter reads. Loosely typed so it tolerates the wire
+ * JSON without importing the agent-runner type into RN source.
+ */
+export interface RestoreCandidate {
+    id?: unknown;
+    status?: unknown;
+    url?: unknown;
+    file?: unknown;
+    line?: unknown;
+    selector?: unknown;
+    updatedAt?: unknown;
+}
+/**
+ * Filter a feedback list to the pills worth restoring on this surface:
+ *
+ * - `status === 'pending'` — resolved/dismissed runs don't come back (web parity).
+ * - `url === surfaceUrl` — RN submits `url: screenName ?? Platform.OS`; a run
+ *   started on a different screen would restore at meaningless coordinates.
+ * - newest first by `updatedAt`, capped at `limit` (default {@link RESTORE_LIMIT}).
+ *
+ * Items missing an `id` are dropped (can't subscribe to them).
+ */
+export declare function restorePills(items: readonly RestoreCandidate[] | null | undefined, surfaceUrl: string, limit?: number): RestoredPill[];

package/dist/native/screenshot.d.ts

@@ -0,0 +1 @@
+export declare function captureScreenshot(): Promise<string>;

package/dist/native/submit-outcome.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Pure submit-outcome reducer (ticket 002).
+ *
+ * `onSubmit` in Pinagent.tsx used to clear the composer (comment, pick,
+ * screenshot) UNCONDITIONALLY after `submitFeedback()` returned — so a Metro
+ * restart, a network blip, or a release build at the moment of submit threw
+ * away the typed comment, the picked anchor, and the screenshot, leaving the
+ * user with a 2.5s toast and a blank composer.
+ *
+ * This module computes the next composer state from a `SubmitResult` so the
+ * "keep the draft on failure, clear only on success" rule is data, not buried
+ * UI flow — and is unit-testable here (the RN UI itself is not). Mapping the
+ * outcome to React state lives in `onSubmit`; this just decides the shape.
+ */
+/** The relevant submit result fields (a subset of transport's `SubmitResult`). */
+export interface SubmitOutcomeInput {
+    ok: boolean;
+    id?: string;
+    agentSpawned?: boolean;
+    error?: string;
+}
+/** What the composer should do next, given a submit result. */
+export interface SubmitOutcome {
+    /**
+     * `'clear'` — wipe the composer (comment/pick/shot) and go idle (success).
+     * `'keep'` — retain the composer and surface the error inline + offer Retry.
+     */
+    composer: 'clear' | 'keep';
+    /** Inline error to show under the composer when `composer === 'keep'`. */
+    error: string | null;
+    /**
+     * When a run was spawned, the id to open as a live stream. Null when nothing
+     * to stream (spawn off, or a failed submit).
+     */
+    streamId: string | null;
+    /**
+     * Transient toast text for the non-streaming success/failure paths, or null
+     * when the outcome opens a stream instead (which has its own UI). Kept for a
+     * filed-for-pull-mode confirmation; failures show inline, not a toast.
+     */
+    toast: string | null;
+}
+/**
+ * Decide the next composer state from a submit result.
+ *
+ * - Failure (`ok === false`): keep the composer + its draft, surface the error
+ *   inline (never a vanishing toast), no stream, no clear. Retry re-submits the
+ *   retained payload.
+ * - Success with a spawned agent: clear the composer and open the stream.
+ * - Success without a spawned agent (spawn off / pull mode): clear the composer
+ *   and show a transient "Sent" toast.
+ */
+export declare function submitOutcome(result: SubmitOutcomeInput): SubmitOutcome;

package/dist/native/transcript.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Transcript reducer + wire types for the RN widget.
+ *
+ * Deliberate, dependency-free mirror of `@pinagent/shared`'s `AgentEvent`
+ * union (event-bus.ts), `ServerMessage` (ws-protocol.ts), and the canonical
+ * `renderTranscript` (render-transcript.ts). We DON'T import the package: the
+ * native client ships as **source** and is bundled onto the device by the
+ * consumer's Metro, but `@pinagent/shared` is `private` (unpublished) and
+ * built for Node — importing it into device code would break a real
+ * `npm install @pinagent/react-native`, the same way bundling any unpublished
+ * `@pinagent/*` dep does. The package's `./server` entry CAN depend on shared
+ * (tsdown bundles it into dist); device source cannot.
+ *
+ * Keep in sync with those three files. The shapes are stable and the reducer
+ * mirrors the shared one, extended with the streaming-only kinds (ask/status)
+ * the interactive RN sheet renders.
+ */
+/** Flat AgentEvent union — mirror of `@pinagent/shared`'s `event-bus.ts`. */
+export type AgentEvent = {
+    type: 'init';
+    sessionId: string;
+    model: string;
+    permissionMode: string;
+    apiKeySource: string;
+} | {
+    type: 'text';
+    text: string;
+} | {
+    type: 'tool_use';
+    name: string;
+    summary: string;
+} | {
+    type: 'tool_result';
+    ok: boolean;
+} | {
+    type: 'progress';
+    turn: number;
+} | {
+    type: 'ask_user';
+    askId: string;
+    question: string;
+    context?: string;
+    options?: string[];
+} | {
+    type: 'error';
+    message: string;
+} | {
+    type: 'result';
+    subtype: string;
+    numTurns: number;
+    totalCostUsd: number;
+    durationMs: number;
+} | {
+    type: 'status_changed';
+    status: 'pending' | 'fixed' | 'wontfix' | 'deferred';
+    note: string | null;
+    commitSha: string | null;
+    resolvedAt: string | null;
+};
+/**
+ * Server → client frames the RN client acts on (subset of the web protocol).
+ *
+ * Only the frames the widget handles are modeled. Other frames (project /
+ * extension fan-out, pong) still arrive on the wire — `StreamClient.onMessage`
+ * casts the parsed JSON to this type and its `switch` ignores any `type` it
+ * doesn't handle. We deliberately avoid an open
+ * `{ type: string; [k: string]: unknown }` member: it overlaps every
+ * discriminant, collapsing `event`/`message` to `{}` at the use sites and
+ * defeating narrowing.
+ */
+export type ServerMessage = {
+    type: 'event';
+    feedbackId: string;
+    event: AgentEvent;
+} | {
+    type: 'done';
+    feedbackId: string;
+} | {
+    type: 'error';
+    feedbackId?: string;
+    message: string;
+} | {
+    type: 'worktree_state';
+    feedbackId: string;
+    state: string;
+    commitSha?: string;
+};
+export type TranscriptKind = 'text' | 'tool' | 'error' | 'result' | 'ask' | 'status';
+export interface TranscriptRow {
+    /** Stable key for React lists; derived from event index. */
+    id: string;
+    kind: TranscriptKind;
+    /** Primary text. For tools, the tool name. */
+    text: string;
+    /** Tool argument summary / ask options, when present. */
+    detail?: string;
+    /** tool_result success flag → ✓/✗ marker. */
+    ok?: boolean;
+}
+/**
+ * Fold AgentEvents into render-ready rows. Pure and deterministic — mirrors
+ * the shared `renderTranscript`, plus `ask_user` / `status_changed` rows the
+ * interactive RN sheet shows. `init`, `progress`, `tool_result` produce no row
+ * of their own (`tool_result` annotates the preceding tool row with ✓/✗).
+ */
+export declare function renderTranscript(events: AgentEvent[]): TranscriptRow[];
+/** The latest unanswered ask_user, if the run is currently blocked on one. */
+export declare function pendingAsk(events: AgentEvent[]): {
+    askId: string;
+    question: string;
+    options: string[];
+} | null;

package/dist/native/transport.d.ts

@@ -0,0 +1,49 @@
+import type { RestoreCandidate } from './restore';
+import type { FeedbackInput } from './types';
+/**
+ * Parse `http://192.168.1.5:8081/index.bundle?...` (or the RN packager's
+ * variants) down to `http://192.168.1.5:8081`. Returns null in release builds,
+ * where no Metro server is reachable.
+ *
+ * Prefers RN's `getDevServer()` (TurboModule-backed, works under the New
+ * Architecture) and falls back to the legacy `NativeModules.SourceCode.scriptURL`
+ * for pre-bridgeless RN. The legacy proxy is empty under bridgeless, which is
+ * what made every submit fail with "No dev server" on RN 0.82+.
+ */
+export declare function devServerBaseUrl(): string | null;
+export interface SubmitResult {
+    ok: boolean;
+    id?: string;
+    agentSpawned?: boolean;
+    error?: string;
+}
+/**
+ * Send one comment. Mirrors the web widget's POST to
+ * `/__pinagent/feedback`; the response (`{ id, agentSpawned }`) is the
+ * same one the Vite/Next middleware returns.
+ */
+export declare function submitFeedback(input: FeedbackInput): Promise<SubmitResult>;
+/**
+ * Fetch the conversation list from the dev server (`GET /__pinagent/feedback`).
+ * Used on `<Pinagent/>` mount to restore minimized pills after an app reload —
+ * the server's `.pinagent/db.sqlite` is the source of truth, so RN keeps no
+ * device-local mirror. Returns `[]` (degrade silently) when the dev server is
+ * unreachable or the request fails — exactly as today when there's no server.
+ *
+ * The items are the `storage.list()` projection (`FeedbackRecord[]`); the
+ * caller filters them with `restorePills`. Typed loosely here so the wire JSON
+ * doesn't drag the agent-runner type into RN source.
+ */
+export declare function fetchFeedbackList(): Promise<RestoreCandidate[]>;
+/**
+ * Ask the dev server to open a source location in the editor on the machine
+ * running Metro — the RN analog of the web composer's "navigate to file".
+ * Fire-and-forget: the device gets no useful signal beyond "request sent".
+ */
+export declare function openInEditor(loc: {
+    file: string;
+    line: number;
+    col: number;
+}): Promise<boolean>;
+/** `${Platform.OS} ${Platform.Version}` — RN's stand-in for a UA string. */
+export declare function platformTag(): string;

package/dist/native/types.d.ts

@@ -0,0 +1,108 @@
+/**
+ * The wire shape the RN widget produces. It mirrors `FeedbackInputSchema`
+ * in `packages/agent-runner/src/storage.ts` so the existing server
+ * accepts a phone-filed comment with zero backend changes. Keep this in
+ * lockstep with that zod schema — the middleware re-validates against it.
+ */
+export interface FeedbackInput {
+    /** Comment text the developer typed. 1..8000 chars (server-enforced). */
+    comment: string;
+    /**
+     * Source location of the tapped component, from the fiber's
+     * `_debugSource` (the RN analog of web's `data-pa-loc`). Null when the
+     * tapped view has no resolvable source (a deep native view with no
+     * composite owner in dev).
+     */
+    loc: {
+        file: string;
+        line: number;
+        col: number;
+    } | null;
+    /**
+     * Web sends a CSS selector here for HMR re-anchoring. RN has no
+     * selectors, so v1 sends the component display-name chain (e.g.
+     * "App > HomeScreen > PrimaryButton") purely to satisfy the schema and
+     * give the agent a human-readable hint. See the design doc's
+     * "Deliberate cuts for v1".
+     */
+    selector: string;
+    /** The current route/screen name (web sends the page URL). */
+    url: string;
+    /** Window dimensions at pick time. */
+    viewport: {
+        w: number;
+        h: number;
+    };
+    /** `${Platform.OS} ${Platform.Version}` — the RN analog of a UA string. */
+    userAgent: string;
+    /** base64 PNG (no data: prefix). Capped at 5MB by the middleware. */
+    screenshot: string;
+    /** ISO timestamp. */
+    createdAt: string;
+    /**
+     * Extra elements the developer multi-picked into the SAME comment (the
+     * 2nd…Nth taps). Optional — omitted entirely for a single pick, exactly
+     * like the web widget (the server stores `additional_anchors` as null
+     * unless this is a non-empty array). The agent receives them as
+     * `additionalTargets` and addresses every location. Same per-anchor shape
+     * the web sends in `FeedbackInputSchema.additionalAnchors`
+     * (`packages/agent-runner/src/storage.ts`).
+     */
+    additionalAnchors?: AdditionalAnchor[];
+}
+/**
+ * One extra (non-primary) pick. Matches the web `AdditionalAnchorSchema`
+ * exactly so the server accepts it unchanged: `clickX`/`clickY` are required
+ * integers (the tap point in window coordinates); `component` is optional.
+ */
+export interface AdditionalAnchor {
+    file: string | null;
+    line: number | null;
+    col: number | null;
+    selector: string;
+    clickX: number;
+    clickY: number;
+    component?: string | null;
+}
+/** One segment of the component breadcrumb. */
+export interface PickCrumb {
+    /** Component display name (e.g. `FeatureCard`). */
+    name: string;
+    /**
+     * Source location of that component, from its own `data-pa-loc`. Null when
+     * the component carries no resolvable source (e.g. an untagged 3rd-party
+     * wrapper). Lets the breadcrumb re-anchor the comment onto an ancestor.
+     */
+    loc: FeedbackInput['loc'];
+    /**
+     * Highlight rectangle for this component (window coordinates), so pressing
+     * the crumb moves the on-screen selection outline onto it. Null when it
+     * couldn't be measured.
+     */
+    frame: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null;
+}
+/** Result of resolving a tap point to a source location. */
+export interface PickResult {
+    /** The precise tapped element's source location (the default target). */
+    loc: FeedbackInput['loc'];
+    /** Component display-name breadcrumb, newest (tapped) last. */
+    nameChain: string[];
+    /**
+     * Per-segment breadcrumb (same order as {@link nameChain}: root first,
+     * tapped component last), each carrying its own `loc` so pressing a
+     * breadcrumb can re-anchor the comment onto that ancestor.
+     */
+    chain: PickCrumb[];
+    /** Highlight rectangle in window coordinates, for the overlay outline. */
+    frame: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null;
+}

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

@@ -0,0 +1,54 @@
+/**
+ * RN WebSocket client for live agent streaming.
+ *
+ * Connects to the same Metro host the feedback POST uses (derived from
+ * `devServerBaseUrl()`), swapping the scheme to `ws(s)` and hitting
+ * `/__pinagent/ws` — the endpoint the server mounts via
+ * `pinagentWebsocketEndpoints` (Metro `config.server.websocketEndpoints`).
+ * Because it rides Metro's own port, a physical device needs no port
+ * discovery: if the bundle loaded, this URL is reachable.
+ *
+ * The wire protocol is the web one (`@pinagent/shared`'s ws-protocol): we send
+ * `subscribe` / `user_message` / `ask_response` / `interrupt`, and receive
+ * `event` / `done` / `error`. On reconnect the server replays the full
+ * transcript, so we fire `onReset` first to let the UI rebuild from scratch.
+ *
+ * Scoped to ONE feedback id per client — the RN widget streams a single
+ * conversation at a time (the one just submitted). That keeps this far smaller
+ * than the web client's multiplexed map.
+ */
+import type { AgentEvent } from './transcript';
+export interface StreamHandlers {
+    /** A reconnect is about to replay the transcript — clear and rebuild. */
+    onReset(): void;
+    onEvent(event: AgentEvent): void;
+    /** The run's bus closed (agent finished or idle). */
+    onDone(): void;
+    onError(message: string): void;
+}
+/** Derive `ws(s)://host:port/__pinagent/ws` from Metro's bundle URL. */
+export declare function devServerWsUrl(): string | null;
+export declare class StreamClient {
+    private readonly feedbackId;
+    private readonly handlers;
+    private socket;
+    private reconnectDelay;
+    private reconnectTimer;
+    private closed;
+    private connectedBefore;
+    constructor(feedbackId: string, handlers: StreamHandlers);
+    /** Open the socket and subscribe. Safe to call once per instance. */
+    start(): void;
+    /** Tear down for good — no further reconnects. Call on unmount/dismiss. */
+    stop(): void;
+    /** Queue a follow-up turn for the agent. No-op if the socket isn't open. */
+    sendUserMessage(content: string): void;
+    /** Answer an `ask_user` prompt. */
+    sendAskResponse(askId: string, answer: string): void;
+    /** Interrupt the in-flight run. */
+    interrupt(): void;
+    private connect;
+    private onMessage;
+    private send;
+    private scheduleReconnect;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pinagent/react-native",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "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": [
@@ -25,6 +25,7 @@
   "type": "module",
   "exports": {
     ".": {
+      "types": "./dist/native/index.d.ts",
       "react-native": "./src/native/index.ts",
       "default": "./src/native/index.ts"
     },
@@ -75,16 +76,17 @@
   },
   "devDependencies": {
     "@types/node": "^25.9.1",
+    "@types/react": "^19.2.17",
     "@types/ws": "^8.18.1",
     "tsdown": "^0.22.0",
     "typescript": "^6.0.3",
-    "@pinagent/agent-runner": "0.0.0",
-    "@pinagent/db": "0.0.1"
+    "@pinagent/db": "0.0.1",
+    "@pinagent/agent-runner": "0.0.0"
   },
   "scripts": {
     "prebuild": "node scripts/copy-drizzle.mjs",
-    "build": "tsdown",
+    "build": "tsdown && tsc -p tsconfig.native.json",
     "dev": "tsdown --watch",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.native.json --noEmit"
   }
 }

package/src/native/inspector.ts

@@ -80,8 +80,21 @@ interface RawInspectorData {
   closestInstance?: { _debugSource?: RawFiberLike } | null;
   /** Some versions surface the resolved source straight on the payload. */
   source?: RawFiberLike | null;
-  /** The tapped host view's props — where `data-pa-loc` lands. */
+  /**
+   * NOT the tapped leaf's props. RN fills this from the nearest authored
+   * *composite owner's* FIRST host descendant (`getHostProps` →
+   * `findCurrentHostFiber`) — i.e. that component's outermost view — so a tap
+   * on a nested child surfaces its container here, not the element under the
+   * finger. Used only as a fallback; `closestPublicInstance` pins the leaf.
+   */
   props?: RawProps;
+  /**
+   * The public instance of the host view actually under the finger — the
+   * deepest hit-tested node. Fabric only; Paper passes a numeric view tag we
+   * can't bridge, so we degrade to `props`. Its fiber's `memoizedProps` carry
+   * the leaf's own `data-pa-loc`. See {@link tappedLeafLoc}.
+   */
+  closestPublicInstance?: unknown;
 }
 
 let cachedFn: InspectorFn | null | undefined;
@@ -128,6 +141,8 @@ interface FiberLike {
   tag?: number;
   return?: FiberLike | null;
   stateNode?: { canonical?: { publicInstance?: unknown } } | null;
+  /** Host fibers carry the committed props — where `data-pa-loc` rides. */
+  memoizedProps?: RawProps;
 }
 
 let cachedGetHandle: ((instance: unknown) => FiberLike | null) | null | undefined;
@@ -209,14 +224,57 @@ function paLocOf(props: RawProps): Loc | null {
   return parsePaLoc(props?.['data-pa-loc']);
 }
 
+/**
+ * Walk a host fiber's render-tree parent (`return`) chain, returning the first
+ * `data-pa-loc` found on a fiber's `memoizedProps` — the tapped element itself,
+ * or, when that exact host is untagged (a 3rd-party / RN-internal view), the
+ * nearest authored element enclosing it. Capped against a malformed `return`
+ * cycle. Pure over a fiber-like chain; exported for unit testing without an RN
+ * runtime.
+ */
+export function nearestPaLocUp(fiber: FiberLike | null): Loc | null {
+  for (let i = 0; fiber && i < 10_000; i++) {
+    const loc = paLocOf(fiber.memoizedProps);
+    if (loc) return loc;
+    fiber = fiber.return ?? null;
+  }
+  return null;
+}
+
+/**
+ * The source of the host view actually under the finger.
+ *
+ * RN's `data.props` is NOT the tapped leaf — it's the nearest authored
+ * composite owner's first host descendant (its outer container), so a tap on a
+ * nested child resolves to its parent. To land on the leaf, start from the
+ * hit-tested host (`data.closestPublicInstance`), bridge it to its fiber, and
+ * walk the render-tree parents for the nearest `data-pa-loc`. This mirrors the
+ * web widget walking up the DOM from the clicked node.
+ *
+ * Returns null when the instance can't be bridged (Paper, which surfaces only a
+ * numeric view tag) — `pickLoc` then falls back to `data.props`.
+ */
+function tappedLeafLoc(data: RawInspectorData): Loc | null {
+  return nearestPaLocUp(getHandleFromPublicInstance(data.closestPublicInstance));
+}
+
 /**
  * Resolve the source location. Preferred path: the build-time `data-pa-loc`
- * prop our babel plugin splices on (read from the tapped host view's props,
- * then from each owner outward). Fallback: RN's legacy `_debugSource` /
- * inspector `source` field, for older RN/React where they still exist.
+ * prop our babel plugin splices on — read first from the host view actually
+ * under the finger ({@link tappedLeafLoc}), then from `data.props` and each
+ * owner outward. Fallback: RN's legacy `_debugSource` / inspector `source`
+ * field, for older RN/React where they still exist.
  */
 function pickLoc(data: RawInspectorData, projectRoot: string): Loc | null {
-  // 1. `data-pa-loc` on the directly tapped host view.
+  // 0. The host view actually under the finger. MUST come first: `data.props`
+  //    (step 1) is the nearest composite owner's first host — an outer
+  //    container — so without this a tap on a nested child resolves to its
+  //    parent (e.g. a card's content tapped, but its screen layout returned).
+  const leaf = tappedLeafLoc(data);
+  if (leaf) return leaf;
+
+  // 1. `data-pa-loc` on `data.props` — the nearest authored owner's first host.
+  //    Fallback for when the touched host can't be bridged to a fiber (Paper).
   const direct = paLocOf(data.props);
   if (direct) return direct;
 
@@ -296,10 +354,12 @@ interface RawCrumb {
  */
 function nearestLoc(locs: (Loc | null)[], i: number): Loc | null {
   for (let j = i + 1; j < locs.length; j++) {
-    if (locs[j]) return locs[j];
+    const loc = locs[j];
+    if (loc) return loc;
   }
   for (let j = i - 1; j >= 0; j--) {
-    if (locs[j]) return locs[j];
+    const loc = locs[j];
+    if (loc) return loc;
   }
   return null;
 }

package/src/native/pin-icon.tsx

@@ -12,7 +12,7 @@
  * When the peer isn't installed we fall back to a View-drawn teardrop in the
  * same colour, so the FAB always shows a brand pin — never a generic glyph.
  */
-import type { ReactElement } from 'react';
+import type { ComponentType, ReactElement } from 'react';
 import { View } from 'react-native';
 
 // Canonical pinagent pin — mirror of PIN_PATH / BRAND_VIEWBOX in
@@ -22,9 +22,11 @@ const PIN_PATH =
 const VIEWBOX = '0 0 93 93';
 
 // The two react-native-svg components we use, or `null` when the peer isn't
-// installed. Typed loosely (the peer's types aren't a dep) — native/ isn't
-// tsc-typechecked, and these are only ever rendered as JSX elements.
-type SvgModule = { Svg: unknown; Path: unknown } | null;
+// installed. Typed as bare component types — `react-native-svg`'s own types
+// aren't a dependency, but `unknown` can't be used as a JSX element, and the
+// native source IS declaration-emitted (see tsconfig.native.json), so these
+// must be valid JSX element types.
+type SvgModule = { Svg: ComponentType<any>; Path: ComponentType<any> } | null;
 
 // Resolved once, on first render (dev only — see header). `undefined` = not yet
 // resolved, `null` = peer not installed.