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>.tgzin 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 answerstampwith 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, orviewper person and file. -
Collaboration goes through a
kition-sync/1server (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.
Links, web addresses, and your shortcuts (KitEmbed 1.5, 1.6)
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
openUrlonlyhttps:,http:, andmailto:addresses; asking the person before opening an address is the page's job. shortcutsare keys the kit forwards instead of handling (shortcutevent). ListCmd+Sonly if the page saves itself witheditor.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()anddiscard()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 (EmbedErrorread-only). state()answersnone,open, orready; a kit without drafts answersnoneand refusescompare,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 passkit.schemayourself.
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 (
viewandcommentrefuse writes withread-only), and only the open document (pathmust be its name, elsenot-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.stampchanges; 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.