`BrowserWidget` module for `@effect/platform-browser`

[harrysolovay]

Proposal: BrowserWidget module for @effect/platform-browser

Summary

A small, typed abstraction for launching a cross-origin UI ("widget") in an
iframe or popup and consuming what it sends back as a Stream. The widget is
described via schemas (payload in, items out, error out); a
Launcher service decides how the widget is mounted (embedded iframe vs.
popup window); calling launch returns a Stream whose lifecycle is the
widget's lifecycle.

Motivation

Any browser app that hosts a third-party or cross-origin UI ends up
hand-rolling the same things:

• build a URL with the initial state encoded in the query string
• create an iframe / open a popup, size it, set sandbox / allow
• subscribe to window message events, filter by source, validate data
• know when the child is finished, tear the element down
• surface all of this to the caller as something they can await / compose

Every one of those steps has a natural Effect answer already, but nothing
ties them together. The result is that this logic lives as ad-hoc glue in
app code and is hard to test or swap (e.g. embed in prod, popup in dev,
a no-op launcher in tests).

Core ideas

1. Define the widget schemas

import { Schema as S } from "effect"
import { BrowserWidget } from "@effect/platform-browser"

export const LinkWidget = BrowserWidget.make({
  pathname: "link",
  payload: S.Struct({ challengeId: LinkChallengeId, allowance: Allowance }),
  item: S.Void,     // messages the widget posts back to the host
  error: S.Never,   // typed failure the widget can report
})

• payload is encoded into URL search params (S.toCodecStringTree →
  S.fromURLSearchParams → UrlParams), so the widget page can decode its
  initial state with the same schema on the other side.
• item is the schema of each message the widget posts back to the host.
• error is the typed error channel. The stream's error type is
  LaunchError | UrlError | SchemaError | E.
• The widget also implements Standard Schema for its payload, so it can be
  handed directly to form libraries / validators.

2. Launching a widget is running a stream

// Host side
yield* BrowserWidget.launch(LinkWidget, { challengeId, allowance }).pipe(
  Stream.runDrain,
)

There's no separate "open" / "close" / "subscribe" API. launch returns a
Stream<A, E, R>:

• Running the stream launches the widget. Nothing is mounted until the
  stream is consumed.
• Each element is a validated message from the widget (S.is(item)),
  filtered by event.source so you never see messages from other frames.
• The stream ends when the widget signals done (a well-known
  postMessage sent by the widget's Self.postFinished()).
• Interrupting the stream tears down the widget. The iframe is removed /
  the popup is closed via a scope finalizer, so cancellation, timeouts,
  Stream.take, racing, etc. all just work.

Because it's a Stream, all the usual combinators apply: Stream.take(1)
for a one-shot result, Stream.timeout, Stream.runCollect, Stream.merge
with other event sources, and so on.

3. The launcher is a service

class Launcher extends Context.Service<Launcher, {
  readonly launch: <Payload, A, E>(
    widget: Widget<Payload, A, E>,
    payload: Payload["Type"],
  ) => Stream.Stream<A["Type"], Launcher.Error<E>, Payload["EncodingServices"]>
}>()("@effect/platform-browser/BrowserWidget/Launcher") {}

Two layers ship out of the box:

• EmbedLauncher.layer({ url, className }): creates a full-viewport,
  transparent, sandboxed <iframe>.
• PopupLauncher.layer({ url }): window.opens the widget, closes it
  on scope close.

App code is written once against Launcher; the choice of embed vs. popup
is a layer decision. This also makes widgets trivially testable: provide a
Launcher that returns Stream.make(...) and the calling code never
touches the DOM.

4. The widget side

The child page gets a tiny Self module:

• Self.parent(): window.opener ?? window.parent, i.e. "whoever launched
  me", regardless of embed vs. popup.
• Self.postFinished(): posts the done sentinel that ends the host's stream.
• (Posting items is just parent().postMessage(encoded, origin).)

---

Happy to open a PR if there's appetite.

[84dnnvbdvp-debug]

One security/lifecycle edge seems worth making explicit before this abstraction freezes: filtering message only by event.source does not authenticate the document currently occupying that browsing context.

iframe.contentWindow / a popup reference is a WindowProxy; when that browsing context navigates, the proxy stays associated with the context while the wrapped Window changes. The platform guidance for postMessage therefore recommends checking origin as well as (where useful) source. Otherwise a widget iframe/popup that later navigates to another origin can still send a schema-valid item (or the finished sentinel) from the same source proxy and satisfy a source-only filter.

I’d make sender binding part of the Launcher contract:

• for a normal cross-origin widget URL, derive/pin the expected origin from the configured URL and require both event.source === launchedWindow and event.origin === expectedOrigin; use that exact origin as targetOrigin for host→widget messages too;
• apply the same checks to item, typed-error, and finished/control messages, not only payload-bearing messages;
• decide explicitly how EmbedLauncher behaves if its sandbox omits allow-same-origin. Such a frame has an opaque origin ("null"), so origin pinning cannot distinguish the intended document from another opaque-origin document. If that mode is required, it probably needs a stronger session/channel binding rather than silently falling back to source-only authentication.

A useful regression would launch the trusted widget, navigate that same iframe/popup to another origin, then have the new document post a schema-valid item and finished sentinel. The host stream should neither emit nor terminate. A sibling-window negative control would cover the ordinary source check separately.

References: HTML WindowProxy navigation semantics: https://html.spec.whatwg.org/multipage/nav-history-apis.html#the-windowproxy-exotic-object ; MDN postMessage security guidance: https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage#security_concerns ; iframe sandbox origin behavior: https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/iframe#sandbox

[harrysolovay]

Both launchers already know the widget's origin (derived from the configured URL), so binding the sender is straightforward: require event.source === launchedWindow && event.origin === expectedOrigin for every message, including the finished sentinel, and use that same origin as targetOrigin for anything the host sends back.

On sandboxing: EmbedLauncher should be configurable so that the integrator can specify the iframe security policies directly (allowing inner passkey usage, apple pay, etc.).