eve-hub 0.6.18 → 0.6.19

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # eve-hub
 
+## 0.6.19
+
+### Patch Changes
+
+- The Forms guide tells bots to draw a diagram by default when the reader is trying to understand or review something, and sequence diagrams can group their lines under a labeled host box with an optional `unit` caption.
+
 ## 0.6.18
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eve-hub",
-  "version": "0.6.18",
+  "version": "0.6.19",
   "license": "Apache-2.0",
   "description": "Bot-side code shared by every hub agent: registry tools, the roster hook, the eve channel, the host sandbox and browser, and model helpers.",
   "type": "module",

package/templates/forms.md

@@ -1,7 +1,7 @@
 
 ## Forms
 
-A form is an interactive figure the app draws from a fenced block with a JSON body. Use one only when the shape is the point: a path through parts (`flow`), an order of events (`sequence`), numbers to compare (`chart`), a choice you need from the human (`ask`). Everything else is plain prose. At most one or two forms per message.
+A form is an interactive figure the app draws from a fenced block with a JSON body. When the reader is trying to understand or review something, draw it by default; they should never have to ask. Pick the shape: a path through parts (`flow`), an order of events (`sequence`), numbers to compare (`chart`), a choice you need from the human (`ask`). Anchor the picture in something they know, e.g. a before form then an after form, each labeled, in one message. Every part of one diagram is the same kind of thing (all hosts, all processes or all functions); say which in the sentence before it, and for a sequence in `unit`. A group is the level that contains them (processes grouped under their host). Plain prose is for what no shape helps. At most one or two forms per message.
 
 - Claim first: a sentence that says what the form shows comes before it. A chart's `title` is its claim.
 - Link a word in your prose to a part with `[word](#id)`. Ids are lowercase slugs (`a-z`, `0-9`, `-`, up to 32 characters), unique in the whole message.
@@ -19,10 +19,11 @@ A request leaves the [app](#app), the [hub](#hub) routes it, and a [bot](#bot) a
  "edges": [{"from": "app", "to": "hub", "label": "send"}, {"from": "hub", "to": "bot", "label": "wake"}, {"from": "bot", "to": "hub", "label": "post"}]}
 ```
 
-The stream [drops](#drop) before the client [retries](#retry). `sequence`: actors 2–6, messages 1–16 (`from`, `to`, `label` up to 32, `fail` where it breaks, `ref` as file:line; `from` = `to` for a wait or retry inside one actor). Steps follow message order.
+The stream [drops](#drop) before the client [retries](#retry). `sequence`: actors 2–6, messages 1–16 (`from`, `to`, `label` up to 32, `fail` where it breaks, `ref` as file:line; `from` = `to` for a wait or retry inside one actor). Optional `unit` (up to 48 characters) is printed above the actors, e.g. "each line = one process"; optional `groups` (up to 3, `id` and `label`) with `group` on an actor draws a box around actors that share a host; grouped actors must sit next to each other. Steps follow message order.
 
 ```sequence
-{"actors": [{"id": "hub", "label": "Hub"}, {"id": "client", "label": "Client"}],
+{"unit": "each line = one process", "groups": [{"id": "mac", "label": "Mac"}, {"id": "hub-proj", "label": "Hub project"}],
+ "actors": [{"id": "client", "label": "Client", "group": "mac"}, {"id": "hub", "label": "Hub", "group": "hub-proj"}],
  "messages": [
   {"id": "drop", "from": "hub", "to": "client", "label": "stream drops", "fail": true, "ref": "Client.swift:257"},
   {"id": "retry", "from": "client", "to": "hub", "label": "reconnects", "note": "Resumes from the last event id."}]}