Editor Integration

SuperDocs identifies every block-level element in your document with a data-chunk-id attribute. Your editor must preserve those attributes across the round-trip — HTML in, editor model, HTML back out — for surgical edits to work.

This guide covers attribute preservation in a rich-text editor. For rendering inline diff overlays inside the editor, see Human-in-the-Loop → Rendering diffs inline in your editor. For streaming events, see SSE Streaming. If your product doesn’t have an editor — your AI agent is the consumer of SuperDocs, or you’re running server-side / batch — see Agent Tool Integration or Server Integration instead.

Why this matters

Every SuperDocs response returns HTML like this:

<h2 data-chunk-id="550e8400-e29b-41d4-a716-446655440000">Section 1</h2>
<p data-chunk-id="6a7b8c9d-e0f1-2345-6789-abcdef012345">…</p>

The data-chunk-id values are how the AI references specific sections when it proposes edits. When your app sends the document back on the next turn, those same IDs must still be on the same blocks. If they aren’t, the AI’s “edit Section 2” request lands on the wrong block — or nothing at all. The failure mode is silent. Most rich-text editors strip unknown HTML attributes by default when parsing input into their internal model, and/or don’t emit them when serialising back to HTML. Edits work intermittently on blocks whose tags happen to survive, and fail mysteriously on the rest. No error is thrown. A five-minute check now saves hours of debugging later.

The pattern, in plain English

Every editor integration follows the same three steps:

Parse incoming HTML from SuperDocs into your editor’s document model, preserving data-chunk-id on every block-level node.
Serialise the editor model back to HTML, preserving the same data-chunk-id attributes.
Render incoming final.updated_html and document_sync.content payloads by re-running step 1 against the new HTML.

The snippets below implement these three steps for the six most common editors. Pick the one matching your stack, paste it in, and verify the round-trip with the test at the bottom of this page.

Working snippets

Install the vanilla ProseMirror packages:

npm install prosemirror-state prosemirror-view prosemirror-model \
  prosemirror-schema-basic prosemirror-schema-list prosemirror-history \
  prosemirror-keymap prosemirror-commands

Your schema needs to do two things:

Add data-chunk-id as a preserved attribute on every standard block node (paragraph, heading, list, blockquote, code block, horizontal rule).
Register a wrapper node for <div data-chunk-id="…">…</div> elements. SuperDocs uses these wrappers when a single chunk spans multiple block elements (e.g. a heading plus the paragraphs that follow it). If your schema has no node that matches div[data-chunk-id], the parser will descend into the children, the wrapper’s data-chunk-id will be silently dropped, and any inline-diff or chunk-targeted edit referencing that ID will fail to render. The basic ProseMirror schema does not include a <div> node — you must add one.

// schema.ts
import { Schema, NodeSpec } from "prosemirror-model";
import { schema as basicSchema } from "prosemirror-schema-basic";
import { addListNodes } from "prosemirror-schema-list";

// TS note: prosemirror-model's ParseRule.getAttrs signature has shifted
// across versions. If your compiler complains about the parameter type,
// leave the signature alone and add `as HTMLElement` at the usage site —
// do not refactor the helper.
function withChunkId(spec: NodeSpec): NodeSpec {
  const attrs = { ...(spec.attrs ?? {}), "data-chunk-id": { default: null } };

  const parseDOM = (spec.parseDOM ?? []).map((rule) => ({
    ...rule,
    getAttrs: (node: string | HTMLElement) => {
      const base =
        typeof rule.getAttrs === "function"
          ? rule.getAttrs(node as HTMLElement) ?? {}
          : rule.attrs ?? {};
      if (typeof node === "string") return base;
      return { ...base, "data-chunk-id": node.getAttribute("data-chunk-id") };
    },
  }));

  const originalToDOM = spec.toDOM;
  const toDOM: NodeSpec["toDOM"] = originalToDOM
    ? (node) => {
        const out = originalToDOM(node);
        if (!Array.isArray(out)) return out;
        const [tag, maybeAttrs, ...rest] = out as [string, unknown, ...unknown[]];
        const chunkId = node.attrs["data-chunk-id"];
        if (!chunkId) return out;
        const isAttrs =
          maybeAttrs &&
          typeof maybeAttrs === "object" &&
          !Array.isArray(maybeAttrs) &&
          !(maybeAttrs as { nodeType?: unknown }).nodeType;
        return isAttrs
          ? [tag, { ...(maybeAttrs as Record<string, unknown>), "data-chunk-id": chunkId }, ...rest]
          : [tag, { "data-chunk-id": chunkId }, maybeAttrs, ...rest];
      }
    : undefined;

  return { ...spec, attrs, parseDOM, toDOM };
}

// Wrapper node for multi-element chunks: <div data-chunk-id="…">…</div>.
// Holds one or more block children; preserves the chunk-id on round-trip.
const chunkWrapperSpec: NodeSpec = {
  group: "block",
  content: "block+",
  attrs: { "data-chunk-id": { default: null } },
  parseDOM: [{
    tag: "div[data-chunk-id]",
    getAttrs: (node) =>
      typeof node === "string"
        ? {}
        : { "data-chunk-id": node.getAttribute("data-chunk-id") },
  }],
  toDOM: (node) => [
    "div",
    node.attrs["data-chunk-id"]
      ? { "data-chunk-id": node.attrs["data-chunk-id"] }
      : {},
    0,
  ],
};

let nodes = basicSchema.spec.nodes;
for (const name of ["paragraph", "blockquote", "heading", "horizontal_rule", "code_block"]) {
  const spec = nodes.get(name);
  if (spec) nodes = nodes.update(name, withChunkId(spec));
}
nodes = addListNodes(nodes, "paragraph block*", "block");
for (const name of ["ordered_list", "bullet_list", "list_item"]) {
  const spec = nodes.get(name);
  if (spec) nodes = nodes.update(name, withChunkId(spec));
}
nodes = nodes.addToEnd("chunk_wrapper", chunkWrapperSpec);

export const schema = new Schema({ nodes, marks: basicSchema.spec.marks });

Use this schema when creating your EditorState. Use DOMParser.fromSchema(schema).parse(htmlElement) to load SuperDocs HTML and DOMSerializer.fromSchema(schema).serializeFragment(doc.content) to serialise it back out.Where this slots in: typically inside a React / Vue / Svelte component that mounts ProseMirror via new EditorView(domNode, { state }). Expose two methods on a ref — getHtml() and setHtml(html) — so the chat panel can read the current document before each send and write the updated HTML after each final event.

Install TipTap:

npm install @tiptap/react @tiptap/starter-kit

You need two pieces:

A global-attribute extension that preserves data-chunk-id on every standard block node.
A wrapper Node for <div data-chunk-id="…">…</div> elements. SuperDocs uses these wrappers when a single chunk spans multiple block elements (e.g. a heading plus the paragraphs that follow it). TipTap’s StarterKit has no node that matches a <div>, so without this extra Node the wrapper’s data-chunk-id is silently dropped during parsing — and any inline-diff or chunk-targeted edit referencing that ID will fail to render.

// chunk-id-preserver.ts
import { Extension, Node } from "@tiptap/core";

export const ChunkIdPreserver = Extension.create({
  name: "chunkIdPreserver",
  addGlobalAttributes() {
    return [{
      types: [
        "paragraph",
        "heading",
        "blockquote",
        "bulletList",
        "orderedList",
        "listItem",
        "codeBlock",
        "horizontalRule",
      ],
      attributes: {
        "data-chunk-id": {
          default: null,
          parseHTML: (el) => el.getAttribute("data-chunk-id"),
          renderHTML: (attrs) =>
            attrs["data-chunk-id"]
              ? { "data-chunk-id": attrs["data-chunk-id"] }
              : {},
        },
      },
    }];
  },
});

// Wrapper Node for multi-element chunks: <div data-chunk-id="…">…</div>.
export const ChunkWrapper = Node.create({
  name: "chunkWrapper",
  group: "block",
  content: "block+",
  parseHTML() {
    return [{ tag: "div[data-chunk-id]" }];
  },
  renderHTML({ HTMLAttributes }) {
    return ["div", HTMLAttributes, 0];
  },
  addAttributes() {
    return {
      "data-chunk-id": {
        default: null,
        parseHTML: (el) => el.getAttribute("data-chunk-id"),
        renderHTML: (attrs) =>
          attrs["data-chunk-id"]
            ? { "data-chunk-id": attrs["data-chunk-id"] }
            : {},
      },
    };
  },
});

const editor = useEditor({
  extensions: [StarterKit, ChunkIdPreserver, ChunkWrapper],
  content: superDocsHtml,
});

Then editor.getHTML() returns the round-tripped HTML, and editor.commands.setContent(html, false) loads a new SuperDocs payload without breaking undo history.Where this slots in: anywhere you already use useEditor. If you use additional node extensions (tables, images, custom blocks), add their type names to the types array.

Install Slate:

npm install slate slate-react slate-history

Declare your element types with an optional data-chunk-id field and provide HTML serialisation helpers:

// slate-chunk-id.ts
import { Element as SlateElement, Descendant } from "slate";

export type ChunkedElement = SlateElement & {
  type: string;
  "data-chunk-id"?: string | null;
  children: { text: string }[];
};

// Render incoming SuperDocs HTML into Slate nodes.
export function fromHtml(html: string): ChunkedElement[] {
  const doc = new DOMParser().parseFromString(html, "text/html");
  return Array.from(doc.body.children).map((el) => ({
    type: el.tagName.toLowerCase(),
    "data-chunk-id": el.getAttribute("data-chunk-id"),
    children: [{ text: el.textContent ?? "" }],
  })) as ChunkedElement[];
}

// Serialise Slate nodes back to HTML, preserving data-chunk-id.
export function toHtml(nodes: ChunkedElement[]): string {
  return nodes
    .map((n) => {
      const id = n["data-chunk-id"] ? ` data-chunk-id="${n["data-chunk-id"]}"` : "";
      const tag = n.type ?? "p";
      const inner = n.children.map((c) => c.text ?? "").join("");
      return `<${tag}${id}>${inner}</${tag}>`;
    })
    .join("");
}

In your renderElement, pass data-chunk-id through on the outer DOM element:

function renderElement({ attributes, children, element }: RenderElementProps) {
  const chunkId = (element as ChunkedElement)["data-chunk-id"];
  const Tag = (element as ChunkedElement).type as keyof JSX.IntrinsicElements;
  return (
    <Tag {...attributes} data-chunk-id={chunkId ?? undefined}>
      {children}
    </Tag>
  );
}

Where this slots in: call fromHtml() whenever you receive a document_sync or final event, pass the result to Editor.withoutNormalizing or Transforms.insertNodes as appropriate, and call toHtml(editor.children) before every chat send.

Install Lexical:

npm install lexical @lexical/react @lexical/html

Lexical doesn’t have a first-class “preserve unknown attributes” feature — the cleanest pattern is a WeakMap that stores chunk IDs against nodes, with exportDOM overrides on the block node types you care about.

// chunk-id-store.ts
import { LexicalNode, ElementNode } from "lexical";
import { $generateNodesFromDOM, $generateHtmlFromNodes } from "@lexical/html";

const chunkIds = new WeakMap<LexicalNode, string>();

export const setChunkId = (node: LexicalNode, id: string | null) => {
  if (id) chunkIds.set(node, id);
  else chunkIds.delete(node);
};
export const getChunkId = (node: LexicalNode) => chunkIds.get(node) ?? null;

// Import: walk DOM + Lexical nodes in parallel and record chunk IDs.
export function importHtmlWithChunkIds(editor: any, html: string) {
  editor.update(() => {
    const doc = new DOMParser().parseFromString(html, "text/html");
    const nodes = $generateNodesFromDOM(editor, doc);
    const blocks = doc.body.querySelectorAll("[data-chunk-id]");
    blocks.forEach((el, i) => {
      const id = el.getAttribute("data-chunk-id");
      if (nodes[i] && id) setChunkId(nodes[i], id);
    });
    // Replace editor contents with nodes.
  });
}

// Export: generate HTML, then inject data-chunk-id back onto block elements.
export function exportHtmlWithChunkIds(editor: any, root: ElementNode): string {
  let html = "";
  editor.getEditorState().read(() => {
    html = $generateHtmlFromNodes(editor, null);
  });
  const doc = new DOMParser().parseFromString(`<body>${html}</body>`, "text/html");
  const blocks = doc.body.children;
  const children = root.getChildren();
  for (let i = 0; i < blocks.length && i < children.length; i++) {
    const id = getChunkId(children[i]);
    if (id) blocks[i].setAttribute("data-chunk-id", id);
  }
  return doc.body.innerHTML;
}

Where this slots in: call importHtmlWithChunkIds on document_sync and final, and exportHtmlWithChunkIds before every chat send. Lexical’s model makes this the most custom wiring of any editor on this page — verify the round-trip carefully with the test at the bottom.

Install Quill:

npm install quill

// quill-chunk-id.ts
import Quill from "quill";
const Parchment = Quill.import("parchment") as typeof import("parchment");

const ChunkIdAttributor = new Parchment.Attributor.Attribute(
  "data-chunk-id",
  "data-chunk-id",
  { scope: Parchment.Scope.BLOCK }
);
Quill.register(ChunkIdAttributor, true);

Load SuperDocs HTML via the clipboard API (Parchment preserves block attributes by default once the attributor is registered):

quill.clipboard.dangerouslyPasteHTML(superDocsHtml);

Read the round-tripped HTML with quill.root.innerHTML — data-chunk-id stays on every block.Where this slots in: register the attributor once at startup, before any editor is instantiated. Use clipboard.dangerouslyPasteHTML for every document_sync and final event.

Install the CKEditor 5 base packages:

npm install @ckeditor/ckeditor5-core @ckeditor/ckeditor5-engine

CKEditor 5 uses a schema + conversion model. Register data-chunk-id as an allowed attribute on every block element and set up conversion both ways:

// chunk-id-plugin.ts
import { Plugin } from "@ckeditor/ckeditor5-core";

export default class ChunkIdPreserver extends Plugin {
  static get pluginName() { return "ChunkIdPreserver"; }

  init() {
    const editor = this.editor;
    const schema = editor.model.schema;

    // Allow the attribute on every block-level element.
    schema.extend("$block", { allowAttributes: "chunkId" });

    // Downcast: model → view
    editor.conversion.for("downcast").attributeToAttribute({
      model: "chunkId",
      view: "data-chunk-id",
    });

    // Upcast: view → model
    editor.conversion.for("upcast").attributeToAttribute({
      view: { name: /.+/, key: "data-chunk-id" },
      model: "chunkId",
    });
  }
}

ClassicEditor.create(element, {
  plugins: [..., ChunkIdPreserver],
});

Then editor.getData() returns HTML with data-chunk-id preserved, and editor.setData(html) loads SuperDocs HTML without stripping it.Where this slots in: add ChunkIdPreserver to the plugins array of whichever CKEditor 5 build you’re using. If you have custom block elements (tables, images, custom widgets), ensure schema.extend is called for their names too.

Other editors and custom implementations

The principle is the same regardless of editor: preserve unknown HTML attributes on block-level elements across parse and serialise. Three things to verify in your editor’s documentation:

Does the parser strip unknown attributes by default? Most do. Look for “custom attributes” or “attribute preservation” in the docs.
Does the serialiser emit them when converting back to HTML? If the parser accepted them, the serialiser usually does — but not always.
Does the internal model store them on every block type you plan to use? Often there’s a schema or node definition that has to be extended per node type.

Verification test

Paste any SuperDocs response into your editor, read the HTML back out, and diff against the input. Every data-chunk-id must survive.

const incoming = `<h1 data-chunk-id="abc123">Title</h1><p data-chunk-id="def456">Body</p>`;

editor.setHtml(incoming);
const roundTripped = editor.getHtml();

const inIds = [...incoming.matchAll(/data-chunk-id="([^"]+)"/g)].map(m => m[1]);
const outIds = [...roundTripped.matchAll(/data-chunk-id="([^"]+)"/g)].map(m => m[1]);

console.assert(
  inIds.every(id => outIds.includes(id)),
  "Chunk IDs did not survive the round-trip",
  { inIds, outIds }
);

Run this on every block type your product uses — headings, paragraphs, lists, list items, blockquotes, code blocks, horizontal rules, tables. A gap in any single type will surface as occasional silent edit failures in production.

Stuck?

If your editor isn’t covered here, or chunk-id round-trip is failing despite following the pattern, email hello@superdocs.app or book a 15-minute integration call at cal.com/superdocs. We’ll add your editor’s pattern to this guide.

Getting Started

Capabilities

Account & Billing

Core Concepts

Guides

MCP Integration

Errors & Limits

Code Examples

Editor Integration

Editor Integration

Why this matters

The pattern, in plain English

Working snippets

Other editors and custom implementations

Verification test

Stuck?

Getting Started

Capabilities

Account & Billing

Core Concepts

Guides

MCP Integration

Errors & Limits

Code Examples

​Editor Integration

​Why this matters

​The pattern, in plain English

​Working snippets

​Other editors and custom implementations

​Verification test

​Stuck?

Editor Integration

Why this matters

The pattern, in plain English

Working snippets

Other editors and custom implementations

Verification test

Stuck?