Embedding Surface

The surface starts locally and opens at the address from bootstrap. This page is about embedding it in your application.

The surface edits only the first paragraph

You can’t embed it as a full editor: it declares open, editing the first paragraph, save, and events. This is a verifiable demonstration of the path, not an editor for end users — see Starting Web Surface. The full browser editor is the web host.

Two different ways through iframe

This describes embedding a surface that runs alongside your application — on the same machine as the user: a desktop program starts Surface Host and opens its address in its own window.

If your product lives in the browser and the core must run on the server, you need a different path — Editor in the browser. There, the user installs nothing, and a separate process starts on the server for every open document.

Start with the demo first

If Surface hasn’t run yet, start with launching it: it walks through the full path from installation to a saved file.

How to start the surface

# $CLI — path to the processor, see "Installation and verification"
"$CLI" surface --port 0 \
  --doc /data/input.docx --save /data/output.docx

# first line of stdout: fastdoc.surface-host-bootstrap.v1
# open the address from bootstrap.url in WKWebView, WebView2, or a browser

Mount the surface and remove it

What the surface accepts quietly, and what it quietly drops

Only names starting with --fastdoc- get into cssVariables, and only string values: "16px" gets through, 16 doesn’t. The surface skips everything else with no error and no warning. The list of what it understands is on the Customizing under your brand page.

The locale field is strict too: if you pass something other than a string, or nothing at all, the surface’s language becomes English.

And theme is matched letter for letter against the word dark: only that value makes the surface dark. "Dark", "DARK", true, and any other value silently give you light — there’s no “looks like dark” check here. The theme parameter in the page address follows the same rule.

readOnly here disables input in the surface itself — it disables the edit field and the save button. This is not document protection: commands sent directly over the session don’t obey it. A core-level block is the document’s own protection mode, which refuses any editing command.

There’s only one surface per page. A second mount call doesn’t start a second surface — it first unmounts the first one, silently for the caller, though the host gets an unmounted event it didn’t ask for. You can’t put two documents side by side on one page this way: you need two pages, each with its own surface. For the same reason, window.fastdocSurface.unmount() removes whichever surface is currently alive — not “yours”, but the only one.

And one exception instead of a silent skip: if mount’s first argument isn’t a page node, the call throws TypeError. Here the surface doesn’t forgive — unlike the settings above.

const handle = window.fastdocSurface.mount(container, {
  theme: "light",
  locale: "ru",
  readOnly: false,
  cssVariables: { "--fastdoc-accent": "#2f5bff" }
});

// when the tab or document closes
handle.unmount();

How to receive events

window.addEventListener("fastdoc-host-event", (event) => {
  const message = event.detail;
  if (message.schema !== "fastdoc.surface-host-event.v1") return;

  switch (message.type) {
    case "ready": console.log(message.documentPath); break;
    case "dirty": setUnsavedBadge(message.dirty); break;
    case "saved": console.log(message.path, message.byteCount); break;
    case "error": showError(message.operation, message.message); break;
    case "unmounted": releasePartnerResources(); break;
  }
});

Environment	Where it occurs	Event channel
WKWebView, WebKitGTK	macOS, iOS, Linux	a message handler named fastdocHost
WebView2	Windows	window.chrome.webview, the WebMessageReceived event
A plain browser, no wrapper	everywhere	the DOM event fastdoc-host-event

You don’t need to choose a channel: the surface sends every event to all three at once. The host listens on whichever one it has and knows nothing about the rest.

Honest status of Surface Host

Today this is a portable surface with a limited set: you can mount it in your window and unmount it again, and it emits ready, dirty, saved, error, and unmounted events. That’s enough to prove the embedding boundary, but there’s no full external interface yet to every editor feature or to extending the context menu.

Embedding

<iframe
  src="http://127.0.0.1:9272/?token=a4-local-demo&locale=ru-RU&theme=light"
  title="SumDoc document editor"
  style="width:100%;height:720px;border:0"
></iframe>

The surface reports its states — ready, dirty, saved, error, and unmounted — through the fastdoc-host-event window event. That’s enough to know what’s happening with the document, but not enough to control it: for full access to the model and the whole set of operations, work in parallel through JSON-line exchange or WebSocket.

Known behavior of the current build

During testing, one long-idle connection dropped, and the page reported that it had lost the connection to the surface. Reloading the page and saving right after worked without loss. In a production setup, plan for a connection liveness check, automatic reconnection, and a visible status indicator — so people know whether their edits are being saved.

What to plan for in a production setup

The surface starts on a random free port, not a predetermined one: a busy port and connections from elsewhere to it are one more way to disrupt operation.

The pass is issued anew for every session and must not end up in web server logs together with the page address.

After a drop, the connection recovers, but an edit is never blindly retried: first confirm it wasn’t applied before the drop, or the document will get it twice.

Saving first writes a new copy, and only by the user’s explicit decision does it replace the original file.

After a disconnect and after a save

After a dropped connection, don’t blindly retry the last edit: first read the document’s current state. The connection could have dropped after the edit was already applied, and retrying would duplicate it.

After the saved event, reopen the saved DOCX and confirm the change is there. This is a cheap check that catches any mismatch between what the surface showed and what landed on disk.

Show the operator the session state — connecting, ready, unsaved edits, saving, saved, error. People need to see whether it’s safe to close the window right now.

Exact names

Event names, schemas, the global object, and startup parameters are collected in the browser surface interface reference. Take them from there: on this page they’re given as examples and may lag behind.