@xtframe/skills 0.0.0-stage → 0.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (35) hide show
  1. package/README.md +22 -2
  2. package/package.json +41 -4
  3. package/payload/plugins/xtframe/.claude-plugin/plugin.json +17 -0
  4. package/payload/plugins/xtframe/.codex-plugin/plugin.json +11 -0
  5. package/payload/plugins/xtframe/gemini-extension.json +5 -0
  6. package/payload/plugins/xtframe/skills/xtui/SKILL.md +218 -0
  7. package/payload/plugins/xtframe/skills/xtui/references/canvas.md +90 -0
  8. package/payload/plugins/xtframe/skills/xtui/references/dialect.md +799 -0
  9. package/payload/plugins/xtframe/skills/xtui/references/flow.md +338 -0
  10. package/payload/plugins/xtframe/skills/xtui/references/not-like-web.md +358 -0
  11. package/payload/plugins/xtframe/skills/xtui/references/performance.md +162 -0
  12. package/payload/plugins/xtframe/skills/xtui/references/responsive.md +137 -0
  13. package/payload/plugins/xtframe/skills/xtui/references/style-groups.md +378 -0
  14. package/payload/plugins/xtframe/skills/xtui/references/template.dc.html +56 -0
  15. package/payload/plugins/xtframe/skills/xtui/references/tokens.json +42 -0
  16. package/payload/plugins/xtframe/skills/xtui/references/ui-project.md +161 -0
  17. package/payload/plugins/xtframe/skills/xtui/references/upgrade.md +140 -0
  18. package/payload/plugins/xtframe/skills/xtui/references/vector.md +219 -0
  19. package/payload/plugins/xtframe/skills/xtui/references/verify.md +327 -0
  20. package/payload/plugins/xtframe/skills/xtui-editor/SKILL.md +209 -0
  21. package/payload/plugins/xtframe/skills/xtui-editor/references/design.md +158 -0
  22. package/payload/plugins/xtframe/skills/xtui-editor/references/ops.md +849 -0
  23. package/payload/plugins/xtframe/skills/xtui-editor/references/recipes.md +70 -0
  24. package/payload/plugins/xtframe/skills/xtui-editor/references/scenarios.md +180 -0
  25. package/payload/plugins/xtframe/skills/xtui-editor/references/service.md +167 -0
  26. package/src/agents.mjs +73 -0
  27. package/src/bin.mjs +4 -0
  28. package/src/cli.mjs +286 -0
  29. package/src/converter.mjs +73 -0
  30. package/src/fsutil.mjs +76 -0
  31. package/src/install.mjs +154 -0
  32. package/src/packs.mjs +150 -0
  33. package/src/plugins.mjs +109 -0
  34. package/src/proc.mjs +66 -0
  35. package/src/tar.mjs +103 -0
@@ -0,0 +1,70 @@
1
+ Read this when a change could reuse a ready-made preset (an entrance, an emphasis, an effect, a layout) instead of being built step by step.
2
+
3
+ # Recipes
4
+
5
+ A recipe is a named, reusable way to do a common change (Docs/design/29-ai-endpoint.md §29.5): a
6
+ motion preset, an effect template, a layout template. Recipes are data, not code: the Editor
7
+ Service applies them through its intent operations.
8
+
9
+ ## Where they are today
10
+
11
+ - **No recipe library ships yet.** A UI Project may keep its own under `shared/recipes/`
12
+ (Docs/design/30-ui-project.md §30.2, class 7); read it with `project_get {"section":
13
+ "conventions"}` / `project_search {"query": "recipe"}`, or list the directory if you have the
14
+ project path. When it exists, list its entries to the user by name before choosing one.
15
+ - There is no `recipe.list` or `recipe.apply` operation in the current service (see
16
+ `references/ops.md`); `service_ops` is the authority -- if a later editor adds them, they will
17
+ be listed there, and they take precedence over this file.
18
+
19
+ ## What to use instead
20
+
21
+ The intent operations are the built-in recipes, and they follow the project's motion spec:
22
+
23
+ | Want | Use |
24
+ |---|---|
25
+ | an entrance / exit | `animate.entrance` / `animate.exit` with `style` `fade`, `rise`, `scale` / `fade`, `sink`, `scale` |
26
+ | a pulse, shake or glow on attention | `animate.emphasis` with `kind` `pulse`, `shake`, `glow` |
27
+ | HUD corners, a menu list, an inventory grid placed on the safe area | `layout.anchor` with `template` `hud-corners`, `menu-list`, `inventory` |
28
+ | an effect look | `fx.apply` with a template from `shared/fx/*.xtfxp` (`project_get {"section": "assets"}`) |
29
+ | a palette or mood | `restyle` with a token map |
30
+ | a full state look | `state.apply` |
31
+
32
+ ## Character rig (a mascot, a portrait, a small character)
33
+
34
+ For breathing, a head turn, a nod, a wave, a hit reaction on one vector character (32 §32.5).
35
+ Scenario `create` (building it) or `add-animation` (animating an existing character).
36
+
37
+ 1. **Look first.** `vector_get {"layer": "Mascot", "normalize": true}`: the shapes, their vertices
38
+ and any `skeletons` already there. Parametric shapes cannot be skinned:
39
+ `vector_bake {"layer": "Mascot"}` turns them into paths.
40
+ 2. **Bones from the root out.** One root bone at the pivot (hips, neck base), children toward
41
+ the tips: `bone_add {"layer": "Mascot", "length": 60, "rotate": -90, "translate": [100, 180],
42
+ "id": "Spine"}`, then `bone_add {"layer": "Mascot", "parent": "Spine", "length": 40,
43
+ "rotate": 0, "id": "Head"}`. Lay each bone along the part it moves, inside the shape.
44
+ `bone_list` / `bone_world` to check; `bone_setRest` to fix a rest pose (do it now: weights are
45
+ computed from the rest pose).
46
+ 3. **Bind with auto weights.** `skin_bind {"shape": "Mascot/Body", "skeleton": "Rig"}` per shape
47
+ (rigid parts such as eyes: `auto {"blend": 0}` gives every vertex to its nearest bone).
48
+ 4. **Check and fine-tune.** `bone_pose {"bone": "Mascot/Head", "rotate": 25}` (live, no edit)
49
+ and `scene_screenshot`; where a joint pinches or tears, `skin_get` the vertices there and
50
+ `skin_set` them (blend the two bones around the joint), or `skin_smooth {"iterations": 2}`;
51
+ `skin_prune {"threshold": 0.05}` removes stray influences. A recompile drops the live pose.
52
+ 5. **Constraints.** An arm reaching for a point: `constraint_add {"bone": "Mascot/Forearm",
53
+ "kind": "ik", "target": "#Paw"}` and animate the target. Hair, ears, a tail: a child bone with
54
+ `constraint_add {"bone": "Mascot/Ear", "kind": "spring"}` follows its parent; key only the
55
+ parent.
56
+ 6. **Poses.** `bone_pose {..., "time": t}` writes one transform key per bone (timeline `main` by
57
+ default, `timeline` for another). Key the root and a few bones; let the IK and springs do the
58
+ rest. Keep idles small (a few degrees) and loop them with a trigger.
59
+ 7. **Confirm.** `lint_run` (`skin.*` clean), `scene_screenshot {"timeline": "main", "times": [...]}`
60
+ within the budget, and `export_lottie` when a Lottie copy is wanted (skinned paths bake per
61
+ frame; image meshes are skipped).
62
+
63
+ Do not animate a skinned shape's own transform (lint `skin.ownTransform`): move its bones.
64
+
65
+ The project's layout templates (`conventions/layouts/*.xt`) and symbols (`shared/symbols/`, the
66
+ copies of a symbol library's group, 49.3) are the other reusable pieces: `project_get {"section":
67
+ "conventions"}` and `symbol_list`, then `symbol_instantiate`. A symbol the project does not have
68
+ yet comes from a library group: `symbols_library` to see the groups, `symbols_use {"names": [...]}`
69
+ or `symbols_useGroup {"group": ...}` to copy them in (SKILL.md section 3b), then
70
+ `symbol_instantiate {"source": "project"}`.
@@ -0,0 +1,180 @@
1
+ Read this when you pick the scenario for a change: the 14 scenario contracts, when each applies, the scope and screenshot budget it gives you, and what "done" means for it.
2
+
3
+ # Scenario contracts
4
+
5
+ A scenario is a contract the editor enforces (Docs/design/29-ai-endpoint.md §29.4):
6
+ `session_setScenario {"name", "root"?}` sets your scope, the operations you may call and a
7
+ screenshot budget; `scenario_check` evaluates its `done_when`. The product's contracts are
8
+ `<xtframe>/editor/contracts/scenarios/<name>.yaml`; a UI Project may override one with
9
+ `contracts/scenarios/<name>.yaml` (read it with `project_get {"section": "contracts"}` or the
10
+ `xtui://contracts/<name>.yaml` resource). Read and meta operations are always allowed; everything
11
+ else must match `allowed_ops` and not `forbidden_ops`.
12
+
13
+ Scope: `full` (the whole document), `read-only`, `tokens-only`, `subtree` (needs `root`),
14
+ `selection-or-named` (the subtree of `root` when you give one, else the whole document).
15
+ Budget: `screenshots` counts static `scene_screenshot`s, `video_frames` each sampled time of a
16
+ timeline screenshot; going over is refused. Setting a scenario resets both.
17
+ Model (`model.minCaps`, optional): what the editor's built-in agent needs from its model --
18
+ `tools`, `vision` or both; the AI panel and `xtframe-editor --service --agent` refuse to start a
19
+ scenario whose model lacks one. Tokens (`budget.tokens`, optional, 1 to 5,000,000): the built-in
20
+ agent's total token limit for the scenario (input included); the agent stops at the smaller of it
21
+ and its own limit. `session_setScenario` returns both (`model`, `budget.tokens.max`); neither
22
+ limits an external agent.
23
+
24
+ ## Which one
25
+
26
+ | The user asks for | Scenario | Scope | Budget (shots / frames) | Model (`minCaps`) | Tokens |
27
+ |---|---|---|---|---|---|
28
+ | the design system: palette, variables, type, principles, references, audit, "warmer" | `design-system` | full | 2 / 0 (images 8) | tools, vision | 400k |
29
+ | a new screen built in the editor from a description | `create` | full | 2 / 6 | tools | 400k |
30
+ | cleaning up an import: names, anchors, states, warnings | `repair-import` | full | 2 / 0 | tools | 300k |
31
+ | a different look: colours, theme, mood | `restyle` | full | 2 / 0 | tools | 200k |
32
+ | one element only ("this button") | `single-element` | subtree (give `root`) | 2 / 6 | tools | 200k |
33
+ | entrance, exit or emphasis animation | `add-animation` | selection-or-named | 2 / 6 | tools | 200k |
34
+ | hover, pressed, focus, disabled, clicks | `states-interaction` | selection-or-named | 4 / 6 | tools | 200k |
35
+ | glow, blur, shadow, other effects | `effects` | selection-or-named | 2 / 6 | tools | 200k |
36
+ | a custom shader | `shader` | selection-or-named | 2 / 6 | tools | 200k |
37
+ | wiring game data: ports, bindings, lists | `data-binding` | selection-or-named | 1 / 0 | tools | 200k |
38
+ | other aspect ratios, safe area, longer translations | `multi-resolution` | full | 5 / 0 | tools, vision | 200k |
39
+ | frame time, too many effects | `performance` | full | 2 / 0 | tools, vision | 200k |
40
+ | a review, "what is wrong with this screen" | `review` | read-only | 6 / 6 | tools, vision | 200k |
41
+ | the symbol library: import a set, save project symbols as a group, reload a preset, export, mount | `library` | full | 0 / 0 (and the library-write permission) | tools | 200k |
42
+
43
+ A new screen from a description is normally the `xtui` skill (a board, then an import); use
44
+ `create` only when the user wants it built inside the open editor.
45
+
46
+ ## Allowed operations and done_when
47
+
48
+ Never in any contract (29 §29.17): `history.*`, `project.*` (with `conventions.put` and
49
+ `asset.linkFolder`), `design.approve` and `design.deprecate`. A work item makes its own history
50
+ entries; adopting, pruning and approving happen outside a scenario, by the user -- or by you when
51
+ the user made your seat a steward (SKILL.md "Taking over"). Every write that works on a document
52
+ carries `ifRevision` (ops.md "Revisions").
53
+
54
+ **design-system** (scenario 0; follow `design.md`) -- allowed: `design.get`, `design.search`,
55
+ `design.list`, `design.usage`, `design.audit`, `design.extractPalette`, `design.deriveScale`,
56
+ `design.contrast`, `design.put`, `design.delete`, `design.importReference`,
57
+ `design.importDesignSystem`, `design.link`, `design.unlink`, `design.build`, `design.lint`,
58
+ `design.diff`, `design.export`, `style.setToken`, `scene.screenshot`, `doc.save`, `undo`, `redo`;
59
+ forbidden: `design.approve`, `design.deprecate`, `layer.delete`, `symbol.detach`, `restyle` (a
60
+ person ticks restyle suggestions first). `project.get` / `project.search` are reads and stay
61
+ available. Budget: 2 screenshots, 8 images (each `design.get` of a `ref:` entry; over it is
62
+ `kBudget`), no video frames. Four entry points in the contract's `entries` -- `from-references`
63
+ (needs a vision model: `model.minCaps: [tools, vision]`), `from-existing`, `from-prompt`, `update` --
64
+ each with its inputs, required evidence and report keys; every one starts with `design.get` and
65
+ ends with `design.build`. Done: no lint error; `design.build` called and its lint counts reported
66
+ (manual); every new swatch has a `derived-from` link or an audit source (manual); every entry you
67
+ wrote is still `draft` (manual: a human approves). Report: `entries_added`, `entries_changed`,
68
+ `drafts`, `coverage`, `unlinked`, `lint`, `chosen`, `omitted`.
69
+
70
+ **create** -- allowed: `vector.*`, `bone.*`, `constraint.*`, `skin.*`, `mesh.*`, `cel.*`,
71
+ `layer.*`, `style.*`, `timeline.*`, `animate.*`, `animation.*`, `trigger.set`, `bind.set`,
72
+ `port.set`, `wire.port`, `symbol.*`, `state.*`, `asset.import`, `asset.replace`, `asset.slice`,
73
+ `asset.sync`, `layout.anchor`, `restyle`, `fx.apply`, `doc.setSource`, `doc.save`,
74
+ `export.lottie`, `undo`, `redo`, `flow.set`; forbidden: `asset.setStatus`, `symbol.detach`. Done:
75
+ no lint error; `motion.safeArea`, `motion.fontSize` and `lint.literalColor` clean (token usage >=
76
+ 90%); the content fits the viewport; nothing off screen.
77
+
78
+ **repair-import** -- allowed: `vector.*`, `bone.*`, `constraint.*`, `skin.*`, `mesh.*`,
79
+ `repair.import`, `repair.anchor`, `import.reimport`, `layer.rename`, `layer.group`,
80
+ `layer.setProps`, `layer.setAttrs`, `layer.setFlags`, `layout.anchor`, `style.*` (token
81
+ replacement, selector renames, moving or deleting imported rules), `restyle`, `state.*`,
82
+ `symbol.create`, `symbol.override`, `trigger.set`, `timeline.create`, `timeline.rename`,
83
+ `animate.*`, `asset.replace`, `doc.save`, `undo`, `redo`; forbidden: `layer.delete`,
84
+ `symbol.detach`, `asset.setStatus`. Done: no lint error; `tags.unconverted` and `tags.unknown`
85
+ clean; every import-report warning handled or marked (manual).
86
+
87
+ **restyle** -- allowed: `style.*` (the style stack ops included), `restyle`, `fx.apply`,
88
+ `layer.setProps`, `doc.save`, `undo`, `redo`; forbidden: `layer.create`, `layer.delete`,
89
+ `layer.move`, `layer.rename`, `symbol.*`. Done: no lint error; text contrast at least 4.5:1
90
+ (manual).
91
+
92
+ **single-element** -- allowed: `vector.*`, `bone.*`, `constraint.*`, `skin.*`, `mesh.*`, `cel.*`,
93
+ `layer.*`, `timeline.*`, `animate.*`, `animation.*`, `trigger.set`, `bind.set`, `port.set`,
94
+ `wire.port`, `state.*`, `symbol.create`, `symbol.instantiate`, `symbol.override`, the style
95
+ stack (`style.styles`, `style.addStyle`, `style.removeStyle`, `style.setStyleParams`,
96
+ `style.copyStyles`, `style.pasteStyles`), `fx.apply`, `layout.anchor`, `doc.save`, `undo`, `redo`;
97
+ forbidden: `symbol.detach`, `style.setToken`, `restyle` (a token change is not one element). The
98
+ `subtree` scope still refuses whole-document operations (`timeline.rename`, `style.setRule` ...).
99
+ Done: no lint error; no text overflows.
100
+
101
+ **add-animation** -- allowed: `vector.*`, `bone.*`, `constraint.*`, `skin.*`, `mesh.*`, `cel.*`,
102
+ `animate.*`, `animation.*` (`animation.preset`, `animation.followPath`), `timeline.*`,
103
+ `trigger.set`, `doc.save`, `export.lottie`, `undo`, `redo`; forbidden: `layer.delete`,
104
+ `layout.*`. Done: `motion.duration`, `motion.entrance`, `motion.animateOnly` and
105
+ `lint.triggerTimeline` clean; every target has an `intro` bound to `on:show` (manual); three
106
+ frames show no overlap or clipping (manual).
107
+
108
+ **states-interaction** -- allowed: `state.*`, `trigger.*`, `symbol.*`, `layer.setAttrs` (an
109
+ instance's variant: `{"variant:<prop>": value}`), `timeline.*`, `animate.emphasis`, `doc.save`,
110
+ `undo`, `redo`, `flow.set`; forbidden: `layer.delete`, `symbol.detach`. Done: `lint.stateNoDiff`
111
+ and `lint.triggerTimeline` clean; every hover has a matching leave (manual).
112
+
113
+ **effects** -- allowed: `fx.*`, `layer.setProps`, `layer.addAdjustment`, `layer.removeAdjustment`,
114
+ `style.*`, `timeline.*`, `doc.save`, `undo`, `redo`;
115
+ forbidden: `layer.create`, `layer.delete`. Done: effect layers within budget;
116
+ `motion.effectLayers` and `motion.backdropBlur` clean.
117
+
118
+ **shader** -- allowed: `fx.apply`, `layer.setProps`, `doc.save`, `undo`, `redo` (there is no
119
+ `shader.*` operation); forbidden: `layer.create`, `layer.delete`. Done: the document compiles; a
120
+ shader compile error was retried at most once (manual).
121
+
122
+ **data-binding** -- allowed: `port.*`, `bind.*`, `wire.port`, `trigger.set`, `doc.save`, `undo`,
123
+ `redo`, `flow.set`; forbidden: `layer.delete`. Done: `lint.portUnbound` clean; no lint error.
124
+
125
+ **multi-resolution** -- allowed: `layout.anchor`, `layer.setProps`, `layer.setAttrs`,
126
+ `layer.setText`, `style.setRule` and `style.deleteRule` (`@media` blocks: `media`),
127
+ `style.setToken`, `doc.save`, `undo`, `redo`; forbidden: `layer.delete`. Done: nothing outside
128
+ the safe area; no text overflow (dump and lint); content fits; 16:9, 4:3, 21:9 and 9:16
129
+ screenshots and the longest translation checked (manual).
130
+
131
+ **performance** -- allowed: `fx.*`, `layer.setProps`, `layout.anchor`, `style.setRule`,
132
+ `style.setToken`, `vector.bake`, `doc.save`, `undo`, `redo`; forbidden: `layer.delete`. Done:
133
+ effect layers within budget; `motion.effectLayers` clean; `perf.probe` before and after compared
134
+ in the report (manual).
135
+
136
+ **library** (T-502, 49.7) -- allowed: `symbols.saveAsGroup`, `symbols.loadPreset`,
137
+ `symbols.import`, `symbols.export`, `symbols.mountLibrary`, `symbols.unmountLibrary`; forbidden:
138
+ `layer.*`, `style.*`, `timeline.*`, `symbol.*`, `doc.setSource`, `import.reimport`. The project
139
+ writes `symbols.use` / `useGroup` / `updateCopy` are **not** here: they belong to `create`,
140
+ `restyle`, `repair-import` and `single-element`. Every allowed op also needs the library-write
141
+ permission (`kPermissionDenied` until the user allows it: the preference "Allow AI to change symbol
142
+ libraries" or a one-time approval; a client cannot grant it to itself)
143
+ -- the scenario alone does not grant it. Done (all manual): every imported set was linted first
144
+ (`symbols.lint {path}`) and its licence and findings shown to the user, who agreed; a URL was
145
+ `https`; no project copy was updated by this scenario. Report: `groups_added`, `groups_updated`,
146
+ `groups_trashed`, `lint`, `licenses`, `chosen`, `omitted`.
147
+
148
+ **review** -- no operation besides reading and feedback (`style.styles` included), and
149
+ `layer.setFlags` (the editor's hide / lock / color / adjustment-eye flags; not a document edit). Done: lint findings, screenshots and
150
+ motion-spec violations reported; nothing changed.
151
+
152
+ **Example for `create` / `add-animation`: a mascot or character small motion** (32 §32.5; the
153
+ contract files carry the same example). Build the bones, bind with auto weights, key two poses,
154
+ add one IK, then confirm with an export:
155
+
156
+ ```
157
+ bone_add {"layer": "Mascot", "length": 60, "rotate": -90, "translate": [100, 180], "id": "Spine"}
158
+ bone_add {"layer": "Mascot", "parent": "Spine", "length": 40, "rotate": 0, "id": "Head"}
159
+ skin_bind {"shape": "Mascot/Body", "skeleton": "Rig"}
160
+ bone_pose {"bone": "Mascot/Head", "rotate": -8, "time": 0}
161
+ bone_pose {"bone": "Mascot/Head", "rotate": 8, "time": 1}
162
+ bone_add {"layer": "Mascot", "parent": "Head", "length": 20, "rotate": 0, "id": "Arm"}
163
+ constraint_add {"bone": "Mascot/Arm", "kind": "ik", "target": "#Paw"}
164
+ bone_world {"bone": "Mascot/Arm"} -> lint_run (skin.* clean) -> scene_screenshot {"timeline": "main", "times": [0, 0.5, 1]}
165
+ export_lottie {"path": "<abs>/mascot.json"} (skinned paths bake per frame; check baked[] / skipped[])
166
+ ```
167
+
168
+ `export.lottie` is a whole-document operation: under `add-animation` with a `root` (a subtree
169
+ scope) it is refused; call it without `root`, or after leaving the scenario. The rig operations
170
+ are also listed for `single-element` and `repair-import` (fixing one character, re-binding after
171
+ a re-import). The full recipe is in `recipes.md` ("Character rig").
172
+
173
+ ## Working inside a contract
174
+
175
+ - Call `session_setScenario` before `checkpoint_begin`; the scenario does not open a checkpoint by
176
+ itself.
177
+ - `session_getScope` shows the active scenario and how much budget is left; spend screenshots on
178
+ the final state, not on every step (`scene_dump` and `lint_run` are free).
179
+ - `scenario_check` at the end; fix what fails, and list the `manual` items in the report with what
180
+ you checked for each.
@@ -0,0 +1,167 @@
1
+ Read this when you want to change an open XTFrame UI through the editor itself (the Editor Service) instead of writing files: over MCP (`xtframe-mcp`), or line by line over stdio (`xtframe-editor --service --stdio`).
2
+
3
+ # The Editor Service
4
+
5
+ The editor exposes typed operations on the open UI: `layer.*`, `style.*`, `timeline.*`,
6
+ `trigger.*`, `bind.*`, `port.*`, `symbol.*`, `state.*`, intent operations (`animate.entrance`,
7
+ `layout.anchor`, `restyle`, `fx.apply`, `repair.import`, ...), feedback (`scene.dump`,
8
+ `scene.screenshot`, `lint.run`, `perf.probe`) and bookkeeping (`checkpoint.*`, `session.*`,
9
+ `scenario.*`). Every operation has a JSON schema: `<xtframe>/schemas/editor-service/<op>.json`, or
10
+ `service.ops`. Nothing else is executed: there is no "run this code" operation. The operations by
11
+ kind, with the usual sequences, are in `references/ops.md`.
12
+
13
+ ## 1. Choose the target, then connect
14
+
15
+ The order is fixed: **project > gui > headless > directory**.
16
+
17
+ 1. **Project**: settle the UI Project directory (`<dir>`, holding `<name>.xtui`) before anything
18
+ else. The user may have several editors open -- two GUIs on one project, GUIs on different
19
+ projects, a headless editor next to a GUI. Every editor that has a project open registers in
20
+ `<dir>/.xtcache/editors/<pid>.json` (`{pid, kind: gui|headless, seat, service, since}`); nothing
21
+ is locked.
22
+ 2. **GUI**: `xtframe-mcp --project <dir>` connects to a GUI that has `<dir>` open and listens.
23
+ When a GUI has it open but is not listening (Preferences > AI > "Allow external AI connections"
24
+ is off), it **knocks**: it writes `<dir>/.xtcache/connect-request.json {agent, pid, time}`, the
25
+ GUI shows a non-modal bar "AI agent <name> wants to connect to this project [Allow] [Deny]
26
+ [Allow as steward] [ ] Always allow for this project", and `xtframe-mcp` waits up to 60 s.
27
+ "Allow as steward" also lets your seat run the gates (adopt, prune, approve, deprecate) -- for
28
+ this editor run, or with "Always allow" as `{"name", "steward": true}` in
29
+ `.xtcache/agents.json`. `--agent-name <name>`
30
+ sets the name shown (default: the MCP client's `clientInfo.name`, else `agent`). Denied
31
+ ("connection refused by the editor") or no answer ("no answer from the editor; turn on ..."):
32
+ exit 2, reason on stderr. Report it to the user; do not fall through to another target on your
33
+ own.
34
+ 3. **Headless**: no GUI has it open -> a listening headless editor that has it open.
35
+ 4. **Spawn**: still nothing -> with `--spawn-headless <dir> [--open <ui-id>]` (implies `--project
36
+ <dir>`) it starts `xtframe-editor --service --http --project <dir>` for the session and ends it
37
+ afterwards. Without it: "no editor has <dir> open; start one, or pass --spawn-headless <dir>".
38
+ 5. **Directory**: only when no editor can be used. Files are then written by `xtui` /
39
+ `xtframe-import`, never by this skill; afterwards every editor that has the UI open must reload
40
+ it -- it does so by itself when the UI has no unsaved edits (it watches its files), and you call
41
+ `doc_reload` as soon as you are connected (`doc_status` shows `diskNewer` when it could not).
42
+
43
+ Without `--project`, `xtframe-mcp` uses the global `%LOCALAPPDATA%/XTFrame/service.json` (`port`,
44
+ `token`, `url`; written while "Allow external AI connections" is on) -- whichever editor wrote it
45
+ last, which may not have your project open. Prefer `--project`.
46
+
47
+ **Register the adapter** once:
48
+
49
+ ```
50
+ claude mcp add xtframe -- <xtframe>/bin/win_x64/Release/xtframe-mcp.exe --project <dir>
51
+ ```
52
+
53
+ **Raw HTTP MCP** (no adapter): `POST http://127.0.0.1:<port>/mcp` with `Authorization: Bearer
54
+ <token>`. The registry entry names the editor's `url` but never its token: the token is in
55
+ `service.json` (a headless editor's own service file for a headless one), so `xtframe-mcp
56
+ --project` is the simpler way. The steps:
57
+
58
+ 1. `initialize` (JSON-RPC, with `clientInfo.name`: it becomes your seat's name). The service's own
59
+ `initialize` tool takes no arguments; symbol-library writes (49.7) need the user's leave, which
60
+ the editor asks for when the first one is refused.
61
+ 2. Take the `Mcp-Session-Id` header of that response and send it back on **every** later request.
62
+ 3. Send the notification `notifications/initialized`.
63
+ 4. `tools/call` with the tool name = the operation with `_` for `.` (`layer_setProps`).
64
+ 5. A `404` means the editor forgot the session (it restarted, or the user disconnected you):
65
+ `initialize` again. Scenario, checkpoints and scope belong to the MCP session, so they are gone:
66
+ set the scenario again.
67
+
68
+ **stdio JSON lines (no MCP).** `xtframe-editor --service --stdio --project <dir> <ui-id>`: one request
69
+ per line `{"id", "op", "args", "client"}`, one response per line `{"id", "ok", "result" | "error"}`
70
+ (`<xtframe>/tools/xtframe-service-cli.sh` is an example).
71
+
72
+ Over MCP results come back as `structuredContent` plus text, screenshots as images; a failed
73
+ operation is a tool result with `isError`. Resources: `xtui://project/AGENTS.md`,
74
+ `xtui://contracts/<scenario>.yaml`, `xtui://project/tokens`, `xtui://project/motion-spec`,
75
+ `xtui://project/conventions/<file>`, `xtui://schemas/<op>.json`, and the symbol libraries (49.7):
76
+ `xtframe://symbols/library` (every mounted library with its groups and symbols, = `symbols.library`)
77
+ and `xtframe://symbols/<library>/<group>/<Name>` (one symbol's full entry, = `symbols.get`; also a
78
+ resource template).
79
+
80
+ **Seats.** Each connection is a seat (MCP: `agent` named by `clientInfo.name`; stdio: `--seat`,
81
+ default `headless`); every commit and checkpoint names it. Each seat has its own active document:
82
+ `doc_open {"path": "<ui>"}` opens a UI in the background and makes it yours (the user's view stays;
83
+ `"show": true` switches it, only when asked); calls without `doc` go to it. `doc_list` shows your
84
+ `seat`, `activeDoc` and every seat's.
85
+
86
+ **Taking over (接手).** The user and you may replace each other at any moment, and the user may
87
+ keep editing while you work. Each time you connect:
88
+
89
+ 1. `session_getView`: the user's (or the previous seat's) selection, active timeline and playhead,
90
+ Animate, space, device, zoom and Edit in Place. Work where they were working; move the view
91
+ only with `session_setView` (the editor shows it and names your seat in its status bar). With
92
+ Animate on, `layer_setProps` records keyframes into the active timeline, as the user's edits do.
93
+ 2. `doc_changes {"since": <the last revision you saw, 0 when none>}`: every step since -- the user's
94
+ panel edits (`kind: command`, with the layers they had selected), other agents' operations
95
+ (`kind: op`), undo and redo -- oldest first. Read it before you change anything.
96
+ 3. Every write that works on a document carries `ifRevision` = the `revision` of your latest reply
97
+ for it. `kConflict`: read again (`doc_changes {since}` and what you are changing), retry **once**
98
+ with the new revision if the write still makes sense; a second `kConflict` -- stop and tell the
99
+ user. `undo` / `redo` only undo your own steps (the top of the shared stack must be yours).
100
+ 4. The gates (`history_adopt`, `history_prune`, `design_approve`, `design_deprecate`) answer
101
+ `kForbidden` unless the user made your seat a steward (knock bar "Allow as steward", the AI
102
+ panel's "Allow adopt and approve", `steward: true` in `.xtcache/agents.json`). As a steward, run
103
+ one only when the user asked for it, outside a scenario; the reply has `asSteward: true` and the
104
+ history records "<verb> by <seat> (steward): ..." under your seat.
105
+
106
+ ## 2. Work inside a scenario (a work item)
107
+
108
+ 1. `session_getView`, `doc_changes {since}`, `project_get` (summary, then `agents`, `tokens`,
109
+ `conventions`) and `scene_dump`.
110
+ 2. Pick the scenario from the table and call `session_setScenario {"name": ...}` (add `"root":
111
+ "<layer>"` for one element, `"entry": ...` for a contract entry point such as the design system's
112
+ `from-references` / `from-existing` / `from-prompt` / `update`; it comes back as `entry`). It sets
113
+ your scope, the operations you may call and your screenshot budget; calls outside it fail with the
114
+ reason. The scenario is a **work item on the main line**: with project history it starts with the
115
+ commit "Before <seat>: <scenario>" (`workItem.start`). Only with `"explore": true` -- when the user
116
+ wants to try something out -- does it run on a variant of its own (`variant`, named
117
+ "<seat>: <scenario>"); report the variant to the user, who compares and adopts or discards it in
118
+ the editor -- you adopt only as a steward, when the user asks.
119
+ 3. `checkpoint_begin {"scenario": ...}` before the first edit (skip it when the editor's AI panel
120
+ started you: its prompt says so).
121
+ 4. Edit (every write with `ifRevision`); check with `lint_run`, `scene_dump`, and at most the
122
+ budgeted `scene_screenshot`s (animations: a `timeline` plus 3-6 `times`).
123
+ 5. `scenario_check` evaluates the contract's `done_when`; fix what fails, report the `manual` items.
124
+ 6. `session_endScenario` ends the work item: it saves, and when you wrote anything runs the gates
125
+ and sets the checkpoint "<seat> · <scenario> · HH:MM" whose note holds `{workItem, seat,
126
+ scenario, entry, start, touched, gates}`. Read `gates` (`lint: {errors, warnings}`, `contract:
127
+ {ok, violations}`): nothing is rolled back, the History panel shows a badge, so fix until lint
128
+ has no error. Nothing written -> `{empty: true}`, no checkpoint. Starting the next scenario or
129
+ disconnecting ends it too; end it yourself, one work item at a time per MCP session.
130
+ 7. `checkpoint_commit` when the user is happy, `checkpoint_rollback` to throw everything away (your
131
+ own checkpoint rolls back in any scenario, unless someone else -- a human or another client --
132
+ edited the document since it began). An explore work item ends with "AI: <scenario> done"
133
+ committed on its variant; `session_setScenario {"name": "", "rollback": true}` discards that
134
+ variant instead (back to where the scenario began, `design/` files included; the variant is kept,
135
+ marked abandoned, until the user prunes it).
136
+ 8. End with what you chose, what you deliberately left out and which rule you broke, if any.
137
+
138
+ Destructive operations (`layer_delete`, `timeline_delete`, `symbol_detach`, `design_delete`,
139
+ overwriting `asset_import`) need `"confirm": true`, and only after the user said yes.
140
+
141
+ History (36): `history_status`, `history_list {kind: checkpoints|variants|log, ref?, limit?}`,
142
+ `history_checkpoint {name, note?}`, `history_variant {name, from?}`, `history_switch {to,
143
+ discard?}` and `history_compare {a, b}` are yours to call (outside a scenario; a project without
144
+ history answers `kUnsupported`). `history_restore {checkpoint}` (main back to a checkpoint, the
145
+ line left behind kept as a variant) is open to every seat -- only on the user's word. Adopting and
146
+ pruning (`history.adopt` / `prune`) are gates: `kForbidden` unless your seat is a steward (see
147
+ "Taking over" above), and never inside a scenario. `xtframe-mcp --scenario <name> [--entry <entry>]` and `xtframe-editor --service --stdio
148
+ --scenario <name> [--entry <entry>]` start the session under that scenario already.
149
+
150
+ Each scenario's scope, budget and `done_when` are in `references/scenarios.md`.
151
+
152
+ | The user asks for | Scenario |
153
+ |---|---|
154
+ | tokens, palette, conventions of a new project | `design-system` |
155
+ | a new screen from a description | `create` |
156
+ | cleaning up an import (names, anchors, states) | `repair-import` |
157
+ | a different look (colours, theme, mood) | `restyle` |
158
+ | one element only | `single-element` (with `root`) |
159
+ | entrance / exit / emphasis animation | `add-animation` |
160
+ | hover, pressed, states, clicks | `states-interaction` |
161
+ | glow, blur, shadow, other effects | `effects` |
162
+ | a custom shader | `shader` |
163
+ | wiring game data (ports, bindings) | `data-binding` |
164
+ | other aspect ratios, safe area, longer translations | `multi-resolution` |
165
+ | frame time, too many effects | `performance` |
166
+ | a review, "what is wrong with this screen" | `review` (read only) |
167
+ | the symbol library (import a set, save a group, reload a preset, export, mount) | `library` (plus the library-write permission) |
package/src/agents.mjs ADDED
@@ -0,0 +1,73 @@
1
+ // Coding agents this CLI knows: where each one reads skills, and how to tell it is installed.
2
+ // Paths follow vercel-labs/skills docs/agents.md (docs/01-research.md §1.1). `~` is the user's
3
+ // home; project paths are relative to the current directory. More agents (or corrected paths)
4
+ // can be added in ~/.xtframe/agents.json: [{ "id", "name", "detect": [...], "global", "project" }].
5
+ import fs from 'node:fs';
6
+ import path from 'node:path';
7
+
8
+ import { readJson } from './fsutil.mjs';
9
+
10
+ const BUILTIN = [
11
+ { id: 'claude-code', name: 'Claude Code', detect: ['~/.claude'], global: '~/.claude/skills', project: '.claude/skills', plugin: 'claude' },
12
+ { id: 'codex', name: 'Codex', detect: ['~/.codex'], global: '~/.agents/skills', project: '.agents/skills' },
13
+ { id: 'gemini-cli', name: 'Gemini CLI', detect: ['~/.gemini'], global: '~/.gemini/skills', project: '.agents/skills' },
14
+ { id: 'github-copilot', name: 'GitHub Copilot', detect: ['~/.copilot'], global: '~/.copilot/skills', project: '.agents/skills', plugin: 'copilot' },
15
+ { id: 'cursor', name: 'Cursor', detect: ['~/.cursor'], global: '~/.cursor/skills', project: '.agents/skills' },
16
+ { id: 'opencode', name: 'OpenCode', detect: ['~/.config/opencode'], global: '~/.config/opencode/skills', project: '.agents/skills' },
17
+ { id: 'windsurf', name: 'Windsurf', detect: ['~/.codeium/windsurf'], global: '~/.codeium/windsurf/skills', project: '.windsurf/skills' },
18
+ { id: 'antigravity', name: 'Antigravity', detect: ['~/.gemini/antigravity'], global: '~/.gemini/antigravity/skills', project: '.agents/skills' },
19
+ { id: 'amp', name: 'Amp', detect: ['~/.config/amp'], global: '~/.config/agents/skills', project: '.agents/skills' },
20
+ { id: 'cline', name: 'Cline', detect: ['~/.cline'], global: '~/.agents/skills', project: '.agents/skills' },
21
+ { id: 'kiro-cli', name: 'Kiro CLI', detect: ['~/.kiro'], global: '~/.kiro/skills', project: '.kiro/skills' },
22
+ { id: 'goose', name: 'Goose', detect: ['~/.config/goose'], global: '~/.config/goose/skills', project: '.goose/skills' },
23
+ { id: 'roo', name: 'Roo Code', detect: ['~/.roo'], global: '~/.roo/skills', project: '.roo/skills' },
24
+ { id: 'continue', name: 'Continue', detect: ['~/.continue'], global: '~/.continue/skills', project: '.continue/skills' },
25
+ { id: 'qwen-code', name: 'Qwen Code', detect: ['~/.qwen'], global: '~/.qwen/skills', project: '.qwen/skills' },
26
+ { id: 'droid', name: 'Droid (Factory)', detect: ['~/.factory'], global: '~/.factory/skills', project: '.agents/skills' },
27
+ { id: 'augment', name: 'Augment', detect: ['~/.augment'], global: '~/.augment/skills', project: '.augment/skills' },
28
+ { id: 'junie', name: 'Junie', detect: ['~/.junie'], global: '~/.junie/skills', project: '.junie/skills' },
29
+ { id: 'trae', name: 'Trae', detect: ['~/.trae'], global: '~/.trae/skills', project: '.trae/skills' },
30
+ ];
31
+
32
+ export function expandHome(p, home) {
33
+ if (p === '~') return home;
34
+ if (p.startsWith('~/')) return path.join(home, ...p.slice(2).split('/'));
35
+ return p;
36
+ }
37
+
38
+ /** All known agents (built-in, then ~/.xtframe/agents.json overriding by id). */
39
+ export function knownAgents(ctx) {
40
+ const extra = readJson(path.join(ctx.xtHome, 'agents.json'), []);
41
+ const byId = new Map(BUILTIN.map((a) => [a.id, a]));
42
+ for (const a of Array.isArray(extra) ? extra : []) {
43
+ if (a && typeof a.id === 'string' && a.global) byId.set(a.id, { name: a.id, detect: [a.global], project: '.agents/skills', ...a });
44
+ }
45
+ return [...byId.values()];
46
+ }
47
+
48
+ export function isDetected(agent, ctx) {
49
+ return (agent.detect || []).some((p) => fs.existsSync(expandHome(p, ctx.home)));
50
+ }
51
+
52
+ /** The skills directory of `agent` for a scope ('global' | 'project'). */
53
+ export function skillsDir(agent, scope, ctx) {
54
+ if (scope === 'project') return agent.project ? path.resolve(ctx.cwd, agent.project) : null;
55
+ return agent.global ? expandHome(agent.global, ctx.home) : null;
56
+ }
57
+
58
+ /**
59
+ * Agents to install into: `ids` (comma list, or 'all' for every known agent) or every detected
60
+ * one. Unknown ids throw.
61
+ */
62
+ export function selectAgents(ctx, ids) {
63
+ const all = knownAgents(ctx);
64
+ if (!ids) return all.filter((a) => isDetected(a, ctx));
65
+ if (ids === 'all') return all;
66
+ const out = [];
67
+ for (const id of ids.split(',').map((s) => s.trim()).filter(Boolean)) {
68
+ const a = all.find((x) => x.id === id);
69
+ if (!a) throw new Error(`unknown agent '${id}' (run 'xtframe-skills agents' for the list)`);
70
+ out.push(a);
71
+ }
72
+ return out;
73
+ }
package/src/bin.mjs ADDED
@@ -0,0 +1,4 @@
1
+ #!/usr/bin/env node
2
+ import { main } from './cli.mjs';
3
+
4
+ process.exitCode = main(process.argv.slice(2));