-174

.agent-task.md

reviewed

··· 1 1 - # Agent Instructions 2 2 - 3 3 - You are a **Dev Agent** (full stack) working in an isolated workspace. Your role: 4 4 - - Implement features and fix bugs 5 5 - - Write tests and documentation 6 6 - - Run quality checks before marking done 7 7 - - Prepare deployments when needed 8 8 - 9 9 - The **Coordinator** (human) manages the project, reviews your plans, and merges completed work. 10 10 - 11 11 - ## Resources 12 12 - 13 13 - All these files are in YOUR workspace directory (use `pwd` to confirm): 14 14 - - `TODO.md` - Project tasks and priorities 15 15 - - `notes/development.md` - Architecture and dev guide 16 16 - 17 17 - **Do NOT access files in ~/misc/mpeek/ or any parent directory. Your workspace has everything you need.** 18 18 - 19 19 - ## Status Reporting 20 20 - 21 21 - Report status so the coordinator knows your progress: 22 22 - 23 23 - ```bash 24 24 - agent-status "working" "brief description" 25 25 - agent-status "blocked" "what you need" # Only when truly stuck 26 26 - agent-status "review" "ready for review" 27 27 - agent-status "done" "what you accomplished" 28 28 - ``` 29 29 - 30 30 - --- 31 31 - 32 32 - ## Policies 33 33 - 34 34 - ### Policy: Autonomy 35 35 - 36 36 - - **Work independently** - Make reasonable decisions without asking. You have full access to the codebase. 37 37 - - **Don't ask for basic permissions** - Common tools (ls, find, npm, yarn, jj, node, etc.) are pre-approved. 38 38 - - **Batch your work** - Do multiple related operations before pausing. 39 39 - - **Only interrupt when truly blocked** - Not for confirmations, only for missing information you can't find. 40 40 - 41 41 - ### Policy: Workspace 42 42 - 43 43 - - **Work in your current directory** - Your workspace is an isolated jj worktree with a full copy of the repo. 44 44 - - **CRITICAL: Use YOUR workspace path for all file operations** - When using Read/Edit tools, files must be in YOUR workspace directory (check with `pwd`), NOT the main repo. Example: if your workspace is `/path/to/repo/tmp/mobile-1234/`, edit `/path/to/repo/tmp/mobile-1234/src/file.js`, NOT `/path/to/repo/src/file.js`. 45 45 - - **Never use hardcoded paths to ~/misc/mpeek or similar** - Always resolve paths relative to your current working directory. 46 46 - 47 47 - ### Policy: Process Safety (CRITICAL) 48 48 - 49 49 - **NEVER interfere with processes outside your workspace.** 50 50 - 51 51 - - **Do NOT kill, stop, or signal processes** you didn't start (no `kill`, `pkill`, `killall` on external processes) 52 52 - - **Do NOT modify system state** outside your workspace (no writing to /tmp shared files, no global npm installs, etc.) 53 53 - - **Only manage processes YOU started** within YOUR workspace session 54 54 - - **If external processes block you, REPORT IT** - don't try to fix it yourself 55 55 - 56 56 - Violations of this policy compromise other agents and the coordinator's work. If you encounter a port conflict or blocking process, use `agent-status "blocked" "description"` and wait for coordinator assistance. 57 57 - 58 58 - ### Policy: Commands (CRITICAL) 59 59 - 60 60 - **STOP. READ THIS BEFORE RUNNING ANY COMMAND.** 61 61 - 62 62 - 1. **ALWAYS use package.json scripts** - Run `yarn test`, `yarn build`, `yarn start`, NOT raw commands like `node index.js` or `npm run`. 63 63 - 64 64 - 2. **NEVER use && or ; or |** - These require approval EVERY time. Run commands separately. 65 65 - 66 66 - 3. **Check package.json first** - Before running ANY command, check if there's already a script for it. 67 67 - 68 68 - **BAD (will be rejected):** 69 69 - ```bash 70 70 - cd backend/server && node index.js 71 71 - npm install && npm test 72 72 - NODE_ENV=test node --test 73 73 - ``` 74 74 - 75 75 - **GOOD:** 76 76 - ```bash 77 77 - yarn test 78 78 - yarn start 79 79 - yarn build 80 80 - ``` 81 81 - 82 82 - If a script doesn't exist for what you need, ADD ONE to package.json first, then run it. 83 83 - 84 84 - ### Policy: Version Control 85 85 - 86 86 - **This repo uses jj (Jujutsu), not git. Never use git commands directly.** 87 87 - 88 88 - ```bash 89 89 - jj st # status 90 90 - jj log # log recent changes 91 91 - jj diff # diff working copy 92 92 - jj commit -m "message" # commit your work 93 93 - jj squash -m "message" # squash into parent with message (when finishing) 94 94 - ``` 95 95 - 96 96 - Key differences from git: 97 97 - - No staging area - all changes tracked automatically 98 98 - - `jj commit` creates new empty change on top 99 99 - - **NEVER move the main bookmark** - coordinator handles that via `mmerge` 100 100 - - Don't push directly - coordinator handles pushing after merge 101 101 - 102 102 - **CRITICAL: Commit frequently to avoid losing work!** 103 103 - - If you see "working copy is stale", COMMIT FIRST before running `jj workspace update-stale` 104 104 - - `jj workspace update-stale` will OVERWRITE uncommitted changes 105 105 - - Commit after every significant edit, not just at the end 106 106 - - Use `jj commit -m "WIP: description"` for work-in-progress saves 107 107 - 108 108 - ### Policy: Sync Before Starting Work 109 109 - 110 110 - After your plan is approved and before starting implementation, **always rebase on main** to get the latest changes: 111 111 - 112 112 - ```bash 113 113 - jj rebase -d main 114 114 - ``` 115 115 - 116 116 - This ensures you have the latest code and TODO.md state from other agents or the coordinator. 117 117 - 118 118 - ### Policy: Commits 119 119 - 120 120 - - Ask before committing - don't commit automatically, but do offer to commit when work is done 121 121 - - User (dietrich ayala) is sole author of all commits 122 122 - 123 123 - ### Policy: Quality 124 124 - 125 125 - Before marking any task as done: 126 126 - 127 127 - 1. **Tests** - Write tests for new functionality. Run all tests and ensure they pass. 128 128 - 2. **Documentation** - Update relevant docs (README, API docs, etc.) if behavior changes. 129 129 - 3. **Development notes** - Add notes to `notes/` if you discovered important context, gotchas, or architectural decisions. 130 130 - 4. **Verify** - Run the build/lint/tests. Do NOT mark done if tests fail. 131 131 - 132 132 - ### Policy: Cleanup 133 133 - 134 134 - When your task is complete, you MUST complete this checklist: 135 135 - 136 136 - **1. Mark task complete in TODO.md** 137 137 - - Find your task in the Today section, change `- [~]` (in-progress) to `- [x]` (done) 138 138 - - Move to Done section under current week heading (`### YYYY-WNN`) 139 139 - 140 140 - **2. Write development notes** (if applicable) 141 141 - - Add to existing file in `notes/` or create new one 142 142 - - Focus on what future developers need to know 143 143 - 144 144 - **3. Record learnings** (if you discovered tips, gotchas, or patterns) 145 145 - - Create or append to `notes/agent-learnings.md` in your workspace 146 146 - - The coordinator will consolidate these after merging 147 147 - 148 148 - **4. Squash your work** 149 149 - ```bash 150 150 - jj squash -m "description of changes" 151 151 - ``` 152 152 - The coordinator will handle the actual merge with `mmerge`. 153 153 - 154 154 - **5. Report completion** 155 155 - ```bash 156 156 - agent-status "done" "summary of what you accomplished" 157 157 - ``` 158 158 - 159 159 - **Do NOT skip these steps.** Never access files outside your workspace. 160 160 - 161 161 - --- 162 162 - 163 163 - ## BEFORE REPORTING DONE 164 164 - 165 165 - You MUST complete the cleanup checklist. Verify: 166 166 - - [ ] TODO.md updated: task changed from `[~]` to `[x]`, moved to Done section under `### 2026-WNN` 167 167 - - [ ] `jj squash -m "description"` run to squash your commits 168 168 - - [ ] `agent-status "done" "summary"` called 169 169 - 170 170 - **Failure to update TODO.md means the task is not complete.** 171 171 - 172 172 - --- 173 173 - 174 174 - ## Your Taskshared iOS build artifacts in ./tmp to avoid full rebuilds per workspace (one mobile task at a time)

+325 -156

DEVELOPMENT.md

reviewed

··· 1 1 - # Development Guide 1 1 + # Peek Development Guide 2 2 3 3 - ## Commands 3 3 + ## Project Overview 4 4 5 5 - Bare commands (`dev`, `start`, `debug`, `kill`, `restart`) default to Electron. Use `BACKEND=tauri` to switch: 5 5 + Peek is a web user agent application that provides alternative ways to interact with web pages through keyboard shortcuts, modal windows, and background scripts. It's designed as a concept preview exploring task-aligned interfaces for the web, moving beyond traditional tabbed browsers. 6 6 7 7 - ```bash 8 8 - yarn debug # Electron (default) 9 9 - BACKEND=tauri yarn debug # Tauri 10 10 - yarn debug:electron # Explicit Electron 11 11 - yarn debug:tauri # Explicit Tauri 12 12 - ``` 7 7 + **Multi-Backend Architecture**: Peek supports multiple backends (Electron, Tauri) that can coexist and sync data. The `app/` directory is **backend-agnostic** and must not contain backend-specific code. Backend-specific code lives in `backend/{electron,tauri}/`. 8 8 + 9 9 + ## Requirements 10 10 + 11 11 + - **Node.js 24+** - Required for both desktop (Electron 40) and server 12 12 + - Install via `nvm install 24` or download from nodejs.org 13 13 14 14 - All Electron commands automatically build TypeScript before running. 14 14 + ## Key Commands 15 15 16 16 + ### Development 16 17 ```bash 17 17 - # Install dependencies 18 18 - yarn install 18 18 + nvm use 24 # Ensure Node 24 is active 19 19 + yarn install # Install dependencies 20 20 + yarn debug # Run in development mode (with devtools) 21 21 + yarn start # Start normally 22 22 + yarn package # Package (output: out/mac-arm64/) 23 23 + yarn package:install # Package and install to /Applications (macOS) 24 24 + yarn make # Build distributable packages 25 25 + yarn npm audit # Check for security vulnerabilities 19 26 20 20 - # Run in development mode (with devtools + hot reload) 21 21 - yarn debug 27 27 + # Tauri backend 28 28 + yarn tauri:dev # Run Tauri in development 29 29 + yarn tauri:build # Build Tauri for production 30 30 + yarn tauri:check # Check Tauri compiles 31 31 + yarn tauri:test # Run Tauri smoke tests (Rust) 22 32 23 23 - # Start the application normally 24 24 - yarn start 33 33 + # Tauri Mobile (iOS/Android) 34 34 + yarn tauri:ios:dev # Run on iOS simulator 35 35 + yarn tauri:ios:build # Build for iOS 36 36 + yarn tauri:ios:xcode # Open Xcode project 37 37 + yarn tauri:android:dev # Run on Android emulator 25 38 26 26 - # Build TypeScript only (usually not needed - commands auto-build) 27 27 - yarn build 39 39 + # Server (webhook API for mobile sync) 40 40 + yarn server:install # Install server dependencies 41 41 + yarn server:start # Run production server 42 42 + yarn server:dev # Run with hot reload 43 43 + yarn server:test # Run server tests 44 44 + yarn server:healthcheck # Verify server starts 28 45 ``` 29 46 30 30 - ## Hot Reload (Electron only) 31 31 - 32 32 - In dev mode (`yarn debug` or `DEBUG=1`), hot reload is enabled: 33 33 - - Watches `app/` and `extensions/` directories 34 34 - - Auto-reloads all windows when `.html`, `.js`, or `.css` files change 35 35 - - No restart needed for renderer-side changes 36 36 - 37 37 - Note: Changes to `backend/` TypeScript files still require rebuilding (`yarn build`) and restarting the app. Hot reload is not yet implemented for the Tauri backend. 38 38 - 47 47 + ### Testing 39 48 ```bash 40 40 - # Typical dev workflow: 41 41 - yarn debug # Start app with hot reload 42 42 - # Edit files in app/ or extensions/ 43 43 - # Windows auto-reload on save 49 49 + yarn test # Run all tests (headless) 50 50 + yarn test:electron # Run Electron tests only 51 51 + yarn test:visible # Run with visible windows 52 52 + yarn test:grep "pattern" # Run specific test by name 44 53 ``` 45 54 46 46 - ```bash 47 47 - # Package the application (output: out/mac-arm64/) 48 48 - yarn package 49 49 - 50 50 - # Package and install to /Applications (macOS) 51 51 - yarn package:install 52 52 - 53 53 - # Build distributable packages 54 54 - yarn make 55 55 - 56 56 - # Check for security vulnerabilities 57 57 - yarn npm audit 58 58 - 59 59 - # Test packaged build with dev profile 60 60 - PROFILE=dev out/mac-arm64/Peek.app/Contents/MacOS/Peek 61 61 - ``` 55 55 + **Testing Policy**: When fixing bugs or adding features, always add tests to cover the change. Tests live in `tests/desktop/smoke.spec.ts`. 62 56 63 57 ## Architecture Overview 64 58 65 59 ### Core Structure 66 60 67 67 - The application uses a multi-window Electron architecture: 68 68 - 69 61 1. **Main Process** (`index.js`): 70 62 - Manages app lifecycle, windows, shortcuts, IPC communication 71 63 - Implements custom `peek://` protocol for internal navigation ··· 74 66 75 67 2. **Renderer Process** (`app/`): 76 68 - Core app logic loads from `peek://app/background.html` 77 77 - - Feature modules: peeks, slides, scripts, cmd, groups 69 69 + - Extension loader at `app/extensions/loader.js` 70 70 + - Feature modules: scripts, cmd (registered in `app/features.js`) 71 71 + - Built-in extensions: groups, peeks, slides (in `./extensions/`) 78 72 - Settings UI at `peek://app/settings/settings.html` 79 79 - - Datastore viewer at `peek://app/datastore/viewer.html` 80 73 81 74 3. **Peek API** (`window.app`): 82 82 - - Unified API exposed to all `peek://` pages 83 83 - - Provides shortcuts, window management, pubsub, datastore, and theme APIs 84 84 - - See `docs/PEEK-API.md` for complete reference 75 75 + - `api.window.*` for window management 76 76 + - `api.shortcuts.*` for hotkeys (local by default, `{ global: true }` for OS-level) 77 77 + - `api.datastore.*` for data persistence 78 78 + - `api.commands.*` for command palette integration 79 79 + - `api.theme.*` for theme management 80 80 + - `api.publish()`/`api.subscribe()` for cross-window messaging 81 81 + 82 82 + ### Backend Structure 83 83 + ``` 84 84 + backend/ 85 85 + ├── electron/ # Electron desktop backend (current primary) 86 86 + │ ├── datastore.ts # SQLite via better-sqlite3 87 87 + │ ├── ipc.ts # IPC handlers 88 88 + │ └── protocol.ts # peek:// protocol handler 89 89 + ├── tauri/ # Tauri desktop backend (Rust) 90 90 + │ ├── src-tauri/ 91 91 + │ │ ├── src/ 92 92 + │ │ │ ├── lib.rs # App setup 93 93 + │ │ │ ├── datastore.rs # SQLite via rusqlite 94 94 + │ │ │ └── commands/ # IPC command handlers 95 95 + │ │ └── tests/smoke.rs # Rust smoke tests 96 96 + │ └── preload.js # Peek API implementation (Tauri) 97 97 + ├── tauri-mobile/ # Tauri mobile app (iOS/Android) 98 98 + │ ├── src/ # React frontend 99 99 + │ └── src-tauri/ # Rust backend 100 100 + └── server/ # Webhook API server for mobile sync 101 101 + ├── index.js # Hono HTTP server 102 102 + ├── db.js # SQLite via better-sqlite3 103 103 + └── users.js # Multi-user API key auth 104 104 + ``` 105 105 + 106 106 + **Data Sync**: Both backends use the same SQLite database path (`~/.config/Peek/{profile}/datastore.sqlite`). Only one backend should run at a time (file lock). 85 107 86 108 ### Custom Protocol 109 109 + - `peek://app/...` - Core application files (from `app/` directory) 110 110 + - `peek://ext/{shortname}/...` - Extension files 111 111 + - `peek://tauri/...` - Tauri backend files (only in Tauri) 87 112 88 88 - - Uses `peek://` scheme for internal pages 89 89 - - Cross-origin network access enabled for peek:// pages 90 90 - - Special APIs available: window control, global hotkeys, pubsub messaging 113 113 + ### Extensions Architecture 91 114 92 92 - ### Profile Management 115 115 + Extensions run in isolated BrowserWindow processes at `peek://ext/{id}/background.html`. 93 116 94 94 - Profile is determined automatically: 95 95 - - Packaged app (`/Applications/Peek.app`) uses `default` profile 117 117 + ``` 118 118 + extensions/ 119 119 + ├── example/ # Hello world example 120 120 + ├── groups/ 121 121 + ├── peeks/ 122 122 + └── slides/ 123 123 + ├── manifest.json # Extension metadata 124 124 + ├── settings-schema.json # Settings UI schema (optional) 125 125 + ├── background.html # Entry point 126 126 + └── background.js # Main logic (ES module export) 127 127 + ``` 128 128 + 129 129 + **Background script pattern:** 130 130 + ```javascript 131 131 + const api = window.app; 132 132 + 133 133 + const extension = { 134 134 + id: 'example', 135 135 + labels: { name: 'Example' }, 136 136 + 137 137 + init() { 138 138 + api.shortcuts.register('Option+x', handler, { global: true }); 139 139 + api.commands.register({ name: 'my-cmd', description: '...', execute: fn }); 140 140 + }, 141 141 + 142 142 + uninit() { 143 143 + api.shortcuts.unregister('Option+x', { global: true }); 144 144 + api.commands.unregister('my-cmd'); 145 145 + } 146 146 + }; 147 147 + 148 148 + export default extension; 149 149 + ``` 150 150 + 151 151 + ### Window Management 152 152 + - Windows identified by keys for lifecycle management (e.g., `peek:${address}`) 153 153 + - Modal windows use `type: 'panel'` to return focus to previous app on close 154 154 + - Parameters: `modal`, `keepLive`, `persistState`, `transparent`, `height`, `width`, `key` 155 155 + - "Escape IZUI" design - ESC key always returns to previous context 156 156 + 157 157 + ### Data Storage 158 158 + 159 159 + **Settings Storage (localStorage)**: 160 160 + - Profile-based data separation in `{userData}/{PROFILE}/` directory 161 161 + - Features use `openStore(id, defaults, clear)` utility from `app/utils.js` 162 162 + 163 163 + **Datastore (TinyBase)**: 164 164 + - In-memory TinyBase store for structured data 165 165 + - Runs in main process with IPC handlers for renderer access 166 166 + - Schema defined in `app/datastore/schema.js` 167 167 + - Tables: `addresses`, `visits`, `content`, `tags`, `blobs`, `scripts_data`, `feeds` 168 168 + 169 169 + **Profile Management**: 170 170 + - Packaged app uses `default` profile 96 171 - Running from source (`yarn start`) uses `dev` profile 97 97 - - `PROFILE` env var overrides (e.g., `PROFILE=test yarn start`) 172 172 + - `PROFILE` env var overrides automatic detection 98 173 99 99 - Profile data stored in `{userData}/{PROFILE}/` directory. 174 174 + ## Common Pitfalls 100 175 101 101 - ## Window API 176 176 + 1. Don't use relative paths in peek:// URLs - use absolute paths 177 177 + 2. Remember to unregister shortcuts when features unload 178 178 + 3. Windows opened by features should be tracked and closed on unload 179 179 + 4. Modal windows require both `modal: true` and `type: 'panel'` 180 180 + 5. Window keys must be unique - use pattern like `peek:${address}` 181 181 + 6. Check if items are enabled (`item.enabled == true`) before registering shortcuts 182 182 + 7. Datastore API returns `{ success, data }` - always check `result.success` 183 183 + 8. Pubsub subscriptions are keyed by source - same source subscribing twice overwrites 184 184 + 9. **Never put backend-specific code in `app/`** 185 185 + 10. **Run `yarn install` after Electron upgrades** - Native modules (better-sqlite3) must be recompiled for the new Electron ABI. The postinstall script handles this automatically, but you must run `yarn install` to trigger it. System Node and Electron have different ABIs even at the same major version (e.g., Node 24 = ABI 137, Electron 40 = ABI 143). 102 186 103 103 - ### Opening Windows 187 187 + ## Code Style 104 188 105 105 - ```javascript 106 106 - import windows from './windows.js'; 189 189 + - ES6 modules throughout (type: "module" in package.json) 190 190 + - Async/await preferred over callbacks 191 191 + - Console logging for debugging (controlled by DEBUG env var) 192 192 + - No TypeScript in app/, pure JavaScript 193 193 + - Uses `nodemon` for hot reload during development 107 194 108 108 - // Modal window (closes on blur/ESC) 109 109 - windows.openModalWindow(url, options); 195 195 + ## Security Notes 110 196 111 111 - // Regular window 112 112 - windows.createWindow(url, options); 113 113 - ``` 197 197 + - This is a concept preview, NOT production-ready 198 198 + - No formal security audit performed 199 199 + - Different security model than traditional browsers 200 200 + - Be cautious with cross-origin access and custom APIs 114 201 115 115 - ### Window Options 202 202 + ## Mobile Development (Tauri iOS/Android) 203 203 + 204 204 + Mobile development uses the separate `peek-save` app in `backend/tauri-mobile/`. 205 205 + 206 206 + **CRITICAL - Build with Xcode GUI for iOS:** 207 207 + - NEVER run `xcodebuild` commands from terminal for final builds 208 208 + - Use Xcode GUI (Product → Build, Product → Run) for reliable builds 116 209 117 117 - | Option | Type | Description | 118 118 - |--------|------|-------------| 119 119 - | `width`, `height` | number | Window dimensions | 120 120 - | `x`, `y` | number | Window position | 121 121 - | `modal` | boolean | Frameless, closes on blur | 122 122 - | `key` | string | Unique ID for window reuse | 123 123 - | `keepLive` | boolean | Hide instead of close | 124 124 - | `escapeMode` | string | ESC behavior: `'close'`, `'navigate'`, `'auto'` | 125 125 - | `trackingSource` | string | Source for visit tracking | 210 210 + **CRITICAL - Do NOT run `xcodegen generate`:** 211 211 + - The Xcode project has custom settings that xcodegen overwrites 126 212 127 127 - ### Escape Handling 213 213 + ### Quick Start (One Command) 128 214 129 129 - Windows can control how ESC behaves using `escapeMode`: 215 215 + The easiest way to set up mobile development with sync testing: 130 216 131 131 - - **`'close'`** (default): ESC immediately closes/hides the window 132 132 - - **`'navigate'`**: Renderer handles ESC first; closes only when renderer signals root state 133 133 - - **`'auto'`**: Transient windows (opened via hotkey from another app) close immediately; active windows use navigate behavior 217 217 + ```bash 218 218 + cd backend/tauri-mobile 134 219 135 135 - #### Using escapeMode: 'navigate' 220 220 + # First time: build both debug and release Rust libraries 221 221 + npm run build # Build frontend 222 222 + cd src-tauri 223 223 + cargo build --target aarch64-apple-ios-sim # Debug (simulator) 224 224 + cargo build --target aarch64-apple-ios --release # Release (device) 225 225 + cd .. 136 226 137 137 - 1. Open window with `escapeMode: 'navigate'`: 138 138 - ```javascript 139 139 - windows.createWindow(url, { escapeMode: 'navigate' }); 227 227 + # Start everything (servers, configure iOS, seed test data, open Xcode) 228 228 + npm run dev:ios 140 229 ``` 141 230 142 142 - 2. Register escape handler in renderer: 143 143 - ```javascript 144 144 - api.escape.onEscape(() => { 145 145 - if (canNavigateBack) { 146 146 - navigateBack(); 147 147 - return { handled: true }; // ESC was handled internally 148 148 - } 149 149 - return { handled: false }; // At root, let window close 150 150 - }); 231 231 + `npm run dev:ios` does all of this automatically: 232 232 + 1. Resets server data for a clean slate 233 233 + 2. Starts backend server on a random port (10000-19999) 234 234 + 3. Starts frontend dev server on port 1420 235 235 + 4. Configures iOS simulator with server URL and API key 236 236 + 5. Copies both debug and release Rust libraries 237 237 + 6. Opens Xcode 238 238 + 7. Seeds test data (3 items on server, 3 on iOS) 239 239 + 240 240 + ### Available npm Scripts 241 241 + 242 242 + ```bash 243 243 + # Development 244 244 + npm run dev:ios # Full dev setup (servers + config + seed + Xcode) 245 245 + npm run xcode # Just copy libraries and open Xcode 246 246 + npm run seed # Seed test data (needs SERVER_URL and API_KEY env vars) 247 247 + npm run reset:server # Delete server data directory 248 248 + 249 249 + # Building 250 250 + npm run build # Build frontend (tsc + vite) 251 251 + npm run build:ios # Build frontend + debug Rust library 252 252 + npm run build:ios:release # Build frontend + release Rust library 253 253 + 254 254 + # Testing 255 255 + npm run test # Run integration tests 256 256 + npm run test:verbose # Run tests with verbose output 151 257 ``` 152 258 153 153 - See `notes/escape-navigation.md` for full design details. 259 259 + ### iOS Build Process (Manual) 154 260 155 155 - ## Dock / App Switcher Visibility (macOS) 261 261 + If you need to build manually instead of using `npm run dev:ios`: 156 262 157 157 - The dock icon visibility is dynamic based on window state and user preference: 263 263 + ```bash 264 264 + # 1. Build frontend 265 265 + cd backend/tauri-mobile && npm install && npm run build 158 266 159 159 - - **Windows visible**: Dock icon shown (regardless of preference) 160 160 - - **No windows visible**: Dock icon hidden (unless preference enabled) 267 267 + # 2. Build debug library (for simulator) 268 268 + cd src-tauri 269 269 + cargo tauri build --target aarch64-apple-ios-sim --debug 270 270 + mkdir -p gen/apple/Externals/arm64/Debug 271 271 + cp target/aarch64-apple-ios-sim/debug/deps/libpeek_save_lib.a gen/apple/Externals/arm64/Debug/libapp.a 161 272 162 162 - The `showInDockAndSwitcher` preference controls whether to *always* show the dock icon, even when no windows are open. When disabled (default), the dock icon only appears while Peek windows are visible. 273 273 + # 3. Build release library (for device) 274 274 + cargo tauri build --target aarch64-apple-ios 275 275 + mkdir -p gen/apple/Externals/arm64/Release 276 276 + cp target/aarch64-apple-ios/release/deps/libpeek_save_lib.a gen/apple/Externals/arm64/Release/libapp.a 163 277 164 164 - This is implemented via: 165 165 - - `getVisibleWindowCount()` - counts non-background visible windows 166 166 - - `updateDockVisibility()` - shows/hides dock based on window count + pref 167 167 - - Called from: window-open, window-show, maybeHideApp, prefs change 278 278 + # 4. Create assets symlink (if missing) 279 279 + ln -s ../../../dist gen/apple/assets 168 280 169 169 - ## App Icon Generation 281 281 + # 5. Open Xcode and build from GUI 282 282 + open gen/apple/peek-save.xcodeproj 283 283 + ``` 170 284 171 171 - The macOS app icon is generated from a source PNG using ImageMagick. The process applies rounded corners and adds padding to match macOS icon guidelines. 285 285 + ### Testing Bidirectional Sync 172 286 173 173 - ### Icon files in `assets/` 287 287 + After running `npm run dev:ios`, test data is automatically seeded: 174 288 175 175 - - `appicon-source.png` - Original source image (1232x1232, no rounding) 176 176 - - `appicon-rounded.png` - Processed version with rounded corners and padding (1024x1024) 177 177 - - `appicon.icns` - Final macOS icon file used by electron-builder 289 289 + **Server has 3 items:** 290 290 + - URL: https://github.com/from-server (tags: server, github) 291 291 + - URL: https://example.com/from-server-1 (tags: server, test) 292 292 + - Text: "This is a text note from the server" (tags: server, note) 178 293 179 179 - ### Regenerating the icon 294 294 + **iOS Simulator has 3 items:** 295 295 + - URL: https://mobile-only-1.example.com (tags: mobile, local) 296 296 + - URL: https://mobile-news.example.com (tags: local) 297 297 + - Text: "This text was created on mobile only" (tags: mobile) 180 298 181 181 - Requires ImageMagick (`brew install imagemagick`). 299 299 + **To test:** 300 300 + 1. Build and run in Xcode (Cmd+R) 301 301 + 2. Go to Settings in the app 302 302 + 3. Settings should already be configured (server URL and API key) 303 303 + 4. Tap **Sync All** to pull and push 304 304 + 5. After sync, both server and iOS should have 6 items 182 305 306 306 + **Gotchas:** 307 307 + - The `gen/apple/assets` symlink must exist or Xcode fails with "No such file or directory" 308 308 + - Debug scheme = simulator, Release scheme = device 309 309 + - If Rust code changes, rebuild the library and copy again 310 310 + - The "Build Rust Code" pre-build script in Xcode can hang indefinitely - pre-building avoids this 311 311 + - iOS simulator can't reach `localhost` - use Mac's IP address (dev:ios handles this automatically) 312 312 + 313 313 + ## Server Backend (Webhook API) 314 314 + 315 315 + The server backend (`backend/server/`) is a remote HTTP API for syncing data from the mobile app. It's separate from the desktop backends - it doesn't implement the Peek API, it's a standalone Node.js server. 316 316 + 317 317 + ### Server Commands 183 318 ```bash 184 184 - SRC="assets/appicon-source.png" 185 185 - ROUNDED="assets/appicon-rounded.png" 319 319 + # From project root 320 320 + yarn server:install # Install dependencies (first time) 321 321 + yarn server:start # Run production server (port 3000) 322 322 + yarn server:dev # Run with hot reload 323 323 + yarn server:test # Run unit tests (92 tests) 324 324 + yarn server:healthcheck # Verify server starts and responds 186 325 187 187 - SIZE=1232 188 188 - RADIUS=222 # ~18% of size for rounded corners 326 326 + # From backend/server/ 327 327 + npm install 328 328 + npm start 329 329 + npm run dev 330 330 + npm test 331 331 + npm run test:api:local # Test against local server (needs PEEK_LOCAL_KEY) 332 332 + npm run test:api:prod # Test against production (needs PEEK_PROD_KEY, PEEK_PROD_URL) 333 333 + ``` 189 334 190 190 - # Step 1: Apply rounded corners to source 191 191 - magick "$SRC" \ 192 192 - \( +clone -alpha extract \ 193 193 - -draw 'fill black polygon 0,0 0,'"$RADIUS $RADIUS"',0 fill white circle '"$RADIUS,$RADIUS $RADIUS"',0' \ 194 194 - \( +clone -flip \) -compose Multiply -composite \ 195 195 - \( +clone -flop \) -compose Multiply -composite \ 196 196 - \) -alpha off -compose CopyOpacity -composite \ 197 197 - /tmp/rounded-temp.png 335 335 + ### Server Architecture 336 336 + - **Hono** - Lightweight HTTP framework (like Express but faster) 337 337 + - **better-sqlite3** - SQLite database (same as Electron backend) 338 338 + - **Multi-user** - Each user gets isolated database in `./data/{userId}/` 339 339 + - **API key auth** - Bearer token authentication, keys hashed with SHA-256 198 340 199 199 - # Step 2: Add padding (scale to 80% and center on 1024x1024 canvas) 200 200 - magick /tmp/rounded-temp.png \ 201 201 - -resize 824x824 \ 202 202 - -gravity center \ 203 203 - -background transparent \ 204 204 - -extent 1024x1024 \ 205 205 - "$ROUNDED" 341 341 + ### Server API Endpoints 342 342 + All endpoints except `/` require `Authorization: Bearer <api_key>` header. 206 343 207 207 - # Step 3: Generate iconset and convert to icns 208 208 - mkdir -p assets/AppIcon.iconset 209 209 - for size in 16 32 64 128 256 512 1024; do 210 210 - magick "$ROUNDED" -resize ${size}x${size} PNG32:"assets/AppIcon.iconset/icon_${size}x${size}.png" 211 211 - done 344 344 + | Endpoint | Method | Description | 345 345 + |----------|--------|-------------| 346 346 + | `/` | GET | Health check (public) | 347 347 + | `/webhook` | POST | Receive items from mobile (`{ urls, texts, tagsets }`) | 348 348 + | `/urls` | GET | List saved URLs | 349 349 + | `/urls/:id` | DELETE | Delete URL | 350 350 + | `/urls/:id/tags` | PATCH | Update URL tags | 351 351 + | `/texts` | GET/POST | List or create texts | 352 352 + | `/tagsets` | GET/POST | List or create tagsets | 353 353 + | `/images` | GET/POST | List or upload images | 354 354 + | `/images/:id` | GET/DELETE | Get or delete image | 355 355 + | `/items` | GET/POST | Unified endpoint (filter with `?type=`) | 356 356 + | `/tags` | GET | List tags by frecency | 212 357 213 213 - # Create @2x variants 214 214 - cp assets/AppIcon.iconset/icon_32x32.png assets/AppIcon.iconset/icon_16x16@2x.png 215 215 - cp assets/AppIcon.iconset/icon_64x64.png assets/AppIcon.iconset/icon_32x32@2x.png 216 216 - cp assets/AppIcon.iconset/icon_256x256.png assets/AppIcon.iconset/icon_128x128@2x.png 217 217 - cp assets/AppIcon.iconset/icon_512x512.png assets/AppIcon.iconset/icon_256x256@2x.png 218 218 - cp assets/AppIcon.iconset/icon_1024x1024.png assets/AppIcon.iconset/icon_512x512@2x.png 219 219 - rm assets/AppIcon.iconset/icon_64x64.png assets/AppIcon.iconset/icon_1024x1024.png 358 358 + ### Server Deployment (Railway) 220 359 221 221 - iconutil -c icns assets/AppIcon.iconset -o assets/appicon.icns 222 222 - rm -rf assets/AppIcon.iconset /tmp/rounded-temp.png 360 360 + > **For the comprehensive deployment guide**, see the "Railway Deployment (Peek Server)" section in `CLAUDE.md`. This includes step-by-step workflow, user management, production testing, and troubleshooting. 361 361 + 362 362 + The server is configured for Railway deployment. 363 363 + 364 364 + **Initial Setup:** 365 365 + 1. Connect Railway to `backend/server/` subdirectory 366 366 + 2. Attach a persistent volume, set `DATA_DIR` env var to mount path 367 367 + 3. Create users via the `users.js` module 368 368 + 369 369 + **Deploying Updates:** 370 370 + ```bash 371 371 + # Link to project (one-time, from backend/server/) 372 372 + railway link -p <project-name> -s <service-name> -e production 373 373 + 374 374 + # Always run tests first 375 375 + npm test 376 376 + 377 377 + # Deploy 378 378 + railway up -d 379 379 + 380 380 + # Check logs 381 381 + railway logs -n 50 382 382 + 383 383 + # Health check 384 384 + curl https://peek-node.up.railway.app/ 223 385 ``` 224 386 225 225 - ### Icon design notes 387 387 + **Deployment Order (Server + Mobile):** 388 388 + 1. **Server first** - stateless, has auto-migrations that run on first request 389 389 + 2. **Mobile second** - works offline, adapts to server changes 390 390 + 3. One-way sync only: mobile → server (no pull/download sync yet) 226 391 227 227 - - Rounded corners at ~18% radius matches common macOS app icon style 228 228 - - 80% content size with 10% padding on each side matches Apple HIG 229 229 - - Source image should be square, ideally 1024x1024 or larger 392 392 + **Migration Gotcha:** 393 393 + When adding database columns via migration, ensure indexes on those columns are created AFTER the column migration runs, not in the initial CREATE TABLE statement. 230 394 231 231 - ## Known Issues 395 395 + ### Server Database Schema 396 396 + Different from desktop datastore - optimized for mobile sync: 397 397 + - `items` - Unified table (type: url/text/tagset/image) 398 398 + - `tags` - Tag names with frecency scoring 399 399 + - `item_tags` - Many-to-many junction 400 400 + - `settings` - Key-value config 232 401 233 233 - - **Tray icon in packaged builds**: Tray icon displays correctly in debug mode but not in packaged app builds. Works fine in dev. 402 402 + Images stored on disk in `./data/{userId}/images/` with content-hash deduplication.

+3 -3

MULTI_AGENT_WORKFLOW.md

reviewed

··· 433 433 434 434 ### Development Resources 435 435 436 436 - - See `notes/development.md` for architecture, commands, and common pitfalls 437 437 - - See `docs/PEEK-API.md` for the Peek API reference 438 438 - - See `extensions/README.md` for extension development 436 436 + - See `DEVELOPMENT.md` for architecture, commands, and common pitfalls 437 437 + - See `docs/api.md` for the Peek API reference 438 438 + - See `docs/extensions.md` for extension development 439 439 440 440 --- 441 441

+49 -379

README.md

reviewed

··· 1 1 # Peek 2 2 3 3 - Peek is a web user agent application designed for using the web where, when and how you want. 3 3 + A web user agent for using the web where, when, and how you want. 4 4 5 5 - Today's browsers are one-size-fits-all applications, cramming the vast universe of user needs across an unimaginably large web into in an unmodifiable tabbed-window design. 5 5 + Peek is not a browser. It's a workbench for experimenting with task-aligned interfaces for the web - making it easy to create new UI shapes for the web that fit your needs in the moment. 6 6 7 7 - Peek is a web user agent that is a workbench for experimenting with task alignment - making it easy to create new user interface shapes for the web which fit our need in the moment. 8 8 - 9 9 - We often use the web with a specific goal in mind - that goal should drive the design of the interface of the web user agent. 7 7 + **Status:** Concept preview. Not safe for daily use. No security audit. 10 8 11 9 <img width="969" alt="settings screenshot" src="settings-screenshot.png"> 12 10 13 13 - ## Important notes 14 14 - 15 15 - ___PEEK IS NOT A WEB BROWSER___ 16 16 - 17 17 - Peek is not a web browser, and will never be a browser in the way you are probably familiar with: There are no tabs, and no windows in the tabbed-browser-like sense of them. Peek likely does not have many other of many details we are used to in web browsers, but do not notice until they are missing. Peek may be most useful to you if you view it as an entirely different type of application than a traditional web browser. 18 18 - 19 19 - ___PEEK IS A CONCEPT PREVIEW___ 20 20 - 21 21 - Peek is not safe for daily use yet! It is a proof of concept. Do not use it for anything critical. Peek does not have the same security approach as traditional web browsers, and its security model and security user interface have not yet been determined. Peek has not had a security audit. 22 22 - 23 11 ## Features 24 12 25 25 - You can use Peek in a few ways, with more coming: 26 26 - 27 27 - - Peeks - Keyboard-activated modal chromeless web pages for quickly glancing at or interacting with pages 28 28 - - Slides - Keyboard- or gesture-activated modal chromeless web pages which slide in from any screen edges 29 29 - - Scripts - Scripts periodically executed against a web page in the background which extract data for you to route to other pages or applications, or to aggregate, store and process later 30 30 - 31 31 - In progress, or thinking about: 32 32 - 33 33 - - Commands - a graphical command entry palette (GCLI) for opening pages or executing commands against them 34 34 - - Groups - a way to categorize, recall and interact with groups of pages 35 35 - - "native" web apps - using Peek as a way to "install" web pages on the local device, as separate applications instead of just separate processes 36 36 - - "Peeklets" HUD - select parts of pages to add to collection which are rendered as an overlay, toggled by shortcut 37 37 - 38 38 - ### Usage 39 39 - 40 40 - - Settings 41 41 - * In app, `Cmd/Ctrl+r,` or launch app to open settings, or click tray icon 42 42 - * Configure Peeks/Slides/Scripts in settings 43 43 - - Peeks 44 44 - * `Opt+0-9` to open Peeks 45 45 - - Slides 46 46 - * `Opt+←→↑↓` to open Slides 47 47 - 48 48 - ### Peeks 49 49 - 50 50 - Peeks are keyboard activated modal chromeless web pages mapped to `Opt+0-9` and closed on blur, the `Escape` key or `cmd/ctrl+w`. 51 51 - 52 52 - ### Slides 53 53 - 54 54 - Slides are gesture activated modal chromeless web pages which slide in from left/right/bottom/top, and closed on blur, the `Escape` key or `cmd/ctrl+w`. 55 55 - 56 56 - ### Scripts 57 57 - 58 58 - Scripts periodically load a web page in the background and extract data matching a CSS selector, stores it, and notify the user when the resulting data changes. 59 59 - 60 60 - Ok, so not really "scripts" yet. But safe and effective enough for now. 61 61 - 62 62 - ## Design 63 63 - 64 64 - Many user tasks on the web are either transient, chained or persistent, data oriented, or some mix of those. Neither the document-oriented nor application-centric web meets those needs. Traditional browser makers can't meet those needs well, for many reasons. 65 65 - 66 66 - Characteristics of how we use the web, that are not addressed in contemporary web browsers: 67 67 - 68 68 - - transient 69 69 - - chained 70 70 - - persistent 71 71 - - data-centric 72 72 - - archival / evidential 73 73 - 74 74 - Some thoughts driving the design of Peek: 75 75 - 76 76 - - Web user agents should be bounded by the user, not browser vendor business models 77 77 - - Windows and tabs should have died a long time ago, a mixed metaphor constraining the ability of the web to grow/thrive/change and meet user needs 78 78 - - Security user interface must be a clear articulation of risks and trade-offs, and users should own the decisions 79 79 - 80 80 - ### Escape IZUI 81 81 - 82 82 - TODO: articulate the escape-to-leave aspect, eg you can peek from *other* applications and ESC to go back to exactly where you were without breaking the task flow. 83 83 - 84 84 - Escape is an inverted zooming user interface (IZUI) design for a flexible window manager that makes possible a web user agent application than can have multiple entry points and a heterogeneous windowing ecosystem. 85 85 - 86 86 - IZUI vs ZUI 87 87 - 88 88 - * ZUIs navigate by starting from a known root and user navigates by zooming ever further in, and then back out 89 89 - * Escape can enter a window stack at any point, and via a variety of methods, often from outside the application 90 90 - * Instead of navigating by zooming in, all interfaces can zoom out to go back, using the Escape key 91 91 - * This design allows unbounded and diverse entry points, but with predictable behavior 92 92 - * Regardless of the entry point, the user always has a consistent path to familiar ground 93 93 - 94 94 - Escape navigation model 95 95 - * navigation base can start at any level in stack 96 96 - * forward navigations are added on top of stack 97 97 - * backwards navigations walk the stack in reverse up the tree to the root 98 98 - 99 99 - ## Architecture / Implementation 100 100 - 101 101 - About this space: 102 102 - 103 103 - - Web pages can themselves be navigators of the web 104 104 - - Embrace the app-ness of the web platform, as a way to efficiently access the document-ness 105 105 - - Decouple html+js+css from http+dns+ssl - not entirely, but that trust+security model is not a required starting point 106 106 - - Javascript is ok here 107 107 - 108 108 - Peek is designed to be modular and configurable around the idea that parts of it 109 109 - can run in different environments. 110 110 - 111 111 - For example: 112 112 - - Planning on a mobile app which syncs and runs your peeks/slides/scripts 113 113 - - I'd like to have a decentralized compute option for running your scripts outside of your clients and syncing the data 114 114 - - Want cloud storage for all config and data, esp infinite history, so can do fun things with it 115 115 - 116 116 - ### Feature extensibility 117 117 - 118 118 - An extensibility model for achieving "personal web workbench" requires a few things: 119 119 - - UI extensibility requires OS-level window features beyond what the web allows today (also a baby step towards a minimal OS user interface) 120 120 - - Data harvest/transform/process/publish requires a method of moving data between features (web apps) *locally*, cf Web Actions/Intents/Applets, MCP, pubsub, MQTT etc 121 121 - - Portable ways of accessing network, storage and compute, which address 122 122 - 123 123 - The current implementation has only a few sketches of that world implemented, and has gone through a few iterations: 124 124 - - first proof of concept was all Electron - so, privileged JS 125 125 - - second experiment moved each feature to a separate web app running in own window scope, with access to smallest possible custom API, with one main web app loading and orchestrating the others, using pubsub for cross-app communication 126 126 - - third and current implementation bundles all features into one web app, with access to smallest possible custom API for platform-level capabilities 127 127 - 128 128 - The web app is loaded into custom scheme of `peek`, which provides access to a few special apis noted in the next section, allows cross-origin network access and other things. 129 129 - 130 130 - This is not ideal, as the extensibility vector is contributions to core, which too tightly bounds experimentation and innovation. 131 131 - 132 132 - However it's pretty portable given the small custom API surface area. 133 133 - 134 134 - It would be nice, but not required, to have some alignment with the WebExtension spec - blur your eyes and they're in a similar direction. 135 135 - 136 136 - ### Peek API 137 137 - 138 138 - Initially the prototype was all Electron. But that's not interesting, and doesn't 139 139 - really tell us anything about constraints of the web itself. 140 140 - 141 141 - So instead I asked this question: What's the minimum capability set that a web app would 142 142 - need to build the features I need? 13 13 + - **Peeks** - Keyboard-activated modal web pages (`Opt+0-9`) 14 14 + - **Slides** - Gesture-activated pages that slide in from screen edges (`Opt+arrows`) 15 15 + - **Scripts** - Background page monitors that extract and track data 16 16 + - **Commands** - Command palette for opening pages and executing actions 17 17 + - **Groups** - Tag-based page organization (like Firefox Panorama) 18 18 + - **Sync** - Cross-device sync between desktop, mobile, and server 143 19 144 144 - The answer, so far, is giving `peek` apps the following APIs: 20 20 + ## Quick Start 145 21 146 146 - - window open/close 147 147 - - global hotkey registration 148 148 - - pubsub messaging 22 22 + ```bash 23 23 + # Requirements: Node.js 24+ 24 24 + nvm use 24 149 25 150 150 - Custom window api might be able to away entirely, by passing window.open features, working on that. 151 151 - 152 152 - ### Desktop App 153 153 - 154 154 - Proof of concept is Electron. By far the best option today for cross-platform desktop apps which need a web rendering engine. There's really nothing else remotely suited (yet). 155 155 - 156 156 - User interface: 157 157 - - the built-in features are all modal chromeless web pages at this point 158 158 - - settings UI uses custom sidebar navigation with dark mode support 159 159 - 160 160 - TODO 161 161 - - Need to look at whether could library-ize some of what Agregore implemented for non-HTTP protocol support. 162 162 - - Min browser might be interesting as a forkable base to work from and contribute to, if they're open to it. At least, should look more at the architecture. 163 163 - 164 164 - ## Contribution 165 165 - 166 166 - - in proto stage 167 167 - - all dragons, no promises 168 168 - 169 169 - ## Development 170 170 - 171 171 - ``` 26 26 + # Install and run 172 27 yarn install 173 173 - yarn debug 28 28 + yarn debug # Development mode with devtools 29 29 + yarn start # Normal mode 174 30 ``` 175 31 176 176 - ### Mobile 177 177 - 178 178 - - Quick access to Script output and manual runs, as widgets (or output from cloud runners?) 179 179 - - Peeks still totes useful here - on mobile is more like "quick dial" features 180 180 - 181 181 - ### Cloud 182 182 - 183 183 - - Going full crypto payments for distributed compute on this one. 184 184 - 185 185 - ## Papercut / use-case log 186 186 - 187 187 - Core high level actions 188 188 - - open a web page on top/bottom/left/right 189 189 - - keep web pages persistent in the background 190 190 - - quickly open a web page modally, and close it 191 191 - 192 192 - Misc specific 193 193 - - open bandcamp in a window, move over to 2nd display, accidently close it while moving around between other windows 194 194 - - recent books or recipes from newsletters i subscribe to (but probably didn't read) 195 195 - - extract a table from a page periodically, send it somewhere as csv or whatever (chained actions) 196 196 - - collect microformats, metadata, events 197 197 - - web page w/ some locations as an input to a map (creates overlay) "map this page" 198 198 - - be able to see where a book/etc recommendation came from 199 199 - - save a tweet, with URL / image / relevant text, but not whole page webrecorder style 200 200 - - "watch local event listings, rate against my music listening patterns and send me shows i might be interested in going to" 201 201 - 202 202 - Content scripts 203 203 - - extract+log shazams 204 204 - - extract+log spotify playlist 205 205 - 206 206 - Calculators (variant of script + cmd?) 207 207 - - page -> table 208 208 - - page -> summary 209 209 - - page -> microsummaries 210 210 - - page -> dates 211 211 - - page -> events 212 212 - 213 213 - Workflow deconstructing a "why" task flavour of bookmarking 214 214 - - save https://www.criterionchannel.com/hong-kong-in-new-york 215 215 - - extract the movies 216 216 - - get reference metadata for each (?!) 217 217 - - add to "to watch list", with pointer back to source url 218 218 - 219 219 - ## Groups 220 220 - 221 221 - - panorama/tabcandy-ish 222 222 - - all browser history 223 223 - - smart groups vs curated groups 224 224 - - autoclustering on topic/date 225 225 - - escape from a new page enters default group? 226 226 - 227 227 - Groups + Cmds 228 228 - - top/bottom inputs for filtering/grouping/etc 229 229 - - implemented is a cmd input? 230 230 - - cmds for opening/searching/finding/viewing/filtering/piping 231 231 - - cmds for moving pages into groups 232 232 - - groups -> {x} (eg export/pipe) could depend on the chaining/piping bit (see below) 233 233 - 234 234 - Architecture 235 235 - - internally is tags? 236 236 - - static vs dynamic groups tho? 237 237 - 238 238 - Publishing 239 239 - - publishing groups as internal/public feeds? 240 240 - - to pinboard? 241 241 - 242 242 - ## History view/search 243 243 - 244 244 - A lot of groups work depends on history being in place, and being accessable and annotate-able. 245 245 - 246 246 - ideally use chromium history 247 247 - 248 248 - storage+access 249 249 - - check out Agregore history viewing approach 250 250 - - check out state of electron+webext 251 251 - - other way of accessing underlying chromium history? 252 252 - 253 253 - features 254 254 - - awesomebar algo scoring 255 255 - - adaptive matching 256 256 - 257 257 - ## Chaining / piping 258 258 - 259 259 - investigate: vague thought re chaining: 260 260 - - dynamic interstitial representations 261 261 - - mime type detection? 262 262 - - eg image previews 263 263 - - or a table of data 264 264 - - previews of cmds? 265 265 - 266 266 - interfaces 267 267 - - horizontal vs vertical chains 268 268 - - back/forward navigation? 269 269 - - each step is a cmd+preview? 270 270 - - dynamic cmd+previews? 271 271 - 272 272 - import/export/undo/redo 273 273 - - record/replay? 274 274 - - save a chain as a compound action (cmd)? 275 275 - 276 276 - architecture 277 277 - - look at web actions/intents/applets 278 278 - - xml pipeline language 279 279 - 280 280 - ## Mobile 281 281 - 282 282 - - some of the features don't make sense as-is on mobile 283 283 - - but maybe quick access on mobile to slides/peeks would be nice 284 284 - - and seeing output of content scripts, or ability to re-run locally on demand 285 285 - - needs some sync facility (inevitable anyway) 286 286 - 287 287 - ## Use-cases 288 288 - 289 289 - Peeks 290 290 - - translate 291 291 - - calendar 292 292 - - ai chat 293 293 - - currency conversion 294 294 - - everytimezone 295 295 - - tldraw 296 296 - 297 297 - Slides 298 298 - - music: Soundcloud, Hypem 299 299 - - stock prices 300 300 - - notepad 301 301 - - todo list 302 302 - 303 303 - Scripts 304 304 - - weather change, eg upcoming weather 305 305 - - crypto prices 306 306 - 307 307 - Cmd - web 308 308 - - open url 309 309 - - web search 310 310 - - image search 311 311 - - conversions? 312 312 - - ddg !actions 313 313 - 314 314 - Cmd - system 315 315 - - search browser history 316 316 - - set peeks/slides 317 317 - - open settings 318 318 - - restart app 319 319 - - llm prompts 320 320 - 321 321 - Future 322 322 - - address something to switch between 323 323 - - pipe from/to? 32 32 + See [DEVELOPMENT.md](DEVELOPMENT.md) for full development guide. 324 33 325 325 - Publishing high level 326 326 - - author web content 327 327 - - pull in bits from the web 328 328 - - share preview for feedback 329 329 - - publish (or at least get output) 34 34 + ## Architecture 330 35 331 331 - Publishing examples 332 332 - - writing an event recap 36 36 + Peek supports multiple backends sharing the same renderer code: 333 37 334 334 - Publishing: event recap post 335 335 - - make a new markdown doc 336 336 - - sections titled for each video title 337 337 - - each video's embed code in each section 338 338 - - navigate around the document for review and updates 339 339 - - need to easily preview rendered content 340 340 - - share preview link 341 341 - - publish (somewhere?) 38 38 + ``` 39 39 + peek/ 40 40 + ├── app/ # Renderer (backend-agnostic) 41 41 + ├── extensions/ # Built-in extensions 42 42 + ├── backend/ 43 43 + │ ├── electron/ # Desktop (primary) 44 44 + │ ├── tauri/ # Desktop (Rust alternative) 45 45 + │ ├── tauri-mobile/ # iOS/Android 46 46 + │ └── server/ # Sync server (Node.js/Hono) 47 47 + └── docs/ # Documentation 48 48 + ``` 342 49 343 343 - Music 344 344 - - commands 345 345 - - views 346 346 - - last.fm of my own, to POSSE out 50 50 + ## Documentation 347 51 348 348 - ## Unfiled 52 52 + | Doc | Description | 53 53 + |-----|-------------| 54 54 + | [DEVELOPMENT.md](DEVELOPMENT.md) | Development setup, commands, architecture | 55 55 + | [docs/api.md](docs/api.md) | Peek API reference (`window.app`) | 56 56 + | [docs/extensions.md](docs/extensions.md) | Extension development | 57 57 + | [docs/datastore.md](docs/datastore.md) | Data storage and schema | 58 58 + | [docs/sync.md](docs/sync.md) | Cross-device sync | 59 59 + | [docs/MOBILE.md](docs/MOBILE.md) | Mobile development | 349 60 350 350 - markdown hot reload previewer w/ toc 351 351 - - markdown support, with sidebar nav 352 352 - - reader mode 353 353 - - hot reload for file:// (other?) 354 354 - - add side-by-side view 355 355 - - once md and side-by-side, add side-by-side so the md is the nav, content is the preview 356 356 - - what's the cmd chain for this? 61 61 + ## Design Philosophy 357 62 358 358 - content types + chaining 359 359 - - cmd: view as… table, feed, markdown, data points, named entities 360 360 - - chain: static archive, publish, save, share (os), mailto 361 361 - - cmd params, eg {url}, which can themselves autocomplete (eg history) 63 63 + - Web pages can be navigators of the web 64 64 + - User tasks on the web are transient, chained, persistent, or data-oriented - none well-served by tabbed browsers 65 65 + - The "Escape IZUI" pattern: enter at any point, ESC always returns to familiar ground 66 66 + - Minimum viable API surface for web apps to access platform capabilities 362 67 363 363 - multiprotocol 364 364 - - at 365 365 - - ipfs/ipns 366 366 - - pragmatic addressing+rendering for data (r/d/masl + mime handlers) 68 68 + See [notes/extensibility.md](notes/extensibility.md) for detailed design notes. 367 69 368 368 - broader patterns (chatting w/ luke) 369 369 - - why do we have to copy/paste? 370 370 - - devtools and ide are divorced 70 70 + ## Contributing 371 71 372 372 - chainframe/framechain 373 373 - - (web intents/applets/actions) + (webxdc/miniapps/tiles/farcasterframes) 72 72 + Concept stage - contributions welcome but expect dragons. 374 73 375 375 - Small examples of agency 74 74 + ## License 376 75 377 377 - - users can move, resize, change things to their requirements 378 378 - - eg, browsers restrict min-height of a window, but i should be able make as short as i like 379 379 - 380 380 - ## History 381 381 - 382 382 - In working on Firefox and related things at Mozilla from 2006 - 2019, there were a few specific initiatives which best aligned with my needs as a user on the web: 383 383 - 384 384 - - The Awesomebar: infinite history + personalized local search index 385 385 - - Ubiquity: Natural language commands + chaining 386 386 - - Jetpack: The Mozilla Labs version - web-platfrom-centric extensibility 387 387 - - Panorama: née TabCandy, web pages as groups instead of tabs in windows 388 388 - 389 389 - A few others which were in the right direction but didn't achieve their optimal form: 390 390 - 391 391 - - Greasemonkey 392 392 - - Microsummaries 393 393 - - Contacts extension 394 394 - 395 395 - The first version of the Peek application has some bits of each of these, and the original Peek browser extension. 396 396 - 397 397 - ### Peek browser extension 398 398 - 399 399 - Peek was a browser extension that let you quickly peek at your favorite web pages without breaking your flow - loading pages mapped to keyboard shortcuts into a modal window with no controls, closable via the `Escape` key. 400 400 - 401 401 - However, as browser extension APIs became increasingly limited, it was not possible to create a decent user experience and I abandoned it. You can access the extension in this repo [in the extension directory](/autonome/peek/extension/). 402 402 - 403 403 - The only way to create the ideal user experience for a web user agent that *Does What I Want* is to make it a browser-ish application, and that's what Peek is now. 404 404 - 405 405 - 406 406 - 76 76 + MIT

+3 -3

backend/README.md

reviewed

··· 5 5 ## Design Principles 6 6 7 7 1. **Backend Abstraction**: The `app/` directory contains all renderer code and must work unchanged with any backend 8 8 - 2. **Shared API Contract**: All backends expose the same Peek API (`window.app`) - see `docs/PEEK-API.md` 8 8 + 2. **Shared API Contract**: All backends expose the same Peek API (`window.app`) - see `docs/api.md` 9 9 3. **Shared Data**: Backends use the same SQLite schema and can share database files 10 10 4. **Profile Isolation**: Data is separated by profile (dev, default, etc.) 11 11 ··· 72 72 Database location: `{app_data}/{profile}/datastore.sqlite` 73 73 74 74 ### 4. Peek API Injection 75 75 - Inject the `window.app` API before any page scripts run. See `docs/PEEK-API.md` for the complete API reference. 75 75 + Inject the `window.app` API before any page scripts run. See `docs/api.md` for the complete API reference. 76 76 77 77 ## API Contract 78 78 ··· 185 185 2. Implement custom protocol handler for `peek://` 186 186 3. Implement SQLite datastore with shared schema 187 187 4. Implement window management commands 188 188 - 5. Implement the Peek API (`window.app`) matching `docs/PEEK-API.md` 188 188 + 5. Implement the Peek API (`window.app`) matching `docs/api.md` 189 189 6. Inject the API before page scripts run 190 190 191 191 The renderer code (`app/`) should work without modification.

docs/Peek-API.md docs/api.md

reviewed

+180

docs/datastore.md

reviewed

··· 1 1 + # Peek Datastore 2 2 + 3 3 + The Peek Personal Datastore stores addresses, navigation history, tags, notes, and other user data. It uses SQLite with a unified schema across all backends (Electron, Tauri, Server). 4 4 + 5 5 + ## Architecture 6 6 + 7 7 + All data operations are handled in the main/backend process, with renderer processes accessing via IPC through `window.app.datastore`. 8 8 + 9 9 + ``` 10 10 + Renderer Process Main/Backend Process 11 11 + ┌─────────────────┐ ┌─────────────────────┐ 12 12 + │ window.app. │ IPC invoke() │ IPC Handlers │ 13 13 + │ datastore.* │───────────────▶│ ├─ add-item │ 14 14 + │ │ │ ├─ query-items │ 15 15 + │ │ │ ├─ add-visit │ 16 16 + │ │ │ └─ ... │ 17 17 + └─────────────────┘ │ │ │ 18 18 + │ ▼ │ 19 19 + │ ┌─────────────┐ │ 20 20 + │ │ SQLite │ │ 21 21 + │ │ Database │ │ 22 22 + │ └─────────────┘ │ 23 23 + └─────────────────────┘ 24 24 + ``` 25 25 + 26 26 + ### Why IPC-Based? 27 27 + 28 28 + 1. **Backend Portability** - Same renderer code works with Electron, Tauri, or mobile 29 29 + 2. **Storage Flexibility** - Can swap SQLite for other backends without renderer changes 30 30 + 3. **Security** - Datastore logic in trusted main process 31 31 + 4. **Sync Readiness** - Same API can route to local or remote storage 32 32 + 33 33 + ## Database Schema 34 34 + 35 35 + Location: `{app_data}/{profile}/datastore.sqlite` 36 36 + 37 37 + ### Core Tables 38 38 + 39 39 + #### `items` - Unified Item Storage 40 40 + Stores all user content types: URLs, text notes, tagsets, images. 41 41 + 42 42 + | Column | Type | Description | 43 43 + |--------|------|-------------| 44 44 + | id | TEXT | Primary key (UUID) | 45 45 + | type | TEXT | `url`, `text`, `tagset`, `image` | 46 46 + | content | TEXT | The actual content (URL, note text, etc.) | 47 47 + | title | TEXT | Display title | 48 48 + | metadata | TEXT | JSON for flexible extra data | 49 49 + | createdAt | TEXT | ISO timestamp | 50 50 + | updatedAt | TEXT | ISO timestamp | 51 51 + | syncedAt | TEXT | Last sync timestamp | 52 52 + | sync_id | TEXT | Server-assigned ID for sync | 53 53 + 54 54 + #### `visits` - Navigation History 55 55 + Tracks page visits with timing and context. 56 56 + 57 57 + | Column | Type | Description | 58 58 + |--------|------|-------------| 59 59 + | id | TEXT | Primary key | 60 60 + | addressId | TEXT | FK to items | 61 61 + | timestamp | INTEGER | Unix timestamp (ms) | 62 62 + | duration | INTEGER | Time spent (ms) | 63 63 + | source | TEXT | `peek`, `slide`, `direct`, `link` | 64 64 + | windowType | TEXT | `modal`, `persistent`, `main` | 65 65 + 66 66 + #### `tags` - Tag Definitions 67 67 + | Column | Type | Description | 68 68 + |--------|------|-------------| 69 69 + | id | TEXT | Primary key | 70 70 + | name | TEXT | Tag name (unique) | 71 71 + | frecency | REAL | Usage frequency score | 72 72 + 73 73 + #### `item_tags` - Tag Associations 74 74 + | Column | Type | Description | 75 75 + |--------|------|-------------| 76 76 + | item_id | TEXT | FK to items | 77 77 + | tag_id | TEXT | FK to tags | 78 78 + 79 79 + #### `extension_settings` - Extension Config 80 80 + Key-value storage for extension and core settings. 81 81 + 82 82 + | Column | Type | Description | 83 83 + |--------|------|-------------| 84 84 + | key | TEXT | Setting key (e.g., `sync.serverUrl`) | 85 85 + | value | TEXT | JSON-encoded value | 86 86 + 87 87 + ## API Reference 88 88 + 89 89 + Access via `window.app.datastore` in any `peek://` page. 90 90 + 91 91 + ### Items 92 92 + 93 93 + ```javascript 94 94 + // Add item 95 95 + const result = await api.datastore.addItem({ 96 96 + type: 'url', 97 97 + content: 'https://example.com', 98 98 + title: 'Example', 99 99 + tags: ['bookmark', 'work'] 100 100 + }); 101 101 + 102 102 + // Query items 103 103 + const urls = await api.datastore.queryItems({ type: 'url' }); 104 104 + const tagged = await api.datastore.queryItems({ tag: 'bookmark' }); 105 105 + 106 106 + // Update item 107 107 + await api.datastore.updateItem(id, { title: 'New Title' }); 108 108 + 109 109 + // Delete item 110 110 + await api.datastore.deleteItem(id); 111 111 + ``` 112 112 + 113 113 + ### Tags 114 114 + 115 115 + ```javascript 116 116 + // Get or create tag 117 117 + const tag = await api.datastore.getOrCreateTag('bookmark'); 118 118 + 119 119 + // Tag an item 120 120 + await api.datastore.tagItem(itemId, tagId); 121 121 + 122 122 + // Untag 123 123 + await api.datastore.untagItem(itemId, tagId); 124 124 + 125 125 + // Get item's tags 126 126 + const tags = await api.datastore.getItemTags(itemId); 127 127 + 128 128 + // Get items by tag 129 129 + const items = await api.datastore.getItemsByTag(tagId); 130 130 + ``` 131 131 + 132 132 + ### Visits 133 133 + 134 134 + ```javascript 135 135 + // Record visit 136 136 + await api.datastore.addVisit(addressId, { 137 137 + source: 'peek', 138 138 + windowType: 'modal' 139 139 + }); 140 140 + 141 141 + // Query visits 142 142 + const history = await api.datastore.queryVisits({ 143 143 + limit: 100, 144 144 + offset: 0 145 145 + }); 146 146 + ``` 147 147 + 148 148 + ### Settings 149 149 + 150 150 + ```javascript 151 151 + // Get setting 152 152 + const value = await api.datastore.getSetting('sync.serverUrl'); 153 153 + 154 154 + // Set setting 155 155 + await api.datastore.setSetting('sync.serverUrl', 'https://...'); 156 156 + ``` 157 157 + 158 158 + ### Stats 159 159 + 160 160 + ```javascript 161 161 + const stats = await api.datastore.getStats(); 162 162 + // Returns: { items: 150, visits: 1200, tags: 25 } 163 163 + ``` 164 164 + 165 165 + ## Sync 166 166 + 167 167 + The datastore syncs between backends via the server API: 168 168 + 169 169 + 1. **Desktop ↔ Server**: Bidirectional sync in `backend/electron/sync.ts` 170 170 + 2. **Mobile → Server**: Push sync from mobile app 171 171 + 3. **Conflict Resolution**: Last-write-wins based on `updatedAt` 172 172 + 173 173 + See `docs/sync.md` for sync architecture details. 174 174 + 175 175 + ## Files 176 176 + 177 177 + - `backend/electron/datastore.ts` - Electron SQLite implementation 178 178 + - `backend/tauri/src-tauri/src/datastore.rs` - Tauri SQLite implementation 179 179 + - `backend/server/db.js` - Server SQLite implementation 180 180 + - `app/datastore/` - Shared schema and helpers

+347

docs/extensions.md

reviewed

··· 1 1 + # Peek Extensions 2 2 + 3 3 + Extensions are isolated modules that communicate with the core app via IPC and pubsub messaging. 4 4 + 5 5 + ## Hybrid Extension Architecture 6 6 + 7 7 + Peek uses a **hybrid extension loading model** that balances memory efficiency with crash isolation: 8 8 + 9 9 + ### Built-in Extensions (Consolidated) 10 10 + Built-in extensions (`cmd`, `groups`, `peeks`, `slides`) run as **iframes in a single extension host window**: 11 11 + - Share a single Electron BrowserWindow process 12 12 + - Memory efficient (~80-120MB vs ~200-400MB for separate windows) 13 13 + - Origin isolation via unique URL hosts (`peek://cmd/`, `peek://groups/`, etc.) 14 14 + - If one crashes, others in the same host are affected 15 15 + 16 16 + ### External Extensions (Separate Windows) 17 17 + External extensions (including `example` and user-installed) run in **separate BrowserWindows**: 18 18 + - Each has its own Electron process 19 19 + - Crash isolation - one extension crashing doesn't affect others 20 20 + - Uses `peek://ext/{id}/` URL scheme 21 21 + - Better for untrusted or experimental extensions 22 22 + 23 23 + ``` 24 24 + ┌─────────────────────────────────────────────────────────────┐ 25 25 + │ Extension Host Window (peek://app/extension-host.html) │ 26 26 + │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────┐ │ 27 27 + │ │ <iframe> │ │ <iframe> │ │ <iframe> │ │<iframe> │ │ 28 28 + │ │ peek://cmd/ │ │peek://groups│ │peek://peeks/│ │peek:// │ │ 29 29 + │ │ │ │ │ │ │ │slides/ │ │ 30 30 + │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────┘ │ 31 31 + └─────────────────────────────────────────────────────────────┘ 32 32 + 33 33 + ┌─────────────────┐ ┌─────────────────┐ 34 34 + │ BrowserWindow │ │ BrowserWindow │ 35 35 + │ peek://ext/ │ │ peek://ext/ │ 36 36 + │ example/ │ │ user-ext/ │ 37 37 + │ (separate proc) │ │ (separate proc) │ 38 38 + └─────────────────┘ └─────────────────┘ 39 39 + ``` 40 40 + 41 41 + ### Origin Isolation 42 42 + 43 43 + Each extension gets a unique origin regardless of loading mode: 44 44 + - Built-in: `peek://cmd/background.html` → origin `peek://cmd` 45 45 + - External: `peek://ext/example/background.html` → origin `peek://ext` 46 46 + 47 47 + This prevents cross-extension access to localStorage, DOM, and globals. 48 48 + 49 49 + ## Extension Structure 50 50 + 51 51 + Each extension lives in its own directory under `extensions/`: 52 52 + 53 53 + ``` 54 54 + extensions/ 55 55 + example/ 56 56 + manifest.json # Extension metadata 57 57 + settings-schema.json # Settings UI schema (optional) 58 58 + background.html # Entry point (loads background.js) 59 59 + background.js # Main extension logic 60 60 + *.html, *.js, *.css # Additional UI files 61 61 + ``` 62 62 + 63 63 + ### manifest.json 64 64 + 65 65 + Required fields: 66 66 + ```json 67 67 + { 68 68 + "id": "example", 69 69 + "shortname": "example", 70 70 + "name": "Example Extension", 71 71 + "description": "What this extension does", 72 72 + "version": "1.0.0", 73 73 + "background": "background.html" 74 74 + } 75 75 + ``` 76 76 + 77 77 + Optional fields: 78 78 + ```json 79 79 + { 80 80 + "builtin": true, 81 81 + "settingsSchema": "./settings-schema.json" 82 82 + } 83 83 + ``` 84 84 + 85 85 + ### settings-schema.json 86 86 + 87 87 + Defines the settings UI for the extension. Used by Settings to render configuration forms. 88 88 + 89 89 + ```json 90 90 + { 91 91 + "prefs": { 92 92 + "type": "object", 93 93 + "properties": { 94 94 + "greeting": { 95 95 + "type": "string", 96 96 + "description": "Custom greeting message", 97 97 + "default": "Hello World" 98 98 + } 99 99 + } 100 100 + }, 101 101 + "storageKeys": { 102 102 + "PREFS": "prefs" 103 103 + }, 104 104 + "defaults": { 105 105 + "prefs": { 106 106 + "greeting": "Hello World" 107 107 + } 108 108 + } 109 109 + } 110 110 + ``` 111 111 + 112 112 + For extensions with list-based settings (like peeks/slides), add an `item` schema: 113 113 + ```json 114 114 + { 115 115 + "prefs": { ... }, 116 116 + "item": { 117 117 + "type": "object", 118 118 + "properties": { 119 119 + "title": { "type": "string", "title": "Title" }, 120 120 + "enabled": { "type": "boolean", "title": "Enabled" } 121 121 + } 122 122 + }, 123 123 + "storageKeys": { 124 124 + "PREFS": "prefs", 125 125 + "ITEMS": "items" 126 126 + }, 127 127 + "defaults": { 128 128 + "prefs": { ... }, 129 129 + "items": [] 130 130 + } 131 131 + } 132 132 + ``` 133 133 + 134 134 + ### background.html 135 135 + 136 136 + Entry point that loads the extension as an ES module: 137 137 + 138 138 + ```html 139 139 + <!DOCTYPE html> 140 140 + <html> 141 141 + <head> 142 142 + <meta charset="UTF-8"> 143 143 + <title>My Extension</title> 144 144 + </head> 145 145 + <body> 146 146 + <script type="module"> 147 147 + import extension from './background.js'; 148 148 + 149 149 + const api = window.app; 150 150 + const extId = extension.id; 151 151 + 152 152 + console.log(`[ext:${extId}] background.html loaded`); 153 153 + 154 154 + // Signal ready to main process 155 155 + api.publish('ext:ready', { 156 156 + id: extId, 157 157 + manifest: { 158 158 + id: extension.id, 159 159 + labels: extension.labels, 160 160 + version: '1.0.0' 161 161 + } 162 162 + }, api.scopes.SYSTEM); 163 163 + 164 164 + // Initialize extension 165 165 + if (extension.init) { 166 166 + console.log(`[ext:${extId}] calling init()`); 167 167 + extension.init(); 168 168 + } 169 169 + 170 170 + // Handle shutdown 171 171 + api.subscribe('app:shutdown', () => { 172 172 + if (extension.uninit) extension.uninit(); 173 173 + }, api.scopes.SYSTEM); 174 174 + 175 175 + api.subscribe(`ext:${extId}:shutdown`, () => { 176 176 + if (extension.uninit) extension.uninit(); 177 177 + }, api.scopes.SYSTEM); 178 178 + </script> 179 179 + </body> 180 180 + </html> 181 181 + ``` 182 182 + 183 183 + ### background.js 184 184 + 185 185 + Main extension logic as an ES module: 186 186 + 187 187 + ```javascript 188 188 + const api = window.app; 189 189 + 190 190 + const extension = { 191 191 + id: 'example', 192 192 + labels: { 193 193 + name: 'Example' 194 194 + }, 195 195 + 196 196 + init() { 197 197 + console.log('[example] init'); 198 198 + 199 199 + // Register commands 200 200 + api.commands.register({ 201 201 + name: 'my-command', 202 202 + description: 'Does something', 203 203 + execute: () => { 204 204 + console.log('Command executed!'); 205 205 + } 206 206 + }); 207 207 + 208 208 + // Register shortcuts 209 209 + api.shortcuts.register('Option+x', () => { 210 210 + console.log('Shortcut triggered!'); 211 211 + }); 212 212 + 213 213 + // Subscribe to events 214 214 + api.subscribe('some:event', (msg) => { 215 215 + console.log('Event received:', msg); 216 216 + }, api.scopes.GLOBAL); 217 217 + }, 218 218 + 219 219 + uninit() { 220 220 + console.log('[example] uninit'); 221 221 + api.commands.unregister('my-command'); 222 222 + api.shortcuts.unregister('Option+x'); 223 223 + } 224 224 + }; 225 225 + 226 226 + export default extension; 227 227 + ``` 228 228 + 229 229 + ## Extension API 230 230 + 231 231 + Extensions access the Peek API via `window.app`. See `docs/api.md` for the complete reference. 232 232 + 233 233 + Common APIs used by extensions: 234 234 + 235 235 + ### Commands 236 236 + ```javascript 237 237 + api.commands.register({ name, description, execute }) 238 238 + api.commands.unregister(name) 239 239 + ``` 240 240 + 241 241 + ### Shortcuts 242 242 + ```javascript 243 243 + api.shortcuts.register(shortcut, callback) // e.g., 'Option+1' 244 244 + api.shortcuts.unregister(shortcut) 245 245 + ``` 246 246 + 247 247 + ### Pubsub Messaging 248 248 + ```javascript 249 249 + api.publish(topic, data, scope) 250 250 + api.subscribe(topic, callback, scope) 251 251 + 252 252 + // Scopes 253 253 + api.scopes.SELF // Only this window 254 254 + api.scopes.SYSTEM // System-level events 255 255 + api.scopes.GLOBAL // All windows 256 256 + ``` 257 257 + 258 258 + ### Windows 259 259 + ```javascript 260 260 + api.window.open(url, options) 261 261 + // Options: modal, keepLive, transparent, height, width, key 262 262 + ``` 263 263 + 264 264 + ### Datastore 265 265 + ```javascript 266 266 + await api.datastore.getRow(table, id) 267 267 + await api.datastore.setRow(table, id, data) 268 268 + await api.datastore.deleteRow(table, id) 269 269 + await api.datastore.getTable(table) 270 270 + ``` 271 271 + 272 272 + ### Extension Settings 273 273 + ```javascript 274 274 + await api.extensions.getSettings(extId) 275 275 + await api.extensions.setSettings(extId, key, value) 276 276 + ``` 277 277 + 278 278 + ## Extension Loading 279 279 + 280 280 + ### Load Order and the cmd Extension 281 281 + 282 282 + The `cmd` extension is the command registry - all other extensions register their commands with it via `api.commands.register()`. Because of this dependency: 283 283 + 284 284 + 1. **cmd loads first** (sequential) - must be ready before other extensions register commands 285 285 + 2. **Other extensions load in parallel** - for faster startup 286 286 + 3. **cmd cannot be disabled** - it's required infrastructure, not optional functionality 287 287 + 288 288 + This is enforced in `isBuiltinExtensionEnabled()` which always returns `true` for cmd. 289 289 + 290 290 + ### Hybrid Loading Process 291 291 + 292 292 + Extensions are loaded in hybrid mode by `loadExtensions()` in `backend/electron/main.ts`: 293 293 + 294 294 + 1. **Create extension host window** - Single BrowserWindow at `peek://app/extension-host.html` 295 295 + 2. **Load built-in extensions as iframes** - `cmd`, `groups`, `peeks`, `slides` loaded via IPC into the host 296 296 + 3. **Load external extensions as separate windows** - Each gets its own BrowserWindow 297 297 + 298 298 + ```typescript 299 299 + // Which extensions use consolidated mode (defined in main.ts) 300 300 + const CONSOLIDATED_EXTENSION_IDS = ['cmd', 'groups', 'peeks', 'slides']; 301 301 + ``` 302 302 + 303 303 + ### Built-in Extensions 304 304 + 305 305 + Built-in extensions are registered in `index.js`: 306 306 + ```javascript 307 307 + registerExtensionPath('example', path.join(__dirname, 'extensions', 'example')); 308 308 + ``` 309 309 + 310 310 + Built-in extensions that are NOT in `CONSOLIDATED_EXTENSION_IDS` (like `example`) are treated as external and get separate windows. This is intentional - it exercises external extension code paths during development. 311 311 + 312 312 + ### External Extensions 313 313 + 314 314 + External extensions are: 315 315 + 1. Added via Settings UI (stored in datastore `extensions` table) 316 316 + 2. Loaded on startup if `enabled === 1` and have a valid `path` 317 317 + 3. Always run in separate BrowserWindows for crash isolation 318 318 + 319 319 + ## Settings Integration 320 320 + 321 321 + Extensions with `settingsSchema` in their manifest automatically get a settings section in the Settings UI. The schema is loaded at runtime when the extension window is created. 322 322 + 323 323 + Settings are stored in the `extension_settings` datastore table with: 324 324 + - `extensionId`: The extension's ID 325 325 + - `key`: Setting key (e.g., 'prefs', 'items') 326 326 + - `value`: JSON-encoded setting value 327 327 + 328 328 + Extensions can listen for settings changes: 329 329 + ```javascript 330 330 + api.subscribe(`${extId}:settings-changed`, (msg) => { 331 331 + // Reload configuration 332 332 + }, api.scopes.GLOBAL); 333 333 + ``` 334 334 + 335 335 + ## Lifecycle Events 336 336 + 337 337 + - `ext:ready` - Published when extension is initialized 338 338 + - `ext:all-loaded` - Published when all extensions finish loading 339 339 + - `app:shutdown` - Sent before app closes 340 340 + - `ext:{id}:shutdown` - Sent when specific extension is being unloaded 341 341 + - `{extId}:settings-changed` - Sent when extension settings are modified 342 342 + 343 343 + ## Debugging 344 344 + 345 345 + Console logs from extensions are forwarded to stdout with prefix `[ext:{id}]`. 346 346 + 347 347 + Run with `DEBUG=1 yarn start` for verbose logging.

+115

docs/sync.md

reviewed

··· 1 1 + # Peek Sync 2 2 + 3 3 + Cross-platform data synchronization between mobile, desktop, and server. 4 4 + 5 5 + ## Architecture 6 6 + 7 7 + ``` 8 8 + ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ 9 9 + │ Mobile │────▶│ Server │◀────│ Desktop │ 10 10 + │ (Tauri) │ │ (Hono) │ │ (Electron) │ 11 11 + └─────────────┘ └─────────────┘ └─────────────┘ 12 12 + │ │ │ 13 13 + ▼ ▼ ▼ 14 14 + SQLite SQLite SQLite 15 15 + ``` 16 16 + 17 17 + The server acts as the source of truth. All clients push and pull data via the server's REST API. 18 18 + 19 19 + ## Item Types 20 20 + 21 21 + All platforms use the same unified types: 22 22 + 23 23 + | Type | Description | Content Field | 24 24 + |------|-------------|---------------| 25 25 + | `url` | Saved URLs/bookmarks | The URL string | 26 26 + | `text` | Text content/notes | The text content | 27 27 + | `tagset` | Tag-only items | null | 28 28 + | `image` | Binary images | Base64 data or filename | 29 29 + 30 30 + ## Sync Protocol 31 31 + 32 32 + ### Pull (Server → Client) 33 33 + 34 34 + 1. Fetch: `GET /items` (full) or `GET /items/since/:timestamp` (incremental) 35 35 + 2. For each server item: 36 36 + - Find local item by `syncId` matching server `id` 37 37 + - If not found: insert new item 38 38 + - If found and server is newer: update local 39 39 + - If local is newer: skip (will push later) 40 40 + 41 41 + ### Push (Client → Server) 42 42 + 43 43 + 1. Query items where `syncSource = ''` OR `updatedAt > lastSyncTime` 44 44 + 2. For each item: `POST /items` with type, content, tags 45 45 + 3. On success: update local `syncId` and `syncSource` 46 46 + 47 47 + ### Conflict Resolution 48 48 + 49 49 + **Last-write-wins** based on `updatedAt` timestamp. 50 50 + 51 51 + ## API Endpoints 52 52 + 53 53 + ### Server 54 54 + 55 55 + ``` 56 56 + GET /items # All items 57 57 + GET /items/since/:timestamp # Items modified after timestamp 58 58 + GET /items/:id # Single item 59 59 + POST /items # Create item 60 60 + PATCH /items/:id/tags # Update tags 61 61 + DELETE /items/:id # Delete item 62 62 + ``` 63 63 + 64 64 + ### Desktop IPC 65 65 + 66 66 + ```javascript 67 67 + await window.app.sync.getConfig() // Get server URL, API key 68 68 + await window.app.sync.setConfig(cfg) // Save config 69 69 + await window.app.sync.pull() // Pull from server 70 70 + await window.app.sync.push() // Push to server 71 71 + await window.app.sync.full() // Full bidirectional sync 72 72 + ``` 73 73 + 74 74 + ## Configuration 75 75 + 76 76 + ### Desktop 77 77 + 78 78 + Sync settings stored in `extension_settings` table: 79 79 + - `sync.serverUrl` - Server URL 80 80 + - `sync.apiKey` - API key 81 81 + - `sync.lastSyncTime` - Last sync timestamp 82 82 + - `sync.autoSync` - Enable auto-sync 83 83 + 84 84 + ### Mobile 85 85 + 86 86 + Settings keys in Tauri: 87 87 + - `webhook_url` - Server URL 88 88 + - `webhook_api_key` - API key 89 89 + 90 90 + ## Known Limitations 91 91 + 92 92 + ### Deletes Not Synced (HIGH) 93 93 + 94 94 + Deleted items are local-only. Items may "resurrect" on other devices after sync. 95 95 + 96 96 + **Current behavior:** 97 97 + 1. Delete on desktop sets `deletedAt` locally 98 98 + 2. Deleted items excluded from push query 99 99 + 3. Server never learns about deletion 100 100 + 4. Other devices still see the item 101 101 + 102 102 + **Workaround:** Delete on all devices manually. 103 103 + 104 104 + ### Push Failures Not Retried (HIGH) 105 105 + 106 106 + Failed push operations are logged but not retried. After sync, `lastSyncTime` advances, so failed items won't be picked up on next sync. 107 107 + 108 108 + **Workaround:** Manually trigger sync if network issues occurred. 109 109 + 110 110 + ## Files 111 111 + 112 112 + - `backend/electron/sync.ts` - Desktop sync implementation 113 113 + - `backend/server/db.js` - Server database with sync support 114 114 + - `backend/tauri-mobile/src-tauri/src/commands/sync.rs` - Mobile sync 115 115 + - `notes/sync-edge-cases.md` - Detailed edge case documentation

+1 -1

extensions/README.md

reviewed

··· 228 228 229 229 ## Extension API 230 230 231 231 - Extensions access the Peek API via `window.app`. See `docs/PEEK-API.md` for the complete reference. 231 231 + Extensions access the Peek API via `window.app`. See `docs/api.md` for the complete reference. 232 232 233 233 Common APIs used by extensions: 234 234

notes/datastore-architecture.md notes/research/datastore-architecture.md

reviewed

notes/datastore-integration.md notes/research/datastore-integration.md

reviewed

notes/datastore-research.md notes/research/datastore-research.md

reviewed

notes/datastore-schema.md notes/research/datastore-schema.md

reviewed

notes/datastore.md notes/research/datastore.md

reviewed

-402

notes/development.md

reviewed

··· 1 1 - # Peek Development Guide 2 2 - 3 3 - ## Project Overview 4 4 - 5 5 - Peek is a web user agent application that provides alternative ways to interact with web pages through keyboard shortcuts, modal windows, and background scripts. It's designed as a concept preview exploring task-aligned interfaces for the web, moving beyond traditional tabbed browsers. 6 6 - 7 7 - **Multi-Backend Architecture**: Peek supports multiple backends (Electron, Tauri) that can coexist and sync data. The `app/` directory is **backend-agnostic** and must not contain backend-specific code. Backend-specific code lives in `backend/{electron,tauri}/`. 8 8 - 9 9 - ## Requirements 10 10 - 11 11 - - **Node.js 24+** - Required for both desktop (Electron 40) and server 12 12 - - Install via `nvm install 24` or download from nodejs.org 13 13 - 14 14 - ## Key Commands 15 15 - 16 16 - ### Development 17 17 - ```bash 18 18 - nvm use 24 # Ensure Node 24 is active 19 19 - yarn install # Install dependencies 20 20 - yarn debug # Run in development mode (with devtools) 21 21 - yarn start # Start normally 22 22 - yarn package # Package (output: out/mac-arm64/) 23 23 - yarn package:install # Package and install to /Applications (macOS) 24 24 - yarn make # Build distributable packages 25 25 - yarn npm audit # Check for security vulnerabilities 26 26 - 27 27 - # Tauri backend 28 28 - yarn tauri:dev # Run Tauri in development 29 29 - yarn tauri:build # Build Tauri for production 30 30 - yarn tauri:check # Check Tauri compiles 31 31 - yarn tauri:test # Run Tauri smoke tests (Rust) 32 32 - 33 33 - # Tauri Mobile (iOS/Android) 34 34 - yarn tauri:ios:dev # Run on iOS simulator 35 35 - yarn tauri:ios:build # Build for iOS 36 36 - yarn tauri:ios:xcode # Open Xcode project 37 37 - yarn tauri:android:dev # Run on Android emulator 38 38 - 39 39 - # Server (webhook API for mobile sync) 40 40 - yarn server:install # Install server dependencies 41 41 - yarn server:start # Run production server 42 42 - yarn server:dev # Run with hot reload 43 43 - yarn server:test # Run server tests 44 44 - yarn server:healthcheck # Verify server starts 45 45 - ``` 46 46 - 47 47 - ### Testing 48 48 - ```bash 49 49 - yarn test # Run all tests (headless) 50 50 - yarn test:electron # Run Electron tests only 51 51 - yarn test:visible # Run with visible windows 52 52 - yarn test:grep "pattern" # Run specific test by name 53 53 - ``` 54 54 - 55 55 - **Testing Policy**: When fixing bugs or adding features, always add tests to cover the change. Tests live in `tests/desktop/smoke.spec.ts`. 56 56 - 57 57 - ## Architecture Overview 58 58 - 59 59 - ### Core Structure 60 60 - 61 61 - 1. **Main Process** (`index.js`): 62 62 - - Manages app lifecycle, windows, shortcuts, IPC communication 63 63 - - Implements custom `peek://` protocol for internal navigation 64 64 - - Handles profile management and data persistence 65 65 - - Hosts the TinyBase datastore with IPC handlers for renderer access 66 66 - 67 67 - 2. **Renderer Process** (`app/`): 68 68 - - Core app logic loads from `peek://app/background.html` 69 69 - - Extension loader at `app/extensions/loader.js` 70 70 - - Feature modules: scripts, cmd (registered in `app/features.js`) 71 71 - - Built-in extensions: groups, peeks, slides (in `./extensions/`) 72 72 - - Settings UI at `peek://app/settings/settings.html` 73 73 - 74 74 - 3. **Peek API** (`window.app`): 75 75 - - `api.window.*` for window management 76 76 - - `api.shortcuts.*` for hotkeys (local by default, `{ global: true }` for OS-level) 77 77 - - `api.datastore.*` for data persistence 78 78 - - `api.commands.*` for command palette integration 79 79 - - `api.theme.*` for theme management 80 80 - - `api.publish()`/`api.subscribe()` for cross-window messaging 81 81 - 82 82 - ### Backend Structure 83 83 - ``` 84 84 - backend/ 85 85 - ├── electron/ # Electron desktop backend (current primary) 86 86 - │ ├── datastore.ts # SQLite via better-sqlite3 87 87 - │ ├── ipc.ts # IPC handlers 88 88 - │ └── protocol.ts # peek:// protocol handler 89 89 - ├── tauri/ # Tauri desktop backend (Rust) 90 90 - │ ├── src-tauri/ 91 91 - │ │ ├── src/ 92 92 - │ │ │ ├── lib.rs # App setup 93 93 - │ │ │ ├── datastore.rs # SQLite via rusqlite 94 94 - │ │ │ └── commands/ # IPC command handlers 95 95 - │ │ └── tests/smoke.rs # Rust smoke tests 96 96 - │ └── preload.js # Peek API implementation (Tauri) 97 97 - ├── tauri-mobile/ # Tauri mobile app (iOS/Android) 98 98 - │ ├── src/ # React frontend 99 99 - │ └── src-tauri/ # Rust backend 100 100 - └── server/ # Webhook API server for mobile sync 101 101 - ├── index.js # Hono HTTP server 102 102 - ├── db.js # SQLite via better-sqlite3 103 103 - └── users.js # Multi-user API key auth 104 104 - ``` 105 105 - 106 106 - **Data Sync**: Both backends use the same SQLite database path (`~/.config/Peek/{profile}/datastore.sqlite`). Only one backend should run at a time (file lock). 107 107 - 108 108 - ### Custom Protocol 109 109 - - `peek://app/...` - Core application files (from `app/` directory) 110 110 - - `peek://ext/{shortname}/...` - Extension files 111 111 - - `peek://tauri/...` - Tauri backend files (only in Tauri) 112 112 - 113 113 - ### Extensions Architecture 114 114 - 115 115 - Extensions run in isolated BrowserWindow processes at `peek://ext/{id}/background.html`. 116 116 - 117 117 - ``` 118 118 - extensions/ 119 119 - ├── example/ # Hello world example 120 120 - ├── groups/ 121 121 - ├── peeks/ 122 122 - └── slides/ 123 123 - ├── manifest.json # Extension metadata 124 124 - ├── settings-schema.json # Settings UI schema (optional) 125 125 - ├── background.html # Entry point 126 126 - └── background.js # Main logic (ES module export) 127 127 - ``` 128 128 - 129 129 - **Background script pattern:** 130 130 - ```javascript 131 131 - const api = window.app; 132 132 - 133 133 - const extension = { 134 134 - id: 'example', 135 135 - labels: { name: 'Example' }, 136 136 - 137 137 - init() { 138 138 - api.shortcuts.register('Option+x', handler, { global: true }); 139 139 - api.commands.register({ name: 'my-cmd', description: '...', execute: fn }); 140 140 - }, 141 141 - 142 142 - uninit() { 143 143 - api.shortcuts.unregister('Option+x', { global: true }); 144 144 - api.commands.unregister('my-cmd'); 145 145 - } 146 146 - }; 147 147 - 148 148 - export default extension; 149 149 - ``` 150 150 - 151 151 - ### Window Management 152 152 - - Windows identified by keys for lifecycle management (e.g., `peek:${address}`) 153 153 - - Modal windows use `type: 'panel'` to return focus to previous app on close 154 154 - - Parameters: `modal`, `keepLive`, `persistState`, `transparent`, `height`, `width`, `key` 155 155 - - "Escape IZUI" design - ESC key always returns to previous context 156 156 - 157 157 - ### Data Storage 158 158 - 159 159 - **Settings Storage (localStorage)**: 160 160 - - Profile-based data separation in `{userData}/{PROFILE}/` directory 161 161 - - Features use `openStore(id, defaults, clear)` utility from `app/utils.js` 162 162 - 163 163 - **Datastore (TinyBase)**: 164 164 - - In-memory TinyBase store for structured data 165 165 - - Runs in main process with IPC handlers for renderer access 166 166 - - Schema defined in `app/datastore/schema.js` 167 167 - - Tables: `addresses`, `visits`, `content`, `tags`, `blobs`, `scripts_data`, `feeds` 168 168 - 169 169 - **Profile Management**: 170 170 - - Packaged app uses `default` profile 171 171 - - Running from source (`yarn start`) uses `dev` profile 172 172 - - `PROFILE` env var overrides automatic detection 173 173 - 174 174 - ## Common Pitfalls 175 175 - 176 176 - 1. Don't use relative paths in peek:// URLs - use absolute paths 177 177 - 2. Remember to unregister shortcuts when features unload 178 178 - 3. Windows opened by features should be tracked and closed on unload 179 179 - 4. Modal windows require both `modal: true` and `type: 'panel'` 180 180 - 5. Window keys must be unique - use pattern like `peek:${address}` 181 181 - 6. Check if items are enabled (`item.enabled == true`) before registering shortcuts 182 182 - 7. Datastore API returns `{ success, data }` - always check `result.success` 183 183 - 8. Pubsub subscriptions are keyed by source - same source subscribing twice overwrites 184 184 - 9. **Never put backend-specific code in `app/`** 185 185 - 10. **Run `yarn install` after Electron upgrades** - Native modules (better-sqlite3) must be recompiled for the new Electron ABI. The postinstall script handles this automatically, but you must run `yarn install` to trigger it. System Node and Electron have different ABIs even at the same major version (e.g., Node 24 = ABI 137, Electron 40 = ABI 143). 186 186 - 187 187 - ## Code Style 188 188 - 189 189 - - ES6 modules throughout (type: "module" in package.json) 190 190 - - Async/await preferred over callbacks 191 191 - - Console logging for debugging (controlled by DEBUG env var) 192 192 - - No TypeScript in app/, pure JavaScript 193 193 - - Uses `nodemon` for hot reload during development 194 194 - 195 195 - ## Security Notes 196 196 - 197 197 - - This is a concept preview, NOT production-ready 198 198 - - No formal security audit performed 199 199 - - Different security model than traditional browsers 200 200 - - Be cautious with cross-origin access and custom APIs 201 201 - 202 202 - ## Mobile Development (Tauri iOS/Android) 203 203 - 204 204 - Mobile development uses the separate `peek-save` app in `backend/tauri-mobile/`. 205 205 - 206 206 - **CRITICAL - Build with Xcode GUI for iOS:** 207 207 - - NEVER run `xcodebuild` commands from terminal for final builds 208 208 - - Use Xcode GUI (Product → Build, Product → Run) for reliable builds 209 209 - 210 210 - **CRITICAL - Do NOT run `xcodegen generate`:** 211 211 - - The Xcode project has custom settings that xcodegen overwrites 212 212 - 213 213 - ### Quick Start (One Command) 214 214 - 215 215 - The easiest way to set up mobile development with sync testing: 216 216 - 217 217 - ```bash 218 218 - cd backend/tauri-mobile 219 219 - 220 220 - # First time: build both debug and release Rust libraries 221 221 - npm run build # Build frontend 222 222 - cd src-tauri 223 223 - cargo build --target aarch64-apple-ios-sim # Debug (simulator) 224 224 - cargo build --target aarch64-apple-ios --release # Release (device) 225 225 - cd .. 226 226 - 227 227 - # Start everything (servers, configure iOS, seed test data, open Xcode) 228 228 - npm run dev:ios 229 229 - ``` 230 230 - 231 231 - `npm run dev:ios` does all of this automatically: 232 232 - 1. Resets server data for a clean slate 233 233 - 2. Starts backend server on a random port (10000-19999) 234 234 - 3. Starts frontend dev server on port 1420 235 235 - 4. Configures iOS simulator with server URL and API key 236 236 - 5. Copies both debug and release Rust libraries 237 237 - 6. Opens Xcode 238 238 - 7. Seeds test data (3 items on server, 3 on iOS) 239 239 - 240 240 - ### Available npm Scripts 241 241 - 242 242 - ```bash 243 243 - # Development 244 244 - npm run dev:ios # Full dev setup (servers + config + seed + Xcode) 245 245 - npm run xcode # Just copy libraries and open Xcode 246 246 - npm run seed # Seed test data (needs SERVER_URL and API_KEY env vars) 247 247 - npm run reset:server # Delete server data directory 248 248 - 249 249 - # Building 250 250 - npm run build # Build frontend (tsc + vite) 251 251 - npm run build:ios # Build frontend + debug Rust library 252 252 - npm run build:ios:release # Build frontend + release Rust library 253 253 - 254 254 - # Testing 255 255 - npm run test # Run integration tests 256 256 - npm run test:verbose # Run tests with verbose output 257 257 - ``` 258 258 - 259 259 - ### iOS Build Process (Manual) 260 260 - 261 261 - If you need to build manually instead of using `npm run dev:ios`: 262 262 - 263 263 - ```bash 264 264 - # 1. Build frontend 265 265 - cd backend/tauri-mobile && npm install && npm run build 266 266 - 267 267 - # 2. Build debug library (for simulator) 268 268 - cd src-tauri 269 269 - cargo tauri build --target aarch64-apple-ios-sim --debug 270 270 - mkdir -p gen/apple/Externals/arm64/Debug 271 271 - cp target/aarch64-apple-ios-sim/debug/deps/libpeek_save_lib.a gen/apple/Externals/arm64/Debug/libapp.a 272 272 - 273 273 - # 3. Build release library (for device) 274 274 - cargo tauri build --target aarch64-apple-ios 275 275 - mkdir -p gen/apple/Externals/arm64/Release 276 276 - cp target/aarch64-apple-ios/release/deps/libpeek_save_lib.a gen/apple/Externals/arm64/Release/libapp.a 277 277 - 278 278 - # 4. Create assets symlink (if missing) 279 279 - ln -s ../../../dist gen/apple/assets 280 280 - 281 281 - # 5. Open Xcode and build from GUI 282 282 - open gen/apple/peek-save.xcodeproj 283 283 - ``` 284 284 - 285 285 - ### Testing Bidirectional Sync 286 286 - 287 287 - After running `npm run dev:ios`, test data is automatically seeded: 288 288 - 289 289 - **Server has 3 items:** 290 290 - - URL: https://github.com/from-server (tags: server, github) 291 291 - - URL: https://example.com/from-server-1 (tags: server, test) 292 292 - - Text: "This is a text note from the server" (tags: server, note) 293 293 - 294 294 - **iOS Simulator has 3 items:** 295 295 - - URL: https://mobile-only-1.example.com (tags: mobile, local) 296 296 - - URL: https://mobile-news.example.com (tags: local) 297 297 - - Text: "This text was created on mobile only" (tags: mobile) 298 298 - 299 299 - **To test:** 300 300 - 1. Build and run in Xcode (Cmd+R) 301 301 - 2. Go to Settings in the app 302 302 - 3. Settings should already be configured (server URL and API key) 303 303 - 4. Tap **Sync All** to pull and push 304 304 - 5. After sync, both server and iOS should have 6 items 305 305 - 306 306 - **Gotchas:** 307 307 - - The `gen/apple/assets` symlink must exist or Xcode fails with "No such file or directory" 308 308 - - Debug scheme = simulator, Release scheme = device 309 309 - - If Rust code changes, rebuild the library and copy again 310 310 - - The "Build Rust Code" pre-build script in Xcode can hang indefinitely - pre-building avoids this 311 311 - - iOS simulator can't reach `localhost` - use Mac's IP address (dev:ios handles this automatically) 312 312 - 313 313 - ## Server Backend (Webhook API) 314 314 - 315 315 - The server backend (`backend/server/`) is a remote HTTP API for syncing data from the mobile app. It's separate from the desktop backends - it doesn't implement the Peek API, it's a standalone Node.js server. 316 316 - 317 317 - ### Server Commands 318 318 - ```bash 319 319 - # From project root 320 320 - yarn server:install # Install dependencies (first time) 321 321 - yarn server:start # Run production server (port 3000) 322 322 - yarn server:dev # Run with hot reload 323 323 - yarn server:test # Run unit tests (92 tests) 324 324 - yarn server:healthcheck # Verify server starts and responds 325 325 - 326 326 - # From backend/server/ 327 327 - npm install 328 328 - npm start 329 329 - npm run dev 330 330 - npm test 331 331 - npm run test:api:local # Test against local server (needs PEEK_LOCAL_KEY) 332 332 - npm run test:api:prod # Test against production (needs PEEK_PROD_KEY, PEEK_PROD_URL) 333 333 - ``` 334 334 - 335 335 - ### Server Architecture 336 336 - - **Hono** - Lightweight HTTP framework (like Express but faster) 337 337 - - **better-sqlite3** - SQLite database (same as Electron backend) 338 338 - - **Multi-user** - Each user gets isolated database in `./data/{userId}/` 339 339 - - **API key auth** - Bearer token authentication, keys hashed with SHA-256 340 340 - 341 341 - ### Server API Endpoints 342 342 - All endpoints except `/` require `Authorization: Bearer <api_key>` header. 343 343 - 344 344 - | Endpoint | Method | Description | 345 345 - |----------|--------|-------------| 346 346 - | `/` | GET | Health check (public) | 347 347 - | `/webhook` | POST | Receive items from mobile (`{ urls, texts, tagsets }`) | 348 348 - | `/urls` | GET | List saved URLs | 349 349 - | `/urls/:id` | DELETE | Delete URL | 350 350 - | `/urls/:id/tags` | PATCH | Update URL tags | 351 351 - | `/texts` | GET/POST | List or create texts | 352 352 - | `/tagsets` | GET/POST | List or create tagsets | 353 353 - | `/images` | GET/POST | List or upload images | 354 354 - | `/images/:id` | GET/DELETE | Get or delete image | 355 355 - | `/items` | GET/POST | Unified endpoint (filter with `?type=`) | 356 356 - | `/tags` | GET | List tags by frecency | 357 357 - 358 358 - ### Server Deployment (Railway) 359 359 - 360 360 - > **For the comprehensive deployment guide**, see the "Railway Deployment (Peek Server)" section in `CLAUDE.md`. This includes step-by-step workflow, user management, production testing, and troubleshooting. 361 361 - 362 362 - The server is configured for Railway deployment. 363 363 - 364 364 - **Initial Setup:** 365 365 - 1. Connect Railway to `backend/server/` subdirectory 366 366 - 2. Attach a persistent volume, set `DATA_DIR` env var to mount path 367 367 - 3. Create users via the `users.js` module 368 368 - 369 369 - **Deploying Updates:** 370 370 - ```bash 371 371 - # Link to project (one-time, from backend/server/) 372 372 - railway link -p <project-name> -s <service-name> -e production 373 373 - 374 374 - # Always run tests first 375 375 - npm test 376 376 - 377 377 - # Deploy 378 378 - railway up -d 379 379 - 380 380 - # Check logs 381 381 - railway logs -n 50 382 382 - 383 383 - # Health check 384 384 - curl https://peek-node.up.railway.app/ 385 385 - ``` 386 386 - 387 387 - **Deployment Order (Server + Mobile):** 388 388 - 1. **Server first** - stateless, has auto-migrations that run on first request 389 389 - 2. **Mobile second** - works offline, adapts to server changes 390 390 - 3. One-way sync only: mobile → server (no pull/download sync yet) 391 391 - 392 392 - **Migration Gotcha:** 393 393 - When adding database columns via migration, ensure indexes on those columns are created AFTER the column migration runs, not in the initial CREATE TABLE statement. 394 394 - 395 395 - ### Server Database Schema 396 396 - Different from desktop datastore - optimized for mobile sync: 397 397 - - `items` - Unified table (type: url/text/tagset/image) 398 398 - - `tags` - Tag names with frecency scoring 399 399 - - `item_tags` - Many-to-many junction 400 400 - - `settings` - Key-value config 401 401 - 402 402 - Images stored on disk in `./data/{userId}/images/` with content-hash deduplication.

notes/sync-architecture.md notes/research/sync-architecture.md

reviewed

notes/sync-edge-cases.md notes/research/sync-edge-cases.md

reviewed