feat(tree): reapply "feat: add fluid-controlled map interfaces"

[jenn-le]

This reapplies #27688 with a fix to the FluidIterableIterator interface that was causing downstream call sites to infer the type with undefined.

[Copilot]

Pull request overview

This PR reapplies the previously reverted “fluid-controlled map interfaces” change by introducing FluidIterable* / Fluid*Map types in @fluidframework/core-interfaces, then updating @fluidframework/tree (and fluid-framework re-exports) to use FluidReadonlyMap-based iteration to avoid downstream breakage from TypeScript stdlib iterator type changes.

Changes:

• Add FluidIterable, FluidIterableIterator, FluidReadonlyMap, and FluidMap to @fluidframework/core-interfaces (with type-level tests validating assignability and inference behavior).
• Update TreeIndex to extend FluidReadonlyMap, and add TreeMapNodeAlpha to provide FluidReadonlyMap-based iteration for map nodes.
• Re-export the new core-interfaces types through fluid-framework, and update API reports / docs accordingly.

Reviewed changes

Copilot reviewed 20 out of 20 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
packages/framework/fluid-framework/src/index.ts	Re-exports new map/iterator types via @fluidframework/core-interfaces/internal.
packages/framework/fluid-framework/api-report/fluid-framework.alpha.api.md	API report updates reflecting new exports and updated tree map/index types.
packages/dds/tree/src/test/simple-tree/api/schemaFactory.spec.ts	Updates test casting to use TreeMapNodeAlpha for map iteration.
packages/dds/tree/src/simple-tree/node-kinds/map/mapNodeTypes.ts	Updates schema type definitions/docs to reference TreeMapNodeAlpha.
packages/dds/tree/src/simple-tree/node-kinds/map/mapNode.ts	Introduces TreeMapNodeAlpha and updates map schema implementation to implement it.
packages/dds/tree/src/simple-tree/node-kinds/map/index.ts	Exports TreeMapNodeAlpha from the map node-kind barrel.
packages/dds/tree/src/simple-tree/node-kinds/index.ts	Re-exports TreeMapNodeAlpha from node-kinds barrel.
packages/dds/tree/src/simple-tree/index.ts	Re-exports TreeMapNodeAlpha from simple-tree barrel.
packages/dds/tree/src/simple-tree/api/schemaFactoryAlpha.ts	Updates docs to reference TreeMapNodeAlpha.
packages/dds/tree/src/index.ts	Re-exports TreeMapNodeAlpha from the package root barrel.
packages/dds/tree/src/feature-libraries/indexing/types.ts	Switches TreeIndex from ReadonlyMap to FluidReadonlyMap.
packages/dds/tree/src/feature-libraries/indexing/anchorTreeIndex.ts	Adds [Symbol.toStringTag] to satisfy the new FluidReadonlyMap requirement.
packages/dds/tree/src/entrypoints/alpha.ts	Adds TreeMapNodeAlpha to alpha entrypoint exports.
packages/dds/tree/src/api.ts	Adds asAlpha(TreeMapNode) -> TreeMapNodeAlpha overload.
packages/dds/tree/api-report/tree.alpha.api.md	API report updates for TreeIndex and new TreeMapNodeAlpha.
packages/common/core-interfaces/src/test/types/fluidMapTypes.ts	Adds compile-time type tests for the new interfaces and iterator inference behavior.
packages/common/core-interfaces/src/index.ts	Exports the new map/iterator interfaces from the main barrel.
packages/common/core-interfaces/src/fluidMap.ts	Adds definitions for FluidIterable* and Fluid*Map interfaces (incl. iterator return branch typing).
packages/common/core-interfaces/api-report/core-interfaces.legacy.alpha.api.md	API report updates reflecting new alpha interfaces.
.changeset/bright-bananas-yell.md	Changeset documenting the new interfaces and tree API adjustments.

[Copilot]

Schema sets an own [Symbol.toStringTag] value of "TreeMapNodeSchema". When useMapPrototype is true, the instance’s prototype is faked to Map.prototype to emulate an ES6 Map, but this own property will override Map.prototype[Symbol.toStringTag] ("Map") and change Object.prototype.toString.call(node) away from [object Map]. Consider using the standard "Map" tag (or only overriding when not emulating a Map) to preserve the intended Map emulation behavior.

Suggested change

	public readonly [Symbol.toStringTag] = "TreeMapNodeSchema";
	public get [Symbol.toStringTag](): string {
	return useMapPrototype ? "Map" : "TreeMapNodeSchema";
	}

[github-actions]

🔗 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