experiments in a post-browser web
docs: add comprehensive feature tour of desktop app
+778
+778
docs/feature-tour.md
+778
docs/feature-tour.md
···
1
+
# Peek Feature Tour
2
+
3
+
A comprehensive guide to every feature in Peek, the desktop web user agent. Peek reimagines how you interact with the web -- replacing tabs with floating windows, keyboard shortcuts, and a command palette.
4
+
5
+
---
6
+
7
+
## Core
8
+
9
+
### Command Palette
10
+
11
+
**Summary:** The central hub for all actions in Peek. Type commands, search history, open URLs, chain operations, and access every feature from one keyboard-driven interface.
12
+
13
+
**Where in UI:** Global hotkey or local shortcut.
14
+
15
+
**How to try it:**
16
+
1. Press `Option+Space` (global, works from any app) or `Cmd+K` (local, when a Peek window is focused).
17
+
2. Start typing a command name (e.g., `note`, `open`, `google`).
18
+
3. Commands appear as you type -- press Enter to execute, or add arguments after the command name.
19
+
4. The palette also searches your URL history, so typing part of a domain or page title will surface matching pages.
20
+
21
+
### Open URL
22
+
23
+
**Summary:** Open any URL in a new floating Peek window. Automatically adds `https://` to bare domains.
24
+
25
+
**Where in UI:** Command palette.
26
+
27
+
**How to try it:**
28
+
1. Open the command palette (`Option+Space`).
29
+
2. Type `open example.com` or `open https://en.wikipedia.org`.
30
+
3. Press Enter. A new window appears with the page loaded.
31
+
32
+
### Modal Window
33
+
34
+
**Summary:** Open a URL in a transient modal window that auto-hides when it loses focus or you press Escape.
35
+
36
+
**Where in UI:** Command palette.
37
+
38
+
**How to try it:**
39
+
1. Open the command palette.
40
+
2. Type `modal https://example.com`.
41
+
3. Press Enter. The page opens in a modal. Click away or press Escape to dismiss it.
42
+
43
+
### Settings
44
+
45
+
**Summary:** Central configuration panel for Peek and all its extensions. Covers global preferences (shortcuts, startup behavior, session restore, tray icon, title bars, backup) and per-extension settings.
46
+
47
+
**Where in UI:** Keyboard shortcut or command palette.
48
+
49
+
**How to try it:**
50
+
1. Press `Cmd+,` to open Settings.
51
+
2. The sidebar lists all configurable areas: Core settings, Cmd, Editor, Groups, Peeks, Slides, Web Search, Scripts, etc.
52
+
3. Each section has form controls for its preferences. Changes take effect immediately.
53
+
54
+
### System Tray Icon
55
+
56
+
**Summary:** An optional system tray icon that provides quick access to Peek. Click to open the most recent window or the command palette.
57
+
58
+
**Where in UI:** System tray (menu bar on macOS).
59
+
60
+
**How to try it:**
61
+
1. Open Settings (`Cmd+,`).
62
+
2. Ensure "Show tray icon" is enabled.
63
+
3. Look for the Peek icon in the system tray / menu bar area. Click it.
64
+
65
+
### Dock Visibility
66
+
67
+
**Summary:** Control whether Peek always appears in the macOS Dock and app switcher, or only when windows are visible.
68
+
69
+
**Where in UI:** Settings > Core > "Show in dock".
70
+
71
+
**How to try it:**
72
+
1. Open Settings.
73
+
2. Toggle "Show in dock" off. Peek disappears from the Dock when no windows are open, running silently in the background.
74
+
75
+
### Session Restore
76
+
77
+
**Summary:** Peek remembers your open windows (URLs, positions, sizes) and can restore them on restart. Includes periodic autosave.
78
+
79
+
**Where in UI:** Settings > Core.
80
+
81
+
**How to try it:**
82
+
1. Open Settings and ensure "Restore session on startup" is enabled.
83
+
2. Open several web pages in Peek, arrange them on screen.
84
+
3. Quit and relaunch Peek. Your windows reappear in their previous positions.
85
+
4. The "Autosave interval" setting (default: 5 minutes) controls how frequently session state is saved.
86
+
87
+
### Profiles
88
+
89
+
**Summary:** Isolated data workspaces with separate SQLite databases, session data, and sync configurations. Development builds automatically use a `dev` profile to keep data separate from production.
90
+
91
+
**Where in UI:** Settings.
92
+
93
+
**How to try it:**
94
+
1. Open Settings and look for the Profiles section.
95
+
2. Create a new profile with a custom name.
96
+
3. Switch to the new profile (requires app restart).
97
+
4. Each profile has its own history, tags, groups, and sync settings.
98
+
99
+
### Database Backup
100
+
101
+
**Summary:** Automatic daily compressed backups of the SQLite database using `VACUUM INTO`. Configurable backup directory and retention count (default: 7 backups).
102
+
103
+
**Where in UI:** Settings > Core > "Backup directory". Also accessible from the Diagnostic page.
104
+
105
+
**How to try it:**
106
+
1. Open Settings and set "Backup directory" to a folder path (e.g., `~/peek-backups`).
107
+
2. Backups occur automatically on startup if more than 24 hours have passed since the last one.
108
+
3. To manually trigger a backup, open the Diagnostic page (`peek://app/diagnostic.html`) and click "Backup Now".
109
+
110
+
### Ad Blocker
111
+
112
+
**Summary:** Built-in native ad and tracker blocking powered by Ghostery's adblocker-electron. Uses EasyList and EasyPrivacy filter lists.
113
+
114
+
**Where in UI:** Runs automatically in the background.
115
+
116
+
**How to try it:**
117
+
1. Open any web page with ads (e.g., a news site).
118
+
2. Ads and trackers are blocked at the network level before the page loads, resulting in cleaner, faster page rendering.
119
+
120
+
### Quit Shortcut
121
+
122
+
**Summary:** Configurable keyboard shortcut to quit the application.
123
+
124
+
**Where in UI:** Settings > Core > "Quit shortcut".
125
+
126
+
**How to try it:**
127
+
1. Press `Cmd+Q` (default) to quit Peek.
128
+
2. Change the shortcut in Settings if you prefer a different key combination.
129
+
130
+
---
131
+
132
+
## Page / Canvas
133
+
134
+
### Floating Page Windows
135
+
136
+
**Summary:** Every web page opens in its own floating, frameless window positioned on a fullscreen transparent canvas. Windows can be freely dragged, resized, and overlapped.
137
+
138
+
**Where in UI:** Open any URL via the command palette, history, groups, or web search.
139
+
140
+
**How to try it:**
141
+
1. Open a page (`open example.com` in the command palette).
142
+
2. The page appears as a floating window. Hold the mouse still on the page body for 2 seconds (configurable "drag hold delay" in Settings) -- the cursor changes to a hand, then drag to move the window.
143
+
3. Use the corner resize handle to change dimensions.
144
+
145
+
### Navbar
146
+
147
+
**Summary:** A floating URL bar that appears above the page window. Shows the current URL with back/forward/reload controls. Auto-hides to save space; revealed by hovering the trigger zone above the page or pressing `Cmd+L`.
148
+
149
+
**Where in UI:** Top of any page window.
150
+
151
+
**How to try it:**
152
+
1. Open a web page.
153
+
2. Press `Cmd+L` to show the navbar and focus the URL field.
154
+
3. Hover the mouse over the thin strip at the very top of the page to reveal the navbar.
155
+
4. Use the back arrow, forward arrow, and reload buttons, or type a new URL.
156
+
157
+
### Page Navigation Shortcuts
158
+
159
+
**Summary:** Standard keyboard shortcuts for navigating within a page window.
160
+
161
+
**Where in UI:** Any page window.
162
+
163
+
**How to try it:**
164
+
- `Cmd+[` or `Cmd+Left` -- go back in page history.
165
+
- `Cmd+]` or `Cmd+Right` -- go forward.
166
+
- `Cmd+R` -- reload the current page.
167
+
- `Escape` -- if the webview has history, go back; otherwise close the window (behavior depends on IZUI state).
168
+
169
+
### Drag Hold Delay
170
+
171
+
**Summary:** Configurable delay before a window becomes draggable. Prevents accidental drags when clicking or selecting text. The navbar background provides instant drag (no delay).
172
+
173
+
**Where in UI:** Settings > Core > "Window drag hold delay".
174
+
175
+
**How to try it:**
176
+
1. Open Settings and set "Window drag hold delay" (default: 2 seconds).
177
+
2. On a page, click and hold without moving. After the delay, the cursor changes to a hand.
178
+
3. Now move the mouse to drag the window.
179
+
4. On the navbar background, drag is instant with no delay.
180
+
181
+
### Mode Indicator
182
+
183
+
**Summary:** A small label on each page window showing the current mode (e.g., "page", "group"). When in group mode, also displays the group name.
184
+
185
+
**Where in UI:** Bottom-left corner of page windows.
186
+
187
+
**How to try it:**
188
+
1. Open a page -- the mode indicator says "page".
189
+
2. Open a group (see Groups section below) -- member windows show "group" plus the group name.
190
+
191
+
### OAuth Detection
192
+
193
+
**Summary:** Automatically detects OAuth/authentication flows (Google, Microsoft, Auth0, Apple ID, etc.) and suppresses the navbar auto-show hover behavior so it does not interfere with credential entry.
194
+
195
+
**Where in UI:** Automatic, invisible to the user.
196
+
197
+
**How to try it:**
198
+
1. Navigate to a login page that uses OAuth (e.g., sign in with Google).
199
+
2. Hovering the trigger zone above the page will not reveal the navbar, avoiding interruption.
200
+
3. You can still press `Cmd+L` to manually show the navbar.
201
+
202
+
---
203
+
204
+
## Editor
205
+
206
+
### Markdown Editor
207
+
208
+
**Summary:** A full-featured markdown editor with a three-panel layout: outline sidebar (table of contents generated from headers), CodeMirror editing area, and live preview. Supports focus mode, autosave, and resizable panels.
209
+
210
+
**Where in UI:** Global hotkey, local shortcut, or command palette.
211
+
212
+
**How to try it:**
213
+
1. Press `Option+E` (global) or `Cmd+E` (local) to open the editor.
214
+
2. Or type `open editor` in the command palette.
215
+
3. Start typing markdown. The outline updates from your headers; the preview renders live.
216
+
217
+
### Vim Mode
218
+
219
+
**Summary:** Optional vim keybindings for the editor, including `:set wrap`/`:set nowrap` for line wrapping, `:set number`/`:set nonumber` for line numbers, and `:q` to close.
220
+
221
+
**Where in UI:** Settings > Editor > "Vim mode".
222
+
223
+
**How to try it:**
224
+
1. Open Settings, go to the Editor section, and enable "Vim mode".
225
+
2. Open the editor. Use vim navigation (`h`, `j`, `k`, `l`), insert mode (`i`), visual mode (`v`), and ex commands (`:w`, `:q`).
226
+
3. Type `:set wrap` to enable line wrapping, `:set nowrap` to disable it.
227
+
4. Type `:set number` to show line numbers, `:set nonumber` to hide them.
228
+
229
+
### Autosave
230
+
231
+
**Summary:** When editing a datastore item (note or other text), changes are automatically saved 1.5 seconds after you stop typing. The status line shows "saved", "saving", or "unsaved".
232
+
233
+
**Where in UI:** Automatic in the editor when editing an existing item.
234
+
235
+
**How to try it:**
236
+
1. Open an existing note in the editor (use `edit` command or click a note in Tags view).
237
+
2. Make changes. The status line updates to "unsaved", then "saving", then "saved".
238
+
239
+
---
240
+
241
+
## Organization
242
+
243
+
### Tags
244
+
245
+
**Summary:** A flexible tagging system for organizing saved items (URLs, notes, tagsets). Tags are ranked by frecency (frequency + recency). Browse all items filtered by tags, add/remove tags from the active window, and create tagsets (items that are just collections of tags).
246
+
247
+
**Where in UI:** Global hotkey, local shortcut, or command palette.
248
+
249
+
**How to try it:**
250
+
1. Press `Option+T` (global) or `Cmd+T` (local) to open the Tags browser.
251
+
2. Browse all saved items. Click tag buttons to filter by tag.
252
+
3. To tag the current page: open the command palette and type `tag design, inspiration` (comma-separated tags).
253
+
4. To view tags on the current page: type `tags` in the command palette.
254
+
5. To remove a tag: type `untag design` in the command palette.
255
+
6. To create a tagset: type `tagset #project, #active, #frontend` in the command palette.
256
+
257
+
### Groups
258
+
259
+
**Summary:** Save your current window layout as a named group. All open page URLs are tagged with the group name. Reopen the group later to restore all windows, including their saved screen positions and z-ordering.
260
+
261
+
**Where in UI:** Global hotkey, local shortcut, or command palette.
262
+
263
+
**How to try it:**
264
+
1. Open several web pages and arrange them on screen.
265
+
2. Open the command palette and type `new group research` to save all open pages to a group called "research".
266
+
3. Close all windows.
267
+
4. Type `open group research` in the command palette. All pages reopen in their saved positions.
268
+
5. Press `Option+G` (global) or `Cmd+G` (local) to open the Groups browser for a visual overview.
269
+
270
+
### Notes
271
+
272
+
**Summary:** Quick note creation from the command palette with smart type detection. If the input is a URL, it is saved as a URL item. If it is hashtags (`#foo #bar`), it is saved as a tagset. Otherwise it is saved as a text note tagged with `note` and `from:cmd`.
273
+
274
+
**Where in UI:** Command palette.
275
+
276
+
**How to try it:**
277
+
1. Open the command palette and type `note Remember to review the API docs`.
278
+
2. The text is saved as a note.
279
+
3. Type `note https://example.com` -- saved as a URL item.
280
+
4. Type `note #project #done` -- saved as a tagset.
281
+
5. Type `notes` to list recent notes.
282
+
6. Type `list notes #todo` to filter notes by tag.
283
+
7. Type `note` with no arguments to open a blank editor.
284
+
285
+
### Edit Note
286
+
287
+
**Summary:** Search for existing notes and open them in the editor.
288
+
289
+
**Where in UI:** Command palette.
290
+
291
+
**How to try it:**
292
+
1. Open the command palette and type `edit API`.
293
+
2. Matching notes appear in the dropdown. Select one to open it in the editor.
294
+
295
+
### URL Save
296
+
297
+
**Summary:** Explicitly save a URL to the datastore.
298
+
299
+
**Where in UI:** Command palette.
300
+
301
+
**How to try it:**
302
+
1. Type `url https://example.com/interesting-article` in the command palette.
303
+
2. The URL is saved and available in history, tags browser, and groups.
304
+
305
+
### History Search
306
+
307
+
**Summary:** Search and open pages from your saved URL history. URLs are ranked by frecency. Every saved URL also appears as a searchable entry in the command palette.
308
+
309
+
**Where in UI:** Command palette.
310
+
311
+
**How to try it:**
312
+
1. Type `history wikipedia` in the command palette.
313
+
2. The best frecency-ranked match opens in a new window.
314
+
3. Or just start typing a URL or page title in the command palette -- history entries surface automatically.
315
+
316
+
---
317
+
318
+
## Search
319
+
320
+
### Web Search
321
+
322
+
**Summary:** Search the web directly from the command palette. Supports multiple engines (Google, DuckDuckGo, Bing, Wikipedia, Kagi) with per-engine shortcut commands. Includes search suggestions with debounce and caching.
323
+
324
+
**Where in UI:** Command palette.
325
+
326
+
**How to try it:**
327
+
1. Type `web search electron framework` in the command palette. Results open in a new window using your default engine.
328
+
2. Use engine-specific shortcuts: `google something`, `ddg privacy tools`, `wiki quantum physics`, `bing news`, `kagi best IDE`.
329
+
3. Type `open web search` to open a dedicated search window.
330
+
331
+
### OpenSearch Discovery
332
+
333
+
**Summary:** Automatically discovers search engines from visited websites via their OpenSearch description documents. Discovered engines are saved and become usable from the command palette.
334
+
335
+
**Where in UI:** Automatic (configurable in Settings > Web Search > "Auto-discover search engines").
336
+
337
+
**How to try it:**
338
+
1. Visit a website that provides an OpenSearch description (many do, such as GitHub, Stack Overflow).
339
+
2. Peek detects the OpenSearch link and registers the site as a search engine.
340
+
3. The new engine appears in the command palette as a shortcut command.
341
+
342
+
### Search Suggestions
343
+
344
+
**Summary:** As you type a search query, suggestions from the selected engine appear in real time. Suggestions are cached for 5 minutes.
345
+
346
+
**Where in UI:** Command palette when using web search commands.
347
+
348
+
**How to try it:**
349
+
1. Type `google how to` in the command palette.
350
+
2. Suggestions appear below the input as you type. Select one to search for it.
351
+
3. Toggle suggestions on/off in Settings > Web Search > "Enable search suggestions".
352
+
353
+
### Local Search
354
+
355
+
**Summary:** Search across all local items (URLs, notes, tags, history) in a dedicated search window.
356
+
357
+
**Where in UI:** Global hotkey or command palette.
358
+
359
+
**How to try it:**
360
+
1. Press `Option+F` (global) to open the local search window.
361
+
2. Or type `localsearch` in the command palette.
362
+
3. Type a query to search across all stored items.
363
+
364
+
---
365
+
366
+
## Feeds
367
+
368
+
### RSS/Atom Feed Reader
369
+
370
+
**Summary:** Subscribe to RSS and Atom feeds. Feeds are polled every 15 minutes for new entries. View entries in a dedicated reader UI, sorted by date.
371
+
372
+
**Where in UI:** Global hotkey or command palette.
373
+
374
+
**How to try it:**
375
+
1. Press `Option+Shift+F` (global) to open the Feed Reader.
376
+
2. Or type `new feed https://example.com/rss.xml` in the command palette to subscribe.
377
+
3. Type `feeds` in the command palette to browse subscribed feeds.
378
+
4. Type `refresh feeds` to manually poll all feeds for updates.
379
+
380
+
---
381
+
382
+
## Entity Recognition
383
+
384
+
### Automatic Entity Extraction
385
+
386
+
**Summary:** Automatically extracts people, places, organizations, events, emails, phone numbers, and dates from visited web pages using regex, microformat, and JSON-LD extractors. Entities are stored and searchable.
387
+
388
+
**Where in UI:** Automatic (runs on page load) or manual via command palette.
389
+
390
+
**How to try it:**
391
+
1. Visit a web page with structured content (news articles, business pages, event listings).
392
+
2. After a 2-second delay, entities are extracted and stored.
393
+
3. Type `extract entities` in the command palette to manually trigger extraction on the current page.
394
+
4. Type `open entities` or `list entities` to browse extracted entities.
395
+
396
+
### URL Item Enrichment
397
+
398
+
**Summary:** When entities are extracted, Peek also reads OpenGraph metadata (title, description, image, site name) from the page and enriches the stored URL item. This improves display in the Tags browser and other views.
399
+
400
+
**Where in UI:** Automatic, invisible to the user.
401
+
402
+
**How to try it:**
403
+
1. Save a URL and visit it. The entity extraction pipeline enriches the stored item with OG metadata.
404
+
2. Open the Tags browser to see enriched titles and descriptions for URL items.
405
+
406
+
---
407
+
408
+
## Scripts
409
+
410
+
### Userscripts / Content Scripts
411
+
412
+
**Summary:** Create, edit, and manage custom JavaScript scripts that run on web pages matching URL patterns. Scripts support match/exclude patterns, multiple injection timings (`document-end`, etc.), and can be enabled/disabled individually.
413
+
414
+
**Where in UI:** Local shortcut or command palette.
415
+
416
+
**How to try it:**
417
+
1. Press `Cmd+Shift+S` to open the Scripts Manager.
418
+
2. Or type `scripts` or `new script My Script` in the command palette.
419
+
3. In the manager, create a new script. Set match patterns (e.g., `*://*.example.com/*`), write JavaScript code, and enable it.
420
+
4. Visit a matching page. The script executes automatically.
421
+
422
+
---
423
+
424
+
## Window Management
425
+
426
+
### Window Switcher
427
+
428
+
**Summary:** A fullscreen transparent overlay that shows all open Peek windows, allowing quick switching between them.
429
+
430
+
**Where in UI:** Global hotkey or command palette.
431
+
432
+
**How to try it:**
433
+
1. Open several pages in Peek.
434
+
2. Press the Windows shortcut (configurable, check Settings > Windows) to open the overlay.
435
+
3. Or type `windows` in the command palette.
436
+
4. Click a window to switch to it.
437
+
438
+
### Center Window / Center All Windows
439
+
440
+
**Summary:** Center the active window (or all windows) on their respective displays.
441
+
442
+
**Where in UI:** Command palette.
443
+
444
+
**How to try it:**
445
+
1. Type `center window` in the command palette to center the currently active window.
446
+
2. Type `center all windows` to center every open window.
447
+
448
+
### Peeks (Quick Access Modals)
449
+
450
+
**Summary:** Assign up to 10 web pages to `Option+0` through `Option+9` hotkeys. Each one opens as a modal popup that disappears when you switch away. Optionally keep the window alive in the background and persist its state.
451
+
452
+
**Where in UI:** Settings > Peeks, then use assigned hotkeys.
453
+
454
+
**How to try it:**
455
+
1. Open Settings and go to the Peeks section.
456
+
2. Add a URL (e.g., `https://calendar.google.com`) and assign it to key 1.
457
+
3. Enable the item. Press `Option+1` from anywhere. The page pops up instantly.
458
+
4. Press Escape or switch to another app to dismiss it.
459
+
460
+
### Slides (Edge-Anchored Panels)
461
+
462
+
**Summary:** Assign web pages to slide in from screen edges (Up, Down, Left, Right) via `Option+Arrow` hotkeys. Great for dashboards, chat, or reference material that you want always accessible from a screen edge.
463
+
464
+
**Where in UI:** Settings > Slides, then use assigned hotkeys.
465
+
466
+
**How to try it:**
467
+
1. Open Settings and go to the Slides section.
468
+
2. Add a URL and assign it to the "Right" edge.
469
+
3. Enable the item. Press `Option+Right` from anywhere. The page slides in from the right edge.
470
+
471
+
### Pagestream (Browsing History Stream)
472
+
473
+
**Summary:** A vertical, chat-like navigational interface showing your browsing history as a scrollable stream. Provides a visual timeline of pages visited.
474
+
475
+
**Where in UI:** Global hotkey or command palette.
476
+
477
+
**How to try it:**
478
+
1. Press the Pagestream shortcut (configurable in Settings) to open the stream.
479
+
2. Or type `pagestream` or `open pagestream` in the command palette.
480
+
3. Scroll through your browsing history. Click an entry to reopen the page.
481
+
482
+
---
483
+
484
+
## Command Chaining
485
+
486
+
### Pipe Commands Together
487
+
488
+
**Summary:** Commands can produce output that feeds into other commands, forming pipelines. Commands declare what MIME types they accept and produce. The command palette shows compatible next-step commands after a producing command runs.
489
+
490
+
**Where in UI:** Command palette.
491
+
492
+
**How to try it:**
493
+
1. Type `list notes #todo` in the command palette. This produces JSON output.
494
+
2. Compatible commands appear: `csv` (convert to CSV), `save` (save to file), `markdown` (format as markdown), `save as note` (save as a new note).
495
+
3. Select `csv` to convert the JSON to CSV format.
496
+
4. Then select `save` to write the CSV to a file on disk.
497
+
498
+
### CSV Export
499
+
500
+
**Summary:** Convert JSON data to CSV format. Designed to be used in a chain after commands that produce JSON output (like `list notes`, `list tags`, `list groups`).
501
+
502
+
**Where in UI:** Command palette (chain step).
503
+
504
+
**How to try it:**
505
+
1. Run `list notes` in the command palette.
506
+
2. Select `csv` from the suggested chain commands.
507
+
3. The data is converted to comma-separated values.
508
+
509
+
### Markdown Export
510
+
511
+
**Summary:** Format JSON items as a readable markdown document with headers, tags, metadata, and content sections. Opens an interactive editor for reviewing and editing the result.
512
+
513
+
**Where in UI:** Command palette (chain step).
514
+
515
+
**How to try it:**
516
+
1. Run `list notes #project` in the command palette.
517
+
2. Select `markdown` from the chain commands.
518
+
3. A formatted markdown document appears in an editor window.
519
+
520
+
### Save to File
521
+
522
+
**Summary:** Save any chain output to a file on disk using a native save dialog. Accepts any MIME type. Automatically generates a filename with date and appropriate extension.
523
+
524
+
**Where in UI:** Command palette (chain step).
525
+
526
+
**How to try it:**
527
+
1. Run any chain that produces output (e.g., `list groups | csv`).
528
+
2. Select `save` from the chain commands.
529
+
3. A native file picker appears. Choose a location and filename.
530
+
531
+
### Save as Note
532
+
533
+
**Summary:** Save text chain output as a new note in the datastore, tagged with `note` and `from:cmd`.
534
+
535
+
**Where in UI:** Command palette (chain step).
536
+
537
+
**How to try it:**
538
+
1. Run a chain that produces text output (e.g., `list notes #draft | markdown`).
539
+
2. Select `save as note` from the chain commands.
540
+
3. The content is saved as a new note item.
541
+
542
+
### Open File
543
+
544
+
**Summary:** Open a text file from disk using the native file picker. The file content enters the chain as output, which can then be piped to `save as note`, `csv`, or other commands.
545
+
546
+
**Where in UI:** Command palette.
547
+
548
+
**How to try it:**
549
+
1. Type `open file` in the command palette.
550
+
2. A native file picker opens. Select a text file (markdown, JSON, CSV, etc.).
551
+
3. The file content is loaded and available for chaining to downstream commands.
552
+
553
+
### Chain Editor
554
+
555
+
**Summary:** When a chain produces text output (especially via `markdown`), an interactive editor window opens where you can review, edit, and then save or close the result. Uses CodeMirror with optional vim mode.
556
+
557
+
**Where in UI:** Automatic after certain chain steps.
558
+
559
+
**How to try it:**
560
+
1. Run `list notes | markdown` in the command palette.
561
+
2. The Chain Editor opens with the formatted markdown. Edit as needed.
562
+
3. Press Escape (or `:q` in vim mode) to close.
563
+
564
+
---
565
+
566
+
## Sync
567
+
568
+
### Sync Now
569
+
570
+
**Summary:** Manually trigger a full bidirectional sync with the server. Pulls new items from the server and pushes local changes. Reports counts of pulled, pushed, and conflicting items.
571
+
572
+
**Where in UI:** Command palette.
573
+
574
+
**How to try it:**
575
+
1. Ensure sync is configured in Settings (server URL and API key).
576
+
2. Type `Sync now` in the command palette.
577
+
3. The command runs and reports results (e.g., "Sync completed: 3 pulled, 2 pushed").
578
+
579
+
---
580
+
581
+
## HUD (Heads-Up Display)
582
+
583
+
### Always-On-Top Status Overlay
584
+
585
+
**Summary:** A small, always-on-top overlay showing the current IZUI state (Transient/Active), mode, and window information. Automatically hides when Peek loses focus and reappears when focused.
586
+
587
+
**Where in UI:** Global hotkey, local shortcut, or command palette.
588
+
589
+
**How to try it:**
590
+
1. Press `Option+H` (global) or `Cmd+H` (local) to toggle the HUD.
591
+
2. Or type `hud` in the command palette.
592
+
3. A small translucent panel appears in the top-left corner showing state information.
593
+
4. Toggle again to dismiss.
594
+
595
+
---
596
+
597
+
## IZUI (Invocable Zoom User Interface)
598
+
599
+
### Transient vs Active State
600
+
601
+
**Summary:** Peek tracks whether you invoked it from another app (transient) or are actively working in it (active). This controls Escape key behavior: in transient mode, Escape closes immediately; in active mode, Escape navigates internally and never closes.
602
+
603
+
**Where in UI:** Automatic, reflected in the HUD overlay.
604
+
605
+
**How to try it:**
606
+
1. While in another app, press `Option+Space` to invoke the command palette (transient mode).
607
+
2. Press Escape -- the palette closes and focus returns to the previous app.
608
+
3. While working in Peek, press `Cmd+K` to open the palette (active mode).
609
+
4. Press Escape -- the palette closes but you remain in Peek.
610
+
611
+
---
612
+
613
+
## DevTools / Debugging
614
+
615
+
### DevTools Command
616
+
617
+
**Summary:** Open Chrome DevTools for the most recently active content window. Useful for inspecting web pages loaded in Peek.
618
+
619
+
**Where in UI:** Command palette.
620
+
621
+
**How to try it:**
622
+
1. Open a web page in Peek.
623
+
2. Type `devtools` in the command palette.
624
+
3. DevTools opens in a detached window for the active page.
625
+
626
+
### Debug Command
627
+
628
+
**Summary:** Open a URL in a new window with DevTools automatically enabled and detached.
629
+
630
+
**Where in UI:** Command palette.
631
+
632
+
**How to try it:**
633
+
1. Type `debug https://example.com` in the command palette.
634
+
2. The page opens alongside a detached DevTools window.
635
+
636
+
### Diagnostic Page
637
+
638
+
**Summary:** An internal tool for inspecting localStorage, datastore contents, and managing backups. Useful for troubleshooting.
639
+
640
+
**Where in UI:** Navigate to `peek://app/diagnostic.html`.
641
+
642
+
**How to try it:**
643
+
1. Open the command palette and type `open peek://app/diagnostic.html`.
644
+
2. Use the buttons to dump localStorage, dump datastore extension settings, create backups, or list existing backups.
645
+
646
+
---
647
+
648
+
## Extensions (Advanced / Hidden)
649
+
650
+
### Help Docs (Easter Egg)
651
+
652
+
**Summary:** A hidden documentation overlay that shows animated help hints from screen edges. Disguised as "Help docs" in the extension system. Disabled by default.
653
+
654
+
**Where in UI:** Command palette.
655
+
656
+
**How to try it:**
657
+
1. Type `help docs` in the command palette.
658
+
2. A fullscreen transparent, click-through overlay appears with animated documentation hints.
659
+
3. Type `help docs` again to toggle it off.
660
+
661
+
### Example Gallery
662
+
663
+
**Summary:** A demonstration extension showcasing the Peek API -- feature detection, image handling, and storage patterns. Useful for developers building extensions.
664
+
665
+
**Where in UI:** Listed in Settings as an extension.
666
+
667
+
**How to try it:**
668
+
1. Open Settings. Look for the Example Gallery extension.
669
+
2. Enable it if needed. The extension demonstrates Peek API capabilities.
670
+
671
+
---
672
+
673
+
## Keyboard Shortcut Reference
674
+
675
+
### Global Shortcuts (work from any app)
676
+
677
+
| Shortcut | Action |
678
+
|----------|--------|
679
+
| `Option+Space` | Open command palette |
680
+
| `Option+E` | Open editor |
681
+
| `Option+T` | Open tags browser |
682
+
| `Option+G` | Open groups browser |
683
+
| `Option+F` | Open local search |
684
+
| `Option+Shift+F` | Open feed reader |
685
+
| `Option+H` | Toggle HUD overlay |
686
+
| `Option+0` through `Option+9` | Open assigned Peek (configurable) |
687
+
| `Option+Arrow` | Open assigned Slide from screen edge (configurable) |
688
+
| Windows shortcut | Open window switcher (configurable) |
689
+
| Pagestream shortcut | Open pagestream (configurable) |
690
+
691
+
### Local Shortcuts (work when a Peek window is focused)
692
+
693
+
| Shortcut | Action |
694
+
|----------|--------|
695
+
| `Cmd+K` | Open command palette |
696
+
| `Cmd+E` | Open editor |
697
+
| `Cmd+T` | Open tags browser |
698
+
| `Cmd+G` | Open groups browser |
699
+
| `Cmd+H` | Toggle HUD overlay |
700
+
| `Cmd+,` | Open settings |
701
+
| `Cmd+Shift+S` | Open scripts manager |
702
+
| `Cmd+Q` | Quit (configurable) |
703
+
704
+
### Page Window Shortcuts
705
+
706
+
| Shortcut | Action |
707
+
|----------|--------|
708
+
| `Cmd+L` | Show navbar and focus URL field |
709
+
| `Cmd+R` | Reload page |
710
+
| `Cmd+[` or `Cmd+Left` | Go back |
711
+
| `Cmd+]` or `Cmd+Right` | Go forward |
712
+
| `Escape` | Go back (if history) or close window |
713
+
714
+
### Editor Shortcuts (Vim Mode)
715
+
716
+
| Command | Action |
717
+
|---------|--------|
718
+
| `:set wrap` | Enable line wrapping |
719
+
| `:set nowrap` | Disable line wrapping |
720
+
| `:set number` | Show line numbers |
721
+
| `:set nonumber` | Hide line numbers |
722
+
| `:q` | Close editor |
723
+
724
+
---
725
+
726
+
## Command Palette Command Reference
727
+
728
+
All commands accessible from `Option+Space` or `Cmd+K`:
729
+
730
+
| Command | Description |
731
+
|---------|-------------|
732
+
| `open <url>` | Open URL in a new window |
733
+
| `modal <url>` | Open URL in a transient modal |
734
+
| `note <text or url>` | Save a note (auto-detects URL, tagset, or text) |
735
+
| `notes` | List recent notes |
736
+
| `list notes [#tag ...]` | List notes filtered by tags |
737
+
| `edit [search]` | Search notes and open in editor |
738
+
| `url <url>` | Save a URL to datastore |
739
+
| `history [search]` | Search and open from URL history |
740
+
| `tag [tags]` | Add tags to the active window URL |
741
+
| `tags [search]` | Show tags for active window or search all tags |
742
+
| `untag <tags>` | Remove tags from the active window URL |
743
+
| `tagset <#tag1,#tag2,...>` | Create a tagset item |
744
+
| `groups` | Browse saved groups |
745
+
| `list groups` | List groups with item counts |
746
+
| `open group <name>` | Open all URLs in a group |
747
+
| `new group <name>` | Save current windows to a named group |
748
+
| `web search <query>` | Search using default engine |
749
+
| `google <query>` | Search Google |
750
+
| `ddg <query>` | Search DuckDuckGo |
751
+
| `bing <query>` | Search Bing |
752
+
| `wiki <query>` | Search Wikipedia |
753
+
| `kagi <query>` | Search Kagi |
754
+
| `localsearch` | Open local search window |
755
+
| `feeds` | Browse subscribed feeds |
756
+
| `new feed <url>` | Subscribe to an RSS/Atom feed |
757
+
| `refresh feeds` | Poll all feeds for updates |
758
+
| `open editor` | Open the markdown editor |
759
+
| `scripts` | Open scripts manager |
760
+
| `new script [name]` | Create a new userscript |
761
+
| `extract entities` | Extract entities from current page |
762
+
| `open entities` | Open entity browser |
763
+
| `list entities` | List extracted entities |
764
+
| `windows` | Open window switcher overlay |
765
+
| `center window` | Center active window on display |
766
+
| `center all windows` | Center all windows |
767
+
| `pagestream` | Open browsing history stream |
768
+
| `Sync now` | Trigger manual sync |
769
+
| `hud` | Toggle HUD overlay |
770
+
| `help docs` | Toggle help docs overlay |
771
+
| `devtools` | Open DevTools for active window |
772
+
| `debug <url>` | Open URL with DevTools enabled |
773
+
| `open file` | Open a text file from disk |
774
+
| `csv` | Convert JSON to CSV (chain) |
775
+
| `markdown` | Convert JSON to markdown (chain) |
776
+
| `save [filename]` | Save chain output to file |
777
+
| `save as note` | Save chain output as a note |
778
+
| `lists` | Produce sample list data (chain demo) |