@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.
Files changed (36) hide show
  1. package/README.md +22 -2
  2. package/package.json +41 -4
  3. package/payload/plugins/xtframe/.claude-plugin/plugin.json +17 -0
  4. package/payload/plugins/xtframe/.codex-plugin/plugin.json +11 -0
  5. package/payload/plugins/xtframe/gemini-extension.json +5 -0
  6. package/payload/plugins/xtframe/skills/xtui/SKILL.md +245 -0
  7. package/payload/plugins/xtframe/skills/xtui/references/canvas.md +93 -0
  8. package/payload/plugins/xtframe/skills/xtui/references/dialect.md +874 -0
  9. package/payload/plugins/xtframe/skills/xtui/references/flow.md +339 -0
  10. package/payload/plugins/xtframe/skills/xtui/references/from-procedural.md +140 -0
  11. package/payload/plugins/xtframe/skills/xtui/references/not-like-web.md +358 -0
  12. package/payload/plugins/xtframe/skills/xtui/references/performance.md +182 -0
  13. package/payload/plugins/xtframe/skills/xtui/references/responsive.md +137 -0
  14. package/payload/plugins/xtframe/skills/xtui/references/style-groups.md +404 -0
  15. package/payload/plugins/xtframe/skills/xtui/references/template.dc.html +56 -0
  16. package/payload/plugins/xtframe/skills/xtui/references/tokens.json +101 -0
  17. package/payload/plugins/xtframe/skills/xtui/references/ui-project.md +170 -0
  18. package/payload/plugins/xtframe/skills/xtui/references/upgrade.md +141 -0
  19. package/payload/plugins/xtframe/skills/xtui/references/vector.md +223 -0
  20. package/payload/plugins/xtframe/skills/xtui/references/verify.md +349 -0
  21. package/payload/plugins/xtframe/skills/xtui-editor/SKILL.md +219 -0
  22. package/payload/plugins/xtframe/skills/xtui-editor/references/design.md +158 -0
  23. package/payload/plugins/xtframe/skills/xtui-editor/references/ops.md +988 -0
  24. package/payload/plugins/xtframe/skills/xtui-editor/references/recipes.md +70 -0
  25. package/payload/plugins/xtframe/skills/xtui-editor/references/scenarios.md +211 -0
  26. package/payload/plugins/xtframe/skills/xtui-editor/references/service.md +175 -0
  27. package/src/agents.mjs +73 -0
  28. package/src/bin.mjs +4 -0
  29. package/src/cli.mjs +286 -0
  30. package/src/converter.mjs +73 -0
  31. package/src/fsutil.mjs +76 -0
  32. package/src/install.mjs +154 -0
  33. package/src/packs.mjs +150 -0
  34. package/src/plugins.mjs +109 -0
  35. package/src/proc.mjs +66 -0
  36. 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).