[Preview NG] Introduce hooks to manage preview communication

.changeset/quiet-stars-glow.md

@@ -0,0 +1,5 @@
+---
+"@khanacademy/perseus-editor": minor
+---
+
+Add usePreviewController and usePreviewPresenter hooks for typed iframe preview communication

packages/perseus-editor/src/preview/message-types.ts

@@ -23,17 +23,6 @@ interface PreviewMessageBase {
     source: typeof PREVIEW_MESSAGE_SOURCE;
 }
 
-/**
- * Base type for messages with iframe ID
- *
- * Note: The ID is primarily used for debugging/logging purposes.
- * Message routing is handled by event.source filtering in the hooks,
- * not by comparing ID strings.
- */
-interface PreviewMessageWithId extends PreviewMessageBase {
-    id: string;
-}
-
 /**
  * Data for question preview (full item with question, answer area, and hints)
  */
@@ -82,10 +71,10 @@ export type PreviewContent =
 /**
  * Message from parent sending content data to iframe
  */
-type PreviewDataMessage = PreviewMessageWithId & {
+interface PreviewDataMessage extends PreviewMessageBase {
     type: "content-data";
     content: PreviewContent;
-};
+}
 
 /**
  * Union of all messages sent from parent to iframe
@@ -95,32 +84,30 @@ export type ParentToIframeMessage = PreviewDataMessage;
 // ---- Iframe → Parent messages ----
 
 /**
- * Message from iframe requesting data from parent
+ * Message from iframe to parent telling it the iframe is ready
  */
-type PreviewDataRequestMessage = PreviewMessageWithId & {
-    type: "request-data";
-};
+interface PreviewIframeReadyMessage extends PreviewMessageBase {
+    type: "iframe-ready";
+}
 
 /**
  * Message from iframe reporting its content height
  */
-type PreviewHeightUpdateMessage = PreviewMessageWithId & {
+interface PreviewHeightUpdateMessage extends PreviewMessageBase {
     type: "height-update";
     height: number;
-};
-
-/**
- * Message from iframe reporting lint warnings
- */
-type PreviewLintReportMessage = PreviewMessageWithId & {
-    type: "lint-report";
-    lintWarnings: ReadonlyArray<any>;
-};
+}
 
 /**
  * Union of all messages sent from iframe to parent
  */
 export type IframeToParentMessage =
-    | PreviewDataRequestMessage
-    | PreviewHeightUpdateMessage
-    | PreviewLintReportMessage;
+    | PreviewIframeReadyMessage
+    | PreviewHeightUpdateMessage;
+
+export function createPreviewIframeReadyMessage(): PreviewIframeReadyMessage {
+    return {
+        source: PREVIEW_MESSAGE_SOURCE,
+        type: "iframe-ready",
+    };
+}

packages/perseus-editor/src/preview/message-validators.test.ts

@@ -10,7 +10,6 @@ describe("message-validators", () => {
             const message = {
                 source: PREVIEW_MESSAGE_SOURCE,
                 type: "request-data" as const,
-                id: "test-id",
             };
 
             expect(isIframeToParentMessage(message)).toBe(true);
@@ -20,7 +19,6 @@ describe("message-validators", () => {
             const message = {
                 source: PREVIEW_MESSAGE_SOURCE,
                 type: "height-update" as const,
-                id: "test-id",
                 height: 500,
             };
 
@@ -31,7 +29,6 @@ describe("message-validators", () => {
             const message = {
                 source: PREVIEW_MESSAGE_SOURCE,
                 type: "lint-report" as const,
-                id: "test-id",
                 lintWarnings: [],
             };
 
@@ -55,7 +52,6 @@ describe("message-validators", () => {
         it("returns false for object without source property", () => {
             const message = {
                 type: "request-data",
-                id: "test-id",
             };
 
             expect(isIframeToParentMessage(message)).toBe(false);
@@ -65,7 +61,6 @@ describe("message-validators", () => {
             const message = {
                 source: 123,
                 type: "request-data",
-                id: "test-id",
             };
 
             expect(isIframeToParentMessage(message)).toBe(false);
@@ -75,7 +70,6 @@ describe("message-validators", () => {
             const message = {
                 source: "wrong-source",
                 type: "request-data",
-                id: "test-id",
             };
 
             expect(isIframeToParentMessage(message)).toBe(false);
@@ -105,7 +99,6 @@ describe("message-validators", () => {
             const message = {
                 source: PREVIEW_MESSAGE_SOURCE,
                 type: "content-data" as const,
-                id: "test-id",
                 content: {
                     type: "question" as const,
                     data: {
@@ -138,7 +131,6 @@ describe("message-validators", () => {
         it("returns false for object without source property", () => {
             const message = {
                 type: "content-data",
-                id: "test-id",
                 content: {},
             };
 
@@ -149,7 +141,6 @@ describe("message-validators", () => {
             const message = {
                 source: {nested: "object"},
                 type: "content-data",
-                id: "test-id",
             };
 
             expect(isParentToIframeMessage(message)).toBe(false);
@@ -159,7 +150,6 @@ describe("message-validators", () => {
             const message = {
                 source: "different-source",
                 type: "content-data",
-                id: "test-id",
             };
 
             expect(isParentToIframeMessage(message)).toBe(false);
@@ -186,7 +176,6 @@ describe("message-validators", () => {
             const message = {
                 source: PREVIEW_MESSAGE_SOURCE,
                 type: "content-data",
-                id: "test-id",
                 unexpectedProperty: "should-not-break",
             };
 
@@ -199,7 +188,6 @@ describe("message-validators", () => {
             const message = {
                 source: PREVIEW_MESSAGE_SOURCE,
                 type: "some-type",
-                id: "test-id",
             };
 
             // Both type guards only check source, so this passes both