Dock Engine Contract#
The web terminal’s dock runs CANOPY’s dock engine, which lives in the CANOPY
screen runtime (packages/dock-engine): the layout model and its
validation, geometry, drop planning, open/close/reopen and hit-testing, as pure
functions with no DOM and no runtime dependencies. OSPREY does not edit it.
What OSPREY holds#
OSPREY holds three things from the runtime. Each is pinned to one runtime
commit and checked by a test under tests/dock_engine/:
What |
Pinned by |
Checked by |
|---|---|---|
The built engine: |
The runtime commit, path and git blob of each, in
|
|
The engine’s cases: the runtime’s |
The runtime commit, path and git blob of each copy, in
|
|
The server’s layout rules:
|
The engine’s cases |
|
The engine files are byte copies of the runtime’s dist/. Their manifest
entries have no URL, so osprey vendor fetch never fetches them: a missing
or changed copy is an error that names the commit to re-copy from. The terminal
serves the engine at /static/vendor/dock-engine.mjs beside dockview.
The server’s rules use the standard library only, so a preset, a layout report or an agent operation is refused for the reason the browser would give.
OSPREY’s policy#
The engine’s layout grammar lets a tile hold several panels (a tile’s tabs
field is a list). OSPREY holds one panel per tile, as a policy of its own
above the engine. It lives in three places: the browser’s dock-policy.js
and dock-open.js, the layout holder dock-apply.js, and the server’s
presets.crowded_tile, which the agent operation routes, the layout report
and the profile build all use. Each refuses a layout with a crowded tile for
the one reason one_panel_per_tile. The vendored engine and its pinned
cases are unchanged: a tile’s tabs is always one entry.
Changing the engine#
A rule changes in the runtime first, with its cases. Then, from one runtime
commit, re-copy the bundle and the two case directories, re-pin them in
cases-pin.json, update the two manifest entries, and change
dock_layout until the cases pass.