@xtframe/skills 0.0.0-stage → 0.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (35) hide show
  1. package/README.md +22 -2
  2. package/package.json +41 -4
  3. package/payload/plugins/xtframe/.claude-plugin/plugin.json +17 -0
  4. package/payload/plugins/xtframe/.codex-plugin/plugin.json +11 -0
  5. package/payload/plugins/xtframe/gemini-extension.json +5 -0
  6. package/payload/plugins/xtframe/skills/xtui/SKILL.md +218 -0
  7. package/payload/plugins/xtframe/skills/xtui/references/canvas.md +90 -0
  8. package/payload/plugins/xtframe/skills/xtui/references/dialect.md +799 -0
  9. package/payload/plugins/xtframe/skills/xtui/references/flow.md +338 -0
  10. package/payload/plugins/xtframe/skills/xtui/references/not-like-web.md +358 -0
  11. package/payload/plugins/xtframe/skills/xtui/references/performance.md +162 -0
  12. package/payload/plugins/xtframe/skills/xtui/references/responsive.md +137 -0
  13. package/payload/plugins/xtframe/skills/xtui/references/style-groups.md +378 -0
  14. package/payload/plugins/xtframe/skills/xtui/references/template.dc.html +56 -0
  15. package/payload/plugins/xtframe/skills/xtui/references/tokens.json +42 -0
  16. package/payload/plugins/xtframe/skills/xtui/references/ui-project.md +161 -0
  17. package/payload/plugins/xtframe/skills/xtui/references/upgrade.md +140 -0
  18. package/payload/plugins/xtframe/skills/xtui/references/vector.md +219 -0
  19. package/payload/plugins/xtframe/skills/xtui/references/verify.md +327 -0
  20. package/payload/plugins/xtframe/skills/xtui-editor/SKILL.md +209 -0
  21. package/payload/plugins/xtframe/skills/xtui-editor/references/design.md +158 -0
  22. package/payload/plugins/xtframe/skills/xtui-editor/references/ops.md +849 -0
  23. package/payload/plugins/xtframe/skills/xtui-editor/references/recipes.md +70 -0
  24. package/payload/plugins/xtframe/skills/xtui-editor/references/scenarios.md +180 -0
  25. package/payload/plugins/xtframe/skills/xtui-editor/references/service.md +167 -0
  26. package/src/agents.mjs +73 -0
  27. package/src/bin.mjs +4 -0
  28. package/src/cli.mjs +286 -0
  29. package/src/converter.mjs +73 -0
  30. package/src/fsutil.mjs +76 -0
  31. package/src/install.mjs +154 -0
  32. package/src/packs.mjs +150 -0
  33. package/src/plugins.mjs +109 -0
  34. package/src/proc.mjs +66 -0
  35. package/src/tar.mjs +103 -0
@@ -0,0 +1,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,162 @@
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
+ These are the costs of XTFrame's GPU renderers (wgpu, GL). The headless screenshot of
6
+ `references/verify.md` step 5 renders in software and shows none of them; when you need numbers,
7
+ `xtframe-view <project-dir> --ui <ui> --headless --renderer wgpu --perf` prints per-frame passes,
8
+ draw calls, effect cache hits / misses and the mip chains made. **Passes per frame is the number
9
+ to watch**: every off-screen step is one, and on the wgpu target the CPU cost of a frame follows
10
+ it almost linearly.
11
+
12
+ ## A UI that does not change costs nothing
13
+
14
+ - When nothing in a UI changes, the previous GPU frame is submitted again. When anything changes,
15
+ the whole UI is rebuilt and redrawn; there is no partial redraw on the GPU (10 §10.12; T-667
16
+ withdrawn). One small looping animation therefore keeps the whole UI redrawing every frame:
17
+ keep idle loops few, especially in a UI that also has uncached effects.
18
+ - An effect whose content and parameters did not change since the last frame is drawn from a
19
+ cached result (one textured quad). **Moving the whole element** (a `translate` animation, a
20
+ bobbing sprite with a drop shadow) reuses the cached result at the new position (10 §10.16 W2;
21
+ T-721); rotating or scaling it does not. An effect is rendered again every frame when its
22
+ parameters animate, or when **anything inside the element changes** -- one blinking child, a
23
+ shine bar sweeping across a card -- because the effect covers the element and everything in it.
24
+ Effects over `engine://` textures are never cached; for `backdrop-filter` see below.
25
+
26
+ ## Shadows
27
+
28
+ A `box-shadow` is drawn analytically -- one draw, no off-screen layer -- only when all of these
29
+ hold for its element (10 §10.12; T-668, T-680, T-681):
30
+
31
+ - every effect on the element is an outer shadow (several are fine; `filter: drop-shadow()` is one
32
+ too): no `inset` shadow, other `filter` function or `backdrop-filter` on the **same** element;
33
+ - the element is at `opacity: 1`, has no `mix-blend-mode`, has no 3D transform of its own and is
34
+ not on a tilted plane (`rotateX` / `rotateY`); a `perspective` on an ancestor alone does not
35
+ matter (T-716);
36
+ - its background covers the whole border box with one alpha of at least 0.9: a colour, or a
37
+ gradient whose stops all share that alpha (not a translucent colour under a translucent
38
+ gradient); no `clip-path`; not `visibility: hidden`;
39
+ - nothing inside it reaches past its border box (text counts by its glyph boxes), or `overflow`
40
+ clips its children;
41
+ - no `outline`, or a solid, fully opaque one on a fully opaque background.
42
+
43
+ Every other shadow is an off-screen effect layer (below): `inset` shadows, shadows on transparent
44
+ or translucent boxes, on an `<img>` or text with no such background, a shadow next to another `filter`
45
+ function on the same element, a dashed or translucent outline, content that pokes out -- and a converted
46
+ shadow while its element fades (`opacity` < 1), for the length of the fade. **For a cheap shadow,
47
+ put it alone on an opaque box**; put filters and backdrop blurs on another element. Animating
48
+ only the shadow's offset, blur, spread or colour on such a box costs one draw per frame; on any
49
+ other shadow it re-renders the whole effect every frame.
50
+ `xtframe-view --no-box-shadow` shows the old off-screen path for a comparison.
51
+
52
+ ## Effect layers and animated size
53
+
54
+ - An element with an effect that is not a converted shadow (`filter`, `backdrop-filter`, the
55
+ other shadows) is drawn through an off-screen layer; `opacity` < 1 on such an element adds one
56
+ more layer of the same size. The layer covers the element **and everything inside it** on
57
+ screen (children included; `overflow: hidden` does not shrink it, `clip-path` does), grown by
58
+ the effect's reach (1.5 x the blur; a shadow's offset and spread too), cut to the screen and
59
+ rounded up to 32 px steps (at least 64 px). Its memory, and the pixels every effect pass
60
+ touches, grow with that area.
61
+ - Layer textures are pooled by exact size (50 §50.ac). An animation that changes the size needs a
62
+ new texture each time it crosses a 32 px step, and one scene can leave dozens of sizes behind;
63
+ creating textures can stall a frame on integrated GPUs (50 §50.ac, note 2 and note 4).
64
+ - The size changes with: `scale`, rotation (the bounding box grows), an animated blur radius or
65
+ shadow offset / spread, children moving out of the element's box, moving partly off screen.
66
+ It does not change with: moving while fully on screen, `opacity`, colour changes.
67
+ - Scaling a large element that has a blur is the worst case: the box and the blur reach grow
68
+ together. When a zoom needs a blur, put the effect on a wrapper element that does not scale and
69
+ whose box already covers the content at its largest: the layer then keeps the wrapper's size
70
+ (the blur then stays the same on screen instead of scaling with the content).
71
+
72
+ ## Keep what has an effect still
73
+
74
+ Measured on a 1,200-element HUD (the War Table benchmark, 2026-11): these rewrites, with the same
75
+ picture on screen, took a third of the frame cost away.
76
+
77
+ - **Move what animates out of the element that has the effect.** A card with a shadow and a shine
78
+ bar inside re-renders its shadow every frame; make the bar a sibling laid over the card with the
79
+ same position and the same rounded clip, and the card's shadow is cached. The same for a pulsing
80
+ light inside a tab, and for blinking cells on a large shadowed board.
81
+ - **Do not animate or transition shadow parameters** for a state change. Give the element a shim
82
+ with the "hover" (or "selected") shadow at fixed parameters and fade the shim's `opacity`; for a
83
+ breathing glow, cross-fade two fixed shadows. Transition `transform`, `opacity` and colours,
84
+ not blur, spread or offset.
85
+ - **A blinking element should be one primitive.** An element that has both a background and a
86
+ border and animates `opacity` needs an off-screen layer; split it into a border-only and a
87
+ fill-only sibling that share the animation (the fill inset by the border width so they do not
88
+ overlap), or blink a plain coloured box.
89
+ - **A soft glow under something can be a gradient.** A radial gradient with a dozen stops that
90
+ follow the blurred falloff needs no effect at all.
91
+ - **A shadow on a transparent sprite** (`<img>` with `filter: drop-shadow()`) is always an
92
+ off-screen blur. It is cached while the sprite only moves; do not also scale or rotate it in an
93
+ idle loop.
94
+ - **`backdrop-filter`** reads what is behind the element, so its blur is redone every frame that
95
+ anything on screen changes. Its own shadows are computed from the element alone (as in CSS: a
96
+ backdrop blur does not thicken the element's shadow -- T-729); while the panel's own content
97
+ does not change, its content and shadows are reused and only the blur is redone (T-730) -- a
98
+ panel with an animated child inside redoes everything, so lay the moving part over the panel as
99
+ a sibling. Use few glass panels, and do not stack them over each other: a panel
100
+ that covers another has to wait for it.
101
+
102
+ ## 3D
103
+
104
+ - Put `perspective` on the smallest container that needs it, not on the UI's root. Elements on
105
+ the untilted plane are drawn as ordinary 2D content either way, but the root of a 3D space wraps
106
+ each of its children, and effects and clips on a tilted plane (`rotateX` / `rotateY`) cannot use
107
+ the cheap paths above.
108
+ - A `transform` with only 2D functions (`translateX() translateY()`, `rotate()`, `scale()`) stays
109
+ 2D inside a 3D space, also when a timeline or animation drives it (T-725). A non-zero
110
+ `translateZ`, `rotateX` or `rotateY` -- static or in any keyframe -- makes the element a 3D layer.
111
+ - Inside a 3D space, flat content and 3D layers are ordered by depth and then by document order
112
+ (T-727): a flat sibling written after a tilted board is drawn over it. Do not rely on a sibling
113
+ "always being underneath" because it is flat.
114
+
115
+ ## Interaction
116
+
117
+ - A `:hover`, `:active` or `:focus` change restyles only the elements a rule can match
118
+ (T-723), and a binding write restyles only the bound element; neither is a reason to avoid
119
+ them. A binding that writes the same value again does nothing.
120
+ - A transition starts when the **target** value changes; re-applying the same value does not
121
+ restart it (05 §5.6a).
122
+
123
+ ## Clips
124
+
125
+ - `overflow: hidden` with `border-radius`, and rounded backgrounds, cost no off-screen layer at
126
+ 1x, up to three nested levels (10 §10.16 W1; T-718). Other clip shapes (`ellipse()`, `polygon()`,
127
+ an `inset()` with elliptic radii) and a fourth nested rounded clip still do.
128
+
129
+ ## Images
130
+
131
+ - `publish.images.compress` in the `.xtui` (`references/ui-project.md`) decides how
132
+ `xtframe-pack` writes bitmaps: `none` (the default; fastest to pack -- use it while iterating),
133
+ `bc7` (every bitmap and atlas page) or `auto` (BC7 only for images and atlas pages with both
134
+ sides at least 256 px). Publish with `bc7` or `auto`: a BC7 image takes 1 byte per pixel of GPU
135
+ memory instead of 4, and the GPU path uploads it without decoding it first (10 §10.13).
136
+ - BC7 is lossy. Check images with hard edges or fine detail (stamps, badges) in a screenshot; keep
137
+ one as it is with `compress: none` on that asset in the project's `manifest/assets.yaml`.
138
+ - Layout is unchanged by compression: the packer pads images to a multiple of 4 but records the
139
+ original size, and that is the size the layout uses.
140
+ - iOS and Android (GLES) have no BC7: the image is decoded to RGBA there, still lossy and with no
141
+ memory saving (10 §10.13 item 8).
142
+ - **Make each bitmap at about the size it is shown** (at the target resolution). An image drawn
143
+ smaller than its pixel size gets a mip chain the first time it is drawn minified -- one third
144
+ more memory, kept -- on top of the pixels nobody sees; an image never drawn smaller has none
145
+ (10 §10.11 item 7; T-665).
146
+
147
+ ## Antialiasing
148
+
149
+ GPU targets draw at 1x by default (`xtframe-view --msaa` defaults to 1). At 1x XTFrame
150
+ antialiases rotated and skewed images, concave shapes and SVG icons, strokes, text at any size
151
+ and angle, rounded, rotated and path clips, and borders (10 §10.11). Do not ask for MSAA for edge
152
+ quality: 4x multiplies the surface and layer memory several times over. The exceptions are
153
+ images and strokes under a 3D projection, image meshes and particles, and a host's own GPU
154
+ backend that does not support these draws (10 §10.14).
155
+
156
+ ## Hidden UIs and hidden elements
157
+
158
+ - An element at `opacity: 0` (its own or an ancestor's) or `display: none` is not painted at all,
159
+ so its effects make no layer. Any opacity above 0 paints it in full, effects included.
160
+ - When the host hides a whole UI, its textures go back to the GPU target's pools and its decoded
161
+ images to an idle list; the host sets those budgets (50 §50.ab, §50.ac). Nothing on the board
162
+ changes them.