@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.
- package/package.json +1 -1
- package/payload/plugins/xtframe/.claude-plugin/plugin.json +1 -1
- package/payload/plugins/xtframe/.codex-plugin/plugin.json +1 -1
- package/payload/plugins/xtframe/gemini-extension.json +1 -1
- package/payload/plugins/xtframe/skills/xtui/SKILL.md +28 -1
- package/payload/plugins/xtframe/skills/xtui/references/canvas.md +8 -5
- package/payload/plugins/xtframe/skills/xtui/references/dialect.md +84 -9
- package/payload/plugins/xtframe/skills/xtui/references/flow.md +2 -1
- package/payload/plugins/xtframe/skills/xtui/references/from-procedural.md +140 -0
- package/payload/plugins/xtframe/skills/xtui/references/performance.md +20 -0
- package/payload/plugins/xtframe/skills/xtui/references/style-groups.md +26 -0
- package/payload/plugins/xtframe/skills/xtui/references/tokens.json +60 -1
- package/payload/plugins/xtframe/skills/xtui/references/ui-project.md +9 -0
- package/payload/plugins/xtframe/skills/xtui/references/upgrade.md +3 -2
- package/payload/plugins/xtframe/skills/xtui/references/vector.md +5 -1
- package/payload/plugins/xtframe/skills/xtui/references/verify.md +29 -7
- package/payload/plugins/xtframe/skills/xtui-editor/SKILL.md +14 -4
- package/payload/plugins/xtframe/skills/xtui-editor/references/ops.md +161 -22
- package/payload/plugins/xtframe/skills/xtui-editor/references/scenarios.md +45 -14
- package/payload/plugins/xtframe/skills/xtui-editor/references/service.md +9 -1
|
@@ -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
|
|
139
|
-
|
|
140
|
-
the
|
|
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)`),
|
|
147
|
-
|
|
148
|
-
|
|
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
|
|
132
|
-
copy, tokens kept, one undo step) and run it only on their word -- never automatically
|
|
133
|
-
|
|
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
|
|
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-
|
|
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
|
|
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
|
|
145
|
-
as it was. Read the message, fix the value and call again.
|
|
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
|
|
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
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
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). `
|
|
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"
|
|
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`.
|
|
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
|
|
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
|
|
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
|
|
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`, `
|
|
97
|
-
forbidden: `symbol.detach`, `style.setToken`,
|
|
98
|
-
`
|
|
99
|
-
|
|
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.*`, `
|
|
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: `
|
|
119
|
-
`
|
|
120
|
-
|
|
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.
|