🔄 Sync stable → main (#2687)

* feat(vscode-ext): add test suite and clean up extension (SD-2341) (#2553)

* feat(vscode-ext): add test suite and clean up extension

SD-2341: Add contract tests verifying SuperDoc API surface the extension
depends on, plus build verification for the extension host bundle.

- Contract tests check: class export, style.css export, prototype methods
  (export, destroy, getHTML, EventEmitter), and constructor config options
- Build test verifies esbuild can bundle extension host without errors
- Fix onError → onException (callback was silently ignored)
- Remove unused VS Code config settings (autoSaveDelay, enableAutoSave)
- Move acquireVsCodeApi() before first debug() call (was dead code)
- Remove dead 'save' message from Ctrl+S handler
- Remove unnecessary currentFileData state variable
- Tighten contract test regexes to match config.* patterns
- Remove vscode-build pre-commit hook (CI handles this)

* ci(vscode-ext): add CI workflow and test step to release

- New ci-vscode-ext.yml: runs lint, typecheck, tests, and extension host
  build on PRs touching vscode-ext or superdoc source
- Add test step to release-vscode-ext.yml before publishing

* ci: tighten workflow path filters to reduce spurious runs

- ci-superdoc: add apps/mcp, apps/vscode-ext, packages/react,
  packages/sdk, evals to paths-ignore
- ci-demos, ci-docs, ci-sdk: remove pnpm-lock.yaml from path triggers
  (lockfile changes alone shouldn't trigger unrelated CI)

* feat(vscode-ext): auto-release on SuperDoc updates (#2555)

SD-2342: Expand release workflow path triggers and use patch-commit-filter
so superdoc core commits trigger VS Code extension releases.

- Add superdoc source paths to release-vscode-ext.yml triggers
- Replace semantic-release-commit-filter with patch-commit-filter.cjs
  (same pattern as CLI/SDK)
- @next auto-deploys to GitHub releases only (low risk)
- @latest still requires manual cherry-pick to stable (human gate)

* docs(vscode-ext): rewrite README for Marketplace

- Remove outdated "not yet on Marketplace" text
- Add install command, feature list, how it works section
- Match CLI/SDK README structure and brand voice

* chore(vscode): 2.0.0 [skip ci]

Credit balance is too low

* feat(vscode-ext): add tests, enable comments, clean up extension (SD-2341) (#2558)

* feat(vscode-ext): enable comments bubble rendering

Show Word document comments in the editor by passing
comments: { visible: true } to the SuperDoc constructor.

* fix(vscode-ext): allow comment and tracked change balloons to render

Remove display:flex and justify-content:center from #superdoc container
so SuperDoc's internal layout can allocate space for the right margin
where comment bubbles and tracked change balloons appear.

* docs(vscode-ext): add demo GIF and rewrite README for Marketplace

Add animated demo showing AI-driven tracked changes via MCP.
Rewrite README with badges, feature list, install instructions,
and AI integration section.

* chore(vscode-ext): add icon, homepage, and Marketplace metadata

Add SuperDoc brand logo as extension icon, homepage link, bugs URL,
gallery banner color, and additional keywords for discoverability.

* chore(vscode-ext): remove demo GIF from git, host externally

Remove demo.gif from repo to avoid bloating git history with a 6.8MB
binary. Add to .gitignore and .vscodeignore. README will reference
a GitHub-hosted URL once uploaded.

* fix(vscode-ext): cap release bumps at minor to prevent accidental majors

Upstream superdoc commits with breaking change markers triggered a
v2.0.0 bump. The extension has no public API — it just bundles superdoc —
so breaking changes in the engine don't warrant a major version bump
for the extension. Add releaseRules to cap at minor.

* fix(vscode-ext): use semantic-release-pnpm for correct version resolution

Root cause of the v2.0.0 bump: package.json has version 0.0.0 (pnpm
workspace convention) but @semantic-release/npm doesn't handle this
correctly — it computed the version from package.json instead of the
git tag. Switch to semantic-release-pnpm which resolves versions from
tags, matching superdoc and react packages.

* chore(vscode): 2.1.0 [skip ci]

### What's New

- **Word comments** — View and add Word comments with margin bubbles directly in the editor.

### Improvements

- **Marketplace presence** — README redesigned with feature list, install instructions, and AI integration guide; extension now discoverable with improved keywords and gallery banner.
- **Better documentation** — Added demo GIF, clarified AI integration via MCP, and linked to enterprise licensing.
- **Extension metadata** — Added SuperDoc brand icon, homepage link, and issue tracker URL for better indexing.

### Internal

- **Release process** — Switched to semantic-release-pnpm for correct version resolution from git tags, preventing version mismatches from pnpm workspace conventions.
- **Stability** — Capped release bumps at minor version to prevent accidental major releases from upstream breaking changes (the extension has no public API).
- **Tests** — Added test infrastructure with vitest.
- **Comment rendering** — Fixed layout to allow comment bubbles and tracked change balloons to render in the right margin.

* fix(vscode-ext): bundle demo GIF locally for Marketplace

VS Code Marketplace can't resolve GitHub user-attachment URLs.
Add demo.gif to the repo and vsix package so it renders on the
Marketplace listing page.

* chore(vscode): 2.1.1 [skip ci]

### Fixes

- **VS Code extension** — Demo GIF now bundles locally in the extension package, rendering correctly on the VS Code Marketplace.

* fix(super-converter): normalize inline nodes in non-TOC docPartObj content

The generic docPartObj handler was missing the normalizeDocPartContent()
call that the TOC handler already had, causing documents with non-TOC
gallery types (page numbers, bibliographies, cover pages) containing
top-level inline nodes (bookmarks, comments, permissions) to fail with
"Invalid content for node type documentPartObject".

Also expanded the inline node type set to include commentRangeStart,
commentRangeEnd, permStart, and permEnd.

SD-2357

* chore(release): 1.23.1 [skip ci]

### Fixes

- **Document part object normalization** — The generic document part handler now correctly normalizes inline nodes (bookmarks, comments, permissions) in non-TOC gallery types. Documents with page numbers, bibliographies, cover pages, and other gallery types no longer fail when they contain top-level inline content.

* chore(cli): 0.4.1 [skip ci]

### Fixes

- **Document part object normalization** — The generic handler for document parts now correctly normalizes inline nodes (bookmarks, comments, permissions) in non-TOC gallery types. Documents with page numbers, bibliographies, cover pages, and other structured gallery types no longer fail when they contain top-level inline content.

* fix(vscode-ext): fix broken images on VS Code marketplace (#2640) (#2641)

Stop vsce from rewriting relative image paths to incorrect GitHub raw
URLs (missing apps/vscode-ext/ prefix). Remove shields.io badges that
show "rate limited by upstream service" on the marketplace.

* chore(vscode): 2.1.2 [skip ci]

### Fixes

- **VS Code extension marketplace rendering** — Removed shields.io badges that displayed "rate limited" status, and prevented vsce from rewriting relative image paths to incorrect GitHub raw URLs.
- **Document part objects with inline content** — Non-TOC gallery types (page numbers, bibliographies, cover pages) now correctly normalize top-level inline nodes (bookmarks, comments, permissions) instead of failing with "Invalid content for node type documentPartObject."

* fix(vscode-ext): use absolute URL for demo GIF on marketplace

The marketplace web page cannot load images from the VSIX bundle — it
requires publicly accessible URLs. Use the full GitHub raw URL with the
correct subdirectory path instead of a relative path.

* chore(vscode): 2.1.3 [skip ci]

### Fixes

- **VS Code Marketplace** — The demo GIF now displays correctly on the extension's marketplace page. The extension previously used a relative image path, which the marketplace can't load; we now use the full GitHub raw URL.

* fix: update lock file

* chore(release): 1.24.0 [skip ci]

### What's New

- **Mathematical equations** — Render OMML math with browser-native MathML, including fractions, bars, and precise accent stretching; cursor positioning works after inline equations.
- **Password-protected documents** — Open encrypted .docx files with a customizable password prompt surface; fully configurable UI text, titles, and error handling.
- **Multi-column copy-paste** — Preserve column layout and structure when copying from multi-column sections; automatic image collision detection prevents overwrites.
- **Document protection** — Create, manage, and remove permission ranges; set editing restrictions on document sections.
- **Find and replace** — Built-in search and replace functionality with refresh on active transaction.
- **Generic surfaces API** — Dialogs and floating panel support for custom extensions.
- **Spell check infrastructure** — Proofing platform for integrating spell-check libraries.
- **RTL table rendering** — Right-to-left tables respect w:bidiVisual with visually reversed columns, mirrored cell layout, and correct border handling.
- **Word comments in VS Code** — View and add Word comments with margin bubbles directly in the extension editor.

### Improvements

- **Block references** — Superdoc_create now returns a ref handle; use it directly in superdoc_format instead of searching first (33% fewer API calls).
- **Block formatting accuracy** — Formatting now resolves through the full style-engine cascade (docDefaults → Normal style → paragraph style → inline marks) instead of just inline marks, ensuring accurate fontFamily, fontSize, color, and bold values even on style-driven formatting.
- **AI tool descriptions** — Improved superdoc_create, superdoc_format, and superdoc_list guidance to prevent LLM misuse and simplify successful operations.
- **Math accent rendering** — Underbars on compound expressions like x+y now stretch correctly (U+203E overline instead of combining marks); display style and Cambria Math font match Word rendering.
- **RTL cursor navigation** — Arrow keys now move the cursor in the correct visual direction in Arabic and other RTL text; vertical navigation (up/down) works correctly with inverted search direction.
- **Paragraph borders and spacing** — Border expansion now overlaps with paragraph spacing per ECMA-376, not stacking; fixed cursorY positioning and continuation fragment alignment after page breaks.
- **Comment rendering** — Fixed layout to allow comment bubbles and tracked-change balloons to render in the right margin without overflow.
- **Footnote rendering** — Reference markers normalize before superscript layout; render as scaled superscript digits with correct baseline shift handling.
- **Toolbar dropdowns** — Better activation when editor is unfocused; font attributes queue correctly for delayed commands.
- **VS Code extension marketplace** — README redesigned with feature list, install instructions, AI integration guide, and improved metadata for discoverability; extension icon and homepage link added.
- **Inline structured content** — Inherit run formatting (bold, color, font) when inserting inline SDT elements; respect pending toolbar formatting.
- **Table of contents** — Apply useAppliedOutlineLevel without requiring \o range switch; TOC with \u-only instructions now works correctly.

### Fixes

- **Math cursor positioning** — Clicks in overflow areas around inline math equations now resolve to correct ProseMirror positions.
- **Comment scrolling** — Fixed scroll behavior regression after painter refactor.
- **RTL click-to-position mapping** — Clicks on RTL text now map to the correct document position; fixed hidden span handling in line bounds calculation.
- **Diacritical marks in tracked changes** — Composition handling now allows diacritical symbols in track changes operations; dead-key placeholders work correctly.
- **Style inheritance on Enter** — Pressing Enter at the end of unformatted text no longer inherits parent paragraph formatting; clearing formatting with an empty storedMarks array is now respected across paragraph splits and run management.
- **Document part object normalization** — Non-TOC gallery types (page numbers, bibliographies, cover pages) now correctly normalize inline nodes (bookmarks, comments, permissions) instead of failing with "Invalid content" errors.
- **Table cell newlines** — Newline characters in structured content table cells now split into separate paragraphs instead of losing content after the first newline.
- **SDT hover in view mode** — Hovering block and inline structured content containers in viewing mode no longer shows background highlights.
- **Comment export** — Resolved comments now export with correct w15:done attribute; commentsExtended.xml is included even when no threaded comments exist.
- **VS Code extension marketplace rendering** — Demo GIF bundles locally in the VSIX package; image paths use absolute GitHub URLs instead of relative paths that the marketplace can't resolve.
- **CLI validation** — Fixed inline-special insertion positioning and schema validation.
- **Headless numbering sync** — Fixed infinite loop when list definitions are missing; sync now terminates correctly.
- **DOCX export** — Handle null or undefined converter declaration with standard XML fallback (version="1.0" encoding="UTF-8" standalone="yes").
- **Layout engine architecture** — Removed remaining pm-adapter boundary leaks; layout-bridge now self-contained with local PX_PER_PT constant.

* chore(release): 1.24.1 [skip ci]

Now I'll generate the release notes based on the actual changes I've analyzed:

### Fixes

- **Math blocks** — Display math paragraphs now inherit spacing (before and after) from their containing paragraph, matching Word's rendering.
- **File replacement with live collaboration** — Fixed issue where the live collaboration fragment wasn't cleared during document rebuild, which could cause stale fragment references.
- **Image resize in view mode** — Image resize handles no longer appear when the document is in viewing mode; handles are properly cleared when switching document modes.

* chore(cli): 0.5.0 [skip ci]

### What's New

- **Mathematical equations** — Render OMML math with browser-native MathML, including fractions, bars, and precise accent stretching; cursor positioning works after inline equations.
- **Password-protected documents** — Open encrypted .docx files with a customizable password prompt surface; fully configurable UI text, titles, and error handling.
- **Multi-column copy-paste** — Preserve column layout and structure when copying from multi-column sections; automatic image collision detection prevents overwrites.
- **Document protection** — Create, manage, and remove permission ranges; set editing restrictions on document sections.
- **Find and replace** — Built-in search and replace functionality with refresh on active transaction.
- **Generic surfaces API** — Dialogs and floating panel support for custom extensions.
- **Spell check infrastructure** — Proofing platform for integrating spell-check libraries.
- **RTL table rendering** — Right-to-left tables respect w:bidiVisual with visually reversed columns, mirrored cell layout, and correct border handling.
- **Word comments in VS Code** — View and add Word comments with margin bubbles directly in the extension editor.

### Improvements

- **Block references** — superdoc_create now returns a ref handle; use it directly in superdoc_format instead of searching first (33% fewer API calls).
- **Block formatting accuracy** — Formatting now resolves through the full style-engine cascade (docDefaults → Normal style → paragraph style → inline marks), ensuring accurate fontFamily, fontSize, color, and bold values.
- **Math rendering precision** — Underbars on compound expressions like x+y now stretch correctly; display style and Cambria Math font match Word rendering.
- **RTL cursor navigation** — Arrow keys now move the cursor in the correct visual direction in Arabic and other RTL text; vertical navigation (up/down) works correctly.
- **Paragraph borders and spacing** — Border expansion now overlaps with paragraph spacing per ECMA-376, not stacking; fixed cursorY positioning and continuation fragment alignment after page breaks.
- **Comment rendering** — Fixed layout to allow comment bubbles and tracked-change balloons to render without overflow.
- **Footnote rendering** — Reference markers normalize before superscript layout; render as scaled superscript digits with correct baseline shift handling.
- **Toolbar dropdowns** — Better activation when editor is unfocused; font attributes queue correctly for delayed commands.
- **VS Code extension marketplace** — README redesigned with feature list, install instructions, AI integration guide; extension icon and homepage link added.
- **Inline structured content** — Inherit run formatting (bold, color, font) when inserting inline SDT elements; respect pending toolbar formatting.
- **Table of contents** — Apply useAppliedOutlineLevel without requiring \o range switch; TOC with \u-only instructions now works correctly.
- **Click-to-position mapping in RTL** — Clicks on RTL text now map to the correct document position; fixed hidden span handling in line bounds calculation.

### Fixes

- **Math cursor positioning** — Clicks in overflow areas around inline math equations now resolve to correct ProseMirror positions.
- **Comment scrolling** — Fixed scroll behavior regression after painter refactor.
- **Diacritical marks in tracked changes** — Composition handling now allows diacritical symbols in track changes operations; dead-key placeholders work correctly.
- **Style inheritance on Enter** — Pressing Enter at the end of unformatted text no longer inherits parent paragraph formatting; clearing formatting with an empty storedMarks array is now respected.
- **Document part object normalization** — Non-TOC gallery types (page numbers, bibliographies, cover pages) now correctly normalize inline nodes (bookmarks, comments, permissions).
- **Table cell newlines** — Newline characters in structured content table cells now split into separate paragraphs instead of losing content.
- **SDT hover in view mode** — Hovering block and inline structured content containers in viewing mode no longer shows background highlights.
- **Comment export** — Resolved comments now export with correct w15:done attribute; commentsExtended.xml is included even when no threaded comments exist.
- **VS Code extension marketplace rendering** — Demo GIF bundles locally in the VSIX package; image paths use absolute GitHub URLs instead of relative paths.
- **CLI validation** — Fixed inline-special insertion positioning and schema validation.
- **Headless numbering sync** — Fixed infinite loop when list definitions are missing; sync now terminates correctly.
- **DOCX export** — Handle null or undefined converter declaration with standard XML fallback (version="1.0" encoding="UTF-8" standalone="yes").

* chore(template-builder, esign): bump superdoc peer dep to ^1.23.0 (#2678)

* chore(template-builder): bump superdoc peer dep to ^1.23.0

Picks up fixes shipped since v1.19.0 that are relevant to Cake Equity:
- SD-2323: image resize handles hidden in view mode
- SD-1361: layout engine no longer hides block SDTs
- SD-1850: ProseMirror CSS scoped to prevent host-app bleed

* chore(esign): bump superdoc peer dep to ^1.23.0

Same version bump as template-builder to pick up fixes since v1.19.0.

* chore(template-builder): 1.3.0 [skip ci]

### Fixes

- **Image resize handles in view mode** — Overlay handles no longer appear when documents are in viewing mode; properly cleared when switching document modes.
- **Block structured content rendering** — Layout engine no longer hides block SDTs (structured content elements); document structure preserved through rendering.
- **Style isolation** — ProseMirror CSS scoped to editor container; prevents stylesheet bleed into host application UI.

* fix(types): remove ambient shims that override external package types (IT-852) (#2686)

* fix(types): remove ambient shims that override external package types (IT-852)

The published `_internal-shims.d.ts` contained `declare module` blocks for
prosemirror-*, vue, eventemitter3, yjs, and @hocuspocus/provider that typed
all exports as `any`. These ambient declarations globally override real types,
breaking consumers who use those packages (e.g. Tiptap users lost all
prosemirror type safety).

- Remove all external package shims from `ensure-types.cjs`
- Keep only `@superdoc/*` workspace package shims (consumers can't install those)
- Add prosemirror-* as optional peerDependencies (public API re-exports their types)
- Add IT-852 regression test: consumer-typecheck scenario that installs prosemirror
  alongside superdoc and verifies types are real (not `any`) via `@ts-expect-error`

* chore: update pnpm lockfile for new prosemirror peer deps

* fix(types): keep @hocuspocus/provider, yjs, y-prosemirror as required peers

---------

Co-authored-by: Caio Pizzol <97641911+caio-pizzol@users.noreply.github.com>
Co-authored-by: Caio Pizzol <caio@harbourshare.com>
Co-authored-by: semantic-release-bot <semantic-release-bot@martynus.net>
Co-authored-by: Nick Bernal <nick@superdoc.dev>
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: 5 people

packages/template-builder/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superdoc-dev/template-builder",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "React template builder component for SuperDoc",
   "type": "module",
   "main": "./dist/index.js",