@xtframe/skills 0.0.0-stage → 0.18.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +22 -2
- package/package.json +41 -4
- package/payload/plugins/xtframe/.claude-plugin/plugin.json +17 -0
- package/payload/plugins/xtframe/.codex-plugin/plugin.json +11 -0
- package/payload/plugins/xtframe/gemini-extension.json +5 -0
- package/payload/plugins/xtframe/skills/xtui/SKILL.md +218 -0
- package/payload/plugins/xtframe/skills/xtui/references/canvas.md +90 -0
- package/payload/plugins/xtframe/skills/xtui/references/dialect.md +799 -0
- package/payload/plugins/xtframe/skills/xtui/references/flow.md +338 -0
- package/payload/plugins/xtframe/skills/xtui/references/not-like-web.md +358 -0
- package/payload/plugins/xtframe/skills/xtui/references/performance.md +162 -0
- package/payload/plugins/xtframe/skills/xtui/references/responsive.md +137 -0
- package/payload/plugins/xtframe/skills/xtui/references/style-groups.md +378 -0
- package/payload/plugins/xtframe/skills/xtui/references/template.dc.html +56 -0
- package/payload/plugins/xtframe/skills/xtui/references/tokens.json +42 -0
- package/payload/plugins/xtframe/skills/xtui/references/ui-project.md +161 -0
- package/payload/plugins/xtframe/skills/xtui/references/upgrade.md +140 -0
- package/payload/plugins/xtframe/skills/xtui/references/vector.md +219 -0
- package/payload/plugins/xtframe/skills/xtui/references/verify.md +327 -0
- package/payload/plugins/xtframe/skills/xtui-editor/SKILL.md +209 -0
- package/payload/plugins/xtframe/skills/xtui-editor/references/design.md +158 -0
- package/payload/plugins/xtframe/skills/xtui-editor/references/ops.md +849 -0
- package/payload/plugins/xtframe/skills/xtui-editor/references/recipes.md +70 -0
- package/payload/plugins/xtframe/skills/xtui-editor/references/scenarios.md +180 -0
- package/payload/plugins/xtframe/skills/xtui-editor/references/service.md +167 -0
- package/src/agents.mjs +73 -0
- package/src/bin.mjs +4 -0
- package/src/cli.mjs +286 -0
- package/src/converter.mjs +73 -0
- package/src/fsutil.mjs +76 -0
- package/src/install.mjs +154 -0
- package/src/packs.mjs +150 -0
- package/src/plugins.mjs +109 -0
- package/src/proc.mjs +66 -0
- package/src/tar.mjs +103 -0
|
@@ -0,0 +1,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