@pinepaper.studio/mcp-server 1.6.15 → 1.6.16

package/README.de.md

@@ -19,7 +19,7 @@
 
 Der PinePaper MCP-Server lässt KI-Assistenten über das Model Context Protocol Grafiken in [PinePaper Studio](https://pinepaper.studio) erstellen und animieren. Funktioniert mit jeder KI, die MCP-Tool-Aufrufe unterstützt (Claude, GPT, Gemini, lokale Modelle usw.).
 
-Der Server bietet **154 Tools**: Zeichnen, Animation, Diagramme, Karten, Typografie, Physik, Bildbearbeitung, Datenvisualisierung und Export:
+Der Server bietet **157 Tools**: Zeichnen, Animation, Diagramme, Karten, Typografie, Physik, Bildbearbeitung, Datenvisualisierung und Export:
 
 - Text, Formen, Geometrie und komplexe Grafiken erstellen
 - Mit deklarativen **Relationen** animieren statt mit Keyframes

package/README.es.md

@@ -19,7 +19,7 @@
 
 El servidor MCP de PinePaper permite a los asistentes de IA crear y animar gráficos en [PinePaper Studio](https://pinepaper.studio) a través del Model Context Protocol. Funciona con cualquier IA que soporte llamadas a herramientas MCP (Claude, GPT, Gemini, modelos locales, etc.).
 
-Expone **154 herramientas**: dibujo, animación, diagramas, mapas, tipografía, física, edición de imágenes, visualización de datos y exportación:
+Expone **157 herramientas**: dibujo, animación, diagramas, mapas, tipografía, física, edición de imágenes, visualización de datos y exportación:
 
 - Crear texto, formas, geometría y gráficos complejos
 - Animar con **relaciones** declarativas en lugar de fotogramas clave

package/README.fr.md

@@ -19,7 +19,7 @@
 
 Le serveur MCP PinePaper permet aux assistants IA de créer et d'animer des graphiques dans [PinePaper Studio](https://pinepaper.studio) via le Model Context Protocol. Compatible avec toute IA gérant les appels d'outils MCP (Claude, GPT, Gemini, modèles locaux, etc.).
 
-Il expose **154 outils** : dessin, animation, diagrammes, cartes, typographie, physique, retouche d'image, visualisation de données et export :
+Il expose **157 outils** : dessin, animation, diagrammes, cartes, typographie, physique, retouche d'image, visualisation de données et export :
 
 - Créer du texte, des formes, de la géométrie et des graphiques complexes
 - Animer avec des **relations** déclaratives plutôt que des images clés

package/README.hi.md

@@ -19,7 +19,7 @@
 
 PinePaper MCP सर्वर AI असिस्टेंट्स को Model Context Protocol के ज़रिए [PinePaper Studio](https://pinepaper.studio) में ग्राफ़िक्स बनाने और एनिमेट करने देता है। MCP टूल कॉलिंग वाले किसी भी AI (Claude, GPT, Gemini, लोकल मॉडल आदि) के साथ काम करता है।
 
-सर्वर **154 टूल** देता है — ड्रॉइंग, एनिमेशन, डायग्राम, नक्शे, टाइपोग्राफ़ी, फिज़िक्स, इमेज एडिटिंग, डेटा विज़ुअलाइज़ेशन और एक्सपोर्ट:
+सर्वर **157 टूल** देता है — ड्रॉइंग, एनिमेशन, डायग्राम, नक्शे, टाइपोग्राफ़ी, फिज़िक्स, इमेज एडिटिंग, डेटा विज़ुअलाइज़ेशन और एक्सपोर्ट:
 
 - टेक्स्ट, आकृतियाँ, ज्यामिति और जटिल ग्राफ़िक्स बनाना
 - कीफ़्रेम की जगह व्यवहार बताने वाले **रिलेशन** से एनिमेशन

package/README.ja.md

@@ -19,7 +19,7 @@
 
 PinePaper MCP サーバーは、MCP 経由で AI アシスタントが [PinePaper Studio](https://pinepaper.studio) 上にグラフィックを作成・アニメーションさせるためのサーバーです。MCP ツールコールに対応した AI（Claude、GPT、Gemini、ローカルモデルなど）で動作します。
 
-**154 個のツール**を提供 — 描画・アニメーション・図・地図・タイポグラフィ・物理・画像編集・データ可視化・エクスポート：
+**157 個のツール**を提供 — 描画・アニメーション・図・地図・タイポグラフィ・物理・画像編集・データ可視化・エクスポート：
 
 - テキスト、図形、ジオメトリ、複雑なグラフィックの作成
 - キーフレームではなく、ふるまいを宣言する**リレーション**でアニメーション

package/README.ko.md

@@ -19,7 +19,7 @@
 
 PinePaper MCP 서버는 AI 어시스턴트가 MCP를 통해 [PinePaper Studio](https://pinepaper.studio)에서 그래픽을 만들고 애니메이션하게 해줍니다. MCP 툴 콜을 지원하는 모든 AI(Claude, GPT, Gemini, 로컬 모델 등)와 호환됩니다.
 
-**154개의 툴** 제공 — 드로잉, 애니메이션, 다이어그램, 지도, 타이포그래피, 물리, 이미지 편집, 데이터 시각화, 내보내기:
+**157개의 툴** 제공 — 드로잉, 애니메이션, 다이어그램, 지도, 타이포그래피, 물리, 이미지 편집, 데이터 시각화, 내보내기:
 
 - 텍스트·도형·기하·복잡한 그래픽 생성
 - 키프레임 대신 행동을 선언하는 **릴레이션**으로 애니메이션

package/README.md

@@ -30,7 +30,7 @@
 
 PinePaper MCP Server enables AI assistants to create and animate graphics in [PinePaper Studio](https://pinepaper.studio) via the Model Context Protocol (MCP). Works with any AI that supports MCP tool calling (Claude, GPT, Gemini, local models, etc.).
 
-The server exposes **154 tools** across drawing, animation, diagrams, maps, typography, physics, image editing, data visualization, and export. Using natural language, you can:
+The server exposes **157 tools** across drawing, animation, diagrams, maps, typography, physics, image editing, data visualization, and export. Using natural language, you can:
 
 - Create geometric shapes, text collages, diagrams, and data charts
 - Apply 37+ character-level text effects and 28+ vertex deformation presets
@@ -41,7 +41,7 @@ The server exposes **154 tools** across drawing, animation, diagrams, maps, typo
 
 ## Running it: local or hosted
 
-**Local is free and complete.** Every one of the 154 tools works when you run
+**Local is free and complete.** Every one of the 157 tools works when you run
 this server yourself. There is no reduced tier and nothing held back.
 
 What it needs:
@@ -246,6 +246,61 @@ If you do not want an agent executing anything, `code` mode is a first-class pat
 - Puppeteer mode launches Chrome with `--no-sandbox` and `--disable-setuid-sandbox`. That is routine for headless automation and it does weaken Chrome's own process sandbox. If that matters where you are running it, use `code` mode or put the server in a container.
 - Puppeteer itself is an **optional** peer dependency, kept out of the default tree precisely because a headless browser plus an install script is what scanners flag hardest. Install it only if you want the executing mode.
 
+## What's new in 1.6.16
+
+### New: video editing on the timeline
+
+`pinepaper_media` gains `split` (cut a clip in two at a time),
+`add_transition` (a crossfade or a dip between two clips that meet), and
+`set_clip` with `timeOffset` to move a clip, not only trim it. Uploads take
+`atPlayhead: true` to start at the current playback time. A studio that cannot
+do one of these says so rather than reporting success.
+
+### New: AI image generation (beta)
+
+`pinepaper_generate` creates images with AI models in the PinePaper cloud and
+can place the first one on the canvas; `pinepaper_generate_estimate` prices a
+request and lists the models, free. It is charged per image, needs a service
+account key (`PINEPAPER_API_KEY`), and is enabled per organisation during the
+beta — without it the tools say so, and nothing is charged.
+
+Words are never drawn by the model: pass them as `input.text` (headline,
+subhead, caption, call to action, label) and they are added as real, editable
+PinePaper text over the image, laid out inside the title-safe area and given a
+dark backing only where the image behind them is too bright to read.
+
+### New: add to an animation instead of replacing it
+
+`pinepaper_keyframe_animate` takes `append: true` to add keys to an item's
+existing animation — a button press after an entrance. Without it, a second
+call replaces the animation, and the result now says when that happened.
+
+### New: byte-identical exports
+
+`pinepaper_agent_export` takes `deterministic: true` for MP4 and WebM: the same
+scene gives the same file, so exports can be checksummed or cached by hash. If
+a run could not be pinned, the result says not to rely on the hash.
+
+### Fixed
+
+- `pinepaper_import_asset` with a `url` failed on every call after fetching the
+  file successfully.
+- `pinepaper_sound` `render_soundtrack` timed out on longer soundtracks; it now
+  has the same time budget as other exports.
+- `pinepaper_audio_beats` answered success with no result for larger audio, and
+  could not read a local file path. Both work now.
+- `pinepaper_camera_animate` without keyframes failed with a raw JSON error; it
+  now says what `keyframes` needs.
+- `pinepaper_precomp`: `create` returned an internal id that no tool accepted,
+  and `add` / `remove` could not work at all. All three now round-trip the
+  precomp's item id, and a failed `remove` is reported.
+- `pinepaper_media` `set_time_remap`, `speed_ramp`, `match_cut` and the track
+  matte actions accept the media id that upload returns, as documented.
+- `modify_item` `content` on text whose content is keyframed now warns that the
+  keyframes override it.
+- Exporting a landscape canvas for a portrait platform (TikTok, Stories) — or
+  the reverse — is a fidelity warning with the fix, not only a note.
+
 ## What's new in 1.6.15
 
 ### New: the PinePaper mark
@@ -1171,7 +1226,7 @@ Fourteen new tools (121 → 135) and new actions across the surface — the rele
 
 ## Toolkits & Token Budget
 
-154 tools is a lot of context. The server ships a **toolkit** system that serves only the tools a given client needs, plus a **verbosity** system that controls how long each tool description is.
+157 tools is a lot of context. The server ships a **toolkit** system that serves only the tools a given client needs, plus a **verbosity** system that controls how long each tool description is.
 
 **Toolkit profiles** (`PINEPAPER_TOOLKIT`):
 
@@ -1376,7 +1431,7 @@ Generate instruction/code pairs for LLM fine-tuning:
 
 ## Tools Reference
 
-All 154 tools, grouped by the tag used for toolkit filtering.
+All 157 tools, grouped by the tag used for toolkit filtering.
 
 ### Canvas (`canvas`)
 | Tool | Description |
@@ -1477,6 +1532,9 @@ All 154 tools, grouped by the tag used for toolkit filtering.
 |------|-------------|
 | `pinepaper_execute_generator` | Run a background generator |
 | `pinepaper_list_generators` | List available generators |
+| `pinepaper_generate` | AI image generation in the PinePaper cloud (charged; beta, per organisation) |
+| `pinepaper_generate_estimate` | Free price check, and the model list |
+| `pinepaper_generate_status` | Collect a generation that outlived its timeout |
 | `pinepaper_apply_effect` | Apply sparkle, blast, and other effects |
 | `pinepaper_text_effect` | 37 character-level text animations; replaces the text with one keyframed item per character |
 | `pinepaper_add_filter` | Add an image filter |
@@ -1871,6 +1929,8 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
 |----------|-------------|---------|
 | `PINEPAPER_STUDIO_URL` | PinePaper Studio URL to connect to (`/editor` is appended automatically) | `https://pinepaper.studio` |
 | `PINEPAPER_HEADLESS` | Run the browser headless (set `false` to watch it work) | `true` |
+| `PINEPAPER_API_KEY` | Service-account key (`pp_sa_…`) for the cloud-backed tools (`pinepaper_generate`) | — |
+| `PINEPAPER_CLOUD_URL` | The PinePaper cloud those tools call | `https://cloud.pinepaper.studio` |
 | `PINEPAPER_EXECUTION_MODE` | `puppeteer` (execute in a real browser) or `code` (return generated code only) | `puppeteer` |
 | `PINEPAPER_EXPORT_DIR` | Directory for exported files | `<tmpdir>/pinepaper-exports` |
 | `PINEPAPER_LOCALE` | Language locale code | `en` |

package/README.pt-BR.md

@@ -19,7 +19,7 @@
 
 O servidor MCP do PinePaper permite que assistentes de IA criem e animem gráficos no [PinePaper Studio](https://pinepaper.studio) via Model Context Protocol. Funciona com qualquer IA que suporte chamadas de ferramenta MCP (Claude, GPT, Gemini, modelos locais etc.).
 
-São **154 ferramentas**: desenho, animação, diagramas, mapas, tipografia, física, edição de imagens, visualização de dados e exportação:
+São **157 ferramentas**: desenho, animação, diagramas, mapas, tipografia, física, edição de imagens, visualização de dados e exportação:
 
 - Criar texto, formas, geometria e gráficos complexos
 - Animar com **relações** declarativas em vez de keyframes

package/README.zh-CN.md

@@ -19,7 +19,7 @@
 
 PinePaper MCP 服务器让 AI 助手通过 MCP 协议在 [PinePaper Studio](https://pinepaper.studio) 中创建和驱动图形动画。兼容任何支持 MCP 工具调用的 AI（Claude、GPT、Gemini、本地模型等）。
 
-服务器提供 **154 个工具**，覆盖绘图、动画、图表、地图、排版、物理、图像编辑、数据可视化与导出：
+服务器提供 **157 个工具**，覆盖绘图、动画、图表、地图、排版、物理、图像编辑、数据可视化与导出：
 
 - 创建文本、形状、几何图形与复杂图稿
 - 用行为驱动的**关系（relations）**做动画，而不是逐帧关键帧

package/dist/build-info.json

@@ -1,5 +1,5 @@
 {
-  "sha": "21f9ebb",
+  "sha": "d683e91",
   "dirty": false,
-  "builtAt": "2026-09-25T20:36:58.520Z"
+  "builtAt": "2026-09-27T06:25:49.247Z"
 }

package/dist/ontology/upstream-vocabulary.d.ts

@@ -4,9 +4,9 @@
  * FxTool's ITEM_TYPE_MAP and type classes (anchor, description, parentType,
  * mcpTool, mcpAction), read from the loaded module.
  *
- * Source: FxTool origin/main 253a01a04c886713f610e619ac6205e59751dbb4
+ * Source: FxTool origin/main 9dd578afaa83c6286bfa2f554e8665407be400e1
  *   js/ontology/Vocabulary.js
- * sha256: 8c39f8ad6d2da359
+ * sha256: 48fb80f82d3d3220
  *
  * vocabulary.ts merges these over its hand-written port: the engine's map
  * wins where the two disagree, and a class the port lacks is added.

package/dist/ontology/upstream-vocabulary.js

@@ -4,9 +4,9 @@
  * FxTool's ITEM_TYPE_MAP and type classes (anchor, description, parentType,
  * mcpTool, mcpAction), read from the loaded module.
  *
- * Source: FxTool origin/main 253a01a04c886713f610e619ac6205e59751dbb4
+ * Source: FxTool origin/main 9dd578afaa83c6286bfa2f554e8665407be400e1
  *   js/ontology/Vocabulary.js
- * sha256: 8c39f8ad6d2da359
+ * sha256: 48fb80f82d3d3220
  *
  * vocabulary.ts merges these over its hand-written port: the engine's map
  * wins where the two disagree, and a class the port lacks is added.

package/dist/tools/definitions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"definitions.d.ts","sourceRoot":"","sources":["../../src/tools/definitions.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,oCAAoC,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AA+B/C,eAAO,MAAM,cAAc,6kbAyK+G,CAAC;AAW3I,eAAO,MAAM,eAAe,EAAE,IAAI,EAukRjC,CAAC;AAEF;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAE5D;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,EAAE,CAEvC;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,EAAE,CAO3D;AAED;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAE9D;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,aAAa,GAAG,IAAI,EAAE,CAQrE"}
+{"version":3,"file":"definitions.d.ts","sourceRoot":"","sources":["../../src/tools/definitions.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,oCAAoC,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AA+B/C,eAAO,MAAM,cAAc,6kbAyK+G,CAAC;AAW3I,eAAO,MAAM,eAAe,EAAE,IAAI,EA2qRjC,CAAC;AAEF;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAE5D;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,MAAM,EAAE,CAEvC;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,EAAE,CAO3D;AAED;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAE9D;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,aAAa,GAAG,IAAI,EAAE,CAQrE"}

package/dist/tools/definitions.js

@@ -1755,6 +1755,91 @@ EXAMPLE: { checks: ["contrast", "flash"], duration: 6, fps: 20 }`,
             },
         },
     },
+    {
+        name: 'pinepaper_generate',
+        annotations: { title: 'Generate Image (cloud)', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+        description: `Generate images with an AI model in the PinePaper cloud, and optionally place the first one on the canvas. CHARGED per output — price it first with pinepaper_generate_estimate (free).
+
+Needs a service-account key in PINEPAPER_API_KEY (pp_sa_…, render:create scope). It is an internal beta enabled per organisation: without it the result says "not enabled for your organisation", and nothing is charged. Every refusal says whether anything was charged.
+
+- model or useCase: a model id from pinepaper_generate_estimate {listModels: true}, or a use case and the cloud picks its default (hero stills, plates, text in the image, character-consistent edits).
+- input: { prompt, aspect ('16:9' | '9:16' | '1:1' | '4:5'), n (1-4), seed?, negativePrompt?, imageUrls? (https references for edit models) }.
+- brief / designRef: always passed on; the cloud records each generation against the design.
+- place: 'cover' (fill the canvas, centred; default when true) or 'contain' — places the first asset: an image as an image item, a video as a video layer (with its durationSeconds). The fit uses the asset's delivered size, not the requested aspect.
+- timeoutSec: how long to wait (default 180). A job that outlives it keeps running and is only charged if it delivers; collect it with pinepaper_generate_status.
+
+WORDS ARE VECTOR: give words as input.text [{content, role?: headline|subhead|caption|cta|label, font?}]. The model makes a text-free plate; the words come back as textLayers (plus a hint), and with place they are added as real, editable text over it: headline top-left (Anton by default), subhead below, caption / cta bottom-left, label top-right, inside title-safe, each contrast-checked against the plate (a dark scrim is added only where it falls short of WCAG 4.5:1, or 3:1 for large text). Their item ids are in placement.text.
+
+The result: assets [{assetId, ref, width, height}] — the sizes the files HAVE (a model may pick its own size for an aspect), chargedUsd, and any model notes (e.g. a SynthID watermark) to pass on.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                model: { type: 'string' },
+                useCase: { type: 'string' },
+                input: {
+                    type: 'object',
+                    properties: {
+                        prompt: { type: 'string' },
+                        aspect: { type: 'string', enum: ['16:9', '9:16', '1:1', '4:5'] },
+                        n: { type: 'integer', minimum: 1, maximum: 4 },
+                        seed: { type: 'integer' },
+                        negativePrompt: { type: 'string' },
+                        imageUrls: { type: 'array', items: { type: 'string' }, maxItems: 14, description: 'Reference / start-frame images: https URLs, or your own generated images as their ref "/scene-assets/<id>" (chain a still into a video or a character edit).' },
+                        seconds: { type: 'number', exclusiveMinimum: 0, maximum: 60, description: 'Video models: clip length; each model allows its own lengths (listModels).' },
+                        text: { type: 'array', maxItems: 12, items: { type: 'object', properties: { content: { type: 'string' }, role: { type: 'string', enum: ['headline', 'subhead', 'caption', 'cta', 'label'] }, font: { type: 'string' } }, required: ['content'] }, description: 'Words for the design. The model never draws them: the plate comes back text-free and these return as textLayers — with place, laid out as real PinePaper text.' },
+                        allowText: { type: 'boolean', description: 'Let the MODEL draw text — eval-tier models only (e.g. ideogram-v3); refused (422) elsewhere. Prefer text.' },
+                    },
+                    required: ['prompt'],
+                },
+                brief: { type: 'string' },
+                designRef: { type: 'object', properties: { kind: { type: 'string' }, id: { type: 'string' } }, required: ['kind', 'id'] },
+                place: { anyOf: [{ type: 'boolean' }, { type: 'string', enum: ['cover', 'contain'] }] },
+                timeoutSec: { type: 'integer', minimum: 10, maximum: 1800 },
+            },
+            required: ['input'],
+        },
+    },
+    {
+        name: 'pinepaper_generate_estimate',
+        annotations: { title: 'Estimate Generation (free)', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+        description: `Free: price a pinepaper_generate call before making it, or list the models. { listModels: true } returns every model you may use with its price per output, use cases, licence notes and the defaults per use case; { model | useCase, input } returns the estimate for that request. Needs PINEPAPER_API_KEY, like pinepaper_generate.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                model: { type: 'string' },
+                useCase: { type: 'string' },
+                input: {
+                    type: 'object',
+                    properties: {
+                        prompt: { type: 'string' },
+                        aspect: { type: 'string', enum: ['16:9', '9:16', '1:1', '4:5'] },
+                        n: { type: 'integer', minimum: 1, maximum: 4 },
+                        seed: { type: 'integer' },
+                        negativePrompt: { type: 'string' },
+                        imageUrls: { type: 'array', items: { type: 'string' }, maxItems: 14, description: 'Reference / start-frame images: https URLs, or your own generated images as their ref "/scene-assets/<id>" (chain a still into a video or a character edit).' },
+                        seconds: { type: 'number', exclusiveMinimum: 0, maximum: 60, description: 'Video models: clip length; each model allows its own lengths (listModels).' },
+                        text: { type: 'array', maxItems: 12, items: { type: 'object', properties: { content: { type: 'string' }, role: { type: 'string', enum: ['headline', 'subhead', 'caption', 'cta', 'label'] }, font: { type: 'string' } }, required: ['content'] }, description: 'Words for the design. The model never draws them: the plate comes back text-free and these return as textLayers — with place, laid out as real PinePaper text.' },
+                        allowText: { type: 'boolean', description: 'Let the MODEL draw text — eval-tier models only (e.g. ideogram-v3); refused (422) elsewhere. Prefer text.' },
+                    },
+                    required: ['prompt'],
+                },
+                listModels: { type: 'boolean' },
+            },
+        },
+    },
+    {
+        name: 'pinepaper_generate_status',
+        annotations: { title: 'Generation Status', readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+        description: `Collect a pinepaper_generate job that outlived its timeoutSec: its status, and when done its assets and chargedUsd. place: 'cover' | 'contain' places the first image, as pinepaper_generate does.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                jobId: { type: 'string' },
+                place: { anyOf: [{ type: 'boolean' }, { type: 'string', enum: ['cover', 'contain'] }] },
+            },
+            required: ['jobId'],
+        },
+    },
     {
         name: 'pinepaper_render_batch',
         annotations: {
@@ -2043,15 +2128,18 @@ EXAMPLE: { times: [0, 0.5, 1, 1.5, 2], seed: 42 }`,
         description: `Bring VIDEO and AUDIO onto the canvas from a URL, and control playback. Uploaded video is a first-class canvas item (drag, scale, animate, export like any shape); audio rides the timeline.
 
 ACTIONS:
-- upload_video: { url (required), position?, scale?, timeOffset? (timeline start, s), clipInPoint?, clipOutPoint? (trim, s) } → { id, duration, width, height, name }
-- upload_audio: { url (required), volume? (0–1, default 1), loop?, muted?, timeOffset? } → { id, registryId, duration, name }. Pass loop EXPLICITLY — loop:true for a music bed, loop:false for a voice-over or sting; when omitted, the studio's own default applies and differs between builds.
+- upload_video: { url (required), position?, scale?, timeOffset? (timeline start, s) or atPlayhead?: true (start at the current playback time), clipInPoint?, clipOutPoint? (trim, s) } → { id, duration, width, height, name }
+- upload_audio: { url (required), volume? (0–1, default 1), loop?, muted?, timeOffset? or atPlayhead? } → { id, registryId, duration, name }. Pass loop EXPLICITLY — loop:true for a music bed, loop:false for a voice-over or sting; when omitted, the studio's own default applies and differs between builds.
 - list: → all media [{ id, kind, duration, … }]
 - remove: { id } → removed boolean
 - set_playback_rate: { id, rate (0.25–4) } → applies to video or audio
-- set_clip: { id, inPoint, outPoint (media-time s, outPoint > inPoint) } → re-trim an ALREADY-uploaded clip (video or audio)
+- set_clip: { id, inPoint, outPoint (media-time s, outPoint > inPoint), timeOffset? (canvas s: also MOVE the clip to start there) } → re-trim an ALREADY-uploaded clip (video or audio). A studio that cannot move clips refuses timeOffset rather than ignoring it.
+- split: { id, at (canvas s) } → cut a clip in two: { leftId, rightId, leftMediaId, rightMediaId, at }. The first half keeps its id. Refused (not claimed) where the studio cannot split or the time is outside the clip.
+- add_transition: { fromItemId (ends at the cut), toItemId (starts at it), transition?: { type: 'crossfade'|'dip', seconds, color } } → the same in preview and export. Split a clip, then transition between its halves, or join two clips that meet.
+- For an IMAGE on the timeline, use pinepaper_import_image with bornAt / ttl (seconds on screen).
 
 NOTES:
-- URL-based: the URL is fetched in the browser, so it must be reachable + CORS-permitted.
+- The server fetches the URL (or reads a local path / data: URL) and hands the page the bytes, so it does not need to be CORS-permitted.
 - Use the returned id with set_playback_rate / set_clip / remove, and (for video) modify/animate it like any item.
 
 VIDEO EDITING:
@@ -2065,14 +2153,16 @@ EXAMPLE: { action: 'upload_video', url: 'https://…/clip.mp4', scale: 0.5, time
         inputSchema: {
             type: 'object',
             properties: {
-                action: { type: 'string', enum: ['upload_video', 'upload_audio', 'list', 'remove', 'set_playback_rate', 'set_clip', 'set_time_remap', 'speed_ramp', 'match_cut', 'apply_track_matte', 'stop_live_matte'], description: "Media action" },
+                action: { type: 'string', enum: ['upload_video', 'upload_audio', 'list', 'remove', 'set_playback_rate', 'set_clip', 'split', 'add_transition', 'set_time_remap', 'speed_ramp', 'match_cut', 'apply_track_matte', 'stop_live_matte'], description: "Media action" },
+                transition: { type: 'object', properties: { type: { type: 'string', enum: ['crossfade', 'dip'] }, seconds: { type: 'number', exclusiveMinimum: 0, maximum: 10 }, color: { type: 'string' } }, description: "add_transition: { type ('crossfade' default | 'dip'), seconds, color (dip) }." },
+                atPlayhead: { type: 'boolean', description: 'upload_video / upload_audio: start at the current playback time (instead of timeOffset).' },
                 remapTrack: { type: 'array', items: { type: 'object', properties: { time: { type: 'number' }, value: { type: 'number' }, easing: { type: 'string' } }, required: ['time', 'value'] }, description: 'set_time_remap: canvas-seconds → source-seconds curve (≥2 points). null clears the remap.' },
                 segments: { type: 'array', items: { type: 'object', properties: { duration: { type: 'number' }, speed: { type: 'number' } }, required: ['duration', 'speed'] }, description: 'speed_ramp: consecutive {duration, speed} segments. speed 0 = freeze frame, negative = reverse.' },
                 fromItemId: { type: 'string', description: 'match_cut: outgoing shot item id.' },
                 toItemId: { type: 'string', description: 'match_cut: incoming shot item id.' },
                 subject: { type: 'string', enum: ['detect', 'bounds'], description: "match_cut: subject source — 'detect' (on-device DETR, needs consent on first use) or 'bounds'." },
                 label: { type: 'string', description: 'match_cut: narrow detection to one class ("person") when the biggest object is not the subject.' },
-                at: { type: 'number', description: 'match_cut: cut time in seconds (default 0).' },
+                at: { type: 'number', description: 'match_cut: cut time in seconds (default 0). split: the canvas time to cut at (required).' },
                 settle: { type: 'number', description: 'match_cut: seconds to relax to natural framing (default 0.8).' },
                 fade: { type: 'number', description: 'match_cut: crossfade seconds; 0 = hard cut (default 0.12).' },
                 consent: { type: 'boolean', description: 'match_cut: allow the detection model download (a first run without it returns needsConsent instead of downloading silently).' },
@@ -2089,7 +2179,7 @@ EXAMPLE: { action: 'upload_video', url: 'https://…/clip.mp4', scale: 0.5, time
                 outPoint: { type: 'number', description: 'Clip out-point (media-time s, > inPoint) — set_clip.' },
                 position: { type: 'object', properties: { x: { type: 'number' }, y: { type: 'number' } }, description: 'Canvas position — upload_video.' },
                 scale: { type: 'number', description: 'Scale factor — upload_video.' },
-                timeOffset: { type: 'number', description: 'Timeline start offset (s) — upload_video / upload_audio.' },
+                timeOffset: { type: 'number', description: 'Timeline start offset (s) — upload_video / upload_audio; set_clip: move the clip to start here.' },
                 clipInPoint: { type: 'number', description: 'Trim in-point (s) — upload_video.' },
                 clipOutPoint: { type: 'number', description: 'Trim out-point (s) — upload_video.' },
                 volume: { type: 'number', description: 'Volume 0–1 (default 1) — upload_audio.' },
@@ -3571,6 +3661,10 @@ EXAMPLE — Reveal at 2s, skip first second of keyframe data, end at 4s of keyfr
                     type: 'number',
                     description: 'Stop at N seconds into the keyframe data (tail trim). Default: lastKeyframeTime.',
                 },
+                append: {
+                    type: 'boolean',
+                    description: 'Add these keys to the item\'s existing track (same-time keys merge, new values win) instead of replacing it — e.g. a button press after an entrance. Without it, a second call replaces the track. result.track says whether the track was appended to or replaced; studios without merge replace, and say so.',
+                },
             },
             required: ['itemId', 'keyframes'],
         },
@@ -4901,7 +4995,9 @@ ACTIONS:
 - update_from_instance: Promote an instance's edits back into the master. Params: instanceId
 - detach: Make an instance an ordinary independent item. Params: instanceId
 
-Overrides are the point: an instance can differ from its master and still receive master updates.`,
+Overrides are the point: an instance can differ from its master and still receive master updates.
+
+Instances carry the master's LOOK (geometry, style, text), not its animation: instantiate and sync copy what the master is, not its keyframes or animations. To animate instances, animate each one (keyframe_animate on its instanceId, or stagger across them).`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -8050,6 +8146,7 @@ VERIFY MOTION BEFORE YOU RENDER. An export takes seconds to minutes and shows yo
                 alphaQuantizer: { type: 'integer', minimum: 0, maximum: 63, description: 'webm with transparent: alpha-stream quality, 0 = lossless … 63.' },
                 loop: { anyOf: [{ type: 'boolean' }, { type: 'integer', minimum: 0, maximum: 1000 }], description: 'gif / apng: true = loop forever, false / 0 / 1 = play once, n = play n times (email clients often want a few plays, not forever). Refused on video formats — see SEAMLESS LOOPS.' },
                 broadcast: { type: 'boolean', description: 'mp4 only: broadcast-safe — BT.709, limited range (16-235), tagged bt709, constant bitrate with an 8 Mbps floor at 720p+ (4 below). result.video reports what the encoder did.' },
+                deterministic: { type: 'boolean', description: 'mp4 / webm: byte-identical files for the same scene (pins the container timestamps), so exports can be checksummed or cached by hash.' },
                 broadcastHeadroom: { type: 'integer', minimum: 0, maximum: 40, description: 'mp4 with broadcast only, default 12: luma codes kept clear at both ends, so encoder ringing stays legal (12 measured clean on hard edges; 4 = ~100x fewer out-of-range samples, 12 = ~1000x; never zero). Fidelity raises luma_out_of_range with the legaliser command when any remain.' },
                 bitrate: { type: 'integer', minimum: 100000, maximum: 200000000, description: 'mp4 / webm: target bits/s, replacing the quality-derived one. The browser encoder treats it as a CEILING; result.video.achievedBitrate is what it produced.' },
                 minBitrate: { type: 'integer', minimum: 100000, maximum: 200000000, description: 'mp4 / webm: a floor; a miss is a fidelity warning naming the re-encode a delivery spec needs.' },