perf(comments): batch tracked change creation and virtualize floating bubbles (SD-1997)#2168

Merged

harbournick merged 6 commits intomainfrom

caio/sd-1997-perf-virtualizelazy-load-floating-comment-bubbles-for-large

Feb 25, 2026

Contributor

caio-pizzol commented Feb 25, 2026 •

edited

Loading

FloatingComments rendered all comment bubbles at once - for a document with 588 tracked change comments, that meant 588 CommentDialog components mounted simultaneously, freezing the UI.

Now only the ~5 comments near the viewport get mounted. The rest are lightweight placeholder divs. An IntersectionObserver watches which placeholders are close to the viewport and mounts/unmounts CommentDialogs as you scroll.

Also fixed a bug where typing caused the entire comments sidebar to flicker — the hasInitializedLocations watcher was toggling false→true on every comment change, unmounting and remounting the whole component.

linear bot commented Feb 25, 2026

SD-1997 perf: virtualize/lazy-load floating comment bubbles for large documents


          perf(comments): virtualize floating comment bubbles with Intersection…

a76291e

…Observer

Replace the two-pass render pipeline (hidden measurement container + visible
container mounting all 588 CommentDialogs simultaneously) with IntersectionObserver
virtualization. Only comments within 600px of the viewport mount the heavy
CommentDialog component; the rest are lightweight placeholder divs.

- allPositions computed with collision avoidance replaces imperative processLocations
- Module-level _heightsCache survives component remounts
- verticalOffset converted to computed for proper reactivity
- SuperDoc.vue watcher changed to one-way false→true (prevents unmount/remount flicker)
- Expose getCommentPositionKey from comments-store for canonical ID resolution

SD-1997

caio-pizzol force-pushed the caio/sd-1997-perf-virtualizelazy-load-floating-comment-bubbles-for-large branch from 1afd1ea to a76291e Compare

February 25, 2026 02:30

github-actions bot added the risk: sensitive label

caio-pizzol changed the title ~~perf(comments): batch tracked change creation and virtualize floating bubbles~~ perf(comments): batch tracked change creation and virtualize floating bubbles (SD-1997)

caio-pizzol marked this pull request as draft

February 25, 2026 02:33

This comment was marked as outdated.

Sign in to view

caio-pizzol mentioned this pull request

superdoc unresponsive on document with lot of tracked changes #1721

Closed

4 tasks

caio-pizzol added 2 commits

February 25, 2026 07:33


          test(comments): add behavior tests for floating comment virtualization

74a1652

Verify that:
- Floating comment placeholders appear after creating tracked changes
- CommentDialogs mount near the viewport via IntersectionObserver
- Typing does not cause comment sidebar to flicker (hasInitializedLocations fix)

SD-1997


          chore: fix lockfile missing SDK optional dependency specifiers

105dd30

The SDK platform packages (@superdoc-dev/sdk-darwin-arm64, etc.) were
added as optionalDependencies in a093891 but pnpm skipped resolving
them because of os/cpu restrictions, leaving the lockfile without
specifiers. CI with --frozen-lockfile then failed.

caio-pizzol marked this pull request as ready for review

February 25, 2026 10:48


          chore: ignore SDK scripts in eslint config

880f5d9

The .mjs files in packages/sdk/scripts/ cause parse errors with
typescript-eslint. These are standalone Node scripts, not part of
the library source.

chatgpt-codex-connector bot reviewed

View reviewed changes

chatgpt-codex-connector bot left a comment

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 105dd3072a

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

packages/superdoc/src/components/CommentsLayer/FloatingComments.vue Outdated Show resolved Hide resolved

packages/superdoc/src/components/CommentsLayer/FloatingComments.vue Show resolved Hide resolved

caio-pizzol added 2 commits

February 25, 2026 08:16


          fix(comments): resolve activeComment key mismatch for imported Word c…

8c2d48a

…omments

activeComment stores commentId but pos.id uses getCommentPositionKey (prefers
importedId). For imported comments where importedId !== commentId, the template
guard failed and the active dialog could unmount when scrolled out of viewport.


          fix(tests): update comment test selectors for virtualized FloatingCom…

7946bb9

…ments

The selector .floating-comment > .comments-dialog expected a parent-child
relationship, but Vue merges both classes onto the same DOM element. Changed
to .comment-placeholder .comments-dialog which matches the virtualized template.

caio-pizzol requested review from VladaHarbour, artem-harbour, harbournick and tupizz

February 25, 2026 11:38

caio-pizzol self-assigned this

caio-pizzol added priority: high labels

caio-pizzol linked an issue

that may be closed by this pull request

superdoc unresponsive on document with lot of tracked changes #1721

Closed

4 tasks

caio-pizzol commented

View reviewed changes

packages/superdoc/src/components/CommentsLayer/FloatingComments.vue

               import { useSuperdocStore } from '@superdoc/stores/superdoc-store';
               import CommentDialog from '@superdoc/components/CommentsLayer/CommentDialog.vue';
+              const ESTIMATED_HEIGHT = 80;

Contributor Author

caio-pizzol Feb 25, 2026

80px is the approximate height of a collapsed comment bubble with one line of text

caio-pizzol commented

View reviewed changes

packages/superdoc/src/components/CommentsLayer/FloatingComments.vue

               import CommentDialog from '@superdoc/components/CommentsLayer/CommentDialog.vue';
+              const ESTIMATED_HEIGHT = 80;
+              const OBSERVER_MARGIN = 600;

Contributor Author

caio-pizzol Feb 25, 2026

600px is roughly one viewport of pre-loading margin

caio-pizzol commented

View reviewed changes

packages/superdoc/src/components/CommentsLayer/FloatingComments.vue

+                  pageComments.sort((a, b) => a.top - b.top);
+                  for (let i = 1; i < pageComments.length; i++) {
+                    const prev = pageComments[i - 1];
+                    const minTop = prev.top + prev.height + 15;

Contributor Author

caio-pizzol Feb 25, 2026

15px gap matches the visual spacing the old implementation used between stacked comment bubbles

(there's another issue to work specifically on comments bubble positioning)

caio-pizzol commented

View reviewed changes

packages/superdoc/src/components/CommentsLayer/FloatingComments.vue

+                  const current = measuredHeights.value[key];
+                  if (current !== bounds.height) {
+                    _heightsCache[key] = bounds.height;
+                    measuredHeights.value = { ...measuredHeights.value, [key]: bounds.height };

Contributor Author

caio-pizzol Feb 25, 2026

Spread instead of direct mutation measuredHeights.value[key] = x because Vue's ref reactivity doesn't track nested property additions

caio-pizzol commented

View reviewed changes

packages/superdoc/src/components/CommentsLayer/FloatingComments.vue

+              };
+              // Reactive vertical offset — stays in sync as allPositions recomputes from height measurements
+              const verticalOffset = computed(() => {

Contributor Author

caio-pizzol Feb 25, 2026

When a comment is active, we shift the entire sidebar so the bubble aligns with its text anchor in the editor

caio-pizzol commented

View reviewed changes

packages/superdoc/src/components/CommentsLayer/FloatingComments.vue

		@@ -1,10 +1,18 @@
		<script>

Contributor Author

caio-pizzol Feb 25, 2026

This is intentional — when hasInitializedLocations toggles in SuperDoc.vue the component unmounts and remounts

harbournick approved these changes

View reviewed changes

Collaborator

harbournick left a comment

LGTM

harbournick merged commit 70fd7d9 into main

10 checks passed

harbournick deleted the caio/sd-1997-perf-virtualizelazy-load-floating-comment-bubbles-for-large branch

February 25, 2026 19:39

Contributor

superdoc-bot bot commented Feb 25, 2026

🎉 This PR is included in superdoc v1.17.0-next.6

The release is available on GitHub release

superdoc-bot bot added the released on @next label

harbournick pushed a commit that referenced this pull request


          chore(release): 1.17.0 [skip ci]

0c0b2b9

# [1.17.0](v1.16.0...v1.17.0) (2026-02-28)

### Bug Fixes

* active track change ([#2163](#2163)) ([108c14d](108c14d))
* add currentTotalPages getter and pagination-update event ([#2202](#2202)) ([95b4579](95b4579)), closes [#958](#958)
* always call resolveComment after custom TC bubble handlers (SD-2049) ([#2204](#2204)) ([34fb4e0](34fb4e0))
* backward replace insert text ([#2172](#2172)) ([66f0849](66f0849))
* **collaboration:** deduplicate updateYdocDocxData during replaceFile (SD-1920) ([#2162](#2162)) ([52962fc](52962fc))
* **comments:** cross-page collision avoidance for floating comment bubbles (SD-1998) ([#2180](#2180)) ([6cfbeca](6cfbeca))
* **comments:** remove synchronous dispatch from plugin apply() (SD-1940) ([#2157](#2157)) ([887175b](887175b))
* **css:** scope ProseMirror CSS to prevent bleeding into host apps (SD-1850) ([#2134](#2134)) ([b9d98fa](b9d98fa))
* document-api improvements, plan mode, query.match, mutations ([6221580](6221580))
* **document-api:** delete table cell fix ([#2209](#2209)) ([5e5c43f](5e5c43f))
* **document-api:** distribute columns command fixes ([#2207](#2207)) ([8f4eaf7](8f4eaf7))
* **document-api:** fix cell shading in document api ([#2215](#2215)) ([456f60e](456f60e))
* **document-api:** insert table cell ([#2210](#2210)) ([357ee90](357ee90))
* **document-api:** plan-engine reliability fixes and error diagnostics ([#2185](#2185)) ([abfd81b](abfd81b))
* **document-api:** split table cell command ([#2217](#2217)) ([0b3e2b4](0b3e2b4))
* **document-api:** split table command ([#2214](#2214)) ([ec31699](ec31699))
* **editor:** render styles applied inside SDT fields (SD-2011) ([#2188](#2188)) ([9c34be3](9c34be3))
* **editor:** selection highlight flickers when dragging across mark boundaries (SD-2024) ([#2205](#2205)) ([ba03e76](ba03e76))
* extract duplicate block identity normalization from docxImporter ([7f7ff93](7f7ff93))
* improve backspace behavior near run boundaries for tracked changes ([#2175](#2175)) ([6c9c7a3](6c9c7a3))
* **layout:** per-section footer constraints for multi-section docs (SD-1837) ([#2022](#2022)) ([e11acc5](e11acc5))
* normalize review namespace into trackChanges, harden input validation ([33e907b](33e907b))
* outside click for toolbar dropdown ([#2174](#2174)) ([5f859c7](5f859c7))
* preserve line spacing and indentation on Google Docs paste ([#2183](#2183)) ([b9a7357](b9a7357)), closes [#2151](#2151)
* **shapes:** render grouped DrawingML shapes with custom geometry (SD-1877) ❇️ ([#2105](#2105)) ([14985a5](14985a5))
* support cell spacing ([#1879](#1879)) ([1639967](1639967))
* **tables:** expand auto-width tables to fill available page width ([#2109](#2109)) ([15f36bc](15f36bc))
* text highlight on export ([#2189](#2189)) ([9cbd022](9cbd022))
* track highlight changes ([#2192](#2192)) ([e164625](e164625))
* undo/redo actions ([#2161](#2161)) ([495e92f](495e92f))

### Features

* allow custom accept/reject handlers for TC bubbles ([#1921](#1921)) ([e30abf6](e30abf6))
* **document-api:** add format operations font size alignment color font family ([#2179](#2179)) ([f19c688](f19c688))
* **document-api:** add plan-based mutation engine with query.match and style capture ([#2160](#2160)) ([365293a](365293a))
* **document-api:** doc default initial styles ([#2184](#2184)) ([f25e41f](f25e41f))
* **document-api:** include anchored text in comments list response ([#2177](#2177)) ([b3a2912](b3a2912))
* **document-api:** inline formatting parity core end-to-end ([#2197](#2197)) ([b405b03](b405b03))
* **document-api:** inline formatting rpr parity ([#2198](#2198)) ([41ab771](41ab771))
* **document-api:** section commands ([#2199](#2199)) ([ec4abe3](ec4abe3))
* **document-api:** support deleting entire block nodes not only text ([#2181](#2181)) ([2897246](2897246))
* **document-api:** table of contents commands ([#2200](#2200)) ([baa72c4](baa72c4))
* **document-api:** tables namespace and commands ([#2182](#2182)) ([b80ee31](b80ee31))
* **markdown:** add markdown override to sdk, improve conversion ([#2196](#2196)) ([04a1c71](04a1c71))
* preserve w:view setting through DOCX round-trip ([#2190](#2190)) ([48b4210](48b4210)), closes [#2070](#2070)
* **track-changes:** clear comment bubbles when bulk accept or reject TCs ([#2159](#2159)) ([27fbe8e](27fbe8e))

### Performance Improvements

* **comments:** batch tracked change comment creation on load ([#2166](#2166)) ([0c2eca5](0c2eca5))
* **comments:** batch tracked change creation and virtualize floating bubbles (SD-1997) ([#2168](#2168)) ([70fd7d9](70fd7d9))

harbournick pushed a commit that referenced this pull request


          chore(release): 1.17.0 [skip ci]

a0b506b

# [1.17.0](v1.16.0...v1.17.0) (2026-03-03)

### Bug Fixes

* active track change ([#2163](#2163)) ([108c14d](108c14d))
* add currentTotalPages getter and pagination-update event ([#2202](#2202)) ([95b4579](95b4579)), closes [#958](#958)
* always call resolveComment after custom TC bubble handlers (SD-2049) ([#2204](#2204)) ([34fb4e0](34fb4e0))
* backward replace insert text ([#2172](#2172)) ([66f0849](66f0849))
* before paragraph spacing inside table cells ([#1842](#1842)) ([c7efa85](c7efa85))
* **collaboration:** deduplicate updateYdocDocxData during replaceFile (SD-1920) ([#2162](#2162)) ([52962fc](52962fc))
* **comments:** cross-page collision avoidance for floating comment bubbles (SD-1998) ([#2180](#2180)) ([6cfbeca](6cfbeca))
* **comments:** emit empty comment positions so undo clears orphan bubbles ([#2235](#2235)) ([12ba727](12ba727))
* **comments:** improve multiline comment input styling ([#2242](#2242)) ([e6a0dab](e6a0dab))
* **comments:** prevent comment mark from extending to adjacent typed text ([#2241](#2241)) ([07fecd8](07fecd8))
* **comments:** reduce sidebar jitter when clicking comments (SD-2034) ([#2250](#2250)) ([c3568d2](c3568d2))
* **comments:** remove synchronous dispatch from plugin apply() (SD-1940) ([#2157](#2157)) ([887175b](887175b))
* **css:** scope ProseMirror CSS to prevent bleeding into host apps (SD-1850) ([#2134](#2134)) ([b9d98fa](b9d98fa))
* document-api improvements, plan mode, query.match, mutations ([6221580](6221580))
* **document-api:** delete table cell fix ([#2209](#2209)) ([5e5c43f](5e5c43f))
* **document-api:** distribute columns command fixes ([#2207](#2207)) ([8f4eaf7](8f4eaf7))
* **document-api:** fix cell shading in document api ([#2215](#2215)) ([456f60e](456f60e))
* **document-api:** insert table cell ([#2210](#2210)) ([357ee90](357ee90))
* **document-api:** plan-engine reliability fixes and error diagnostics ([#2185](#2185)) ([abfd81b](abfd81b))
* **document-api:** split table cell command ([#2217](#2217)) ([0b3e2b4](0b3e2b4))
* **document-api:** split table command ([#2214](#2214)) ([ec31699](ec31699))
* **editor:** render styles applied inside SDT fields (SD-2011) ([#2188](#2188)) ([9c34be3](9c34be3))
* **editor:** selection highlight flickers when dragging across mark boundaries (SD-2024) ([#2205](#2205)) ([ba03e76](ba03e76))
* extract duplicate block identity normalization from docxImporter ([7f7ff93](7f7ff93))
* improve backspace behavior near run boundaries for tracked changes ([#2175](#2175)) ([6c9c7a3](6c9c7a3))
* **layout:** per-section footer constraints for multi-section docs (SD-1837) ([#2022](#2022)) ([e11acc5](e11acc5))
* markdown block-separator blank lines and heading split style-mark normalization ([e988adc](e988adc))
* normalize review namespace into trackChanges, harden input validation ([33e907b](33e907b))
* outside click for toolbar dropdown ([#2174](#2174)) ([5f859c7](5f859c7))
* prefer full decoration range ([#2239](#2239)) ([ac15e31](ac15e31)), closes [#collectDesiredState](https://github.com/superdoc-dev/superdoc/issues/collectDesiredState) [#resolveEffectiveRanges](https://github.com/superdoc-dev/superdoc/issues/resolveEffectiveRanges) [#setPreviousRanges](https://github.com/superdoc-dev/superdoc/issues/setPreviousRanges)
* preserve line spacing and indentation on Google Docs paste ([#2183](#2183)) ([b9a7357](b9a7357)), closes [#2151](#2151)
* preserve text-align on paste from Google Docs ([#2208](#2208)) ([762231b](762231b))
* rollback comments colors / ui ([#2216](#2216)) ([a99b5ab](a99b5ab))
* **scroll:** wait for virtualized page mount and center text element ([#2221](#2221)) ([95f634e](95f634e))
* **shapes:** render grouped DrawingML shapes with custom geometry (SD-1877) ❇️ ([#2105](#2105)) ([14985a5](14985a5))
* splitting run with header adds empty row ([#2229](#2229)) ([e1965fc](e1965fc))
* **super-converter:** handle empty pic:spPr in image import ([#2254](#2254)) ([2b8dbce](2b8dbce))
* **super-editor:** backspace across run boundaries without splitting list items ([#2258](#2258)) ([27ccb64](27ccb64))
* support cell spacing ([#1879](#1879)) ([1639967](1639967))
* **tables:** defaultTableStyle support, cell fixes ([#2246](#2246)) ([74fca9c](74fca9c))
* **tables:** expand auto-width tables to fill available page width ([#2109](#2109)) ([15f36bc](15f36bc))
* **tables:** preserve TableGrid defaults and style-driven spacing/bor… ([#2230](#2230)) ([b0a482f](b0a482f))
* text highlight on export ([#2189](#2189)) ([9cbd022](9cbd022))
* track highlight changes ([#2192](#2192)) ([e164625](e164625))
* **track-changes:** correct format change description for already-formatted text (SD-2077) ([#2253](#2253)) ([b2ffc0d](b2ffc0d))
* **track-changes:** handle ReplaceAroundStep in tracked changes mode (SD-2061) ([#2225](#2225)) ([8f3cbe4](8f3cbe4))
* **track-changes:** remove ghost TrackFormat on multi-node format cancel ([#2233](#2233)) ([e925ef9](e925ef9))
* undo/redo actions ([#2161](#2161)) ([495e92f](495e92f))
* **virtualization:** correct scroll mapping and viewport sizing at non-100% zoom ([#2171](#2171)) ([84af4c0](84af4c0)), closes [#registryKey](https://github.com/superdoc-dev/superdoc/issues/registryKey)

### Features

* allow custom accept/reject handlers for TC bubbles ([#1921](#1921)) ([e30abf6](e30abf6))
* **comments:** improve floating comments ui ([#2195](#2195)) ([e870cfb](e870cfb))
* **document-api:** add format operations font size alignment color font family ([#2179](#2179)) ([f19c688](f19c688))
* **document-api:** add get markdown to sdks ([e42b56d](e42b56d))
* **document-api:** add plan-based mutation engine with query.match and style capture ([#2160](#2160)) ([365293a](365293a))
* **document-api:** default table style setting ([#2248](#2248)) ([3ad4e9f](3ad4e9f))
* **document-api:** default target-less insert to document end ([#2244](#2244)) ([c717e2b](c717e2b))
* **document-api:** doc default initial styles ([#2184](#2184)) ([f25e41f](f25e41f))
* **document-api:** format.paragraph for w:pPr formatting ([#2218](#2218)) ([32c9991](32c9991))
* **document-api:** history name space ([#2219](#2219)) ([41dea37](41dea37))
* **document-api:** include anchored text in comments list response ([#2177](#2177)) ([b3a2912](b3a2912))
* **document-api:** inline formatting parity core end-to-end ([#2197](#2197)) ([b405b03](b405b03))
* **document-api:** inline formatting rpr parity ([#2198](#2198)) ([41ab771](41ab771))
* **document-api:** lists namespace  ([#2223](#2223)) ([09ebfcb](09ebfcb))
* **document-api:** section commands ([#2199](#2199)) ([ec4abe3](ec4abe3))
* **document-api:** support deleting entire block nodes not only text ([#2181](#2181)) ([2897246](2897246))
* **document-api:** table of contents commands ([#2200](#2200)) ([baa72c4](baa72c4))
* **document-api:** tables namespace and commands ([#2182](#2182)) ([b80ee31](b80ee31))
* **document-api:** toc commands ([#2220](#2220)) ([767e010](767e010))
* **images:** allow drag-and-drop for images in editor ([#2227](#2227)) ([4b36780](4b36780))
* **layout-engine:** render table headers, tblLook support ([#2256](#2256)) ([db6a2ff](db6a2ff))
* **link-popover:** custom link popovers ([#2222](#2222)) ([070190f](070190f))
* **markdown:** add markdown override to sdk, improve conversion ([#2196](#2196)) ([04a1c71](04a1c71))
* preserve w:view setting through DOCX round-trip ([#2190](#2190)) ([48b4210](48b4210)), closes [#2070](#2070)
* real time collab in python sdk ([#2243](#2243)) ([dc3b4fd](dc3b4fd))
* **tables:** allow resizing table rows ([#2226](#2226)) ([2c6da10](2c6da10))
* **tables:** improve cell color application (context), column dragging, table pasting ([#2228](#2228)) ([066b9eb](066b9eb))
* **table:** toggle header row sets both cell types and repeatHeader atomically ([#2245](#2245)) ([2f5899d](2f5899d))
* **track-changes:** clear comment bubbles when bulk accept or reject TCs ([#2159](#2159)) ([27fbe8e](27fbe8e))

### Performance Improvements

* **comments:** batch tracked change comment creation on load ([#2166](#2166)) ([0c2eca5](0c2eca5))
* **comments:** batch tracked change creation and virtualize floating bubbles (SD-1997) ([#2168](#2168)) ([70fd7d9](70fd7d9))

Collaborator

harbournick commented Mar 3, 2026

🎉 This PR is included in superdoc v1.17.0

The release is available on GitHub release

harbournick added the released on @latest label

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

chatgpt-codex-connector[bot] chatgpt-codex-connector[bot] left review comments

tupizz Awaiting requested review from tupizz

artem-harbour Awaiting requested review from artem-harbour

VladaHarbour Awaiting requested review from VladaHarbour

harbournick Awaiting requested review from harbournick

Labels

priority: high released on @latest released on @next risk: sensitive