Embed in your page: kit editors with @kition/embed

Mount a kit’s editor with KitionEmbed.mount over your storage and your users (the editor and its WebAssembly engine load from your CDN), check the document, and review an agent’s draft or let your agent work in the open editor.

The full reference is the embed reference. This page is the SDK view: what a customer wires up, and where it sits in the Kition kit platform.

import { KitionEmbed } from '@kition/embed'

const editor = await KitionEmbed.mount(element, {
  kit: {
    id: 'kit.note',
    // static files on your CDN: the editor and its WebAssembly engine
    url: 'https://cdn.example.com/kition/note-ui/',
  },
  file: { id: 'plan-2026', name: 'Plan.md' },
  storage,             // your StorageProvider: read, stamp, write (versioned), create
  identity,            // your IdentityProvider: token, user, users, permissions
  collaboration: { server: 'wss://sync.example.com/v1/sync' }, // optional: co-editing
})
  • Kit packages (kits/kition-<kit>-<version>.tgz in the bundle) are static folders: host them on their own origin with the policy in the embed reference section 3 (UI-H3).

  • Storage is yours. A write carries the version it read; refuse a stale one with EmbedConflictError, and answer stamp with the current version, so an edit made elsewhere (an agent's save) is never written over. The editor writes one save at a time, each over the version the one before it wrote, and does not write the same bytes twice in a row, so a stale version always means the file changed elsewhere.

  • Identity and permissions are yours: edit, comment, or view per person and file.

  • Collaboration goes through a kition-sync/1 server (Kition Server).

  • Checks: editor.check() lists what the kit finds wrong with the document ({ code, severity, target, message, fix? }, errors first); editor.check({ draft: true }) checks the agent's draft.

A kit opens no window itself. Give the storage provider the callbacks and the kit offers what they serve; leave them out and it shows links as plain text:

const storage = {
  ...files,
  resolveLink: (fromFileId, link) => workspace.resolve(fromFileId, link), // { fileId, name, kitId, version, path } | null
  open: (fileId, view) => app.openTab(fileId, view),                       // { opened }
  openUrl: async (url) => ({ opened: await app.confirmAndOpen(url) }),     // show the full address first
}
const editor = await KitionEmbed.mount(element, { kit, file, storage, shortcuts: ['Cmd+S', 'Cmd+J'] })
editor.on('shortcut', (key) => app.runShortcut(key))
  • The embed calls them only from a person's gesture in the kit and passes openUrl only https:, http:, and mailto: addresses; asking the person before opening an address is the page's job.
  • shortcuts are keys the kit forwards instead of handling (shortcut event). List Cmd+S only if the page saves itself with editor.save().

The agent's draft, reviewed in your page (KitEmbed 1.3)

An agent edits a draft of the document; the person sees what it changes and merges or discards it. The draft event says when the draft opens, changes, is ready for review, or closes:

editor.on('draft', async ({ state }) => {
  if (state !== 'ready') return hideReview()
  const { summary, before, after } = await editor.draft.compare({ maxSize: 640 })
  showReview(summary, before, after) // created / changed / deleted objects, and PNGs of both sides
})
mergeButton.onclick = () => editor.draft.merge()     // one undo step, recorded as the agent's
discardButton.onclick = () => editor.draft.discard() // the document stays as it is
  • Call merge() and discard() only from the person's click, never from an agent's or a model's output (Kit UI protocol UI-D1). A person who may not edit cannot (EmbedError read-only).
  • state() answers none, open, or ready; a kit without drafts answers none and refuses compare, merge, discard (unsupported); there is nothing to merge without a draft (no-draft).
  • The draft's comparison needs the kit's schema; the embed reads the one the kit package ships (model/schema.json; serve it with the package, readable by the page), else loads it from @kition/script's generated kits, or pass kit.schema yourself.

Your agent in the open editor (editor.agentPort, KitEmbed 1.3)

Your agent (on your server) can work in the document the person has open, with the same MCP tools kition-kits-mcp offers on files (<prefix>_inspect, _commands, _run, _query, _batch, _check, _draft_ready, _draft_reopen). editor.agentPort() is an MCP server for one editor; your page relays its messages to your server, and your server hands them to the agent:

// In the page:
import { relayAgentPort } from '@kition/embed'
const port = editor.agentPort({ principal: 'agent:assistant', label: 'Assistant' })
void relayAgentPort(port, {
  next: async () => { const r = await fetch('/agent/next'); return r.status === 204 ? null : r.json() },
  reply: async (message) => { await fetch('/agent/reply', { method: 'POST', body: JSON.stringify(message) }) },
})

// On the server (Node): one relay per open document.
import { createAgentRelay } from '@kition/script/node'
const relay = createAgentRelay()
// GET /agent/next  -> relay.next({ signal })   (abort when the page's request closes)
// POST /agent/reply -> relay.reply(body)
// the agent's MCP messages -> relay.request(message)
  • The agent's edits go to a draft by default (agentPort({ draft: false }) lets it edit live). It can ask for review (<prefix>_draft_ready) but has no tool that merges or discards: the person does, in the page.
  • It edits no more than the person may (view and comment refuse writes with read-only), and only the open document (path must be its name, else not-open).
  • Authenticate both sides yourself: relay only to the page of the person who asked for the agent.
  • Without a relay, an agent works headless on the file (kition-kits-mcp, Agents (MCP)) and the page sees its save as a new version (storage.stamp changes; the editor offers to reload), never as a draft.

Example: examples/embed-app. With EMBED_WORKSPACE=<folder> its server keeps the files in a folder (workspace.mjs, src/workspace-storage.ts), which is how the agent example shares them; its server also relays an agent to the open editors (agent-relay.mjs, /api/agent/<name>/mcp), and the page shows a review bar for the agent's draft. examples/agent-mcp/live.mjs is such an agent.

Kition kit platform: KitEmbed 1.8, the Kit UI protocol (reference), kit editors.

From kition-sdk docs/sdk/embed.md, where the snippets are tested.Source on GitHub