@xtframe/skills 0.19.1 → 0.19.3
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/package.json +1 -1
- package/payload/plugins/xtframe/.claude-plugin/plugin.json +1 -1
- package/payload/plugins/xtframe/.codex-plugin/plugin.json +1 -1
- package/payload/plugins/xtframe/gemini-extension.json +1 -1
- package/payload/plugins/xtframe/skills/xtui/references/dialect.md +33 -20
- package/payload/plugins/xtframe/skills/xtui/references/style-groups.md +8 -6
- package/payload/plugins/xtframe/skills/xtui/references/vector.md +2 -0
- package/payload/plugins/xtframe/skills/xtui/references/verify.md +1 -1
- package/payload/plugins/xtframe/skills/xtui-editor/SKILL.md +6 -0
- package/payload/plugins/xtframe/skills/xtui-editor/references/ops.md +21 -7
- package/payload/plugins/xtframe/skills/xtui-editor/references/scenarios.md +15 -8
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@xtframe/skills",
|
|
3
|
-
"version": "0.19.
|
|
3
|
+
"version": "0.19.3",
|
|
4
4
|
"description": "Search for XTFrame agent skills and install them, with the XTFrame converter, into every coding agent on this machine (Claude Code, Codex, Gemini CLI, Copilot, Cursor, OpenCode, ...).",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
@@ -275,23 +275,27 @@ DOM only exists in the browser, so they are dropped), and `<sc-for>` / `<sc-if>`
|
|
|
275
275
|
`grayscale()`, `hue-rotate()`, `invert()`, `sepia()`, `opacity()` and `drop-shadow()`.
|
|
276
276
|
The colour functions merge into one adjustment applied in a fixed order (brightness, contrast,
|
|
277
277
|
saturate/grayscale, hue-rotate, invert, sepia, opacity), not in the order written; each may appear
|
|
278
|
-
only once. Every other filter function is dropped.
|
|
279
|
-
(
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
`
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
278
|
+
only once. Every other filter function is dropped. XTFrame's own `brightness` is additive and
|
|
279
|
+
`hue-rotate()` is a YIQ hue rotation (18 §18.3), so a `hue-rotate()` that changes anything is
|
|
280
|
+
reported as `degraded`, and an out-of-range `contrast`/`saturate` is clamped with a finding
|
|
281
|
+
(24 §24.15.4, T-566a/b records).
|
|
282
|
+
- **`filter: brightness()` is converted to look the same as on the web** (18 §18.13 amendment,
|
|
283
|
+
T-824). The import composes the `brightness()` and `contrast()` of one `filter` in the order
|
|
284
|
+
written and writes them as a `contrast` + `brightness` pair: `brightness(0.4)` becomes
|
|
285
|
+
`color-adjust(contrast(-0.6) brightness(-0.75))`, which is CSS's `0.4 * colour`. Between
|
|
286
|
+
`brightness(1/3)` and `brightness(2)` the result matches the web with no finding (the editor's
|
|
287
|
+
panel then shows those two numbers, not the one you wrote). Outside that range:
|
|
288
|
+
`brightness(0)` is black, exact; below 1/3 white stays exact but dark tones turn black sooner than
|
|
289
|
+
on the web (`degraded: below 1/3 the dark tones turn black sooner ...`) -- for a strong dim put
|
|
290
|
+
a black element over it with `opacity` = 1 - the value instead (`brightness(0.2)` -> a black
|
|
291
|
+
overlay at `opacity: 0.8`); above 2 it is clamped to `brightness(2)` with a finding. A `filter`
|
|
292
|
+
that also holds `invert()`, `sepia()` or `opacity()` keeps the old additive conversion
|
|
293
|
+
(`brightness(0.4)` adds -0.6, so a dark background goes black) and says so as `degraded` --
|
|
294
|
+
keep `brightness()` out of such a `filter`. `backdrop-filter: brightness()` is still additive
|
|
295
|
+
with the same finding (`backdrop-blur` has no contrast): do not dim a backdrop with it.
|
|
296
|
+
`brightness()` and `drop-shadow()` in one `filter` work and may be keyed together (a silhouette
|
|
297
|
+
revealed with a rim light): every key lists both, in the same order; the rim light does not
|
|
298
|
+
darken with the brightness. Check such an element in a screenshot.
|
|
295
299
|
- `clip-path` with `inset()`, `circle()`, `ellipse()` or `polygon()` is supported **statically**
|
|
296
300
|
(a diagonal split screen: two layers with `polygon(0 0, 58% 0, 42% 100%, 0 100%)` and its
|
|
297
301
|
complement). It **cannot be animated**: a `clip-path` in a keyframe or a transition is dropped
|
|
@@ -332,7 +336,12 @@ DOM only exists in the browser, so they are dropped), and `<sc-for>` / `<sc-if>`
|
|
|
332
336
|
- Fonts (07 §7.20): `.ttf`, `.otf` and the collections `.ttc` / `.otc` are found (each face of a
|
|
333
337
|
collection is its own family); `font-weight` picks the nearest installed weight (CSS Fonts 4
|
|
334
338
|
rules, the `wght` axis of a variable font), and a weight of 600 or more on a family whose
|
|
335
|
-
heaviest face is lighter is drawn as synthetic bold.
|
|
339
|
+
heaviest face is lighter is drawn as synthetic bold. Within a family the normal-width face is
|
|
340
|
+
chosen before italic and weight (07 §7.21), so a family that also ships narrow or condensed faces
|
|
341
|
+
(`"Arial"`, `"Myriad Pro"`) draws its normal width; a face's older per-style family name
|
|
342
|
+
(`"Arial Narrow"`, `"Segoe UI Semibold"`) also matches when no face has that name as its
|
|
343
|
+
typographic family, which is how to ask for a narrow face (`font-stretch` is not supported;
|
|
344
|
+
`xtframe-view --list-fonts` prints such names as `alias-of=<family>`). When the first CJK family of a
|
|
336
345
|
`font-family` stack is not installed, import, `xtframe-view` and `xtframe-pack` report
|
|
337
346
|
`missing font '<family>'` (`font.missing`; the fix hint is the stack without that family)
|
|
338
347
|
instead of falling back silently: install the font or drop it from the stack. CJK line breaking
|
|
@@ -461,7 +470,8 @@ transition: <prop|all> <duration> [<easing>] [<delay>]
|
|
|
461
470
|
- Naming a `@keyframes` that does not exist is a compile error, not a warning.
|
|
462
471
|
- Accepted and drawn right (each tried in a converted project): `filter: grayscale(0)` to
|
|
463
472
|
`grayscale(1)` keyed (a freeze frame going grey); `brightness()` and `drop-shadow()` keyed
|
|
464
|
-
together in one `filter
|
|
473
|
+
together in one `filter` (each key's `brightness()` is converted on its own: the keys match the
|
|
474
|
+
web, the frames between them are slightly darker, since the pair is not linear in the factor); a looping `@keyframes` animation on the child of an element a timeline
|
|
465
475
|
moves; `steps()` with large step counts; a whole-shot `filter: blur(18px)` to `blur(0px)` on a
|
|
466
476
|
sliding container (a whip pan). Procedural motion of every kind: `references/from-procedural.md`.
|
|
467
477
|
|
|
@@ -474,7 +484,10 @@ works even when the `<defs>` comes after the shape or sits inside a `<g>`. No `<
|
|
|
474
484
|
Gradients must be defined inside the same `<svg>` that uses them; `fx`/`fy` (focal point),
|
|
475
485
|
`spreadMethod="reflect|repeat"`, and a radial gradient stretched into an ellipse (a non-uniform
|
|
476
486
|
or skewed `gradientTransform`, or `objectBoundingBox` on a non-square shape) are not supported:
|
|
477
|
-
the centre, pad and a circle are used, with a warning.
|
|
487
|
+
the centre, pad and a circle are used, with a warning. Linear gradients follow any
|
|
488
|
+
`gradientTransform` (skew, non-uniform scale) and a diagonal `objectBoundingBox` gradient on a
|
|
489
|
+
non-square shape as browsers draw them, and `objectBoundingBox` x `gradientTransform` is applied in
|
|
490
|
+
SVG's order for both kinds (T-829, T-830). Or upload a PNG. An inline `<svg>` is imported as
|
|
478
491
|
an editable vector layer (T-224); `data-xt-vector="file"` asks for a `shared/img/` file instead.
|
|
479
492
|
Inside `<svg>` tag and attribute names keep their case (`linearGradient`, `viewBox`,
|
|
480
493
|
`gradientUnits`), and intent tags work on the `<svg>` and on its shapes: a `data-xt-timeline` on
|
|
@@ -81,12 +81,12 @@ the same table is the Editor Service resource `xtui://style-groups.json`.
|
|
|
81
81
|
| Scale / 縮放 | `scale` | `scale` | layout | percent | % | | yes |
|
|
82
82
|
| Offset / 位移 | `translate` | `translate` | layout | text | | | yes |
|
|
83
83
|
| Auto orient / 自動定向 | `autoOrient` | `auto-orient` | layout | toggle | | `none`, `path` | |
|
|
84
|
-
| Clip content / 裁切內容 | `overflow` | `overflow` | layout | choice | | `visible`, `hidden`, `scroll` | |
|
|
84
|
+
| Clip content / 裁切內容 | `overflow` | `overflow` | layout | choice | | `visible`, `hidden`, `scroll`, `auto` | |
|
|
85
85
|
| Clip content X / 水平裁切內容 | `overflowX` | `overflow-x` | layout | choice | | | |
|
|
86
86
|
| Clip content Y / 垂直裁切內容 | `overflowY` | `overflow-y` | layout | choice | | | |
|
|
87
87
|
| Order / 順序 | `order` | `order` | layout | number | | | |
|
|
88
88
|
| Stacking order / 疊放順序 | `zIndex` | `z-index` | layout | number | | | |
|
|
89
|
-
| Display / 顯示方式 | `display` | `display` | layout | choice | | `block`, `flex`, `none` | |
|
|
89
|
+
| Display / 顯示方式 | `display` | `display` | layout | choice | | `block`, `flex`, `none`, `grid` | |
|
|
90
90
|
| Self alignment / 自身對齊 | `alignSelf` | `align-self` | layout | choice | | `auto`, `stretch`, `flex-start`, `flex-end`, `center` | |
|
|
91
91
|
| Flex / 伸縮 | `flex` | `flex` | layout | text | | | |
|
|
92
92
|
| Grow / 放大比例 | `flexGrow` | `flex-grow` | layout | number | 0.. | | yes |
|
|
@@ -107,8 +107,8 @@ Also present when `display` is `flex` or `grid`.
|
|
|
107
107
|
| Parameter | Parameter name | CSS property | Section | Row | Range / unit | Values | Animatable |
|
|
108
108
|
|---|---|---|---|---|---|---|---|
|
|
109
109
|
| Direction / 方向 | `flexDirection` | `flex-direction` | layout | choice | | `row`, `column` | |
|
|
110
|
-
| Wrap / 換行 | `flexWrap` | `flex-wrap` | layout | choice | | `nowrap`, `wrap` | |
|
|
111
|
-
| Distribution / 分布 | `justifyContent` | `justify-content` | layout | choice | | `flex-start`, `flex-end`, `center`, `space-between`, `space-around`, `space-evenly` | |
|
|
110
|
+
| Wrap / 換行 | `flexWrap` | `flex-wrap` | layout | choice | | `nowrap`, `wrap`, `wrap-reverse` | |
|
|
111
|
+
| Distribution / 分布 | `justifyContent` | `justify-content` | layout | choice | | `flex-start`, `flex-end`, `center`, `space-between`, `space-around`, `space-evenly`, `stretch` | |
|
|
112
112
|
| Alignment / 對齊 | `alignItems` | `align-items` | layout | choice | | `stretch`, `flex-start`, `flex-end`, `center` | |
|
|
113
113
|
| Line alignment / 行對齊 | `alignContent` | `align-content` | layout | choice | | `flex-start`, `flex-end`, `center`, `space-between`, `space-around`, `space-evenly`, `stretch` | |
|
|
114
114
|
| Cell alignment / 格內對齊 | `justifyItems` | `justify-items` | layout | choice | | | |
|
|
@@ -329,7 +329,7 @@ document at `hud/hud.xt` writes `texture="../shared/img/spark.png"`.
|
|
|
329
329
|
| Writing mode / 書寫方向 | `writingMode` | `writing-mode` | style | choice | | `horizontal-tb`, `vertical-rl`, `vertical-lr` | |
|
|
330
330
|
| Text orientation / 文字方向 | `textOrientation` | `text-orientation` | style | choice | | `mixed`, `upright`, `sideways` | |
|
|
331
331
|
| Language / 語言 | `lang` | `lang` | style | text | | | |
|
|
332
|
-
| Text rendering / 文字繪製 | `textRendering` | `text-rendering` | style | choice | | `auto`, `geometricPrecision
|
|
332
|
+
| Text rendering / 文字繪製 | `textRendering` | `text-rendering` | style | choice | | `auto`, `geometricPrecision` | |
|
|
333
333
|
| Transition / 過渡 | `transition` | `transition` | style | text | | | |
|
|
334
334
|
| Animation / 動畫 | `animation` | `animation` | style | text | | | |
|
|
335
335
|
| Layer / 圖層 | `layer` | `layer` | layout | text | | | |
|
|
@@ -390,7 +390,9 @@ names below -- e.g. `effect.color-adjust.saturation`, not `saturate`. With the s
|
|
|
390
390
|
in the chain use its index, `effect.<i>.<name>`. Every effect also has `enabled`; `color` is its
|
|
391
391
|
colour; a drop shadow's `offset` keys `offsetX` / `offsetY` as one value (`"<x>px <y>px"`).
|
|
392
392
|
`brightness` is **additive** (0 = unchanged, -1 = black), unlike CSS `brightness()`, which
|
|
393
|
-
multiplies.
|
|
393
|
+
multiplies. The board import writes a `filter: brightness(x)` as the equivalent pair
|
|
394
|
+
`contrast` x - 1 with `brightness` 0.5 - 0.5/x (T-824), so an imported element keys both; to dim
|
|
395
|
+
a layer by hand, lower `contrast` and `brightness` together the same way, or its `opacity`.
|
|
394
396
|
|
|
395
397
|
| Function | Track names (in order) | `color` |
|
|
396
398
|
|---|---|---|
|
|
@@ -35,6 +35,8 @@ and animated.
|
|
|
35
35
|
supported, each with a warning: `fx`/`fy` (the centre is used), `spreadMethod="reflect"` /
|
|
36
36
|
`"repeat"` (pad is used), and elliptical radial gradients -- a `gradientTransform` with
|
|
37
37
|
non-uniform scale or skew, or `objectBoundingBox` on a non-square shape, draws a circle.
|
|
38
|
+
Linear gradients have none of these limits: skew, non-uniform scale and a diagonal
|
|
39
|
+
`objectBoundingBox` gradient on a non-square shape draw as in a browser (T-829, T-830).
|
|
38
40
|
6. **Prefer declarative motion to hand-computed keyframes.** Use `path-trim` for strokes that
|
|
39
41
|
draw on, `transform` / `opacity` on shapes, and `d` keyframes only for real morphs. A morph
|
|
40
42
|
needs the same number of vertices in every keyframe.
|
|
@@ -263,7 +263,7 @@ still happen:
|
|
|
263
263
|
| `backdrop-filter` without `blur()`, or with a function other than `blur/saturate/brightness` | dropped + warning |
|
|
264
264
|
| `vw/vh/rem/em/calc()` | that declaration dropped + warning |
|
|
265
265
|
| `outline*` | kept (T-325); `dashed`/`dotted`/... become `solid` + warning |
|
|
266
|
-
| a `filter
|
|
266
|
+
| a `filter` function other than `blur`/`drop-shadow` and the colour functions (`references/dialect.md`) | dropped + warning |
|
|
267
267
|
| `<sc-for>` / `<sc-if>` / `renderVals()` | expanded **once** from `data-props` defaults; script output never appears |
|
|
268
268
|
| `<dc-import>` / `x-import` components | dropped + warning |
|
|
269
269
|
| a tag outside the allow list (`table`, `tr`, `td`, ...) | becomes `<div>` + warning (low fidelity) |
|
|
@@ -180,6 +180,12 @@ library, extra mounts, the project's) in **groups**; a project holds **copies**
|
|
|
180
180
|
without switching the user's view; `show: true` only when the user asked to see it.
|
|
181
181
|
- **One MCP session, one work item at a time**: finish one (`session_endScenario`) before starting
|
|
182
182
|
the next.
|
|
183
|
+
- **Arranging layers**: place, align, distribute, re-anchor and reorder with `layer_place`,
|
|
184
|
+
`layer_align`, `layer_distribute`, `layer_constrain` and `layer_order` (and create with
|
|
185
|
+
`layer_create {kind, box}`) instead of working out `left` / `top` yourself -- the editor handles
|
|
186
|
+
constraints, the anchor form, stacks and the px factor and writes what a person's canvas gesture
|
|
187
|
+
writes (ops.md "Layout"). `box` is the writable border box in design px; `rect` is the
|
|
188
|
+
on-screen bounding box -- read `box`, write `box`.
|
|
183
189
|
|
|
184
190
|
## 5. Report
|
|
185
191
|
|
|
@@ -109,7 +109,8 @@ removes one. `layer.setProps {layer, props, state?}` writes style properties int
|
|
|
109
109
|
|---|---|
|
|
110
110
|
| Layers | `layer.create {parent, tag?, name?, text?, attrs?, index?}`, `layer.move {layer, parent, index?}`, `layer.rename {layer, name}`, `layer.setProps {layer, props, state?}`, `layer.setText {layer, text}`, `layer.setAttrs {layer, attrs}` (attribute -> value, null removes; **attributes go here** -- `editor-only`, `class`, `data-*`, `aria-*`, `src`, `href`, `ui-scale`, `media-override`; `layer.setProps` takes style properties only and refuses an attribute name as `unknown property`. `id`, `on:*`, `bind:*`, `port:*` refused: use `layer.rename`, `trigger.set`, `bind.set`, `port.set`; `layer.create {attrs}` follows the same rules with the same messages), `layer.setFlags {layer, hidden?, locked?, solo?, color?, collapsed?, adjustHidden?}` (the editor's own layer flags, see "Locked layers" below), `layer.duplicate {layer, count?}` (the layers panel's Duplicate: the subtree and its `#id` rules under the copies' new names, `count` 1-100 copies; the reply lists `copies`), `layer.group {layers, kind?}` (the layers panel's Group / Convert to Stack, layers with one parent, in document order: `group` (default) wraps them into a new `Group_<n>` div; `stack` gives `display: flex` -- a single group layer in place, else wrapped into `Stack_<n>`; the reply names the `layer`), `layer.delete {layer, confirm}` (the layers panel's Delete: one undo step takes the layer, its subtree, their tracks on every timeline (reply `removedTracks`), their expressions (`removedExpressions`) and the rules whose subject is only their `#id` -- `#id`, `#id:hover`, `#id:state(...)` (`removedRules`). While something **elsewhere** points into it -- another layer's trigger or binding, a stylesheet trigger, a flow edge -- it is refused with `kInvalidArgument` and the message lists up to 10 of them as `[{"kind": "trigger" | "binding" | "flow", "where": "#Other on:press"}]` -- the same list is the error's `references` field: change those first, then delete). `layer.setAttrs` / `layer.create` `src`, `href` (not of a `<link>`) and `texture` must name an existing file (`kNotFound` with the resolved path), as a `url()` of `layer.setProps` must |
|
|
111
111
|
| Style | `style.setToken {name, value}`, `style.setTheme {theme}` (preview only), `style.setRule {selector, props, file?, media?}` (declarations of the rule with exactly this selector, e.g. `.card:hover`; null removes one; the rule is added when missing; default the UI's own stylesheet, a shared one only when `file` names it. `media` is an `@media` query such as `(max-width: 1280px)` or `(aspect-ratio <= 4/3)`: the rule inside that `@media` block is written, the block added at the end of the stylesheet when missing, e.g. `@media (max-width: 1280px) { .card { left: 1px } }`; a rule left empty goes, and its block with it; in a format 2 document one call splits by kind: geometry -- what `<layout>` takes, e.g. `width`, `left`, `display` -- goes to the same-selector rule of `<layout>`, the rest to `<style>` (or `file`), with `media` into each section's `@media` block, each rule made when missing, one undo step; the reply's `rule` is the `<style>` one and `rules` lists both), `style.renameRule {selector, newSelector, file?}` (the style rules panel's selector edit; format 2: the `<layout>` and `<style>` rules of the selector together), `style.deleteRule {selector, media?, file?, confirm}` (a whole rule; with `media` the rule inside that `@media` block; format 2 without `file`: both sections' rules, listed in `files`), `style.moveDecl {from, to, prop, fromFile?, toFile?}` (the panel's Move to: the destination rule takes the value, the source loses it and goes when empty; format 2: both rules looked for in the property's section first). These three find a rule as `style.setRule` does (a rule only in a shared stylesheet needs its `file`); `kNotFound` names a missing rule or property. A token (`style.setToken`, `restyle`, `design.put` of a variable) is the same edit the token panel makes: it changes the open UI's copy of `shared/tokens.xts`, the panel shows it at once and `doc.save` writes the file |
|
|
112
|
-
|
|
|
112
|
+
| Layout (T-856, T-857: as the canvas does it) | **Place layers with these, not by computing `left` / `top` yourself**: the editor writes the result the way a canvas gesture does -- the layer's constraints, the v2 anchor form (`anchor` / `offset` / `size`), a stack child's place, the px factor -- so the file is the one a person would get. `layer.setProps` with geometry stays allowed (no warning), for a value you mean literally. **`box` and `rect`**: `box {x, y, width, height}` (in `scene.dump`, `layer.get` and every reply here) is the layer's border box in design px from the canvas origin, without transforms -- the numbers you write back; `rect` is where it shows on screen (viewport px, the bounding box after rotation and the parents' transforms), for looking, not for writing. `rotation` (degrees) sits next to `box`; a layer without a layout (`display: none`, a symbol's content) has neither. `layer.place {layer, box?, dx?, dy?, rotation?, origin?}` / `{layers, dx?, dy?}` (a canvas drag, resize or rotation: `box` any of `x`, `y`, `width`, `height` -- x / y move the layer there, width / height resize it anchored at the box's top-left corner; `dx` / `dy` move by design px (not with `box.x` / `box.y`); `rotation` absolute degrees; `origin {x, y}` the transform origin, fractions 0-1 of the box; several layers take `dx` / `dy` only. A box read and written back changes nothing (`changed: false`), x + 10 reads back x + 10, also for a rotated layer or the child of a scaled / rotated parent. The declarations follow the layer's own placement -- constraints, the v2 anchor form, relative offsets, a stack child's `width` / `height` / `flex-basis`; a stack child's x / y (or dx / dy) is `kUnsupported`: the stack's order places it, `layer.order` / `layer.move` change that), `layer.align {layers, edge, to?}` (`edge` `left` \| `hcenter` \| `right` \| `top` \| `vcenter` \| `bottom`; `to` `selection` (default: the layers' common bounds, two or more layers) \| `parent` (each to its parent's content box; the only choice for one layer)), `layer.distribute {layers, mode}` (`horizontal` / `vertical`: equal gaps, three or more layers; `tidy`: rows sorted by position with the average gaps, two or more), `layer.order {layer, to}` (`front` \| `back` \| `forward` \| `backward` among its siblings -- paint order, and the flow order in a stack; `layer.move` is for another parent or an exact index; already there = `changed: false`), `layer.constrain {layer, horizontal?, vertical?}` (how a free layer is anchored in its containing block, as the constraint widget sets it; the layer stays where it is; an axis left out keeps its constraint; `left` \| `right` \| `center` (`top` \| `bottom` \| `center`), plus in a version 2 document `left-right` / `top-bottom` (the anchor form's stretch) and in a version 1 document `scale` (percentages) -- the other one is `kUnsupported`; a stack child is `kInvalidArgument`). Stack children keep the place the stack gives them in `layer.align` / `layer.distribute` (a note says so). Under Animate (`session.setView {animate: true}`) align, distribute and place record `transform` keyframes at the playhead into the selected timeline (else `root-anim` / `<symbol>-anim`, created at 2 s), as the canvas does. A symbol's content (`<Symbol>/<id>`) is refused (`kUnsupported`). Replies: each layer's `box`, `rotation` and `rect` after the edit, `changed`, and `expanded` (the `layer.setProps` / `layer.move` each step amounts to). `layer.create {parent, kind?, box?, ...}` with `kind` (`free-container` (default), `stack-container`, `rectangle`, `ellipse`, `text`, `image` (`attrs {src}`), `symbol` (`attrs {symbol}`), `external`, `particles`, `cel-animation`; `vector` is `kUnsupported`) or `box` creates as the canvas create tools do -- geometry, the tool's look, the responsive defaults; `box` is a `scene.dump` box (x and y; width and height together, or neither: the default 100 x 100, an image its own size); without a box it lands at the parent's content box corner; a stack parent places it in its flow; not with `tag` or `index`; the reply carries its `box`. Without `kind` and `box` `layer.create` makes the bare element as before |
|
|
113
|
+
| Timelines | `timeline.create {name, duration?, scope?}`, `timeline.setKeyframe {name, layer, prop, time, value, easing?}` (an effect parameter `prop` is `effect.<index|name>.<param>`: a vec2 as a whole, e.g. `effect.shadow.offset` or a shader vec2, is one key with two numbers, `"<x>px <y>px"` or `"<x> <y>"`; `<param>.x` / `.y` key one component; slots `p<n>` (float 0-15), `c<n>` (colour 0-3), `v<n>` (vec2 from float slot n, 0-14) address any effect without its names; `time` is seconds: a time past the timeline's `duration` is written all the same and the reply's `notes` says `time <t> s is past the timeline's end (<end> s); times are seconds`), `timeline.setKeyframes {name, keys: [{layer, prop, time, value, easing?}], scope?}` (many keys, each as `timeline.setKeyframe` takes it, at most 2000: one undo step, checked against the compile once -- one bad key or a result that does not compile refuses the whole batch and changes nothing; reply `{written: n}`; the same past-the-end note for the latest time; use it instead of a loop of `timeline.setKeyframe`), `timeline.setEasing {name, layer, prop, time, easing}`, `timeline.removeKeyframe {name, layer, prop, time}`, `timeline.removeTrack {name, layer, prop?, scope?}` (the layer's track of `prop`, or all its tracks without it, keys included, one undo step; reply `{removed: n}`; no such track: `kNotFound`), `timeline.delete {name, confirm}`, `timeline.rename {name, newName, scope?}`, `timeline.duplicate {name, newName, scope?}` (triggers that play the old name are not rewritten), `timeline.setDuration {name, duration, mode?, scope?}` (`clip`, default: only the length changes, keys past the end stay; `scale`: every key, marker and cue time scales by new / old length), `timeline.setMarker {name, time, label, scope?}` / `timeline.setCue {name, time, sound, scope?}` (a name adds the marker / cue at `time` or renames the one there; `null` removes it. Renaming a marker also rewrites the triggers in the timeline's scope that name it -- `timeline(t).marker(m)`, `play(t, ... from=m)`, `seek(t, m)` -- in the same undo step, as the timeline panel does; `.xts` `on-...` declarations, flow parameters and other UIs are not rewritten), `timeline.moveKeys {name, keys: [{layer, prop, time}], dt?, scale?: {pivot?, factor}, scope?}` (new time = pivot + (time - pivot) x factor + dt, clamped at 0; all keys in one undo step; use it instead of remove + set), `timeline.stagger {name, keys: [{layer, prop, time}], interval?, order?, reverse?, seed?, scope?}` (each layer's keys shift by i x `interval` ms, default 50; `order` layer \| reverse \| random \| center; the reply lists `layers: [{layer, delayMs}]`, the shift in milliseconds), `timeline.fromAnimations {name, scope?, duration?, autoplay?, markers?, addMarkers?, dryRun?}` (the CSS `animation`s of the scope's subtree -- default the whole document -- that share a cycle become a new root-scope timeline `name`: keys at delay + p x duration with iterations expanded, the collected declarations and the `@keyframes` only they used removed, `autoplay` `loop` (default: `on:show` `play(name, loop)` on the scope element) \| `once` (`play(name, hold)`) \| `none`; `markers: true` adds one where each layer turns visible; one undo step; reply `collected`, `kept` (each with `reason` and `message`), `tracks`, `markers`, `removedKeyframes`; nothing collected = no change, `created: false`), `animation.preset {layer, preset, timeline?, at?, scope?}` (a stroke preset on a vector shape `<svg>/<shape>`: `draw-on`, `draw-off`, `marching-ants`, `pulse-stroke`; default timeline `intro`), `animation.followPath {path, layer, timeline, start?, end?, samples?, align?, autoOrient?, scope?}` (bakes the shape `path` into `layer`'s `transform` translate keys, evenly spaced by arc length), `timeline.setExpression {timeline, layer, prop, component?, text?, enabled?, scope?}` (Docs/design/58: an After Effects style expression on one row, e.g. `wiggle(2, 6)`, lowered into keyframes when the document compiles; `prop` `translate` + `component` `y`, or `"translate.y"`; `text: ""` removes it, `enabled: false` switches it off; a row without keys first gets a key at 0 s with its current value (reply `addedKey`), all in one undo step; refused on a row whose translate keys carry a motion path, and on a version 1 document with a `needsV2` message; the reply's `expression` carries the compile status as `timeline.get` shows it), `timeline.bakeExpression {timeline, layer, prop, component?, inputs?, scope?}` (After Effects' Convert Expression to Keyframes: the keys the expression lowers to replace that row's keys and the expression is removed, one undo step; on one component of a two-value row such as `translate.y` the other component keeps its motion -- its values are sampled at the new key times, and where the two need different easings that stretch is cut into linear keys (reply `approximated: true`); `rotate.x` / `rotate.y` go into the layer's `transform` track as `rotateX()` / `rotateY()`; an expression with run-time inputs (`needsRuntime`: `port()`, another element's layout result, another timeline's row, `randomPerPlay()`) is baked with the current test values -- the ports' values in the preview, the last layout, the rows' current values, `randomPerPlay()` at the middle of its range -- or with `inputs: {ports: {<name>: n}, layout: {<layer>: {left, top, width, height}}, rows: {<layer>: {<row>: n}}, randomPerPlay: 0..1}`, and the reply adds `runtime: true`, `usedInputs` and a `warning` (the row no longer reacts to game values); refused while the expression is off, has an error, lowers differently per symbol instance, or the document does not compile; the reply gives `keys` (written), `lowered` and the `track`). `layer.delete`, `layer.move` and `timeline.removeKeyframe` remove the expressions whose layer or row they take away and list them as `removedExpressions`; `layer.rename`, `timeline.rename` and `timeline.duplicate` carry them along |
|
|
113
114
|
| Interaction | `trigger.set {layer, event, actions}`, `state.set {layer, state, prop, value}`, `bind.set {layer, target, expr}`, `port.set {layer, name, type, dir?, expose?, default?}` (`type: ""` removes the port; `default` is a literal such as `80`, `true`, `"Guest"`, `#ff0000`; null removes it, omitted keeps it while the type is unchanged. In source format 2 no `port:` attribute is written: the port is a line of `<ports>`, so `layer` is `body` (the document's ports) or a symbol's root (`<Symbol>/<root>`, the symbol's ports), and any other layer is `kUnsupported`) |
|
|
114
115
|
| Flow | `flow.set {graph, dryRun?}` (replaces the whole `.xtflow` graph `{nodes, edges, groups?}`, one undo step, written by `doc.save`; parse errors fail the call; `dryRun: true` only returns `problems`; a `flow.animatesWithContinuousSignal` warning is not in `problems`, it appears in the editor's Messages panel as `flow: warning: ...`, so look at Messages after a `flow.set` and rewrite the edge: a flow drives, it never interpolates). Read it first with `flow.get` and send it back whole. T-371: works on a background document too (`doc` = a UI opened without `show`); the graph stays with that UI when the user switches to it |
|
|
115
116
|
| Flow `state` node (T-541) | a flow graph may hold `{id, type: "state", params: {states: [..], initial?, transitions: [{from, on, to}], events?}}`: one pulse input per event, `set` (string) and `guard` (bool); outputs `state`, `index`, `changed`, `enter<Name>` / `exit<Name>` per state. Edges into an element take `#id.setState` with edge params `state` (required) and `mode` (`on` / `off` / `toggle`). Sent whole through `flow.set` like every other node |
|
|
@@ -443,10 +444,15 @@ An inline `<svg>` is a vector layer, and its shapes are addressed as `<svg id>/<
|
|
|
443
444
|
given; a paint writes a gradient as the panel does), `width`, `corners: [{vertex, radius}]`
|
|
444
445
|
(radius 0 = sharp; a `<path>` only) and `modifiers` (replaces the stack of the shape's group:
|
|
445
446
|
listed ids keep their place, new ones are appended, unlisted ones go), so a look no longer needs
|
|
446
|
-
a whole-layer `svg` rewrite.
|
|
447
|
+
a whole-layer `svg` rewrite. When `shapes` creates a shape or gives one new geometry (`d`,
|
|
448
|
+
`vertices`, `contours`, `params`), the box is refitted to the content as the Create tool does
|
|
449
|
+
(1:1 viewBox only); appearance-only upserts and `svg` leave the box alone.
|
|
447
450
|
- `vector.editPath {shape, ops}` applies ops in order: `insert {seg, t}`, `delete {index}`,
|
|
448
451
|
`move {index, p, in?, out?}`, `setType {index, type}`, `close`, `open`, `reverse`,
|
|
449
|
-
`setFirst {index}`. Each op may name a `contour`.
|
|
452
|
+
`setFirst {index}`. Each op may name a `contour`. As the node tool, a viewBox that is not 1:1 is
|
|
453
|
+
normalized first and the box is refitted to the content after (the layer box moves and resizes,
|
|
454
|
+
the content's coordinates shift so the viewBox starts at `0 0`; the box stays when a shape has
|
|
455
|
+
`d` keys or the layer has a rig), all one undo step.
|
|
450
456
|
- `vector.boolean {shapes, op}`: op is union | subtract (the first minus the rest) | intersect |
|
|
451
457
|
exclude | divide, and the shapes must be in one layer. The result keeps the topmost shape's id
|
|
452
458
|
and look.
|
|
@@ -457,7 +463,10 @@ An inline `<svg>` is a vector layer, and its shapes are addressed as `<svg id>/<
|
|
|
457
463
|
`skipped[]`), `flipH` / `flipV` (each shape about its own center), `merge {layers}` (other vector
|
|
458
464
|
layers move into `layer`), `split` (each top-level shape / group gets its own layer), `join
|
|
459
465
|
{points: two open end points}`, `break {point}`, `dissolve {points}` (points are `{contour?,
|
|
460
|
-
index}` as in `contours`; `d` keys of the same topology follow).
|
|
466
|
+
index}` as in `contours`; `d` keys of the same topology follow). `flipH` / `flipV` / `join` /
|
|
467
|
+
`break` / `dissolve` normalize and refit the box as the node tool does, `merge` refits the merged
|
|
468
|
+
layer; the Object menu ops (`outlineStroke`, `simplify`, `offset`, `flatten`, `toPath`, `split`)
|
|
469
|
+
do not refit.
|
|
461
470
|
- `vector.textToOutlines {layer}` turns a text layer into a vector layer of glyph paths
|
|
462
471
|
(`<id>_g<n>`); `vector.extract {layer, path?}` writes the layer as a standard `.svg` (default
|
|
463
472
|
`shared/img/<id>.svg` of the project, registered in the asset manifest) and replaces it by an
|
|
@@ -569,12 +578,12 @@ To draw a new cel, `cel.add` a copy, then edit its shapes with `vector.set` / `v
|
|
|
569
578
|
| `animate.entrance {layers, style?, duration?, stagger?, delay?, timeline?}` | an `intro` timeline: `fade`, `rise` or `scale`, staggered within the spec (`duration`, `stagger`, `delay` in seconds) |
|
|
570
579
|
| `animate.exit {layers, style?, ...}` | an `outro`: `fade`, `sink` or `scale` |
|
|
571
580
|
| `animate.emphasis {layers, kind, duration?, timeline?}` | `pulse`, `shake` or `glow` |
|
|
572
|
-
| `layout.anchor {layers, template, margin?}` | anchors to the safe area by template: `hud-corners`, `menu-list`, `inventory` |
|
|
581
|
+
| `layout.anchor {layers, template, margin?}` | anchors to the safe area by template: `hud-corners`, `menu-list`, `inventory`. `hud-corners` pins each layer to its nearest viewport corner at the margin (design px; default the safe area) and writes it as the canvas writes a placement (T-854): the anchor form (`anchor` / `offset` / `size`) in a v2 document, else `left`/`right`/`top`/`bottom` + `width`/`height` against the layer's real containing block, margins subtracted, not rounded to whole px |
|
|
573
582
|
| `restyle {tokens}` | many token values at once (a new palette, a mood) |
|
|
574
583
|
| `fx.apply {layers, template}` | an effect template (`shared/fx/*.xtfxp`) |
|
|
575
584
|
| `state.apply {target, state, diff}` | a whole state look at once (a layer, or a symbol: `<inner>.<prop>` keys) |
|
|
576
585
|
| `wire.port {layer, prop, port, converters?, type?}` | declares the port if needed and binds it |
|
|
577
|
-
| `repair.import {report?}` | the import report's fixable warnings: names, anchors, states |
|
|
586
|
+
| `repair.import {report?}` | the import report's fixable warnings: names, anchors, states. A px `left`/`top` layer in the right/bottom half of its containing block is re-anchored to the nearer edges in place, as the canvas constraint widget writes it (T-854): the anchor form in a v2 document, else `right`/`bottom` against the real containing block, margins subtracted, design px, not rounded |
|
|
578
587
|
| `repair.anchor {root?, safeArea?}` | a fixed-size root (lint `layout.fixedRoot`) -> the root fills the viewport, its px layers anchored to the safe area (nearest edge within 25%, else centered; `anchored[]` per layer) |
|
|
579
588
|
| `repair.dedup {class, layers?}` | undoes the importer's style dedup (`dedup.shared`): the shared class rule's declarations go into each layer's own `#id` rule (its own values win) and the class is removed; the rule stays |
|
|
580
589
|
| `repair.effectBase {layer, effect}` | puts a base effect back (`effect.baseAdded`): every function of `effect` the layer's base style lacks is added (`backdrop-blur` first); idempotent, `added[]` |
|
|
@@ -596,7 +605,7 @@ The result of an intent operation lists `expanded[]`, the low-level operations i
|
|
|
596
605
|
|
|
597
606
|
| Operation | Use |
|
|
598
607
|
|---|---|
|
|
599
|
-
| `scene.dump {scope?}` | layers with rect, visibility, states, triggers, bindings (`worldLayer: true` on a layer whose `world-layer` is `on`); `visibility` lists offscreen, empty, transparent, occluded, textOverflow, outsideSafeArea; effects usage |
|
|
608
|
+
| `scene.dump {scope?}` | layers with rect (on screen), box (design px, the numbers `layer.place` takes back), rotation, visibility, states, triggers, bindings (`worldLayer: true` on a layer whose `world-layer` is `on`); `visibility` lists offscreen, empty, transparent, occluded, textOverflow, outsideSafeArea; effects usage |
|
|
600
609
|
| `scene.screenshot {scope?, state?, device?, lang?, timeline?, times?}` | a PNG; `times` (3-6) samples an animation. Counts against the scenario budget. `state: {layer, state}` forces `hover`, `pressed` (`:active`), `focus`, `checked`, `disabled` or a custom `:state(name)` on that layer; a rule with a `transition` is captured at its starting point, not its end |
|
|
601
610
|
| `lint.run {scope?}` | motion spec (`motion.*`), `lint.triggerTimeline`, `lint.stateNoDiff`, `lint.portUnbound`, `lint.literalColor`, `lint.textOverflow`, `layout.pxOutsideLogical`, `layout.fixedRoot`, `tags.*`, `contract.*`, `perf.*`, `skin.*`, `mesh.degenerate`, `mesh.pinOutside`, `compile` |
|
|
602
611
|
| `perf.probe {frames?}` | frame time, workload, fill rate, % of budget |
|
|
@@ -851,12 +860,17 @@ import.reimport
|
|
|
851
860
|
initialize
|
|
852
861
|
layer.create
|
|
853
862
|
layer.addAdjustment
|
|
863
|
+
layer.align
|
|
864
|
+
layer.constrain
|
|
854
865
|
layer.delete
|
|
866
|
+
layer.distribute
|
|
855
867
|
layer.duplicate
|
|
856
868
|
layer.get
|
|
857
869
|
layer.group
|
|
858
870
|
layer.list
|
|
859
871
|
layer.move
|
|
872
|
+
layer.order
|
|
873
|
+
layer.place
|
|
860
874
|
layer.removeAdjustment
|
|
861
875
|
layer.rename
|
|
862
876
|
layer.setAttrs
|
|
@@ -87,7 +87,8 @@ no lint error; `motion.safeArea`, `motion.fontSize` and `lint.literalColor` clea
|
|
|
87
87
|
|
|
88
88
|
**repair-import** -- allowed: `vector.*`, `bone.*`, `constraint.*`, `skin.*`, `mesh.*`,
|
|
89
89
|
`repair.import`, `repair.anchor`, `import.reimport`, `layer.rename`, `layer.group`,
|
|
90
|
-
`layer.setProps`, `layer.setAttrs`, `layer.setFlags`, `layout.anchor`,
|
|
90
|
+
`layer.setProps`, `layer.place`, `layer.align`, `layer.distribute`, `layer.constrain`, `layer.order`, `layer.setAttrs`, `layer.setFlags`, `layout.anchor`,
|
|
91
|
+
`style.*` (token
|
|
91
92
|
replacement, selector renames, moving or deleting imported rules), `restyle`, `state.*`,
|
|
92
93
|
`symbol.create`, `symbol.override`, `trigger.set`, `timeline.create`, `timeline.rename`,
|
|
93
94
|
`animate.*`, `asset.replace`, `doc.save`, `undo`, `redo`, `repair.dedup`, `repair.effectBase`,
|
|
@@ -96,7 +97,7 @@ replacement, selector renames, moving or deleting imported rules), `restyle`, `s
|
|
|
96
97
|
clean; every import-report warning handled or marked (manual).
|
|
97
98
|
|
|
98
99
|
**restyle** -- allowed: `style.*` (the style stack ops included), `restyle`, `fx.apply`,
|
|
99
|
-
`layer.setProps`, `catalog.add`, `catalog.list`, `doc.save`, `undo`, `redo`; forbidden: `layer.create`, `layer.delete`,
|
|
100
|
+
`layer.setProps`, `layer.place`, `layer.align`, `layer.distribute`, `layer.constrain` (not `layer.order`: no structure change), `catalog.add`, `catalog.list`, `doc.save`, `undo`, `redo`; forbidden: `layer.create`, `layer.delete`,
|
|
100
101
|
`layer.move`, `layer.rename`, `symbol.*`. Done: no lint error; text contrast at least 4.5:1
|
|
101
102
|
(manual).
|
|
102
103
|
|
|
@@ -122,7 +123,8 @@ instance's variant: `{"variant:<prop>": value}`), `timeline.*`, `animate.emphasi
|
|
|
122
123
|
`undo`, `redo`, `flow.set`; forbidden: `layer.delete`, `symbol.detach`. Done: `lint.stateNoDiff`
|
|
123
124
|
and `lint.triggerTimeline` clean; every hover has a matching leave (manual).
|
|
124
125
|
|
|
125
|
-
**effects** -- allowed: `fx.*`, `layer.setProps`, `layer.
|
|
126
|
+
**effects** -- allowed: `fx.*`, `layer.setProps`, `layer.place`, `layer.align`, `layer.distribute`, `layer.constrain`, `layer.order`,
|
|
127
|
+
`layer.addAdjustment`, `layer.removeAdjustment`,
|
|
126
128
|
`style.*`, `timeline.*`, `catalog.add`, `catalog.list`, `layer.setAttrs` (the numbers of a
|
|
127
129
|
`<particles>` layer are its attributes), `doc.save`, `undo`, `redo`;
|
|
128
130
|
forbidden: `layer.create`, `layer.delete`. Done: effect layers within budget;
|
|
@@ -130,7 +132,8 @@ forbidden: `layer.create`, `layer.delete`. Done: effect layers within budget;
|
|
|
130
132
|
|
|
131
133
|
**shader** -- allowed: `shader.*` (`shader.list`, `shader.get`, `shader.create`, `shader.setSource`:
|
|
132
134
|
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:
|
|
135
|
+
`layer.setProps`, `layer.place`, `layer.align`, `layer.distribute`, `layer.constrain`, `layer.order`, `catalog.add` (apply it: `catalog.add {id: "custom", file:
|
|
136
|
+
"<name>", layer}`),
|
|
134
137
|
`doc.save`, `undo`, `redo`; forbidden: `layer.create`,
|
|
135
138
|
`layer.delete`. A source the parser refuses comes back with `errors: [{line, column, message}]`.
|
|
136
139
|
Done: the document compiles; a shader compile error was retried at most once (manual).
|
|
@@ -145,21 +148,25 @@ in the `expand` margin outside the box it is below 0 or above 1. `i.boxSize` is
|
|
|
145
148
|
in CSS px (no dpr). Effects that stick to the content (a light beam, a glow, scan lines lined up
|
|
146
149
|
with it) use `local`. A `vec2` parameter is a plain pair of numbers: compare it with `uv` or with
|
|
147
150
|
`local`, whichever the shader means. `i.texelSize` / `i.layerSize` describe the window in device
|
|
148
|
-
pixels.
|
|
149
|
-
|
|
151
|
+
pixels. On a vector or scene layer (a shape or group inside an `<svg>`) the box is the layer's own
|
|
152
|
+
geometry box in its local space, without the stroke (a group: the union of its shapes; the same box
|
|
153
|
+
an `objectBoundingBox` gradient uses), so the stroke falls outside 0..1. `local` and `boxSize` are 0
|
|
154
|
+
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
|
|
150
155
|
`fallback:` -- so look at a shader with `xtframe-view --headless --renderer wgpu`, not the default
|
|
151
156
|
software render.
|
|
152
157
|
|
|
153
158
|
**data-binding** -- allowed: `port.*`, `bind.*`, `wire.port`, `trigger.set`, `doc.save`, `undo`,
|
|
154
159
|
`redo`, `flow.set`; forbidden: `layer.delete`. Done: `lint.portUnbound` clean; no lint error.
|
|
155
160
|
|
|
156
|
-
**multi-resolution** -- allowed: `layout.anchor`, `layer.
|
|
161
|
+
**multi-resolution** -- allowed: `layout.anchor`, `layer.place`, `layer.align`, `layer.distribute`, `layer.constrain`, `layer.order`, `layer.setProps`,
|
|
162
|
+
`layer.setAttrs`,
|
|
157
163
|
`layer.setText`, `style.setRule` and `style.deleteRule` (`@media` blocks: `media`),
|
|
158
164
|
`style.setToken`, `doc.save`, `undo`, `redo`; forbidden: `layer.delete`. Done: nothing outside
|
|
159
165
|
the safe area; no text overflow (dump and lint); content fits; 16:9, 4:3, 21:9 and 9:16
|
|
160
166
|
screenshots and the longest translation checked (manual).
|
|
161
167
|
|
|
162
|
-
**performance** -- allowed: `fx.*`, `layer.setProps`, `
|
|
168
|
+
**performance** -- allowed: `fx.*`, `layer.setProps`, `layer.place`, `layer.align`, `layer.distribute`, `layer.constrain`, `layer.order`, `layout.anchor`,
|
|
169
|
+
`style.setRule`,
|
|
163
170
|
`style.setToken`, `vector.bake`, `doc.save`, `undo`, `redo`; forbidden: `layer.delete`. Done:
|
|
164
171
|
effect layers within budget; `motion.effectLayers` clean; `perf.probe` before and after compared
|
|
165
172
|
in the report (manual).
|