Changed Elements V3 API Support

[diegopinate]

This PR adds support for the Changed Elements V3 API (currently in Tech Preview), while keeping existing V1/V2 behavior unchanged.

See API documentation (requires login until Tech Preview is finalized).

What changed

• Added a new DiffJobClient for V3, with the V3 request/response shape normalized so the rest of the app can keep using the existing comparison flow.
• Kept V2 support intact, and added an apiVersion prop to ChangedElementsWidget to choose between v1, v2, and v3.
• Added V3 feature tracking when the compare dialog opens in V3 mode.
• Added a test app flag, VITE_USE_V3_COMPARISON=true, to switch the test app to V3.

Compatibility

• Existing V2 consumers do not need to change anything unless they want to upgrade.
• useV2Widget still works, but apiVersion is now the preferred option.
• Custom IComparisonJobClient implementations now need to provide apiVersion.

[changeset-bot]

🦋 Changeset detected

Latest commit: 1f95416

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@itwin/changed-elements-react	Major

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[Copilot]

Pull request overview

Adds Changed Elements V3 (tech preview) support by introducing a V3-backed comparison-job client and wiring API-version selection through the widget while preserving existing V1/V2 behavior.

Changes:

• Introduces DiffJobClient (V3) that normalizes V3 diff-job requests/responses into the existing IComparisonJobClient shape.
• Adds apiVersion support to ChangedElementsWidget (with useV2Widget deprecated) and performs an apiVersion consistency check in the V2/V3 modal.
• Updates test app + docs and adds a comprehensive DiffJobClient unit test suite.

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
packages/test-app-frontend/src/environment.ts	Adds VITE_USE_V3_COMPARISON flag wiring for the test app.
packages/test-app-frontend/src/App/ITwinJsApp/ITwinJsApp.tsx	Switches between ComparisonJobClient (v2) and DiffJobClient (v3) based on env flag; passes apiVersion to widget.
packages/test-app-frontend/.env	Documents new V3 flag.
packages/changed-elements-react/src/widgets/comparisonJobWidget/components/VersionCompareSelectModal.tsx	Adds apiVersion prop + client/version mismatch guard; adjusts pending/running job keying.
packages/changed-elements-react/src/widgets/ChangedElementsWidget.tsx	Adds apiVersion prop (prefers over useV2Widget), resolves mode, and adds V3 feature tracking hook.
packages/changed-elements-react/src/tests/DiffJobClient.test.ts	Adds unit tests covering V3 job posting, composite-id resolution, strategy filtering, and error mapping.
packages/changed-elements-react/src/index.ts	Exports DiffJobClient and additional comparison-job types.
packages/changed-elements-react/src/clients/IComparisonJobClient.ts	Adds apiVersion, diffing strategy types, and expands job/request typing for V2/V3 compatibility.
packages/changed-elements-react/src/clients/DiffJobClient.ts	Implements V3 diff job client with composite-id resolution and normalized job shapes.
packages/changed-elements-react/src/clients/ComparisonJobClient.ts	Adds apiVersion and enforces ID-based posting for v2 client.
packages/changed-elements-react/src/api/VersionCompare.ts	Extends feature tracking interface for optional V3 selector usage tracking.
packages/changed-elements-react/README.md	Updates usage docs for v2/v3 setup and new apiVersion prop.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 5 comments.

[Copilot]

Pull request overview

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

[CalebGerman]

Looks structurally correct to me. But I do not know the details of V3 so @mattbjordan may need to review as well. Just left nit picks