@copilotkit/learning 0.0.1

package/src/__tests__/routes.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vitest";
+import { toOriginAndRoute, toRoute } from "../routes";
+
+describe("raw URLs", () => {
+  it("retains ID-like and encoded path segments even with legacy templates", () => {
+    const path = "/users/jane@example.com/orders/123/search/private%20search";
+    expect(toRoute(path, ["/users/:id/orders/:order/search/:query"])).toBe(
+      path,
+    );
+    expect(toRoute("/")).toBe("/");
+  });
+
+  it("preserves the full URL and resolves relative URLs", () => {
+    expect(
+      toOriginAndRoute(
+        "/deals/9?token=synthetic#details",
+        ["/deals/:id"],
+        "https://app.example.com/x",
+      ),
+    ).toEqual({
+      url: "https://app.example.com/deals/9?token=synthetic#details",
+      origin: "https://app.example.com",
+      route: "/deals/9",
+    });
+  });
+});

package/src/__tests__/trajectory-collector.test.ts

@@ -0,0 +1,367 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type * as ClickCapture from "../clicks";
+import type * as InputCapture from "../inputs";
+import {
+  createTrajectoryCollector,
+  MAX_TRAJECTORY_EVENT_BYTES,
+} from "../trajectory-collector";
+import type {
+  JsonValue,
+  TrajectoryCaptureOptions,
+  TrajectoryCollector,
+  TrajectoryEvent,
+} from "../trajectory-types";
+
+// jsdom cannot produce trusted clicks. The capture module itself remains real.
+vi.mock("../clicks", async (importOriginal) => {
+  const actual = await importOriginal<typeof ClickCapture>();
+  return {
+    ...actual,
+    installClickCapture: (
+      params: Parameters<typeof actual.installClickCapture>[0],
+    ) => actual.installClickCapture({ ...params, isTrusted: () => true }),
+  };
+});
+
+vi.mock("../inputs", async (importOriginal) => {
+  const actual = await importOriginal<typeof InputCapture>();
+  return {
+    ...actual,
+    installInputCapture: (
+      params: Parameters<typeof actual.installInputCapture>[0],
+    ) => actual.installInputCapture({ ...params, isTrusted: () => true }),
+  };
+});
+
+const NOW = 1_790_866_801_000;
+const collectors: TrajectoryCollector[] = [];
+
+function setup(options: TrajectoryCaptureOptions = {}) {
+  const send = vi.fn<(event: TrajectoryEvent) => void>();
+  const onError = vi.fn();
+  const collector = createTrajectoryCollector({
+    routes: ["/deals", "/deals/:id"],
+    send,
+    onError,
+    ...options,
+  });
+  collectors.push(collector);
+  return { collector, send, onError };
+}
+
+beforeEach(() => {
+  vi.useFakeTimers();
+  vi.setSystemTime(NOW);
+  history.replaceState(null, "", "/deals?email=secret@example.com#private");
+  document.body.innerHTML =
+    '<div data-message-id="private-message"><button data-copilotkit-action="deal.open">Private deal text</button></div>';
+});
+
+afterEach(() => {
+  collectors.splice(0).forEach((collector) => collector.stop());
+  document.body.innerHTML = "";
+  vi.useRealTimers();
+});
+
+describe("Trajectory capture contract", () => {
+  it("sends real page, click, and navigation capture as plain events without chat context", () => {
+    const fetchBefore = globalThis.fetch;
+    const xhrBefore = XMLHttpRequest.prototype.open;
+    const { collector, send } = setup();
+    collector.start();
+    document.querySelector("button")!.click();
+    history.pushState(null, "", "/deals/42?token=private#secret");
+
+    expect(send.mock.calls.map(([event]) => event)).toMatchObject([
+      {
+        type: "CUSTOM",
+        name: "page",
+        timestamp: NOW,
+        value: {
+          route: "/deals",
+          url: `${location.origin}/deals?email=secret@example.com#private`,
+          title: document.title,
+          referrer: document.referrer,
+        },
+      },
+      {
+        type: "CUSTOM",
+        name: "click",
+        timestamp: NOW,
+        value: {
+          route: "/deals",
+          target: {
+            tag: "button",
+            role: null,
+            action: "deal.open",
+            text: "Private deal text",
+            attributes: { "data-copilotkit-action": "deal.open" },
+          },
+        },
+      },
+      {
+        type: "CUSTOM",
+        name: "navigation",
+        timestamp: NOW,
+        value: {
+          from: `${location.origin}/deals?email=secret@example.com#private`,
+          to: `${location.origin}/deals/42?token=[redacted]#secret`,
+          navigationType: "push",
+        },
+      },
+    ]);
+    expect(JSON.stringify(send.mock.calls)).not.toMatch(
+      /threadId|"seq"|trajectoryId|learningContainerIds/,
+    );
+    expect(globalThis.fetch).not.toBe(fetchBefore);
+    expect(XMLHttpRequest.prototype.open).not.toBe(xhrBefore);
+    collector.stop();
+    expect(globalThis.fetch).toBe(fetchBefore);
+    expect(XMLHttpRequest.prototype.open).toBe(xhrBefore);
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it("retains unconfigured paths and user edits without Thread enrichment", () => {
+    const { collector, send } = setup({ routes: [] });
+    collector.start();
+    history.pushState(
+      null,
+      "",
+      "/users/alice/private-email@example.com?view=full#profile",
+    );
+    document.body.innerHTML =
+      '<input id="email" type="email" data-message-id="message-1">';
+    const input = document.querySelector("input")!;
+    input.value = "synthetic@example.com";
+    input.dispatchEvent(new Event("input", { bubbles: true }));
+    expect(send.mock.calls[0]?.[0].value).toMatchObject({
+      route: "/deals",
+      url: expect.stringContaining("?email="),
+    });
+    expect(send.mock.calls[1]?.[0].value).toMatchObject({
+      to: `${location.origin}/users/alice/private-email@example.com?view=full#profile`,
+    });
+    expect(send.mock.calls[2]?.[0]).toMatchObject({
+      name: "input",
+      value: {
+        eventType: "input",
+        target: {
+          value: "synthetic@example.com",
+          attributes: { "data-message-id": "message-1" },
+        },
+      },
+    });
+    expect(send.mock.calls[2]?.[0].value).not.toHaveProperty("threadId");
+    expect(send.mock.calls[2]?.[0].value).not.toHaveProperty("messageId");
+  });
+
+  it("sends raw network bodies and excludes its configured transport URL", async () => {
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = vi.fn(async () =>
+      Response.json(
+        { result: "synthetic-response" },
+        { headers: { "x-capture": "full" } },
+      ),
+    );
+    const { collector, send } = setup({ ignoreUrls: ["/capture-ingest"] });
+    try {
+      collector.start();
+      const response = await fetch("/api/deals?key=synthetic#full", {
+        method: "POST",
+        headers: { "x-test": "synthetic-header" },
+        body: "synthetic-request",
+      });
+      expect(await response.json()).toEqual({ result: "synthetic-response" });
+      await fetch("/capture-ingest", { method: "POST", body: "ignore-self" });
+      await vi.advanceTimersByTimeAsync(0);
+      const events = send.mock.calls
+        .map(([event]) => event)
+        .filter((event) => event.name === "network");
+      expect(events).toHaveLength(1);
+      expect(events[0]?.value).toMatchObject({
+        url: `${location.origin}/api/deals?key=synthetic#full`,
+        request: {
+          headers: { "x-test": "synthetic-header" },
+          body: { status: "complete", text: "synthetic-request" },
+        },
+        response: {
+          headers: { "x-capture": "full" },
+          body: { status: "complete", text: '{"result":"synthetic-response"}' },
+        },
+      });
+    } finally {
+      collector.stop();
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  it("honors ignored DOM subtrees without reading their content", () => {
+    document.body.innerHTML =
+      '<section data-copilotkit-ignore><button data-copilotkit-action="secret">Private</button></section>';
+    const { collector, send } = setup();
+    collector.start();
+    document.querySelector("button")!.click();
+    expect(send).toHaveBeenCalledTimes(1);
+  });
+
+  it("supports capture switches while retaining initial page context", () => {
+    const { collector, send } = setup({
+      capture: {
+        clicks: false,
+        navigation: false,
+        inputs: false,
+        network: false,
+      },
+    });
+    collector.start();
+    document.querySelector("button")!.click();
+    history.pushState(null, "", "/deals/42");
+    expect(send.mock.calls.map(([event]) => event.name)).toEqual(["page"]);
+  });
+
+  it("starts once and removes capture on stop without buffering events", async () => {
+    const pushBefore = History.prototype.pushState;
+    const { collector, send } = setup();
+    collector.emit("app.before", true);
+    collector.start();
+    collector.start();
+    collector.stop();
+    document.querySelector("button")!.click();
+    history.pushState(null, "", "/deals/42");
+    collector.emit("app.after", true);
+    await vi.advanceTimersByTimeAsync(10_000);
+    expect(send).toHaveBeenCalledTimes(1);
+    expect(History.prototype.pushState).toBe(pushBefore);
+    expect(vi.getTimerCount()).toBe(0);
+    collector.start();
+    expect(send).toHaveBeenCalledTimes(2);
+  });
+
+  it.each<JsonValue>([
+    null,
+    true,
+    42,
+    "done",
+    [1, "yes", null],
+    { nested: { outcome: "approved" } },
+  ])("preserves developer JSON values: %j", (value) => {
+    const { collector, send } = setup();
+    collector.start();
+    collector.emit("deal.approved", value);
+    expect(send.mock.calls[1]?.[0]).toEqual({
+      type: "CUSTOM",
+      name: "deal.approved",
+      timestamp: NOW,
+      value,
+    });
+  });
+
+  it("snapshots developer objects and allows shared non-cyclic values", () => {
+    const { collector, send } = setup();
+    const shared = { status: "approved" };
+    const value = { first: shared, second: shared };
+    collector.start();
+    collector.emit("deal.approved", value);
+    shared.status = "changed";
+    expect(send.mock.calls[1]?.[0].value).toEqual({
+      first: { status: "approved" },
+      second: { status: "approved" },
+    });
+  });
+
+  it("rejects non-JSON values, cycles, empty names, and reserved event names", () => {
+    const { collector, send, onError } = setup();
+    const cycle: Record<string, unknown> = {};
+    cycle.self = cycle;
+    collector.start();
+    for (const value of [
+      undefined,
+      NaN,
+      Infinity,
+      BigInt(1),
+      new Date(),
+      () => {},
+      { absent: undefined },
+      [undefined],
+      cycle,
+    ]) {
+      collector.emit("invalid", value as JsonValue);
+    }
+    collector.emit("", null);
+    collector.emit(" ", null);
+    collector.emit("click", {});
+    collector.emit("thread.linked", {});
+    expect(send).toHaveBeenCalledTimes(1);
+    expect(onError).toHaveBeenCalledTimes(13);
+    expect(
+      onError.mock.calls.every(([error]) => error.code === "INVALID_EVENT"),
+    ).toBe(true);
+  });
+
+  it("enforces the 16 KiB UTF-8 limit, including the event envelope", () => {
+    const { collector, send, onError } = setup();
+    collector.start();
+    const empty = {
+      type: "CUSTOM",
+      name: "app.value",
+      timestamp: NOW,
+      value: "",
+    };
+    const available =
+      MAX_TRAJECTORY_EVENT_BYTES -
+      new TextEncoder().encode(JSON.stringify(empty)).byteLength;
+    collector.emit("app.value", "a".repeat(available));
+    collector.emit("app.value", "a".repeat(available + 1));
+    collector.emit("app.value", "😀".repeat(Math.floor(available / 2)));
+    expect(send).toHaveBeenCalledTimes(2);
+    expect(onError).toHaveBeenCalledTimes(2);
+    expect(onError).toHaveBeenCalledWith(
+      expect.objectContaining({ code: "EVENT_TOO_LARGE" }),
+    );
+  });
+
+  it("rejects NUL characters and event names the Gateway cannot store", () => {
+    const { collector, send, onError } = setup();
+    collector.start();
+    collector.emit("app.value", "null\0character");
+    collector.emit("app.value", { "key\0name": "value" });
+    collector.emit("app\0name", true);
+    collector.emit("a".repeat(201), true);
+    expect(send).toHaveBeenCalledTimes(1);
+    expect(onError).toHaveBeenCalledTimes(4);
+    expect(
+      onError.mock.calls.every(([error]) => error.code === "INVALID_EVENT"),
+    ).toBe(true);
+  });
+
+  it("runs filtering before final validation and sending", () => {
+    const { collector, send, onError } = setup({
+      beforeSend: (event) =>
+        event.name === "page"
+          ? null
+          : { ...event, value: undefined as unknown as JsonValue },
+    });
+    collector.start();
+    collector.emit("app.event", true);
+    expect(send).not.toHaveBeenCalled();
+    expect(onError).toHaveBeenCalledWith(
+      expect.objectContaining({ code: "INVALID_EVENT" }),
+    );
+  });
+
+  it("contains callback errors and does not retry failed sends", async () => {
+    const { collector, send } = setup({
+      onError: () => {
+        throw new Error("diagnostic callback");
+      },
+    });
+    send.mockImplementation(() => {
+      throw new Error("failed send");
+    });
+    expect(() => collector.start()).not.toThrow();
+    await vi.advanceTimersByTimeAsync(10_000);
+    collector.stop();
+    expect(send).toHaveBeenCalledTimes(1);
+    expect(vi.getTimerCount()).toBe(0);
+  });
+});

package/src/__tests__/vitest-environment.mjs

@@ -0,0 +1,23 @@
+import { builtinEnvironments } from "vitest/environments";
+
+export default {
+  ...builtinEnvironments.jsdom,
+  async setup(global, options) {
+    // jsdom has no fetch/Response implementation. Keep FormData in the same
+    // realm as Node's Response: Node 24 no longer serializes jsdom FormData.
+    const formData = global.FormData;
+    const environment = await builtinEnvironments.jsdom.setup(global, options);
+    const descriptor = Object.getOwnPropertyDescriptor(global, "FormData");
+    Object.defineProperty(global, "FormData", {
+      configurable: true,
+      writable: true,
+      value: formData,
+    });
+    return {
+      teardown() {
+        Object.defineProperty(global, "FormData", descriptor);
+        environment.teardown(global);
+      },
+    };
+  },
+};

package/src/clicks.ts

@@ -0,0 +1,193 @@
+import { createRedactor, isCredentialKey } from "./redact";
+import type { Redactor } from "./redact";
+import { REDACTED } from "./types";
+import type { ClickTarget, Emit, EnrichFn } from "./types";
+
+const INTERACTIVE =
+  'button, a[href], input, select, textarea, label, summary, [role], [data-copilotkit-action], [contenteditable]:not([contenteditable="false"])';
+const RECOVERY_DISTANCE_PX = 5;
+// `[role]` also matches containers such as role="main"; cap their text so one
+// click cannot exceed the 16 KiB event limit and be dropped.
+const MAX_TEXT_LENGTH = 1000;
+
+/** `closest()` that continues through shadow roots to their hosts. */
+function closestAcrossShadow(el: Element, selector: string) {
+  let current: Element | null = el;
+  while (current !== null) {
+    const match = current.closest(selector);
+    if (match !== null) return match;
+    const root = current.getRootNode();
+    current = root instanceof ShadowRoot ? root.host : null;
+  }
+  return null;
+}
+
+interface Described {
+  element: Element;
+  target: Omit<ClickTarget, "input">;
+}
+
+interface PointerOrigin {
+  described: Described | null;
+  x: number;
+  y: number;
+}
+
+/**
+ * Finds the nearest interactive element and retains its text, attributes, and value.
+ * The explicit `data-copilotkit-ignore` opt-out still applies.
+ */
+export function describeTarget(el: Element, redact: Redactor) {
+  if (closestAcrossShadow(el, "[data-copilotkit-ignore]") !== null) return null;
+  const element = el.closest(INTERACTIVE) ?? el;
+  // React and server markup can mirror the password into the value attribute.
+  const password = redact.isPassword(element);
+  const described: Described = {
+    element,
+    target: {
+      tag: element.localName,
+      role: element.getAttribute("role"),
+      action: element.getAttribute("data-copilotkit-action"),
+      text: (element.textContent ?? "").slice(0, MAX_TEXT_LENGTH),
+      attributes: Object.fromEntries(
+        Array.from(element.attributes, ({ name, value }) => [
+          name,
+          // Credential-named attributes (`data-api-key`) are redacted whole;
+          // URL-valued ones (`href`, `action`, …) can carry credentials too.
+          (password && name === "value") ||
+          isCredentialKey(name.replace(/^data-/, ""))
+            ? REDACTED
+            : redact.url(value),
+        ]),
+      ),
+      ...readControlValue(element, redact),
+    },
+  };
+  return described;
+}
+
+/** Snapshot live control properties; HTML attributes do not reflect edited values. */
+export function readControlValue(element: Element, redact: Redactor) {
+  if (element instanceof HTMLInputElement) {
+    return {
+      value: redact.isPassword(element) ? REDACTED : element.value,
+      ...(["checkbox", "radio"].includes(element.type)
+        ? { checked: element.checked }
+        : {}),
+      ...(element.type === "file"
+        ? {
+            files: Array.from(element.files ?? [], (file) => ({
+              name: file.name,
+              type: file.type,
+              size: file.size,
+              lastModified: file.lastModified,
+            })),
+          }
+        : {}),
+    };
+  }
+  if (element instanceof HTMLSelectElement) {
+    return {
+      value: element.value,
+      selectedValues: Array.from(
+        element.selectedOptions,
+        (option) => option.value,
+      ),
+    };
+  }
+  if (element instanceof HTMLTextAreaElement) return { value: element.value };
+  if (element.matches('[contenteditable]:not([contenteditable="false"])')) {
+    return { value: element.textContent ?? "" };
+  }
+  return {};
+}
+
+function eventElement(event: Event) {
+  const [first] = event.composedPath();
+  return first instanceof Element ? first : null;
+}
+
+function isRootOrDetached(el: Element) {
+  return el.localName === "body" || el.localName === "html" || !el.isConnected;
+}
+
+function isNear(origin: PointerOrigin, event: MouseEvent) {
+  return (
+    Math.abs(origin.x - event.clientX) <= RECOVERY_DISTANCE_PX &&
+    Math.abs(origin.y - event.clientY) <= RECOVERY_DISTANCE_PX
+  );
+}
+
+/**
+ * Listens for clicks in the capture phase on `window`, so handlers that stop
+ * propagation do not hide them. The target is described at `pointerdown`,
+ * because a re-render before `click` can move the click to `<body>`.
+ */
+export function installClickCapture(params: {
+  emit: Emit;
+  getRoute: () => string;
+  enrich?: EnrichFn;
+  // ponytail: test seam only. jsdom cannot create trusted events; the collector never passes this.
+  isTrusted?: (event: Event) => boolean;
+  redact?: Redactor;
+}) {
+  const {
+    emit,
+    getRoute,
+    enrich,
+    isTrusted = (event) => event.isTrusted,
+    redact = createRedactor(),
+  } = params;
+  let origin: PointerOrigin | null = null;
+
+  const onPointerDown = (event: PointerEvent) => {
+    try {
+      if (event.isPrimary === false) return;
+      const el = eventElement(event);
+      origin = {
+        described: el === null ? null : describeTarget(el, redact),
+        x: event.clientX,
+        y: event.clientY,
+      };
+    } catch {
+      origin = null;
+    }
+  };
+
+  const onClick = (event: MouseEvent) => {
+    const pointerOrigin = origin;
+    origin = null;
+    try {
+      if (!isTrusted(event)) return;
+      const el = eventElement(event);
+      if (el === null) return;
+      const canRecover =
+        pointerOrigin !== null &&
+        isRootOrDetached(el) &&
+        isNear(pointerOrigin, event);
+      const described = canRecover
+        ? pointerOrigin.described
+        : describeTarget(el, redact);
+      if (described === null) return;
+      const input = event.detail === 0 ? "keyboard" : "pointer";
+      emit("click", {
+        target: { ...described.target, input },
+        route: getRoute(),
+        url: redact.url(location.href),
+        ...enrich?.(described.element),
+      });
+    } catch {
+      // Capture must never break the host app's click.
+    }
+  };
+
+  window.addEventListener("pointerdown", onPointerDown, {
+    capture: true,
+    passive: true,
+  });
+  window.addEventListener("click", onClick, { capture: true, passive: true });
+  return () => {
+    window.removeEventListener("pointerdown", onPointerDown, { capture: true });
+    window.removeEventListener("click", onClick, { capture: true });
+  };
+}