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

package/src/tools/define.ts

@@ -0,0 +1,65 @@
+import type { JsonSchema } from "../json-schema";
+
+export type { JsonSchema };
+
+/** A model-facing tool, independent of any provider SDK. */
+export type ToolDefinition<Input, Output> = {
+  name: string;
+  description: string;
+  inputSchema: JsonSchema;
+  execute(input: Input): Promise<Output>;
+};
+
+export type AnyTool = ToolDefinition<never, unknown>;
+
+/** A `read_me` module contributed from outside the built-in set. */
+export type GuidanceModule = {
+  name: string;
+  /** One line shown in the `read_me` module list. */
+  summary: string;
+  guidance(): string;
+};
+
+/**
+ * Converts tools to the Vercel AI SDK shape without depending on it: pass
+ * the SDK's own `jsonSchema` helper, e.g.
+ * `toAISDKTools(tools, { jsonSchema })` with `import { jsonSchema } from "ai"`.
+ */
+export function toAISDKTools<T extends Record<string, AnyTool>, Schema>(
+  tools: T,
+  sdk: { jsonSchema: (schema: JsonSchema) => Schema },
+): {
+  [K in keyof T]: {
+    description: string;
+    inputSchema: Schema;
+    execute: T[K]["execute"];
+  };
+} {
+  const result: Record<string, unknown> = {};
+  for (const [key, tool] of Object.entries(tools)) {
+    result[key] = {
+      description: tool.description,
+      inputSchema: sdk.jsonSchema(tool.inputSchema),
+      execute: (input: never) => tool.execute(input),
+    };
+  }
+  return result as never;
+}
+
+/**
+ * Each tool's name, description, and input schema without `execute`, for
+ * declaring tools to a model where they do not run, e.g. on a server that
+ * forwards calls to tools executing in the browser.
+ */
+export function getToolDeclarations<T extends Record<string, AnyTool>>(
+  tools: T,
+): { [K in keyof T]: { description: string; inputSchema: JsonSchema } } {
+  const result: Record<string, unknown> = {};
+  for (const [key, tool] of Object.entries(tools)) {
+    result[key] = {
+      description: tool.description,
+      inputSchema: tool.inputSchema,
+    };
+  }
+  return result as never;
+}

package/src/tools/edits.ts

@@ -0,0 +1,73 @@
+export type WidgetEdit = { old_string: string; new_string: string };
+
+export type ApplyEditsResult =
+  | { ok: true; code: string }
+  | { ok: false; error: string; index: number };
+
+const countOccurrences = (haystack: string, needle: string) => {
+  let count = 0;
+  for (
+    let at = haystack.indexOf(needle);
+    at !== -1;
+    at = haystack.indexOf(needle, at + 1)
+  ) {
+    count++;
+    if (count > 1) break;
+  }
+  return count;
+};
+
+const preview = (text: string) =>
+  JSON.stringify(text.length > 80 ? `${text.slice(0, 80)}…` : text);
+
+/**
+ * Applies exact string replacements in order. Each `old_string` must occur
+ * exactly once in the code as it stands after the previous edits; on any
+ * failure no edit is applied.
+ */
+export function applyWidgetEdits(
+  code: string,
+  edits: readonly WidgetEdit[],
+): ApplyEditsResult {
+  if (edits.length === 0) {
+    return {
+      ok: false,
+      error: "edits must contain at least one replacement",
+      index: -1,
+    };
+  }
+  let next = code;
+  for (const [index, edit] of edits.entries()) {
+    if (!edit.old_string) {
+      return { ok: false, error: `edits[${index}].old_string is empty`, index };
+    }
+    if (edit.old_string === edit.new_string) {
+      return {
+        ok: false,
+        error: `edits[${index}] does not change anything`,
+        index,
+      };
+    }
+    const count = countOccurrences(next, edit.old_string);
+    if (count === 0) {
+      return {
+        ok: false,
+        error: `edits[${index}].old_string was not found: ${preview(edit.old_string)}. Copy it exactly from the widget's latest code.`,
+        index,
+      };
+    }
+    if (count > 1) {
+      return {
+        ok: false,
+        error: `edits[${index}].old_string occurs more than once: ${preview(edit.old_string)}. Include surrounding text so it matches exactly one place.`,
+        index,
+      };
+    }
+    const at = next.indexOf(edit.old_string);
+    next =
+      next.slice(0, at) +
+      edit.new_string +
+      next.slice(at + edit.old_string.length);
+  }
+  return { ok: true, code: next };
+}

package/src/tools/registry.ts

@@ -0,0 +1,44 @@
+export type WidgetRecord = {
+  title: string;
+  code: string;
+  /** Increments on every show or edit of this title. */
+  version: number;
+};
+
+export type WidgetRegistry = {
+  get(title: string): WidgetRecord | undefined;
+  set(title: string, code: string): WidgetRecord;
+  delete(title: string): boolean;
+  list(): WidgetRecord[];
+  subscribe(listener: (record: WidgetRecord) => void): () => void;
+};
+
+/** Tracks the latest code of each widget by title, so edits apply to what the user sees. */
+export function createWidgetRegistry(
+  initial: Iterable<{ title: string; code: string }> = [],
+): WidgetRegistry {
+  const records = new Map<string, WidgetRecord>();
+  const listeners = new Set<(record: WidgetRecord) => void>();
+  for (const { title, code } of initial) {
+    records.set(title, { title, code, version: 1 });
+  }
+  return {
+    get: (title) => records.get(title),
+    set(title, code) {
+      const record = {
+        title,
+        code,
+        version: (records.get(title)?.version ?? 0) + 1,
+      };
+      records.set(title, record);
+      for (const listener of listeners) listener(record);
+      return record;
+    },
+    delete: (title) => records.delete(title),
+    list: () => [...records.values()],
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+  };
+}

package/src/tools/tools.ts

@@ -0,0 +1,361 @@
+import type { PreviewResult } from "../preview";
+import {
+  buildWidgetGuidance,
+  MODULE_SUMMARIES,
+  normalizeModules,
+  WIDGET_MODULES,
+  type GuidanceOptions,
+  type Platform,
+  type WidgetModule,
+} from "../prompts/guidance";
+import {
+  detectWidgetKind,
+  type ColorScheme,
+  type WidgetKind,
+} from "../protocol";
+import type {
+  AnyTool,
+  GuidanceModule,
+  JsonSchema,
+  ToolDefinition,
+} from "./define";
+import { applyWidgetEdits, type WidgetEdit } from "./edits";
+import { createWidgetRegistry, type WidgetRegistry } from "./registry";
+
+/** A built-in module, or the name of a module passed in `modules`. */
+export type ReadMeModule = WidgetModule | (string & {});
+
+export type ReadMeInput = { modules?: ReadMeModule[]; platform?: Platform };
+
+export type ShowWidgetInput = {
+  title: string;
+  loading_messages?: string[];
+  widget_code: string;
+};
+
+export type ShowWidgetResult =
+  | { ok: true; title: string; kind: WidgetKind; version: number }
+  | { ok: false; title: string; error: string };
+
+export type EditWidgetInput = { title: string; edits: WidgetEdit[] };
+
+export type EditWidgetResult =
+  | { ok: true; title: string; version: number; applied: number }
+  | { ok: false; title: string; error: string };
+
+export type PreviewWidgetInput = {
+  widget_code: string;
+  width?: number;
+  appearance?: ColorScheme;
+};
+
+export type WidgetTools = {
+  read_me: ToolDefinition<ReadMeInput, string>;
+  show_widget: ToolDefinition<ShowWidgetInput, ShowWidgetResult>;
+  edit_widget: ToolDefinition<EditWidgetInput, EditWidgetResult>;
+  preview_widget: ToolDefinition<PreviewWidgetInput, PreviewResult>;
+};
+
+export type CreateWidgetToolsOptions = {
+  registry?: WidgetRegistry;
+  /** Guidance options other than modules and platform, which the model picks. */
+  guidance?: Omit<GuidanceOptions, "modules" | "platform">;
+  /** Renders code offscreen for `preview_widget`, typically `previewWidget` from the core entry. */
+  preview?: (
+    code: string,
+    options: { width?: number; appearance?: ColorScheme },
+  ) => Promise<PreviewResult>;
+  /** Extra `read_me` modules, such as `specGuidanceModule(catalog)` from `generative-frame/spec/tools`. */
+  modules?: readonly GuidanceModule[];
+};
+
+const TITLE_SCHEMA: JsonSchema = {
+  type: "string",
+  description:
+    "Short snake_case identifier for the widget, unique in this conversation (e.g. `q3_revenue_by_region`). Reuse it to replace or edit the widget.",
+};
+
+/**
+ * Model-facing tools for widgets, independent of any provider SDK: each has
+ * a name, a description, a JSON Schema for its input, and `execute`.
+ * `extraTools` are added as they are (for example `createSpecTools(catalog)`
+ * from `generative-frame/spec/tools`), and `modules` extend `read_me`.
+ */
+export function createWidgetTools<
+  Extra extends Record<string, AnyTool> = Record<never, never>,
+>(
+  options: CreateWidgetToolsOptions & { extraTools?: Extra } = {},
+): WidgetTools & Extra {
+  const registry = options.registry ?? createWidgetRegistry();
+  const extraModules = options.modules ?? [];
+  const moduleNames: readonly string[] = [
+    ...WIDGET_MODULES,
+    ...extraModules.map((m) => m.name),
+  ];
+  const moduleDocs = [
+    ...WIDGET_MODULES.map((m) => `${m} (${MODULE_SUMMARIES[m]})`),
+    ...extraModules.map((m) => `${m.name} (${m.summary})`),
+  ];
+
+  const tools: WidgetTools = {
+    read_me: {
+      name: "read_me",
+      description:
+        "Returns the rules for writing widgets plus guidance for the requested modules. Call it silently before your first `show_widget` call, and again when you need a module whose guidance you do not have yet. Do not mention this call to the user.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          modules: {
+            type: "array",
+            description: `Modules to load: ${moduleDocs.join("; ")}.`,
+            items: { type: "string", enum: moduleNames },
+          },
+          platform: {
+            type: "string",
+            enum: ["desktop", "mobile"],
+            description: "The user's client. Defaults to desktop.",
+          },
+        },
+        additionalProperties: false,
+      },
+      async execute(input) {
+        const requested: readonly string[] = input.modules ?? [];
+        const extra = extraModules
+          .filter((m) => requested.includes(m.name))
+          .map((m) => m.guidance())
+          .join("\n\n");
+        const modules = normalizeModules(requested);
+        if (extra && modules.length === 0) return extra;
+        const guidance = buildWidgetGuidance({
+          ...options.guidance,
+          modules,
+          platform: input.platform === "mobile" ? "mobile" : "desktop",
+        });
+        return extra ? `${guidance}\n\n${extra}` : guidance;
+      },
+    },
+
+    show_widget: {
+      name: "show_widget",
+      description:
+        "Shows a visual widget (HTML fragment or SVG) inline in the conversation, streaming it as you write. Write a short <style> first, then markup, then scripts. Call read_me first. Showing a title that already exists replaces that widget.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          title: TITLE_SCHEMA,
+          loading_messages: {
+            type: "array",
+            description:
+              "One to four short status lines shown while the widget streams.",
+            items: { type: "string" },
+            maxItems: 4,
+          },
+          widget_code: {
+            type: "string",
+            description:
+              "The widget: an HTML fragment (no doctype, html, head, or body), or code starting with <svg for a standalone SVG.",
+          },
+        },
+        required: ["title", "widget_code"],
+        additionalProperties: false,
+      },
+      async execute(input) {
+        if (!input.widget_code?.trim()) {
+          return {
+            ok: false,
+            title: input.title,
+            error: "widget_code is empty",
+          };
+        }
+        const record = registry.set(input.title, input.widget_code);
+        return {
+          ok: true,
+          title: input.title,
+          kind: detectWidgetKind(input.widget_code),
+          version: record.version,
+        };
+      },
+    },
+
+    edit_widget: {
+      name: "edit_widget",
+      description:
+        "Changes a widget you already showed with exact string replacements, applied in order to its latest code. Each old_string must match exactly one place; include surrounding text to make it unique. No edit is applied if any one fails.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          title: TITLE_SCHEMA,
+          edits: {
+            type: "array",
+            minItems: 1,
+            items: {
+              type: "object",
+              properties: {
+                old_string: {
+                  type: "string",
+                  description:
+                    "Exact text to find, copied from the widget's latest code.",
+                },
+                new_string: {
+                  type: "string",
+                  description: "Replacement text.",
+                },
+              },
+              required: ["old_string", "new_string"],
+              additionalProperties: false,
+            },
+          },
+        },
+        required: ["title", "edits"],
+        additionalProperties: false,
+      },
+      async execute(input) {
+        const record = registry.get(input.title);
+        if (!record) {
+          const known = registry.list().map((r) => r.title);
+          return {
+            ok: false,
+            title: input.title,
+            error: `No widget titled "${input.title}".${
+              known.length > 0 ? ` Known widgets: ${known.join(", ")}.` : ""
+            } Use show_widget to create it.`,
+          };
+        }
+        const result = applyWidgetEdits(record.code, input.edits ?? []);
+        if (!result.ok)
+          return { ok: false, title: input.title, error: result.error };
+        const updated = registry.set(input.title, result.code);
+        return {
+          ok: true,
+          title: input.title,
+          version: updated.version,
+          applied: input.edits.length,
+        };
+      },
+    },
+
+    preview_widget: {
+      name: "preview_widget",
+      description:
+        "Renders widget code offscreen without showing it and reports errors, console output, the rendered height, whether it came out blank, and a screenshot. Use it to check complex widgets before showing them.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          widget_code: { type: "string", description: "Complete widget code." },
+          width: {
+            type: "number",
+            description: "Layout width in CSS pixels. Defaults to 680.",
+            minimum: 240,
+            maximum: 1600,
+          },
+          appearance: {
+            type: "string",
+            enum: ["light", "dark"],
+            description: "Color scheme to render in. Defaults to light.",
+          },
+        },
+        required: ["widget_code"],
+        additionalProperties: false,
+      },
+      async execute(input) {
+        if (!options.preview) {
+          return {
+            ok: false,
+            kind: detectWidgetKind(input.widget_code),
+            width: 0,
+            height: 0,
+            blank: true,
+            errors: [
+              {
+                kind: "error",
+                message: "Previews are not available in this environment.",
+              },
+            ],
+            console: [],
+          };
+        }
+        return options.preview(input.widget_code, {
+          ...(input.width !== undefined ? { width: input.width } : {}),
+          ...(input.appearance !== undefined
+            ? { appearance: input.appearance }
+            : {}),
+        });
+      },
+    },
+  };
+
+  return { ...tools, ...options.extraTools } as WidgetTools & Extra;
+}
+
+export type WidgetInstructionsOptions = {
+  /**
+   * Inline `read_me` output for these modules into the instructions, which
+   * saves the model a round trip at the cost of a larger system prompt.
+   */
+  preload?: ReadMeInput;
+};
+
+/** Whether `read_me` lists a module, which is how composed modules become visible. */
+const readMeOffers = (tools: WidgetTools, module: string) =>
+  (
+    tools.read_me.inputSchema.properties?.["modules"]?.items?.enum ?? []
+  ).includes(module);
+
+const WIDGET_TOOL_RULES = [
+  "- Call `read_me` once, silently, before your first `show_widget` call, with the modules you need.",
+  "- Change an existing widget with `edit_widget` (exact string replacements) instead of re-sending it.",
+];
+
+/**
+ * A short system prompt section telling the model when and how to use the
+ * widget tools, optionally with `read_me` guidance preloaded. With
+ * `render_spec` among the tools, it also tells the model when to answer in
+ * Markdown, with a spec, or with a widget.
+ */
+export async function buildWidgetInstructions(
+  tools: WidgetTools & Record<string, AnyTool>,
+  options: WidgetInstructionsOptions = {},
+): Promise<string> {
+  const lines =
+    "render_spec" in tools
+      ? [
+          "## Choosing how to answer",
+          "",
+          "Use the lightest format that fully answers the request:",
+          "",
+          "- Markdown, with no tool call, for explanations, advice, short answers, and anything read once. Most answers are text.",
+          "- `render_spec` for structured content the user scans or acts on, built from the app's components: comparisons, step-by-step guides, plans and itineraries, summaries of facts, and forms or choices. A spec can show values its `$calc` formulas compute from state, such as totals or quantities that follow a guest count; a tool whose point is the calculation, such as a calculator, is a widget.",
+          "- `show_widget` for interactive tools that calculate as the user changes inputs, such as calculators, simulations, and games, and for visuals the components cannot draw.",
+          "",
+          "Do not render a paragraph or a short list. Around a rendered answer, keep prose to a sentence or two and do not repeat what it shows.",
+          "",
+          "The Declarative UI guidance describes what goes inside a `render_spec` call; its output rules apply to those patches, not to your answer.",
+          "",
+          "## Widgets",
+          "",
+          ...WIDGET_TOOL_RULES,
+          `- The ${WIDGET_MODULES.map((module) => `\`${module}\``).join(", ")} modules of \`read_me\` guide \`show_widget\` code, so a \`render_spec\` answer never needs them.`,
+          ...(readMeOffers(tools, "spec") &&
+          !options.preload?.modules?.includes("spec")
+            ? [
+                "- Load the `spec` module with `read_me` before your first `render_spec` call.",
+              ]
+            : []),
+        ]
+      : [
+          "## Visual widgets",
+          "",
+          "When a visual would explain better than text (charts, diagrams, comparisons, small interactive tools, forms), show it with `show_widget` instead of describing it. Keep surrounding prose short and do not repeat what the widget shows.",
+          ...WIDGET_TOOL_RULES,
+        ];
+  const preloaded = options.preload?.modules ?? [];
+  if (preloaded.length) {
+    lines.push(
+      `- The guidance for ${preloaded.map((module) => `\`${module}\``).join(", ")} follows, so never load it with \`read_me\`.`,
+    );
+  }
+  if (options.preload) {
+    lines.push("", await tools.read_me.execute(options.preload));
+  }
+  return lines.join("\n");
+}

package/src/tools.ts

@@ -0,0 +1,32 @@
+export {
+  buildWidgetInstructions,
+  createWidgetTools,
+  type CreateWidgetToolsOptions,
+  type EditWidgetInput,
+  type EditWidgetResult,
+  type PreviewWidgetInput,
+  type ReadMeInput,
+  type ReadMeModule,
+  type WidgetInstructionsOptions,
+  type ShowWidgetInput,
+  type ShowWidgetResult,
+  type WidgetTools,
+} from "./tools/tools";
+export {
+  getToolDeclarations,
+  toAISDKTools,
+  type AnyTool,
+  type GuidanceModule,
+  type JsonSchema,
+  type ToolDefinition,
+} from "./tools/define";
+export {
+  applyWidgetEdits,
+  type ApplyEditsResult,
+  type WidgetEdit,
+} from "./tools/edits";
+export {
+  createWidgetRegistry,
+  type WidgetRecord,
+  type WidgetRegistry,
+} from "./tools/registry";

package/src/version.ts

@@ -0,0 +1,4 @@
+export const VERSION =
+  typeof __AUI_PACKAGE_VERSION__ === "string"
+    ? __AUI_PACKAGE_VERSION__
+    : "0.0.0";

package/src/vue/Widget.tsx

@@ -0,0 +1,74 @@
+import { defineComponent, h, watchEffect, type CSSProperties } from "vue";
+import { syncWidgetCode } from "./sync";
+import { useWidget, type UseWidgetOptions } from "./useWidget";
+export type WidgetProps = UseWidgetOptions & {
+  code: string;
+  streaming?: boolean;
+  className?: string;
+  style?: CSSProperties;
+};
+/** Renders model-generated HTML or SVG in a Safe Content Frame, streaming as code grows. */
+export const Widget = defineComponent(
+  (props: WidgetProps, { attrs }) => {
+    const { ref, widget } = useWidget(() => {
+      const {
+        code: _code,
+        streaming: _streaming,
+        className: _className,
+        style: _style,
+        ...options
+      } = props;
+      return options;
+    });
+    watchEffect(
+      () => {
+        if (widget.value)
+          syncWidgetCode(widget.value, props.code, props.streaming ?? false);
+      },
+      { flush: "post" },
+    );
+    return () =>
+      h("div", {
+        ...attrs,
+        ref,
+        class: [attrs.class, props.className],
+        style: props.style,
+      });
+  },
+  {
+    name: "Widget",
+    inheritAttrs: false,
+    props: [
+      "code",
+      "streaming",
+      "className",
+      "style",
+      "tokens",
+      "initialState",
+      "csp",
+      "product",
+      "maxHeight",
+      "id",
+      "unsafeShimDomain",
+      "frame",
+      "opaqueOrigin",
+      "context",
+      "animate",
+      "css",
+      "minHeight",
+      "readyTimeoutMs",
+      "onPrompt",
+      "onMessage",
+      "onOpenLink",
+      "onCallTool",
+      "onInitialized",
+      "onRequestDisplayMode",
+      "onUpdateModelContext",
+      "onCopyText",
+      "onWidgetState",
+      "onResize",
+      "onError",
+      "onLog",
+    ],
+  },
+);

package/src/vue/sync.ts

@@ -0,0 +1,36 @@
+import type { WidgetHandle } from "../widget";
+
+export type CodeUpdate =
+  | { type: "none" }
+  | { type: "append"; chunk: string }
+  | { type: "replace"; code: string };
+
+/** Decides how to move a widget from the code it has to `next`. */
+export function planCodeUpdate(current: string, next: string): CodeUpdate {
+  if (next === current) return { type: "none" };
+  if (next.startsWith(current)) {
+    return { type: "append", chunk: next.slice(current.length) };
+  }
+  return { type: "replace", code: next };
+}
+
+const ignore = () => {};
+
+/**
+ * Brings a widget in line with a code prop that is either complete or still
+ * growing: only the new suffix is written while it grows, `end` runs once it
+ * stops, and anything that is not an extension replaces the widget's code.
+ */
+export function syncWidgetCode(
+  widget: Pick<WidgetHandle, "code" | "ended" | "write" | "end" | "replace">,
+  code: string,
+  streaming: boolean,
+): void {
+  const plan = planCodeUpdate(widget.code, code);
+  if (widget.ended || plan.type === "replace") {
+    if (plan.type !== "none") void widget.replace(code).catch(ignore);
+    return;
+  }
+  if (plan.type === "append") widget.write(plan.chunk);
+  if (!streaming && code.length > 0) void widget.end().catch(ignore);
+}