Where to start the pilot

How to embed a working example in 30 minutes

The goal of the first run isn’t production use. The goal is simpler: open your own document inside your own application, change it, receive events, and confirm the saved file is correct.

Time	Action	Expected result
0–5 min	Take the editor surface and any document of yours; choose which window you’ll show it in.	Three things are known: the program itself, the source document, and a separate file for the result.
5–10 min	Start the surface on a free local port.	You get back the page address, a one-time pass to it, and a schema name with a version number — there’s no separate version field in the startup line, the number is in the name itself.
10–15 min	Create a web view window and open this address in it.	The editor loads inside your window.
15–20 min	Attach a message handler for the editor.	The ready event arrives — you can show that the document is open.
20–25 min	Edit the first paragraph and save. The first one specifically: the surface shows and edits a single paragraph — this is an embedding trial, not an editor (what it includes).	The dirty and saved events arrive, and the result file appears.
25–30 min	Reopen the saved file and stop the surface.	The edit is there; the subscriptions, connection, and process are closed and left nothing behind.

What starts the surface

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

The call sequence on the host side

bootstrap = startSurface(input, output)
webview.onMessage(event => handleA4Event(event))
webview.open(bootstrap.url)
waitFor('ready')
// the user edits the document
waitFor('dirty'); requestSave(); waitFor('saved')
webview.close(); stopSurface()

What “30 minutes” means

An embedding path without Electron — through the system web-view component — exists and is documented; a pre-assembled evaluation kit (Evaluation Kit) is issued for it — the same one mentioned below and explained in the glossary. A public developer kit, single sign-on, a storage adapter, and your brand’s styling rules are separate work after the pilot.

What to give three specialists so they can decide — go or no-go

First the big picture and a live example. Then the internals, the session contract, and commercial terms.

Recommended reading order

1. The SumDoc — what it is section and the pages next to it: objects and relationships, the Rust/Web split, deployment options, and the quick start.

2. The architecture specification — a separate delivery document (see What is delivered): protocol, lifecycle, security, versioning, deployment, and acceptance for production use.

3. The Evaluation Kit — a separate delivery artifact (see What is delivered): Surface Host, host examples, three DOCX files, schemas and types, known limitations, and a quick start.

4. The capability matrix — what’s proven for your chosen platform and on your real documents.

5. The pilot plan — a single “open → edit → event → save → reopen” route, with the conditions under which it’s judged successful.

Five questions for the first meeting

1. Where does the editor need to run: on Windows or macOS workstations, in the browser, on phones, or as a service on your servers?

2. How does your application hand over the document, and where should it receive the new version?

3. Which ten user actions are mandatory in the first pilot?

4. What documents, and what sizes, do you actually work with?

5. What’s mandatory for single sign-on, audit, network, updates, long-term version support, and data residency?

Criteria for a successful first pilot

Ready for the next conversation

The editor opened inside your product; a user changed a real document; your application received the ready, dirty, and saved events; the saved file reopened; permissions, versions, and audit stayed on your side; after closing, no hanging processes or subscriptions were left behind.

What to read after this page

The SumDoc embeddable editor’s architecture specification is a detailed document for architects and engineers — the one you move on to once you’ve worked through the product’s basic model. It’s issued together with the evaluation kit; on the site the same topics are broken out by part: how the editor works, session lifecycle, session contract, deployment options, and security.

What’s described here, and what’s set separately

This describes the product’s proven architectural foundation. The public developer kit, the command list, availability commitments, the license, and the final capability profile are fixed in separate appendices to the pilot and the contract.

Suggested next step

• 60–90 minutes: agree on one real document which objects are addressable, which events arrive, and what shows up in the context menu.

• Lock in the interaction contract version and the pilot’s capability profile.

• Build one end-to-end example: right-click on a table cell → your context menu → a typed edit → save and reopen.

• After acceptance, extend the list of supported objects in pieces, rather than promising the whole Word feature set in one statement.