@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,358 @@
1
+ # Where XTFrame is not HTML/CSS
2
+
3
+ The board is HTML, but what runs is XTFrame: the importer turns it into a `.xt` (source format 2:
4
+ the sections `<ports>`, `<body>`, `<layout>`, `<style>`, `<timelines>`; the look in the UI's `.xts`,
5
+ linked as `<style src>`), and the engine is not a browser. Read this page first; each line is one
6
+ difference and the way to write it. The `.xt`/`.xts` forms are what the import produces and what
7
+ `xtframe-compile` checks; on a board the same intent goes through the `data-xt-*` tags of
8
+ `dialect.md` (`data-xt-bind="target=expr"`, `data-xt-port`, `data-xt-trigger`).
9
+
10
+ ## Layout and painting
11
+
12
+ - **Geometry only in `<layout>`** (54 §54.1, §54.5). Position, anchoring, size, margin and
13
+ padding, flex and grid, `order`, `z-index`, `overflow`, `layer`, 3D space and the responsive
14
+ switches are written in the `<layout>` section, everything else (colour, border, text, opacity,
15
+ effects, `cursor`) in `<style>`; a `width` in `<style>` is the error `style.geometryInStyle`, a
16
+ `color` in `<layout>` is `layout.notGeometry`. No one rule holds both: the same selector appears
17
+ once in each section. `display: none` is the one geometry value `<style>` may write. On a board
18
+ you still write ordinary CSS; the import splits it (`style-groups.md`, column Section, lists
19
+ where each property goes).
20
+ - **Always border-box.** There is no `box-sizing`; `width`/`height` include padding and border.
21
+ A ring that sticks out of its box: an absolute child with `left/top/right/bottom: -5px`.
22
+ - **`display` is `block | flex | grid | none`.** No `inline`, `inline-block`, `contents`, `table`.
23
+ Lay rows out with `display: flex` (`grid` is a fixed-track subset).
24
+ - **An element holds either text or child elements** (07 §7.8, 05 §5.9.3). Text whose children
25
+ are all inline markup (`<span>`, `<b>`, `<i>`, `<u>`, `<s>`, `<a>`, `<glyph>`, `<img inline>`)
26
+ is folded into one rich text: each child becomes a run of that text, not an element, so an
27
+ `id`, `bind:` or `on:` on it does nothing (text beside a `<div>` child is an error). To keep
28
+ the child an element, put the text beside it in its own `<span>`:
29
+ `<div><span>Volume</span><span id="Val" bind:text="vol"></span></div>`, not
30
+ `<div>Volume <span id="Val" bind:text="vol"></span></div>`. (lint: `web.textWithChildren`)
31
+ - **`position` is `static | relative | absolute`.** No `fixed` or `sticky`: put the element at
32
+ document level with `position: absolute`.
33
+ - **No global stacking.** `z-index` only reorders siblings. To draw above everything and escape
34
+ `overflow: hidden`, give the subtree `layer: overlay` -- a `<layout>` property
35
+ (`#Confirm { layer: overlay; }`), never an attribute (`<div layer="overlay">` does nothing).
36
+ Inside an overlay container, a child that must cover a nested overlay needs `layer: overlay` too.
37
+ - **`pointer-events` is inherited.** A full-screen container for dialogs takes every click; write
38
+ `pointer-events: none` on the container and `pointer-events: auto` on each panel root.
39
+ - **A `<use>` instance root is a sized box** that takes clicks even when everything inside is
40
+ `display: none`; hide the instance itself (`display: none` on `#Confirm`), or use the line above.
41
+ - **Flex items have no min-content minimum** (06 §6.9). CSS stops a shrinking flex item at its
42
+ longest word (`min-width: auto`); XTFrame lets it shrink to 0, so text wraps into a sliver or
43
+ overflows. Give text items a `min-width` or `flex-shrink: 0`; the import flags the case as
44
+ `layout.flexShrinkText` (24 §24.14.5).
45
+ - **`height: N%` on a child of an `auto`-height parent is nothing** (06 §6.4). A `%` height
46
+ resolves only against a parent whose height is set (px or a resolvable `%`) or comes from
47
+ `top` + `bottom` on an absolute parent (a child of `<body>` takes the viewport's); when the
48
+ parent's height comes from its content, the `%` counts as `auto`. Give the parent a height
49
+ (`#Panel { height: 320px; }`), or size the child with flex: in a `display: flex` parent write
50
+ `size: auto fill` in `<layout>` (or `flex-grow: 1` in a column). (lint: `web.percentHeightOnAuto`)
51
+ - **`translateZ` sorts whole layers, not pixels** (19 §19.6). 3D layers are drawn far to near by
52
+ the depth of each layer's anchor; two planes that intersect never cut through each other (one
53
+ covers the other entirely), and a 2D sibling between 3D siblings splits them into separate sort
54
+ groups. Keep crossing planes apart in z.
55
+ - **`vw`/`vh` do not follow `uiscale`** (05 §5.9.9). px (with em, font sizes, borders, radii and
56
+ shadows) is multiplied by the UI scale; `vw`, `vh`, `vmin` and `vmax` follow the viewport only.
57
+ Write the size in px (`width: 480px`, not `width: 25vw`) unless it must follow the viewport.
58
+ (lint: `web.vwVhVsUiscale`)
59
+
60
+ ## Data and bindings
61
+
62
+ - **Ports have a direction, and each side reads one of them** (53 §53.5.4, 27 §27.8 and the
63
+ T-568 / T-573 records). A **flow reads `out` ports** (as sources) and writes `in` ports (the
64
+ `set(port)` sink); it cannot read an `in` port. The **board binds `in` ports**: a `bind:` whose
65
+ source is an `out` port compiles with the warning `bind.outPortSource`. Such a binding still
66
+ updates when the host calls `setPort` on that out port, and when a flow `emit` node sends to the
67
+ declared out port (the port is written first, then the host event goes out), but nothing else
68
+ feeds it. When both sides need one value, mirror it with `set()`: `on:port(lang)="set(lang_out,
69
+ port(lang))"` copies the host's `in` port to an `out` port the flow can read.
70
+ - **`bind:` beats a static class.** With `bind:class.paused="status | eq(Paused)"` the bound value
71
+ decides `paused` from the start (even before the port gets a value); a static `class="paused"`
72
+ on the same element is ignored. Bind it or write it, not both.
73
+ - **List ports are typed.** In `<ports>`: `rows: list<struct{title: string}> in` or a base-type
74
+ list `labels: list<string> in` (`number, string, bool, color, vec2, vec3, enum`; `<` needs no
75
+ escaping there, only in a board's `data-xt-port` attribute: `list&lt;...&gt;`). In a repeat
76
+ template `item(field)` reads a struct field and `item()` the whole entry; elsewhere
77
+ `bind:text="labels | item(2)"` reads entry 2 (out of range: the type's empty value -- `""`, `0`,
78
+ `false`). The host sends JSON: `[{"title":"A"}]` or `["a","b"]`; a default is the same JSON:
79
+ `labels: list<string> in = ["a","b"]`.
80
+ - **Lists nest.** A struct field can be a list itself, and a `<repeat>` inside a template repeats
81
+ that field with `port="item(<field>)"`. Inside the inner template `item()`, `index` and `count`
82
+ mean the inner list; `outer.item(field)` and `outer.index` read the enclosing entry (one level
83
+ only). Only the outermost repeat may `virtualize`.
84
+ ```xml
85
+ <ports>
86
+ groups: list<struct{name: string, rows: list<struct{t: string}>}> in
87
+ </ports>
88
+ <body>
89
+ <repeat port="groups" id="Rows">
90
+ <div id="Group"><span id="Title" bind:text="item(name)"></span>
91
+ <repeat port="item(rows)" id="Sub">
92
+ <span id="Cell" bind:text="format('{0}.{1} {2}', outer.index, index, item(t))"></span>
93
+ </repeat>
94
+ </div>
95
+ </repeat>
96
+ </body>
97
+ ```
98
+ Path ids nest (`Rows/2/Sub/0/Cell`); the host sends nested JSON
99
+ (`[{"name":"A","rows":[{"t":"x"}]}]`) or edits one inner list as the port `Rows/2.rows`. An
100
+ `emit` from an inner row reports the outer row's index; the inner index is in the element's
101
+ path id. A symbol may hold the inner repeat itself: declare `rows: list<struct{t: string}> in`
102
+ in the symbol's `<ports>`, write `<repeat port="rows" id="Sub">` inside it, and put the
103
+ instance in the outer template with `<use symbol="Row" id="Cell" bind:rows="item(rows)">`;
104
+ each outer row gets its own copy of the list (`Rows/2/Cell/Sub/0/X`, port `Rows/2/Cell.rows`)
105
+ and follows `listUpdate` of the outer row in place.
106
+ - **`bind:visible` keeps the space.** False means `visibility: hidden`: the box still takes its
107
+ place in the layout (it only stops painting and taking clicks). To remove it from the layout
108
+ write `bind:display="flag"` (false -> `display: none`, true -> the style sheet's `display`
109
+ again). `bind:disabled="flag"` sets the built-in `:disabled` state (no click, no focus).
110
+ - **`Disabled` is always the built-in state.** `bind:state.Disabled`, `:state(Disabled)`,
111
+ `state(Disabled, on)`, `requires="states: Disabled"` and the host's `setCustomState(x,
112
+ "Disabled", ...)` all mean `:disabled`; no custom state is made. It disables the whole subtree
113
+ for input (no press, click or focus inside, like `fieldset[disabled]`), but `:disabled` matches
114
+ only the element itself: style the inside with `#Root:disabled #Track { ... }`.
115
+ `Focused`, `Hover`, `Active` and `Checked` work the same way (`:focus`, `:hover`, `:active`,
116
+ `:checked`); `requires="states: Focused"` is met by `:focus`, `:focus-within` or
117
+ `:state(Focused)` in any selector of a group (`#Box:focus-within, :state(Focused) #Box`).
118
+ - **`<use>` state goes on the instance root.** `bind:state.Open` (or `state="Open"`) on a `<use>`
119
+ sets the state of the instance root, so a symbol rule reads it as an ancestor:
120
+ `:state(Open) #Inner { ... }`. `#Inner:state(Open)` is the inner element's own state and does
121
+ not match.
122
+ - **Text input: `bind:value`, `on:change`, `value`.** `<input bind:value="query"
123
+ on:change="set(query, value); emit(search)">`: the port fills the field (typing does not write
124
+ the port back), `on:change` and `on:input` fire on every edit, and `value` is the field's
125
+ current text (only inside those two triggers). The port value comes back over what the user
126
+ typed when the input is shown again (after `display: none` on it or an ancestor), after the
127
+ host's `restoreState`, and on the action `reset(value)` (e.g. `on:blur="reset(value)"`; only on
128
+ an element with `bind:value`). `focus()` with no argument focuses the element
129
+ itself, e.g. `on:state(Open).enter="focus()"`. `placeholder` is drawn while the value is empty
130
+ (focused too) in `color` at 50 % alpha, or in the `:root` token `--placeholder-color`; it may
131
+ be an `@key` (a key with no string draws nothing, never the key itself).
132
+ - **`on:focus` / `on:blur` do not bubble; `on:focusin` / `on:focusout` do.** Put
133
+ `on:focusin="play(glow)"` on a container to react when any field inside takes the focus
134
+ (the web's `focusin`). The host selects text with `ElementRef::selectAll()` /
135
+ `setSelection(start, end)` (UTF-8 byte offsets) and reads `selection()`; `focus()` on an element
136
+ under `display: none` is refused (`kUnsupported`) - show it first or use `on:show="focus()"` -
137
+ unless a port change made since the last frame may show it: then the focus lands in the next
138
+ `update()` once the element is laid out.
139
+ `setValue` works while it is hidden.
140
+ - **A hidden surface keeps running but is not laid out.** After `requestHide()` (or
141
+ `setInitialVisibility(false)`) its triggers, timelines, flow and bindings go on, layout and
142
+ painting stop, and the first shown frame lays it out again; `boundingBox` of a hidden UI is the
143
+ last shown one. `requestShow()` / `requestHide()` called from inside an event or host callback
144
+ take effect when that dispatch ends.
145
+ - **A plain attribute on `<use>` sets a port.** `<use symbol="Pager" id="P" icon="prev" count="3">`
146
+ gives the instance's in-ports `icon` and `count` those starting values (by the port's type; a
147
+ list or struct takes JSON). It cannot be combined with `bind:icon` on the same `<use>`, and an
148
+ out or event port cannot be set this way. `state="Dragging"` starts the instance in a custom
149
+ state the symbol declares or uses (for a static preview). An attribute that is no port of the
150
+ symbol is a warning under `--strict`, so a typo does not pass silently. Attribute names are
151
+ case-insensitive (`hasadv="false"` sets the port `hasAdv`), so two ports differing only in case are
152
+ an error.
153
+ - **Do not name a port `index`, `count`, `item` or `time`.** A declared port wins over the
154
+ reserved name, so inside a symbol with a port `index` the word `index` reads the port, not the
155
+ repeat (the compiler warns). Converter names (`format`, `scale`, `offset`...) are fine as port
156
+ names: after a `|` the name is always the converter. In a repeat
157
+ template `repeat.index`, `repeat.count` and `repeat.item(field)` always mean the repeat.
158
+ - **`<repeat>` is a box.** Its entries are children of the `<repeat>` element, never of its
159
+ parent: lay them out on the repeat (`#Rows { display: flex; flex-direction: column; }` in
160
+ `<layout>`), and do
161
+ not expect `order` to mix entries with elements outside it. Two repeats around a panel when one
162
+ panel must sit between entries.
163
+ - **Virtualizing is opt-in and narrow.** Write `<repeat virtualize>`; putting it in a scroll box
164
+ does not virtualize. Only equal-height, vertically stacked entries; never on a wrapping grid.
165
+ The scroll box needs a height: a 0 px viewport shows nothing and `xtframe-view --strict` warns
166
+ `virtualized repeat "X" has a zero-height viewport`.
167
+ - **Shared column widths: document tokens.** There is no `<table>`. Declare the widths once as
168
+ document tokens (`:root { --col-title: 240px; }` in `<style>`: tokens are declared there, never
169
+ in `<layout>`) and write `width: var(--col-title)` in the `<layout>` rules of the header and of
170
+ the row symbol; a symbol's `var()` reads the document's tokens.
171
+ - **Symbol styles cannot see ancestor classes.** In `symbol(Card) { ... }` the outermost selector
172
+ part matches the instance root or something inside it, so `symbol(Card) { .layout-tall #Box { } }`
173
+ never matches when `#Box` is an inner element (the compiler warns; a class the host adds at
174
+ run time is not visible to it). On the symbol's root (`.layout-tall #Card`, `#Card` its
175
+ top-level element) it is fine. Put the class on the `<use>` (`<use symbol="Card"
176
+ class="layout-tall">`), or feed a port and `bind:class.tall` inside the symbol.
177
+
178
+ ## Events
179
+
180
+ - **Keyboard activation is on by default.** With focus on a `<button>`, Enter and Space click it
181
+ (Space on a checkbox, Enter on other focusable elements); Tab and the arrows move focus. An app
182
+ that keeps Space for itself writes `<body key-activation="none">` (focus navigation stays).
183
+ - **`dblclick` exists** (`on:dblclick`); the first click still arrives as `click`. A host
184
+ listener reads `Event::clicks` (1 on the first click, 2 on the second and on DoubleClick).
185
+ - **A slider inside a symbol needs no host code.** `pointer.fraction(#Track).x` (0..1 across the
186
+ element, clamped) and `pointer.local(#Track).x` (px) are `set()` values, valid only in pointer
187
+ triggers (`press`/`pointerdown`, `release`/`pointerup`, `click`, `dblclick`, `hover`, `leave`,
188
+ `pointermove`, `pointercancel`, `pointerdrag`); `#Track` is an element of the same symbol.
189
+ `pointermove` goes to the pressed element while a button is held, so guard it with `if active`:
190
+
191
+ ```xml
192
+ <symbol name="Slider">
193
+ <ports>
194
+ value: number in
195
+ </ports>
196
+ <div id="Body"
197
+ on:pointerdown="set(value, pointer.fraction(#Track).x)"
198
+ on:pointermove="if active set(value, pointer.fraction(#Track).x)"
199
+ on:pointercancel="set(value, 0)">
200
+ <div id="Track"></div><div id="Thumb"></div></div>
201
+ </symbol>
202
+ ```
203
+
204
+ `pointercancel` comes instead of the release when the press is taken away (the window lost
205
+ focus, the pointer left it with the button held, or the host cancelled); no `click` follows.
206
+ Simpler: `on:pointerdrag` fires once per frame (latest position) after a left press on the
207
+ element moved `drag-threshold` px (default 4), until the release - no `draggable`, no ghost, no
208
+ `drag.*` events; `if dragging` is true while it runs; the release still fires `on:release`:
209
+
210
+ ```xml
211
+ <div id="Body"
212
+ on:pointerdown="set(value, pointer.fraction(#Track).x)"
213
+ on:pointerdrag="set(value, pointer.fraction(#Track).x)">
214
+ <div id="Track"></div><div id="Thumb"></div></div>
215
+ ```
216
+
217
+ (the same symbol, with `value` in its `<ports>`.)
218
+
219
+ The host hears these writes through `HostPorts::addInputListener(port, fn)` (only the UI's own
220
+ `set()` / bindings call it, never the host's own `set`).
221
+ - **Pick a mouse button in the trigger name.** `on:press(right)`, `on:release(left)`,
222
+ `on:click(middle)`, `on:dblclick(left)`, `on:pointermove(left)` (the button held); no button =
223
+ any. Conditions combine with `and` (no `or`: write two triggers): `if button(left)`, `if
224
+ state(Open)` (custom or `Hover`/`Active`/`Focus`/`Checked`/`Disabled`), `if port(value) gt 0.5`
225
+ (`eq ne gt lt ge le`, a constant), `if not ...`:
226
+ `on:click="if not state(Open) and port(count) eq 1 state(Open, on)"`. `if button()` only in a
227
+ pointer trigger.
228
+ - **`hit-slop` widens what a pointer hits, not the box.** A 6 px track with `hit-slop: 10px` (1-4
229
+ values like `margin`; px, `%`, `em`) is pressed 10 px around it; layout and paint do not change,
230
+ and an element with `clip-path` does not grow.
231
+ - **Wheel deltas are notches.** 1.0 = one line; a touchpad gives fractions.
232
+ - **List reorder by drag.** Make each row `draggable drop-target` inside the `<repeat>` and show
233
+ the insertion mark with `on:drag.over` / `on:drag.leave` (or the `DropHover` state). The host
234
+ listens for DragOver (sent on every move over a row) / Drop and reads `Event::dropIndex` (the
235
+ insertion index: the row under the pointer, +1 in its lower half; over the dragged row itself
236
+ that row counts; 0xFFFFFFFF off the list - a drop outside every target is only `DragEnd` with
237
+ `dropped == false`, so "before the first / after the last" is the host's call), plus
238
+ `dropFraction`, `sourceItem` / `targetItem` (the host's Drop event carries `dropFraction` too),
239
+ then reorders the list port. Undo the "dragging" look in `on:drag.cancel` (Escape, right
240
+ click, focus loss): no `drop` follows. Only the left button drags (`draggable="any-button"`:
241
+ any); Escape before the drag starts cancels the press (no click); after a cancel other buttons
242
+ do nothing until all are released. `drag-threshold="12"` on the row delays the start (default
243
+ 4 px); a drag never clicks; `drag-ghost="none"` draws no ghost (style `:state(Dragging)`
244
+ instead). An `overflow: scroll` list scrolls by itself while the pointer is within 24 px of its
245
+ edge, re-sending DragOver each frame; `drag-autoscroll="false"` on the list turns that off.
246
+ On a `<use>` these drag attributes are plain attributes, not ports. To bring entry `i` into
247
+ view (virtualized too, even right after `listInsert`) the host calls
248
+ `ElementRef::scrollIntoView("Rows", i, ScrollAlign::Center)` on the scroll container.
249
+ - **Files dragged in from the OS land on `drop-target` elements too.** No `<input type=file>`,
250
+ no `dragenter` / `dataTransfer`: the same `on:drag.over` / `on:drag.leave` / `on:drop` and
251
+ `DropHover` state fire (no `drag.start` / `drag.cancel`; hover only where the host reports it -
252
+ Windows does), `if external` tells them from an in-UI drag, and the host reads the paths from
253
+ its Drop event (`HostEvent::paths`, `Event::externalPaths`), never the UI. With no
254
+ `drop-target` under the pointer nothing fires and the OS shows the "no drop" cursor; to react as
255
+ soon as files enter the window, make `body` a `drop-target`. A `DragLeave` with
256
+ `Event::leftWindow` true means the drag left the window (false: it moved to another target).
257
+ - **Light-dismiss is `on:outsidepress`.** It fires on a visible element when a press lands
258
+ outside its subtree (a `layer: overlay` child still counts as inside), never bubbles, and
259
+ stops once the element is hidden, so a popover dismisses itself with
260
+ `<div id="Menu" on:outsidepress="hide()">...</div>` (and opens again with `show()`).
261
+ Modal-style: `on:outsidepress="consume(); hide()"` also takes that press - the element under
262
+ it gets no press, release or click - so no backdrop element is needed (`consume()` only there;
263
+ a host listener sets `Event::consume`). An element that becomes visible during that same press
264
+ does not get it.
265
+ - **`on:scroll` fires on the scroll container** (and bubbles) whenever its offset changes: the
266
+ wheel, a drag near its edge, or the host's `ElementRef::scrollTo / scrollBy / scrollIntoView`.
267
+ - **Path ids, not CSS paths.** `<instance id>/<inner id>` in a symbol, `<repeat id>/<i>/<template
268
+ id>` in a list (`Rows/3/Name`), `<instance id>.<port>` for a port; `byId` and the host port
269
+ lookup take them. A trigger on an element inside an instance goes on the `<use>` as
270
+ `on:<event>@<inner path>` (`<use symbol="Tabs" id="Pages" on:press@T1="set(tab, 0)">`); there
271
+ are no `on-<event>` style rules. Inner ids are flat: `Seek/Track` even when
272
+ `Track` sits inside `Root` in the symbol (not `Seek/Root/Track`); only a nested `<use>` or
273
+ `<repeat>` adds a segment.
274
+ - **`emit` names.** `emit(<port>)` of a declared `out`/`event` port reaches the host as that port
275
+ (from a symbol instance: the instance's port). An undeclared `emit(winClose)` is sent verbatim
276
+ as the host event name, with no instance prefix, so a host (or a headless test) matches it
277
+ literally.
278
+
279
+ ## Language
280
+
281
+ - **The host switches the language; the UI never does** (13 §13.8, 07 §7.8). Texts written as
282
+ keys (`@menu_title`, from `data-xt-key` on the board) are resolved by the host's
283
+ `ILocalizationProvider` for the language set with `Context::setLanguage(lang)`; that call
284
+ re-lays out every document and re-picks the font fallback chain. No trigger action and no flow
285
+ node calls `setLanguage`. `postSystemEvent("languageChanged", lang)` only tells the flows (the
286
+ `system` node's `languageChanged`) and the documents' `system.*` ports. A UI that must switch
287
+ language without host strings uses an `enum` port and `select(...)` per text instead.
288
+
289
+ ## Styles
290
+
291
+ - **`@media` works, within limits.** `min-/max-width`, `min-/max-height` (px only),
292
+ `aspect-ratio`, `orientation`, `platform`, `input`, `prefers-reduced-motion`, `resolution`. No
293
+ nested `@media`, no `symbol()` blocks or token declarations inside one, no `@container`.
294
+ Unsupported queries are dropped with a warning.
295
+ - **An animated effect needs a base effect in the static style** (18 §18.4: every keyframe and
296
+ the element must list the same effect functions). The importer now adds the missing base itself
297
+ for a `@keyframes` or `data-xt-timeline` that animates `filter`, `box-shadow` or
298
+ `backdrop-filter`, and says so (`effect.baseAdded`, 24 §24.14.3 and the T-567 record). It cannot
299
+ for a `@keyframes` that only a class rule starts (a trigger adds the class): write the effect in
300
+ that element's own style. `text-shadow` keys do not animate (`effect.dropped`).
301
+
302
+ ## After the import: the diagnostics list
303
+
304
+ The import never stops at a problem: it writes the UI anyway and lists every difference between
305
+ the board and the result (24 §24.15). Each run writes `<project>/<ui>/<ui>.diagnostics.json` and
306
+ `<project>/diagnostics.json` (also `--diagnostics <file>`, under `--lint` too); stdout prints the
307
+ items that are not accepted as `<severity> <code> <source>:<line>:<col> #<element>: <message>` and
308
+ ends with `import finished: E error(s), W warning(s), I info(s); see <file>`. Each item has a
309
+ stable `code` (24 §24.15.4: `anchor.*`, `import.*`, `effect.*`, `bind.*`, `tag.*`, `font.*`,
310
+ `layout.*`, `svg.*`), a severity (`error`: the result differs and has no safe value; `warning`:
311
+ differs, a conservative value was used; `info`: told only) and a `fix` of kind `board`, `editor`
312
+ or `none`. `--strict` only changes the exit code (1 on an error or a Low-fidelity node).
313
+
314
+ The repair loop (24 §24.15.3):
315
+
316
+ 1. Read the list. Fix every `board` item on the board (`fix.board` names the attribute and value)
317
+ and import again; fixed items disappear.
318
+ 2. Hand the `editor` items to the `xtui-editor` skill (its repair operations) once the UI is open
319
+ in the editor.
320
+ 3. A difference that is intended is **accepted**, not left to repeat: `data-xt-allow="<code>[,
321
+ <code>]"` on the element on the board, or the editor's accepted list (`.xteditor.json`
322
+ `diagnostics.accepted[]`, keyed by code, element and summary). Accepted items are not listed
323
+ again on a re-import.
324
+ 4. Report what is left (`hint` / `none` items) to the user, with their codes.
325
+
326
+ ## List items: how to write them
327
+
328
+ Copy the standard symbol `ListItem` (`Assets/Symbols/groups/broadsheet-2026/list/ListItem.xt`, Docs/design/30 30.13).
329
+ It shows the three ways data reaches an entry, one each:
330
+
331
+ - **values -> in-ports** (the default): the symbol's `<ports>` declares `title: string in` and
332
+ `selected: bool in`; the instance in a repeat template takes them with `bind:<port>`, and each
333
+ entry keeps its own copy.
334
+ - **free content -> a slot**: `<slot name="trailing">` for a badge, an icon or a button; the slot
335
+ content belongs to the using document and may bind `item(...)` and document ports itself.
336
+ - **states -> `bind:state.<Name>`**: `Selected` follows the `selected` port; exclusive states go
337
+ into a state group (`state-groups="Mark: Unread|Read"`).
338
+
339
+ ```xml
340
+ <ports>
341
+ items: list<struct{title: string, subtitle: string, badge: string, selected: bool}> in
342
+ </ports>
343
+ <body>
344
+ <div id="List">
345
+ <repeat port="items" id="Rows">
346
+ <use symbol="ListItem" id="Item" bind:title="item(title)" bind:subtitle="item(subtitle)"
347
+ bind:selected="item(selected)">
348
+ <slot name="trailing"><span id="Badge" bind:text="item(badge)"></span></slot>
349
+ </use>
350
+ </repeat>
351
+ </div>
352
+ </body>
353
+ ```
354
+
355
+ A port belongs to the document's or a symbol's `<ports>`, never to an element (`port:` on an
356
+ element is the error `ports.onElement`): for per-entry values declare it on the symbol and bind
357
+ it on the `<use>`. A click on an entry emits `activate`, a double click also `dblactivate`;
358
+ both carry the entry index. The host addresses one entry's port as `Rows/3/Item.title`.
@@ -0,0 +1,182 @@
1
+ Read this when a board has shadows, filters, backdrop blurs, large animated elements or many large images, and before a UI is published: what costs on a GPU target, and what does not.
2
+
3
+ # Performance: what costs on the GPU, and what does not
4
+
5
+ **Do not remove an effect because you guess it is expensive.** Write it, then measure with
6
+ `xtframe-view <project-dir> --ui <ui> --headless --renderer wgpu --perf`; only a measured number
7
+ is a reason to drop or change it (`SKILL.md` section 1c). A blur over static content is cached and
8
+ costs one textured quad per frame once drawn; a blur whose radius animates is redrawn every frame
9
+ and its layer grows and shrinks with the radius -- still a few passes, so try it before deciding.
10
+
11
+ One project's measurement, not a guarantee: a 59-second converted opening rendered 900 frames on
12
+ the GPU in 2.4 s as first converted (blurs dropped, particles and shaders added later) and in
13
+ 2.3 s as fully converted (whole-shot blur, full-screen greyscale and a dozen looping animations
14
+ kept) -- different content, so not a strict comparison, but no measurable cost. Software rendering was slow for both
15
+ (about 0.15 s a frame at 1920x1080), so check long animations on the GPU: `--renderer wgpu` with
16
+ `--advance <seconds>` to jump to a moment (`references/verify.md`). Blur and shadow radii above
17
+ 64 device px are clamped with a message (`dialect.md`).
18
+
19
+ These are the costs of XTFrame's GPU renderers (wgpu, GL). The headless screenshot of
20
+ `references/verify.md` step 5 renders in software and shows none of them; when you need numbers,
21
+ `xtframe-view <project-dir> --ui <ui> --headless --renderer wgpu --perf` prints per-frame passes,
22
+ draw calls, effect cache hits / misses and the mip chains made. **Passes per frame is the number
23
+ to watch**: every off-screen step is one, and on the wgpu target the CPU cost of a frame follows
24
+ it almost linearly.
25
+
26
+ ## A UI that does not change costs nothing
27
+
28
+ - When nothing in a UI changes, the previous GPU frame is submitted again. When anything changes,
29
+ the whole UI is rebuilt and redrawn; there is no partial redraw on the GPU (10 §10.12; T-667
30
+ withdrawn). One small looping animation therefore keeps the whole UI redrawing every frame:
31
+ keep idle loops few, especially in a UI that also has uncached effects.
32
+ - An effect whose content and parameters did not change since the last frame is drawn from a
33
+ cached result (one textured quad). **Moving the whole element** (a `translate` animation, a
34
+ bobbing sprite with a drop shadow) reuses the cached result at the new position (10 §10.16 W2;
35
+ T-721); rotating or scaling it does not. An effect is rendered again every frame when its
36
+ parameters animate, or when **anything inside the element changes** -- one blinking child, a
37
+ shine bar sweeping across a card -- because the effect covers the element and everything in it.
38
+ Effects over `engine://` textures are never cached; for `backdrop-filter` see below.
39
+
40
+ ## Shadows
41
+
42
+ A `box-shadow` is drawn analytically -- one draw, no off-screen layer -- only when all of these
43
+ hold for its element (10 §10.12; T-668, T-680, T-681):
44
+
45
+ - every effect on the element is an outer shadow (several are fine; `filter: drop-shadow()` is one
46
+ too): no `inset` shadow, other `filter` function or `backdrop-filter` on the **same** element;
47
+ - the element is at `opacity: 1`, has no `mix-blend-mode`, has no 3D transform of its own and is
48
+ not on a tilted plane (`rotateX` / `rotateY`); a `perspective` on an ancestor alone does not
49
+ matter (T-716);
50
+ - its background covers the whole border box with one alpha of at least 0.9: a colour, or a
51
+ gradient whose stops all share that alpha (not a translucent colour under a translucent
52
+ gradient); no `clip-path`; not `visibility: hidden`;
53
+ - nothing inside it reaches past its border box (text counts by its glyph boxes), or `overflow`
54
+ clips its children;
55
+ - no `outline`, or a solid, fully opaque one on a fully opaque background.
56
+
57
+ Every other shadow is an off-screen effect layer (below): `inset` shadows, shadows on transparent
58
+ or translucent boxes, on an `<img>` or text with no such background, a shadow next to another `filter`
59
+ function on the same element, a dashed or translucent outline, content that pokes out -- and a converted
60
+ shadow while its element fades (`opacity` < 1), for the length of the fade. **For a cheap shadow,
61
+ put it alone on an opaque box**; put filters and backdrop blurs on another element. Animating
62
+ only the shadow's offset, blur, spread or colour on such a box costs one draw per frame; on any
63
+ other shadow it re-renders the whole effect every frame.
64
+ `xtframe-view --no-box-shadow` shows the old off-screen path for a comparison.
65
+
66
+ ## Effect layers and animated size
67
+
68
+ - An element with an effect that is not a converted shadow (`filter`, `backdrop-filter`, the
69
+ other shadows) is drawn through an off-screen layer; `opacity` < 1 on such an element adds one
70
+ more layer of the same size. The layer covers the element **and everything inside it** on
71
+ screen (children included; `overflow: hidden` does not shrink it, `clip-path` does), grown by
72
+ the effect's reach (1.5 x the blur; a shadow's offset and spread too), cut to the screen and
73
+ rounded up to 32 px steps (at least 64 px). Its memory, and the pixels every effect pass
74
+ touches, grow with that area.
75
+ - Layer textures are pooled by exact size (50 §50.ac). An animation that changes the size needs a
76
+ new texture each time it crosses a 32 px step, and one scene can leave dozens of sizes behind;
77
+ creating textures can stall a frame on integrated GPUs (50 §50.ac, note 2 and note 4).
78
+ - The size changes with: `scale`, rotation (the bounding box grows), an animated blur radius or
79
+ shadow offset / spread, children moving out of the element's box, moving partly off screen.
80
+ It does not change with: moving while fully on screen, `opacity`, colour changes.
81
+ - Scaling a large element that has a blur is the worst case: the box and the blur reach grow
82
+ together. When a zoom needs a blur, put the effect on a wrapper element that does not scale and
83
+ whose box already covers the content at its largest: the layer then keeps the wrapper's size
84
+ (the blur then stays the same on screen instead of scaling with the content).
85
+
86
+ ## Keep what has an effect still
87
+
88
+ Measured on a 1,200-element HUD (the War Table benchmark, 2026-11): these rewrites, with the same
89
+ picture on screen, took a third of the frame cost away.
90
+
91
+ - **Move what animates out of the element that has the effect.** A card with a shadow and a shine
92
+ bar inside re-renders its shadow every frame; make the bar a sibling laid over the card with the
93
+ same position and the same rounded clip, and the card's shadow is cached. The same for a pulsing
94
+ light inside a tab, and for blinking cells on a large shadowed board.
95
+ - **Do not animate or transition shadow parameters** for a state change. Give the element a shim
96
+ with the "hover" (or "selected") shadow at fixed parameters and fade the shim's `opacity`; for a
97
+ breathing glow, cross-fade two fixed shadows. Transition `transform`, `opacity` and colours,
98
+ not blur, spread or offset.
99
+ - **A blinking element should be one primitive.** An element that has both a background and a
100
+ border and animates `opacity` needs an off-screen layer; split it into a border-only and a
101
+ fill-only sibling that share the animation (the fill inset by the border width so they do not
102
+ overlap), or blink a plain coloured box.
103
+ - **A soft glow under something can be a gradient.** A radial gradient with a dozen stops that
104
+ follow the blurred falloff needs no effect at all.
105
+ - **A shadow on a transparent sprite** (`<img>` with `filter: drop-shadow()`) is always an
106
+ off-screen blur. It is cached while the sprite only moves; do not also scale or rotate it in an
107
+ idle loop.
108
+ - **`backdrop-filter`** reads what is behind the element, so its blur is redone every frame that
109
+ anything on screen changes. Its own shadows are computed from the element alone (as in CSS: a
110
+ backdrop blur does not thicken the element's shadow -- T-729); while the panel's own content
111
+ does not change, its content and shadows are reused and only the blur is redone (T-730) -- a
112
+ panel with an animated child inside redoes everything, so lay the moving part over the panel as
113
+ a sibling. Use few glass panels, and do not stack them over each other: a panel
114
+ that covers another has to wait for it.
115
+
116
+ ## 3D
117
+
118
+ - Put `perspective` on the smallest container that needs it, not on the UI's root. Elements on
119
+ the untilted plane are drawn as ordinary 2D content either way, but the root of a 3D space wraps
120
+ each of its children, and effects and clips on a tilted plane (`rotateX` / `rotateY`) cannot use
121
+ the cheap paths above.
122
+ - A `transform` with only 2D functions (`translateX() translateY()`, `rotate()`, `scale()`) stays
123
+ 2D inside a 3D space, also when a timeline or animation drives it (T-725). A non-zero
124
+ `translateZ`, `rotateX` or `rotateY` -- static or in any keyframe -- makes the element a 3D layer.
125
+ - Inside a 3D space, flat content and 3D layers are ordered by depth and then by document order
126
+ (T-727): a flat sibling written after a tilted board is drawn over it. Do not rely on a sibling
127
+ "always being underneath" because it is flat.
128
+
129
+ ## Interaction
130
+
131
+ - A `:hover`, `:active` or `:focus` change restyles only the elements a rule can match
132
+ (T-723), and a binding write restyles only the bound element; neither is a reason to avoid
133
+ them. A binding that writes the same value again does nothing.
134
+ - A transition starts when the **target** value changes; re-applying the same value does not
135
+ restart it (05 §5.6a).
136
+ - Put text that changes often (a counter, a timer, a round number, a score) in a container whose
137
+ `width` and `height` are fixed lengths (06 §6.x; T-755, T-782 -- its `overflow` does not matter).
138
+ Such a container is a layout boundary: a change inside it lays out only the container, not the
139
+ whole screen. A container sized by its content (`auto`) or a flex item that grows or shrinks
140
+ (anything but `flex: none`) is not one, and the change lays out everything up to the next
141
+ boundary above it -- often the whole UI.
142
+
143
+ ## Clips
144
+
145
+ - `overflow: hidden` with `border-radius`, and rounded backgrounds, cost no off-screen layer at
146
+ 1x, up to three nested levels (10 §10.16 W1; T-718). Other clip shapes (`ellipse()`, `polygon()`,
147
+ an `inset()` with elliptic radii) and a fourth nested rounded clip still do.
148
+
149
+ ## Images
150
+
151
+ - `publish.images.compress` in the `.xtui` (`references/ui-project.md`) decides how
152
+ `xtframe-pack` writes bitmaps: `none` (the default; fastest to pack -- use it while iterating),
153
+ `bc7` (every bitmap and atlas page) or `auto` (BC7 only for images and atlas pages with both
154
+ sides at least 256 px). Publish with `bc7` or `auto`: a BC7 image takes 1 byte per pixel of GPU
155
+ memory instead of 4, and the GPU path uploads it without decoding it first (10 §10.13).
156
+ - BC7 is lossy. Check images with hard edges or fine detail (stamps, badges) in a screenshot; keep
157
+ one as it is with `compress: none` on that asset in the project's `manifest/assets.yaml`.
158
+ - Layout is unchanged by compression: the packer pads images to a multiple of 4 but records the
159
+ original size, and that is the size the layout uses.
160
+ - iOS and Android (GLES) have no BC7: the image is decoded to RGBA there, still lossy and with no
161
+ memory saving (10 §10.13 item 8).
162
+ - **Make each bitmap at about the size it is shown** (at the target resolution). An image drawn
163
+ smaller than its pixel size gets a mip chain the first time it is drawn minified -- one third
164
+ more memory, kept -- on top of the pixels nobody sees; an image never drawn smaller has none
165
+ (10 §10.11 item 7; T-665).
166
+
167
+ ## Antialiasing
168
+
169
+ GPU targets draw at 1x by default (`xtframe-view --msaa` defaults to 1). At 1x XTFrame
170
+ antialiases rotated and skewed images, concave shapes and SVG icons, strokes, text at any size
171
+ and angle, rounded, rotated and path clips, and borders (10 §10.11). Do not ask for MSAA for edge
172
+ quality: 4x multiplies the surface and layer memory several times over. The exceptions are
173
+ images and strokes under a 3D projection, image meshes and particles, and a host's own GPU
174
+ backend that does not support these draws (10 §10.14).
175
+
176
+ ## Hidden UIs and hidden elements
177
+
178
+ - An element at `opacity: 0` (its own or an ancestor's) or `display: none` is not painted at all,
179
+ so its effects make no layer. Any opacity above 0 paints it in full, effects included.
180
+ - When the host hides a whole UI, its textures go back to the GPU target's pools and its decoded
181
+ images to an idle list; the host sets those budgets (50 §50.ab, §50.ac). Nothing on the board
182
+ changes them.