@xtframe/skills 0.18.0 → 0.19.2

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.
@@ -10,10 +10,19 @@ screenshot budget; `scenario_check` evaluates its `done_when`. The product's con
10
10
  `xtui://contracts/<name>.yaml` resource). Read and meta operations are always allowed; everything
11
11
  else must match `allowed_ops` and not `forbidden_ops`.
12
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).
13
+ Scope: `full` (the whole document), `read-only`, `tokens-only`, `subtree` (needs `root` or a
14
+ selected layer), `selection-or-named` (the subtree of `root` when you give one, else of the work
15
+ site's selection -- the user's selection in the editor -- else the whole document). A scope taken
16
+ from the selection is said in the reply's `notes`; `root: "*"` asks for the whole document. Under a
17
+ subtree scope every op the contract lists works, Global ones (`style.setRule`, `timeline.create`)
18
+ and project-file writes (`shader.create`, `shader.setSource`) included.
15
19
  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.
20
+ timeline screenshot; going over is refused. Setting a scenario resets both. The numbers are the
21
+ contract's `budget`; a project that needs more (a long animation) raises them in its own
22
+ `contracts/scenarios/<name>.yaml` (a copy of the product's file with a larger `budget`) -- ask
23
+ the user, do not write it on your own. To look at many moments of a long animation without
24
+ spending the budget, use `xtframe-view <ui> --headless --renderer wgpu --advance <seconds>
25
+ --frames 1 --screenshot out.png` (`service.md`).
17
26
  Model (`model.minCaps`, optional): what the editor's built-in agent needs from its model --
18
27
  `tools`, `vision` or both; the AI panel and `xtframe-editor --service --agent` refuse to start a
19
28
  scenario whose model lacks one. Tokens (`budget.tokens`, optional, 1 to 5,000,000): the built-in
@@ -71,7 +80,8 @@ wrote is still `draft` (manual: a human approves). Report: `entries_added`, `ent
71
80
  `layer.*`, `style.*`, `timeline.*`, `animate.*`, `animation.*`, `trigger.set`, `bind.set`,
72
81
  `port.set`, `wire.port`, `symbol.*`, `state.*`, `asset.import`, `asset.replace`, `asset.slice`,
73
82
  `asset.sync`, `layout.anchor`, `restyle`, `fx.apply`, `doc.setSource`, `doc.save`,
74
- `export.lottie`, `undo`, `redo`, `flow.set`; forbidden: `asset.setStatus`, `symbol.detach`. Done:
83
+ `export.lottie`, `undo`, `redo`, `flow.set`, `catalog.add`, `catalog.list`, `diagnostics.*`, `shader.*`
84
+ (`timeline.removeTrack` is one of `timeline.*`); forbidden: `asset.setStatus`, `symbol.detach`. Done:
75
85
  no lint error; `motion.safeArea`, `motion.fontSize` and `lint.literalColor` clean (token usage >=
76
86
  90%); the content fits the viewport; nothing off screen.
77
87
 
@@ -80,12 +90,13 @@ no lint error; `motion.safeArea`, `motion.fontSize` and `lint.literalColor` clea
80
90
  `layer.setProps`, `layer.setAttrs`, `layer.setFlags`, `layout.anchor`, `style.*` (token
81
91
  replacement, selector renames, moving or deleting imported rules), `restyle`, `state.*`,
82
92
  `symbol.create`, `symbol.override`, `trigger.set`, `timeline.create`, `timeline.rename`,
83
- `animate.*`, `asset.replace`, `doc.save`, `undo`, `redo`; forbidden: `layer.delete`,
93
+ `animate.*`, `asset.replace`, `doc.save`, `undo`, `redo`, `repair.dedup`, `repair.effectBase`,
94
+ `repair.passthrough`, `diagnostics.fix`, `diagnostics.accept`; forbidden: `layer.delete`,
84
95
  `symbol.detach`, `asset.setStatus`. Done: no lint error; `tags.unconverted` and `tags.unknown`
85
96
  clean; every import-report warning handled or marked (manual).
86
97
 
87
98
  **restyle** -- allowed: `style.*` (the style stack ops included), `restyle`, `fx.apply`,
88
- `layer.setProps`, `doc.save`, `undo`, `redo`; forbidden: `layer.create`, `layer.delete`,
99
+ `layer.setProps`, `catalog.add`, `catalog.list`, `doc.save`, `undo`, `redo`; forbidden: `layer.create`, `layer.delete`,
89
100
  `layer.move`, `layer.rename`, `symbol.*`. Done: no lint error; text contrast at least 4.5:1
90
101
  (manual).
91
102
 
@@ -93,10 +104,11 @@ clean; every import-report warning handled or marked (manual).
93
104
  `layer.*`, `timeline.*`, `animate.*`, `animation.*`, `trigger.set`, `bind.set`, `port.set`,
94
105
  `wire.port`, `state.*`, `symbol.create`, `symbol.instantiate`, `symbol.override`, the style
95
106
  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.
107
+ `style.copyStyles`, `style.pasteStyles`), `fx.apply`, `catalog.add`, `catalog.list`,
108
+ `layout.anchor`, `doc.save`, `undo`, `redo`; forbidden: `symbol.detach`, `style.setToken`,
109
+ `restyle` (a token change is not one element). Under its `subtree` scope the listed whole-document
110
+ operations work too (`timeline.create`, `timeline.rename` ...); one it does not list
111
+ (`style.setRule`) is refused. Done: no lint error; no text overflows.
100
112
 
101
113
  **add-animation** -- allowed: `vector.*`, `bone.*`, `constraint.*`, `skin.*`, `mesh.*`, `cel.*`,
102
114
  `animate.*`, `animation.*` (`animation.preset`, `animation.followPath`), `timeline.*`,
@@ -111,13 +123,34 @@ instance's variant: `{"variant:<prop>": value}`), `timeline.*`, `animate.emphasi
111
123
  and `lint.triggerTimeline` clean; every hover has a matching leave (manual).
112
124
 
113
125
  **effects** -- allowed: `fx.*`, `layer.setProps`, `layer.addAdjustment`, `layer.removeAdjustment`,
114
- `style.*`, `timeline.*`, `doc.save`, `undo`, `redo`;
126
+ `style.*`, `timeline.*`, `catalog.add`, `catalog.list`, `layer.setAttrs` (the numbers of a
127
+ `<particles>` layer are its attributes), `doc.save`, `undo`, `redo`;
115
128
  forbidden: `layer.create`, `layer.delete`. Done: effect layers within budget;
116
129
  `motion.effectLayers` and `motion.backdropBlur` clean.
117
130
 
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).
131
+ **shader** -- allowed: `shader.*` (`shader.list`, `shader.get`, `shader.create`, `shader.setSource`:
132
+ the `.xtfx` file itself, see ops.md "Custom shaders"; allowed under a subtree scope too), `fx.apply`,
133
+ `layer.setProps`, `catalog.add` (apply it: `catalog.add {id: "custom", file: "<name>", layer}`),
134
+ `doc.save`, `undo`, `redo`; forbidden: `layer.create`,
135
+ `layer.delete`. A source the parser refuses comes back with `errors: [{line, column, message}]`.
136
+ Done: the document compiles; a shader compile error was retried at most once (manual).
137
+
138
+ *Custom shader inputs (`XtInput`, `.xtfx`)* -- `i.uv` is screen space: 0..1 across the effect's
139
+ off-screen window (the content's on-screen bounding box plus `expand`, clipped to the viewport),
140
+ top-down. A transform on the layer or its parents does not move or turn it, and a full-screen layer
141
+ that slides leaves it where it was: use it for full-screen post effects (vignette, grain, colour
142
+ fringing). `i.local` follows the layer: 0..1 across the layer's own border box (top-left 0,0),
143
+ through the layer's and its parents' transforms, so it moves, scales and rotates with the layer;
144
+ in the `expand` margin outside the box it is below 0 or above 1. `i.boxSize` is the border box size
145
+ in CSS px (no dpr). Effects that stick to the content (a light beam, a glow, scan lines lined up
146
+ with it) use `local`. A `vec2` parameter is a plain pair of numbers: compare it with `uv` or with
147
+ `local`, whichever the shader means. `i.texelSize` / `i.layerSize` describe the window in device
148
+ pixels. On a vector or scene layer (a shape or group inside an `<svg>`) the box is the layer's own
149
+ geometry box in its local space, without the stroke (a group: the union of its shapes; the same box
150
+ an `objectBoundingBox` gradient uses), so the stroke falls outside 0..1. `local` and `boxSize` are 0
151
+ on a layer with no geometry and on a host whose shader wrapper predates them. The software renderer never runs a shader -- it applies the
152
+ `fallback:` -- so look at a shader with `xtframe-view --headless --renderer wgpu`, not the default
153
+ software render.
121
154
 
122
155
  **data-binding** -- allowed: `port.*`, `bind.*`, `wire.port`, `trigger.set`, `doc.save`, `undo`,
123
156
  `redo`, `flow.set`; forbidden: `layer.delete`. Done: `lint.portUnbound` clean; no lint error.
@@ -50,6 +50,11 @@ last, which may not have your project open. Prefer `--project`.
50
50
  claude mcp add xtframe -- <xtframe>/bin/win_x64/Release/xtframe-mcp.exe --project <dir>
51
51
  ```
52
52
 
53
+ **Reading `xtframe-mcp` from a script**: its stdin / stdout are UTF-8. On Windows a Python script
54
+ must say so -- `subprocess.Popen([...], stdin=PIPE, stdout=PIPE, encoding="utf-8")` (or
55
+ `subprocess.run(..., capture_output=True, encoding="utf-8")`); without `encoding` Python uses the
56
+ system code page and Chinese layer names, text and messages come back garbled.
57
+
53
58
  **Raw HTTP MCP** (no adapter): `POST http://127.0.0.1:<port>/mcp` with `Authorization: Bearer
54
59
  <token>`. The registry entry names the editor's `url` but never its token: the token is in
55
60
  `service.json` (a headless editor's own service file for a headless one), so `xtframe-mcp
@@ -119,7 +124,10 @@ keep editing while you work. Each time you connect:
119
124
  3. `checkpoint_begin {"scenario": ...}` before the first edit (skip it when the editor's AI panel
120
125
  started you: its prompt says so).
121
126
  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`).
127
+ budgeted `scene_screenshot`s (animations: a `timeline` plus 3-6 `times`). Outside the editor, a
128
+ saved UI at a later second (flows and on:show timelines included) is
129
+ `xtframe-view <ui> --headless --renderer wgpu --advance 54 --frames 1 --screenshot out.png`
130
+ (`--advance` runs the time before it without painting; no screenshot budget).
123
131
  5. `scenario_check` evaluates the contract's `done_when`; fix what fails, report the `manual` items.
124
132
  6. `session_endScenario` ends the work item: it saves, and when you wrote anything runs the gates
125
133
  and sets the checkpoint "<seat> · <scenario> · HH:MM" whose note holds `{workItem, seat,