@ulearning/ai-generative-frame 0.0.0-stage → 1.0.0-next.0

package/src/runtime/index.ts

@@ -0,0 +1,343 @@
+import {
+  INIT_MESSAGE,
+  METHODS,
+  READY_MESSAGE,
+  type ColorScheme,
+  type EndResult,
+  type FrameInspection,
+  type HostContext,
+  type InitMessage,
+  type ScreenshotOptions,
+  type WidgetSize,
+} from "../protocol";
+import { createRpcPeer, RPC_ERROR, RpcError, type RpcPeer } from "../rpc";
+import { VERSION } from "../version";
+import { installDiagnostics, isBlankRender } from "./diagnostics";
+import { createStreamRenderer } from "./morph";
+import { captureScreenshot } from "./screenshot";
+import { measureRoot, reportableSize } from "./size";
+import { clearFrameStorage } from "./storage";
+
+export type RuntimeConfig = {
+  hostOrigin: string;
+  animate: boolean;
+};
+
+const VARIABLE_NAME = /^--[\w-]+$/;
+const READY_INTERVAL_MS = 100;
+const READY_ATTEMPTS = 100;
+
+type Listener = (event: Event) => void;
+
+/** Boots the in-frame runtime: handshake, streaming renderer, bridge, and widget globals. */
+export function startRuntime(win: Window & typeof globalThis = window): void {
+  const doc = win.document;
+  const configElement = doc.getElementById("gf-config");
+  const config = JSON.parse(
+    configElement?.textContent ?? "{}",
+  ) as RuntimeConfig;
+  configElement?.remove();
+  const root = doc.getElementById("gf-root") ?? doc.body;
+
+  let peer: RpcPeer | undefined;
+  let context: HostContext = {};
+  let toolInput: Record<string, unknown> | null = null;
+  let toolOutput: unknown = null;
+  let widgetState: unknown = null;
+  let lastSize: WidgetSize = { width: 0, height: 0 };
+
+  const diagnostics = installDiagnostics(win, {
+    onError: (error) => peer?.notify(METHODS.error, error),
+    onConsole: (entry) => {
+      if (entry.level === "warn" || entry.level === "error") {
+        peer?.notify(METHODS.log, entry);
+      }
+    },
+  });
+
+  const reducedMotion = win.matchMedia?.("(prefers-reduced-motion: reduce)");
+  const renderer = createStreamRenderer({
+    root,
+    animate: () => config.animate !== false && !reducedMotion?.matches,
+    onScriptError: (message, src) =>
+      diagnostics.record({
+        kind: "script",
+        message,
+        ...(src ? { source: src } : {}),
+      }),
+  });
+
+  const measure = (): WidgetSize => measureRoot(root);
+
+  let sizeFrame: number | undefined;
+  const reportSize = () => {
+    sizeFrame = undefined;
+    const size = reportableSize(root);
+    if (!size) return;
+    const maxHeight = context.containerDimensions?.maxHeight;
+    // The host sizes the iframe to the content, so a scrollbar would only flash
+    // while the two catch up and steal width; it is needed only past maxHeight.
+    doc.documentElement.style.overflowY =
+      typeof maxHeight === "number" && size.height > maxHeight
+        ? "auto"
+        : "hidden";
+    if (size.width === lastSize.width && size.height === lastSize.height)
+      return;
+    lastSize = size;
+    peer?.notify(METHODS.sizeChanged, size);
+  };
+  const scheduleSize = () => {
+    sizeFrame ??= win.requestAnimationFrame(reportSize);
+  };
+  if (typeof win.ResizeObserver === "function") {
+    new win.ResizeObserver(scheduleSize).observe(root);
+  }
+
+  const applyContext = (next: HostContext) => {
+    const previousTheme = context.theme;
+    context = { ...context, ...next };
+    const style = doc.documentElement.style;
+    let themeChanged = false;
+    if (next.theme === "light" || next.theme === "dark") {
+      style.colorScheme = next.theme;
+      doc.documentElement.dataset["theme"] = next.theme;
+      themeChanged = next.theme !== previousTheme;
+    }
+    const variables = next.styles?.variables;
+    if (variables && typeof variables === "object") {
+      for (const [name, value] of Object.entries(variables)) {
+        if (VARIABLE_NAME.test(name) && typeof value === "string") {
+          style.setProperty(name, value);
+        }
+      }
+      themeChanged = true;
+    }
+    if (themeChanged) {
+      win.dispatchEvent(
+        new CustomEvent("themechange", {
+          detail: {
+            theme: context.theme,
+            variables: context.styles?.variables,
+          },
+        }),
+      );
+    }
+  };
+
+  const requirePeer = () => {
+    if (!peer) throw new Error("generative-frame is not connected to its host");
+    return peer;
+  };
+
+  const sendPrompt = (text: string) =>
+    requirePeer().request(METHODS.message, {
+      role: "user",
+      content: [{ type: "text", text: String(text) }],
+    });
+  const openLink = (url: string) =>
+    requirePeer().request(METHODS.openLink, { url: String(url) });
+  const callTool = (name: string, args?: Record<string, unknown>) =>
+    requirePeer().request(METHODS.callTool, {
+      name,
+      ...(args !== undefined ? { arguments: args } : {}),
+    });
+  const requestDisplayMode = (mode: string) =>
+    requirePeer().request(METHODS.requestDisplayMode, { mode });
+  const updateModelContext = (params: unknown) =>
+    requirePeer().request(METHODS.updateModelContext, params);
+  const copyText = async (text: string) => {
+    await requirePeer().request(METHODS.copyText, { text: String(text) });
+  };
+  const setState = (state: unknown) => {
+    widgetState = state;
+    requirePeer().notify(METHODS.widgetState, { state });
+  };
+
+  const genframe = {
+    version: VERSION,
+    get theme(): ColorScheme | undefined {
+      return context.theme;
+    },
+    get context(): HostContext {
+      return context;
+    },
+    get toolInput() {
+      return toolInput;
+    },
+    get toolOutput() {
+      return toolOutput;
+    },
+    get state() {
+      return widgetState;
+    },
+    sendPrompt,
+    openLink,
+    callTool,
+    requestDisplayMode,
+    updateModelContext,
+    copyText,
+    setState,
+    on(type: "themechange" | "toolinput" | "toolresult", listener: Listener) {
+      win.addEventListener(type, listener);
+      return () => win.removeEventListener(type, listener);
+    },
+  };
+
+  const globals = win as unknown as Record<string, unknown>;
+  globals["genframe"] = genframe;
+  globals["sendPrompt"] = sendPrompt;
+  globals["openLink"] = openLink;
+  // The sandboxed frame cannot write the clipboard, so a widget's own writes are copied by the host too.
+  if (win.navigator.clipboard)
+    Object.defineProperty(win.navigator.clipboard, "writeText", {
+      configurable: true,
+      value: copyText,
+    });
+  else
+    Object.defineProperty(win.navigator, "clipboard", {
+      configurable: true,
+      value: { writeText: copyText },
+    });
+  win.open = ((url?: string | URL) => {
+    if (url !== undefined) void openLink(String(url)).catch(() => {});
+    return null;
+  }) as typeof win.open;
+
+  doc.addEventListener(
+    "click",
+    (event) => {
+      if (event.defaultPrevented || !(event.target instanceof win.Element)) {
+        return;
+      }
+      const anchor = event.target.closest("a[href]");
+      if (!anchor) return;
+      const href = anchor.getAttribute("href") ?? "";
+      if (href.startsWith("#")) return;
+      let url: URL;
+      try {
+        url = new URL(href, config.hostOrigin);
+      } catch {
+        return;
+      }
+      if (url.protocol !== "http:" && url.protocol !== "https:") return;
+      event.preventDefault();
+      void openLink(url.href).catch(() => {});
+    },
+    true,
+  );
+
+  const endResult = (): EndResult => {
+    const size = measure();
+    return {
+      size,
+      blank: isBlankRender(root),
+      errorCount: diagnostics.errors.length,
+    };
+  };
+
+  const inspect = (): FrameInspection => ({
+    kind: renderer.kind,
+    ended: renderer.ended,
+    size: measure(),
+    blank: renderer.ended ? isBlankRender(root) : false,
+    errors: [...diagnostics.errors],
+    console: [...diagnostics.console],
+  });
+
+  const onRequest = async (method: string, params: unknown) => {
+    const p = (params ?? {}) as Record<string, unknown>;
+    switch (method) {
+      case METHODS.end:
+        await renderer.end();
+        scheduleSize();
+        return endResult();
+      case METHODS.replace:
+        if (typeof p["code"] !== "string") {
+          throw new RpcError(
+            RPC_ERROR.invalidParams,
+            "replace requires a string 'code'",
+          );
+        }
+        await renderer.replace(p["code"]);
+        scheduleSize();
+        return endResult();
+      case METHODS.screenshot:
+        renderer.flush();
+        return captureScreenshot(root, p as ScreenshotOptions);
+      case METHODS.inspect:
+        renderer.flush();
+        return inspect();
+      case METHODS.clearStorage:
+        return clearFrameStorage(win);
+      default:
+        throw new RpcError(
+          RPC_ERROR.methodNotFound,
+          `Unknown method: ${method}`,
+        );
+    }
+  };
+
+  const onNotification = (method: string, params: unknown) => {
+    const p = (params ?? {}) as Record<string, unknown>;
+    switch (method) {
+      case METHODS.write:
+        if (typeof p["chunk"] === "string") renderer.write(p["chunk"]);
+        return;
+      case METHODS.hostContextChanged:
+        applyContext(p as HostContext);
+        return;
+      case METHODS.toolInputPartial:
+      case METHODS.toolInput: {
+        const args = p["arguments"];
+        toolInput =
+          args && typeof args === "object"
+            ? (args as Record<string, unknown>)
+            : {};
+        win.dispatchEvent(
+          new CustomEvent("toolinput", {
+            detail: {
+              arguments: toolInput,
+              partial: method === METHODS.toolInputPartial,
+            },
+          }),
+        );
+        return;
+      }
+      case METHODS.toolResult:
+        toolOutput =
+          p["structuredContent"] !== undefined ? p["structuredContent"] : p;
+        win.dispatchEvent(new CustomEvent("toolresult", { detail: p }));
+        return;
+      default:
+        return;
+    }
+  };
+
+  const connect = (port: MessagePort, init: InitMessage) => {
+    peer = createRpcPeer(port, { onRequest, onNotification });
+    widgetState = init.state ?? null;
+    applyContext(init.context ?? {});
+    peer.notify(METHODS.ready, { version: VERSION });
+    scheduleSize();
+    for (const error of diagnostics.errors) peer.notify(METHODS.error, error);
+  };
+
+  let attempts = 0;
+  const announce = () => {
+    attempts++;
+    if (attempts > READY_ATTEMPTS) win.clearInterval(readyTimer);
+    win.parent.postMessage({ type: READY_MESSAGE }, config.hostOrigin);
+  };
+  const onWindowMessage = (event: MessageEvent) => {
+    if (event.source !== win.parent || event.origin !== config.hostOrigin)
+      return;
+    const data = event.data as Partial<InitMessage> | null;
+    if (data?.type !== INIT_MESSAGE || !event.ports[0]) return;
+    win.removeEventListener("message", onWindowMessage);
+    win.clearInterval(readyTimer);
+    connect(event.ports[0], data as InitMessage);
+  };
+  win.addEventListener("message", onWindowMessage);
+  const readyTimer = win.setInterval(announce, READY_INTERVAL_MS);
+  announce();
+}

package/src/runtime/morph.ts

@@ -0,0 +1,352 @@
+import { detectWidgetKind, type WidgetKind } from "../protocol";
+
+export const SCRIPT_PLACEHOLDER = "gf-script";
+
+const NON_VISUAL = new Set([
+  "style",
+  "script",
+  "meta",
+  "link",
+  "title",
+  "base",
+]);
+
+export type ParsedMarkup = {
+  fragment: DocumentFragment;
+  /** Scripts in document order; each one's position holds a placeholder comment. */
+  scripts: Element[];
+};
+
+/**
+ * Drops a trailing `<style>` element that has not closed yet, so half-written
+ * CSS never applies and then snaps when the rule completes.
+ */
+export function stripUnclosedStyle(source: string): string {
+  const open = source.toLowerCase().lastIndexOf("<style");
+  if (open === -1) return source;
+  const next = source.charAt(open + 6);
+  if (next !== "" && !/[\s>/]/.test(next)) return source;
+  return source.toLowerCase().includes("</style", open)
+    ? source
+    : source.slice(0, open);
+}
+
+/**
+ * Parses (possibly partial) markup into a detached fragment. The HTML parser
+ * closes open elements and drops a tag cut off mid-way, so any prefix of a
+ * document parses into a well-formed tree.
+ */
+export function parseMarkup(doc: Document, source: string): ParsedMarkup {
+  const template = doc.createElement("template");
+  template.innerHTML = source;
+  const fragment = template.content;
+  const scripts: Element[] = [];
+  for (const script of Array.from(fragment.querySelectorAll("script"))) {
+    script.replaceWith(doc.createComment(SCRIPT_PLACEHOLDER));
+    scripts.push(script);
+  }
+  return { fragment, scripts };
+}
+
+export type MorphContext = {
+  onAdded(node: Node): void;
+};
+
+const sameNode = (live: Node, next: Node): boolean => {
+  if (live.nodeType !== next.nodeType) return false;
+  if (live.nodeType !== Node.ELEMENT_NODE) return true;
+  const a = live as Element;
+  const b = next as Element;
+  return (
+    a.localName === b.localName &&
+    a.namespaceURI === b.namespaceURI &&
+    a.getAttribute("id") === b.getAttribute("id")
+  );
+};
+
+const syncAttributes = (live: Element, next: Element) => {
+  for (const attr of Array.from(next.attributes)) {
+    if (live.getAttributeNS(attr.namespaceURI, attr.localName) === attr.value) {
+      continue;
+    }
+    try {
+      if (attr.namespaceURI) {
+        live.setAttributeNS(attr.namespaceURI, attr.name, attr.value);
+      } else {
+        live.setAttribute(attr.name, attr.value);
+      }
+    } catch {
+      // The parser accepts attribute names the DOM API rejects; they carry no meaning.
+    }
+  }
+  for (const attr of Array.from(live.attributes)) {
+    if (!next.hasAttributeNS(attr.namespaceURI, attr.localName)) {
+      live.removeAttributeNS(attr.namespaceURI, attr.localName);
+    }
+  }
+};
+
+const patchNode = (live: Node, next: Node, ctx: MorphContext) => {
+  if (live.nodeType !== Node.ELEMENT_NODE) {
+    if (live.nodeValue !== next.nodeValue) live.nodeValue = next.nodeValue;
+    return;
+  }
+  const liveEl = live as Element;
+  const nextEl = next as Element;
+  syncAttributes(liveEl, nextEl);
+  if (
+    liveEl instanceof HTMLTemplateElement &&
+    nextEl instanceof HTMLTemplateElement
+  ) {
+    if (liveEl.innerHTML !== nextEl.innerHTML) {
+      liveEl.content.replaceChildren(nextEl.content);
+    }
+    return;
+  }
+  morphChildren(liveEl, nextEl, ctx);
+};
+
+/**
+ * Makes `live`'s children match `next`'s, reusing live nodes matched by
+ * position and tag. Unmatched nodes move out of `next` into `live`.
+ */
+export function morphChildren(
+  live: ParentNode & Node,
+  next: ParentNode & Node,
+  ctx: MorphContext,
+): void {
+  const nextNodes = Array.from(next.childNodes);
+  let cursor: ChildNode | null = live.firstChild;
+
+  for (let i = 0; i < nextNodes.length; i++) {
+    const nextChild = nextNodes[i]!;
+    if (!cursor) {
+      live.appendChild(nextChild);
+      ctx.onAdded(nextChild);
+      continue;
+    }
+    if (sameNode(cursor, nextChild)) {
+      patchNode(cursor, nextChild, ctx);
+      cursor = cursor.nextSibling;
+      continue;
+    }
+    const following = nextNodes[i + 1];
+    if (following && sameNode(cursor, following)) {
+      live.insertBefore(nextChild, cursor);
+      ctx.onAdded(nextChild);
+      continue;
+    }
+    const afterCursor: ChildNode | null = cursor.nextSibling;
+    if (afterCursor && sameNode(afterCursor, nextChild)) {
+      cursor.remove();
+      patchNode(afterCursor, nextChild, ctx);
+      cursor = afterCursor.nextSibling;
+      continue;
+    }
+    live.replaceChild(nextChild, cursor);
+    ctx.onAdded(nextChild);
+    cursor = afterCursor;
+  }
+
+  while (cursor) {
+    const after: ChildNode | null = cursor.nextSibling;
+    cursor.remove();
+    cursor = after;
+  }
+}
+
+export type ScriptRunner = (
+  placeholder: Comment,
+  original: Element,
+) => Promise<void>;
+
+export type StreamRendererOptions = {
+  root: HTMLElement;
+  /** Whether newly inserted elements fade in. Checked per insertion. */
+  animate?: () => boolean;
+  /** Schedules a coalesced render; returns a cancel function. */
+  schedule?: (render: () => void) => () => void;
+  runScript?: ScriptRunner;
+  onScriptError?: (message: string, src: string | undefined) => void;
+  onRender?: (kind: WidgetKind) => void;
+};
+
+export type StreamRenderer = {
+  readonly source: string;
+  readonly kind: WidgetKind;
+  readonly ended: boolean;
+  readonly scriptsRan: boolean;
+  write(chunk: string): void;
+  /** Renders the complete source, then runs held scripts in document order. */
+  end(): Promise<void>;
+  replace(code: string): Promise<void>;
+  flush(): void;
+};
+
+const SCRIPT_LOAD_TIMEOUT_MS = 15_000;
+
+const defaultSchedule = (render: () => void) => {
+  let done = false;
+  const run = () => {
+    if (done) return;
+    done = true;
+    cancelAnimationFrame(frame);
+    clearTimeout(timer);
+    render();
+  };
+  // rAF alone stalls in hidden or offscreen frames, which previews use.
+  const frame = requestAnimationFrame(run);
+  const timer = setTimeout(run, 50);
+  return () => {
+    done = true;
+    cancelAnimationFrame(frame);
+    clearTimeout(timer);
+  };
+};
+
+export const createScriptRunner =
+  (
+    onError: (message: string, src: string | undefined) => void = () => {},
+  ): ScriptRunner =>
+  (placeholder, original) => {
+    const doc = placeholder.ownerDocument;
+    const script = doc.createElementNS(
+      original.namespaceURI ?? "http://www.w3.org/1999/xhtml",
+      "script",
+    );
+    for (const attr of Array.from(original.attributes)) {
+      try {
+        script.setAttribute(attr.name, attr.value);
+      } catch {
+        // See syncAttributes.
+      }
+    }
+    script.textContent = original.textContent;
+    const src = script.getAttribute("src") ?? script.getAttribute("href");
+    if (!src) {
+      placeholder.replaceWith(script);
+      return Promise.resolve();
+    }
+    return new Promise<void>((resolve) => {
+      const timer = setTimeout(() => {
+        onError(`Script timed out: ${src}`, src);
+        resolve();
+      }, SCRIPT_LOAD_TIMEOUT_MS);
+      script.addEventListener("load", () => {
+        clearTimeout(timer);
+        resolve();
+      });
+      script.addEventListener("error", () => {
+        clearTimeout(timer);
+        onError(`Script failed to load: ${src}`, src);
+        resolve();
+      });
+      placeholder.replaceWith(script);
+    });
+  };
+
+const fadeIn = (node: Node) => {
+  if (node.nodeType !== Node.ELEMENT_NODE) return;
+  const el = node as Element;
+  if (NON_VISUAL.has(el.localName) || typeof el.animate !== "function") return;
+  el.animate([{ opacity: 0 }, { opacity: 1 }], {
+    duration: 200,
+    easing: "ease-out",
+  });
+};
+
+export function createStreamRenderer(
+  options: StreamRendererOptions,
+): StreamRenderer {
+  const { root } = options;
+  const doc = root.ownerDocument;
+  const schedule = options.schedule ?? defaultSchedule;
+  const runScript =
+    options.runScript ?? createScriptRunner(options.onScriptError);
+  let source = "";
+  let kind: WidgetKind = "html";
+  let ended = false;
+  let scriptsRan = false;
+  let cancelScheduled: (() => void) | undefined;
+  let lastRendered: string | undefined;
+  let lastScripts: Element[] = [];
+
+  const ctx: MorphContext = {
+    onAdded(node) {
+      if (options.animate?.()) fadeIn(node);
+    },
+  };
+
+  const render = (final: boolean) => {
+    cancelScheduled?.();
+    cancelScheduled = undefined;
+    const markup = final ? source : stripUnclosedStyle(source);
+    if (markup === lastRendered) return;
+    lastRendered = markup;
+    kind = detectWidgetKind(source);
+    root.dataset["kind"] = kind;
+    const parsed = parseMarkup(doc, markup);
+    lastScripts = parsed.scripts;
+    morphChildren(root, parsed.fragment, ctx);
+    options.onRender?.(kind);
+  };
+
+  const runHeldScripts = async () => {
+    const walker = doc.createTreeWalker(root, NodeFilter.SHOW_COMMENT);
+    const placeholders: Comment[] = [];
+    for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+      if (node.nodeValue === SCRIPT_PLACEHOLDER) {
+        placeholders.push(node as Comment);
+      }
+    }
+    const scripts = lastScripts;
+    for (let i = 0; i < placeholders.length && i < scripts.length; i++) {
+      await runScript(placeholders[i]!, scripts[i]!);
+    }
+    if (scripts.length > 0 && !scriptsRan) {
+      scriptsRan = true;
+      // The bootstrap document loaded long ago; widgets written for a fresh page wait for these.
+      doc.dispatchEvent(new Event("DOMContentLoaded", { bubbles: true }));
+      doc.defaultView?.dispatchEvent(new Event("load"));
+    }
+  };
+
+  return {
+    get source() {
+      return source;
+    },
+    get kind() {
+      return kind;
+    },
+    get ended() {
+      return ended;
+    },
+    get scriptsRan() {
+      return scriptsRan;
+    },
+    write(chunk) {
+      if (ended) throw new Error("Cannot write after end; use replace");
+      if (!chunk) return;
+      source += chunk;
+      cancelScheduled ??= schedule(() => {
+        cancelScheduled = undefined;
+        render(false);
+      });
+    },
+    async end() {
+      if (ended) return;
+      ended = true;
+      render(true);
+      await runHeldScripts();
+    },
+    async replace(code) {
+      ended = true;
+      source = code;
+      render(true);
+      await runHeldScripts();
+    },
+    flush() {
+      if (cancelScheduled) render(ended);
+    },
+  };
+}