@xtframe/skills 0.18.0 → 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.
@@ -135,17 +135,22 @@ it was.
135
135
  - **Exit 3, one-way fallback**: `re-import <ui>: ... (N% unmatched)` above 20% and
136
136
  `import-report.json`'s `reimport[]` row says `fallback: "one-way"`. Too many layers could not be
137
137
  found again (renamed or restructured on the canvas), so the documents were left alone and the new
138
- version was written to `<ui>.import.xt`/`.xts`. Look at that row's `missing` list, restore the
139
- `data-xt-name`/`id` of those layers on the board (canvas.md (c)) and import again; `--force` is
140
- the last resort.
138
+ version was written to `<ui>.import.xt`/`.xts`. Look at that row's `missing` list: if those
139
+ layers were removed from the board on purpose, re-run with `--prune` (the message ends with that
140
+ hint; with `--prune` the layers that are gone do not count, only low-confidence pairings do);
141
+ otherwise restore the `data-xt-name`/`id` of those layers on the board (canvas.md (c)) and import
142
+ again; `--force` is the last resort.
141
143
  - The last stderr line is the fidelity summary
142
144
  (`N declarations dropped, M warnings, K low-fidelity nodes -- see <bundle>/import-report.json`),
143
145
  the last stdout line `imported N UIs, M nodes (a high, b medium, c low), ...`.
144
146
 
145
147
  Re-importing into the **same** `<project-dir>` is the normal way to change a UI: hand-edited
146
- nodes are kept (`kept hand edits on N node(s)`), the UI's `.xtflow` is kept and stays registered,
147
- and an unedited UI Project re-imports byte-identically. What the re-import does per UI
148
- (`re-import <ui>: N matched, N new, N missing`):
148
+ nodes are kept (`kept hand edits on N node(s)`), and an unedited UI Project re-imports
149
+ byte-identically. A UI whose board did not change is not touched at all: it prints
150
+ `<ui>: board unchanged since the last import; its files were left alone` instead of a
151
+ `re-import` line, and no file of it is rewritten (a file whose bytes would not change is never
152
+ rewritten either). With `--prune` and no hand edits, a re-import gives the same result as a fresh
153
+ import. What the re-import does for every other UI (`re-import <ui>: N matched, N new, N missing`):
149
154
 
150
155
  - Layers pair by `data-xt-name`/`id` first, then by geometry, order, nesting and text; a paired
151
156
  layer keeps its editor id.
@@ -154,7 +159,20 @@ and an unedited UI Project re-imports byte-identically. What the re-import does
154
159
  declarations, `bind:` attributes and every rule the editor wrote (in `<layout>` or in a
155
160
  stylesheet).
156
161
  - Layers the canvas no longer has stay, marked `data-xt-missing` (greyed in the editor's layer
157
- panel); `--prune` deletes them instead.
162
+ panel); `--prune` deletes them instead. A kept layer loses a `bind:` / `on:` / `port:` attribute
163
+ whose port the board removed (`removed <attr> from #<id> ...`; the row's `removedBindings`), and a
164
+ symbol definition the board deleted but a kept `<use>` still needs stays (`keptSymbols`), so the
165
+ document still compiles.
166
+ - The UI's `.xtflow`: a flow the import generated and nobody edited follows the board (rewritten
167
+ when the board's flow changed, deleted when the board no longer has one); a hand-edited or
168
+ hand-written `.xtflow` is kept and stays registered.
169
+ - Symbol definitions (`<symbol>` and the libraries under `--symbols-dir`) merge one by one: one
170
+ nobody edited takes the board's version (or goes when the board deleted it), a new one is added,
171
+ and one edited locally is kept with a conflict (`prop: "symbol"`) in the report.
172
+ - A UI whose board is no longer on the canvas is kept, never deleted (`its board is no longer on
173
+ the canvas; the UI was kept`; `import-report.json`'s `uisNotOnCanvas`). In a project without an
174
+ asset manifest, an imported asset nothing references any more is listed in `unreferencedAssets`
175
+ and kept; `--prune` deletes it with its `.meta` (only when nobody edited it).
158
176
  - In the editor the same merge runs from the UI Project panel's **Re-import...** button, and over
159
177
  the Editor Service as `import.reimport {source, ui?, prune?, force?}`.
160
178
 
@@ -175,6 +193,10 @@ An `error:` sends you back to the board. Collect every `warning:` line for the r
175
193
  xtframe-view <project-dir>/<ui>/<ui>.xt --headless --frames 3 --screenshot <abs-path>.png
176
194
  ```
177
195
 
196
+ To see a later moment (an intro's end, second 54 of a loop), `--advance <seconds>` runs the time
197
+ before it without painting and then draws the frames as usual, the same picture as stepping there
198
+ frame by frame: `xtframe-view <ui> --headless --renderer wgpu --advance 54 --frames 1 --screenshot out.png`.
199
+
178
200
  **On Node.js** (no `xtframe-view`: it needs SDL and is not built for WebAssembly) the Editor
179
201
  Service renders the same picture: `xtframe-service --stdio --project <project-dir>` fed `doc.open`
180
202
  and `scene.screenshot`, the PNG decoded from the reply. Paste as is (bash), with `<ui>`,
@@ -126,11 +126,21 @@ library, extra mounts, the project's) in **groups**; a project holds **copies**
126
126
  - **Use in the project** (`create`, `restyle`, `repair-import`, `single-element`):
127
127
  `symbols_useGroup {group}` before building a UI from a group, `symbols_use {names}` for a few
128
128
  symbols -- one undo step each: the files are copied, the tokens appended, the source recorded
129
- (49.3). Then `symbol_instantiate {symbol, parent, source: "project"}` places them.
129
+ (49.3). Then `symbol_instantiate {symbol, parent, source: "project"}` places them, with the name
130
+ the reply gives in `symbols[].qualified`: when the project already had another symbol of that name
131
+ the copy is stored as `<group id>/<Name>` (56.3, `clashes[].reason` `placed`) -- use that name and
132
+ tell the user; never ask them to rename or prefix anything. `symbols_move {from, to}` moves a
133
+ project symbol between `shared/symbols` and a namespace (every reference follows; one undo step).
134
+ - **The project's style** (one per project, 56.2): to make the whole UI look like another group,
135
+ `tokens_applyStyle {group, dryRun: true}` first and show the user what it replaces (their own
136
+ values are marked `custom`) and what it does not cover, then run it without `dryRun` on their word
137
+ (one undo step; only the 52 core tokens change). A symbol that must keep its look whatever the
138
+ style: `symbols_duplicateDetached {name, newName}` (an independent copy with tokens of its own).
130
139
  - **A copy older than the library**: `project_syncSymbols` lists `outdated` / `modified` copies.
131
- Tell the user; **suggest** `symbols_updateCopy {name}` (the library's file over the project's
132
- copy, tokens kept, one undo step) and run it only on their word -- never automatically, and never
133
- for a `modified` copy without saying what the project changed.
140
+ Tell the user; **suggest** `symbols_updateCopy {name}` (the recorded source's file over the
141
+ project's copy, tokens kept, one undo step) and run it only on their word -- never automatically.
142
+ A copy the project changed comes back `updated: false` (`locallyModified` / `staleAndModified`):
143
+ say what the project changed and pass `overwriteLocal: true` only after they agree.
134
144
  - **The library itself** -- `symbols_import`, `symbols_saveAsGroup`, `symbols_loadPreset`,
135
145
  `symbols_export`, `symbols_mountLibrary`, `symbols_unmountLibrary` -- is the **`library`**
136
146
  scenario (`references/scenarios.md`), and every one of them also needs the person's leave because
@@ -38,6 +38,26 @@ with `kConflict` ("document '<doc>' is at revision N (expected M)") and changes
38
38
  3. a second `kConflict` on the same write: stop and tell the user (someone is working on the same
39
39
  thing right now); do not loop.
40
40
 
41
+ **Error replies carry `revision` too** (T-816): every failed call's `error` has, next to `code` and
42
+ `message`, the document's current `revision` -- a failed write may have moved it (a rolled-back edit
43
+ is a change), so take your next `ifRevision` from there, not from your last good reply. Some
44
+ refusals add structured fields: `errors: [{line, column, message}]` (a shader source the parser
45
+ refuses, `shader.*`), `references: [{kind, where}]` (what still points into a layer
46
+ `layer.delete` refuses to remove). **Times are seconds** everywhere (`timeline.*` `time`, the
47
+ `animate.*` `delay`, `scene.screenshot` `time` / `times`); only `interval` / `delayMs` of
48
+ `timeline.stagger` are milliseconds. The board (the `xtui` skill) counts differently -- convert
49
+ when you take a time from it:
50
+
51
+ | Where the time is written | Unit |
52
+ |---|---|
53
+ | board `data-xt-timeline` (`intro: 0 opacity 0, 400 opacity 1`) | a number without a unit is **ms** (`400` = 0.4 s; `400ms` and `0.4s` are also accepted) |
54
+ | board CSS `animation` / `transition` | as written: `s` or `ms` |
55
+ | `timeline.setKeyframe` / `setKeyframes` / `removeKeyframe` / `setEasing` `time`, `timeline.get` key times, `timeline.create` `duration`, `timeline.stagger` `keys[].time` | seconds |
56
+ | `animate.entrance` / `exit` `delay` and `duration` | seconds |
57
+ | `scene.screenshot` `time` / `times`, `xtframe-view --advance` | seconds |
58
+ | `timeline.stagger` `interval` and its reply's `delayMs` | ms |
59
+ | `time` inside a `timeline.setExpression` text | seconds |
60
+
41
61
  T-366: when another seat changed the document's files on disk while it had unsaved edits
42
62
  (`doc.status` `diskNewer`), a write with `ifRevision` fails with `kConflict` too, and so does
43
63
  `doc.save` (with or without it): `doc.reload`, or `doc.save {force: true}` after asking the human.
@@ -71,7 +91,7 @@ removes one. `layer.setProps {layer, props, state?}` writes style properties int
71
91
  | `flow.get` | the flow graph (`.xtflow`): `{path, graph: {nodes, edges, groups?}, problems}`, `problems` = edges whose element endpoint names no layer |
72
92
  | `project.importReport {ui}` | the `import-report.json` of a UI of the project: `{ui, path, report}` |
73
93
  | `project.syncSymbols {diff?}` | T-408: the project's copies of standard symbols against the library: `{library, symbols: [{name, file, standard, status, diff?}], counts, notes}`; `status` is `current`, `outdated` (an earlier library version -- a newer one exists, the copy was not edited) or `modified` (edited in the project); `diff` is a unified diff library -> copy. Reports only, never overwrites a copy |
74
- | `timeline.list`, `timeline.get {name, scope?}` | named timelines; one timeline's tracks and keys |
94
+ | `timeline.list`, `timeline.get {name, scope?, layer?, prop?}` | named timelines; one timeline's tracks and keys (times in seconds; `layer` / `prop` keep only the tracks of that layer / property -- `tracks` stays an array, the other fields are unchanged), and its `expressions` (version 2 documents, see `timeline.setExpression`): per expression `{layer, prop, component, row, text, enabled, status, message?, line?, col?, diagnostics, keys, runtime, ports}` -- `status` `ok` (lowered; `keys` = the keys it lowers to, `{time, value, interp}`), `off`, `error` (`message` says why in plain words; `line` / `col` point into `text` when the compiler can), `needsRuntime` (reads a run-time input -- `port("...")`, another element's layout, another timeline's row, `randomPerPlay()` -- and is compiled into a run-time program; `runtime` is true for such an expression, also when it is an `error`, and `ports` lists the ports it reads) or `notCompiled` (the document does not compile, or a symbol without instances) |
75
95
  | `trigger.get {layer}`, `bind.get {layer}`, `port.get {layer}` | a layer's `on:`, `bind:`, `port:` (each port with its `default` literal, or null). In source format 2 the ports are the `<ports>` lines of the document (`layer: "body"`) or of a symbol (`layer`: its root, `<Symbol>/<root>`); any other layer has none |
76
96
  | `symbol.list`, `state.list {layer}` | symbols with their contracts; a layer's states |
77
97
  | `symbols.libraries` | T-502 (49.7): the mounted symbol libraries: `{libraries: [{id, name, path, readOnly, scope: preset \| user \| project \| extra, defaultGroup, groups, enabled}]}` (a listed but unmounted library has an empty `id`, `enabled: false`) |
@@ -87,21 +107,21 @@ removes one. `layer.setProps {layer, props, state?}` writes style properties int
87
107
 
88
108
  | Kind | Operations |
89
109
  |---|---|
90
- | Layers | `layer.create {parent, tag?, name?, text?, attrs?, index?}`, `layer.move {layer, parent, index?}`, `layer.rename {layer, name}`, `layer.setProps {layer, props, state?}`, `layer.setText {layer, text}`, `layer.setAttrs {layer, attrs}` (attribute -> value, null removes; **attributes go here** -- `editor-only`, `class`, `data-*`, `aria-*`, `src`, `href`, `ui-scale`, `media-override`; `layer.setProps` takes style properties only and refuses an attribute name as `unknown property`. `id`, `on:*`, `bind:*`, `port:*` refused: use `layer.rename`, `trigger.set`, `bind.set`, `port.set`; `layer.create {attrs}` follows the same rules with the same messages), `layer.setFlags {layer, hidden?, locked?, solo?, color?, collapsed?, adjustHidden?}` (the editor's own layer flags, see "Locked layers" below), `layer.duplicate {layer, count?}` (the layers panel's Duplicate: the subtree and its `#id` rules under the copies' new names, `count` 1-100 copies; the reply lists `copies`), `layer.group {layers, kind?}` (the layers panel's Group / Convert to Stack, layers with one parent, in document order: `group` (default) wraps them into a new `Group_<n>` div; `stack` gives `display: flex` -- a single group layer in place, else wrapped into `Stack_<n>`; the reply names the `layer`), `layer.delete {layer, confirm}` |
91
- | Style | `style.setToken {name, value}`, `style.setTheme {theme}` (preview only), `style.setRule {selector, props, file?, media?}` (declarations of the rule with exactly this selector, e.g. `.card:hover`; null removes one; the rule is added when missing; default the UI's own stylesheet, a shared one only when `file` names it. `media` is an `@media` query such as `(max-width: 1280px)` or `(aspect-ratio <= 4/3)`: the rule inside that `@media` block is written, the block added at the end of the stylesheet when missing, e.g. `@media (max-width: 1280px) { .card { left: 1px } }`; a rule left empty goes, and its block with it), `style.renameRule {selector, newSelector, file?}` (the style rules panel's selector edit), `style.deleteRule {selector, media?, file?, confirm}` (a whole rule; with `media` the rule inside that `@media` block), `style.moveDecl {from, to, prop, fromFile?, toFile?}` (the panel's Move to: the destination rule takes the value, the source loses it and goes when empty). These three find a rule as `style.setRule` does (a rule only in a shared stylesheet needs its `file`); `kNotFound` names a missing rule or property. A token (`style.setToken`, `restyle`, `design.put` of a variable) is the same edit the token panel makes: it changes the open UI's copy of `shared/tokens.xts`, the panel shows it at once and `doc.save` writes the file |
92
- | Timelines | `timeline.create {name, duration?, scope?}`, `timeline.setKeyframe {name, layer, prop, time, value, easing?}` (an effect parameter `prop` is `effect.<index|name>.<param>`: a vec2 as a whole, e.g. `effect.shadow.offset` or a shader vec2, is one key with two numbers, `"<x>px <y>px"` or `"<x> <y>"`; `<param>.x` / `.y` key one component; slots `p<n>` (float 0-15), `c<n>` (colour 0-3), `v<n>` (vec2 from float slot n, 0-14) address any effect without its names), `timeline.setEasing {name, layer, prop, time, easing}`, `timeline.removeKeyframe {name, layer, prop, time}`, `timeline.delete {name, confirm}`, `timeline.rename {name, newName, scope?}`, `timeline.duplicate {name, newName, scope?}` (triggers that play the old name are not rewritten), `timeline.setDuration {name, duration, mode?, scope?}` (`clip`, default: only the length changes, keys past the end stay; `scale`: every key, marker and cue time scales by new / old length), `timeline.setMarker {name, time, label, scope?}` / `timeline.setCue {name, time, sound, scope?}` (a name adds the marker / cue at `time` or renames the one there; `null` removes it), `timeline.moveKeys {name, keys: [{layer, prop, time}], dt?, scale?: {pivot?, factor}, scope?}` (new time = pivot + (time - pivot) x factor + dt, clamped at 0; all keys in one undo step; use it instead of remove + set), `timeline.stagger {name, keys: [{layer, prop, time}], interval?, order?, reverse?, seed?, scope?}` (each layer's keys shift by i x `interval` ms, default 50; `order` layer \| reverse \| random \| center), `animation.preset {layer, preset, timeline?, at?, scope?}` (a stroke preset on a vector shape `<svg>/<shape>`: `draw-on`, `draw-off`, `marching-ants`, `pulse-stroke`; default timeline `intro`), `animation.followPath {path, layer, timeline, start?, end?, samples?, align?, autoOrient?, scope?}` (bakes the shape `path` into `layer`'s `transform` translate keys, evenly spaced by arc length) |
110
+ | Layers | `layer.create {parent, tag?, name?, text?, attrs?, index?}`, `layer.move {layer, parent, index?}`, `layer.rename {layer, name}`, `layer.setProps {layer, props, state?}`, `layer.setText {layer, text}`, `layer.setAttrs {layer, attrs}` (attribute -> value, null removes; **attributes go here** -- `editor-only`, `class`, `data-*`, `aria-*`, `src`, `href`, `ui-scale`, `media-override`; `layer.setProps` takes style properties only and refuses an attribute name as `unknown property`. `id`, `on:*`, `bind:*`, `port:*` refused: use `layer.rename`, `trigger.set`, `bind.set`, `port.set`; `layer.create {attrs}` follows the same rules with the same messages), `layer.setFlags {layer, hidden?, locked?, solo?, color?, collapsed?, adjustHidden?}` (the editor's own layer flags, see "Locked layers" below), `layer.duplicate {layer, count?}` (the layers panel's Duplicate: the subtree and its `#id` rules under the copies' new names, `count` 1-100 copies; the reply lists `copies`), `layer.group {layers, kind?}` (the layers panel's Group / Convert to Stack, layers with one parent, in document order: `group` (default) wraps them into a new `Group_<n>` div; `stack` gives `display: flex` -- a single group layer in place, else wrapped into `Stack_<n>`; the reply names the `layer`), `layer.delete {layer, confirm}` (the layers panel's Delete: one undo step takes the layer, its subtree, their tracks on every timeline (reply `removedTracks`), their expressions (`removedExpressions`) and the rules whose subject is only their `#id` -- `#id`, `#id:hover`, `#id:state(...)` (`removedRules`). While something **elsewhere** points into it -- another layer's trigger or binding, a stylesheet trigger, a flow edge -- it is refused with `kInvalidArgument` and the message lists up to 10 of them as `[{"kind": "trigger" | "binding" | "flow", "where": "#Other on:press"}]` -- the same list is the error's `references` field: change those first, then delete). `layer.setAttrs` / `layer.create` `src`, `href` (not of a `<link>`) and `texture` must name an existing file (`kNotFound` with the resolved path), as a `url()` of `layer.setProps` must |
111
+ | Style | `style.setToken {name, value}`, `style.setTheme {theme}` (preview only), `style.setRule {selector, props, file?, media?}` (declarations of the rule with exactly this selector, e.g. `.card:hover`; null removes one; the rule is added when missing; default the UI's own stylesheet, a shared one only when `file` names it. `media` is an `@media` query such as `(max-width: 1280px)` or `(aspect-ratio <= 4/3)`: the rule inside that `@media` block is written, the block added at the end of the stylesheet when missing, e.g. `@media (max-width: 1280px) { .card { left: 1px } }`; a rule left empty goes, and its block with it; in a format 2 document one call splits by kind: geometry -- what `<layout>` takes, e.g. `width`, `left`, `display` -- goes to the same-selector rule of `<layout>`, the rest to `<style>` (or `file`), with `media` into each section's `@media` block, each rule made when missing, one undo step; the reply's `rule` is the `<style>` one and `rules` lists both), `style.renameRule {selector, newSelector, file?}` (the style rules panel's selector edit; format 2: the `<layout>` and `<style>` rules of the selector together), `style.deleteRule {selector, media?, file?, confirm}` (a whole rule; with `media` the rule inside that `@media` block; format 2 without `file`: both sections' rules, listed in `files`), `style.moveDecl {from, to, prop, fromFile?, toFile?}` (the panel's Move to: the destination rule takes the value, the source loses it and goes when empty; format 2: both rules looked for in the property's section first). These three find a rule as `style.setRule` does (a rule only in a shared stylesheet needs its `file`); `kNotFound` names a missing rule or property. A token (`style.setToken`, `restyle`, `design.put` of a variable) is the same edit the token panel makes: it changes the open UI's copy of `shared/tokens.xts`, the panel shows it at once and `doc.save` writes the file |
112
+ | Timelines | `timeline.create {name, duration?, scope?}`, `timeline.setKeyframe {name, layer, prop, time, value, easing?}` (an effect parameter `prop` is `effect.<index|name>.<param>`: a vec2 as a whole, e.g. `effect.shadow.offset` or a shader vec2, is one key with two numbers, `"<x>px <y>px"` or `"<x> <y>"`; `<param>.x` / `.y` key one component; slots `p<n>` (float 0-15), `c<n>` (colour 0-3), `v<n>` (vec2 from float slot n, 0-14) address any effect without its names; `time` is seconds: a time past the timeline's `duration` is written all the same and the reply's `notes` says `time <t> s is past the timeline's end (<end> s); times are seconds`), `timeline.setKeyframes {name, keys: [{layer, prop, time, value, easing?}], scope?}` (many keys, each as `timeline.setKeyframe` takes it, at most 2000: one undo step, checked against the compile once -- one bad key or a result that does not compile refuses the whole batch and changes nothing; reply `{written: n}`; the same past-the-end note for the latest time; use it instead of a loop of `timeline.setKeyframe`), `timeline.setEasing {name, layer, prop, time, easing}`, `timeline.removeKeyframe {name, layer, prop, time}`, `timeline.removeTrack {name, layer, prop?, scope?}` (the layer's track of `prop`, or all its tracks without it, keys included, one undo step; reply `{removed: n}`; no such track: `kNotFound`), `timeline.delete {name, confirm}`, `timeline.rename {name, newName, scope?}`, `timeline.duplicate {name, newName, scope?}` (triggers that play the old name are not rewritten), `timeline.setDuration {name, duration, mode?, scope?}` (`clip`, default: only the length changes, keys past the end stay; `scale`: every key, marker and cue time scales by new / old length), `timeline.setMarker {name, time, label, scope?}` / `timeline.setCue {name, time, sound, scope?}` (a name adds the marker / cue at `time` or renames the one there; `null` removes it), `timeline.moveKeys {name, keys: [{layer, prop, time}], dt?, scale?: {pivot?, factor}, scope?}` (new time = pivot + (time - pivot) x factor + dt, clamped at 0; all keys in one undo step; use it instead of remove + set), `timeline.stagger {name, keys: [{layer, prop, time}], interval?, order?, reverse?, seed?, scope?}` (each layer's keys shift by i x `interval` ms, default 50; `order` layer \| reverse \| random \| center; the reply lists `layers: [{layer, delayMs}]`, the shift in milliseconds), `timeline.fromAnimations {name, scope?, duration?, autoplay?, markers?, addMarkers?, dryRun?}` (the CSS `animation`s of the scope's subtree -- default the whole document -- that share a cycle become a new root-scope timeline `name`: keys at delay + p x duration with iterations expanded, the collected declarations and the `@keyframes` only they used removed, `autoplay` `loop` (default: `on:show` `play(name, loop)` on the scope element) \| `once` (`play(name, hold)`) \| `none`; `markers: true` adds one where each layer turns visible; one undo step; reply `collected`, `kept` (each with `reason` and `message`), `tracks`, `markers`, `removedKeyframes`; nothing collected = no change, `created: false`), `animation.preset {layer, preset, timeline?, at?, scope?}` (a stroke preset on a vector shape `<svg>/<shape>`: `draw-on`, `draw-off`, `marching-ants`, `pulse-stroke`; default timeline `intro`), `animation.followPath {path, layer, timeline, start?, end?, samples?, align?, autoOrient?, scope?}` (bakes the shape `path` into `layer`'s `transform` translate keys, evenly spaced by arc length), `timeline.setExpression {timeline, layer, prop, component?, text?, enabled?, scope?}` (Docs/design/58: an After Effects style expression on one row, e.g. `wiggle(2, 6)`, lowered into keyframes when the document compiles; `prop` `translate` + `component` `y`, or `"translate.y"`; `text: ""` removes it, `enabled: false` switches it off; a row without keys first gets a key at 0 s with its current value (reply `addedKey`), all in one undo step; refused on a row whose translate keys carry a motion path, and on a version 1 document with a `needsV2` message; the reply's `expression` carries the compile status as `timeline.get` shows it), `timeline.bakeExpression {timeline, layer, prop, component?, inputs?, scope?}` (After Effects' Convert Expression to Keyframes: the keys the expression lowers to replace that row's keys and the expression is removed, one undo step; on one component of a two-value row such as `translate.y` the other component keeps its motion -- its values are sampled at the new key times, and where the two need different easings that stretch is cut into linear keys (reply `approximated: true`); `rotate.x` / `rotate.y` go into the layer's `transform` track as `rotateX()` / `rotateY()`; an expression with run-time inputs (`needsRuntime`: `port()`, another element's layout result, another timeline's row, `randomPerPlay()`) is baked with the current test values -- the ports' values in the preview, the last layout, the rows' current values, `randomPerPlay()` at the middle of its range -- or with `inputs: {ports: {<name>: n}, layout: {<layer>: {left, top, width, height}}, rows: {<layer>: {<row>: n}}, randomPerPlay: 0..1}`, and the reply adds `runtime: true`, `usedInputs` and a `warning` (the row no longer reacts to game values); refused while the expression is off, has an error, lowers differently per symbol instance, or the document does not compile; the reply gives `keys` (written), `lowered` and the `track`). `layer.delete`, `layer.move` and `timeline.removeKeyframe` remove the expressions whose layer or row they take away and list them as `removedExpressions`; `layer.rename`, `timeline.rename` and `timeline.duplicate` carry them along |
93
113
  | Interaction | `trigger.set {layer, event, actions}`, `state.set {layer, state, prop, value}`, `bind.set {layer, target, expr}`, `port.set {layer, name, type, dir?, expose?, default?}` (`type: ""` removes the port; `default` is a literal such as `80`, `true`, `"Guest"`, `#ff0000`; null removes it, omitted keeps it while the type is unchanged. In source format 2 no `port:` attribute is written: the port is a line of `<ports>`, so `layer` is `body` (the document's ports) or a symbol's root (`<Symbol>/<root>`, the symbol's ports), and any other layer is `kUnsupported`) |
94
114
  | Flow | `flow.set {graph, dryRun?}` (replaces the whole `.xtflow` graph `{nodes, edges, groups?}`, one undo step, written by `doc.save`; parse errors fail the call; `dryRun: true` only returns `problems`; a `flow.animatesWithContinuousSignal` warning is not in `problems`, it appears in the editor's Messages panel as `flow: warning: ...`, so look at Messages after a `flow.set` and rewrite the edge: a flow drives, it never interpolates). Read it first with `flow.get` and send it back whole. T-371: works on a background document too (`doc` = a UI opened without `show`); the graph stays with that UI when the user switches to it |
95
115
  | Flow `state` node (T-541) | a flow graph may hold `{id, type: "state", params: {states: [..], initial?, transitions: [{from, on, to}], events?}}`: one pulse input per event, `set` (string) and `guard` (bool); outputs `state`, `index`, `changed`, `enter<Name>` / `exit<Name>` per state. Edges into an element take `#id.setState` with edge params `state` (required) and `mode` (`on` / `off` / `toggle`). Sent whole through `flow.set` like every other node |
96
- | Symbols | `symbol.create {layers, name, origin?, shared?}`, `symbol.instantiate {symbol, parent, name?, index?, source?}` (`source`: `document` (default), `project` = `<shared.symbols>/<Symbol>.xt`, `standard` = the standard library, copied into `shared.symbols` first; a library symbol is linked when needed -- `<symbols src>` in a source format 2 document, `<link rel="symbols">` in format 1 -- and the reply names it as `library`), `symbol.override {instance, path, value}`, `symbol.detach {instance, confirm}` |
97
- | Symbol libraries (T-502, 49.7; see "Symbol libraries" below) | `symbols.use {names, group?, library?}`, `symbols.useGroup {group, library?}`, `symbols.updateCopy {name}` write the open project (one undo step each; `create`, `restyle`, `repair-import`, `single-element`). `symbols.saveAsGroup {names, groupId, name, library?}`, `symbols.loadPreset {group, keepOld?}`, `symbols.import {path \| url, library?, as?, replaceOlder?}`, `symbols.export {group, library?, out, author?, license?, fonts?}`, `symbols.mountLibrary {path}`, `symbols.unmountLibrary {id}` write a library or the mount list: the `library` scenario only, and refused with `kPermissionDenied` until the user allows AI library writes (the preference or a one-time approval; a client cannot grant it to itself). None takes `ifRevision` |
98
- | Assets | `asset.import {file, type?, id?, source?, license?, confirm?}`, `asset.setStatus {id, status}` (never `approved`). T-371 (the asset workbench's edits; `asset` is the asset file's project-relative path, e.g. `shared/img/a.png`): `asset.replace {asset, path, allUses?}` (without `allUses`: the file gets the content of `path` -- same extension, absolute or project-relative -- keeping its identity, status draft; with `allUses: true`: every `src`/`href` and `url()` of the document naming `asset` is pointed at the asset `path` instead, one undo step, returns `replaced`), `asset.slice {asset, slices: [left, right, top, bottom]}` (nine-slice in the `.meta`; all zero removes it), `asset.linkFolder {path, collection?}` (an existing absolute directory; an already linked one gets the new collection; writes the project file), `asset.sync` (imports new files of the linked folders, replaces changed ones as `stale`; returns `imported`, `replaced`, `unchanged`, `missing`, `warnings`) |
116
+ | Symbols | `symbol.create {layers, name, origin?, shared?}`, `symbol.instantiate {symbol, parent, name?, index?, source?}` (`source`: `document` (default), `project` = `<shared.symbols>/<Symbol>.xt` -- a qualified `<namespace>/<Name>` is `<shared.symbols>/<namespace>/<Name>.xt` (56.3; the name `symbols.use` returns in `symbols[].qualified`), `standard` = the standard library, copied into `shared.symbols` first; a library symbol is linked when needed -- `<symbols src>` in a source format 2 document, `<link rel="symbols">` in format 1 -- and the reply names it as `library`), `symbol.override {instance, path, value}`, `symbol.detach {instance, confirm}` |
117
+ | Symbol libraries (T-502, 49.7; see "Symbol libraries" below) | `symbols.use {names, group?, library?}`, `symbols.useGroup {group, library?}`, `symbols.updateCopy {name, group?, overwriteLocal?}`, `symbols.move {from, to}`, `symbols.duplicateDetached {name, newName}`, `tokens.applyStyle {group, library?, theme?, dryRun?}` write the open project (one undo step each; `create`, `restyle`, `repair-import`, `single-element`). `symbols.saveAsGroup {names, groupId, name, library?}`, `symbols.loadPreset {group, keepOld?}`, `symbols.import {path \| url, library?, as?, replaceOlder?}`, `symbols.export {group, library?, out, author?, license?, fonts?}`, `symbols.mountLibrary {path}`, `symbols.unmountLibrary {id}` write a library or the mount list: the `library` scenario only, and refused with `kPermissionDenied` until the user allows AI library writes (the preference or a one-time approval; a client cannot grant it to itself). None takes `ifRevision` |
118
+ | Assets | `asset.import {file, type?, id?, source?, license?, confirm?}` (asset ids: lowercase ASCII letters, digits, `-`, `_`, `.` -- not first or last, no `..` -- and non-ASCII characters; no uppercase, spaces, `/`, `\` or `:`. Without `id` the file name is kept when it follows the rule (`bg_01_room.jpg` -> `bg_01_room`), else made to (`Hero Portrait.png` -> `hero-portrait`); an `id` against the rule is refused with `did you mean "..."`; an image in a format the runtime cannot decode -- WebP, AVIF, HEIF, JPEG XL, TIFF, QOI; told by its bytes -- is copied all the same and the reply's `notes` say `image asset "<file>": format <fmt> cannot be decoded (supported: …); convert it to PNG or JPG first`, the lint finding for it is `asset.undecodable`), `asset.setStatus {id, status}` (never `approved`). T-371 (the asset workbench's edits; `asset` is the asset file's project-relative path, e.g. `shared/img/a.png`): `asset.replace {asset, path, allUses?}` (without `allUses`: the file gets the content of `path` -- same extension, absolute or project-relative -- keeping its identity, status draft; with `allUses: true`: every `src`/`href` and `url()` of the document naming `asset` is pointed at the asset `path` instead, one undo step, returns `replaced`), `asset.slice {asset, slices: [left, right, top, bottom]}` (nine-slice in the `.meta`; all zero removes it), `asset.linkFolder {path, collection?}` (an existing absolute directory; an already linked one gets the new collection; writes the project file), `asset.sync` (imports new files of the linked folders, replaces changed ones as `stale`; returns `imported`, `replaced`, `unchanged`, `missing`, `warnings`) |
99
119
  | Vectors (T-224) | `vector.set {layer, svg? \| shapes?}`, `vector.editPath {shape, ops}`, `vector.boolean {shapes, op}`, `vector.bake {layer, shape?}`, `vector.shapeOp {layer, shape?, op, ...}` (T-370), `vector.textToOutlines {layer}`, `vector.extract {layer, path?}`, `vector.morph {shape, action, index?}`, `vector.trace {layer, mode?, threshold?, colors?, minArea?, smoothing?, hideSource?}` (bitmap `<img>` -> new traced `<svg>` layer after it; T-232); read with `vector.get {layer, normalize?}` (see "Vector layers" below) |
100
120
  | Rigs (T-248) | `bone.add {layer, skeleton?, parent?, length, rotate, translate?, id?}`, `bone.remove {bone}`, `bone.setRest {bone, rest}`, `bone.pose {bone, rotate?, translate?, scale?, time?, timeline?}`, `bone.resetToRest {skeleton}`, `bone.setRestFromPose {skeleton}`, `constraint.add {bone, kind, target?, params?}`, `constraint.set {constraint, attr, value}`, `constraint.remove {constraint}`, `skin.bind {shape, skeleton, auto?}`, `skin.set {shape, vertices}`, `skin.unbind {shape}`, `skin.smooth {shape, iterations}`, `skin.prune {shape, threshold}`, `mesh.convert {image}`, `mesh.setPins {mesh, pins}`; read with `bone.list {layer}`, `bone.world {bone}`, `skin.get {shape}`, `mesh.pins {mesh}` (see "Rigs" below) |
101
121
  | Cels (T-229) | `cel.add {group, after?, duplicate?}`, `cel.setRange {group, index, start, end}`, `cel.remove {group, index, confirm}`, `cel.convert {group}`; read with `cel.list {group}` (see "Cel animation" below) |
102
- | Documents | `doc.open {path, show?, discard?}` (a project UI id or a `.xt` path; it becomes **your** active document, opened in the background: the user's view stays. `show: true` also switches the editor's shown document -- only when the user asked to see it. Fails with `kUnsavedChanges` when it would drop unsaved edits; `discard: true` only after asking the human), `doc.reload {discard?}` (reads the document again from disk after anything wrote its files outside the editor -- `xtframe-import`, a re-import from the command line, a direct write; drops its undo history; unsaved edits: `kUnsavedChanges` unless `discard: true`, after asking the human), `doc.save {force?}` (T-366: `kConflict` when the disk is newer, `diskNewer`; `force: true` overwrites it, `doc.setSource {kind, text, file?, ifRevision}` (the source panel's edit, as data: `kind: "xt"` replaces the whole `.xt`, `kind: "xts"` one stylesheet -- `file` as `style.getRules` names it, default the UI's own `.xts`. The text is compiled first; text that does not parse or compile, or that adds a compile warning, is refused with the diagnostics and nothing changes -- in format 2 that includes geometry written in a stylesheet or `<style>` (`style.geometryInStyle`), a look property in `<layout>` (`layout.notGeometry`) and a `port:` attribute instead of a `<ports>` line (`ports.onElement`). Prefer the typed operations; use it for a change none of them makes, after `doc.source`, with `ifRevision`), `undo`, `redo` (T-366, 37.8.1 D3: one stack for everyone; you undo / redo only the steps on top of it that are **your own** -- when the top is someone else's step, `kConflict` "top of the undo stack is <seat>'s edit": leave it, the user's Ctrl+Z is theirs), `import.reimport {source, ui?, prune?, force?, confirm?}`, `export.lottie {path, ui?, timeline?, fps?, bakeUnsupported?, embedImages?, strict?, confirm?}` (T-234: the UI as a Lottie JSON file; returns the report: `skipped`, `baked`, `approximated`. T-261b: it reads the saved files, so `doc.save` first -- unsaved edits fail with `kUnsavedChanges`; overwriting an existing file outside the project needs `confirm: true`) |
122
+ | Documents | `doc.open {path, show?, discard?}` (a project UI id or a `.xt` path; it becomes **your** active document, opened in the background: the user's view stays. `show: true` also switches the editor's shown document -- only when the user asked to see it. Fails with `kUnsavedChanges` when it would drop unsaved edits; `discard: true` only after asking the human), `doc.reload {discard?}` (reads the document again from disk after anything wrote its files outside the editor -- `xtframe-import`, a re-import from the command line, a direct write; drops its undo history; unsaved edits: `kUnsavedChanges` unless `discard: true`, after asking the human), `doc.save {force?}` (T-366: `kConflict` when the disk is newer, `diskNewer`; `force: true` overwrites it; it always saves, even a document that does not compile, and the reply says `compiles: true | false` -- false with the first compile error in `warnings`: fix it before you finish), `doc.setSource {kind, text, file?, ifRevision}` (the source panel's edit, as data: `kind: "xt"` replaces the whole `.xt`, `kind: "xts"` one stylesheet -- `file` as `style.getRules` names it, default the UI's own `.xts`. The text is compiled first; text that does not parse or compile, or that adds a compile warning, is refused with the diagnostics and nothing changes -- in format 2 that includes geometry written in a stylesheet or `<style>` (`style.geometryInStyle`), a look property in `<layout>` (`layout.notGeometry`) and a `port:` attribute instead of a `<ports>` line (`ports.onElement`). Prefer the typed operations; use it for a change none of them makes, after `doc.source`, with `ifRevision`), `undo`, `redo` (T-366, 37.8.1 D3: one stack for everyone; you undo / redo only the steps on top of it that are **your own** -- when the top is someone else's step, `kConflict` "top of the undo stack is <seat>'s edit": leave it, the user's Ctrl+Z is theirs), `import.reimport {source, ui?, prune?, force?, confirm?}`, `export.lottie {path, ui?, timeline?, fps?, bakeUnsupported?, embedImages?, strict?, confirm?}` (T-234: the UI as a Lottie JSON file; returns the report: `skipped`, `baked`, `approximated`. T-261b: it reads the saved files, so `doc.save` first -- unsaved edits fail with `kUnsavedChanges`; overwriting an existing file outside the project needs `confirm: true`) |
103
123
  | Design system (T-310, `design.md`) | `design.put {kind, entry}` (always `draft`; `status: approved` / `approved:` -> `kForbidden`; a token's value goes through `style.setToken`), `design.importReference {path \| url, group, title?, tags?, license?, extract?}`, `design.link {from, rel, to, note?}`, `design.unlink {from, rel, to}`, `design.build` (regenerates `DESIGN.md`, returns the lint counts), `design.export {format: html \| claude-design, out}` (a file / a Claude Design design-system folder inside the project), `design.importDesignSystem {dir}` (T-316: a Claude Design design-system folder back in as drafts; existing values are never overwritten), `design.delete {ref, confirm}` (outside a scenario or in `design-system`: removes the entry and every link to it; refused while a UI, layer or symbol uses it -- `design.usage`; a text, decision or reference entry's files go too; `confirm: true` after asking the human). `design.approve` / `design.deprecate` are human-only gates: `kForbidden` for an AI path unless the user made your seat a steward (37.8.1 D1; the reply then has `asSteward: true` and the entry `approved.by` is "<seat> (steward)"); never inside a scenario. These need the `full` scope |
104
- | Project (T-212) | `project.create {dir, name, id, template?, discard?}` (new UI Project, opened; `kUnsavedChanges` as `doc.open`; writes `<dir>/<name>.xtui`, returns `path` = that file and `dir`), `project.saveAs {dir}` (a lone `.xt` moves into `<dir>/<ui id>/`; a named project is copied; the copy's project file is `<name>.xtui`), `project.publish {target?: {kind: dir, path}, ui?, confirm?}` (complete bundle directory; default: last target, else `<project>/publish`; returns the pack summary; T-261b: a target outside the project, or an existing non-empty directory without `manifest.json`, needs `confirm: true`; T-687: images are written per the project file's `publish.images.compress`, which no op sets -- the user edits it; T-693: a successful publish removes the files in the target's `ui/`, `assets/`, `thumbs/`, `themes/`, `strings/`, `atlas/` and `fonts/` that it neither wrote nor lists). T-261b: these three need the `full` scope |
124
+ | Project (T-212) | `project.create {dir, name, id, template?, discard?}` (new UI Project, opened; `kUnsavedChanges` as `doc.open`; writes `<dir>/<name>.xtui`, returns `path` = that file and `dir`), `project.saveAs {dir}` (a lone `.xt` moves into `<dir>/<ui id>/`; a named project is copied; the copy's project file is `<name>.xtui`), `project.publish {target?: {kind: dir, path}, ui?, confirm?}` (complete bundle directory; default: last target, else `<project>/publish`; returns the pack summary; T-261b: a target outside the project, or an existing non-empty directory without `manifest.json`, needs `confirm: true`; T-714: images are written per the project file's `publish.images.compress`; when the project does not set it, a publish uses `auto` (BC7 for images with both sides >= 256 px; `project.get` reports it as `publish.images.effectiveCompress`); the return also carries `result`, a one-line publish result (bundle size on disk, images compressed / uncompressed / in atlases, estimated display memory); T-693: a successful publish removes the files in the target's `ui/`, `assets/`, `thumbs/`, `themes/`, `strings/`, `atlas/` and `fonts/` that it neither wrote nor lists). `project.setPublishSettings {images?: {compress: auto|bc7|none}, atlas?: {enabled?, maxSize?: 1024|2048|4096, scope?: ui|bundle, mipmaps?}, fonts?: system|bundled, embedImages?, embedFonts?}` (T-714: the Publish dialog's Bundle options; each field optional, nothing is written when one is wrong; `none` is for platforms without BC such as iOS / Android; writes the project file and returns the `publish` object as `project.get` reports it). T-261b: `project.create`, `project.saveAs` and `project.publish` need the `full` scope |
105
125
  | Project files (T-371, `full` scope) | `project.addUi {id, doc?, copyFrom?}` (a blank UI, or a copy of UI `copyFrom` -- its open document as it is now; `doc` defaults to `<prefix>/<id>/<id>.xt` after the project's layout; writes the document and the project file), `project.renameUi {id, newId}` (hosts bind to the id; the global flow's `ui#<id>` endpoints and timeline `ui` parameters are rewritten, `rewritten` lists the files; an open document follows the new id), `project.removeUi {id, confirm, discard?}` (destructive: `confirm: true` after asking; files stay on disk; the UI on screen is refused, switch first; an open background UI with unsaved edits needs `discard` -> else `kUnsavedChanges`; the last UI is refused), `project.set {name?, game?, safeArea?: {default?, console?}, uiscale?: {rule?, logicalHeight?}, clamp?: [min, max|null] | null, dpiFloor?, responsive?: {scale?, position?, visibility?}, input?: {methods?, players?}, languages?, budget?: {frameMs?, effectLayers?, fillRate?, particles?}, engine?: {name?, version?}, platforms?: [{name, resolutions?: [[w, h]]}], fontFallback?: {<lang>: [families]}}` (the project tab's form; every field checked -- safe areas 0..0.5, logicalHeight 1..16384, dpiFloor 0..16, players 1..64, budgets >= 0, `scale` auto/none/clamp(a, b), resolutions 1..16384 -- and nothing written when one is wrong; `platforms` and `fontFallback` replace the whole list / all chains; returns the settings), `project.setAgents {text}` (replaces `AGENTS.md`), `conventions.put {kind: motion | layout, id, body, confirm?}` (`motion`: sets key `id` of `contracts/motion-spec.yaml` to `body`, key order and leading comments kept; `layout`: writes `conventions/layouts/<id>.xt` from the `.xt` text `body`, which must parse; replacing an existing template needs `confirm: true`). These write files, not undo steps |
106
126
 
107
127
  **Editor-only reference layers.** A layer that only helps while designing (a reference image,
@@ -127,7 +147,15 @@ rule). While the work site's `animate` is on (the user's Animate switch, or your
127
147
  `session.setView`), it records like the user's edits do: each animatable property (normal state)
128
148
  becomes a keyframe at the playhead in the active timeline (none selected in the current scope:
129
149
  `root-anim` / `<symbol>-anim`, created at 2 s), the rest is written as usual, one undo step;
130
- `notes` says `recorded into <timeline>@<t>`. Values are CSS as in the `.xts` (`"background-color": "var(--color-accent)"`). Prefer a
150
+ `notes` says `recorded into <timeline>@<t>` and the reply carries `recorded: {timeline, scope,
151
+ time}` (`time` a number: pass the three to `timeline.removeKeyframe` / `timeline.setEasing` to reach
152
+ that key). `record: false` writes the base style this once whatever `animate` says (also on
153
+ `style.setStyleParams`). Keyframe, marker and cue times are written on the millisecond grid (every
154
+ write rounds to 0.001 s, as the `.xt` stores them; two keys of a track in the same millisecond: the
155
+ later write replaces the earlier); a document loaded with finer times keeps them. On a
156
+ `<particles>` layer an attribute (`rate="30"`) beats the declaration (`particle-rate`): a write
157
+ that it overrides gets the note `particle-rate is set by the element's attribute 'rate' and wins;
158
+ use layer.setAttrs`. Values are CSS as in the `.xts` (`"background-color": "var(--color-accent)"`). Prefer a
131
159
  token (`var(--x)`) over a literal colour: the lint reports literals. `style.setRule` takes the
132
160
  same values for class and state selectors (`.card`, `.card:hover`).
133
161
 
@@ -141,8 +169,13 @@ become one layer of their own); every flat view ignores it. It is not animatable
141
169
  `layer.setProps`, `style.setRule` and `state.*` check what they write (T-355): an unknown
142
170
  property name is refused (`unknown property '<name>'`, with a hint); a `url()` must name an
143
171
  existing file; a value the compiler rejects, or newly warns about for that property, is rolled
144
- back (`the edit breaks the compile; rolled back` / `rolled back: <warning>`) and the document stays
145
- as it was. Read the message, fix the value and call again. An `@media` query the compiler does not
172
+ back (`the edit breaks the compile; rolled back; <first error>` / `rolled back: <warning>`) and the
173
+ document stays as it was. Read the message, fix the value and call again. `layer.create`, `layer.delete`,
174
+ `layer.move`, `layer.setAttrs`, `timeline.removeKeyframe` and `timeline.removeTrack` are checked the same
175
+ way (a result that does not compile is rolled back). When the document did not compile **before** your
176
+ write (a person's half-done edit, an old file), the write is made anyway -- so it can be fixed -- and the
177
+ reply's `notes` says `the document does not compile: <first error>`; the write that makes it compile again
178
+ says `the document compiles again`. A missing image or font file is the lint finding `asset.missing`. An `@media` query the compiler does not
146
179
  know (only `min-`/`max-width`/`-height`, `aspect-ratio >=`/`<=`, `orientation`, `resolution`,
147
180
  `platform`, `input` and `prefers-reduced-motion`; `aspect-ratio` takes `<=` / `>=`, not a colon:
148
181
  `(aspect-ratio <= 4/3)`) is rolled back the same way, the message naming the query. So:
@@ -222,21 +255,70 @@ library (`mine`), the extra libraries of the user's mount list and the open proj
222
255
  plus `set.json` with author, version and licence). A project never links a library file: it holds
223
256
  **copies** (49.3), made by the project writes below and recorded in `shared/symbols/index.json`.
224
257
 
258
+ **Same-named symbols (56.3).** Two libraries may both ship a `Button`. A project symbol is known by
259
+ its path under `shared/symbols`: `Button` for a flat file, `<namespace>/Button` for one in a
260
+ namespace directory (one level; the directory is named like a group id). The project resolves a clash
261
+ by itself -- never ask the user to rename or prefix anything: when `symbols.use` copies a symbol whose
262
+ flat name another project symbol already has, the copy goes to `shared/symbols/<group id>/<Name>.xt`
263
+ (with the symbols of its group it uses) and its name in the project is `<group id>/<Name>`. Write
264
+ **that** name in `<use symbol>` / `symbol.instantiate {source: "project"}` (`symbols[].qualified` of
265
+ the reply) and tell the user the new symbol was stored as `<group id>/<Name>` because the project
266
+ already had another `<Name>`. A bare name in a document always means the flat symbol.
267
+
225
268
  - **Reads** (any scenario): `symbols.libraries`, `symbols.library {library?}`, `symbols.get {name,
226
269
  group?, library?}`, `symbols.lint {group? | library? | path?}` -- the Read table above.
227
270
  - **Project writes** (`create`, `restyle`, `repair-import`, `single-element`; one undo step of
228
271
  `ReplaceSharedFile` steps on the active document's stack, so `undo` and a checkpoint rollback take
229
272
  them back): `symbols.use {names, group?, library?}` copies each symbol's file to
230
- `<shared.symbols>/<Name>.xt` (an existing copy is kept and reported in `skipped`), its fonts and
273
+ `<shared.symbols>/<Name>.xt`, with the symbols of its group it uses; `clashes [{name, path, reason,
274
+ existingSource, placed, because}]` reports what was not a plain flat copy: `placed` -- the flat
275
+ name is another symbol's (`existingSource` `<library>/<group>` or `project`), or (`because`) the
276
+ symbol uses one that is there, so the copy went to `<shared.symbols>/<group id>/<Name>.xt` and is
277
+ named `placed` (= `<group id>/<Name>`): use that name and tell the user; `same` -- the project's
278
+ copy is that group's symbol (`placed` names it); `nameTaken` -- the flat name and the namespace copy
279
+ are both other symbols': not copied, tell the user. `symbols [{name, qualified, path, source,
280
+ dependency}]` lists every symbol handled with the name to write in `<use symbol>`. Its fonts and
231
281
  textures to the asset root (same content skipped, other content under a hashed name, `renamed`),
232
282
  appends the tokens it reads that `shared.tokens` lacks with the group's defaults (`tokensAdded`,
233
283
  theme values to the theme files) and records the source; a name no library has fails the whole call
234
284
  with `kNotFound` and nothing is written. `symbols.useGroup {group, library?}` is `use` for every
235
- symbol of the group (call it before building a UI from that group). `symbols.updateCopy {name}`
236
- writes the library's file over the project's copy (fonts and textures by the same rules, the
237
- project's token values kept) -- only on the user's word: `project.syncSymbols` shows which copies
238
- are `outdated` or `modified`, you **suggest**. Replies: `{status, written, skipped, renamed,
239
- tokensAdded, notFound, changes}`.
285
+ symbol of the group (call it before building a UI from that group). `symbols.updateCopy {name,
286
+ group?, overwriteLocal?}` (`name` may be qualified, `<namespace>/<Name>`) writes the file of the copy's **recorded** source (the library and group
287
+ `index.json` records; `group`, when given, must match it) over the project's copy (fonts and
288
+ textures by the same rules, the project's token values kept) -- only on the user's word. Its
289
+ `state`: `upToDate`, `stale` (written), `locallyModified` / `staleAndModified` (the project changed
290
+ its copy: refused, `updated: false`, unless `overwriteLocal: true` -- ask the user first, the
291
+ changes are lost), `noSource` (the project's own symbol) and `sourceMissing` (the recorded library
292
+ is not mounted): never written. Replies: `{status, written, skipped, renamed, tokensAdded,
293
+ notFound, clashes, symbols, changes}`; `updateCopy` adds `{state, updated, source}`.
294
+ `symbols.move {from, to}` moves a project symbol between `shared/symbols` and a namespace
295
+ directory (`from` / `to` qualified, the same bare name: `survey-2026/Button` -> `Button` puts it
296
+ flat, `Button` -> `mine/Button` into `mine/`) -- a rename of its identity: the file and its
297
+ `.xtanim.json` move, `index.json` is re-keyed and every `<use symbol>`, `symbol()` block, symbol
298
+ link and reference of the other symbol files follows, in the open document and in the other UIs on
299
+ disk. Refused (nothing changes) when `to` is taken. Reply `{from, to, file, changes, rewritten}`.
300
+ `symbols.duplicateDetached {name, newName}` (56.2 item 2) copies a project symbol as `newName`
301
+ (flat) that reads tokens of its own -- each `var(--x)` becomes `--<newname lower-case>-<x>`, first
302
+ valued at the project's value now and appended to `shared.tokens` (and to the themes that differ)
303
+ -- so a later style change leaves it alone; the original is untouched and the copy is never updated
304
+ from a library (`index.json` `derivedFrom`, no `source`). Reply `{name, file, tokens [{from, to,
305
+ value}], unresolved, changes}`.
306
+ - **The project's style** (56.2; 47 core vocabulary). A project has **one** style: the values in
307
+ `shared/tokens.xts` and `shared/themes/*.xts` that every symbol reads, whichever library it came
308
+ from. Every library declares the 52 **core tokens** (`--color-*`, `--font-*`, `--space-*`,
309
+ `--radius-*`, ...; `xtframe-symbols tokens-json` marks them `core: true`); anything else is the
310
+ library's extension. `tokens.applyStyle {group, library?, theme?, dryRun?}` replaces the project's
311
+ core token values with the group's (missing ones appended, with the fonts their families need; each
312
+ group theme `tokens-<name>.xts` into `shared/themes/<name>.xts`; `theme` makes that theme the base
313
+ instead) and records the style in `shared/symbols/index.json`; extension tokens, symbols and
314
+ documents are never touched. **Always call it with `dryRun: true` first and show the user the
315
+ report**: `overwritten [{name, theme, before, after, custom}]` (`custom` -- the project's own value,
316
+ not what the last applied style wrote: say so), `added`, `missingCore` (the group lacks them; the
317
+ project's values stay), `uncovered [{name, origin, usedBy}]` (extension tokens project symbols read
318
+ that the new style does not provide: they keep their values and may not match), `themesNotProvided`
319
+ and `copied`; apply it only on their word (one undo step; the reply adds `changes`). When symbols of
320
+ several groups are linked, tokens the project does not declare come from the applied style's group
321
+ (else the first linked group).
240
322
  - **Library writes** (the `library` scenario; `kPermissionDenied` until the user allows them):
241
323
  `symbols.saveAsGroup {names, groupId, name, library?}` turns project symbols into a new group of a
242
324
  writable library (tokens, fonts, textures, themes collected the reverse way; `{groupId, library,
@@ -290,7 +372,14 @@ one-line blurb, target, visible default); talk to the user in these names.
290
372
  | Operation | Does |
291
373
  |---|---|
292
374
  | `catalog.list {target?}` | `entries: [{id, category, name: {en, zh}, blurb: {en, zh}, target}]`; with `target`, only the entries offered for that layer's role (text entries on text layers, shape entries on vector layers), each with `presence`: `absent`, `present` (a style the layer shows already; an effect or modifier of that kind is there) or `full` (an effect while the effect chain holds 16) |
293
- | `catalog.add {target \| targets, id}` | adds the entry to each layer, one undo step: a style writes its visible default into the layer's own rule (`kNotFound` when every layer has it already), an effect goes to the end of the effect chain (repeatable), a modifier to the end of the vector group; a `shader:<name>` example is copied to `<assetRoot>/fx/` and appended as `custom("…")` (the document must be saved). `custom`, `custom-new` and effect templates are not added here (`fx.apply` for templates) |
375
+ | `catalog.add {target \| targets, id}` | adds the entry to each layer, one undo step: a style writes its visible default into the layer's own rule (`kNotFound` when every layer has it already), an effect goes to the end of the effect chain (repeatable), a modifier to the end of the vector group; a `shader:<name>` example is copied to `<assetRoot>/fx/` and appended as `custom("…")` (the document must be saved). `layer` is another name for `target` |
376
+ | `catalog.add {id: "custom", file, layer}` | appends `custom("<file>")` to the end of the layer's effect chain -- the same Core function and undo step as the Effects panel's "Add custom effect". `file` is a file name under `<assetRoot>/fx/` (`heat-haze` or `heat-haze.xtfx`) or a path relative to the project root; written relative to the document. A file that does not exist fails with `kNotFound` (make it with `shader.create`). Reply `{layers, id, file}` (`file` as written). `custom-new` and effect templates are not added here (`shader.create` makes a file; `fx.apply` for templates) |
377
+
378
+ A built-in effect's parameter on a timeline is `effect.<function>.<name>` with the names of the
379
+ `xtui` skill's `style-groups.md` ("Effect parameters on a timeline"), not the CSS function names:
380
+ `effect.color-adjust.saturation`, not `saturate`. Colour adjust's `brightness` is **additive**
381
+ (0 = unchanged, -1 = black), unlike CSS `brightness()`: to dim a layer, lower its `opacity` over
382
+ something dark or put a black layer over it.
294
383
 
295
384
  ```
296
385
  catalog_list {"target": "Btn_1"} -> entries with presence
@@ -298,6 +387,36 @@ catalog_add {"targets": ["Btn_1", "Btn_2"], "id": "shadow"}
298
387
  catalog_add {"target": "Logo_Path", "id": "mod:xt-round"}
299
388
  ```
300
389
 
390
+ ## Custom shaders (`shader.*`, 29 §29.20.3, 18 §18.7)
391
+
392
+ A custom shader is a `.xtfx` file of the project, `<assetRoot>/fx/<name>.xtfx` (header -- `name:`,
393
+ `blurb:`, `param <name> <float|vec2|color> <default> [<min>, <max>]`, `fallback:`, `expand:` -- up to
394
+ `---`, then the HLSL-subset body `float4 xtMain(XtInput i)`; see `scenarios.md` "Custom shader
395
+ inputs"). These operations write the file, not the document: no undo step, no `ifRevision`, and
396
+ not tied to a layer: a scenario that lists them (`shader`, `create`) allows them under a subtree
397
+ scope too. `name` follows the
398
+ asset id rule (lowercase ASCII letters, digits, `-`, `_`, `.`).
399
+
400
+ | Operation | Does |
401
+ |---|---|
402
+ | `shader.list {}` | `shaders: [{name, file, params: [{name, type, default, min?, max?}]}]` by name (`type` float \| vec2 \| color; a colour `default` is `#rrggbb`); a file that does not parse also has `errors` |
403
+ | `shader.get {name}` | `{name, file, source, params}` |
404
+ | `shader.create {name, source?, from?}` | writes a new file from `source`, else from the built-in example `from` (`starter`, default, \| `ripple` \| `swirl`; its header `name:` becomes `name`). A taken name fails with `kAlreadyExists` (no `-2`: pick another name, or `shader.setSource`). Reply `{name, file, params, previous: null, recompiled}`. It only creates the file: apply it with `catalog.add {id: "custom", file: "<name>", layer}` |
405
+ | `shader.setSource {name, source}` | replaces the text of an existing file; reply `{name, file, params, previous, recompiled}` -- `previous` is the SHA-256 of the text it replaced, `recompiled` the open documents that use the file, whose previews were recompiled |
406
+
407
+ Both writes run the `.xtfx` parser (header and HLSL subset) first: a source it refuses fails with
408
+ `kInvalidArgument`, the error's `errors: [{line, column, message}]` point into the whole file, and
409
+ nothing is written -- fix that line and send it once more. A shader parameter is animated with
410
+ `timeline.setKeyframe` / `setKeyframes`: `prop` `effect.<Name>.<param>` (the header's `name:`) or
411
+ `effect.<i>.<param>` (the effect's index in the layer's effect chain).
412
+
413
+ ```
414
+ shader_create {"name": "heat-haze", "from": "ripple"}
415
+ shader_setSource {"name": "heat-haze", "source": "name: HeatHaze\nparam amount float 4 [0, 16]\n---\nfloat4 xtMain(XtInput i)\n{\n return xtSample(i.uv + float2(0, sin(i.uv.x * 40 + xtTime) * amount * i.texelSize.y));\n}\n"}
416
+ catalog_add {"id": "custom", "file": "heat-haze", "layer": "Title", "ifRevision": 41} -> custom("../shared/fx/heat-haze.xtfx") at the end of the chain
417
+ timeline_setKeyframe {"name": "intro", "layer": "Title", "prop": "effect.HeatHaze.amount", "time": 0.5, "value": 8, "ifRevision": 42}
418
+ ```
419
+
301
420
  ## Vector layers (`vector.*`, 31 §31.10)
302
421
 
303
422
  An inline `<svg>` is a vector layer, and its shapes are addressed as `<svg id>/<shape id>`
@@ -447,7 +566,7 @@ To draw a new cel, `cel.add` a copy, then edit its shapes with `vector.set` / `v
447
566
 
448
567
  | Operation | Does |
449
568
  |---|---|
450
- | `animate.entrance {layers, style?, duration?, stagger?, delay?, timeline?}` | an `intro` timeline: `fade`, `rise` or `scale`, staggered within the spec |
569
+ | `animate.entrance {layers, style?, duration?, stagger?, delay?, timeline?}` | an `intro` timeline: `fade`, `rise` or `scale`, staggered within the spec (`duration`, `stagger`, `delay` in seconds) |
451
570
  | `animate.exit {layers, style?, ...}` | an `outro`: `fade`, `sink` or `scale` |
452
571
  | `animate.emphasis {layers, kind, duration?, timeline?}` | `pulse`, `shake` or `glow` |
453
572
  | `layout.anchor {layers, template, margin?}` | anchors to the safe area by template: `hud-corners`, `menu-list`, `inventory` |
@@ -488,13 +607,20 @@ The result of an intent operation lists `expanded[]`, the low-level operations i
488
607
 
489
608
  `scenario.list`, `session.setScenario {name, root?, entry?, explore?, rollback?}` (starts a work
490
609
  item on the main line; `explore: true` runs it on a variant of its own instead; see SKILL.md "Work
491
- items"), `session.endScenario` (ends the work item: saves, runs the gates when it wrote anything and
610
+ items"; a one-layer scenario without `root` takes the work site's selection and says so in `notes`:
611
+ `scope: subtree '<path>' (from the current selection); pass root:"*" for the whole document`;
612
+ `root: "*"` asks for the whole document; under a subtree scope an op the contract lists -- a Global
613
+ one such as `style.setRule` or `timeline.create`, or a project-file write such as `shader.create` -- is allowed), `session.endScenario` (ends the work item: saves, runs the gates when it wrote anything and
492
614
  returns `{empty, touched?, gates: {lint: {errors, warnings}, contract: {ok, violations}},
493
615
  checkpoint}`; nothing written -> `{empty: true}`; idempotent; without a scenario it ends the work item
494
616
  of your writes, see below), `session.getScope` (scope, scenario,
495
617
  budget used, your `seat {id, name, kind}`), `session.setScope {mode, root?}` (only without a
496
618
  scenario), `checkpoint.begin {scenario}`, `checkpoint.commit {id}`, `checkpoint.rollback {id}`,
497
- `checkpoint.list`. T-366: with project history (`.xtvc`) `checkpoint.begin` saves the open
619
+ `checkpoint.list`. Project history is switched on by a person, in the editor's History panel; no
620
+ operation turns it on. Until then `session.endScenario`'s `checkpoint` is `null` with the `note`
621
+ "the project has no history (.xtvc); no checkpoint was set" (and `checkpoint.begin`'s `history` is
622
+ `null`) -- that is normal, not a failure, and the undo stack plus `checkpoint.rollback`
623
+ still work; tell the user once that turning history on in the History panel keeps versions. T-366: with project history (`.xtvc`) `checkpoint.begin` saves the open
498
624
  documents and also sets a history checkpoint named `ai/<scenario>/<n>` by your seat (reply `history`:
499
625
  its slug); the user sees it in the History panel and it stays after you leave. `history.checkpoint`
500
626
  and `history.variant` are written by your seat. Leaving an explore variant with `rollback: true`
@@ -756,6 +882,7 @@ project.saveAs
756
882
  project.search
757
883
  project.set
758
884
  project.setAgents
885
+ project.setPublishSettings
759
886
  project.syncSymbols
760
887
  redo
761
888
  repair.anchor
@@ -775,6 +902,10 @@ session.getView
775
902
  session.setScenario
776
903
  session.setScope
777
904
  session.setView
905
+ shader.create
906
+ shader.get
907
+ shader.list
908
+ shader.setSource
778
909
  skin.bind
779
910
  skin.get
780
911
  skin.prune
@@ -813,25 +944,33 @@ symbols.loadPreset
813
944
  symbols.mountLibrary
814
945
  symbols.saveAsGroup
815
946
  symbols.unmountLibrary
947
+ symbols.move
948
+ symbols.duplicateDetached
816
949
  symbols.updateCopy
817
950
  symbols.use
818
951
  symbols.useGroup
952
+ timeline.bakeExpression
819
953
  timeline.create
820
954
  timeline.delete
821
955
  timeline.duplicate
956
+ timeline.fromAnimations
822
957
  timeline.get
823
958
  timeline.list
824
959
  timeline.moveKeys
825
960
  timeline.play
826
961
  timeline.removeKeyframe
962
+ timeline.removeTrack
827
963
  timeline.rename
828
964
  timeline.seek
829
965
  timeline.setCue
830
966
  timeline.setDuration
831
967
  timeline.setEasing
968
+ timeline.setExpression
832
969
  timeline.setKeyframe
970
+ timeline.setKeyframes
833
971
  timeline.setMarker
834
972
  timeline.stagger
973
+ tokens.applyStyle
835
974
  trigger.get
836
975
  trigger.set
837
976
  undo
@@ -10,10 +10,19 @@ screenshot budget; `scenario_check` evaluates its `done_when`. The product's con
10
10
  `xtui://contracts/<name>.yaml` resource). Read and meta operations are always allowed; everything
11
11
  else must match `allowed_ops` and not `forbidden_ops`.
12
12
 
13
- Scope: `full` (the whole document), `read-only`, `tokens-only`, `subtree` (needs `root`),
14
- `selection-or-named` (the subtree of `root` when you give one, else the whole document).
13
+ Scope: `full` (the whole document), `read-only`, `tokens-only`, `subtree` (needs `root` or a
14
+ selected layer), `selection-or-named` (the subtree of `root` when you give one, else of the work
15
+ site's selection -- the user's selection in the editor -- else the whole document). A scope taken
16
+ from the selection is said in the reply's `notes`; `root: "*"` asks for the whole document. Under a
17
+ subtree scope every op the contract lists works, Global ones (`style.setRule`, `timeline.create`)
18
+ and project-file writes (`shader.create`, `shader.setSource`) included.
15
19
  Budget: `screenshots` counts static `scene_screenshot`s, `video_frames` each sampled time of a
16
- timeline screenshot; going over is refused. Setting a scenario resets both.
20
+ timeline screenshot; going over is refused. Setting a scenario resets both. The numbers are the
21
+ contract's `budget`; a project that needs more (a long animation) raises them in its own
22
+ `contracts/scenarios/<name>.yaml` (a copy of the product's file with a larger `budget`) -- ask
23
+ the user, do not write it on your own. To look at many moments of a long animation without
24
+ spending the budget, use `xtframe-view <ui> --headless --renderer wgpu --advance <seconds>
25
+ --frames 1 --screenshot out.png` (`service.md`).
17
26
  Model (`model.minCaps`, optional): what the editor's built-in agent needs from its model --
18
27
  `tools`, `vision` or both; the AI panel and `xtframe-editor --service --agent` refuse to start a
19
28
  scenario whose model lacks one. Tokens (`budget.tokens`, optional, 1 to 5,000,000): the built-in
@@ -71,7 +80,8 @@ wrote is still `draft` (manual: a human approves). Report: `entries_added`, `ent
71
80
  `layer.*`, `style.*`, `timeline.*`, `animate.*`, `animation.*`, `trigger.set`, `bind.set`,
72
81
  `port.set`, `wire.port`, `symbol.*`, `state.*`, `asset.import`, `asset.replace`, `asset.slice`,
73
82
  `asset.sync`, `layout.anchor`, `restyle`, `fx.apply`, `doc.setSource`, `doc.save`,
74
- `export.lottie`, `undo`, `redo`, `flow.set`; forbidden: `asset.setStatus`, `symbol.detach`. Done:
83
+ `export.lottie`, `undo`, `redo`, `flow.set`, `catalog.add`, `catalog.list`, `diagnostics.*`, `shader.*`
84
+ (`timeline.removeTrack` is one of `timeline.*`); forbidden: `asset.setStatus`, `symbol.detach`. Done:
75
85
  no lint error; `motion.safeArea`, `motion.fontSize` and `lint.literalColor` clean (token usage >=
76
86
  90%); the content fits the viewport; nothing off screen.
77
87
 
@@ -80,12 +90,13 @@ no lint error; `motion.safeArea`, `motion.fontSize` and `lint.literalColor` clea
80
90
  `layer.setProps`, `layer.setAttrs`, `layer.setFlags`, `layout.anchor`, `style.*` (token
81
91
  replacement, selector renames, moving or deleting imported rules), `restyle`, `state.*`,
82
92
  `symbol.create`, `symbol.override`, `trigger.set`, `timeline.create`, `timeline.rename`,
83
- `animate.*`, `asset.replace`, `doc.save`, `undo`, `redo`; forbidden: `layer.delete`,
93
+ `animate.*`, `asset.replace`, `doc.save`, `undo`, `redo`, `repair.dedup`, `repair.effectBase`,
94
+ `repair.passthrough`, `diagnostics.fix`, `diagnostics.accept`; forbidden: `layer.delete`,
84
95
  `symbol.detach`, `asset.setStatus`. Done: no lint error; `tags.unconverted` and `tags.unknown`
85
96
  clean; every import-report warning handled or marked (manual).
86
97
 
87
98
  **restyle** -- allowed: `style.*` (the style stack ops included), `restyle`, `fx.apply`,
88
- `layer.setProps`, `doc.save`, `undo`, `redo`; forbidden: `layer.create`, `layer.delete`,
99
+ `layer.setProps`, `catalog.add`, `catalog.list`, `doc.save`, `undo`, `redo`; forbidden: `layer.create`, `layer.delete`,
89
100
  `layer.move`, `layer.rename`, `symbol.*`. Done: no lint error; text contrast at least 4.5:1
90
101
  (manual).
91
102
 
@@ -93,10 +104,11 @@ clean; every import-report warning handled or marked (manual).
93
104
  `layer.*`, `timeline.*`, `animate.*`, `animation.*`, `trigger.set`, `bind.set`, `port.set`,
94
105
  `wire.port`, `state.*`, `symbol.create`, `symbol.instantiate`, `symbol.override`, the style
95
106
  stack (`style.styles`, `style.addStyle`, `style.removeStyle`, `style.setStyleParams`,
96
- `style.copyStyles`, `style.pasteStyles`), `fx.apply`, `layout.anchor`, `doc.save`, `undo`, `redo`;
97
- forbidden: `symbol.detach`, `style.setToken`, `restyle` (a token change is not one element). The
98
- `subtree` scope still refuses whole-document operations (`timeline.rename`, `style.setRule` ...).
99
- Done: no lint error; no text overflows.
107
+ `style.copyStyles`, `style.pasteStyles`), `fx.apply`, `catalog.add`, `catalog.list`,
108
+ `layout.anchor`, `doc.save`, `undo`, `redo`; forbidden: `symbol.detach`, `style.setToken`,
109
+ `restyle` (a token change is not one element). Under its `subtree` scope the listed whole-document
110
+ operations work too (`timeline.create`, `timeline.rename` ...); one it does not list
111
+ (`style.setRule`) is refused. Done: no lint error; no text overflows.
100
112
 
101
113
  **add-animation** -- allowed: `vector.*`, `bone.*`, `constraint.*`, `skin.*`, `mesh.*`, `cel.*`,
102
114
  `animate.*`, `animation.*` (`animation.preset`, `animation.followPath`), `timeline.*`,
@@ -111,13 +123,32 @@ instance's variant: `{"variant:<prop>": value}`), `timeline.*`, `animate.emphasi
111
123
  and `lint.triggerTimeline` clean; every hover has a matching leave (manual).
112
124
 
113
125
  **effects** -- allowed: `fx.*`, `layer.setProps`, `layer.addAdjustment`, `layer.removeAdjustment`,
114
- `style.*`, `timeline.*`, `doc.save`, `undo`, `redo`;
126
+ `style.*`, `timeline.*`, `catalog.add`, `catalog.list`, `layer.setAttrs` (the numbers of a
127
+ `<particles>` layer are its attributes), `doc.save`, `undo`, `redo`;
115
128
  forbidden: `layer.create`, `layer.delete`. Done: effect layers within budget;
116
129
  `motion.effectLayers` and `motion.backdropBlur` clean.
117
130
 
118
- **shader** -- allowed: `fx.apply`, `layer.setProps`, `doc.save`, `undo`, `redo` (there is no
119
- `shader.*` operation); forbidden: `layer.create`, `layer.delete`. Done: the document compiles; a
120
- shader compile error was retried at most once (manual).
131
+ **shader** -- allowed: `shader.*` (`shader.list`, `shader.get`, `shader.create`, `shader.setSource`:
132
+ the `.xtfx` file itself, see ops.md "Custom shaders"; allowed under a subtree scope too), `fx.apply`,
133
+ `layer.setProps`, `catalog.add` (apply it: `catalog.add {id: "custom", file: "<name>", layer}`),
134
+ `doc.save`, `undo`, `redo`; forbidden: `layer.create`,
135
+ `layer.delete`. A source the parser refuses comes back with `errors: [{line, column, message}]`.
136
+ Done: the document compiles; a shader compile error was retried at most once (manual).
137
+
138
+ *Custom shader inputs (`XtInput`, `.xtfx`)* -- `i.uv` is screen space: 0..1 across the effect's
139
+ off-screen window (the content's on-screen bounding box plus `expand`, clipped to the viewport),
140
+ top-down. A transform on the layer or its parents does not move or turn it, and a full-screen layer
141
+ that slides leaves it where it was: use it for full-screen post effects (vignette, grain, colour
142
+ fringing). `i.local` follows the layer: 0..1 across the layer's own border box (top-left 0,0),
143
+ through the layer's and its parents' transforms, so it moves, scales and rotates with the layer;
144
+ in the `expand` margin outside the box it is below 0 or above 1. `i.boxSize` is the border box size
145
+ in CSS px (no dpr). Effects that stick to the content (a light beam, a glow, scan lines lined up
146
+ with it) use `local`. A `vec2` parameter is a plain pair of numbers: compare it with `uv` or with
147
+ `local`, whichever the shader means. `i.texelSize` / `i.layerSize` describe the window in device
148
+ pixels. `local` and `boxSize` are 0 on a vector or scene layer (no border box) and on a host whose
149
+ shader wrapper predates them. The software renderer never runs a shader -- it applies the
150
+ `fallback:` -- so look at a shader with `xtframe-view --headless --renderer wgpu`, not the default
151
+ software render.
121
152
 
122
153
  **data-binding** -- allowed: `port.*`, `bind.*`, `wire.port`, `trigger.set`, `doc.save`, `undo`,
123
154
  `redo`, `flow.set`; forbidden: `layer.delete`. Done: `lint.portUnbound` clean; no lint error.