samagotchi 0.182.0 → 0.183.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (161) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +68 -1
  3. data/bin/chi +3 -1
  4. data/docs/architecture.md +16 -6
  5. data/docs/bundle-authoring.md +1 -1
  6. data/docs/bundles.md +103 -4
  7. data/docs/cli.md +28 -6
  8. data/docs/configuration.md +2 -1
  9. data/docs/guardrails.md +16 -1
  10. data/docs/internals/block-renderers.md +58 -3
  11. data/docs/internals/bridge.md +13 -5
  12. data/docs/internals/bundles.md +21 -4
  13. data/docs/internals/engine.md +18 -8
  14. data/docs/internals/remote-sessions.md +24 -5
  15. data/docs/internals/web-frontend.md +88 -28
  16. data/docs/internals/working-set.md +1 -1
  17. data/docs/mcp-server.md +80 -0
  18. data/docs/plugins.md +308 -21
  19. data/docs/sessions.md +3 -3
  20. data/docs/sub-agent.md +9 -0
  21. data/docs/testing.md +3 -1
  22. data/docs/thin-clients.md +146 -0
  23. data/lib/samagotchi/bridge/pending_card.rb +4 -3
  24. data/lib/samagotchi/bridge/sse_writer.rb +16 -15
  25. data/lib/samagotchi/bridge.rb +59 -68
  26. data/lib/samagotchi/bundle_command/api_calls.rb +1 -1
  27. data/lib/samagotchi/bundle_command/check.rb +36 -19
  28. data/lib/samagotchi/bundle_command.rb +50 -21
  29. data/lib/samagotchi/bundle_manifest.rb +101 -4
  30. data/lib/samagotchi/bundles/dev/manifest.yml +2 -2
  31. data/lib/samagotchi/bundles/mcp/client.rb +260 -0
  32. data/lib/samagotchi/bundles/mcp/content.rb +107 -0
  33. data/lib/samagotchi/bundles/mcp/http_client.rb +407 -0
  34. data/lib/samagotchi/bundles/mcp/manifest.yml +13 -5
  35. data/lib/samagotchi/bundles/mcp/oauth.rb +814 -0
  36. data/lib/samagotchi/bundles/mcp/plugin.rb +556 -574
  37. data/lib/samagotchi/bundles/mcp/tools.rb +232 -0
  38. data/lib/samagotchi/bundles/system/config_modification_protocol.md +10 -2
  39. data/lib/samagotchi/bundles/system/manifest.yml +2 -2
  40. data/lib/samagotchi/cli/parent_wait.rb +5 -3
  41. data/lib/samagotchi/command_intake.rb +7 -0
  42. data/lib/samagotchi/commands/registry.rb +8 -3
  43. data/lib/samagotchi/continue_offer.rb +24 -15
  44. data/lib/samagotchi/engine/block_fix.rb +4 -4
  45. data/lib/samagotchi/engine/cards.rb +14 -5
  46. data/lib/samagotchi/engine/events.rb +10 -15
  47. data/lib/samagotchi/engine/models.rb +1 -1
  48. data/lib/samagotchi/engine/plugins.rb +3 -0
  49. data/lib/samagotchi/engine/recap.rb +1 -1
  50. data/lib/samagotchi/engine/side_requests.rb +1 -1
  51. data/lib/samagotchi/engine/sign_in.rb +142 -0
  52. data/lib/samagotchi/engine/turn_end.rb +3 -3
  53. data/lib/samagotchi/engine.rb +43 -27
  54. data/lib/samagotchi/engine_snapshots.rb +1 -1
  55. data/lib/samagotchi/guardrail_wiring.rb +3 -1
  56. data/lib/samagotchi/guardrails/protected_paths.rb +51 -2
  57. data/lib/samagotchi/guardrails/verdict.rb +3 -2
  58. data/lib/samagotchi/hold_stop.rb +4 -4
  59. data/lib/samagotchi/idle_recap.rb +19 -11
  60. data/lib/samagotchi/idle_reminders.rb +7 -5
  61. data/lib/samagotchi/idle_scheduler.rb +7 -10
  62. data/lib/samagotchi/installed_bundles/dir.rb +37 -0
  63. data/lib/samagotchi/installed_bundles/manifest.rb +7 -1
  64. data/lib/samagotchi/installed_bundles/plugin_ref.rb +9 -5
  65. data/lib/samagotchi/installed_bundles/record.rb +3 -2
  66. data/lib/samagotchi/installed_bundles/standing.rb +3 -1
  67. data/lib/samagotchi/llm/http.rb +96 -5
  68. data/lib/samagotchi/mcp_command.rb +110 -0
  69. data/lib/samagotchi/mcp_server/http.rb +112 -0
  70. data/lib/samagotchi/mcp_server/protocol.rb +244 -0
  71. data/lib/samagotchi/mcp_server/stdio.rb +92 -0
  72. data/lib/samagotchi/mcp_server/text.rb +155 -0
  73. data/lib/samagotchi/mcp_server/tools.rb +245 -0
  74. data/lib/samagotchi/memory_bundle/asset_installer.rb +40 -12
  75. data/lib/samagotchi/memory_bundle/builder.rb +20 -2
  76. data/lib/samagotchi/memory_bundle/installed_copy.rb +1 -1
  77. data/lib/samagotchi/memory_bundle/installer.rb +16 -3
  78. data/lib/samagotchi/memory_bundle/provenance.rb +18 -1
  79. data/lib/samagotchi/memory_bundle/shas.rb +6 -4
  80. data/lib/samagotchi/memory_bundle/shipped_update.rb +7 -3
  81. data/lib/samagotchi/memory_bundle/status.rb +15 -6
  82. data/lib/samagotchi/memory_bundle/uninstaller.rb +9 -4
  83. data/lib/samagotchi/plugin/api.rb +6 -1
  84. data/lib/samagotchi/plugin/card.rb +36 -11
  85. data/lib/samagotchi/plugin/context.rb +63 -6
  86. data/lib/samagotchi/plugin/http.rb +40 -15
  87. data/lib/samagotchi/plugin/http_errors.rb +15 -0
  88. data/lib/samagotchi/plugin/http_stream.rb +86 -0
  89. data/lib/samagotchi/plugin/http_transport.rb +58 -16
  90. data/lib/samagotchi/plugin/loader.rb +18 -11
  91. data/lib/samagotchi/plugin/secrets.rb +266 -0
  92. data/lib/samagotchi/plugin/sign_in.rb +392 -0
  93. data/lib/samagotchi/plugin/sse_reader.rb +103 -0
  94. data/lib/samagotchi/queued_command.rb +28 -4
  95. data/lib/samagotchi/recap_setup.rb +13 -4
  96. data/lib/samagotchi/ref.rb +3 -2
  97. data/lib/samagotchi/relay_verifier.rb +8 -7
  98. data/lib/samagotchi/relay_watcher.rb +4 -4
  99. data/lib/samagotchi/run_options.rb +2 -1
  100. data/lib/samagotchi/send_command.rb +54 -41
  101. data/lib/samagotchi/session_access/ask.rb +244 -0
  102. data/lib/samagotchi/session_access/contract.rb +5 -0
  103. data/lib/samagotchi/session_access/exchange/token.rb +101 -0
  104. data/lib/samagotchi/session_access/exchange.rb +173 -0
  105. data/lib/samagotchi/session_access/local.rb +25 -6
  106. data/lib/samagotchi/session_access/remote.rb +4 -1
  107. data/lib/samagotchi/session_command_catalog.rb +10 -0
  108. data/lib/samagotchi/session_commands.rb +17 -0
  109. data/lib/samagotchi/session_config.rb +4 -4
  110. data/lib/samagotchi/session_observer.rb +27 -0
  111. data/lib/samagotchi/steer_cut.rb +4 -3
  112. data/lib/samagotchi/terminal_ui/attached_loop/sending.rb +4 -1
  113. data/lib/samagotchi/terminal_ui/formatting.rb +15 -0
  114. data/lib/samagotchi/testing/boundary.rb +4 -0
  115. data/lib/samagotchi/testing/bundle.rb +48 -2
  116. data/lib/samagotchi/testing/fake_http.rb +60 -15
  117. data/lib/samagotchi/testing/host.rb +4 -1
  118. data/lib/samagotchi/testing/recorder.rb +45 -5
  119. data/lib/samagotchi/tools/tool_index.rb +14 -3
  120. data/lib/samagotchi/version.rb +1 -1
  121. data/lib/samagotchi/web/app.rb +8 -6
  122. data/lib/samagotchi/web/ask_routes.rb +292 -0
  123. data/lib/samagotchi/web/mcp_route.rb +88 -0
  124. data/lib/samagotchi/web/public/app.js +2 -3
  125. data/lib/samagotchi/web/public/block_frame.js +72 -11
  126. data/lib/samagotchi/web/public/block_host.js +44 -8
  127. data/lib/samagotchi/web/public/block_regions.js +126 -0
  128. data/lib/samagotchi/web/public/card.js +22 -9
  129. data/lib/samagotchi/web/public/card_actions.js +21 -0
  130. data/lib/samagotchi/web/public/card_kinds.js +1 -1
  131. data/lib/samagotchi/web/public/card_registry.js +3 -2
  132. data/lib/samagotchi/web/public/data.js +15 -12
  133. data/lib/samagotchi/web/public/delete_sheet.js +222 -162
  134. data/lib/samagotchi/web/public/diagram_wiring.js +28 -0
  135. data/lib/samagotchi/web/public/format.js +3 -0
  136. data/lib/samagotchi/web/public/index.html +52 -7
  137. data/lib/samagotchi/web/public/more_sheet.js +6 -4
  138. data/lib/samagotchi/web/public/picture_regions.js +243 -0
  139. data/lib/samagotchi/web/public/picture_viewer.js +113 -12
  140. data/lib/samagotchi/web/public/refs.js +5 -3
  141. data/lib/samagotchi/web/public/region_hit.js +144 -0
  142. data/lib/samagotchi/web/public/removal_sheet_model.js +275 -0
  143. data/lib/samagotchi/web/public/running_tasks.js +6 -4
  144. data/lib/samagotchi/web/public/session_actions.js +105 -100
  145. data/lib/samagotchi/web/session_access_routes.rb +14 -11
  146. data/lib/samagotchi/web/session_control.rb +31 -9
  147. data/lib/samagotchi/web/session_create.rb +2 -2
  148. data/lib/samagotchi/worker/child_side.rb +3 -2
  149. data/lib/samagotchi/worker/command_queue.rb +13 -13
  150. data/lib/samagotchi/worker/leave.rb +3 -3
  151. data/lib/samagotchi/worker/scratch.rb +6 -6
  152. data/lib/samagotchi/worker/signal_grace.rb +6 -5
  153. data/lib/samagotchi/worker/startup.rb +3 -3
  154. data/lib/samagotchi/worker/wake_turns.rb +4 -4
  155. data/lib/samagotchi/worker.rb +32 -21
  156. data/lib/samagotchi/worker_exit_claim.rb +1 -1
  157. data/lib/samagotchi/worker_idle_exit.rb +18 -9
  158. data/lib/samagotchi/worker_inbound.rb +12 -7
  159. data/lib/samagotchi/worker_participant_gate.rb +9 -7
  160. data/lib/samagotchi/worker_task_wakes.rb +7 -5
  161. metadata +31 -1
@@ -19,7 +19,7 @@ model. The TUI is untouched: it shows a fence as source.
19
19
  `renderer_changed`, each with its own reason. ETag + `no-cache`, as static files. A `block_renderers:` list that
20
20
  doesn't parse is logged once per bundle and problem (each list request and file fetch reads it); a bundle this chi is
21
21
  too old for (`requires_chi`) draws nothing, logged once per bundle and version (`block_renderers_too_new`).
22
- 3. `block_watch.js` (`createBlockWatch`, made by `block_host.js`'s `createBlockHost`, wired in `app.js`; a participant's page
22
+ 3. `block_watch.js` (`createBlockWatch`, made by `block_host.js`'s `createBlockHost`, wired by `diagram_wiring.js wireDiagrams` from `app.js`; a participant's page
23
23
  gets the core drawers only, no bundle's renderers: `block_renderers`) finds and watches the blocks; `block_host.js` is its frame drawer (`createFrameDrawer`). The watcher asks an
24
24
  ordered list of drawers, core ones first (`inline_widgets.js` for `chi-ui`: [inline-widgets.md](inline-widgets.md)), then the frame drawer, which waits for `/api/block_renderers`;
25
25
  the first that `claims` the block's language draws it, and a language none claims is left alone. The contract
@@ -35,7 +35,14 @@ model. The TUI is untouched: it shows a fence as source.
35
35
  4. `block_frame.js` (`createBlockFrame`): one hidden frame per language, made on first need, one render at a time, 15 s per
36
36
  call, the renderer files' fetch included (browser `fetch` has no timeout; a fetch past it is a failed load). A timeout, a
37
37
  dead frame or a session switch drops it, and a drop rejects whatever is pending, the load too. Handshake `loaded` → `code {files}` → `ready | failed`,
38
- then `render {id, source, theme}` → `done {id, svg} | error {id, message}`.
38
+ then `render {id, source, theme}` → `done {id, svg, regions?} | error {id, message, bundle?}`. The bootstrap's
39
+ `window.chi` is `{ defineRenderer, features: { regions: true } }`: a renderer returns the SVG, or `{ svg, regions }`
40
+ ([Regions](#regions)). An object without a string `svg` is the bundle's bug, `error {bundle: true}`: its
41
+ `FrameError` isn't `renderer`, so the block fails with its line and no fix is asked; a renderer that throws, or
42
+ returns no object at all (`undefined`, `null`, a number), is as before: a failed render that may be the model's
43
+ (a renderer can return nothing for a source it can't draw), so `renderer` and fixable. Kept so on purpose: the
44
+ bundle flag is for what only a bundle returns (an object), and a bundle's measuring stays inside its own `try`.
45
+ `createBlockFrame`'s `draw` resolves `{svg, regions}` (`render`, its SVG alone, stays); `block_host.js` uses `render` when a cached older `block_frame.js` has no `draw`.
39
46
  5. On success a `<figure class="block-drawn">` goes right before the `<pre>`, which stays in the DOM, `hidden`, so whatever
40
47
  reads text (copy, a claim's walk, fold thresholds) sees what it did. **The DOM is the state** (`block_source.js`): a Revise
41
48
  clone arrives with both. On failure the `<pre>` stays, marked `data-block-failed`, with one muted line: an attribute CSS
@@ -48,7 +55,9 @@ model. The TUI is untouched: it shows a fence as source.
48
55
  movable there; without `openPicture` (an older app.js) a click does nothing. The same is a `.block-zoom` button
49
56
  ("Open in the viewer": icon, `aria-label`) for the keyboard: before the toggle, shown on keyboard focus only, and
50
57
  taking no pointer while hidden; Esc in the viewer gives it the focus back.
51
- 6. Cache: a `Map` on `lang + theme + source`, about 200 entries, holding the `data:` URL; a later `bubble.innerHTML` wipes the
58
+ 6. Cache: a `Map` on `lang + theme + source`, about 200 entries, holding the `data:` URL and, when the renderer reported
59
+ some, the cleaned regions (so a cache hit, a Revise clone and a theme's redraw carry their own; a click finds the
60
+ entry by the `<img>`'s `src`, `pictureOfFigure`, at most 200 compares: an evicted entry gives the picture alone); a later `bubble.innerHTML` wipes the
52
61
  figure and the observer redraws in the same pass. No `crypto.subtle`: it's undefined on a plain-http LAN address. A system
53
62
  theme change redraws through the figure (a hidden `<pre>` never intersects).
54
63
  7. The view: a viewer at the bottom stays there (`scroll.js keepFollowing`); a block drawn above a reader's view keeps
@@ -63,6 +72,51 @@ model. The TUI is untouched: it shows a fence as source.
63
72
  `max-height` says the same number, a backstop whatever the parsing gets wrong. The decode is bounded too
64
73
  (15 s, the mark on until it ends). A very wide picture stays at least 120 px tall and scrolls sideways instead of a sliver.
65
74
 
75
+ ## Regions
76
+
77
+ A renderer may report where a diagram's parts are, so the picture viewer can make them tappable
78
+ ([web-frontend.md](web-frontend.md#picture-viewer)). What it returns beside its SVG, and what the page keeps:
79
+
80
+ ```js
81
+ { kind: "node" | "group" | "edge" | "note",
82
+ id: "BR", // the source's own name, text; "" when none
83
+ label: "Bridge", // what the picture shows, text; "" when none
84
+ box: [x, y, w, h], // fractions of the picture, 0..1; required but for an edge (its label's box)
85
+ points: [[x, y], …], // edge only: 2..16 points along its line
86
+ from: "BR", to: "EN" // edge only, optional: its ends' ids
87
+ }
88
+ ```
89
+
90
+ **Regions are untrusted**: the bundle is trusted, its input is model-written, and a renderer bug must not reach the
91
+ page or stall it. Two gates:
92
+
93
+ 1. **In the frame** (`BOOTSTRAP`): `regions` is sent only when it is an array of at most 600 (`MAX_REGIONS`); otherwise
94
+ the `done` carries none and nothing of it is cloned (a 2M-entry array took 0.4 s in Chromium and 1.4 s in WebKit to
95
+ post, on the page's thread). And what is posted is the frame's **bounded copy** of each entry: its known keys only,
96
+ strings cut to 200 characters (anything else `""`), a box only of 4, at most 16 points, numbers only (else `NaN`),
97
+ a non-object entry `null`; so nothing vast or uncloneable is ever cloned (600 regions with one-megabyte labels,
98
+ posted as they were, crashed a Chromium tab; copied, the render took 2.6 ms in Chromium and 1 ms in WebKit against
99
+ 0.2 and 0 without regions). Regions that throw when read (a proxy) are dropped, and a post that throws anyway is
100
+ sent again without them.
101
+ 2. **In the page**, `block_regions.js cleanRegions` (pure), before the picture is cached: not an array, or over 600 →
102
+ none; a running budget of 128 KB over the *cleaned* fields (kept strings' lengths, 12 per number), past it → none
103
+ (`MAX_REGION_BYTES`); an entry that isn't a plain object or whose `kind` isn't one of the four → skipped; `box`
104
+ exactly 4 finite numbers, clamped to 0..1 and cut to the picture, no area → skipped (an edge loses its box);
105
+ `points` 2..16 pairs of finite numbers, clamped, else the edge is skipped; `id`, `label`, `from`, `to` strings only
106
+ (never `String()` of an object), controls and line separators a space, bidi, zero-width and lone surrogates gone,
107
+ whitespace runs one space, cut by code points to 80 (`label` 120); only own keys of known names are read, and the
108
+ result is new objects. A region left with no name is skipped (a node, note or group with neither `label` nor
109
+ `id`; an edge with no `label` and not both ends): the card and a button name a region by the diagram's own text
110
+ only, and the page never makes one up (a "node 3" means nothing in the source, nor to the model). Nothing stringifies the raw data (structured clone keeps cycles and BigInt). A list dropped
111
+ whole is said once per language (`console.warn`, its count, no model text). **Never cut**: past a cap the picture
112
+ shows with nothing tappable.
113
+
114
+ **What the page does with a region's text: `textContent`, an `aria-label`, composer text. Never markup, a selector, a
115
+ URL, a `data-*` value another module reads back, or a key into an object.** Numbers become percent offsets in
116
+ `style` and the points of the page's own `<polyline>`, through lit bindings. Nothing reaches the server, a session
117
+ file, the DOM of an answer or the model. Cost: 1–2 ms per render in the frame (measuring is the bundle's), one
118
+ `cleanRegions` per render in the page, 1–4 KB a real diagram in the cache.
119
+
66
120
  ## A failed block is asked for again
67
121
 
68
122
  One mechanism for every drawn block, a `chi-ui` picks or walk (core's drawer) and a bundle's renderer (chi-mermaid's
@@ -189,6 +243,7 @@ is model-written**, so a renderer bug or an injected diagram must not reach a pa
189
243
  | Page header `frame-src 'none'` (`App::FRAME_HEADERS`; srcdoc frames still load and run under it) | self-navigation, meta refresh, anchor click, which leak past the frame's CSP in both browsers |
190
244
  | `delete window.RTCPeerConnection` + `webkitRTCPeerConnection` in the bootstrap, before any bundle code | the plain WebRTC call only |
191
245
  | Output only as `<img src="data:…">` | scripts and remote images inside the SVG don't run or load |
246
+ | Regions capped in the frame, cleaned in the page (`block_regions.js`), used as text and numbers only | a renderer's regions as markup, a selector or a URL; a vast or uncloneable list stalling the page |
192
247
 
193
248
  **Hard rules.**
194
249
 
@@ -5,12 +5,19 @@ localhost HTTP server in the worker's process, next to the `Engine` it reads and
5
5
  terminal are its clients; no browser reaches it. [architecture.md](../architecture.md) places it among the layers;
6
6
  this page is the surface: what it keeps, how a client joins and catches up, and every route.
7
7
 
8
- Bridge Engine calls are listed with their reasons in `Bridge::ENGINE_CALLS`; add each new Engine call there.
8
+ Bridge Engine calls are listed with their reasons in `Bridge::ENGINE_CALLS`; add each new Engine call there. Four of
9
+ the Engine's parts are not among them: `Bridge.new` takes them as `event_log:`, `turn_state:`, `question_desk:` and
10
+ `steer_cut:` (the Engine's own `SessionObserver`, `TurnState`, `QuestionDesk` and `SteerCut`: `Engine#event_log`,
11
+ `#turn_state`, `#question_desk`, `#steer_cut`, handed on by the Worker) and calls them directly: `subscribe`,
12
+ `unsubscribe`, `event_count`, `announce` and `synchronize` on the log; `running?`, `controller`, `cancel!` and the
13
+ enqueued-id ledger on the turn state; `pending`, `answer`, `cancel` and `annotate` on the desk; `input_epoch`,
14
+ `cut_for_steer` and `generation_snapshot` on the cut. `ENGINE_CALLS` lists what is left.
9
15
 
10
16
  ## What a Bridge keeps
11
17
 
12
- `Bridge#start` binds a port (OS-assigned, `127.0.0.1`), then subscribes four persistent observers to the Engine
13
- (`Engine#subscribe`, the thread-safe fan-out whose events all carry a monotonic `event_seq`). Each is cheap and
18
+ `Bridge#start` binds a port (OS-assigned, `127.0.0.1`), then subscribes five persistent observers to the event log
19
+ (`SessionObserver#subscribe`, the thread-safe fan-out whose events all carry a monotonic `event_seq`): the capture
20
+ observer (feeding the ring), the accumulator, the drawings, the cards and the pending card. Each is cheap and
14
21
  rescues its own errors: an observer must never break the running turn.
15
22
 
16
23
  | Piece | File (`bridge/`) | Holds |
@@ -265,7 +272,8 @@ the "asking again" and steer-cut rows, ✂ rows and questions (with how they wer
265
272
 
266
273
  ## SSEWriter
267
274
 
268
- One per `GET /session/:id/stream` connection, and itself that connection's observer: `Engine#emit_event` calls
275
+ One per `GET /session/:id/stream` connection, and itself that connection's observer (it takes the event log, no
276
+ Engine): `Engine#emit_event` calls
269
277
  `#call` on the turn's thread, so it only pushes onto a `BoundedQueue` (when full, the oldest entry goes and an
270
278
  overflow flag is set). The connection's own thread (`#serve!`) drains the queue onto the socket, so a slow client
271
279
  cannot stall a turn or another subscriber. An event holding bytes JSON can't take goes out scrubbed
@@ -278,7 +286,7 @@ ring holds the event. `serve!` orders a join so that nothing is missed or double
278
286
  4. drain the queue for `seq > snapshot`; a per-connection high-water mark drops what step 3 already wrote.
279
287
 
280
288
  `?snapshot=1` replaces 2-3: subscribe and `Bridge#snapshot_frame` happen as one step with the event log held
281
- (`Engine#synchronize_events`), the client gets one `snapshot` frame, and live events follow from the next seq.
289
+ (`SessionObserver#synchronize`), the client gets one `snapshot` frame, and live events follow from the next seq.
282
290
 
283
291
  A **`reset`** frame (the same content, numbered with its own seq) is written when a cursor cannot be replayed: it is
284
292
  from another epoch, ahead of the engine (a restarted worker), behind the ring's window (a cursor at `oldest - 1` has
@@ -41,7 +41,7 @@ read side, never the reverse.
41
41
  | Piece | Role |
42
42
  |---|---|
43
43
  | `InstalledBundles` (`installed_bundles.rb`) | `.each(holding:, dir:)` (each installed bundle by name, its `Record`; one whose `manifest.json` doesn't read with `error` set, and with `holding:` only those with that key, or that dir when it doesn't read), `.claimants` (which bundles own a memory file), `.dir` (`MemoryPaths.bundles_dir`) |
44
- | `InstalledBundles::Dir` (installed_bundles/dir.rb) | one bundle's `.bundles/<name>/` as the runtime reads it: `Dir.new(name:, dir:)`, `#record`, `#plugin_dir`, `#plugin_path`, `#scripts_dir`, `#guardrails_dir`, `#kept_manifest_path`, `#file_refusal(kind, file, recorded)` (the one "is this installed file as installed" check: `:plugin`, `:scripts`, `:guardrails`, one order (no sha recorded, missing, changed) and one wording, `bundle X's <folder>/<file> isn't recorded / is missing / differs from the installed one (reinstall the bundle)`, a `Refusal`). Its only state is the name and the folder; `Provenance` is one |
44
+ | `InstalledBundles::Dir` (installed_bundles/dir.rb) | one bundle's `.bundles/<name>/` as the runtime reads it: `Dir.new(name:, dir:)`, `#record`, `#plugin_dir`, `#plugin_path`, `#scripts_dir`, `#guardrails_dir`, `#kept_manifest_path`, `#plugin_part_paths`, `#plugin_refusal(record)` (the whole plugin: the file's `file_refusal`, then each part's in load order, then `:parts_missing`, below; the loader, `Status.plugin_status` and `SessionConfig#unloadable` ask it), `#file_refusal(kind, file, recorded)` (the one "is this installed file as installed" check: `:plugin`, `:scripts`, `:guardrails`, one order (no sha recorded, missing, changed) and one wording, `bundle X's <folder>/<file> isn't recorded / is missing / differs from the installed one (reinstall the bundle)`, a `Refusal`). Its only state is the name and the folder; `Provenance` is one |
45
45
  | `InstalledBundles::Standing`, `Refusal` (installed_bundles/standing.rb) | the usability verdict: `.standings(holding:, dir:)` (the walk, each bundle's `Standing`), `.standing(name, dir:)` (one record; a `manifest.json` that doesn't parse is `:unreadable`, in the walk's words), `Standing.of(name, record)`: `#refusal` is `:unreadable` (the record; `Standing.warn_unreadable` logs `bundle_unreadable` once per process per bundle and reason, whichever reader came across it, `.claimants` too) or `:too_new` (requires_chi), nil when chi may use it; none of the bundle's own files is hashed (a manifest cache miss hashes the kept `manifest.yml`, as `Manifest.of` does). A `Refusal` has `kind`, `text` and, for `:file_changed`, the `actual` and `expected` shas. Each reader keeps only its reaction (below) |
46
46
  | `InstalledBundles::Sha` (installed_bundles/sha.rb) | the record's shas: `.recorded` (either format, `""` for none), `.of_file`, `DEV` (a dev install's `sha256:dev`), `.unchecked?`, `.matches?` |
47
47
  | `BundleCommand` (`lib/samagotchi/bundle_command.rb`) | `chi bundle install/upgrade/uninstall/status/diff/list/build/trash/new/test/check/try` (`install --dev`: the Installer's `dev:`, links and `InstalledBundles::Sha::DEV`); runs the Installer, prints its summary, runs the conflict agent step; refuses a source already installed under another name (`installed_under_another_name?`: a git URL bundle recorded under its repo's name before the manifest named it). `upgrade` resolves its argument by `upgrade_source`: a git URL or an existing path, then a shipped name, then the bare name of an installed bundle — whose record's source it then uses (a git URL with its `#ref`, a dir or an archive that is still there), printed as `Upgrading NAME from SOURCE`; a dev record is refused with `Installer.dev_install_line`, a recorded source that is relative, empty or gone says so and asks for the path or URL of a copy (`Installer.source_gone_line`, the words `ManifestStanding` uses too). After an upgrade or uninstall that changed the bundle's plugin (or brought one in), one line names the sessions still running its old code (`LiveVersions.workers`, the ones whose worker takes a restart) and `chi sessions restart ID` for each: only the plugin stays in memory, since a bundle's rules reload by their stamp and its scripts run from the replaced files. |
@@ -50,7 +50,7 @@ read side, never the reverse.
50
50
  | `BundleCommand::ApiCalls` (bundle_command/api_calls.rb) | what a plugin's source calls of the API, by Prism: `#findings` (a call or keyword the API's classes lack, `check`'s `api`), `#keywords` (the floor check's `call(keyword:)`). Its only list is `MEMBERS`, which object a member gives (`ctx.sessions` → `Plugin::Sessions`); a new such object joins it |
51
51
  | `BundleCommand::Scaffold` (bundle_command/scaffold.rb) | `chi bundle new NAME`: the starting files (block-form `plugin:` entry, `requires_chi` at this chi, a kit test that passes as written); the manifest's shas are filled through `Shas.refresh` |
52
52
  | `BundleCommand::TestRun` (bundle_command/test_run.rb) | `chi bundle test`: `RbConfig.ruby -I <chi's lib>` on `test/**/*_test.rb` (Minitest) or `spec/` (RSpec, as `rake bundles:specs`), under `Bundler.with_unbundled_env` when Bundler's runtime is loaded |
53
- | `Shas` (shas.rb) | a manifest's `sha256:` lines: `.refresh(dir[, text])` rewrites them line by line (the layout kept; a `files:` entry it can't place raises `Shas::Error`), `.stale` → `[Stale(file, old, new)]` (`old` `""` for a placeholder, nil for a plugin / script entry with no sha line), `.parseable` (a placeholder `sha256: sha256:` isn't YAML). Plain Ruby: `rake bundles:sha` / `bundles:check` (`script/release/release_tools.rb`) and `chi bundle check --fix` share it |
53
+ | `Shas` (shas.rb) | a manifest's `sha256:` lines (a plugin part's is a four-space `name.rb: sha256:<hex>` line under `plugin:` `parts:`, the file being the part's name in the bundle dir): `.refresh(dir[, text])` rewrites them line by line (the layout kept; a `files:` entry it can't place raises `Shas::Error`), `.stale` → `[Stale(file, old, new)]` (`old` `""` for a placeholder, nil for a plugin / script entry with no sha line), `.parseable` (a placeholder `sha256: sha256:` isn't YAML). Plain Ruby: `rake bundles:sha` / `bundles:check` (`script/release/release_tools.rb`) and `chi bundle check --fix` share it |
54
54
  | `InstalledBundles::FileDigest` (installed_bundles/file_digest.rb) | the one digest of a file on disk: `.hex(path)` (its bytes, streamed; nil when the path isn't a file, a raise for one that can't be read), `.sha256(path)` = `"sha256:<hex>"`, nil with no file — the shape a record writes for a rule, plugin or script. `InstalledBundles::Sha.of_file`, `Merger.digest`, `Status.checksum`, `InstalledBundles::Record#source_sha`, `FileStanding.differs?` and the Installer's checksum verifiers all go through it; a digest of bytes already in memory (a merge's text, a memory's content that is also its base) stays with the code holding them |
55
55
  | `SourceNormalizer` (source.rb) | source → local dir; a git/zip/tar extract is *owned* and removed after the install |
56
56
  | `SourceIdentity` (source.rb) | what a source is, for comparing two installs of one name: `shipped:<dir>` (any gem or checkout), `git:<url>` (no `#ref`, trailing `/` or `.git`), `path:<realpath>`; nil when it can't place one |
@@ -126,9 +126,10 @@ A guardrail plugin (`plugin:` `required: true`) is known from `InstalledBundles:
126
126
  unparsable kept manifest.yml never drops it (an older chi's `PluginRef` ignores the key):
127
127
  its failure goes to the hook failures as required (`ExtensionLoad#load_plugins` passes them as `guardrail_failures:`),
128
128
  where the gate denies every tool call; a `chi.on(on_error: :fail_closed)` hook is wrapped `Hooks.wrap(policy: :deny)`.
129
- `Plugin::Loader.load_bundle` asks the verdict (`InstalledBundles::Standing`, then `Dir#file_refusal(:plugin, …)`) and reacts (`.namespace_for` is the bundle's
129
+ `Plugin::Loader.load_bundle` asks the verdict (`InstalledBundles::Standing`, then `Dir#plugin_refusal`) and reacts (`.namespace_for` is the bundle's
130
130
  `Samagotchi::Bundles::<bundle>` module); the loading itself is `Plugin::Loader.register_file` (one
131
- plugin file: build, `register`, `commit!`), which raises instead of logging: the bundle test kit
131
+ plugin: its `parts:` `module_eval`'d in order, each with its own path, then the file, into one fresh module; build,
132
+ `register`, `commit!`), which raises instead of logging: the bundle test kit
132
133
  (`Samagotchi::Testing::Bundle`) loads a bundle's source through them, unchecked. `Samagotchi::Testing::Install` is the
133
134
  checked path in a sandbox: the Installer, then `ExtensionLoad` (config hooks, then `load_plugins`), returning the
134
135
  Installer's warnings, this bundle's load failures and what it registered (`Install.registered`, an `Install::Registered` value, also the parity
@@ -136,6 +137,22 @@ spec's shape). A load failure carries `LoadFailures::Failure#location` (the firs
136
137
  bundle, or a SyntaxError's own line), which `Install` maps from the installed copy (`.bundles/<name>/plugin/`)
137
138
  back to the source dir.
138
139
 
140
+ Plugin parts (`plugin:` `parts:`, docs/plugins.md "A plugin in several files"). `BundleManifest#plugin_files` is the
141
+ one ordered list (parts as listed, then the file; nothing sorts it: not the parser, `Provenance#write` or the
142
+ builder). The record keeps them under its plugin, `{"file": …, "sha256": …, "parts": {"client.rb": "sha256:…"}}`
143
+ (`PluginRef#parts`, `{}` without; `Record#plugin_shas` has every file, so `AssetInstaller`, the `Uninstaller` and
144
+ `ShippedUpdate#trash_bound` treat parts as recorded files), each with a base at `bases/plugin/<part>`.
145
+ `BundleManifest::SINCE` has `"plugin.parts"` (the Unreleased comment until `release:bump`). What other chis do:
146
+ - The previous release ignores `parts:` in a manifest and in a record. It installs a too-new plugin with only a
147
+ warning, copying the plugin file alone; after `chi update` this chi refuses that record: `Dir#plugin_refusal`'s
148
+ `:parts_missing` (`bundle X's plugin parts aren't installed (reinstall the bundle)`, status `[parts missing]`), read
149
+ from `InstalledBundles::Manifest#plugin_parts` (the kept manifest's part names, the record's when it isn't read: no
150
+ kept file, or an edited one, is no refusal of this kind).
151
+ - On its own uninstall or upgrade of a record with parts, the parts in `plugin/` are files its record doesn't name:
152
+ `AssetState.in` lists every file in the folder, so they count as edited, get a copy in the trash, and go with the
153
+ folder. Harmless.
154
+ - This chi reads an older record with no `parts` key as no parts: nothing to migrate.
155
+
139
156
  Class-file hooks (retired). A record an older chi installed may still have a `hooks` map and `hooks/*.rb`
140
157
  (`InstalledBundles::Record#hooks`). Nothing loads them, and nothing announces them any more (the first turn, `chi bundle
141
158
  status` and `chi update` did from 0.158 to 0.166). A source with
@@ -124,7 +124,7 @@ Interrupt (Ctrl-C; a one-shot only, a worker traps INT):
124
124
  interrupted result (ToolResponse.run_batch), so no call is kept without its result; a half-streamed reply is
125
125
  not kept; :turn_canceled {cancellation_reason: :ctrl_c}; re-raised (the caller decides whether to exit)
126
126
 
127
- A Stop (Engine#cancel_current_turn!, the Bridge's POST cancel) or a hook's stop_turn:
127
+ A Stop (TurnState#cancel!: the Bridge's POST cancel, Engine#cancel_current_turn!) or a hook's stop_turn:
128
128
  → not an error: LLM::ModelResult(canceled: true, conversation:); complete_turn keeps the conversation with a
129
129
  TurnNote.cancelled note; text streamed before the cancel stays, marked [interrupted]
130
130
 
@@ -331,7 +331,12 @@ only input (`entries`, `reachable_names`, `left_out_names`, `removed_names`, `st
331
331
  One object (`turn_state.rb`), guarded by a `Monitor`, that the turn thread writes (`begin_turn`, `release_turn`)
332
332
  and other threads read: the idle scheduler, the Bridge's request threads, plugin threads, the UIs. It holds
333
333
  running, `context` (nil between turns), `last_context`, `controller`, the turn's thread and `ended`, the sink,
334
- steers and carried steers, and the activity clock.
334
+ steers and carried steers, and the activity clock. The hosts hold it (`Engine#turn_state`): the Worker reads it once
335
+ after it built the Engine and hands it to the Bridge and its own collaborators (`WorkerInbound`, `WorkerIdleExit`,
336
+ `ContinueOffer`), and the Engine hands it to its idle jobs (`IdleReminders`, `IdleRecap`). They call its readers,
337
+ `cancel!`, `record_activity` and the enqueued-id ledger; only the turn thread calls the writers (`begin!`,
338
+ `replace_context`, `ended!`, `finish!`). spec/bridge/turn_state_calls_spec.rb lists, per host file, the TurnState
339
+ methods it may call.
335
340
 
336
341
  - `begin!(context:, controller:, sink:, input_waiting:)`: all of it in one step, carried steers become steers. The
337
342
  context is built whole before (mode and git included), **so no reader sees a running turn with the last turn's
@@ -439,7 +444,7 @@ KernelLoop has its own `Turn` struct, a run's.
439
444
  TurnContext.**
440
445
  - Specs: `run_context(settings: …)` and `attach_services(kernel, tools: …)` (spec/support/test_kernel.rb).
441
446
  - `controller` is an in-process signal; another process stops a worker's turn through the Bridge (`POST cancel` →
442
- `Engine#cancel_current_turn!`).
447
+ `TurnState#cancel!`, on the Engine's TurnState the Worker handed the Bridge).
443
448
 
444
449
  **The live conversation and the checkpoint.** Both loops register the array they append to on the kernel
445
450
  (`KernelLoop#llm_context_turn`, `LLMContextForget::Turn#conversation`, tagged with the run's `turn_id`).
@@ -453,8 +458,9 @@ as a killed turn's (canceled, `worker_stopped`); the turn's end writes over it.
453
458
 
454
459
  ### SteerCut, GenerationPhase and WaitingSteer
455
460
 
456
- The Engine's one `SteerCut` (`steer_cut.rb`) owns a `GenerationPhase` and a `WaitingSteer`. The Bridge and the TUI
457
- ask it (`Engine#cut_for_steer`, `#input_epoch`, `#generation_snapshot`), the stream handler feeds it
461
+ The Engine's one `SteerCut` (`steer_cut.rb`) owns a `GenerationPhase` and a `WaitingSteer`. The Bridge holds it
462
+ (`Engine#steer_cut`, handed on by the Worker) and asks it (`#cut_for_steer`, `#input_epoch`, `#generation_snapshot`;
463
+ the Engine forwards the same three), the stream handler feeds it
458
464
  (`SteerCut#observe`), a drain that took input calls `#delivered!`, and `release_turn` calls `#finished!`.
459
465
 
460
466
  - `GenerationPhase`: whether a steer sent as a cut (`/cut TEXT`, `chi send --cut`) may cut the running generation.
@@ -486,11 +492,15 @@ observers (`Engine#subscribe`), which get a copy with a monotonic `event_seq`: t
486
492
  thinking tails, and in a worker the Bridge ([bridge.md](bridge.md)). **Errors in the sink or an observer are
487
493
  caught; they never break the turn.**
488
494
 
489
- `Engine#announce` puts an event that belongs to no turn (`Engine::ANNOUNCEABLE_EVENTS`: `turn_enqueued`,
495
+ `Engine#announce` puts an event that belongs to no turn (`SessionObserver::ANNOUNCEABLE_EVENTS`: `turn_enqueued`,
490
496
  `turn_dequeued` (`{enqueued_id, client_id}`: the remover's), `card`, `hook_notice`, `guardrail_warning`, `participants_changed`
491
497
  ([participants](participants.md#the-owners-terminal)), and more) to the observers only. `:side_usage` (a side
492
498
  request's usage and the session's side sums) goes to the observers the same way from `Engine#note_side_usage` (any
493
- thread), without being announceable.
499
+ thread), without being announceable. The list and the check are the event log's (`SessionObserver#announce`, the
500
+ same ArgumentError before anything is numbered); `Engine#announce` forwards to it. The Engine creates the log and
501
+ shows it (`Engine#event_log`): a worker's hosts (the Bridge, the Worker and its collaborators) hold that one log and
502
+ call it directly, so `Engine#subscribe`/`#unsubscribe`/`#event_count`/`#announce`/`#synchronize_events` stay for the
503
+ Engine's own parts, the one-shot host and Engine-only specs.
494
504
 
495
505
  Turn events (the main ones; `events.rb` keeps the shared sets):
496
506
 
@@ -783,7 +793,7 @@ are in [architecture.md](../architecture.md)'s file table.
783
793
  | `engine/participants.rb` | `Engine::ParticipantsPart`: the turn's author, a pair turn's stop, the participants line |
784
794
  | `engine/session.rb` | `Engine::SessionPart`: `#session=`, the state dir, the relay's view, the system prompt |
785
795
  | `engine/verify.rb` | `Engine::VerifyPart`: the Verify/Revise anchors' stage builder |
786
- | `engine/questions.rb` | `Engine::QuestionsPart`: ask-user-question (QuestionDesk, forwarded) |
796
+ | `engine/questions.rb` | `Engine::QuestionsPart`: ask-user-question (QuestionDesk, forwarded: the hosts hold `Engine#question_desk`; the forwards stay for the Engine's parts, the one-shot and Engine-only specs) |
787
797
  | `engine/toolkit.rb` | `Engine::ToolkitPart`: the toolkit, `ctx.load_tools`, the toolkit suggestion's builder |
788
798
  | `engine/context_judge.rb` | `Engine::ContextJudgePart`: the candidate judge's builder and `judge_late_candidates` |
789
799
  | `engine/turn_helpers.rb` | `Engine::TurnHelpersPart`: turn settings, images, model ref, used memories, the warm-up's builder |
@@ -77,6 +77,25 @@ exist. **A new session command or flag fails that spec until you choose one.**
77
77
  registry flag (`--recap-base-url` …) is this machine's config: `LOCAL_ONLY` without being listed
78
78
  (`Contract.run_status`). The contract spec fails on a run flag in neither.
79
79
 
80
+ ## Exchange
81
+
82
+ `SessionAccess::Exchange` (`session_access/exchange.rb`) holds the stateless pieces of "send one message and bind its
83
+ wait", over either backend (it calls only their public methods): `locate` (resolve, head, the poll while a continue
84
+ is in flight: `Located` or `Unsent`), `relocate` (located again after a continue took the link), `attempt` (one
85
+ delivery: show, the caller's check, owner, images, the delivery choice, `deliver_turn`: `Attempted` or `Stopped`),
86
+ `bind` (`ReplyWait::Target.message`) and `wait` (the backend's wait, the turn id and the UTF-8 text). It prints
87
+ nothing, keeps no state between calls, never retries and lets the backend's errors raise. `SendCommand` keeps its
88
+ retry loop, rescues and lines and calls these pieces (its Exchange reads `CONTINUING_WAIT` and `pause` when built, the
89
+ specs' stubs); `CLI::ParentWait` (chi send's and chi answer's wait) calls `wait`. `SessionAccess::Ask`
90
+ (`session_access/ask.rb`) is its own short loop over the same pieces for one message and one wait slice on one
91
+ deadline (chi web's starts with the request: `locate`'s `deadline:` and `relocate`'s `bounded: true` end the continue
92
+ waits `Ask::MIN_SLICE` before it, a continue that takes the link after it gets no second delivery, and the Bridge wait
93
+ of a worker starting draws on it too; chi web stopping cuts the continue waits at the next look, `Refused :canceled`,
94
+ 503 `server_stopping`; a client that goes away is not seen (WEBrick), so its handler runs on to that deadline),
95
+ answering `Reply` (with an `Exchange::Token` on timeout), `Ran` or `Refused`: chi web's `POST …/ask`
96
+ builds one per request over a `Local` that delivers through chi web's own manager and Bridge (`Web::AskRoutes::
97
+ AskAccess`), and plan 2's MCP server reuses it without chi web. The routes: [thin-clients.md](../thin-clients.md).
98
+
80
99
  ## One request, end to end
81
100
 
82
101
  `chi --remote studio send ab12 -m "fix it" --wait`:
@@ -84,8 +103,8 @@ registry flag (`--recap-base-url` …) is this machine's config: `LOCAL_ONLY` wi
84
103
  1. **bin/chi → Dispatch.** The flag is removed. `send` and `send --message` / `--wait` are `SUPPORTED`. `Remotes.find("studio")`
85
104
  reads `$XDG_CONFIG_HOME/samagotchi/remotes.yml`. Then `SendCommand.new(argv, access: Remote.new(entry)).run`.
86
105
  2. **SendCommand.** The client-side checks (UI-only slash commands, image ingest) run. The machine-local ones are
87
- skipped (next section). Every id is resolved once up front (`SendCommand#target`): `Remote#resolve`, then
88
- `Remote#head`, where input for it goes (a continued session's chain's newest link).
106
+ skipped (next section). Every id is resolved once up front (`SendCommand#target` → `Exchange#locate`):
107
+ `Remote#resolve`, then `Remote#head`, where input for it goes (a continued session's chain's newest link).
89
108
  3. **Remote → HTTPTransport.** The first request on a `Remote` is preceded by `check_server!`, which sends
90
109
  `GET /api/info` and needs `app: "chi-web"` plus the `session_commands` feature. Next come
91
110
  `GET /api/sessions/resolve?id=ab12`, `GET /api/sessions/resolve?id=<full id>&head=1` (`{id, asked, via}`:
@@ -93,8 +112,8 @@ registry flag (`--recap-base-url` …) is this machine's config: `LOCAL_ONLY` wi
93
112
  ignores `head=1` and answers `{id}`, read as `same`, so the message goes to the id named as before; a participant's
94
113
  token never asks, and the participant branch of the route answers `{id}` alone) and
95
114
  `POST …/wait/prepare {busy: true, queue:}` (`Remote#busy`) on the id it answered, then
96
- `POST …/wait/prepare {turn, created}` for the `WaitStart`. `deliver` calls `Remote#show` and `#owner` (each
97
- `GET /api/sessions/:id?brief=1`), then
115
+ `POST …/wait/prepare {turn, created}` for the `WaitStart`. `deliver`'s pass (`Exchange#attempt`) calls
116
+ `Remote#show` and `#owner` (each `GET /api/sessions/:id?brief=1`), then
98
117
  `POST …/turn {prompt, client_id: "cli:send", history: false}`. A 202 ack becomes a `DeliverResult` with `via`
99
118
  (`bridge` or `file`).
100
119
  4. **chi web.** `Web::App#route` runs the Host check (`local_host_header?`), then `cross_site?`, then in LAN mode for a
@@ -102,7 +121,7 @@ registry flag (`--recap-base-url` …) is this machine's config: `LOCAL_ONLY` wi
102
121
  before any handler runs. A `:session` route turns an `ArgumentError` into its unknown-session 404. The handlers in
103
122
  `SessionAccessRoutes` call `session_access`, a `SessionAccess::Local` on chi web's own state dir. The page's older
104
123
  routes (`/turn`, `/answer`, `/stop`, …) call `SessionManager` and the Bridge directly, as before.
105
- 5. **The wait.** `ParentWait#wait_for_reply` → `Remote#wait_reply` loops on `POST …/wait` with
124
+ 5. **The wait.** `ParentWait#wait_for_reply` → `Exchange#wait` → `Remote#wait_reply` loops on `POST …/wait` with
106
125
  `timeout: min(time left, WAIT_SLICE)` (30 s). The server runs `ReplyWait.call` for at most `WAIT_MAX_SECONDS` (30 s)
107
126
  and returns the `ReplyWait::Result` fields plus `parent_strategy`. On a `timeout` status the client asks again until
108
127
  its own `--timeout` runs out, at which point it builds the `timeout` result itself. Each slice is a fresh `ReplyWait`
@@ -14,7 +14,8 @@ by `npm run e2e` (`spec/e2e/`). `app.js` has no unit spec of its own; `viewer_bo
14
14
  **Every module has a size cap, `app.js` its own**: `npm run lint` fails past `max-lines` in `eslint.config.js`
15
15
  (counted as `wc -l` counts, comments and blank lines too). Every `public/*.js` module: 1200 (`samagotchi/module-size`,
16
16
  about 10% over the largest, `turn_block.js`), so a module near it splits rather than becoming the next `app.js`.
17
- `app.js` (`samagotchi/app-size`): 1638, its size once the lightbox went into `picture_viewer.js`; down from 1649, its
17
+ `app.js` (`samagotchi/app-size`): 1637, its size once the diagrams' wiring went into `diagram_wiring.js`; down from 1638,
18
+ its size once the lightbox went into `picture_viewer.js`, itself down from 1649, its
18
19
  size plus 50 once the session-open flow went into `session_sync.js` and `session_view.js`, itself ratcheted down from 2000, itself down from 2250 when the versions, the owner's claim links and
19
20
  Verify, the composer's mode and the strip's hide went into modules of their own. A new feature goes into a module of
20
21
  its own, wired from `app.js` in a few lines; a refactor that shrinks `app.js` ratchets its cap down with it. Never
@@ -29,9 +30,15 @@ on an existing module, imported by a new version of another, then finds the old
29
30
  page. A factory dep a new version stops passing is the same hazard the other way round: the store's redraws took
30
31
  `updateInfoBar` and the chip controls out of `stream_handlers.js`'s deps (and `updateInfoBar`/`updateComposerMode`
31
32
  out of `send_turn.js`, `session_actions.js` and `lists_view.js`); a page loaded before keeps all its old modules
32
- until a reload, so the risk is a mixed cache, not an open tab. `answer_fold.js`, `details_motion.js`,
33
+ until a reload, so the risk is a mixed cache, not an open tab. An export a new version stops importing stays until
34
+ the next release (its baseline refresh) for the same reason, marked as kept for an older cached module (the delete
35
+ sheet kept `isChained`, `format.js deleteConfirmText` and `running_tasks.js tasksConfirmText` that way; and, for the
36
+ same release, the hooks 0.182.0's modules still call: `session_actions.js` passes `plain` and a `failed` that toasts
37
+ when the sheet is gone, and gives archive's ask a `deletePlan` that rejects with the refusal, and `delete_sheet.js`'s
38
+ `deleteToast` leaves out the stopped tasks the old `session_actions.js` adds itself; `delete_mixed_cache.test.js` loads
39
+ each pair, the old file from `spec/web/public/fixtures/v0.182.0/`). `answer_fold.js`, `details_motion.js`,
33
40
  `turn_range.js`, `history_reveal.js`, `latest.js`, `session_payload.js`, `method_api.js`, `session_store.js`,
34
- `session_fields.js`, `feature_gates.js`, `revise_stack.js`, `revise_switch.js`, `shell_command.js`, `stale_params.js`, `popover_modal.js`, `more_sheet.js`, `delete_sheet.js` (Deleting a chained session, below), `running_tasks.js` (a delete's or archive's 409 `tasks_running`: the tasks' line, the second confirm, the toast's suffix; DOM-free, so `stop_sheet.js` and `delete_sheet.js` share its cut), `hash_intent.js` (what the hash asks for: session, all, start or keep), `worker_features.js`, `version_notices.js`, `owner_claim.js`, `owner_verify.js`, `composer_mode.js`, `strip_hidden.js`, `block_open.js`, `text_roots.js`, `block_source.js`, `block_frame.js`, `block_host.js`, `block_watch.js`, `card_stamps.js`, `recap_stamp.js` (a saved recap's place by its `opening_id` stamp, else its count), `inline_widgets.js`, `widget_walk.js`, `widget_picks.js`, `history_shape.js` (the history's shape, live against a reload: the e2e reload checks and the opt-in reload check share its normalizer and its `ACCEPTED` allowlist), `turn_pieces.js` (a finished turn's one order and its answer rule: the live hand-off's `handOffOrder` and `turnEnded`, and a reload's `turnHistoryNodes`), `reload_check.js` (the opt-in `web.reload_check`: after the stage's hand-off, the turn against a reload of it, the counts posted; the history without its cards and questions, and those as data: the page's `card_registry.js` against one seeded from the read, this turn's entries, a capped read's missing keys skipped), `turn_drawing.js` (a finished turn's drawing, `turn_drawings` in the show: its fold into steps and its end kind; `turn_block.js` draws it), `stage_stall.js` (the stage's quiet signal), `stage_quiet_clock.js`, `stage_dom.js`, `stage_answer.js`, `stage_pager.js`, `stage_cloud.js`, `stage_handoff.js`, `stage_place.js`, `stage_probe.js` (the stage's features: below, The stage's modules), `card_kinds.js` (what a card waits as, from its data: the kind, approval and folded-row text the stage's registry takes; the node's read is its cross-check), `card_registry.js` (the open session's cards as data, an observer of the stream's card events and a read's seed: Where state lives), `history_end.js` (the stage's one move of pieces to the history's end), `stage_opened.js` (a running turn opened in the history while a card waits: the lead-in bubble, the moves, the end fold), `stage_asking.js` (the stage's docked card and its fold: the docking and lead-in rules, the opening, a waiting card's own toggle, the folded row's text per kind, the fold's choice, reveal and the docked card's fold; `stage_view.js` wires it), `stage_waiting.js` (the stage's waiting cards as data, keyed by `data-qid` / `data-card-id`: kind, docked, approval, the stage's order, the shown card and its pager, the docked card's fold, kept for this tab in `chi_asking_fold:<session>`; `front`, `count`, `shown`, `blocking`), `stage_cards.js` (the cards that wait in the stage: `PENDING`, `ASKS`, `waitsInStage`, read by `stage_model.js placeKind`), `resync_reach.js` (a re-read that can't reach chi web keeps the drawn history; the status chip says retrying / offline, outside a turn), `session_sync.js` (the open session's sync: `select`, `resync` and its retries, the stream's life; the stream handle and the re-read bookkeeping are its own), `session_view.js` (the open session's view: `renderSessionView` draws a read, `forgetSession` resets the page for another session, `readTurnEnd`, `endTurnView`; app.js makes both right after the cards, each reaching the other and the later views through getters), `participant_main.js`, `participant_bar.js`, `viewer_self.js`, `participant_history.js` (a participant's ↑/↓ list), `stage_owner_wait.js`, `participant_revise.js` (a participant's page: The participant's page, below), `ws_timeline.js`, `ws_cards.js`, `ws_peek.js`, `ws_reader.js`, `ws_way_in.js`, `ws_item_sig.js`, `ws_markdown.js` (what chi has of a working-set item: below, The working set's reader), `session_prefs.js` (a session's own view settings, `<key>:<session>`: Storage keys, below), `ws_sections.js` (the working set's head view: its sections from the prompt's parts, [working-set.md](working-set.md), The head view), `ws_order.js` (the working-set list's order: last touched first, held while it is open, [working-set.md](working-set.md), The list's order), `ctx_tokens.js` (the context's token count beside its %: `ctxTokens`, below), `stage_view_memory.js` (what was opened of a running turn, per session, in memory: Where state lives), `peer_data.js`, `peer_exchange.js`, `peer_note.js`, `peer_links.js` (a peer's send and answer in the conversation: The peer exchange, below), `peer_chip.js` (a paired peer's one chip in the session bar: The peer exchange), `picture_viewer.js` (the picture viewer, `#lightbox`: below, Picture viewer), `pan_zoom.js` (its maths, pure), `no_contact_fill.js` (a text field that isn't a contact form: autocomplete off and a name with no contact word, against iOS Safari's AutoFill Contact bar; a template's fields carry the same attributes, and its spec checks the page's markup for them) and the `objectives_*.js` modules are new modules for that reason. The last four `block_*` draw fenced blocks (`block_watch.js` finds and watches them, `block_host.js` is its frame drawer for a bundle's renderers): [block-renderers.md](block-renderers.md). `inline_widgets.js` is its core drawer for `chi-ui` blocks, drawing `widget_walk.js`'s and `widget_picks.js`'s widgets in a shadow root styled by `widgets.css`: [inline-widgets.md](inline-widgets.md).
41
+ `session_fields.js`, `feature_gates.js`, `revise_stack.js`, `revise_switch.js`, `shell_command.js`, `stale_params.js`, `popover_modal.js`, `more_sheet.js`, `delete_sheet.js` (The delete sheet, below), `removal_sheet_model.js` (its words: rows, button words, the archive model, the toast; DOM-free), `running_tasks.js` (a delete's or archive's tasks: their line and the toast's suffix; DOM-free, so `stop_sheet.js` and the delete sheet share its cut), `hash_intent.js` (what the hash asks for: session, all, start or keep), `worker_features.js`, `version_notices.js`, `owner_claim.js`, `owner_verify.js`, `composer_mode.js`, `strip_hidden.js`, `block_open.js`, `text_roots.js`, `block_source.js`, `block_frame.js`, `block_host.js`, `block_watch.js`, `card_stamps.js`, `recap_stamp.js` (a saved recap's place by its `opening_id` stamp, else its count), `inline_widgets.js`, `widget_walk.js`, `widget_picks.js`, `history_shape.js` (the history's shape, live against a reload: the e2e reload checks and the opt-in reload check share its normalizer and its `ACCEPTED` allowlist), `turn_pieces.js` (a finished turn's one order and its answer rule: the live hand-off's `handOffOrder` and `turnEnded`, and a reload's `turnHistoryNodes`), `reload_check.js` (the opt-in `web.reload_check`: after the stage's hand-off, the turn against a reload of it, the counts posted; the history without its cards and questions, and those as data: the page's `card_registry.js` against one seeded from the read, this turn's entries, a capped read's missing keys skipped), `turn_drawing.js` (a finished turn's drawing, `turn_drawings` in the show: its fold into steps and its end kind; `turn_block.js` draws it), `stage_stall.js` (the stage's quiet signal), `stage_quiet_clock.js`, `stage_dom.js`, `stage_answer.js`, `stage_pager.js`, `stage_cloud.js`, `stage_handoff.js`, `stage_place.js`, `stage_probe.js` (the stage's features: below, The stage's modules), `card_kinds.js` (what a card waits as, from its data: the kind, approval and folded-row text the stage's registry takes; the node's read is its cross-check), `card_registry.js` (the open session's cards as data, an observer of the stream's card events and a read's seed: Where state lives), `history_end.js` (the stage's one move of pieces to the history's end), `stage_opened.js` (a running turn opened in the history while a card waits: the lead-in bubble, the moves, the end fold), `stage_asking.js` (the stage's docked card and its fold: the docking and lead-in rules, the opening, a waiting card's own toggle, the folded row's text per kind, the fold's choice, reveal and the docked card's fold; `stage_view.js` wires it), `stage_waiting.js` (the stage's waiting cards as data, keyed by `data-qid` / `data-card-id`: kind, docked, approval, the stage's order, the shown card and its pager, the docked card's fold, kept for this tab in `chi_asking_fold:<session>`; `front`, `count`, `shown`, `blocking`), `stage_cards.js` (the cards that wait in the stage: `PENDING`, `ASKS`, `waitsInStage`, read by `stage_model.js placeKind`), `resync_reach.js` (a re-read that can't reach chi web keeps the drawn history; the status chip says retrying / offline, outside a turn), `session_sync.js` (the open session's sync: `select`, `resync` and its retries, the stream's life; the stream handle and the re-read bookkeeping are its own), `session_view.js` (the open session's view: `renderSessionView` draws a read, `forgetSession` resets the page for another session, `readTurnEnd`, `endTurnView`; app.js makes both right after the cards, each reaching the other and the later views through getters), `participant_main.js`, `participant_bar.js`, `viewer_self.js`, `participant_history.js` (a participant's ↑/↓ list), `stage_owner_wait.js`, `participant_revise.js` (a participant's page: The participant's page, below), `ws_timeline.js`, `ws_cards.js`, `ws_peek.js`, `ws_reader.js`, `ws_way_in.js`, `ws_item_sig.js`, `ws_markdown.js` (what chi has of a working-set item: below, The working set's reader), `session_prefs.js` (a session's own view settings, `<key>:<session>`: Storage keys, below), `ws_sections.js` (the working set's head view: its sections from the prompt's parts, [working-set.md](working-set.md), The head view), `ws_order.js` (the working-set list's order: last touched first, held while it is open, [working-set.md](working-set.md), The list's order), `ctx_tokens.js` (the context's token count beside its %: `ctxTokens`, below), `stage_view_memory.js` (what was opened of a running turn, per session, in memory: Where state lives), `peer_data.js`, `peer_exchange.js`, `peer_note.js`, `peer_links.js` (a peer's send and answer in the conversation: The peer exchange, below), `peer_chip.js` (a paired peer's one chip in the session bar: The peer exchange), `picture_viewer.js` (the picture viewer, `#lightbox`: below, Picture viewer), `pan_zoom.js` (its maths, pure), `diagram_wiring.js` (`wireDiagrams`: the block host with the viewer as its `openPicture`, the viewer closed on a theme change, the regions' layer given to the viewer; the viewer itself stays made in app.js, which `createSessionView` reads first), `block_regions.js` (a renderer's regions cleaned, pure: [block-renderers.md](block-renderers.md#regions)), `region_hit.js` (their hit test, the arrow keys' nearest region and the reveal under the card, pure), `picture_regions.js` (the regions' layer over the viewer: below, Picture viewer), `no_contact_fill.js` (a text field that isn't a contact form: autocomplete off and a name with no contact word, against iOS Safari's AutoFill Contact bar; a template's fields carry the same attributes, and its spec checks the page's markup for them) and the `objectives_*.js` modules are new modules for that reason. The last four `block_*` draw fenced blocks (`block_watch.js` finds and watches them, `block_host.js` is its frame drawer for a bundle's renderers): [block-renderers.md](block-renderers.md). `inline_widgets.js` is its core drawer for `chi-ui` blocks, drawing `widget_walk.js`'s and `widget_picks.js`'s widgets in a shadow root styled by `widgets.css`: [inline-widgets.md](inline-widgets.md).
35
42
 
36
43
  ## One page, every viewer
37
44
 
@@ -380,30 +387,56 @@ placed at, so `chip_popover.js` places it, marks `aria-expanded` and gives focus
380
387
  `[data-anchor-stand-in]` (⋯). Rows and actions draw into fixed slots, so a row that joins keeps the focus where it was.
381
388
  The e2e reach an item wherever it is with `spec/e2e/support/layout.js` `clickBarItem` (the row, else ⋯'s `[data-row]`).
382
389
 
383
- **Deleting a chained session** (`delete_sheet.js`; docs/sessions.md, Session chains → Deleting a link): Delete on a
384
- session in a chain asks "Delete this link" or "Delete the whole chain" instead of the browser's confirm, which a
385
- session in no chain keeps (`session_actions.js confirmDelete`; `isChained` reads the page's list, which holds archived
386
- links too). In ⋯'s menu, Delete doesn't click `#infoDeleteBtn` for a chained session: `createMoreSheet`'s `onDelete`
387
- (`session_actions.js deleteIn`) takes the panel as a host and draws the sheet in its place (a subview; ‹ More,
388
- `del:back`, draws the list again; a redraw keeps the subview), so no second popover opens. A card's ✕ opens it at the
389
- card (`createDeleteSheet`, on `chip_popover.js`: a bottom sheet on a phone). Both shells keep one live host: a
390
- `host(anchor, id)` (the card's, with the session it opened for) or a Delete in ⋯ makes a new one, and a flow whose host
391
- is no longer the live one (a ✕ on another card while the first plan was read) draws and acts on nothing. What the sheet says comes from
392
- `GET /api/sessions/:id/delete_plan`, fetched as it opens for every session: the server's own plan and refusals
393
- (`SessionChain::Delete::Preview`, the code the delete runs), so the sheet and the delete can't disagree. Plain
394
- sessions have a server-side link plan; the page still uses the plain confirm until the delete-sheet phase sends plans
395
- for it. The preview shares one `session_rows` snapshot across the link and chain choices, while Links performs its own
396
- listing. `deleteChoices` (pure) turns it into the two choices, a schedule's banner
397
- and each refusal's "Not while …"; a plan that says no chain (a link alone past a gap) falls back to the confirm. The
398
- confirm sends the shown choice's `digest` (`expect=`, `data.js deleteSession`/`deleteChain` keep it out of `fetch`);
399
- a `409 plan_changed` re-reads the plan and redraws the sheet with "What this deletes changed; check again" (a link no
400
- longer chained gets the plain confirm). Any other refusal `runDeleteFlow` shows in the sheet
401
- (`refusalModel`: a moved delegate that can't go back offers "Stop its worker, then delete" only when the 409 says
402
- `stoppable`; it stops each, retries only once the stop answers `released`, and says so otherwise, never looping, one
403
- stop at a time).
390
+ **The delete sheet** (`delete_sheet.js`, its words `removal_sheet_model.js`; docs/sessions.md, Deleting a session and
391
+ Session chains → Deleting a link; the design: https://claude.ai/artifact/1A3TL2kkz8a2Pv8obi4jsj): every Delete, and an
392
+ Archive the server refuses, asks in one sheet instead of the browser's `confirm()` / `alert()`. Before anything happens
393
+ it says what goes, what is stopped first and what stays, with one button that names the outcome.
394
+ - **Where.** In ⋯'s menu, Delete always takes the panel as the sheet's host (`createMoreSheet`'s `onDelete` →
395
+ `session_actions.js deleteIn`, which answers true for any session): the panel draws the sheet in its place (a
396
+ subview; ‹ More, `del:back`, draws the list again; a redraw keeps the subview), so no second popover opens inside
397
+ More's click (a popover opened there would see that click as outside and close). A card's ✕ opens it at the card
398
+ (`createDeleteSheet`, on `chip_popover.js` with `SHEET_TALL`: a bottom sheet on a phone, its buttons full width).
399
+ Both shells keep one live host: a `host(anchor, id)` or a Delete in ⋯ makes a new one, and a flow whose host is no
400
+ longer the live one (a ✕ on another card while the first plan was read) draws and acts on nothing.
401
+ - **What it says** comes from `GET /api/sessions/:id/delete_plan`, fetched as it opens, for every session: the
402
+ server's own plan and refusals (`SessionChain::Delete::Preview`, the code the delete runs), so the sheet and the
403
+ delete can't disagree. `deleteChoices(session, plan, sessions)` is the model. A session in no chain:
404
+ `removal_sheet_model.js sessionSheetModel` → `{title, groups, button, stops, foot, tasks}`, its rows from
405
+ `sheetGroups(link)`: **Goes** (its history; the stopped delegates of `delegates.delete`, named from the page's list
406
+ by `format.js cardName`, else the short id; three, then `+N more`), **Stopped first** (`worker`: "Its worker (idle)"
407
+ or "Its running turn"; the `running` tasks through `running_tasks.js tasksLine`, a delegate's with its id in front),
408
+ **Stays** (the running delegates of `delegates.leave`, with the stopped ones under them; the tasks chi can't verify or
409
+ read, never signalled). A chained one keeps its two choices ("this link", "the whole chain"), each with its first
410
+ lines, then its own Stopped first / Stays lines (`choiceTail`). A refusal the plan carries (a one-turn run, a
411
+ schedule, a continue under way) is the "Can't delete … now" view with only Close (`cantModel`); a plan that can't be
412
+ read is the same view.
413
+ - **The button's words** (`buttonWords`): it names the running work it ends: `Stop them and delete` (`Stop it …` for
414
+ one task), `Stop the turn and delete`; an idle worker is only a row and the button stays `Delete`; ` · N sessions`
415
+ when the tap takes more than one session: every session it deletes, the stopped delegates too (`Delete this link · 2
416
+ sessions` with one; the whole chain counts its links and theirs, a step past the mock-up's case 8, by the owner's word); a chain's choices say `Stop 2 tasks
417
+ and delete this link`. While the tap runs it says `Stopping…` (tasks or a turn) or `Deleting…`.
418
+ The sheet opens with focus on Cancel (× or ‹ More while there is none), so a stray Enter never deletes or archives.
419
+ Closed while the tap runs, a refusal that comes after is a sticky toast (`failed` on a host no longer live).
420
+ - **The tap** sends the choice's `digest` (`expect=`) and, whenever the choice's task listing isn't empty, `stopTasks`
421
+ with the ids of its `running` tasks (`stopTasksOptions`; `data.js` sends `stop_tasks=true&tasks=<id,id>`, `tasks=`
422
+ when it lists only records chi can't verify, so such a session can still be deleted and nothing unnamed is stopped).
423
+ A `409 plan_changed` and a `409 tasks_running` (a task that started since) both re-read the plan and show it with
424
+ "What this deletes changed; check again." Any other refusal `runDeleteFlow` shows in the sheet (`refusalModel`: a
425
+ moved delegate that can't go back offers "Stop its worker, then delete" only when the 409 says `stoppable`; it stops
426
+ each, retries only once the stop answers `released`, and says so otherwise, never looping, one stop at a time).
427
+ - **Archive** stays one tap and the Undo toast when nothing is in the way. Its 409 opens the same sheet
428
+ (`session_actions.js setArchived` → `runDeleteFlow` with `archive: {refusal}`): `tasks_running` is
429
+ `archiveSheetModel` (Hidden: it and the 409's `sessions` − 1 delegates; Stopped first: the tasks; `Stop them and
430
+ archive`, its button sending the named ids the same way); a task that started since re-shows it with "What this
431
+ archives changed; check again."; any other refusal is "Can't archive … now". The sheet is at the control tapped:
432
+ ⋯ for the open session's (`toggleArchiveSelected` passes it), else the card's archive button with a box, found by
433
+ `[data-arch="<id>"]` (app.js's wrapper passes no anchor). A 409 that comes once the shell shows another session's
434
+ sheet (opened while the archive was out) leaves that sheet and is a sticky toast (`latest.js stillOn` on the shell's
435
+ `openFor`). An unarchive that fails is a sticky toast. A batch archive
436
+ is untouched (`archiveOne` passes nothing, and skips a session with running tasks).
404
437
  After a delete, `listAfterDelete` drops the `deleted` ids and un-archives the `unarchived` ones in the store, the
405
- selection clears when it went, and the toast (`deleteToast`) names what came back with an "Open" action.
406
-
438
+ selection clears when it went, and the toast (`deleteToast`) says what went, what was stopped and what stays, with
439
+ "Open" for the link that came back or a delegate left running.
407
440
 
408
441
  ## Safe areas
409
442
 
@@ -442,7 +475,8 @@ kept: every open starts fitted.
442
475
  moves, Ctrl/Cmd + wheel zooms at the cursor (a Chromium trackpad pinch is a ctrl + wheel), by `exp(-deltaY ×
443
476
  0.01)`, not fixed steps. Safari's `gesturestart`/`change`/`end` are always prevented (they would zoom the page) and
444
477
  applied only while no touch pointer is down: that is a Mac trackpad; iOS fires them beside the pointers for a
445
- finger pinch, and applying both would double it. A double tap or click (two ups without a move within 300 ms)
478
+ finger pinch, and applying both would double it. A double tap or click (two ups within 300 ms, neither a move: past 4 px for a mouse, 10 for a finger,
479
+ as |dx| + |dy|)
446
480
  goes to max(2.5 × fit, natural) at that point, or back to fit when closer than fit. The `<img>` is never
447
481
  dragged natively (`draggable=false`, `dragstart` prevented, `-webkit-user-drag:none`, `pointer-events:none`) and
448
482
  has no iOS long-press sheet (`-webkit-touch-callout:none`).
@@ -455,7 +489,7 @@ kept: every open starts fitted.
455
489
  so after one it is the page's. A window `resize` (an orientation change) refits a fitted view, else re-clamps; it
456
490
  is listened to only while open.
457
491
  - **It closes by itself**, whatever it shows, on a system theme change (the diagram behind is redrawn; the viewer
458
- holds the old picture; app.js), on a switch to another session or the start page (`session_view.js
492
+ holds the old picture; `diagram_wiring.js`), on a switch to another session or the start page (`session_view.js
459
493
  forgetSession`, given `pictures`; the same session again keeps it) and when the all-sessions view opens (it hides
460
494
  `#center`, the viewer's parent; app.js `applyView`). A bubble rewritten or cloned while it is open leaves it as it
461
495
  is: it holds its own copy of the URL. The toast may show over it (both z-index 50, the toast later); it is modal by
@@ -464,6 +498,32 @@ kept: every open starts fitted.
464
498
  viewer adopts it (or adds one) and draws ✕ and the bar with lit at the first open. ✕ and the bar are glass cards
465
499
  (solid `--bg-panel` under `body.no-glass` and reduced transparency), by `--safe-*`, and the standalone phone
466
500
  app's ✕ is 12px lower, below iOS 26's band under the clock.
501
+ - **A diagram's regions** (a renderer that reports them: [block-renderers.md](block-renderers.md#regions)): the
502
+ viewer's layer, `picture_regions.js createRegionLayer`, made by `diagram_wiring.js` and given by
503
+ `pictures.useLayer?.(layer)` (an older cached `picture_viewer.js` has none: the viewer as before; one with
504
+ `useLayer` but no `bind`, which never shows the card, leaves the layer undrawn and keeps no card's room). The layer
505
+ adds its own `.pv-marks` child to `.pv-pic` (the box marks by percent, the page's own `<svg viewBox="0 0 1 1">`
506
+ with at most two `<polyline>`s, the hovered and the selected arrow's, and a `role="group"` of buttons), and its card
507
+ (`.pv-sel`, `role="region"` "Selected") and visually hidden `aria-live` line join `#lightbox` after the bar.
508
+ **The pointer path is maths** (`region_hit.js`): the surface keeps its pointer capture, so a drag, a pinch and a
509
+ double tap are as before. A tap that isn't a move (4 px for a mouse, 10 for a finger) goes to `layer.tap` before
510
+ the double-tap bookkeeping: the nearest node or note within 3 px, else an arrow's line (7 px at least) or its
511
+ label's box, else the innermost group; nothing → it clears. A finger (18 px) takes a node first only on its box:
512
+ an arrow's line or label within 7 px beats a node only within the finger's margin (two nodes 30 px apart at a
513
+ phone's fit leave the label between them tappable), then the nearest node within 18 px, then an arrow. One region at a time; two with one kind
514
+ and id select together. The mouse with no button down is `layer.hover` at most once per frame (`#lightbox.over`:
515
+ the hand). **The card's room** (`CARD_ROOM` 64 px, 80 on a coarse pointer, beside the bar's 56) is kept in the fit
516
+ of a picture with regions, selected or not, so selecting never moves a fitted picture and no fitted node is under
517
+ the card; zoomed in, a selected node under the card slides up (`revealOffset`), `TAP_MS` after its tap and only if
518
+ no second tap came (a double tap zooms at the point it hit), a keyboard's selection at once. **Keys**: the nodes'
519
+ buttons (`.pv-node`, a full reset of the page's `button` style, `pointer-events: none`; the reset is in each
520
+ button's inline `style` too, so with a stale index.html they are still see-through and take no pointer) are one Tab
521
+ stop (roving `tabindex`, following the selection); the arrows move the focus to the nearest button that way (along +
522
+ 2 × across; a group only when nothing else is that way), Enter or Space is the button's click, which selects; Esc
523
+ clears a selection first and closes second; the card's ✕ clears. When the card goes with the focus in it, the focus
524
+ goes to the cleared region's button, else to the viewer (never `<body>`, where the next Esc wouldn't reach the
525
+ viewer). A focused button never scrolls the surface (its `scroll` is reset). The card's actions row is the layer's
526
+ `actions(region)` (empty for now: the card is the name alone).
467
527
 
468
528
  ## A failed block asked for again
469
529
 
@@ -130,7 +130,7 @@ pending: [Steering: add and unadd](#steering-add-and-unadd)) (`Engine#emit_worki
130
130
  turn-end apply has run by then);
131
131
  - between turns, from `Engine#announce_working_set` (the session's messages, under the event lock; after a
132
132
  `/working-set` op, after a `rollback_to`, and after an `/llm-context` change: the states are the next turn's strategy's): announced
133
- (`working_set_updated` is in `ANNOUNCEABLE_EVENTS`; held after a command's `command_ran` inside
133
+ (`working_set_updated` is in `SessionObserver::ANNOUNCEABLE_EVENTS`; held after a command's `command_ran` inside
134
134
  `holding_announcements`), under the *next* turn's strategy (`SessionModelSettings#turn_llm_context`, as the
135
135
  turn-end warm-up reads it; `TurnSettings` keeps the last turn's, stale after `/llm-context` or `/model`). While a
136
136
  turn runs, the strategy is always the turn's.