@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.
- package/README.md +22 -2
- package/package.json +41 -4
- package/payload/plugins/xtframe/.claude-plugin/plugin.json +17 -0
- package/payload/plugins/xtframe/.codex-plugin/plugin.json +11 -0
- package/payload/plugins/xtframe/gemini-extension.json +5 -0
- package/payload/plugins/xtframe/skills/xtui/SKILL.md +245 -0
- package/payload/plugins/xtframe/skills/xtui/references/canvas.md +93 -0
- package/payload/plugins/xtframe/skills/xtui/references/dialect.md +874 -0
- package/payload/plugins/xtframe/skills/xtui/references/flow.md +339 -0
- package/payload/plugins/xtframe/skills/xtui/references/from-procedural.md +140 -0
- package/payload/plugins/xtframe/skills/xtui/references/not-like-web.md +358 -0
- package/payload/plugins/xtframe/skills/xtui/references/performance.md +182 -0
- package/payload/plugins/xtframe/skills/xtui/references/responsive.md +137 -0
- package/payload/plugins/xtframe/skills/xtui/references/style-groups.md +404 -0
- package/payload/plugins/xtframe/skills/xtui/references/template.dc.html +56 -0
- package/payload/plugins/xtframe/skills/xtui/references/tokens.json +101 -0
- package/payload/plugins/xtframe/skills/xtui/references/ui-project.md +170 -0
- package/payload/plugins/xtframe/skills/xtui/references/upgrade.md +141 -0
- package/payload/plugins/xtframe/skills/xtui/references/vector.md +223 -0
- package/payload/plugins/xtframe/skills/xtui/references/verify.md +349 -0
- package/payload/plugins/xtframe/skills/xtui-editor/SKILL.md +219 -0
- package/payload/plugins/xtframe/skills/xtui-editor/references/design.md +158 -0
- package/payload/plugins/xtframe/skills/xtui-editor/references/ops.md +988 -0
- package/payload/plugins/xtframe/skills/xtui-editor/references/recipes.md +70 -0
- package/payload/plugins/xtframe/skills/xtui-editor/references/scenarios.md +211 -0
- package/payload/plugins/xtframe/skills/xtui-editor/references/service.md +175 -0
- package/src/agents.mjs +73 -0
- package/src/bin.mjs +4 -0
- package/src/cli.mjs +286 -0
- package/src/converter.mjs +73 -0
- package/src/fsutil.mjs +76 -0
- package/src/install.mjs +154 -0
- package/src/packs.mjs +150 -0
- package/src/plugins.mjs +109 -0
- package/src/proc.mjs +66 -0
- 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.
|