[Preview NG] Add typed preview message protocol with validators

[jeremywiebe]

Summary:

This PR is part of a series building a typed, hook-based preview system for the Perseus editor. The new system replaces the untyped window.iframeDataStore + raw postMessage(string) communication with structured, validated message passing via usePreviewHost and usePreviewClient hooks. The new system is being built alongside the old one — no existing behaviour changes until the final PR in the series flips the switch.

---

Adds the typed message protocol that will underpin a new hook-based preview system for the Perseus editor. These types will allow us to understand and more easily control the data that is being sent between the editor and the preview iframe (in both directions). Purely additive — no existing behavior is changed.

The existing message-types.ts defined data types for preview content but had no structure for the messages themselves. This PR adds a PREVIEW_MESSAGE_SOURCE constant, base interfaces for structured messages, typed message definitions for both directions (iframe-to-parent and parent-to-iframe), and union types for use in message event handlers. New type guards in message-validators.ts safely narrow unknown postMessage events.

All existing types and the preview renderer are untouched — the new protocol types will be consumed by hooks in subsequent PRs.

Issue: LEMS-3741

Test plan:

pnpm test

[github-actions]

🗄️ Schema Change: No Changes ✅

[github-actions]

🛠️ Item Splitting: No Changes ✅

[github-actions]

Size Change: 0 B

Total Size: 499 kB

ℹ️ View Unchanged

Filename	Size
packages/kas/dist/es/index.js	20.5 kB
packages/keypad-context/dist/es/index.js	1 kB
packages/kmath/dist/es/index.js	6.36 kB
packages/math-input/dist/es/index.js	98.5 kB
packages/math-input/dist/es/strings.js	1.61 kB
packages/perseus-core/dist/es/index.item-splitting.js	11.9 kB
packages/perseus-core/dist/es/index.js	25.1 kB
packages/perseus-editor/dist/es/index.js	102 kB
packages/perseus-linter/dist/es/index.js	9.3 kB
packages/perseus-score/dist/es/index.js	9.7 kB
packages/perseus-utils/dist/es/index.js	403 B
packages/perseus/dist/es/index.js	195 kB
packages/perseus/dist/es/strings.js	8.27 kB
packages/pure-markdown/dist/es/index.js	1.39 kB
packages/simple-markdown/dist/es/index.js	6.71 kB

_{compressed-size-action}

[github-actions]

npm Snapshot: Published

Good news!! We've packaged up the latest commit from this PR (7a3dded) and published it to npm. You
can install it using the tag PR3474.

Example:

pnpm add @khanacademy/perseus@PR3474

If you are working in Khan Academy's frontend, you can run the below command.

./dev/tools/bump_perseus_version.ts -t PR3474

If you are working in Khan Academy's webapp, you can run the below command.

./dev/tools/bump_perseus_version.js -t PR3474

[claude]

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review to trigger a review and subscribe this PR to future pushes, or @claude review once for a one-time review.

_{Tip: disable this comment in your organization's Code Review settings.}

[mark-fitzgerald]

Since these two functions are equivalent, does that mean that this scaffolding is here for future changes that would cause them to diverge? If such future changes are not expected in the near term, perhaps a comment somewhere on this page explaining the expected nature of the changes?

[jeremywiebe]

Yes. These two function are used in upcoming PRs to filter and type check messages coming into a context via postMessage().

I wanted to make the PRs as small as possible so they are by themselves in a PR. I'd like to avoid hedging these comments and just state them as they'll be in the final state if that's ok.