Implementation:Interpretml Interpret StitchWidget TS

Knowledge Sources	Interpretml Interpret
Domains	Visualization, Jupyter_Widgets, TypeScript
Last Updated	2026-02-07 12:00 GMT

Overview

TypeScript frontend implementation of the Stitch Jupyter widget, providing the StitchModel and StitchView classes that manage bidirectional communication between a sandboxed iframe and the Jupyter kernel via postMessage.

Description

This module implements the client-side (browser) portion of the Stitch widget using the @jupyter-widgets/base framework:

StitchModel -- Extends DOMWidgetModel to define the widget's synchronized state:

• kernelmsg / clientmsg -- String channels for bidirectional communication between the kernel and iframe.
• srcdoc -- HTML content loaded into the sandboxed iframe.
• initial_height / initial_width / initial_border / initial_overflow -- Initial styling for the iframe element.
• Uses standard Jupyter widget serializers and module name/version from a separate version module.

StitchView -- Extends DOMWidgetView to render and manage the widget's DOM:

• Iframe creation -- Creates a sandboxed iframe with allow-scripts permission and applies initial styling from the model.
• Kernel-to-client messaging -- Listens for change:kernelmsg on the model and forwards messages to the iframe via postMessage() with type "kernelmsg".
• Client-to-kernel messaging -- Listens for window.message events from the iframe. Messages with type "clientmsg" are forwarded to the kernel by setting clientmsg on the model. Messages with type "resize" update the iframe dimensions.
• Ready polling -- After iframe creation, polls every 100ms until the model is no longer new, then sends the initial kernel message.
• srcdoc updates -- Listens for change:srcdoc to dynamically reload the iframe content and push the latest kernel message.

Usage

This is the frontend component of the Stitch widget system. It is compiled and bundled as part of the stitch npm package and loaded automatically by JupyterLab/Notebook when the Python StitchWidget is displayed. Developers working on custom InterpretML visualizations interact with the iframe content, sending/receiving messages through the kernelmsg/clientmsg channels.

Code Reference

Source Location

• Repository: Interpretml_Interpret
• File: python/stitch/src/widget.ts

Signature

export class StitchModel extends DOMWidgetModel {
  defaults() {
    return {
      ...super.defaults(),
      _model_name: StitchModel.model_name,
      _view_name: StitchModel.view_name,
      kernelmsg: '',
      clientmsg: '',
      srcdoc: '<p>srcdoc should be defined by the user</p>',
      initial_height: '1px',
      initial_width: '1px',
      initial_border: "0",
      initial_overflow: "hidden",
    };
  }

  static model_name = 'StitchModel';
  static view_name = 'StitchView';
}

export class StitchView extends DOMWidgetView {
  private _iframe: HTMLIFrameElement;
  render(): void;
  kernelmsg_changed(): void;
  srcdoc_changed(): void;
}

Import

import { StitchModel, StitchView } from './widget';

I/O Contract

Inputs

Name	Type	Required	Description
kernelmsg	string	No	Message from the Python kernel to be forwarded to the iframe (synced trait)
srcdoc	string	No	HTML content to load in the sandboxed iframe (synced trait)
initial_height	string	No	Initial iframe height CSS value (default: "1px")
initial_width	string	No	Initial iframe width CSS value (default: "1px")
initial_border	string	No	Initial iframe border CSS value (default: "0")
initial_overflow	string	No	Initial iframe overflow CSS value (default: "hidden")

Outputs

Name	Type	Description
clientmsg	string	Message received from the iframe and synced back to the Python kernel
resize event	object	Iframe dimensions updated from {height, width} in resize messages

Usage Examples

// The widget is typically not instantiated directly in TypeScript.
// It is loaded by Jupyter's widget infrastructure when StitchWidget is displayed.

// Inside an iframe, send a message to the kernel:
window.parent.postMessage({type: "clientmsg", content: "hello from iframe"}, "*");

// Inside an iframe, request a resize:
window.parent.postMessage({type: "resize", content: {height: "400px", width: "100%"}}, "*");

// Inside an iframe, listen for kernel messages:
window.addEventListener("message", (event) => {
  if (event.data.type === "kernelmsg") {
    console.log("Received from kernel:", event.data.content);
  }
});

Related Pages

• Interpretml_Interpret_StitchWidget -- Python backend class that pairs with this TypeScript frontend
• Interpretml_Interpret_VisRenderer -- React visualization renderer that may be loaded inside the iframe