+22

CHANGELOG.md

reviewed

··· 13 13 14 14 Newly done items go here, grouped under level-2 headings by week (date = Monday of that ISO week). 15 15 16 16 + ## 2026-03-11 17 17 + 18 18 + Desktop - IZUI Navigation 19 19 + - [x] ESC at root opens Windows switcher — new `escUnhandledPolicy` second-phase policy for workspace windows in active/idle sessions 20 20 + - [x] Preserve role/escapeMode across session restore — fix canvas mode check to not depend on role 21 21 + 22 22 + Desktop - Editor 23 23 + - [x] Add img tag rendering in preview — sanitized HTML img tags with attribute allowlist and protocol security 24 24 + - [x] Support relative image paths and file:// protocol — resolve images relative to edited file via `peek://local-file/` protocol 25 25 + 26 26 + Desktop - Groups 27 27 + - [x] Restructure group detail view header — group name, edit icon, view mode buttons, and inline sort controls in compact layout 28 28 + - [x] Remove colored dot from group header 29 29 + 30 30 + Desktop - Shortcuts 31 31 + - [x] Change Pagestream shortcut from Cmd/Ctrl+P to Cmd/Ctrl+Shift+P (avoids conflict with Print) 32 32 + 33 33 + Desktop - Docs 34 34 + - [x] Update README — rewrite intro, add desktop screenshot, Core/Features/Keyboard Shortcuts/Feature API sections 35 35 + - [x] Rename extension terminology to features throughout docs and README 36 36 + - [x] Rename docs/extensions.md → features.md, extension-modes.md → feature-modes.md, extension-settings-api.md → feature-settings-api.md 37 37 + 16 38 ## 2026-03-09 17 39 18 40 Desktop - Extensions

+144 -260

README.md

reviewed

··· 14 14 15 15 <img width="969" alt="peek desktop screenshot" src="peek-desktop-screenshot.png"> 16 16 17 17 - ## Important notes 17 17 + ## WARNING! 18 18 19 19 ___PEEK IS NOT A BROWSER___ 20 20 21 21 - Peek is not a 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. 21 21 + Peek is not a 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. 22 22 23 23 ___PEEK IS A CONCEPT PREVIEW___ 24 24 ··· 30 30 31 31 - **IZUI Navigation** — Inverted Zooming User Interface. ESC-key-based navigation model that provides consistent "zoom out" behavior across all interfaces. Enter from anywhere, ESC to go back — predictable at every level. 32 32 - **Window Management** — Heterogeneous windowing: chromeless modals, overlays, slides, workspaces and content windows, each with role-specific behavior. 33 33 - - **Extension System** — All features are extensions with manifest-declared commands, shortcuts, and settings. Extensions can be eager, lazy-loaded, or fully declarative. 34 34 - - **PubSub Messaging** — Cross-window event system for communication between extensions and windows. 33 33 + - **Feature System** — Features are not extensions of a monolithic core — they *are* the functionality, built on a minimal foundation. Each feature declares its own commands, shortcuts, and settings. Features can be eager, lazy-loaded, or fully declarative. 34 34 + - **PubSub Messaging** — Cross-window event system for communication between features and windows. 35 35 - **Data Persistence** — SQLite datastore with schema management, history tracking, and cross-device sync support. 36 36 - **peek:// Protocol** — Custom protocol for internal navigation and cross-origin access. 37 37 - - **Settings** — Per-extension configuration with live reload. `Cmd/Ctrl+,` or tray icon. 37 37 + - **Settings** — Per-feature configuration with live reload. `Cmd/Ctrl+,` or tray icon. 38 38 39 39 ## Features 40 40 41 41 - - **Commands** — Graphical command palette (GCLI) for opening pages, executing commands, chaining outputs, and parameter entry. `Ctrl+Cmd+P` 42 42 - - **Groups** — Categorize, recall and interact with groups of pages. Tag-based with smart and curated grouping. `Ctrl+G` 43 43 - - **Peeks** — Keyboard-activated modal chromeless web pages for quickly glancing at or interacting with pages. `Opt+0-9` 44 44 - - **Slides** — Keyboard-activated modal chromeless web pages which slide in from any screen edge. `Opt+Arrow Keys` 45 45 - - **Editor** — Markdown editor with outline sidebar, live preview, and vim mode. `Ctrl+E` 41 41 + Peek uses the language of "features" over "extensions". "Extend" implies a larger core that you cannot change. Peek inverts that to small core, with as much changeable as possible. Peek features are modular - they are not *extending* core functionality, they *are* the functionality, built on a small-as-possible core. 42 42 + 43 43 + - **Commands** — Global-hotkey-activated graphical command bar (GCLI) for opening pages and features, executing commands, chaining commands. `Opt/Alt+space` (global) and Cmd/Ctrl+k (local) 44 44 + - **Groups** — Categorize, recall and interact with groups of pages. Groups are tags that've been "promoted" intentionally to a group. Groups are also an app-global "mode" (which isn't entirely implemented yet...) `Cmd/Ctrl+G` 45 45 + - **Peeks** — Global-hotkey-activated modal chromeless web pages for quickly glancing at or interacting with pages. `Opt+0-9` 46 46 + - **Slides** — Global-hotkey-activated modal chromeless web pages which slide in from any screen edge. `Opt+Arrow Keys` 47 47 + - **Editor** — Markdown editor with outline sidebar, live preview, vim mode and an *excellent* folding approach. `Cmd/Ctrl+E` 46 48 - **Search** — Search across all items by text and tags. 47 49 - **Tags** — Tag, untag, and browse items by tag. Tag visualization and management. 48 50 - **Tag Actions** — Define custom actions triggered by tags, enabling automated workflows. 49 51 - **Web Search** — Search the web with engine discovery — Google, DuckDuckGo, Kagi, Bing, Wikipedia, and more. 50 50 - - **Windows** — Full-screen window switcher overlay showing all open windows as cards. `Ctrl+Shift+W` 51 51 - - **Pagestream** — Chat-like vertical navigation interface for browsing history. `Ctrl+P` 52 52 + - **Windows** — Full-screen window switcher overlay showing all open windows as cards. `Cmd/Ctrl+Shift+W` 53 53 + - **Pagestream** — Chat-like vertical navigation interface for browsing history and opening and viewing pages. `Cmd/Ctrl+Shift+P` 52 54 - **Entities** — Automatic extraction of people, places, organizations, and events from visited pages. 53 55 - **Scripts** — Periodically execute scripts against web pages in the background to extract data, with change notifications. 54 56 - **Files** — Open local files, CSV conversion, markdown formatting, save operations. 55 57 - **Feeds** — RSS/Atom feed reader. 56 56 - - **Lex** — Lexicon Studio: AT Protocol identity and data browser/editor. 57 57 - - **Sheets** — Widget sheets with freeform card layouts hosting webviews. 58 58 + - **Lexicon Studio** — Lexicon Studio: AT Protocol identity and data browser/editor. 59 59 + - **Widget Sheets** — Widget sheets with freeform card layouts hosting webviews. 58 60 - **Timers** — Countdown timers, alarms, stopwatches, and interval timers. 59 61 - **Sync** — Cross-device synchronization of items, tags, and groups. 60 62 - **HUD** — Always-on-top heads-up display showing current state and mode. `Ctrl+H` ··· 63 65 - "native" web apps — using Peek as a way to "install" web pages on the local device as separate applications 64 66 - "Peeklets" HUD — select parts of pages to add to a collection rendered as an overlay 65 67 68 68 + ## Keyboard Shortcuts 69 69 + 70 70 + ### Global (work from any application) 71 71 + 72 72 + | Shortcut | Action | 73 73 + |----------|--------| 74 74 + | `Opt+Space` | Open command bar | 75 75 + | `Opt+0-9` | Open Peeks (configurable, not all registered by default — configure in settings) | 76 76 + | `Opt+Arrow Keys` | Open Slides (configurable, not all registered by default — configure in settings) | 77 77 + 78 78 + ### Application 79 79 + 80 80 + | Shortcut | Action | 81 81 + |----------|--------| 82 82 + | `ESC` | IZUI navigation — zoom out, go back, close dialogs. At root, opens Windows switcher. Also closes windows depending on role and session state. | 83 83 + | `Cmd/Ctrl+K` | Open command bar (within app) | 84 84 + | `Cmd/Ctrl+L` | Command bar URL mode | 85 85 + | `Cmd/Ctrl+G` | Groups | 86 86 + | `Cmd/Ctrl+E` | Editor | 87 87 + | `Cmd/Ctrl+H` | HUD | 88 88 + | `Cmd/Ctrl+Shift+P` | Pagestream | 89 89 + | `Cmd/Ctrl+Shift+W` | Windows switcher | 90 90 + | `Cmd/Ctrl+Shift+F` | Lists search | 91 91 + | `Cmd/Ctrl+Shift+T` | Undo close window (works for all window types) | 92 92 + | `Cmd/Ctrl+W` | Close window | 93 93 + | `Cmd/Ctrl+,` | Settings | 94 94 + | `Cmd/Ctrl+Q` | Quit | 95 95 + 96 96 + ### Web Page Navigation 97 97 + 98 98 + | Shortcut | Action | 99 99 + |----------|--------| 100 100 + | `Cmd/Ctrl+L` | Focus URL bar | 101 101 + | `Cmd/Ctrl+R` | Reload page | 102 102 + | `Cmd+[` / `Cmd+Left` | Go back | 103 103 + | `Cmd+]` / `Cmd+Right` | Go forward | 104 104 + 66 105 ## Design 67 106 107 107 + Some thoughts driving the design of Peek 108 108 + 109 109 + Core 110 110 + - Feels like home: trust, comfort, control 111 111 + - Continuous instances of magical mind-reading 112 112 + - Sleep at night because no idea or anything you saw is ever lost 113 113 + - Create, save, classify at the speed of thought 114 114 + 115 115 + What makes a home / kitchen / workshop 116 116 + - Everything is right where you need it, b/c you control what is where 117 117 + - When you know what is where, you can make things with less frustration 118 118 + - You generally know what’s happening - who’s around/coming/going, etc, not too much surpri 119 119 + 120 120 + What makes magical mind-readingness 121 121 + - Frecency everywhere all of the time 122 122 + - User actions are training data for sorting 123 123 + - The thing you were thinking of is already at the top of the list 124 124 + 125 125 + What makes awareness 126 126 + - Actions tracked at the core 127 127 + - Metrics generated, rollups displayed, synthesis emergent 128 128 + - Task context with you at the center (vs asking a companion robot - disempowering!) 129 129 + 130 130 + Synthesis 131 131 + - Frecency + adaptive matching gives experience/feeling of magical mind-readingness 132 132 + - Ability to customize/create/generate interfaces gives the comfort of home 133 133 + 134 134 + The rules 135 135 + - Files > arcane/opaque boxes/formats 136 136 + - Metadata can be weird non-file, as long as consistent 137 137 + - External systems require consent to touch my stuff 138 138 + 139 139 + Key capabilities from action/application history chain + addressibility 140 140 + - Record/replay 141 141 + - State feedback loops 142 142 + - Observability 143 143 + 144 144 + Interface spectrum 145 145 + - Consistent predicable interfaces are easy, off-the-shelf 146 146 + - Weird/generative possible via power trio: backgrounding, wm apis, web surface 147 147 + 148 148 + Difference from browsers 149 149 + - Web user agents should be bounded by the user, not browser vendor business models 150 150 + - 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 151 151 + - Security user interface must be a clear articulation of risks and trade-offs, and users should own the decisions 152 152 + 153 153 + ### Task alignment 154 154 + 68 155 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. 69 156 70 157 Characteristics of how we use the web, that are not addressed in contemporary web browsers: ··· 74 161 - persistent 75 162 - data-centric 76 163 - archival / evidential 77 77 - 78 78 - Some thoughts driving the design of Peek: 79 79 - 80 80 - - Web user agents should be bounded by the user, not browser vendor business models 81 81 - - 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 82 82 - - Security user interface must be a clear articulation of risks and trade-offs, and users should own the decisions 83 164 84 165 ### Escape IZUI 85 166 ··· 117 198 - I'd like to have a decentralized compute option for running your scripts outside of your clients and syncing the data 118 199 - Want cloud storage for all config and data, esp infinite history, so can do fun things with it 119 200 120 120 - ### Feature extensibility 201 201 + ### Feature architecture 121 202 122 122 - An extensibility model for achieving "personal web workbench" requires a few things: 123 123 - - UI extensibility requires OS-level window features beyond what the web allows today (also a baby step towards a minimal OS user interface) 203 203 + Peek inverts the traditional browser model. Instead of a large monolithic core with an extension API bolted on, Peek has a minimal core with features that *are* the functionality. Features are not extending something — they are the thing. 204 204 + 205 205 + A modular feature system for achieving "personal web workbench" requires a few things: 206 206 + - UI modularity requires OS-level window capabilities beyond what the web allows today (also a baby step towards a minimal OS user interface) 124 207 - 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 125 125 - - Portable ways of accessing network, storage and compute, which address 208 208 + - Portable ways of accessing network, storage and compute 126 209 127 127 - The current implementation has only a few sketches of that world implemented, and has gone through a few iterations: 128 128 - - first proof of concept was all Electron - so, privileged JS 210 210 + The current implementation has gone through a few iterations: 211 211 + - first proof of concept was all Electron — privileged JS 129 212 - 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 130 213 - third and current implementation bundles all features into one web app, with access to smallest possible custom API for platform-level capabilities 131 214 132 132 - 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. 215 215 + Features are loaded into the custom `peek` scheme, which provides access to a few special APIs noted in the next section, allows cross-origin network access and other things. 133 216 134 134 - This is not ideal, as the extensibility vector is contributions to core, which too tightly bounds experimentation and innovation. 217 217 + The API surface area is small and portable — features built on it could run in other environments with minimal adaptation. 135 218 136 136 - However it's pretty portable given the small custom API surface area. 219 219 + ### Feature API 137 220 138 138 - 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. 221 221 + Features are web apps running in the `peek://` scheme. The question driving the API design: what's the minimum capability set a web app needs to build these features? 139 222 140 140 - ### Peek API 223 223 + The API is exposed as `window.app` in the feature's execution context: 141 224 142 142 - Initially the prototype was all Electron. But that's not interesting, and doesn't 143 143 - really tell us anything about constraints of the web itself. 225 225 + - **Windows** — open, close, modify, and track windows with role-based behavior 226 226 + - **Shortcuts** — register global and local keyboard shortcuts 227 227 + - **PubSub** — publish and subscribe to messages across features and windows, with scoping (self, global, window) 228 228 + - **Commands** — register commands for the command bar, with parameter modes and chaining 229 229 + - **Datastore** — SQLite-backed persistent storage with schema management 230 230 + - **Escape** — register ESC key handlers for IZUI navigation 231 231 + - **IZUI** — query and interact with the navigation state machine 232 232 + - **Files** — open/save dialogs, read/write by path 233 233 + - **Settings** — per-feature preferences with schema validation 234 234 + - **Themes** — access current theme, dark mode state 235 235 + - **Sync** — cross-device synchronization 236 236 + - **Profiles** — user identity and profile management 237 237 + - **Net** — network requests (fetch with cross-origin access) 238 238 + - **Session** — session state and restore 144 239 145 145 - So instead I asked this question: What's the minimum capability set that a web app would 146 146 - need to build the features I need? 147 147 - 148 148 - The answer, so far, is giving `peek` apps the following APIs: 149 149 - 150 150 - - window open/close 151 151 - - global hotkey registration 152 152 - - pubsub messaging 153 153 - 154 154 - Custom window api might be able to away entirely, by passing window.open features, working on that. 240 240 + The API surface is intentionally small and portable — features built on it could run in other environments with minimal adaptation. See [docs/api.md](docs/api.md) for the full reference. 155 241 156 242 ### Desktop App 157 243 ··· 167 253 168 254 ## Contribution 169 255 170 170 - - in proto stage 171 171 - - all dragons, no promises 172 172 - 173 173 - ## Development 174 174 - 175 175 - ``` 176 176 - yarn install 177 177 - yarn debug 178 178 - ``` 179 179 - 180 180 - ### Mobile 181 181 - 182 182 - - Quick access to Script output and manual runs, as widgets (or output from cloud runners?) 183 183 - - Peeks still totes useful here - on mobile is more like "quick dial" features 184 184 - 185 185 - ### Cloud 186 186 - 187 187 - - Going full crypto payments for distributed compute on this one. 188 188 - 189 189 - ## Papercut / use-case log 190 190 - 191 191 - Core high level actions 192 192 - - open a web page on top/bottom/left/right 193 193 - - keep web pages persistent in the background 194 194 - - quickly open a web page modally, and close it 195 195 - 196 196 - Misc specific 197 197 - - open bandcamp in a window, move over to 2nd display, accidently close it while moving around between other windows 198 198 - - recent books or recipes from newsletters i subscribe to (but probably didn't read) 199 199 - - extract a table from a page periodically, send it somewhere as csv or whatever (chained actions) 200 200 - - collect microformats, metadata, events 201 201 - - web page w/ some locations as an input to a map (creates overlay) "map this page" 202 202 - - be able to see where a book/etc recommendation came from 203 203 - - save a tweet, with URL / image / relevant text, but not whole page webrecorder style 204 204 - - "watch local event listings, rate against my music listening patterns and send me shows i might be interested in going to" 205 205 - 206 206 - Content scripts 207 207 - - extract+log shazams 208 208 - - extract+log spotify playlist 209 209 - 210 210 - Calculators (variant of script + cmd?) 211 211 - - page -> table 212 212 - - page -> summary 213 213 - - page -> microsummaries 214 214 - - page -> dates 215 215 - - page -> events 216 216 - 217 217 - Workflow deconstructing a "why" task flavour of bookmarking 218 218 - - save https://www.criterionchannel.com/hong-kong-in-new-york 219 219 - - extract the movies 220 220 - - get reference metadata for each (?!) 221 221 - - add to "to watch list", with pointer back to source url 222 222 - 223 223 - ## Groups 224 224 - 225 225 - - panorama/tabcandy-ish 226 226 - - all browser history 227 227 - - smart groups vs curated groups 228 228 - - autoclustering on topic/date 229 229 - - escape from a new page enters default group? 230 230 - 231 231 - Groups + Cmds 232 232 - - top/bottom inputs for filtering/grouping/etc 233 233 - - implemented is a cmd input? 234 234 - - cmds for opening/searching/finding/viewing/filtering/piping 235 235 - - cmds for moving pages into groups 236 236 - - groups -> {x} (eg export/pipe) could depend on the chaining/piping bit (see below) 237 237 - 238 238 - Architecture 239 239 - - internally is tags? 240 240 - - static vs dynamic groups tho? 241 241 - 242 242 - Publishing 243 243 - - publishing groups as internal/public feeds? 244 244 - - to pinboard? 245 245 - 246 246 - ## History view/search 247 247 - 248 248 - A lot of groups work depends on history being in place, and being accessable and annotate-able. 249 249 - 250 250 - ideally use chromium history 251 251 - 252 252 - storage+access 253 253 - - check out Agregore history viewing approach 254 254 - - check out state of electron+webext 255 255 - - other way of accessing underlying chromium history? 256 256 - 257 257 - features 258 258 - - awesomebar algo scoring 259 259 - - adaptive matching 260 260 - 261 261 - ## Chaining / piping 262 262 - 263 263 - investigate: vague thought re chaining: 264 264 - - dynamic interstitial representations 265 265 - - mime type detection? 266 266 - - eg image previews 267 267 - - or a table of data 268 268 - - previews of cmds? 269 269 - 270 270 - interfaces 271 271 - - horizontal vs vertical chains 272 272 - - back/forward navigation? 273 273 - - each step is a cmd+preview? 274 274 - - dynamic cmd+previews? 275 275 - 276 276 - import/export/undo/redo 277 277 - - record/replay? 278 278 - - save a chain as a compound action (cmd)? 279 279 - 280 280 - architecture 281 281 - - look at web actions/intents/applets 282 282 - - xml pipeline language 256 256 + - In proto stage 257 257 + - All dragons, no promises 283 258 284 259 ## Mobile 285 260 286 286 - - some of the features don't make sense as-is on mobile 287 287 - - but maybe quick access on mobile to slides/peeks would be nice 288 288 - - and seeing output of content scripts, or ability to re-run locally on demand 289 289 - - needs some sync facility (inevitable anyway) 290 290 - 291 291 - ## Use-cases 292 292 - 293 293 - Peeks 294 294 - - translate 295 295 - - calendar 296 296 - - ai chat 297 297 - - currency conversion 298 298 - - everytimezone 299 299 - - tldraw 300 300 - 301 301 - Slides 302 302 - - music: Soundcloud, Hypem 303 303 - - stock prices 304 304 - - notepad 305 305 - - todo list 261 261 + There's a LOT already done here and I haven't even begun to describe it yet. 306 262 307 307 - Scripts 308 308 - - weather change, eg upcoming weather 309 309 - - crypto prices 263 263 + ## Server/Cloud 310 264 311 311 - Cmd - web 312 312 - - open url 313 313 - - web search 314 314 - - image search 315 315 - - conversions? 316 316 - - ddg !actions 265 265 + Server component is a very passive sync+store service right now. 317 266 318 318 - Cmd - system 319 319 - - search browser history 320 320 - - set peeks/slides 321 321 - - open settings 322 322 - - restart app 323 323 - - llm prompts 324 324 - 325 325 - Future 326 326 - - address something to switch between 327 327 - - pipe from/to? 328 328 - 329 329 - Publishing high level 330 330 - - author web content 331 331 - - pull in bits from the web 332 332 - - share preview for feedback 333 333 - - publish (or at least get output) 334 334 - 335 335 - Publishing examples 336 336 - - writing an event recap 337 337 - 338 338 - Publishing: event recap post 339 339 - - make a new markdown doc 340 340 - - sections titled for each video title 341 341 - - each video's embed code in each section 342 342 - - navigate around the document for review and updates 343 343 - - need to easily preview rendered content 344 344 - - share preview link 345 345 - - publish (somewhere?) 346 346 - 347 347 - Music 348 348 - - commands 349 349 - - views 350 350 - - last.fm of my own, to POSSE out 351 351 - 352 352 - ## Unfiled 353 353 - 354 354 - markdown hot reload previewer w/ toc 355 355 - - markdown support, with sidebar nav 356 356 - - reader mode 357 357 - - hot reload for file:// (other?) 358 358 - - add side-by-side view 359 359 - - once md and side-by-side, add side-by-side so the md is the nav, content is the preview 360 360 - - what's the cmd chain for this? 361 361 - 362 362 - content types + chaining 363 363 - - cmd: view as… table, feed, markdown, data points, named entities 364 364 - - chain: static archive, publish, save, share (os), mailto 365 365 - - cmd params, eg {url}, which can themselves autocomplete (eg history) 366 366 - 367 367 - multiprotocol 368 368 - - at 369 369 - - ipfs/ipns 370 370 - - pragmatic addressing+rendering for data (r/d/masl + mime handlers) 371 371 - 372 372 - broader patterns (chatting w/ luke) 373 373 - - why do we have to copy/paste? 374 374 - - devtools and ide are divorced 375 375 - 376 376 - chainframe/framechain 377 377 - - (web intents/applets/actions) + (webxdc/miniapps/tiles/farcasterframes) 378 378 - 379 379 - Small examples of agency 380 380 - 381 381 - - users can move, resize, change things to their requirements 382 382 - - eg, browsers restrict min-height of a window, but i should be able make as short as i like 267 267 + Runs on Railway, I use it daily with few problems (that I know of). 383 268 384 269 ## History 385 270 ··· 408 293 409 294 --- 410 295 411 411 - ## Automated Summary 412 412 - 413 413 - Quick reference for developers. 296 296 + ## Automated Summary (somewhat outdated, but some correct stuff too) 414 297 415 415 - ### Quick Start 298 298 + ### Developer Quick Start 416 299 417 300 ```bash 418 301 # Requirements: Node.js 24+ ··· 423 306 yarn debug # Development mode with devtools 424 307 yarn start # Normal mode 425 308 ``` 309 309 + Look at package.json for a long list of commands for each of the back-ends and testing. 426 310 427 311 See [DEVELOPMENT.md](DEVELOPMENT.md) for full development guide. 428 312 ··· 433 317 ``` 434 318 peek/ 435 319 ├── app/ # Renderer (backend-agnostic) 436 436 - ├── features/ # Built-in extensions 320 320 + ├── features/ # Built-in features 437 321 ├── backend/ 438 322 │ ├── electron/ # Desktop (primary) 439 323 │ ├── tauri/ # Desktop (Rust alternative) ··· 448 332 |-----|-------------| 449 333 | [DEVELOPMENT.md](DEVELOPMENT.md) | Development setup, commands, architecture | 450 334 | [docs/api.md](docs/api.md) | Peek API reference (`window.app`) | 451 451 - | [docs/extensions.md](docs/extensions.md) | Extension development | 452 452 - | [docs/cmd.md](docs/cmd.md) | Command palette extension | 335 335 + | [docs/features.md](docs/features.md) | Feature development | 336 336 + | [docs/cmd.md](docs/cmd.md) | Command palette feature | 453 337 | [docs/themes.md](docs/themes.md) | Theme system | 454 338 | [docs/datastore.md](docs/datastore.md) | Data storage and schema | 455 339 | [docs/sync.md](docs/sync.md) | Cross-device sync | ··· 474 358 | **Mobile (JS)** | Script-style | 9 | `yarn test:mobile` | 475 359 | **Mobile (Rust)** | `cargo test` | 19 | In `backend/tauri-mobile/` | 476 360 | **Tauri Desktop (Rust)** | `cargo test` | 16 | `yarn test:tauri:rust` | 477 477 - | **Lex Extension** | Node `--test` | 38 | `node --test features/lex/tests/` | 361 361 + | **Lex** | Node `--test` | 38 | `node --test features/lex/tests/` | 478 362 479 363 **Electron Unit (TS)** — Backend logic: entities extraction, session management, IZUI state, cmd palette logic, cmd chaining, OAuth bridge, display watcher, noun registry, shortcuts, datastore, completers, tag affordances, page loading. 480 364 ··· 492 376 493 377 **Server** — Sync server: API endpoints, backup, migration. 494 378 495 495 - **Schema Fidelity** — Validates schema consistency across desktop, mobile, server, and extension datastores. 379 379 + **Schema Fidelity** — Validates schema consistency across desktop, mobile, server, and browser extension datastores. 496 380 497 381 **Sync Integration** — Cross-device sync: integration tests, E2E tests, three-way merge, version compatibility. 498 382 499 499 - **Lex Extension** — Lexicon extension: UI logic and background processing. 383 383 + **Lex** — Lexicon feature: UI logic and background processing. 500 384 501 385 Background test commands: `yarn test:electron:bg` runs Playwright headless in background (logs to `/tmp/test-electron.log`). 502 386

docs/extension-modes.md docs/feature-modes.md

reviewed

docs/extension-settings-api.md docs/feature-settings-api.md

reviewed

docs/extensions.md docs/features.md

reviewed

+26 -1

docs/feed.xml

reviewed

··· 4 4 <title>Peek Changelog</title> 5 5 <link>https://tangled.org/burrito.space/peek</link> 6 6 <description>Recent changes to Peek</description> 7 7 - <lastBuildDate>Mon, 09 Mar 2026 22:56:45 GMT</lastBuildDate> 7 7 + <lastBuildDate>Wed, 11 Mar 2026 21:43:58 GMT</lastBuildDate> 8 8 <generator>changelog-to-rss.js</generator> 9 9 <atom:link href="https://tangled.org/burrito.space/peek/raw/main/docs/feed.xml" rel="self" type="application/rss+xml"/> 10 10 + <item> 11 11 + <title>2026-03-11</title> 12 12 + <link>https://tangled.org/burrito.space/peek/blob/main/CHANGELOG.md#2026-03-11</link> 13 13 + <guid isPermaLink="false">https://tangled.org/burrito.space/peek#2026-03-11</guid> 14 14 + <pubDate>Wed, 11 Mar 2026 12:00:00 GMT</pubDate> 15 15 + <description>Desktop - IZUI Navigation 16 16 + - ESC at root opens Windows switcher — new escUnhandledPolicy second-phase policy for workspace windows in active/idle sessions 17 17 + - Preserve role/escapeMode across session restore — fix canvas mode check to not depend on role 18 18 + 19 19 + Desktop - Editor 20 20 + - Add img tag rendering in preview — sanitized HTML img tags with attribute allowlist and protocol security 21 21 + - Support relative image paths and file:// protocol — resolve images relative to edited file via peek://local-file/ protocol 22 22 + 23 23 + Desktop - Groups 24 24 + - Restructure group detail view header — group name, edit icon, view mode buttons, and inline sort controls in compact layout 25 25 + - Remove colored dot from group header 26 26 + 27 27 + Desktop - Shortcuts 28 28 + - Change Pagestream shortcut from Cmd/Ctrl+P to Cmd/Ctrl+Shift+P (avoids conflict with Print) 29 29 + 30 30 + Desktop - Docs 31 31 + - Update README — rewrite intro, add desktop screenshot, Core/Features/Keyboard Shortcuts/Feature API sections 32 32 + - Rename extension terminology to features throughout docs and README 33 33 + - Rename docs/extensions.md → features.md, extension-modes.md → feature-modes.md, extension-settings-api.md → feature-settings-api.md</description> 34 34 + </item> 10 35 <item> 11 36 <title>2026-03-09</title> 12 37 <link>https://tangled.org/burrito.space/peek/blob/main/CHANGELOG.md#2026-03-09</link>

+1 -1

features/pagestream/manifest.json

reviewed

··· 15 15 ], 16 16 "shortcuts": [ 17 17 { 18 18 - "keys": "CommandOrControl+P", 18 18 + "keys": "CommandOrControl+Shift+P", 19 19 "command": "pagestream" 20 20 } 21 21 ]

+195 -172

peek-todo.md

reviewed

··· 1 1 # Peek TODO 2 2 3 3 - ## How we work 4 4 - 5 5 - - We track pending items in this file 6 6 - - In-progress work and current focus goes in WIP.md 7 7 - - Completed items go in CHANGELOG.md, grouped by week 8 8 - - This file is not for notes or description - link to documents in ./notes for that 9 9 - - Checkbox states: `- [ ]` pending, `- [~]` in-progress (move to WIP.md), `- [x]` done (move to CHANGELOG.md) 10 10 - 11 11 - ## Design principles / capabilities / etc 12 12 - 13 13 - core 14 14 - - feels like home: trust, comfort, control 15 15 - - continuous instances of magical mind-reading 16 16 - - sleep at night because no idea or anything you saw is ever lost 17 17 - - create, save, classify at the speed of thought 18 18 - 19 19 - what makes a home / kitchen / workshop 20 20 - - everything is right where you need it, b/c you control what is where 21 21 - - when you know what is where, you can make things with less frustration 22 22 - - you generally know what’s happening - who’s around/coming/going, etc, not too much surprise (but some!) 23 23 - 24 24 - what makes magical mind-readingness 25 25 - - frecency everywhere all of the time 26 26 - - user actions are training data for sorting 27 27 - - the thing you were thinking of is already at the top of the list 28 28 - 29 29 - what makes awareness 30 30 - - actions tracked at the core 31 31 - - metrics generated, rollups displayed, synthesis emergent 32 32 - - task context with you at the center (vs asking a companion robot - disempowering!) 33 33 - 34 34 - synthesis 35 35 - - frecency + adaptive matching gives experience/feeling of magical mind-readingness 36 36 - - ability to customize/create/generate interfaces gives the comfort of home 37 37 - 38 38 - the rules 39 39 - - files > arcane/opaque boxes/formats 40 40 - - metadata can be weird non-file, as long as consistent 41 41 - - external systems require consent to touch my stuff (eg http caching rules) 42 42 - 43 43 - key capabilities from action/application history chain + addressibility 44 44 - 45 45 - - record/replay 46 46 - - state feedback loops 47 47 - - observability 48 48 - 49 49 - interface spectrum 50 50 - - consistent predicable interfaces are easy, off-the-shelf 51 51 - - weird/generative possible via power trio: backgrounding, wm apis, web surface 52 52 - 53 53 - cf 54 54 - - bulthaup - german kitchen maker w/ designs based on carpentry workshops 55 55 - 56 3 ## Unfiled 57 4 58 5 context ··· 78 25 - may require connector/parameter context for each peek address load and connector invocation in a chained command 79 26 80 27 - peeks/slides as addresses + metadata? or urls? eg open({json of peek url + context}) => localhost in left slide, or peek://slide?where=top&url=http://localhost? both? opens up the idea of packaging these declaratively, and no-code createable 81 81 - 82 82 - ## UI Componentry 83 83 - 84 84 - Right now we're replicating/forking html and js across extensions. 85 85 - 86 86 - problems 87 87 - - messy, error prone, poor DRY practice 88 88 - - also means we can't generatively and rapidly build out UIs without whole new piles of html/js/css to manage 89 89 - 90 90 - What it is 91 91 - - flexible / reusable system at the ./app layer 92 92 - - extensions use for creating/generating interfaces 93 93 - - can override/overlay/inject styling 94 94 - - easy to make system-consistent ux and themed visual design 95 95 - - loosely coupled system with deterministic management 96 96 - - like a set of prebuilt controls 97 97 - - designed for single-component, or sets 98 98 - - binds to data source, is reactive to it (events, event-sources, streams, our feed system) 99 99 - 100 100 - what it isn't 101 101 - - designed for complex document hierarchies 102 102 - - js components React-style 103 103 - 104 104 - usage 105 105 - - callers instanciate a control 106 106 - - provide schema/data into a control which has a default template 107 107 - - template can be replaced by caller 108 108 - 109 109 - examples/use-cases 110 110 - - groups, tag ui and windows viewer are all card grids 111 111 - - chaining is command components + card popups with lists, editors, previews, etc 112 112 - - after atproto support, this could be used to bind lexicons + data for generated viewing/CRUD interfaces. 113 113 - - see the Window templates section of this file 114 114 - - see the Pagestream section of this file 115 115 - - see the Chaining section of this file 116 116 - - see the Notes/Editor section of this file 117 117 - - see the Web page experience section of this file 118 118 - - see the Unfiled section of this file 119 119 - - see the Commands section of this file 120 120 - 121 121 - implementation 122 122 - - use https://open-ui.org/ as much as possible, should cover a lot, eg, buttons, card/grid, cmd, carousels 123 123 - - see ~/sync/Sites/base for experiments w/ hud etc 124 124 - 125 125 - reactive schema+card+data system 126 126 - - [ ] cards + json schema + data 127 127 - - [ ] no hierarchy, just single component to start, renders to markup 128 128 - - [ ] instantiatable with data 129 129 - - [ ] receive updates to refresh 130 130 - 131 131 - integration 132 132 - - [ ] determine how extensions will import from core 133 133 - - [ ] determine how consumers will apply styles 134 134 - - [ ] explore node reuse/recycle approaches 135 135 - 136 136 - ui 137 137 - - [ ] button 138 138 - - [ ] button set (eg for tag boards/sets) 139 139 - - [ ] card 140 140 - - [ ] list 141 141 - - [ ] grid 142 142 - - [ ] vertical carousel of cards (like a chat view w/ interactable focus card) 143 143 - - [ ] horizontal carousel of cards (eg for command chaining, day ribbons) 144 144 - - [ ] image viewer 145 145 - - [ ] command input 146 146 - - [ ] command suggestion 147 147 - - [ ] command preview pane 148 148 - - [ ] search/filters on enumerable items (list, grid) 149 149 - - [ ] editor 150 150 - - [ ] column/columns 151 151 - 152 152 - initial porting 153 153 - - [ ] groups -> card/cards 154 154 - - [ ] tags -> card/cards 155 155 - - [ ] tag sets -> button set 156 156 - - [ ] cmd -> command input/suggestions 157 157 - - [ ] cmd chaining -> horizontal carousel, list 158 158 - 159 159 - popup carousel system 160 160 - - [ ] horizontal and vertical carousel components 161 161 - - [ ] see ~/sync/Sites/base/hud.html/css/js for basic ui system 162 162 - - [ ] active item focused in popup 163 163 - - [ ] arrow controls and vim directionals 164 164 - - [ ] port cmd chaining to horizontal carousel popups 165 165 - - [ ] port cmd previews to vertical carousel popups 166 166 - 167 167 - button sets 168 168 - - [ ] set of buttons 169 169 - - [ ] up/depressed states 170 170 - - [ ] x endcap option 171 171 - 172 172 - tags 173 173 - - [ ] all built on buttons and button sets 174 174 - - [ ] tag input field 175 175 - - [ ] combo of selected tags, input w/ filtering search, available tags 176 176 - 177 177 - ## Web page experience (reviewme: partially done) 178 178 - 179 179 - Page loading core 180 180 - - [ ] how to load pages - raw browserwindow (what we do now), webview in a default transparent page that hosts overlay?? 181 181 - - [ ] overlay infrastructure for showing metadata, security info 182 182 - - [ ] interaction with cmd actions (page mode again?) 183 183 - 184 184 - Basic nav etc 185 185 - - [ ] hotkey to select url 186 186 - - [ ] back/forward 187 187 - - [ ] reload 188 188 - - [ ] undo last close 189 189 - - [ ] if url selected in cmd is open in a window already, switch to it (for now) 190 190 - 191 191 - Page info/metadata/action widgets (depends on window templates maybe?) 192 192 - - [ ] defaults, eg sec ui 193 193 - - [ ] metadata (og, whatnot) 194 194 - - [ ] media (imgs, rss, etc) 195 195 - - [ ] actions (new extension cmd type?) 196 196 - - [ ] scripts (tbd) 197 197 - 198 198 - Titlebar 199 199 - - [x] show titlebar on hover at top edge of window for all pages 200 28 201 29 ## Feeds, time-series data 202 30 ··· 701 529 desktop 702 530 - [ ] Tray work 703 531 532 532 + ## Papercut / use-case log 533 533 + 534 534 + Core high level actions 535 535 + - open a web page on top/bottom/left/right 536 536 + - keep web pages persistent in the background 537 537 + - quickly open a web page modally, and close it 538 538 + 539 539 + Misc specific 540 540 + - open bandcamp in a window, move over to 2nd display, accidently close it while moving around between other windows 541 541 + - recent books or recipes from newsletters i subscribe to (but probably didn't read) 542 542 + - extract a table from a page periodically, send it somewhere as csv or whatever (chained actions) 543 543 + - collect microformats, metadata, events 544 544 + - web page w/ some locations as an input to a map (creates overlay) "map this page" 545 545 + - be able to see where a book/etc recommendation came from 546 546 + - save a tweet, with URL / image / relevant text, but not whole page webrecorder style 547 547 + - "watch local event listings, rate against my music listening patterns and send me shows i might be interested in going to" 548 548 + 549 549 + Content scripts 550 550 + - extract+log shazams 551 551 + - extract+log spotify playlist 552 552 + 553 553 + Calculators (variant of script + cmd?) 554 554 + - page -> table 555 555 + - page -> summary 556 556 + - page -> microsummaries 557 557 + - page -> dates 558 558 + - page -> events 559 559 + 560 560 + Workflow deconstructing a "why" task flavour of bookmarking 561 561 + - save https://www.criterionchannel.com/hong-kong-in-new-york 562 562 + - extract the movies 563 563 + - get reference metadata for each (?!) 564 564 + - add to "to watch list", with pointer back to source url 565 565 + 566 566 + ## Groups 567 567 + 568 568 + - panorama/tabcandy-ish 569 569 + - all browser history 570 570 + - smart groups vs curated groups 571 571 + - autoclustering on topic/date 572 572 + - escape from a new page enters default group? 573 573 + 574 574 + Groups + Cmds 575 575 + - top/bottom inputs for filtering/grouping/etc 576 576 + - implemented is a cmd input? 577 577 + - cmds for opening/searching/finding/viewing/filtering/piping 578 578 + - cmds for moving pages into groups 579 579 + - groups -> {x} (eg export/pipe) could depend on the chaining/piping bit (see below) 580 580 + 581 581 + Architecture 582 582 + - internally is tags? 583 583 + - static vs dynamic groups tho? 584 584 + 585 585 + Publishing 586 586 + - publishing groups as internal/public feeds? 587 587 + - to pinboard? 588 588 + 589 589 + ## History view/search 590 590 + 591 591 + A lot of groups work depends on history being in place, and being accessable and annotate-able. 592 592 + 593 593 + ideally use chromium history 594 594 + 595 595 + storage+access 596 596 + - check out Agregore history viewing approach 597 597 + - check out state of electron+webext 598 598 + - other way of accessing underlying chromium history? 599 599 + 600 600 + features 601 601 + - awesomebar algo scoring 602 602 + - adaptive matching 603 603 + 604 604 + ## Chaining / piping 605 605 + 606 606 + investigate: vague thought re chaining: 607 607 + - dynamic interstitial representations 608 608 + - mime type detection? 609 609 + - eg image previews 610 610 + - or a table of data 611 611 + - previews of cmds? 612 612 + 613 613 + interfaces 614 614 + - horizontal vs vertical chains 615 615 + - back/forward navigation? 616 616 + - each step is a cmd+preview? 617 617 + - dynamic cmd+previews? 618 618 + 619 619 + import/export/undo/redo 620 620 + - record/replay? 621 621 + - save a chain as a compound action (cmd)? 622 622 + 623 623 + architecture 624 624 + - look at web actions/intents/applets 625 625 + - xml pipeline language 626 626 + 627 627 + ## Mobile 628 628 + 629 629 + - some of the features don't make sense as-is on mobile 630 630 + - but maybe quick access on mobile to slides/peeks would be nice 631 631 + - and seeing output of content scripts, or ability to re-run locally on demand 632 632 + - needs some sync facility (inevitable anyway) 633 633 + 634 634 + ## Use-cases 635 635 + 636 636 + Peeks 637 637 + - translate 638 638 + - calendar 639 639 + - ai chat 640 640 + - currency conversion 641 641 + - everytimezone 642 642 + - tldraw 643 643 + 644 644 + Slides 645 645 + - music: Soundcloud, Hypem 646 646 + - stock prices 647 647 + - notepad 648 648 + - todo list 649 649 + 650 650 + Scripts 651 651 + - weather change, eg upcoming weather 652 652 + - crypto prices 653 653 + 654 654 + Cmd - web 655 655 + - open url 656 656 + - web search 657 657 + - image search 658 658 + - conversions? 659 659 + - ddg !actions 660 660 + 661 661 + Cmd - system 662 662 + - search browser history 663 663 + - set peeks/slides 664 664 + - open settings 665 665 + - restart app 666 666 + - llm prompts 667 667 + 668 668 + Future 669 669 + - address something to switch between 670 670 + - pipe from/to? 671 671 + 672 672 + Publishing high level 673 673 + - author web content 674 674 + - pull in bits from the web 675 675 + - share preview for feedback 676 676 + - publish (or at least get output) 677 677 + 678 678 + Publishing examples 679 679 + - writing an event recap 680 680 + 681 681 + Publishing: event recap post 682 682 + - make a new markdown doc 683 683 + - sections titled for each video title 684 684 + - each video's embed code in each section 685 685 + - navigate around the document for review and updates 686 686 + - need to easily preview rendered content 687 687 + - share preview link 688 688 + - publish (somewhere?) 689 689 + 690 690 + Music 691 691 + - commands 692 692 + - views 693 693 + - last.fm of my own, to POSSE out 694 694 + 695 695 + ## Unfiled 696 696 + 697 697 + markdown hot reload previewer w/ toc 698 698 + - markdown support, with sidebar nav 699 699 + - reader mode 700 700 + - hot reload for file:// (other?) 701 701 + - add side-by-side view 702 702 + - once md and side-by-side, add side-by-side so the md is the nav, content is the preview 703 703 + - what's the cmd chain for this? 704 704 + 705 705 + content types + chaining 706 706 + - cmd: view as… table, feed, markdown, data points, named entities 707 707 + - chain: static archive, publish, save, share (os), mailto 708 708 + - cmd params, eg {url}, which can themselves autocomplete (eg history) 709 709 + 710 710 + multiprotocol 711 711 + - at 712 712 + - ipfs/ipns 713 713 + - pragmatic addressing+rendering for data (r/d/masl + mime handlers) 714 714 + 715 715 + broader patterns (chatting w/ luke) 716 716 + - why do we have to copy/paste? 717 717 + - devtools and ide are divorced 718 718 + 719 719 + chainframe/framechain 720 720 + - (web intents/applets/actions) + (webxdc/miniapps/tiles/farcasterframes) 721 721 + 722 722 + Small examples of agency 723 723 + 724 724 + - users can move, resize, change things to their requirements 725 725 + - eg, browsers restrict min-height of a window, but i should be able make as short as i like 726 726 +