Mount a kit’s editor on an element of your page. It runs sandboxed from its own origin and reads and saves through your storage, for the people in your identity system.
Your page@kition/embedfrom npm, about 90 KB
Your CDNThe kit packagethe editor and its WebAssembly engine, static files: about 22 MB on first open, then cached
Your storageThe file’s bytesread and written through your callbacks
No Kition server is in that path. Co-editing, if you add it, goes through a sync server.
npm i @kition/embed
embed.ts · after the kition-sdk README
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, // yours: read, stamp, write (versioned), create
identity, // yours: user, users, permissions
})
Choose this when
Your page can run a JavaScript module, with any framework or none.
People co-edit, or your agent works in the document someone has open.
You want the editor’s events, checks and draft review in your own UI.
Run the embed server; your server signs a link for one person and one file, and your page frames it. The file is read and saved through signed callbacks to your storage.
Your pageOne iframeno module, no editor code
Your server@kition/embed-serverthe editor page and its sessions; the kit package from your CDN
Your storageSigned callbacksHEAD, GET and PUT to your server
No Kition server is in that path either: you run the embed server, and it loads the kit package from an origin you host.
npm i @kition/embed-server
server.ts + page.html · condensed from docs/sdk/url.md
// your server: a link for one person and one file
import { signOpenToken } from '@kition/sync/openToken'
const token = await signOpenToken({ iss, aud, tenant, sub, name,
file, version, doc_key, perms, iat, exp }, 'acme-1', privateKey)
<!-- your page: frame it -->
<iframe src="https://docs.example.com/v1/open?token=ko1.…"
allow="clipboard-read; clipboard-write; fullscreen"></iframe>
Choose this when
Your page cannot run a module: a CMS, a low-code tool, a mail client’s web view.
One person edits a file at a time.
You would rather keep the integration on your server: sign a link, answer file callbacks.
Left, this page mounts the Note editor itself; right, the by-link setup that frames the same note: the iframe and the server call that signs its link.
Way 1 · In your page @kition/embed
kition-note · weekly-team-sync.md
Opens weekly-team-sync.md in the real Note editor. Loads about 22 MB.
This page imports @kition/embed and mounts the editor on an element; the note’s bytes stay in this tab. The editor and its WebAssembly engine come from kits.kition.ai, this site’s static kits origin: in your product, your own CDN.
this page · the mount call (LiveKit.tsx)
import { KitionEmbed } from 'https://kits.kition.ai/embed/index.js'
// this page: the Note editor on an element
const editor = await KitionEmbed.mount(element, {
kit: {
id: 'kit.note',
// this site's static kits origin; in your product, your own CDN
url: 'https://kits.kition.ai/note-ui/',
},
file: { id: 'sample-note', name: 'weekly-team-sync.md' },
storage, // read, stamp, write: the note's bytes in this tab
locale: 'en-US',
theme: { colorScheme: 'dark' },
})
Way 2 · By link @kition/embed-server
by link · weekly-team-sync.md
Run the same by-link setup on your machine: node examples/url-embed/serve.mjs in kition-sdk starts an integrator page, the embed server and the kit packages.
By link, your page holds one <iframe> and no editor code; the editor page and its saves run on the embed server you run.
import { signOpenToken } from '@kition/sync/openToken'
const token = await signOpenToken({
iss: 'acme.app', aud: 'docs-example', tenant: 'acme',
sub: user.id, name: user.name,
file: 'res-42', // your immutable file id
version: 'v7', // the version you open
doc_key: 'res-42.g3', // the file's generation: change it when the file is replaced
perms: { edit: true, comment: true, download: true, share: false, export: true },
watermark: null, // or { text: 'Ann · Confidential' }
iat: now, exp: now + 300, // at most an hour; a few minutes is enough
}, 'acme-1', privateKey)
const src = `https://docs.example.com/v1/open?token=${encodeURIComponent(token)}`
Side by side
In your page or by link
In your page or by link: the differences
In your page @kition/embed
By link @kition/embed-server
What you add to your page
@kition/embed and one KitionEmbed.mount(element, …) call
One <iframe src=…>; no module, no JavaScript integration
What you run
The kit package (static files: the editor and its WebAssembly engine) on your CDN, an origin apart from your page (and a sync server, for co-editing)
The embed server (Node 20.6 or later), and the kit packages on your CDN; your server signs the links and answers the callbacks
Where the editor runs
In a sandboxed frame from the kit’s origin, inside your page
On the embed server’s page, which your page frames; the kit loads from another origin
Files
Your StorageProvider in the page: read, stamp, write (versioned), create
HMAC-signed HTTP callbacks to your server: HEAD, GET and PUT /files/{file} with If-Match. The embed server keeps no document and creates no files
People and permissions
Your IdentityProvider: edit, comment or view per person and file
Signed into the link: the person, edit, comment or view, and download, export, share and a watermark
Co-editing
Yes, with the collaboration option: Kition Server or Kition Cloud
No: single-user, one editor per link
Your agent in the open document
editor.agentPort(): its edits go to a draft the person compares and merges or discards in your page
Not in the framed page: it offers no agent port and no draft review
Events and API
The full editor API: saved, changed, conflict, draft, presence and other events; save(), check(), the object model
Two messages to your page: ready, and saved with the new version
Best for
Apps that can run a module and want co-editing, agents or their own controls around the editor
Pages that cannot run a module, where one person edits one file
Co-editing, your agent in the open document and draft review come with @kition/embed in your page; embedded by link, the editor is single-user. From kition-sdk’s embed guide and embed-by-link guide.
Way 1 · @kition/embed
Embed in your page
One call mounts a kit’s editor on an element. The editor and its WebAssembly engine load from your CDN and run sandboxed on that origin; the file is read and saved through your storage, for your users. Works with React, Vue, Svelte, plain JS, Node, Next.js and any MCP client.
embed.ts · from docs/sdk/embed.md
import { KitionEmbed } from '@kition/embed'
const editor = await KitionEmbed.mount(element, {
kit: {
id: 'kit.doc',
// static files on your CDN: the editor and its WebAssembly engine
url: 'https://cdn.example.com/kition/doc-ui/',
},
file: { id: 'project-proposal', name: 'project-proposal.docx' },
// your StorageProvider:
// read, stamp, write (versioned), create
storage,
// your IdentityProvider:
// token, user, users, permissions
identity,
})
kition-doc · project-proposal.docx
Opens project-proposal.docx in the real Doc editor. Loads about 37 MB.
How it works
1.1
Your pageKitionEmbed.mount
You pass kit.url, the kit package’s folder on your CDN, with the file’s id and name, your storage and your identity provider.
Your CDNThe editor and its WebAssembly engine
The browser downloads the kit package from kit.url (about 22 MB for Note the first time, then from its cache) and runs it in a sandboxed frame of that origin; after the handshake everything travels over a private MessagePort.
Your storageread, stamp, write, create
Every save goes back through your StorageProvider. A write carries the version it read, so an edit made elsewhere is never written over.
Host the kit package
Download it. Note’s is kition-note-<version>.tgz on kition-note’s releases; it unpacks to note-ui/.
Upload the folder to your CDN, object storage or any static host, on an origin that is not your page’s.
Point kit.url at it. The browser fetches the editor and the .wasm from there when someone opens a file.
Why another origin: the editor runs in a sandboxed frame of that origin, so it cannot reach your page’s cookies, storage or session. Kition hosts no kit packages for your product: they are your files, on your CDN.
Headers on the kit origin
.wasm as application/wasm.
A content security policy whose frame-ancestors names your page, and no X-Frame-Options: DENY or SAMEORIGIN.
CORS: the frame needs none. If your page reviews agent drafts, let it read model/schema.json.
Cache: hashed files under assets/ for a year (immutable); the rest for a short time, so a new version reaches people.
# 1. the Note kit package, from kition-note's release
curl -LO https://github.com/KitionAI/kition-note/releases/download/package-v0.1.0/kition-note-0.1.0.tgz
tar -xzf kition-note-0.1.0.tgz
# → note-ui/: index.html, assets/, engine/ (the .wasm), fonts/
# 2. upload note-ui/ to your CDN, object storage or static host,
# on an origin that is not your page's, e.g.
# https://cdn.example.com/kition/note-ui/
# 3. check the engine is served as WebAssembly
curl -sI https://cdn.example.com/kition/note-ui/engine/kition_note_kit_bg.wasm | grep -i content-type
# content-type: application/wasm
The SDK’s example page mounts the Note editor over files kept in the browser, with co-editing, its own toolbar button, a script run through the object model and an agent’s draft review.
kition-sdk · examples/embed-app/src/main.ts
main.ts
const editor = await KitionEmbed.mount(element.querySelector('.frame'), {
kit: { id: found.kit.id, url: found.kit.url },
file: { id: file.id, name: file.name },
storage,
identity,
...(settings.collab ? { collaboration: { server: settings.server, ...(room ? { room } : {}) } } : {}),
locale: 'en-US',
theme: { colorScheme: 'light', tokens: { '--kit-primary': '#5645d4' } },
// The page's own button in the editor, and the person's own hides kept with the page.
ui: {
add: [{ id: 'example.submit', place: 'action', label: { 'en-US': 'Submit for review' }, icon: 'send' }],
personal: { hide: hides()[found.kit.id] ?? [] },
customize: ({ hide }) => localStorage.setItem(HIDES, JSON.stringify({ ...hides(), [found.kit.id]: hide })),
},
// The page edits notes through the object model too (the "Run script" button).
model: found.key === 'note',
})
editor.on('collab', (state) => { /* status: off, connecting, online, offline */ })
editor.on('presence', (peers) => { /* who else is in the file */ })
editor.on('error', report)
// The agent's draft, for the person to review: Merge and Discard run only on their click (UI-D1).
editor.on('draft', (info) => { /* show the review bar when info.state is 'ready' */ })
saveButton.addEventListener('click', () => void editor.save().catch(report))
editor.ready().then(() => (element.dataset.ready = 'true'), (error) => { report(error); closeFile(file.id) })
editor.on('draft', async ({ state }) => {
if (state !== 'ready') return hideReview()
const { summary, before, after } = await editor.draft.compare({ maxSize: 640 })
// created / changed / deleted objects, and PNGs of both sides
showReview(summary, before, after)
})
// one undo step, recorded as the agent's
mergeButton.onclick = () => editor.draft.merge()
// the document stays as it is
discardButton.onclick = () => editor.draft.discard()
Limits and requirements
1.4
Host each kit package on an origin of its own (your CDN), never your page’s: the frame’s allow-same-origin is safe only because the origins differ.
Serve .wasm as application/wasm, with a content security policy that allows the kit’s scripts, workers and WebAssembly, and frame-ancestors naming your page.
Your page’s policy lets the kit origin into frames (frame-src) and, when co-editing, its sockets reach the sync server.
Mount in the browser: with server-side rendering, render the element on the server and mount on the client.