experiments in a post-browser web
docs(v1-removal): break Phase 3 into ~8 small agent-sized work packages
+402
+402
docs/v1-removal-phase3-tasks.md
+402
docs/v1-removal-phase3-tasks.md
···
1
+
# V1 Removal — Phase 3 Work Packages
2
+
3
+
Break Phase 3 (destructive cleanup of remaining v1 plumbing) into small
4
+
agent-sized tasks. Each package is sized for a 15–20 min agent spawn.
5
+
6
+
See `docs/v1-removal-plan.md` for background, the rolled-back Phase 3
7
+
attempt's lessons, and the Phase 2/2.5 work that's already landed.
8
+
9
+
---
10
+
11
+
## Current state (what's still v1)
12
+
13
+
After Phase 2.5 cleanup, these v1 surfaces are still present:
14
+
15
+
1. **`extensionHostWindow`** BrowserWindow + `createExtensionHostWindow()`
16
+
— still created at startup. Loads `peek://app/extension-host.html`.
17
+
Now empty (no iframes; cmd/hud/page moved out). Still needed because
18
+
smoke tests assert on the URL's existence (`smoke.spec.ts:4177, 4189,
19
+
4359, 5292, 5299, 5379`) and the v1 portion of `extensionBroadcaster`
20
+
still iterates its frames.
21
+
2. **`extensionWindows` map** — never populated after Phase 2.5 #3
22
+
(`createExtensionWindow` was deleted). Still referenced by
23
+
`destroyExtensionWindow`, `getExtensionWindow`, `getRunningExtensions`,
24
+
`getAllRegisteredExtensions`, broadcaster loop. Dead-path: all callers
25
+
hit an always-empty map.
26
+
3. **`loadedConsolidatedExtensions` Set + `CONSOLIDATED_EXTENSION_IDS`
27
+
list** — list has 20 ids, but post-v2 migration none of them load
28
+
through the consolidated host. `loadedConsolidatedExtensions.add(...)`
29
+
still called for `cmd`/`hud`/`page` solely to keep them visible in
30
+
`getRunningExtensions()`.
31
+
4. **Legacy IPC channels in `ipc.ts`** — ~103 `ipcMain.handle/on` calls
32
+
for `window-*`, `datastore-*`, `context-*`, `chrome-ext:*`, `oauth-*`,
33
+
`izui-*`, `extension-*`, `feature-registry:*`, `feature-install:*`,
34
+
`feature-settings-schema`, `screen-*`, `save-space-workspaces`,
35
+
`sync-full`, `renderer-log`, `app-quit`, `app-restart`, and the
36
+
`IPC_CHANNELS.*` set (`SUBSCRIBE`, `PUBLISH`, `CLOSE_WINDOW`,
37
+
`REGISTER_SHORTCUT`, `UNREGISTER_SHORTCUT`, `MODIFY_WINDOW`,
38
+
`CONSOLE`). Callers: `preload.js` and `tile-preload.cts` fallback
39
+
branches.
40
+
5. **`preload.js`** (2693 LOC) — still referenced by `entry.ts:152`
41
+
(`setPreloadPath`), webview v1 fallback in `entry.ts:207`, and
42
+
`ipc.ts:2268,2670` window-open fallback for non-tile URLs.
43
+
6. **Fallback branches in `tile-preload.cts`** — 4 explicit
44
+
`if (!hasXxxCapability()) return ipcRenderer.invoke('legacy-*')`
45
+
branches for `izui-*` + ~70 unconditional `ipcRenderer.invoke(...)`
46
+
calls against legacy non-`tile:*` channels (datastore-*, window-*,
47
+
context-*, extension-*, chrome-ext:*, oauth-*, screen-*, feature-*,
48
+
sync-full, etc.). Each is a candidate to re-route to a strict
49
+
`tile:*` handler or (if the capability gate is redundant) to delete
50
+
entirely. ~10 sites need validation.
51
+
7. **`IPC_CHANNELS` const** in `backend/config.ts:16-27` — imported by
52
+
`backend/electron/ipc.ts`, `backend/electron/index.ts`,
53
+
`backend/electron/config.ts`. Delete after no callers remain.
54
+
8. **`getRunningExtensions()` / `getAllRegisteredExtensions()` /
55
+
`isConsolidatedExtension()`** — still called from `ipc.ts:1300,1310,
56
+
1323,1333`. Features pane + extension-management IPCs depend on them.
57
+
Need to keep the product surface but rewrite to use
58
+
`getLoadedTileIds()` + `getTileManifest()` instead of the v1 maps.
59
+
60
+
Other minor surfaces:
61
+
- `INTERNAL_URLS` array in `ipc.ts:2306` references
62
+
`peek://app/extension-host.html` for opener-parent detection — follows
63
+
from #1.
64
+
- `tests/fixtures/desktop-app.ts:227` — test helper filters out the
65
+
extension-host window. Follows from #1.
66
+
67
+
---
68
+
69
+
## Dependency graph
70
+
71
+
```
72
+
phase3.1 (audit ext-host deletion feasibility)
73
+
|
74
+
+-- phase3.2 (delete extensionWindows map + friends) [indep]
75
+
|
76
+
+-- phase3.3 (collapse tile-preload izui fallbacks) [indep]
77
+
|
78
+
+-- phase3.4 (audit legacy IPC channels vs callers) [indep, audit-only]
79
+
|
80
+
v
81
+
phase3.5 (rewrite getRunningExtensions / getAllRegisteredExtensions for v2)
82
+
|
83
+
v
84
+
phase3.6 (delete extensionHostWindow + host HTML + broadcaster v1 branch)
85
+
|
86
+
v
87
+
phase3.7 (delete IPC_CHANNELS.* + preload.js consumers) <- depends on 3.4
88
+
|
89
+
v
90
+
phase3.8 (delete preload.js file + cleanup)
91
+
```
92
+
93
+
### Parallelism
94
+
95
+
- **Wave 1 (parallel):** 3.1, 3.2, 3.3, 3.4 — all independent, audit or
96
+
narrowly-scoped delete.
97
+
- **Wave 2 (sequential):** 3.5 after 3.1 (needs audit outcome).
98
+
- **Wave 3:** 3.6 after 3.5.
99
+
- **Wave 4:** 3.7 after 3.4 + 3.6.
100
+
- **Wave 5:** 3.8 after 3.7.
101
+
102
+
---
103
+
104
+
## Work packages
105
+
106
+
### phase3.1 — Audit: can `extensionHostWindow` be removed?
107
+
108
+
**Scope:** Read-only audit. Document whether the 6 smoke-test assertions
109
+
on `peek://app/extension-host.html` represent a real product assertion
110
+
(there must be exactly one extension host window) or are historical. For
111
+
each of the 6 sites in `smoke.spec.ts`, note what the test is actually
112
+
validating and whether the assertion can be rewritten against v2 tile
113
+
windows or deleted. Produce a short report (append to this doc or in a
114
+
commit body) recommending one of: (a) rewrite tests + delete window,
115
+
(b) delete tests + delete window, (c) keep window as empty shell.
116
+
117
+
**Files:**
118
+
- `/Users/dietrich/misc/mpeek/tests/desktop/smoke.spec.ts` (lines 1383,
119
+
4177, 4189, 4359, 5292, 5299, 5379)
120
+
- `/Users/dietrich/misc/mpeek/tests/fixtures/desktop-app.ts:227`
121
+
- `/Users/dietrich/misc/mpeek/tests/README.md:140` (docs reference)
122
+
123
+
**Dependencies:** none
124
+
125
+
**Budget:** 20 min
126
+
127
+
**Validation:** none (audit-only). Commit the recommendation doc.
128
+
129
+
**Risk:** low — no source changes. Output is a decision input for 3.6.
130
+
131
+
---
132
+
133
+
### phase3.2 — Delete `extensionWindows` map + `destroyExtensionWindow` + `getExtensionWindow`
134
+
135
+
**Scope:** After Phase 2.5 #3 deleted `createExtensionWindow()`, nothing
136
+
populates `extensionWindows`. Delete the map, its inserts/deletes, the
137
+
`destroyExtensionWindow` + `getExtensionWindow` exports, and the
138
+
broadcaster loop iterating it. Update callers in `ipc.ts:1199, 1290,
139
+
1333` — they become no-ops returning `false`/`null`, or delete the IPC
140
+
handlers entirely if no tile uses them.
141
+
142
+
**Files:**
143
+
- `/Users/dietrich/misc/mpeek/backend/electron/main.ts` (lines 73-77,
144
+
247-258, 1335-1343, 1393-1397, 1418-1442, 1447-1450)
145
+
- `/Users/dietrich/misc/mpeek/backend/electron/index.ts:149-151`
146
+
- `/Users/dietrich/misc/mpeek/backend/electron/ipc.ts:97-98, 1199,
147
+
1290, 1333`
148
+
149
+
**Dependencies:** none (map is already orphan data)
150
+
151
+
**Budget:** 20 min
152
+
153
+
**Validation:**
154
+
- `yarn tsc --noEmit`
155
+
- `yarn test:unit`
156
+
- `yarn test:electron:bg -g "smoke"` (smoke suite to catch regressions)
157
+
158
+
**Risk:** low — dead code elimination; map is already never populated.
159
+
160
+
---
161
+
162
+
### phase3.3 — Collapse `hasIzuiCapability()` fallback branches in tile-preload
163
+
164
+
**Scope:** Four sites in `tile-preload.cts` have
165
+
`if (!hasIzuiCapability()) return ipcRenderer.invoke('izui-*')`.
166
+
These fall back to legacy non-`tile:*` channels. Every current v2 tile
167
+
with izui needs should declare the `izui` capability. Audit each of the
168
+
4 methods: verify the strict `tile:*` handler exists, verify no
169
+
currently-deployed tile relies on the fallback. Replace with an
170
+
unconditional error throw + remove the fallback branch + remove the
171
+
corresponding `ipcMain.handle('izui-*')` legacy handler in `ipc.ts` if
172
+
no other caller.
173
+
174
+
**Files:**
175
+
- `/Users/dietrich/misc/mpeek/backend/electron/tile-preload.cts` (lines
176
+
1624, 1636, 1644, 1652, 1660)
177
+
- `/Users/dietrich/misc/mpeek/backend/electron/ipc.ts` (`izui-*` handler
178
+
sites — grep first)
179
+
180
+
**Dependencies:** none
181
+
182
+
**Budget:** 20 min
183
+
184
+
**Validation:**
185
+
- `yarn tsc --noEmit`
186
+
- `yarn test:unit`
187
+
- `yarn test:electron:bg -g "izui"` (+ windows-switcher tests, which
188
+
exercise izui heavily)
189
+
190
+
**Risk:** medium — if any tile was silently relying on the fallback
191
+
(i.e. not declaring `izui` capability), it'll start throwing. The audit
192
+
step is the mitigation.
193
+
194
+
---
195
+
196
+
### phase3.4 — Audit: which legacy IPC channels are still live?
197
+
198
+
**Scope:** Read-only. For each of the ~103 `ipcMain.handle/on`
199
+
registrations in `ipc.ts`, grep who calls it. Three buckets per channel:
200
+
(a) only called from `preload.js` → falls when preload.js falls; (b)
201
+
also called from `tile-preload.cts` unconditionally → needs strict
202
+
migration; (c) called from chrome-extension content scripts or other
203
+
non-preload surface → keep. Produce a table: channel → bucket → action.
204
+
Output as a new section in this doc.
205
+
206
+
**Files to grep (callers):**
207
+
- `/Users/dietrich/misc/mpeek/preload.js`
208
+
- `/Users/dietrich/misc/mpeek/backend/electron/tile-preload.cts`
209
+
- `/Users/dietrich/misc/mpeek/chrome-extensions/**` (content scripts)
210
+
- `/Users/dietrich/misc/mpeek/backend/tauri/preload.js` (reference,
211
+
don't touch)
212
+
- `/Users/dietrich/misc/mpeek/app/**` (legacy `app.*` call sites)
213
+
214
+
**Dependencies:** none
215
+
216
+
**Budget:** 30 min (genuine audit with unknown scope — 103 channels)
217
+
218
+
**Validation:** none (audit). Commit audit table.
219
+
220
+
**Risk:** low — read-only. Output drives 3.7 sizing.
221
+
222
+
---
223
+
224
+
### phase3.5 — Rewrite `getRunningExtensions()` / `getAllRegisteredExtensions()` for v2
225
+
226
+
**Scope:** These two functions still read `loadedConsolidatedExtensions`
227
+
+ `extensionWindows` + `declarativeExtensions` + `CONSOLIDATED_EXTENSION_IDS`.
228
+
Rewrite to: running = `getLoadedTileIds()` + `declarativeExtensions` +
229
+
core-renderer ids (cmd/hud/page; hardcoded list since they're explicit).
230
+
Registered = `getRegisteredExtensionIds()` (unchanged) with running-set
231
+
derived the same way. Delete `isConsolidatedExtension()` + the
232
+
`loadedConsolidatedExtensions` adds at lines 1214/1225/1237. Verify
233
+
Features pane still displays everything correctly.
234
+
235
+
**Files:**
236
+
- `/Users/dietrich/misc/mpeek/backend/electron/main.ts` (lines 89, 97,
237
+
1214, 1225, 1237, 1313-1373, 1380-1413, 1462-1464)
238
+
- `/Users/dietrich/misc/mpeek/backend/electron/ipc.ts:100, 1300, 1310,
239
+
1323` (`isConsolidatedExtension` callsite + handlers)
240
+
- `/Users/dietrich/misc/mpeek/backend/electron/index.ts` (if exported)
241
+
242
+
**Dependencies:** phase3.1 (if 3.1 recommends deleting the host window,
243
+
the cleanup is tighter)
244
+
245
+
**Budget:** 30 min
246
+
247
+
**Validation:**
248
+
- `yarn tsc --noEmit`
249
+
- `yarn test:electron:bg -g "features"` (Features pane / settings tests)
250
+
- `yarn test:electron:bg -g "extension-list"` if any exist
251
+
- Manual smoke: launch app, check Settings > Features shows everything.
252
+
253
+
**Risk:** medium — Features pane is a real user-facing surface. Test
254
+
coverage on it may be thin; run a manual smoke.
255
+
256
+
---
257
+
258
+
### phase3.6 — Delete `extensionHostWindow` + host HTML + broadcaster v1 branch
259
+
260
+
**Scope:** Conditional on phase3.1's recommendation being (a) or (b).
261
+
Delete `extensionHostWindow` variable, `createExtensionHostWindow()`,
262
+
`getExtensionHostWindow()`, the `await createExtensionHostWindow()` call
263
+
at `main.ts:1208`, the broadcaster loop iterating host frames
264
+
(`main.ts:226-244`), the `INTERNAL_URLS` reference in `ipc.ts:2306`, and
265
+
the `app/extension-host.html` file. Update smoke tests per 3.1 outcome.
266
+
267
+
**Files:**
268
+
- `/Users/dietrich/misc/mpeek/backend/electron/main.ts` (lines 80, 226-
269
+
244, 767-771, 1103-1176, 1208, 1321, 1386, 1455-1457)
270
+
- `/Users/dietrich/misc/mpeek/backend/electron/ipc.ts:2306`
271
+
- `/Users/dietrich/misc/mpeek/app/extension-host.html` — delete
272
+
- `/Users/dietrich/misc/mpeek/tests/desktop/smoke.spec.ts` (lines per
273
+
3.1)
274
+
- `/Users/dietrich/misc/mpeek/tests/fixtures/desktop-app.ts:227`
275
+
- `/Users/dietrich/misc/mpeek/tests/README.md:140`
276
+
277
+
**Dependencies:** phase3.1 (audit), phase3.5 (rewrites the map consumers
278
+
that reference the host window)
279
+
280
+
**Budget:** 30 min
281
+
282
+
**Validation:**
283
+
- `yarn tsc --noEmit`
284
+
- `yarn test:electron:bg -g "smoke"` (full smoke suite)
285
+
- `yarn test:electron:bg` (full) if smoke passes
286
+
287
+
**Risk:** high — this is the "big one." Deletes a window that's existed
288
+
since the start of v1. Any test or product code still implicitly
289
+
depending on it will break. Phase 3.1's audit is the safety net.
290
+
291
+
---
292
+
293
+
### phase3.7 — Delete unused legacy IPC channels + `IPC_CHANNELS` const
294
+
295
+
**Scope:** For each channel from phase3.4 bucket (a) (only preload.js
296
+
callers), delete the `ipcMain.handle/on(...)` registration in `ipc.ts`.
297
+
For bucket (b) channels, convert the `tile-preload.cts` calls to strict
298
+
`tile:*` paths (audit which need capability gates, which are privileged).
299
+
Delete the `IPC_CHANNELS` const from `backend/config.ts`. Update
300
+
`backend/electron/ipc.ts:121`, `backend/electron/index.ts:13`,
301
+
`backend/electron/config.ts:14` imports. Delete the
302
+
`IPC_CHANNELS.SUBSCRIBE/PUBLISH/CLOSE_WINDOW/REGISTER_SHORTCUT/
303
+
UNREGISTER_SHORTCUT/MODIFY_WINDOW/CONSOLE/RENDERER_LOG/APP_QUIT/
304
+
APP_RESTART` handler blocks at `ipc.ts:4158-4476`.
305
+
306
+
**Files:**
307
+
- `/Users/dietrich/misc/mpeek/backend/electron/ipc.ts` (many lines —
308
+
see phase3.4 output)
309
+
- `/Users/dietrich/misc/mpeek/backend/electron/tile-preload.cts` (the
310
+
~70 `ipcRenderer.invoke('legacy-*')` sites in bucket (b))
311
+
- `/Users/dietrich/misc/mpeek/backend/config.ts:16-27`
312
+
- `/Users/dietrich/misc/mpeek/backend/electron/config.ts:14`
313
+
- `/Users/dietrich/misc/mpeek/backend/electron/index.ts:13`
314
+
315
+
**Dependencies:** phase3.4 (must know bucket per channel), phase3.6
316
+
(host window gone = no frame.send path using IPC_CHANNELS names), phase
317
+
3.2 (broadcaster loop simplified)
318
+
319
+
**Budget:** Split into sub-packages — the whole sweep is too big for
320
+
one agent. Suggested split:
321
+
- **phase3.7a** (20 min): bucket-(a) channels (preload-only callers).
322
+
Just delete the handler and the preload.js wrapper.
323
+
- **phase3.7b** (20 min): window-* channels (~14 channels). Route
324
+
tile-preload calls to existing `tile:window:*` handlers; delete
325
+
legacy window-* handlers.
326
+
- **phase3.7c** (20 min): datastore-* channels (~25 channels). Route
327
+
tile-preload calls to existing `tile:datastore:*` handlers; add
328
+
strict variants where missing.
329
+
- **phase3.7d** (20 min): extension-* + feature-* channels (~12
330
+
channels) + context-* + chrome-ext:* audit — these are the ones
331
+
most likely to need product decisions; may bounce back to user.
332
+
- **phase3.7e** (15 min): `IPC_CHANNELS.*` handlers (9 channels) +
333
+
delete the const.
334
+
335
+
**Validation per sub-package:**
336
+
- `yarn tsc --noEmit`
337
+
- `yarn test:unit`
338
+
- `yarn test:electron:bg` (each sub-package)
339
+
340
+
**Risk:** medium–high per sub-package. Bucket (b) tile-preload sites
341
+
may hit product-critical paths. Split per domain (window/datastore/
342
+
extension) so each agent has a tight scope and the blast radius stays
343
+
small.
344
+
345
+
---
346
+
347
+
### phase3.8 — Delete `preload.js` file + final cleanup
348
+
349
+
**Scope:** After 3.7, nothing should import or use `preload.js`. Delete
350
+
the file. Remove `preloadPath`/`setPreloadPath`/`getPreloadPath` from
351
+
`backend/electron/config.ts`, `entry.ts`, `index.ts`, and the window-open
352
+
fallback at `ipc.ts:2268,2670`. Update `will-attach-webview` in
353
+
`entry.ts:189-211` to drop the v1 fallback branch — all peek:// webview
354
+
children get `tile-preload.cjs` unconditionally (or throw if not a v2
355
+
tile).
356
+
357
+
**Files:**
358
+
- `/Users/dietrich/misc/mpeek/preload.js` — delete (2693 LOC)
359
+
- `/Users/dietrich/misc/mpeek/backend/electron/entry.ts` (lines 63, 152,
360
+
157, 189-211)
361
+
- `/Users/dietrich/misc/mpeek/backend/electron/config.ts` (preload path
362
+
getters/setters)
363
+
- `/Users/dietrich/misc/mpeek/backend/electron/index.ts` (exports)
364
+
- `/Users/dietrich/misc/mpeek/backend/electron/ipc.ts` (lines 119,
365
+
2268, 2670)
366
+
367
+
**Dependencies:** phase3.7 (all buckets) + phase3.6
368
+
369
+
**Budget:** 20 min
370
+
371
+
**Validation:**
372
+
- `yarn tsc --noEmit`
373
+
- `yarn test:unit`
374
+
- `yarn test:electron:bg` (full suite)
375
+
- `git grep preload.js` → should only match comments, docs, or
376
+
Tauri-local copy (which is out of scope per Phase 2.5 #5)
377
+
- `git grep "IPC_CHANNELS\b"` → zero matches
378
+
379
+
**Risk:** medium — the final delete. If anything sneaks through 3.7, it
380
+
breaks here. Mitigation: the tsc + test runs in 3.7 should catch it
381
+
first.
382
+
383
+
---
384
+
385
+
## Out of scope (deferred to Phase 4)
386
+
387
+
- Tauri-side preload migration (`backend/tauri/preload.js`,
388
+
`backend/tauri-mobile/.../include_str!`). Per Phase 2.5 #5 — copy to a
389
+
Tauri-local path if Electron deletion would break `include_str!`.
390
+
- Manifest v3 bump / `type?` field deletion / `windowHints` cleanup —
391
+
Phase 4.
392
+
- `docs/tile-preload-trimming-plan.md`, `docs/tiles-single-file.md`,
393
+
`docs/command-audit.md` doc updates — Phase 4.
394
+
395
+
---
396
+
397
+
## Sizing principle (per feedback_agent_budgets_short.md)
398
+
399
+
All packages target 15–30 min. Packages that hit the ceiling (3.4, 3.6,
400
+
3.7) are the ones with genuine unknowns; if they overrun, the agent
401
+
commits what it has + reports blocker so the next spawn adjusts scope.
402
+
Prefer shipping 5 validated packages over 10 sketchy ones.