Host page events

This reference covers what embed.js does on the host page in response to widget messages. These behaviors exist only with the script embed method.

Messages moving from the widget iframe through embed.js into a tars:bridge event, host navigation, the image lightbox, and the Escape key path back to the widget

The tars:bridge event

embed.js re-dispatches two widget messages on window, as a CustomEvent named tars:bridge: tars:data and tars:action. The original message is the event’s detail.

window.addEventListener("tars:bridge", (event) => {
  const msg = event.detail;
  if (msg.type === "tars:data") {
    console.log("captured variables", msg.variables);
  }
});

detail.type	Payload	Fired when
`tars:data`	`variables`: captured conversation variables	The widget posts a data message
`tars:action`	No declared fields	Reserved in the protocol. No widget code posts this message today

tars:bridge is a passthrough. Per-gambit bridge events fire only after a host sends tars:init, which embed.js does not send. Today those events reach only the native WebView bridge. A tars:navigate message from the widget navigates the host page with window.location.assign. Only http: and https: URLs are accepted, any other protocol is ignored. Relative routes resolve against the host page’s origin. The message carries redirectTo next to route. Both hold the same URL, and embed.js reads only route. A flow triggers this through a redirect input gambit, and the gambit’s Open in New Tab option decides which path runs. With the option off, the gambit counts down, then the widget posts tars:navigate and embed.js replaces the host page. With the option on, the widget renders a plain link with a target="_blank" attribute and posts no message. The end user opens the target in a new tab. When an end user opens an image attachment, the widget escapes its iframe: embed.js renders the lightbox as a full-page shadow-DOM overlay on the host page. Arrow keys switch images, and Escape closes the overlay. Without embed.js (direct iframe), images open inside the frame instead.

Escape key

While the widget panel is open, Escape on the host page closes it. The widget is notified with a closed message, so its state stays consistent.

Welcome

Core concepts

Guides

Developer

The tars:bridge event

Host navigation

Escape key

​The tars:bridge event

​Host navigation

​Image lightbox

​Escape key

​Related pages

The tars:bridge event

Host navigation

Image lightbox

Escape key

Related pages