feat(CODAP-1092): notify/reload plugins on locale change

[kswenson]

Summary

• Adds ?lang= query parameter to iframe URLs for localized plugins (Importer, TP-Sampler, Scrambler, storyBuilder) so they reload with the correct locale when the user switches language
• Includes lang in the interactiveFrame.get API response so plugins can read the current locale
• Broadcasts a localeChanged notification to non-localized plugins via iframePhone so they can react programmatically
• Adds handlesLocaleChange opt-out: plugins that handle locale changes themselves can set this via interactiveFrame.update to prevent automatic reload

How it works

1. Localized plugins (matched by URL patterns in kLocalizedPluginPatterns): their iframe src gets ?lang=<locale> appended, which changes when locale changes, triggering an iframe reload. The iframePhone connection is torn down and re-established via a localeVersion counter in the useEffect deps.

2. All other plugins: receive a localeChanged notification via broadcastMessage(), matching V2 behavior. Their iframe src doesn't change, so they don't reload.

3. Opt-out mechanism: plugins can call interactiveFrame.update({ handlesLocaleChange: true }) to signal they handle locale changes programmatically, which prevents automatic reload even for localized plugins.

Test plan

• Verify localized plugins (Importer, TP-Sampler, Scrambler, storyBuilder) reload when switching locale
• Verify non-localized plugins do NOT reload when switching locale
• Verify interactiveFrame.get returns lang property
• Verify interactiveFrame.update({ handlesLocaleChange: true }) prevents reload
• Run npm test — all 2138 tests pass
• Run TypeScript type check — clean

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 86.04651% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 85.51%. Comparing base (2a3224a) to head (eaf4b50).
⚠️ Report is 81 commits behind head on main.

Files with missing lines	Patch %	Lines
...onents/web-view/use-data-interactive-controller.ts	57.14%	6 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2392      +/-   ##
==========================================
+ Coverage   85.45%   85.51%   +0.05%     
==========================================
  Files         753      753              
  Lines       41500    41540      +40     
  Branches    10235    10257      +22     
==========================================
+ Hits        35462    35521      +59     
+ Misses       6028     6006      -22     
- Partials       10       13       +3     

Flag	Coverage Δ
cypress	69.62% <61.11%> (+0.05%)	⬆️
jest	56.91% <65.11%> (+0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[cypress]

codap-v3    Run #10421

Run Properties:   Passed #10421  •  870c1538ee: Merge pull request #2392 from concord-consortium/CODAP-1092-plugin-locale-switch...

Project	codap-v3
Branch Review	main
Run status	Passed #10421
Run duration	05m 30s
Commit	870c1538ee: Merge pull request #2392 from concord-consortium/CODAP-1092-plugin-locale-switch...
Committer	Kirk Swenson
View all properties for this run ↗︎

---

Test results
Failures	0
Flaky	1
Pending	73
Skipped	0
Passing	300
View all changes introduced in this branch ↗︎

[Copilot]

Pull request overview

Implements locale-change support for embedded plugins in CODAP v3 by reloading a small set of known localized plugins via ?lang= iframe URL changes, while notifying other plugins of locale changes via iframePhone.

Changes:

• Extend the Data Interactive interactiveFrame API to expose current lang and accept handlesLocaleChange (opt-out of reload).
• Add localized-plugin detection (kLocalizedPluginPatterns + needsLocaleReload) and compute iframe src with ?lang= for those plugins.
• Add a MobX locale reaction in the web-view DI controller to either trigger reconnect (localized) or broadcast localeChanged (others), plus URL utility + tests.

Reviewed changes

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

Show a summary per file

File	Description
v3/src/data-interactive/handlers/interactive-frame-handler.ts	Returns lang and persists handlesLocaleChange onto the WebView model.
v3/src/data-interactive/handlers/interactive-frame-handler.test.ts	Adds coverage for lang in get() and handlesLocaleChange in update().
v3/src/data-interactive/data-interactive-types.ts	Extends DIInteractiveFrame with lang and handlesLocaleChange.
v3/src/components/web-view/web-view.tsx	Uses a derived iframeSrc that appends ?lang= only for reload-needed plugins.
v3/src/components/web-view/web-view-utils.ts	Adds appendLangParam() helper for updating/adding the lang query param.
v3/src/components/web-view/web-view-utils.test.ts	Adds unit tests for appendLangParam() behavior.
v3/src/components/web-view/web-view-model.ts	Adds handlesLocaleChange + needsLocaleReload view and setter.
v3/src/components/web-view/web-view-model.test.ts	Adds tests for needsLocaleReload and the new volatile flag.
v3/src/components/web-view/web-view-defs.ts	Defines kLocalizedPluginPatterns list used to decide reload behavior.
v3/src/components/web-view/use-data-interactive-controller.ts	Adds locale-change reaction to bump a version counter or broadcast localeChanged.
v3/doc/plugin-locale-switching-design.md	Adds a design doc for the approach.
v3/doc/2026-02-14-plugin-locale-switching.md	Adds an implementation plan doc for the feature.

---

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

[Copilot]

Pull request overview

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

---

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

[dougmartin]

Looks good 👍