@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,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<...>`). 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.
|