@pixerate/editor 0.152.0 → 0.154.0

package/dist/spreadsheet/index.js

@@ -46,6 +46,7 @@ import {
   copySheetName,
   createConditionalFormatRule,
   createSpreadsheetClipboardData,
+  createSpreadsheetEditorDocument,
   csvImportAdapter,
   defaultIconThresholds,
   deleteSheetInFormula,
@@ -125,7 +126,7 @@ import {
   validateCellInput,
   validateDefinedName,
   validateSheetName
-} from "../chunk-VGJTUCWM.js";
+} from "../chunk-4J4MC3F5.js";
 import {
   FormulaEvaluator,
   FormulaLambda,
@@ -197,6 +198,9 @@ import {
   serializeCsv,
   serializeTsv
 } from "../chunk-WJSD3MAZ.js";
+import "../chunk-GNV54DLO.js";
+import "../chunk-WHKNYFM2.js";
+import "../chunk-HF5QZS7Z.js";
 export {
   CONDITIONAL_FORMAT_ICON_SETS,
   CONDITIONAL_FORMAT_PRESETS,
@@ -264,6 +268,7 @@ export {
   copySheetName,
   createConditionalFormatRule,
   createSpreadsheetClipboardData,
+  createSpreadsheetEditorDocument,
   csvImportAdapter,
   dateValueToSerial,
   defaultIconThresholds,

package/dist/tokens/editorDocument.d.cts

@@ -0,0 +1,10 @@
+import { type EditorDocument } from '../persistence/editorDocument.cjs';
+import type { TokenState } from './types.cjs';
+import type { TokenStore } from './store.cjs';
+/**
+ * The save / load / undo contract for a `TokenStore` (kind `tokens`, document: the
+ * `TokenState` of collections, modes and variables). A recorded load (agents) is one undo step
+ * and refuses a state with any problem; opening a file (`history: "reset"`) keeps what
+ * `parseTokenState` can read and reports the rest in the `LoadReport`.
+ */
+export declare function createTokensEditorDocument(store: TokenStore): EditorDocument<TokenState>;

package/dist/tokens/editorDocument.d.ts

@@ -0,0 +1,10 @@
+import { type EditorDocument } from '../persistence/editorDocument.js';
+import type { TokenState } from './types.js';
+import type { TokenStore } from './store.js';
+/**
+ * The save / load / undo contract for a `TokenStore` (kind `tokens`, document: the
+ * `TokenState` of collections, modes and variables). A recorded load (agents) is one undo step
+ * and refuses a state with any problem; opening a file (`history: "reset"`) keeps what
+ * `parseTokenState` can read and reports the rest in the `LoadReport`.
+ */
+export declare function createTokensEditorDocument(store: TokenStore): EditorDocument<TokenState>;

package/dist/tokens/index.cjs

@@ -51,7 +51,11 @@
 
 
 
-var _chunk2ZO4RSDScjs = require('../chunk-2ZO4RSDS.cjs');
+
+var _chunkHVX35M2Icjs = require('../chunk-HVX35M2I.cjs');
+require('../chunk-5H2C3QSF.cjs');
+require('../chunk-L5OWG2NA.cjs');
+require('../chunk-2BSBFBOA.cjs');
 
 
 
@@ -113,4 +117,5 @@ var _chunkA6QWKBJPcjs = require('../chunk-A6QWKBJP.cjs');
 
 
 
-exports.EMPTY_TOKEN_STATE = _chunk2ZO4RSDScjs.EMPTY_TOKEN_STATE; exports.TOKEN_SCOPES_BY_TYPE = _chunk2ZO4RSDScjs.TOKEN_SCOPES_BY_TYPE; exports.TOKEN_TYPES = _chunk2ZO4RSDScjs.TOKEN_TYPES; exports.TokenError = _chunk2ZO4RSDScjs.TokenError; exports.TokenStore = _chunk2ZO4RSDScjs.TokenStore; exports.W3C_TOKENS_EXTENSION = _chunk2ZO4RSDScjs.W3C_TOKENS_EXTENSION; exports.addTokenMode = _chunk2ZO4RSDScjs.addTokenMode; exports.checkTokenAlias = _chunk2ZO4RSDScjs.checkTokenAlias; exports.coerceTokenLiteral = _chunk2ZO4RSDScjs.coerceTokenLiteral; exports.createTokenCollection = _chunk2ZO4RSDScjs.createTokenCollection; exports.createTokenStore = _chunk2ZO4RSDScjs.createTokenStore; exports.createTokenVariable = _chunk2ZO4RSDScjs.createTokenVariable; exports.cssString = _chunk2ZO4RSDScjs.cssString; exports.defaultTokenId = _chunk2ZO4RSDScjs.defaultTokenId; exports.defaultTokenValue = _chunk2ZO4RSDScjs.defaultTokenValue; exports.deleteTokenCollection = _chunk2ZO4RSDScjs.deleteTokenCollection; exports.deleteTokenVariables = _chunk2ZO4RSDScjs.deleteTokenVariables; exports.exportTokensCss = _chunk2ZO4RSDScjs.exportTokensCss; exports.exportW3CTokens = _chunk2ZO4RSDScjs.exportW3CTokens; exports.exportW3CTokensJson = _chunk2ZO4RSDScjs.exportW3CTokensJson; exports.findTokenCollection = _chunk2ZO4RSDScjs.findTokenCollection; exports.findTokenMode = _chunk2ZO4RSDScjs.findTokenMode; exports.findTokenVariable = _chunk2ZO4RSDScjs.findTokenVariable; exports.formatTokenCssValue = _chunk2ZO4RSDScjs.formatTokenCssValue; exports.formatTokenValue = _chunk2ZO4RSDScjs.formatTokenValue; exports.getCollectionVariables = _chunk2ZO4RSDScjs.getCollectionVariables; exports.getCurrentMode = _chunk2ZO4RSDScjs.getCurrentMode; exports.getDefaultMode = _chunk2ZO4RSDScjs.getDefaultMode; exports.getTokenCollection = _chunk2ZO4RSDScjs.getTokenCollection; exports.getTokenCssName = _chunk2ZO4RSDScjs.getTokenCssName; exports.getTokenCssVariables = _chunk2ZO4RSDScjs.getTokenCssVariables; exports.getTokenVariable = _chunk2ZO4RSDScjs.getTokenVariable; exports.hexToRgba = _chunkA6QWKBJPcjs.hexToRgba; exports.importW3CTokens = _chunk2ZO4RSDScjs.importW3CTokens; exports.isTokenAlias = _chunk2ZO4RSDScjs.isTokenAlias; exports.isTokenInScope = _chunk2ZO4RSDScjs.isTokenInScope; exports.isTokenScopeKnown = _chunk2ZO4RSDScjs.isTokenScopeKnown; exports.literalTokenType = _chunk2ZO4RSDScjs.literalTokenType; exports.moveTokenMode = _chunk2ZO4RSDScjs.moveTokenMode; exports.normalizeTokenColor = _chunkA6QWKBJPcjs.normalizeTokenColor; exports.normalizeTokenName = _chunk2ZO4RSDScjs.normalizeTokenName; exports.normalizeTokenScopes = _chunk2ZO4RSDScjs.normalizeTokenScopes; exports.parseTokenState = _chunk2ZO4RSDScjs.parseTokenState; exports.prepareTokenValue = _chunk2ZO4RSDScjs.prepareTokenValue; exports.removeTokenMode = _chunk2ZO4RSDScjs.removeTokenMode; exports.renameTokenCollection = _chunk2ZO4RSDScjs.renameTokenCollection; exports.renameTokenMode = _chunk2ZO4RSDScjs.renameTokenMode; exports.renameTokenVariable = _chunk2ZO4RSDScjs.renameTokenVariable; exports.resolveToken = _chunk2ZO4RSDScjs.resolveToken; exports.resolveTokenInMode = _chunk2ZO4RSDScjs.resolveTokenInMode; exports.resolveTokenValue = _chunk2ZO4RSDScjs.resolveTokenValue; exports.rgbaToHex = _chunkA6QWKBJPcjs.rgbaToHex; exports.setTokenValue = _chunk2ZO4RSDScjs.setTokenValue; exports.tokenSlug = _chunk2ZO4RSDScjs.tokenSlug; exports.updateTokenVariable = _chunk2ZO4RSDScjs.updateTokenVariable;
+
+exports.EMPTY_TOKEN_STATE = _chunkHVX35M2Icjs.EMPTY_TOKEN_STATE; exports.TOKEN_SCOPES_BY_TYPE = _chunkHVX35M2Icjs.TOKEN_SCOPES_BY_TYPE; exports.TOKEN_TYPES = _chunkHVX35M2Icjs.TOKEN_TYPES; exports.TokenError = _chunkHVX35M2Icjs.TokenError; exports.TokenStore = _chunkHVX35M2Icjs.TokenStore; exports.W3C_TOKENS_EXTENSION = _chunkHVX35M2Icjs.W3C_TOKENS_EXTENSION; exports.addTokenMode = _chunkHVX35M2Icjs.addTokenMode; exports.checkTokenAlias = _chunkHVX35M2Icjs.checkTokenAlias; exports.coerceTokenLiteral = _chunkHVX35M2Icjs.coerceTokenLiteral; exports.createTokenCollection = _chunkHVX35M2Icjs.createTokenCollection; exports.createTokenStore = _chunkHVX35M2Icjs.createTokenStore; exports.createTokenVariable = _chunkHVX35M2Icjs.createTokenVariable; exports.createTokensEditorDocument = _chunkHVX35M2Icjs.createTokensEditorDocument; exports.cssString = _chunkHVX35M2Icjs.cssString; exports.defaultTokenId = _chunkHVX35M2Icjs.defaultTokenId; exports.defaultTokenValue = _chunkHVX35M2Icjs.defaultTokenValue; exports.deleteTokenCollection = _chunkHVX35M2Icjs.deleteTokenCollection; exports.deleteTokenVariables = _chunkHVX35M2Icjs.deleteTokenVariables; exports.exportTokensCss = _chunkHVX35M2Icjs.exportTokensCss; exports.exportW3CTokens = _chunkHVX35M2Icjs.exportW3CTokens; exports.exportW3CTokensJson = _chunkHVX35M2Icjs.exportW3CTokensJson; exports.findTokenCollection = _chunkHVX35M2Icjs.findTokenCollection; exports.findTokenMode = _chunkHVX35M2Icjs.findTokenMode; exports.findTokenVariable = _chunkHVX35M2Icjs.findTokenVariable; exports.formatTokenCssValue = _chunkHVX35M2Icjs.formatTokenCssValue; exports.formatTokenValue = _chunkHVX35M2Icjs.formatTokenValue; exports.getCollectionVariables = _chunkHVX35M2Icjs.getCollectionVariables; exports.getCurrentMode = _chunkHVX35M2Icjs.getCurrentMode; exports.getDefaultMode = _chunkHVX35M2Icjs.getDefaultMode; exports.getTokenCollection = _chunkHVX35M2Icjs.getTokenCollection; exports.getTokenCssName = _chunkHVX35M2Icjs.getTokenCssName; exports.getTokenCssVariables = _chunkHVX35M2Icjs.getTokenCssVariables; exports.getTokenVariable = _chunkHVX35M2Icjs.getTokenVariable; exports.hexToRgba = _chunkA6QWKBJPcjs.hexToRgba; exports.importW3CTokens = _chunkHVX35M2Icjs.importW3CTokens; exports.isTokenAlias = _chunkHVX35M2Icjs.isTokenAlias; exports.isTokenInScope = _chunkHVX35M2Icjs.isTokenInScope; exports.isTokenScopeKnown = _chunkHVX35M2Icjs.isTokenScopeKnown; exports.literalTokenType = _chunkHVX35M2Icjs.literalTokenType; exports.moveTokenMode = _chunkHVX35M2Icjs.moveTokenMode; exports.normalizeTokenColor = _chunkA6QWKBJPcjs.normalizeTokenColor; exports.normalizeTokenName = _chunkHVX35M2Icjs.normalizeTokenName; exports.normalizeTokenScopes = _chunkHVX35M2Icjs.normalizeTokenScopes; exports.parseTokenState = _chunkHVX35M2Icjs.parseTokenState; exports.prepareTokenValue = _chunkHVX35M2Icjs.prepareTokenValue; exports.removeTokenMode = _chunkHVX35M2Icjs.removeTokenMode; exports.renameTokenCollection = _chunkHVX35M2Icjs.renameTokenCollection; exports.renameTokenMode = _chunkHVX35M2Icjs.renameTokenMode; exports.renameTokenVariable = _chunkHVX35M2Icjs.renameTokenVariable; exports.resolveToken = _chunkHVX35M2Icjs.resolveToken; exports.resolveTokenInMode = _chunkHVX35M2Icjs.resolveTokenInMode; exports.resolveTokenValue = _chunkHVX35M2Icjs.resolveTokenValue; exports.rgbaToHex = _chunkA6QWKBJPcjs.rgbaToHex; exports.setTokenValue = _chunkHVX35M2Icjs.setTokenValue; exports.tokenSlug = _chunkHVX35M2Icjs.tokenSlug; exports.updateTokenVariable = _chunkHVX35M2Icjs.updateTokenVariable;

package/dist/tokens/index.d.cts

@@ -9,3 +9,4 @@ export * from './model.cjs';
 export * from './store.cjs';
 export * from './css.cjs';
 export * from './w3c.cjs';
+export * from './editorDocument.cjs';

package/dist/tokens/index.d.ts

@@ -9,3 +9,4 @@ export * from './model.js';
 export * from './store.js';
 export * from './css.js';
 export * from './w3c.js';
+export * from './editorDocument.js';

package/dist/tokens/index.js

@@ -11,6 +11,7 @@ import {
   createTokenCollection,
   createTokenStore,
   createTokenVariable,
+  createTokensEditorDocument,
   cssString,
   defaultTokenId,
   defaultTokenValue,
@@ -51,7 +52,10 @@ import {
   setTokenValue,
   tokenSlug,
   updateTokenVariable
-} from "../chunk-LFKLA7RC.js";
+} from "../chunk-BCY22GBH.js";
+import "../chunk-GNV54DLO.js";
+import "../chunk-WHKNYFM2.js";
+import "../chunk-HF5QZS7Z.js";
 import {
   hexToRgba,
   normalizeTokenColor,
@@ -70,6 +74,7 @@ export {
   createTokenCollection,
   createTokenStore,
   createTokenVariable,
+  createTokensEditorDocument,
   cssString,
   defaultTokenId,
   defaultTokenValue,

package/dist/vector/index.cjs

@@ -41,9 +41,6 @@ var _chunkQT26RHKKcjs = require('../chunk-QT26RHKK.cjs');
 var _chunkLIXLD433cjs = require('../chunk-LIXLD433.cjs');
 
 
-var _chunk5H2C3QSFcjs = require('../chunk-5H2C3QSF.cjs');
-
-
 
 
 
@@ -515,7 +512,6 @@ require('../chunk-BXMIBMVG.cjs');
 
 
 var _chunkCVFAAZXEcjs = require('../chunk-CVFAAZXE.cjs');
-require('../chunk-L5OWG2NA.cjs');
 
 
 
@@ -562,6 +558,10 @@ var _chunkCWM3CUUXcjs = require('../chunk-CWM3CUUX.cjs');
 var _chunkXFM3OCHUcjs = require('../chunk-XFM3OCHU.cjs');
 require('../chunk-NIBFDFYW.cjs');
 require('../chunk-UWEQ55MY.cjs');
+
+
+var _chunk5H2C3QSFcjs = require('../chunk-5H2C3QSF.cjs');
+require('../chunk-L5OWG2NA.cjs');
 require('../chunk-2BSBFBOA.cjs');
 
 

package/dist/vector/index.js

@@ -39,9 +39,6 @@ import {
   subpathToMorphContour,
   turnMorphContour
 } from "../chunk-UILRJQFD.js";
-import {
-  defineEditorDocument
-} from "../chunk-GNV54DLO.js";
 import {
   DEFAULT_VECTOR_FONT,
   IDENTITY_MATRIX,
@@ -515,7 +512,6 @@ import "../chunk-ORDXMBD4.js";
 import {
   createProvenance
 } from "../chunk-M6DNZNVY.js";
-import "../chunk-WHKNYFM2.js";
 import {
   bezierPathBounds,
   bezierPathToSvg,
@@ -562,6 +558,10 @@ import {
 } from "../chunk-QGHEDC7B.js";
 import "../chunk-SIFAIGB3.js";
 import "../chunk-VDGBHYC7.js";
+import {
+  defineEditorDocument
+} from "../chunk-GNV54DLO.js";
+import "../chunk-WHKNYFM2.js";
 import "../chunk-HF5QZS7Z.js";
 import {
   HistoryManager

package/dist/video-editor/index.cjs

@@ -141,14 +141,14 @@ require('../chunk-PY4GWSE2.cjs');
 var _chunkEBDZWIOPcjs = require('../chunk-EBDZWIOP.cjs');
 
 
-var _chunk5H2C3QSFcjs = require('../chunk-5H2C3QSF.cjs');
-require('../chunk-L5OWG2NA.cjs');
-
-
 
 
 var _chunkRUZQMYXHcjs = require('../chunk-RUZQMYXH.cjs');
 require('../chunk-WOFXZ3XU.cjs');
+
+
+var _chunk5H2C3QSFcjs = require('../chunk-5H2C3QSF.cjs');
+require('../chunk-L5OWG2NA.cjs');
 require('../chunk-2BSBFBOA.cjs');
 
 

package/dist/video-editor/index.js

@@ -139,16 +139,16 @@ import "../chunk-EHLOCVWB.js";
 import {
   namedWithSuggestion
 } from "../chunk-W4KFNAWC.js";
-import {
-  defineEditorDocument
-} from "../chunk-GNV54DLO.js";
-import "../chunk-WHKNYFM2.js";
 import {
   EffectsSlot,
   createEffectToolProvider,
   isEffectError
 } from "../chunk-7KWJEYIK.js";
 import "../chunk-V2ZCJRDM.js";
+import {
+  defineEditorDocument
+} from "../chunk-GNV54DLO.js";
+import "../chunk-WHKNYFM2.js";
 import "../chunk-HF5QZS7Z.js";
 import {
   HistoryManager

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixerate/editor",
-  "version": "0.152.0",
+  "version": "0.154.0",
   "description": "UI-agnostic rich text and media editing core library",
   "author": "Pixerate",
   "license": "MIT",

package/skills/README.md

@@ -20,6 +20,7 @@ that uses the tools can load the matching skill.
 | [`pixerate-video-editor`](pixerate-video-editor/SKILL.md) | Non-linear video editing: tracks, clips, transitions, export. |
 | [`pixerate-generation`](pixerate-generation/SKILL.md) | Planning, estimating and running paid media generation. |
 | [`pixerate-parameters`](pixerate-parameters/SKILL.md) | Effect parameters, presets and keyframes. |
+| [`pixerate-tokens`](pixerate-tokens/SKILL.md) | Design tokens: collections, modes, variables and aliases, through the whole-set document tools. |
 | [`pixerate-effect-authoring`](pixerate-effect-authoring/SKILL.md) | Authoring shaders and procedural effects: inspecting parameters and source code, setting values and presets, keyframing animation tracks, playback timing, and previewing. |
 | [`pixerate-color`](pixerate-color/SKILL.md) | Colour inspection, WCAG accessibility and contrast optimization, CVD simulation, palette audits, harmonies, and OKLab/OKLCH blends. |
 

package/skills/pixerate-canvas/SKILL.md

@@ -130,6 +130,20 @@ the reason (for example a variant combination that already exists, or a cycle).
 | `rename_variant_property` | Rename property `name` to `newName` across a set; instances keep their variant. |
 | `rename_variant_value` | Rename `value` of `property` to `newValue` across a set; instances keep their variant. |
 
+### Save and open
+
+The host may add the shared document tools (see `pixerate-agent-tools`). A canvas document is `{ nodes, edges, scenes }`: every node (`id`, `position`, `data`, `type`, `parentId`...) and edge without selection or measurement, plus the saved scenes.
+
+| Tool | Use |
+| --- | --- |
+| `get_canvas_document` | Take a copy of the whole canvas as `{ kind, formatVersion, revision, document }` before a risky rewrite, or to hand it on. To read the canvas, use `get_editor_state`: it is smaller and says more. Refuses very large canvases. |
+| `load_canvas_document` | Put back a copy from `get_canvas_document` (its `document`, or the whole result). Checked first: duplicate ids, edges to missing nodes and parents that do not exist are refused and nothing changes. One undo step (`undo_canvas` brings the previous canvas back). To add or change a few nodes use `canvas_add_node` / `canvas_update_node`. |
+| `undo_canvas` | Undo the last canvas change (one tool call, command or user gesture such as a drag). Returns `undone` (the step's name) and whether more can be undone. Fails with "Nothing to undo." when there is nothing. |
+| `redo_canvas` | Redo the last undone canvas change. |
+| `save_canvas_document` | Save the canvas under a `name` in the host's storage (the same name replaces that copy). Returns the `key`. Only listed when the host has storage. Save when the user asks, not after every edit. |
+| `list_saved_canvas_documents` | List saved canvases (`key`, `name`, `savedAt`), newest first. |
+| `open_saved_canvas_document` | Replace the canvas with a saved one by `key`. One undo step. Ask before opening over changes the user has not saved. |
+
 ## Commands
 
 Run these through `run_command` / `run_commands`. Each takes `ids` (default: the selection) unless

package/skills/pixerate-rich-text/SKILL.md

@@ -106,6 +106,20 @@ Errors, namespacing (`doc-1__find_text`) and `run_commands` batching are covered
 | `prompt_set_variable` | Set the value of a template variable (`name` without braces, `value` any JSON value). Prefer this over editing the prompt text when only a slot's value changes. |
 | `prompt_select` | Select prompt text between two positions (`from === to` places the cursor), e.g. to show the user what you changed. |
 
+### Save and open
+
+The host may add the shared document tools (see `pixerate-agent-tools`). A rich text document is the editor's ProseMirror JSON (`{ "type": "doc", "content": [...] }`), with marks such as tracked changes and comment anchors; comment threads stay in their own store.
+
+| Tool | Use |
+| --- | --- |
+| `get_rich_text_document` | Take a copy of the whole document as `{ kind, formatVersion, revision, document }` before a risky rewrite, or to hand it on. To read the document, use `get_text`: it is smaller and says more. Refuses very large documents. |
+| `load_rich_text_document` | Put back a copy from `get_rich_text_document` (its `document`, or the whole result). Checked first: when anything is wrong nothing changes and the error says what. One undo step (`undo_rich_text` brings the previous document back). Refused while the document is read-only. To change text use `replace_range`, `replace_text` or `insert_text`: they keep formatting and comments. |
+| `undo_rich_text` | Undo the last document edit (one tool call or one user gesture). Returns `undone` (the step's name, when it has one) and whether more can be undone. Fails with "Nothing to undo." when there is nothing. |
+| `redo_rich_text` | Redo the last undone document edit. |
+| `save_rich_text_document` | Save the document under a `name` in the host's storage (the same name replaces that copy). Returns the `key`. Only listed when the host has storage. Save when the user asks, not after every edit. |
+| `list_saved_rich_text_documents` | List saved documents (`key`, `name`, `savedAt`), newest first. |
+| `open_saved_rich_text_document` | Replace the document with a saved one by `key`. One undo step. Ask before opening over changes the user has not saved. |
+
 ## Commands
 
 Run with `run_command` / `run_commands` when the host registers them. Check

package/skills/pixerate-spreadsheet/SKILL.md

@@ -107,6 +107,20 @@ cell was deleted), `#NAME?`, `#N/A` (lookup miss), `#NUM!`, `#CYCLE!` (circular
 | `unmerge_cells` | Split every merge touching a `range` (a single cell is enough) back into cells; the value stays top-left. Returns the ranges unmerged; fails when there are none (`get_range` lists them). Unmerge before sorting, filtering or transposing a region. |
 | `transpose_range` | Swap rows and columns of a `range` in place, anchored at its top-left (`A1:C2` becomes `A1:B3`), moving values, formulas and formats; formulas that pointed into the range follow their cells. Cells the new shape covers outside the old range are overwritten, so check that area is empty first. Refused across merges (unmerge first), read-only cells or spills. Returns the new range. |
 
+### Save and open
+
+The host may add the shared document tools (see `pixerate-agent-tools`). A spreadsheet document is the whole workbook: `{ sheets: [{ columns, rows, cells, ... }], activeSheetId, names }`; selection and editing state are not part of it.
+
+| Tool | Use |
+| --- | --- |
+| `get_spreadsheet_document` | Take a copy of the whole workbook as `{ kind, formatVersion, revision, document }` before a risky rewrite, or to hand it on. To read the workbook, use `get_range`: it is smaller and says more. Refuses very large documents. |
+| `load_spreadsheet_document` | Put back a copy from `get_spreadsheet_document` (its `document`, or the whole result). Checked first: when anything is wrong nothing changes and the error says what. One undo step (`undo_spreadsheet` brings the previous workbook back). To change cells use `set_range` or `set_cell`. |
+| `undo_spreadsheet` | Undo the last workbook edit (one tool call or one user gesture). Returns `undone` (the step's name, when it has one) and whether more can be undone. Fails with "Nothing to undo." when there is nothing. |
+| `redo_spreadsheet` | Redo the last undone workbook edit. |
+| `save_spreadsheet_document` | Save the workbook under a `name` in the host's storage (the same name replaces that copy). Returns the `key`. Only listed when the host has storage. Save when the user asks, not after every edit. |
+| `list_saved_spreadsheet_documents` | List saved workbooks (`key`, `name`, `savedAt`), newest first. |
+| `open_saved_spreadsheet_document` | Replace the workbook with a saved one by `key`. One undo step. Ask before opening over changes the user has not saved. |
+
 ## Commands
 
 Run with `run_command` when the host registers them. Merge, unmerge and transpose act on the

package/skills/pixerate-tokens/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: pixerate-tokens
+description: How to read and change Pixerate design tokens (collections of variables with a value per mode, such as Light and Dark, and aliases between variables) through the shared document tools - getting the whole token set, editing collections, modes, variables and aliases, loading it back as one undo step, undo and redo, and saving or opening named token sets. Use when token tools (get_tokens_document, load_tokens_document...) are available or the user asks to change design tokens, theme colours, spacing scales or light / dark modes.
+---
+
+# Design tokens
+
+A token set holds **collections** (for example "Colours" or "Spacing"), each with one or more
+**modes** ("Light" and "Dark", or "Mobile" and "Desktop"), and **variables** (`color`,
+`number`, `string` or `boolean`) with a value for each mode of their collection. A value can be
+an alias to another variable, so `button/background` can point at `brand/primary` and follow it.
+Hosts turn the set into CSS variables per mode (`exportTokensCss`) and W3C design-token JSON.
+
+There are no per-variable tools yet: read the whole set with `get_tokens_document`, change the
+JSON, and write it back with `load_tokens_document`. Read `pixerate-agent-tools` first for tool
+naming and errors.
+
+## Working method
+
+1. **Read.** `get_tokens_document`. Note collection, mode and variable ids: values are keyed by
+   mode id, and aliases name variable ids.
+2. **Change the copy.** Keep every id you are not deliberately removing. New ids must be unique
+   strings. Give every variable a value for every mode of its collection.
+3. **Write once.** `load_tokens_document` with the whole edited document. It is checked first: a
+   variable in a missing collection, a value for a missing mode or a broken alias is refused and
+   nothing changes. One load is one undo step.
+4. **Check.** Read the result's `revision`; if it did not change, nothing was different.
+
+## Best practices
+
+- Name variables by role, not value: `text/primary`, not `grey-900`. Use `/` for groups.
+- Put raw values in one primitives collection and point role variables at them with aliases,
+  so a theme change touches one place.
+- Keep modes for real alternatives (Light / Dark). Do not make a mode per brand colour.
+- Do not alias a variable to itself or in a cycle.
+
+## Save and open
+
+The host may add the shared document tools (see `pixerate-agent-tools`). A tokens document is the whole `TokenState`: `{ collections: [{ id, name, modes: [{ id, name }] }], variables: [{ id, collectionId, name, type, valuesByMode }] }`. A value is a literal for its type (`"#rrggbb"` colours, numbers, strings, booleans) or an alias `{ "alias": "<variable id>" }`.
+
+| Tool | Use |
+| --- | --- |
+| `get_tokens_document` | Take a copy of the whole token set as `{ kind, formatVersion, revision, document }` before a risky rewrite, or to hand it on. To read the token set, use `get_tokens_document`: it is smaller and says more. Refuses very large documents. |
+| `load_tokens_document` | Put back a copy from `get_tokens_document` (its `document`, or the whole result). Checked first: when anything is wrong nothing changes and the error says what. One undo step (`undo_tokens` brings the previous token set back). Use it for every change: read the document, edit the JSON, load it back. |
+| `undo_tokens` | Undo the last token set edit (one tool call or one user gesture). Returns `undone` (the step's name, when it has one) and whether more can be undone. Fails with "Nothing to undo." when there is nothing. |
+| `redo_tokens` | Redo the last undone token set edit. |
+| `save_tokens_document` | Save the token set under a `name` in the host's storage (the same name replaces that copy). Returns the `key`. Only listed when the host has storage. Save when the user asks, not after every edit. |
+| `list_saved_tokens_documents` | List saved token sets (`key`, `name`, `savedAt`), newest first. |
+| `open_saved_tokens_document` | Replace the token set with a saved one by `key`. One undo step. Ask before opening over changes the user has not saved. |
+
+## Pitfalls
+
+- Removing a variable that others alias leaves broken aliases: point them elsewhere in the same
+  load.
+- `load_tokens_document` replaces everything. Do not send a partial document: missing
+  collections and variables are deleted.