@xtframe/skills 0.0.0-stage → 0.19.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +22 -2
- package/package.json +41 -4
- package/payload/plugins/xtframe/.claude-plugin/plugin.json +17 -0
- package/payload/plugins/xtframe/.codex-plugin/plugin.json +11 -0
- package/payload/plugins/xtframe/gemini-extension.json +5 -0
- package/payload/plugins/xtframe/skills/xtui/SKILL.md +245 -0
- package/payload/plugins/xtframe/skills/xtui/references/canvas.md +93 -0
- package/payload/plugins/xtframe/skills/xtui/references/dialect.md +874 -0
- package/payload/plugins/xtframe/skills/xtui/references/flow.md +339 -0
- package/payload/plugins/xtframe/skills/xtui/references/from-procedural.md +140 -0
- package/payload/plugins/xtframe/skills/xtui/references/not-like-web.md +358 -0
- package/payload/plugins/xtframe/skills/xtui/references/performance.md +182 -0
- package/payload/plugins/xtframe/skills/xtui/references/responsive.md +137 -0
- package/payload/plugins/xtframe/skills/xtui/references/style-groups.md +404 -0
- package/payload/plugins/xtframe/skills/xtui/references/template.dc.html +56 -0
- package/payload/plugins/xtframe/skills/xtui/references/tokens.json +101 -0
- package/payload/plugins/xtframe/skills/xtui/references/ui-project.md +170 -0
- package/payload/plugins/xtframe/skills/xtui/references/upgrade.md +141 -0
- package/payload/plugins/xtframe/skills/xtui/references/vector.md +223 -0
- package/payload/plugins/xtframe/skills/xtui/references/verify.md +349 -0
- package/payload/plugins/xtframe/skills/xtui-editor/SKILL.md +219 -0
- package/payload/plugins/xtframe/skills/xtui-editor/references/design.md +158 -0
- package/payload/plugins/xtframe/skills/xtui-editor/references/ops.md +988 -0
- package/payload/plugins/xtframe/skills/xtui-editor/references/recipes.md +70 -0
- package/payload/plugins/xtframe/skills/xtui-editor/references/scenarios.md +211 -0
- package/payload/plugins/xtframe/skills/xtui-editor/references/service.md +175 -0
- package/src/agents.mjs +73 -0
- package/src/bin.mjs +4 -0
- package/src/cli.mjs +286 -0
- package/src/converter.mjs +73 -0
- package/src/fsutil.mjs +76 -0
- package/src/install.mjs +154 -0
- package/src/packs.mjs +150 -0
- package/src/plugins.mjs +109 -0
- package/src/proc.mjs +66 -0
- package/src/tar.mjs +103 -0
|
@@ -0,0 +1,349 @@
|
|
|
1
|
+
Read this when a board dump exists (`<dump>/project/canvas.json` plus its `*.dc.html`) and you are about to turn it into a UI Project: lint, import, compile, screenshot, report, open the editor.
|
|
2
|
+
|
|
3
|
+
# Verify: board dump -> UI Project -> editor
|
|
4
|
+
|
|
5
|
+
Every entry of the `xtui` skill ends here. `<dump>` is the directory holding `project/`,
|
|
6
|
+
`<project-dir>` is the UI Project the import writes (`<name>.xtui` at its root; when the UI
|
|
7
|
+
belongs to an existing UI Project, that project's root, `references/ui-project.md`), `<xtframe>` is
|
|
8
|
+
the XTFrame checkout. Run the steps in
|
|
9
|
+
order; do not skip one because the previous one was clean.
|
|
10
|
+
|
|
11
|
+
**You own compliance.** When the lint (step 2) or the compile (step 4) reports a problem, fix the
|
|
12
|
+
**board** (`<dump>/project/*.dc.html`, against `references/dialect.md`) and run again from step 2,
|
|
13
|
+
at most three rounds. Still failing after that: give the user the error text verbatim and stop.
|
|
14
|
+
Never patch the generated `.xt` / `.xts` to make an error go away.
|
|
15
|
+
|
|
16
|
+
## No native converter, but Node.js (convert mode on Node)
|
|
17
|
+
|
|
18
|
+
When there is no native `xtframe-import` and no way to build one (a cloud session, a sandbox, a
|
|
19
|
+
machine without the checkout) but `node --version` reports 18 or newer, you are still in **convert
|
|
20
|
+
mode**: the Node.js builds of the tools are the same programs compiled to WebAssembly, with the
|
|
21
|
+
same command lines, files, diagnostics and exit codes as the native ones. Use them as
|
|
22
|
+
`npx xtframe-import ...` (the npm converter package, `@xtframe/import-wasm`) or, from a checkout, as
|
|
23
|
+
`node <xtframe>/Code/Tools/wasm/bin/<tool>.js ...` (`xtframe-import`, `xtframe-compile`,
|
|
24
|
+
`xtframe-pack`, `xtframe-service`; the checkout needs `bash Tools/Scripts/build_wasm.sh` once, with
|
|
25
|
+
the Emscripten SDK, unless `Code/Tools/wasm/dist/` is already there). `Code/Tools/wasm/` is
|
|
26
|
+
**experimental** (not published to npm; outside the compatibility promise): when one of its tools
|
|
27
|
+
fails where the native one would not, say so in the report and fall back to deliver mode. Run steps 1-7 below with them;
|
|
28
|
+
only the screenshot (step 5) takes the `xtframe-service` path, and step 8 says where there is no
|
|
29
|
+
editor.
|
|
30
|
+
|
|
31
|
+
## Deliver mode (no converter and no Node.js)
|
|
32
|
+
|
|
33
|
+
Use this whole section instead of steps 1-8 only when `SKILL.md` step 0 found no `xtframe-import`,
|
|
34
|
+
no way to build it **and no Node.js 18+** to run its Node.js build. The deliverable is the
|
|
35
|
+
**dump**, which `xtframe-import dc` reads unchanged on any
|
|
36
|
+
machine that has XTFrame.
|
|
37
|
+
|
|
38
|
+
1. **Self-check the board** by reading, since the lint cannot run: every `*.dc.html` listed in
|
|
39
|
+
`project/canvas.json` `order` exists; every `<img src="/_blob/<id>">` and `@font-face` `src`
|
|
40
|
+
has its file under `<dump>/_blob/`; every `data-xt-*` tag you used is in
|
|
41
|
+
`references/dialect.md` (tag names, value forms, the port and timeline syntax); every id a
|
|
42
|
+
`data-xt-trigger` / binding / timeline refers to exists on the board; symbol names are in the
|
|
43
|
+
standard library or declared on the board; colours come from tokens, not literals. Fix what
|
|
44
|
+
you find; this replaces lint round 1.
|
|
45
|
+
2. **Package**: `<dump>/project/canvas.json`, `<dump>/project/*.dc.html`, `<dump>/_blob/*`,
|
|
46
|
+
and, when the UI belongs to an existing UI Project, nothing else (the import merges). Put a
|
|
47
|
+
`README.txt` beside `project/` with the exact command:
|
|
48
|
+
|
|
49
|
+
```
|
|
50
|
+
xtframe-import dc <dump> -o <project-dir> [--tokens <tokens.json>] [--fonts-dir <dir>]
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
(`<project-dir>` = the existing UI Project root when there is one, else a new directory;
|
|
54
|
+
add `--force` only when re-importing a UI the user agreed to overwrite.) Then
|
|
55
|
+
`xtframe-view "<project-dir>/<name>.xtui" --ui <ui> --headless --screenshot out.png` to see it,
|
|
56
|
+
or open the `.xtui` in `xtframe-editor`.
|
|
57
|
+
3. **Hand it over** as files (a zip when there is more than one directory): the dump path, the
|
|
58
|
+
command, and a short list of what the import will report as degradations if you knowingly used
|
|
59
|
+
something the dialect downgrades. State plainly that lint, compile and screenshot were not run
|
|
60
|
+
here. Do not write `.xt` / `.xts` by hand as a substitute; the import is the only producer.
|
|
61
|
+
|
|
62
|
+
## 1. Check the dump
|
|
63
|
+
|
|
64
|
+
`project/canvas.json` must exist, and so must every `*.dc.html` its `order` lists and every
|
|
65
|
+
`/_blob/<id>` a board references (`<img src>` and `@font-face` `src`), saved as
|
|
66
|
+
`<dump>/_blob/<id>`. A missing file is an error: report it, do not import around it.
|
|
67
|
+
|
|
68
|
+
The converters are the ones on PATH or under `<xtframe>/bin/win_x64/Release/`; if one is missing,
|
|
69
|
+
build it from `<xtframe>`, naming only the targets (no suites after `--`), with
|
|
70
|
+
|
|
71
|
+
```
|
|
72
|
+
bash Tools/Scripts/dev_check.sh --release xtframe-import xtframe-view xtframe-compile --
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
## 2. Lint
|
|
76
|
+
|
|
77
|
+
```
|
|
78
|
+
xtframe-import dc --lint <dump>
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
Writes nothing. One line per construct outside the dialect:
|
|
82
|
+
`<file>:<line>: <subject> -- dropped|degraded|invalid|fail: <reason>`. Exit 3 means it found
|
|
83
|
+
something, 0 clean, 2 usage, 1 the dump could not be read. Anything marked `fail` or `invalid`
|
|
84
|
+
will not survive step 3: fix the board first.
|
|
85
|
+
|
|
86
|
+
The intent tags (`references/dialect.md`) add their own lines: an unreadable or unknown
|
|
87
|
+
`data-xt-*` (`... could not be read`, `... is not a known data-xt-* tag`), and the tag lint as
|
|
88
|
+
`<file>:<line>: tag.<rule> -- warning: <message>`:
|
|
89
|
+
|
|
90
|
+
| Rule | Means | Fix on the board |
|
|
91
|
+
|---|---|---|
|
|
92
|
+
| `tag.triggerWithoutTimeline` | a trigger plays/stops/seeks a timeline no `data-xt-timeline` of that scope declares; the action was dropped | declare the timeline, or correct the name |
|
|
93
|
+
| `tag.stateNoDiff` | a `data-xt-state` element looks exactly like its Normal element | give the state its own look, or delete it |
|
|
94
|
+
| `tag.portUnbound` | a declared port is never bound, triggered on, emitted or set | bind it, or remove it from `data-xt-port` |
|
|
95
|
+
|
|
96
|
+
## 3. Import
|
|
97
|
+
|
|
98
|
+
```
|
|
99
|
+
xtframe-import dc <dump> -o <project-dir> [--tokens <tokens.json>] [--fonts-dir <dir>] [--force]
|
|
100
|
+
[--prune] [--diff-out <changes.json>] [--symbols-dir shared/symbols]
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
`--tokens` is optional: `<dump>/project/ds/*/tokens.json` is found automatically (pass the UI
|
|
104
|
+
Project's one explicitly, `references/ui-project.md`). `--symbols-dir <dir>` writes every
|
|
105
|
+
`data-xt-symbol` definition to `<project-dir>/<dir>/<Name>.xt` (a symbol library the UI links)
|
|
106
|
+
instead of the UI's own `<head>`; a library already there is kept unless `--force`. `--fonts-dir`
|
|
107
|
+
supplies the files for fonts the board links but the importer does not download (they are listed
|
|
108
|
+
in `missingFonts`). Exit codes: 0 ok, 1 an import/write error, 2 usage, 3 the re-import found
|
|
109
|
+
conflicting edits or fell back to a one-way import (below).
|
|
110
|
+
|
|
111
|
+
The import writes (or merges into) `<project-dir>/<name>.xtui` (the board's canvas name, else
|
|
112
|
+
`Imported Canvas`; a name that cannot be a file name uses the id); it never writes `bundle.xtproj`
|
|
113
|
+
or `ui-project.json` any more. A directory that only has an old `ui-project.json` or
|
|
114
|
+
`bundle.xtproj` is read as a UI Project and gets `<name>.xtui` next to it; the old file is left as
|
|
115
|
+
it was.
|
|
116
|
+
|
|
117
|
+
- **Exit 1 with `write failed (kInternal)`**: the importer's own verify step rejected a generated
|
|
118
|
+
document. The compiler diagnostics are printed just above it as
|
|
119
|
+
`xtframe-import: <file>:<line>:<col>: <message> [node <id>]` and repeated in
|
|
120
|
+
`import-report.json`'s `compileErrors[]`. Nothing was written. Fix the declaration it names on
|
|
121
|
+
the board; if it points nowhere useful, reproduce with `xtframe-compile <ui>.xt -o <tmp>.xtir`.
|
|
122
|
+
- **Exit 3, conflicts**: both the editor and the canvas changed the same property of a layer. The
|
|
123
|
+
merged documents keep the editor's value, the new version sits beside them as `<ui>.import.xt` /
|
|
124
|
+
`.xts`, and `import-report.json`'s `conflicts` lists each one with `prop`, `base`, `local` and
|
|
125
|
+
`incoming`. Show the user the list; they either change the canvas (and re-import) or re-run
|
|
126
|
+
with `--force` (which discards every editor change). That is the user's call, not yours --
|
|
127
|
+
with one exception: when the report says `no reimport baseline: these conflicts compare the
|
|
128
|
+
board with the generated files, not with hand edits; ...` (an old project imported before the
|
|
129
|
+
merge kept a baseline) **and** the user has already said the board is the source of truth, re-run
|
|
130
|
+
with `--force` directly; without that statement, ask as usual (`references/upgrade.md` step 5).
|
|
131
|
+
- **`anchor.flowMoved: <id> is moved by the flow; wrap it in a dock`** (warning): the UI's flow
|
|
132
|
+
writes that element's `left` / `top`, so the import left its board px instead of anchoring it.
|
|
133
|
+
Wrap it in a dock on the board, move the flow's positions to dock-relative values (in the
|
|
134
|
+
generator script when there is one) and import again (`references/responsive.md` section 3).
|
|
135
|
+
- **Exit 3, one-way fallback**: `re-import <ui>: ... (N% unmatched)` above 20% and
|
|
136
|
+
`import-report.json`'s `reimport[]` row says `fallback: "one-way"`. Too many layers could not be
|
|
137
|
+
found again (renamed or restructured on the canvas), so the documents were left alone and the new
|
|
138
|
+
version was written to `<ui>.import.xt`/`.xts`. Look at that row's `missing` list: if those
|
|
139
|
+
layers were removed from the board on purpose, re-run with `--prune` (the message ends with that
|
|
140
|
+
hint; with `--prune` the layers that are gone do not count, only low-confidence pairings do);
|
|
141
|
+
otherwise restore the `data-xt-name`/`id` of those layers on the board (canvas.md (c)) and import
|
|
142
|
+
again; `--force` is the last resort.
|
|
143
|
+
- The last stderr line is the fidelity summary
|
|
144
|
+
(`N declarations dropped, M warnings, K low-fidelity nodes -- see <bundle>/import-report.json`),
|
|
145
|
+
the last stdout line `imported N UIs, M nodes (a high, b medium, c low), ...`.
|
|
146
|
+
|
|
147
|
+
Re-importing into the **same** `<project-dir>` is the normal way to change a UI: hand-edited
|
|
148
|
+
nodes are kept (`kept hand edits on N node(s)`), and an unedited UI Project re-imports
|
|
149
|
+
byte-identically. A UI whose board did not change is not touched at all: it prints
|
|
150
|
+
`<ui>: board unchanged since the last import; its files were left alone` instead of a
|
|
151
|
+
`re-import` line, and no file of it is rewritten (a file whose bytes would not change is never
|
|
152
|
+
rewritten either). With `--prune` and no hand edits, a re-import gives the same result as a fresh
|
|
153
|
+
import. What the re-import does for every other UI (`re-import <ui>: N matched, N new, N missing`):
|
|
154
|
+
|
|
155
|
+
- Layers pair by `data-xt-name`/`id` first, then by geometry, order, nesting and text; a paired
|
|
156
|
+
layer keeps its editor id.
|
|
157
|
+
- The canvas's new geometry, text, colors and images arrive; properties the editor changed stay
|
|
158
|
+
(the editor records them in `<ui>.xteditor.json`), and so do timelines, `on:` triggers, `<ports>`
|
|
159
|
+
declarations, `bind:` attributes and every rule the editor wrote (in `<layout>` or in a
|
|
160
|
+
stylesheet).
|
|
161
|
+
- Layers the canvas no longer has stay, marked `data-xt-missing` (greyed in the editor's layer
|
|
162
|
+
panel); `--prune` deletes them instead. A kept layer loses a `bind:` / `on:` / `port:` attribute
|
|
163
|
+
whose port the board removed (`removed <attr> from #<id> ...`; the row's `removedBindings`), and a
|
|
164
|
+
symbol definition the board deleted but a kept `<use>` still needs stays (`keptSymbols`), so the
|
|
165
|
+
document still compiles.
|
|
166
|
+
- The UI's `.xtflow`: a flow the import generated and nobody edited follows the board (rewritten
|
|
167
|
+
when the board's flow changed, deleted when the board no longer has one); a hand-edited or
|
|
168
|
+
hand-written `.xtflow` is kept and stays registered.
|
|
169
|
+
- Symbol definitions (`<symbol>` and the libraries under `--symbols-dir`) merge one by one: one
|
|
170
|
+
nobody edited takes the board's version (or goes when the board deleted it), a new one is added,
|
|
171
|
+
and one edited locally is kept with a conflict (`prop: "symbol"`) in the report.
|
|
172
|
+
- A UI whose board is no longer on the canvas is kept, never deleted (`its board is no longer on
|
|
173
|
+
the canvas; the UI was kept`; `import-report.json`'s `uisNotOnCanvas`). In a project without an
|
|
174
|
+
asset manifest, an imported asset nothing references any more is listed in `unreferencedAssets`
|
|
175
|
+
and kept; `--prune` deletes it with its `.meta` (only when nobody edited it).
|
|
176
|
+
- In the editor the same merge runs from the UI Project panel's **Re-import...** button, and over
|
|
177
|
+
the Editor Service as `import.reimport {source, ui?, prune?, force?}`.
|
|
178
|
+
|
|
179
|
+
## 4. Compile every UI
|
|
180
|
+
|
|
181
|
+
The importer accepts values the compiler later refuses, and those vanish silently from the render.
|
|
182
|
+
For each UI:
|
|
183
|
+
|
|
184
|
+
```
|
|
185
|
+
xtframe-compile <project-dir>/<ui>/<ui>.xt -o <tmp>/<ui>.xtir
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
An `error:` sends you back to the board. Collect every `warning:` line for the report.
|
|
189
|
+
|
|
190
|
+
## 5. Screenshot
|
|
191
|
+
|
|
192
|
+
```
|
|
193
|
+
xtframe-view <project-dir>/<ui>/<ui>.xt --headless --frames 3 --screenshot <abs-path>.png
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
To see a later moment (an intro's end, second 54 of a loop), `--advance <seconds>` runs the time
|
|
197
|
+
before it without painting and then draws the frames as usual, the same picture as stepping there
|
|
198
|
+
frame by frame: `xtframe-view <ui> --headless --renderer wgpu --advance 54 --frames 1 --screenshot out.png`.
|
|
199
|
+
|
|
200
|
+
**On Node.js** (no `xtframe-view`: it needs SDL and is not built for WebAssembly) the Editor
|
|
201
|
+
Service renders the same picture: `xtframe-service --stdio --project <project-dir>` fed `doc.open`
|
|
202
|
+
and `scene.screenshot`, the PNG decoded from the reply. Paste as is (bash), with `<ui>`,
|
|
203
|
+
`<project-dir>` and the absolute output path filled in; `"device": "21:9"` (or `{"w", "h"}`) is the
|
|
204
|
+
second aspect below:
|
|
205
|
+
|
|
206
|
+
```
|
|
207
|
+
printf '%s\n' '{"id":1,"op":"doc.open","args":{"path":"<ui>"}}' \
|
|
208
|
+
'{"id":2,"op":"scene.screenshot","args":{"device":"16:9"}}' \
|
|
209
|
+
| node <xtframe>/Code/Tools/wasm/bin/xtframe-service.js --stdio --project <project-dir> \
|
|
210
|
+
| node -e 'let s="";process.stdin.on("data",(d)=>{s+=d}).on("end",()=>{for(const l of s.trim().split("\n")){const r=JSON.parse(l);if(!r.ok){console.error(`${r.id}: ${r.error.code}: ${r.error.message}`);process.exitCode=1}else if(r.result.images){require("fs").writeFileSync(process.argv[1],Buffer.from(r.result.images[0].png,"base64"));console.log(`wrote ${process.argv[1]} (${r.result.images[0].width}x${r.result.images[0].height})`)}}})' <abs-path>.png
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
(`xtframe-service` has no npm package: it is the checkout's experimental Node.js build.) A failed request prints `<id>: <code>: <message>` and exits 1: treat it like a failed
|
|
214
|
+
`xtframe-view`. There is no `--port` here: the picture shows the ports' declared defaults.
|
|
215
|
+
|
|
216
|
+
Use an **absolute** path; a screenshot that cannot be written is an error, not a silent skip.
|
|
217
|
+
Look at it next to the board (or the description) and list the visible differences. A sibling
|
|
218
|
+
`<ui>.xtflow` is loaded automatically (stderr says `xtframe-view: loaded flow <path>`); add
|
|
219
|
+
`--no-flow` to see the static board. stderr must not contain `flow.animatesWithContinuousSignal`
|
|
220
|
+
(a flow edge that animates from a continuous signal; rewrite it per `flow.md` Rules, and use `--strict`
|
|
221
|
+
to make it fail the run).
|
|
222
|
+
|
|
223
|
+
The import anchors the board to the safe area (dialect.md, **Board setup**), so take a second
|
|
224
|
+
shot at another aspect with the board's height, e.g. `--height 720 --device 21:9`: the corner
|
|
225
|
+
panels should hug the screen's safe edges and the centered ones stay centered. An element that
|
|
226
|
+
drifted the wrong way needs `data-xt-anchor` on the board, or, when it should stay aligned with a
|
|
227
|
+
sibling or the flow moves it, a dock (`references/responsive.md` section 3). For a responsive
|
|
228
|
+
request take the whole aspect set instead (16:9 at 1280x720 and 1920x1080, 21:9, 32:9, 4:3, 16:10
|
|
229
|
+
and portrait 1080x1920; `references/responsive.md` section 4). The import may print
|
|
230
|
+
`info: UI Project (.xtui) spec.logicalHeight set to <h> (the board height)`; that is expected.
|
|
231
|
+
|
|
232
|
+
`xtframe-view <project-dir> --ui <ui> --headless --screenshot <abs-path>.png` shows
|
|
233
|
+
the UI the way a game gets it: the UI Project is packed into a Bundle under `%TEMP%` first
|
|
234
|
+
(`xtframe-view: packed ...`), and the UI's registered flow comes along. That pack follows the
|
|
235
|
+
project's `publish.images.compress` (`references/ui-project.md` section 3c): with `bc7` or `auto`
|
|
236
|
+
the first run encodes the images and is slower, later runs reuse the encode cache.
|
|
237
|
+
|
|
238
|
+
`--headless` renders in software. To see the GPU picture, add `--renderer wgpu` (or `gl`); these
|
|
239
|
+
switches of `xtframe-view --help` matter for comparisons:
|
|
240
|
+
|
|
241
|
+
| Switch | Does |
|
|
242
|
+
|---|---|
|
|
243
|
+
| `--msaa N` | MSAA samples for the windowed backend and `--renderer gl\|wgpu`: `4` or `1` (none); the default is 1, the GPU targets' default too (`references/performance.md`, **Antialiasing**) |
|
|
244
|
+
| `--no-box-shadow` | keeps element drop shadows as off-screen effects (no analytic box shadows), for before/after comparisons |
|
|
245
|
+
| `--no-system-fonts` | does not add the system fonts: bundle fonts only, like a C ABI host without system fonts -- use it to check that the UI's text does not depend on fonts the game will not have |
|
|
246
|
+
| `--perf` | frame tracing; with `--renderer wgpu` one more line of per-frame GPU counts (passes, draw calls, effect cache, mip chains) |
|
|
247
|
+
|
|
248
|
+
To see it with data, set ports before the first frame: `--port hp=40`, a list or struct as JSON
|
|
249
|
+
(`--port 'items=[{"name":"A"},{"name":"B"}]'` in bash). In PowerShell the inner double quotes
|
|
250
|
+
can be dropped on the way to a native command (`--port: expected <name>=<value>` or a JSON
|
|
251
|
+
error): put `$PSNativeCommandArgumentPassing = 'Legacy'` before the call and escape them inside
|
|
252
|
+
single quotes (`--port 'items=[{\"name\":\"A\"}]'`). `--strict` also prints the document's runtime
|
|
253
|
+
warnings (e.g. a virtualized list with a zero-height viewport) at the end of the run.
|
|
254
|
+
|
|
255
|
+
## 6. Report the degradations
|
|
256
|
+
|
|
257
|
+
Group every warning (lint, import report, compile) and say what the user should do. The ones that
|
|
258
|
+
still happen:
|
|
259
|
+
|
|
260
|
+
| On the board | What you get |
|
|
261
|
+
|---|---|
|
|
262
|
+
| `display: grid`, two-dimensional | `display: block` + warning (one-dimensional grids become flex) |
|
|
263
|
+
| `backdrop-filter` without `blur()`, or with a function other than `blur/saturate/brightness` | dropped + warning |
|
|
264
|
+
| `vw/vh/rem/em/calc()` | that declaration dropped + warning |
|
|
265
|
+
| `outline*` | kept (T-325); `dashed`/`dotted`/... become `solid` + warning |
|
|
266
|
+
| a `filter()` other than `blur`/`drop-shadow`/`brightness` | dropped + warning |
|
|
267
|
+
| `<sc-for>` / `<sc-if>` / `renderVals()` | expanded **once** from `data-props` defaults; script output never appears |
|
|
268
|
+
| `<dc-import>` / `x-import` components | dropped + warning |
|
|
269
|
+
| a tag outside the allow list (`table`, `tr`, `td`, ...) | becomes `<div>` + warning (low fidelity) |
|
|
270
|
+
| Google Fonts `<link>` | listed in `missingFonts`, not downloaded: pass `--fonts-dir` |
|
|
271
|
+
| multi-layer `background` | works, but becomes stacked child `<div>`s (the node tree changes) |
|
|
272
|
+
| per-side `border-*-color` that disagree | the first colour is used for the whole box + warning |
|
|
273
|
+
| multi-layer `background` inside a keyframe | only the bottom layer animates + warning |
|
|
274
|
+
| a `transform` sequence needing 3D shear or z scale | compile **error** (the import fails) |
|
|
275
|
+
|
|
276
|
+
Do **not** warn about these any more, they import correctly: `class` attributes, `transform` in
|
|
277
|
+
any order, `rgba()` border colours, single-side `padding-*`/`margin-*`/`border-*-width`,
|
|
278
|
+
`repeating-*` and `circle`/`ellipse` gradients, several `box-shadow`s, `text-shadow`,
|
|
279
|
+
`animation-*` longhands, SVG `<defs>` gradients, `opacity: 0`, `<img>` + `visibility`,
|
|
280
|
+
`cubic-bezier(.6,...)`, `forwards`, `{{hole}}` inside inline SVG attributes.
|
|
281
|
+
|
|
282
|
+
Also read `import-report.json`: `nodes[].warnings`, `missingFonts`, `skipped`, `bindings`,
|
|
283
|
+
`lint` (the tag lint), `conflicts`, `compileErrors`.
|
|
284
|
+
|
|
285
|
+
## 7. Ids and titles
|
|
286
|
+
|
|
287
|
+
The UI id is the board root element's `id`; the board `title` is only the fallback (slugified) and
|
|
288
|
+
the display name. If a root has no `id` and its title is not `[a-z0-9-]`, say which id the import
|
|
289
|
+
produced and offer to add a root `id` on the board rather than renaming files afterwards.
|
|
290
|
+
|
|
291
|
+
Elements without an authored `id` get a content-hash id (`n-xxxxxxxx`) that moves whenever the
|
|
292
|
+
design changes. List every element a flow or the host must reach that still lacks a real id.
|
|
293
|
+
|
|
294
|
+
## 8. Open the editor
|
|
295
|
+
|
|
296
|
+
The last step, always -- except on a machine without the editor (convert mode on Node.js, a cloud
|
|
297
|
+
session): then report the UI Project path and say the editor was not opened here, nothing else.
|
|
298
|
+
Otherwise start it in the background and do not wait for it to exit:
|
|
299
|
+
|
|
300
|
+
```
|
|
301
|
+
Start-Process -FilePath "<editor-exe>" -ArgumentList '"<project-dir>"' # Windows PowerShell
|
|
302
|
+
start "" "<editor-exe>" "<project-dir>" # Windows cmd
|
|
303
|
+
"<editor-exe>" "<project-dir>" & # Linux / macOS shell
|
|
304
|
+
```
|
|
305
|
+
|
|
306
|
+
On Windows use `Start-Process` (or `start` from cmd), also when your own shell is Git Bash
|
|
307
|
+
(`powershell -NoProfile -Command "Start-Process ..."`): a `bash ... &` child is killed when the
|
|
308
|
+
tool's shell exits, so the editor does not stay open.
|
|
309
|
+
|
|
310
|
+
`<editor-exe>` is `<xtframe>/bin/win_x64/Release/xtframe-editor.exe`. If it does not
|
|
311
|
+
exist, build it from `<xtframe>`:
|
|
312
|
+
|
|
313
|
+
```
|
|
314
|
+
bash Tools/Scripts/dev_check.sh --release xtframe-editor --
|
|
315
|
+
```
|
|
316
|
+
|
|
317
|
+
The editor needs Qt: `XT_QT_DIR` must point at a Qt installation (the directory holding
|
|
318
|
+
`include/` and `lib/`) when the build is configured. If it is unset and no Qt can be found, say so
|
|
319
|
+
and stop at the UI Project path instead of guessing.
|
|
320
|
+
|
|
321
|
+
Then report the UI Project path and "editor opened".
|
|
322
|
+
|
|
323
|
+
If the editor comes up unresponsive: Windows only records an `AppHangB1` and the crash log is
|
|
324
|
+
empty. XTFrame's own log has a hang watchdog: look for a `=== HANG` block (stack + minidump path)
|
|
325
|
+
in its log directory, report that block, and **do not retry** blindly.
|
|
326
|
+
|
|
327
|
+
## Packing a Bundle (only when the user asks for one)
|
|
328
|
+
|
|
329
|
+
Not part of steps 1-8: a Bundle is the published form a game loads. From the UI Project:
|
|
330
|
+
|
|
331
|
+
```
|
|
332
|
+
xtframe-pack <project-dir> -o <bundle-dir> [--ui <id>]... [--compress bc7|bc3|bc1|auto|none]
|
|
333
|
+
[--no-cache] [--cache-dir <dir>] [--keep-stale]
|
|
334
|
+
```
|
|
335
|
+
|
|
336
|
+
(`-o` may be left out when the `.xtui` sets `publish.outDir`.)
|
|
337
|
+
|
|
338
|
+
- `--compress` overrides the project's `publish.images.compress` for this run
|
|
339
|
+
(`references/ui-project.md` section 3c; `bc3` / `bc1` are accepted here too, not in the `.xtui`). Encoded
|
|
340
|
+
images are cached in `<bundle-dir>/../.xtframe-cache/bc/`, so a later pack only encodes what
|
|
341
|
+
changed; `--cache-dir <dir>` puts the cache elsewhere, `--no-cache` turns it off. The Bundle is
|
|
342
|
+
the same byte for byte with or without the cache.
|
|
343
|
+
- **A successful pack deletes stale files.** It removes every regular file directly inside the
|
|
344
|
+
Bundle's `ui/`, `assets/`, `thumbs/`, `themes/`, `strings/`, `atlas/` and `fonts/`, and the
|
|
345
|
+
known root files (`bundle.xtflow`, leftover `.tmp` files), that this pack neither wrote nor
|
|
346
|
+
lists in its `manifest.json`, and prints `xtframe-pack: removed N stale file(s) (B bytes) from
|
|
347
|
+
<bundle-dir>`. A failed pack removes nothing; files listed by a previous manifest of a different
|
|
348
|
+
project are kept. **Never put your own files into those directories of a Bundle.**
|
|
349
|
+
`--keep-stale` turns the removal off. The editor's Publish (`project.publish`) does the same.
|
|
@@ -0,0 +1,219 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: xtui-editor
|
|
3
|
+
description: Change a UI that is open in the XTFrame editor, through the editor itself (the Editor Service, over xtframe-mcp or a headless editor) - layers, styles and tokens, timelines and keyframes, triggers, states, symbols, ports and bindings, effects, anchors, re-import, symbol libraries (use a group, import a set, save a group), with scene dumps, lint and screenshots as feedback, one of 14 scenario contracts and a checkpoint per change; it never writes .xt/.xts/.dc.html files. Use it when the user wants "this UI" in the editor changed, mentions panels, the timeline, symbols or scenarios, or the editor is running (service.json present). To make a new UI or import from Claude Design, use xtui instead.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# xtui-editor
|
|
7
|
+
|
|
8
|
+
The editor skill: every change to a UI **that already exists in the XTFrame editor**. You work on
|
|
9
|
+
the open document through typed operations of the Editor Service -- the same ones the editor's own
|
|
10
|
+
AI panel uses -- and the editor keeps undo, checkpoints and the user's view in step. The board
|
|
11
|
+
(`.dc.html`) and the generated `.xt`/`.xts` are not yours to write: making a UI from a description
|
|
12
|
+
or a Claude Design canvas is the `xtui` skill.
|
|
13
|
+
|
|
14
|
+
| Reference | Holds |
|
|
15
|
+
|---|---|
|
|
16
|
+
| `references/service.md` | choosing the target (project > gui > headless > directory), connecting (MCP, raw HTTP, a headless editor, stdio), the work item loop |
|
|
17
|
+
| `references/ops.md` | the operations by kind (read, write, intent, feedback, bookkeeping) and the usual sequences |
|
|
18
|
+
| `references/scenarios.md` | the 14 scenario contracts: when to pick which, scope, budget, `done_when` |
|
|
19
|
+
| `references/recipes.md` | recipes (reusable motion/effect presets) and how to find them |
|
|
20
|
+
| `references/design.md` | the design system (`design/`, `design.*`): when to read `DESIGN.md`, the four entry points, evidence rules, the report |
|
|
21
|
+
|
|
22
|
+
## 0. Is this the right skill?
|
|
23
|
+
|
|
24
|
+
- The user wants a **new** UI, gives a description to build from, a Claude Design canvas URL, a
|
|
25
|
+
board dump or asks to redo the board: stop, that is `xtui`.
|
|
26
|
+
- The user wants the UI in the editor changed (a colour, an animation, a hover state, a binding,
|
|
27
|
+
"fix what the import left", "review this screen"), or an editor has the project open
|
|
28
|
+
(`<project>/.xtcache/editors/` lists one, or `%LOCALAPPDATA%/XTFrame/service.json` exists):
|
|
29
|
+
continue. No `service.json` does **not** mean no editor: the user may have one open that is not
|
|
30
|
+
listening, or several.
|
|
31
|
+
|
|
32
|
+
## 1. Connect: project > gui > headless > directory
|
|
33
|
+
|
|
34
|
+
Read `references/service.md` section 1. The order is fixed:
|
|
35
|
+
|
|
36
|
+
1. **Project.** Settle the UI Project directory first (the one holding `<name>.xtui`; ask when it
|
|
37
|
+
is not clear). Never assume the user has only one editor open, or only this project.
|
|
38
|
+
2. **GUI, then headless.** `xtframe-mcp --project <dir> [--agent-name <name>]` finds the editor
|
|
39
|
+
itself: a GUI that has `<dir>` open and listens; else a GUI that has it open but does not listen
|
|
40
|
+
-- it **knocks** (the user sees "AI agent <name> wants to connect" with Allow / Deny / Allow as
|
|
41
|
+
steward) and waits up to 60 s; else a headless editor that has it open. Refused or unanswered: it exits with the reason
|
|
42
|
+
on stderr; tell the user, do not go around it.
|
|
43
|
+
3. **Spawn.** Nothing has it open: `xtframe-mcp --spawn-headless <dir> [--open <ui-id>]` (it implies
|
|
44
|
+
`--project <dir>`, so it still prefers an open editor) starts a headless editor for the session.
|
|
45
|
+
No MCP client at all: `xtframe-editor --service --stdio --project <dir> <ui-id>`, one JSON request
|
|
46
|
+
per line.
|
|
47
|
+
4. **Directory, last resort.** Only when no editor can be used at all may files be written directly
|
|
48
|
+
(that is `xtui`'s board and `xtframe-import`, never hand-written `.xt` / `.xts`). Afterwards the
|
|
49
|
+
editor that has the UI open must `doc.reload` it (or pick up the change itself: it watches its
|
|
50
|
+
files) -- call `doc_reload` as soon as you are connected again.
|
|
51
|
+
|
|
52
|
+
Then `initialize` (the handshake: product version, formats, the op names this editor has and the
|
|
53
|
+
deprecated ones -- use only those names, `references/ops.md`), `project_get` (and `AGENTS.md`,
|
|
54
|
+
tokens, conventions through it) and `scene_dump`: know the
|
|
55
|
+
project's rules and what is on screen before touching anything. `doc_list` shows which UI is yours
|
|
56
|
+
(`activeDoc`) and what the other seats work on. Then take over (section 2).
|
|
57
|
+
|
|
58
|
+
## 2. Taking over (接手)
|
|
59
|
+
|
|
60
|
+
The user and you can replace each other at any point: they may have been editing this UI a minute
|
|
61
|
+
ago, another agent may have left it half done, and the user may keep editing while you work. So,
|
|
62
|
+
every time you connect (and again when you come back after a pause):
|
|
63
|
+
|
|
64
|
+
1. **Where were they?** `session_getView`: the selection, the active timeline and its playhead,
|
|
65
|
+
Animate, the space, the device and Edit in Place. Work there; move the view only with
|
|
66
|
+
`session_setView` (the editor names your seat in its status bar). With Animate on,
|
|
67
|
+
`layer_setProps` records keyframes, as the user's own edits do.
|
|
68
|
+
2. **What did they do?** `doc_changes {"since": <revision>}` -- `<revision>` is the last revision
|
|
69
|
+
you saw of that UI (your last reply's `revision`, or the `revision` a hand-over note gives you;
|
|
70
|
+
`0` when you have none). Every step since, the user's (`kind: command`, with the layers they had
|
|
71
|
+
selected) and other agents' (`kind: op`), oldest first. Read it before changing anything and say
|
|
72
|
+
in your report what you continued from. `history_list {"kind": "checkpoints"}` shows the earlier
|
|
73
|
+
work items (each seat's, with `touched` in the note).
|
|
74
|
+
3. **Write with `ifRevision`, always.** Every write that works on a document carries the
|
|
75
|
+
`revision` of your latest reply for it (ops.md "Revisions"). `kConflict` means someone changed
|
|
76
|
+
it meanwhile: read again (`doc_changes {since}` plus the layer or rule you are changing), redo
|
|
77
|
+
the write **once** with the new revision if it still makes sense; a second `kConflict` -- stop and
|
|
78
|
+
tell the user who is changing what, do not loop.
|
|
79
|
+
4. **Undo only your own steps.** `undo` / `redo` act on one shared stack and refuse with
|
|
80
|
+
`kConflict` ("top of the undo stack is <seat>'s edit") when the top step is not yours. Never try
|
|
81
|
+
to undo the user's work; ask.
|
|
82
|
+
5. **Gates.** Adopting a variant, pruning variants and approving or deprecating a design entry
|
|
83
|
+
(`history_adopt`, `history_prune`, `design_approve`, `design_deprecate`) are the user's. They
|
|
84
|
+
answer `kForbidden` unless the user made your seat a **steward** -- "Allow as steward" on the
|
|
85
|
+
knock bar, "Allow adopt and approve" in the AI panel, or `steward: true` for your name in the
|
|
86
|
+
project's `.xtcache/agents.json` (never write that file yourself). As a steward, call them only
|
|
87
|
+
when the user asked for that exact thing, outside a scenario; the reply has `asSteward: true` and
|
|
88
|
+
the history records "adopted by <seat> (steward): ..." under your seat -- report it.
|
|
89
|
+
`history_restore` (main back to a checkpoint) is open to you, but only on the user's word.
|
|
90
|
+
|
|
91
|
+
## 3. Every change is one work item
|
|
92
|
+
|
|
93
|
+
```
|
|
94
|
+
scenario_list / session_setScenario {name, root?} start the work item (references/scenarios.md)
|
|
95
|
+
checkpoint_begin {scenario} before the first edit
|
|
96
|
+
... operations (references/ops.md), every write with ifRevision ...
|
|
97
|
+
scene_dump / lint_run / scene_screenshot (budgeted) look at the result
|
|
98
|
+
scenario_check the contract's done_when
|
|
99
|
+
session_endScenario ends the work item: read its gates
|
|
100
|
+
checkpoint_commit {id} or checkpoint_rollback {id} the user decides
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
- Pick the scenario from what the user asked (`references/scenarios.md`); it fixes your scope, the
|
|
104
|
+
operations you may call and your screenshot budget. A call outside it fails with the reason:
|
|
105
|
+
do not work around it, tell the user or pick the right scenario.
|
|
106
|
+
- Prefer **intent operations** (`animate.entrance`, `layout.anchor`, `restyle`, `fx.apply`,
|
|
107
|
+
`state.apply`, `wire.port`, `repair.import`) over many low-level ones: one call, one undo step,
|
|
108
|
+
and they follow the project's motion spec.
|
|
109
|
+
- Destructive operations (`layer.delete`, `timeline.delete`, `symbol.detach`, `design.delete`,
|
|
110
|
+
overwriting `asset.import`, `import.reimport` with `force`) need `"confirm": true`, and only after
|
|
111
|
+
the user said yes to that exact thing.
|
|
112
|
+
- Look before you report: `lint_run` must be clean for the rules the scenario names, and
|
|
113
|
+
`scene_dump`'s `visibility` must not list the layers you touched as offscreen, occluded or
|
|
114
|
+
overflowing.
|
|
115
|
+
|
|
116
|
+
## 3b. Symbol libraries (49.7)
|
|
117
|
+
|
|
118
|
+
The symbols a UI instantiates come from **symbol libraries** (the presets, the user's own
|
|
119
|
+
library, extra mounts, the project's) in **groups**; a project holds **copies** of the ones it uses
|
|
120
|
+
(`references/ops.md` "Symbol libraries"). Through the editor:
|
|
121
|
+
|
|
122
|
+
- **Look first**: `symbols_libraries`, then `symbols_library` (groups, each group's symbols with
|
|
123
|
+
their contract summary, `source`, `lint {errors, warnings}`), `symbols_get {name}` for one
|
|
124
|
+
symbol's full entry. Reads, allowed everywhere. No style named: the preset library's default
|
|
125
|
+
group `broadsheet-2026`; "my X group": that one.
|
|
126
|
+
- **Use in the project** (`create`, `restyle`, `repair-import`, `single-element`):
|
|
127
|
+
`symbols_useGroup {group}` before building a UI from a group, `symbols_use {names}` for a few
|
|
128
|
+
symbols -- one undo step each: the files are copied, the tokens appended, the source recorded
|
|
129
|
+
(49.3). Then `symbol_instantiate {symbol, parent, source: "project"}` places them, with the name
|
|
130
|
+
the reply gives in `symbols[].qualified`: when the project already had another symbol of that name
|
|
131
|
+
the copy is stored as `<group id>/<Name>` (56.3, `clashes[].reason` `placed`) -- use that name and
|
|
132
|
+
tell the user; never ask them to rename or prefix anything. `symbols_move {from, to}` moves a
|
|
133
|
+
project symbol between `shared/symbols` and a namespace (every reference follows; one undo step).
|
|
134
|
+
- **The project's style** (one per project, 56.2): to make the whole UI look like another group,
|
|
135
|
+
`tokens_applyStyle {group, dryRun: true}` first and show the user what it replaces (their own
|
|
136
|
+
values are marked `custom`) and what it does not cover, then run it without `dryRun` on their word
|
|
137
|
+
(one undo step; only the 52 core tokens change). A symbol that must keep its look whatever the
|
|
138
|
+
style: `symbols_duplicateDetached {name, newName}` (an independent copy with tokens of its own).
|
|
139
|
+
- **A copy older than the library**: `project_syncSymbols` lists `outdated` / `modified` copies.
|
|
140
|
+
Tell the user; **suggest** `symbols_updateCopy {name}` (the recorded source's file over the
|
|
141
|
+
project's copy, tokens kept, one undo step) and run it only on their word -- never automatically.
|
|
142
|
+
A copy the project changed comes back `updated: false` (`locallyModified` / `staleAndModified`):
|
|
143
|
+
say what the project changed and pass `overwriteLocal: true` only after they agree.
|
|
144
|
+
- **The library itself** -- `symbols_import`, `symbols_saveAsGroup`, `symbols_loadPreset`,
|
|
145
|
+
`symbols_export`, `symbols_mountLibrary`, `symbols_unmountLibrary` -- is the **`library`**
|
|
146
|
+
scenario (`references/scenarios.md`), and every one of them also needs the person's leave because
|
|
147
|
+
libraries are shared by every project and permanent: the refusal `kPermissionDenied` ("library
|
|
148
|
+
writes need the \"Allow AI to change symbol libraries\" preference or a one-time approval") means
|
|
149
|
+
the editor is asking the user (allow this time / always / deny) -- wait, tell the user what you
|
|
150
|
+
want to do and why, and do not work around it (no file writes). Only the user grants it (allow
|
|
151
|
+
this time, or the preference); a client cannot grant it to itself.
|
|
152
|
+
- **The user gives a set** (a `.xtsymbols` file or a set directory): first `symbols_lint {path}`
|
|
153
|
+
-- it reads `set.json` without importing -- and show the user the **licence** (`set.license`,
|
|
154
|
+
`set.fontsLicense`), author, version and every finding (`groups[].issues`, with `errors` /
|
|
155
|
+
`warnings`); only when they agree, `symbols_import {path, library?, replaceOlder?}`. The import
|
|
156
|
+
report says per group whether it was `added`, `updated` (the old one in `.trash/`), `unchanged`
|
|
157
|
+
or `older-skipped` (ask before `replaceOlder: true`). A **URL** must be `https://`: anything else
|
|
158
|
+
is refused and you never fetch it by other means; the editor downloads it (64 MB at most) and
|
|
159
|
+
lints after the download, so show the URL, get the agreement first, then report `downloaded
|
|
160
|
+
{bytes, sha256}`, the licence and the lint from the reply.
|
|
161
|
+
|
|
162
|
+
## 4. Work items
|
|
163
|
+
|
|
164
|
+
- **One change = one work item**: `session_setScenario` ... `session_endScenario`. The work item
|
|
165
|
+
runs on the main line: it starts with the commit "Before <seat>: <scenario>" and, when it wrote
|
|
166
|
+
anything, ends with the checkpoint "<seat> · <scenario> · HH:MM" (projects with history).
|
|
167
|
+
Nothing is rolled back for you; the user reviews it in the History panel.
|
|
168
|
+
- **Explore only when asked**: `explore: true` runs the work item on a variant of its own -- only
|
|
169
|
+
when the user wants to try something they may throw away. You do not adopt a variant, unless the
|
|
170
|
+
user made your seat a steward and asks you to (section 2).
|
|
171
|
+
- **Gates**: read `gates` in the `session_endScenario` reply (`lint: {errors, warnings}`,
|
|
172
|
+
`contract: {ok, violations}`). Errors left: start a new work item, fix them until lint has no
|
|
173
|
+
error, and report what stays in `violations`.
|
|
174
|
+
- **Revisions**: every reply carries `revision`; send the last one you saw as `ifRevision` on
|
|
175
|
+
**every** write. `kConflict`: read again, retry once, then report to the user (section 2).
|
|
176
|
+
- **After writing files** (`xtframe-import`, a command-line re-import, any direct write): call
|
|
177
|
+
`doc_reload` for every UI it touched (unsaved edits: ask the user before `discard: true`).
|
|
178
|
+
`doc_status` shows `diskNewer` when the files changed on disk under unsaved edits.
|
|
179
|
+
- **Other UIs**: `doc_open {"path": "<ui>", "show": false}` makes another UI your active document
|
|
180
|
+
without switching the user's view; `show: true` only when the user asked to see it.
|
|
181
|
+
- **One MCP session, one work item at a time**: finish one (`session_endScenario`) before starting
|
|
182
|
+
the next.
|
|
183
|
+
|
|
184
|
+
## 5. Report
|
|
185
|
+
|
|
186
|
+
End every change with three lists -- the editor's AI panel shows the same:
|
|
187
|
+
|
|
188
|
+
- **Chosen**: what you changed and why (layers, timelines, tokens; which intent operations).
|
|
189
|
+
- **Deliberately left out**: what you could have done and did not (the scenario forbids it, the
|
|
190
|
+
motion spec advises against it, the user did not ask).
|
|
191
|
+
- **Violated**: any motion-spec or contract rule you broke, with the reason; "none" when none.
|
|
192
|
+
Include the gates of the work item.
|
|
193
|
+
|
|
194
|
+
Then ask whether to commit the checkpoint or roll it back. Name what you took over (section 2:
|
|
195
|
+
the user's or another seat's steps you continued from) and any gate you ran as a steward.
|
|
196
|
+
|
|
197
|
+
## 6. What this skill never does
|
|
198
|
+
|
|
199
|
+
- Write, patch or delete files: no `.xt`, `.xts`, `.xtflow`, `.dc.html`, tokens or contracts on
|
|
200
|
+
disk. Every change goes through an operation, so it is undoable and the editor stays the owner.
|
|
201
|
+
`doc.save` is the only way anything reaches disk.
|
|
202
|
+
- Read project files: besides the schemas (`<xtframe>/schemas/editor-service/`) and `service.json`,
|
|
203
|
+
ask the editor:
|
|
204
|
+
|
|
205
|
+
| To read | Ask with |
|
|
206
|
+
|---|---|
|
|
207
|
+
| the `.xt` / `.xts` text | `doc_source {file?}` |
|
|
208
|
+
| class, state and shared rules | `style_getRules {selector?, file?}` |
|
|
209
|
+
| the flow graph (`.xtflow`) | `flow_get` (change it with `flow_set`) |
|
|
210
|
+
| the import report | `project_importReport {ui}` |
|
|
211
|
+
| the spec, conventions, tokens, `AGENTS.md` | `project_get {section}` |
|
|
212
|
+
| the symbol libraries, a group's symbols, one symbol's contract, a set's licence and lint | `symbols_libraries`, `symbols_library {library?}`, `symbols_get {name}`, `symbols_lint {group? \| path?}` |
|
|
213
|
+
| layers and their own rules | `layer_get`, `scene_dump` |
|
|
214
|
+
| ports and their defaults | `port_get {layer}` |
|
|
215
|
+
| revision, unsaved state, disk changes | `doc_status` |
|
|
216
|
+
|
|
217
|
+
- Approve assets (`asset.setStatus` to `approved` is refused: a human approves).
|
|
218
|
+
- Change the board or the Claude Design canvas: a board change is `xtui` plus a re-import
|
|
219
|
+
(`import.reimport` from here merges it and keeps the editor's changes).
|