improvement(client-presence): Json in-out improvements

[jason-ha]

Externally:

• reduce data in requirement to JsonSerializable as that is sufficient. See test(client-core-interfaces): JsonSerializable is enough #24751. Corresponding "local" events are updated to match.

Internally:

• use OpaqueJsonDeserialized as stored and message type for generic (unknown) cases. system:presence workspace data values are kept exact under interface ConnectionValueState.
• add helpers for needed conversions

---

Co-authored-by: Tyler Butler tylerbu@microsoft.com

[Copilot]

Pull Request Overview

This PR improves JSON input/output handling for client-presence by simplifying the externally required data to JsonSerializable and switching internal handling to use OpaqueJsonDeserialized. In addition, the changes update tests and internal helpers to consistently wrap and unwrap JSON values using the new opaque JSON utilities.

• Removed the redundant JsonDeserialized requirement in initial values.
• Updated tests to wrap literal JSON objects with toOpaqueJson.
• Refactored multiple components (including notifications, value managers, and internal utilities) to use opaque JSON conversion and reveal functions.

Reviewed Changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
packages/framework/presence/src/test/presenceStates.spec.ts	Updated the createValueManager signature to remove the redundant JsonDeserialized.
packages/framework/presence/src/test/presenceDatastoreManager.spec.ts	Replaced raw JSON objects with toOpaqueJson wrappers in test cases.
packages/framework/presence/src/test/notificationsManager.spec.ts	Updated notification test values to use opaque JSON wrapping.
packages/framework/presence/src/test/latestValueManager.spec.ts	Added an extra test for inferred nullable types and adjusted opaque JSON usage.
packages/framework/presence/src/test/latestMapValueManager.spec.ts	Renamed a key from "true" to "boolean" and used toOpaqueJson consistently.
packages/framework/presence/src/test/batching.spec.ts	Replaced inline JSON values with toOpaqueJson wrappers for consistency.
packages/framework/presence/src/systemWorkspace.ts	Refactored state update handling with revealOpaqueJson for JSON unwrapping.
packages/framework/presence/src/notificationsManager.ts	Converted notification payload values using toOpaqueJson and revealOpaqueJson.
packages/framework/presence/src/latestValueManager.ts	Adjusted local value setter to wrap the value with toOpaqueJson and use a new shallow clone helper.
packages/framework/presence/src/latestMapValueManager.ts	Applied opaque JSON conversion in set and emit methods.
packages/framework/presence/src/internalUtils.ts	Introduced new helper functions (toOpaqueJson, revealOpaqueJson, asDeeplyReadonlyDeserializedJson) for opaque JSON conversion.
packages/framework/presence/api-report/*	Updated API types and documentation to reflect the new opaque JSON conventions.

Comments suppressed due to low confidence (4)

packages/framework/presence/src/test/latestMapValueManager.spec.ts:204

• The key has been renamed from 'true' to 'boolean'; verify that no consumer of this test data relies on the previous key naming to avoid breaking changes.

boolean: true,

packages/framework/presence/src/notificationsManager.ts:247

• The use of revealOpaqueJson to unwrap the notification update payload is a key design change. Please ensure that the structure of the unwrapped value matches the expected notification format throughout the system.

const value = revealOpaqueJson(updateValue.value);

packages/framework/presence/src/test/presenceStates.spec.ts:46

• The change to remove JsonDeserialized from the initial value type is clear; please ensure that downstream code expects only JsonSerializable without relying on deserialized data.

initial: JsonSerializable<T>,

packages/framework/presence/src/latestValueManager.ts:128

• Using toOpaqueJson to wrap the value in the local setter enforces opaque JSON conversion. Confirm that this change aligns with the expected handling of JSON values in all related components.

this.value.value = toOpaqueJson<T>(value);

[tylerbutler]

Just a couple of docs nits. Thanks for pulling this together.

[Josmithr]

Wrong type used here. I also generally recommend against repeating the name of the item in its docs.

Suggested change

	* `ValueRequiredState` is used to represent a state that may have a value.
	* Represents a state that may have a value.

[jason-ha]

Using the name is continued trial of addressing the style/format question from end of May. (Awaiting yours and @WayneFerrao's comment) See last message: #24718 (comment)
I think we are likely to get the name wrong like this; so I think we don't have it. Full sentences? Use period even if not?

[Josmithr]

Replied in the other PR. Sorry, never saw that comment.

[Josmithr]

Left some nitpicks, but overall looks good to me.

[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:
  222981 links
    1707 destination URLs
    1939 URLs ignored
       0 warnings
       0 errors