+
+
+
+```
+
+## Component Reference
+
+See the [Native UI Component Reference](./reference.md) for a complete list of available components and their properties.
+
+## Common Patterns
+
+### 1. Building an iOS-Style Form
+
+```tsx
+import {
+ FlutterCupertinoFormSection,
+ FlutterCupertinoFormRow,
+ FlutterCupertinoTextField,
+ FlutterCupertinoButton
+} from '@openwebf/react-cupertino-ui';
+
+export function ProfileForm() {
+ return (
+
+
+
+
+
+
+
+
+ Save Changes
+
+
+ );
+}
+```
+
+### 2. Building a Settings Screen
+
+```tsx
+import {
+ FlutterCupertinoListSection,
+ FlutterCupertinoListTile,
+ FlutterCupertinoSwitch
+} from '@openwebf/react-cupertino-ui';
+
+export function SettingsScreen() {
+ return (
+
+ }
+ />
+ }
+ />
+
+ );
+}
+```
+
+### 3. Showing a Native Dialog
+
+```tsx
+import { FlutterCupertinoAlertDialog } from '@openwebf/react-cupertino-ui';
+
+export function ConfirmationDialog({ onConfirm, onCancel }) {
+ return (
+
+ );
+}
+```
+
+## Best Practices
+
+### 1. Mix Native UI with HTML/CSS
+You don't have to use native UI everywhere. Mix and match:
+```tsx
+// Use native components for platform-specific UIs
+
+ Save
+
+
+// Use HTML/CSS for custom layouts
+
+
Custom Design
+
This uses regular HTML/CSS
+
+```
+
+### 2. Use Native UI for Complex Components
+Native UI components handle complex interactions better:
+- Date pickers → Use `FlutterCupertinoDatePicker` instead of HTML input
+- Sliders → Use `FlutterCupertinoSlider` for native feel
+- Segmented controls → Use `FlutterCupertinoSegmentedControl`
+
+### 3. Check Component Documentation
+Always check the official documentation for component props and events:
+- https://openwebf.com/en/ui-components/cupertino
+
+### 4. Use TypeScript for Type Safety
+All native UI packages include TypeScript definitions:
+```tsx
+import type { FlutterCupertinoButtonProps } from '@openwebf/react-cupertino-ui';
+
+const buttonProps: FlutterCupertinoButtonProps = {
+ variant: 'filled',
+ onClick: () => console.log('Clicked')
+};
+```
+
+## Troubleshooting
+
+### Issue: Components Not Rendering
+
+**Cause**: Flutter package not installed or initialized
+
+**Solution**:
+1. Check that the Flutter package is in `pubspec.yaml`
+2. Verify `installWebFCupertinoUI()` is called in main.dart
+3. Run `flutter pub get`
+4. Rebuild your Flutter app
+
+### Issue: TypeScript Errors for Components
+
+**Cause**: NPM package not installed correctly
+
+**Solution**:
+```bash
+# Reinstall the package
+npm install @openwebf/react-cupertino-ui --save
+
+# Clear node_modules and reinstall
+rm -rf node_modules package-lock.json
+npm install
+```
+
+### Issue: Vue Components Not Found
+
+**Cause**: Vue bindings need to be generated
+
+**Solution**: Follow the "For Vue + Cupertino UI" steps in Step 2 above to generate Vue bindings using `webf codegen`.
+
+### Issue: Props Don't Match Flutter Widget
+
+**Cause**: WebF automatically converts between JavaScript and Dart naming
+
+**Solution**:
+- JavaScript uses camelCase: `onClick`, `onChange`, `placeholder`
+- Flutter uses camelCase too, so props map directly
+- Check documentation for exact prop names
+
+## Resources
+
+- **Component Gallery**: https://openwebf.com/en/ui-components
+- **Cupertino UI Docs**: https://openwebf.com/en/ui-components/cupertino
+- **WebF CLI Docs**: https://openwebf.com/en/docs/tools/webf-cli
+- **React Examples**: https://github.com/openwebf/react-cupertino-gallery
+- **Vue Examples**: https://github.com/openwebf/vue-cupertino-gallery
+
+## Next Steps
+
+After setting up native UI:
+
+1. **Explore components**: Visit https://openwebf.com/en/ui-components to see all available components
+2. **Check examples**: Look at the gallery apps for React and Vue
+3. **Mix with HTML/CSS**: Use native UI where it makes sense, HTML/CSS elsewhere
+4. **Performance**: Native UI components render at 60fps with Flutter-level performance
+
+## Summary
+
+- ✅ Native UI libraries provide pre-built, platform-specific components
+- ✅ Cupertino UI for iOS-style apps (30+ components available now)
+- ✅ Form UI for validated forms (available now)
+- ✅ Material UI coming soon for Android-style apps
+- ✅ Install Flutter packages first, then npm packages
+- ✅ Mix native UI with HTML/CSS as needed
+- ✅ Better performance than HTML/CSS for complex UIs
+- ✅ Full React and Vue support
diff --git a/.agents/skills/webf-native-ui/reference.md b/.agents/skills/webf-native-ui/reference.md
new file mode 100644
index 0000000000..4744846e38
--- /dev/null
+++ b/.agents/skills/webf-native-ui/reference.md
@@ -0,0 +1,562 @@
+# Native UI Component Reference
+
+This reference lists all available native UI components in WebF's native UI libraries.
+
+## Cupertino UI Components (iOS-style)
+
+### Navigation & Layout
+
+#### FlutterCupertinoTabScaffold
+Creates a tabbed application structure with tab bar.
+
+**Props**:
+- `tabs` - Array of tab definitions
+- `initialIndex` - Starting tab index (default: 0)
+
+**Example**:
+```tsx
+
+```
+
+#### FlutterCupertinoTabBar
+Bottom tab bar for navigation.
+
+**Props**:
+- `items` - Array of tab bar items
+- `currentIndex` - Active tab index
+- `onTap` - Callback when tab is tapped
+
+**Example**:
+```tsx
+ console.log('Tab:', index)}
+/>
+```
+
+#### FlutterCupertinoTabView
+Content container for tab views.
+
+**Props**:
+- `children` - Tab content
+- `builder` - Optional builder function
+
+---
+
+### Buttons & Actions
+
+#### FlutterCupertinoButton
+iOS-style button with multiple variants.
+
+**Props**:
+- `variant` - Button style: `'filled'`, `'text'`, or `'plain'` (default: `'text'`)
+- `onClick` - Click handler
+- `disabled` - Disable button (default: false)
+- `children` - Button label/content
+- `color` - Custom button color
+- `padding` - Custom padding
+
+**Example**:
+```tsx
+ console.log('Clicked')}
+ disabled={false}
+>
+ Continue
+
+```
+
+---
+
+### Dialogs & Overlays
+
+#### FlutterCupertinoAlertDialog
+Native iOS alert dialog.
+
+**Props**:
+- `title` - Dialog title
+- `content` - Dialog message/content
+- `actions` - Array of action buttons
+ - `label` - Button text
+ - `onPress` - Button callback
+ - `isDestructive` - Red destructive style (default: false)
+ - `isDefaultAction` - Bold default style (default: false)
+
+**Example**:
+```tsx
+ {} },
+ { label: 'Delete', onPress: () => {}, isDestructive: true }
+ ]}
+/>
+```
+
+#### FlutterCupertinoActionSheet
+Bottom sheet with action options.
+
+**Props**:
+- `title` - Sheet title
+- `message` - Sheet message
+- `actions` - Array of action buttons
+- `cancelButton` - Cancel button configuration
+
+**Example**:
+```tsx
+ {} },
+ { label: 'Option 2', onPress: () => {} }
+ ]}
+ cancelButton={{ label: 'Cancel', onPress: () => {} }}
+/>
+```
+
+#### FlutterCupertinoModalPopup
+Generic modal popup container.
+
+**Props**:
+- `children` - Popup content
+- `onDismiss` - Callback when dismissed
+
+**Example**:
+```tsx
+ console.log('Dismissed')}>
+
+
Modal Content
+
+
+```
+
+#### FlutterCupertinoContextMenu
+Long-press context menu.
+
+**Props**:
+- `actions` - Array of menu actions
+- `children` - Trigger element
+
+**Example**:
+```tsx
+ {} },
+ { label: 'Delete', onPress: () => {}, isDestructive: true }
+ ]}
+>
+
+
+```
+
+---
+
+### Lists
+
+#### FlutterCupertinoListSection
+Grouped list section with header/footer.
+
+**Props**:
+- `header` - Section header text
+- `footer` - Section footer text
+- `children` - List items (FlutterCupertinoListTile)
+
+**Example**:
+```tsx
+
+
+
+
+```
+
+#### FlutterCupertinoListTile
+Individual list item.
+
+**Props**:
+- `title` - Main title text
+- `subtitle` - Optional subtitle text
+- `leading` - Leading widget/icon
+- `trailing` - Trailing widget/icon
+- `onTap` - Tap callback
+- `additionalInfo` - Right-side info text
+
+**Example**:
+```tsx
+}
+ onTap={() => console.log('Tapped')}
+/>
+```
+
+---
+
+### Forms
+
+#### FlutterCupertinoFormSection
+Form section container with header.
+
+**Props**:
+- `header` - Section header text
+- `footer` - Section footer text
+- `children` - Form rows
+
+**Example**:
+```tsx
+
+
+
+
+
+```
+
+#### FlutterCupertinoFormRow
+Form row with label and input.
+
+**Props**:
+- `label` - Row label text
+- `children` - Input widget
+- `error` - Error message text
+- `helper` - Helper text
+
+**Example**:
+```tsx
+
+
+
+```
+
+---
+
+### Text Input
+
+#### FlutterCupertinoTextField
+Native iOS text field.
+
+**Props**:
+- `placeholder` - Placeholder text
+- `value` - Current value
+- `onChanged` - Change handler
+- `keyboardType` - Keyboard type: `'text'`, `'email'`, `'number'`, `'phone'`, `'url'`
+- `obscureText` - Hide text (for passwords, default: false)
+- `maxLines` - Maximum lines (default: 1)
+- `readOnly` - Read-only mode (default: false)
+- `autofocus` - Auto-focus on mount (default: false)
+- `clearButtonMode` - Show clear button: `'never'`, `'always'`, `'editing'`, `'notEditing'`
+
+**Example**:
+```tsx
+ setName(value)}
+ keyboardType="text"
+ clearButtonMode="editing"
+/>
+```
+
+#### FlutterCupertinoSearchTextField
+Search field with search icon and clear button.
+
+**Props**:
+- `placeholder` - Placeholder text (default: "Search")
+- `value` - Current value
+- `onChanged` - Change handler
+- `onSubmitted` - Submit handler
+
+**Example**:
+```tsx
+ setSearchQuery(value)}
+ onSubmitted={(value) => performSearch(value)}
+/>
+```
+
+---
+
+### Pickers
+
+#### FlutterCupertinoDatePicker
+Native iOS date picker.
+
+**Props**:
+- `mode` - Picker mode: `'date'`, `'time'`, `'dateTime'`
+- `initialDate` - Starting date (ISO string)
+- `minimumDate` - Minimum selectable date
+- `maximumDate` - Maximum selectable date
+- `onDateTimeChanged` - Date change handler
+
+**Example**:
+```tsx
+ console.log('Selected:', date)}
+/>
+```
+
+---
+
+### Controls
+
+#### FlutterCupertinoSwitch
+Native iOS toggle switch.
+
+**Props**:
+- `value` - Switch state (boolean)
+- `onChanged` - Change handler
+- `activeColor` - Color when active
+
+**Example**:
+```tsx
+ setIsEnabled(value)}
+ activeColor="#007AFF"
+/>
+```
+
+#### FlutterCupertinoSlider
+Native iOS slider.
+
+**Props**:
+- `value` - Current value (0.0 to 1.0)
+- `onChanged` - Change handler
+- `min` - Minimum value (default: 0.0)
+- `max` - Maximum value (default: 1.0)
+- `divisions` - Number of discrete divisions
+- `activeColor` - Track color when active
+
+**Example**:
+```tsx
+ setVolume(value)}
+ min={0}
+ max={100}
+ divisions={100}
+/>
+```
+
+#### FlutterCupertinoSegmentedControl
+Segmented control for mutually exclusive choices.
+
+**Props**:
+- `children` - Map of segment widgets `{ '0': , '1': }`
+- `groupValue` - Currently selected value
+- `onValueChanged` - Selection change handler
+
+**Example**:
+```tsx
+Day,
+ '1': Week,
+ '2': Month
+ }}
+ groupValue={selectedPeriod}
+ onValueChanged={(value) => setSelectedPeriod(value)}
+/>
+```
+
+#### FlutterCupertinoCheckbox
+iOS-style checkbox.
+
+**Props**:
+- `value` - Checked state (boolean)
+- `onChanged` - Change handler
+- `activeColor` - Color when checked
+
+**Example**:
+```tsx
+ setIsChecked(value)}
+/>
+```
+
+#### FlutterCupertinoRadio
+iOS-style radio button.
+
+**Props**:
+- `value` - Radio value
+- `groupValue` - Selected value in group
+- `onChanged` - Change handler
+
+**Example**:
+```tsx
+ setSelectedOption(value)}
+/>
+```
+
+---
+
+### Icons & Colors
+
+#### FlutterCupertinoIcon
+iOS SF Symbols icons.
+
+**Props**:
+- `name` - SF Symbol name (e.g., `'house'`, `'person'`, `'gear'`)
+- `size` - Icon size (default: 28)
+- `color` - Icon color
+
+**Example**:
+```tsx
+
+```
+
+**Common SF Symbols**:
+- Navigation: `'house'`, `'magnifyingglass'`, `'person'`, `'gear'`, `'ellipsis'`
+- Actions: `'plus'`, `'minus'`, `'checkmark'`, `'xmark'`, `'trash'`
+- Media: `'play.fill'`, `'pause.fill'`, `'heart.fill'`, `'star.fill'`
+- Communication: `'message.fill'`, `'envelope.fill'`, `'phone.fill'`
+
+---
+
+## Component Naming Conventions
+
+### React
+All components use PascalCase with `Flutter` prefix:
+```tsx
+import { FlutterCupertinoButton } from '@openwebf/react-cupertino-ui';
+
+Click Me
+```
+
+### Vue
+Components use PascalCase (not kebab-case) in templates:
+```vue
+
+
+ Click Me
+
+
+
+
+```
+
+---
+
+## TypeScript Support
+
+All native UI packages include full TypeScript definitions:
+
+```tsx
+import type {
+ FlutterCupertinoButtonProps,
+ FlutterCupertinoTextFieldProps,
+ FlutterCupertinoSwitchProps
+} from '@openwebf/react-cupertino-ui';
+
+const buttonProps: FlutterCupertinoButtonProps = {
+ variant: 'filled',
+ onClick: () => console.log('Clicked')
+};
+```
+
+---
+
+## Event Handlers
+
+### Common Event Props
+- `onClick` / `onTap` - Tap/click events
+- `onChanged` - Value change events
+- `onSubmitted` - Form submission events
+- `onDismiss` - Dismiss/close events
+- `onFocus` / `onBlur` - Focus events
+
+### Event Data
+Most events pass the new value directly:
+```tsx
+// Switch
+ setEnabled(newValue)}
+/>
+
+// Text field
+ setText(newText)}
+/>
+```
+
+---
+
+## Styling Native Components
+
+### Using CSS Classes
+Native components can have CSS classes for layout:
+```tsx
+
+ Click Me
+
+```
+
+```css
+.my-button-wrapper {
+ margin: 20px;
+ width: 200px;
+}
+```
+
+### Custom Colors
+Many components accept color props:
+```tsx
+
+ Delete
+
+
+
+```
+
+### Note on Styling Limitations
+Native UI components render as Flutter widgets, so:
+- ✅ Can control: position, size, margin, padding (via wrapper)
+- ❌ Cannot control: internal styling, fonts, borders (use Flutter theming)
+
+---
+
+## Resources
+
+- **Official Documentation**: https://openwebf.com/en/ui-components
+- **Cupertino Gallery**: https://openwebf.com/en/ui-components/cupertino
+- **SF Symbols Browser**: https://developer.apple.com/sf-symbols/
+- **Form Validation**: https://pub.dev/packages/form_builder_validators
+
+---
+
+## Getting Help
+
+- **Component not working?** Check that the Flutter package is installed and initialized
+- **TypeScript errors?** Ensure the npm package is installed correctly
+- **Props not working?** Check the official documentation for the exact prop names
+- **Vue components?** Generate bindings using `webf codegen` command
diff --git a/.agents/skills/webf-quickstart/SKILL.md b/.agents/skills/webf-quickstart/SKILL.md
new file mode 100644
index 0000000000..778704c15c
--- /dev/null
+++ b/.agents/skills/webf-quickstart/SKILL.md
@@ -0,0 +1,222 @@
+---
+name: webf-quickstart
+description: Get started with WebF development - setup WebF Go, create a React/Vue/Svelte project with Vite, and load your first app. Use when starting a new WebF project, onboarding new developers, or setting up development environment.
+---
+
+# WebF Quickstart
+
+> **Note**: Building WebF apps is nearly identical to building regular web apps with Vite + React/Vue/Svelte. The only difference is you replace your browser with **WebF Go** for testing during development. Everything else - project structure, build tools, testing frameworks, and deployment - works the same way.
+
+> **⚠️ IMPORTANT**: WebF Go is for **development and testing ONLY**. For production, you must build a Flutter app with WebF integration. Do NOT distribute WebF Go to end users.
+
+Get up and running with WebF in minutes. This skill guides you through setting up your development environment, creating your first project, and loading it in WebF Go.
+
+## What You Need
+
+**Only Node.js is required** - that's it!
+
+- Node.js (LTS version recommended) from [nodejs.org](https://nodejs.org/)
+- **You do NOT need**: Flutter SDK, Xcode, or Android Studio
+
+WebF lets web developers build native apps using familiar web tools.
+
+## Step-by-Step Setup
+
+### 1. Download WebF Go (For Testing Only)
+
+WebF Go is a pre-built native app containing the WebF rendering engine. It's designed for **development and testing purposes only** - not for production deployment.
+
+**For Desktop Development:**
+- Download WebF Go for your OS (macOS, Windows, Linux)
+- Get it from: **https://openwebf.com/en/go**
+
+**For Mobile Testing:**
+- iOS: Download from App Store
+- Android: Download from Google Play
+
+**Remember**: WebF Go is a testing tool. For production apps, you'll need to build a Flutter app with WebF integration.
+
+Launch WebF Go - you'll see an input field ready to load your app.
+
+### 2. Create Your Project with Vite
+
+Open your terminal and create a new project:
+
+```bash
+npm create vite@latest my-webf-app
+```
+
+Vite will prompt you to:
+1. Choose a framework: **React**, **Vue**, **Svelte**, etc.
+2. Choose a variant (JavaScript or TypeScript)
+
+### 3. Install Dependencies and Start Dev Server
+
+```bash
+# Move into your project
+cd my-webf-app
+
+# Install dependencies
+npm install
+
+# Start the dev server
+npm run dev
+```
+
+Your terminal will show URLs like:
+```
+ VITE v5.0.0 ready in 123 ms
+
+ ➜ Local: http://localhost:5173/
+ ➜ Network: http://192.168.1.100:5173/
+```
+
+### 4. Load in WebF Go
+
+**For Desktop:**
+1. Copy the `http://localhost:5173/` URL
+2. Paste into WebF Go's input field
+3. Press Enter or click "Go"
+
+**For Mobile Device:**
+⚠️ **IMPORTANT**: Mobile devices cannot access `localhost`
+
+You MUST use the Network URL instead:
+1. Make sure your computer and mobile device are on the **same WiFi network**
+2. Use `--host` flag to expose the dev server:
+ ```bash
+ npm run dev -- --host
+ ```
+3. Copy the **Network** URL (e.g., `http://192.168.1.100:5173/`)
+4. Type it into WebF Go on your mobile device
+5. Press "Go"
+
+Your app will now render in WebF! 🎉
+
+### 5. Verify Hot Reload
+
+Make a quick change to your code and save. The app should automatically update - this is Vite's Hot Module Replacement (HMR) working with WebF.
+
+### 6. (Optional) Setup Chrome DevTools
+
+To debug your app:
+1. Click the floating debug button in WebF Go
+2. Click "Copy" to get the DevTools URL (`devtools://...`)
+3. Paste into desktop Google Chrome browser
+4. You can now use Console, Elements, Network tabs
+
+**Note**: JavaScript breakpoints don't work yet - use `console.log()` instead.
+
+## Common Issues and Solutions
+
+### Issue: "Cannot connect" on mobile device
+
+**Causes & Solutions:**
+- ✗ Using `localhost` → ✓ Use Network URL (`http://192.168.x.x:5173`)
+- ✗ Different WiFi networks → ✓ Put both devices on same network
+- ✗ Missing `--host` flag → ✓ Use `npm run dev -- --host`
+- ✗ Firewall blocking port → ✓ Allow port 5173 through firewall
+
+### Issue: "Connection refused"
+
+- Dev server not running → Run `npm run dev`
+- Wrong port number → Check terminal output for correct port
+- Firewall blocking → Temporarily disable to test
+
+### Issue: App loads but doesn't update
+
+- HMR not working → Refresh the page manually
+- Dev server error → Check terminal for errors
+- Network connection lost → Reconnect WiFi
+
+## Production Deployment
+
+⚠️ **WebF Go is NOT for production use**. It's a testing tool for developers.
+
+### For Production Apps
+
+When you're ready to deploy to end users, you need to:
+
+**1. Build Your Web Bundle**
+```bash
+npm run build
+```
+
+**2. Host Your Bundle**
+- Deploy to any web hosting (Vercel, Netlify, CDN, etc.)
+- Your bundle will be accessible via URL (e.g., `https://your-app.com`)
+
+**3. Create a Flutter App with WebF Integration**
+
+You or your Flutter team needs to:
+- Set up a Flutter project
+- Add the WebF Flutter package to `pubspec.yaml`
+- Configure the app (name, icon, splash screen, permissions)
+- Load your web bundle URL in the WebF widget
+
+**Example Flutter Integration:**
+```dart
+import 'package:webf/webf.dart';
+
+class MyApp extends StatelessWidget {
+ @override
+ Widget build(BuildContext context) {
+ return WebF(
+ bundle: WebFBundle.fromUrl('https://your-app.com'),
+ );
+ }
+}
+```
+
+**4. Build and Deploy Flutter App**
+- Build for iOS and Android
+- Submit to App Store and Google Play
+
+**Resources:**
+- [WebF Integration Guide](https://openwebf.com/en/docs/developer-guide/integration)
+- [Flutter App Setup](https://openwebf.com/en/docs/developer-guide/app-setup)
+
+### Development vs Production
+
+| Aspect | Development | Production |
+|--------|------------|------------|
+| **Tool** | WebF Go | Custom Flutter app |
+| **Purpose** | Testing & iteration | End-user distribution |
+| **Setup** | Download and run | Build Flutter app |
+| **Distribution** | Don't distribute | App Store/Google Play |
+| **Requirements** | Node.js only | Flutter SDK required |
+
+## Next Steps
+
+Now that you have a working dev environment:
+
+1. **Learn the #1 difference**: WebF uses async rendering - see the `webf-async-rendering` skill
+2. **Check API compatibility**: Not all web APIs work in WebF - see `webf-api-compatibility` skill
+3. **Add navigation**: Multi-screen apps use WebF routing - see `webf-routing-setup` skill
+
+## Quick Reference
+
+```bash
+# Create new project
+npm create vite@latest my-app
+
+# Start dev server (desktop)
+npm run dev
+
+# Start dev server (mobile - with network access)
+npm run dev -- --host
+
+# Install dependencies
+npm install
+
+# Build for production
+npm run build
+```
+
+## Resources
+
+- **Getting Started Guide**: https://openwebf.com/en/docs/developer-guide/getting-started
+- **WebF Go Guide**: https://openwebf.com/en/docs/learn-webf/webf-go
+- **Development Workflow**: https://openwebf.com/en/docs/developer-guide/development-workflow
+- **Download WebF Go**: https://openwebf.com/en/go
+- **Full Documentation**: https://openwebf.com/en/docs
\ No newline at end of file
diff --git a/.agents/skills/webf-quickstart/reference.md b/.agents/skills/webf-quickstart/reference.md
new file mode 100644
index 0000000000..df0128d8d2
--- /dev/null
+++ b/.agents/skills/webf-quickstart/reference.md
@@ -0,0 +1,199 @@
+# WebF Quickstart - Quick Reference
+
+> **⚠️ IMPORTANT**: WebF Go is for **testing and development ONLY**. For production, you must build a Flutter app with WebF integration.
+
+## Setup Checklist
+
+- [ ] Node.js installed (LTS version)
+- [ ] WebF Go downloaded and installed (for testing)
+- [ ] Project created with Vite
+- [ ] Dependencies installed (`npm install`)
+- [ ] Dev server running (`npm run dev`)
+- [ ] App loaded in WebF Go
+
+## Essential Commands
+
+```bash
+# Create project
+npm create vite@latest my-app
+cd my-app
+npm install
+
+# Development
+npm run dev # Desktop (localhost)
+npm run dev -- --host # Mobile (network access)
+
+# Production (Web Bundle)
+npm run build # Create production build
+npm run preview # Preview production build
+vercel deploy # Deploy to hosting
+```
+
+## Network URLs by Platform
+
+| Platform | URL Pattern | Example |
+|----------|-------------|---------|
+| Desktop | `http://localhost:PORT` | `http://localhost:5173` |
+| Mobile | `http://NETWORK-IP:PORT` | `http://192.168.1.100:5173` |
+
+**Critical**: Mobile devices cannot access `localhost` - always use Network URL!
+
+## Troubleshooting Quick Fixes
+
+| Problem | Quick Fix |
+|---------|-----------|
+| Mobile can't connect | Use `npm run dev -- --host` and Network URL |
+| Different WiFi | Put both devices on same network |
+| Firewall blocks | Allow port 5173 (or your dev server port) |
+| HMR not working | Hard refresh or restart dev server |
+| DevTools won't connect | Must use desktop Chrome browser |
+
+## Port Configuration
+
+Default Vite port: `5173`
+
+To change port:
+```bash
+# Option 1: Flag
+npm run dev -- --port 3000
+
+# Option 2: vite.config.js
+export default {
+ server: {
+ port: 3000,
+ host: true // Expose on network
+ }
+}
+```
+
+## DevTools Setup
+
+1. Click floating button in WebF Go
+2. Click "Copy" → Gets `devtools://...` URL
+3. Paste in desktop Chrome
+4. Use Console, Elements, Network tabs
+5. ⚠️ Breakpoints don't work - use `console.log()`
+
+## Supported Frameworks
+
+All work out-of-the-box with Vite:
+
+- ✅ React (16, 17, 18, 19)
+- ✅ Vue (2, 3)
+- ✅ Svelte
+- ✅ Preact
+- ✅ Solid
+- ✅ Qwik
+- ✅ Vanilla JS
+
+## HTTPS for Mobile Testing
+
+Some APIs require HTTPS. To enable:
+
+```bash
+npm install -D @vitejs/plugin-basic-ssl
+```
+
+```js
+// vite.config.js
+import basicSsl from '@vitejs/plugin-basic-ssl'
+
+export default {
+ plugins: [basicSsl()],
+ server: {
+ https: true
+ }
+}
+```
+
+Then use `https://192.168.x.x:5173` instead of `http://`
+
+## Common Vite Flags
+
+```bash
+# Network access (mobile testing)
+npm run dev -- --host
+
+# Custom port
+npm run dev -- --port 3000
+
+# Open browser automatically
+npm run dev -- --open
+
+# Clear cache
+npm run dev -- --force
+```
+
+## File Structure
+
+```
+my-webf-app/
+├── src/
+│ ├── main.jsx # Entry point
+│ ├── App.jsx # Root component
+│ └── index.css # Global styles
+├── public/ # Static assets
+├── index.html # HTML template
+├── package.json # Dependencies
+└── vite.config.js # Vite configuration
+```
+
+## Environment Detection
+
+Check if running in WebF:
+
+```javascript
+// WebF exposes global WebF object
+if (typeof WebF !== 'undefined') {
+ console.log('Running in WebF');
+} else {
+ console.log('Running in browser');
+}
+```
+
+## Production Deployment
+
+⚠️ **WebF Go is NOT for production**. It's a testing tool only.
+
+### Production Checklist
+
+1. **Build Web Bundle**
+ ```bash
+ npm run build
+ ```
+
+2. **Deploy Bundle to Hosting**
+ ```bash
+ vercel deploy # or Netlify, AWS S3, etc.
+ ```
+
+3. **Create Flutter App with WebF**
+ - Set up Flutter project
+ - Add `webf` package to `pubspec.yaml`
+ - Configure app (icons, permissions, etc.)
+ - Load your bundle URL
+
+4. **Build & Submit Flutter App**
+ - Build for iOS and Android
+ - Submit to App Store/Google Play
+
+### Key Differences
+
+| Development | Production |
+|------------|------------|
+| WebF Go | Custom Flutter app |
+| Testing only | End-user distribution |
+| No Flutter SDK needed | Flutter SDK required |
+| Don't distribute | App Store/Google Play |
+
+**Resources:**
+- Integration: https://openwebf.com/en/docs/developer-guide/integration
+- Flutter Setup: https://openwebf.com/en/docs/developer-guide/app-setup
+
+## Next Skill After Setup
+
+After successful setup, you'll need:
+
+1. **Async Rendering** (`webf-async-rendering`) - Most important concept
+2. **API Compatibility** (`webf-api-compatibility`) - What works/doesn't work
+3. **Routing Setup** (`webf-routing-setup`) - Multi-screen navigation
\ No newline at end of file
diff --git a/.agents/skills/webf-routing-setup/SKILL.md b/.agents/skills/webf-routing-setup/SKILL.md
new file mode 100644
index 0000000000..2d27cea8bb
--- /dev/null
+++ b/.agents/skills/webf-routing-setup/SKILL.md
@@ -0,0 +1,584 @@
+---
+name: webf-routing-setup
+description: Setup hybrid routing with native screen transitions in WebF - configure navigation using WebF routing instead of SPA routing. Use when setting up navigation, implementing multi-screen apps, or when react-router-dom/vue-router doesn't work as expected.
+---
+
+# WebF Routing Setup
+
+> **Note**: WebF development is nearly identical to web development - you use the same tools (Vite, npm, Vitest), same frameworks (React, Vue, Svelte), and same deployment services (Vercel, Netlify). This skill covers **one of the 3 key differences**: routing with native screen transitions instead of SPA routing. The other two differences are async rendering and API compatibility.
+
+**WebF does NOT use traditional Single-Page Application (SPA) routing.** Instead, it uses **hybrid routing** where each route renders on a separate, native Flutter screen with platform-native transitions.
+
+## The Fundamental Difference
+
+### In Browsers (SPA Routing)
+Traditional web routing uses the History API or hash-based routing:
+
+```javascript
+// Browser SPA routing (react-router-dom, vue-router)
+// ❌ This pattern does NOT work in WebF
+import { BrowserRouter, Routes, Route } from 'react-router-dom';
+
+// Single page with client-side routing
+// All routes render in the same screen
+// Transitions are CSS-based
+```
+
+The entire app runs in one screen, and route changes are simulated with JavaScript and CSS.
+
+### In WebF (Hybrid Routing)
+Each route is a separate Flutter screen with native transitions:
+
+```javascript
+// WebF hybrid routing
+// ✅ This pattern WORKS in WebF
+import { Routes, Route, WebFRouter } from '@openwebf/react-router';
+
+// Each route renders on a separate Flutter screen
+// Transitions use native platform animations
+// Hardware back button works correctly
+```
+
+**Think of it like native mobile navigation** - each route is a new screen in a navigation stack, not a section of a single web page.
+
+## Why Hybrid Routing?
+
+WebF's approach provides true native app behavior:
+
+1. **Native Transitions** - Platform-specific animations (Cupertino for iOS, Material for Android)
+2. **Proper Lifecycle** - Each route has its own lifecycle, similar to native apps
+3. **Hardware Back Button** - Android back button works correctly
+4. **Memory Management** - Unused routes can be unloaded
+5. **Deep Linking** - Integration with platform deep linking
+6. **Synchronized Navigation** - Flutter Navigator and WebF routing stay in sync
+
+## React Setup
+
+### Installation
+
+```bash
+npm install @openwebf/react-router
+```
+
+**CRITICAL**: Do NOT use `react-router-dom` - it will not work correctly in WebF.
+
+### Basic Route Configuration
+
+```jsx
+import { Route, Routes } from '@openwebf/react-router';
+import { HomePage } from './pages/home';
+import { ProfilePage } from './pages/profile';
+import { SettingsPage } from './pages/settings';
+
+function App() {
+ return (
+
+ {/* Each Route must have a title prop */}
+ } title="Home" />
+ } title="Profile" />
+ } title="Settings" />
+
+ );
+}
+
+export default App;
+```
+
+**Important**: The `title` prop appears in the native navigation bar for that screen.
+
+### Programmatic Navigation
+
+Use the `WebFRouter` object for navigation:
+
+```jsx
+import { WebFRouter } from '@openwebf/react-router';
+
+function HomePage() {
+ // Navigate forward (push new screen)
+ const goToProfile = () => {
+ WebFRouter.pushState({ userId: 123 }, '/profile');
+ };
+
+ // Replace current screen (no back button)
+ const replaceWithSettings = () => {
+ WebFRouter.replaceState({}, '/settings');
+ };
+
+ // Navigate back
+ const goBack = () => {
+ WebFRouter.back();
+ };
+
+ // Navigate forward
+ const goForward = () => {
+ WebFRouter.forward();
+ };
+
+ return (
+
+
Home Page
+
+
+
+
+
+ );
+}
+```
+
+### Passing Data Between Routes
+
+Use the state parameter to pass data:
+
+```jsx
+import { WebFRouter, useLocation } from '@openwebf/react-router';
+
+// Sender component
+function ProductList() {
+ const viewProduct = (product) => {
+ // Pass product data to detail screen
+ WebFRouter.pushState({
+ productId: product.id,
+ productName: product.name,
+ productPrice: product.price
+ }, '/product/detail');
+ };
+
+ return (
+
+ );
+}
+```
+
+## Environment Detection
+
+### Method 1: Check for WebF Global
+
+```javascript
+const isWebF = typeof window !== 'undefined' && typeof window.webf !== 'undefined';
+```
+
+### Method 2: Check for WebFRouter
+
+```javascript
+import { WebFRouter } from '@openwebf/react-router';
+
+const isWebF = typeof WebFRouter !== 'undefined';
+```
+
+### Method 3: Environment Variable
+
+Set environment variable during build:
+
+```bash
+# .env.webf
+VITE_PLATFORM=webf
+
+# .env.browser
+VITE_PLATFORM=browser
+```
+
+```javascript
+const isWebF = import.meta.env.VITE_PLATFORM === 'webf';
+```
+
+## Platform-Specific Features
+
+Some features only make sense in one environment:
+
+```jsx
+import { isWebF } from './routing/router-adapter';
+import { WebFShare } from '@openwebf/webf-share';
+
+function ShareButton({ title, url }) {
+ if (!isWebF) {
+ // Browser: Use Web Share API or fallback
+ const handleShare = async () => {
+ if (navigator.share) {
+ await navigator.share({ title, url });
+ } else {
+ // Fallback: copy to clipboard
+ navigator.clipboard.writeText(url);
+ alert('Link copied to clipboard!');
+ }
+ };
+
+ return ;
+ }
+
+ // WebF: Use native share
+ if (!WebFShare.isAvailable()) {
+ return null;
+ }
+
+ const handleShare = async () => {
+ await WebFShare.shareText({ text: title, url });
+ };
+
+ return ;
+}
+```
+
+## Build Configuration
+
+### Vite Configuration
+
+```javascript
+// vite.config.js
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig(({ mode }) => {
+ const isWebF = mode === 'webf';
+
+ return {
+ plugins: [react()],
+ define: {
+ 'import.meta.env.IS_WEBF': isWebF
+ },
+ build: {
+ // Different output directories for different platforms
+ outDir: isWebF ? 'dist-webf' : 'dist-browser'
+ }
+ };
+});
+```
+
+**Build commands**:
+
+```bash
+# Build for browser
+npm run build
+
+# Build for WebF
+npm run build -- --mode webf
+```
+
+### Package.json Scripts
+
+```json
+{
+ "scripts": {
+ "dev": "vite",
+ "dev:webf": "vite --mode webf",
+ "build": "vite build",
+ "build:webf": "vite build --mode webf",
+ "preview": "vite preview"
+ }
+}
+```
+
+## TypeScript Support
+
+Add types for the router adapter:
+
+```typescript
+// src/routing/router-adapter.d.ts
+export interface NavigateState {
+ [key: string]: any;
+}
+
+export interface NavigateAPI {
+ push: (path: string, state?: NavigateState) => void;
+ replace: (path: string, state?: NavigateState) => void;
+ back: () => void;
+ forward: () => void;
+}
+
+export const navigate: NavigateAPI;
+export const isWebF: boolean;
+
+export function RouterProvider({ children }: { children: React.ReactNode }): JSX.Element;
+export function Link({ to, state, children, ...props }: {
+ to: string;
+ state?: NavigateState;
+ children: React.ReactNode;
+ [key: string]: any;
+}): JSX.Element;
+
+export { Routes, Route, useLocation, useParams, useNavigate } from '@openwebf/react-router';
+```
+
+## Testing Both Platforms
+
+### Test in Browser
+
+```bash
+npm run dev
+# Open http://localhost:5173 in browser
+```
+
+### Test in WebF
+
+```bash
+npm run dev -- --host
+# Open http://192.168.x.x:5173 in WebF Go
+```
+
+## Best Practices
+
+### 1. Use Adapter Consistently
+
+❌ **Don't mix routers**:
+```jsx
+import { WebFRouter } from '@openwebf/react-router';
+import { useNavigate } from 'react-router-dom';
+// This will break!
+```
+
+✅ **Use adapter everywhere**:
+```jsx
+import { navigate, useLocation } from './routing/router-adapter';
+// Works in both environments
+```
+
+### 2. Handle Missing State Gracefully
+
+```jsx
+function DetailPage() {
+ const location = useLocation();
+ const data = location.state?.data || getDefaultData();
+
+ // Always have fallback for missing state
+ return
{data.name}
;
+}
+```
+
+### 3. Test in Both Environments
+
+- Develop in browser for fast iteration
+- Test in WebF Go regularly
+- CI/CD should test both builds
+
+### 4. Platform-Specific Code
+
+Use feature flags for platform-specific behavior:
+
+```jsx
+import { isWebF } from './routing/router-adapter';
+
+function Header() {
+ return (
+
+
My App
+ {isWebF ? (
+
+ ) : (
+
+ )}
+
+ );
+}
+```
+
+### 5. Keep Router Logic Simple
+
+Don't create overly complex abstractions. The adapter should be thin and predictable.
+
+## Summary
+
+The router adapter pattern allows you to:
+
+1. ✅ Write once, run in browser and WebF
+2. ✅ Use familiar routing APIs
+3. ✅ Handle platform differences gracefully
+4. ✅ Test consistently across platforms
+5. ✅ Maintain a single codebase
+
+**Key Files**:
+- `src/routing/router-adapter.jsx` - Router abstraction
+- `src/routing/use-navigation.js` - Navigation hook
+- `.env.webf` / `.env.browser` - Environment config
+
+**Development Flow**:
+1. Develop in browser (fast iteration)
+2. Test in WebF Go (native behavior)
+3. Build for both platforms
+4. Deploy to web and app stores
+
+This approach gives you the best of both worlds: web development speed and native app experience.
\ No newline at end of file
diff --git a/.agents/skills/webf-routing-setup/examples.md b/.agents/skills/webf-routing-setup/examples.md
new file mode 100644
index 0000000000..e514714829
--- /dev/null
+++ b/.agents/skills/webf-routing-setup/examples.md
@@ -0,0 +1,947 @@
+# WebF Routing - Complete Examples
+
+## Example 1: Basic Multi-Screen App (React)
+
+A simple app with three screens: Home, Profile, and Settings.
+
+```jsx
+// src/App.jsx
+import { Routes, Route } from '@openwebf/react-router';
+import HomePage from './pages/HomePage';
+import ProfilePage from './pages/ProfilePage';
+import SettingsPage from './pages/SettingsPage';
+
+function App() {
+ return (
+
+ } title="Home" />
+ } title="Profile" />
+ } title="Settings" />
+
+ );
+}
+
+export default App;
+```
+
+```jsx
+// src/pages/HomePage.jsx
+import { WebFRouter } from '@openwebf/react-router';
+
+function HomePage() {
+ const goToProfile = () => {
+ WebFRouter.pushState({}, '/profile');
+ };
+
+ const goToSettings = () => {
+ WebFRouter.pushState({}, '/settings');
+ };
+
+ return (
+
+ ))}
+ 
+ 
+ 
+ 
+ 
+