Architecture and lifecycle

Editor SDK connects the browser to the Office editor to send requests and receive results. First open the document with an Office open URL. The SDK's save() requests a save from Office; Office and the storage adapter handle writing the file and authenticating storage access. Reopen the source file to verify that your changes were saved.

Request flow

Each request receives a unique message ID. The SDK stores a pending Promise until the matching result arrives or the timeout expires. Responses must come from the configured editor origin and use the expected Thinkfree envelope.

Entry points

Entry point	Returns	Use when
Office.word(iframe, options?), Office.cell(…), Office.show(…)	WordApp / CellApp / ShowApp (OfficeApp<M>)	Recommended - you have the iframe element
createOffice(options)	Office<M>	You need explicit options or a targetWindow

Office.* is a get-or-create facade over createOffice: the same iframe returns the same handle until disconnect(), the origin is derived from iframe.src, and the handle adds whenReady() on top of getDocument(), getTools(), and execute().

Office.* options (OfficeAppOptions)

Option	Required	Description
frameworkOrigin	No	Editor origin; derived from iframe.src when omitted. Required for data:/blob: or missing src
timeoutMs	No	Per-request timeout; default is 5,000 ms

createOffice() options (OfficeOptions)

Option	Required	Description
module	Yes	word, cell, or show
frameworkOrigin	Yes	Exact editor origin; * is rejected
iframeEl	One of two	Iframe whose contentWindow receives commands
targetWindow	One of two	Explicit target window for a non-iframe topology
timeoutMs	No	Per-request timeout; default is 5,000 ms

Handle members

module, execute(method, params?), getDocument(), getTools(options?), registerTools(modelContext, options?), getToolSchemas(), getSystemPrompt(), disconnect(), and - on app handles only - whenReady(limitMs?).

Document handles

getDocument() returns a Proxy handle, not a serialized document. The handle stores identity or navigation information and resolves the current Office object when a method runs.

• Word (word) and Presentation (show) use identity-based proxy handles: every method is one round trip.
• Spreadsheet (cell) navigation such as getTable().getRange() builds a path locally; the terminal call resolves it. getWorksheet() is not part of it - it resolves the sheet on the call itself.
• Handle arguments are serialized as proxy descriptors when passed to other methods.
• Returned proxy descriptors are converted back into handles.

Do not serialize handles into application storage or treat them as durable IDs.

Lifecycle rules

1. Load an Office open URL in the iframe.
2. Obtain one app handle for that iframe and module (Office.word(iframe)).
3. Wait until the editor can answer SDK commands (await app.whenReady()).
4. Execute document operations.
5. Save through Office when required (save() on Word and Presentation documents).
6. Call disconnect() before discarding the iframe or changing its src to another document or module.

Calling a handle method after disconnect() fails with code 1003 (DESTROYED). Disconnecting with outstanding requests also rejects those requests so callers do not remain pending indefinitely. Binding the same iframe to a different module without disconnecting first fails with INVALID_ARGUMENT.

Security boundary

• The editor origin is taken from iframe.src or your frameworkOrigin option; do not accept it from arbitrary user input.
• Allow only trusted Office origins in the host application and editor configuration.
• Treat the document-open URL as sensitive when it grants access to a document.
• The SDK validates event.origin on every message and never posts to *.
• Do not place API keys, storage credentials, or Office signing keys in public runtime config.

Editor SDK does not authenticate the user or grant document access. Authorize the user and obtain the document-open URL before connecting.