Browser surface interface (Browser Surface API)

One surface per page

The active surface is kept in a single place in the module. A second call to mount doesn’t create a second surface — it first unmounts the first one, silently for the caller, but the host receives an unmounted event it didn’t ask for. You can’t put two documents side by side on one page this way.

This is also why the two unmount methods in the declarations below differ. On Handle, it unmounts your surface; on FastDocSurface, it unmounts whichever one is currently active — and that may no longer be yours.

And there’s one place where the surface doesn’t forgive mistakes: if the first argument to mount isn’t a page node, the call throws a TypeError. The settings next to it, by contrast, are silently dropped — see what is accepted and what is discarded.

Starting the surface. $CLI is the path to the processor inside the installed application, defined on the Installation and verification page:

"$CLI" surface --port 0 --doc /absolute/input.docx --save /absolute/output.docx

What the surface exposes on the window. The names start with fastdoc — this is the document engine’s internal name in the code, not a different product: the rename to SumDoc didn’t touch them, because changing the names in the code would break compatibility for anyone who has already embedded the surface. The same applies to the spreadsheet, with the fastsheet prefix.

interface HostConfig { theme?:"light"|"dark"; locale?:string; readOnly?:boolean; cssVariables?:Record<`--fastdoc-${string}`,string>; }
interface Handle { container:HTMLElement; hostConfig:Readonly<HostConfig>; unmount():void; }
interface FastDocSurface { version:"fastdoc.surface-mount.v1"; mount(container:HTMLElement, config?:HostConfig):Handle; unmount():void; }
// window.fastdocSurface: FastDocSurface

Events for your application

type SurfaceEvent =
 | {schema:"fastdoc.surface-host-event.v1";type:"ready";documentPath:string;savePath:string;theme:string;locale:string}
 | {schema:"fastdoc.surface-host-event.v1";type:"dirty";dirty:boolean}
 | {schema:"fastdoc.surface-host-event.v1";type:"saved";dirty:false;path:string;byteCount:number}
 | {schema:"fastdoc.surface-host-event.v1";type:"error";operation:"connect"|"save";message:string}
 | {schema:"fastdoc.surface-host-event.v1";type:"unmounted"};
window.addEventListener("fastdoc-host-event", e => consume((e as CustomEvent<SurfaceEvent>).detail));
// In WKWebView, events arrive at the fastdocHost handler; in WebView2, via WebMessageReceived

The surface is limited today: mounting and unmounting, reading and editing the first paragraph, saving, finishing, and five events. Arbitrary document structure, selection, and the context menu are not exposed.