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

package/src/assistant-ui/useSharedContext.ts

@@ -0,0 +1,40 @@
+import { onScopeDispose, toValue, watch, type MaybeRefOrGetter } from "vue";
+import {
+  createSharedContext,
+  type ModelContextSource,
+  type SharedContext,
+} from "./modelContext";
+type SharedContextOptions = {
+  title: string;
+  toolCallId: string;
+  initial: SharedContext | undefined;
+  useModelContext: (source: ModelContextSource) => void;
+  onShare: (context: SharedContext | undefined) => void;
+  muted?: boolean;
+};
+/** One persistent context per mounted call; reactive options supply the current title and callback. */
+export function useSharedContext(
+  options: MaybeRefOrGetter<SharedContextOptions>,
+): (context: SharedContext | undefined) => void {
+  const initial = toValue(options);
+  let disposed = false;
+  const shared = createSharedContext(initial.initial, {
+    name: () => {
+      const value = toValue(options);
+      return value.title || value.toolCallId;
+    },
+    muted: () => toValue(options).muted ?? false,
+    onShare: (context) => toValue(options).onShare(context),
+  });
+  initial.useModelContext(shared.source);
+  watch(
+    () => toValue(options).muted ?? false,
+    () => shared.notify(),
+  );
+  onScopeDispose(() => {
+    disposed = true;
+  });
+  return (context) => {
+    if (!disposed) shared.share(context);
+  };
+}

package/src/assistant-ui.ts

@@ -0,0 +1,14 @@
+export {
+  createWidgetToolkit,
+  useAssistantUiThemeTokens,
+  useWidgetInstructions,
+  type RenderReportOptions,
+  type WidgetRenderReport,
+  type WidgetToolkit,
+  type WidgetToolkitOptions,
+} from "./assistant-ui/toolkit";
+export type {
+  ToolkitDisplay,
+  ToolkitExecution,
+  WidgetToolkitExtension,
+} from "./assistant-ui/extension";

package/src/bootstrap.ts

@@ -0,0 +1,112 @@
+import { buildCsp, type CspOptions } from "./csp";
+import type { HostContext } from "./protocol";
+import { runtimeSource } from "./runtime/generated";
+import {
+  DEFAULT_LIGHT_TOKENS,
+  themeVariables,
+  type ThemeTokens,
+} from "./theme";
+
+const escapeAttribute = (value: string) =>
+  value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
+
+const escapeScript = (value: string) =>
+  value.replace(/<\/(script)/gi, "<\\/$1");
+
+const escapeStyle = (value: string) => value.replace(/<\/(style)/gi, "<\\/$1");
+
+const SAFE_VARIABLE = /^--[\w-]+$/;
+const SAFE_VALUE = /^[^;{}<>]*$/;
+
+const rootDeclarations = (variables: Record<string, string>) =>
+  Object.entries(variables)
+    .filter(
+      ([name, value]) => SAFE_VARIABLE.test(name) && SAFE_VALUE.test(value),
+    )
+    .map(([name, value]) => `${name}:${value};`)
+    .join("");
+
+/**
+ * Base styles: transparent page, host typography, and themed form controls,
+ * so plain markup already matches the host before any widget CSS loads.
+ */
+const BASE_CSS = `
+*,*::before,*::after{box-sizing:border-box}
+html,body{margin:0;padding:0;background:transparent}
+html{overflow-y:hidden}
+body{font-family:var(--font-sans);font-size:16px;line-height:1.5;color:var(--color-text);-webkit-font-smoothing:antialiased;overflow-wrap:anywhere}
+#gf-root{display:flow-root;width:100%}
+#gf-root[data-kind=svg]>svg{display:block;width:100%;height:auto}
+h1,h2,h3,h4{line-height:1.25;margin:0 0 .5em;font-weight:600}
+h1{font-size:22px}h2{font-size:18px}h3{font-size:16px}h4{font-size:14px}
+p{margin:0 0 .75em}
+a{color:var(--color-accent)}
+code,kbd,pre,samp{font-family:var(--font-mono);font-size:.9em}
+small{color:var(--color-text-muted)}
+table{border-collapse:collapse;width:100%;font-size:14px;font-variant-numeric:tabular-nums}
+th{font-weight:500;color:var(--color-text-muted);text-align:left}
+th,td{padding:6px 10px;border-bottom:1px solid var(--color-border)}
+button,input,select,textarea{font:inherit;color:inherit}
+button{cursor:pointer;padding:6px 14px;border-radius:var(--radius-md);border:1px solid var(--color-border-strong);background:var(--color-surface);transition:background-color .15s,border-color .15s}
+button:hover{background:var(--color-surface-muted)}
+button:active{transform:translateY(1px)}
+button:disabled{opacity:.5;cursor:not-allowed}
+input:not([type=checkbox]):not([type=radio]):not([type=range]),select,textarea{padding:6px 10px;border-radius:var(--radius-sm);border:1px solid var(--color-border-strong);background:var(--color-surface)}
+input[type=checkbox],input[type=radio],input[type=range],progress,meter{accent-color:var(--color-accent)}
+:focus-visible{outline:2px solid var(--color-accent);outline-offset:2px}
+.sr-only{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0}
+@media (prefers-reduced-motion:reduce){*,*::before,*::after{animation-duration:.01ms!important;animation-iteration-count:1!important;transition-duration:.01ms!important;scroll-behavior:auto!important}}
+`.trim();
+
+export type BootstrapOptions = {
+  /** The embedding page's origin; the frame only talks to this origin. */
+  hostOrigin: string;
+  csp?: CspOptions | string;
+  tokens?: ThemeTokens;
+  /** Fade in elements as they stream in. Always off under reduced motion. */
+  animate?: boolean;
+  /** Extra CSS appended after the base styles. */
+  css?: string;
+  /** Overrides the bundled runtime, mainly for tests. */
+  runtime?: string;
+};
+
+/**
+ * The document every widget frame loads once. It carries the CSP, the theme,
+ * and the runtime; widget code arrives later over the private port.
+ */
+export function buildBootstrapHtml(options: BootstrapOptions): string {
+  const tokens = options.tokens ?? DEFAULT_LIGHT_TOKENS;
+  const csp =
+    typeof options.csp === "string" ? options.csp : buildCsp(options.csp);
+  const config = JSON.stringify({
+    hostOrigin: options.hostOrigin,
+    animate: options.animate ?? true,
+  }).replace(/</g, "\\u003c");
+
+  return [
+    "<!doctype html>",
+    `<html lang="en" data-theme="${tokens.colorScheme}" style="color-scheme:${tokens.colorScheme};background:transparent">`,
+    "<head>",
+    '<meta charset="utf-8">',
+    `<meta http-equiv="Content-Security-Policy" content="${escapeAttribute(csp)}">`,
+    '<meta name="viewport" content="width=device-width,initial-scale=1">',
+    `<style id="gf-base">:root{${rootDeclarations(themeVariables(tokens))}}\n${BASE_CSS}${
+      options.css ? `\n${escapeStyle(options.css)}` : ""
+    }</style>`,
+    "</head>",
+    '<body><div id="gf-root"></div>',
+    `<script id="gf-config" type="application/json">${config}</script>`,
+    `<script>${escapeScript(options.runtime ?? runtimeSource)}</script>`,
+    "</body>",
+    "</html>",
+  ].join("\n");
+}
+
+/** Host context sent with init and on every theme change. */
+export function themeContext(tokens: ThemeTokens): HostContext {
+  return {
+    theme: tokens.colorScheme,
+    styles: { variables: themeVariables(tokens) },
+  };
+}

package/src/csp.ts

@@ -0,0 +1,96 @@
+/** Script, style, image, and font hosts widgets may load from by default. */
+export const DEFAULT_CDN_ORIGINS: readonly string[] = [
+  "https://cdnjs.cloudflare.com",
+  "https://cdn.jsdelivr.net",
+  "https://unpkg.com",
+  "https://esm.sh",
+];
+
+/** Google Fonts stylesheet origins for an explicit `fontStyleOrigins` opt-in. */
+export const DEFAULT_FONT_STYLE_ORIGINS: readonly string[] = [
+  "https://fonts.googleapis.com",
+];
+
+/** Google Fonts file origins for an explicit `fontOrigins` opt-in. */
+export const DEFAULT_FONT_ORIGINS: readonly string[] = [
+  "https://fonts.gstatic.com",
+];
+
+export type CspOptions = {
+  /** Origins for scripts, styles, images, fonts, and media. Defaults to `DEFAULT_CDN_ORIGINS`. */
+  cdnOrigins?: readonly string[];
+  /** Extra origins for font stylesheets, allowed only in `style-src`. Empty by default. */
+  fontStyleOrigins?: readonly string[];
+  /** Extra origins for font files, allowed only in `font-src`. Empty by default. */
+  fontOrigins?: readonly string[];
+  /** Origins `fetch`, XHR, and WebSocket may reach. Empty by default, blocking those requests. */
+  connectOrigins?: readonly string[];
+  /** Extra image origins, such as an image proxy. */
+  imageOrigins?: readonly string[];
+  /** Origins that may be embedded in nested frames. Empty by default. */
+  frameOrigins?: readonly string[];
+  /** Allows `eval` and `new Function`, which some charting libraries need. Off by default. */
+  allowEval?: boolean;
+};
+
+const KEYWORDS = new Set(["'self'", "'none'", "data:", "blob:", "https:"]);
+
+const isSafeSource = (value: string, allowWebSocket: boolean): boolean => {
+  if (KEYWORDS.has(value)) return true;
+  const scheme = allowWebSocket ? /^(?:https?|wss?):\/\//i : /^https?:\/\//i;
+  if (!scheme.test(value) || /[\s;'"`,]/.test(value)) return false;
+  try {
+    const url = new URL(value.replace("://*.", "://wildcard."));
+    return (
+      url.username === "" &&
+      url.password === "" &&
+      url.search === "" &&
+      url.hash === ""
+    );
+  } catch {
+    return false;
+  }
+};
+
+const sources = (
+  values: readonly string[] | undefined,
+  allowWebSocket = false,
+) => [
+  ...new Set(
+    (values ?? []).filter(
+      (value) =>
+        typeof value === "string" && isSafeSource(value, allowWebSocket),
+    ),
+  ),
+];
+
+/** Builds the Content-Security-Policy every widget frame enforces. */
+export function buildCsp(options: CspOptions = {}): string {
+  const cdn = sources(options.cdnOrigins ?? DEFAULT_CDN_ORIGINS);
+  const connect = sources(options.connectOrigins, true);
+  const frames = sources(options.frameOrigins);
+  const images = sources(options.imageOrigins);
+  const fontStyles = sources(options.fontStyleOrigins);
+  const fonts = sources(options.fontOrigins);
+  const directive = (name: string, values: readonly string[]) =>
+    `${name} ${values.length > 0 ? values.join(" ") : "'none'"}`;
+
+  return [
+    "default-src 'none'",
+    directive("script-src", [
+      "'unsafe-inline'",
+      ...(options.allowEval ? ["'unsafe-eval'"] : []),
+      ...cdn,
+    ]),
+    directive("style-src", ["'unsafe-inline'", ...cdn, ...fontStyles]),
+    directive("img-src", ["data:", "blob:", ...cdn, ...images]),
+    directive("font-src", ["data:", ...cdn, ...fonts]),
+    directive("media-src", ["data:", "blob:", ...cdn]),
+    directive("connect-src", connect),
+    directive("frame-src", frames),
+    "worker-src blob:",
+    "object-src 'none'",
+    "base-uri 'none'",
+    "form-action 'none'",
+  ].join("; ");
+}

package/src/index.ts

@@ -0,0 +1,44 @@
+export {
+  clearWidgetStorage,
+  createWidget,
+  widgetStorageSalt,
+  type CreateWidgetOptions,
+  type Screenshot,
+  type ToolCallRequest,
+  type UiMessageParams,
+  type WidgetEventMap,
+  type WidgetHandle,
+  type WidgetHandlers,
+  type WidgetInspection,
+} from "./widget";
+export {
+  previewWidget,
+  type PreviewOptions,
+  type PreviewResult,
+} from "./preview";
+export { buildCsp, DEFAULT_CDN_ORIGINS, type CspOptions } from "./csp";
+export {
+  readThemeTokens,
+  defaultThemeTokens,
+  DEFAULT_LIGHT_TOKENS,
+  DEFAULT_DARK_TOKENS,
+  type ThemeTokens,
+  type ThemeTokenName,
+  type ThemeTokenSources,
+} from "./theme";
+export type {
+  ColorScheme,
+  ClearStorageResult,
+  ConsoleEntry,
+  ConsoleLevel,
+  DisplayMode,
+  EndResult,
+  FrameInspection,
+  HostContext,
+  McpAppInitializeParams,
+  ScreenshotOptions,
+  WidgetError,
+  WidgetErrorKind,
+  WidgetKind,
+  WidgetSize,
+} from "./protocol";

package/src/json-schema.ts

@@ -0,0 +1,353 @@
+/** The JSON Schema subset this package writes and validates. */
+export type JsonSchema = {
+  type?: JsonSchemaType | readonly JsonSchemaType[];
+  description?: string;
+  properties?: Record<string, JsonSchema>;
+  required?: readonly string[];
+  items?: JsonSchema;
+  enum?: readonly unknown[];
+  const?: unknown;
+  anyOf?: readonly JsonSchema[];
+  oneOf?: readonly JsonSchema[];
+  minItems?: number;
+  maxItems?: number;
+  minLength?: number;
+  maxLength?: number;
+  minimum?: number;
+  maximum?: number;
+  additionalProperties?: boolean | JsonSchema;
+  default?: unknown;
+};
+
+export type JsonSchemaType =
+  | "string"
+  | "number"
+  | "integer"
+  | "boolean"
+  | "object"
+  | "array"
+  | "null";
+
+/** A validation failure at a JSON Pointer inside the validated value. */
+export type SchemaIssue = { path: string; message: string };
+
+/** The parts of a Standard Schema this package uses. */
+export type StandardSchemaLike = {
+  readonly "~standard": {
+    readonly version: 1;
+    readonly vendor: string;
+    readonly validate: (
+      value: unknown,
+    ) => StandardResult | Promise<StandardResult>;
+    readonly jsonSchema?: {
+      readonly input: (options: { target: string }) => Record<string, unknown>;
+    };
+  };
+};
+
+type StandardResult = {
+  readonly issues?:
+    | ReadonlyArray<{
+        readonly message: string;
+        readonly path?:
+          | ReadonlyArray<PropertyKey | { readonly key: PropertyKey }>
+          | undefined;
+      }>
+    | undefined;
+};
+
+export const isStandardSchema = (value: unknown): value is StandardSchemaLike =>
+  typeof value === "object" &&
+  value !== null &&
+  "~standard" in value &&
+  typeof (value as StandardSchemaLike)["~standard"]?.validate === "function";
+
+/** JSON Schema for a schema that is either JSON Schema or a Standard Schema exposing one. */
+export const toJsonSchema = (
+  schema: JsonSchema | StandardSchemaLike | undefined,
+): JsonSchema | undefined => {
+  if (!schema) return undefined;
+  if (!isStandardSchema(schema)) return schema;
+  try {
+    return schema["~standard"].jsonSchema?.input({
+      target: "draft-2020-12",
+    }) as JsonSchema | undefined;
+  } catch {
+    return undefined;
+  }
+};
+
+const escapeToken = (token: string | number) =>
+  String(token).replace(/~/g, "~0").replace(/\//g, "~1");
+
+const typeOf = (value: unknown): JsonSchemaType => {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  if (typeof value === "number")
+    return Number.isInteger(value) ? "integer" : "number";
+  return typeof value as JsonSchemaType;
+};
+
+const matchesType = (value: unknown, type: JsonSchemaType) => {
+  const actual = typeOf(value);
+  if (type === "number") return actual === "number" || actual === "integer";
+  return actual === type;
+};
+
+const deepEqual = (a: unknown, b: unknown): boolean => {
+  if (a === b) return true;
+  if (typeof a !== "object" || typeof b !== "object" || !a || !b) return false;
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  const keysA = Object.keys(a);
+  const keysB = Object.keys(b);
+  return (
+    keysA.length === keysB.length &&
+    keysA.every((key) =>
+      deepEqual(
+        (a as Record<string, unknown>)[key],
+        (b as Record<string, unknown>)[key],
+      ),
+    )
+  );
+};
+
+export { deepEqual };
+
+export type ValidateOptions = {
+  /** Values for which this returns true are accepted without checking, e.g. expressions. */
+  skip?: (value: unknown) => boolean;
+};
+
+/**
+ * Validates a value against the JSON Schema subset above and returns every
+ * issue found. Keywords outside the subset are ignored.
+ */
+export function validateJsonSchema(
+  schema: JsonSchema,
+  value: unknown,
+  options: ValidateOptions = {},
+  path = "",
+): SchemaIssue[] {
+  if (options.skip?.(value)) return [];
+  const issues: SchemaIssue[] = [];
+  const at = path || "/";
+
+  if (schema.anyOf || schema.oneOf) {
+    const branches = (schema.anyOf ?? schema.oneOf)!;
+    const passes = branches.some(
+      (branch) => validateJsonSchema(branch, value, options, path).length === 0,
+    );
+    if (!passes) {
+      issues.push({ path: at, message: "does not match any allowed shape" });
+      return issues;
+    }
+  }
+
+  if (schema.type !== undefined) {
+    const types = typeof schema.type === "string" ? [schema.type] : schema.type;
+    if (!types.some((type) => matchesType(value, type))) {
+      issues.push({
+        path: at,
+        message: `expected ${types.join(" or ")}, got ${typeOf(value)}`,
+      });
+      return issues;
+    }
+  }
+
+  if (schema.const !== undefined && !deepEqual(schema.const, value)) {
+    issues.push({
+      path: at,
+      message: `must be ${JSON.stringify(schema.const)}`,
+    });
+  }
+  if (schema.enum && !schema.enum.some((option) => deepEqual(option, value))) {
+    issues.push({
+      path: at,
+      message: `must be one of ${schema.enum.map((o) => JSON.stringify(o)).join(", ")}`,
+    });
+  }
+
+  if (typeof value === "string") {
+    if (schema.minLength !== undefined && value.length < schema.minLength) {
+      issues.push({
+        path: at,
+        message: `must be at least ${schema.minLength} characters`,
+      });
+    }
+    if (schema.maxLength !== undefined && value.length > schema.maxLength) {
+      issues.push({
+        path: at,
+        message: `must be at most ${schema.maxLength} characters`,
+      });
+    }
+  }
+
+  if (typeof value === "number") {
+    if (schema.minimum !== undefined && value < schema.minimum) {
+      issues.push({ path: at, message: `must be >= ${schema.minimum}` });
+    }
+    if (schema.maximum !== undefined && value > schema.maximum) {
+      issues.push({ path: at, message: `must be <= ${schema.maximum}` });
+    }
+  }
+
+  if (Array.isArray(value)) {
+    if (schema.minItems !== undefined && value.length < schema.minItems) {
+      issues.push({
+        path: at,
+        message: `must have at least ${schema.minItems} items`,
+      });
+    }
+    if (schema.maxItems !== undefined && value.length > schema.maxItems) {
+      issues.push({
+        path: at,
+        message: `must have at most ${schema.maxItems} items`,
+      });
+    }
+    if (schema.items) {
+      value.forEach((item, index) =>
+        issues.push(
+          ...validateJsonSchema(
+            schema.items!,
+            item,
+            options,
+            `${path}/${index}`,
+          ),
+        ),
+      );
+    }
+  }
+
+  if (typeOf(value) === "object") {
+    const record = value as Record<string, unknown>;
+    for (const key of schema.required ?? []) {
+      if (record[key] === undefined) {
+        issues.push({
+          path: `${path}/${escapeToken(key)}`,
+          message: "is required",
+        });
+      }
+    }
+    for (const [key, child] of Object.entries(record)) {
+      const childPath = `${path}/${escapeToken(key)}`;
+      const childSchema = schema.properties?.[key];
+      if (childSchema) {
+        if (child !== undefined) {
+          issues.push(
+            ...validateJsonSchema(childSchema, child, options, childPath),
+          );
+        }
+      } else if (schema.additionalProperties === false) {
+        issues.push({ path: childPath, message: "is not an allowed property" });
+      } else if (typeof schema.additionalProperties === "object") {
+        issues.push(
+          ...validateJsonSchema(
+            schema.additionalProperties,
+            child,
+            options,
+            childPath,
+          ),
+        );
+      }
+    }
+  }
+
+  return issues;
+}
+
+const containsSkipped = (
+  value: unknown,
+  skip: (value: unknown) => boolean,
+): boolean =>
+  skip(value) ||
+  (typeof value === "object" &&
+    value !== null &&
+    Object.values(value).some((child) => containsSkipped(child, skip)));
+
+/**
+ * Validates against JSON Schema or a Standard Schema. A Standard Schema that
+ * validates asynchronously is not awaited and reports no issues, and neither
+ * does one whose value contains a skipped placeholder.
+ */
+export function validateSchema(
+  schema: JsonSchema | StandardSchemaLike,
+  value: unknown,
+  options: ValidateOptions = {},
+): SchemaIssue[] {
+  if (!isStandardSchema(schema)) {
+    return validateJsonSchema(schema, value, options);
+  }
+  // A Standard Schema cannot be told to accept placeholders, so values that
+  // contain one are left to the component.
+  if (options.skip && containsSkipped(value, options.skip)) return [];
+  const result = schema["~standard"].validate(value);
+  if (result instanceof Promise) return [];
+  return (result.issues ?? []).map((issue) => ({
+    path:
+      (issue.path ?? [])
+        .map(
+          (segment) =>
+            `/${escapeToken(
+              String(
+                typeof segment === "object" && segment !== null
+                  ? segment.key
+                  : segment,
+              ),
+            )}`,
+        )
+        .join("") || "/",
+    message: issue.message,
+  }));
+}
+
+const describeType = (
+  schema: JsonSchema | undefined,
+  depth: number,
+): string => {
+  if (!schema) return "unknown";
+  if (schema.const !== undefined) return JSON.stringify(schema.const);
+  if (schema.enum) return schema.enum.map((o) => JSON.stringify(o)).join(" | ");
+  const branches = schema.anyOf ?? schema.oneOf;
+  if (branches) return branches.map((b) => describeType(b, depth)).join(" | ");
+  const types =
+    schema.type === undefined
+      ? []
+      : typeof schema.type === "string"
+        ? [schema.type]
+        : [...schema.type];
+  if (types.length > 1) {
+    return types
+      .map((type) => describeType({ ...schema, type }, depth))
+      .join(" | ");
+  }
+  switch (types[0]) {
+    case "integer":
+      return "integer";
+    case "array":
+      return `${describeType(schema.items, depth)}[]`.replace(
+        /^(.* \| .*)\[\]$/,
+        "($1)[]",
+      );
+    case "object":
+      return schema.properties && depth < 3
+        ? describeObject(schema, depth + 1)
+        : "object";
+    case undefined:
+      return schema.properties ? describeObject(schema, depth + 1) : "unknown";
+    default:
+      return types[0];
+  }
+};
+
+const describeObject = (schema: JsonSchema, depth: number): string => {
+  const required = new Set(schema.required ?? []);
+  const fields = Object.entries(schema.properties ?? {}).map(
+    ([key, child]) =>
+      `${key}${required.has(key) ? "" : "?"}: ${describeType(child, depth)}`,
+  );
+  return fields.length ? `{ ${fields.join("; ")} }` : "{}";
+};
+
+/** A compact TypeScript-like rendering of a schema, for prompts. */
+export const describeSchema = (schema: JsonSchema | undefined): string =>
+  describeType(schema, 0);