Skip to content

feat: add React Native support with agentation-rn package #48

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
skylarbarrera wants to merge 6 commits into
base: main
Choose a base branch
from
Open

feat: add React Native support with agentation-rn package #48

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
13febca
feat: add React Native support with agentation-rn package
skylarbarrera Jan 25, 2026
5b07e53
refactor(agentation-rn): major code reorganization and settings panel…
skylarbarrera Jan 26, 2026
d419c92
fix(agentation-rn): reorder toolbar buttons to match web (Copy, Trash…
skylarbarrera Jan 26, 2026
18e7a6f
feat(agentation-rn): add light/dark mode theming
skylarbarrera Jan 26, 2026
73f49ba
feat(agentation-rn): add markers visibility toggle and toolbar parity…
skylarbarrera Jan 26, 2026
ae675fe
refactor(agentation-rn): dead code removal and web API parity
skylarbarrera Jan 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .npmrc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,2 +1,5 @@
node-linker=hoisted
public-hoist-pattern[]=*react*
public-hoist-pattern[]=*@types/react*
public-hoist-pattern[]=*expo*
public-hoist-pattern[]=*react-native*
15 changes: 14 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,10 +40,23 @@ The toolbar appears in the bottom-right corner. Click to activate, then click an

Agentation captures class names, selectors, and element positions so AI agents can `grep` for the exact code you're referring to. Instead of describing "the blue button in the sidebar," you give the agent `.sidebar > button.primary` and your feedback.

## Packages

| Package | Platform | Install |
|---------|----------|---------|
| `agentation` | Web (React) | `npm install agentation` |
| `agentation-rn` | React Native | `npm install agentation-rn` |

## Requirements

### Web
- React 18+
- Desktop browser (mobile not supported)
- Desktop browser

### React Native
- React Native >= 0.72.0
- React >= 18.0.0
- iOS & Android supported

## Docs

Expand Down
2 changes: 2 additions & 0 deletions packages/agentation-rn/.gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
node_modules/
dist/
79 changes: 79 additions & 0 deletions packages/agentation-rn/CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
# Agentation RN Package

This is the publishable npm package for React Native. Changes here affect everyone who installs `agentation-rn`.

## Critical Rules

1. **NEVER run `npm publish`** - Only publish when explicitly instructed
2. **NEVER bump version** in package.json without explicit instruction
3. **NEVER modify exports** in index.ts without discussing breaking changes

## What Gets Published

- `dist/` folder (compiled from `src/`)
- `package.json`, `README.md`, `LICENSE`

## Before Modifying `src/`

- Consider: Is this a breaking change?
- Consider: Does this affect the API surface?
- Consider: Will existing users' code still work?
- Consider: Does this break parity with the web package?

## Main Export

```tsx
import { Agentation } from 'agentation-rn';
```

## Mobile-Specific APIs

These are React Native additions not in the web package:

- `useAgentationScroll` - ScrollView marker positioning
- `AgenationView` - Modal/sheet annotation context

## Programmatic API (Web Parity)

The component exposes these callback props (matching web 1.2.0+):

- `onAnnotationAdd(annotation)` - when annotation created
- `onAnnotationDelete(annotation)` - when annotation deleted
- `onAnnotationUpdate(annotation)` - when annotation edited
- `onAnnotationsClear(annotations[])` - when all cleared
- `onCopy(markdown)` - when copy button clicked
- `copyToClipboard` (boolean, default: true)

**API stability**: These are public contracts. Changing signatures or removing callbacks is a breaking change requiring a major version bump.

## Testing Changes

1. Run `pnpm build` to ensure it compiles
2. Run `pnpm typecheck` for TypeScript validation
3. Test the example app on iOS: `cd example && pnpm ios`
4. Test the example app on Android: `cd example && pnpm android`

## Publishing

When instructed to publish a new npm version:

1. Bump version in `package.json`
2. Run `pnpm build`
3. Commit the version bump
4. Run `npm publish --access public` (will prompt for OTP)
5. Push to main

## Web API Parity

Maintain compatibility with the web `agentation` package:

| Feature | Web | RN | Notes |
|---------|-----|-----|-------|
| Annotation callbacks | ✅ | ✅ | Same signatures |
| Demo mode | ✅ | ✅ | Same props |
| Output levels | ✅ | ✅ | compact/standard/detailed/forensic |
| Settings persistence | ✅ | ✅ | localStorage vs AsyncStorage |
| `identifyElement` | ✅ | ✅ | Alias for `detectComponent` |
| `getElementPath` | ✅ | ✅ | Alias for `formatElementPath` |

When adding features, consider if they should also be added to the web package.
27 changes: 27 additions & 0 deletions packages/agentation-rn/LICENSE
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
PolyForm Shield License 1.0.0

Copyright (c) 2026 Benji Taylor

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to use,
copy, modify, and distribute the Software, subject to the following conditions:

1. You may not use the Software to provide a product or service that competes
with the Software or any product or service offered by the Licensor that
includes the Software.

2. You may not remove or obscure any licensing, copyright, or other notices
included in the Software.

3. If you distribute the Software or any derivative works, you must include a
copy of this license.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

For more information, see https://polyformproject.org/licenses/shield/1.0.0
212 changes: 212 additions & 0 deletions packages/agentation-rn/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,212 @@
# agentation-rn

React Native support for [Agentation](https://agentation.dev) - Visual feedback for AI coding agents.

Tap components in your app to create annotations, then copy structured markdown output for AI tools like Claude Code.

## Installation

```bash
npm install agentation-rn
# or
yarn add agentation-rn
# or
pnpm add agentation-rn
```

### Peer Dependencies

```bash
npm install react-native-safe-area-context
```

Optional (for enhanced features):
```bash
npm install @callstack/liquid-glass react-native-svg
```

## Quick Start

```tsx
import { Agentation } from 'agentation-rn';

export default function App() {
return (
<Agentation
onAnnotationAdd={(annotation) => console.log('Added:', annotation)}
onCopy={(markdown) => {
// Send to your AI tool
console.log('Markdown:', markdown);
}}
>
<YourApp />
</Agentation>
);
}
```

## Features

- **Tap to Annotate** - Tap any component to create an annotation
- **Component Detection** - Automatically identifies React components with file paths and line numbers
- **Structured Output** - Generates AI-ready markdown with element context
- **4 Detail Levels** - compact, standard, detailed, forensic
- **Settings Persistence** - Saves preferences via AsyncStorage
- **Navigation Support** - Detects React Navigation routes

## API

### `<Agentation>`

Main wrapper component. Provides annotation functionality to your entire app.

```tsx
<Agentation
onAnnotationAdd={(annotation) => {}} // Called when annotation created
onAnnotationUpdate={(annotation) => {}} // Called when annotation edited
onAnnotationDelete={(annotation) => {}} // Called when annotation deleted
onAnnotationsClear={(annotations) => {}} // Called when all cleared
onCopy={(markdown) => {}} // Called when markdown copied
>
<YourApp />
</Agentation>
```

### Mobile-Specific APIs

#### `useAgentationScroll`

Required for ScrollViews - keeps annotation markers positioned correctly during scroll.

```tsx
import { useAgentationScroll } from 'agentation-rn';

function MyScreen() {
const { onScroll, scrollEventThrottle } = useAgentationScroll();

return (
<ScrollView
onScroll={onScroll}
scrollEventThrottle={scrollEventThrottle}
>
{/* Your content */}
</ScrollView>
);
}
```

#### `<AgenationView>`

For Modals and Sheets - provides isolated annotation context since iOS modals render outside the normal view hierarchy.

```tsx
import { AgenationView } from 'agentation-rn';
import { Modal } from 'react-native';

function MyModal({ visible, onClose }) {
return (
<Modal visible={visible} onRequestClose={onClose}>
<AgenationView>
<ModalContent />
</AgenationView>
</Modal>
);
}
```

### Hooks

#### `useAnnotations`

Low-level hook for custom annotation UIs.

```tsx
import { useAnnotations } from 'agentation-rn';

const {
annotations,
addAnnotation,
updateAnnotation,
deleteAnnotation,
clearAnnotations,
copyToClipboard,
settings,
updateSettings,
} = useAnnotations({ screenName: 'MyScreen' });
```

### Utilities

```tsx
import {
// Component detection
detectComponent,
identifyElement, // alias for detectComponent
formatElementPath,
getElementPath, // alias for formatElementPath

// Markdown generation
generateMarkdown,
generateSimpleMarkdown,

// Storage
saveAnnotations,
loadAnnotations,
clearAnnotations,

// Helpers
copyToClipboard,
generateId,
} from 'agentation-rn';
```

## Platform Support

| Platform | Status |
|----------|--------|
| iOS | Supported |
| Android | Supported |
| React Native | >= 0.72.0 |
| React | >= 18.0.0 |

### Navigation Support

| Library | Status |
|---------|--------|
| React Navigation | Supported |
| Expo Router | Coming soon |

## Output Example

When you copy annotations, you get structured markdown:

```markdown
# App Feedback - MyScreen

## Annotation 1
- **Element:** Button (src/components/Button.tsx:42)
- **Comment:** This button should be larger
- **Position:** x: 150, y: 320

## Annotation 2
- **Element:** Text (src/screens/Home.tsx:18)
- **Comment:** Font size too small on mobile
- **Position:** x: 20, y: 180
```

## Running the Example

```bash
cd packages/agentation-rn/example
pnpm install

# iOS
pnpm ios

# Android
pnpm android
```

## License

PolyForm-Shield-1.0.0
6 changes: 6 additions & 0 deletions packages/agentation-rn/example/.gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
node_modules/
.expo/

# Native folders - generated by `npx expo prebuild`
ios/
android/
Loading