@pinagent/react-native 0.1.0

package/src/native/inspector.ts

@@ -0,0 +1,407 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * 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';
+
+// Internal RN module — not a public export, but the path has been stable
+// and is what the built-in Inspector imports. Typed loosely on purpose.
+//
+// `inspectedView` must be a **host component public instance** (a view ref's
+// `.current`), NOT a `findNodeHandle` tag: on Fabric the renderer calls
+// `getNodeFromPublicInstance(inspectedView)` and then hit-tests *within that
+// view's shadow subtree*. A number fails the guard ("expects to receive a
+// host component"); the instance must also be an ancestor of the tapped view,
+// so we pass the app root (see `rootHostInstance`), not pinagent's overlay.
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+type InspectorFn = (
+  inspectedView: unknown,
+  locationX: number,
+  locationY: number,
+  callback: (data: RawInspectorData) => void,
+) => void;
+
+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;
+  /** The tapped host view's props — where `data-pa-loc` lands. */
+  props?: RawProps;
+}
+
+let cachedFn: InspectorFn | null | undefined;
+
+function asFn(mod: unknown): InspectorFn | null {
+  const fn = (mod as { default?: unknown })?.default ?? mod;
+  return typeof fn === 'function' ? (fn as InspectorFn) : null;
+}
+
+function loadInspector(): InspectorFn | null {
+  if (cachedFn !== undefined) return cachedFn;
+  // The inspector module moved in RN 0.81:
+  //   Libraries/Inspector/… → src/private/devsupport/devmenu/elementinspector/…
+  // We require the RN 0.81+ path only and deliberately do NOT fall back to the
+  // pre-0.81 `Libraries/Inspector/…` path: that file no longer exists on modern
+  // RN, so a static `require` of it makes Metro's resolver log an "invalid
+  // package.json / file does not exist" warning on every bundle (RN's `./*`
+  // exports entry maps it to a missing `.js`). The legacy inspector also
+  // predates the build-time `data-pa-loc` prop this package relies on, so it
+  // couldn't carry a location anyway — pre-0.81 RN degrades to `loc: null`.
+  // Lazy so a production build (widget tree-shaken / `__DEV__`-gated away)
+  // never reaches into RN internals.
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires, global-require
+    const fn = asFn(
+      require('react-native/src/private/devsupport/devmenu/elementinspector/getInspectorDataForViewAtPoint'),
+    );
+    if (fn) {
+      cachedFn = fn;
+      return cachedFn;
+    }
+  } catch {
+    // Module absent (release build, Node/CI, or an RN version that moved it).
+  }
+  cachedFn = null;
+  return cachedFn;
+}
+
+// React fiber tag for a host component (`<View>`, `<Text>`, …). Stable across
+// React versions.
+const HOST_COMPONENT = 5;
+
+interface FiberLike {
+  tag?: number;
+  return?: FiberLike | null;
+  stateNode?: { canonical?: { publicInstance?: unknown } } | null;
+}
+
+let cachedGetHandle: ((instance: unknown) => FiberLike | null) | null | undefined;
+
+function getHandleFromPublicInstance(instance: unknown): FiberLike | null {
+  if (cachedGetHandle === undefined) {
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-var-requires, global-require
+      const RNPrivate = require('react-native/Libraries/ReactPrivate/ReactNativePrivateInterface');
+      const fn = RNPrivate?.getInternalInstanceHandleFromPublicInstance;
+      cachedGetHandle = typeof fn === 'function' ? fn : null;
+    } catch {
+      cachedGetHandle = null;
+    }
+  }
+  try {
+    return cachedGetHandle ? cachedGetHandle(instance) : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Climb from pinagent's own overlay view to the app's **root** host view and
+ * return its public instance.
+ *
+ * Why: `getInspectorDataForViewAtPoint` hit-tests *within* the shadow subtree
+ * of the instance we pass. pinagent mounts as a sibling/descendant of the
+ * app, so its own view's subtree doesn't contain the tapped component — we
+ * must hand the inspector an ancestor that does. RN's built-in Inspector uses
+ * `AppContainer`'s inner root view for exactly this; we reach the same node by
+ * walking the fiber `return` chain to the topmost host component.
+ *
+ * Defensive: any failure (Paper, an RN internals shuffle, a null handle)
+ * falls back to the instance we were given — the picker degrades, never
+ * throws.
+ */
+function rootHostInstance(publicInstance: unknown): unknown {
+  let fiber = getHandleFromPublicInstance(publicInstance);
+  if (!fiber) return publicInstance;
+  let topHost: FiberLike | null = null;
+  // Cap the walk — a malformed `return` cycle must not spin forever.
+  for (let i = 0; fiber && i < 10_000; i++) {
+    if (fiber.tag === HOST_COMPONENT) topHost = fiber;
+    fiber = fiber.return ?? null;
+  }
+  const rootInstance = topHost?.stateNode?.canonical?.publicInstance;
+  return rootInstance ?? publicInstance;
+}
+
+/**
+ * Turn an absolute `_debugSource.fileName` into the project-relative,
+ * POSIX path the rest of pinagent expects (matching what the web babel
+ * plugin emits). Falls back to the raw filename if it isn't under root.
+ */
+function toProjectRelative(fileName: string, projectRoot: string): string {
+  const norm = fileName.replace(/\\/g, '/');
+  const root = projectRoot.replace(/\\/g, '/').replace(/\/+$/, '');
+  if (root && norm.startsWith(`${root}/`)) return norm.slice(root.length + 1);
+  return norm;
+}
+
+type Loc = NonNullable<PickResult['loc']>;
+
+/**
+ * Parse a `data-pa-loc` value (`"src/Foo.tsx:42:7"`) into a {@link Loc}.
+ * The path may itself contain colons on exotic platforms, so we split off
+ * the trailing `:line:col` rather than splitting greedily.
+ */
+function parsePaLoc(value: unknown): Loc | null {
+  if (typeof value !== 'string') return null;
+  const m = /^(.*):(\d+):(\d+)$/.exec(value);
+  if (!m) return null;
+  return { file: m[1]!, line: Number(m[2]), col: Number(m[3]) };
+}
+
+/** The first `data-pa-loc` found on the tapped view or its nearest owner. */
+function paLocOf(props: RawProps): Loc | null {
+  return parsePaLoc(props?.['data-pa-loc']);
+}
+
+/**
+ * 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.
+ */
+function pickLoc(data: RawInspectorData, projectRoot: string): Loc | null {
+  // 1. `data-pa-loc` on the directly tapped host view.
+  const direct = paLocOf(data.props);
+  if (direct) return direct;
+
+  // 2. `data-pa-loc` walking the owner hierarchy from the tapped element out.
+  for (let i = (data.hierarchy?.length ?? 0) - 1; i >= 0; i--) {
+    const item = data.hierarchy?.[i];
+    const loc = paLocOf(item?.getInspectorData?.(() => null)?.props);
+    if (loc) return loc;
+  }
+
+  // 3. Legacy `_debugSource` / inspector `source` (pre-React-19 / pre-0.81).
+  const src = legacySource(data);
+  if (src?.fileName && typeof src.lineNumber === 'number') {
+    return {
+      file: toProjectRelative(src.fileName, projectRoot),
+      line: src.lineNumber,
+      col: src.columnNumber ?? 0,
+    };
+  }
+  return null;
+}
+
+function legacySource(data: RawInspectorData): RawFiberLike | null {
+  if (data.source?.fileName) return data.source;
+  if (data.closestInstance?._debugSource?.fileName) {
+    return data.closestInstance._debugSource;
+  }
+  for (let i = (data.hierarchy?.length ?? 0) - 1; i >= 0; i--) {
+    const item = data.hierarchy?.[i];
+    const src = item?.getInspectorData?.(() => null)?.source;
+    if (src?.fileName) return src;
+  }
+  return 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 function isAuthoredComponentName(name: unknown): name is string {
+  return (
+    typeof name === 'string' && name.length > 0 && !name.startsWith('RCT') && !name.includes('(')
+  );
+}
+
+function nameChainOf(data: RawInspectorData): string[] {
+  return (data.hierarchy ?? []).map((h) => h.name).filter(isAuthoredComponentName);
+}
+
+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.
+ */
+function crumbsOf(data: RawInspectorData): RawCrumb[] {
+  return (data.hierarchy ?? [])
+    .filter((h): h is RawHierarchyItem & { name: string } => isAuthoredComponentName(h.name))
+    .map((h) => {
+      const inspector = h.getInspectorData?.(() => null);
+      return { name: h.name, loc: paLocOf(inspector?.props), measure: inspector?.measure };
+    });
+}
+
+/**
+ * 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 function measureFrame(measure?: (cb: RawMeasureCb) => void): Promise<Frame | null> {
+  if (!measure) return Promise.resolve(null);
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (f: Frame | null) => {
+      if (!settled) {
+        settled = true;
+        resolve(f);
+      }
+    };
+    const timer = setTimeout(() => finish(null), 150);
+    try {
+      measure((_x, _y, width, height, pageX, pageY) => {
+        clearTimeout(timer);
+        finish(width > 0 || height > 0 ? { x: pageX, y: pageY, width, height } : null);
+      });
+    } catch {
+      clearTimeout(timer);
+      finish(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 function resolvePick(
+  rootView: unknown,
+  x: number,
+  y: number,
+  projectRoot: string,
+): Promise<PickResult> {
+  const fn = loadInspector();
+  if (!fn) {
+    // Inspector unavailable (release build, or an RN version that moved
+    // the module). Degrade gracefully — the comment can still be filed
+    // with `loc: null`, which the server accepts.
+    return Promise.resolve({ loc: null, nameChain: [], chain: [], frame: null });
+  }
+  const inspectedView = rootHostInstance(rootView);
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (r: PickResult) => {
+      if (!settled) {
+        settled = true;
+        resolve(r);
+      }
+    };
+    // The callback is sometimes never invoked if the point misses every
+    // view; guard with a microtask-ish fallback so the picker can't hang.
+    const timer = setTimeout(() => done({ loc: null, nameChain: [], chain: [], frame: null }), 250);
+    try {
+      fn(inspectedView, x, y, (data) => {
+        clearTimeout(timer);
+        const frame = data.frame
+          ? {
+              x: data.frame.left,
+              y: data.frame.top,
+              width: data.frame.width,
+              height: data.frame.height,
+            }
+          : null;
+        const rawCrumbs = crumbsOf(data);
+        const loc = pickLoc(data, projectRoot);
+        const nameChain = nameChainOf(data);
+        // Measure each crumb so pressing one can move the on-screen highlight
+        // to that ancestor. Concurrent, each guarded — adds ~one measure pass.
+        Promise.all(rawCrumbs.map((c) => measureFrame(c.measure)))
+          .then((frames) => {
+            done({
+              loc,
+              nameChain,
+              chain: rawCrumbs.map((c, i) => ({
+                name: c.name,
+                loc: c.loc,
+                frame: frames[i] ?? null,
+              })),
+              frame,
+            });
+          })
+          .catch(() => {
+            // Measuring failed wholesale — still return the pick without
+            // per-crumb frames rather than hang.
+            done({
+              loc,
+              nameChain,
+              chain: rawCrumbs.map((c) => ({ name: c.name, loc: c.loc, frame: null })),
+              frame,
+            });
+          });
+      });
+    } catch {
+      clearTimeout(timer);
+      done({ loc: null, nameChain: [], chain: [], frame: null });
+    }
+  });
+}

package/src/native/multi-pick.ts

@@ -0,0 +1,74 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * 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;
+}
+
+/** Map one extra pick to the wire `AdditionalAnchor` shape. */
+function toAnchor(pick: ChipPick): AdditionalAnchor {
+  return {
+    file: pick.loc?.file ?? null,
+    line: pick.loc?.line ?? null,
+    col: pick.loc?.col ?? null,
+    selector: pick.selector,
+    clickX: Math.round(pick.clickX),
+    clickY: Math.round(pick.clickY),
+  };
+}
+
+/**
+ * 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 function buildAdditionalAnchors(
+  extras: readonly ChipPick[],
+): AdditionalAnchor[] | undefined {
+  if (extras.length === 0) return undefined;
+  return extras.map(toAnchor);
+}
+
+/**
+ * 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 function removeChip(picks: readonly ChipPick[], key: string): ChipPick[] {
+  return picks.filter((p) => p.key !== key);
+}

package/src/native/restore.ts

@@ -0,0 +1,91 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * 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 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;
+}
+
+function isNonEmptyString(v: unknown): v is string {
+  return typeof v === 'string' && v.length > 0;
+}
+
+/** Human-readable target for the pill header (mirrors `onSubmit`'s logic). */
+function targetFor(item: RestoreCandidate): string {
+  if (isNonEmptyString(item.file) && typeof item.line === 'number') {
+    return `${item.file}:${item.line}`;
+  }
+  if (isNonEmptyString(item.selector)) {
+    // The selector is the component name-chain ("App > Home > Button"); the
+    // innermost (tapped) component is the most useful label.
+    const last = item.selector.split('>').pop()?.trim();
+    if (last) return last;
+  }
+  return 'component';
+}
+
+/**
+ * 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 function restorePills(
+  items: readonly RestoreCandidate[] | null | undefined,
+  surfaceUrl: string,
+  limit: number = RESTORE_LIMIT,
+): RestoredPill[] {
+  if (!Array.isArray(items)) return [];
+  return items
+    .filter((it) => isNonEmptyString(it.id) && it.status === 'pending' && it.url === surfaceUrl)
+    .sort((a, b) => updatedAtMs(b.updatedAt) - updatedAtMs(a.updatedAt))
+    .slice(0, Math.max(0, limit))
+    .map((it) => ({ id: it.id as string, target: targetFor(it) }));
+}
+
+/** Parse an ISO `updatedAt` to epoch ms; unparseable values sort oldest (0). */
+function updatedAtMs(v: unknown): number {
+  if (typeof v !== 'string') return 0;
+  const ms = Date.parse(v);
+  return Number.isNaN(ms) ? 0 : ms;
+}

package/src/native/screenshot.ts

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Screenshot capture — the RN analog of the web widget's `html-to-image`.
+ *
+ * Uses `react-native-view-shot`'s `captureScreen`, which snapshots the
+ * whole window (so the picked component plus its surroundings land in the
+ * image, same as the web capture). Returns base64 PNG with no `data:`
+ * prefix, matching the `screenshot` field the middleware decodes.
+ *
+ * `react-native-view-shot` is an optional peer: if it isn't installed we
+ * return a 1x1 transparent PNG so the comment can still be filed (the
+ * server requires a non-empty screenshot string). The same transparent
+ * placeholder the web widget uses on capture failure.
+ */
+const TRANSPARENT_PNG_BASE64 =
+  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=';
+
+export async function captureScreenshot(): Promise<string> {
+  try {
+    // Lazy require so a release build never pulls the native module in.
+    // eslint-disable-next-line @typescript-eslint/no-var-requires, global-require
+    const { captureScreen } = require('react-native-view-shot');
+    // result: 'base64' returns the raw base64 string (no data: prefix),
+    // which is exactly what FeedbackInput.screenshot wants.
+    const b64: string = await captureScreen({
+      format: 'png',
+      quality: 0.9,
+      result: 'base64',
+    });
+    return b64;
+  } catch {
+    return TRANSPARENT_PNG_BASE64;
+  }
+}

package/src/native/submit-outcome.ts

@@ -0,0 +1,70 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * 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 function submitOutcome(result: SubmitOutcomeInput): SubmitOutcome {
+  if (!result.ok) {
+    return {
+      composer: 'keep',
+      error: `Failed: ${result.error ?? 'unknown'}`,
+      streamId: null,
+      toast: null,
+    };
+  }
+  if (result.agentSpawned && result.id) {
+    return { composer: 'clear', error: null, streamId: result.id, toast: null };
+  }
+  return { composer: 'clear', error: null, streamId: null, toast: 'Sent' };
+}