🔄 Sync stable → main#3394
Merged
Merged
Conversation
Based on my exploration of the changes, here are the release notes for v1.11.0: ### What's New - **Wrapper packages declare superdoc as direct dependency** — `@superdoc-dev/template-builder` and `@superdoc-dev/esign` now include SuperDoc as a regular dependency, not just a peer dependency. This ensures automatic installation of compatible versions when these wrappers serve as your SuperDoc entrypoint. ### Fixes - **Toolbar serialization prevents unnecessary re-renders** — Inline toolbar configuration objects are now properly memoized, preventing SuperDoc from reinitializing on every parent component render.
The catch wrapping resolveSelectionTarget in metadataAttachWrapper
collapsed every error to INVALID_TARGET. resolveSelectionTarget
actually distinguishes:
- missing blockId / node: DocumentApiAdapterError('TARGET_NOT_FOUND', ...)
- bad offset / shape error: DocumentApiAdapterError('INVALID_TARGET', ...)
metadata.attach explicitly declares possibleFailureCodes:
['TARGET_NOT_FOUND', 'INVALID_TARGET', 'INVALID_INPUT'], so the
collapse silently changed a documented failure mode into the wrong
code and misled clients that branch on it (missing target is
retryable; bad shape is a programming error).
Catch now preserves DocumentApiAdapterError.code for the two
documented codes and falls through to INVALID_TARGET for anything
else (defensive default).
Two new wrapper tests lock in the distinction:
- Missing blockId returns TARGET_NOT_FOUND.
- Out-of-range offset returns INVALID_TARGET.
This is landing on the main-into-stable merge PR so the release
ships with the correct contract; cherry-pick to main follows in a
separate PR.
…6-05-19 Merge main into stable
### What's New
**Metadata API** — Anchor JSON payloads to text ranges with `editor.doc.metadata.attach()`, `list()`, `get()`, `update()`, `remove()`. Backed by hidden inline content controls and Custom XML storage.
**Custom XML storage operations** — Manage Custom XML Data Storage Parts with full CRUD: `editor.doc.customXml.parts.list()`, `get()`, `create()`, `patch()`, `remove()`. Round-trips through .docx export with complete package coordination.
**Content controls viewport integration** — Hit-test and anchor contextual UI to content controls. `ui.contentControls.getRect({ id })` returns painted bounds without DOM scraping.
**Paragraph direction commands** — Set paragraph direction with `editor.commands.setParagraphDirection({ direction })`. Alignment mirrors automatically in RTL. Headless toolbar via `controller.execute('direction-ltr'/'direction-rtl')`.
**Table of Contents toolbar button** — Insert and update TOCs from the UI with overflow menu and schema validation.
**Table RTL rendering** — Tables with `w:bidiVisual` now render cell order, borders (`tblBorders`/`tcBorders` start/end sides), and padding (`w:tcMar`) correctly. Arrow-key navigation respects visual direction.
**RTL mixed-bidi backspace** — Backspace at run boundaries between RTL and LTR text now produces correct direction markup.
**Format painter Word parity** — Format painter UX and state calculation now matches Microsoft Word behavior, including in headless mode.
### Improvements
**Type system precision** — Drained 26 instances of `any` from public API: `EditorTransactionEvent.transaction` now `Transaction`, `Config.onAwarenessUpdate.states` now `AwarenessState[]`, error causes now `unknown`.
**Direction context architecture** — Direction now resolves through typed per-axis contexts (paragraph, table, cell, section) per ECMA-376. Section bidi no longer forces paragraph direction; table bidi no longer affects cell paragraphs.
**Font theme preservation** — Run font theme references (`w:asciiTheme`, `w:hAnsiTheme`, etc.) survive user formatting and export round-trip correctly.
**Content control appearance** — Hidden content controls (`w15:appearance="hidden"`) render without visible chrome or alias text, enabling invisible anchors.
**Tracked change comment threading** — User comments anchored to tracked changes thread under the TC bubble on re-import. Accepting/rejecting a TC cascades to anchored comments.
**Table cell margin precedence** — Cell-level `w:tcMar` margins correctly override table defaults. Mixed logical/physical families resolve to physical LTR-default.
**Search match visibility** — Highlights now win over inline highlight marks via `!important`. Cross-page scrolling accounts for DOM and selection updates.
**EMF+ image rendering** — Images embedded in EMF+ payloads (Office charts, slides) extract and render via PNG/JPEG instead of placeholder. Raw pixel formats decode via canvas.
**Run metadata preservation** — TextRun now preserves run-level direction (`w:rtl`) and script (`w:cs`, `w:lang`) for future formatting stack decisions.
**Text direction hit-testing** — Hit-testing separates writing-mode (vertical/horizontal) from inline direction (RTL), fixing targets on vertical-text documents.
**Content control typing** — Typeless `w:sdt` elements resolve to `'richText'` per spec instead of `'unknown'`.
**Indent robustness** — Increase/Decrease Indent no longer crash on fresh paragraphs; style-derived indent honored on cache miss.
**RTL date rendering** — RTL-tagged date text injects directional marks so mixed-direction dates render in correct visual order.
**Slash menu UX** — Menu closes on Escape (re-inserts `/`), Backspace (removes `/`), allows immediate re-open without cooldown.
**Rich-text default** — New content controls default to `'richText'` with explicit `<w:richText/>` in markup.
### Fixes
- Metadata error codes properly distinguished (`TARGET_NOT_FOUND` vs `INVALID_TARGET`)
- Large image upload and resize now works in headers/footers
- SVG images import with correct MIME type
- Paragraph margin floats round to integers on export per ECMA-376
- Default run properties no longer injected on round-trip when absent in source
- Table diffing gates paragraph identity on depth, preventing cell↔body mispairing
- Table visual direction only forced by inline `w:bidiVisual`, not style cascade
- Comment range markers preserved as siblings to unpaired tracked changes
- Toolbar dropdown focus restored on Escape, allowing Enter to reopen
- Paragraph writing-mode now inherits from body section when omitted
- Locked content controls now mutable via document-api using attribute steps
- Hyperlink `w:rStyle="CommentReference"` preserved on anchor runs through round-trip
- Content-locked inline SDTs now selectable and deletable with single click/Delete
- Hebrew/Arabic presentation forms recognized as strong-RTL in mixed-bidi detection
- Native selection caret refinement gated to local caret only
- Metadata dry-run now throws `REVISION_MISMATCH` on stale revision instead of false-success
### What's New
**Metadata API** — Anchor JSON payloads to text ranges with `editor.doc.metadata.attach()`, `list()`, `get()`, `update()`, `remove()`. Backed by hidden inline content controls and Custom XML Data Storage Parts.
**Custom XML operations** — Full CRUD for Custom XML Data Storage Parts via `editor.doc.customXml.parts.list()`, `get()`, `create()`, `patch()`, `remove()` with complete OOXML package coordination.
**Content controls viewport surface** — `ui.contentControls.getRect({ id })` returns painted bounds. Query active controls via React hook `useSuperDocContentControls()` or `ui.contentControls.get()`.
**Paragraph direction controls** — `editor.commands.setParagraphDirection({ direction })` sets LTR/RTL with automatic alignment mirroring. Headless toolbar via `controller.execute('direction-ltr'/'direction-rtl')`.
**Table of Contents toolbar button** — Insert and update TOCs from the UI with overflow menu and schema validation.
**Table RTL rendering** — Tables with `w:bidiVisual` now render cell order, borders, and padding correctly. Arrow-key navigation respects visual direction.
**RTL mixed-bidi backspace** — Backspace at run boundaries between RTL and LTR text produces correct direction markup.
**Format painter Word parity** — Format painter UX and state calculation now matches Microsoft Word, including headless mode.
**Type precision** — Drained 26 instances of `any` from public API. `EditorTransactionEvent.transaction` now `Transaction`, `Config.onAwarenessUpdate.states` now `AwarenessState[]`, error causes now `unknown`.
### Improvements
**Font theme preservation** — Run font theme references (`w:asciiTheme`, `w:hAnsiTheme`, etc.) survive user formatting and export round-trip.
**Content control appearance** — Hidden content controls (`w15:appearance="hidden"`) render without visible chrome or alias text, enabling invisible anchors.
**Tracked change comment threading** — User comments anchored to tracked changes thread under the TC bubble on re-import. Accept/reject cascades to anchored comments.
**Table cell margin precedence** — Cell-level `w:tcMar` margins correctly override table defaults. Logical/physical families resolve to physical LTR-default.
**Search match visibility** — Highlights win over inline background marks via `!important`. Cross-page scrolling accounts for DOM and selection updates.
**EMF+ image rendering** — Images embedded in EMF+ payloads (Office charts, slides) extract and render via PNG/JPEG instead of placeholder. Raw pixel formats decode via canvas.
**Run metadata preservation** — TextRun preserves run-level direction (`w:rtl`) and script (`w:cs`, `w:lang`) for future formatting decisions.
**Text direction hit-testing** — Hit-testing separates writing-mode (vertical/horizontal) from inline direction (RTL), fixing targets on vertical-text documents.
**Content control typing** — Typeless `w:sdt` elements resolve to `'richText'` per spec, not `'unknown'`.
**Indent robustness** — Increase/Decrease Indent no longer crash on fresh paragraphs; style-derived indent honored on cache miss.
**RTL date rendering** — RTL-tagged date text injects directional marks for correct visual order in mixed-direction dates.
**Slash menu UX** — Menu closes on Escape (re-inserts `/`), Backspace (removes `/`), allows immediate re-open without cooldown. Shows search header and empty state during active filter.
**Large image upload in headers/footers** — Image resize and insertion now works reliably in header and footer contexts.
**SVG image MIME type** — SVG images import with correct `image/svg+xml` type.
**Paragraph writing-mode inheritance** — Paragraph `w:textDirection` inherits from body section when omitted.
**Textbox image rendering** — Images inside Word textboxes now render alongside text; hidden textbox drawings stay hidden.
### Fixes
**Metadata error codes** — `TARGET_NOT_FOUND` and `INVALID_TARGET` now properly distinguished; `metadata.attach` no longer collapses all errors to `INVALID_TARGET`.
**Metadata dry-run revision check** — `metadata.attach` and `metadata.remove` validate `expectedRevision` on dry-run, throwing `REVISION_MISMATCH` on stale instead of false-success.
**Paragraph margin normalization** — Paragraph margin floats round to integers on export per ECMA-376 `ST_TwipsMeasure`.
**Table diffing** — Paragraph identity gated on structural depth, preventing cell↔body mispairing on structural + text changes.
**Table visual direction cascade** — Table visual direction only forced by inline `w:bidiVisual`, not style cascade.
**Comment range markers** — Comment range markers preserved as siblings to unpaired tracked changes.
**TC-comment parent linking** — `trackedChangeParentId` now correctly points at actual TC marks; parallel id-map collisions fixed.
**TC cascade resolve** — Accepting/rejecting a tracked change cascades to all anchored user comments via filtered per-document resolution.
**TC reply threading** — Replies under TC bubbles thread correctly on re-import regardless of `commentsExtended.xml` presence.
**TC color on comments** — TC insertion/deletion color preserved on anchored comments.
**Hyperlink rStyle** — Hyperlink `w:rStyle="CommentReference"` preserved on anchor runs through round-trip.
**Content-locked SDT mutability** — Locked content controls now mutable via document-api using AttrSteps; false-success no-ops on `setValue`, `replaceContent` eliminated.
**Inline SDT selection** — Content-locked inline SDTs now selectable and deletable with single click/Delete.
**Hebrew/Arabic presentation forms** — Presentation forms (FB1D-FB4F, FB50-FDFF, FE70-FEFF) recognized as strong-RTL in mixed-bidi detection.
**Native selection caret** — Native caret refinement gated to local caret only; remote cursors and vertical-arrow probes no longer hijacked.
**Toolbar dropdown focus** — Dropdown focus restored on Escape, allowing Enter to reopen.
**Formatting marks button** — Now hidden by default and opt-in via `modules.toolbar.showFormattingMarksButton` config.
**Find input focus** — Find input focus restored after match navigation, allowing repeated Enter/Shift+Enter to advance.
**Bold/italic complex-script** — `boldCs`/`italicCs` no longer auto-propagated from bold/italic marks; only preserved when explicitly present.
**Numbering.xml round-trip** — Tentative (unused) numbering definitions preserved on export. Default numbering omitted on blank docs.
**Default run properties export** — bCs/iCs/highlight `w:val="none"` no longer injected on round-trip when absent in source.
**Themed run override** — User font changes on themed runs now respected; themed references no longer restored over user choice.
**Temporary flag import** — `<w:temporary/>` and `w:val` states parsed correctly; property surfaces in API.
**Cell margin key family** — Cell-level `w:tcMar` logical/physical key family preserved; no duplicate left/right from logical start/end.
**Table cell margin resolution** — Cell-level `w:tcMar` correctly overrides table-level `w:tblCellMar` per ECMA-376 precedence.
**Explicit bidiVisual false** — `w:bidiVisual w:val="0"` preserved on export, resolves to `visualDirection: 'ltr'` overriding style.
**Table borders/padding mirror** — Logical start/end stored as LTR-default physical; painter owns single visual mirror, eliminating double-mirror bugs.
**Table indent RTL** — Table indent (`w:tblInd`) anchors to right edge in RTL per spec.
**RTL alignment mirrors** — Paragraph alignment (left/right) mirrors stored OOXML justification in RTL context.
**RLM injection for dates** — RTL date text injects RLM (U+200F) around separators for visual reordering parity with Word.
**Paragraph direction resolution** — Paragraph direction resolves through typed directionContext per spec; section bidi MUST NOT cascade to paragraph (spec violation fixed).
**CommentReference rStyle** — Synthesized comment anchor runs emit canonical `<w:rStyle w:val="CommentReference"/>`.
**Track changes initialization race** — `getTrackChanges` now null-safe against pre-initialization state.
**Hyperlink field preservation** — Hyperlink fields split across boundaries preserve mark on constructed TC wrappers.
**Paste URL unlink** — Paste-added underline now tagged for removal on unlink; no stray formatting.
**Block SDT delete** — Delete key removes block SDTs when cursor at first text position.
**TOC sanitizer recursion** — TOC sanitizer recurses into nested marks; `tocPageNumber` filtered regardless of depth.
**Text offset readback** — Position readback uses flattened offset model matching write side; `editor.doc.bookmarks.list()` offsets round-trip correctly.
### What's New
**Metadata API** — Anchor JSON payloads to text ranges with `editor.doc.metadata.attach()`, `list()`, `get()`, `update()`, `remove()`. Hidden inline content controls + Custom XML Data Storage Parts handle the storage.
**Custom XML storage operations** — Full CRUD for Custom XML Data Storage Parts via `editor.doc.customXml.parts.list()`, `get()`, `create()`, `patch()`, `remove()`. Coordinates the entire .docx package on read and write.
**Content controls viewport surface** — `ui.contentControls.getRect({ id })` returns painted bounds. Query active controls via `useSuperDocContentControls()` React hook or `ui.contentControls.get()`.
**Paragraph direction commands** — `editor.commands.setParagraphDirection({ direction })` sets LTR/RTL with automatic alignment mirroring. Headless toolbar via `controller.execute('direction-ltr'/'direction-rtl')`.
**Table of Contents toolbar button** — Insert and update TOCs from the UI with schema validation and overflow menu support.
**Table RTL rendering** — Tables with `w:bidiVisual` now render cell order, borders, and padding correctly. Arrow-key navigation respects visual direction.
**RTL mixed-bidi backspace** — Backspace at run boundaries between RTL and LTR text produces correct direction markup.
**Format painter Word parity** — Format painter UX and state calculation now match Microsoft Word, including headless mode.
### Improvements
**Type precision** — Drained 26 instances of `any` from public API. `EditorTransactionEvent.transaction` now `Transaction`, `Config.onAwarenessUpdate.states` now `AwarenessState[]`, error causes now `unknown`.
**Font theme preservation** — Run font theme references (`w:asciiTheme`, `w:hAnsiTheme`, etc.) survive user formatting and export round-trip.
**Content control appearance** — Hidden content controls render without visible chrome or alias text, enabling invisible anchors.
**Tracked change comment threading** — User comments anchored to tracked changes thread under the TC bubble on re-import. Accept/reject cascades to anchored comments.
**Table cell margin precedence** — Cell-level `w:tcMar` margins correctly override table defaults. Logical/physical families resolve to physical LTR-default.
**Search match visibility** — Highlights win over inline background marks via `!important`. Cross-page scrolling accounts for DOM and selection updates.
**EMF+ image rendering** — Images embedded in Office charts and slides extract and render via PNG/JPEG instead of placeholder. Raw pixel formats decode via canvas.
**Run metadata preservation** — TextRun preserves run-level direction and script for future formatting decisions.
**Text direction hit-testing** — Hit-testing separates writing-mode from inline direction, fixing targets on vertical-text documents.
**Content control typing** — Typeless `w:sdt` elements resolve to `'richText'` per spec, not `'unknown'`.
**Indent robustness** — Increase/Decrease Indent no longer crash on fresh paragraphs; style-derived indent honored on cache miss.
**RTL date rendering** — RTL-tagged date text injects directional marks for correct visual order in mixed-direction dates.
**Slash menu UX** — Menu closes on Escape (re-inserts `/`), Backspace (removes `/`), allows immediate re-open without cooldown. Shows search header and empty state during active filter.
**Large image upload in headers/footers** — Image resize and insertion now works reliably in header and footer contexts.
**SVG image MIME type** — SVG images import with correct `image/svg+xml` type.
**Paragraph writing-mode inheritance** — Paragraph `w:textDirection` inherits from body section when omitted.
**Textbox image rendering** — Images inside Word textboxes now render alongside text; hidden textbox drawings stay hidden.
**Direction context architecture** — Direction now resolves through typed per-axis contexts (paragraph, table, cell, section) per OOXML spec.
**Block SDT deletion** — Delete key removes block SDTs when cursor at first text position.
**Locked content control mutability** — Locked content controls now mutable via document-api using attribute steps; false-success no-ops eliminated.
**Inline SDT selectability** — Content-locked inline SDTs now selectable and deletable with single click/Delete.
### Fixes
**Metadata error codes** — `TARGET_NOT_FOUND` and `INVALID_TARGET` now properly distinguished; `metadata.attach` no longer collapses all errors to `INVALID_TARGET`.
**Metadata dry-run revision check** — `metadata.attach` and `metadata.remove` validate `expectedRevision` on dry-run, throwing `REVISION_MISMATCH` on stale instead of false-success.
**Paragraph margin normalization** — Paragraph margin floats round to integers on export per ECMA-376 `ST_TwipsMeasure`.
**Table diffing** — Paragraph identity gated on structural depth, preventing cell↔body mispairing on structural + text changes.
**Table visual direction cascade** — Table visual direction only forced by inline `w:bidiVisual`, not style cascade.
**Comment range markers** — Comment range markers preserved as siblings to unpaired tracked changes.
**TC-comment parent linking** — `trackedChangeParentId` now correctly points at actual TC marks; parallel id-map collisions fixed.
**TC cascade resolve** — Accepting/rejecting a tracked change cascades to all anchored user comments via filtered per-document resolution.
**TC reply threading** — Replies under TC bubbles thread correctly on re-import regardless of `commentsExtended.xml` presence.
**TC color on comments** — TC insertion/deletion color preserved on anchored comments.
**Hyperlink rStyle** — Hyperlink `w:rStyle="CommentReference"` preserved on anchor runs through round-trip.
**Hebrew/Arabic presentation forms** — Presentation forms recognized as strong-RTL in mixed-bidi detection.
**Native selection caret** — Native caret refinement gated to local caret only; remote cursors and vertical-arrow probes no longer hijacked.
**Toolbar dropdown focus** — Dropdown focus restored on Escape, allowing Enter to reopen.
**Formatting marks button** — Now hidden by default and opt-in via `modules.toolbar.showFormattingMarksButton` config.
**Find input focus** — Find input focus restored after match navigation, allowing repeated Enter/Shift+Enter to advance.
**Bold/italic complex-script** — `boldCs`/`italicCs` no longer auto-propagated from bold/italic marks; only preserved when explicitly present.
**Numbering.xml round-trip** — Tentative numbering definitions preserved on export. Default numbering omitted on blank docs.
**Default run properties export** — bCs/iCs/highlight `w:val="none"` no longer injected on round-trip when absent in source.
**Themed run override** — User font changes on themed runs now respected; themed references no longer restored over user choice.
**Temporary flag import** — `<w:temporary/>` and `w:val` states parsed correctly; property surfaces in API.
**Cell margin key family** — Cell-level `w:tcMar` logical/physical key family preserved; no duplicate left/right from logical start/end.
**Table cell margin resolution** — Cell-level `w:tcMar` correctly overrides table-level `w:tblCellMar` per ECMA-376 precedence.
**Explicit bidiVisual false** — `w:bidiVisual w:val="0"` preserved on export, resolves to `visualDirection: 'ltr'` overriding style.
**Table borders/padding mirror** — Logical start/end stored as LTR-default physical; painter owns single visual mirror, eliminating double-mirror bugs.
**Table indent RTL** — Table indent anchors to right edge in RTL per spec.
**RTL alignment mirrors** — Paragraph alignment mirrors stored OOXML justification in RTL context.
**CommentReference rStyle** — Synthesized comment anchor runs emit canonical `<w:rStyle w:val="CommentReference"/>`.
**Track changes initialization race** — `getTrackChanges` now null-safe against pre-initialization state.
**Hyperlink field preservation** — Hyperlink fields split across boundaries preserve mark on constructed TC wrappers.
**Paste URL unlink** — Paste-added underline now tagged for removal on unlink; no stray formatting.
**TOC sanitizer recursion** — TOC sanitizer recurses into nested marks; `tocPageNumber` filtered regardless of depth.
**Text offset readback** — Position readback uses flattened offset model matching write side; `editor.doc.bookmarks.list()` offsets round-trip correctly.
### What's New **Content Controls as first-class viewport entities** — Hit-test and retrieve rendered rects for SDTs without DOM attribute scraping. Enables custom UI overlays and smart field chips without duplicating position logic. **ContentControls handle with React hook** — Read-only programmatic access to the active set, cached list, and individual control info. Mirrors the existing comments and tracked-changes surfaces. **Metadata API for anchored payloads** — Document API operations on bookmarks, comments, tracked changes, and content controls now support anchored metadata: `attach`, `remove`, `update` with revision safety and dry-run preview. **Custom XML parts CRUD** — Create, patch, remove, and list custom XML data storage parts through the Document API. Full OOXML package coordination with proper rels, properties, and content-type management. (Phase A; dry-run support tracked separately.) **RTL table support** — Paragraph direction toolbar buttons (headless API). Visual direction context for tables with proper border/margin mirroring per ECMA-376. Logical cell-margin start/end mapping to physical padding. **TOC toolbar item** — Add, update, and manage tables of contents from the editor UI. Respects schema constraints; sanitizes nested marks on rebuild. **Format painter UX improvements** — Toolbar behavior now matches Microsoft Word: one-time mode by default, click state resets on use. **Large image upload in headers/footers** — Image replacement and resizing now work in header/footer contexts, matching body editing capabilities. ### Improvements **Metadata API error distinction preserved** — `metadata.attach` now correctly surfaces `TARGET_NOT_FOUND` for missing nodes and `INVALID_TARGET` for malformed shapes, instead of collapsing both to `INVALID_TARGET`. Clients that branch on error code for retry logic now get the right signal. **Paragraph direction resolution per ECMA-376** — Paragraph inline direction now comes from the paragraph's own `w:bidi` property (or style cascade), not section bidi or run-count heuristics. Latin paragraphs in RTL sections now render left-aligned, matching Word. **Table cell margins round-trip faithful** — Logical `w:start`/`w:end` attributes on cell margins now import and export correctly. Cell-level exceptions now properly override table-level defaults instead of silently dropping. **Theme fonts preserved on round-trip** — Documents with `w:*Theme` rFont slots (per-script theme references) now round-trip without losing the theme linkage to font resolution. User font overrides correctly drop theme refs. **Hyperlink marks survive tracked-change field splits** — Inserted hyperlinks that cross paragraph boundaries now export and re-import with the mark intact, instead of losing the link on the split portion. **EMF+ and raw-pixel image rendering** — Embedded PNG/JPEG inside EMF+ payloads now render (extraction from GDI+ records). Raw-pixel EMF+ bitmaps decode and render as PNG with proper alpha handling. **SVG image MIME types corrected** — Imported SVG images now export with correct content type instead of generic binary type. **Search match visibility improved** — Matches now stay visible over source document highlight marks (run-level color) via `!important` CSS override. Find-and-navigation focus behavior corrected to keep focus on search input through repeated Enter/Shift+Enter. **Comments and tracked changes round-trip together** — Comments anchored to tracked changes now resolve cascading when accepting/rejecting the TC, and properly thread as replies under the TC bubble on re-import (regardless of file origin). **Numbered list definitions preserved** — Documents with tentative numbering (definitions not yet applied) now preserve those unused definitions on export instead of stripping them. Active numbering stays unchanged. **Type safety hardened** — `EditorTransactionEvent.transaction` now typed as `Transaction` instead of `any`. `Config.onAwarenessUpdate.states` now properly typed as `AwarenessState[]`. Deep type audit strengthened via consumer matrix and package-shape verification. **Default paragraph properties no longer injected** — `w:bCs`, `w:iCs`, and explicit `highlight=none` are no longer auto-generated on round-trip when absent from source, reducing export size and eliminating false-positive "intentional" toggles. **Paragraph margin twips normalized on export** — Float-valued `w:pgMar` attributes (inherited from upstream pipelines) now export as integer twips per ECMA-376 §17.6.11, satisfying strict consumers. **Explicit inline bidi preserved** — `w:bidiVisual w:val="0"` (explicit false for table visual direction) now exports correctly instead of being conflated with absent bidi, restoring the cascade-override semantics. **RTL date rendering matches Word** — RTL date tokens now render with the same visual order Word produces (via per-run `dir` isolation and Unicode RLM markers around separators). **Content control defaults standardized** — Newly created controls now default to `richText` type with explicit `w:richText` in SDTPR (matching Word) instead of the untyped `unknown`. Imported typeless Word controls properly resolve to `richText` per ECMA-376 §17.5.2.26. **Content control mutations respect locking** — Programmatic updates to locked SDTs now use `AttrSteps` and inner-range writes instead of wrapper replacement, bypassing lock filters. Operations like `text.setValue` and `replaceContent` now succeed on `sdtLocked` controls as the spec permits. **Paragraph indentation respects style cascade** — Increase/Decrease Indent now correctly read style-derived indent on cache miss instead of crashing before initial render. ### Fixes **Slash menu dismissal restored** — Context menu now closes correctly on Backspace/Delete/Escape/ArrowLeft with proper slash reinsertion logic (slash-triggered opens only). Pressing `/` immediately after dismissal no longer inserts a literal slash. Menu headers and empty states now visible during filter. **Toolbar dropdown keyboard focus** — Dropdown can reopen via Enter after Escape restores focus to the trigger button. Split buttons unaffected. **Block SDT deletion** — Delete key now removes block-level content controls when cursor is at the first position (matching Backspace behavior). **Mixed-bidi Backspace** — Backspace at mixed-direction boundaries now routes through the canonical command chain instead of bypassing undo grouping, history boundaries, and tracked-change wrapping setup. **Hebrew/Arabic presentation forms recognized** — Strong-RTL character detection now includes Hebrew and Arabic presentation-form blocks (FB1D-FB4F, FB50-FDFF, FE70-FEFF), fixing mixed-bidi-backspace boundary detection for runs using legacy fonts. **Native caret refinement gated** — Browser native-selection caret fallback now only applies to the local user's caret, not arbitrary positions queried by remote-cursor manager or arrow-nav binary search. **Revision safety on metadata dry-run** — `metadata.attach` and `metadata.remove` now check `expectedRevision` before returning early on `dryRun: true`, catching stale revisions instead of falsely reporting success. **Copy-slice metadata hidden** — Slice metadata on copied content no longer surfaces in pasted result. **Hidden inline SDT visibility** — `w15:appearance="hidden"` SDTs now truly transparent: chrome suppressed, alias label omitted from DOM, text excluded from copy-paste and screen readers. **SDT temporary property imported** — `w:temporary` flag now imports and surfaces through `ContentControlProperties.temporary` (previously always undefined even when source XML said true). **Find input focus restored** — Pressing Enter in search input now re-focuses the input after navigation, allowing repeated Enter/Shift+Enter to advance through matches without focus stealing to the editor. **Cross-page search scroll stabilized** — Match navigation now scrolls matches into view reliably by preventing focus-steal scroll conflicts, consuming selection-update flags, and re-asserting scroll position on the next frame to catch late displacement. **Section direction doesn't cascade to paragraphs** — Body `w:bidi` on headers/footers no longer incorrectly applied to contained paragraphs (ECMA-376 §17.6.1 compliance). **Comment position readback aligned with write model** — `editor.doc.bookmarks.list()` now returns offsets matching the write-side flattened model instead of counting inline wrapper tokens, eliminating drift. **Duplicate Comment-TC anchor resolve** — Accepting/rejecting a tracked change no longer incorrectly resolves unrelated comments in multi-document sessions (scoped by document ID). **Comment highlight specificity restored** — Comment inline background-color no longer clobbered by lock-hover styles in viewing mode, and hidden inline SDTs excluded from lock-hover styling. **Paragraph font preservation** — Runs imported with multiple theme slots (e.g., ascii/hAnsi/cs themed) now survive user font overrides correctly (primary slot comparison only, per-script extras ignored as non-intent signal). **Paragraph link round-trip** — `w:commentRangeStart` now folds into tracked-change wrapper as first child instead of sitting as sibling, preserving TC-comment linkage on re-import. Replies under TC bubbles now thread correctly on re-import regardless of file origin. **Custom XML schemaRefs distinction** — Omitted vs. empty distinction for `<schemaRefs>` element now preserved on round-trip (ECMA-376 §22.5.2.3): omitted means "app infers," empty means "no schemas," populated means "use these." **Package declaration emit honest** — Release pipeline now gates stable releases with same package-shape and deep-type-audit checks as @next, preventing unverified publishes on latest tag.
### What's New **Content Controls as first-class viewport entities** — Hit-test and retrieve rendered rects for SDTs without DOM attribute scraping. Enables custom UI overlays and smart field chips without duplicating position logic. **ContentControls handle with React hook** — Read-only programmatic access to the active set, cached list, and individual control info via `useSuperDocContentControls()` and `ui.contentControls`. Mirrors the existing comments and tracked-changes surfaces. **Metadata API for anchored payloads** — Document API operations on bookmarks, comments, tracked changes, and content controls now support anchored metadata: `attach`, `remove`, `update` with revision safety and dry-run preview. **Custom XML parts CRUD** — Create, patch, remove, and list custom XML data storage parts through the Document API. Full OOXML package coordination with proper rels, properties, and content-type management. **RTL table support** — Paragraph direction toolbar buttons (headless API). Visual direction context for tables with proper border/margin mirroring per ECMA-376. Logical cell-margin start/end mapping to physical padding. **TOC toolbar item** — Add, update, and manage tables of contents from the editor UI. Respects schema constraints; sanitizes nested marks on rebuild. **Format painter UX improvements** — Toolbar behavior now matches Microsoft Word: one-time mode by default, click state resets on use. **Large image upload in headers/footers** — Image replacement and resizing now work in header/footer contexts, matching body editing capabilities. ### Improvements **Metadata API error distinction preserved** — `metadata.attach` now correctly surfaces `TARGET_NOT_FOUND` for missing nodes and `INVALID_TARGET` for malformed shapes, instead of collapsing both. Clients that branch on error code for retry logic now get the right signal. **Paragraph direction resolution per ECMA-376** — Paragraph inline direction now comes from the paragraph's own `w:bidi` property, not section bidi or run-count heuristics. Latin paragraphs in RTL sections now render left-aligned, matching Word. **Table cell margins round-trip faithful** — Logical `w:start`/`w:end` attributes on cell margins now import and export correctly. Cell-level exceptions now properly override table-level defaults instead of silently dropping. **Theme fonts preserved on round-trip** — Documents with `w:*Theme` rFont slots now round-trip without losing the theme linkage to font resolution. User font overrides correctly drop theme refs. **Hyperlink marks survive tracked-change field splits** — Inserted hyperlinks that cross paragraph boundaries now export and re-import with the mark intact. **EMF+ and raw-pixel image rendering** — Embedded PNG/JPEG inside EMF+ payloads now render. Raw-pixel EMF+ bitmaps decode and render as PNG with proper alpha handling. **SVG image MIME types corrected** — Imported SVG images now export with correct content type instead of generic binary type. **Search match visibility improved** — Matches now stay visible over source document highlight marks via `!important` CSS override. Find-and-navigation focus behavior corrected to keep focus on search input through repeated Enter/Shift+Enter. **Comments and tracked changes round-trip together** — Comments anchored to tracked changes now resolve cascading when accepting/rejecting the TC, and properly thread as replies under the TC bubble on re-import. **Numbered list definitions preserved** — Documents with tentative numbering now preserve those unused definitions on export instead of stripping them. **Type safety hardened** — `EditorTransactionEvent.transaction` now typed as `Transaction` instead of `any`. `Config.onAwarenessUpdate.states` now properly typed as `AwarenessState[]`. Deep type audit strengthened via consumer matrix and package-shape verification. **Default paragraph properties no longer injected** — `w:bCs`, `w:iCs`, and explicit `highlight=none` are no longer auto-generated on round-trip, reducing export size and eliminating false-positive "intentional" toggles. **Paragraph margin twips normalized on export** — Float-valued `w:pgMar` attributes now export as integer twips per ECMA-376 §17.6.11. **Explicit inline bidi preserved** — `w:bidiVisual w:val="0"` now exports correctly instead of being conflated with absent bidi. **RTL date rendering matches Word** — RTL date tokens now render with the same visual order Word produces via per-run `dir` isolation and Unicode RLM markers around separators. **Content control defaults standardized** — Newly created controls now default to `richText` type with explicit `w:richText` in SDTPR, matching Word instead of the untyped `unknown`. **Content control mutations respect locking** — Programmatic updates to locked SDTs now use `AttrSteps` and inner-range writes instead of wrapper replacement, bypassing lock filters. Operations like `text.setValue` and `replaceContent` now succeed on `sdtLocked` controls as the spec permits. **Paragraph indentation respects style cascade** — Increase/Decrease Indent now correctly read style-derived indent on cache miss instead of crashing before initial render. ### Fixes **Slash menu dismissal restored** — Context menu now closes correctly on Backspace/Delete/Escape/ArrowLeft with proper slash reinsertion logic. **Toolbar dropdown keyboard focus** — Dropdown can reopen via Enter after Escape restores focus to the trigger button. **Block SDT deletion** — Delete key now removes block-level content controls when cursor is at the first position. **Mixed-bidi Backspace** — Backspace at mixed-direction boundaries now routes through the canonical command chain instead of bypassing undo grouping and tracked-change wrapping. **Hebrew/Arabic presentation forms recognized** — Strong-RTL character detection now includes presentation-form blocks (FB1D-FB4F, FB50-FDFF, FE70-FEFF), fixing mixed-bidi-backspace boundary detection. **Native caret refinement gated** — Browser native-selection caret fallback now only applies to the local user's caret, not arbitrary positions queried by remote-cursor manager or arrow-nav. **Revision safety on metadata dry-run** — `metadata.attach` and `metadata.remove` now check `expectedRevision` before returning early on `dryRun: true`. **Copy-slice metadata hidden** — Slice metadata on copied content no longer surfaces in pasted result. **Hidden inline SDT visibility** — `w15:appearance="hidden"` SDTs now truly transparent: chrome suppressed, alias label omitted from DOM, text excluded from copy-paste and screen readers. **SDT temporary property imported** — `w:temporary` flag now imports and surfaces through `ContentControlProperties.temporary`. **Find input focus restored** — Pressing Enter in search input now re-focuses the input after navigation, allowing repeated Enter/Shift+Enter to advance through matches. **Cross-page search scroll stabilized** — Match navigation now scrolls matches into view reliably by preventing focus-steal scroll conflicts. **Section direction doesn't cascade to paragraphs** — Body `w:bidi` on headers/footers no longer incorrectly applied to contained paragraphs per ECMA-376 §17.6.1. **Comment position readback aligned** — `editor.doc.bookmarks.list()` now returns offsets matching the write-side flattened model instead of counting inline wrapper tokens. **Duplicate Comment-TC anchor resolve** — Accepting/rejecting a tracked change no longer incorrectly resolves unrelated comments in multi-document sessions. **Comment highlight specificity restored** — Comment inline background-color no longer clobbered by lock-hover styles in viewing mode. **Paragraph font preservation** — Runs imported with multiple theme slots now survive user font overrides correctly. **Paragraph link round-trip** — `w:commentRangeStart` now folds into tracked-change wrapper as first child instead of sitting as sibling, preserving TC-comment linkage on re-import. **Custom XML schemaRefs distinction** — Omitted vs. empty distinction for `<schemaRefs>` element now preserved on round-trip per ECMA-376 §22.5.2.3. **Package declaration emit honest** — Release pipeline now gates stable releases with same package-shape and deep-type-audit checks as @next, preventing unverified publishes on latest tag.
### What's New **Content Controls as first-class viewport entities** — Hit-test and retrieve rendered rects for SDTs without DOM attribute scraping. Enables custom UI overlays and smart field chips without duplicating position logic. **ContentControls React hook** — `useSuperDocContentControls()` mirrors the existing comments and tracked-changes surfaces. Read-only programmatic access to the active set, cached list, and individual control info. **Metadata API for anchored payloads** — Document API operations on bookmarks, comments, tracked changes, and content controls now support anchored metadata: `attach`, `remove`, `update` with revision safety and dry-run preview. **Custom XML parts CRUD** — Create, patch, remove, and list custom XML data storage parts through the Document API. Full OOXML package coordination with proper rels, properties, and content-type management. **RTL table support** — Paragraph direction toolbar buttons. Visual direction context for tables with proper border/margin mirroring per ECMA-376. Logical cell-margin start/end mapping to physical padding. **TOC toolbar item** — Add, update, and manage tables of contents from the editor UI. Respects schema constraints; sanitizes nested marks on rebuild. **Format painter UX improvements** — Toolbar behavior now matches Microsoft Word: one-time mode by default, click state resets on use. **Large image upload in headers/footers** — Image replacement and resizing now work in header/footer contexts, matching body editing capabilities. ### Improvements **Metadata API error distinction** — `metadata.attach` now correctly surfaces `TARGET_NOT_FOUND` for missing nodes and `INVALID_TARGET` for malformed shapes, instead of collapsing both to `INVALID_TARGET`. **Paragraph direction resolution per ECMA-376** — Paragraph inline direction now comes from the paragraph's own `w:bidi` property, not section bidi or run-count heuristics. Latin paragraphs in RTL sections now render left-aligned. **Table cell margins round-trip faithful** — Logical `w:start`/`w:end` attributes on cell margins now import and export correctly. Cell-level exceptions now properly override table-level defaults. **Theme fonts preserved on round-trip** — Documents with `w:*Theme` rFont slots now round-trip without losing the theme linkage to font resolution. **Hyperlink marks survive tracked-change field splits** — Inserted hyperlinks that cross paragraph boundaries now export and re-import with the mark intact. **EMF+ and raw-pixel image rendering** — Embedded PNG/JPEG inside EMF+ payloads now render. Raw-pixel EMF+ bitmaps decode and render as PNG with proper alpha handling. **SVG image MIME types corrected** — Imported SVG images now export with correct content type. **Search match visibility improved** — Matches now stay visible over source document highlight marks via `!important` CSS override. **Comments and tracked changes round-trip together** — Comments anchored to tracked changes now resolve cascading when accepting/rejecting the TC, and properly thread as replies. **Numbered list definitions preserved** — Documents with tentative numbering now preserve those unused definitions on export. **Type safety hardened** — `EditorTransactionEvent.transaction` now typed as `Transaction` instead of `any`. `Config.onAwarenessUpdate.states` now properly typed as `AwarenessState[]`. **Default paragraph properties no longer injected** — `w:bCs`, `w:iCs`, and explicit `highlight=none` are no longer auto-generated on round-trip when absent from source. **Paragraph margin twips normalized on export** — Float-valued `w:pgMar` attributes now export as integer twips per ECMA-376. **Explicit inline bidi preserved** — `w:bidiVisual w:val="0"` now exports correctly instead of being conflated with absent bidi. **RTL date rendering matches Word** — RTL date tokens now render with the same visual order Word produces via per-run `dir` isolation and Unicode RLM markers. **Content control defaults standardized** — Newly created controls now default to `richText` type with explicit `w:richText` in SDTPR. **Content control mutations respect locking** — Programmatic updates to locked SDTs now use `AttrSteps` and inner-range writes, bypassing lock filters. Operations like `text.setValue` now succeed on `sdtLocked` controls as the spec permits. **Paragraph indentation respects style cascade** — Increase/Decrease Indent now correctly read style-derived indent on cache miss. **Package shape hardened** — Release pipeline gates stable releases with same package-shape and deep-type-audit checks as @next. ### Fixes **Slash menu dismissal restored** — Context menu now closes correctly on Backspace/Delete/Escape/ArrowLeft with proper slash reinsertion logic. Menu headers and empty states now visible during filter. **Toolbar dropdown keyboard focus** — Dropdown can reopen via Enter after Escape restores focus to the trigger button. **Block SDT deletion** — Delete key now removes block-level content controls when cursor is at the first position. **Mixed-bidi Backspace** — Backspace at mixed-direction boundaries now routes through the canonical command chain. **Hebrew/Arabic presentation forms recognized** — Strong-RTL character detection now includes presentation-form blocks, fixing mixed-bidi-backspace boundary detection. **Native caret refinement gated** — Browser native-selection caret fallback now only applies to the local user's caret. **Revision safety on metadata dry-run** — `metadata.attach` and `metadata.remove` now check `expectedRevision` before returning early on `dryRun: true`. **Copy-slice metadata hidden** — Slice metadata on copied content no longer surfaces in pasted result. **Hidden inline SDT visibility** — `w15:appearance="hidden"` SDTs now truly transparent: chrome suppressed, alias label omitted, text excluded from copy-paste and screen readers. **SDT temporary property imported** — `w:temporary` flag now imports and surfaces through `ContentControlProperties.temporary`. **Find input focus restored** — Pressing Enter in search input now re-focuses the input after navigation. **Cross-page search scroll stabilized** — Match navigation now scrolls matches into view reliably. **Section direction doesn't cascade to paragraphs** — Body `w:bidi` on headers/footers no longer incorrectly applied to contained paragraphs. **Comment position readback aligned with write model** — `editor.doc.bookmarks.list()` now returns offsets matching the write-side flattened model. **Duplicate Comment-TC anchor resolved** — Accepting/rejecting a tracked change no longer incorrectly resolves unrelated comments in multi-document sessions. **Comment highlight specificity restored** — Comment inline background-color no longer clobbered by lock-hover styles. **Paragraph font preservation** — Runs imported with multiple theme slots now survive user font overrides correctly. **Paragraph link round-trip** — `w:commentRangeStart` now folds into tracked-change wrapper, preserving TC-comment linkage on re-import. **Custom XML schemaRefs distinction** — Omitted vs. empty distinction for `<schemaRefs>` element now preserved on round-trip per ECMA-376.
Based on the diff and commits, here are the release notes for v2.7.1: ### What's New - **Metadata API** — `metadata.attach()`, `metadata.remove()`, and `metadata.get()` now available as a contract layer for anchored metadata operations. - **Custom XML parts API** — Read, create, update, and delete custom XML parts via `customXml.parts.*` operations. - **Native paragraph direction toolbar** — Toggle LTR/RTL direction on paragraphs directly from the editor. - **Content controls as viewport entities** — Access and manipulate content controls through the document viewport API. - **Formatting marks button** — Now configurable as opt-in via editor settings instead of always visible. ### Fixes **Document Fidelity** - Preserve `numbering.xml` definitions on DOCX round-trip. - Preserve theme fonts (`rFonts`) when round-tripping documents. - Preserve explicit `w:bidiVisual` values (`true` and `false`) on export. - Preserve table cell margin (`w:tcMar`) logical/physical key family on round-trip. - Preserve comment reference styles on comment anchor runs. - Stop injecting default run properties and normalize paragraph margins to twips on round-trip. - Import and lock appearance default contract for inline SDTs. **Comments & Tracked Changes** - Track change edits in document body now appear in the comments bubble. - Keep comment range markers around unpaired tracked changes during edits. **Direction & RTL** - Honor inline `w:bidiVisual` only for table visual direction; respect table style settings otherwise. - Recognize Hebrew and Arabic presentation forms as strong RTL text. - Remove double-mirror transformation for logical cell margins in RTL tables. - Preserve explicit `bidiVisual=false` in table direction resolution. - Separate text direction detection from RTL hit testing logic. **Content Controls** - Mutate locked SDTs (structured document tags) via internal attribute steps and range writes. - Default newly-created content controls to `richText` instead of `unknown`. **Metadata API** - Distinguish `TARGET_NOT_FOUND` from `INVALID_TARGET` error codes in `metadata.attach()` — clients branching on error types now receive the correct code. - Throw `REVISION_MISMATCH` on metadata dry-run when expected revision doesn't match. - Honor `expectedRevision` parameter on `metadata.attach()` and `metadata.remove()` dry-run. - Align position readback with write-side offset model in document API. **UI & Interaction** - Restore find input focus after navigating matches in search. - Restore toolbar dropdown keyboard focus after interaction. - Gate native-selection caret refinement to local cursor positioning only. - Recurse into nested marks when sanitizing table of contents. - Add null-safe guard to `getTrackChanges()` to prevent initialization race crashes. - Fix slash menu dismissal state logic. **Type Safety** - Align PDF config type in esign package — `pdfLib` now typed as `object` instead of `any`.
superdoc-bot
Bot
added
patch-sync
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
Contributor
Author
|
🎉 This PR is included in superdoc-sdk v1.10.1 |
Contributor
Author
|
🎉 This PR is included in @superdoc-dev/mcp v0.6.1 The release is available on GitHub release |
Contributor
Author
|
🎉 This PR is included in superdoc-cli v0.12.0 The release is available on GitHub release |
Contributor
Author
|
🎉 This PR is included in superdoc-sdk v1.11.0 |
Contributor
Author
|
🎉 This PR is included in @superdoc-dev/mcp v0.7.0 The release is available on GitHub release |
Contributor
Author
|
🎉 This PR is included in superdoc v1.35.0 The release is available on GitHub release |
Contributor
Author
|
🎉 This PR is included in @superdoc-dev/react v1.6.0 The release is available on GitHub release |
Contributor
Author
|
🎉 This PR is included in vscode-ext v2.7.0 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Merges latest stable patches into main with a real merge commit so stable release tags remain reachable from main.
This keeps
@nextprerelease version calculation ahead of the latest published stable release.Merge requirement
This PR must be merged with GitHub's merge-commit option. Squash or rebase merging will discard stable ancestry and break
@nextversion calculation again.Conflict handling
Merge status:
clean.Version-only release artifact conflicts are auto-resolved to keep stable's already-published versions. Non-version conflicts fail this workflow instead of committing conflict markers.
Auto-created by sync-patches workflow.