@copilotkit/learning 0.0.1 → 1.80.0

package/src/inputs.ts

@@ -1,9 +1,32 @@
 import { describeTarget, readControlValue } from "./clicks";
 import { createRedactor } from "./redact";
 import type { Redactor } from "./redact";
-import type { Emit } from "./types";
+import { REDACTED } from "./types";
+import type { ClickTarget, Emit } from "./types";
 
-/** Records user edits without changing the control or interfering with its listeners. */
+const TEXT_DEBOUNCE_MS = 300;
+const TEXT_INPUT_TYPES = new Set([
+  "text",
+  "search",
+  "tel",
+  "url",
+  "email",
+  "password",
+  "number",
+]);
+type ControlValue = ReturnType<typeof readControlValue>;
+interface Edit {
+  state: ControlValue;
+  payload: {
+    eventType: string;
+    target: Omit<ClickTarget, "input">;
+    url: string;
+    route: string;
+  };
+  timer?: ReturnType<typeof setTimeout>;
+}
+
+/** Records settled user edits without interfering with the host app's controls. */
 export function installInputCapture(params: {
   emit: Emit;
   isTrusted?: (event: Event) => boolean;
@@ -14,29 +37,154 @@ export function installInputCapture(params: {
     isTrusted = (event: Event) => event.isTrusted,
     redact = createRedactor(),
   } = params;
-  const onInput = (event: Event) => {
+  let active = true;
+  const pending = new Map<Element, Edit>();
+  // A native change can echo a settled input on blur. Consume that one echo;
+  // every fresh trusted input is a new edit, even if its redacted value matches.
+  const changeEcho = new WeakMap<Element, string>();
+  const composing = new WeakMap<Element, boolean>();
+
+  const cancel = (element: Element) => {
+    clearTimeout(pending.get(element)?.timer);
+    pending.delete(element);
+  };
+  const deliver = (element: Element, edit: Edit) => {
     try {
-      if (!isTrusted(event)) return;
-      const [element] = event.composedPath();
-      if (!(element instanceof Element)) return;
-      const described = describeTarget(element, redact);
-      if (described === null) return;
-      const value = readControlValue(element, redact);
-      if (!("value" in value)) return;
-      emit("input", {
-        eventType: event.type,
-        target: { ...described.target, ...value },
+      // Recheck privacy, but retain the observed value and route even if a host
+      // handler reset or removed the control before this trailing delivery.
+      if (!active || describeTarget(element, redact) === null) return;
+      // A host can reset the live value before making this field sensitive.
+      // Drop the old snapshot: mirrored text/attributes may contain its value.
+      if (redact.isPassword(element) && edit.state.value !== REDACTED) return;
+      if (edit.payload.eventType === "input") {
+        changeEcho.set(element, JSON.stringify(edit.state));
+      }
+      edit.payload.url = redact.url(edit.payload.url);
+      edit.payload.target.text = redact.url(edit.payload.target.text);
+      edit.payload.target.attributes = Object.fromEntries(
+        Object.entries(edit.payload.target.attributes).map(([key, value]) => [
+          key,
+          redact.url(value),
+        ]),
+      );
+      emit("input", edit.payload);
+    } catch {
+      // Capture must never break an edit or a later action in the host app.
+    }
+  };
+  const flush = () => {
+    // Clear before callbacks: an emit can synchronously stop or restart capture.
+    const edits = [...pending];
+    for (const [element] of edits) cancel(element);
+    for (const [element, edit] of edits) deliver(element, edit);
+  };
+  const observe = (element: Element, eventType: string, settle: boolean) => {
+    if (pending.size > 0 && !pending.has(element)) flush();
+    if (!active) return;
+    const described = describeTarget(element, redact);
+    if (described === null) {
+      cancel(element);
+      return;
+    }
+    const state = readControlValue(element, redact);
+    if (!("value" in state)) return;
+    const text =
+      element instanceof HTMLTextAreaElement ||
+      (element instanceof HTMLInputElement &&
+        TEXT_INPUT_TYPES.has(element.type)) ||
+      element.matches('[contenteditable]:not([contenteditable="false"])');
+    if (!text) flush();
+    const signature = JSON.stringify(state);
+    const echo =
+      eventType === "change" &&
+      (signature === JSON.stringify(pending.get(element)?.state) ||
+        signature === changeEcho.get(element));
+    changeEcho.delete(element);
+    if (echo) {
+      flush();
+      changeEcho.delete(element);
+      return;
+    }
+    cancel(element);
+    const edit: Edit = {
+      state,
+      payload: {
+        eventType,
+        target: { ...described.target, ...state },
         url: redact.url(location.href),
         route: location.pathname,
-      });
+      },
+    };
+    if (!text) {
+      deliver(element, edit);
+      return;
+    }
+    if (settle) {
+      edit.timer = setTimeout(() => {
+        cancel(element);
+        deliver(element, edit);
+      }, TEXT_DEBOUNCE_MS);
+    }
+    pending.set(element, edit);
+  };
+  const onEdit = (event: Event) => {
+    try {
+      if (!active || !isTrusted(event)) return;
+      const [element] = event.composedPath();
+      if (!(element instanceof Element)) return;
+      if (event.type === "compositionstart") {
+        composing.set(element, true);
+        clearTimeout(pending.get(element)?.timer);
+        return;
+      }
+      if (event.type === "compositionend") composing.set(element, false);
+      // Keep a draft during composition for explicit action/stop flushes. An
+      // end event takes precedence over a late input's stale isComposing flag.
+      const inComposition =
+        composing.get(element) === true ||
+        (composing.get(element) !== false &&
+          "isComposing" in event &&
+          event.isComposing === true);
+      observe(
+        element,
+        event.type === "compositionend" ? "input" : event.type,
+        !inComposition,
+      );
+      if (event.type === "change") flush();
     } catch {
       // Capture must never break an edit in the host app.
     }
   };
-  window.addEventListener("input", onInput, { capture: true, passive: true });
-  window.addEventListener("change", onInput, { capture: true, passive: true });
-  return () => {
-    window.removeEventListener("input", onInput, { capture: true });
-    window.removeEventListener("change", onInput, { capture: true });
+  const onAction = (event: Event) => {
+    if (event.type !== "pagehide" && !isTrusted(event)) return;
+    if (event.type === "keydown") {
+      const [element] = event.composedPath();
+      // Window capture runs before no-form send handlers can reset the control.
+      // IME completion can precede its final keydown, which still reports 229.
+      if (
+        !(event instanceof KeyboardEvent) ||
+        event.key !== "Enter" ||
+        event.isComposing ||
+        event.keyCode === 229 ||
+        (element instanceof Element && composing.get(element) === true)
+      )
+        return;
+    }
+    flush();
+  };
+  const editTypes = ["input", "change", "compositionstart", "compositionend"];
+  const actionTypes = ["click", "submit", "focusout", "pagehide", "keydown"];
+  for (const type of editTypes)
+    window.addEventListener(type, onEdit, { capture: true, passive: true });
+  for (const type of actionTypes)
+    window.addEventListener(type, onAction, { capture: true, passive: true });
+  const uninstall = () => {
+    active = false;
+    for (const element of pending.keys()) cancel(element);
+    for (const type of editTypes)
+      window.removeEventListener(type, onEdit, true);
+    for (const type of actionTypes)
+      window.removeEventListener(type, onAction, true);
   };
+  return Object.assign(uninstall, { flush });
 }

package/src/redact.ts

@@ -148,8 +148,11 @@ export function createRedactor() {
         seen.add(record.target as Element);
   };
 
-  /** Replaces remembered values, raw and in their JSON and URL encodings. */
-  const scrub = (text: string) => {
+  /**
+   * Replaces remembered values, raw and in their JSON and URL encodings, plus
+   * `normalize(value)` when given and at least 4 characters long.
+   */
+  const scrub = (text: string, normalize?: (value: string) => string) => {
     for (const value of [...remembered.values()].sort(
       (a, b) => b.length - a.length,
     ))
@@ -158,6 +161,7 @@ export function createRedactor() {
         JSON.stringify(value).slice(1, -1),
         encodeURIComponent(value),
         new URLSearchParams({ v: value }).toString().slice(2),
+        ...[normalize?.(value) ?? ""].filter((normal) => normal.length >= 4),
       ])
         text = /^\d+$/.test(form)
           ? // One-time codes must not match inside longer numbers.
@@ -191,6 +195,7 @@ export function createRedactor() {
 
   return {
     isPassword,
+    scrub,
     /**
      * Tracks password fields for the session: existing ones, `type` toggles away
      * from "password", and typed values even when input capture is off.

package/src/trajectory-collector.ts

@@ -53,7 +53,9 @@ export function createTrajectoryCollector(
   },
 ): TrajectoryCollector {
   let active = false;
+  let generation = 0;
   let uninstalls: (() => void)[] = [];
+  let flushInputs: (() => void) | undefined;
 
   const report = (code: string, message: string) => {
     try {
@@ -67,6 +69,9 @@ export function createTrajectoryCollector(
 
   const record = (name: string, value: JsonValue) => {
     if (!active) return;
+    const current = generation;
+    if (name !== "input" && name !== "network") flushInputs?.();
+    if (!active || generation !== current) return;
     let payload: TrajectoryEvent;
     try {
       const event: TrajectoryEvent = {
@@ -77,7 +82,7 @@ export function createTrajectoryCollector(
       };
       const kept =
         options.beforeSend === undefined ? event : options.beforeSend(event);
-      if (kept === null || !active) return;
+      if (kept === null || !active || generation !== current) return;
       if (
         kept.type !== "CUSTOM" ||
         typeof kept.name !== "string" ||
@@ -130,6 +135,12 @@ export function createTrajectoryCollector(
   };
 
   const stop = () => {
+    const current = generation;
+    const flush = flushInputs;
+    flushInputs = undefined;
+    flush?.();
+    if (generation !== current) return;
+    generation++;
     active = false;
     const installed = uninstalls;
     uninstalls = [];
@@ -140,6 +151,7 @@ export function createTrajectoryCollector(
     start() {
       if (active || typeof window === "undefined") return;
       active = true;
+      generation++;
       // Native callers can emit developer events without browser observers.
       if (typeof window.addEventListener !== "function") return;
       // One per session: fields seen and values typed are forgotten on stop().
@@ -155,7 +167,9 @@ export function createTrajectoryCollector(
           uninstalls.push(installNavigationCapture({ emit: capture, redact }));
         }
         if (options.capture?.inputs !== false) {
-          uninstalls.push(installInputCapture({ emit: capture, redact }));
+          const inputs = installInputCapture({ emit: capture, redact });
+          flushInputs = inputs.flush;
+          uninstalls.push(inputs);
         }
         if (options.capture?.network !== false) {
           uninstalls.push(

package/src/types.ts

@@ -49,6 +49,12 @@ export interface ClickTarget {
   role: string | null;
   action: string | null;
   text: string;
+  /**
+   * Short, cleaned name of the clicked control (click events only). Comes from
+   * `aria-labelledby`, `aria-label`, an input caption or `alt`, `title`, or a
+   * control's own text. Omitted when no safe name exists.
+   */
+  label?: string;
   attributes: Record<string, string>;
   value?: string;
   checked?: boolean;

package/CHANGELOG.md

@@ -1,9 +0,0 @@
-# Changelog — learning lane
-
-`@copilotkit/learning` versions independently of the monorepo packages
-(`scopes.learning` in `release.config.json`).
-
-`release / create-pr` prepends a section here for each release, and
-`release / publish` reads that section back as the GitHub Release body.
-
-Entries begin with the first independent release cut after this file was added.