@take-out/docs 0.0.42

package/hot-updater.md

@@ -0,0 +1,223 @@
+---
+name: hot-updater
+description: Guide for implementing OTA updates and hot updates in React Native apps. INVOKE WHEN: hot updater, OTA updates, over-the-air updates, app updates, code push, deploy updates, @hot-updater/react-native, HotUpdaterProvider, useHotUpdater, update deployment.
+---
+
+# Hot Updater Guide
+
+This guide covers the hot update system for delivering over-the-air (OTA)
+updates to React Native applications.
+
+## Overview
+
+The hot updater system allows you to push JavaScript bundle updates to deployed
+React Native apps without going through the app store review process. This
+enables rapid bug fixes and feature deployments.
+
+## Architecture
+
+### Components
+
+1. **@hot-updater/react-native** - React Native client library
+2. **HotUpdaterProvider** - React context provider for update management
+3. **Feature Flags** - Remote configuration via PostHog
+4. **Update Server** - Hosts update bundles (configurable via feature flag)
+
+## Setup
+
+### Installation
+
+The hot-updater package is already installed:
+
+```bash
+bun add @hot-updater/react-native
+```
+
+### Configuration
+
+In `app.config.ts`:
+
+```typescript
+{
+  expo: {
+    version: "0.0.6",
+    runtimeVersion: version, // Required for appVersion strategy
+    plugins: [
+      [
+        "@hot-updater/react-native",
+        {
+          channel: APP_VARIANT, // development, preview, or production
+        }
+      ]
+    ]
+  }
+}
+```
+
+### Feature Flags
+
+Two feature flags control hot updates:
+
+1. **ENABLE_HOT_UPDATES** - Boolean flag to enable/disable hot updates
+2. **HOT_UPDATE_SERVER_URL** - Dynamic config for update server URL
+
+Configure these in PostHog or your feature flag service.
+
+## Implementation
+
+### Provider Setup
+
+Wrap your app with the HotUpdaterProvider:
+
+```tsx
+import { HotUpdaterProvider } from '~/features/hot-updater'
+
+function App() {
+  return <HotUpdaterProvider>{/* Your app components */}</HotUpdaterProvider>
+}
+```
+
+### Update Notification UI
+
+Add the notification component to show update prompts:
+
+```tsx
+import { HotUpdaterNotification } from '~/features/hot-updater'
+
+function AppLayout() {
+  return (
+    <>
+      {/* Your app content */}
+      <HotUpdaterNotification />
+    </>
+  )
+}
+```
+
+### Using the Hook
+
+Access hot updater functionality in components:
+
+```tsx
+import { useHotUpdater } from '~/features/hot-updater'
+
+function SettingsScreen() {
+  const {
+    isUpdateAvailable,
+    isDownloading,
+    downloadProgress,
+    checkForUpdate,
+    applyUpdate,
+    lastCheckTime,
+  } = useHotUpdater()
+
+  return (
+    <View>
+      {isUpdateAvailable && <Button onPress={applyUpdate}>Apply Update</Button>}
+
+      <Button onPress={checkForUpdate}>Check for Updates</Button>
+
+      {lastCheckTime && (
+        <Text>Last checked: {lastCheckTime.toLocaleString()}</Text>
+      )}
+    </View>
+  )
+}
+```
+
+## Update Strategy
+
+### Version Management
+
+The app uses the "appVersion" strategy:
+
+- Runtime version matches app version (e.g., "0.0.6")
+- Updates are compatible within the same runtime version
+- Native changes require a new app store release
+
+### Channels
+
+Updates are distributed through channels based on APP_VARIANT:
+
+- **development** - For development builds
+- **preview** - For staging/preview builds
+- **production** - For production releases
+
+### Update Check Frequency
+
+- On app launch
+- When app returns to foreground
+- Every 30 minutes while app is active
+- Manual check via UI
+
+## Deployment
+
+### Creating an Update
+
+1. Make JavaScript/asset changes (no native code changes)
+2. Build the update bundle:
+
+   ```bash
+   eas update --branch [branch-name] --message "[update message]"
+   ```
+
+3. The update is automatically distributed to devices
+
+### Update Server
+
+Configure the update server URL via the HOT_UPDATE_SERVER_URL feature flag. The
+default server handles:
+
+- Bundle hosting
+- Version compatibility checks
+- Channel-based distribution
+- Download progress tracking
+
+## Monitoring
+
+### Analytics Events
+
+The system tracks these events via PostHog:
+
+- `hot_update_available` - Update detected
+- `hot_update_downloaded` - Update downloaded successfully
+- `hot_update_check_error` - Error checking for updates
+- `hot_update_apply_error` - Error applying update
+
+### Debugging
+
+Enable verbose logging:
+
+```tsx
+// In development
+console.info('Hot updates enabled:', isEnabled)
+console.info('Server URL:', serverUrl)
+console.info('Current version:', Updates.currentVersion)
+```
+
+## Best Practices
+
+### Do's
+
+1. **Test updates thoroughly** in development/preview channels first
+2. **Use feature flags** to control rollout
+3. **Monitor analytics** after deploying updates
+4. **Keep updates small** - large bundles take longer to download
+5. **Version native changes** properly with runtime version bumps
+
+### Don'ts
+
+1. **Don't include native changes** in hot updates
+2. **Don't skip testing** in preview environments
+3. **Don't force updates** without user consent
+4. **Don't update during critical user operations**
+5. **Don't ignore error tracking**
+
+## Rollback Strategy
+
+If an update causes issues:
+
+1. **Disable via feature flag** - Turn off ENABLE_HOT_UPDATES
+2. **Deploy fix** - Create and test a fix
+3. **Roll forward** - Deploy the fix as a new update
+4. **Monitor** - Track analytics to ensure issues are resolved

package/native-hot-update.md

@@ -0,0 +1,252 @@
+---
+name: native-hot-update
+description: Native hot update (OTA/over-the-air) system guide for @take-out/native-hot-update. Use for HotUpdaterSplash, splash screen, deploy-hot-update scripts, update issues, or troubleshooting OTA updates.
+---
+
+# Native Hot Update System
+
+## Overview
+
+The app uses hot updates to deploy code changes to production without requiring
+app store submissions. Updates are checked on app start and applied
+automatically or after user confirmation.
+
+## Architecture
+
+### Package
+
+Located at packages/native-hot-update, this is a reusable package that provides:
+
+- Instance-based API via createHotUpdater()
+- Pluggable storage interface (get/set/delete)
+- Timeout protection (5s soft, 20s hard)
+- Progress tracking during downloads
+- Alert handling for critical updates
+
+### Integration
+
+Located at src/features/hot-updater, this integrates the package with the app:
+
+- useHotUpdater hook with PostHog feature flags
+- HotUpdaterSplash component for app initialization
+- Analytics tracking for update events
+
+## Update Flow
+
+### On App Start
+
+1. HotUpdaterSplash component renders
+2. useHotUpdater hook checks PostHog feature flags
+3. If enabled, queries update server for available updates
+4. Shows splash screen during download with progress indicator
+5. After timeout or completion, displays app content
+
+### Update Types
+
+Critical updates reload immediately if user hasn't accessed the app yet. If the
+user is already in the app, an alert prompts them to reload now or later.
+
+Non-critical updates download silently and apply on the next app restart.
+
+Rollback updates check if a pre-release bundle is active and skip if the current
+version is newer.
+
+## Configuration
+
+### Feature Flags
+
+Controlled via PostHog:
+
+- ENABLE_HOT_UPDATES: Master on/off switch
+- HOT_UPDATE_SERVER_URL: Server endpoint for updates
+
+### Environment
+
+Required variables in .env:
+
+- HOT_UPDATER_SUPABASE_URL
+- HOT_UPDATER_SUPABASE_ANON_KEY
+- HOT_UPDATER_SUPABASE_BUCKET_NAME
+
+### Update Strategy
+
+Uses appVersion strategy, which requires runtimeVersion set in app.config.ts to
+match the version field.
+
+## Deployment
+
+### Manual
+
+Run deployment scripts for specific platforms:
+
+```
+bun deploy-hot-update:ios
+bun deploy-hot-update:android
+bun deploy-hot-update
+```
+
+### Automated
+
+Two GitHub Actions workflows handle deployments.
+
+Manual deployment via Actions tab:
+- Workflow: deploy-hot-update.yml
+- Choose platform, channel, and critical flag
+- Triggered manually from GitHub Actions UI
+
+Automatic deployment after CI success:
+- Workflow: auto-deploy-hot-update.yml
+- Runs when CI completes on main branch
+- Deploys to production-pre channel
+- Non-critical updates only
+
+Required GitHub secrets:
+- HOT_UPDATER_SUPABASE_URL
+- HOT_UPDATER_SUPABASE_ANON_KEY
+- HOT_UPDATER_SUPABASE_BUCKET_NAME
+
+### Channels
+
+- production-pre: Pre-release testing channel
+- production: Stable release channel
+
+## Usage
+
+### Basic Integration
+
+```ts
+import { HotUpdaterSplash } from '~/features/hot-updater/HotUpdaterSplash'
+
+export function Layout() {
+  return (
+    <HotUpdaterSplash>
+      <App />
+    </HotUpdaterSplash>
+  )
+}
+```
+
+The component handles update checks automatically and shows a splash screen
+during downloads.
+
+### Custom Behavior
+
+```ts
+import { useHotUpdater } from '~/features/hot-updater/useHotUpdater'
+
+export function CustomUpdater() {
+  const { userClearedForAccess, progress } = useHotUpdater()
+
+  if (!userClearedForAccess) {
+    return <CustomSplash progress={progress} />
+  }
+
+  return <App />
+}
+```
+
+### Debugging
+
+```ts
+import { hotUpdater } from '@take-out/native-hot-update'
+
+console.info('Applied OTA:', hotUpdater.getAppliedOta())
+console.info('Short ID:', hotUpdater.getShortOtaId())
+console.info('Channel:', hotUpdater.getChannel())
+console.info('Pending:', hotUpdater.getIsUpdatePending())
+```
+
+## Alert Behavior
+
+### Critical Updates
+
+Before user accesses app: Reloads automatically After user accesses app: Shows
+alert with "Later" and "Reload Now" options
+
+### Non-Critical Updates
+
+No alerts shown. Updates apply silently on next app restart.
+
+### Rollback Protection
+
+If using a pre-release bundle and a rollback is detected, shows alert: "Update
+Skipped - Skipped rollback because you are using a newer pre-release bundle."
+
+## Storage
+
+The package uses a pluggable storage interface. The app provides MMKV storage:
+
+```ts
+import { MMKV } from 'react-native-mmkv'
+import { createMMKVStorage } from '@take-out/native-hot-update/mmkv'
+
+const mmkv = new MMKV({ id: 'hot-updater' })
+const storage = createMMKVStorage(mmkv)
+```
+
+Storage persists:
+
+- Bundle IDs per app version
+- Pre-release bundle markers
+- Update state across app restarts
+
+## Analytics
+
+Update events are automatically tracked via PostHog:
+
+- ota_update_downloaded: When update completes
+- ota_update_error: When update fails
+
+Event properties include bundle ID, critical flag, file URL, and error details.
+
+## Timeout Protection
+
+Soft timeout at 5 seconds: Shows app if no update is downloading Hard timeout at
+20 seconds: Always shows app regardless of update state
+
+This prevents slow servers or network issues from blocking user access.
+
+## Build Configuration
+
+The hot-updater.config.ts file at the project root configures:
+
+- Build adapter: bare (with Hermes enabled)
+- Storage: Supabase
+- Database: Supabase
+- Update strategy: appVersion
+
+## Platform Support
+
+iOS and Android both supported. Web is a no-op (splash component renders
+children immediately).
+
+Updates are deployed per platform and can be triggered independently.
+
+## Security
+
+Updates are served via Supabase with configured access controls. The anon key is
+used for read access to the update bundles.
+
+Pre-release updates use a separate channel and are marked in storage to prevent
+accidental rollbacks.
+
+## Troubleshooting
+
+### Updates not applying
+
+Check feature flags in PostHog, verify server URL is configured, confirm
+.env.hotupdater has correct credentials.
+
+### Splash screen stuck
+
+Check network connectivity, verify server is responding, review timeout logs.
+
+### Wrong version shown
+
+Use hotUpdater.getAppliedOta() to check current bundle, compare with server to
+verify latest version is available.
+
+## References
+
+- Package README: packages/native-hot-update/README.md
+- Integration guide: packages/native-hot-update/INTEGRATION.md

package/one-components.md

@@ -0,0 +1,234 @@
+---
+name: one-components
+description: One framework components guide for navigation, layouts, and UI elements. INVOKE WHEN: Link, Redirect, navigation, Head, meta tags, SEO, SafeAreaView, StatusBar, device safe areas, Stack, Tabs, Slot, layout components, LoadProgressBar, ScrollBehavior.
+---
+
+# one framework: components
+
+comprehensive guide to built-in components in one framework for navigation,
+layouts, and ui enhancements.
+
+## navigation components
+
+### Link
+
+type-safe navigation component for both web and native.
+
+```tsx
+import { Link } from 'one'
+
+<Link href="/blog">go to blog</Link>
+<Link href="/blog/post" replace>replace history</Link>
+<Link href="https://example.com" target="_blank">external</Link>
+```
+
+**props:**
+
+- `href` (required): typed route path
+- `asChild`: forward props to child component
+- `replace`: replace history instead of push
+- `push`: explicitly push to history
+- `className`: web class, native css interop
+- `target`: web-only (\_blank, \_self, \_top, \_parent)
+- `rel`: web-only (nofollow, noopener, noreferrer, etc.)
+- `download`: web-only download attribute
+
+**examples:**
+
+```tsx
+// basic navigation
+<Link href="/home/profile">view profile</Link>
+
+// dynamic routes (type-safe)
+<Link href={`/user/${userId}`}>user page</Link>
+
+// replace history
+<Link href="/login" replace>login</Link>
+
+// external link
+<Link href="https://github.com" target="_blank" rel="noopener">
+  github
+</Link>
+
+// as child (forward to custom component)
+<Link href="/about" asChild>
+  <CustomButton>about us</CustomButton>
+</Link>
+```
+
+### Redirect
+
+redirects when route is focused. uses `useFocusEffect` internally.
+
+```tsx
+import { Redirect } from 'one'
+
+export default function Page() {
+  const { isAuthenticated } = useAuth()
+
+  if (!isAuthenticated) {
+    return <Redirect href="/login" />
+  }
+
+  return <Content />
+}
+```
+
+**props:**
+
+- `href`: destination route
+
+**note:** prefer using `~/interface/Link` over One's Link component in this project.
+
+## ui components
+
+### Head
+
+control `<head>` on web and app meta on native.
+
+```tsx
+import { Head } from 'one'
+
+export default function Page() {
+  return (
+    <>
+      <Head>
+        <title>my page title</title>
+        <meta name="description" content="page description" />
+        <meta property="og:image" content="/og-image.png" />
+      </Head>
+      <Content />
+    </>
+  )
+}
+```
+
+can be used in any route or component. web: renders into `<head>`, native:
+controls app metadata.
+
+### SafeAreaView
+
+re-exports from `react-native-safe-area-context`. respects device safe areas
+(notches, status bars).
+
+```tsx
+import { SafeAreaView } from 'one'
+
+export default function Page() {
+  return (
+    <SafeAreaView edges={['top', 'left', 'right']}>
+      <Content />
+    </SafeAreaView>
+  )
+}
+```
+
+**props:**
+
+- `edges`: array of edges to apply safe area ('top' | 'bottom' | 'left' |
+  'right')
+
+one uses `SafeAreaProvider` from react navigation automatically.
+
+### LoadProgressBar
+
+web-only loading bar during page transitions.
+
+```tsx
+// app/_layout.tsx
+import { LoadProgressBar, Slot } from 'one'
+
+export default function Layout() {
+  return (
+    <>
+      <LoadProgressBar
+        startDelay={100}
+        finishDelay={100}
+        initialPercent={20}
+        updateInterval={100}
+        sporadicness={0.3}
+      />
+      <Slot />
+    </>
+  )
+}
+```
+
+**props:**
+
+- `startDelay`: delay before showing (ms)
+- `finishDelay`: delay before hiding (ms)
+- `initialPercent`: starting percentage (0-100)
+- `updateInterval`: update frequency (ms)
+- `sporadicness`: randomness factor (0-1)
+
+### ScrollBehavior
+
+automatic scroll restoration for web. resets to top on new page, restores
+position on back/forward.
+
+```tsx
+// app/_layout.tsx
+import { ScrollBehavior, Slot } from 'one'
+
+export default function Layout() {
+  return (
+    <>
+      <ScrollBehavior />
+      <Slot />
+    </>
+  )
+}
+```
+
+**props:**
+
+- `disabled`: boolean | 'restore' - disable completely or only restoration
+
+```tsx
+// disable restoration, keep reset behavior
+<ScrollBehavior disabled="restore" />
+
+// disable completely
+<ScrollBehavior disabled={true} />
+```
+
+## practical patterns
+
+### safe area with scroll
+
+```tsx
+import { SafeAreaView, ScrollView } from 'one'
+
+export default function Page() {
+  return (
+    <SafeAreaView edges={['top']} style={{ flex: 1 }}>
+      <ScrollView>
+        <Content />
+      </ScrollView>
+    </SafeAreaView>
+  )
+}
+```
+
+### progressive loading indicator
+
+```tsx
+// app/_layout.tsx
+import { LoadProgressBar, Slot } from 'one'
+
+export default function Layout() {
+  return (
+    <>
+      <LoadProgressBar
+        startDelay={200} // wait 200ms before showing
+        finishDelay={300} // wait 300ms before hiding
+        initialPercent={30} // start at 30%
+        updateInterval={80} // update every 80ms
+        sporadicness={0.4} // moderate randomness
+      />
+      <Slot />
+    </>
+  )
+}
+```