experiments in a post-browser web
icon fixes, more notes and todos
+214
-20
+3
.gitignore
+3
.gitignore
.yarn/install-state.gz
.yarn/install-state.gz
This is a binary file and will not be displayed.
+132
DEVELOPMENT.md
+132
DEVELOPMENT.md
···
1
+
# Development Guide
2
+
3
+
## Commands
4
+
5
+
```bash
6
+
# Install dependencies
7
+
yarn install
8
+
9
+
# Run in development mode (with devtools)
10
+
yarn debug
11
+
12
+
# Start the application normally
13
+
yarn start
14
+
15
+
# Package the application (output: out/mac-arm64/)
16
+
yarn package
17
+
18
+
# Package and install to /Applications (macOS)
19
+
yarn package:install
20
+
21
+
# Build distributable packages
22
+
yarn make
23
+
24
+
# Check for security vulnerabilities
25
+
yarn npm audit
26
+
27
+
# Test packaged build with dev profile
28
+
PROFILE=dev out/mac-arm64/Peek.app/Contents/MacOS/Peek
29
+
```
30
+
31
+
## Architecture Overview
32
+
33
+
### Core Structure
34
+
35
+
The application uses a multi-window Electron architecture:
36
+
37
+
1. **Main Process** (`index.js`):
38
+
- Manages app lifecycle, windows, shortcuts, IPC communication
39
+
- Implements custom `peek://` protocol for internal navigation
40
+
- Handles profile management and data persistence
41
+
- Hosts the TinyBase datastore with IPC handlers for renderer access
42
+
43
+
2. **Renderer Process** (`app/`):
44
+
- Core app logic loads from `peek://app/background.html`
45
+
- Feature modules: peeks, slides, scripts, cmd, groups
46
+
- Settings UI at `peek://app/settings/settings.html`
47
+
- Datastore viewer at `peek://app/datastore/viewer.html`
48
+
49
+
3. **Preload Script** (`preload.js`):
50
+
- Bridges main/renderer with secure API exposure via contextBridge
51
+
- Provides shortcuts, window management, pubsub, and datastore APIs
52
+
53
+
### Custom Protocol
54
+
55
+
- Uses `peek://` scheme for internal pages
56
+
- Cross-origin network access enabled for peek:// pages
57
+
- Special APIs available: window control, global hotkeys, pubsub messaging
58
+
59
+
### Profile Management
60
+
61
+
Profile is determined automatically:
62
+
- Packaged app (`/Applications/Peek.app`) uses `default` profile
63
+
- Running from source (`yarn start`) uses `dev` profile
64
+
- `PROFILE` env var overrides (e.g., `PROFILE=test yarn start`)
65
+
66
+
Profile data stored in `{userData}/{PROFILE}/` directory.
67
+
68
+
## App Icon Generation
69
+
70
+
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.
71
+
72
+
### Icon files in `assets/`
73
+
74
+
- `appicon-source.png` - Original source image (1232x1232, no rounding)
75
+
- `appicon-rounded.png` - Processed version with rounded corners and padding (1024x1024)
76
+
- `appicon.icns` - Final macOS icon file used by electron-builder
77
+
78
+
### Regenerating the icon
79
+
80
+
Requires ImageMagick (`brew install imagemagick`).
81
+
82
+
```bash
83
+
SRC="assets/appicon-source.png"
84
+
ROUNDED="assets/appicon-rounded.png"
85
+
86
+
SIZE=1232
87
+
RADIUS=222 # ~18% of size for rounded corners
88
+
89
+
# Step 1: Apply rounded corners to source
90
+
magick "$SRC" \
91
+
\( +clone -alpha extract \
92
+
-draw 'fill black polygon 0,0 0,'"$RADIUS $RADIUS"',0 fill white circle '"$RADIUS,$RADIUS $RADIUS"',0' \
93
+
\( +clone -flip \) -compose Multiply -composite \
94
+
\( +clone -flop \) -compose Multiply -composite \
95
+
\) -alpha off -compose CopyOpacity -composite \
96
+
/tmp/rounded-temp.png
97
+
98
+
# Step 2: Add padding (scale to 80% and center on 1024x1024 canvas)
99
+
magick /tmp/rounded-temp.png \
100
+
-resize 824x824 \
101
+
-gravity center \
102
+
-background transparent \
103
+
-extent 1024x1024 \
104
+
"$ROUNDED"
105
+
106
+
# Step 3: Generate iconset and convert to icns
107
+
mkdir -p assets/AppIcon.iconset
108
+
for size in 16 32 64 128 256 512 1024; do
109
+
magick "$ROUNDED" -resize ${size}x${size} PNG32:"assets/AppIcon.iconset/icon_${size}x${size}.png"
110
+
done
111
+
112
+
# Create @2x variants
113
+
cp assets/AppIcon.iconset/icon_32x32.png assets/AppIcon.iconset/icon_16x16@2x.png
114
+
cp assets/AppIcon.iconset/icon_64x64.png assets/AppIcon.iconset/icon_32x32@2x.png
115
+
cp assets/AppIcon.iconset/icon_256x256.png assets/AppIcon.iconset/icon_128x128@2x.png
116
+
cp assets/AppIcon.iconset/icon_512x512.png assets/AppIcon.iconset/icon_256x256@2x.png
117
+
cp assets/AppIcon.iconset/icon_1024x1024.png assets/AppIcon.iconset/icon_512x512@2x.png
118
+
rm assets/AppIcon.iconset/icon_64x64.png assets/AppIcon.iconset/icon_1024x1024.png
119
+
120
+
iconutil -c icns assets/AppIcon.iconset -o assets/appicon.icns
121
+
rm -rf assets/AppIcon.iconset /tmp/rounded-temp.png
122
+
```
123
+
124
+
### Icon design notes
125
+
126
+
- Rounded corners at ~18% radius matches common macOS app icon style
127
+
- 80% content size with 10% padding on each side matches Apple HIG
128
+
- Source image should be square, ideally 1024x1024 or larger
129
+
130
+
## Known Issues
131
+
132
+
- **Tray icon in packaged builds**: Tray icon displays correctly in debug mode but not in packaged app builds. Works fine in dev.
+57
-18
TODO.md
+57
-18
TODO.md
···
2
2
3
3
## v0.4 - Minimum viable web workbench
4
4
5
+
- [ ] Design philosophy write-up w/ driving principles and characteristics
5
6
- [ ] Multi-protocol architecture
6
7
- [ ] Content publishing
7
8
- [ ] Event model
8
9
- [ ] Chaining
10
+
- [ ] Images
11
+
- [ ] Lists/feeds
12
+
13
+
## v? - Editor & Notes
14
+
15
+
Requires chaining and "activities"
16
+
17
+
- [ ] Notes in datastore
18
+
- [ ] Editor app (in/out datastore)
19
+
20
+
## v? - Extensibility
21
+
22
+
Peek extensions
23
+
- [ ] figure out background app vs other
24
+
- [ ] maybe cmd stays in core?
25
+
- [ ] is background runtime aware? eg mobile/extension/desktop
26
+
- [ ] background app separation from "feature" apps, is runtime aware
27
+
28
+
Web extensions
29
+
- [ ] WebExtension integration for priority only, on some platforms
30
+
31
+
- [ ] App cmds (eg Editor -> cmd to edit note X)
32
+
9
33
10
34
## v? Portability
11
35
12
-
- [ ] Abstraction of subset of core API to work in extension too
36
+
- [ ] Common background runtime
37
+
- [ ] Datastore -> background
38
+
- [ ] API -> background
39
+
- [ ] Define subset of core API for portability
40
+
- [ ] Extension back-end
41
+
- [ ] Mobile (webview) back-end
42
+
- [ ] Tauri back-end
43
+
44
+
## v? Pages, Tagging & Groups
45
+
46
+
Opening pages
47
+
- [x] Open page by default in cmd
48
+
- [x] Open page from OS, other apps
49
+
50
+
Page model & metadata
51
+
- [ ] Basic overlay
52
+
- [ ] Page embedding
53
+
54
+
Tagging
55
+
- [x] Cmd to tag current page
56
+
57
+
Groups
58
+
- [x] Groups based on tags, for now
59
+
- [x] Untagged -> default group
60
+
- [x] Cmd to open groups home
61
+
62
+
- [ ] What does it mean for a group to be active/not
63
+
- [ ] Open new empty page (in a group or not)
64
+
65
+
Cmd
66
+
- [ ] adaptive matching
67
+
- [ ] frecency
13
68
14
-
## v0.3 - Personal daily driver
69
+
## V.0.3 - Datastore
15
70
16
71
- [x] Datastore
17
-
- [x] Open URLs by default
18
-
- [ ] Cmd bar adaptive matching and frecency
19
-
- [ ] Page model and user interface
20
-
- [ ] Peek:// extensibility model
21
-
- [ ] figure out background app vs other
22
-
- [ ] maybe cmd stays in core?
23
-
- [ ] is background runtime aware? eg mobile/extension/desktop
24
-
- [ ] background app separation from "feature" apps, is runtime aware
25
-
- [ ] Notes in datastore
26
-
- [ ] Editor app (in/out datastore)
27
-
- [ ] App cmds (eg Editor -> cmd to edit note X)
28
-
- [ ] Tags + Groups
29
-
- [ ] Images
30
-
- [ ] Lists/feeds
31
-
- [ ] WebExtension integration for priority only
32
-
- [ ] Design philosophy write-up w/ driving principles and characteristics
33
72
34
73
## v0.2 - MVCP (minimum viable concept preview)
35
74
assets/appicon-rounded.png
assets/appicon-rounded.png
This is a binary file and will not be displayed.
assets/appicon.icns
assets/appicon.icns
This is a binary file and will not be displayed.
+10
-2
notes/extensibility.md
+10
-2
notes/extensibility.md
···
18
18
- Hotkey registration
19
19
- Pubsub messaging
20
20
21
-
22
21
Open questions for later:
23
22
23
+
- Dirty writes - add ext or sys as source. also ensure no direct writes, only api adds
24
+
- Sharded space, in/outbox style too maybe
24
25
- Trade off exfiltration-proof-ness for sensitive access, eg history?
25
-
- How to provide authorship verification?
26
+
- How to provide authorship verification? regular website + sigs
26
27
- How to provide tamper detection?
27
28
- How to do extension-specific settings? Manifest link to bundled settings UI? Or a api for placement into Settings app?
28
29
- How to allow for maximal unloading vs always persistent
29
30
- How to do remixes, eg take verified extension X, copy and hack
31
+
32
+
Mobile:
33
+
- open web pages
34
+
- if calls a registration api, user can choose to add
35
+
- permissions
36
+
- expose peek api upon approval
37
+
- also, preverification via sync
+11
notes/groups-model.md
+11
notes/groups-model.md