@cardenelabs/dragon 0.46.0 → 0.46.3

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.
package/README.md CHANGED
@@ -1,33 +1,45 @@
1
1
  # @cardenelabs/dragon
2
2
 
3
- 動く図を、人は dragon記法で、AI は JSON で書くための package。
3
+ Animated diagrams that people write in a plain notation and AI writes as JSON.
4
4
 
5
- ## 入れ方
5
+ [日本語](https://github.com/cardene777/dragon/blob/main/packages/dragon/README.ja.md)
6
+
7
+ dragon draws a diagram that plays step by step from a short text file.
8
+ The catalog, with every kind of diagram and an editor that plays what you type, is at <https://cardene777.github.io/dragon/>.
9
+
10
+ ## Install
6
11
 
7
12
  ```sh
8
13
  npm install @cardenelabs/dragon
9
14
  ```
10
15
 
11
- 0.35.0 は根本から作り直した版で、0.34.0 までの記法と入口は使えない。
12
- 今までの記法 (日本語の鍵の YAML と JSON)、`textDslToDiagram` と `jsonToDiagram` を含む入口、`@cardenelabs/cdl` へ渡して描く仕組みは [#2983](https://github.com/cardene777/dragon/issues/2983) で消した。
13
- 作り直しで決めたことは [#2982](https://github.com/cardene777/dragon/issues/2982) にまとめている。
16
+ The package has four parts.
14
17
 
15
- 0.36.0 では記法を dragon記法に作り直したため、0.35.x の記法の file は書き直さないと読めない。
16
- 原本の JSON は 0.35.x と同じ形で、そのまま読める。
17
- 書き直す時は、下の dragon記法の節と、前の形と新しい形の対応表を見る。
18
+ | Part | What it is |
19
+ |---|---|
20
+ | Source | JSON with a shared skeleton and fields for each kind of diagram. It carries a format version, and older versions are converted when read |
21
+ | Notation | The dragon notation, where the first English word of each line decides its kind (the section below). It converts to and from JSON, and names and text can be in any language ([notation guide](https://github.com/cardene777/dragon/blob/main/packages/dragon/examples/quick-start.en.md)) |
22
+ | Renderer | Draws the source on a page and plays it one step at a time. It draws sequence, architecture, state, git, time, and tree diagrams |
23
+ | Export | The `dragon export` command writes MP4, GIF, HTML, and PNG from the same source |
18
24
 
19
- この package は次の 4 つを持つ。
25
+ ## A first diagram
20
26
 
21
- | 持つ物 | 形 |
22
- |---|---|
23
- | 原本 | 共通の骨格と図の種類ごとの欄を持つ JSON。版を持ち、古い版は読む時に変換する |
24
- | 記法 | 行の頭の英語の語で行の種類が決まる dragon記法 (下の節)。JSON と行き来でき、名前と文は日本語でも書ける ([書き方](https://github.com/cardene777/dragon/blob/main/packages/dragon/examples/quick-start.md)、[英語の書き方](https://github.com/cardene777/dragon/blob/main/packages/dragon/examples/quick-start.en.md)) |
25
- | 描く部品 | 原本から時系列図と構成図を描き、段ごとに動かす部品。cdl には頼らない |
26
- | 書き出し | 同じ原本から mp4、GIF、HTML、PNG を書き出す命令 |
27
+ ```dragon
28
+ sequence Ask to sign in
29
+
30
+ box browser as User's browser [note: operated by the user, color: slate]
31
+ box app as App [note: asks for sign-in, color: blue]
32
+
33
+ step Press sign in
34
+ say The user presses the app's sign-in button.
35
+ browser -> app: GET /login
36
+ ```
37
+
38
+ Paste it into the editor on the catalog to watch it play, or put it on your own page as the next section shows.
27
39
 
28
- ## 頁に置く
40
+ ## Put it on a page
29
41
 
30
- 頁で 1 度だけ字の入口 `@cardenelabs/dragon/fonts` を import し、記法を読んだ原本を `mountDiagram` に渡す。
42
+ Import the font entry `@cardenelabs/dragon/fonts` once on the page, and pass the source read from the notation to `mountDiagram`.
31
43
 
32
44
  ```ts
33
45
  import "@cardenelabs/dragon/fonts";
@@ -42,22 +54,22 @@ if (host === null) throw new Error("#figure not found");
42
54
  const player = mountDiagram(host, parsed.diagram);
43
55
  ```
44
56
 
45
- 字の入口は、同梱の 2 つの字 (Noto Sans JP と JetBrains Mono) の CSS を読み込むだけで、何も出さない。
46
- 図は同梱の字で測った字の幅で組むため、読み込まないと端末の字で描かれ、札から字がはみ出すことがある。
47
- CSS と字の file は、束ねる道具 (Vite など) が頁へ運ぶ。
48
- この入口は Node の組み込みの module を読まないため、Next.js の Turbopack のように頁を束ねる道具でもそのまま読める。
49
- 原本の file を今の版へ移す `migrateFile` は、Node でだけ動く入口 `@cardenelabs/dragon/node` から引く。
57
+ The font entry only loads the CSS for the two bundled fonts (Noto Sans JP and JetBrains Mono) and exports nothing.
58
+ Diagrams are laid out with character widths measured from the bundled fonts, so without it they are drawn in the device's fonts and text can overflow its labels.
59
+ A bundler (such as Vite) carries the CSS and font files to the page.
60
+ The entry does not read Node's built-in modules, so it also works with bundlers such as Next.js Turbopack.
61
+ `migrateFile`, which moves a source file to the current format version, comes from the Node-only entry `@cardenelabs/dragon/node`.
50
62
 
51
- `mountDiagram` が返す `player` で段を動かす (`next`、`prev`、`play`、`pause`、`destroy`)。
52
- 3 つめの引数には色味や段が替わった時に呼ぶ関数などの設定 (`PlayerOptions`) を渡す。
53
- 置いた時に流さず決めた段の止め絵で止めて置くには `pausedAt` に段の番号 (0 から) を、1 度だけ流して最後の段で止めるには `playOnce: true` を渡す。
54
- `still: true` を渡すと、最後の段の止め絵に全ての段の線の名前と箱の中の処理を最後の段と同じ濃さで出し、動かさない読者にも流れ全体を 1 枚で見せる。
55
- `still` は `renderDiagram` にも渡せる。
56
- どれも渡さなければ、置いた時から全ての段を繰り返し流す。
63
+ Use the `player` returned by `mountDiagram` to move through the steps (`next`, `prev`, `play`, `pause`, `destroy`).
64
+ The third argument takes settings (`PlayerOptions`), such as the palette and a function called when the step changes.
65
+ To place a diagram stopped on a still of one step, pass the step number (from 0) as `pausedAt`, and to play it once and stop on the last step, pass `playOnce: true`.
66
+ `still: true` stops on the last step, shows every step's line labels and box actions as strongly as the last step's, and does not move, so readers who do not play the diagram still see the whole flow in one picture.
67
+ `renderDiagram` also takes `still`.
68
+ Without any of these, the diagram plays every step on a loop from the moment it is placed.
57
69
 
58
- 色味は名前 (`palette`) で選び、`colors` に色の変数の名前と値を渡すと、渡した色だけを描く明暗 (`theme`) の色として上書きする。
59
- 鍵は色味が持つ名前 (`bg`、`surf`、`ink`、`line`、`c-green`、`t-green` など。型は `ColorName`) で、渡さない色は名前で選んだ色味の値のまま残る。
60
- 置いた図、寄って追う時の全体図、釦と段の帯のどれも同じ色で塗る。`renderDiagram` も同じ `colors` を受ける。
70
+ Choose colors by name with `palette`, and pass color variable names and values in `colors` to override only those colors for the current `theme`.
71
+ The keys are the names the palette has (`bg`, `surf`, `ink`, `line`, `c-green`, `t-green`, and so on; the type is `ColorName`), and the colors you leave out keep the palette's values.
72
+ The placed diagram, the overview shown while following, and the buttons and step bar all use the same colors, and `renderDiagram` takes the same `colors`.
61
73
 
62
74
  ```ts
63
75
  mountDiagram(host, parsed.diagram, {
@@ -66,13 +78,13 @@ mountDiagram(host, parsed.diagram, {
66
78
  });
67
79
  ```
68
80
 
69
- 色味に無い名前と、`;`、`"`、`<` などを含む色として読めない値を渡すと、その名前を挙げて描かずに断る。
81
+ A name the palette does not have, or a value that cannot be read as a color (one that contains `;`, `"`, `<`, and so on), is refused with that name and nothing is drawn.
70
82
 
71
- ## 図の種類の部品を後から読む
83
+ ## Load diagram kinds on demand
72
84
 
73
- 頁が最初に読む量を抑えたい時は、`@cardenelabs/dragon/light` から読む。
74
- 既定の入口と同じ部品を出すが、`git`、`lineup`、`state`、`time`、`tree` の描く部品を持たず、`loadKind` を待った時に読む。
75
- 読んだ後は既定の入口と同じ関数で、待たずに同じ図を描く。
85
+ To keep what a page loads first small, import from `@cardenelabs/dragon/light`.
86
+ It exports the same functions as the default entry, but leaves out the renderers for `git`, `lineup`, `state`, `time`, and `tree` and loads them when you await `loadKind`.
87
+ After that, the same functions as the default entry draw the same diagram without waiting.
76
88
 
77
89
  ```ts
78
90
  import { loadKind, mountDiagram, parseNotation } from "@cardenelabs/dragon/light";
@@ -84,234 +96,234 @@ if (parsed.ok) {
84
96
  }
85
97
  ```
86
98
 
87
- 読んでいない種類を描くと、その種類の名前を含む誤りで止まる。
88
- 読み込みが落ちると `loadKind` が拒否され、次に呼ぶと読み直す。
89
- `sequence` と `architecture` は初めから持つので、`loadKind` を呼ばなくても描ける。
90
- 1 つの頁で既定の入口と混ぜると、全ての種類の部品が頁に入る。
99
+ Drawing a kind that has not been loaded stops with an error that names the kind.
100
+ If loading fails, `loadKind` rejects, and the next call loads it again.
101
+ `sequence` and `architecture` are there from the start, so they draw without calling `loadKind`.
102
+ Mixing it with the default entry on one page puts every kind's renderer on the page.
91
103
 
92
- ## dragon記法
104
+ ## Notation
93
105
 
94
- どの行も次の決まり 4 つに従う。
106
+ Every line follows these four rules.
95
107
 
96
- 1. 行の種類は行の頭の英語の語で決まる。矢印の行だけは箱の名札から始まる
97
- 2. 鍵と値はコロンで区切り、属性は `[ ]` の中に `,` で並べる
98
- 3. 空白を含む名前と文は、行末か `[` の前に置く。`,` か `]` を含む値と、`[` を含む名前だけを `"` で囲む
99
- 4. 入れ子は `group … end` だけ。段は次の `step` までで、字下げは読みやすさのために付ける。`say` の続きの行だけは `say` より深く字下げする
108
+ 1. The first English word of a line decides its kind. Only arrow lines start with a box id
109
+ 2. A colon separates a key from its value, and attributes go inside `[ ]`, separated by `,`
110
+ 3. Names and text with spaces go at the end of the line or before `[`. Wrap only values that contain `,` or `]` and names that contain `[` in `"`
111
+ 4. The only nesting is `group … end`. A step runs until the next `step`, and indentation is for reading. Only the lines that continue a `say` must be indented deeper than `say`
100
112
 
101
- 行の頭の語は `sequence` `architecture` `state` `git` `time` `tree` `group` `end` `box` `branch` `scale` `period` `row` `point` `zoom` `strip` `step` `say` `code` `source` `commit` `mark` `span` `leaf` `node` `act` `note` `set` で、線の行は `名札 -> 名札` と書く。
102
- 箱の行の属性 `link` に飛び先を書くと、描いた図でその箱が飛び先への link になる。
103
- 段の中の `source <名前> [url: <URL>]` の行は段の出典になり、1 つの段に何行でも書け、読み上げの段の一覧に名前の link で出る。
104
- 飛び先と出典の URL には、`/` で始まる path か、`http://` か `https://` で始まる URL だけを書ける。
113
+ The words that start a line are `sequence` `architecture` `state` `git` `time` `tree` `group` `end` `box` `branch` `scale` `period` `row` `point` `zoom` `strip` `step` `say` `code` `source` `commit` `mark` `span` `leaf` `node` `act` `note` `set`, and a line is written as `id -> id`.
114
+ A destination in the `link` attribute of a box line makes that box a link in the drawn diagram.
115
+ A `source <name> [url: <URL>]` line inside a step is a source of that step; a step can have any number, and they are listed as links in the step list that screen readers read.
116
+ A destination or source URL is a path that starts with `/`, or a URL that starts with `http://` or `https://`.
105
117
 
106
118
  ```dragon
107
- architecture 注文を倉庫へ回す
119
+ architecture Send orders to the warehouse
108
120
 
109
- group 店側 as 店 [note: 注文を受ける側, color: blue, icon: cart]
110
- box 受付 [note: 注文を受ける, icon: app]
121
+ group shop as Shop [note: takes orders, color: blue, icon: cart]
122
+ box intake as Intake [note: takes the order, icon: app]
111
123
  end
112
124
 
113
- group 倉庫側 as 倉庫 [note: 品物を送る側, color: green, icon: box]
114
- box 出荷 [note: 品物を送る, icon: truck]
125
+ group warehouse as Warehouse [note: ships the goods, color: green, icon: box]
126
+ box shipping as Shipping [note: ships the goods, icon: truck]
115
127
  end
116
128
 
117
- step 出荷に回す
129
+ step Pass to shipping
118
130
  say
119
- 受付が注文の番号を 2 つまとめて出荷に回す。
120
- 出荷は届いた番号の順に品物を送る。
121
- 受付 -> 出荷: 送ってよい [tag: "#42, #43"]
131
+ Intake bundles two order numbers and passes them to shipping.
132
+ Shipping sends the goods in the order the numbers arrive.
133
+ intake -> shipping: OK to ship [tag: "#42, #43"]
122
134
  ```
123
135
 
124
- `parseNotation` は記法を原本の JSON に、`printNotation` は原本の JSON を記法に直す。
125
- 誤りの文の言葉は `parseNotation(text, { lang: "en" })` のように渡した言葉で決まり、渡さなければ日本語になる。
126
- 前の形の記法 (`時系列図` か `構成図` で始まる形) は読まず、その行の新しい形を示す誤りで止まる。
127
- 前の形と新しい形の対応表は [`CHANGELOG.md`](https://github.com/cardene777/dragon/blob/main/CHANGELOG.md) にある。
136
+ `parseNotation` turns the notation into the source JSON, and `printNotation` turns the source JSON back into the notation.
137
+ Error messages are in the language you pass, as in `parseNotation(text, { lang: "en" })`, and are in Japanese when you pass none.
138
+ The old form of the notation (starting with `時系列図` or `構成図`) is not read, and stops with an error that shows the new form of that line.
139
+ The table from the old form to the new one is in [`CHANGELOG.md`](https://github.com/cardene777/dragon/blob/main/CHANGELOG.md).
128
140
 
129
- ### 状態遷移図
141
+ ### State diagram
130
142
 
131
- `state` で始めると、1 つの物が状態を移る様子を段ごとに追う状態遷移図になる。箱が状態で、線は状態から状態への移り変わり。
132
- 線の送る側に `start` を書くと始まりの印から出る線に、受ける側に `finish` を書くと終わりの印へ入る線になる。
133
- 最初の `step` より前に書いた線は、移れるが今回は通らない道として点線で引く。
143
+ Starting with `state` makes a state diagram that follows one thing moving between states step by step. Each box is a state, and each line is a move from one state to another.
144
+ Write `start` on the sending side for a line out of the start mark, and `finish` on the receiving side for a line into the end mark.
145
+ Lines written before the first `step` are paths the diagram could take but does not this time, drawn dotted.
134
146
 
135
147
  ```dragon
136
- state 注文が届くまでの状態
148
+ state States of an order until it arrives
137
149
 
138
- box 支払い待ち [note: 入金を待つ, color: amber, icon: clock]
139
- box 発送済み [note: 業者が運ぶ, color: violet, icon: truck]
140
- box 配達完了 [note: 受け取られた, color: green, icon: check]
141
- box キャンセル [note: 払った分は返す, color: rose, icon: x]
150
+ box awaiting as Awaiting payment [note: Waits for funds, color: amber, icon: clock]
151
+ box shipped as Shipped [note: With the carrier, color: violet, icon: truck]
152
+ box delivered as Delivered [note: Handed over, color: green, icon: check]
153
+ box cancelled as Cancelled [note: Payment returned, color: rose, icon: x]
142
154
 
143
- 支払い待ち -> キャンセル: 取り消す
144
- キャンセル -> finish
155
+ awaiting -> cancelled: Cancel
156
+ cancelled -> finish
145
157
 
146
- step 注文する
147
- say 注文を確定すると、支払い待ちから始まる。
148
- start -> 支払い待ち: 注文を確定 [tag: #1042]
158
+ step Place the order
159
+ say Confirming the order starts it at Awaiting payment.
160
+ start -> awaiting: Place order [tag: #1042]
149
161
 
150
- step 発送する
151
- say 入金を確かめて品物を送り、発送済みに移る。
152
- 支払い待ち -> 発送済み: 発送 [tag: #1042]
162
+ step Ship
163
+ say Once the payment clears, the goods go out and the order moves to Shipped.
164
+ awaiting -> shipped: Ship [tag: #1042]
153
165
 
154
- step 届く
155
- say 品物が届いて配達完了に移り、注文を閉じる。
156
- 発送済み -> 配達完了: 受け取り [tag: #1042]
157
- 配達完了 -> finish: 注文を閉じる [tag: #1042]
166
+ step Arrive
167
+ say The goods arrive, the order moves to Delivered, and it closes.
168
+ shipped -> delivered: Receive [tag: #1042]
169
+ delivered -> finish: Close the order [tag: #1042]
158
170
  ```
159
171
 
160
- ### 枝分かれの図
172
+ ### Git graph
161
173
 
162
- `git` で始めると、git の枝に commit を積み、取り込むまでを段ごとに追う枝分かれの図になる。枝は `branch` の行で上から順に宣言し、枝ごとに帯が並ぶ。
163
- 段の中では `commit <名札> on <枝>` で枝の先に commit を積み、`copy <元>` で当て直しの commit を、`merge <枝>` で merge commit を作る。`hash` と `note` で丸の外に hash と一言を添える。
164
- `<枝> from <commit>` で枝を切り、`<札> -> <commit>` で commit を作らずに枝の札か `HEAD` を動かす。どの札からも辿れなくなった commit は点線の丸に変わる。
174
+ Starting with `git` makes a git graph that follows commits stacking on branches until they are merged, step by step. Declare branches on `branch` lines from the top, and each branch gets its own band.
175
+ Inside a step, `commit <id> on <branch>` adds a commit to the tip of the branch, `copy <source>` makes a replayed commit, and `merge <branch>` makes a merge commit. `hash` and `note` put a hash and a short note beside the circle.
176
+ `<branch> from <commit>` cuts a branch, and `<ref> -> <commit>` moves a branch ref or `HEAD` without making a commit. A commit that no ref can reach any more turns into a dotted circle.
165
177
 
166
178
  ```dragon
167
- git fix は merge commit で、feature は当て直して取り込む
179
+ git Merge fix with a merge commit and replay feature
168
180
 
169
- branch main [note: 取り込む先]
170
- branch feature [note: 作業の枝]
171
- branch fix [note: 直しの枝]
181
+ branch main [note: Target]
182
+ branch feature [note: Work branch]
183
+ branch fix [note: Fix branch]
172
184
 
173
- step 枝を切る
174
- say main の A から fix と feature を切り、それぞれに commit を積む。
175
- commit A on main [hash: 3fa0c19, note: 最初の形]
185
+ step Cut branches
186
+ say Cut fix and feature from A on main, and add a commit to each.
187
+ commit A on main [hash: 3fa0c19, note: First shape]
176
188
  fix from A
177
- commit F on fix [hash: 9b2e4d1, note: 誤字を直す]
189
+ commit F on fix [hash: 9b2e4d1, note: Fix a typo]
178
190
  feature from A
179
- commit C on feature [hash: c41d0e5, note: 検索を足す]
191
+ commit C on feature [hash: c41d0e5, note: Add search]
180
192
 
181
- step merge commit で取り込む
182
- say fix を merge commit M で main へ取り込む。M は A と F の 2 つを親に持つ。
183
- commit M on main merge fix [hash: 7d3a5e2, note: fix を取り込む]
193
+ step Merge commit
194
+ say Merge fix into main with merge commit M. M has two parents, A and F.
195
+ commit M on main merge fix [hash: 7d3a5e2, note: Merge fix]
184
196
 
185
- step 当て直す
186
- say HEAD を M へ動かして枝から離し、C を M の先へ写して C' を作る。
197
+ step Replay
198
+ say Move HEAD to M to detach it, and copy C onto M as C'.
187
199
  HEAD -> M
188
- commit C' on main copy C [hash: a90c6b4, note: 検索を足す]
200
+ commit C' on main copy C [hash: a90c6b4, note: Add search]
189
201
 
190
- step 早送りする
191
- say feature を C' へ動かし、main も C' まで進める。元の C はどの枝からも辿れなくなる。
202
+ step Fast-forward
203
+ say Move feature to C', and move main up to C' too. The old C can no longer be reached from any branch.
192
204
  feature -> C'
193
205
  main -> C'
194
206
  ```
195
207
 
196
- ### 時間軸の図
208
+ ### Time diagram
197
209
 
198
- `time` で始めると、決まった間隔で進む時間の上で、出来事がどの目盛りで起きたかを段ごとに追う時間軸の図になる。`scale <単位> <長さ> <数>` で目盛りを宣言し、`period` で区切りを、`row` で印の列を、`point` で軸の下の節目を、`zoom <範囲>` で上の帯に拡大する目盛りを宣言する。
199
- 段の中では `now -> <目盛り>` で針を進める。針は目盛り 1 つを決まった速さで進み、過ぎた目盛りの印がその時に出る。`mark` で印の色を変え、`span` で軸の下に範囲の括弧か、印の列を囲む枠を出す。
200
- 中身の帯の欄に `[meter: <割合>]` を付けると物差しになり、`set` で書いた割合まで針と一緒に満ちる。
210
+ Starting with `time` makes a time diagram that follows, step by step, which tick each event happens on along evenly spaced time. `scale <unit> <length> <count>` declares the ticks, `period` the periods, `row` a row of marks, `point` a point below the axis, and `zoom <range>` the ticks to zoom in on in the top band.
211
+ Inside a step, `now -> <tick>` moves the needle. The needle moves one tick at a fixed speed, and the marks of the ticks it passes appear as it goes. `mark` changes the color of marks, and `span` puts a bracket under the axis or a frame around the rows.
212
+ `[meter: <ratio>]` on a strip field makes a meter that fills with the needle up to the ratio written with `set`.
201
213
 
202
214
  ```dragon
203
- time ブロックが確定して戻せなくなるまで
215
+ time How a block becomes final
204
216
 
205
217
  scale slot 12s 64
206
218
  period epoch 32
207
- row ブロック [color: blue, empty: 5]
219
+ row block [color: blue, empty: 5]
208
220
  point C0 at 0
209
221
  point C1 at 32
210
222
  zoom 0-1
211
223
 
212
- box 提案者 [color: blue, icon: user]
213
- box ブロック [color: blue, icon: box]
224
+ box proposer [color: blue, icon: user]
225
+ box block [color: blue, icon: box]
214
226
 
215
- strip 確定の進み: 経過, 今の epoch の票 [meter: 2/3]
227
+ strip Finality: Elapsed, Votes this epoch [meter: 2/3]
216
228
 
217
- step ブロックを出す
218
- say slot ごとに提案者が 1 人選ばれ、ブロックを 1 つ出す。上の帯は最初の 2 slot を拡大した所。
219
- 提案者 -> ブロック [at: 0]
220
- 提案者 -> ブロック [at: 1]
229
+ step Propose blocks
230
+ say In each slot one proposer is chosen and proposes one block. The top band zooms in on the first 2 slots.
231
+ proposer -> block [at: 0]
232
+ proposer -> block [at: 1]
221
233
  now -> 1
222
- set 経過: 24 秒
234
+ set Elapsed: 24 s
223
235
 
224
- step 1 epoch 分の票を集める
225
- say 32 slot で 1 epoch。針が過ぎた slot にブロックの印が出て、提案者が応答しなかった slot は空きの印になる。
226
- note C0: 提案済み [color: blue]
227
- span 0-31: 1 epoch = 6.4 分 [color: slate]
236
+ step Collect one epoch of votes
237
+ say 32 slots make one epoch. A block mark appears on each slot the needle passes, and a slot whose proposer did not answer gets an empty mark.
238
+ note C0: Proposed [color: blue]
239
+ span 0-31: 1 epoch = 6.4 min [color: slate]
228
240
  now -> 31
229
- set 経過: 6 分 24 秒
230
- set 今の epoch の票: 97%
241
+ set Elapsed: 6 min 24 s
242
+ set Votes this epoch: 97%
231
243
 
232
- step 次の epoch へ進む
233
- say C0 への票が全体の 2/3 を超えたので、C0 は正当化される。次の epoch では C1 へ票が集まる。
234
- note C0: 正当化 [color: violet]
235
- note C1: 提案済み [color: blue]
244
+ step Move to the next epoch
245
+ say Votes for C0 passed 2/3 of the total, so C0 is justified. In the next epoch, votes gather on C1.
246
+ note C0: Justified [color: violet]
247
+ note C1: Proposed [color: blue]
236
248
  now -> 63
237
- set 経過: 12 分 48 秒
238
- set 今の epoch の票: 97%
239
-
240
- step C0 が確定する
241
- say C1 も正当化されると、続けて正当化された 2 つのうち前の C0 が確定する。確定したブロックは戻せない。
242
- C0 -> C1: 2/3 を超えた [carry: none]
243
- note C1: 正当化 [color: violet]
244
- note C0: 確定 [color: green]
245
- mark ブロック 0-31 [color: green]
246
- span 0-31: 確定して戻せない [shape: box, color: rose]
249
+ set Elapsed: 12 min 48 s
250
+ set Votes this epoch: 97%
251
+
252
+ step C0 becomes final
253
+ say Once C1 is justified too, the earlier of the two justified in a row, C0, becomes final. A final block cannot be undone.
254
+ C0 -> C1: over 2/3 [carry: none]
255
+ note C1: Justified [color: violet]
256
+ note C0: Final [color: green]
257
+ mark block 0-31 [color: green]
258
+ span 0-31: Final, cannot be undone [shape: box, color: rose]
247
259
  ```
248
260
 
249
- ### 木の図
261
+ ### Tree diagram
250
262
 
251
- `tree` で始めると、葉の値を親へ畳み上げて1つの根にまとめる構造を段ごとに追う木の図になる。段の中の `leaf <名札> [hash: <値>]` で葉を、`node <名札> of <子>, <子> [hash: <値>]` で親を書くと、書いた段で箱が現れる。
252
- 葉は書いた順に左から並び、親は子の真ん中の上に置かれ、どの親にも組まれなかった箱が根になる。
253
- 親子の箱どうしの線の運ぶ物は木の線の上を走り、通った木の線はその色で残る。木の線を運ぶ物が通った段から後は、運ぶ物を送るか受けた箱だけを濃く出す。
263
+ Starting with `tree` makes a tree diagram that follows, step by step, how leaf values fold up into their parents until one root remains. Inside a step, `leaf <id> [hash: <value>]` writes a leaf and `node <id> of <child>, <child> [hash: <value>]` writes a parent, and each box appears in the step that writes it.
264
+ Leaves line up from the left in written order, a parent sits above the middle of its children, and the box that no parent takes becomes the root.
265
+ A carrier on a line between a parent and a child runs along the tree line, and the tree line keeps that color once passed. From the step a carrier first runs on a tree line, only the boxes that send or receive carriers are drawn strongly.
254
266
 
255
267
  ```dragon
256
- tree 取引が含まれることを確かめる
257
-
258
- step 取引ごとに値を出す
259
- say 4件の取引それぞれから値を出す。この値が木の葉になる。
260
- leaf 取引1 [hash: 3fa0]
261
- leaf 取引2 [hash: 8b04]
262
- leaf 取引3 [hash: c41d]
263
- leaf 取引4 [hash: e5f8]
264
-
265
- step 2つずつ組む
266
- say 隣どうしの値を2つずつつないで、もう1度値を出す。親が2つできる。
267
- node 1と2 of 取引1, 取引2 [hash: 7a21]
268
- node 3と4 of 取引3, 取引4 [hash: b9e4]
269
-
270
- step 根ができる
271
- say 残った2つを組むと、全ての取引の値をまとめた根が1つできる。
272
- node 根 of 1と2, 3と4 [hash: e71c]
273
-
274
- step 取引3から根まで上る
275
- say 隣の値を受け取りながら親へ上る。取引1と取引2を読まなくても、根の値が出る。
276
- 取引3 -> 3と4 [tag: c41d]
277
- 取引4 -> 3と4 [tag: e5f8]
278
- 3と4 -> 根 [tag: b9e4]
279
- 1と2 -> 根 [tag: 7a21]
268
+ tree Proving a transaction is included
269
+
270
+ step Hash each transaction
271
+ say Compute a value from each of the 4 transactions. These values become the leaves.
272
+ leaf tx1 [hash: 3fa0]
273
+ leaf tx2 [hash: 8b04]
274
+ leaf tx3 [hash: c41d]
275
+ leaf tx4 [hash: e5f8]
276
+
277
+ step Pair them up
278
+ say Join neighbouring values two at a time and hash again. Two parents appear.
279
+ node 1to2 of tx1, tx2 [hash: 7a21]
280
+ node 3to4 of tx3, tx4 [hash: b9e4]
281
+
282
+ step The root appears
283
+ say Joining the last two gives one root that sums up every transaction.
284
+ node root of 1to2, 3to4 [hash: e71c]
285
+
286
+ step Climb from tx3 to the root
287
+ say Take the neighbouring value at each level and climb. The root comes out without reading tx1 or tx2.
288
+ tx3 -> 3to4 [tag: c41d]
289
+ tx4 -> 3to4 [tag: e5f8]
290
+ 3to4 -> root [tag: b9e4]
291
+ 1to2 -> root [tag: 7a21]
280
292
  ```
281
293
 
282
- ## 書き出し
294
+ ## Export
283
295
 
284
- 書き出しは画面なしの Chromium で、頁と同じ描画を時刻を止めて 1 コマずつ撮る。
285
- 撮ったコマは同じ Chromium の中で mp4 と GIF に詰めるので、ffmpeg は要らない。
286
- Chromium を動かす `playwright-core` は、書き出しを使う時だけ入れる。
296
+ Export uses a headless Chromium and captures the same drawing as the page one frame at a time, with the clock stopped.
297
+ The captured frames are packed into MP4 and GIF inside the same Chromium, so ffmpeg is not needed.
298
+ Install `playwright-core`, which runs Chromium, only when you use export.
287
299
 
288
300
  ```sh
289
301
  pnpm add -D playwright-core
290
302
  pnpm exec playwright-core install chromium
291
303
  ```
292
304
 
293
- 原本の JSON (`.json`) か記法 (`.dragon`) を渡すと、同じ名前の 4 つの file を書き出す。
305
+ Pass the source JSON (`.json`) or the notation (`.dragon`) and it writes four files with the same name.
294
306
 
295
307
  ```sh
296
308
  dragon export ccip.json --out out
297
309
  ```
298
310
 
299
- | 設定 | 意味 |
311
+ | Option | Meaning |
300
312
  |---|---|
301
- | `--out <dir>` | 書き出す先。無ければ作る (既定は今の dir) |
302
- | `--width <px>` | 枠の幅。見せ方 (全体を止める / 寄って追う) を選び、寄って追う窓の幅になる |
303
- | `--palette <名前>` | 色味 (`clear` / `paper` / `night`、既定は `paper`) |
304
- | `--theme <明暗>` | `light` か `dark` |
305
- | `--lang <言葉>` | 図の中の字 (全体図の札、HTML の読み上げの名前、描けない時の断りの文) と、命令が出す使い方の文と誤りの文の言葉 (`ja` か `en`)。記法の file でも JSON の原本でも、既定は `ja` |
306
- | `--fps <数>` | mp4 の 1 秒のコマの数 (既定 30) |
307
- | `--gif-fps <数>` | GIF の 1 秒のコマの数 (既定 10) |
308
- | `--format <形>` | 書き出す形を `,` で区切る (既定 `mp4,gif,html,png`) |
309
-
310
- PNG は最後の段の止め絵を、全体を止めた見せ方で撮る。
311
- 図の中で字が重なる段がある時は、書き出したうえで重なりを段と文で 1 件 1 行ずつ標準エラーに出す (例 `段 5: 段の番号 1 と段の番号 5 が重なる`)。終わり方は 0 のまま変えない。
312
- HTML は図で描く字だけに削った字の file を埋めた 1 file で、外へ何も取りに行かない。
313
- node から呼ぶ時は `@cardenelabs/dragon/export` の `exportDiagram` を使う。
314
-
315
- ## license
313
+ | `--out <dir>` | Where to write. Created if missing (default: the current dir) |
314
+ | `--width <px>` | Frame width. Picks the view (`fixed` / `follow`) and sets the window width for `follow` |
315
+ | `--palette <name>` | Colors (`clear` / `paper` / `night`, default `paper`) |
316
+ | `--theme <mode>` | `light` or `dark` |
317
+ | `--lang <lang>` | Language of the text in the diagram (overview labels, the names read in HTML, and the message when it cannot draw) and of the command's usage and error messages (`ja` or `en`). Defaults to `ja` for both notation files and source JSON |
318
+ | `--fps <n>` | Frames per second of the MP4 (default 30) |
319
+ | `--gif-fps <n>` | Frames per second of the GIF (default 10) |
320
+ | `--format <formats>` | The formats to write, separated by `,` (default `mp4,gif,html,png`) |
321
+
322
+ The PNG is a still of the last step in the `fixed` view.
323
+ When text overlaps in some step, the export still finishes and prints each overlap on its own line to standard error, with the step and the text (with `--lang en`, for example `Step 5: Step number 1 and step number 5 overlap`). The exit code stays 0.
324
+ The HTML is a single file with fonts cut down to the characters the diagram draws, and it fetches nothing from outside.
325
+ To call it from Node, use `exportDiagram` from `@cardenelabs/dragon/export`.
326
+
327
+ ## License
316
328
 
317
329
  MIT