array node treeChanged delta payload by daesunp · Pull Request #26927 · microsoft/FluidFramework

daesunp · 2026-04-02T18:36:07Z

Description

Adds support for delta payload for array node events in treeChanged.

Copilot

Pull request overview

This PR expands the nodeChanged delta payload for array nodes by adding a per-element nested change description (childDelta) on "retain" ops, enabling consumers (e.g., text editors) to perform more granular updates without re-diffing entire subtrees.

Changes:

Add ArrayNodeRetainOp.childDelta?: NodeDelta and introduce the recursive NodeDelta type to describe nested changes within retained elements.
Extend the delta → array-ops conversion to populate childDelta from nested fields marks, and update AnchorSet batching so array nodeChanged can fire for “pure nested changes” (retain-with-fields) in hydrated mode.
Update/expand test coverage around hydration behavior and add new tests validating childDelta shape/content.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
packages/framework/fluid-framework/api-report/fluid-framework.alpha.api.md	API report update for newly exported `NodeDelta` and `childDelta` on array retain ops.
packages/dds/tree/src/test/tableSchema.spec.ts	Adjust hydration-aware expectations for `nodeChanged` firing behavior.
packages/dds/tree/src/test/simple-tree/api/treeNodeApi.spec.ts	Adds/updates tests for hydration behavior and validates `childDelta` payloads.
packages/dds/tree/src/simple-tree/index.ts	Re-export `NodeDelta` from the simple-tree surface.
packages/dds/tree/src/simple-tree/api/treeNodeApi.ts	Implements `NodeDelta`, `childDelta` generation, and updated delta conversion logic.
packages/dds/tree/src/simple-tree/api/treeAlpha.ts	Re-export `NodeDelta` from TreeAlpha API.
packages/dds/tree/src/simple-tree/api/index.ts	Re-export `NodeDelta` from the simple-tree API index.
packages/dds/tree/src/index.ts	Re-export `NodeDelta` from the package root.
packages/dds/tree/src/entrypoints/legacy.ts	Include `NodeDelta` in generated legacy entrypoint exports.
packages/dds/tree/src/entrypoints/alpha.ts	Include `NodeDelta` in generated alpha entrypoint exports.
packages/dds/tree/src/core/tree/anchorSet.ts	Emit `childrenChangedAfterBatch` for array fields on retain-with-fields-only marks (hydrated mode).
packages/dds/tree/api-report/tree.alpha.api.md	API report update for `NodeDelta` and `childDelta` on array retain ops.

Copilot · 2026-04-02T21:22:50Z

packages/dds/tree/src/simple-tree/api/treeNodeApi.ts

+			// A retain mark with nested `fields` implies a tree node was retained, not a leaf.
+			// Reaching here indicates an unexpected internal state.
+			fail("Expected a tree node for a retain mark with nested fields.");
+		}


buildPropertyDelta can emit { kind: "leaf", newValue: undefined } when an optional field is cleared/removed (object nodes represent empty optional fields as undefined). TreeLeafValue explicitly excludes undefined, so this both violates the exported NodeDelta type and gives consumers an invalid value. Consider explicitly handling detach-only marks (field cleared) with a dedicated delta variant (e.g. kind: "deleted") or widen the leaf/newValue encoding to include undefined, and update NodeDelta + API reports accordingly.

Suggested change

}

}

if (propertyValue === undefined) {

// Optional fields that are cleared are represented as `undefined` in the post-change object view.

// `TreeLeafValue` excludes `undefined`, so avoid emitting an invalid leaf delta payload.

// Use the existing empty object delta encoding to signal that the property changed without

// reporting a nested retained subtree.

return { kind: "object", changedProperties: new Map() };

}

Updated to have kind: "deleted"

Copilot · 2026-04-02T21:22:51Z

packages/dds/tree/src/simple-tree/api/treeNodeApi.ts

+	} else {
+		// Map or record node: stored field keys are the property keys.
+		// Map entries are accessed via .get() — direct property access does not work on map node proxies.
+		assert(isMapNodeSchema(nodeSchema), "expected map or record schema in map branch");
+		const mapNode = node as unknown as TreeMapNode;


The map/record branch in buildNodeDeltaFromFields asserts isMapNodeSchema(nodeSchema), but the comment and NodeDelta docs say this should handle both map and record nodes. For NodeKind.Record schemas this assertion will fire, breaking childDelta generation for record nodes. Please add record support (e.g. check isMapNodeSchema || isRecordNodeSchema and read values using the appropriate access pattern).

Added section for recode nodes

Josmithr · 2026-04-03T00:28:32Z

packages/dds/tree/src/simple-tree/api/treeChangeEvents.ts

+	 * - Array nodes define a change as when an element is added, removed, moved, or replaced,
+	 * or when a property of an element changes (i.e., a nested change within an element).
+	 * In the latter case, the {@link ArrayNodeRetainOp.childDelta} field on the corresponding
+	 * retain op describes what changed within the element.


I don't think we want to report nested changes as a part of the nodeChanged event. Presumably we only want to do this for the treeChanged event to be consistent with other node types. nodeChanged is a shallow check, and treeChanged is a deep check.

Updated to be in treeChanged and now just provides a boolean instead of childDelta

Josmithr · 2026-04-03T00:30:11Z

packages/dds/tree/api-report/tree.alpha.api.md

 }

+// @alpha @sealed
+export type NodeDelta = {


How does treeChanged represent deep tree changes? Seems like we would want to leverage the same tree structure (presumably just adding support for arrays).

Moved to treechanged :)

github-actions · 2026-04-07T20:51:52Z

🔗 No broken links found! ✅

Your attention to detail is admirable.

linkcheck output


> fluid-framework-docs-site@0.0.0 ci:check-links /home/runner/work/FluidFramework/FluidFramework/docs
> start-server-and-test "npm run serve -- --no-open" 3000 check-links

1: starting server using command "npm run serve -- --no-open"
and when url "[ 'http://127.0.0.1:3000' ]" is responding with HTTP status code 200
running tests using command "npm run check-links"


> fluid-framework-docs-site@0.0.0 serve
> docusaurus serve --no-open

[SUCCESS] Serving "build" directory at: http://localhost:3000/

> fluid-framework-docs-site@0.0.0 check-links
> linkcheck http://localhost:3000 --skip-file skipped-urls.txt

Crawling...

Stats:
  278943 links
    1879 destination URLs
    2124 URLs ignored
       0 warnings
       0 errors

daesunp added 2 commits April 2, 2026 20:44

Add childDelta to array nodeChanged retain ops

cdbe1e1

api docs and lint fix

32f933e

daesunp force-pushed the additional-retain-op-info branch from 4718fbf to 32f933e Compare April 2, 2026 20:44

cleanup

db8e531

daesunp marked this pull request as ready for review April 2, 2026 21:17

daesunp requested a review from a team as a code owner April 2, 2026 21:17

Copilot AI review requested due to automatic review settings April 2, 2026 21:17

Copilot started reviewing on behalf of daesunp April 2, 2026 21:17 View session

Copilot AI reviewed Apr 2, 2026

View reviewed changes

daesunp added 3 commits April 2, 2026 21:47

lint fix

8b6fa17

clean up / PR review

e5c37a2

update api docs

647040c

Josmithr reviewed Apr 3, 2026

View reviewed changes

daesunp added 2 commits April 7, 2026 18:05

move payload to treeChanged

92a6ee7

cleanup

6390682

daesunp changed the title ~~Add childDelta to array nodeChanged retain ops~~ array node treeChanged delta payload Apr 7, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

array node treeChanged delta payload#26927

array node treeChanged delta payload#26927
daesunp wants to merge 8 commits intomicrosoft:mainfrom
daesunp:additional-retain-op-info

daesunp commented Apr 2, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 2, 2026

Uh oh!

daesunp Apr 2, 2026

Uh oh!

Copilot AI Apr 2, 2026

Uh oh!

daesunp Apr 2, 2026

Uh oh!

Josmithr Apr 3, 2026

Uh oh!

daesunp Apr 7, 2026

Uh oh!

Josmithr Apr 3, 2026

Uh oh!

daesunp Apr 7, 2026

Uh oh!

github-actions bot commented Apr 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

-		}
+		}
+		if (propertyValue === undefined) {
+			// Optional fields that are cleared are represented as `undefined` in the post-change object view.
+			// `TreeLeafValue` excludes `undefined`, so avoid emitting an invalid leaf delta payload.
+			// Use the existing empty object delta encoding to signal that the property changed without
+			// reporting a nested retained subtree.
+			return { kind: "object", changedProperties: new Map() };
+		}

Conversation

daesunp commented Apr 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

daesunp Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

daesunp Apr 2, 2026

Choose a reason for hiding this comment

Uh oh!

Josmithr Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

daesunp Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Josmithr Apr 3, 2026

Choose a reason for hiding this comment

Uh oh!

daesunp Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Apr 7, 2026

linkcheck output

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

daesunp commented Apr 2, 2026 •

edited

Loading