@xtframe/skills 0.0.0-stage → 0.19.1

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