postMessage scroll control for usingandunderstanding.ai embed mode

Context

I'm building a slide deck (reveal.js, deployed at https://geoffreychallen.com/mdx/talks/2026-05-12-the-new-computing/, served from http://localhost:3000 in dev) that embeds the site in an <iframe> with ?embed=true&colorScheme=light. The embedded page has more content than fits on the slide, and I want the presenter to be able to scroll the embed remotely (from a slide-side button or keypress) without clicking into the iframe and stealing focus from reveal's slide-nav.

Because the iframe is cross-origin, the parent can't call contentWindow.scrollTo directly. The site has to opt in by listening for a postMessage and scrolling itself.

What to implement

Add a message event listener that runs only when embed mode is active (i.e., the ?embed=true codepath that already adds body.embed-mode). The natural home is the existing EmbedMode client component (the one that currently sets the body class and calls setTheme(colorScheme)).

Message protocol

The parent will send messages of the form:

type ScrollMessage =
  | { type: "uai:scroll-by"; delta: number; smooth?: boolean }      // scrollBy({ top: delta })
  | { type: "uai:scroll-to"; top: number; smooth?: boolean }        // scrollTo({ top })
  | { type: "uai:scroll-page"; direction: "up" | "down"; smooth?: boolean }; // ~viewport-height jump

All three should call window.scrollBy/window.scrollTo on the iframe's own window with behavior: smooth ? "smooth" : "auto" (default true).

The uai: prefix is just a namespace so we don't collide with other senders.

Security

Hard-allowlist the parent origin. Reject anything else silently. Allowlist these three:

const ALLOWED_PARENT_ORIGINS = new Set([
  "https://geoffreychallen.com",
  "https://www.geoffreychallen.com",
  "http://localhost:3000",
]);

Check event.origin against that set on every message. Don't trust event.source or event.data until origin passes.

Lifecycle

• Attach the listener in useEffect only when embed === "true".
• Return a cleanup that removes it.
• Do not attach when embed mode is off — we don't want random pages on the site to be scrollable by arbitrary framers.

Sketch

useEffect(() => {
  if (!isEmbedMode) return;
  function onMessage(event: MessageEvent) {
    if (!ALLOWED_PARENT_ORIGINS.has(event.origin)) return;
    const msg = event.data;
    if (!msg || typeof msg !== "object") return;
    const behavior: ScrollBehavior = msg.smooth === false ? "auto" : "smooth";
    switch (msg.type) {
      case "uai:scroll-by":
        if (typeof msg.delta === "number") window.scrollBy({ top: msg.delta, behavior });
        break;
      case "uai:scroll-to":
        if (typeof msg.top === "number") window.scrollTo({ top: msg.top, behavior });
        break;
      case "uai:scroll-page": {
        const delta = window.innerHeight * 0.9 * (msg.direction === "up" ? -1 : 1);
        window.scrollBy({ top: delta, behavior });
        break;
      }
    }
  }
  window.addEventListener("message", onMessage);
  return () => window.removeEventListener("message", onMessage);
}, [isEmbedMode]);

How the parent will use it

For reference (you don't need to write this — it lives on my side):

iframe.contentWindow.postMessage(
  { type: "uai:scroll-page", direction: "down" },
  "https://usingandunderstanding.ai"
);

Acceptance

• With ?embed=true, posting {type:"uai:scroll-page", direction:"down"} from an allowed origin scrolls the page down ~one viewport.
• With ?embed=true but a non-allowlisted parent origin, posting the same message does nothing.
• Without ?embed=true (normal page load), the listener is not attached at all.
• No regressions to the existing setTheme / embed-mode body-class behavior.

Also, please

While you're in there, please drop the gate that requires embed=true for colorScheme to take effect — I want ?colorScheme=light to work on the public homepage too, with or without embed mode. (You already mentioned this is in progress.)

Your task

First, run git status, git diff, and git log --oneline -10 to understand the current state.

Then add and commit all modified files with a descriptive message. Break the changes into multiple commits if appropriate. If there are untracked files, ask if they should be added or added to the appropriate .gitignore file. The user may also want to take over at this point, so provide an abort option as well. Always check changes for unnecessary debugging statements or logging that might have been accidentally included. Prompt the user if you find any, and offer to remove each one by one. Do not use interactive git staging (git add -p) as it does not work.

Can we make it possible to embed the learning animations, like the digit explorer? The embed would have only the component itself, no chrome, no additional explanation. We could add embed links to the resources page or the per-resource pedagogical explanation.

Your task

First, run git status, git diff, and git log --oneline -10 to understand the current state.

Then add and commit all modified files with a descriptive message. Break the changes into multiple commits if appropriate. If there are untracked files, ask if they should be added or added to the appropriate .gitignore file. The user may also want to take over at this point, so provide an abort option as well. Always check changes for unnecessary debugging statements or logging that might have been accidentally included. Prompt the user if you find any, and offer to remove each one by one. Do not use interactive git staging (git add -p) as it does not work.

Your task

First, run git status, git diff, and git log --oneline -10 to understand the current state.

Then add and commit all modified files with a descriptive message. Break the changes into multiple commits if appropriate. If there are untracked files, ask if they should be added or added to the appropriate .gitignore file. The user may also want to take over at this point, so provide an abort option as well. Always check changes for unnecessary debugging statements or logging that might have been accidentally included. Prompt the user if you find any, and offer to remove each one by one. Do not use interactive git staging (git add -p) as it does not work.