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

package/src/runtime/screenshot.ts

@@ -0,0 +1,288 @@
+import type { ScreenshotOptions } from "../protocol";
+
+const XHTML = "http://www.w3.org/1999/xhtml";
+const SVG = "http://www.w3.org/2000/svg";
+const MAX_CANVAS_SIDE = 4096;
+const SKIP = new Set(["script", "noscript", "template"]);
+
+export type Screenshot = {
+  dataUrl: string;
+  width: number;
+  height: number;
+};
+
+const createDefaultStyles = (doc: Document) => {
+  const cache = new Map<string, Map<string, string>>();
+  let sandbox: HTMLElement | undefined;
+  let svgSandbox: SVGSVGElement | undefined;
+
+  let host: HTMLElement | undefined;
+
+  const ensureSandbox = () => {
+    if (sandbox) return;
+    host = doc.createElement("div");
+    host.setAttribute("aria-hidden", "true");
+    host.style.cssText =
+      "all:initial;position:absolute;left:-99999px;top:0;visibility:hidden;contain:strict;width:0;height:0;";
+    // Document rules such as `*{box-sizing:border-box}` do not cross a shadow
+    // boundary, so probes inside it report the defaults the serialized image
+    // will actually render with.
+    const shadow = host.attachShadow({ mode: "closed" });
+    sandbox = doc.createElement("div");
+    svgSandbox = doc.createElementNS(SVG, "svg");
+    sandbox.appendChild(svgSandbox);
+    shadow.appendChild(sandbox);
+    doc.body.appendChild(host);
+  };
+
+  return {
+    get(el: Element): Map<string, string> {
+      const key = `${el.namespaceURI}|${el.localName}`;
+      let styles = cache.get(key);
+      if (styles) return styles;
+      ensureSandbox();
+      const probe = doc.createElementNS(el.namespaceURI ?? XHTML, el.localName);
+      (el.namespaceURI === SVG ? svgSandbox! : sandbox!).appendChild(probe);
+      const computed = doc.defaultView!.getComputedStyle(probe);
+      styles = new Map();
+      for (let i = 0; i < computed.length; i++) {
+        const name = computed.item(i);
+        styles.set(name, computed.getPropertyValue(name));
+      }
+      probe.remove();
+      cache.set(key, styles);
+      return styles;
+    },
+    dispose() {
+      host?.remove();
+    },
+  };
+};
+
+const toDataUrl = (
+  source: CanvasImageSource,
+  width: number,
+  height: number,
+) => {
+  const canvas = document.createElement("canvas");
+  canvas.width = Math.max(1, width);
+  canvas.height = Math.max(1, height);
+  canvas.getContext("2d")!.drawImage(source, 0, 0, width, height);
+  return canvas.toDataURL("image/png");
+};
+
+/**
+ * Clones `node` with every computed style that differs from both the
+ * element's default and its parent's value written inline, because a
+ * serialized SVG image cannot see the frame's stylesheets.
+ */
+const cloneWithStyles = (
+  node: Node,
+  defaults: ReturnType<typeof createDefaultStyles>,
+  parentStyle: CSSStyleDeclaration | undefined,
+): Node | null => {
+  if (node.nodeType === Node.TEXT_NODE) return node.cloneNode();
+  if (node.nodeType !== Node.ELEMENT_NODE) return null;
+  const el = node as Element;
+  if (SKIP.has(el.localName)) return null;
+
+  const view = el.ownerDocument.defaultView!;
+  const style = view.getComputedStyle(el);
+  let clone: Element;
+
+  if (el instanceof view.HTMLCanvasElement) {
+    clone = el.ownerDocument.createElement("img");
+    try {
+      clone.setAttribute("src", el.toDataURL("image/png"));
+    } catch {
+      // A tainted canvas cannot be read; it stays empty in the capture.
+    }
+  } else if (
+    el instanceof view.HTMLImageElement &&
+    el.complete &&
+    el.naturalWidth > 0 &&
+    !el.src.startsWith("data:")
+  ) {
+    clone = el.cloneNode(false) as Element;
+    try {
+      clone.setAttribute(
+        "src",
+        toDataUrl(el, el.naturalWidth, el.naturalHeight),
+      );
+    } catch {
+      // Cross-origin images without CORS cannot be inlined.
+    }
+  } else {
+    clone = el.cloneNode(false) as Element;
+  }
+
+  if (el instanceof view.HTMLInputElement) {
+    if (el.type === "checkbox" || el.type === "radio") {
+      if (el.checked) clone.setAttribute("checked", "");
+      else clone.removeAttribute("checked");
+    } else {
+      clone.setAttribute("value", el.value);
+    }
+  } else if (el instanceof view.HTMLTextAreaElement) {
+    clone.textContent = el.value;
+  } else if (el instanceof view.HTMLSelectElement) {
+    clone.setAttribute("data-gf-value", el.value);
+  }
+
+  const base = defaults.get(el);
+  const declarations: string[] = [];
+  for (let i = 0; i < style.length; i++) {
+    const name = style.item(i);
+    if (name.startsWith("--")) continue;
+    const value = style.getPropertyValue(name);
+    if (
+      value !== base.get(name) ||
+      (parentStyle && value !== parentStyle.getPropertyValue(name))
+    ) {
+      declarations.push(`${name}:${value}`);
+    }
+  }
+  if (style.animationName !== "none" || style.transitionProperty !== "none") {
+    declarations.push("animation:none", "transition:none");
+  }
+  clone.setAttribute("style", declarations.join(";"));
+
+  if (!(el instanceof view.HTMLTextAreaElement)) {
+    for (const child of Array.from(el.childNodes)) {
+      const childClone = cloneWithStyles(child, defaults, style);
+      if (childClone) clone.appendChild(childClone);
+    }
+  }
+  if (el instanceof view.HTMLSelectElement) {
+    for (const option of Array.from(clone.querySelectorAll("option"))) {
+      if (
+        option.getAttribute("value") === el.value ||
+        option.textContent === el.value
+      ) {
+        option.setAttribute("selected", "");
+      }
+    }
+  }
+  return clone;
+};
+
+/** Embeds `@font-face` rules that are already self-contained (`data:` sources). */
+const collectInlineFontFaces = (doc: Document): string => {
+  const rules: string[] = [];
+  for (const sheet of Array.from(doc.styleSheets)) {
+    let cssRules: CSSRuleList;
+    try {
+      cssRules = sheet.cssRules;
+    } catch {
+      continue;
+    }
+    for (const rule of Array.from(cssRules)) {
+      if (
+        rule.constructor.name === "CSSFontFaceRule" &&
+        !/url\((?!\s*["']?data:)/i.test(rule.cssText)
+      ) {
+        rules.push(rule.cssText);
+      }
+    }
+  }
+  return rules.join("\n");
+};
+
+/**
+ * The capture box: the clone is laid out at the root's own width, and the
+ * image grows to the full scroll size so content overflowing the root is
+ * not clipped.
+ */
+export const measureCapture = (root: HTMLElement) => {
+  const rect = root.getBoundingClientRect();
+  const layoutWidth = Math.max(1, Math.ceil(rect.width));
+  return {
+    layoutWidth,
+    width: Math.max(layoutWidth, Math.ceil(root.scrollWidth)),
+    height: Math.max(1, Math.ceil(Math.max(rect.height, root.scrollHeight))),
+  };
+};
+
+const loadImage = (src: string) =>
+  new Promise<HTMLImageElement>((resolve, reject) => {
+    const img = new Image();
+    img.onload = () => resolve(img);
+    img.onerror = () =>
+      reject(new Error("The serialized widget failed to rasterize"));
+    img.src = src;
+  });
+
+/**
+ * Captures `root` as a PNG data URL by serializing a styled clone into an SVG
+ * `foreignObject` and drawing it onto a canvas. Best effort: web fonts loaded
+ * by URL, cross-origin images, and pseudo-elements are not reproduced.
+ */
+export async function captureScreenshot(
+  root: HTMLElement,
+  options: ScreenshotOptions = {},
+): Promise<Screenshot> {
+  const doc = root.ownerDocument;
+  const view = doc.defaultView!;
+  await doc.fonts?.ready;
+
+  const { layoutWidth, width, height } = measureCapture(root);
+
+  const defaults = createDefaultStyles(doc);
+  let clone: Node | null;
+  try {
+    clone = cloneWithStyles(root, defaults, view.getComputedStyle(doc.body));
+  } finally {
+    defaults.dispose();
+  }
+  const wrapper = doc.createElementNS(XHTML, "div");
+  wrapper.setAttribute(
+    "style",
+    `width:${width}px;height:${height}px;overflow:hidden;`,
+  );
+  if (clone) wrapper.appendChild(clone);
+  if (clone instanceof Element) {
+    clone.setAttribute(
+      "style",
+      `${clone.getAttribute("style") ?? ""};width:${layoutWidth}px;margin:0;`,
+    );
+  }
+
+  const fonts = collectInlineFontFaces(doc);
+  const markup = new XMLSerializer().serializeToString(wrapper);
+  const svg =
+    `<svg xmlns="${SVG}" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}">` +
+    `<foreignObject x="0" y="0" width="100%" height="100%">` +
+    (fonts
+      ? `<style xmlns="${XHTML}">${fonts.replace(/</g, "\\3c ")}</style>`
+      : "") +
+    markup +
+    `</foreignObject></svg>`;
+
+  const image = await loadImage(
+    `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}`,
+  );
+
+  const requested = options.scale ?? Math.min(view.devicePixelRatio || 1, 2);
+  const scale = Math.max(
+    0.1,
+    Math.min(requested, MAX_CANVAS_SIDE / width, MAX_CANVAS_SIDE / height),
+  );
+  const canvas = doc.createElement("canvas");
+  canvas.width = Math.round(width * scale);
+  canvas.height = Math.round(height * scale);
+  const context = canvas.getContext("2d");
+  if (!context) throw new Error("Canvas 2D context is unavailable");
+  const background =
+    options.background ??
+    view
+      .getComputedStyle(doc.documentElement)
+      .getPropertyValue("--color-background")
+      .trim();
+  if (background) {
+    context.fillStyle = background;
+    context.fillRect(0, 0, canvas.width, canvas.height);
+  }
+  context.scale(scale, scale);
+  context.drawImage(image, 0, 0, width, height);
+  return { dataUrl: canvas.toDataURL("image/png"), width, height };
+}

package/src/runtime/size.ts

@@ -0,0 +1,17 @@
+import type { WidgetSize } from "../protocol";
+
+export function measureRoot(root: Element): WidgetSize {
+  const rect = root.getBoundingClientRect();
+  return { width: Math.ceil(rect.width), height: Math.ceil(rect.height) };
+}
+
+/**
+ * The size to report to the host, or `undefined` while the root has no
+ * layout width. A frame laid out at zero width (a collapsed or hidden
+ * container, or Chrome's full-page capture) wraps its content one word per
+ * line, and its height would size the iframe far past its content.
+ */
+export function reportableSize(root: Element): WidgetSize | undefined {
+  const size = measureRoot(root);
+  return size.width > 0 ? size : undefined;
+}

package/src/runtime/storage.ts

@@ -0,0 +1,49 @@
+import type { ClearStorageResult } from "../protocol";
+
+const EXPIRED = "expires=Thu, 01 Jan 1970 00:00:00 GMT";
+
+/** Clears everything this frame's origin stores in the browser. */
+export async function clearFrameStorage(
+  win: Window,
+): Promise<ClearStorageResult> {
+  const cleared: string[] = [];
+  const attempt = async (kind: string, clear: () => unknown) => {
+    try {
+      if ((await clear()) !== false) cleared.push(kind);
+    } catch {}
+  };
+
+  await attempt("localStorage", () => win.localStorage.clear());
+  await attempt("sessionStorage", () => win.sessionStorage.clear());
+  await attempt("indexedDB", async () => {
+    const idb = win.indexedDB;
+    if (typeof idb?.databases !== "function") return false;
+    const databases = await idb.databases();
+    await Promise.all(
+      databases.map(
+        ({ name }) =>
+          name &&
+          new Promise<void>((resolve) => {
+            const request = idb.deleteDatabase(name);
+            request.onsuccess =
+              request.onerror =
+              request.onblocked =
+                () => resolve();
+          }),
+      ),
+    );
+    return true;
+  });
+  await attempt("cacheStorage", async () => {
+    if (!win.caches) return false;
+    for (const key of await win.caches.keys()) await win.caches.delete(key);
+    return true;
+  });
+  await attempt("cookies", () => {
+    for (const part of win.document.cookie.split(";")) {
+      const name = part.split("=")[0]?.trim();
+      if (name) win.document.cookie = `${name}=; ${EXPIRED}; path=/`;
+    }
+  });
+  return { cleared };
+}

package/src/spec/actions.ts

@@ -0,0 +1,111 @@
+import type { Catalog } from "./catalog";
+import { resolveValue, type ExpressionContext } from "./expressions";
+import type { SpecStateStore } from "./state";
+import type { ActionBinding } from "./types";
+
+/** Where an action was dispatched from. */
+export type ActionSource = {
+  elementId?: string;
+  /** The event name, or the watched path for `watch`. */
+  trigger?: string;
+  /** Whether a component's event or a `watch` binding dispatched the action. */
+  kind?: "event" | "watch";
+};
+
+export type ActionHandler = (
+  params: Record<string, unknown>,
+  context: ActionSource & { state: SpecStateStore },
+) => unknown;
+
+export type ActionDispatcherOptions = {
+  store: SpecStateStore;
+  catalog?: Catalog;
+  /** Handlers by action name; they take precedence over `onAction`. */
+  handlers?: Record<string, ActionHandler>;
+  /** Called for catalog actions without a handler. */
+  onAction?: (
+    name: string,
+    params: Record<string, unknown>,
+    context: ActionSource & { state: SpecStateStore },
+  ) => unknown;
+  /** Reports actions that fail or are unknown instead of throwing. */
+  onError?: (error: Error, binding: ActionBinding) => void;
+};
+
+export type ActionDispatcher = (
+  bindings: ActionBinding | readonly ActionBinding[] | undefined,
+  context: Omit<ExpressionContext, "state" | "event"> &
+    ActionSource & {
+      /** The payload the event carried, read by `{ $event }`. */
+      payload?: unknown;
+    },
+) => Promise<unknown[]>;
+
+/**
+ * Creates the function elements use to run their bound actions: params are
+ * resolved against current state (and the event payload), `setState` writes
+ * the store, and every other action goes to a host handler. Actions in a list
+ * run in order, see state written by the ones before them, and stop at the
+ * first one that fails.
+ */
+export function createActionDispatcher(
+  options: ActionDispatcherOptions,
+): ActionDispatcher {
+  const report = (error: unknown, binding: ActionBinding) => {
+    const normalized =
+      error instanceof Error ? error : new Error(String(error));
+    if (options.onError) options.onError(normalized, binding);
+    else
+      console.warn(
+        `[generative-frame] action "${binding.action}" failed:`,
+        normalized,
+      );
+  };
+
+  return async (bindings, context) => {
+    const list =
+      bindings === undefined
+        ? []
+        : Array.isArray(bindings)
+          ? bindings
+          : [bindings];
+    const results: unknown[] = [];
+    for (const binding of list as ActionBinding[]) {
+      const { payload, elementId, trigger, kind, ...scope } = context;
+      const params = (resolveValue(binding.params ?? {}, {
+        ...scope,
+        state: options.store.getState(),
+        event: payload,
+      }) ?? {}) as Record<string, unknown>;
+      const source = {
+        ...(elementId !== undefined ? { elementId } : {}),
+        ...(trigger !== undefined ? { trigger } : {}),
+        ...(kind !== undefined ? { kind } : {}),
+        state: options.store,
+      };
+      try {
+        const handler = options.handlers?.[binding.action];
+        if (handler) {
+          results.push(await handler(params, source));
+        } else if (binding.action === "setState") {
+          if (typeof params["path"] !== "string") {
+            throw new Error("setState needs a string `path`");
+          }
+          options.store.set(params["path"], params["value"]);
+          results.push(undefined);
+        } else if (options.catalog && !options.catalog.action(binding.action)) {
+          throw new Error(`Unknown action "${binding.action}"`);
+        } else if (options.onAction) {
+          results.push(await options.onAction(binding.action, params, source));
+        } else {
+          throw new Error(`No handler for action "${binding.action}"`);
+        }
+      } catch (error) {
+        report(error, binding);
+        results.push(undefined);
+        break;
+      }
+    }
+    return results;
+  };
+}