@pinagent/react-native 0.1.4 → 0.2.2

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,117 @@
+/**
+ * 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;
+    /** The tapped host view's props — where `data-pa-loc` lands. */
+    props?: RawProps;
+}
+type Loc = NonNullable<PickResult['loc']>;
+/**
+ * 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.1.4",
+  "version": "0.2.2",
   "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"
     },
@@ -49,6 +50,7 @@
   "peerDependencies": {
     "react": ">=18",
     "react-native": ">=0.74",
+    "react-native-svg": ">=13",
     "react-native-view-shot": ">=3"
   },
   "peerDependenciesMeta": {
@@ -58,6 +60,9 @@
     "react-native": {
       "optional": true
     },
+    "react-native-svg": {
+      "optional": true
+    },
     "react-native-view-shot": {
       "optional": true
     }
@@ -71,6 +76,7 @@
   },
   "devDependencies": {
     "@types/node": "^25.9.1",
+    "@types/react": "^19.2.17",
     "@types/ws": "^8.18.1",
     "tsdown": "^0.22.0",
     "typescript": "^6.0.3",
@@ -79,8 +85,8 @@
   },
   "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/Pinagent.tsx

@@ -16,7 +16,7 @@
  * analog. Renders `null` in production so it has zero cost in release
  * builds.
  *
- * Flow: tap the 💬 FAB to arm picking → tap a view → we resolve its source
+ * 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
@@ -33,8 +33,10 @@
 import type { ReactElement } from 'react';
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import {
+  Animated,
   Keyboard,
   Modal,
+  PanResponder,
   Platform,
   Pressable,
   StyleSheet,
@@ -43,8 +45,10 @@ import {
   useWindowDimensions,
   View,
 } from 'react-native';
+import { BRAND_CREAM, BRAND_GOLD, BRAND_INK } from './brand';
 import { resolvePick } from './inspector';
 import { buildAdditionalAnchors, type ChipPick, removeChip } from './multi-pick';
+import { PinIcon } from './pin-icon';
 import { restorePills } from './restore';
 import { StreamSheet } from './StreamSheet';
 import { captureScreenshot } from './screenshot';
@@ -102,6 +106,109 @@ function useKeyboardHeight(): number {
   return height;
 }
 
+const FAB_SIZE = 52;
+// Resting insets matching the old fixed layout (right/bottom), plus a uniform
+// edge margin used to keep the button on-screen once it's free to roam.
+const FAB_MARGIN = 20;
+const FAB_BOTTOM = 40;
+// Movement (px) under which a press counts as a tap, not a drag.
+const FAB_TAP_SLOP = 6;
+
+interface DraggableFab {
+  panHandlers: ReturnType<typeof PanResponder.create>['panHandlers'];
+  transform: ReturnType<Animated.ValueXY['getTranslateTransform']>;
+}
+
+/**
+ * Make the FAB draggable anywhere on screen.
+ *
+ * The button defaults to the bottom-right (matching the old fixed `right: 20,
+ * bottom: 40` layout) but can be dragged to any edge — handy when it sits over
+ * the very control the developer wants to comment on. A single PanResponder
+ * owns BOTH gestures: a stationary press (total movement under `FAB_TAP_SLOP`)
+ * fires `onTap` to arm picking, while any real movement relocates the button.
+ * Position lives in an `Animated.ValueXY` of the button's top-left in window
+ * coords; we keep a plain-object mirror (`committed`) because PanResponder
+ * callbacks can't read an Animated.Value synchronously.
+ *
+ * Position is session-local: RN keeps no device store (the dev-server DB is the
+ * source of truth and holds no ephemeral UI state), so it resets to the default
+ * corner on reload — same as the rest of the widget's transient UI.
+ */
+function useDraggableFab(width: number, height: number, onTap: () => void): DraggableFab {
+  // Clamp a top-left position so the whole button stays on-screen.
+  const clamp = useCallback(
+    (x: number, y: number) => {
+      const maxX = Math.max(FAB_MARGIN, width - FAB_SIZE - FAB_MARGIN);
+      const maxY = Math.max(FAB_MARGIN, height - FAB_SIZE - FAB_MARGIN);
+      return {
+        x: Math.min(Math.max(FAB_MARGIN, x), maxX),
+        y: Math.min(Math.max(FAB_MARGIN, y), maxY),
+      };
+    },
+    [width, height],
+  );
+
+  // Default resting spot: bottom-right corner.
+  const home = useMemo(
+    () => clamp(width - FAB_SIZE - FAB_MARGIN, height - FAB_SIZE - FAB_BOTTOM),
+    [clamp, width, height],
+  );
+
+  const pos = useRef(new Animated.ValueXY(home)).current;
+  const committed = useRef(home);
+
+  // Keep the button on-screen across rotations / window-size changes.
+  useEffect(() => {
+    const next = clamp(committed.current.x, committed.current.y);
+    if (next.x !== committed.current.x || next.y !== committed.current.y) {
+      committed.current = next;
+      pos.setValue(next);
+    }
+  }, [clamp, pos]);
+
+  const responder = useMemo(
+    () =>
+      PanResponder.create({
+        // Claim the touch up front so a plain tap still reaches `onTap`; we
+        // discriminate tap vs drag by distance on release.
+        onStartShouldSetPanResponder: () => true,
+        onPanResponderGrant: () => {
+          // Drag relative to where the button currently rests.
+          pos.setOffset(committed.current);
+          pos.setValue({ x: 0, y: 0 });
+        },
+        onPanResponderMove: Animated.event([null, { dx: pos.x, dy: pos.y }], {
+          useNativeDriver: false,
+        }),
+        onPanResponderRelease: (_e, g) => {
+          pos.flattenOffset();
+          if (Math.abs(g.dx) <= FAB_TAP_SLOP && Math.abs(g.dy) <= FAB_TAP_SLOP) {
+            // No real movement → it was a tap; undo any sub-pixel drift.
+            pos.setValue(committed.current);
+            onTap();
+            return;
+          }
+          // Commit the dragged spot, clamped on-screen, with a small settle.
+          const next = clamp(committed.current.x + g.dx, committed.current.y + g.dy);
+          committed.current = next;
+          Animated.spring(pos, { toValue: next, useNativeDriver: false, bounciness: 0 }).start();
+        },
+        onPanResponderTerminate: (_e, g) => {
+          // Lost the responder mid-gesture (e.g. to a parent scroll view):
+          // keep wherever the drag had reached rather than snapping away.
+          pos.flattenOffset();
+          const next = clamp(committed.current.x + g.dx, committed.current.y + g.dy);
+          committed.current = next;
+          pos.setValue(next);
+        },
+      }),
+    [pos, clamp, onTap],
+  );
+
+  return { panHandlers: responder.panHandlers, transform: pos.getTranslateTransform() };
+}
+
 /**
  * Hard dev-only gate. `__DEV__` is `false` in release bundles, so the
  * whole widget — and its require()s into RN internals — drops out. Kept
@@ -160,6 +267,18 @@ function PinagentDev({ projectRoot = '', screenName }: PinagentProps): ReactElem
     setExpandedId((cur) => (cur === id ? null : cur));
   }, []);
 
+  // Tapping the FAB toggles picking; cancelling a pick also drops a pending
+  // "+ Add element" intent. Extracted so the draggable-FAB gesture can fire it
+  // on a stationary press (a drag relocates the button instead — see below).
+  const toggleFab = useCallback(() => {
+    setPhase((p) => {
+      if (p === 'picking') addingExtra.current = false;
+      return p === 'picking' ? 'idle' : 'picking';
+    });
+  }, []);
+
+  const fab = useDraggableFab(width, height, toggleFab);
+
   // Restore minimized pills after an app reload (Fast Refresh, shake-reload,
   // restart). The dev server (.pinagent/db.sqlite) is the source of truth — RN
   // keeps no device-local store — so on mount we fetch the conversation list,
@@ -266,13 +385,15 @@ function PinagentDev({ projectRoot = '', screenName }: PinagentProps): ReactElem
 
   // The source location the comment is currently anchored to: the precise
   // tapped element while the innermost crumb is selected, otherwise the
-  // chosen ancestor component's own location.
+  // chosen ancestor component's own (nearest-source-resolved) location. Each
+  // ancestor falls back to the precise tapped loc so an untaggable crumb still
+  // shows a real path rather than degrading to a bare component name.
   const activeLoc = useMemo(() => {
     if (!pick) return null;
     const last = pick.chain.length - 1;
     if (selectedIndex >= 0 && selectedIndex < pick.chain.length) {
       if (selectedIndex === last) return pick.loc ?? pick.chain[last]?.loc ?? null;
-      return pick.chain[selectedIndex]?.loc ?? null;
+      return pick.chain[selectedIndex]?.loc ?? pick.loc ?? null;
     }
     return pick.loc ?? null;
   }, [pick, selectedIndex]);
@@ -537,22 +658,27 @@ function PinagentDev({ projectRoot = '', screenName }: PinagentProps): ReactElem
         </View>
       </Modal>
 
-      {/* Floating action button. Toggles picking; shows status while
-          sending. Hidden during `capturing` so it stays out of the
-          screenshot. */}
+      {/* Floating action button. Drag it anywhere; tap to toggle picking.
+          Shows status while sending. Hidden during `capturing` so it stays
+          out of the screenshot. Positioned via an animated translate so the
+          PanResponder can move it (see useDraggableFab). */}
       {phase !== 'capturing' && (
-        <Pressable
-          onPress={() =>
-            setPhase((p) => {
-              // Cancelling a pick also drops a pending "+ Add element" intent.
-              if (p === 'picking') addingExtra.current = false;
-              return p === 'picking' ? 'idle' : 'picking';
-            })
-          }
-          style={[styles.fab, phase === 'picking' && styles.fabActive]}
+        <Animated.View
+          {...fab.panHandlers}
+          accessibilityRole="button"
+          accessibilityLabel="Pinagent — tap to comment, drag to move"
+          style={[
+            styles.fab,
+            phase === 'picking' && styles.fabActive,
+            { transform: fab.transform },
+          ]}
         >
-          <Text style={styles.fabText}>{phase === 'sending' ? '…' : '💬'}</Text>
-        </Pressable>
+          {phase === 'sending' ? (
+            <Text style={styles.fabText}>…</Text>
+          ) : (
+            <PinIcon size={26} color={BRAND_CREAM} />
+          )}
+        </Animated.View>
       )}
 
       {toast && (
@@ -673,13 +799,20 @@ const styles = StyleSheet.create({
   btnDisabled: { opacity: 0.4 },
   btnPrimaryText: { color: '#fff', fontWeight: '600' },
   fab: {
+    // Anchored top-left; the live position is applied via an animated
+    // translate so the FAB can be dragged (see useDraggableFab). FAB_SIZE
+    // must stay in sync with width/height below.
     position: 'absolute',
-    right: 20,
-    bottom: 40,
+    left: 0,
+    top: 0,
     width: 52,
     height: 52,
     borderRadius: 26,
-    backgroundColor: '#111827',
+    backgroundColor: BRAND_INK,
+    // Constant-width rim so toggling the active gold ring never shifts layout;
+    // cream @ 14% is the same subtle idle rim the web widget FAB uses.
+    borderWidth: 2,
+    borderColor: 'rgba(252, 249, 232, 0.14)',
     alignItems: 'center',
     justifyContent: 'center',
     shadowColor: '#000',
@@ -688,8 +821,9 @@ const styles = StyleSheet.create({
     shadowOffset: { width: 0, height: 2 },
     elevation: 5,
   },
-  fabActive: { backgroundColor: '#3b82f6' },
-  fabText: { fontSize: 22 },
+  // Gold ring while picking (web widget parity) — replaces the old blue fill.
+  fabActive: { borderColor: BRAND_GOLD },
+  fabText: { fontSize: 22, color: BRAND_CREAM },
   toast: {
     position: 'absolute',
     bottom: 110,

package/src/native/brand.ts

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * 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 const BRAND_INK = '#201B21';
+/** Warm cream — the pin mark on dark surfaces, light backgrounds, brand identity. */
+export const BRAND_CREAM = '#FCF9E8';
+/** Gold accent — focus rings; the active picking state. */
+export const BRAND_GOLD = '#FFD700';

package/src/native/inspector.ts

@@ -282,19 +282,65 @@ interface RawCrumb {
   measure?: (cb: RawMeasureCb) => void;
 }
 
+/**
+ * The nearest resolvable source to hierarchy index `i`, searching descendants
+ * first (deeper into the component, toward the tapped leaf) then ancestors
+ * (outward toward the root). Returns the first non-null `loc`, or null.
+ *
+ * Why descendants first: a crumb's own props come from RN's `getInspectorData`,
+ * which surfaces the first HOST fiber *inside* that component's render
+ * (`getHostProps`/`findCurrentHostFiber`). When that host carries no
+ * `data-pa-loc` (e.g. it's an untagged 3rd-party view), the most relevant real
+ * source is still the next tagged host *within* this component's subtree — a
+ * descendant — before we fall back to an enclosing ancestor.
+ */
+function nearestLoc(locs: (Loc | null)[], i: number): Loc | null {
+  for (let j = i + 1; j < locs.length; j++) {
+    const loc = locs[j];
+    if (loc) return loc;
+  }
+  for (let j = i - 1; j >= 0; j--) {
+    const loc = locs[j];
+    if (loc) return loc;
+  }
+  return null;
+}
+
 /**
  * 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`).
  */
-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 };
-    });
+export function crumbsOf(data: RawInspectorData): RawCrumb[] {
+  // Resolve each hierarchy item's inspector data ONCE. We compute locs over the
+  // FULL hierarchy (not just the authored crumbs) so the nearest-source
+  // fallback can borrow a location from an untagged host sitting between two
+  // authored components.
+  const items = (data.hierarchy ?? []).map((h) => {
+    const inspector = h.getInspectorData?.(() => null);
+    return { name: h.name, loc: paLocOf(inspector?.props), measure: inspector?.measure };
+  });
+  const locs = items.map((it) => it.loc);
+  return items
+    .map((it, i) => ({ it, i }))
+    .filter(({ it }) => isAuthoredComponentName(it.name))
+    .map(({ it, i }) => ({
+      name: it.name as string,
+      loc: it.loc ?? nearestLoc(locs, i),
+      measure: it.measure,
+    }));
 }
 
 /**

package/src/native/pin-icon.tsx

@@ -0,0 +1,88 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * 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 { ComponentType, ReactElement } from 'react';
+import { View } from 'react-native';
+
+// Canonical pinagent pin — mirror of PIN_PATH / BRAND_VIEWBOX in
+// `packages/ui/src/tokens.ts`. Keep in sync if the mark changes there.
+const PIN_PATH =
+  'M38.0761 27C24.2046 27 16.7486 43.8193 26.2852 53.7027L26.4587 53.8761L47.2659 74.6834L68.0732 53.8761L68.2466 53.7027C77.9567 43.8193 70.3273 27 56.4558 27L38.0761 27Z';
+const VIEWBOX = '0 0 93 93';
+
+// The two react-native-svg components we use, or `null` when the peer isn't
+// 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.
+let svgModule: SvgModule | undefined;
+function resolveSvg(): SvgModule {
+  if (svgModule !== undefined) return svgModule;
+  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 mod = require('react-native-svg');
+    svgModule = { Svg: mod.Svg ?? mod.default, Path: mod.Path };
+  } catch {
+    svgModule = null;
+  }
+  return svgModule;
+}
+
+export interface PinIconProps {
+  /** Square edge length, in px. */
+  size?: number;
+  /** Fill colour of the pin (pass a brand token). */
+  color: string;
+}
+
+export function PinIcon({ size = 26, color }: PinIconProps): ReactElement {
+  const svg = resolveSvg();
+  if (svg?.Svg && svg.Path) {
+    const { Svg, Path } = svg;
+    return (
+      <Svg width={size} height={size} viewBox={VIEWBOX}>
+        <Path d={PIN_PATH} fill={color} />
+      </Svg>
+    );
+  }
+  return <FallbackPin size={size} color={color} />;
+}
+
+/**
+ * react-native-svg-free fallback: a map-pin teardrop drawn from a single View —
+ * a rounded square with one squared corner, rotated so the point faces down.
+ * The classic CSS `border-radius: 50% 50% 50% 0` recipe, in the brand colour.
+ */
+function FallbackPin({ size, color }: { size: number; color: string }): ReactElement {
+  const d = Math.round(size * 0.8);
+  return (
+    <View
+      style={{
+        width: d,
+        height: d,
+        backgroundColor: color,
+        borderTopLeftRadius: d / 2,
+        borderTopRightRadius: d / 2,
+        borderBottomRightRadius: d / 2,
+        borderBottomLeftRadius: 0,
+        transform: [{ rotate: '-45deg' }],
+      }}
+    />
+  );
+}