Web SDK

"@morphscreen/web"

The web SDK's functions and types: loadCore, createAnswer and its options, the Answer it returns, the Core and its sessions, and the actions.

View as Markdown
TypeScript
import { createAnswer, connectAgent, loadCore } from "@morphscreen/web";
import "@morphscreen/web/morphscreen.css";

loadCore

TypeScript
loadCore(src: string | URL | ArrayBuffer | Uint8Array | Response): Promise<Core>

Loads the core from morphscreen.wasm, or morphscreen-agent.wasm for connectAgent, and starts the answer faces loading alongside. Load it once and share it.

createAnswer

TypeScript
createAnswer(el: HTMLElement, options: AnswerOptions): Answer

Draws an answer into el, which gets the class ms-answer.

Option Type What it does
core Core from loadCore
packs string[] packs beyond core; every one when left out, [] for core alone
custom Pack[] your own packs
components Record<string, Mount> how to draw your own components: (el, { attrs, html, text }) => cleanup?
onAction (action: Action) => void the reader asked, submitted, finished a quiz, voted or changed state
onComponentState (node, state) => void an interactive component's state changed because the reader acted
imageHosts string[] hosts pictures may load from; any other shows its description
maps MapTiles your map provider and key
maplibre module, or a function that loads it MapLibre GL 6.16 or later, for live maps
onOps (ops: Op[]) => void every op, for logging or a renderer of your own

Answer

Method What it does
push(text) the next piece of the model's text
end(truncated?) the answer is over; true if it hit the token limit
html() the finished answer as HTML, what a server would send
applyState(states) sets interactive components' state, by node id
destroy() stops and clears it

Action

TypeScript
type Action =
  | { type: "ask"; text: string; node: string }
  | { type: "submit"; node: string; form: string; button: string; fields: Record<string, FieldValue> }
  | { type: "quiz"; node: string; score: number; total: number; answers: { question: string; choice: string; right: boolean | null }[] }
  | { type: "vote"; node: string; name: string; choice: string }
  | { type: "state"; node: string; name: string; value: unknown };

type FieldValue = string | number | boolean | string[] | File[] | { lat: number; lng: number; accuracy: number };

Actions and state says when each is sent.

Core

Method What it does
prompt(packs?, custom?) the system prompt for that catalog
session(packs?, custom?) a Session that reads one answer
actionMessage(action) the user message an action starts, worded as the API words it

Session

For reading an answer yourself, without drawing it:

Method What it does
push(text) feeds the next piece; returns the ops it produced
finish(truncated?) the answer is over; returns the last ops
html(), tree() the answer as HTML, or as its tree
verdict() the core's verdict: valid, truncated, the component count and the diagnostics
allowImages(hosts) where the HTML's pictures may load from

Other exports

  • connectAgent(el, options): a conversation with an AG-UI agent (its reference).
  • allowedImage(src, { imageHosts }): whether a picture's address may load.
  • enhanceCharts(root): makes the charts under root respond (tooltips, legend items that switch a series off), for HTML from the server; returns a function that undoes it.

The package also has @morphscreen/web/react (React) and @morphscreen/web/theme (theme).