@xtframe/skills 0.0.0-stage → 0.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (35) hide show
  1. package/README.md +22 -2
  2. package/package.json +41 -4
  3. package/payload/plugins/xtframe/.claude-plugin/plugin.json +17 -0
  4. package/payload/plugins/xtframe/.codex-plugin/plugin.json +11 -0
  5. package/payload/plugins/xtframe/gemini-extension.json +5 -0
  6. package/payload/plugins/xtframe/skills/xtui/SKILL.md +218 -0
  7. package/payload/plugins/xtframe/skills/xtui/references/canvas.md +90 -0
  8. package/payload/plugins/xtframe/skills/xtui/references/dialect.md +799 -0
  9. package/payload/plugins/xtframe/skills/xtui/references/flow.md +338 -0
  10. package/payload/plugins/xtframe/skills/xtui/references/not-like-web.md +358 -0
  11. package/payload/plugins/xtframe/skills/xtui/references/performance.md +162 -0
  12. package/payload/plugins/xtframe/skills/xtui/references/responsive.md +137 -0
  13. package/payload/plugins/xtframe/skills/xtui/references/style-groups.md +378 -0
  14. package/payload/plugins/xtframe/skills/xtui/references/template.dc.html +56 -0
  15. package/payload/plugins/xtframe/skills/xtui/references/tokens.json +42 -0
  16. package/payload/plugins/xtframe/skills/xtui/references/ui-project.md +161 -0
  17. package/payload/plugins/xtframe/skills/xtui/references/upgrade.md +140 -0
  18. package/payload/plugins/xtframe/skills/xtui/references/vector.md +219 -0
  19. package/payload/plugins/xtframe/skills/xtui/references/verify.md +327 -0
  20. package/payload/plugins/xtframe/skills/xtui-editor/SKILL.md +209 -0
  21. package/payload/plugins/xtframe/skills/xtui-editor/references/design.md +158 -0
  22. package/payload/plugins/xtframe/skills/xtui-editor/references/ops.md +849 -0
  23. package/payload/plugins/xtframe/skills/xtui-editor/references/recipes.md +70 -0
  24. package/payload/plugins/xtframe/skills/xtui-editor/references/scenarios.md +180 -0
  25. package/payload/plugins/xtframe/skills/xtui-editor/references/service.md +167 -0
  26. package/src/agents.mjs +73 -0
  27. package/src/bin.mjs +4 -0
  28. package/src/cli.mjs +286 -0
  29. package/src/converter.mjs +73 -0
  30. package/src/fsutil.mjs +76 -0
  31. package/src/install.mjs +154 -0
  32. package/src/packs.mjs +150 -0
  33. package/src/plugins.mjs +109 -0
  34. package/src/proc.mjs +66 -0
  35. package/src/tar.mjs +103 -0
@@ -0,0 +1,849 @@
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
+ T-366: when another seat changed the document's files on disk while it had unsaved edits
42
+ (`doc.status` `diskNewer`), a write with `ifRevision` fails with `kConflict` too, and so does
43
+ `doc.save` (with or without it): `doc.reload`, or `doc.save {force: true}` after asking the human.
44
+ Operations that write project files rather than a document (`design.*`, `project.*`,
45
+ `conventions.put`, `asset.import` / `slice` / `linkFolder` / `sync`, `history.*`) take no
46
+ `ifRevision`.
47
+
48
+ **Attributes vs style properties.** Two different writes, each refusing the other's names:
49
+ `layer.setAttrs {layer, attrs}` writes attributes -- `editor-only`, `class`, `data-*`, `aria-*`,
50
+ `src`, `href`, `ui-scale`, `media-override`, `variant:<prop>` (an instance's variant); `null`
51
+ removes one. `layer.setProps {layer, props, state?}` writes style properties into the layer's
52
+ `#id` rule (or its state rule) and refuses an attribute name as `unknown property`. `id` is
53
+ `layer.rename`; `on:*`, `bind:*`, `port:*` are `trigger.set`, `bind.set`, `port.set` (refused by
54
+ `layer.setAttrs` and `layer.create {attrs}` alike). Rules for classes, states and `@media` are
55
+ `style.setRule`.
56
+
57
+ ## Read (never change anything)
58
+
59
+ | Operation | Returns |
60
+ |---|---|
61
+ | `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`) |
62
+ | `project.search {query, limit?}` | matching references and conventions |
63
+ | `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}]`) |
64
+ | `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 |
65
+ | `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 |
66
+ | `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" |
67
+ | `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"}`) |
68
+ | `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`) |
69
+ | `style.getTokens` | tokens and themes in effect |
70
+ | `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 |
71
+ | `flow.get` | the flow graph (`.xtflow`): `{path, graph: {nodes, edges, groups?}, problems}`, `problems` = edges whose element endpoint names no layer |
72
+ | `project.importReport {ui}` | the `import-report.json` of a UI of the project: `{ui, path, report}` |
73
+ | `project.syncSymbols {diff?}` | T-408: the project's copies of standard symbols against the library: `{library, symbols: [{name, file, standard, status, diff?}], counts, notes}`; `status` is `current`, `outdated` (an earlier library version -- a newer one exists, the copy was not edited) or `modified` (edited in the project); `diff` is a unified diff library -> copy. Reports only, never overwrites a copy |
74
+ | `timeline.list`, `timeline.get {name, scope?}` | named timelines; one timeline's tracks and keys |
75
+ | `trigger.get {layer}`, `bind.get {layer}`, `port.get {layer}` | a layer's `on:`, `bind:`, `port:` (each port with its `default` literal, or null). In source format 2 the ports are the `<ports>` lines of the document (`layer: "body"`) or of a symbol (`layer`: its root, `<Symbol>/<root>`); any other layer has none |
76
+ | `symbol.list`, `state.list {layer}` | symbols with their contracts; a layer's states |
77
+ | `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`) |
78
+ | `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 |
79
+ | `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 |
80
+ | `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 |
81
+ | `asset.list {status?}` | the asset manifest (`draft`, `approved`, `stale`, `pending`) |
82
+ | `service.ops` | the operation list with schemas |
83
+ | `initialize` | the handshake (above): `{version, format: {xtui, ir}, behavior, ops, deprecated}` |
84
+ | `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 |
85
+
86
+ ## Write (one undo step each)
87
+
88
+ | Kind | Operations |
89
+ |---|---|
90
+ | Layers | `layer.create {parent, tag?, name?, text?, attrs?, index?}`, `layer.move {layer, parent, index?}`, `layer.rename {layer, name}`, `layer.setProps {layer, props, state?}`, `layer.setText {layer, text}`, `layer.setAttrs {layer, attrs}` (attribute -> value, null removes; **attributes go here** -- `editor-only`, `class`, `data-*`, `aria-*`, `src`, `href`, `ui-scale`, `media-override`; `layer.setProps` takes style properties only and refuses an attribute name as `unknown property`. `id`, `on:*`, `bind:*`, `port:*` refused: use `layer.rename`, `trigger.set`, `bind.set`, `port.set`; `layer.create {attrs}` follows the same rules with the same messages), `layer.setFlags {layer, hidden?, locked?, solo?, color?, collapsed?, adjustHidden?}` (the editor's own layer flags, see "Locked layers" below), `layer.duplicate {layer, count?}` (the layers panel's Duplicate: the subtree and its `#id` rules under the copies' new names, `count` 1-100 copies; the reply lists `copies`), `layer.group {layers, kind?}` (the layers panel's Group / Convert to Stack, layers with one parent, in document order: `group` (default) wraps them into a new `Group_<n>` div; `stack` gives `display: flex` -- a single group layer in place, else wrapped into `Stack_<n>`; the reply names the `layer`), `layer.delete {layer, confirm}` |
91
+ | Style | `style.setToken {name, value}`, `style.setTheme {theme}` (preview only), `style.setRule {selector, props, file?, media?}` (declarations of the rule with exactly this selector, e.g. `.card:hover`; null removes one; the rule is added when missing; default the UI's own stylesheet, a shared one only when `file` names it. `media` is an `@media` query such as `(max-width: 1280px)` or `(aspect-ratio <= 4/3)`: the rule inside that `@media` block is written, the block added at the end of the stylesheet when missing, e.g. `@media (max-width: 1280px) { .card { left: 1px } }`; a rule left empty goes, and its block with it), `style.renameRule {selector, newSelector, file?}` (the style rules panel's selector edit), `style.deleteRule {selector, media?, file?, confirm}` (a whole rule; with `media` the rule inside that `@media` block), `style.moveDecl {from, to, prop, fromFile?, toFile?}` (the panel's Move to: the destination rule takes the value, the source loses it and goes when empty). These three find a rule as `style.setRule` does (a rule only in a shared stylesheet needs its `file`); `kNotFound` names a missing rule or property. A token (`style.setToken`, `restyle`, `design.put` of a variable) is the same edit the token panel makes: it changes the open UI's copy of `shared/tokens.xts`, the panel shows it at once and `doc.save` writes the file |
92
+ | Timelines | `timeline.create {name, duration?, scope?}`, `timeline.setKeyframe {name, layer, prop, time, value, easing?}` (an effect parameter `prop` is `effect.<index|name>.<param>`: a vec2 as a whole, e.g. `effect.shadow.offset` or a shader vec2, is one key with two numbers, `"<x>px <y>px"` or `"<x> <y>"`; `<param>.x` / `.y` key one component; slots `p<n>` (float 0-15), `c<n>` (colour 0-3), `v<n>` (vec2 from float slot n, 0-14) address any effect without its names), `timeline.setEasing {name, layer, prop, time, easing}`, `timeline.removeKeyframe {name, layer, prop, time}`, `timeline.delete {name, confirm}`, `timeline.rename {name, newName, scope?}`, `timeline.duplicate {name, newName, scope?}` (triggers that play the old name are not rewritten), `timeline.setDuration {name, duration, mode?, scope?}` (`clip`, default: only the length changes, keys past the end stay; `scale`: every key, marker and cue time scales by new / old length), `timeline.setMarker {name, time, label, scope?}` / `timeline.setCue {name, time, sound, scope?}` (a name adds the marker / cue at `time` or renames the one there; `null` removes it), `timeline.moveKeys {name, keys: [{layer, prop, time}], dt?, scale?: {pivot?, factor}, scope?}` (new time = pivot + (time - pivot) x factor + dt, clamped at 0; all keys in one undo step; use it instead of remove + set), `timeline.stagger {name, keys: [{layer, prop, time}], interval?, order?, reverse?, seed?, scope?}` (each layer's keys shift by i x `interval` ms, default 50; `order` layer \| reverse \| random \| center), `animation.preset {layer, preset, timeline?, at?, scope?}` (a stroke preset on a vector shape `<svg>/<shape>`: `draw-on`, `draw-off`, `marching-ants`, `pulse-stroke`; default timeline `intro`), `animation.followPath {path, layer, timeline, start?, end?, samples?, align?, autoOrient?, scope?}` (bakes the shape `path` into `layer`'s `transform` translate keys, evenly spaced by arc length) |
93
+ | Interaction | `trigger.set {layer, event, actions}`, `state.set {layer, state, prop, value}`, `bind.set {layer, target, expr}`, `port.set {layer, name, type, dir?, expose?, default?}` (`type: ""` removes the port; `default` is a literal such as `80`, `true`, `"Guest"`, `#ff0000`; null removes it, omitted keeps it while the type is unchanged. In source format 2 no `port:` attribute is written: the port is a line of `<ports>`, so `layer` is `body` (the document's ports) or a symbol's root (`<Symbol>/<root>`, the symbol's ports), and any other layer is `kUnsupported`) |
94
+ | Flow | `flow.set {graph, dryRun?}` (replaces the whole `.xtflow` graph `{nodes, edges, groups?}`, one undo step, written by `doc.save`; parse errors fail the call; `dryRun: true` only returns `problems`; a `flow.animatesWithContinuousSignal` warning is not in `problems`, it appears in the editor's Messages panel as `flow: warning: ...`, so look at Messages after a `flow.set` and rewrite the edge: a flow drives, it never interpolates). Read it first with `flow.get` and send it back whole. T-371: works on a background document too (`doc` = a UI opened without `show`); the graph stays with that UI when the user switches to it |
95
+ | Flow `state` node (T-541) | a flow graph may hold `{id, type: "state", params: {states: [..], initial?, transitions: [{from, on, to}], events?}}`: one pulse input per event, `set` (string) and `guard` (bool); outputs `state`, `index`, `changed`, `enter<Name>` / `exit<Name>` per state. Edges into an element take `#id.setState` with edge params `state` (required) and `mode` (`on` / `off` / `toggle`). Sent whole through `flow.set` like every other node |
96
+ | Symbols | `symbol.create {layers, name, origin?, shared?}`, `symbol.instantiate {symbol, parent, name?, index?, source?}` (`source`: `document` (default), `project` = `<shared.symbols>/<Symbol>.xt`, `standard` = the standard library, copied into `shared.symbols` first; a library symbol is linked when needed -- `<symbols src>` in a source format 2 document, `<link rel="symbols">` in format 1 -- and the reply names it as `library`), `symbol.override {instance, path, value}`, `symbol.detach {instance, confirm}` |
97
+ | Symbol libraries (T-502, 49.7; see "Symbol libraries" below) | `symbols.use {names, group?, library?}`, `symbols.useGroup {group, library?}`, `symbols.updateCopy {name}` write the open project (one undo step each; `create`, `restyle`, `repair-import`, `single-element`). `symbols.saveAsGroup {names, groupId, name, library?}`, `symbols.loadPreset {group, keepOld?}`, `symbols.import {path \| url, library?, as?, replaceOlder?}`, `symbols.export {group, library?, out, author?, license?, fonts?}`, `symbols.mountLibrary {path}`, `symbols.unmountLibrary {id}` write a library or the mount list: the `library` scenario only, and refused with `kPermissionDenied` until the user allows AI library writes (the preference or a one-time approval; a client cannot grant it to itself). None takes `ifRevision` |
98
+ | Assets | `asset.import {file, type?, id?, source?, license?, confirm?}`, `asset.setStatus {id, status}` (never `approved`). T-371 (the asset workbench's edits; `asset` is the asset file's project-relative path, e.g. `shared/img/a.png`): `asset.replace {asset, path, allUses?}` (without `allUses`: the file gets the content of `path` -- same extension, absolute or project-relative -- keeping its identity, status draft; with `allUses: true`: every `src`/`href` and `url()` of the document naming `asset` is pointed at the asset `path` instead, one undo step, returns `replaced`), `asset.slice {asset, slices: [left, right, top, bottom]}` (nine-slice in the `.meta`; all zero removes it), `asset.linkFolder {path, collection?}` (an existing absolute directory; an already linked one gets the new collection; writes the project file), `asset.sync` (imports new files of the linked folders, replaces changed ones as `stale`; returns `imported`, `replaced`, `unchanged`, `missing`, `warnings`) |
99
+ | Vectors (T-224) | `vector.set {layer, svg? \| shapes?}`, `vector.editPath {shape, ops}`, `vector.boolean {shapes, op}`, `vector.bake {layer, shape?}`, `vector.shapeOp {layer, shape?, op, ...}` (T-370), `vector.textToOutlines {layer}`, `vector.extract {layer, path?}`, `vector.morph {shape, action, index?}`, `vector.trace {layer, mode?, threshold?, colors?, minArea?, smoothing?, hideSource?}` (bitmap `<img>` -> new traced `<svg>` layer after it; T-232); read with `vector.get {layer, normalize?}` (see "Vector layers" below) |
100
+ | Rigs (T-248) | `bone.add {layer, skeleton?, parent?, length, rotate, translate?, id?}`, `bone.remove {bone}`, `bone.setRest {bone, rest}`, `bone.pose {bone, rotate?, translate?, scale?, time?, timeline?}`, `bone.resetToRest {skeleton}`, `bone.setRestFromPose {skeleton}`, `constraint.add {bone, kind, target?, params?}`, `constraint.set {constraint, attr, value}`, `constraint.remove {constraint}`, `skin.bind {shape, skeleton, auto?}`, `skin.set {shape, vertices}`, `skin.unbind {shape}`, `skin.smooth {shape, iterations}`, `skin.prune {shape, threshold}`, `mesh.convert {image}`, `mesh.setPins {mesh, pins}`; read with `bone.list {layer}`, `bone.world {bone}`, `skin.get {shape}`, `mesh.pins {mesh}` (see "Rigs" below) |
101
+ | Cels (T-229) | `cel.add {group, after?, duplicate?}`, `cel.setRange {group, index, start, end}`, `cel.remove {group, index, confirm}`, `cel.convert {group}`; read with `cel.list {group}` (see "Cel animation" below) |
102
+ | Documents | `doc.open {path, show?, discard?}` (a project UI id or a `.xt` path; it becomes **your** active document, opened in the background: the user's view stays. `show: true` also switches the editor's shown document -- only when the user asked to see it. Fails with `kUnsavedChanges` when it would drop unsaved edits; `discard: true` only after asking the human), `doc.reload {discard?}` (reads the document again from disk after anything wrote its files outside the editor -- `xtframe-import`, a re-import from the command line, a direct write; drops its undo history; unsaved edits: `kUnsavedChanges` unless `discard: true`, after asking the human), `doc.save {force?}` (T-366: `kConflict` when the disk is newer, `diskNewer`; `force: true` overwrites it, `doc.setSource {kind, text, file?, ifRevision}` (the source panel's edit, as data: `kind: "xt"` replaces the whole `.xt`, `kind: "xts"` one stylesheet -- `file` as `style.getRules` names it, default the UI's own `.xts`. The text is compiled first; text that does not parse or compile, or that adds a compile warning, is refused with the diagnostics and nothing changes -- in format 2 that includes geometry written in a stylesheet or `<style>` (`style.geometryInStyle`), a look property in `<layout>` (`layout.notGeometry`) and a `port:` attribute instead of a `<ports>` line (`ports.onElement`). Prefer the typed operations; use it for a change none of them makes, after `doc.source`, with `ifRevision`), `undo`, `redo` (T-366, 37.8.1 D3: one stack for everyone; you undo / redo only the steps on top of it that are **your own** -- when the top is someone else's step, `kConflict` "top of the undo stack is <seat>'s edit": leave it, the user's Ctrl+Z is theirs), `import.reimport {source, ui?, prune?, force?, confirm?}`, `export.lottie {path, ui?, timeline?, fps?, bakeUnsupported?, embedImages?, strict?, confirm?}` (T-234: the UI as a Lottie JSON file; returns the report: `skipped`, `baked`, `approximated`. T-261b: it reads the saved files, so `doc.save` first -- unsaved edits fail with `kUnsavedChanges`; overwriting an existing file outside the project needs `confirm: true`) |
103
+ | Design system (T-310, `design.md`) | `design.put {kind, entry}` (always `draft`; `status: approved` / `approved:` -> `kForbidden`; a token's value goes through `style.setToken`), `design.importReference {path \| url, group, title?, tags?, license?, extract?}`, `design.link {from, rel, to, note?}`, `design.unlink {from, rel, to}`, `design.build` (regenerates `DESIGN.md`, returns the lint counts), `design.export {format: html \| claude-design, out}` (a file / a Claude Design design-system folder inside the project), `design.importDesignSystem {dir}` (T-316: a Claude Design design-system folder back in as drafts; existing values are never overwritten), `design.delete {ref, confirm}` (outside a scenario or in `design-system`: removes the entry and every link to it; refused while a UI, layer or symbol uses it -- `design.usage`; a text, decision or reference entry's files go too; `confirm: true` after asking the human). `design.approve` / `design.deprecate` are human-only gates: `kForbidden` for an AI path unless the user made your seat a steward (37.8.1 D1; the reply then has `asSteward: true` and the entry `approved.by` is "<seat> (steward)"); never inside a scenario. These need the `full` scope |
104
+ | Project (T-212) | `project.create {dir, name, id, template?, discard?}` (new UI Project, opened; `kUnsavedChanges` as `doc.open`; writes `<dir>/<name>.xtui`, returns `path` = that file and `dir`), `project.saveAs {dir}` (a lone `.xt` moves into `<dir>/<ui id>/`; a named project is copied; the copy's project file is `<name>.xtui`), `project.publish {target?: {kind: dir, path}, ui?, confirm?}` (complete bundle directory; default: last target, else `<project>/publish`; returns the pack summary; T-261b: a target outside the project, or an existing non-empty directory without `manifest.json`, needs `confirm: true`; T-687: images are written per the project file's `publish.images.compress`, which no op sets -- the user edits it; T-693: a successful publish removes the files in the target's `ui/`, `assets/`, `thumbs/`, `themes/`, `strings/`, `atlas/` and `fonts/` that it neither wrote nor lists). T-261b: these three need the `full` scope |
105
+ | Project files (T-371, `full` scope) | `project.addUi {id, doc?, copyFrom?}` (a blank UI, or a copy of UI `copyFrom` -- its open document as it is now; `doc` defaults to `<prefix>/<id>/<id>.xt` after the project's layout; writes the document and the project file), `project.renameUi {id, newId}` (hosts bind to the id; the global flow's `ui#<id>` endpoints and timeline `ui` parameters are rewritten, `rewritten` lists the files; an open document follows the new id), `project.removeUi {id, confirm, discard?}` (destructive: `confirm: true` after asking; files stay on disk; the UI on screen is refused, switch first; an open background UI with unsaved edits needs `discard` -> else `kUnsavedChanges`; the last UI is refused), `project.set {name?, game?, safeArea?: {default?, console?}, uiscale?: {rule?, logicalHeight?}, clamp?: [min, max|null] | null, dpiFloor?, responsive?: {scale?, position?, visibility?}, input?: {methods?, players?}, languages?, budget?: {frameMs?, effectLayers?, fillRate?, particles?}, engine?: {name?, version?}, platforms?: [{name, resolutions?: [[w, h]]}], fontFallback?: {<lang>: [families]}}` (the project tab's form; every field checked -- safe areas 0..0.5, logicalHeight 1..16384, dpiFloor 0..16, players 1..64, budgets >= 0, `scale` auto/none/clamp(a, b), resolutions 1..16384 -- and nothing written when one is wrong; `platforms` and `fontFallback` replace the whole list / all chains; returns the settings), `project.setAgents {text}` (replaces `AGENTS.md`), `conventions.put {kind: motion | layout, id, body, confirm?}` (`motion`: sets key `id` of `contracts/motion-spec.yaml` to `body`, key order and leading comments kept; `layout`: writes `conventions/layouts/<id>.xt` from the `.xt` text `body`, which must parse; replacing an existing template needs `confirm: true`). These write files, not undo steps |
106
+
107
+ **Editor-only reference layers.** A layer that only helps while designing (a reference image,
108
+ a guide) carries the `editor-only` attribute: the editor shows it, a publish drops it.
109
+
110
+ ```
111
+ layer_setAttrs {"layer": "RefShot", "attrs": {"editor-only": ""}} null removes it again
112
+ ```
113
+
114
+ **Locked layers (26.1.4).** `layer.setFlags {layer, hidden?, locked?, solo?, color?, collapsed?, adjustHidden?}`
115
+ writes the editor's sidecar (`<ui>.xteditor.json`): `color` is a tag 0-7 (null clears it);
116
+ `adjustHidden` is the eye of a group's adjustment layer (46 §46.7: the preview draws the group
117
+ without its composite styles -- opacity, blend, clip, effects; the file and a publish keep them). It is
118
+ not a document edit -- no undo step, no new `revision` -- but it counts as a write of your work
119
+ item (`touched`). A layer the user locked, or any layer inside it, refuses every write
120
+ (`layer.setProps`, `layer.setAttrs`, `layer.create` under it, ...) with `kForbidden`: "layer
121
+ '<id>' is locked: layer.setFlags {layer, locked:false} first". Unlock only when the user asked
122
+ for the change on that layer, and say so in the report; `layer.setFlags` itself is never refused
123
+ by a lock. `layer.get` returns the flags.
124
+
125
+ `layer.setProps` writes the layer's own `#id` rule (or, with `state`, its `:hover`/`:state()`
126
+ rule). While the work site's `animate` is on (the user's Animate switch, or yours through
127
+ `session.setView`), it records like the user's edits do: each animatable property (normal state)
128
+ becomes a keyframe at the playhead in the active timeline (none selected in the current scope:
129
+ `root-anim` / `<symbol>-anim`, created at 2 s), the rest is written as usual, one undo step;
130
+ `notes` says `recorded into <timeline>@<t>`. Values are CSS as in the `.xts` (`"background-color": "var(--color-accent)"`). Prefer a
131
+ token (`var(--x)`) over a literal colour: the lint reports literals. `style.setRule` takes the
132
+ same values for class and state selectors (`.card`, `.card:hover`).
133
+
134
+ The 3D panel's "World layer" switch is the style property `world-layer` (`off` | `on`): set it
135
+ with `layer.setProps {layer, props: {"world-layer": "on"}}` and remove it with `null` (what
136
+ unchecking does). It only matters on a host that shows the UI in layers (the layer and its subtree
137
+ become one layer of their own); every flat view ignores it. It is not animatable: never key it.
138
+
139
+ ## `.xts` value rules
140
+
141
+ `layer.setProps`, `style.setRule` and `state.*` check what they write (T-355): an unknown
142
+ property name is refused (`unknown property '<name>'`, with a hint); a `url()` must name an
143
+ existing file; a value the compiler rejects, or newly warns about for that property, is rolled
144
+ back (`the edit breaks the compile; rolled back` / `rolled back: <warning>`) and the document stays
145
+ as it was. Read the message, fix the value and call again. An `@media` query the compiler does not
146
+ know (only `min-`/`max-width`/`-height`, `aspect-ratio >=`/`<=`, `orientation`, `resolution`,
147
+ `platform`, `input` and `prefers-reduced-motion`; `aspect-ratio` takes `<=` / `>=`, not a colon:
148
+ `(aspect-ratio <= 4/3)`) is rolled back the same way, the message naming the query. So:
149
+
150
+ - **Names** (layer ids, symbol, timeline and state names): `[A-Za-z][A-Za-z0-9_-]*`, starting with
151
+ a letter, not ending in `-`.
152
+ - **Images**: `background-image: url("../shared/img/x.png")` -- the URL **in quotes** (an unquoted
153
+ one containing `/` fails) and relative to the `.xt` file, not to the project.
154
+ - **Effects**: XTFrame has no `filter` or `text-shadow` in `.xts`. Write `effect:` (box level:
155
+ `effect: shadow(0 4px 12px #00000040) blur(4px)`, `backdrop-blur(...)`, `outline(...)`) and
156
+ `text-effect:` (glyph level: `text-effect: outline 2px #000, shadow 1px 2px 3px #f00`,
157
+ `glow 4px #ffd000`). The importer converts the CSS forms; the editor does not.
158
+ - **Show / hide from data**: any non-shorthand property can be a binding target, so a flag shows or
159
+ hides a layer with `bind.set {layer, target: "display", expr: "flag | select(true: block, false:
160
+ none)"}` (written `bind:display="flag | select(true: block, false: none)"`), not only through
161
+ `visibility`.
162
+
163
+ ## Style stack (`style.*Style*`, 46 §46.8)
164
+
165
+ The Properties panel shows an element as a stack of units: position & size (fixed), the styles
166
+ (groups of CSS properties: `autolayout`, `fill`, `stroke`, `corner`, `image`, `text`, `outline`,
167
+ `vector`, `particles`, `interaction`, `responsive`, `opacity`, `clip`, `clip-media`, `space3d`),
168
+ the effect sequence and the modifiers. Nothing is stored: a style is present when the element's
169
+ effective declarations name one of its properties. The resource `xtui://style-groups.json` lists
170
+ every group's CSS properties, parameter names and defaults. Talk to the user in style names; the
171
+ file still holds CSS.
172
+
173
+ | Operation | Does |
174
+ |---|---|
175
+ | `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) |
176
+ | `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 |
177
+ | `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) |
178
+ | `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) |
179
+ | `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 |
180
+ | `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 |
181
+ | `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 |
182
+ | `layer.removeAdjustment {target}` | removes every composite style and the effect sequence from a group layer's own rule |
183
+
184
+ Parameter names are the group's, not the CSS names (`width` of `stroke` is `border-width`; the
185
+ `xtui` skill's `references/style-groups.md` and the resource list them all). Minimal calls:
186
+
187
+ ```
188
+ style_styles {"target": "Health_Bar"} -> units: placement, fill, stroke, ...
189
+ style_addStyle {"targets": ["Btn_1", "Btn_2"], "group": "stroke"}
190
+ style_removeStyle {"target": "Btn_1", "group": "corner"}
191
+ style_setStyleParams {"target": "Btn_1", "group": "stroke", "params": {"width": "2px", "color": "var(--border)"}}
192
+ style_setStyleParams {"target": "Btn_1", "group": "opacity", "params": {"opacity": "0.8", "mixBlendMode": "screen"}}
193
+ style_copyStyles {"targets": ["Btn_1"], "groups": ["stroke"]} -> payload (the JSON below)
194
+ layer_addAdjustment {"target": "Group_3", "group": "opacity"}
195
+ layer_removeAdjustment {"target": "Group_3"}
196
+ layer_setFlags {"layer": "Group_3", "adjustHidden": true} preview without the adjustment
197
+ ```
198
+
199
+ `style.pasteStyles` takes the clipboard JSON of the stack panel (46 §46.6) as an object or as its
200
+ text; `mode: "paramsOnly"` is the panel's Alt+Ctrl+V:
201
+
202
+ ```
203
+ style_pasteStyles {"targets": ["Btn_2", "Btn_3"], "mode": "merge", "payload":
204
+ { "xtframe": "styles", "v": 1,
205
+ "items": [
206
+ { "kind": "style", "group": "stroke", "decls": { "border-width": "2px", "border-color": "var(--border)" } },
207
+ { "kind": "effect", "effect": "shadow(0 4px 12px #00000040) glow(6px var(--accent))" },
208
+ { "kind": "modifier", "xml": "<xt-round radius=\"6\"/>" } ] }}
209
+ ```
210
+
211
+ Inside an item the declarations are CSS (`decls`), as copied; a `modifier` item lands only on a
212
+ vector group (others: skipped, see `notes`). There is no operation to reorder styles: the order of
213
+ the styles section is fixed by the group table.
214
+
215
+ ## Symbol libraries (`symbols.*`, 49 §49.7)
216
+
217
+ A **library** is a directory of **groups** (`library.json`, `groups/<id>/` with `group.json`,
218
+ `index.json`, the `.xt` files, `tokens.xts`, theme files, `fonts/`, `textures/`, `thumbnails/`); the
219
+ editor mounts the presets (read-only, id `preset`, default group `broadsheet-2026`), the user's own
220
+ library (`mine`), the extra libraries of the user's mount list and the open project's
221
+ `shared/symbol-library/`. A group travels as a **set** (`.xtsymbols`, a stored zip of the same tree
222
+ plus `set.json` with author, version and licence). A project never links a library file: it holds
223
+ **copies** (49.3), made by the project writes below and recorded in `shared/symbols/index.json`.
224
+
225
+ - **Reads** (any scenario): `symbols.libraries`, `symbols.library {library?}`, `symbols.get {name,
226
+ group?, library?}`, `symbols.lint {group? | library? | path?}` -- the Read table above.
227
+ - **Project writes** (`create`, `restyle`, `repair-import`, `single-element`; one undo step of
228
+ `ReplaceSharedFile` steps on the active document's stack, so `undo` and a checkpoint rollback take
229
+ them back): `symbols.use {names, group?, library?}` copies each symbol's file to
230
+ `<shared.symbols>/<Name>.xt` (an existing copy is kept and reported in `skipped`), its fonts and
231
+ textures to the asset root (same content skipped, other content under a hashed name, `renamed`),
232
+ appends the tokens it reads that `shared.tokens` lacks with the group's defaults (`tokensAdded`,
233
+ theme values to the theme files) and records the source; a name no library has fails the whole call
234
+ with `kNotFound` and nothing is written. `symbols.useGroup {group, library?}` is `use` for every
235
+ symbol of the group (call it before building a UI from that group). `symbols.updateCopy {name}`
236
+ writes the library's file over the project's copy (fonts and textures by the same rules, the
237
+ project's token values kept) -- only on the user's word: `project.syncSymbols` shows which copies
238
+ are `outdated` or `modified`, you **suggest**. Replies: `{status, written, skipped, renamed,
239
+ tokensAdded, notFound, changes}`.
240
+ - **Library writes** (the `library` scenario; `kPermissionDenied` until the user allows them):
241
+ `symbols.saveAsGroup {names, groupId, name, library?}` turns project symbols into a new group of a
242
+ writable library (tokens, fonts, textures, themes collected the reverse way; `{groupId, library,
243
+ lint}`); `symbols.loadPreset {group, keepOld?}` copies the installed preset group over the user
244
+ library's (the old one to `.trash/`, `trashed`; `keepOld` keeps it as `<id>@<version>`);
245
+ `symbols.import {path | url, library?, as?, replaceOlder?}` imports a set (`.xtsymbols` or a set
246
+ directory; a `url` must be `https://`, the editor downloads it -- 64 MB, 60 s -- and the reply has
247
+ `downloaded {bytes, sha256}`), every check before anything is written, per group `action` =
248
+ `added` | `updated` (old one in `.trash/`) | `unchanged` | `older-skipped` (`replaceOlder` replaces)
249
+ with its `lint`; `symbols.export {group, library?, out, author?, license?, fonts?}` writes a set
250
+ (`out` ending in `.xtsymbols` is the archive, else a set directory); `symbols.mountLibrary {path}` /
251
+ `symbols.unmountLibrary {id}` change the user's mount list (the presets, `mine` and the project
252
+ library cannot be unmounted). The default library of a write is the first writable one (`mine`).
253
+ - **Permission.** Libraries are shared by every project and permanent, so the library writes answer
254
+ `kPermissionDenied` ("library writes need the \"Allow AI to change symbol libraries\" preference
255
+ or a one-time approval") for an AI client until the user allows them: the editor asks once per
256
+ client (allow this time / always / deny) when the first one is refused; only the user grants it,
257
+ never the client itself. Wait for the user; never write library files yourself.
258
+ - **Resources** (MCP): `xtframe://symbols/library` (= `symbols.library`),
259
+ `xtframe://symbols/<library>/<group>/<Name>` (= `symbols.get`).
260
+
261
+ **Build a HUD from a group**
262
+
263
+ ```
264
+ symbols_libraries -> symbols_library {"library": "mine"} which groups, their lint state
265
+ session_setScenario {"name": "create"} -> checkpoint_begin {"scenario": "create"}
266
+ symbols_useGroup {"group": "broadsheet-2026"} copies, tokens, index.json; one undo step
267
+ symbol_instantiate {"symbol": "HealthBar", "parent": "Hud", "source": "project", "ifRevision": 41}
268
+ ```
269
+
270
+ **Import a set the user handed you**
271
+
272
+ ```
273
+ symbols_lint {"path": "C:/sets/neon.xtsymbols"} set {author, license, fontsLicense, version}, groups[].issues
274
+ -> show licence and findings, ask
275
+ session_setScenario {"name": "library"}
276
+ symbols_import {"path": "C:/sets/neon.xtsymbols"} (kPermissionDenied: the editor is asking the user; wait)
277
+ -> groups[].action, lint; then symbols_useGroup in a create scenario when the user wants it in the project
278
+ ```
279
+
280
+ ## Effect catalog (`catalog.*`, 46 §46.13)
281
+
282
+ The editor's **+ Add effect** button opens one catalog, in the artist's words: appearance (fill,
283
+ stroke, corners, focus ring, image fit), effects (drop shadow, glow, blur, frosted glass, shine,
284
+ color adjust, gradient fade, outline), compositing (clip shape, opacity & blend), text (text
285
+ effect, text reveal, decoration) and, on vector layers, the shape modifiers. Each entry adds a
286
+ **visible default**, so the change shows at once (a stroke contrasts with the fill; a glow uses the
287
+ `accent` token). The resource `xtui://effect-catalog.json` lists every entry (id, names en / zh,
288
+ one-line blurb, target, visible default); talk to the user in these names.
289
+
290
+ | Operation | Does |
291
+ |---|---|
292
+ | `catalog.list {target?}` | `entries: [{id, category, name: {en, zh}, blurb: {en, zh}, target}]`; with `target`, only the entries offered for that layer's role (text entries on text layers, shape entries on vector layers), each with `presence`: `absent`, `present` (a style the layer shows already; an effect or modifier of that kind is there) or `full` (an effect while the effect chain holds 16) |
293
+ | `catalog.add {target \| targets, id}` | adds the entry to each layer, one undo step: a style writes its visible default into the layer's own rule (`kNotFound` when every layer has it already), an effect goes to the end of the effect chain (repeatable), a modifier to the end of the vector group; a `shader:<name>` example is copied to `<assetRoot>/fx/` and appended as `custom("…")` (the document must be saved). `custom`, `custom-new` and effect templates are not added here (`fx.apply` for templates) |
294
+
295
+ ```
296
+ catalog_list {"target": "Btn_1"} -> entries with presence
297
+ catalog_add {"targets": ["Btn_1", "Btn_2"], "id": "shadow"}
298
+ catalog_add {"target": "Logo_Path", "id": "mod:xt-round"}
299
+ ```
300
+
301
+ ## Vector layers (`vector.*`, 31 §31.10)
302
+
303
+ An inline `<svg>` is a vector layer, and its shapes are addressed as `<svg id>/<shape id>`
304
+ (`Icon/Ring`).
305
+
306
+ - `vector.get {layer, normalize?}` returns `{svg: {id, viewBox, w, h}, shapes: [{id, kind, d?,
307
+ params?, fill, stroke, strokeWidth, fillRule, opacity, vertices?, contours?, appearance, width,
308
+ corners, modifiers, skin?}], skeletons}`; `appearance` is `{fillOpacity, strokeOpacity,
309
+ strokeLinecap, strokeLinejoin, strokeMiterlimit, strokeDasharray, strokeDashoffset, fillPaint,
310
+ strokePaint}` (a paint is `{mode: none|solid|linear|radial, color?, p0?, p1?, stops?: [{offset,
311
+ color}]}`, null when unset), `width` is `{taperStart, taperEnd, profile: [{t, w}]}`, `corners`
312
+ are the rounded corners `[{vertex, radius, corner}]` (`vertex` = flat index) and `modifiers` the
313
+ stack of the shape's group `[{id, kind, enabled, baked, params}]` (kind trim | repeat | round |
314
+ pucker | zigzag | twist | wiggle | offset | merge); `skin` (skinned shapes only) is `{skeleton, vertices, bones: [{bone, weight}]}` with
315
+ each bone's average weight, `skeletons` is `bone.list`'s tree.
316
+ `vertices` / `contours` hold `{p: [x, y], in, out, type}` with the handles relative to `p`, and
317
+ `type` is corner | smooth | symmetric | auto. `normalize: true` also expands the parametric
318
+ shapes (rect, circle, star...).
319
+ - `vector.set {layer, svg}` replaces the whole content with SVG text. It is the cheapest way to
320
+ draw. Unsupported elements come back in `skipped[]`.
321
+ - `vector.set {layer, shapes: [...]}` upserts shapes by id: `d` or `vertices`, `params`, `fill`,
322
+ `stroke`, `strokeWidth`. A `var(--x)` colour becomes the `.xts` rule `#Svg/Shape { fill:
323
+ var(--x); }`. It also takes back what `vector.get` returns (T-370): `appearance` (only the fields
324
+ given; a paint writes a gradient as the panel does), `width`, `corners: [{vertex, radius}]`
325
+ (radius 0 = sharp; a `<path>` only) and `modifiers` (replaces the stack of the shape's group:
326
+ listed ids keep their place, new ones are appended, unlisted ones go), so a look no longer needs
327
+ a whole-layer `svg` rewrite.
328
+ - `vector.editPath {shape, ops}` applies ops in order: `insert {seg, t}`, `delete {index}`,
329
+ `move {index, p, in?, out?}`, `setType {index, type}`, `close`, `open`, `reverse`,
330
+ `setFirst {index}`. Each op may name a `contour`.
331
+ - `vector.boolean {shapes, op}`: op is union | subtract (the first minus the rest) | intersect |
332
+ exclude | divide, and the shapes must be in one layer. The result keeps the topmost shape's id
333
+ and look.
334
+ - `vector.bake {layer, shape?}`: parametric shapes (or only `shape`) become `<path>`s.
335
+ - `vector.shapeOp {layer, shape?, op}` runs the editor's Object menu / node tool command (one undo
336
+ step): `outlineStroke`, `simplify {tolerance}`, `offset {distance, join?}`, `flatten`, `toPath`
337
+ (on `shape`, or every shape of the layer when omitted; the ones it does not apply to come back in
338
+ `skipped[]`), `flipH` / `flipV` (each shape about its own center), `merge {layers}` (other vector
339
+ layers move into `layer`), `split` (each top-level shape / group gets its own layer), `join
340
+ {points: two open end points}`, `break {point}`, `dissolve {points}` (points are `{contour?,
341
+ index}` as in `contours`; `d` keys of the same topology follow). The box is not refitted.
342
+ - `vector.textToOutlines {layer}` turns a text layer into a vector layer of glyph paths
343
+ (`<id>_g<n>`); `vector.extract {layer, path?}` writes the layer as a standard `.svg` (default
344
+ `shared/img/<id>.svg` of the project, registered in the asset manifest) and replaces it by an
345
+ `<img>`.
346
+ - `vector.morph {shape, action: setFirst, index}` moves the start vertex (keys follow);
347
+ `vector.morph {shape, action: equalize}` gives every `d` keyframe of the shape the same contours,
348
+ closed flags and vertex counts (longest segments split) and returns `{added, keys}`.
349
+
350
+ **Topology mismatch.** `vector.editPath` edits the shape and every `d` keyframe of that shape
351
+ (the `@timeline` track `d`) that has the same topology: the same contours, vertex counts and
352
+ closed flags. A `move` shifts each keyframe's vertex by the same delta. Keyframes with another
353
+ topology are left alone and listed in `skippedKeys: [{timeline, t}]`. Then either:
354
+
355
+ 1. Run `vector.morph {shape, action: equalize}` (lint `vector.morphTopology` lists such tracks),
356
+ 2. Rewrite those keys with `timeline.setKeyframe` so that every key has the same vertex count
357
+ (insert the matching vertices), or
358
+ 3. Remove them and re-key from the edited shape.
359
+
360
+ Never leave a `d` track with mixed topologies: the morph snaps instead of interpolating.
361
+
362
+ ## Rigs (`bone.*`, `constraint.*`, `skin.*`, `mesh.*`, 32 §32.5)
363
+
364
+ A skeleton (`<xt-skeleton>`) lives inside a vector layer; its bones bend the `<path>`s and
365
+ `<xt-mesh>`es skinned to it. Bones, constraints, shapes and meshes are addressed like shapes:
366
+ `<svg id>/<id>` (`Mascot/Head`) or a bare id that is unique in the document. Every edit is one
367
+ undo step. Coordinates are the `<svg>`'s group space unless said otherwise; angles are degrees,
368
+ positive turns clockwise (y down).
369
+
370
+ Pose vs rest (T-249): a bone's `rotate` / `translate` / `scale` / `length` are its **static pose**
371
+ (what it shows and starts at); `rest-rotate` / `rest-translate` / `rest-scale` / `rest-length` are
372
+ its **bind pose** (each defaults to the posed value). Shapes deform by pose x inverse(rest), so
373
+ posing a bound skeleton bends its shapes; binding writes the rest from the current pose.
374
+
375
+ | Operation | Arguments | Does / returns |
376
+ |---|---|---|
377
+ | `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 |
378
+ | `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}` |
379
+ | `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) |
380
+ | `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 |
381
+ | `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`) |
382
+ | `bone.resetToRest` | `skeleton` | every bone's static pose back to its rest; returns the skeleton as in `bone.list` |
383
+ | `bone.setRestFromPose` | `skeleton` | every bone's rest set to its static pose (bound shapes re-bind at the pose, weights unchanged); returns the skeleton |
384
+ | `bone.world` | `bone` | the evaluated pose after constraints and springs: `{origin, tip, angle, length}` in viewport coordinates, `local {origin, angle}` in group space |
385
+ | `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) |
386
+ | `constraint.set` | `constraint`, `attr`, `value` (`""` removes it) | a parameter, `space` or `target` (`#id`); the kind cannot change |
387
+ | `constraint.remove` | `constraint` | |
388
+ | `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) |
389
+ | `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`) |
390
+ | `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 |
391
+ | `skin.unbind` | `shape` | removes `xt-skin` and the weights |
392
+ | `skin.smooth` | `shape`, `iterations` (1..100) | each vertex averaged with its neighbours (path: previous / next vertex; mesh: pins sharing a triangle) |
393
+ | `skin.prune` | `shape`, `threshold` (0..1) | drops weights below it (each vertex keeps its heaviest), renormalizes |
394
+ | `mesh.pins` | `mesh` | `{href, pins: [[x, y]], tris: [i...], skin}` |
395
+ | `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}` |
396
+ | `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}` |
397
+
398
+ Vertex numbers are the editor's vertices of the path, contour by contour (the order of
399
+ `vector.get`'s `contours`); a closed contour that ends on its start point does not count that end
400
+ twice. Pins are numbered in `<xt-pins>` order and live in the mesh's local space (under its
401
+ `transform`). A pin's texture coordinate is (pin - (x, y)) over the mesh `width` / `height`
402
+ (clamped to the image). To deform an image: `mesh.convert`, add pins
403
+ where it should bend with `mesh.setPins` (the old pins first, in order), then `skin.bind`.
404
+
405
+ Errors: an unknown bone / constraint / skeleton / bone name in weights is `kNotFound`; a weight
406
+ outside 0..1 or a vertex index past the end is `kOutOfRange`; `auto` values outside their range,
407
+ `translate` on a child bone, a target missing on ik / transform / rotation, or a shape that cannot
408
+ be skinned is `kInvalidArgument`.
409
+
410
+ `lint.run` includes the rig rules: `skin.weightsStale` (weights no longer match the vertices or
411
+ bones), `skin.budget` (over 10k skinned points, 128 bones, 64 springs, an IK chain over 8),
412
+ `skin.ownTransform` (a skinned shape's own transform is animated: animate the bones),
413
+ `mesh.degenerate` (a triangle under 0.01 px^2: move or remove a pin), `mesh.pinOutside` (info: a
414
+ pin more than 10% outside the image). `export.lottie` bakes skinned paths per frame (`baked[]` reports
415
+ `vector.bakedFrames`), bakes elements bound to a bone port as per-frame transforms, and skips
416
+ meshes (`lottie.unsupported: mesh`).
417
+
418
+ ## Cel animation (`cel.*`, 31 §31.7.5)
419
+
420
+ A layer with `data-xt-cels="1"` is a cel group: its child layers, in document order, are cels
421
+ 0..N-1 and one cel shows at a time. Cel i is visible during `[start_i, end_i)`, written as
422
+ `visibility` hold keyframes (`steps(1, end)`) of each cel on the selected timeline of the group's
423
+ scope, else `root-anim` / `<symbol>-anim` (created at 2 s). There is nothing else to keep in step:
424
+ the runtime only sees `visibility` keys. Indexes are 0-based, times are seconds, one frame
425
+ (1 / fps, fps = the motion spec's `fps`, else 24) is the shortest cel. Inside a vector layer the
426
+ group is addressed `<svg id>/<g id>` when it is not the `<svg>` itself.
427
+
428
+ - `cel.list {group}` returns `{group, scope, timeline, fps, written, cels: [{index, id, track,
429
+ start, end, frames}]}`. `written: false` means no cel has frames yet: the cels share the
430
+ timeline length equally until the first edit writes them.
431
+ - `cel.add {group, after?, duplicate?}` adds a cel after cel `after` (default: the last). With
432
+ `duplicate` (default true) it is a copy of that cel with fresh ids (`Cel_n`); otherwise an empty
433
+ `<g>` (vector group) or `<div>`. It takes the length of cel `after`; later cels shift and a
434
+ written timeline duration grows. `added` is the new cel's id.
435
+ - `cel.setRange {group, index, start, end}` moves the cel's start (the boundary shared with the
436
+ previous cel) and end (shared with the next); neighbours follow, each keeps one frame.
437
+ - `cel.remove {group, index, confirm}` deletes cel `index` (its layer and frames); its time goes to
438
+ the previous cel (the next one for cel 0). `removed` is the deleted cel's id.
439
+ - `cel.convert {group}` makes the layer `group` with child layers (it needs an id) a cel group: unnamed
440
+ children get names and equal ranges over the timeline length. Replies like `cel.list`.
441
+
442
+ To draw a new cel, `cel.add` a copy, then edit its shapes with `vector.set` / `vector.editPath`
443
+ (`<svg id>/<shape id>` of the copy's new ids, from `vector.get`). `lint.run` reports
444
+ `cels.missingFrames` (info) for cels without frames.
445
+
446
+ ## Intent (one call = one macro = one undo step; follow the motion spec)
447
+
448
+ | Operation | Does |
449
+ |---|---|
450
+ | `animate.entrance {layers, style?, duration?, stagger?, delay?, timeline?}` | an `intro` timeline: `fade`, `rise` or `scale`, staggered within the spec |
451
+ | `animate.exit {layers, style?, ...}` | an `outro`: `fade`, `sink` or `scale` |
452
+ | `animate.emphasis {layers, kind, duration?, timeline?}` | `pulse`, `shake` or `glow` |
453
+ | `layout.anchor {layers, template, margin?}` | anchors to the safe area by template: `hud-corners`, `menu-list`, `inventory` |
454
+ | `restyle {tokens}` | many token values at once (a new palette, a mood) |
455
+ | `fx.apply {layers, template}` | an effect template (`shared/fx/*.xtfxp`) |
456
+ | `state.apply {target, state, diff}` | a whole state look at once (a layer, or a symbol: `<inner>.<prop>` keys) |
457
+ | `wire.port {layer, prop, port, converters?, type?}` | declares the port if needed and binds it |
458
+ | `repair.import {report?}` | the import report's fixable warnings: names, anchors, states |
459
+ | `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) |
460
+ | `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 |
461
+ | `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[]` |
462
+ | `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`) |
463
+
464
+ ## Diagnostics (24 §24.15: the import's problem list)
465
+
466
+ 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`).
467
+
468
+ | Operation | Does |
469
+ |---|---|
470
+ | `diagnostics.list {ui?}` | the project's list (or one UI's); items carry `index`, `accepted` (from the UIs' `.xteditor.json`), plus `counts` |
471
+ | `diagnostics.accept {code, element, detail?, message?, ui?}` | records the difference in the UI's `.xteditor.json` `diagnostics.accepted[]`; not listed again on later imports |
472
+ | `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 |
473
+
474
+ The result of an intent operation lists `expanded[]`, the low-level operations it performed.
475
+
476
+ ## Feedback
477
+
478
+ | Operation | Use |
479
+ |---|---|
480
+ | `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 |
481
+ | `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 |
482
+ | `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` |
483
+ | `perf.probe {frames?}` | frame time, workload, fill rate, % of budget |
484
+ | `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) |
485
+ | `scenario.check {name?}` | the active contract's `done_when`, pass/fail per item |
486
+
487
+ ## Bookkeeping
488
+
489
+ `scenario.list`, `session.setScenario {name, root?, entry?, explore?, rollback?}` (starts a work
490
+ item on the main line; `explore: true` runs it on a variant of its own instead; see SKILL.md "Work
491
+ items"), `session.endScenario` (ends the work item: saves, runs the gates when it wrote anything and
492
+ returns `{empty, touched?, gates: {lint: {errors, warnings}, contract: {ok, violations}},
493
+ checkpoint}`; nothing written -> `{empty: true}`; idempotent; without a scenario it ends the work item
494
+ of your writes, see below), `session.getScope` (scope, scenario,
495
+ budget used, your `seat {id, name, kind}`), `session.setScope {mode, root?}` (only without a
496
+ scenario), `checkpoint.begin {scenario}`, `checkpoint.commit {id}`, `checkpoint.rollback {id}`,
497
+ `checkpoint.list`. T-366: with project history (`.xtvc`) `checkpoint.begin` saves the open
498
+ documents and also sets a history checkpoint named `ai/<scenario>/<n>` by your seat (reply `history`:
499
+ its slug); the user sees it in the History panel and it stays after you leave. `history.checkpoint`
500
+ and `history.variant` are written by your seat. Leaving an explore variant with `rollback: true`
501
+ fails with `kUnsavedChanges` while it holds someone else's unsaved edits (yours are dropped).
502
+ T-367 (37.8.1 D5): writes **without** a scenario are a work item too -- it starts with your first
503
+ write and ends at your `doc.save` (its reply lists the ended items in `workItems`), your next
504
+ `session.setScenario` / `session.endScenario`, or when you disconnect; with history it leaves the
505
+ checkpoint "<seat> · HH:MM" (note `scenario: ""`, lint gates). The user's own edits are work items
506
+ of the user's seat the same way (ended by a save, 30 idle minutes, or your `session.setScenario`,
507
+ which first closes the user's item); `touched` records track layers of `timeline.*` in every scope,
508
+ the selector of `style.setRule`, the token of `style.setToken` and `flow` for `flow.set`.
509
+
510
+ `session.setView {selection?, timeline?, animate?, space?, device?, zoom?, pan?, editInPlace?}`
511
+ changes the work site (not an edit, no undo step) and replies with the whole view like
512
+ `session.getView`: `selection` (layer paths, `[]` = none), `timeline {scope?, name?, playhead?,
513
+ loop?: {start, end}, onion?: {before?, after?, mode?: frames|cels}}` (`name` must exist; `""`
514
+ selects none), `animate` (the Animate switch), `space` (Canvas, Code, Flow, Project, Demo), `device` (a
515
+ preset or `"W:H"`), `zoom` (<= 0 = fit), `pan` `[x, y]`, `editInPlace` (a symbol instance, `""`
516
+ leaves). In the editor it shows at once and the status bar says "<seat> selected N layers" /
517
+ "<seat> switched to timeline <name>" for three seconds; a headless editor keeps it (`timeline`,
518
+ `device`, `zoom`, `pan` in the UI's sidecar, the rest for your seat). `vector`, `safeArea` and `fit`
519
+ are read-only. A scenario whose scope is one layer (`subtree`, `selection-or-named`) started
520
+ without `root` works on the work site's selection (its primary layer; reply `rootFrom: selection`);
521
+ with nothing selected `selection-or-named` is the full scope.
522
+
523
+ History (36; `kUnsupported` when the project has no `.xtvc`): `history.status`,
524
+ `history.list {kind: checkpoints|variants|log, ref?, limit?}`, `history.checkpoint {name, note?}`,
525
+ `history.variant {name, from?}`, `history.switch {to, discard?}`, `history.compare {a, b}` are
526
+ yours (outside a scenario). `history.restore {checkpoint}` (main goes back to a checkpoint; the
527
+ line left behind is kept as a variant) is open to every seat since T-372 -- call it only when the
528
+ user asked for exactly that. `history.adopt {variant}` and `history.prune {variants, confirm}` are
529
+ **gates** (37.8.1 D1): `kForbidden` ("human-only ... unless a person makes its seat a steward")
530
+ unless the user made your seat a **steward** -- with "Allow as steward" on the knock bar, the AI
531
+ panel's "Allow adopt and approve", or `{"name": "<your seat>", "steward": true}` in the project's
532
+ `.xtcache/agents.json` (never edit that file yourself). A steward's call replies `asSteward: true`
533
+ and `steward: "adopted by <seat> (steward): <variant>"`; the history gets a commit with that message
534
+ by your seat, and your work item's checkpoint note lists it under `steward`. Even as a steward,
535
+ adopt or prune only when the user asked for it, outside a scenario (no contract allows them), and
536
+ say so in the report. Over MCP these tools are listed with "[Human-only gate ...]" in their
537
+ description.
538
+ T-261b: `checkpoint.rollback` is an edit. Your own checkpoint (one this client began) rolls back under
539
+ any scope or scenario while every change to the document since it began is your own (T-261c: no
540
+ edit, undo or redo by a human or another client, no file written by another client, the document
541
+ not replaced or switched); otherwise it needs the `full` scope and a scenario that lists it, and the
542
+ refusal ends with `; the document was edited by someone else since this checkpoint began` when that
543
+ is the reason.
544
+
545
+ ## Sequences
546
+
547
+ **Recolour one button with a token**
548
+
549
+ ```
550
+ session_setScenario {"name": "single-element", "root": "BtnPlay"}
551
+ checkpoint_begin {"scenario": "single-element"}
552
+ doc_status {} -> revision 41
553
+ layer_setProps {"layer": "BtnPlay", "props": {"background-color": "var(--color-accent)"}, "ifRevision": 41}
554
+ lint_run {"scope": "BtnPlay"} -> scene_screenshot {"scope": "BtnPlay"}
555
+ ```
556
+
557
+ **Entrance animation for a menu**
558
+
559
+ ```
560
+ session_setScenario {"name": "add-animation", "root": "Menu"}
561
+ checkpoint_begin {"scenario": "add-animation"}
562
+ animate_entrance {"layers": ["Title", "MenuList"], "style": "rise", "ifRevision": 41} -> revision 42
563
+ trigger_set {"layer": "Menu", "event": "show", "actions": "play(intro)", "ifRevision": 42}
564
+ lint_run -> scene_screenshot {"timeline": "intro", "times": [0, 0.15, 0.4]}
565
+ ```
566
+
567
+ **Hover and pressed states**
568
+
569
+ ```
570
+ session_setScenario {"name": "states-interaction", "root": "BtnPlay"}
571
+ checkpoint_begin {"scenario": "states-interaction"}
572
+ state_apply {"target": "BtnPlay", "state": "hover", "diff": {"background-color": "var(--color-accent-hover)"}, "ifRevision": 41}
573
+ state_apply {"target": "BtnPlay", "state": "pressed", "diff": {"background-color": "var(--color-accent-pressed)"}, "ifRevision": 42}
574
+ scene_screenshot {"scope": "BtnPlay", "state": {"layer": "BtnPlay", "state": "hover"}}
575
+ ```
576
+
577
+ **Wire a health bar to the game**
578
+
579
+ ```
580
+ session_setScenario {"name": "data-binding", "root": "HpBar"}
581
+ checkpoint_begin {"scenario": "data-binding"}
582
+ wire_port {"layer": "HpFill", "prop": "width", "port": "hp", "type": "number",
583
+ "converters": ["range(0,hp_max,0%,100%)"], "ifRevision": 41}
584
+ port_set {"layer": "body", "name": "hp_max", "type": "number", "ifRevision": 42}
585
+ lint_run (lint.portUnbound must be clean)
586
+ ```
587
+
588
+ In source format 2 the document's ports live in `<ports>`, reached as the layer `body` (a format 1
589
+ document may declare them on its top layer, e.g. `Hud`); `wire_port` with `type` declares `hp` there too.
590
+
591
+ **Mascot idle (bones, auto weights, two poses, an IK)**
592
+
593
+ ```
594
+ session_setScenario {"name": "add-animation"}
595
+ checkpoint_begin {"scenario": "add-animation"}
596
+ bone_add {"layer": "Mascot", "length": 60, "rotate": -90, "translate": [100, 180], "id": "Spine", "ifRevision": 41}
597
+ bone_add {"layer": "Mascot", "parent": "Spine", "length": 40, "rotate": 0, "id": "Head", "ifRevision": 42}
598
+ skin_bind {"shape": "Mascot/Body", "skeleton": "Rig", "ifRevision": 43}
599
+ bone_pose {"bone": "Mascot/Head", "rotate": -8, "time": 0, "ifRevision": 44}
600
+ bone_pose {"bone": "Mascot/Head", "rotate": 8, "time": 1, "ifRevision": 45}
601
+ lint_run -> scene_screenshot {"timeline": "main", "times": [0, 0.5, 1]}
602
+ ```
603
+
604
+ **Clean up after an import**
605
+
606
+ ```
607
+ session_setScenario {"name": "repair-import"}
608
+ checkpoint_begin {"scenario": "repair-import"}
609
+ repair_import {"ifRevision": 41}
610
+ layout_anchor {"layers": ["HpPanel", "Ammo"], "template": "hud-corners", "ifRevision": 42}
611
+ lint_run -> scenario_check
612
+ ```
613
+
614
+ Then, every time: `session_endScenario` (read its `gates`; fix until lint has no error), the
615
+ three-list report and `checkpoint_commit` or `checkpoint_rollback` on the user's word (SKILL.md
616
+ sections 4 and 5).
617
+
618
+ **Change another UI without moving the user's view**
619
+
620
+ ```
621
+ doc_open {"path": "PauseMenu"} your active document now; the GUI stays
622
+ doc_status {} revision, modified, diskNewer
623
+ style_getRules {"selector": ".card:hover"} -> style_setRule {"selector": ".card:hover",
624
+ "props": {"background-color": "var(--color-accent)"}, "ifRevision": 12}
625
+ doc_save {"ifRevision": 13}
626
+ ```
627
+
628
+ (Each reply's `revision` is the `ifRevision` of your next write; the numbers above are examples.)
629
+
630
+ **After writing files outside the editor** (`xtframe-import`, a direct write)
631
+
632
+ ```
633
+ doc_status {} diskNewer / modified
634
+ doc_reload {} (unsaved edits: ask the user, then {"discard": true})
635
+ ```
636
+
637
+ ## All operations
638
+
639
+ Every operation by name (`Tools/Scripts/check_ops_doc.sh` keeps this list equal to
640
+ `Assets/Schemas/editor-service/`).
641
+
642
+ ```
643
+ animate.emphasis
644
+ animate.entrance
645
+ animate.exit
646
+ animation.followPath
647
+ animation.preset
648
+ asset.import
649
+ asset.linkFolder
650
+ asset.list
651
+ asset.replace
652
+ asset.setStatus
653
+ asset.slice
654
+ asset.sync
655
+ bind.get
656
+ bind.set
657
+ bone.add
658
+ bone.list
659
+ bone.pose
660
+ bone.remove
661
+ bone.resetToRest
662
+ bone.setRest
663
+ bone.setRestFromPose
664
+ bone.world
665
+ catalog.add
666
+ catalog.list
667
+ cel.add
668
+ cel.convert
669
+ cel.list
670
+ cel.remove
671
+ cel.setRange
672
+ checkpoint.begin
673
+ checkpoint.commit
674
+ checkpoint.list
675
+ checkpoint.rollback
676
+ constraint.add
677
+ constraint.remove
678
+ constraint.set
679
+ conventions.put
680
+ design.approve
681
+ design.audit
682
+ design.build
683
+ design.contrast
684
+ design.delete
685
+ design.deprecate
686
+ design.deriveScale
687
+ design.diff
688
+ design.export
689
+ design.extractPalette
690
+ design.get
691
+ design.importDesignSystem
692
+ design.importReference
693
+ design.link
694
+ design.lint
695
+ design.list
696
+ design.put
697
+ design.search
698
+ design.unlink
699
+ design.usage
700
+ diagnostics.accept
701
+ diagnostics.fix
702
+ diagnostics.list
703
+ doc.changes
704
+ doc.list
705
+ doc.open
706
+ doc.reload
707
+ doc.save
708
+ doc.setSource
709
+ doc.source
710
+ doc.status
711
+ export.lottie
712
+ flow.get
713
+ flow.set
714
+ fx.apply
715
+ history.adopt
716
+ history.checkpoint
717
+ history.compare
718
+ history.list
719
+ history.prune
720
+ history.restore
721
+ history.status
722
+ history.switch
723
+ history.variant
724
+ import.reimport
725
+ initialize
726
+ layer.create
727
+ layer.addAdjustment
728
+ layer.delete
729
+ layer.duplicate
730
+ layer.get
731
+ layer.group
732
+ layer.list
733
+ layer.move
734
+ layer.removeAdjustment
735
+ layer.rename
736
+ layer.setAttrs
737
+ layer.setFlags
738
+ layer.setProps
739
+ layer.setText
740
+ layout.anchor
741
+ lint.run
742
+ mesh.convert
743
+ mesh.pins
744
+ mesh.setPins
745
+ perf.probe
746
+ port.get
747
+ port.set
748
+ project.addUi
749
+ project.create
750
+ project.get
751
+ project.importReport
752
+ project.publish
753
+ project.removeUi
754
+ project.renameUi
755
+ project.saveAs
756
+ project.search
757
+ project.set
758
+ project.setAgents
759
+ project.syncSymbols
760
+ redo
761
+ repair.anchor
762
+ repair.dedup
763
+ repair.effectBase
764
+ repair.import
765
+ repair.passthrough
766
+ restyle
767
+ scenario.check
768
+ scenario.list
769
+ scene.dump
770
+ scene.screenshot
771
+ service.ops
772
+ session.endScenario
773
+ session.getScope
774
+ session.getView
775
+ session.setScenario
776
+ session.setScope
777
+ session.setView
778
+ skin.bind
779
+ skin.get
780
+ skin.prune
781
+ skin.set
782
+ skin.smooth
783
+ skin.unbind
784
+ state.apply
785
+ state.list
786
+ state.set
787
+ style.addStyle
788
+ style.copyStyles
789
+ style.deleteRule
790
+ style.getRules
791
+ style.getTokens
792
+ style.moveDecl
793
+ style.pasteStyles
794
+ style.removeStyle
795
+ style.renameRule
796
+ style.setRule
797
+ style.setStyleParams
798
+ style.setTheme
799
+ style.setToken
800
+ style.styles
801
+ symbol.create
802
+ symbol.detach
803
+ symbol.instantiate
804
+ symbol.list
805
+ symbol.override
806
+ symbols.export
807
+ symbols.get
808
+ symbols.import
809
+ symbols.libraries
810
+ symbols.library
811
+ symbols.lint
812
+ symbols.loadPreset
813
+ symbols.mountLibrary
814
+ symbols.saveAsGroup
815
+ symbols.unmountLibrary
816
+ symbols.updateCopy
817
+ symbols.use
818
+ symbols.useGroup
819
+ timeline.create
820
+ timeline.delete
821
+ timeline.duplicate
822
+ timeline.get
823
+ timeline.list
824
+ timeline.moveKeys
825
+ timeline.play
826
+ timeline.removeKeyframe
827
+ timeline.rename
828
+ timeline.seek
829
+ timeline.setCue
830
+ timeline.setDuration
831
+ timeline.setEasing
832
+ timeline.setKeyframe
833
+ timeline.setMarker
834
+ timeline.stagger
835
+ trigger.get
836
+ trigger.set
837
+ undo
838
+ vector.bake
839
+ vector.boolean
840
+ vector.editPath
841
+ vector.extract
842
+ vector.get
843
+ vector.morph
844
+ vector.set
845
+ vector.shapeOp
846
+ vector.textToOutlines
847
+ vector.trace
848
+ wire.port
849
+ ```