Embed · two ways

Two ways to embed a kit’s editor

Two ways to embed a kit’s editor: in your page with @kition/embed, or by link with @kition/embed-server. Both are free, open source and need no key.

Copy for AI

Way 1

In your page @kition/embed

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.

  1. Your page@kition/embedfrom npm, about 90 KB
  2. Your CDNThe kit packagethe editor and its WebAssembly engine, static files: about 22 MB on first open, then cached
  3. 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.

See both, live

The same note, embedded both ways

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, your page holds one <iframe> and no editor code; the editor page and its saves run on the embed server you run.

your page · one iframe
<iframe src="https://docs.example.com/v1/open?token=ko1.…"
  allow="clipboard-read; clipboard-write; fullscreen"></iframe>
your server · from docs/sdk/url.md
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/embedBy link @kition/embed-server
What you add to your page@kition/embed and one KitionEmbed.mount(element, …) callOne <iframe src=…>; no module, no JavaScript integration
What you runThe 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 runsIn a sandboxed frame from the kit’s origin, inside your pageOn the embed server’s page, which your page frames; the kit loads from another origin
FilesYour StorageProvider in the page: read, stamp, write (versioned), createHMAC-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 permissionsYour IdentityProvider: edit, comment or view per person and fileSigned into the link: the person, edit, comment or view, and download, export, share and a watermark
Co-editingYes, with the collaboration option: Kition Server or Kition CloudNo: single-user, one editor per link
Your agent in the open documenteditor.agentPort(): its edits go to a draft the person compares and merges or discards in your pageNot in the framed page: it offers no agent port and no draft review
Events and APIThe full editor API: saved, changed, conflict, draft, presence and other events; save(), check(), the object modelTwo messages to your page: ready, and saved with the new version
Best forApps that can run a module and want co-editing, agents or their own controls around the editorPages 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
  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.

  2. 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.

  3. 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
  1. Download it. Note’s is kition-note-<version>.tgz on kition-note’s releases; it unpacks to note-ui/.
  2. Upload the folder to your CDN, object storage or any static host, on an origin that is not your page’s.
  3. 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.

The full list, with the exact policy: embed reference, Hosting kit packages.

terminal · Note’s kit package on your CDN
# 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 calls that matter

1.2

A complete example

1.3

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) })
Its storage
storage.ts · examples/embed-app/src/storage.ts (condensed)
const storage = {
  read: async (fileId) => {
    const file = files.get(fileId)
    return { bytes: file.bytes.slice(), version: `v${file.version}` }
  },
  stamp: async (fileId) =>
    files.has(fileId) ? `v${files.get(fileId).version}` : null,
  write: async (fileId, bytes, { expectedVersion }) => {
    const file = files.get(fileId)
    const current = `v${file.version}`
    if (expectedVersion !== null && expectedVersion !== current)
      throw new EmbedConflictError(fileId, current)
    files.set(fileId, { ...file, bytes: bytes.slice(), version: file.version + 1 })
    return { version: `v${file.version + 1}` }
  },
  // an export or a copy: keep it, answer { fileId, name, version }
  create: async (name, bytes) => { /* … */ },
}
An agent’s draft, reviewed in the page
docs/sdk/embed.md
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.
Try the editors in the playground
Way 2 · @kition/embed-serverCan’t run a module in your page? Embed by link: frame one signed iframe from the embed server you run.

Put a real editor in your product

Install the package, put the kit package on your CDN, mount it on an element. Or run the embed server and frame a signed link.

npm i @kition/embed