@pixerate/editor 0.80.0 → 0.81.0

package/README.md

@@ -211,7 +211,7 @@ Built-in providers:
 | Provider | Tools |
 | :--- | :--- |
 | `createRichTextToolProvider(editor, { id })` | `get_text` (`format`, `blocks: true` for every paragraph's positions), `find_text`, `insert_text`, `replace_text` (all matches or the n-th, one undo step), `replace_range`, `replace_selection`, `set_selection`, `edit_table` (when tables are on). Read-only editors get `get_text` and `find_text`. |
-| `createSpreadsheetToolProvider(controller, { id })` | `get_range`, `set_cell`, `set_range` (2D block, one undo step, refuses read-only targets), `insert_rows`, `delete_rows`, `insert_columns`, `delete_columns` |
+| `createSpreadsheetToolProvider(controller, { id })` | `get_range`, `set_cell`, `set_range` (2D block, one undo step, refuses read-only targets), `insert_rows`, `delete_rows`, `insert_columns`, `delete_columns`, `merge_cells`, `unmerge_cells`, `transpose_range` (on an A1 range, not the user's selection) |
 | `createEditorMcpToolProvider({ id, getSnapshot, applySteps })` | `get_editor_state`, `canvas_add_node`, `canvas_remove_nodes`, `canvas_connect`, `canvas_update_node`, `canvas_layout`, `canvas_select`, `canvas_highlight`, `prompt_insert_text`, `prompt_replace_range`, `prompt_set_variable`, `prompt_select`, `view_editor` (with `captureView`) |
 | `createCanvasComponentToolProvider`, `createCommandToolProvider`, `createImageEditorToolProvider`, `createGenerationToolProvider` | See the canvas, commands, image editor and generation docs |
 
@@ -250,6 +250,16 @@ const result = await registry.callTool(name, args); // MCP tools/call result
 
 It exports `ToolRegistry`, `createToolRegistry`, `ToolRegistryError`, the tool types (`AgentTool`, `AgentToolProvider`, `AgentToolHandler`, `ToolCallContext`, `McpToolDefinition`, `McpToolResult`, `McpListToolsResult`, `ToolCallError`), `validateJsonSchema` / `SchemaValidationError`, the static tool definitions (`EDITOR_MCP_TOOLS`, `EDITOR_CANVAS_TOOLS`, `EDITOR_PROMPT_TOOLS`) and `createMcpServer`. `/agent` re-exports all of it, so existing imports keep working. `createEditorMcpToolProvider` stays in `/agent` because its `layout` operation runs dagre.
 
+### Agent skills
+
+The package ships an [Agent Skill](https://agentskills.io) per editor domain in `skills/` (`pixerate-chart`, `pixerate-video-editor`, ...) plus `pixerate-agent-tools` for what they share. Each tells a model when and how to use every tool and command of its domain and the practice an expert would follow. Copy them into your agent's skills folder:
+
+```bash
+cp -R node_modules/@pixerate/editor/skills/* .claude/skills/
+```
+
+See [`skills/README.md`](./skills/README.md) for the list.
+
 ## Commands, shortcuts and the command palette
 
 `@pixerate/editor/commands` gives every action one id that menus, keyboard shortcuts, the command palette and agents all run, so they share enablement and parameter validation. It has no third-party imports.
@@ -323,7 +333,7 @@ const plan = planGenerationRequest({ aspectRatio: "21:9", count: 3 }, model, { s
 ```
 
 - **Strategies**: `nearest` (default) snaps enum values to the closest option, clamps and rounds ranges, truncates text and reference lists, and drops unsupported fields and references, reporting each change. Ties go to the higher value, or to the lower one with `downgrade`. `upgrade` also breaks ties upwards but does not drop references the model cannot use: that is an error, as is a text-only model given image references. `error` changes nothing and reports every mismatch. Missing required references, unsupported modes (`edit` / `inpaint`) and a model mismatch are always errors. Planning is pure and deterministic.
-- **Schema and agents**: `capabilitiesToJsonSchema(model)` builds a strict request schema (enums, `minimum` / `maximum`, `maxItems`, and descriptions for per-role limits) that `validateJsonSchema` checks. `createGenerationToolProvider({ models, generate, estimate? })` adds `list_models`, `plan_generation` and `estimate_generation` (read-only) and `generate` (destructive) to a `ToolRegistry`. `generate` requires an `idempotencyKey`: a retry with the same key and arguments returns the first result (or joins it while it is still running) instead of generating again. `mergeCapabilities(remote, overlay)` keeps server capability values and takes only presentation fields (`name`, `description`, `badges`, `icon`, `group`) and overlay-only models from the overlay.
+- **Schema and agents**: `capabilitiesToJsonSchema(model)` builds a strict request schema (enums, `minimum` / `maximum`, `maxItems`, and descriptions for per-role limits) that `validateJsonSchema` checks. `createGenerationToolProvider({ models, generate, estimate? })` adds `list_models`, `plan_generation` and `estimate_generation` (read-only) and `generate` (destructive) to a `ToolRegistry`. `generate` requires an `idempotencyKey`: a retry with the same key and arguments returns the first result (or joins it while it is still running) instead of generating again. `createGenerationHistoryToolProvider({ store, models?, templates?, assets? })` lets an agent use the generation history: `list_generations`, `get_generation`, and `recreate_generation` / `vary_generation`, which return a request (with drift) to pass to `generate` rather than spending themselves. `mergeCapabilities(remote, overlay)` keeps server capability values and takes only presentation fields (`name`, `description`, `badges`, `icon`, `group`) and overlay-only models from the overlay.
 - **Provenance**: `createProvenance({ rawPrompt, templates, bindings, values, model, plan })` pins the exact bodies and versions of every template the prompt reached, and records the variable values, the resolved prompt with its source map, the planned settings, adjustments and references. `serializeProvenance` / `parseProvenance` are versioned. `recreateRequest(provenance)` returns the request that was sent, and `replayProvenancePrompt` re-resolves the prompt from the pinned bodies.
 - **Lookups and progress**: `createBatchResolver({ fetch, maxBatch, delayMs })` batches and dedupes lookups; a failed batch resolves its keys as empty instead of retrying. `estimateJobProgress({ startedAt, now, expectedMs })` returns a time-based percent that stays at or below 95 until `done`, and a label such as `~2m left` or `Almost done…`. `expectedDurationFor(model, request)` uses the model's `timing`.
 - **Forms**: `getGenerationControls(model)` and `getReferenceSlots(model, request)` describe the controls that the React and Svelte `<GenerationSettings>` render.
@@ -372,7 +382,7 @@ editor.setAdjustmentLayerMaskProps(id, { density: 0.6 });
 - **Layer masks**: `AdjustmentLayer.mask` (`{ width, height, rle, density?, feather?, enabled? }`) scales the layer's opacity per pixel; it is resampled through the crop / rotation / flips like the image. `selectionFromLayerMask` loads it back.
 - **Document**: `toJSON()` adds `selection` (run-length encoded, `r1:` + base64) only when something is selected, and layers only carry `mask` when they have one, so selection- and mask-free documents serialize exactly as before. Selections are part of undo history. `renderMask()` / `toMaskDataURL()` include the selection for inpainting.
 - **Viewport**: marching ants by default, `quickMask` tints the unselected area; `RenderOptions.selectionDisplay` overrides, `draftSelectionPath` shows a shape being drawn. `SelectionGesture` turns pointer events into selections for UIs.
-- **Agent tools**: `createImageEditorToolProvider` adds `get_selection`, `select_region`, `select_by_color`, `modify_selection`, `refine_selection` and `apply_selection_as_mask`.
+- **Agent tools**: `createImageEditorToolProvider` adds `get_selection`, `select_region`, `select_by_color`, `modify_selection`, `refine_selection` and `apply_selection_as_mask`, plus `get_image_info`, `get_histogram`, `update_adjustment_layer`, `move_adjustment_layer`, `remove_adjustment_layer`, `set_crop`, `reset_crop`, `set_rotation`, `flip_image`, `undo_image` and `redo_image`.
 - **Pixels**: the tools read the source image through a canvas; pass `setSamplePixels(imageData)` (or `{ pixels }` per call) where there is no canvas or the image is cross-origin.
 
 ## Spreadsheet sheets, defined names and LAMBDA

package/dist/agent/index.cjs

@@ -45,7 +45,7 @@ var _chunkK73CKYUMcjs = require('../chunk-K73CKYUM.cjs');
 var _chunkQIWFEEWGcjs = require('../chunk-QIWFEEWG.cjs');
 
 
-var _chunkHXDMZQTDcjs = require('../chunk-HXDMZQTD.cjs');
+var _chunkTPOT575Pcjs = require('../chunk-TPOT575P.cjs');
 require('../chunk-26BVFKHU.cjs');
 
 
@@ -85,7 +85,12 @@ var _chunkCKRNELPOcjs = require('../chunk-CKRNELPO.cjs');
 var _chunkTYOAJDFDcjs = require('../chunk-TYOAJDFD.cjs');
 require('../chunk-IFHKKVXH.cjs');
 require('../chunk-BVP3TSLH.cjs');
-require('../chunk-UN33YOXW.cjs');
+
+
+
+
+
+var _chunkPA5S7KPCcjs = require('../chunk-PA5S7KPC.cjs');
 
 
 
@@ -1044,6 +1049,14 @@ function parseColumn(name) {
   if (!COLUMN_REGEX.test(name.trim())) throw new Error(`Invalid column "${name}". Use a letter name, e.g. "C".`);
   return _chunkXP5IUZUOcjs.colNameToIndex.call(void 0, name.trim().toUpperCase());
 }
+function parseRange(ref) {
+  const [startRef, endRef = startRef, extra] = String(ref).split(":");
+  if (extra !== void 0) throw new Error(`Invalid range "${ref}". Use A1 notation, e.g. "A1:C5".`);
+  const start = parseCell(startRef);
+  const end = parseCell(endRef);
+  return _chunkPA5S7KPCcjs.normalizeRange.call(void 0, { startRow: start.row, startCol: start.col, endRow: end.row, endCol: end.col });
+}
+var formatRange = (r) => `${_chunkXP5IUZUOcjs.indexToColName.call(void 0, r.startCol)}${r.startRow + 1}:${_chunkXP5IUZUOcjs.indexToColName.call(void 0, r.endCol)}${r.endRow + 1}`;
 var CELL_INPUT = { type: ["string", "number", "boolean", "null"] };
 function createSpreadsheetToolProvider(controller, options) {
   const lookup = (row, col) => {
@@ -1054,7 +1067,7 @@ function createSpreadsheetToolProvider(controller, options) {
   const getRange = {
     name: "get_range",
     title: "Read cells",
-    description: 'Reads a cell range in A1 notation (e.g. "A1:C5" or "B2") and returns computed values, raw input and errors.',
+    description: 'Reads a cell range in A1 notation (e.g. "A1:C5" or "B2") and returns computed values, raw input, errors and the merged ranges that touch it (a merged range shows its value in its top-left cell).',
     inputSchema: {
       type: "object",
       properties: {
@@ -1097,11 +1110,13 @@ function createSpreadsheetToolProvider(controller, options) {
         values.push(valueRow);
         raw.push(rawRow);
       }
+      const read = { startRow: r0, startCol: c0, endRow: r1, endCol: c1 };
       return {
-        range: values.length && values[0].length ? `${_chunkXP5IUZUOcjs.indexToColName.call(void 0, c0)}${r0 + 1}:${_chunkXP5IUZUOcjs.indexToColName.call(void 0, c1)}${r1 + 1}` : null,
+        range: values.length && values[0].length ? formatRange(read) : null,
         values,
         raw,
         errors,
+        merges: controller.getMerges().filter((m) => _chunkPA5S7KPCcjs.rangesIntersect.call(void 0, m, read)).map(formatRange),
         sheet: { rows: rowCount, columns: colCount }
       };
     }
@@ -1272,10 +1287,91 @@ function createSpreadsheetToolProvider(controller, options) {
       return { deleted: count, sheet: sheetSize() };
     }
   );
+  const RANGE = { type: "string", description: 'A1-notation range of at least two cells, e.g. "A1:C1".' };
+  const inSheet = (r, ref) => {
+    if (r.endRow >= controller.document.rows.length || r.endCol >= controller.document.columns.length) {
+      throw new Error(`Range ${ref} is outside the sheet (${controller.document.rows.length} rows, ${controller.document.columns.length} columns).`);
+    }
+  };
+  const readOnlyIn = (r) => {
+    const cells = [];
+    for (let row = r.startRow; row <= r.endRow; row++) {
+      for (let col = r.startCol; col <= r.endCol; col++) if (isReadOnly(row, col)) cells.push(`${_chunkXP5IUZUOcjs.indexToColName.call(void 0, col)}${row + 1}`);
+    }
+    return cells;
+  };
+  const SPILL = "it overlaps the spill range of a dynamic array formula; move or clear that formula first";
+  const mergeCells = structural(
+    "merge_cells",
+    "Merge cells",
+    "Merges a range into one cell showing the top-left cell's value. The other cells in the range are cleared, so move their contents first. Merges fully inside the range are absorbed. One undo step. Returns the merged range and the cells that were cleared. Use merges only for titles outside data regions: they break sorting, filtering and transposing.",
+    { range: RANGE },
+    ["range"],
+    true,
+    ({ range }) => {
+      const r = parseRange(range);
+      inSheet(r, range);
+      if (_chunkPA5S7KPCcjs.isSingleCellRange.call(void 0, r)) throw new Error(`${range} is a single cell; give a range of at least two cells.`);
+      const partial = controller.getMerges().find((m) => _chunkPA5S7KPCcjs.rangesIntersect.call(void 0, m, r) && !_chunkPA5S7KPCcjs.rangeContainsRange.call(void 0, r, m));
+      if (partial) throw new Error(`${range} partly overlaps the merged range ${formatRange(partial)}; include all of it or unmerge it first.`);
+      const readOnly = readOnlyIn(r);
+      if (readOnly.length) throw new Error(`Read-only cells: ${readOnly.slice(0, 20).join(", ")}. Nothing was merged.`);
+      const cleared = [];
+      for (let row = r.startRow; row <= r.endRow; row++) {
+        for (let col = r.startCol; col <= r.endCol; col++) {
+          if (row === r.startRow && col === r.startCol) continue;
+          const { rowDef, colDef } = lookup(row, col);
+          if (controller.getCell(rowDef.id, colDef.id).raw !== "") cleared.push(`${_chunkXP5IUZUOcjs.indexToColName.call(void 0, col)}${row + 1}`);
+        }
+      }
+      if (!controller.mergeCells(r)) throw new Error(`Cannot merge ${range}: ${SPILL}.`);
+      return { merged: formatRange(r), cleared };
+    }
+  );
+  const unmergeCells = structural(
+    "unmerge_cells",
+    "Unmerge cells",
+    "Splits every merged range that touches a range back into separate cells (the value stays in the top-left cell; the others are empty). One undo step. Returns the ranges that were unmerged.",
+    { range: { type: "string", description: 'A1-notation cell or range; every merge touching it is split, e.g. "A1".' } },
+    ["range"],
+    false,
+    ({ range }) => {
+      const r = parseRange(range);
+      const touched = controller.getMerges().filter((m) => _chunkPA5S7KPCcjs.rangesIntersect.call(void 0, m, r));
+      if (!touched.length) throw new Error(`No merged cells in ${range}. get_range lists the merges in a range.`);
+      controller.unmergeCells(r);
+      return { unmerged: touched.map(formatRange) };
+    }
+  );
+  const transposeRange = structural(
+    "transpose_range",
+    "Transpose a range",
+    "Swaps the rows and columns of a range in place, anchored on its top-left cell (A1:C2 becomes A1:B3), moving values, formulas, formats and rules; formulas that point into the range follow their cells. The sheet grows to fit. One undo step. Returns the new range. Cells the result covers outside the original range are overwritten.",
+    { range: RANGE },
+    ["range"],
+    true,
+    ({ range }) => {
+      const s = parseRange(range);
+      inSheet(s, range);
+      if (_chunkPA5S7KPCcjs.isSingleCellRange.call(void 0, s)) throw new Error(`${range} is a single cell; give a range of at least two cells.`);
+      const t = {
+        startRow: s.startRow,
+        startCol: s.startCol,
+        endRow: s.startRow + (s.endCol - s.startCol),
+        endCol: s.startCol + (s.endRow - s.startRow)
+      };
+      const merge = controller.getMerges().find((m) => _chunkPA5S7KPCcjs.rangesIntersect.call(void 0, m, s) || _chunkPA5S7KPCcjs.rangesIntersect.call(void 0, m, t));
+      if (merge) throw new Error(`Cannot transpose ${range}: the merged range ${formatRange(merge)} is in the way; unmerge it first.`);
+      const readOnly = [.../* @__PURE__ */ new Set([...readOnlyIn(s), ...readOnlyIn(t)])];
+      if (readOnly.length) throw new Error(`Read-only cells: ${readOnly.slice(0, 20).join(", ")}. Nothing was transposed.`);
+      if (!controller.transposeRange(s)) throw new Error(`Cannot transpose ${range}: ${SPILL}.`);
+      return { range: formatRange(t), sheet: sheetSize() };
+    }
+  );
   return {
     id: options.id,
     namespace: options.namespace,
-    tools: [getRange, setCell, setRange, insertRows, deleteRows, insertColumns, deleteColumns]
+    tools: [getRange, setCell, setRange, insertRows, deleteRows, insertColumns, deleteColumns, mergeCells, unmergeCells, transposeRange]
   };
 }
 function missingArgumentsMessage(name, args) {
@@ -1481,7 +1577,7 @@ function createCanvasComponentToolProvider(controller, options = { id: "canvas-c
       ({ id }) => check(controller.restoreMainComponent(id))
     )
   ];
-  if (_chunkHXDMZQTDcjs.hasVariantCommands.call(void 0, controller)) {
+  if (_chunkTPOT575Pcjs.hasVariantCommands.call(void 0, controller)) {
     const SET = { type: "string", description: "Component set, or one of its variants (default: the selection\u2019s set)." };
     const VARIANT = { type: "string", description: "Variant id (default: the first selected variant)." };
     const VALUES = { type: "object", additionalProperties: { type: "string" }, description: 'Variant property \u2192 value, e.g. { "Size": "Medium" }.' };