@pinagent/react-native 0.1.2 → 0.2.1

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,63 @@ 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++) {
+    if (locs[j]) return locs[j];
+  }
+  for (let j = i - 1; j >= 0; j--) {
+    if (locs[j]) return locs[j];
+  }
+  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,86 @@
+// 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 { 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 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;
+
+// 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' }],
+      }}
+    />
+  );
+}