@xtframe/skills 0.0.0-stage → 0.19.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +22 -2
- package/package.json +41 -4
- package/payload/plugins/xtframe/.claude-plugin/plugin.json +17 -0
- package/payload/plugins/xtframe/.codex-plugin/plugin.json +11 -0
- package/payload/plugins/xtframe/gemini-extension.json +5 -0
- package/payload/plugins/xtframe/skills/xtui/SKILL.md +245 -0
- package/payload/plugins/xtframe/skills/xtui/references/canvas.md +93 -0
- package/payload/plugins/xtframe/skills/xtui/references/dialect.md +874 -0
- package/payload/plugins/xtframe/skills/xtui/references/flow.md +339 -0
- package/payload/plugins/xtframe/skills/xtui/references/from-procedural.md +140 -0
- package/payload/plugins/xtframe/skills/xtui/references/not-like-web.md +358 -0
- package/payload/plugins/xtframe/skills/xtui/references/performance.md +182 -0
- package/payload/plugins/xtframe/skills/xtui/references/responsive.md +137 -0
- package/payload/plugins/xtframe/skills/xtui/references/style-groups.md +404 -0
- package/payload/plugins/xtframe/skills/xtui/references/template.dc.html +56 -0
- package/payload/plugins/xtframe/skills/xtui/references/tokens.json +101 -0
- package/payload/plugins/xtframe/skills/xtui/references/ui-project.md +170 -0
- package/payload/plugins/xtframe/skills/xtui/references/upgrade.md +141 -0
- package/payload/plugins/xtframe/skills/xtui/references/vector.md +223 -0
- package/payload/plugins/xtframe/skills/xtui/references/verify.md +349 -0
- package/payload/plugins/xtframe/skills/xtui-editor/SKILL.md +219 -0
- package/payload/plugins/xtframe/skills/xtui-editor/references/design.md +158 -0
- package/payload/plugins/xtframe/skills/xtui-editor/references/ops.md +988 -0
- package/payload/plugins/xtframe/skills/xtui-editor/references/recipes.md +70 -0
- package/payload/plugins/xtframe/skills/xtui-editor/references/scenarios.md +211 -0
- package/payload/plugins/xtframe/skills/xtui-editor/references/service.md +175 -0
- package/src/agents.mjs +73 -0
- package/src/bin.mjs +4 -0
- package/src/cli.mjs +286 -0
- package/src/converter.mjs +73 -0
- package/src/fsutil.mjs +76 -0
- package/src/install.mjs +154 -0
- package/src/packs.mjs +150 -0
- package/src/plugins.mjs +109 -0
- package/src/proc.mjs +66 -0
- package/src/tar.mjs +103 -0
|
@@ -0,0 +1,988 @@
|
|
|
1
|
+
Read this when you are about to call Editor Service operations: which operation does what, grouped by kind, and the short sequences most changes are made of.
|
|
2
|
+
|
|
3
|
+
# Editor Service operations
|
|
4
|
+
|
|
5
|
+
200 operations (all listed by name at the end). The exact arguments of each are its JSON schema:
|
|
6
|
+
`<xtframe>/schemas/editor-service/<op>.json` (`index.json` lists them all, with the MCP
|
|
7
|
+
annotations), or `service_ops` at runtime. Over MCP the tool name is the operation with `_` for
|
|
8
|
+
`.` (`layer.setProps` -> `layer_setProps`). A layer is named by its path: its id, or
|
|
9
|
+
`<Symbol>/<id>` inside a symbol definition; an instance's inner layer is changed with
|
|
10
|
+
`symbol.override`, not with `layer.*`; the document's `<body>` is the path `body`. Every argument
|
|
11
|
+
list takes an optional `doc` (default: **your** active document -- each client has its own, see
|
|
12
|
+
`doc.open`).
|
|
13
|
+
|
|
14
|
+
**Handshake -- call `initialize` first.** It returns `{version, format: {xtui, ir}, behavior, ops,
|
|
15
|
+
deprecated}`: the editor's product version, the `.xtui` and IR format versions it writes
|
|
16
|
+
(`ir` as `"2.<minor>"`), the newest behavior version (`spec.behavior`), the names of the operations
|
|
17
|
+
this editor has, and `deprecated: [{op, replacedBy}]`. Use only names from `ops`; an operation this
|
|
18
|
+
list does not name is not there in that editor (older build) -- say so instead of guessing. Over
|
|
19
|
+
MCP the same object is in the `initialize` result's `_meta["xtframe/handshake"]`, and the tool list
|
|
20
|
+
marks an old name `[Deprecated -> <new tool>]`. An old name still works for at least one product
|
|
21
|
+
MINOR (it runs the new operation, and the reply carries `deprecated: {op, replacedBy, message}`),
|
|
22
|
+
but always call the `replacedBy` name.
|
|
23
|
+
|
|
24
|
+
**Revisions -- send `ifRevision` on every write.** Every reply names the `revision` of the document
|
|
25
|
+
the call resolved (an integer that grows with each change, by anyone: the user at the editor,
|
|
26
|
+
another agent, the disk). Every write that works on a document -- every operation whose schema has
|
|
27
|
+
`ifRevision` (`layer.*`, `style.*` except the reads, `timeline.*`, `trigger.set`, `bind.set`,
|
|
28
|
+
`port.set`, `state.*`, `symbol.*`, `vector.*`, the rig and cel operations, the intent operations,
|
|
29
|
+
`flow.set`, `doc.setSource`, `doc.save`, `undo`, `redo`, ...) -- **always** carries `ifRevision`:
|
|
30
|
+
the `revision` of your latest reply for that document. The user may be editing the same UI at any
|
|
31
|
+
moment, so there is no "short work item" exception. When the document has moved on, the call fails
|
|
32
|
+
with `kConflict` ("document '<doc>' is at revision N (expected M)") and changes nothing. Then:
|
|
33
|
+
|
|
34
|
+
1. read again: `doc.changes {since: <your revision>}` (what the others did), and `layer.get` /
|
|
35
|
+
`style.getRules` / `timeline.get` for what you are about to change;
|
|
36
|
+
2. decide whether your write still makes sense on top of that, and send it **once** more with the
|
|
37
|
+
new `revision`;
|
|
38
|
+
3. a second `kConflict` on the same write: stop and tell the user (someone is working on the same
|
|
39
|
+
thing right now); do not loop.
|
|
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
|
+
|
|
61
|
+
T-366: when another seat changed the document's files on disk while it had unsaved edits
|
|
62
|
+
(`doc.status` `diskNewer`), a write with `ifRevision` fails with `kConflict` too, and so does
|
|
63
|
+
`doc.save` (with or without it): `doc.reload`, or `doc.save {force: true}` after asking the human.
|
|
64
|
+
Operations that write project files rather than a document (`design.*`, `project.*`,
|
|
65
|
+
`conventions.put`, `asset.import` / `slice` / `linkFolder` / `sync`, `history.*`) take no
|
|
66
|
+
`ifRevision`.
|
|
67
|
+
|
|
68
|
+
**Attributes vs style properties.** Two different writes, each refusing the other's names:
|
|
69
|
+
`layer.setAttrs {layer, attrs}` writes attributes -- `editor-only`, `class`, `data-*`, `aria-*`,
|
|
70
|
+
`src`, `href`, `ui-scale`, `media-override`, `variant:<prop>` (an instance's variant); `null`
|
|
71
|
+
removes one. `layer.setProps {layer, props, state?}` writes style properties into the layer's
|
|
72
|
+
`#id` rule (or its state rule) and refuses an attribute name as `unknown property`. `id` is
|
|
73
|
+
`layer.rename`; `on:*`, `bind:*`, `port:*` are `trigger.set`, `bind.set`, `port.set` (refused by
|
|
74
|
+
`layer.setAttrs` and `layer.create {attrs}` alike). Rules for classes, states and `@media` are
|
|
75
|
+
`style.setRule`.
|
|
76
|
+
|
|
77
|
+
## Read (never change anything)
|
|
78
|
+
|
|
79
|
+
| Operation | Returns |
|
|
80
|
+
|---|---|
|
|
81
|
+
| `project.get {section?, path?}` | the UI Project: `summary` (with `path` = the project file `<name>.xtui`, `dir`, `legacyFile` when it was read from an old `ui-project.json` / `bundle.xtproj`, `unnamed` for a lone `.xt`, `publish` targets), `spec`, `tokens`, `conventions`, `symbols`, `contracts`, `motionSpec`, `references`, `agents` (AGENTS.md), `assets`, `design` (the design document, as `design.get`) |
|
|
82
|
+
| `project.search {query, limit?}` | matching references and conventions |
|
|
83
|
+
| `doc.list` | `open` documents (`name`, `modified`), the shown one (`active`), the project's `uis`, your `seat` and `activeDoc`, and every connected seat (`seats: [{client, seat, kind, activeDoc}]`) |
|
|
84
|
+
| `session.getView` | the work site (37.8.2), what the user (or the seat before you) is looking at: `selection` (layer paths, primary first), `vector` (`{svg}` in the vector editing mode, else null), `editInPlace` (the instance being edited in place, "" = none), `space` (Canvas, Code, Flow, Project, Demo), `animate`, `timeline {scope, name, playhead, loop {start, end}, onion {before, after, mode}}`, `device`, `zoom`, `fit`, `pan`, `safeArea`; `host` is `gui` (the editor's screen) or `headless` (selection, space, animate and Edit in Place kept per seat). **Call it before taking over** someone's work |
|
|
85
|
+
| `doc.status` | `{doc, revision, modified, path, diskNewer, lastDiskChange}`: `diskNewer` is true when its files changed on disk (another editor, `xtframe-import`, a direct write) while it had unsaved edits |
|
|
86
|
+
| `doc.changes {since, seat?}` | T-367 (37.8.3): every undo step of the document after revision `since`, by any seat, oldest first: `{changes: [{revision, seat, kind, name, layers, time}], truncated}`. `kind` is `command` (the user's own edit in a panel, `name` = the step's label; the user's undo / redo show as `Undo <label>` / `Redo <label>`) or `op` (a service call, `name` = the op). `layers` is what the step touched (layer paths; selectors, `--token` names and `flow` for those ops; for the user's steps the layers selected at the time). At most 500 rows -- `truncated: true` means ask again with `since` = the last row's revision; kept in memory since the editor started. **Read it before taking over**: "what did the user do since revision N" |
|
|
87
|
+
| `doc.source {file?}` | the source text as it would be saved now, nothing written: the `.xt` (default), or one stylesheet (`file` as `style.getRules` names it); `{file, text}`. In source format 2 (`<xt version="2">`, Docs/design/54) the `.xt` text holds the sections `<ports>`, `<body>`, `<layout>` (geometry), inline `<style>` and `<timelines>`, and an imported UI's own `.xts` is its appearance `<style src>`; on such a document `file` may also name a section -- `ports`, `body`, `layout`, `style` or `timelines` -- and the reply is the first section of that kind as written in the `.xt` (`doc.source {file: "layout"}`) |
|
|
88
|
+
| `layer.list {root?}`, `layer.get {layer}` | the layer tree; one layer's attributes, rules, computed box and editor `flags` (`{hidden, locked, solo, color, collapsed}`, see `layer.setFlags`) |
|
|
89
|
+
| `style.getTokens` | tokens and themes in effect |
|
|
90
|
+
| `style.getRules {file?, selector?}` | the stylesheet rules (inline, linked and shared `.xts`): `rules: [{file, index, selector, declarations, line, media}]`; `media` is `""` for a top-level rule and the query for a rule inside `@media` (its `index` is then null); `layer.get` gives only a layer's own rules, this gives class, shared and `@media` rules too |
|
|
91
|
+
| `flow.get` | the flow graph (`.xtflow`): `{path, graph: {nodes, edges, groups?}, problems}`, `problems` = edges whose element endpoint names no layer |
|
|
92
|
+
| `project.importReport {ui}` | the `import-report.json` of a UI of the project: `{ui, path, report}` |
|
|
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 |
|
|
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) |
|
|
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 |
|
|
96
|
+
| `symbol.list`, `state.list {layer}` | symbols with their contracts; a layer's states |
|
|
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`) |
|
|
98
|
+
| `symbols.library {library?}` | one library (or all): its groups with `source {kind, set, setVersion}`, `lint {errors, warnings}` (the persisted mark), `problems` (broken files) and each symbol in summary (`name`, `file`, `category`, `requires {states, slots}`, `ports`, `timelines`, `thumbnail`). **Call it first** when symbols come up |
|
|
99
|
+
| `symbols.get {name, group?, library?}` | one symbol's full index entry (`requires`, `ports [{name, type, dir}]`, `timelines`, `tokens [{name, default}]`, `fonts`, `textures`, `content` hash) plus where it was found (`library`, `group`, `path`); the first mounted library with the name wins |
|
|
100
|
+
| `symbols.lint {group?, library?, path?}` | the symbol lint (49.6): a group, a library, every mounted library, or -- `path` -- a `.xtsymbols` archive / set directory read **without importing** (its `set {author, license, fontsLicense, version, ...}` comes back too): `{groups: [{id, dir, symbols, errors, warnings, issues: [{level, symbol, code, message}]}], errors, warnings, set?}`. Run it on a set before `symbols.import` and show the user licence and findings |
|
|
101
|
+
| `asset.list {status?}` | the asset manifest (`draft`, `approved`, `stale`, `pending`) |
|
|
102
|
+
| `service.ops` | the operation list with schemas |
|
|
103
|
+
| `initialize` | the handshake (above): `{version, format: {xtui, ir}, behavior, ops, deprecated}` |
|
|
104
|
+
| `design.get {section?, id?, resolve?, forAi?}`, `design.search {query?, kinds?, tags?, color?, limit?}`, `design.list {kind, status?, group?}`, `design.usage {id}`, `design.audit {scope?}`, `design.extractPalette {ref, count?}`, `design.deriveScale {swatch? \| value?, steps?, method?}`, `design.contrast {fg, bg}`, `design.lint`, `design.diff {from, to?}` | the design system (`design/`, see `design.md`): the document or one entry (a `ref:` entry with its file as base64), search (text, kinds, tags, nearest colours), lists, usage and impact, the audit of literal values, colour tools, the design lint, a semantic diff |
|
|
105
|
+
|
|
106
|
+
## Write (one undo step each)
|
|
107
|
+
|
|
108
|
+
| Kind | Operations |
|
|
109
|
+
|---|---|
|
|
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 |
|
|
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`) |
|
|
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 |
|
|
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 |
|
|
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`) |
|
|
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) |
|
|
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) |
|
|
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) |
|
|
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`) |
|
|
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 |
|
|
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 |
|
|
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 |
|
|
126
|
+
|
|
127
|
+
**Editor-only reference layers.** A layer that only helps while designing (a reference image,
|
|
128
|
+
a guide) carries the `editor-only` attribute: the editor shows it, a publish drops it.
|
|
129
|
+
|
|
130
|
+
```
|
|
131
|
+
layer_setAttrs {"layer": "RefShot", "attrs": {"editor-only": ""}} null removes it again
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
**Locked layers (26.1.4).** `layer.setFlags {layer, hidden?, locked?, solo?, color?, collapsed?, adjustHidden?}`
|
|
135
|
+
writes the editor's sidecar (`<ui>.xteditor.json`): `color` is a tag 0-7 (null clears it);
|
|
136
|
+
`adjustHidden` is the eye of a group's adjustment layer (46 §46.7: the preview draws the group
|
|
137
|
+
without its composite styles -- opacity, blend, clip, effects; the file and a publish keep them). It is
|
|
138
|
+
not a document edit -- no undo step, no new `revision` -- but it counts as a write of your work
|
|
139
|
+
item (`touched`). A layer the user locked, or any layer inside it, refuses every write
|
|
140
|
+
(`layer.setProps`, `layer.setAttrs`, `layer.create` under it, ...) with `kForbidden`: "layer
|
|
141
|
+
'<id>' is locked: layer.setFlags {layer, locked:false} first". Unlock only when the user asked
|
|
142
|
+
for the change on that layer, and say so in the report; `layer.setFlags` itself is never refused
|
|
143
|
+
by a lock. `layer.get` returns the flags.
|
|
144
|
+
|
|
145
|
+
`layer.setProps` writes the layer's own `#id` rule (or, with `state`, its `:hover`/`:state()`
|
|
146
|
+
rule). While the work site's `animate` is on (the user's Animate switch, or yours through
|
|
147
|
+
`session.setView`), it records like the user's edits do: each animatable property (normal state)
|
|
148
|
+
becomes a keyframe at the playhead in the active timeline (none selected in the current scope:
|
|
149
|
+
`root-anim` / `<symbol>-anim`, created at 2 s), the rest is written as usual, one undo step;
|
|
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
|
|
159
|
+
token (`var(--x)`) over a literal colour: the lint reports literals. `style.setRule` takes the
|
|
160
|
+
same values for class and state selectors (`.card`, `.card:hover`).
|
|
161
|
+
|
|
162
|
+
The 3D panel's "World layer" switch is the style property `world-layer` (`off` | `on`): set it
|
|
163
|
+
with `layer.setProps {layer, props: {"world-layer": "on"}}` and remove it with `null` (what
|
|
164
|
+
unchecking does). It only matters on a host that shows the UI in layers (the layer and its subtree
|
|
165
|
+
become one layer of their own); every flat view ignores it. It is not animatable: never key it.
|
|
166
|
+
|
|
167
|
+
## `.xts` value rules
|
|
168
|
+
|
|
169
|
+
`layer.setProps`, `style.setRule` and `state.*` check what they write (T-355): an unknown
|
|
170
|
+
property name is refused (`unknown property '<name>'`, with a hint); a `url()` must name an
|
|
171
|
+
existing file; a value the compiler rejects, or newly warns about for that property, is rolled
|
|
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
|
|
179
|
+
know (only `min-`/`max-width`/`-height`, `aspect-ratio >=`/`<=`, `orientation`, `resolution`,
|
|
180
|
+
`platform`, `input` and `prefers-reduced-motion`; `aspect-ratio` takes `<=` / `>=`, not a colon:
|
|
181
|
+
`(aspect-ratio <= 4/3)`) is rolled back the same way, the message naming the query. So:
|
|
182
|
+
|
|
183
|
+
- **Names** (layer ids, symbol, timeline and state names): `[A-Za-z][A-Za-z0-9_-]*`, starting with
|
|
184
|
+
a letter, not ending in `-`.
|
|
185
|
+
- **Images**: `background-image: url("../shared/img/x.png")` -- the URL **in quotes** (an unquoted
|
|
186
|
+
one containing `/` fails) and relative to the `.xt` file, not to the project.
|
|
187
|
+
- **Effects**: XTFrame has no `filter` or `text-shadow` in `.xts`. Write `effect:` (box level:
|
|
188
|
+
`effect: shadow(0 4px 12px #00000040) blur(4px)`, `backdrop-blur(...)`, `outline(...)`) and
|
|
189
|
+
`text-effect:` (glyph level: `text-effect: outline 2px #000, shadow 1px 2px 3px #f00`,
|
|
190
|
+
`glow 4px #ffd000`). The importer converts the CSS forms; the editor does not.
|
|
191
|
+
- **Show / hide from data**: any non-shorthand property can be a binding target, so a flag shows or
|
|
192
|
+
hides a layer with `bind.set {layer, target: "display", expr: "flag | select(true: block, false:
|
|
193
|
+
none)"}` (written `bind:display="flag | select(true: block, false: none)"`), not only through
|
|
194
|
+
`visibility`.
|
|
195
|
+
|
|
196
|
+
## Style stack (`style.*Style*`, 46 §46.8)
|
|
197
|
+
|
|
198
|
+
The Properties panel shows an element as a stack of units: position & size (fixed), the styles
|
|
199
|
+
(groups of CSS properties: `autolayout`, `fill`, `stroke`, `corner`, `image`, `text`, `outline`,
|
|
200
|
+
`vector`, `particles`, `interaction`, `responsive`, `opacity`, `clip`, `clip-media`, `space3d`),
|
|
201
|
+
the effect sequence and the modifiers. Nothing is stored: a style is present when the element's
|
|
202
|
+
effective declarations name one of its properties. The resource `xtui://style-groups.json` lists
|
|
203
|
+
every group's CSS properties, parameter names and defaults. Talk to the user in style names; the
|
|
204
|
+
file still holds CSS.
|
|
205
|
+
|
|
206
|
+
| Operation | Does |
|
|
207
|
+
|---|---|
|
|
208
|
+
| `style.styles {target, state?}` | the units of a layer in panel order, each `{kind, group, name, scope, params: [{name, css, value, source, selector?, binding?, state?}]}` (`source`: own / rule / binding / none; `effect` on the effect unit, `modifiers` on the modifier unit) |
|
|
209
|
+
| `style.addStyle {target \| targets, group, state?}` | writes the group's default declarations into each layer's own rule (a token of the matching meaning when the UI has one, e.g. `var(--border)`), one undo step; groups without defaults (`placement`, `effects`, `modifiers`, ...) are refused |
|
|
210
|
+
| `style.removeStyle {target \| targets, group, state?}` | deletes the group's properties from each own rule (the reply lists `removed`); a style a class rule provides stays (`kNotFound`: edit that rule with `style.setRule`, or override) |
|
|
211
|
+
| `style.setStyleParams {target, group, params, state?}` | parameter name -> value (`{"width": "2px"}` for `stroke`), written as `layer.setProps` writes the CSS property (Animate records keyframes the same way) |
|
|
212
|
+
| `style.copyStyles {targets, groups?, kinds?, state?}` | the clipboard JSON `{"xtframe": "styles", "v": 1, "items": [...]}` of the first layer: one `style` item per style (its effective declarations), the `effect` item, one `modifier` item per modifier; never position & size |
|
|
213
|
+
| `style.pasteStyles {targets, payload, mode?, state?}` | pastes that JSON: `merge` (default) writes every style, replaces the effect sequence and appends modifiers to vector groups (others: skipped, see `notes`); `paramsOnly` only overwrites styles a layer already shows. One undo step |
|
|
214
|
+
| `layer.addAdjustment {target, group?}` | on a group layer (group, stack, 3D group, vector group): adds a composite style (`opacity`, default, or `clip`) -- the adjustment layer of the layers panel |
|
|
215
|
+
| `layer.removeAdjustment {target}` | removes every composite style and the effect sequence from a group layer's own rule |
|
|
216
|
+
|
|
217
|
+
Parameter names are the group's, not the CSS names (`width` of `stroke` is `border-width`; the
|
|
218
|
+
`xtui` skill's `references/style-groups.md` and the resource list them all). Minimal calls:
|
|
219
|
+
|
|
220
|
+
```
|
|
221
|
+
style_styles {"target": "Health_Bar"} -> units: placement, fill, stroke, ...
|
|
222
|
+
style_addStyle {"targets": ["Btn_1", "Btn_2"], "group": "stroke"}
|
|
223
|
+
style_removeStyle {"target": "Btn_1", "group": "corner"}
|
|
224
|
+
style_setStyleParams {"target": "Btn_1", "group": "stroke", "params": {"width": "2px", "color": "var(--border)"}}
|
|
225
|
+
style_setStyleParams {"target": "Btn_1", "group": "opacity", "params": {"opacity": "0.8", "mixBlendMode": "screen"}}
|
|
226
|
+
style_copyStyles {"targets": ["Btn_1"], "groups": ["stroke"]} -> payload (the JSON below)
|
|
227
|
+
layer_addAdjustment {"target": "Group_3", "group": "opacity"}
|
|
228
|
+
layer_removeAdjustment {"target": "Group_3"}
|
|
229
|
+
layer_setFlags {"layer": "Group_3", "adjustHidden": true} preview without the adjustment
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
`style.pasteStyles` takes the clipboard JSON of the stack panel (46 §46.6) as an object or as its
|
|
233
|
+
text; `mode: "paramsOnly"` is the panel's Alt+Ctrl+V:
|
|
234
|
+
|
|
235
|
+
```
|
|
236
|
+
style_pasteStyles {"targets": ["Btn_2", "Btn_3"], "mode": "merge", "payload":
|
|
237
|
+
{ "xtframe": "styles", "v": 1,
|
|
238
|
+
"items": [
|
|
239
|
+
{ "kind": "style", "group": "stroke", "decls": { "border-width": "2px", "border-color": "var(--border)" } },
|
|
240
|
+
{ "kind": "effect", "effect": "shadow(0 4px 12px #00000040) glow(6px var(--accent))" },
|
|
241
|
+
{ "kind": "modifier", "xml": "<xt-round radius=\"6\"/>" } ] }}
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
Inside an item the declarations are CSS (`decls`), as copied; a `modifier` item lands only on a
|
|
245
|
+
vector group (others: skipped, see `notes`). There is no operation to reorder styles: the order of
|
|
246
|
+
the styles section is fixed by the group table.
|
|
247
|
+
|
|
248
|
+
## Symbol libraries (`symbols.*`, 49 §49.7)
|
|
249
|
+
|
|
250
|
+
A **library** is a directory of **groups** (`library.json`, `groups/<id>/` with `group.json`,
|
|
251
|
+
`index.json`, the `.xt` files, `tokens.xts`, theme files, `fonts/`, `textures/`, `thumbnails/`); the
|
|
252
|
+
editor mounts the presets (read-only, id `preset`, default group `broadsheet-2026`), the user's own
|
|
253
|
+
library (`mine`), the extra libraries of the user's mount list and the open project's
|
|
254
|
+
`shared/symbol-library/`. A group travels as a **set** (`.xtsymbols`, a stored zip of the same tree
|
|
255
|
+
plus `set.json` with author, version and licence). A project never links a library file: it holds
|
|
256
|
+
**copies** (49.3), made by the project writes below and recorded in `shared/symbols/index.json`.
|
|
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
|
+
|
|
268
|
+
- **Reads** (any scenario): `symbols.libraries`, `symbols.library {library?}`, `symbols.get {name,
|
|
269
|
+
group?, library?}`, `symbols.lint {group? | library? | path?}` -- the Read table above.
|
|
270
|
+
- **Project writes** (`create`, `restyle`, `repair-import`, `single-element`; one undo step of
|
|
271
|
+
`ReplaceSharedFile` steps on the active document's stack, so `undo` and a checkpoint rollback take
|
|
272
|
+
them back): `symbols.use {names, group?, library?}` copies each symbol's file to
|
|
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
|
|
281
|
+
textures to the asset root (same content skipped, other content under a hashed name, `renamed`),
|
|
282
|
+
appends the tokens it reads that `shared.tokens` lacks with the group's defaults (`tokensAdded`,
|
|
283
|
+
theme values to the theme files) and records the source; a name no library has fails the whole call
|
|
284
|
+
with `kNotFound` and nothing is written. `symbols.useGroup {group, library?}` is `use` for every
|
|
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).
|
|
322
|
+
- **Library writes** (the `library` scenario; `kPermissionDenied` until the user allows them):
|
|
323
|
+
`symbols.saveAsGroup {names, groupId, name, library?}` turns project symbols into a new group of a
|
|
324
|
+
writable library (tokens, fonts, textures, themes collected the reverse way; `{groupId, library,
|
|
325
|
+
lint}`); `symbols.loadPreset {group, keepOld?}` copies the installed preset group over the user
|
|
326
|
+
library's (the old one to `.trash/`, `trashed`; `keepOld` keeps it as `<id>@<version>`);
|
|
327
|
+
`symbols.import {path | url, library?, as?, replaceOlder?}` imports a set (`.xtsymbols` or a set
|
|
328
|
+
directory; a `url` must be `https://`, the editor downloads it -- 64 MB, 60 s -- and the reply has
|
|
329
|
+
`downloaded {bytes, sha256}`), every check before anything is written, per group `action` =
|
|
330
|
+
`added` | `updated` (old one in `.trash/`) | `unchanged` | `older-skipped` (`replaceOlder` replaces)
|
|
331
|
+
with its `lint`; `symbols.export {group, library?, out, author?, license?, fonts?}` writes a set
|
|
332
|
+
(`out` ending in `.xtsymbols` is the archive, else a set directory); `symbols.mountLibrary {path}` /
|
|
333
|
+
`symbols.unmountLibrary {id}` change the user's mount list (the presets, `mine` and the project
|
|
334
|
+
library cannot be unmounted). The default library of a write is the first writable one (`mine`).
|
|
335
|
+
- **Permission.** Libraries are shared by every project and permanent, so the library writes answer
|
|
336
|
+
`kPermissionDenied` ("library writes need the \"Allow AI to change symbol libraries\" preference
|
|
337
|
+
or a one-time approval") for an AI client until the user allows them: the editor asks once per
|
|
338
|
+
client (allow this time / always / deny) when the first one is refused; only the user grants it,
|
|
339
|
+
never the client itself. Wait for the user; never write library files yourself.
|
|
340
|
+
- **Resources** (MCP): `xtframe://symbols/library` (= `symbols.library`),
|
|
341
|
+
`xtframe://symbols/<library>/<group>/<Name>` (= `symbols.get`).
|
|
342
|
+
|
|
343
|
+
**Build a HUD from a group**
|
|
344
|
+
|
|
345
|
+
```
|
|
346
|
+
symbols_libraries -> symbols_library {"library": "mine"} which groups, their lint state
|
|
347
|
+
session_setScenario {"name": "create"} -> checkpoint_begin {"scenario": "create"}
|
|
348
|
+
symbols_useGroup {"group": "broadsheet-2026"} copies, tokens, index.json; one undo step
|
|
349
|
+
symbol_instantiate {"symbol": "HealthBar", "parent": "Hud", "source": "project", "ifRevision": 41}
|
|
350
|
+
```
|
|
351
|
+
|
|
352
|
+
**Import a set the user handed you**
|
|
353
|
+
|
|
354
|
+
```
|
|
355
|
+
symbols_lint {"path": "C:/sets/neon.xtsymbols"} set {author, license, fontsLicense, version}, groups[].issues
|
|
356
|
+
-> show licence and findings, ask
|
|
357
|
+
session_setScenario {"name": "library"}
|
|
358
|
+
symbols_import {"path": "C:/sets/neon.xtsymbols"} (kPermissionDenied: the editor is asking the user; wait)
|
|
359
|
+
-> groups[].action, lint; then symbols_useGroup in a create scenario when the user wants it in the project
|
|
360
|
+
```
|
|
361
|
+
|
|
362
|
+
## Effect catalog (`catalog.*`, 46 §46.13)
|
|
363
|
+
|
|
364
|
+
The editor's **+ Add effect** button opens one catalog, in the artist's words: appearance (fill,
|
|
365
|
+
stroke, corners, focus ring, image fit), effects (drop shadow, glow, blur, frosted glass, shine,
|
|
366
|
+
color adjust, gradient fade, outline), compositing (clip shape, opacity & blend), text (text
|
|
367
|
+
effect, text reveal, decoration) and, on vector layers, the shape modifiers. Each entry adds a
|
|
368
|
+
**visible default**, so the change shows at once (a stroke contrasts with the fill; a glow uses the
|
|
369
|
+
`accent` token). The resource `xtui://effect-catalog.json` lists every entry (id, names en / zh,
|
|
370
|
+
one-line blurb, target, visible default); talk to the user in these names.
|
|
371
|
+
|
|
372
|
+
| Operation | Does |
|
|
373
|
+
|---|---|
|
|
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) |
|
|
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.
|
|
383
|
+
|
|
384
|
+
```
|
|
385
|
+
catalog_list {"target": "Btn_1"} -> entries with presence
|
|
386
|
+
catalog_add {"targets": ["Btn_1", "Btn_2"], "id": "shadow"}
|
|
387
|
+
catalog_add {"target": "Logo_Path", "id": "mod:xt-round"}
|
|
388
|
+
```
|
|
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
|
+
|
|
420
|
+
## Vector layers (`vector.*`, 31 §31.10)
|
|
421
|
+
|
|
422
|
+
An inline `<svg>` is a vector layer, and its shapes are addressed as `<svg id>/<shape id>`
|
|
423
|
+
(`Icon/Ring`).
|
|
424
|
+
|
|
425
|
+
- `vector.get {layer, normalize?}` returns `{svg: {id, viewBox, w, h}, shapes: [{id, kind, d?,
|
|
426
|
+
params?, fill, stroke, strokeWidth, fillRule, opacity, vertices?, contours?, appearance, width,
|
|
427
|
+
corners, modifiers, skin?}], skeletons}`; `appearance` is `{fillOpacity, strokeOpacity,
|
|
428
|
+
strokeLinecap, strokeLinejoin, strokeMiterlimit, strokeDasharray, strokeDashoffset, fillPaint,
|
|
429
|
+
strokePaint}` (a paint is `{mode: none|solid|linear|radial, color?, p0?, p1?, stops?: [{offset,
|
|
430
|
+
color}]}`, null when unset), `width` is `{taperStart, taperEnd, profile: [{t, w}]}`, `corners`
|
|
431
|
+
are the rounded corners `[{vertex, radius, corner}]` (`vertex` = flat index) and `modifiers` the
|
|
432
|
+
stack of the shape's group `[{id, kind, enabled, baked, params}]` (kind trim | repeat | round |
|
|
433
|
+
pucker | zigzag | twist | wiggle | offset | merge); `skin` (skinned shapes only) is `{skeleton, vertices, bones: [{bone, weight}]}` with
|
|
434
|
+
each bone's average weight, `skeletons` is `bone.list`'s tree.
|
|
435
|
+
`vertices` / `contours` hold `{p: [x, y], in, out, type}` with the handles relative to `p`, and
|
|
436
|
+
`type` is corner | smooth | symmetric | auto. `normalize: true` also expands the parametric
|
|
437
|
+
shapes (rect, circle, star...).
|
|
438
|
+
- `vector.set {layer, svg}` replaces the whole content with SVG text. It is the cheapest way to
|
|
439
|
+
draw. Unsupported elements come back in `skipped[]`.
|
|
440
|
+
- `vector.set {layer, shapes: [...]}` upserts shapes by id: `d` or `vertices`, `params`, `fill`,
|
|
441
|
+
`stroke`, `strokeWidth`. A `var(--x)` colour becomes the `.xts` rule `#Svg/Shape { fill:
|
|
442
|
+
var(--x); }`. It also takes back what `vector.get` returns (T-370): `appearance` (only the fields
|
|
443
|
+
given; a paint writes a gradient as the panel does), `width`, `corners: [{vertex, radius}]`
|
|
444
|
+
(radius 0 = sharp; a `<path>` only) and `modifiers` (replaces the stack of the shape's group:
|
|
445
|
+
listed ids keep their place, new ones are appended, unlisted ones go), so a look no longer needs
|
|
446
|
+
a whole-layer `svg` rewrite.
|
|
447
|
+
- `vector.editPath {shape, ops}` applies ops in order: `insert {seg, t}`, `delete {index}`,
|
|
448
|
+
`move {index, p, in?, out?}`, `setType {index, type}`, `close`, `open`, `reverse`,
|
|
449
|
+
`setFirst {index}`. Each op may name a `contour`.
|
|
450
|
+
- `vector.boolean {shapes, op}`: op is union | subtract (the first minus the rest) | intersect |
|
|
451
|
+
exclude | divide, and the shapes must be in one layer. The result keeps the topmost shape's id
|
|
452
|
+
and look.
|
|
453
|
+
- `vector.bake {layer, shape?}`: parametric shapes (or only `shape`) become `<path>`s.
|
|
454
|
+
- `vector.shapeOp {layer, shape?, op}` runs the editor's Object menu / node tool command (one undo
|
|
455
|
+
step): `outlineStroke`, `simplify {tolerance}`, `offset {distance, join?}`, `flatten`, `toPath`
|
|
456
|
+
(on `shape`, or every shape of the layer when omitted; the ones it does not apply to come back in
|
|
457
|
+
`skipped[]`), `flipH` / `flipV` (each shape about its own center), `merge {layers}` (other vector
|
|
458
|
+
layers move into `layer`), `split` (each top-level shape / group gets its own layer), `join
|
|
459
|
+
{points: two open end points}`, `break {point}`, `dissolve {points}` (points are `{contour?,
|
|
460
|
+
index}` as in `contours`; `d` keys of the same topology follow). The box is not refitted.
|
|
461
|
+
- `vector.textToOutlines {layer}` turns a text layer into a vector layer of glyph paths
|
|
462
|
+
(`<id>_g<n>`); `vector.extract {layer, path?}` writes the layer as a standard `.svg` (default
|
|
463
|
+
`shared/img/<id>.svg` of the project, registered in the asset manifest) and replaces it by an
|
|
464
|
+
`<img>`.
|
|
465
|
+
- `vector.morph {shape, action: setFirst, index}` moves the start vertex (keys follow);
|
|
466
|
+
`vector.morph {shape, action: equalize}` gives every `d` keyframe of the shape the same contours,
|
|
467
|
+
closed flags and vertex counts (longest segments split) and returns `{added, keys}`.
|
|
468
|
+
|
|
469
|
+
**Topology mismatch.** `vector.editPath` edits the shape and every `d` keyframe of that shape
|
|
470
|
+
(the `@timeline` track `d`) that has the same topology: the same contours, vertex counts and
|
|
471
|
+
closed flags. A `move` shifts each keyframe's vertex by the same delta. Keyframes with another
|
|
472
|
+
topology are left alone and listed in `skippedKeys: [{timeline, t}]`. Then either:
|
|
473
|
+
|
|
474
|
+
1. Run `vector.morph {shape, action: equalize}` (lint `vector.morphTopology` lists such tracks),
|
|
475
|
+
2. Rewrite those keys with `timeline.setKeyframe` so that every key has the same vertex count
|
|
476
|
+
(insert the matching vertices), or
|
|
477
|
+
3. Remove them and re-key from the edited shape.
|
|
478
|
+
|
|
479
|
+
Never leave a `d` track with mixed topologies: the morph snaps instead of interpolating.
|
|
480
|
+
|
|
481
|
+
## Rigs (`bone.*`, `constraint.*`, `skin.*`, `mesh.*`, 32 §32.5)
|
|
482
|
+
|
|
483
|
+
A skeleton (`<xt-skeleton>`) lives inside a vector layer; its bones bend the `<path>`s and
|
|
484
|
+
`<xt-mesh>`es skinned to it. Bones, constraints, shapes and meshes are addressed like shapes:
|
|
485
|
+
`<svg id>/<id>` (`Mascot/Head`) or a bare id that is unique in the document. Every edit is one
|
|
486
|
+
undo step. Coordinates are the `<svg>`'s group space unless said otherwise; angles are degrees,
|
|
487
|
+
positive turns clockwise (y down).
|
|
488
|
+
|
|
489
|
+
Pose vs rest (T-249): a bone's `rotate` / `translate` / `scale` / `length` are its **static pose**
|
|
490
|
+
(what it shows and starts at); `rest-rotate` / `rest-translate` / `rest-scale` / `rest-length` are
|
|
491
|
+
its **bind pose** (each defaults to the posed value). Shapes deform by pose x inverse(rest), so
|
|
492
|
+
posing a bound skeleton bends its shapes; binding writes the rest from the current pose.
|
|
493
|
+
|
|
494
|
+
| Operation | Arguments | Does / returns |
|
|
495
|
+
|---|---|---|
|
|
496
|
+
| `bone.list` | `layer` | `{skeletons: [{id, bones: [{id, parent, rest: {translate, rotate, scale, length}, pose: {translate, rotate, scale, length}, length (pose), constraints: [{id, bone, kind, target, params, space?}]}]}]}`, bones in preorder |
|
|
497
|
+
| `bone.add` | `layer`, `length` (>= 0), `rotate`, `parent?` (bone id: a child at its tip), `skeleton?` (root bones; created when missing; default the layer's first skeleton, else a new `Rig`), `translate?` [x, y] (root bones only), `id?` | `{bone, skeleton}` |
|
|
498
|
+
| `bone.remove` | `bone` | child bones move to its parent (keeping their rest angle), its constraints and those targeting it go, its weights go to its parent (a root's to its first child) |
|
|
499
|
+
| `bone.setRest` | `bone`, `rest: {translate? (root only), rotate?, scale?, length?}` | writes the bind pose (`rest-*`; the pose stays, so bound shapes re-bind); child bones keep their rest world angle |
|
|
500
|
+
| `bone.pose` | `bone`, `rotate?`, `translate?` (root only), `scale?`, `time?`, `timeline?` (default `main`) | with `time`: one `transform` keyframe on the bone (missing components = the static pose); without: writes the static pose (an edit, one undo step; the rest stays, so bound shapes deform). Returns `world` (as `bone.world`) |
|
|
501
|
+
| `bone.resetToRest` | `skeleton` | every bone's static pose back to its rest; returns the skeleton as in `bone.list` |
|
|
502
|
+
| `bone.setRestFromPose` | `skeleton` | every bone's rest set to its static pose (bound shapes re-bind at the pose, weights unchanged); returns the skeleton |
|
|
503
|
+
| `bone.world` | `bone` | the evaluated pose after constraints and springs: `{origin, tip, angle, length}` in viewport coordinates, `local {origin, angle}` in group space |
|
|
504
|
+
| `constraint.add` | `bone`, `kind` (`ik` \| `transform` \| `rotation` \| `spring`), `target?` (`#id` in the same `<svg>`; required except spring), `params?` (`strength`, `invert`, `chain`, `mix`, `inertia`, `damping`, `gravity`, `enabled`, `space`) | `{constraint}`; appended last on the bone (applied last) |
|
|
505
|
+
| `constraint.set` | `constraint`, `attr`, `value` (`""` removes it) | a parameter, `space` or `target` (`#id`); the kind cannot change |
|
|
506
|
+
| `constraint.remove` | `constraint` | |
|
|
507
|
+
| `skin.bind` | `shape`, `skeleton`, `auto?: {blend 0..1 (default 1; 0 = all to the nearest bone), influence (0, 10] (default 2)}` | auto weights from each vertex to the bones' rest segments (4 nearest); rebinding replaces the weights. `shape` is a `<path>` or `<xt-mesh>` (bake a parametric shape first) |
|
|
508
|
+
| `skin.get` | `shape` | `{skeleton, bones, mesh, vertices: [{index, position, p, in?, out?}]}`, each column `[{bone, weight}]` (normalized, heaviest first; a mesh pin has only `p`) |
|
|
509
|
+
| `skin.set` | `shape`, `vertices: [{index, p, in?, out?}]` | changes only the listed vertices; weights 0..1, at most 4 bones, normalized; `in` / `out` default to `p`; a bone of the skeleton not yet in the skin is added |
|
|
510
|
+
| `skin.unbind` | `shape` | removes `xt-skin` and the weights |
|
|
511
|
+
| `skin.smooth` | `shape`, `iterations` (1..100) | each vertex averaged with its neighbours (path: previous / next vertex; mesh: pins sharing a triangle) |
|
|
512
|
+
| `skin.prune` | `shape`, `threshold` (0..1) | drops weights below it (each vertex keeps its heaviest), renormalizes |
|
|
513
|
+
| `mesh.pins` | `mesh` | `{href, pins: [[x, y]], tris: [i...], skin}` |
|
|
514
|
+
| `mesh.convert` | `image` (an `<image>` / `<img>` in a vector layer with `href`, `width`, `height`) | replaces it by an `<xt-mesh>` at the same place: its `x` / `y` / `transform` kept, four corner pins (x, y)..(x + width, y + height) in that local space, their triangles, its id kept. Returns `{mesh, href, pins}` |
|
|
515
|
+
| `mesh.setPins` | `mesh`, `pins: [[x, y], ...]` (at least 3, not all on one line; keep the first four as the corners) | rewrites the pins and re-triangulates them (Delaunay, `<xt-tris>`); a skinned mesh keeps each pin's weights by index, added pins get weights interpolated from the mesh around them. Returns `{mesh, pins, tris, skin}` |
|
|
516
|
+
|
|
517
|
+
Vertex numbers are the editor's vertices of the path, contour by contour (the order of
|
|
518
|
+
`vector.get`'s `contours`); a closed contour that ends on its start point does not count that end
|
|
519
|
+
twice. Pins are numbered in `<xt-pins>` order and live in the mesh's local space (under its
|
|
520
|
+
`transform`). A pin's texture coordinate is (pin - (x, y)) over the mesh `width` / `height`
|
|
521
|
+
(clamped to the image). To deform an image: `mesh.convert`, add pins
|
|
522
|
+
where it should bend with `mesh.setPins` (the old pins first, in order), then `skin.bind`.
|
|
523
|
+
|
|
524
|
+
Errors: an unknown bone / constraint / skeleton / bone name in weights is `kNotFound`; a weight
|
|
525
|
+
outside 0..1 or a vertex index past the end is `kOutOfRange`; `auto` values outside their range,
|
|
526
|
+
`translate` on a child bone, a target missing on ik / transform / rotation, or a shape that cannot
|
|
527
|
+
be skinned is `kInvalidArgument`.
|
|
528
|
+
|
|
529
|
+
`lint.run` includes the rig rules: `skin.weightsStale` (weights no longer match the vertices or
|
|
530
|
+
bones), `skin.budget` (over 10k skinned points, 128 bones, 64 springs, an IK chain over 8),
|
|
531
|
+
`skin.ownTransform` (a skinned shape's own transform is animated: animate the bones),
|
|
532
|
+
`mesh.degenerate` (a triangle under 0.01 px^2: move or remove a pin), `mesh.pinOutside` (info: a
|
|
533
|
+
pin more than 10% outside the image). `export.lottie` bakes skinned paths per frame (`baked[]` reports
|
|
534
|
+
`vector.bakedFrames`), bakes elements bound to a bone port as per-frame transforms, and skips
|
|
535
|
+
meshes (`lottie.unsupported: mesh`).
|
|
536
|
+
|
|
537
|
+
## Cel animation (`cel.*`, 31 §31.7.5)
|
|
538
|
+
|
|
539
|
+
A layer with `data-xt-cels="1"` is a cel group: its child layers, in document order, are cels
|
|
540
|
+
0..N-1 and one cel shows at a time. Cel i is visible during `[start_i, end_i)`, written as
|
|
541
|
+
`visibility` hold keyframes (`steps(1, end)`) of each cel on the selected timeline of the group's
|
|
542
|
+
scope, else `root-anim` / `<symbol>-anim` (created at 2 s). There is nothing else to keep in step:
|
|
543
|
+
the runtime only sees `visibility` keys. Indexes are 0-based, times are seconds, one frame
|
|
544
|
+
(1 / fps, fps = the motion spec's `fps`, else 24) is the shortest cel. Inside a vector layer the
|
|
545
|
+
group is addressed `<svg id>/<g id>` when it is not the `<svg>` itself.
|
|
546
|
+
|
|
547
|
+
- `cel.list {group}` returns `{group, scope, timeline, fps, written, cels: [{index, id, track,
|
|
548
|
+
start, end, frames}]}`. `written: false` means no cel has frames yet: the cels share the
|
|
549
|
+
timeline length equally until the first edit writes them.
|
|
550
|
+
- `cel.add {group, after?, duplicate?}` adds a cel after cel `after` (default: the last). With
|
|
551
|
+
`duplicate` (default true) it is a copy of that cel with fresh ids (`Cel_n`); otherwise an empty
|
|
552
|
+
`<g>` (vector group) or `<div>`. It takes the length of cel `after`; later cels shift and a
|
|
553
|
+
written timeline duration grows. `added` is the new cel's id.
|
|
554
|
+
- `cel.setRange {group, index, start, end}` moves the cel's start (the boundary shared with the
|
|
555
|
+
previous cel) and end (shared with the next); neighbours follow, each keeps one frame.
|
|
556
|
+
- `cel.remove {group, index, confirm}` deletes cel `index` (its layer and frames); its time goes to
|
|
557
|
+
the previous cel (the next one for cel 0). `removed` is the deleted cel's id.
|
|
558
|
+
- `cel.convert {group}` makes the layer `group` with child layers (it needs an id) a cel group: unnamed
|
|
559
|
+
children get names and equal ranges over the timeline length. Replies like `cel.list`.
|
|
560
|
+
|
|
561
|
+
To draw a new cel, `cel.add` a copy, then edit its shapes with `vector.set` / `vector.editPath`
|
|
562
|
+
(`<svg id>/<shape id>` of the copy's new ids, from `vector.get`). `lint.run` reports
|
|
563
|
+
`cels.missingFrames` (info) for cels without frames.
|
|
564
|
+
|
|
565
|
+
## Intent (one call = one macro = one undo step; follow the motion spec)
|
|
566
|
+
|
|
567
|
+
| Operation | Does |
|
|
568
|
+
|---|---|
|
|
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) |
|
|
570
|
+
| `animate.exit {layers, style?, ...}` | an `outro`: `fade`, `sink` or `scale` |
|
|
571
|
+
| `animate.emphasis {layers, kind, duration?, timeline?}` | `pulse`, `shake` or `glow` |
|
|
572
|
+
| `layout.anchor {layers, template, margin?}` | anchors to the safe area by template: `hud-corners`, `menu-list`, `inventory` |
|
|
573
|
+
| `restyle {tokens}` | many token values at once (a new palette, a mood) |
|
|
574
|
+
| `fx.apply {layers, template}` | an effect template (`shared/fx/*.xtfxp`) |
|
|
575
|
+
| `state.apply {target, state, diff}` | a whole state look at once (a layer, or a symbol: `<inner>.<prop>` keys) |
|
|
576
|
+
| `wire.port {layer, prop, port, converters?, type?}` | declares the port if needed and binds it |
|
|
577
|
+
| `repair.import {report?}` | the import report's fixable warnings: names, anchors, states |
|
|
578
|
+
| `repair.anchor {root?, safeArea?}` | a fixed-size root (lint `layout.fixedRoot`) -> the root fills the viewport, its px layers anchored to the safe area (nearest edge within 25%, else centered; `anchored[]` per layer) |
|
|
579
|
+
| `repair.dedup {class, layers?}` | undoes the importer's style dedup (`dedup.shared`): the shared class rule's declarations go into each layer's own `#id` rule (its own values win) and the class is removed; the rule stays |
|
|
580
|
+
| `repair.effectBase {layer, effect}` | puts a base effect back (`effect.baseAdded`): every function of `effect` the layer's base style lacks is added (`backdrop-blur` first); idempotent, `added[]` |
|
|
581
|
+
| `repair.passthrough {layer, attr, value}` | writes a dropped pass-through attribute back (`import.dropped` with this fix): `tabindex`, `autofocus`, `focus-trap`, `nav:up|down|left|right` ("#id"), `key-activation` (on `body`) |
|
|
582
|
+
|
|
583
|
+
## Diagnostics (24 §24.15: the import's problem list)
|
|
584
|
+
|
|
585
|
+
The importer writes `diagnostics.json` (the UI Project's, every item) and `<ui>/<ui>.diagnostics.json`. Each item: `code`, `severity` (error | warning | info), `message`, `element`, `ui`, `detail`, `fix {kind: board | editor | none, applicability: machine | maybe | hint, board, editor {op, args}}`, `accepted`. After an import: fix the board-side items on the board and re-import, then apply the `editor` items, then report what is left (`hint` / `none`).
|
|
586
|
+
|
|
587
|
+
| Operation | Does |
|
|
588
|
+
|---|---|
|
|
589
|
+
| `diagnostics.list {ui?}` | the project's list (or one UI's); items carry `index`, `accepted` (from the UIs' `.xteditor.json`), plus `counts` |
|
|
590
|
+
| `diagnostics.accept {code, element, detail?, message?, ui?}` | records the difference in the UI's `.xteditor.json` `diagnostics.accepted[]`; not listed again on later imports |
|
|
591
|
+
| `diagnostics.fix {index, ui?, doc?}` | runs item `index`'s `fix.editor` op (a `repair.*`) on its UI (pass `doc: <ui>`), drops it from the files, re-runs `lint.run`; returns the new list plus `fixed`, `result`, `lint`. A board / hint item fails with kUnsupported |
|
|
592
|
+
|
|
593
|
+
The result of an intent operation lists `expanded[]`, the low-level operations it performed.
|
|
594
|
+
|
|
595
|
+
## Feedback
|
|
596
|
+
|
|
597
|
+
| Operation | Use |
|
|
598
|
+
|---|---|
|
|
599
|
+
| `scene.dump {scope?}` | layers with rect, visibility, states, triggers, bindings (`worldLayer: true` on a layer whose `world-layer` is `on`); `visibility` lists offscreen, empty, transparent, occluded, textOverflow, outsideSafeArea; effects usage |
|
|
600
|
+
| `scene.screenshot {scope?, state?, device?, lang?, timeline?, times?}` | a PNG; `times` (3-6) samples an animation. Counts against the scenario budget. `state: {layer, state}` forces `hover`, `pressed` (`:active`), `focus`, `checked`, `disabled` or a custom `:state(name)` on that layer; a rule with a `transition` is captured at its starting point, not its end |
|
|
601
|
+
| `lint.run {scope?}` | motion spec (`motion.*`), `lint.triggerTimeline`, `lint.stateNoDiff`, `lint.portUnbound`, `lint.literalColor`, `lint.textOverflow`, `layout.pxOutsideLogical`, `layout.fixedRoot`, `tags.*`, `contract.*`, `perf.*`, `skin.*`, `mesh.degenerate`, `mesh.pinOutside`, `compile` |
|
|
602
|
+
| `perf.probe {frames?}` | frame time, workload, fill rate, % of budget |
|
|
603
|
+
| `timeline.play {name}`, `timeline.seek {name, time}` | preview in the editor; the work site follows: that timeline becomes the active one and the timeline panel's playhead moves (a `notes` line when the timeline lives in a scope the panel is not showing) |
|
|
604
|
+
| `scenario.check {name?}` | the active contract's `done_when`, pass/fail per item |
|
|
605
|
+
|
|
606
|
+
## Bookkeeping
|
|
607
|
+
|
|
608
|
+
`scenario.list`, `session.setScenario {name, root?, entry?, explore?, rollback?}` (starts a work
|
|
609
|
+
item on the main line; `explore: true` runs it on a variant of its own instead; see SKILL.md "Work
|
|
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
|
|
614
|
+
returns `{empty, touched?, gates: {lint: {errors, warnings}, contract: {ok, violations}},
|
|
615
|
+
checkpoint}`; nothing written -> `{empty: true}`; idempotent; without a scenario it ends the work item
|
|
616
|
+
of your writes, see below), `session.getScope` (scope, scenario,
|
|
617
|
+
budget used, your `seat {id, name, kind}`), `session.setScope {mode, root?}` (only without a
|
|
618
|
+
scenario), `checkpoint.begin {scenario}`, `checkpoint.commit {id}`, `checkpoint.rollback {id}`,
|
|
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
|
|
624
|
+
documents and also sets a history checkpoint named `ai/<scenario>/<n>` by your seat (reply `history`:
|
|
625
|
+
its slug); the user sees it in the History panel and it stays after you leave. `history.checkpoint`
|
|
626
|
+
and `history.variant` are written by your seat. Leaving an explore variant with `rollback: true`
|
|
627
|
+
fails with `kUnsavedChanges` while it holds someone else's unsaved edits (yours are dropped).
|
|
628
|
+
T-367 (37.8.1 D5): writes **without** a scenario are a work item too -- it starts with your first
|
|
629
|
+
write and ends at your `doc.save` (its reply lists the ended items in `workItems`), your next
|
|
630
|
+
`session.setScenario` / `session.endScenario`, or when you disconnect; with history it leaves the
|
|
631
|
+
checkpoint "<seat> · HH:MM" (note `scenario: ""`, lint gates). The user's own edits are work items
|
|
632
|
+
of the user's seat the same way (ended by a save, 30 idle minutes, or your `session.setScenario`,
|
|
633
|
+
which first closes the user's item); `touched` records track layers of `timeline.*` in every scope,
|
|
634
|
+
the selector of `style.setRule`, the token of `style.setToken` and `flow` for `flow.set`.
|
|
635
|
+
|
|
636
|
+
`session.setView {selection?, timeline?, animate?, space?, device?, zoom?, pan?, editInPlace?}`
|
|
637
|
+
changes the work site (not an edit, no undo step) and replies with the whole view like
|
|
638
|
+
`session.getView`: `selection` (layer paths, `[]` = none), `timeline {scope?, name?, playhead?,
|
|
639
|
+
loop?: {start, end}, onion?: {before?, after?, mode?: frames|cels}}` (`name` must exist; `""`
|
|
640
|
+
selects none), `animate` (the Animate switch), `space` (Canvas, Code, Flow, Project, Demo), `device` (a
|
|
641
|
+
preset or `"W:H"`), `zoom` (<= 0 = fit), `pan` `[x, y]`, `editInPlace` (a symbol instance, `""`
|
|
642
|
+
leaves). In the editor it shows at once and the status bar says "<seat> selected N layers" /
|
|
643
|
+
"<seat> switched to timeline <name>" for three seconds; a headless editor keeps it (`timeline`,
|
|
644
|
+
`device`, `zoom`, `pan` in the UI's sidecar, the rest for your seat). `vector`, `safeArea` and `fit`
|
|
645
|
+
are read-only. A scenario whose scope is one layer (`subtree`, `selection-or-named`) started
|
|
646
|
+
without `root` works on the work site's selection (its primary layer; reply `rootFrom: selection`);
|
|
647
|
+
with nothing selected `selection-or-named` is the full scope.
|
|
648
|
+
|
|
649
|
+
History (36; `kUnsupported` when the project has no `.xtvc`): `history.status`,
|
|
650
|
+
`history.list {kind: checkpoints|variants|log, ref?, limit?}`, `history.checkpoint {name, note?}`,
|
|
651
|
+
`history.variant {name, from?}`, `history.switch {to, discard?}`, `history.compare {a, b}` are
|
|
652
|
+
yours (outside a scenario). `history.restore {checkpoint}` (main goes back to a checkpoint; the
|
|
653
|
+
line left behind is kept as a variant) is open to every seat since T-372 -- call it only when the
|
|
654
|
+
user asked for exactly that. `history.adopt {variant}` and `history.prune {variants, confirm}` are
|
|
655
|
+
**gates** (37.8.1 D1): `kForbidden` ("human-only ... unless a person makes its seat a steward")
|
|
656
|
+
unless the user made your seat a **steward** -- with "Allow as steward" on the knock bar, the AI
|
|
657
|
+
panel's "Allow adopt and approve", or `{"name": "<your seat>", "steward": true}` in the project's
|
|
658
|
+
`.xtcache/agents.json` (never edit that file yourself). A steward's call replies `asSteward: true`
|
|
659
|
+
and `steward: "adopted by <seat> (steward): <variant>"`; the history gets a commit with that message
|
|
660
|
+
by your seat, and your work item's checkpoint note lists it under `steward`. Even as a steward,
|
|
661
|
+
adopt or prune only when the user asked for it, outside a scenario (no contract allows them), and
|
|
662
|
+
say so in the report. Over MCP these tools are listed with "[Human-only gate ...]" in their
|
|
663
|
+
description.
|
|
664
|
+
T-261b: `checkpoint.rollback` is an edit. Your own checkpoint (one this client began) rolls back under
|
|
665
|
+
any scope or scenario while every change to the document since it began is your own (T-261c: no
|
|
666
|
+
edit, undo or redo by a human or another client, no file written by another client, the document
|
|
667
|
+
not replaced or switched); otherwise it needs the `full` scope and a scenario that lists it, and the
|
|
668
|
+
refusal ends with `; the document was edited by someone else since this checkpoint began` when that
|
|
669
|
+
is the reason.
|
|
670
|
+
|
|
671
|
+
## Sequences
|
|
672
|
+
|
|
673
|
+
**Recolour one button with a token**
|
|
674
|
+
|
|
675
|
+
```
|
|
676
|
+
session_setScenario {"name": "single-element", "root": "BtnPlay"}
|
|
677
|
+
checkpoint_begin {"scenario": "single-element"}
|
|
678
|
+
doc_status {} -> revision 41
|
|
679
|
+
layer_setProps {"layer": "BtnPlay", "props": {"background-color": "var(--color-accent)"}, "ifRevision": 41}
|
|
680
|
+
lint_run {"scope": "BtnPlay"} -> scene_screenshot {"scope": "BtnPlay"}
|
|
681
|
+
```
|
|
682
|
+
|
|
683
|
+
**Entrance animation for a menu**
|
|
684
|
+
|
|
685
|
+
```
|
|
686
|
+
session_setScenario {"name": "add-animation", "root": "Menu"}
|
|
687
|
+
checkpoint_begin {"scenario": "add-animation"}
|
|
688
|
+
animate_entrance {"layers": ["Title", "MenuList"], "style": "rise", "ifRevision": 41} -> revision 42
|
|
689
|
+
trigger_set {"layer": "Menu", "event": "show", "actions": "play(intro)", "ifRevision": 42}
|
|
690
|
+
lint_run -> scene_screenshot {"timeline": "intro", "times": [0, 0.15, 0.4]}
|
|
691
|
+
```
|
|
692
|
+
|
|
693
|
+
**Hover and pressed states**
|
|
694
|
+
|
|
695
|
+
```
|
|
696
|
+
session_setScenario {"name": "states-interaction", "root": "BtnPlay"}
|
|
697
|
+
checkpoint_begin {"scenario": "states-interaction"}
|
|
698
|
+
state_apply {"target": "BtnPlay", "state": "hover", "diff": {"background-color": "var(--color-accent-hover)"}, "ifRevision": 41}
|
|
699
|
+
state_apply {"target": "BtnPlay", "state": "pressed", "diff": {"background-color": "var(--color-accent-pressed)"}, "ifRevision": 42}
|
|
700
|
+
scene_screenshot {"scope": "BtnPlay", "state": {"layer": "BtnPlay", "state": "hover"}}
|
|
701
|
+
```
|
|
702
|
+
|
|
703
|
+
**Wire a health bar to the game**
|
|
704
|
+
|
|
705
|
+
```
|
|
706
|
+
session_setScenario {"name": "data-binding", "root": "HpBar"}
|
|
707
|
+
checkpoint_begin {"scenario": "data-binding"}
|
|
708
|
+
wire_port {"layer": "HpFill", "prop": "width", "port": "hp", "type": "number",
|
|
709
|
+
"converters": ["range(0,hp_max,0%,100%)"], "ifRevision": 41}
|
|
710
|
+
port_set {"layer": "body", "name": "hp_max", "type": "number", "ifRevision": 42}
|
|
711
|
+
lint_run (lint.portUnbound must be clean)
|
|
712
|
+
```
|
|
713
|
+
|
|
714
|
+
In source format 2 the document's ports live in `<ports>`, reached as the layer `body` (a format 1
|
|
715
|
+
document may declare them on its top layer, e.g. `Hud`); `wire_port` with `type` declares `hp` there too.
|
|
716
|
+
|
|
717
|
+
**Mascot idle (bones, auto weights, two poses, an IK)**
|
|
718
|
+
|
|
719
|
+
```
|
|
720
|
+
session_setScenario {"name": "add-animation"}
|
|
721
|
+
checkpoint_begin {"scenario": "add-animation"}
|
|
722
|
+
bone_add {"layer": "Mascot", "length": 60, "rotate": -90, "translate": [100, 180], "id": "Spine", "ifRevision": 41}
|
|
723
|
+
bone_add {"layer": "Mascot", "parent": "Spine", "length": 40, "rotate": 0, "id": "Head", "ifRevision": 42}
|
|
724
|
+
skin_bind {"shape": "Mascot/Body", "skeleton": "Rig", "ifRevision": 43}
|
|
725
|
+
bone_pose {"bone": "Mascot/Head", "rotate": -8, "time": 0, "ifRevision": 44}
|
|
726
|
+
bone_pose {"bone": "Mascot/Head", "rotate": 8, "time": 1, "ifRevision": 45}
|
|
727
|
+
lint_run -> scene_screenshot {"timeline": "main", "times": [0, 0.5, 1]}
|
|
728
|
+
```
|
|
729
|
+
|
|
730
|
+
**Clean up after an import**
|
|
731
|
+
|
|
732
|
+
```
|
|
733
|
+
session_setScenario {"name": "repair-import"}
|
|
734
|
+
checkpoint_begin {"scenario": "repair-import"}
|
|
735
|
+
repair_import {"ifRevision": 41}
|
|
736
|
+
layout_anchor {"layers": ["HpPanel", "Ammo"], "template": "hud-corners", "ifRevision": 42}
|
|
737
|
+
lint_run -> scenario_check
|
|
738
|
+
```
|
|
739
|
+
|
|
740
|
+
Then, every time: `session_endScenario` (read its `gates`; fix until lint has no error), the
|
|
741
|
+
three-list report and `checkpoint_commit` or `checkpoint_rollback` on the user's word (SKILL.md
|
|
742
|
+
sections 4 and 5).
|
|
743
|
+
|
|
744
|
+
**Change another UI without moving the user's view**
|
|
745
|
+
|
|
746
|
+
```
|
|
747
|
+
doc_open {"path": "PauseMenu"} your active document now; the GUI stays
|
|
748
|
+
doc_status {} revision, modified, diskNewer
|
|
749
|
+
style_getRules {"selector": ".card:hover"} -> style_setRule {"selector": ".card:hover",
|
|
750
|
+
"props": {"background-color": "var(--color-accent)"}, "ifRevision": 12}
|
|
751
|
+
doc_save {"ifRevision": 13}
|
|
752
|
+
```
|
|
753
|
+
|
|
754
|
+
(Each reply's `revision` is the `ifRevision` of your next write; the numbers above are examples.)
|
|
755
|
+
|
|
756
|
+
**After writing files outside the editor** (`xtframe-import`, a direct write)
|
|
757
|
+
|
|
758
|
+
```
|
|
759
|
+
doc_status {} diskNewer / modified
|
|
760
|
+
doc_reload {} (unsaved edits: ask the user, then {"discard": true})
|
|
761
|
+
```
|
|
762
|
+
|
|
763
|
+
## All operations
|
|
764
|
+
|
|
765
|
+
Every operation by name (`Tools/Scripts/check_ops_doc.sh` keeps this list equal to
|
|
766
|
+
`Assets/Schemas/editor-service/`).
|
|
767
|
+
|
|
768
|
+
```
|
|
769
|
+
animate.emphasis
|
|
770
|
+
animate.entrance
|
|
771
|
+
animate.exit
|
|
772
|
+
animation.followPath
|
|
773
|
+
animation.preset
|
|
774
|
+
asset.import
|
|
775
|
+
asset.linkFolder
|
|
776
|
+
asset.list
|
|
777
|
+
asset.replace
|
|
778
|
+
asset.setStatus
|
|
779
|
+
asset.slice
|
|
780
|
+
asset.sync
|
|
781
|
+
bind.get
|
|
782
|
+
bind.set
|
|
783
|
+
bone.add
|
|
784
|
+
bone.list
|
|
785
|
+
bone.pose
|
|
786
|
+
bone.remove
|
|
787
|
+
bone.resetToRest
|
|
788
|
+
bone.setRest
|
|
789
|
+
bone.setRestFromPose
|
|
790
|
+
bone.world
|
|
791
|
+
catalog.add
|
|
792
|
+
catalog.list
|
|
793
|
+
cel.add
|
|
794
|
+
cel.convert
|
|
795
|
+
cel.list
|
|
796
|
+
cel.remove
|
|
797
|
+
cel.setRange
|
|
798
|
+
checkpoint.begin
|
|
799
|
+
checkpoint.commit
|
|
800
|
+
checkpoint.list
|
|
801
|
+
checkpoint.rollback
|
|
802
|
+
constraint.add
|
|
803
|
+
constraint.remove
|
|
804
|
+
constraint.set
|
|
805
|
+
conventions.put
|
|
806
|
+
design.approve
|
|
807
|
+
design.audit
|
|
808
|
+
design.build
|
|
809
|
+
design.contrast
|
|
810
|
+
design.delete
|
|
811
|
+
design.deprecate
|
|
812
|
+
design.deriveScale
|
|
813
|
+
design.diff
|
|
814
|
+
design.export
|
|
815
|
+
design.extractPalette
|
|
816
|
+
design.get
|
|
817
|
+
design.importDesignSystem
|
|
818
|
+
design.importReference
|
|
819
|
+
design.link
|
|
820
|
+
design.lint
|
|
821
|
+
design.list
|
|
822
|
+
design.put
|
|
823
|
+
design.search
|
|
824
|
+
design.unlink
|
|
825
|
+
design.usage
|
|
826
|
+
diagnostics.accept
|
|
827
|
+
diagnostics.fix
|
|
828
|
+
diagnostics.list
|
|
829
|
+
doc.changes
|
|
830
|
+
doc.list
|
|
831
|
+
doc.open
|
|
832
|
+
doc.reload
|
|
833
|
+
doc.save
|
|
834
|
+
doc.setSource
|
|
835
|
+
doc.source
|
|
836
|
+
doc.status
|
|
837
|
+
export.lottie
|
|
838
|
+
flow.get
|
|
839
|
+
flow.set
|
|
840
|
+
fx.apply
|
|
841
|
+
history.adopt
|
|
842
|
+
history.checkpoint
|
|
843
|
+
history.compare
|
|
844
|
+
history.list
|
|
845
|
+
history.prune
|
|
846
|
+
history.restore
|
|
847
|
+
history.status
|
|
848
|
+
history.switch
|
|
849
|
+
history.variant
|
|
850
|
+
import.reimport
|
|
851
|
+
initialize
|
|
852
|
+
layer.create
|
|
853
|
+
layer.addAdjustment
|
|
854
|
+
layer.delete
|
|
855
|
+
layer.duplicate
|
|
856
|
+
layer.get
|
|
857
|
+
layer.group
|
|
858
|
+
layer.list
|
|
859
|
+
layer.move
|
|
860
|
+
layer.removeAdjustment
|
|
861
|
+
layer.rename
|
|
862
|
+
layer.setAttrs
|
|
863
|
+
layer.setFlags
|
|
864
|
+
layer.setProps
|
|
865
|
+
layer.setText
|
|
866
|
+
layout.anchor
|
|
867
|
+
lint.run
|
|
868
|
+
mesh.convert
|
|
869
|
+
mesh.pins
|
|
870
|
+
mesh.setPins
|
|
871
|
+
perf.probe
|
|
872
|
+
port.get
|
|
873
|
+
port.set
|
|
874
|
+
project.addUi
|
|
875
|
+
project.create
|
|
876
|
+
project.get
|
|
877
|
+
project.importReport
|
|
878
|
+
project.publish
|
|
879
|
+
project.removeUi
|
|
880
|
+
project.renameUi
|
|
881
|
+
project.saveAs
|
|
882
|
+
project.search
|
|
883
|
+
project.set
|
|
884
|
+
project.setAgents
|
|
885
|
+
project.setPublishSettings
|
|
886
|
+
project.syncSymbols
|
|
887
|
+
redo
|
|
888
|
+
repair.anchor
|
|
889
|
+
repair.dedup
|
|
890
|
+
repair.effectBase
|
|
891
|
+
repair.import
|
|
892
|
+
repair.passthrough
|
|
893
|
+
restyle
|
|
894
|
+
scenario.check
|
|
895
|
+
scenario.list
|
|
896
|
+
scene.dump
|
|
897
|
+
scene.screenshot
|
|
898
|
+
service.ops
|
|
899
|
+
session.endScenario
|
|
900
|
+
session.getScope
|
|
901
|
+
session.getView
|
|
902
|
+
session.setScenario
|
|
903
|
+
session.setScope
|
|
904
|
+
session.setView
|
|
905
|
+
shader.create
|
|
906
|
+
shader.get
|
|
907
|
+
shader.list
|
|
908
|
+
shader.setSource
|
|
909
|
+
skin.bind
|
|
910
|
+
skin.get
|
|
911
|
+
skin.prune
|
|
912
|
+
skin.set
|
|
913
|
+
skin.smooth
|
|
914
|
+
skin.unbind
|
|
915
|
+
state.apply
|
|
916
|
+
state.list
|
|
917
|
+
state.set
|
|
918
|
+
style.addStyle
|
|
919
|
+
style.copyStyles
|
|
920
|
+
style.deleteRule
|
|
921
|
+
style.getRules
|
|
922
|
+
style.getTokens
|
|
923
|
+
style.moveDecl
|
|
924
|
+
style.pasteStyles
|
|
925
|
+
style.removeStyle
|
|
926
|
+
style.renameRule
|
|
927
|
+
style.setRule
|
|
928
|
+
style.setStyleParams
|
|
929
|
+
style.setTheme
|
|
930
|
+
style.setToken
|
|
931
|
+
style.styles
|
|
932
|
+
symbol.create
|
|
933
|
+
symbol.detach
|
|
934
|
+
symbol.instantiate
|
|
935
|
+
symbol.list
|
|
936
|
+
symbol.override
|
|
937
|
+
symbols.export
|
|
938
|
+
symbols.get
|
|
939
|
+
symbols.import
|
|
940
|
+
symbols.libraries
|
|
941
|
+
symbols.library
|
|
942
|
+
symbols.lint
|
|
943
|
+
symbols.loadPreset
|
|
944
|
+
symbols.mountLibrary
|
|
945
|
+
symbols.saveAsGroup
|
|
946
|
+
symbols.unmountLibrary
|
|
947
|
+
symbols.move
|
|
948
|
+
symbols.duplicateDetached
|
|
949
|
+
symbols.updateCopy
|
|
950
|
+
symbols.use
|
|
951
|
+
symbols.useGroup
|
|
952
|
+
timeline.bakeExpression
|
|
953
|
+
timeline.create
|
|
954
|
+
timeline.delete
|
|
955
|
+
timeline.duplicate
|
|
956
|
+
timeline.fromAnimations
|
|
957
|
+
timeline.get
|
|
958
|
+
timeline.list
|
|
959
|
+
timeline.moveKeys
|
|
960
|
+
timeline.play
|
|
961
|
+
timeline.removeKeyframe
|
|
962
|
+
timeline.removeTrack
|
|
963
|
+
timeline.rename
|
|
964
|
+
timeline.seek
|
|
965
|
+
timeline.setCue
|
|
966
|
+
timeline.setDuration
|
|
967
|
+
timeline.setEasing
|
|
968
|
+
timeline.setExpression
|
|
969
|
+
timeline.setKeyframe
|
|
970
|
+
timeline.setKeyframes
|
|
971
|
+
timeline.setMarker
|
|
972
|
+
timeline.stagger
|
|
973
|
+
tokens.applyStyle
|
|
974
|
+
trigger.get
|
|
975
|
+
trigger.set
|
|
976
|
+
undo
|
|
977
|
+
vector.bake
|
|
978
|
+
vector.boolean
|
|
979
|
+
vector.editPath
|
|
980
|
+
vector.extract
|
|
981
|
+
vector.get
|
|
982
|
+
vector.morph
|
|
983
|
+
vector.set
|
|
984
|
+
vector.shapeOp
|
|
985
|
+
vector.textToOutlines
|
|
986
|
+
vector.trace
|
|
987
|
+
wire.port
|
|
988
|
+
```
|