@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.
- 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 +218 -0
- package/payload/plugins/xtframe/skills/xtui/references/canvas.md +90 -0
- package/payload/plugins/xtframe/skills/xtui/references/dialect.md +799 -0
- package/payload/plugins/xtframe/skills/xtui/references/flow.md +338 -0
- package/payload/plugins/xtframe/skills/xtui/references/not-like-web.md +358 -0
- package/payload/plugins/xtframe/skills/xtui/references/performance.md +162 -0
- package/payload/plugins/xtframe/skills/xtui/references/responsive.md +137 -0
- package/payload/plugins/xtframe/skills/xtui/references/style-groups.md +378 -0
- package/payload/plugins/xtframe/skills/xtui/references/template.dc.html +56 -0
- package/payload/plugins/xtframe/skills/xtui/references/tokens.json +42 -0
- package/payload/plugins/xtframe/skills/xtui/references/ui-project.md +161 -0
- package/payload/plugins/xtframe/skills/xtui/references/upgrade.md +140 -0
- package/payload/plugins/xtframe/skills/xtui/references/vector.md +219 -0
- package/payload/plugins/xtframe/skills/xtui/references/verify.md +327 -0
- package/payload/plugins/xtframe/skills/xtui-editor/SKILL.md +209 -0
- package/payload/plugins/xtframe/skills/xtui-editor/references/design.md +158 -0
- package/payload/plugins/xtframe/skills/xtui-editor/references/ops.md +849 -0
- package/payload/plugins/xtframe/skills/xtui-editor/references/recipes.md +70 -0
- package/payload/plugins/xtframe/skills/xtui-editor/references/scenarios.md +180 -0
- package/payload/plugins/xtframe/skills/xtui-editor/references/service.md +167 -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,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
|
+
```
|