API reference / @docmentis/udoc-editor / UDocEditor

Class: UDocEditor

The document editor — construct it with UDocEditor.create and drive it with open / close / destroy.

Extends

• UDocBase<UDocEditorEvents>

Properties

version

readonly static version: string;

This package's version, from its package.json.

Accessors

mode

get mode(): EditorMode;

The current editor mode; "mode:changed" fires when it changes.

---

searchMatches

get searchMatches(): readonly SearchMatch[];

The matches the search has found so far, in document order.

---

searchActiveIndex

get searchActiveIndex(): number;

The index of the current match in searchMatches; -1 for none.

---

docType

get docType(): UDocType | null;

The open document's doc type, or null with no document open.

---

sourceFormat

get sourceFormat(): FileFormat | null;

The file format the open document came from — what saving it back means — or null with no document open, or for a package that recorded none.

---

pageCount

get pageCount(): number;

The pages composed so far — not the document's total until composing finishes, so it grows as pages compose ahead. 0 with no document open, or for a doc type without pages.

---

currentPage

get currentPage(): number;

The current page's 0-based index, as goToPage takes it; "currentPage:changed" fires when it changes.

---

sheetCount

get sheetCount(): number;

How many sheets the open workbook has, hidden ones included, so that an index counts the workbook's own sheets in order. 0 with no document open, or one without sheets.

---

currentSheet

get currentSheet(): number;

The sheet shown: its 0-based index, as goToSheet takes it, or -1 with no document open, or one without sheets. "currentSheet:changed" fires when it changes.

---

sheets

get sheets(): readonly SheetInfo[];

The open workbook's sheets, in its own order — hidden ones too — so that a sheet's index here is the one goToSheet takes and currentSheet reports. Empty with no document open, or one without sheets. The same array until it changes, when "sheets:changed" fires.

---

theme

get theme(): ThemeMode;

The color theme, as setTheme or the toolbar's theme button last set it.

---

isFullscreen

get isFullscreen(): boolean;

Whether the document UI fills the screen, by setFullscreen or the toolbar menu's Fullscreen button.

---

scrollMode

get scrollMode(): ScrollMode;

How the view scrolls, as setScrollMode or the view settings last set it.

---

layoutMode

get layoutMode(): LayoutMode;

How the pages group into spreads, as setLayoutMode or the view settings last set it.

---

pageRotation

get pageRotation(): 0 | 90 | 180 | 270;

The turn every page is shown at, as setPageRotation or the view settings last set it.

---

pageGap

get pageGap(): PageGap | null;

The gaps between pages, as setPageGap last set them; null for the built-in gaps.

---

fit

get fit(): Fit;

The fit the open document is shown by, as setFit, the zoom menu, or an explicit zoom ("none") last set it.

---

zoom

get zoom(): number;

The zoom on screen, 1 being 100% — the fit's derived zoom while one is active.

---

dpi

get dpi(): number;

The CSS px per inch the open document shows at: the dpi option or setDpi's, else its doc type's default.

---

activePanel

get activePanel(): PanelTab | null;

The open side panel, or null for none; "panel:changed" fires when it changes.

---

navigationScrollAlignment

get navigationScrollAlignment(): ScrollAlignment;

Where a followed link or outline item, or a chosen comment, lands, as setNavigationScrollAlignment last set it.

---

searchScrollAlignment

get searchScrollAlignment(): ScrollAlignment;

Where a search match lands, as setSearchScrollAlignment last set it.

Methods

create()

static create(container, options?): Promise<UDocEditor>;

Create an editor mounted into container. Spawns the render worker and loads the WASM (async), then mounts the UI. Rejects with an unsupportedUDocError on runtimes without OffscreenCanvas-in-worker support.

Parameters

Parameter	Type
container	HTMLElement
options?	UDocEditorOptions

---

startLocalCollaborationService()

static startLocalCollaborationService(bytes, options?): Promise<string>;

Start a local collaboration service on the document in bytes, and resolve with its id — the page's own udoc server for one document, for editors in this page to openLocal and joinLocalCollaboration.

Editors that each open the same bytes can't collaborate: a document's ids are minted as its parts load, so two editors that load them in a different order hold different ids for the same content. The service imports the document once, in a worker of its own, and keeps its udoc package, which every editor opening it shares; then it serves their collaboration, as udoc-server serves one for a document it keeps. It ends when the last editor joined to it leaves.

Its session is started as an editor's is, under options: it rejects when the license refuses it.

Parameters

Parameter	Type
bytes	Uint8Array
options?	LocalCollaborationServiceOptions

---

insertImage()

insertImage(bytes, contentType): Promise<void>;

Insert the image file bytes as a picture on the current slide, centred and scaled down to fit, then selected — what the Insert tab's Image does with the file it asks for. contentType is the file's MIME type (image/png, …); an empty one is read from the bytes' own signature. One committing edit (one undo step). The image never enters the CRDT: it reaches a peer through opaquePartsSince. Rejects for a document that isn't a presentation, or bytes no codec reads.

Parameters

Parameter	Type
bytes	Uint8Array
contentType	string

---

setShowRuler()

setShowRuler(visible): void;

Show or hide the page ruler on paged documents (PDF / DOCX / PPTX). A user preference; the ruler is additionally hidden automatically in "view" mode (a reading pose needs no measurement chrome). A spreadsheet's row/column headers are essential and never affected.

Parameters

Parameter	Type
visible	boolean

---

setShowFormattingMarks()

setShowFormattingMarks(visible): void;

Show or hide formatting marks — ¶ at each paragraph end, a dot in each space, an arrow in each tab, ↵ at each line break — on wordprocessing documents; the same toggle as the ribbon's button. A user preference, off by default; the marks are editing chrome, so they're additionally hidden outside "edit" mode.

Parameters

Parameter	Type
visible	boolean

---

setMode()

setMode(mode): void;

Switch the editor mode. Ignored if mode isn't in the configured allowedModes. Drives the toolbar's command set and pointer behavior.

Parameters

Parameter	Type
mode	EditorMode

---

destroy()

destroy(): void;

Tear down components, listeners, and the render worker.

---

registerFonts()

registerFonts(fonts): void;

Offer fonts of the host's own to every document opened after this call. Each is either a font file's bytes — TrueType, OpenType, a collection, WOFF, WOFF2 or EOT — which name their own family and faces, or a UrlFont: a family and face, and the URL its file is fetched from once a document's text asks for it. Bytes that aren't a font register nothing.

A document's own embedded fonts still come first; registered bytes, then URLs, come ahead of Google Fonts and the bundled fonts. Each call adds to the last. The document already open keeps the fonts it opened with — its text was shaped as it opened — so register before open.

Parameters

Parameter	Type
fonts	readonly ( | Uint8Array<ArrayBufferLike> | UrlFont)[]

---

open()

open(source, options?): Promise<void>;

Open a document — source its URL, which is fetched, a Blob such as a File, which it reads, or its bytes — as OpenOptions says: its format, detected unless given, its file's name, and the password a protected one opens with. While it opens, "document:loading" reports how far its bytes have been read, and the loading overlay shows once it has taken long enough to notice. The opened document's doc type and source format are then docType and sourceFormat, and a workbook's sheets sheetCount and currentSheet.

Rejects with a UDocError when the document doesn't open — an io one when its URL can't be fetched — after showing it, with the license notice for a licensing refusal.

Parameters

Parameter	Type
source	string | Uint8Array<ArrayBufferLike> | URL | Blob
options?	OpenOptions

---

openRemote()

openRemote(url): Promise<void>;

Open the document a udoc server keeps, part by part: url is its package resource, …/documents/{documentId}/package. The engine fetches each part the first time the document needs it, so only the parts it reaches are downloaded. The doc type and source format are then docType and sourceFormat, and a failure rejects, as for open.

Parameters

Parameter	Type
url	string

---

openLocal()

openLocal(id): Promise<void>;

Open the document the local collaboration service id keeps (the id the class's static startLocalCollaborationService resolves with): its package, with every edit the service has merged. The doc type and source format are then docType and sourceFormat, and a failure rejects, as for open.

Parameters

Parameter	Type
id	string

---

undo()

undo(): Promise<void>;

Undo the last edit. Resolves once the layout has been refreshed.

---

redo()

redo(): Promise<void>;

Redo the last undone edit. Resolves once the layout has been refreshed.

---

mintId()

mintId(): Promise<string | null>;

Mint one fresh, CRDT-safe id (its 32-char hex key) — id allocation is the session's, so a minted id can't collide with a loader or peer id. An InsertObjects command carries the ids of the objects it inserts, so the host mints one here, stamps it into the object it builds, and names it in the command (and can select by it afterward). Resolves to null with no open document or a doc type that mints no ids.

---

selectedObjectIds()

selectedObjectIds(): Promise<string[]>;

The hex keys of the graphics objects currently selected here — empty when nothing is selected. The read that lets a host act on the current selection by id, e.g. read one instance's selection and selectObjects the same ids in another.

---

selectObjects()

selectObjects(page, ids): void;

Select the graphics objects named by ids (their 32-char hex keys) on the page at index page — id-addressed selection, the programmatic counterpart of a pointer click. A portable selection is confined to one page, so the page rides with the ids. Presence only (no edit, no undo step), so it fires "selection:changed" and a sync transport broadcasts it as this one's selection — collaborators see it in this peer's color. Unknown ids are skipped; an empty list clears the selection.

Parameters

Parameter	Type
page	number
ids	string[]

---

setSelection()

setSelection(selection): void;

Set the selection to a doc-type-tagged UDocSelection — the agnostic, id-addressed presence path used where selectObjects (portable objects only) can't express the selection, e.g. presentation shapes: { presentation: { shapes: { slide, selection: { shapes: ids } } } }. Presence only (no undo step); fires "selection:changed" and a sync transport broadcasts it as this peer's selection. Pass { presentation: "none" } (or the doc type's empty variant) to clear.

Parameters

Parameter	Type
selection	UDocSelection

---

selection()

selection(): Promise<UDocSelection | null>;

The current selection as the tagged UDocSelection, or null when nothing is selected / no document — the doc-type-agnostic read (portable objects, presentation shapes, …). The counterpart of selectedObjectIds for doc types beyond portable; lets a host read its own or a peer's selection whatever the doc type.

---

clearSelection()

clearSelection(): void;

Clear the selection (presence only; fires "selection:changed").

---

execute()

execute(command): Promise<void>;

Execute one arbitrary, doc-type-tagged UDocCommand — the single write seam. Every edit is a command: page structure (InsertPage / DeletePage / ReorderPage, addressed by index), object content (InsertObjects / TransformObjects / DeleteObjects, addressed by PageId + object ids), and their presentation twins. A host crafts the strongly-typed command from the declared type (UDocCommand, in the wasm's udoc.d.ts) — there are no per-verb methods; this is how all writes happen, so the same shape is loggable and replayable. Build the object payloads the host's own way and mint their ids with mintId. One committing edit (one undo step); resolves once the layout has refreshed, with any selection change reported via "selection:changed". Rejects if the command is invalid for the open document.

Parameters

Parameter	Type
command	UDocCommand

---

getPageAnnotations()

getPageAnnotations(page): Promise<Annotation[]>;

Get the annotations on a page of a PDF, in paint order — the engine's model of each (Annotation), read without its appearance (null). A reply is an annotation of its own, naming the one it answers in its markup's inReplyTo.

Every geometry field is in the page's unrotated MediaBox space — origin top-left, PDF points, +y downward — whatever the page's /Rotate. [] for a document that isn't a PDF.

Parameters

Parameter	Type	Description
page	number	Page index (0-based)

---

addPageAnnotation()

addPageAnnotation(page, annotation): Promise<Annotation>;

Add a new annotation to a page.

If annotation.name (its /NM) is omitted, a UUID is generated and assigned — the key the other calls take, which a save writes and a reopen reads back, where an annotation's id is minted afresh each time a file is read. Its id is minted too where it has none, and its appearance is generated where it has none. The returned value is the annotation as inserted (with id and name populated). The selection is left as it was.

Pass ephemeral: true to create one that shows but is never saved or printed; updatePageAnnotation can flip the flag to promote a preview into a saved annotation (or demote a saved one).

Annotations are supported on PDF documents only. Resolves once "annotation:inserted" has fired for it.

Parameters

Parameter	Type	Description
page	number	Page index (0-based)
annotation	Annotation	-

Returns

Promise<Annotation>

The inserted annotation (with id and name populated).

---

addPageAnnotations()

addPageAnnotations(page, annotations): Promise<Annotation[]>;

Add several annotations to one page in a single edit — one undo step. Use it when importing or restoring annotations. "annotation:inserted" still fires once per annotation, in input order.

Parameters

Parameter	Type	Description
page	number	Page index (0-based)
annotations	Annotation[]	Annotations to insert (may mix ephemeral and saved)

Returns

Promise<Annotation[]>

The inserted annotations (with id and name populated), in input order.

---

updatePageAnnotation()

updatePageAnnotation(
   page, 
   name, 
   annotation
): Promise<Annotation>;

Replace an existing annotation, identified by its name (NM), with annotation whole — a field it omits is cleared. Its id and name are kept even where annotation gives others. Its appearance is generated afresh where annotation gives none — but a stamp's picture, which stays while its icon and colour do.

Parameters

Parameter	Type	Description
page	number	Page index (0-based)
name	string	The annotation's name (NM).
annotation	Annotation	-

Returns

Promise<Annotation>

The updated annotation.

Throws

If no annotation with the given name is found on the page.

---

updatePageAnnotations()

updatePageAnnotations(page, updates): Promise<Annotation[]>;

Replace several annotations on one page, as updatePageAnnotation does each. Validation is atomic: if any name is missing on the page the call throws before any change is applied. "annotation:updated" fires once per entry.

Parameters

Parameter	Type	Description
page	number	Page index (0-based)
updates	object[]	-

Returns

Promise<Annotation[]>

The updated annotations, in input order.

---

patchPageAnnotation()

patchPageAnnotation(
   page, 
   name, 
   patch
): Promise<Annotation>;

Patch an existing annotation, identified by its name (NM).

Unlike updatePageAnnotation, which replaces the entire annotation, this only overwrites the fields present in patch, and merges an object field into the annotation's, all the way down — so { kind: { highlight: { markup: { author } } } } keeps the quads and every other markup entry.

Semantics:

• id and name in the patch are ignored; a kind of another subtype replaces the kind whole.
• An array is replaced whole.
• undefined values are skipped, not treated as "clear this field"; null clears.

Parameters

Parameter	Type	Description
page	number	Page index (0-based)
name	string	The annotation's name (NM).
patch	AnnotationPatch	Fields to merge into the existing annotation.

Returns

Promise<Annotation>

The patched annotation.

Throws

If no annotation with the given name is found on the page.

---

patchPageAnnotations()

patchPageAnnotations(page, patches): Promise<Annotation[]>;

Patch several annotations on one page, as patchPageAnnotation does each. Validation is atomic, as updatePageAnnotations'.

Parameters

Parameter	Type	Description
page	number	Page index (0-based)
patches	object[]	-

Returns

Promise<Annotation[]>

The patched annotations, in input order.

---

removePageAnnotation()

removePageAnnotation(page, name): Promise<void>;

Remove an annotation, identified by its name (NM), with what answers it — its replies, state notes and group members — and its popup.

Parameters

Parameter	Type	Description
page	number	Page index (0-based)
name	string	The annotation's name (NM).

Throws

If no annotation with the given name is found on the page.

---

goToPage()

goToPage(page): void;

Scroll the viewport to page index page (0-based, clamped to the pages composed).

Parameters

Parameter	Type
page	number

---

goToNextPage()

goToNextPage(): void;

Step to the next page, as the view controls' arrow does — the next spread's in spread scrolling. Nothing past the last page composed.

---

goToPrevPage()

goToPrevPage(): void;

Step to the previous page, as the view controls' arrow does — the previous spread's in spread scrolling. Nothing before the first.

---

goToSheet()

goToSheet(sheet): Promise<void>;

Show a sheet of the open workbook, as clicking its tab does: sheet is its 0-based index, as currentSheet counts it, or its name. Resolves once a frame showing it has painted, so an overlay drawn then lands on it; or once the view has moved on without it, another sheet chosen first or the document closed. Each sheet's pages count from 0, so goToPage moves within the sheet shown.

Rejects with no workbook open, an index past the last sheet, a name no sheet has, or a sheet that isn't visible — hidden or very hidden, it has no tab, and Excel shows it only once unhidden.

Parameters

Parameter	Type
sheet	string | number

---

goToDestination()

goToDestination(destination, options?): Promise<void>;

Follow a PDF destination, as clicking a link to it does: a named one resolves through the document's named destinations, and the view lands as its view asks — the point it lands where options.scrollAlignment says, else where setNavigationScrollAlignment does. Resolves once it has landed, or not: a name the document doesn't define, or a document that isn't a PDF, leaves the view.

Parameters

Parameter	Type
destination	Destination
options?	{ scrollAlignment?: ScrollAlignment; }

---

setNavigationScrollAlignment()

setNavigationScrollAlignment(alignment): void;

Set where a followed link or outline item, or a chosen comment, lands; see the navigationScrollAlignment option.

Parameters

Parameter	Type
alignment	ScrollAlignment

---

snapshot()

snapshot(): Promise<Uint8Array<ArrayBufferLike>>;

Serialize this one's CRDT for sync with a peer — feed the bytes to the peer's merge. The unit of collaboration; the transport is the caller's concern.

---

saveToBytes()

saveToBytes(format, strategy?): Promise<Uint8Array<ArrayBufferLike>>;

Save the open document as format, faithfully — the bytes reopen as the same document. format is one of the open doc type's own (a PDF saves to "pdf", a presentation to "pptx"); sourceFormat is what saving it back means. strategy is how much of the file it was opened from, the original, the saved bytes keep: a "delta" or "incremental" save writes over it, which a document opened with openRemote doesn't hold; without it, the one keeping the most of it that format saves by ("incremental" for a PDF, "rewrite" for a CSV, a TSV, a PSV or an image, else "delta"). Rejects for a format its doc type doesn't save to, a format that never saves by strategy, no original to write over, or a save that isn't built yet.

Parameters

Parameter	Type
format	FileFormat
strategy?	SaveStrategy

---

saveToPackage()

saveToPackage(version?): Promise<Uint8Array<ArrayBufferLike>>;

Save the open document as a udoc package — the bytes of a .udoc zip, which open reopens. It records the source format, so a reopened package can still be saved back to it. version makes it a checkpoint, baseline v<version>, which keeps the edit log a reopen replays; without it the package is a flat baseline — the whole document and no log.

Parameters

Parameter	Type
version?	number

---

requestRemoteCopy()

requestRemoteCopy(strategy?): Promise<Uint8Array<ArrayBufferLike>>;

Ask the udoc server the open document was opened from (openRemote) for a copy of it, saved as its source format by strategy, else by the engine's for it — a "delta" or "incremental" copy is the server's to save, since only it holds the original. Resolves with the copy's bytes. Rejects for a document not opened with openRemote, or one that records no source format, and with the server's message for what it refuses.

Parameters

Parameter	Type
strategy?	SaveStrategy

---

download()

download(filename?): Promise<void>;

Save the open document as its source format and hand it to the browser as a download named filename — default the name open was given, else document.<format>. What the toolbar's Download does.

It saves by the strategy that keeps the most of the original the format can: a PDF appends its edits as a new revision, so its signatures stay valid; an OOXML document writes its modified parts over the original; an image rewrites. A document opened with openRemote asks its server for that copy (requestRemoteCopy). Rejects as saveToBytes does.

Parameters

Parameter	Type
filename?	string

---

print()

print(options?): Promise<void>;

Print the open document through the browser's print dialog. Without options it opens its own print dialog first, to choose the pages and quality — what the toolbar's Print does; with them it prints as they say.

Every page of a PDF at "standard" quality prints as the PDF itself, saved as download saves it, through the browser's own viewer. Anything else prints rendered: each page rendered at the quality's DPI, one sheet each, with input held while they render — Cancel there stops the print. The print job is named after the file open was given. Rejects with no document open, one without pages (a spreadsheet), or a page index past its last page.

Parameters

Parameter	Type
options?	PrintOptions

---

renderPage()

renderPage(page, options?): Promise<ImageBitmap>;

Render page page — a 0-based index, as goToPage takes it — to an image, as the document now stands, at RenderPageOptions' scale. It renders off the viewport, so nothing on screen changes; a page not yet composed is composed first. Rejects with no document open, one without pages (a spreadsheet), or a page past its last.

Parameters

Parameter	Type
page	number
options?	RenderPageOptions

---

exportToBytes()

exportToBytes(format): Promise<Uint8Array<ArrayBufferLike>>;

Export the open document as format, "pdf" — a rendering of its laid-out pages as the document now stands, fixed and one-way, unlike saveToBytes, whose bytes reopen as the same document. Every page is composed first, and the fonts it names fetched, so none is drawn in a stand-in. Rejects with no document open, and with a UDocError whose code is "unsupported" for a spreadsheet, whose sheets have no print pages yet.

Parameters

Parameter	Type
format	ExportFormat

---

exportPageToBytes()

exportPageToBytes(page, format): Promise<Uint8Array<ArrayBufferLike>>;

Export page page — a 0-based index, as goToPage takes it — as the document now stands, as format: { png: { scale } }, the bytes of a PNG at scale image pixels per point (1 is 72 DPI), or "svg", an SVG document sized in points. Like renderPage, it renders off the viewport, and composes a page not yet composed first; unlike it, it fetches the fonts the page names first, so none is drawn in a stand-in. Rejects with no document open, a page past its last, or a scale that isn't a positive number.

Parameters

Parameter	Type
page	number
format	PageExportFormat

---

search()

search(query, options?): Promise<readonly SearchMatch[]>;

Search the open document for query, matching letter case only with caseSensitive, and — with fuzzy — comparing with separators dropped and typographic punctuation folded, so a quotation from another source still finds its text. scope limits the search to part of the document (a PDF's pages, a deck's slides, a workbook's sheet); without it the whole document is searched.

The matches arrive in document order, batch by batch, each firing "search:changed"; their highlights show on the pages, and the first match becomes current and is brought into view. Resolves with every match once the search has found them all — or with none when a newer search, clearSearch or an edit retires it. The search stays in force: an edit runs it again, and "search:changed" carries what that run finds. Each match carries its page, its highlight and the words around it.

Parameters

Parameter	Type
query	string
options?	SearchOptions & object

---

searchNext()

searchNext(options?): void;

Make the next match current, wrapping past the last, and bring it into view — where options.scrollAlignment says, else where setSearchScrollAlignment does.

Parameters

Parameter	Type
options?	{ scrollAlignment?: ScrollAlignment; }

---

searchPrev()

searchPrev(options?): void;

Make the previous match current, wrapping past the first, and bring it into view, as searchNext does.

Parameters

Parameter	Type
options?	{ scrollAlignment?: ScrollAlignment; }

---

setSearchActiveIndex()

setSearchActiveIndex(index, options?): void;

Make match index of searchMatches current and bring it into view, as searchNext does.

Parameters

Parameter	Type
index	number
options?	{ scrollAlignment?: ScrollAlignment; }

---

setSearchScrollAlignment()

setSearchScrollAlignment(alignment): void;

Set where a search match lands when it becomes current; see the searchScrollAlignment option.

Parameters

Parameter	Type
alignment	ScrollAlignment

---

clearSearch()

clearSearch(): void;

Drop the search: no query, no matches, no highlights.

---

searchMatchSelection()

searchMatchSelection(match): Promise<UDocSelection | null>;

The selection naming match's text — hand it to setSelection to select the match. Resolves null when nothing there can be selected (text inside a PDF group, a document changed since the search).

Parameters

Parameter	Type
match	SearchMatch

---

requestRemoteCheckpoint()

requestRemoteCheckpoint(): Promise<RemoteCheckpointResponse>;

Ask the udoc server the open document was opened from (openRemote) to checkpoint it: save its document as a new baseline. Resolves with that baseline's version. Nothing reopens: the document stays open as it was. Rejects for a document not opened with openRemote, and with the server's message for what it refuses.

---

versionVector()

versionVector(): Promise<Uint8Array<ArrayBufferLike>>;

Read this one's version vector — the per-peer op counts it holds. Hand the bytes to a peer's patchSince so it returns only the ops this one is missing; that delta goes to merge. The incremental counterpart to shipping a whole snapshot.

---

patchSince()

patchSince(peer): Promise<Uint8Array<ArrayBufferLike>>;

Compute the ops this one holds that a peer — identified by its versionVector bytes — does not. Feed the returned patch to that peer's merge.

Parameters

Parameter	Type
peer	Uint8Array

---

merge()

merge(data): Promise<void>;

Merge a peer's snapshot or patchSince and refresh the layout.

Parameters

Parameter	Type
data	Uint8Array

---

opaquePartsSince()

opaquePartsSince(peer): Promise<Uint8Array<ArrayBufferLike>>;

The content of every opaque part — an inserted picture's image, which the CRDT names but does not carry — this one holds whose write a peer, identified by its versionVector bytes, lacks. Send it ahead of the patchSince patch that names them, to the peer's mergeOpaqueParts; empty when there is nothing to send.

Parameters

Parameter	Type
peer	Uint8Array

---

mergeOpaqueParts()

mergeOpaqueParts(data): Promise<void>;

Hold a peer's opaquePartsSince content and refresh the layout.

Parameters

Parameter	Type
data	Uint8Array

---

presence()

presence(): Promise<Uint8Array<ArrayBufferLike>>;

Serialize this one's presence — its selection — for sync with a peer: the transient channel beside snapshot (last-write-wins, no history, never part of a save). Feed the bytes to a peer's mergePresence; see the "selection:changed" event for when.

---

mergePresence()

mergePresence(data): Promise<void>;

Merge a peer's presence. The peer's selection appears in the selection overlay, in a stable per-peer color. Does not fire "selection:changed", so a sync listener can't loop.

Parameters

Parameter	Type
data	Uint8Array

---

setUserInfo()

setUserInfo(name): void;

Set the local user's info — currently a display name, the label peers draw on this one's selection (beside the per-peer color), and the author of the annotations drawn here. Sticky: it survives a re-open and applies even when set before a document is open. Rides the presence channel, so it fires "selection:changed" (the cue to broadcast presence) and collaborators pick the name up on the next merge. An avatar and other fields can join the signature later.

Parameters

Parameter	Type
name	string

---

joinRemoteCollaboration()

joinRemoteCollaboration(url, name): void;

Join the collaboration a udoc server keeps for the open document, as name — the label peers draw on this one's selection, set as setUserInfo sets it. url is its collaboration resource, …/documents/{documentId}/collaboration. This one's edits and selection reach everyone else in it, and theirs reach this one; a lost connection is rejoined. The collaboration:* events say how it goes.

Leaves any collaboration already joined. The collaboration belongs to the open document: opening another or closing this one leaves it. Throws with no document open.

Parameters

Parameter	Type
url	string
name	string

---

joinLocalCollaboration()

joinLocalCollaboration(id, name): void;

Join the collaboration of the local collaboration service id, as name — as joinRemoteCollaboration joins a server's, with the document openLocal opened from it. Over the page, not a network, so it is never interrupted.

Leaves any collaboration already joined; opening another document or closing this one leaves it. Throws with no document open, or no service id — never started, or ended.

Parameters

Parameter	Type
id	string
name	string

---

leaveCollaboration()

leaveCollaboration(): void;

Leave the collaboration, local or remote — joined or paused; fires "collaboration:left" if joined. This one's selection and pointer leave the others' views at once, and theirs this one's. The last one joined to a local collaboration service leaving ends the service.

---

pauseCollaboration()

pauseCollaboration(): void;

Pause co-editing — what the people button's Pause does: leave the collaboration as leaveCollaboration does, firing "collaboration:left", but keep how to join it again; a local collaboration service stays up for it. Edits go on here, and there, apart. Does nothing unless joined.

---

resumeCollaboration()

resumeCollaboration(): void;

Resume co-editing paused: join the collaboration again, firing "collaboration:joined" once answered. What each side edited meanwhile merges both ways, so a pause loses no edit. Does nothing unless paused.

---

setEnablePointerSharing()

setEnablePointerSharing(enabled): void;

Share this one's pointer with the collaboration it joins, or stop sharing it — when it stops, the others' copy of it disappears. The initial value is set at construction via enablePointerSharing; the people button's menu switches it too.

Parameters

Parameter	Type
enabled	boolean

---

setOverlay()

setOverlay(
   id, 
   source, 
   options?
): void;

Register (or replace) a page-anchored HTML overlay under id: DOM chrome (corner buttons, inter-page dividers, comment pins) positioned over the canvas and kept pinned to the pages as they scroll and zoom. The viewport is painted in Rust; this is how a host adds interactive HTML on top of it. Multiple overlays render at once, stacked in registration order. The built-in chrome — the annotation bar and the comment popup among it — registers through this same surface under udoc:-prefixed ids, so a host can removeOverlay or replace the built-ins exactly like its own. Write an OverlaySource mapping each frame's pages to elements.

An overlay paints under the selection's boxes and handles, as the page chrome does; aboveSelection puts it over them, for chrome that belongs over the selected object — as the built-in annotation bar and comment popup do.

Parameters

Parameter	Type
id	string
source	OverlaySource
options?	OverlayOptions

---

removeOverlay()

removeOverlay(id): boolean;

Remove the overlay registered under id — including the built-ins (e.g. "udoc:annotation-bar"). Returns false if unknown.

Parameters

Parameter	Type
id	string

---

setTheme()

setTheme(theme): void;

Set the color theme: "light", "dark", or "system" (follows the OS prefers-color-scheme). Restyles the chrome and recolors the engine-painted viewport backdrop to match.

Parameters

Parameter	Type
theme	ThemeMode

---

setFullscreen()

setFullscreen(fullscreen): Promise<void>;

Fill the screen with the document UI, or leave it, as the toolbar menu's Fullscreen button does. The browser enters fullscreen only in answer to a user gesture, so call it from the host's own click handler; the promise rejects when the browser refuses. Leaving resolves at once when it isn't fullscreen.

Parameters

Parameter	Type
fullscreen	boolean

---

setScrollMode()

setScrollMode(mode): void;

Scroll one spread at a time ("spread") or continuously ("continuous") — the view settings' Scroll section.

Parameters

Parameter	Type
mode	ScrollMode

---

setLayoutMode()

setLayoutMode(mode): void;

Group the pages into spreads, shown side by side, as mode says — the view settings' Layout section. PDF and Word documents only; any other shows single pages.

Parameters

Parameter	Type
mode	LayoutMode

---

setPageRotation()

setPageRotation(rotation): void;

Turn every page rotation degrees clockwise on top of its own — the view settings' Rotation section. A view setting: the document is unchanged, and nothing is saved or shared with collaborators. PDF and Word documents only; any other shows its pages upright.

Parameters

Parameter	Type
rotation	0 | 90 | 180 | 270

---

setPageGap()

setPageGap(gap): void;

Set the gaps between pages, in document points — horizontal between the pages of a spread, vertical from one spread to the next; null restores the built-in gaps.

Parameters

Parameter	Type
gap	PageGap | null

---

setFit()

setFit(fit): void;

Fit the open document by fit, and open every later one by it; null restores each doc type's default fit. The zoom menu still picks a fit for the open document alone.

Parameters

Parameter	Type
fit	Fit | null

---

setZoom()

setZoom(zoom): void;

Zoom the open document to zoom — 1 is 100% — dropping its fit, as the zoom menu does. Clamped to the bounds setMinZoom and setMaxZoom set.

Parameters

Parameter	Type
zoom	number

---

zoomIn()

zoomIn(): void;

Zoom to the next zoom step above the zoom on screen; a no-op at the top step.

---

zoomOut()

zoomOut(): void;

Zoom to the next zoom step below the zoom on screen; a no-op at the bottom step.

---

setMinZoom()

setMinZoom(zoom): void;

Set the lowest explicit zoom; an explicit zoom below it rises to it.

Parameters

Parameter	Type
zoom	number

---

setMaxZoom()

setMaxZoom(zoom): void;

Set the highest explicit zoom; an explicit zoom above it drops to it.

Parameters

Parameter	Type
zoom	number

---

setDpi()

setDpi(dpi): void;

Set the screen's CSS px per physical inch, which 100% is measured against — the dpi option, for a calibration made while it runs. The zoom stays, so the page shows at the same zoom in its new size.

Parameters

Parameter	Type
dpi	number

---

openPanel()

openPanel(panel): void;

Open the side panel panel, in place of whichever is open. Ignored for a panel the options hide — or the open document's type offers none of, or whose whole side is hidden.

Parameters

Parameter	Type
panel	PanelTab

---

closePanel()

closePanel(): void;

Close the open side panel, if any.

---

setViewControlsPlacement()

setViewControlsPlacement(placement): void;

Dock the view-state controls (page nav + zoom + view settings) in the top toolbar ("top-toolbar"), the bottom floating bar ("floating", the default), or the bottom status bar ("status-bar"). The initial value is set at construction via viewControlsPlacement.

Parameters

Parameter	Type
placement	ViewControlsPlacement

---

on()

on<K>(event, handler): () => void;

Subscribe to an event (e.g. "currentPage:changed"). Returns an unsubscribe function. See UDocEvents for events + payloads.

Type Parameters

Type Parameter
K extends keyof UDocEditorEvents

Parameters

Parameter	Type
event	K
handler	EventHandler<UDocEditorEvents, K>

Returns

() => void

---

off()

off<K>(event, handler): void;

Unsubscribe a handler previously registered with on.

Type Parameters

Type Parameter
K extends keyof UDocEditorEvents

Parameters

Parameter	Type
event	K
handler	EventHandler<UDocEditorEvents, K>

---

close()

close(): void;

Close the current document.