Starting Web Surface

What you need before you start

The commands below run in the prepared ~/Desktop/SumDoc-API-first-run folder. It comes, together with the a4-api-demo.mjs and start-web-demo.sh scripts, from the Evaluation Kit — a separate delivery artifact (see What is delivered). It is not part of the SumDoc installer and cannot be downloaded from dl.layers.md: request it from the vendor.

If you don’t have the Evaluation Kit yet, an installed SumDoc is enough to follow the same path manually: fastdoc-cli lives inside the application (see Installation and verification), the request format is described in Request and response objects, and the full list of commands is in the reference. SumSheet has an example of a fully written-out script: verified script. :::

Surface is a ready-made local editor page on top of the same Rust core. It’s the fastest way to see embedding in action: you start a local host and put its URL into a WebView or iframe.

What the surface can do today

It declares exactly four capabilities: open a document, edit the first paragraph, save, and emit events to your application. This is a verifiable demonstration of the “open → edit → save” path, not a full browser editor: arbitrary editing, selection, and the context menu aren’t exposed yet.

The full browser editor is a different path: the same desktop application runs there, while the core computes the document on the server. :::

The surface starts with a single processor command. The path to it depends on your system; the other arguments are the same: --doc — which document to open, --save — where to save (the same file by default).

The --doc value below is the sample from the delivery itself — the same file the quick start begins with. Any DOCX of yours works too: the surface opens whatever it’s given.

macOS

CLI="/Applications/SumDoc.app/Contents/Resources/runtime/native/fastdoc-cli"
DOC="/Applications/SumDoc.app/Contents/Resources/app/fixtures/docx/simple_text.docx"
"$CLI" surface --doc "$DOC" \
  --save ~/Desktop/api-demo-web-result.docx

Windows

$CLI = "C:\Program Files\SumDoc\resources\runtime\native\fastdoc-cli.exe"
$DOC = "C:\Program Files\SumDoc\resources\app\fixtures\docx\simple_text.docx"
& $CLI surface --doc $DOC `
  --save "$HOME\Desktop\api-demo-web-result.docx"

Linux

CLI="/opt/SumDoc/resources/runtime/native/fastdoc-cli"
DOC="/opt/SumDoc/resources/app/fixtures/docx/simple_text.docx"
"$CLI" surface --doc "$DOC" \
  --save ~/Desktop/api-demo-web-result.docx

In response, the processor prints a JSON line with a ready-made address — open it in your browser. The address contains a one-time pass, so there’s nothing to substitute.

The Evaluation Kit has a ready-made script for the same purpose, start-web-demo.sh; it runs the same command with a preset port and pass.

1. Wait for the document to load.
2. Place the cursor in the first paragraph and add text.
3. Click the Save DOCX button — it’s labeled in English, same as on the surface itself.
4. Check the file given in --save.
5. Stop the surface with Control+C in the same terminal window.

The port and pass are new every run

The system picks the default port, and the pass is generated anew on every run — so an address from someone else’s example won’t work. fastdoc-cli prints both values at startup as a single JSON line:

{"schema":"fastdoc.surface-host-bootstrap.v1","host":"127.0.0.1",
 "port":54321,"token":"…","url":"http://127.0.0.1:54321/?token=…",
 "document_path":"/absolute/input.docx",
 "save_path":"/absolute/output.docx","ready":true}

Take the ready-made url from this line — it already contains the required pass. Both paths come along with it: document_path — the opened document, save_path — where the save will go. Your application can show them to the user without having to remember what it passed on the command line itself. :::

What’s next

The surface is up and running. Next:

• embed it in your product — Embedding Surface;
• exact event names, schemas, and parameters — Browser surface interface.