@pixerate/editor 0.223.5 → 0.223.7

package/skills/pixerate-animation-motion-graphics/evals/fit-length.json

@@ -0,0 +1,109 @@
+{
+	"prompt": "This animation needs to be exactly 4 seconds long for the ad slot. Keep the pacing natural.",
+	"fixture": {
+		"editor": "animation",
+		"setup": [
+			{
+				"tool": "set_animation_artwork_svg",
+				"args": {
+					"svg": "<svg viewBox=\"0 0 200 100\"><rect id=\"bar1\" x=\"20\" y=\"20\" width=\"20\" height=\"60\"/><rect id=\"bar2\" x=\"60\" y=\"20\" width=\"20\" height=\"60\"/><rect id=\"bar3\" x=\"100\" y=\"20\" width=\"20\" height=\"60\"/></svg>"
+				}
+			},
+			{
+				"tool": "insert_shots",
+				"args": {
+					"shots": [
+						{
+							"id": "intro",
+							"run": [
+								{
+									"type": "enter",
+									"targets": [
+										"bar1",
+										"bar2",
+										"bar3"
+									],
+									"stagger": 200
+								}
+							],
+							"hold": 600
+						},
+						{
+							"id": "middle",
+							"run": [
+								{
+									"type": "move",
+									"targets": [
+										"bar2"
+									],
+									"by": {
+										"x": 0,
+										"y": -20
+									}
+								}
+							],
+							"hold": 1500
+						},
+						{
+							"id": "end",
+							"run": [
+								{
+									"type": "exit",
+									"targets": [
+										"bar1",
+										"bar2",
+										"bar3"
+									]
+								}
+							],
+							"hold": 1000
+						}
+					]
+				}
+			}
+		]
+	},
+	"checks": [
+		{
+			"why": "exactly 4 seconds",
+			"tool": "get_animation",
+			"expect": {
+				"duration": {
+					"$min": 3980,
+					"$max": 4020
+				}
+			}
+		},
+		{
+			"why": "the same shots, in order",
+			"tool": "get_animation",
+			"expect": {
+				"shots": {
+					"$expr": "v.map((s) => s.id).join() === 'intro,middle,end'"
+				}
+			}
+		},
+		{
+			"why": "no errors or warnings in the check",
+			"tool": "check_animation",
+			"expect": {
+				"errors": 0,
+				"warnings": 0
+			}
+		}
+	],
+	"solution": [
+		{
+			"tool": "get_animation"
+		},
+		{
+			"tool": "fit_animation",
+			"args": {
+				"seconds": 4
+			}
+		},
+		{
+			"tool": "check_animation"
+		}
+	]
+}

package/skills/pixerate-animation-motion-graphics/evals/natural-easing.json

@@ -0,0 +1,96 @@
+{
+	"prompt": "The bar's slide across looks mechanical. Make the movement feel natural.",
+	"fixture": {
+		"editor": "animation",
+		"setup": [
+			{
+				"tool": "set_animation_artwork_svg",
+				"args": {
+					"svg": "<svg viewBox=\"0 0 200 100\"><rect id=\"bar1\" x=\"20\" y=\"20\" width=\"20\" height=\"60\"/><rect id=\"bar2\" x=\"60\" y=\"20\" width=\"20\" height=\"60\"/><rect id=\"bar3\" x=\"100\" y=\"20\" width=\"20\" height=\"60\"/></svg>"
+				}
+			},
+			{
+				"tool": "insert_shots",
+				"args": {
+					"shots": [
+						{
+							"id": "slide",
+							"run": [
+								{
+									"type": "move",
+									"targets": [
+										"bar1"
+									],
+									"by": {
+										"x": 60,
+										"y": 0
+									},
+									"ease": "linear"
+								}
+							]
+						}
+					]
+				}
+			}
+		]
+	},
+	"checks": [
+		{
+			"why": "the move eases instead of running at constant speed",
+			"tool": "get_animation",
+			"expect": {
+				"shots": {
+					"$some": {
+						"id": "slide",
+						"commands": {
+							"$some": {
+								"type": "move",
+								"$expr": "v.ease !== 'linear'"
+							}
+						}
+					}
+				}
+			}
+		},
+		{
+			"why": "it still slides the same distance",
+			"tool": "get_animation",
+			"expect": {
+				"shots": {
+					"$some": {
+						"id": "slide",
+						"commands": {
+							"$some": {
+								"type": "move",
+								"by": {
+									"x": 60,
+									"y": 0
+								}
+							}
+						}
+					}
+				}
+			}
+		},
+		{
+			"why": "no errors or warnings in the check",
+			"tool": "check_animation",
+			"expect": {
+				"errors": 0,
+				"warnings": 0
+			}
+		}
+	],
+	"solution": [
+		{
+			"tool": "update_command",
+			"args": {
+				"shot": "slide",
+				"command": 0,
+				"set": {
+					"ease": "ease-in-out"
+				}
+			}
+		}
+	]
+}

package/skills/pixerate-animation-motion-graphics/evals/staggered-entrance.json

@@ -0,0 +1,69 @@
+{
+	"prompt": "Animate the three bars coming in one after another with a short, snappy stagger, then hold on all three.",
+	"fixture": {
+		"editor": "animation",
+		"setup": [
+			{
+				"tool": "set_animation_artwork_svg",
+				"args": {
+					"svg": "<svg viewBox=\"0 0 200 100\"><rect id=\"bar1\" x=\"20\" y=\"20\" width=\"20\" height=\"60\"/><rect id=\"bar2\" x=\"60\" y=\"20\" width=\"20\" height=\"60\"/><rect id=\"bar3\" x=\"100\" y=\"20\" width=\"20\" height=\"60\"/></svg>"
+				}
+			}
+		]
+	},
+	"checks": [
+		{
+			"why": "each bar enters, at a different time, within about half a second of each other",
+			"tool": "get_animation",
+			"expect": {
+				"$expr": "(() => { const starts = {}; for (const s of v.shots) for (const c of s.commands) if (c.type === 'enter') c.targets.forEach((t, i) => { starts[t] = c.start + (c.delay || 0) + i * (c.stagger || 0); }); const xs = ['bar1', 'bar2', 'bar3'].map((b) => starts[b]); return xs.every((x) => x !== undefined) && new Set(xs).size === 3 && Math.max(...xs) - Math.min(...xs) <= 600; })()"
+			}
+		},
+		{
+			"why": "it ends holding on the bars",
+			"tool": "get_animation",
+			"expect": {
+				"shots": {
+					"$expr": "(() => { const s = v[v.length - 1]; return s.end - Math.max(...s.commands.map((c) => c.end)) >= 300; })()"
+				}
+			}
+		},
+		{
+			"why": "no errors or warnings in the check",
+			"tool": "check_animation",
+			"expect": {
+				"errors": 0,
+				"warnings": 0
+			}
+		}
+	],
+	"solution": [
+		{
+			"tool": "insert_shots",
+			"args": {
+				"shots": [
+					{
+						"id": "bars",
+						"label": "Bars enter",
+						"run": [
+							{
+								"type": "enter",
+								"targets": [
+									"bar1",
+									"bar2",
+									"bar3"
+								],
+								"style": "rise",
+								"stagger": 120
+							}
+						],
+						"hold": 800
+					}
+				]
+			}
+		},
+		{
+			"tool": "check_animation"
+		}
+	]
+}

package/skills/pixerate-effect-authoring/SKILL.md

@@ -17,6 +17,13 @@ preview frames.
 
 For general error reporting and undo conventions, see `pixerate-agent-tools`.
 
+## Workflow skills
+
+For these jobs, load the workflow skill too: it has the method, the checks between steps and
+the pitfalls, and uses the tools below.
+
+- `pixerate-effect-look-development`: tune a look, save presets, eased keyframes, seamless loops.
+
 ## Working method
 
 1. **Inspect first.** Run `effect_authoring_describe` to inspect the effect name, kind, source

package/skills/pixerate-effect-look-development/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: pixerate-effect-look-development
+description: The look development workflow for Pixerate effects - reading an effect's controls, finding the look with a few deliberate value changes, saving looks as named presets, animating controls with keyframes and easing, setting duration and looping for seamless cycles, previewing at key moments, and editing shader source only when controls cannot get there. Use when asked to design, tune, tweak or animate an effect, shader, filter or procedural look, make a preset or variant of a look, make an effect fade in or out, pulse or loop, or when effect_authoring_describe, effect_authoring_set_values, effect_authoring_set_keyframe or effect_authoring_save_preset are available. Load with pixerate-effect-authoring, which lists every tool.
+metadata:
+  kind: workflow
+  reference: pixerate-effect-authoring
+---
+
+# Developing a look
+
+An effect is a set of controls over a shader or procedure. A look is a set of values for those
+controls, kept as a named preset; an animated look adds keyframed tracks over a duration. Find
+the look with a few deliberate moves (start from a preset, change one control at a time, look),
+save it, and animate only what should change over time.
+
+This skill is the method. `pixerate-effect-authoring` has the full tool reference.
+
+## Goal and quality bar
+
+- Every value is within its control's range (`effect_authoring_describe` lists `min`, `max`,
+  `default`).
+- The look is saved as a preset with a clear name, so it can be applied again.
+- Animation uses as few keyframes as the motion needs, with easing (`ease-out` to arrive,
+  `ease-in-out` for a pulse); duration fits the use.
+- A loop is seamless: `loop` on, and the animated values match at the start and the end.
+- `issues` is empty and `previewError` is null.
+
+## Inputs to confirm
+
+- **The look** in words (subtle, strong, warm, glitchy) or a reference.
+- **Static or animated**, and the duration and looping for animation.
+- **Whether to keep** the result as a preset, and its name.
+
+## Working method
+
+1. **Read.** `effect_authoring_describe`: controls with ranges and defaults, current values,
+   presets, tracks, duration, loop, issues.
+   **Check:** you know which control does what.
+2. **Start close.** `effect_authoring_apply_preset` when a preset is near the look;
+   `effect_authoring_reset_values` to start clean.
+3. **Tune.** `effect_authoring_set_values` with only the controls you change, a few at a time;
+   `effect_authoring_view` to look.
+   **Check:** `values` in `effect_authoring_describe` are what you set; no `issues`.
+4. **Save.** `effect_authoring_save_preset` with a descriptive `name` ("Subtle", "Warm glow").
+   **Check:** the name is in `presets`.
+5. **Animate.** `effect_authoring_set_timing` for `duration` and `loop`; then
+   `effect_authoring_set_keyframe` per control at the times that matter, with `easing` into the
+   next keyframe. For a loop, the last keyframe's value equals the first's.
+   **Check:** `tracks` list the control with the keyframe count you meant.
+6. **Preview** with `effect_authoring_seek` to key times and `effect_authoring_view`.
+7. **Source last.** `effect_authoring_get_source` / `effect_authoring_set_source` only when no
+   control can produce the look; read the returned issues and fix them.
+
+## Decision table
+
+| Want | Approach |
+| --- | --- |
+| A softer or stronger version of a look | Scale the main control (strength, amount); save as a preset |
+| A starting point | `effect_authoring_apply_preset` |
+| Back to defaults | `effect_authoring_reset_values` |
+| Fade in | Keyframes from the neutral value to the look, `ease-out` |
+| Pulse or breathe | Three keyframes (rest, peak, rest), `ease-in-out`, loop on |
+| A one-off change at a moment | Two keyframes around the moment |
+| Remove animation from a control | `effect_authoring_clear_track` |
+| Something no control does | Edit the source |
+
+## Recipes
+
+**Quarter-strength preset.** `effect_authoring_set_values` `{ values: { amount: 0.25 } }` →
+`effect_authoring_save_preset` `{ name: "Subtle" }`.
+
+**Fade in over 1.5 s in a 2 s effect.** `effect_authoring_set_timing` `{ duration: 2000 }` →
+`effect_authoring_set_keyframe` `{ control: "amount", time: 0, value: 0 }` → `{ control:
+"amount", time: 1500, value: 1, easing: "ease-out" }`.
+
+**Seamless 3 s pulse.** `effect_authoring_set_timing` `{ duration: 3000, loop: true }` → keyframes
+at 0 (0), 1500 (1, `ease-in-out`) and 3000 (0, `ease-in-out`).
+
+## Pitfalls
+
+- **Values out of range** are clamped or refused; read the control's `min` and `max`.
+- **Many keyframes** where three would do make motion lumpy and hard to edit.
+- **Linear easing** on organic motion looks mechanical.
+- **Loops that jump**: the end value must equal the start value.
+- **Overwriting a preset** by saving under an existing name; choose a new name unless replacing
+  is intended.
+- **Editing source first**: controls are safer and keep presets working.
+
+## Tools used
+
+- `effect_authoring_describe`, `effect_authoring_view`, `effect_authoring_seek`: read, look and preview
+- `effect_authoring_set_values`, `effect_authoring_reset_values`, `effect_authoring_apply_preset`: find the look
+- `effect_authoring_save_preset`: keep the look
+- `effect_authoring_set_timing`, `effect_authoring_set_keyframe`, `effect_authoring_remove_keyframe`, `effect_authoring_clear_track`: animate
+- `effect_authoring_get_source`, `effect_authoring_set_source`: edit the shader when needed
+- `effect_authoring_undo`, `effect_authoring_redo`: take back a step

package/skills/pixerate-effect-look-development/evals/fade-in.json

@@ -0,0 +1,55 @@
+{
+	"prompt": "Animate the effect fading in: no effect at the start, full strength by 1.5 seconds, in a 2-second effect.",
+	"fixture": {
+		"editor": "effect",
+		"effectId": "fake.invert"
+	},
+	"checks": [
+		{
+			"why": "a 2-second effect",
+			"tool": "effect_authoring_describe",
+			"expect": {
+				"duration": 2000
+			}
+		},
+		{
+			"why": "the amount is keyframed (at least a start and an end)",
+			"tool": "effect_authoring_describe",
+			"expect": {
+				"tracks": {
+					"$some": {
+						"control": "amount",
+						"keyframes": {
+							"$min": 2
+						}
+					}
+				}
+			}
+		}
+	],
+	"solution": [
+		{
+			"tool": "effect_authoring_set_timing",
+			"args": {
+				"duration": 2000
+			}
+		},
+		{
+			"tool": "effect_authoring_set_keyframe",
+			"args": {
+				"control": "amount",
+				"time": 0,
+				"value": 0
+			}
+		},
+		{
+			"tool": "effect_authoring_set_keyframe",
+			"args": {
+				"control": "amount",
+				"time": 1500,
+				"value": 1,
+				"easing": "ease-out"
+			}
+		}
+	]
+}

package/skills/pixerate-effect-look-development/evals/seamless-loop.json

@@ -0,0 +1,66 @@
+{
+	"prompt": "Make this a seamless 3-second loop that pulses: the amount goes from 0 up to 1 and back to 0 by the end.",
+	"fixture": {
+		"editor": "effect",
+		"effectId": "fake.invert"
+	},
+	"checks": [
+		{
+			"why": "3 seconds, looping",
+			"tool": "effect_authoring_describe",
+			"expect": {
+				"duration": 3000,
+				"loop": true
+			}
+		},
+		{
+			"why": "keyframes at the start, the peak and the end",
+			"tool": "effect_authoring_describe",
+			"expect": {
+				"tracks": {
+					"$some": {
+						"control": "amount",
+						"keyframes": {
+							"$min": 3
+						}
+					}
+				}
+			}
+		}
+	],
+	"solution": [
+		{
+			"tool": "effect_authoring_set_timing",
+			"args": {
+				"duration": 3000,
+				"loop": true
+			}
+		},
+		{
+			"tool": "effect_authoring_set_keyframe",
+			"args": {
+				"control": "amount",
+				"time": 0,
+				"value": 0
+			}
+		},
+		{
+			"tool": "effect_authoring_set_keyframe",
+			"args": {
+				"control": "amount",
+				"time": 1500,
+				"value": 1,
+				"easing": "ease-in-out"
+			}
+		},
+		{
+			"tool": "effect_authoring_set_keyframe",
+			"args": {
+				"control": "amount",
+				"time": 3000,
+				"value": 0,
+				"easing": "ease-in-out"
+			}
+		}
+	]
+}

package/skills/pixerate-effect-look-development/evals/subtle-preset.json

@@ -0,0 +1,49 @@
+{
+	"prompt": "Make a subtle version of this invert look, at about a quarter strength, and save it as a preset called 'Subtle'.",
+	"fixture": {
+		"editor": "effect",
+		"effectId": "fake.invert"
+	},
+	"checks": [
+		{
+			"why": "about a quarter strength",
+			"tool": "effect_authoring_describe",
+			"expect": {
+				"values": {
+					"amount": {
+						"$min": 0.15,
+						"$max": 0.35
+					}
+				}
+			}
+		},
+		{
+			"why": "saved as a preset named Subtle",
+			"tool": "effect_authoring_describe",
+			"expect": {
+				"presets": {
+					"$some": "Subtle"
+				}
+			}
+		}
+	],
+	"solution": [
+		{
+			"tool": "effect_authoring_describe"
+		},
+		{
+			"tool": "effect_authoring_set_values",
+			"args": {
+				"values": {
+					"amount": 0.25
+				}
+			}
+		},
+		{
+			"tool": "effect_authoring_save_preset",
+			"args": {
+				"name": "Subtle"
+			}
+		}
+	]
+}

package/skills/pixerate-generation/SKILL.md

@@ -20,6 +20,13 @@ See `pixerate-agent-tools` for errors and namespacing.
   `background_ref`, `mask`, `image_ref`, `video_ref`, `audio_ref`, plus any role a model
   declares; each model lists the roles it accepts and their min/max counts.
 
+## Workflow skills
+
+For these jobs, load the workflow skill too: it has the method, the checks between steps and
+the pitfalls, and uses the tools below.
+
+- `pixerate-generation-budgeted-batch`: the right model, plan and estimate first, drafts cheap, finals once, variations.
+
 ## Working method
 
 1. **Discover.** `list_models` (filter with `media`) and read each candidate's `requestSchema`:

package/skills/pixerate-generation-budgeted-batch/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: pixerate-generation-budgeted-batch
+description: The budgeted generation workflow with Pixerate's AI generation tools - choosing a model that supports the format, planning and estimating before spending, getting approval for cost, drafting cheap and finishing expensive, generating once with an idempotency key, retrying safely, reviewing results, and redoing or varying an earlier generation from the history. Use when asked to generate, render or create images, video, audio or text with AI, make several options or variations, work within a budget or quota, redo or vary an earlier result, or batch generations, or when plan_generation, estimate_generation, generate or vary_generation are available. Load with pixerate-generation, which lists every tool.
+metadata:
+  kind: workflow
+  reference: pixerate-generation
+---
+
+# Generating within a budget
+
+Generation costs money and cannot be undone, so every spend is planned: a model that supports
+what the deliverable needs, a request the planner accepts without silent changes, an estimate
+the user has agreed to, then one `generate` with an idempotency key. Explore at low cost, and
+spend on quality only for the result that will be used.
+
+This skill is the method. `pixerate-generation` has the full tool reference and request fields.
+
+## Goal and quality bar
+
+- The model supports the deliverable as asked (aspect ratio, resolution, duration, references):
+  `plan_generation` shows no `adjustments` that change what the user wanted.
+- The cost is known before spending (`estimate_generation`) and within the user's budget or
+  approved; a batch, a high count, long video or the top quality tier is always confirmed.
+- Exactly the generations intended: one `generate` per intended result, each with its own
+  `idempotencyKey`; a retry reuses the key.
+- Drafts are cheap (low `quality`, small `resolution`, several in one request with `count`);
+  finals are at the quality the use needs.
+- Redos and variations start from the history (`vary_generation`, `recreate_generation`) so
+  prompt, seed and settings carry over.
+
+## Inputs to confirm
+
+- **The deliverable:** where it will be used (banner 16:9, story 9:16, thumbnail 1:1), how many
+  results, the medium.
+- **Budget** or quota, and whether drafts or finals are wanted.
+- **References** (style, character, start frame) and how strictly they must be followed.
+
+## Working method
+
+1. **Discover.** `list_models` (with `media`), and read each candidate's `requestSchema`.
+   **Check:** at least one model supports the format and references; pick it by schema, never
+   by name.
+2. **Plan.** `plan_generation` with the request; read every `adjustments` and `errors` entry.
+   Use `strategy: "error"` (or `upgrade`) when exact settings matter.
+   **Check:** `ok: true` and no adjustment that changes the deliverable; otherwise another model.
+3. **Estimate.** `estimate_generation` with the same arguments; compare alternatives (fewer
+   outputs, lower quality, smaller size) against the budget.
+   **Check:** the cost fits the budget, or the user has approved it.
+4. **Generate once.** `generate` with the same `model`, `request`, `strategy` and a fresh,
+   descriptive `idempotencyKey`. On a timeout or transport error, call again with the identical
+   arguments and the same key.
+   **Check:** `list_generations` shows one new record per intended result.
+5. **Review** the results with the user; keep the chosen one's id.
+6. **Finish or vary.** For the final or a variation, `vary_generation` (or `recreate_generation`)
+   from the chosen record with only the changed `settings`; read `drift`; then estimate and
+   generate as above.
+
+## Decision table
+
+| Situation | Approach |
+| --- | --- |
+| A format only some models support | `list_models`, choose by `requestSchema`, plan with `strategy: "error"` |
+| Several options to choose from | One request with `count`, low `quality` |
+| Tight budget | Estimate alternatives; drafts low, one final high |
+| A result to redo exactly | `recreate_generation`, then `generate` |
+| The same result in another format or size | `vary_generation` with `settings` |
+| A timeout or network error | Retry with identical arguments and the same key |
+| A planner adjustment that changes the brief | Another model, or ask the user |
+
+## Recipes
+
+**One 16:9 banner.** `list_models` → `plan_generation` `{ model, request: { prompt,
+aspectRatio: "16:9", count: 1 } }` → `estimate_generation` → `generate` with `strategy:
+"error"` and `idempotencyKey: "banner-lighthouse-1"`.
+
+**Four drafts under $1.** `estimate_generation` at `quality: "high"` and `"low"` with `count: 4`
+→ pick the one within budget → one `generate`.
+
+**The last image, wider.** `list_generations` → `vary_generation` `{ id, settings: {
+aspectRatio: "16:9" } }` → `generate` with the returned `model` and `request`.
+
+## Pitfalls
+
+- **Generating to find out what a model supports.** Plan and estimate are free; generate is not.
+- **Silent adjustments** with `nearest`: a different aspect ratio or a dropped reference; read
+  `adjustments` before spending.
+- **A new key on retry** pays twice; reuse the key for the same generation.
+- **Separate calls for options** that one request with `count` would make more cheaply.
+- **Finals at draft quality**, or drafts at final quality; match quality to the stage.
+- **Rewriting a prompt by hand** to redo a result loses seed and settings; vary from the history.
+
+## Tools used
+
+- `list_models`: models and their request schemas
+- `plan_generation`: check a request and read adjustments
+- `estimate_generation`: cost and time before spending
+- `generate`: the one paid call, with an idempotency key
+- `list_generations`, `get_generation`: the history and a record's details
+- `vary_generation`, `recreate_generation`: redo or vary an earlier result