Support Fluid Framework 3, and bump to 2.0.0-internal.19

[huntj88]

Stacked on #888, which contains the ESM-only build/test migration.

Summary

Adds Fluid Framework 3 support alongside Fluid 2 in 2.0.0-internal.19, with dependency range >=2.102 <2.120 || >=3.0.0 <3.10.0 across packages, samples, and test utilities. The lockfile resolves Fluid 3.0.1.

• Replace the legacy container compatibility argument with FluidOldestSupportedClient = "2.0.0". Fluid 2.102.0 is the first version accepting the SemVer form required by Fluid 3. This raises the installation/build floor without raising the configured collaboration compatibility floor. The constant remains unannotated to support both Fluid type names.
• Replace removed LogLevel.default / .error aliases with .info / .essential, preserving their numeric values.

SharedMap typing

IUseSharedMapResults<TData>.sharedMap now uses TypedSharedMap<TData> | undefined, preserving typed get, forEach, values, and entries, boolean delete, and chainable set with DDS members.

This uses a local MIT-licensed copy of Fluid's map interfaces, not re-exported from the package entry point. Mutator overrides precede FluidMap & SharedMap: changing the copied signatures directly breaks assignability through Fluid's forEach callback. Hook runtime behavior is unchanged.

Consumer-facing type differences and caveats:

• On Fluid 3, the result is no longer assignable to a built-in Map. After checking it is defined, new Map(sharedMap) creates a local, unsynchronized snapshot.
• The third forEach callback argument has Fluid's void mutator returns. Use the outer sharedMap for boolean deletion results or chaining.
• The inherited generic set remains permissive; use setEntry for TData-constrained writes. Use sharedMap.entries() for typed iteration; direct for...of sharedMap retains its previous untyped value inference.

Validation

Local validation on Node 24.14.0, with separate installations and all relevant Fluid dependencies aligned to each tested version:

Check	2.102.0 (floor)	3.0.1 (locked)
All packages, test utilities, and samples build	Pass	Pass
Live Share / canvas / media tests	81 / 17 / 57 passing	81 / 17 / 57 passing
Targeted SharedMap assignment, inference, chaining, and iteration type checks	Pass	Pass

[Jason Hartman (jason-ha)]

Changes are viable as is.
Notes on optional improvements - especially a path to not lose type-safety for IShareMap use.

[Jason Hartman (jason-ha)]

Fluid 3 has no default. Consumers must always pass a value. "2.0.0" though is the lowest supported version.

[Jason Hartman (jason-ha)]

Unless these picked up /beta or /legacy imports (not something I see), then these can be "^2.102.0 || ^3.0.0".

[Jason Hartman (jason-ha)]

Still can use ^2 || ^3 here to simplify maintenance. Not a blocker.

[huntj88]

The latest commit uses  ^2.102.0 || ^3.0.0  for the internal test utilities, so future 2.x/3.x releases no longer need range updates. kept the 2.102 floor to stay aligned with the SDK’s minimum and avoid older-version incompatibilities. Published SDK ranges remain bounded.

[Jason Hartman (jason-ha)]

I was not suggesting use of ^ to add risk. I suggested assuming the specs were good before.
After a search and also noting use of @fluid-internal/test-driver-definitions I see that was not the case. test-utils is definitely doing the unstable stuff.
Since there are internal uses only exact is correct if this package went external. I agree with the new README statement.

[Jason Hartman (jason-ha)]

I think you can drop this comment.

[Jason Hartman (jason-ha)]

This is a little unfortunate on the FF side.
We do want to distance APIs from built-in types since they can change shape and FF might not implement the new features.
The incompatibility here was not intentional and we might patch that for 3.1 that is too late. The alternative here is to make a local copy of https://github.com/microsoft/FluidFramework/blob/main/packages/common/core-interfaces/src/fluidMap.ts and type as FluidMap<string, TData> &. That should be viable for all 2.x and 3.x versions of FF.

[huntj88]

looking at the local-copy approach, with one addition. I have not pushed this code yet, just wanted your opinion first

FluidMap<string, TData> & SharedMap restores get, but FluidMap's delete(key): void / set(key, value): void shadow ISharedMap's own boolean / this, since the FluidMap half comes first in overload order. That would cost consumers if (map.delete(k)) and .set(a, b).set(c, d) — breaks the shipped typing never had. An overrides interface, first in the intersection, puts them back:

export interface ISharedMapValueOverrides<TData> {
    delete(key: string): boolean;
    set(key: string, value: TData): TypedSharedMap<TData>;
}

export type TypedSharedMap<TData> = ISharedMapValueOverrides<TData> &
    FluidMap<string, TData> &
    SharedMap;

These only restate what ISharedMap already declares, so they match runtime — and FluidMap's doc comment anticipates it ("subtypes may override this to return a boolean if appropriate").

Verified with tsc --strict on both ends of the range, 2.102.0 and 3.0.1, assigning a real SharedMap in a generic context as useSharedMap does: get, delete, set chaining, forEach / values / entries / for..of, and the DDS members all behave as they do today. The one thing no typing can preserve is const m: Map<string, TData> = sharedMap — Fluid 3's SharedMap isn't a Map, so that's TS2322 now; consumers copy (new Map(sharedMap)) or use getEntry / setEntry. Release-notes item.

The copy lives in packages/live-share-react/src/types/FluidMap.ts, verbatim apart from our prettier config, and isn't re-exported from the entry point so the names can't collide with Fluid's own. It gets deleted when we drop 2.x.

Before I push — do the delete / set overrides look safe to you long-term, and if the 3.1 patch lands, does the local copy become unnecessary?

[Jason Hartman (jason-ha)]

The return type of delete and set should be boolean and this respectively for 3.0+. At least that is what I get with this mock up:

interface ISharedMap
	extends FluidMap<string, any> {
	get<T = any>(key: string): T | undefined;
	set<T = unknown>(key: string, value: T): this;
	delete(key: string): boolean;
}
type setReturn = ReturnType<(FluidMap<string, any> & ISharedMap)["set"]>;
type deleteReturn = ReturnType<(FluidMap<string, any> & ISharedMap)["delete"]>;

For <3.0, I see the same.
It would be okay for live-share FluidMap to declare set and delete to match ISharedMap declarations since that is the only place things are combined.

3.1 won't really solve the issue.

[Jason Hartman (jason-ha)]

Node20+ and TS5.9+ support require-esm. This would be sufficient to retain CommonJS and use FF 3.x, but moving to just ESM is probably better. The same require-esm feature will allow live-share CommonJS consumers to use ESM only version of live-share packages.
Official FF statement is that CommonJS is not supported as FF wants to reserve the right to use top-level awaits. FF would only actually do so at a 3.x0.0 boundary; so, the current >=3.0 <3.10 dep spec protects against trouble.

This comment is really just for give complete information.

[Jason Hartman (jason-ha)]

I am a little surprised these are needed. My quick tests said they weren't needed. Not a blocker but I am curious what I missed.

[huntj88]

The difference is  ReturnType<>  versus actual calls: your probe picks the last signature, while calls here match  FluidMap ’s earlier void overloads. Without the overrides, boolean deletion checks and set chaining fail. Confirmed with TS 5.5.4 / Fluid 3.0.1.

Changing the copied FluidMap signatures instead breaks assignability through forEach’s callback-map type, so the separate overrides preserve both compatibility and the expected return types.

[huntj88]

maybe something like this instead?

[Jason Hartman (jason-ha)]

Given the elements involved I don't see a better solution.
I've learned that the competing definitions are not combined but are treated as overloads. Type processing picks the last signature, but an actual call uses the first that matches and they all match. Tricky.

[Jason Hartman (jason-ha)]

Still can use ^2 || ^3 here to simplify maintenance. Not a blocker.

[Jason Hartman (jason-ha)]

When I looked at live-share code to see exactly what you were seeing, I noticed that at least @microsoft/08.3d-model is not well configured. Since live-share-react is import only and @microsoft/08.3d-model is CommonJS (no "type": "module" in package.json and tsconfig.json is using "module": "Node16"), these are unhappy. I had a completely successful "build"; so, I guess something is messing with settings or doesn't respect the full rules.
04.live-share-react tsconfig.json is using ESNext+Bundler.