In short
Most applications that only load and display documents do not need source changes. Review the sections below if your code uses XLSX selection, selection context, removed option or type names, OOXML MCP tools, or Viewer onError callbacks.
v0.77 deliberately removes short-lived compatibility surfaces instead of maintaining two APIs for the same operation. Update the affected calls before upgrading; there are no temporary aliases for the removed names.
- XLSX selection: replace select(), selection and onSelectionChange with setSelection(), selectionState and onSelectionStateChange.
- Selection context: check context.kind before reading text, cell-range or element details.
- Element selection: opt in with enableElementSelection to select charts, pictures and shapes and show their non-editable outline.
- Context menus: use onContextMenu and await getContext(); originalEvent remains available synchronously for preventDefault().
- MCP: use the consolidated active-context and replacement format tools; removed subset tools are not retained as aliases.
- API cleanup: remove non-functional options and exact aliases, and stop passing load-only or render-only options to APIs that cannot use them.
- Errors: awaitable Viewer methods reject; onError is reserved for Viewer-managed background work with no Promise to await.
Why these changes ship together
The old XLSX API described only one range and could not preserve all Excel selection details. DOCX and PPTX also lacked a consistent way to pass selected text or objects to another application. v0.77 gives all three formats explicit selection and a size-limited copy of the selected content.
The MCP and error-handling changes follow the same approach: each task now has one supported API, and asynchronous methods report errors through their returned Promise.
Replace the XLSX selection compatibility API
The previous select(), selection, onSelectionChange, CellRange and SelectionMode exports are removed. They could not represent Excel’s separate selected areas, ActiveCell and Shift-extension anchor without overloading one range value.
Use setSelection(), selectionState, onSelectionStateChange, XlsxSelectionState and XlsxSelectionArea. A1 strings remain accepted by setSelection() for the common single-range case.
Replace CellRange values with XlsxSelectionState, and describe each selected region with XlsxSelectionArea. If you constructed SelectionMode values directly, the old cols and all modes correspond to the new columns and sheet area kinds.
Before
const viewer = new XlsxViewer(container, {
onSelectionChange(range) {
updateSelection(range);
},
});
viewer.select('B2:D6');After
const viewer = new XlsxViewer(container, {
onSelectionStateChange(state) {
updateSelection(state);
},
});
viewer.setSelection('B2:D6');Check context.kind before reading selection details
The DocxSelectionContext and XlsxSelectionContext types can now contain selected text, XLSX cells, or an element such as a chart or picture. Check context.kind first so TypeScript knows which details are available.
The native DOCX helper readDocxSelectionContext() is renamed to readDocxTextSelectionContext() because it reads only a DOM text selection. Use DocxViewer.getSelectionContext() for the text-or-element union.
PptxElementSelectionContext is renamed to PptxElementContext. The data shape is unchanged, and the new name also fits direct point queries where no Viewer selection exists.
Read a cross-format context safely
const context = viewer.getSelectionContext();
if (context?.kind === 'text') {
consumeText(context.text);
} else if (context?.kind === 'range') {
consumeCells(context.cells);
} else if (context?.kind === 'element') {
consumeElement(context.elementType);
}Replace removed MCP subset tools
Normal VS Code use does not require a manual change. Update only custom prompts, tool allowlists, or other integrations that refer to one of the removed tool names.
Use ooxml_get_active_context for the active OOXML preview and its current text, range or element context. This replaces the earlier active-selection tool name and keeps one routing entry point for all three formats.
- Replace xlsx_get_sheet_names with xlsx_parse.
- Replace docx_get_paragraph with docx_get_body_element.
- Replace pptx_get_shape and pptx_get_shape_text with pptx_get_element.
- Replace ooxml_get_active_selection with ooxml_get_active_context.
Remove unused rendering options
DOCX showTrackChanges is removed from browser and Node render options because the retained paint pipeline never consulted it; true and false produced identical pixels. Tracked revisions continue to render as they do today, but the library no longer advertises a non-functional Final / No Markup switch.
Borrowed Viewer factories no longer accept load-only mode because they use the mode of the document that is already loaded. DocxDocument.collectPageRuns() now accepts only width and currentDate. PptxPresentation.presentSlide() no longer accepts skipMediaControls.
XlsxWorkbook.renderViewport() no longer accepts fetchImage or loadedImages because the workbook owns its image loading and cache.
Use public rendering option types
Use XlsxRenderViewportOptions with XlsxWorkbook.renderViewport() and RenderViewportToBitmapOptions with renderViewportToBitmap(). Use CollectPageRunsOptions with DocxDocument.collectPageRuns().
WireRenderPageOptions, WireRenderViewportOptions and WireSizeOverrides were internal worker-message types and are no longer exported.
Rename exported type aliases
Replace XlsxChartSeries, SeriesDataLabels, DataLabelOverride, DataPointOverride, ErrBars and ManualLayout with ChartSeries, ChartSeriesDataLabels, ChartDataLabelOverride, ChartDataPointOverride, ChartErrBars and ChartManualLayout.
Replace OoxmlErrorSource with OoxmlErrorStage. Rename old stage values as follows: zip-part → decompression, parser → parsing, serializer → serialization and renderer → rendering.
Password-protected files now load through Viewers
No source change is needed. Existing Viewer code that supplies LoadOptions.password now works as the public API already promised.
Catch every awaitable Viewer failure
Viewer load() and onError no longer form alternative completion channels. load(), navigation and every other public method that returns a Promise reject that Promise on failure, even when onError is configured. The same failure is never delivered twice.
Keep onError only when the application needs failures from Viewer-managed work that has no Promise to await, such as later virtualized rendering or embedded-media playback.
Separate awaited and background failures
const viewer = new DocxViewer(canvas, {
onError(error) {
reportBackgroundFailure(error);
},
});
try {
await viewer.load(file);
} catch (error) {
showLoadFailure(error);
}