@xtframe/skills 0.0.0-stage → 0.18.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 (35) hide show
  1. package/README.md +22 -2
  2. package/package.json +41 -4
  3. package/payload/plugins/xtframe/.claude-plugin/plugin.json +17 -0
  4. package/payload/plugins/xtframe/.codex-plugin/plugin.json +11 -0
  5. package/payload/plugins/xtframe/gemini-extension.json +5 -0
  6. package/payload/plugins/xtframe/skills/xtui/SKILL.md +218 -0
  7. package/payload/plugins/xtframe/skills/xtui/references/canvas.md +90 -0
  8. package/payload/plugins/xtframe/skills/xtui/references/dialect.md +799 -0
  9. package/payload/plugins/xtframe/skills/xtui/references/flow.md +338 -0
  10. package/payload/plugins/xtframe/skills/xtui/references/not-like-web.md +358 -0
  11. package/payload/plugins/xtframe/skills/xtui/references/performance.md +162 -0
  12. package/payload/plugins/xtframe/skills/xtui/references/responsive.md +137 -0
  13. package/payload/plugins/xtframe/skills/xtui/references/style-groups.md +378 -0
  14. package/payload/plugins/xtframe/skills/xtui/references/template.dc.html +56 -0
  15. package/payload/plugins/xtframe/skills/xtui/references/tokens.json +42 -0
  16. package/payload/plugins/xtframe/skills/xtui/references/ui-project.md +161 -0
  17. package/payload/plugins/xtframe/skills/xtui/references/upgrade.md +140 -0
  18. package/payload/plugins/xtframe/skills/xtui/references/vector.md +219 -0
  19. package/payload/plugins/xtframe/skills/xtui/references/verify.md +327 -0
  20. package/payload/plugins/xtframe/skills/xtui-editor/SKILL.md +209 -0
  21. package/payload/plugins/xtframe/skills/xtui-editor/references/design.md +158 -0
  22. package/payload/plugins/xtframe/skills/xtui-editor/references/ops.md +849 -0
  23. package/payload/plugins/xtframe/skills/xtui-editor/references/recipes.md +70 -0
  24. package/payload/plugins/xtframe/skills/xtui-editor/references/scenarios.md +180 -0
  25. package/payload/plugins/xtframe/skills/xtui-editor/references/service.md +167 -0
  26. package/src/agents.mjs +73 -0
  27. package/src/bin.mjs +4 -0
  28. package/src/cli.mjs +286 -0
  29. package/src/converter.mjs +73 -0
  30. package/src/fsutil.mjs +76 -0
  31. package/src/install.mjs +154 -0
  32. package/src/packs.mjs +150 -0
  33. package/src/plugins.mjs +109 -0
  34. package/src/proc.mjs +66 -0
  35. package/src/tar.mjs +103 -0
@@ -0,0 +1,338 @@
1
+ Read this when the user wants the UI to react (selection, hover previews, counters, bars, timers, screen flow, a demo mode, "make it work"): it is how to write and check `<ui>.xtflow`.
2
+
3
+ **A flow drives; it never interpolates.** It triggers and selects (counters, timers, selection, screen flow, simulated game values); the motion itself (parallax, spinning, glides) belongs to `bind:`, `@timeline`/`animation` and `transition` (see **Rules**, below).
4
+
5
+ # Flow: making a UI interactive
6
+
7
+ Writes `<project-dir>/<ui>/<ui>.xtflow`, makes sure the `.xtui` points at it, and checks it with
8
+ `xtframe-view`. Format reference: `<xtframe>/Docs/design/53-flow-language.md` (the format §53.2,
9
+ every node §53.4, connection points §53.5, rules §53.6). Worked example, with a
10
+ generator: `<xtframe>/tests/import/fixtures/dc/difficulty-select/gen_flow_v2.py` and
11
+ `difficulty-select.v2.xtflow` (35 nodes, 88 edges).
12
+
13
+ Arguments: `<project-dir>` (the UI Project) and `<ui-id>` (required), plus the interaction spec in plain words. Find
14
+ `<xtframe>` and the binaries as in SKILL.md step 0. The UI is static until this file exists;
15
+ the board and the flow have different lifetimes (a re-import keeps the `.xtflow`).
16
+
17
+ ## 1. Inventory the connection points
18
+
19
+ Read `<project-dir>/<ui>/<ui>.xt`. Every element the flow touches needs an **authored** `id`.
20
+ Imported ids of the form `n-xxxxxxxx` are content hashes: they change when the design changes, so
21
+ never bind to one. If a needed element has no authored id, stop and ask for it to be added on the
22
+ board (then re-import) rather than binding to the hash.
23
+
24
+ On an existing UI Project you can also see what a running flow holds:
25
+
26
+ ```
27
+ xtframe-view <ui>.xt --headless --frames 3 --dump-flow-values
28
+ ```
29
+
30
+ List, for the user, the ids you will use and what each is for.
31
+
32
+ ## 2. Ports and types
33
+
34
+ Element `#id` outputs: `Click` `PointerEnter` `PointerLeave` `Focus` `Blur` `AnimationEnd` (pulse),
35
+ `Change` (string), `hover` (bool).
36
+ Element inputs: `setText` `setStyle` `setValue` (string), `addClass` `removeClass` `toggleClass`
37
+ (pulse, edge param `class`), `focus` (pulse), `setProperty` (number, edge param `prop` = a PropId
38
+ name such as `RotationX`, `RotationY`, `TranslateX`, `ScaleX`; continuous sources must not reach it, see Rules), `playAnimation` (string: a
39
+ `@keyframes` name) and `stopAnimation` (pulse), `setState` (pulse, edge params `state` = a custom state name or a built-in alias, and
40
+ `mode` = `on`/`off`/`toggle`, default `on`; the flow form of the `state()` trigger action; T-541).
41
+ `<anim>` elements: outputs `Marker` (string), `localTime` (number), `Finished` (pulse); inputs
42
+ `play` `pause` `resume` (pulse), `seek` (number, seconds), `setSpeed` (number).
43
+ `#document` outputs: `clock` `viewportWidth` `viewportHeight` `pointerX` `pointerY` `pointerNX`
44
+ `pointerNY` (number; NX/NY are −1..1 with 0 at the viewport centre), `pointerDown` (bool)
45
+ (continuous sources must not reach a visual input; see Rules).
46
+ Declared ports (the `.xt`'s `<ports>`; 53 §53.5.4): **`#document.<port>`** is the endpoint of a
47
+ port of the document -- the form to write. `#<root id>.<port>` (the board root's id, where the
48
+ ports sat before source format 2) still resolves to the same port as a compatibility alias and
49
+ the editor's flow lint reports it as `flow.rootPortAlias` (info; fix: rewrite as
50
+ `#document.<port>`; 53 §53.5.4, T-604; `xtframe-compile` and `xtframe-import --lint` do not list
51
+ it yet), and `xtframe-compile --migrate` rewrites such endpoints. A port of a symbol instance is
52
+ `#<instance id>.<port>`. An **`out`** port is a **source** the flow reads; an **`in`** (or `call`)
53
+ port is a **sink** the flow writes (`set(port)`). The flow cannot read an `in` port (`port
54
+ '#<id>.<p>' is an input (in/call) port`) nor write an `out` port: to let it see a value the host
55
+ writes into an `in` port, mirror it on the board (`on:port(lang)="set(lang_out, port(lang))"`)
56
+ and read `lang_out`. A port named like a built-in element port (`Click`, `setText`…) cannot be
57
+ addressed from a flow.
58
+
59
+ Nodes (params → input ports → output ports); all **24** types, each specified in
60
+ 53 §53.4 (`<xtframe>/Docs/design/53-flow-language.md`):
61
+
62
+ | type | params | inputs | outputs |
63
+ |---|---|---|---|
64
+ | `constant` | `value` | — | `out` |
65
+ | `counter` | `step` `initial` `min` `max`, `wrap` (bool, default false: past `max` jump to `min` and back, no clamping) | `increment` `decrement` `reset` (pulse), `set` (number) | `value` (number) |
66
+ | `toggle` | `initial` (bool) | `toggle` `setTrue` `setFalse` (pulse) | `value` (bool), `changed` (pulse) |
67
+ | `timer` | `interval` (s), `autostart` (bool), `repeat` (bool, default true) | `start` `stop` (pulse) | `tick` (pulse), `count` (number) |
68
+ | `clock` | — | — | `seconds` (number) |
69
+ | `random` | `min` `max` `integer` | `trigger` (pulse) | `value` (number) |
70
+ | `math` | `op`: `add sub mul div min max clamp map abs round mod`; `lo/hi` for clamp, `inLo/inHi/outLo/outHi` for map; `mod` = float remainder with the sign of `a`, `b` 0 gives 0 | `a` `b` (number) | `out` (number) |
71
+ | `compare` | `op`: `eq ne lt le gt ge` | `a` `b` (same type) | `out` (bool), `true` `false` (pulse) |
72
+ | `toString` | `format` (`{}`), `decimals` | `in` (any value) | `out` (string) |
73
+ | `select` | — | `cond` (bool), `a` `b` (same type) | `out` (type inferred from `a`/`b`) |
74
+ | `radio` | `count` (2..64), `initial` | `set0`…`set<count-1>` (pulse), `set` (number) | `index` (number), `changed` (pulse) |
75
+ | `lookup` | `values` (array of one type) | `index` (number, clamped) | `out` (element type) |
76
+ | `merge` | — | `in` (pulse, many edges) | `out` (pulse) |
77
+ | `format` | `format` with `{a}` `{b}` `{c}` `{d}`, `decimals` | `a` `b` `c` `d` | `out` (string) |
78
+ | `filter` | `op`: `deadband` `quantize` `sample`; `threshold` (>= 0, deadband), `step` (> 0, quantize) | `in` (number, bool or string; `quantize` takes a number; type inferred like `select`), `trigger` (pulse, `sample` only), `reset` (pulse) | `out` (type of `in`), `passed` (pulse) |
79
+ | `throttle` | `unit`: `frames` `seconds` `hz`; `rate`; `trailing` (bool, default true) | `in` (any type, a pulse too), `rate` (number, optional: overrides the param), `reset` (pulse) | `out` (type of `in`), `passed` (pulse), `dropped` (number) |
80
+ | `state` | `states` (2..64 names), `initial` (default: the first), `transitions` (`[{from, on, to}]`, `from` may be `"*"`), `events` (default: the `on` names) | one pulse per event name, `set` (string: jump to a state), `guard` (bool, false swallows the events) | `state` (string), `index` (number), `changed` (pulse), `enter<Name>` `exit<Name>` (pulse, per state) |
81
+ | `lifecycle` | — | — (the UI's own surface: shown when it first appears visible and on every `requestShow` / `show`, hidden when it finishes hiding; UI flows only, the global flow uses `ui#<ui>.shown` / `hidden`) | `shown` `hidden` (pulse) |
82
+ | `system` | — | — (the host's `postSystemEvent`) | `loading` `paused` `resumed` `disconnected` `back` (pulse), `languageChanged` `platform` `inputDevice` `reducedMotion` (string, sent on every post) |
83
+ | `sound` | `cue`, `volume` (default 1) | `trigger` (pulse) | — (a host event) |
84
+ | `haptic` | `cue` | `trigger` (pulse) | — (a host event) |
85
+ | `spawn` | `symbol` | `trigger` (pulse) | — (a host event) |
86
+ | `emit` | `port` | `trigger` (pulse), `value` (any; stored) | — (a host event with the last `value`; to a declared `out` port it also writes that port, so bindings on it update) |
87
+ | `timeline` | `name`, `scope` (element id), `ui` (global flow only), `loop` (bool), `rate` (default 1), `hold` (bool, default false: when true the last frame stays, like the trigger `play()`; false returns to the base values) | `play` `stop` (pulse), `seek` (number, s) | `end` (pulse), `marker` (string) |
88
+
89
+ Rules the loader enforces:
90
+
91
+ - An edge's two ends must have the same type. Exceptions: any value may feed `toString.in` and
92
+ `format.a`…`d`, and a **pulse input accepts any source** (the value is discarded, arrival is the
93
+ trigger).
94
+ - A **value** input takes exactly **one** edge. Exceptions: `#id.setStyle` accepts several edges
95
+ (each is merged property by property, like the runtime `setStyle`), and `#id.setProperty` edges
96
+ are distinguished by their `prop` parameter.
97
+ - No cycles. A pulse-only self loop (`timer.tick → timer.stop`) is not a cycle; anything else that
98
+ closes a loop fails to load.
99
+ - Every problem is printed and the flow refuses to run — there is no partial load.
100
+
101
+ File shape:
102
+
103
+ ```json
104
+ { "version": 1,
105
+ "nodes": [ { "id": "sel", "type": "radio", "params": { "count": 5, "initial": 1 } } ],
106
+ "edges": [ { "from": "#diff-apex.PointerEnter", "to": "sel.set4" },
107
+ { "from": "lv.out", "to": "#root.toggleClass", "params": { "class": "dark" } } ] }
108
+ ```
109
+
110
+ ## Rules: a flow drives, it never interpolates
111
+
112
+ A flow only **triggers** and **selects**. An edge whose source is a **continuous signal** and whose
113
+ destination is a **visual input** (`#id.setProperty`, `#id.setStyle`, a `#id.playAnimation` string that
114
+ changes every frame) is the flow animating, and is not allowed.
115
+
116
+ - **Continuous sources**: `#document.clock` `pointerX` `pointerY` `pointerNX` `pointerNY` `viewportWidth`
117
+ `viewportHeight`, `clock.seconds`, `<anim>.localTime`, an element's `hover` value, and anything
118
+ that passed through `math`, `toString`, `format` or `select` (`a`/`b`) on the way. `compare` (its bool and
119
+ pulse outputs), `lookup` and `select.cond` end the marking: they discretise.
120
+ - **Fine**: discrete sources to visual inputs (`radio.index → lookup → setStyle`, `Click → playAnimation`),
121
+ and continuous sources to non-visual ends (`clock.seconds → toString → setText`, `pointerNX → compare →
122
+ toggleClass`, any `set(port)` edge, node inputs). Declared ports, `counter`/`radio`/`toggle`
123
+ values and `timer.count` are discrete however often they change.
124
+ - `xtframe-view` (and `xtframe-pack`, and the editor's flow panel through its Messages) prints
125
+ `flow.animatesWithContinuousSignal` for every offending edge: `warning:` normally, `error:` with `--strict`.
126
+ **Any such line must be rewritten before you deliver the flow** (section 6, step 1).
127
+ - **The three replacement paths** (none of them goes through the flow):
128
+ 1. **Pointer parallax**: a `pointermove` trigger writes declared `in` ports, `bind:` reads them
129
+ (recipe below).
130
+ 2. **Clock-driven decoration** (breathing, sweeps, spinning rings, marquees): an `@timeline` with
131
+ `loop`, or an `animation` declaration with `infinite`. The clock number on screen
132
+ (`clock.seconds → toString → setText`) is a non-visual end and stays valid.
133
+ 3. **Delayed states**: a trigger `then` chain, `on:state(X).enter` / `.exit` timelines, the binding
134
+ converters `delay(t)` / `tween(d)`; a flow `timer` may fire the trigger (`tick → toggleClass`
135
+ or `→ setState`).
136
+ - A simulated game value (demo mode) is the one place the flow computes numbers every frame: send
137
+ it through `set(port)` (recipe below).
138
+
139
+ ## 3. Patterns
140
+
141
+ - **One-of-N state** (a menu, a tab strip): **one `radio`** with `count: N`. Each item's
142
+ `Click`/`PointerEnter`/`Focus` goes to `sel.set<k>`. Every per-item value is then **one `lookup`**
143
+ whose `values` array is indexed by `sel.index` — one node per driven property, not one per item.
144
+ (This is what turned the worked example from 196 nodes / 352 edges into 40 / 99.)
145
+ - **Per-state styling**: prefer `lookup` → `#id.addClass`/`toggleClass` when the board authored the
146
+ states as classes (the import keeps authored classes), otherwise a `lookup` of whole declaration
147
+ strings → `#id.setStyle`. `setStyle` takes several edges now, so independent properties may come
148
+ from separate tables.
149
+ - **Show / hide**: `visibility: visible` / `visibility: hidden` through a `lookup`. `opacity: 0` and
150
+ `<img>` + `visibility` both work correctly, so use whichever the design calls for; a wrapper
151
+ `<div>` with `overflow: hidden` whose `height` toggles is still the sturdiest switch when the
152
+ element must also stop taking space.
153
+ - **Numbers to bars**: `toString("width: {}%") → setStyle`, or `format` when the bar's colour
154
+ changes with the value.
155
+ - **Text from several sources**: `format` with `{a}{b}` instead of chaining `toString`s.
156
+ - **Pointer parallax on a 3D panel** (replacement path 1; not a flow): the root's `on:pointermove`
157
+ writes two declared `number in` ports, and the panels read them with `bind:`. The flow is not
158
+ involved, and nothing needs an `.xtflow` for it. `a` is the panel's authored resting angle, so the
159
+ rest pose still matches the design:
160
+
161
+ ```xml
162
+ <ports>
163
+ nx: number in
164
+ ny: number in
165
+ </ports>
166
+ <body>
167
+ <div id="root" on:pointermove="set(nx, pointer.fraction(#root).x | range(0, 1, -1, 1)); set(ny, pointer.fraction(#root).y | range(0, 1, -1, 1))">
168
+ <div id="world-layer" bind:translate-x="nx | range(-1, 1, 30, -30)"> ... </div>
169
+ <div id="panel" bind:rotate-y="nx | range(-1, 1, a-8, a+8)" bind:rotate-x="ny | range(-1, 1, 6, -6)"> ... </div>
170
+ </div>
171
+ </body>
172
+ ```
173
+
174
+ Use real numbers for `a-8` / `a+8` (an authored 24deg gives `16, 32`; a reversed range such
175
+ as `32, 16` flips the direction). `bind:` knows `rotate-x`, `rotate-y`, `rotate`, `translate-x`,
176
+ `translate-y`, `translate-z`, `scale-x`, `scale-y` and also `left`/`top` (a layer that is moved by
177
+ `left`/`top` keeps its `transition: left ..., top ...` glide from the stylesheet). The trigger
178
+ element must cover the viewport (the root) or be `pointer-watch: true`. Several elements may read
179
+ the same port. `#root`/`#panel` above are ids you chose on the board.
180
+ - **Clock-driven decoration** (replacement path 2): `animation: ring-spin 7.2s linear 0s infinite`
181
+ on the element, with `@keyframes ring-spin { from { transform: rotate(0deg); } to { transform: rotate(360deg); } }`
182
+ in the stylesheet (50 deg/s is `360 / 50 = 7.2s`; a counter-rotating ring is `-360deg`), or an
183
+ `@timeline` with `loop`. Never `clock.seconds → math → setStyle`.
184
+ - **Delayed state**: `then` in a trigger chain, an `on:state(X).enter="play(...)"` timeline, `delay(0.15s)` in a binding;
185
+ from a flow, `timer {interval, autostart, repeat: false}` and let its `tick` fire a discrete action
186
+ (`addClass`, `setState`, or a toggle whose bool value is written to a port).
187
+ - **Timed state** (a 2.4 s deploy bar): `timer` with `interval`, `autostart: false`,
188
+ `repeat: false`; the trigger goes to `start`, and `tick` resets the state. `repeat: false` stops
189
+ it after the single tick, so a later `start` runs it again.
190
+ - **Firing an authored animation**: `#id.playAnimation` with the `@keyframes` name as the string
191
+ (duration/easing come from that element's own `animation` declaration, else 1 s linear);
192
+ `stopAnimation` to cancel. Prefer a `transition` on the element plus `setStyle` for simple
193
+ state changes.
194
+ - **Demo mode / simulating the game**: the flow may compute a simulated game value (from `clock`,
195
+ `timer`, `random`, `counter`), but it must be written to a **declared port** with an edge to
196
+ `#document.<port>`, and the UI reads that port with the same `bind:` as in the real game. The sim then
197
+ exercises the exact bindings the host will use, and `set(port)` is a non-visual end, so there is
198
+ no warning. Put `filter` (drop jitter) and `throttle` (a host-like update rate) between the maths
199
+ and the port; give the bound element a `transition` or `tween(0.2s)` for the smooth motion
200
+ (the flow only sends targets):
201
+
202
+ ```json
203
+ { "version": 1,
204
+ "nodes": [ { "id": "clock", "type": "clock" },
205
+ { "id": "hpRaw", "type": "math", "params": { "op": "map", "inLo": 0, "inHi": 60, "outLo": 100, "outHi": 0 } },
206
+ { "id": "hpSim", "type": "math", "params": { "op": "clamp", "lo": 0, "hi": 100 } },
207
+ { "id": "hpQuiet", "type": "filter", "params": { "op": "deadband", "threshold": 0.5 } },
208
+ { "id": "hpRate", "type": "throttle", "params": { "unit": "hz", "rate": 10 } } ],
209
+ "edges": [ { "from": "clock.seconds", "to": "hpRaw.a" },
210
+ { "from": "hpRaw.out", "to": "hpSim.a" },
211
+ { "from": "hpSim.out", "to": "hpQuiet.in" },
212
+ { "from": "hpQuiet.out", "to": "hpRate.in" },
213
+ { "from": "hpRate.out", "to": "#document.hp" } ] }
214
+ ```
215
+
216
+ ```xml
217
+ <ports>
218
+ hp: number in = 100
219
+ </ports>
220
+ <body>
221
+ <div id="hud">
222
+ <div id="hp-fill" bind:width="hp | range(0, 100, 0%, 100%) | tween(0.2s, ease-out)"></div>
223
+ <span id="hp-text" bind:text="hp | round(0)">100</span>
224
+ </div>
225
+ </body>
226
+ ```
227
+
228
+ Drop the sim edges (or the whole `.xtflow`) and the real game writes `hp` through the same port.
229
+ `clock.seconds → toString → #id.setText` for a plain clock readout needs no port.
230
+ - **Many triggers, one action**: `merge` (pulse inputs already accept many edges, but `merge` keeps
231
+ the graph readable when the fan-in is large).
232
+ - **Run once on load** (53 §53.1.3, seeding): when the graph loads, every node pushes its starting
233
+ output once -- a `constant`'s value, `counter`/`toggle`/`radio`/`state` initial values, the
234
+ recomputed nodes evaluated once. **Values** reach their sinks: a `constant` (or `radio.initial →
235
+ lookup`) wired to `#id.setText` / `setStyle` / `setValue` / a declared `in` port sets the starting
236
+ text, style or port. Seeding is **not a delivery of pulses**: `compare` fires no `true` /
237
+ `false`, `state.set` and `timeline.seek` ignore it, and a `constant` wired to a pulse input is no
238
+ start signal (`constant → timer.start` never starts the timer) -- never rely on seeding to fire a
239
+ pulse. So a starting class or state goes on
240
+ the board (or through a value path such as `radio.index → lookup → setStyle`), and a pulse that
241
+ must fire once when the UI appears comes from **`lifecycle.shown`** (53 §53.102): it fires in the
242
+ same frame, before the first update, so `lifecycle.shown → intro.play` paints the intro's first
243
+ frame on the first frame drawn (and again on every later `show`). The board's
244
+ `on:show="play(intro)"` does the same; pick one. An autostart timer
245
+ (`timer {autostart: true, repeat: false}`) is only for a real delay: its `tick` comes after the
246
+ first frames are already on screen, so an intro started from it flashes the final state first
247
+ (lint `flow.introByTimer` warns).
248
+ - **Wrap-around and remainders**: `counter {min, max, wrap: true}` cycles a carousel (one step past
249
+ `max` lands on `min`); `math {op: mod}` gives the remainder for "every Nth" logic
250
+ (53 §53.100).
251
+ - **Timeline that should stay at its end**: the flow `timeline` node returns to the base values when
252
+ it ends unless `hold: true` (the trigger `play()` holds by default; 53 §53.100).
253
+ - **Rate-limiting a port**: a host port that only needs a few updates a second (or a value that
254
+ jitters) goes through `filter` and `throttle` before it is written:
255
+ `#document.pointerNX → filter {op: deadband, threshold: 0.02} → throttle {unit: hz, rate: 10} →`
256
+ the declared `in` port (an edge to `#document.<port>`), with `bind:rotate-y` on the element reading
257
+ that port. `filter` and `throttle` only decide which values are sent (`deadband` and `quantize` drop
258
+ noise, `sample` sends on a `trigger`; `throttle` passes at most one value per window, the last
259
+ held value goes out when the window ends, and nothing is sent without an input); they make no
260
+ in-between values, so give the element a `transition` for the smooth motion. A `rate` that is 0,
261
+ negative, NaN or infinite turns the limit off, and wiring a number to `throttle.rate` changes it while
262
+ running. `unit: frames` with `trailing: false` on a `Click` is a double-click guard.
263
+
264
+ ## 3b. The global flow and the host
265
+
266
+ - **Global flow** (`bundle.xtflow`; addresses `ui#<uiId>.<element>.<port>` / `ui#<uiId>.<port>`,
267
+ 53 §53.5.5): an endpoint whose UI is not registered yet is **dormant**, not an error -- its edges
268
+ neither send nor receive until the host adds that UI, and they go dormant again when it is
269
+ removed; node state (radio, counter, state) is never reset by this (late binding, T-582). When a
270
+ UI is added, every value edge into it is sent the source's current value once (pulses are not
271
+ replayed, T-583), so a settings screen opened later still shows the selection the flow already
272
+ holds. Errors stay errors: `ui#` in a UI's own flow, `#id.port` in the global flow, a wrong
273
+ direction or type, and a global `timeline` node whose `ui` names an unregistered UI.
274
+ - **What the host sees** (53 §53.101, 22 §22.15): `xtframe-pack` writes each UI's flow interface
275
+ into the bundle manifest as `uis[].flowInterface` (and a top-level one for the global flow):
276
+ `emits` (the `emit` nodes' port names and value types), `writes` (in ports the flow sets),
277
+ `reads` (out ports the flow reads) and `system` (the wired `system` outputs). An `in` port the
278
+ flow writes and the host also writes is a conflict to avoid; `ports.out[].origin` tells
279
+ `document`, `trigger` and `flow` events apart.
280
+
281
+ ## 4. Write it
282
+
283
+ **Who writes it.** This section is for a UI Project that is not open in the editor (this skill
284
+ writes the file). When the editor has the UI open, change the flow through the editor instead:
285
+ the `xtui-editor` skill's `flow_get` / `flow_set` (one undo step, saved with `doc_save`), so the
286
+ editor does not end up with a stale graph. If you did write the file while an editor had it open,
287
+ that editor must `doc_reload` the UI.
288
+
289
+ Beyond ~40 edges, write a small generator next to the UI Project (`gen_<ui>.py`) and generate the
290
+ `.xtflow` from it; commit both. The script holds the data table (one row per option), a `node()` /
291
+ `edge()` helper and a `table()` helper for the `lookup` pattern, and nothing else. Copy the shape
292
+ from `Tests/import/fixtures/dc/difficulty-select/gen_flow_v2.py`.
293
+
294
+ ## 5. Register it in the UI Project
295
+
296
+ Write the file as `<project-dir>/<ui>/<ui>.xtflow` — exactly that name. The editor, `xtframe-view`
297
+ and (from T-359) the packer `xtframe-pack` all pick up a sibling `<ui>.xtflow` of that name even
298
+ when the `.xtui` does not list it; still register it. The importer registers it in the `.xtui` on
299
+ the next import and **never overwrites it**, even on a re-import. If the UI Project has not been
300
+ re-imported since, or the flow has a different name, add `"flow": "<ui>/<ui>.xtflow"` to that UI's
301
+ entry in the `.xtui` by hand (a differently named flow is found only through that entry).
302
+
303
+ ## 6. Check it
304
+
305
+ 1. Load it: `xtframe-view <project-dir>/<ui>/<ui>.xt --headless --frames 3`. The sibling
306
+ `<ui>.xtflow` is loaded automatically and stderr says `xtframe-view: loaded flow <path>`; no such
307
+ line means the file is misnamed or misplaced. Read every `warning:` line that follows: each
308
+ `flow.animatesWithContinuousSignal` names an edge to rewrite with the Rules above (add `--strict` to
309
+ make it an error and a non-zero exit); never deliver a flow that still prints it. `xtframe-view <project-dir> --ui <ui>`
310
+ does the same through a Bundle packed from the UI Project and proves the registration from
311
+ step 5. A load or type
312
+ error prints one line per problem and exits 2. (`--flow <file>` still loads a differently named
313
+ graph; `--no-flow` runs without any.)
314
+ 2. Values: add `--dump-flow-values` (and `--dump-every N` to watch them change); every output port
315
+ prints as `<node>.<port> = <value>` (a pulse prints the literal `pulse`).
316
+ 3. Drive the interaction, no user needed:
317
+ `--event "<frame> #<id>.<Port>"` (repeatable; `Click`, `PointerEnter`, `PointerLeave`, `Focus`,
318
+ `Blur`, `Change=<value>`), `--event "<frame> key <name>"` for a key (it goes to the focused
319
+ element, so focus it first; 08 §8.20, 22 T-571 record) and `--pointer "<frame> <x> <y>
320
+ [move|down|up]"`. All apply just before that frame's update, so give earlier frames time to lay
321
+ out (frame 2+).
322
+ 4. Per state: `--print-text <id>` (repeatable) for the bound texts and
323
+ `--screenshot <abs-path>.png` for the look. Look at every screenshot.
324
+ 5. Anything you could not reach headless (long hover chains, a real mouse path), say so and ask the
325
+ user to try it in the editor's Demo mode.
326
+
327
+ Example — select the third item at frame 2, lean the pointer, and capture the result:
328
+
329
+ ```
330
+ xtframe-view difficulty-select.xt --headless --frames 6 \
331
+ --event "2 #diff-veteran.PointerEnter" --pointer "3 900 300 move" \
332
+ --print-text diff-tab --dump-flow-values --screenshot D:/tmp/veteran.png
333
+ ```
334
+
335
+ ## 7. Report
336
+
337
+ Node and edge counts, the ids bound and what drives each, one screenshot per state, the
338
+ `--dump-flow-values` block for the interesting states, and the paths you could not verify.