@pixerate/editor 0.14.1 → 0.14.3

package/README.md

@@ -0,0 +1,108 @@
+# @pixerate/editor
+
+UI-agnostic core of the Pixerate editor toolkit: a prompt-template grammar with recursive resolution and sourcemaps, plain-text and markdown serializers, headless [TipTap](https://tiptap.dev) extensions, and framework-free controllers for rich text, spreadsheets, images and node-graph canvases.
+
+Framework bindings: [`@pixerate/editor-react`](https://www.npmjs.com/package/@pixerate/editor-react) · [`@pixerate/editor-svelte`](https://www.npmjs.com/package/@pixerate/editor-svelte)
+
+```bash
+npm install @pixerate/editor
+```
+
+## Prompt grammar
+
+Prompts use three token types:
+
+| Syntax | Token | Example |
+| :--- | :--- | :--- |
+| `{{name}}` | template, replaced by its body (recursively) | `{{golden_hour}}` |
+| `{variable}` | variable, filled from a values map | `{subject}` |
+| `__instruction__` | instruction, a styled directive for the model | `__award_winning__` |
+
+```ts
+import {
+  tokenizePrompt,
+  resolveTemplates,
+  resolveVariables,
+  resolveTemplatesWithMapping,
+  mapResolvedOffsetToRaw,
+  TEMPLATE_LOOP_ERROR,
+} from "@pixerate/editor/grammar";
+
+const templates = [
+  { name: "mood", body: "cinematic cyber-noir" },
+  { name: "scene", body: "rainy street, {{mood}}" },
+];
+
+tokenizePrompt("Shot of {{scene}} with {subject}");
+// [{ type: "text", … }, { type: "template", value: "scene", start: 8, end: 17, … }, …]
+
+resolveTemplates("Shot of {{scene}}", templates);
+// "Shot of rainy street, cinematic cyber-noir"
+
+resolveVariables("Hello {user}", { user: "Ada" }); // "Hello Ada"
+
+// Map offsets in the resolved text back to the source (for error highlighting, carets, …)
+const { text, map } = resolveTemplatesWithMapping("Shot of {{scene}}", templates);
+mapResolvedOffsetToRaw(text.length, map); // 17, the end of "{{scene}}"
+```
+
+- **Cycles and depth.** A tag that would recurse into itself is replaced with `TEMPLATE_LOOP_ERROR` (`"[Template loop detected]"`), and tags nested deeper than `maxDepth` (default `10`) with `TEMPLATE_DEPTH_ERROR`. The rest of the prompt still resolves, so check with `result.includes(TEMPLATE_LOOP_ERROR)`.
+- **Versions.** Templates may carry `versions` and `latestVersion`. Pin specific versions with `resolveTemplates(text, templates, { bindings: { name: "v1" } })`.
+
+## Serializers
+
+```ts
+import {
+  plainTextToTipTapHtml,
+  htmlToPlainText,
+  getEditorText,
+  markdownToTipTapHtml,
+  getEditorMarkdown,
+  extractMentionsFromDoc,
+} from "@pixerate/editor/serializers";
+```
+
+- `plainTextToTipTapHtml` / `htmlToPlainText` round-trip multi-line plain text through TipTap paragraphs without leaking HTML.
+- `markdownToTipTapHtml` renders markdown for TipTap. Raw HTML embedded in the markdown is sanitized against an allowlist (event handlers, `style` and `javascript:` URLs are removed). Pass `{ allowUnsafeHtml: true }` only for fully trusted input.
+
+## Editor controller and extensions
+
+`createEditor` wraps a TipTap `Editor` with plain-text / markdown modes, token callbacks and dirty tracking. It works with any view layer, or with none.
+
+```ts
+import { createEditor, createRichTextPreset, GradientText } from "@pixerate/editor";
+
+const controller = createEditor({
+  element: document.querySelector("#editor"),
+  plainTextMode: true,
+  content: "A photo of {subject} in {{golden_hour}}",
+  extensions: [...createRichTextPreset(), GradientText],
+  onTokensChange: (tokens) => console.log(tokens),
+});
+
+controller.insertText("__award_winning__ "); // at the selection; literal text, never parsed as HTML
+controller.isDirty(); // true
+```
+
+Extensions (`@pixerate/editor/extensions`): `createRichTextPreset`, `GradientText`, `TemplateSuggestions`, `SlashCommands`, `LoadingNode`, `Mention` / `createMentionExtension`, `Image`, `Markdown`, `SmilieReplacer`, `ColorHighlighter`, `FontSize`.
+
+## Other modules
+
+Each module is also available as a subpath import:
+
+| Import | Contents |
+| :--- | :--- |
+| `@pixerate/editor/grammar` | Tokenizer, resolver, sourcemaps. No TipTap or DOM dependencies, so it is safe for Node.js, workers and serverless functions. |
+| `@pixerate/editor/serializers` | Plain text, markdown and mention serializers |
+| `@pixerate/editor/extensions` | Headless TipTap extensions |
+| `@pixerate/editor/history` | `HistoryManager`: a command-pattern undo/redo stack |
+| `@pixerate/editor/spreadsheet` | `SpreadsheetController`, formula parser/evaluator and dependency graph |
+| `@pixerate/editor/image-editor` | `ImageEditorController` and Canvas 2D renderer: crop, adjustments, annotations, depth masks and AI hooks. Needs a DOM/canvas environment. |
+| `@pixerate/editor/canvas` | Node-graph layout (dagre), placement, trajectories, displacement, clipboard and streaming layout helpers |
+| `@pixerate/editor/agent` | MCP tool schemas and a planner for agent-driven canvas edits |
+
+The root entry (`@pixerate/editor`) re-exports everything, including TipTap. In backends, import from `@pixerate/editor/grammar` to keep the dependency graph small.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -2698,6 +2698,114 @@ md2.validateLink = (url) => {
   }
   return defaultValidateLink.call(md2, url);
 };
+var ALLOWED_HTML_TAGS = /* @__PURE__ */ new Set([
+  "a",
+  "abbr",
+  "b",
+  "blockquote",
+  "br",
+  "code",
+  "del",
+  "details",
+  "div",
+  "em",
+  "h1",
+  "h2",
+  "h3",
+  "h4",
+  "h5",
+  "h6",
+  "hr",
+  "i",
+  "img",
+  "input",
+  "kbd",
+  "li",
+  "mark",
+  "ol",
+  "p",
+  "pre",
+  "s",
+  "span",
+  "strong",
+  "sub",
+  "summary",
+  "sup",
+  "table",
+  "tbody",
+  "td",
+  "tfoot",
+  "th",
+  "thead",
+  "tr",
+  "u",
+  "ul"
+]);
+var ALLOWED_HTML_ATTRS = /* @__PURE__ */ new Set([
+  "alt",
+  "align",
+  "checked",
+  "class",
+  "colspan",
+  "disabled",
+  "height",
+  "href",
+  "rel",
+  "rowspan",
+  "src",
+  "start",
+  "target",
+  "title",
+  "type",
+  "width"
+]);
+var HTML_TAG_REGEX = /<(\/?)([a-zA-Z][a-zA-Z0-9-]*)((?:\s+[^\s"'>\/=]+(?:\s*=\s*(?:"[^"]*"|'[^']*'|[^\s"'=<>`]+))?)*)\s*\/?>/g;
+var HTML_ATTR_REGEX = /([^\s"'>\/=]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+)))?/g;
+function sanitizeTag(tagText, isClosing, rawTagName, rawAttrs) {
+  const tagName = rawTagName.toLowerCase();
+  if (!ALLOWED_HTML_TAGS.has(tagName)) return escapeHtml(tagText);
+  if (isClosing) return `</${tagName}>`;
+  if (tagName === "input" && !/\stype\s*=\s*["']?checkbox["']?[\s>/]/i.test(tagText)) {
+    return escapeHtml(tagText);
+  }
+  let attrs = "";
+  let attrMatch;
+  HTML_ATTR_REGEX.lastIndex = 0;
+  while ((attrMatch = HTML_ATTR_REGEX.exec(rawAttrs)) !== null) {
+    const name = attrMatch[1].toLowerCase();
+    if (!ALLOWED_HTML_ATTRS.has(name) && !/^data-[a-z0-9_.-]+$/.test(name)) {
+      continue;
+    }
+    const rawValue = attrMatch[2] ?? attrMatch[3] ?? attrMatch[4];
+    if (rawValue === void 0) {
+      attrs += ` ${name}`;
+      continue;
+    }
+    const value = md2.utils.unescapeAll(rawValue);
+    if ((name === "href" || name === "src") && // Browsers ignore control characters and whitespace inside schemes.
+    !md2.validateLink(value.replace(/[\u0000-\u0020\u007f]/g, ""))) {
+      continue;
+    }
+    attrs += ` ${name}="${escapeHtml(value)}"`;
+  }
+  return `<${tagName}${attrs}>`;
+}
+function sanitizeEmbeddedHtml(html) {
+  let result = "";
+  let lastIndex = 0;
+  let match;
+  HTML_TAG_REGEX.lastIndex = 0;
+  while ((match = HTML_TAG_REGEX.exec(html)) !== null) {
+    result += html.slice(lastIndex, match.index).replace(/</g, "&lt;");
+    result += sanitizeTag(match[0], match[1], match[2], match[3]);
+    lastIndex = match.index + match[0].length;
+  }
+  return result + html.slice(lastIndex).replace(/</g, "&lt;");
+}
+var defaultHtmlInline = md2.renderer.rules.html_inline;
+var defaultHtmlBlock = md2.renderer.rules.html_block;
+md2.renderer.rules.html_inline = (tokens, idx, options, env, self) => env?.allowUnsafeHtml ? defaultHtmlInline(tokens, idx, options, env, self) : sanitizeEmbeddedHtml(tokens[idx].content);
+md2.renderer.rules.html_block = (tokens, idx, options, env, self) => env?.allowUnsafeHtml ? defaultHtmlBlock(tokens, idx, options, env, self) : sanitizeEmbeddedHtml(tokens[idx].content);
 function preprocessMarkdownFileLinks(content) {
   if (!content) return "";
   return content.replace(
@@ -2705,8 +2813,8 @@ function preprocessMarkdownFileLinks(content) {
     (_match, rawLabel, href) => {
       const trimmed = rawLabel.trim();
       const codeMatch = trimmed.match(/^`([^`]+)`$/);
-      const labelContent = codeMatch ? `<code>${codeMatch[1]}</code>` : trimmed;
-      return `<a href="${href}" data-file-link="true" title="Click to copy file path">${labelContent}</a>`;
+      const labelContent = codeMatch ? `<code>${escapeHtml(codeMatch[1])}</code>` : escapeHtml(trimmed);
+      return `<a href="${escapeHtml(href)}" data-file-link="true" title="Click to copy file path">${labelContent}</a>`;
     }
   );
 }
@@ -2722,7 +2830,7 @@ function markdownToTipTapHtml(markdown, options) {
     };
     content = preprocessMarkdownMentions(content, mentionOpts);
   }
-  return md2.render(content);
+  return md2.render(content, { allowUnsafeHtml: options?.allowUnsafeHtml });
 }
 function getEditorMarkdown(editor) {
   if (!editor) return "";