experiments in a post-browser web
docs(phase3): 3.8a audit — app/context call surface
+99
+99
docs/v1-removal-phase3-tasks.md
+99
docs/v1-removal-phase3-tasks.md
···
1567
1567
Each agent follows the 25-min ceiling; if any package overruns,
1568
1568
commit-what-you-have + report blocker. Splits noted inline (3.6g, 3.8b,
1569
1569
3.10, 3.11b) are pre-authorised.
1570
+
1571
+
---
1572
+
1573
+
### phase3.8a — context audit (2026-04-18)
1574
+
1575
+
#### Channel inventory in `app/context/*.js`
1576
+
1577
+
| File | IPC channel(s) invoked | Where called |
1578
+
|------|------------------------|--------------|
1579
+
| `app/context/index.js` | `context-set` (in `set()`, line 80) | indirectly via `history.js` import; `set()` is the only IPC path |
1580
+
| `app/context/history.js` | `context-set` (in `save()`, line 56) | called by `index.js::set()` when `persist=true` |
1581
+
| `app/context/history.js` | `context-history` (in `query()`, line 77) | called by `index.js::getHistory()` |
1582
+
| `app/context/history.js` | `context-snapshot` (in `getSnapshot()`, line 110) | called by `index.js::getSnapshot()` |
1583
+
| `app/context/store.js` | _none_ — pure in-memory; no IPC | internal only |
1584
+
1585
+
Channels **not** present in `app/context/*.js`: `context-get`,
1586
+
`context-windows-with-value`, `context-windows-in-space`. Those are
1587
+
exposed by `preload.js::api.context` but are not called directly inside
1588
+
these modules.
1589
+
1590
+
#### Who actually calls `app/context/*.js`?
1591
+
1592
+
**Nobody.** A full-codebase grep finds zero `import … from
1593
+
'peek://app/context/…'`, zero `import … from './context/…'` or similar
1594
+
in any `.js`, `.ts`, `.cts`, or `.html` file outside the three
1595
+
`app/context/` files themselves. The JSDoc comment at the top of
1596
+
`index.js` advertises a `peek://app/context/index.js` URL but no
1597
+
renderer has ever wired it up. `context.init(renderer)` is never called
1598
+
from anywhere — `ipcRenderer` stays `null` in every live session, so
1599
+
the three IPC invocations are dead code today.
1600
+
1601
+
#### Who calls `api.context.*` (tile-preload surface)?
1602
+
1603
+
All live context consumers go through `api.context` on `window.app`,
1604
+
which tile-preload provides. Confirmed callers:
1605
+
1606
+
| File | Methods used |
1607
+
|------|--------------|
1608
+
| `app/cmd/panel.js` | `get`, `setMode`, `watchMode` |
1609
+
| `app/page/page.js` | `get`, `setMode`, `watchMode` |
1610
+
| `app/hud/widgets/mode.js` | `get`, `watchMode` |
1611
+
| `features/spaces/background.js` | `get`, `setMode`, `getWindowsInSpace` |
1612
+
| `features/groups/background.js` | `get`, `setMode`, `getWindowsInSpace` |
1613
+
| `features/groups/home.js` | `setMode` |
1614
+
| `features/editor/home.js` | `setMode` |
1615
+
| `features/entities/background.js` | `set` |
1616
+
1617
+
All renderers listed above load `tile-preload.cjs` (cmd, hud, page via
1618
+
their glue files; spaces, groups, editor, entities as v2 tiles). Every
1619
+
feature tile has a `context` capability declared in its manifest, so
1620
+
they already use `contextStrict` (`tile:context:*` channels). The core
1621
+
builtins (cmd, hud, page) are `trustedBuiltin` grants with no `context`
1622
+
capability key, so they fall through to `contextCompat` (`context-get /
1623
+
context-set / …`) — those six compat branches in tile-preload are the
1624
+
ones that still depend on `preload.js`.
1625
+
1626
+
#### Six `contextCompat` fallback branches in tile-preload
1627
+
1628
+
```
1629
+
contextCompat.get → ipcRenderer.invoke('context-get', …)
1630
+
contextCompat.set → ipcRenderer.invoke('context-set', …)
1631
+
contextCompat.history → ipcRenderer.invoke('context-history', …)
1632
+
contextCompat.snapshot → ipcRenderer.invoke('context-snapshot', …)
1633
+
contextCompat.windowsWithValue → ipcRenderer.invoke('context-windows-with-value', …)
1634
+
contextCompat.windowsInSpace → ipcRenderer.invoke('context-windows-in-space', …)
1635
+
```
1636
+
1637
+
The compat path is taken when `grantedCapabilities.context` is falsy.
1638
+
For cmd/hud/page, the token grant carries `trustedBuiltin: true` but no
1639
+
`context` key, so `hasContextCapability()` returns `false` and every
1640
+
`api.context.*` call in those three renderers hits the compat channels.
1641
+
1642
+
#### Migration path recommendation
1643
+
1644
+
**Option (ii) — add `context` capability to the trustedBuiltin grant
1645
+
for cmd, hud, and page** is the correct migration path.
1646
+
1647
+
`app/context/*.js` is dead code and does not need to be ported or moved;
1648
+
it can be deleted as part of 3.8b. The real migration work is entirely
1649
+
in the backend: `cmd-glue.ts`, `hud-glue.ts`, and `page-glue.ts` (or
1650
+
wherever the trustedBuiltin capability set is assembled) need `context:
1651
+
true` added to the grant so `hasContextCapability()` returns `true` for
1652
+
those windows. Once that is done, the six `contextCompat` fallback
1653
+
branches in `tile-preload.cts` are unreachable and can be deleted along
1654
+
with the matching `ipc.ts` legacy `context-get / context-set /
1655
+
context-history / context-snapshot / context-windows-*` handlers. No
1656
+
consumer renderer needs code changes — they already call `api.context.*`
1657
+
and tile-preload's `api.context` will silently switch to strict channels
1658
+
once the capability is present. Option (i) (a new tile) introduces
1659
+
unnecessary indirection; option (iii) (inline per-renderer) is the same
1660
+
work as option (ii) but harder to validate. Option (ii) is a two-line
1661
+
change to the grant payload and unblocks both the compat-branch delete
1662
+
and the eventual `preload.js` delete.
1663
+
1664
+
**Suggested 3.8b scope update:** delete `app/context/*.js` (three files,
1665
+
currently unreferenced dead code), add `context: true` to the cmd/hud/
1666
+
page trustedBuiltin capability grant in the relevant glue files, delete
1667
+
the six `contextCompat` compat branches from `tile-preload.cts`, and
1668
+
delete the five legacy `context-*` handlers from `ipc.ts`.